D8: split core into core, engine and api layers (#463)

.agents/skills/layerfs-js-sdk/SKILL.md

@@ -157,12 +157,12 @@ overwrite it.
 
 ## Import the SDK
 
-The SDK is the `api/agent/sdk` folder of the LayerFS checkout. Link it into
+The SDK is the `api/agent` folder of the LayerFS checkout. Link it into
 your folder once:
 
 ```bash
 npm init -y >/dev/null && npm pkg set type=module
-npm install --no-audit --no-fund "file:$LAYERFS_REPO/api/agent/sdk"   # LAYERFS_REPO: the LayerFS checkout
+npm install --no-audit --no-fund "file:$LAYERFS_REPO/api/agent"   # LAYERFS_REPO: the LayerFS checkout
 ```
 
 Then, in any `.mjs` file:
@@ -362,7 +362,7 @@ For Rust projects, follow the live-checked [Cargo workflow](references/rules/car
 
 ## Methods
 
-Copied from [`api/how-to-use/agent.md`](../../../api/how-to-use/agent.md#methods), which is the source of truth.
+Copied from [`api/docs/agent.md`](../../../api/docs/agent.md#methods), which is the source of truth.
 Every method is positional and returns a Promise. Each group's page has, for every
 method, its arguments, result fields, refusals with what to do, limits and examples.
 
@@ -379,6 +379,6 @@ A `ref` is `main`, a Branch name, a Commit id or a Layer id. Paths are absolute
 view (`/src/index.js`). Pages are `{ items, hasMore }`; advance with
 `pagePos + items.length`.
 
-Deeper material: the [SDK guide](../../../api/how-to-use/agent.md), the
-[`layerfs` command](../../../api/how-to-use/agent.md#the-layerfs-command) and the
+Deeper material: the [SDK guide](../../../api/docs/agent.md), the
+[`layerfs` command](../../../api/docs/agent.md#the-layerfs-command) and the
 [0.1.7 SDK and UI guide](../../../docs/versioned/0.1.7/sdk-and-ui.md).

.agents/skills/layerfs-js-sdk/references/methods/branch.md

@@ -2,7 +2,7 @@
 
 > **Status:** Current general guide. Part of the `layerfs-js-sdk` skill. Examples were
 > captured live in issue #334 Phase A at `b30e4fb8f`. Opaque IDs are shortened;
-> the full replies and trace are in `core/target/issue334/phase-a/`.
+> the full replies and trace are in `target/issue334/phase-a/`.
 
 Examples use `layerfs` as connected in [SKILL.md](../../SKILL.md#connect-to-a-project) and work on the Branch
 `"work"`. Paging works as described

.agents/skills/layerfs-js-sdk/references/methods/fs-read.md

@@ -2,7 +2,7 @@
 
 > **Status:** Current general guide. Part of the `layerfs-js-sdk` skill. Examples were
 > captured live in issue #334 Phase A at `b30e4fb8f`. Opaque IDs are shortened;
-> the full replies and trace are in `core/target/issue334/phase-a/`.
+> the full replies and trace are in `target/issue334/phase-a/`.
 
 Examples use `layerfs` as connected in [SKILL.md](../../SKILL.md#connect-to-a-project) and work on the Branch
 `"work"`.
@@ -240,7 +240,7 @@ The output above preserves the Phase A capture at `b30e4fb8f`, which exposed
 issue #334 BUG-001 by omitting a direct child. After the matcher fix, Phase B
 step 005 checked `fs.glob('work', 'test/**/*.test.js', '/')` against the new
 project and returned `items: ['/test/health.test.js']`; its full reply is retained
-in `core/target/issue334/phase-b/005-test-m1.out`. The external matcher regression
+in `target/issue334/phase-b/005-test-m1.out`. The external matcher regression
 also covers direct children and several nested levels.
 
 ## `fs.diff_files(leftRef, leftPath, rightRef, rightPath)`

.agents/skills/layerfs-js-sdk/references/methods/fs-write.md

@@ -2,7 +2,7 @@
 
 > **Status:** Current general guide. Part of the `layerfs-js-sdk` skill. Examples were
 > captured live in issue #334 Phase A at `b30e4fb8f`. Opaque IDs are shortened;
-> the full replies and trace are in `core/target/issue334/phase-a/`.
+> the full replies and trace are in `target/issue334/phase-a/`.
 
 Examples use `layerfs` as connected in [SKILL.md](../../SKILL.md#connect-to-a-project) and work on the Branch
 `"work"`.

.agents/skills/layerfs-js-sdk/references/methods/project.md

@@ -2,7 +2,7 @@
 
 > **Status:** Current general guide. Part of the `layerfs-js-sdk` skill. Examples were
 > captured live in issue #334 Phase A at `b30e4fb8f`. Opaque IDs are shortened;
-> the full replies and trace are in `core/target/issue334/phase-a/`. The client
+> the full replies and trace are in `target/issue334/phase-a/`. The client
 > factories and `list_sandboxes` are #428's; result shapes are unchanged.
 
 Examples use `layerfs` as connected in [SKILL.md](../../SKILL.md#connect-to-a-project).

.agents/skills/layerfs-js-sdk/references/methods/sandbox.md

@@ -2,7 +2,7 @@
 
 > **Status:** Current general guide. Part of the `layerfs-js-sdk` skill. The methods
 > are #428's; behaviour is from the source and its Docker checks
-> (`api/agent/sdk/test/verify/sandbox_real.mjs`).
+> (`api/agent/test/verify/sandbox_real.mjs`).
 
 Examples use `layerfs` as connected in [SKILL.md](../../SKILL.md#connect-to-a-project).
 

.agents/skills/layerfs-js-sdk/references/rules/cargo.md

@@ -1,7 +1,7 @@
 # Rust and Cargo in a Workspace
 
 > **Status:** Current general guide. Live Cargo 1.85.1 checks in issue #337
-> Phase A used product `db5b1bac9`; raw receipts are in
+> Phase A used product `db5b1bac9`; at that pin the receipt path was
 > `core/target/issue337/phase-a/`. These are diagnostics, not benchmarks.
 
 ## Put all mutable Cargo state in the view

.agents/skills/layerfs-sdk-observe/references/tracing.md

@@ -2,7 +2,7 @@
 
 > **Status:** Current general guide. Part of the `layerfs-sdk-observe` skill. Describes the
 > #333 trace, merged to `main` in `62b225766`. Its source of truth is the call trace
-> section of [`api/how-to-use/backend.md`](../../../../api/how-to-use/backend.md#the-call-trace).
+> section of [`api/docs/backend.md`](../../../../api/docs/backend.md#the-call-trace).
 
 ## Turning it on
 

.cargo/config.toml

@@ -3,7 +3,7 @@
 # This file sits at the repository root, not under `core/`, because cargo
 # discovers `.cargo/config.toml` by walking up from the **current working
 # directory**. The repository's prescribed commands run from this root with
-# `--manifest-path core/Cargo.toml`, which never looks inside `core/.cargo/`, so
+# the root manifest; a manifest path never selects a nested `.cargo/`, so
 # the flags used to be silently absent from exactly the builds that matter.
 # It is scoped by target cfg, so x86_64 and every other target are untouched.
 #
@@ -18,15 +18,15 @@
 #
 # Measured consequence of losing them (same source, same machine, same protocol):
 # 214 MiB/s against 802 MiB/s on one stream, 425 against 1556 MiB/s on two.
-# `core/crates/layerfs-bridge` now refuses to compile for aarch64 without this
+# `engine/crates/layerfs-bridge` now refuses to compile for aarch64 without this
 # profile instead of silently negotiating the ChaCha20-Poly1305 fallback.
 #
 # These are the crates' own documented cfg knobs plus the ARMv8 target features,
 # not patches. An explicit RUSTFLAGS environment variable overrides this table, so
 # a scripted or container build that sets RUSTFLAGS must repeat these flags.
 #
 # The reference workspace that lived under root `crates/` was retired by R9c
-# (2026-10-10); `core/` is the only Cargo workspace these flags apply to.
+# (2026-10-10); the root workspace now covers core, engine and api.
 [target.'cfg(target_arch = "aarch64")']
 rustflags = [
     "--cfg", "aes_armv8",

core/.config/nextest.toml → .config/nextest.toml

@@ -1,5 +1,5 @@
 # nextest profiles for the non-blocking GitHub CI. Selection lives in
-# core/tools/ci_tests.py; this file only sets how a selected test runs.
+# tools/ci_tests.py; this file only sets how a selected test runs.
 
 [profile.ci]
 # Every test is its own process. Report all failures; never retry one.

.github/workflows/ci.yml

@@ -1,22 +1,33 @@
 # Fast lane: runs after a push and reports. It is never a required check and
 # never blocks a push or merge; agents do not wait for it (AGENTS.md §4).
-# Slow and FUSE mount tests run in nightly.yml. Selection: core/tools/ci_tests.py.
-# The JavaScript API (api/, binding crate layerfs-node) is left out of CI (owner,
-# 2026-10-23): no path trigger, excluded from Clippy and tests, skipped by the guard.
+# Slow and FUSE mount tests run in nightly.yml. Selection: tools/ci_tests.py.
+# The Node binding (engine/crates/layerfs-node) and the JavaScript packages in
+# api/ stay outside CI (owner, 2026-10-23): no path trigger, excluded from
+# Clippy/tests and skipped by the guard. The Rust layerfs-api crate is included.
 name: ci
 
 on:
   push:
     branches: [main]
     paths:
       - "core/**"
+      - "engine/**"
+      - "!engine/crates/layerfs-node/**"
+      - "Cargo.*"
+      - ".config/**"
+      - "tools/**"
       - ".cargo/**"
       - ".github/workflows/ci.yml"
       - "!**/*.md"
       - "!core/docs/**"
   pull_request:
     paths:
       - "core/**"
+      - "engine/**"
+      - "!engine/crates/layerfs-node/**"
+      - "Cargo.*"
+      - ".config/**"
+      - "tools/**"
       - ".cargo/**"
       - ".github/workflows/ci.yml"
       - "!**/*.md"
@@ -44,14 +55,14 @@ jobs:
     steps:
       - uses: actions/checkout@v7.0.1
       - run: rustup toolchain install 1.85.1 --profile minimal --component rustfmt
-      - run: cargo +1.85.1 fmt --manifest-path core/Cargo.toml --all -- --check
+      - run: cargo +1.85.1 fmt --manifest-path Cargo.toml --all -- --check
       # Each check reports even when an earlier one failed.
       - if: ${{ !cancelled() }}
-        run: python3 -B core/tools/check_product_boundary.py --skip-sdk
+        run: python3 -B tools/check_product_boundary.py --skip-sdk
       - if: ${{ !cancelled() }}
-        run: python3 -B core/tools/check_fuser_integrity.py
+        run: python3 -B tools/check_fuser_integrity.py
       - if: ${{ !cancelled() }}
-        run: python3 -B -m unittest discover -s core/tools -p 'test_*.py'
+        run: python3 -B -m unittest discover -s tools -p 'test_*.py'
 
   clippy:
     runs-on: ubuntu-24.04
@@ -61,9 +72,9 @@ jobs:
       - run: rustup toolchain install 1.85.1 --profile minimal --component clippy
       - uses: Swatinem/rust-cache@v2.9.2
         with:
-          workspaces: core -> target
+          workspaces: . -> target
           save-if: ${{ github.ref == 'refs/heads/main' }}
-      - run: cargo +1.85.1 clippy --manifest-path core/Cargo.toml --locked --workspace --exclude layerfs-node --all-targets -- -D warnings
+      - run: cargo +1.85.1 clippy --manifest-path Cargo.toml --locked --workspace --exclude layerfs-node --all-targets -- -D warnings
 
   test:
     runs-on: ubuntu-24.04
@@ -85,7 +96,7 @@ jobs:
           tool: cargo-nextest@0.9.146
       - uses: Swatinem/rust-cache@v2.9.2
         with:
-          workspaces: core -> target
+          workspaces: . -> target
           save-if: ${{ github.ref == 'refs/heads/main' }}
       # Build first so compile time is never counted against the test ceiling.
       # Only the fast lane's test targets are built (one --test per name), since
@@ -94,21 +105,21 @@ jobs:
       # no tests). --timings writes where build time goes, per unit.
       - name: Build test binaries
         run: |
-          targets="$(python3 -B core/tools/ci_tests.py targets fast)"
+          targets="$(python3 -B tools/ci_tests.py targets fast)"
           # shellcheck disable=SC2086 # one --test flag per word
-          cargo +1.85.1 test --manifest-path core/Cargo.toml --locked \
+          cargo +1.85.1 test --manifest-path Cargo.toml --locked \
             --workspace --exclude layerfs-node $targets --no-run --timings
       - name: Upload build timings
         if: ${{ !cancelled() }}
         uses: actions/upload-artifact@v7.0.2
         with:
           name: test-build-timings
-          path: core/target/cargo-timings/cargo-timing.html
+          path: target/cargo-timings/cargo-timing.html
           retention-days: 14
       - name: Run fast tests (whole run capped at 120 s)
         run: |
-          targets="$(python3 -B core/tools/ci_tests.py targets fast)"
-          filter="$(python3 -B core/tools/ci_tests.py filter fast)"
+          targets="$(python3 -B tools/ci_tests.py targets fast)"
+          filter="$(python3 -B tools/ci_tests.py filter fast)"
           # shellcheck disable=SC2086 # one --test flag per word
-          timeout 120 cargo +1.85.1 nextest run --manifest-path core/Cargo.toml --locked \
+          timeout 120 cargo +1.85.1 nextest run --manifest-path Cargo.toml --locked \
             --workspace --exclude layerfs-node $targets --profile ci -E "$filter"

.github/workflows/format.yml

@@ -8,13 +8,11 @@ on:
   push:
     branches: [main]
     paths:
-      - "core/tools/**/*.py"
       - "tools/**/*.py"
       - "ruff.toml"
       - ".github/workflows/format.yml"
   pull_request:
     paths:
-      - "core/tools/**/*.py"
       - "tools/**/*.py"
       - "ruff.toml"
       - ".github/workflows/format.yml"

.github/workflows/nightly.yml

@@ -1,9 +1,9 @@
 # Nightly lane: the tests the fast lane leaves out. Report only; never a
-# required check. Selection: core/tools/ci_tests.py.
+# required check. Selection: tools/ci_tests.py.
 #  - slow:  binaries that take 5 s or more to run, plus the "heavy" ones that
 #           take 5 s or more of build CPU (left out of the push job), on the
 #           runner
-#  - mount: Linux-only layerfs-daemon targets that mount FUSE. Each binary runs
+#  - mount: Linux-only daemon and SDK targets that mount FUSE. Each binary runs
 #           in its own fresh container with /dev/fuse and SYS_ADMIN, as the
 #           existing native proofs do: forced_unavailable needs fusectl absent,
 #           and fp2_negotiation_flags needs one test thread.
@@ -38,19 +38,19 @@ jobs:
           tool: cargo-nextest@0.9.146
       - uses: Swatinem/rust-cache@v2.9.2
         with:
-          workspaces: core -> target
+          workspaces: . -> target
       - name: Build test binaries
         run: |
-          targets="$(python3 -B core/tools/ci_tests.py targets nightly)"
+          targets="$(python3 -B tools/ci_tests.py targets nightly)"
           # shellcheck disable=SC2086 # one --test flag per word
-          cargo +1.85.1 test --manifest-path core/Cargo.toml --locked \
+          cargo +1.85.1 test --manifest-path Cargo.toml --locked \
             --workspace --exclude layerfs-node $targets --no-run
       - name: Run slow and heavy tests (whole run capped at 120 s)
         run: |
-          targets="$(python3 -B core/tools/ci_tests.py targets nightly)"
-          filter="$(python3 -B core/tools/ci_tests.py filter nightly)"
+          targets="$(python3 -B tools/ci_tests.py targets nightly)"
+          filter="$(python3 -B tools/ci_tests.py filter nightly)"
           # shellcheck disable=SC2086 # one --test flag per word
-          timeout 120 cargo +1.85.1 nextest run --manifest-path core/Cargo.toml --locked \
+          timeout 120 cargo +1.85.1 nextest run --manifest-path Cargo.toml --locked \
             --workspace --exclude layerfs-node $targets --profile ci -E "$filter"
 
   mount:
@@ -61,14 +61,14 @@ jobs:
       - run: rustup toolchain install 1.85.1 --profile minimal
       - uses: Swatinem/rust-cache@v2.9.2
         with:
-          workspaces: core -> target
+          workspaces: . -> target
       - name: Build mount test binaries
         run: |
-          targets="$(python3 -B core/tools/ci_tests.py mount-targets)"
+          targets="$(python3 -B tools/ci_tests.py mount-targets)"
           # shellcheck disable=SC2086 # one --test flag per word
-          cargo +1.85.1 test --manifest-path core/Cargo.toml --locked -p layerfs-daemon \
+          cargo +1.85.1 test --manifest-path Cargo.toml --locked -p layerfs-daemon -p layerfs-api \
             $targets --no-run --message-format json > "$RUNNER_TEMP/build.json"
-          python3 -B core/tools/ci_tests.py executables < "$RUNNER_TEMP/build.json" > "$RUNNER_TEMP/mount.tsv"
+          python3 -B tools/ci_tests.py executables < "$RUNNER_TEMP/build.json" > "$RUNNER_TEMP/mount.tsv"
           test -s "$RUNNER_TEMP/mount.tsv"
           wc -l < "$RUNNER_TEMP/mount.tsv"
       - name: Prepare FUSE and the test image

.gitignore

@@ -1,5 +1,7 @@
 target/
-/core/target-linux/
+# The Node addon that api/scripts/build-native.mjs builds beside its crate.
+/engine/crates/layerfs-node/layerfs.node
+/target-linux/
 /eval/runs/
 /eval/datasets/
 .DS_Store