Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Add the Rust engine toolchain, CI check, engine shell and addon loader, and let each storage engine name what it can do (rust-engine/core) (#9631)
Garry Tan0cdc2fc538ce
diff --git a/.github/workflows/nightly-watch.yml b/.github/workflows/nightly-watch.ymlindex 438bf92059..f01b1d8312 100644--- a/.github/workflows/nightly-watch.yml+++ b/.github/workflows/nightly-watch.yml@@ -59,6 +59,7 @@ on:- TLA+ specs- Stable daily- Upgrade matrix+ - Rust enginetypes: [completed]branches: [master]workflow_dispatch:diff --git a/.github/workflows/rust-engine.yml b/.github/workflows/rust-engine.ymlnew file mode 100644index 0000000000..cce6e65784--- /dev/null+++ b/.github/workflows/rust-engine.yml@@ -0,0 +1,329 @@+name: Rust engine++# Checks for the optional Rust engine under rust/. Rust is never required to build or run+# gbrain: the last job proves that by removing Rust from PATH and building the normal binary.+#+# Jobs:+# checks formatting, clippy, unit tests, and cargo-deny (licenses, sources, advisories).+# The advisory check downloads the RustSec database, so it needs network access.+# addon builds the addon (`bun run rust:build`) and runs the Bun smoke test+# (rust/smoke/run.ts, including a `bun build --compile` executable) on Linux x64 and+# macOS arm64, then uploads the .node file.+# without-rust no Rust on PATH: bun install, bun run build, ./bin/gbrain --version.+# scope reads a pull request's changed files and picks the advisory check and addon cells.+#+# Runs only when something the Rust engine depends on changes (the path list below). The two+# rust-unit-arms entries start with `**/` because those files arrive in a later change and the+# repo's doc-path check rejects a plain path to a file that does not exist yet; the pattern still+# matches the same files.+#+# Event parity (docs/TESTING.md#event-parity), named exceptions:+# - The macOS addon cell runs on pushes to master, on workflow_dispatch, and on pull requests+# that change rust/** or the loader files (src/core/rust-engine.ts, src/core/rust-engine/**).+# macOS runners are the landing line's bottleneck. Covered by every push to master.+# - The cargo-deny advisory check runs on a pull request only when it changes rust/** (which+# holds rust/Cargo.lock), so a new RustSec advisory cannot turn an unrelated pull request red.+# Covered by every push to master and the daily Rust engine schedule, which runs only `checks`.++on:+ pull_request:+ paths:+ - 'rust/**'+ - 'src/core/rust-engine**'+ - 'src/core/sql-engine-kind.ts'+ - 'src/core/engine.ts'+ - 'src/core/engine-*.ts'+ - 'src/core/engine-sql/**'+ - 'src/schema.sql'+ - 'src/core/migrate.ts'+ - 'src/core/schema-migrations/**'+ - 'src/core/persistence/graduation-*.ts'+ - 'test/helpers/test-backends.ts'+ - '**/test/rust-unit-arms.txt'+ - '**/scripts/rust-unit-arms.ts'+ - '.github/workflows/rust-engine.yml'+ push:+ branches: [master]+ paths:+ - 'rust/**'+ - 'src/core/rust-engine**'+ - 'src/core/sql-engine-kind.ts'+ - 'src/core/engine.ts'+ - 'src/core/engine-*.ts'+ - 'src/core/engine-sql/**'+ - 'src/schema.sql'+ - 'src/core/migrate.ts'+ - 'src/core/schema-migrations/**'+ - 'src/core/persistence/graduation-*.ts'+ - 'test/helpers/test-backends.ts'+ - '**/test/rust-unit-arms.txt'+ - '**/scripts/rust-unit-arms.ts'+ - '.github/workflows/rust-engine.yml'+ workflow_dispatch:+ schedule:+ - cron: '17 7 * * *' # daily 07:17 UTC: cargo-deny advisories on master (checks job only)++permissions:+ contents: read++concurrency:+ group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}+ cancel-in-progress: true++env:+ CARGO_TERM_COLOR: never+ CARGO_INCREMENTAL: '0'++jobs:+ # Event parity (docs/TESTING.md#event-parity): see the named exceptions in the header. Off a+ # pull request every output is the full set. On a pull request whose file list cannot be read+ # (the API stops at 3000 files, or the call fails), everything runs.+ scope:+ runs-on: ubicloud-standard-2-ubuntu-2404+ timeout-minutes: 5+ permissions:+ contents: read+ pull-requests: read+ outputs:+ rust: ${{ steps.scope.outputs.rust }}+ targets: ${{ steps.scope.outputs.targets }}+ steps:+ - id: scope+ shell: bash+ env:+ GH_TOKEN: ${{ github.token }}+ EVENT: ${{ github.event_name }}+ PR: ${{ github.event.pull_request.number }}+ REPO: ${{ github.repository }}+ CHANGED_FILES: ${{ github.event.pull_request.changed_files }}+ run: |+ set -euo pipefail+ rust=true+ macos=true+ if [ "$EVENT" = pull_request ]; then+ if [[ "$CHANGED_FILES" =~ ^[0-9]{1,4}$ ]] && [ "$CHANGED_FILES" -lt 3000 ] \+ && files=$(gh api --paginate "repos/$REPO/pulls/$PR/files?per_page=100" --jq '.[].filename'); then+ grep -Eq '^rust/' <<< "$files" || rust=false+ grep -Eq '^(rust/|src/core/rust-engine(\.ts$|/))' <<< "$files" || macos=false+ fi+ fi+ linux='{"target":"linux-x64-glibc","runner":"ubicloud-standard-4-ubuntu-2404"}'+ # Unverified before the first CI run: the dylib name (libgbrain_napi.dylib) and Bun+ # loading an unsigned .node with process.dlopen.+ darwin='{"target":"darwin-arm64","runner":"macos-26"}'+ if [ "$macos" = true ]; then targets="[$linux,$darwin]"; else targets="[$linux]"; fi+ echo "scope: event=$EVENT rust=$rust macos=$macos"+ echo "rust=$rust" >> "$GITHUB_OUTPUT"+ echo "targets=$targets" >> "$GITHUB_OUTPUT"++ checks:+ name: Format, clippy, unit tests, cargo-deny+ needs: scope+ runs-on: ubicloud-standard-4-ubuntu-2404+ timeout-minutes: 25+ steps:+ - id: checkout+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4+ timeout-minutes: 3+ continue-on-error: true+ with:+ persist-credentials: false+ - name: Check out again after a stalled first attempt+ if: steps.checkout.outcome == 'failure'+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4+ timeout-minutes: 3+ with:+ persist-credentials: false+ # rustup reads the pinned version from rust/rust-toolchain.toml. Every runner this workflow+ # uses ships rustup; a runner without it fails here rather than piping an installer into sh.+ - name: Install the pinned Rust toolchain+ shell: bash+ run: |+ set -euo pipefail+ if ! command -v rustup >/dev/null 2>&1; then+ echo "::error::rustup is not installed on this runner. Use a runner image that ships rustup."+ exit 1+ fi+ channel="$(sed -n 's/^channel = "\(.*\)"$/\1/p' "$GITHUB_WORKSPACE/rust/rust-toolchain.toml")"+ test -n "$channel"+ rustup toolchain install "$channel" --profile minimal --component clippy --component rustfmt+ rustup default "$channel"+ rustc --version+ cargo --version+ # The cache name is built in a step so the cache key line holds no long literal value.+ - name: Name the cache from the lock file and toolchain+ id: cachename+ run: echo "value=rust-checks-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('rust/Cargo.lock', 'rust/rust-toolchain.toml') }}" >> "$GITHUB_OUTPUT"+ - uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3+ with:+ path: |+ ~/.cargo/registry+ ~/.cargo/git+ rust/target+ key: ${{ steps.cachename.outputs.value }}+ restore-keys: |+ rust-checks-${{ runner.os }}-${{ runner.arch }}-+ - name: Format+ working-directory: rust+ run: cargo fmt --check+ - name: Clippy+ working-directory: rust+ run: cargo clippy --all-targets --locked -- -D warnings+ - name: Unit tests+ working-directory: rust+ run: cargo test --locked+ # A pinned prebuilt binary, checked against its SHA-256, so CI does not compile cargo-deny+ # and does not depend on a third-party action.+ - name: Install cargo-deny 0.21.0+ working-directory: ${{ runner.temp }}+ run: |+ set -euo pipefail+ archive=cargo-deny-0.21.0-x86_64-unknown-linux-musl.tar.gz+ curl -fsSL --retry 3 -o "$archive" "https://github.com/EmbarkStudios/cargo-deny/releases/download/0.21.0/$archive"+ echo "a2170b854ff697e79e39c4c538981c9c1bdd803addbae6719a4cb66b4585a903 $archive" | sha256sum -c -+ mkdir -p "$RUNNER_TEMP/cargo-deny-bin"+ tar -xzf "$archive" --strip-components=1 -C "$RUNNER_TEMP/cargo-deny-bin" cargo-deny-0.21.0-x86_64-unknown-linux-musl/cargo-deny+ echo "$RUNNER_TEMP/cargo-deny-bin" >> "$GITHUB_PATH"+ - name: cargo-deny (licenses, bans, sources)+ working-directory: rust+ run: cargo deny --locked check licenses bans sources+ # Event parity (docs/TESTING.md#event-parity): named exception, see the header.+ - name: cargo-deny (advisories)+ if: needs.scope.outputs.rust == 'true'+ working-directory: rust+ run: cargo deny --locked check advisories++ # Event parity (docs/TESTING.md#event-parity): the scope job picks the cells (named exception in+ # the header); the schedule runs only `checks`. macOS minutes cost more than Linux.+ addon:+ name: Addon and Bun smoke / ${{ matrix.target }}+ needs: scope+ if: github.event_name != 'schedule'+ runs-on: ${{ matrix.runner }}+ timeout-minutes: 30+ strategy:+ fail-fast: false+ matrix:+ include: ${{ fromJSON(needs.scope.outputs.targets) }}+ steps:+ - id: checkout+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4+ timeout-minutes: 3+ continue-on-error: true+ with:+ persist-credentials: false+ - name: Check out again after a stalled first attempt+ if: steps.checkout.outcome == 'failure'+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4+ timeout-minutes: 3+ with:+ persist-credentials: false+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2+ with:+ bun-version: 1.4.4+ # rustup reads the pinned version from rust/rust-toolchain.toml. Every runner this workflow+ # uses ships rustup; a runner without it fails here rather than piping an installer into sh.+ - name: Install the pinned Rust toolchain+ shell: bash+ run: |+ set -euo pipefail+ if ! command -v rustup >/dev/null 2>&1; then+ echo "::error::rustup is not installed on this runner. Use a runner image that ships rustup."+ exit 1+ fi+ channel="$(sed -n 's/^channel = "\(.*\)"$/\1/p' "$GITHUB_WORKSPACE/rust/rust-toolchain.toml")"+ test -n "$channel"+ rustup toolchain install "$channel" --profile minimal --component clippy --component rustfmt+ rustup default "$channel"+ rustc --version+ cargo --version+ # The cache name is built in a step so the cache key line holds no long literal value.+ - name: Name the cache from the lock file and toolchain+ id: cachename+ run: echo "value=rust-addon-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('rust/Cargo.lock', 'rust/rust-toolchain.toml') }}" >> "$GITHUB_OUTPUT"+ - uses: actions/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3+ with:+ path: |+ ~/.cargo/registry+ ~/.cargo/git+ rust/target+ key: ${{ steps.cachename.outputs.value }}+ restore-keys: |+ rust-addon-${{ runner.os }}-${{ runner.arch }}-+ - name: Build the addon+ run: bun run rust:build+ - name: Smoke test under Bun (in-process cases, process.exit, compiled executable)+ shell: bash+ run: |+ set -euo pipefail+ export GBRAIN_RUST_ENGINE_ADDON="$PWD/rust/target/addon/gbrain_engine.${{ matrix.target }}.node"+ test -f "$GBRAIN_RUST_ENGINE_ADDON"+ bun rust/smoke/run.ts+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4+ with:+ name: gbrain-engine-addon-${{ matrix.target }}+ path: rust/target/addon/gbrain_engine.${{ matrix.target }}.node+ if-no-files-found: error+ retention-days: 7++ # Event parity (docs/TESTING.md#event-parity): the schedule runs only `checks`.+ without-rust:+ name: Builds and runs with no Rust installed+ if: github.event_name != 'schedule'+ runs-on: ubicloud-standard-4-ubuntu-2404+ timeout-minutes: 20+ steps:+ - id: checkout+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4+ timeout-minutes: 3+ continue-on-error: true+ with:+ persist-credentials: false+ - name: Check out again after a stalled first attempt+ if: steps.checkout.outcome == 'failure'+ uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4+ timeout-minutes: 3+ with:+ persist-credentials: false+ - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2+ with:+ bun-version: 1.4.4+ - name: Install dependencies (bounded, retried once)+ timeout-minutes: 8+ run: bun scripts/ci-bun-install.ts --frozen-lockfile --ignore-scripts+ - name: Remove Rust from PATH, then build and run gbrain+ shell: bash+ run: |+ set -euo pipefail+ # Drop every PATH directory that holds cargo, rustc or rustup. System directories are kept;+ # if Rust lives in one, the check below fails loudly instead of breaking the shell.+ filtered=""+ IFS=: read -r -a dirs <<< "$PATH"+ for dir in "${dirs[@]}"; do+ case "$dir" in+ /usr/bin|/bin|/usr/local/bin|/usr/sbin|/sbin)+ filtered="${filtered:+$filtered:}$dir"+ continue+ ;;+ esac+ if [ -e "$dir/cargo" ] || [ -e "$dir/rustc" ] || [ -e "$dir/rustup" ]; then+ echo "removing from PATH: $dir"+ continue+ fi+ filtered="${filtered:+$filtered:}$dir"+ done+ export PATH="$filtered"+ for tool in cargo rustc rustup; do+ if command -v "$tool" >/dev/null 2>&1; then+ echo "::error::$tool is still on PATH: $(command -v "$tool")"+ exit 1+ fi+ done+ bun run build+ ./bin/gbrain --version+ # The Rust build script must refuse politely, not half-build.+ if bun run rust:build > rust-build.log 2>&1; then+ echo "::error::rust:build succeeded without cargo"+ exit 1+ fi+ grep -q 'cargo was not found' rust-build.logdiff --git a/.gstack/pregate.json b/.gstack/pregate.jsonindex dc8dee366b..1b7d66e4ea 100644--- a/.gstack/pregate.json+++ b/.gstack/pregate.json@@ -107,7 +107,13 @@"skills/skill-budgets.tsv": ["test/skill-health.test.ts"],"skills/skills.lock.history.json": ["test/skills-integrity.test.ts", "test/skillpack-safe-update.test.ts"],"scripts/check-migration-projection.ts": ["test/scripts/check-migration-projection.test.ts"],- "scripts/migration-projection-baseline.tsv": ["test/scripts/check-migration-projection.test.ts"]+ "scripts/migration-projection-baseline.tsv": ["test/scripts/check-migration-projection.test.ts"],+ "rust/Cargo.toml": ["rust/crates/gbrain-napi/src/pool.rs"],+ "rust/Cargo.lock": ["rust/crates/gbrain-napi/src/pool.rs"],+ "rust/deny.toml": ["rust/crates/gbrain-napi/src/pool.rs"],+ "rust/rust-toolchain.toml": ["rust/crates/gbrain-napi/src/pool.rs"],+ "rust/scripts/**": ["rust/smoke/smoke.test.ts"],+ "rust/smoke/**": ["rust/smoke/smoke.test.ts"]},"guards": [{diff --git a/changelog.d/engine-capabilities.md b/changelog.d/engine-capabilities.mdnew file mode 100644index 0000000000..f3975eda4f--- /dev/null+++ b/changelog.d/engine-capabilities.md@@ -0,0 +1,4 @@+**Storage engines now report what they can do as a set of named capabilities, so code can ask for a capability instead of checking which engine it runs on.**++### Changed+- `BrainEngine.capabilities` is a read-only set of named capabilities (`raw_sql`, `persistence_journal`, `minion_queue`, `access_control`, `belief_ledger`, `single_owner`, `postgres_admin`, and one per storage domain). PGLite and Postgres report everything they support today, so nothing is refused and no behavior changes. `src/core/engine-capabilities.ts` holds the list and the table of what each operation, command, cycle phase and job handler needs; a name without a row needs raw SQL. Groundwork for the optional Rust engine (https://github.com/garrytan/gbrain/pull/9593, "PR sequence" step 5).diff --git a/changelog.d/eval-harness-any-engine.md b/changelog.d/eval-harness-any-engine.mdnew file mode 100644index 0000000000..78661862eb--- /dev/null+++ b/changelog.d/eval-harness-any-engine.md@@ -0,0 +1,4 @@+**The in-tree LongMemEval and BrainBench harnesses now accept any storage engine, not only PGLite, so a future engine can run the same evals.**++### Changed+- `src/eval/**` and `gbrain eval longmemeval` take a `BrainEngine` wherever they took a `PGLiteEngine`. The benchmark brain they build is still an in-memory PGLite brain, so eval results and commands are unchanged. Groundwork for the optional Rust engine (https://github.com/garrytan/gbrain/pull/9593, "PR sequence" step 4).diff --git a/changelog.d/rust-engine-addon-loader.md b/changelog.d/rust-engine-addon-loader.mdnew file mode 100644index 0000000000..8abd2e7377--- /dev/null+++ b/changelog.d/rust-engine-addon-loader.md@@ -0,0 +1,9 @@+**gbrain has a loader that checks and loads the experimental Rust engine addon from the gbrain home, refusing with a typed error that names the reason when it cannot; nothing starts it yet, and PGLite and Postgres brains never load the addon.**++### Added+- `loadRustEngineAddon()` (`src/core/rust-engine/addon-loader.ts`) loads the addon for the Rust engine shell. No config value selects the Rust engine yet, so no command calls it. It uses `GBRAIN_RUST_ENGINE_ADDON` when you point it at your own build, and otherwise an addon already in `<gbrain home>/engines/rust/` whose checksum matches this release's manifest. It downloads nothing and writes nothing.+- Two error codes: `rust_engine_addon_missing` (no addon for this release is installed, the `GBRAIN_RUST_ENGINE_ADDON` file does not exist, or no addon is published for this platform) and `rust_engine_addon_mismatch` (checksum, `engine_abi`, `engine_build` or target differ, or the file does not load). Both refuse before the brain is touched and write nothing. `gbrain errors <code>` explains each one.++### Fixed+- The addon refuses typed arrays backed by shared memory by asking the runtime, so hiding `SharedArrayBuffer` or swapping a prototype no longer gets shared memory past the check.+- `bun run rust:build` ignores `CARGO_TARGET_DIR`, so it never packages an older library from another build directory.diff --git a/changelog.d/rust-engine-shell.md b/changelog.d/rust-engine-shell.mdnew file mode 100644index 0000000000..773df82e82--- /dev/null+++ b/changelog.d/rust-engine-shell.md@@ -0,0 +1,8 @@+**The Rust engine has a shell that refuses every storage call with a typed error until its storage lands; PGLite and Postgres brains are unchanged.**++### Added+- `openRustEngine({ addon, databasePath })` (`src/core/rust-engine.ts`) builds the Rust engine shell around an addon the loader already verified. It reports no capabilities. Plan: https://github.com/garrytan/gbrain/pull/9593, "PR sequence" step 8.+- Every `BrainEngine` member the shell does not implement refuses `engine_capability_missing` with the capability as its reason and `written=nothing`, before any work. `src/core/rust-engine/members.ts` classifies each member, and the type fails when a new member is left out.++### Changed+- Every place that assumed exactly two engine kinds now handles the Rust kind (`EngineKind`, `src/core/sql-engine-kind.ts`): SQL-only paths (migrations, cycle locks, engine migration and graduation, embed backfill, page-body batch sizes) refuse it with `engine_capability_missing` instead of treating it as Postgres. The graduation inventory records `rust: false` on every relation.diff --git a/changelog.d/rust-engine-toolchain.md b/changelog.d/rust-engine-toolchain.mdnew file mode 100644index 0000000000..8fd2f2073f--- /dev/null+++ b/changelog.d/rust-engine-toolchain.md@@ -0,0 +1,7 @@+**Contributors can now build an experimental Rust engine addon and check it against Bun with `bun run rust:build` and `bun rust/smoke/run.ts`; gbrain itself does not use it yet and still builds without Rust.**++### Added+- A Rust workspace under `rust/` with one Node-API addon crate. It loads in Bun and reports its target, engine version, a build hash and catalog version. It also holds the proof pieces the later Rust engine work builds on: a worker pool whose calls return promises, cancellation, panics turned into ordinary JavaScript errors, a shutdown that cancels queued work and waits a bounded time for running work, typed-array calls, and a bounded callback queue.+- `bun run rust:build` builds the addon and prints its path and the `GBRAIN_RUST_ENGINE_ADDON=...` line to export. Without Rust installed it stops with install instructions and writes nothing.+- `bun rust/smoke/run.ts` runs the addon through those behaviors under Bun, including a child process that calls `process.exit(0)` while native work is running and a single-file `bun build --compile` executable that loads the addon.+- A `Rust engine` workflow runs only when Rust files or the engine files it depends on change. It checks formatting, clippy, unit tests and cargo-deny, builds and smoke-tests the addon on Linux and macOS, and builds and runs gbrain with Rust removed from `PATH`. `rust/README.md` covers the contributor setup.diff --git a/changelog.d/vorflux-upload-path-dotdot-dir.md b/changelog.d/vorflux-upload-path-dotdot-dir.mdnew file mode 100644index 0000000000..79a0a0583c--- /dev/null+++ b/changelog.d/vorflux-upload-path-dotdot-dir.md@@ -0,0 +1,8 @@+---+important: security+---+**An agent can upload a file that sits in a folder whose name starts with two dots, such as `..drafts/report.pdf`, inside the working directory.**++### Fixed+- `file_upload` over MCP refused a file under a folder like `..drafts/` or `.../` in the working directory with "Upload path must be within the working directory", because the confinement check matched any path whose first name starts with `..`. The check now compares whole path parts on the resolved paths, so only a path that resolves outside the working directory (through `..`, a sibling folder that shares the working directory's name, or a symlinked parent), a symlinked file and the working directory itself are refused. Local CLI uploads were never affected.+- On Windows, an upload path on another drive or a network (UNC) share is now refused for remote callers. The old check accepted it. This is shown with Node's `path.win32`, not on a Windows machine.diff --git a/docs/ENGINES.md b/docs/ENGINES.mdindex 1bae816e43..fae5ad713e 100644--- a/docs/ENGINES.md+++ b/docs/ENGINES.md@@ -1596,6 +1596,35 @@ The real backstop is `test/e2e/op-checkpoint-jsonb-parity.test.ts` +`test/e2e/jsonb-roundtrip.test.ts`, which round-trip writes through real Postgresand assert `jsonb_typeof` — the assertion PGLite cannot make.+## The Rust engine shell++The opt-in Rust engine (`docs/designs/RUST_ENGINE.md`) is under construction. PGLite and Postgres behave exactly+as before, and an install needs no Rust toolchain and no addon. `openRustEngine({ addon, databasePath })`+(`src/core/rust-engine.ts`) is the one seam: the addon loader calls it after it has loaded and verified the native+addon, and gets back the engine: every `BrainEngine` member, with `kind` `'rust'`. `BrainEngine.kind` admits `'rust'`+when the `rust` config value lands; no config value selects the Rust engine yet. Finding, checking and loading the+addon, and refusing a missing or mismatched one, belong to the loader (below), not the shell.++- **Capabilities.** The shell declares no capabilities. Each `BrainEngine` member it does not implement refuses+ `engine_capability_missing` with the capability as `reason` (`raw_sql`, `pages`, `search`, ...), the member in+ `detail`, and `written=nothing`, before any work. `src/core/rust-engine/members.ts` maps every member to its+ capability; the type fails when a new `BrainEngine` member is not classified.+- **SQL-only paths.** Code that only works through SQL (migrations, cycle locks, engine migration and graduation,+ embed backfill, page-body staging) takes the kind as `EngineKind`, narrows it with `sqlEngineKind` or+ `isRustEngineKind` (`src/core/sql-engine-kind.ts`), and refuses a Rust brain with `engine_capability_missing` reason `raw_sql` instead of treating it as Postgres.+- **The addon loader.** `loadRustEngineAddon()` (`src/core/rust-engine/addon-loader.ts`) returns the loaded addon,+ or the refusal `rust_engine_addon_missing` or `rust_engine_addon_mismatch` with its `reason` (`gbrain errors+ <code>`), before the brain is touched. It uses `GBRAIN_RUST_ENGINE_ADDON` (an absolute path to a build from `bun run+ rust:build`; it skips only the release checksum pin) first, then an addon cached at+ `<gbrain home>/engines/rust/<engine_build>/<target>.node` whose SHA-256 equals the cached manifest of this gbrain+ version. It never reaches the network and writes nothing: with no cached addon it refuses with reason+ `not_installed`, and a cached file that fails a check stays as it was. Fetching the release's addon into that cache+ arrives with the capability gate. Only the Rust engine's open path may import the loader, lazily, so a PGLite or+ Postgres brain never loads the addon or creates `<gbrain home>/engines/`.+- **Shared memory.** The addon refuses a typed array whose buffer the runtime (`napi_is_arraybuffer`) does not call a+ plain `ArrayBuffer`, so a `SharedArrayBuffer` view is refused with `InvalidArg` however JavaScript globals or+ prototypes have been changed (`rust/README.md`).+## Adding a new engine1. Create `src/core/<name>-engine.ts` implementing `BrainEngine`@@ -1609,7 +1638,9 @@ and assert `jsonb_typeof` — the assertion PGLite cannot make.engines do. Declare its capabilities honestly. The binding matrix(`test/helpers/executor-binding-matrix.ts`) and the engine-sql contracttests tell you whether the adapter binds, counts, fails and cancels like the- others. A non-SQL engine implements every method itself.+ others. A non-SQL engine implements typed methods instead of a `SqlExecutor`:+ it declares no `raw_sql` capability, and each member it cannot serve yet+ refuses `engine_capability_missing` (see "The Rust engine shell" above).4. Store engine type in `~/.gbrain/config.json`: `{ "engine": "myengine", ... }`5. Add tests. The test suite should be engine-agnostic where possible... same test cases, different engine constructor.6. Document in this file + add a design doc in `docs/`diff --git a/docs/architecture/key-files/engines-1-continued.md b/docs/architecture/key-files/engines-1-continued.mdnew file mode 100644index 0000000000..0eb49d691a--- /dev/null+++ b/docs/architecture/key-files/engines-1-continued.md@@ -0,0 +1,8 @@+# Key files: Engines (1/2, continued)++[Subsystem index](../KEY_FILES.md) · [Previous entries](engines-1.md). Read only the entries relevant to your change.+Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.++- `src/core/pglite-legacy-lock.ts` — core of `gbrain pglite-repair --legacy-lock` (C-3): read-only `inspectLegacyLock` (verdict, plan hash over the legacy dir, advisory this-host-only evidence: kill -0, /proc fd scan, statfs; refuses `live_holder`/`network_filesystem`/`filesystem_unverified`, the last when locality is unknown: neither Linux statfs nor macOS `df -P` + `mount` (`local` flag and a known-local type) confirms a local disk, or a probe failed) and `applyLegacyLockRemoval` (moves the dir aside with a receipt, backs up the prior ownership marker bytes, writes the kernel-v1 marker; the restore command puts the marker back). Test: `test/pathological/c3-pglite-legacy-lock.test.ts`.+- `src/core/pglite-repair.ts` — WAL-repair orchestrator wrapping the resetWal port with the safety layers that make it runnable automatically from `connect()`: `validateWalRepairTarget` (read-only, fail-closed; refuses symlinked dataDir/pg_wal/`global`/pg_control — lstat follows INTERMEDIATE symlinks, so `global/` itself must be checked or surgery would write pg_control through it into a foreign dir; tolerates the in-dir `.gbrain-lock`), rename-based backup (the ENTIRE `pg_wal/` dir + postmaster.pid renamed into a sibling `<dataDir>.wal-repair-backup-<ts>/`, only the 8KB pg_control copied — zero transient disk cost), `restoreWalBackup` (overwrite order: control first via atomic tmp+rename, then a pg_wal dir swap with the reset dir set ASIDE inside the backup — nothing is ever deleted during restore; mtime guard refuses when a foreign segment is newer than the backup; a missing/empty backup NEVER reports `restored:true`), `WalRepairError` (thrown when resetWal fails AFTER the backup — carries the receipt + the best-effort restore's REAL result so the seam's `restored` flag and the `failed-restored`/`failed-not-restored` message arms never lie), a cooldown sidecar `<dataDir>.wal-repair-attempt.json` (skip `'recently-failed'` inside `GBRAIN_PGLITE_WAL_REPAIR_COOLDOWN_SECONDS`, default 3600 — bounds the autopilot/supervisor reconnect loops) with episode-scoped backups (attempts within one corruption episode REUSE the episode's first backup — the pre-damage forensic state, honored only when the sidecar's path is a real non-symlink `<dataDir>.wal-repair-backup-*` sibling since the sidecar is user-writable JSON; retention keeps the newest 3 episodes, never pruning the open episode's), and `attemptWalRepairAndRetry` — the engine seam that NEVER throws (gates: kill-switch → reaped-lock `'possibly-live-writer'` → 10-minute reap-marker quarantine (`msSinceLastReap`, cross-process) → validation → cooldown; then repair → retry create once → restore-and-record on failure; prints a repair-start stderr line so a timeout-killed attempt is self-explaining). `inspectPgliteDataDir` is the read-only diagnosis for `gbrain doctor` + `pglite-repair --dry-run`. Imports runtime values only from `pglite-lock.ts`/`pglite-resetwal.ts`/node:fs — never from `pglite-engine.ts` (no cycle; the engine statically imports THIS file per the engine-live rule). Pinned by `test/pglite-repair.test.ts` + `test/pglite-wal-repair.serial.test.ts`.+- `src/core/pglite-repair-consent.ts` + the repair-failed marker in `src/core/pglite-repair.ts` — when automatic WAL repair fails (or a recent failure put it on cooldown) `recordFailedAutoRepair` writes the sibling `<dataDir>.repair-failed.json`; while it exists `PGLiteEngine.connect()` refuses before `acquireLock` (zero writes to the data dir) with `repairFailedRefusal`: the exit-3 consent payload (effects `destructive`, fix `gbrain pglite-repair [--path] --yes --expect <plan_hash>` from the same `walRepairPlan` the command binds, preview `--dry-run --json`, and the hands-off text `HANDS_OFF_BRAIN_FILES`). The CLI's `exitOnRepairFailed` (`src/cli/cli-error.ts`) exits 3 on it from `connectEngine`; stdio serve maps it to status reason `repair_failed`. Cleared by a completed `pglite-repair` or `reinit-pglite`. Pinned by `test/agent-operator-gate-fixes.{,serial.}test.ts`.diff --git a/docs/architecture/key-files/engines-1.md b/docs/architecture/key-files/engines-1.mdindex a64dc3dd7b..f9a04a41b5 100644--- a/docs/architecture/key-files/engines-1.md+++ b/docs/architecture/key-files/engines-1.md@@ -20,6 +20,8 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/embedding-migration.ts` — provider-agnostic embedding migration core; owns the schema-transition + env-gate primitives. `runSchemaTransition(engine, targetDim)`: ONE transaction rebuilds all four dim-pinned text-embedding-space columns (`content_chunks.embedding`, `query_cache.embedding`, `facts.embedding`, `takes.embedding`) preserving each column's `vector`/`halfvec` type, HNSW gated on `hnswIndexExpected` (dims > 2000 skip the index; exact scans stay correct — 2048d targets work); the HNSW indexes of every rebuilt text-embedding column (`content_chunks` canonical and custom, plus each `TEXT_EMBEDDING_DIM_PINNED_TABLES` entry via `transitionDimPinnedColumn`'s returned definition; the allowed set is `DEFERRED_ANN_TABLES`) are NOT rebuilt in the transaction but recorded in the marker as `deferred_ann_indexes` (`recordDeferredAnnIndexes`) and built after the re-embed drain by `src/core/embedding-ann-build.ts` (CONCURRENTLY on Postgres, INVALID remnants dropped first, one marker update per built index; config-planted definitions outside `<deferred table> USING hnsw (embedding …)` are rejected), while btree/partial dependents replay immediately; `verifyMigrationComplete` blocks on pending or INVALID ANN indexes (`migrate-embeddings-ann-deferred-5088.serial.test.ts`); image/multimodal columns deliberately untouched; AFTER commit it clears `embedded_at` in yielding 50k batches (belt-and-braces hygiene — read surfaces key on the vector itself). `planEmbeddingMigration`: workload via widened stale predicates (absent-column fallback counts every chunk), cost, `signature_census` (top-5 page signatures — DB-reality corroboration of From), `synopsis_tier_pages` (context-tier downgrade consent), bundle-aware `reranker_warning`, `dim_change` via the shared `schemaRebuildNeeded` (null ⇒ rebuild, same computation apply uses). `applyEmbeddingMigration`: env≠target refusal (`detectEnvOverride`; `detectEnvPresence` drives the ==target notice) → marker v2 write (same-target re-apply preserves `started_at`; retarget records `superseded` history) → full rebuild when the chunks column is off-width, else INDEPENDENT repair of stale dim-pinned columns (`readDimPinnedWidths`) → false-target-stamp clearing (chunk-model truth) + guarded NULL-signature-inclusive invalidation (embed_skip pages' retained vectors preserved; both via `embedding-invalidation.ts`) BEFORE config writes (same-dim-swap crash safety) → DB plane → file-plane callback → cache purge. `verifyMigrationComplete`: the ONLY basis for "nothing to migrate" — column + pinned widths, wide stale census, false-stamp census blocker (embedded chunks whose `model` contradicts a page already stamped with the target signature), `missing_embeddings` residue, chunkless-pages census, embed_skip-NULL visibility (report-only detail, never a blocker), marker state, un-merged file plane (or env-canonical), env-contradiction blocker; never trusts `from_model`. `completeEmbeddingMigration`: marker delete + completion stamp in ONE transaction (no lost-receipt crash window); accepts content-free `extra` (smoke-check outcome). `readMigrationState` (corrupt-safe), `readMigrationStatus` (read-only, spend-free, everything-degrades-to-null), `verifySearchRoundTrip` (completion smoke check: one sample per distinct eligible page, picked by an index-ordered walk of the newest eligible chunks bounded at 1,000; the longest eligible chunk is re-read under the page lock and queried as title (160 chars) plus chunk (512); query-side `embedQuery` + `searchVector`, hit identity by page_id, NEVER throws, warn-don't-block, content-free samples), `resolveRerankerExposure`/`resolveRerankerPlan`/`applyRerankerAction` (D8 companion switch: bundle-resolved exposure; auto→target-provider default reranker, never a silent third provider; config write + cache purge in one tx), `reconcilePageSignatures` (batch-boundary stamp repair). Engine-pure; every step idempotent under crash + re-run — the NULL-embedding column is the checkpoint. Pinned by `test/embedding-migration.test.ts`, `test/migrate-embeddings-hardening.serial.test.ts`, `test/e2e/migrate-embeddings-postgres.test.ts`.+- `src/core/engine-capabilities.ts` — the named capabilities an engine reports (`BrainEngine.capabilities`, a read-only set) and the table of what each operation, CLI command, cycle phase and minion handler needs. PGLite and Postgres report every shared capability plus `raw_sql`; only PGLite reports `single_owner` and only Postgres reports `postgres_admin`. `capabilitiesForEngineKind` returns a fresh set per engine. `requiredCapabilities(consumer, name)` answers `['raw_sql']` for any name without a row, and `missingCapabilities(engine, consumer, name)` lists what an engine lacks (empty on both SQL engines). Callers ask a capability instead of branching on `engine.kind`. Pinned by `test/engine-capabilities.test.ts`.+- `src/core/engine-constants.ts` — single source of truth for engine batch-sizing constants. Exports `DELETE_BATCH_SIZE = 500` consumed by both engines' `deletePages` + `resolveSlugsByPaths` and by the sync delete + rename loops. Lives outside `engine.ts` (the interface module) to avoid circular-import worry — bounded per-statement work for predictable lock hold time + write amplification. Also exports `TRAVERSE_PATH_ROW_CAP = 5000`, the raw-row bound on `traversePaths`/`traversePathsDetailed` (both engines `LIMIT CAP + 1`; the extra row is the truncation probe; counted before edge dedup), and `TRAVERSE_WALK_ROW_CAP = 20000`, the bound on simple-path rows the recursive walks enumerate (`traverseGraph` and `traversePaths*`, both engines). The walk CTE is pulled through `LIMIT` so a dense hub stops enumerating, rows are deduped to `(page, depth)` before the edge join or the per-node link aggregation, and `traversePaths` stops recursing one layer early because the deepest layer only terminates edges. A capped walk sets `truncated` on `traversePathsDetailed`.- `src/core/engine-sql/bootstrap.ts` — the forward-reference bootstrap, one implementation for both engines (refactor wave 1, E1): probes, in one round-trip, every column/table the embedded schema blob forward-references that older brains may lack, and adds only what is missing (column-only `ADD COLUMN IF NOT EXISTS`, plus the `sources` table + default seed and `SET DEFAULT` where the upgrade window needs it); fresh installs and current brains no-op. Callers: `PGLiteEngine.initSchema` (`pgliteBootstrapTarget(db)`), `PostgresEngine.initSchema` and `db.ts:initSchema` (`applyPostgresForwardReferenceBootstrap(conn)`, on the DDL connection holding advisory lock 42; the db.ts path replays the blob without migrations, safe because NULL-tolerant read predicates accept pre-backfill rows). Engine differences are dialect hooks: probe schema (`current_schema()` vs `'public'`), the Postgres-blob-only `dream_verdicts.expires_at` probe + ALTER (inside `dialect-only:postgres` markers so the PGLite coverage check does not count it), and the per-engine position of the v39 `content_chunks` ALTER. The Postgres probe runs with tagged-template driver options (prepared on direct Postgres, unprepared through PgBouncer). A snapshot-hash root (`snapshot-schema-inputs.ts`). Covered by `test/schema-bootstrap-coverage.test.ts` (parses this file), `test/bootstrap.test.ts` and `test/e2e/postgres-bootstrap.test.ts`; per-probe inventory in `docs/designs/refactor-wave-1/w1-inventory.md`.@@ -43,6 +45,4 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/pglite-statements.ts` — `PgliteStatementCache`, the PGLite counterpart of postgres.js prepared statements. `PGLiteEngine._attachDatabase` routes the root handle's `query`/`exec` through it and `transaction()` routes each transaction handle. A statement text seen twice is prepared once as a named server-side statement; later calls send one Bind/Execute/Sync batch and parse rows with parsers resolved at prepare time, instead of PGlite's parse/describe round trips and its per-query copy of `db.parsers`. PostgreSQL's plan cache replans on invalidation; a changed result shape (`0A000`) or missing statement (`26000`) drops the entry and retries outside a transaction. `ALTER`/`CREATE`/`DROP`/`DO`/`DISCARD`/`DEALLOCATE` text, `ANALYZE`/`VACUUM` (PostgreSQL keeps a prepared plan across a statistics refresh, so a plan made before the table had statistics would outlive planner-stats' first-read ANALYZE) and any non-transaction-control `exec` clear the cache, retired names are closed in the next prepare batch, an instance-level `query`/`exec` override (test seams) takes precedence on the root handle, and `_closeInternal` drops the cache with the database so a disconnected engine does not retain its PGLite instance. `configurePgliteCodecs` removes composite-row array parsers after connect, since gbrain never selects those arrays, and replaces PGlite's per-byte bytea codec with Buffer's hex codec (a 4 MiB bytea batch no longer allocates ~250 MB of garbage). Pinned by `test/pglite-statements.test.ts`.-- `src/core/pglite-legacy-lock.ts` — core of `gbrain pglite-repair --legacy-lock` (C-3): read-only `inspectLegacyLock` (verdict, plan hash over the legacy dir, advisory this-host-only evidence: kill -0, /proc fd scan, statfs; refuses `live_holder`/`network_filesystem`/`filesystem_unverified`, the last when locality is unknown: neither Linux statfs nor macOS `df -P` + `mount` (`local` flag and a known-local type) confirms a local disk, or a probe failed) and `applyLegacyLockRemoval` (moves the dir aside with a receipt, backs up the prior ownership marker bytes, writes the kernel-v1 marker; the restore command puts the marker back). Test: `test/pathological/c3-pglite-legacy-lock.test.ts`.-- `src/core/pglite-repair.ts` — WAL-repair orchestrator wrapping the resetWal port with the safety layers that make it runnable automatically from `connect()`: `validateWalRepairTarget` (read-only, fail-closed; refuses symlinked dataDir/pg_wal/`global`/pg_control — lstat follows INTERMEDIATE symlinks, so `global/` itself must be checked or surgery would write pg_control through it into a foreign dir; tolerates the in-dir `.gbrain-lock`), rename-based backup (the ENTIRE `pg_wal/` dir + postmaster.pid renamed into a sibling `<dataDir>.wal-repair-backup-<ts>/`, only the 8KB pg_control copied — zero transient disk cost), `restoreWalBackup` (overwrite order: control first via atomic tmp+rename, then a pg_wal dir swap with the reset dir set ASIDE inside the backup — nothing is ever deleted during restore; mtime guard refuses when a foreign segment is newer than the backup; a missing/empty backup NEVER reports `restored:true`), `WalRepairError` (thrown when resetWal fails AFTER the backup — carries the receipt + the best-effort restore's REAL result so the seam's `restored` flag and the `failed-restored`/`failed-not-restored` message arms never lie), a cooldown sidecar `<dataDir>.wal-repair-attempt.json` (skip `'recently-failed'` inside `GBRAIN_PGLITE_WAL_REPAIR_COOLDOWN_SECONDS`, default 3600 — bounds the autopilot/supervisor reconnect loops) with episode-scoped backups (attempts within one corruption episode REUSE the episode's first backup — the pre-damage forensic state, honored only when the sidecar's path is a real non-symlink `<dataDir>.wal-repair-backup-*` sibling since the sidecar is user-writable JSON; retention keeps the newest 3 episodes, never pruning the open episode's), and `attemptWalRepairAndRetry` — the engine seam that NEVER throws (gates: kill-switch → reaped-lock `'possibly-live-writer'` → 10-minute reap-marker quarantine (`msSinceLastReap`, cross-process) → validation → cooldown; then repair → retry create once → restore-and-record on failure; prints a repair-start stderr line so a timeout-killed attempt is self-explaining). `inspectPgliteDataDir` is the read-only diagnosis for `gbrain doctor` + `pglite-repair --dry-run`. Imports runtime values only from `pglite-lock.ts`/`pglite-resetwal.ts`/node:fs — never from `pglite-engine.ts` (no cycle; the engine statically imports THIS file per the engine-live rule). Pinned by `test/pglite-repair.test.ts` + `test/pglite-wal-repair.serial.test.ts`.-- `src/core/pglite-repair-consent.ts` + the repair-failed marker in `src/core/pglite-repair.ts` — when automatic WAL repair fails (or a recent failure put it on cooldown) `recordFailedAutoRepair` writes the sibling `<dataDir>.repair-failed.json`; while it exists `PGLiteEngine.connect()` refuses before `acquireLock` (zero writes to the data dir) with `repairFailedRefusal`: the exit-3 consent payload (effects `destructive`, fix `gbrain pglite-repair [--path] --yes --expect <plan_hash>` from the same `walRepairPlan` the command binds, preview `--dry-run --json`, and the hands-off text `HANDS_OFF_BRAIN_FILES`). The CLI's `exitOnRepairFailed` (`src/cli/cli-error.ts`) exits 3 on it from `connectEngine`; stdio serve maps it to status reason `repair_failed`. Cleared by a completed `pglite-repair` or `reinit-pglite`. Pinned by `test/agent-operator-gate-fixes.{,serial.}test.ts`.+Continued in [Engines (1/2, continued)](engines-1-continued.md).diff --git a/docs/architecture/key-files/engines-2-continued.md b/docs/architecture/key-files/engines-2-continued.mdindex 2745736cd5..c891566c1b 100644--- a/docs/architecture/key-files/engines-2-continued.md+++ b/docs/architecture/key-files/engines-2-continued.md@@ -10,3 +10,5 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/migration-timeout.ts` — #7108 the migration statement budget (`migrationStatementTimeoutMs`, default 10 min; `setMigrationStatementTimeoutMs` from operator-only `gbrain apply-migrations --statement-timeout <minutes>`, restored when that run returns; 0 removes it) and the timed-out-migration record (config `schema_migration_timeout`: version, name, whether the run had a prelude, idle-in-transaction pids sampled at the failure): `runMigrations` writes it on a 57014 or a statement-timeout retry exhaustion and deletes it after a pass reaches head. A schema-graph leaf (no release version, so the PGLite snapshot hash stays stable). `migration-timeout-advice.ts` turns a record into the one fix both apply-migrations (`migrations_pending` still_behind) and doctor `schema_version` show: timed out unbatched and this release has a prelude → rerun; idle sessions open → ask_user, check `doctor --locks`, end the ones still open, rerun; none → ask_user, one run with `--statement-timeout 120`.- `src/core/owned-table-shapes.ts` — #9190 the shape check for tables gbrain owns by a generic name (`oauth_clients`, `oauth_tokens`, `oauth_codes`): one catalog query in `current_schema()` compares each existing table's v32 columns and their types with what gbrain has always created (a wrong type is named before a missing column), and `assertOwnedTableShapes` throws `foreign_table` (table, column, type found, type needed, the `SET SCHEMA` fix) on the first mismatch. `applyForwardReferenceBootstrap` (engine-sql/bootstrap.ts) runs it before any DDL, so `initSchema` on both engines refuses before the schema replay, and `runMigrations` runs it before its repairs and the first pending migration. Pinned on both engines by `test/upgrade-foreign-oauth-table.test.ts`.- `src/core/derived-state-maintainers.ts` + `src/core/schema-migrations/v281-derived-state-maintainers-fail-closed.ts` — #7637: the eight derived-state maintainer triggers (page retrievals, atom scan state, tag revision, version trust and attribution, page search vector, projection queue, trust generation) stay SECURITY INVOKER and fail closed. `requireMaintainerPoliciesSql(table, commands)` is the PL/pgSQL each body runs before touching another table: when `row_security_active(table)` holds and no permissive `pg_policy` row for the caller (PUBLIC or a role it has USAGE of) covers a command, it raises `writer_coordinator_required` (`managed_writer_guard:unreadable_state`, DETAIL `state` = the table), so an empty read never counts as nothing to do. Each body lives with its schema (`TAG_REVISION_FUNCTION_SQL`, `SNAPSHOT_VERSION_FUNCTION`, `STAMP_VERSION_FUNCTION`, `BUMP_FUNCTION`, `PAGE_PROJECTION_QUEUE_FUNCTION_SQL`, `pageSearchVectorTriggerFnSql`); the page retrievals body is a schema blob fragment here. v281 replaces only the functions (the search vector under the configured FTS language), never the triggers. The policies a scoped writer needs are the ENGINES.md maintainer recipe (`test/derived-state-maintainers-7637.test.ts`, applied verbatim).+- `src/core/rust-engine.ts` + `src/core/rust-engine/` — the opt-in Rust engine shell (ENGINES.md "The Rust engine shell"). `openRustEngine({ addon, databasePath })` is the one seam the addon loader calls after it has loaded and verified the native addon; it returns a `RustEngine` (every `BrainEngine` member except `kind`, which is `'rust'`; `BrainEngine.kind` admits it once the `rust` config value lands; no capabilities, D18) that keeps the addon handle and store path and owns only its lifecycle (`connect` records the config, `disconnect` runs the `registerBeforeDisconnect` stops, `reconnect` does both). Every other `BrainEngine` member is installed from the prototype loop and refuses `engine_capability_missing` (reason = `rustMemberCapability(member)`, detail `member=… capability=… outcome=none written=nothing`) before any work. `rust-engine/members.ts` (`RUST_ENGINE_MEMBERS`, `satisfies Record<keyof BrainEngine, MemberClass>`) classifies every member, so a new engine method fails typecheck until it is classified. `rust-engine/errors.ts` (`capabilityMissing(capability, member, outcome)`) builds the refusal. `src/core/sql-engine-kind.ts` (`EngineKind`, `isSqlEngineKind`, `isRustEngineKind`, `sqlEngineKind(kind, member)`) narrows a kind for SQL-only code and refuses `raw_sql` for Rust; `page-body/limits.ts` `stageBatchBytes(kind)` uses it. Pinned by `test/rust-engine-shell.test.ts`.+- `src/core/rust-engine/addon-loader.ts` — the Rust engine addon loader (ENGINES.md "The Rust engine shell"). `loadRustEngineAddon(overrides?)` returns `{ ok: true, addon }` or `{ ok: false, code, reason, message }` for the two refusals and rethrows anything else; `loadRustAddon` is the throwing form. Order: `GBRAIN_RUST_ENGINE_ADDON` (an absolute path to a `bun run rust:build` file; skips only the release checksum pin, `engine_abi` and target are still checked); then the addon at `<gbrain home>/engines/rust/<engine_build>/<target>.node` named by the cached `manifest-<version>.json` of the running version, loaded only when its SHA-256 equals the manifest's. It never reaches the network, takes no lock and writes nothing; a refusal leaves every file as it was. Only the Rust engine's open path may import the loader, lazily, so PGLite and Postgres brains never load the addon or create `<gbrain home>/engines/`; it loads with `process.dlopen` from a computed path (a literal `require` of a `.node` would be bundled into compiled executables). Reasons (`addon-errors.ts`, listed in `error-registry.ts`): `rust_engine_addon_missing` is `unsupported_target`, `not_installed` or `override_not_found`; `rust_engine_addon_mismatch` is `digest`, `engine_abi`, `engine_build`, `target` or `load_failed`; both are raised before the brain is touched. `addon-manifest.ts` parses the manifest and holds `RUST_ENGINE_ABI` and `RELEASE_ADDON_TARGETS` (`linux-x64-glibc`, `darwin-arm64`); `addon-target.ts` names this platform's target. The addon itself (`rust/crates/gbrain-napi/src/binding.rs`) refuses a typed array whose buffer the runtime (`napi_is_arraybuffer`) does not call a plain `ArrayBuffer`, so hiding `SharedArrayBuffer` or swapping a prototype changes nothing. Pinned by `test/rust-engine-addon-loader.test.ts` and `rust/smoke/smoke.test.ts`.diff --git a/docs/contracts/public-surface.json b/docs/contracts/public-surface.jsonindex c91d7fed61..98d703718f 100644--- a/docs/contracts/public-surface.json+++ b/docs/contracts/public-surface.json@@ -2573,6 +2573,7 @@"embedding_unconfigured": 1,"embedding_width_mismatch": 1,"enforced_member_refused": 3,+ "engine_capability_missing": 1,"engine_closed": 1,"engine_degraded": 1,"engine_embedding_mismatch": 1,@@ -2892,6 +2893,8 @@"revision_required": 1,"revision_unavailable": 1,"runtime_build_skew": 1,+ "rust_engine_addon_mismatch": 1,+ "rust_engine_addon_missing": 1,"schedule_install_failed": 1,"schedule_unsupported": 1,"schema_lock_blocked": 1,diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex 23bd2291a3..9d73e751ca 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -1752,6 +1752,18 @@ Reasons: `command_not_allowed`, `member_not_usable`, `target_not_readable`, `labMore: [docs/guides/enforced-member.md#refused](../../docs/guides/enforced-member.md#refused)+### engine_capability_missing++<a id="engine_capability_missing"></a>++| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |+|---|---|---|---|---|---|---|+| The brain's engine does not implement the capability this call needs (reason names it), so the call was refused before any work and nothing was written. | The Rust engine preview grows one capability at a time. A call that needs a capability it does not report is refused up front instead of running part of the way; detail names the member, the capability and whether anything was written (written=nothing unless the outcome is partial or unknown). | Run the call on a pglite or postgres brain, or wait for a gbrain release whose Rust engine reports the capability. | agent | `repeat the read that failed` | 1 | no |++Reasons: `raw_sql`, `persistence_journal`, `minion_queue`, `access_control`, `belief_ledger`, `single_owner`, `postgres_admin`, `schema`, `transactions`, `sources`, `config`, `pages`, `page_versions`, `page_body`, `tags`, `chunks`, `embeddings`, `keyword_search`, `vector_search`, `links`, `timeline`, `graph`, `facts`, `takes`, `files`, `code_edges`, `salience`, `health`, `raw_data`, `eval_capture`, `ingest_log`, `dream_verdicts`, `contradictions`, `ontology`.++More: [docs/ENGINES.md#the-rust-engine-shell](../../docs/ENGINES.md#the-rust-engine-shell)+### engine_closed<a id="engine_closed"></a>@@ -4800,6 +4812,26 @@ More: [docs/guides/windowed-reads.md#revision_changed](../../docs/guides/windoweMore: [docs/guides/troubleshooting.md#runtime-build-skew](../../docs/guides/troubleshooting.md#runtime-build-skew)+### rust_engine_addon_mismatch++<a id="rust_engine_addon_mismatch"></a>++| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |+|---|---|---|---|---|---|---|+| The Rust engine addon on this machine does not match what this gbrain release expects (checksum, engine_abi, engine_build or target), so it was not used and gbrain wrote nothing. | A different addon build could read or write the brain with a different on-disk format, so only the addon the running release names, with the checksum in its manifest, is loaded. A file that fails the check is left as it was. | Rebuild the addon with bun run rust:build and point GBRAIN_RUST_ENGINE_ADDON at the path it prints, or install the gbrain release that matches the addon, or switch engine in the gbrain config back to pglite or postgres. | user | `gbrain doctor --json` | 1 | no |++Reasons: `digest`, `engine_abi`, `engine_build`, `target`, `load_failed`.++### rust_engine_addon_missing++<a id="rust_engine_addon_missing"></a>++| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |+|---|---|---|---|---|---|---|+| The Rust engine is selected (engine: rust), but no addon for this gbrain release is installed on this machine, or no addon is published for this platform, so gbrain opened nothing and wrote nothing. | The Rust engine ships as a separate addon file kept in the gbrain home, checked against the checksum in this release's manifest before it loads. Without a checked addon the engine cannot open, and gbrain refuses before touching the brain. | Point GBRAIN_RUST_ENGINE_ADDON at an addon you built with bun run rust:build, or switch engine in the gbrain config back to pglite or postgres. | user | `gbrain doctor --json` | 1 | yes |++Reasons: `unsupported_target`, `not_installed`, `override_not_found`.+### schedule_install_failed<a id="schedule_install_failed"></a>diff --git a/llms-full.txt b/llms-full.txtindex 993752fb87..d27c5ed84b 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -6238,6 +6238,35 @@ The real backstop is `test/e2e/op-checkpoint-jsonb-parity.test.ts` +`test/e2e/jsonb-roundtrip.test.ts`, which round-trip writes through real Postgresand assert `jsonb_typeof` — the assertion PGLite cannot make.+## The Rust engine shell++The opt-in Rust engine (`docs/designs/RUST_ENGINE.md`) is under construction. PGLite and Postgres behave exactly+as before, and an install needs no Rust toolchain and no addon. `openRustEngine({ addon, databasePath })`+(`src/core/rust-engine.ts`) is the one seam: the addon loader calls it after it has loaded and verified the native+addon, and gets back the engine: every `BrainEngine` member, with `kind` `'rust'`. `BrainEngine.kind` admits `'rust'`+when the `rust` config value lands; no config value selects the Rust engine yet. Finding, checking and loading the+addon, and refusing a missing or mismatched one, belong to the loader (below), not the shell.++- **Capabilities.** The shell declares no capabilities. Each `BrainEngine` member it does not implement refuses+ `engine_capability_missing` with the capability as `reason` (`raw_sql`, `pages`, `search`, ...), the member in+ `detail`, and `written=nothing`, before any work. `src/core/rust-engine/members.ts` maps every member to its+ capability; the type fails when a new `BrainEngine` member is not classified.+- **SQL-only paths.** Code that only works through SQL (migrations, cycle locks, engine migration and graduation,+ embed backfill, page-body staging) takes the kind as `EngineKind`, narrows it with `sqlEngineKind` or+ `isRustEngineKind` (`src/core/sql-engine-kind.ts`), and refuses a Rust brain with `engine_capability_missing` reason `raw_sql` instead of treating it as Postgres.+- **The addon loader.** `loadRustEngineAddon()` (`src/core/rust-engine/addon-loader.ts`) returns the loaded addon,+ or the refusal `rust_engine_addon_missing` or `rust_engine_addon_mismatch` with its `reason` (`gbrain errors+ <code>`), before the brain is touched. It uses `GBRAIN_RUST_ENGINE_ADDON` (an absolute path to a build from `bun run+ rust:build`; it skips only the release checksum pin) first, then an addon cached at+ `<gbrain home>/engines/rust/<engine_build>/<target>.node` whose SHA-256 equals the cached manifest of this gbrain+ version. It never reaches the network and writes nothing: with no cached addon it refuses with reason+ `not_installed`, and a cached file that fails a check stays as it was. Fetching the release's addon into that cache+ arrives with the capability gate. Only the Rust engine's open path may import the loader, lazily, so a PGLite or+ Postgres brain never loads the addon or creates `<gbrain home>/engines/`.+- **Shared memory.** The addon refuses a typed array whose buffer the runtime (`napi_is_arraybuffer`) does not call a+ plain `ArrayBuffer`, so a `SharedArrayBuffer` view is refused with `InvalidArg` however JavaScript globals or+ prototypes have been changed (`rust/README.md`).+## Adding a new engine1. Create `src/core/<name>-engine.ts` implementing `BrainEngine`@@ -6251,7 +6280,9 @@ and assert `jsonb_typeof` — the assertion PGLite cannot make.engines do. Declare its capabilities honestly. The binding matrix(`test/helpers/executor-binding-matrix.ts`) and the engine-sql contracttests tell you whether the adapter binds, counts, fails and cancels like the- others. A non-SQL engine implements every method itself.+ others. A non-SQL engine implements typed methods instead of a `SqlExecutor`:+ it declares no `raw_sql` capability, and each member it cannot serve yet+ refuses `engine_capability_missing` (see "The Rust engine shell" above).4. Store engine type in `~/.gbrain/config.json`: `{ "engine": "myengine", ... }`5. Add tests. The test suite should be engine-agnostic where possible... same test cases, different engine constructor.6. Document in this file + add a design doc in `docs/`diff --git a/package.json b/package.jsonindex c78aa027dd..6b69441de4 100644--- a/package.json+++ b/package.json@@ -49,6 +49,7 @@"scripts": {"dev": "bun run src/cli.ts","build": "bun build --compile --no-compile-autoload-bunfig --define GBRAIN_BUILD_COMMIT=\\\"$(git rev-parse HEAD)\\\" --outfile bin/gbrain src/cli.ts src/core/skills/resolver/hook-worker.ts",+ "rust:build": "bun rust/scripts/build.ts","build:all": "bun build --compile --no-compile-autoload-bunfig --define GBRAIN_BUILD_COMMIT=\\\"$(git rev-parse HEAD)\\\" --target=bun-darwin-arm64 --outfile bin/gbrain-darwin-arm64 src/cli.ts src/core/skills/resolver/hook-worker.ts && bun build --compile --no-compile-autoload-bunfig --define GBRAIN_BUILD_COMMIT=\\\"$(git rev-parse HEAD)\\\" --target=bun-linux-x64 --outfile bin/gbrain-linux-x64 src/cli.ts src/core/skills/resolver/hook-worker.ts","build:admin": "cd admin && bun run build && cd .. && bun run scripts/build-admin-embedded.ts","build:admin-embedded": "bun run scripts/build-admin-embedded.ts",diff --git a/rust/.gitignore b/rust/.gitignorenew file mode 100644index 0000000000..039990ecfe--- /dev/null+++ b/rust/.gitignore@@ -0,0 +1,2 @@+# Cargo build output, including the addon copied to target/addon/ by rust/scripts/build.ts.+target/diff --git a/rust/Cargo.lock b/rust/Cargo.locknew file mode 100644index 0000000000..6e57bda6b3--- /dev/null+++ b/rust/Cargo.lock@@ -0,0 +1,365 @@+# This file is automatically @generated by Cargo.+# It is not intended for manual editing.+version = 4++[[package]]+name = "bitflags"+version = "2.13.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"++[[package]]+name = "block-buffer"+version = "0.10.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"+dependencies = [+ "generic-array",+]++[[package]]+name = "cfg-if"+version = "1.0.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"++[[package]]+name = "convert_case"+version = "0.12.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1af709f1f33454bf52eadfc8c78b3b9ef9cb26fb54d16dc9cd9a7299f899fd1b"+dependencies = [+ "unicode-segmentation",+]++[[package]]+name = "cpufeatures"+version = "0.2.17"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"+dependencies = [+ "libc",+]++[[package]]+name = "crypto-common"+version = "0.1.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"+dependencies = [+ "generic-array",+ "typenum",+]++[[package]]+name = "ctor"+version = "1.0.14"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ea691ed9f36489d087419b8b2ba3ef27d89621380b4178c73e2445a379e4e0f4"+dependencies = [+ "link-section",+]++[[package]]+name = "digest"+version = "0.10.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"+dependencies = [+ "block-buffer",+ "crypto-common",+]++[[package]]+name = "futures"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9a31d2a3fbaaeb2af2368bbdd904aa8e812d3c04a1ee10d3171f52d556e5d0a3"+dependencies = [+ "futures-channel",+ "futures-core",+ "futures-executor",+ "futures-io",+ "futures-sink",+ "futures-task",+ "futures-util",+]++[[package]]+name = "futures-channel"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"+dependencies = [+ "futures-core",+ "futures-sink",+]++[[package]]+name = "futures-core"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"++[[package]]+name = "futures-executor"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "031b47cf1a3c6cc8bc2fc76cd437f521619387907d469316e7c0bc278f1f5432"+dependencies = [+ "futures-core",+ "futures-task",+ "futures-util",+]++[[package]]+name = "futures-io"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"++[[package]]+name = "futures-macro"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9fb9654ba8355388abeb8dcb4fc62f511300867002afc858860463bdd9fe0c44"+dependencies = [+ "proc-macro2",+ "quote",+ "syn",+]++[[package]]+name = "futures-sink"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"++[[package]]+name = "futures-task"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"++[[package]]+name = "futures-util"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"+dependencies = [+ "futures-channel",+ "futures-core",+ "futures-io",+ "futures-macro",+ "futures-sink",+ "futures-task",+ "memchr",+ "pin-project-lite",+ "slab",+]++[[package]]+name = "gbrain-napi"+version = "0.0.0"+dependencies = [+ "napi",+ "napi-build",+ "napi-derive",+ "sha2",+]++[[package]]+name = "generic-array"+version = "0.14.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"+dependencies = [+ "typenum",+ "version_check",+]++[[package]]+name = "libc"+version = "0.2.191"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"++[[package]]+name = "libloading"+version = "0.9.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a1832accd5a4ca2795ace4d05d15c4039be15b62d3b950eff99746a990e3cc10"+dependencies = [+ "cfg-if",+ "windows-link",+]++[[package]]+name = "link-section"+version = "0.19.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4d9aae57673c1a235149777a74d152f3210ebd3e3b13346d2cdb6809e566bd3c"++[[package]]+name = "memchr"+version = "2.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"++[[package]]+name = "napi"+version = "3.16.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "567c62b9c2d0fae123713f766686ad66a2c75b45ba3ee01ed8b06a7e99bc435b"+dependencies = [+ "bitflags",+ "ctor",+ "futures",+ "libc",+ "napi-build",+ "napi-sys",+ "nohash-hasher",+ "rustc-hash",+]++[[package]]+name = "napi-build"+version = "2.6.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b899b545d3aa6dca985939059f258c5488d34e4ecf39c274e20009748f4b846d"++[[package]]+name = "napi-derive"+version = "3.7.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "94c8098ed9d61a1bbd019519c637817531b0e24023ef4b5678f2f0cbe24bed9c"+dependencies = [+ "convert_case",+ "ctor",+ "napi-derive-backend",+ "proc-macro2",+ "quote",+ "syn",+]++[[package]]+name = "napi-derive-backend"+version = "7.0.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "314cd6ca42bd978fd8bae84b4137e1322bbf3e83552fca8dbd7d18034188ff3a"+dependencies = [+ "convert_case",+ "proc-macro2",+ "quote",+ "semver",+ "syn",+]++[[package]]+name = "napi-sys"+version = "3.4.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d153beb7d5c973f4b9395be8a83054a28968b61188f1dd1a2cc2321af22daea2"+dependencies = [+ "libloading",+]++[[package]]+name = "nohash-hasher"+version = "0.2.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2bf50223579dc7cdcfb3bfcacf7069ff68243f8c363f62ffa99cf000a6b9c451"++[[package]]+name = "pin-project-lite"+version = "0.2.17"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"++[[package]]+name = "proc-macro2"+version = "1.0.107"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"+dependencies = [+ "unicode-ident",+]++[[package]]+name = "quote"+version = "1.0.47"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"+dependencies = [+ "proc-macro2",+]++[[package]]+name = "rustc-hash"+version = "2.1.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"++[[package]]+name = "semver"+version = "1.0.28"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8a7852d02fc848982e0c167ef163aaff9cd91dc640ba85e263cb1ce46fae51cd"++[[package]]+name = "sha2"+version = "0.10.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"+dependencies = [+ "cfg-if",+ "cpufeatures",+ "digest",+]++[[package]]+name = "slab"+version = "0.4.12"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"++[[package]]+name = "syn"+version = "3.0.10"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79"+dependencies = [+ "proc-macro2",+ "quote",+ "unicode-ident",+]++[[package]]+name = "typenum"+version = "1.20.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"++[[package]]+name = "unicode-ident"+version = "1.0.27"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"++[[package]]+name = "unicode-segmentation"+version = "1.13.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c6f5d3c3b1bf09027a88a6bc961fc00497d651009560b5463668dc81b0fa87a8"++[[package]]+name = "version_check"+version = "0.9.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"++[[package]]+name = "windows-link"+version = "0.2.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"diff --git a/rust/Cargo.toml b/rust/Cargo.tomlnew file mode 100644index 0000000000..6dbf1cf2ae--- /dev/null+++ b/rust/Cargo.toml@@ -0,0 +1,17 @@+[workspace]+resolver = "3"+members = ["crates/*"]+# rust/bench is a separate standalone workspace (its own Cargo.lock); it is not part of the addon build.+exclude = ["bench"]++[workspace.package]+edition = "2024"+license = "MIT"+publish = false+rust-version = "1.100"++[profile.release]+# The binding turns a Rust panic into a JavaScript error with catch_unwind, which needs unwinding.+panic = "unwind"+lto = "thin"+codegen-units = 16diff --git a/rust/README.md b/rust/README.mdnew file mode 100644index 0000000000..a83dc8eeee--- /dev/null+++ b/rust/README.md@@ -0,0 +1,136 @@+# Rust engine (experimental)++This folder holds an optional Rust engine for gbrain. Nothing in gbrain uses it yet. Today it is a+small Node-API addon that proves the pieces a Rust engine needs: that Bun can load it, call it,+cancel its work, survive its panics and shut it down cleanly. You do not need Rust to build, test+or run gbrain.++## What you need++[rustup](https://rustup.rs). That is all. It reads `rust/rust-toolchain.toml` and installs the+pinned Rust version (with `clippy` and `rustfmt`) the first time you build.++```sh+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh+```++## Build the addon++From the repo root:++```sh+bun run rust:build+```++It prints the path of the built file and the line to export:++```+Built /path/to/gbrain/rust/target/addon/gbrain_engine.linux-x64-glibc.node+Point gbrain at it with:++ export GBRAIN_RUST_ENGINE_ADDON=/path/to/gbrain/rust/target/addon/gbrain_engine.linux-x64-glibc.node+```++Run that `export` line in your shell. If cargo is missing the command stops with install+instructions and writes nothing. The build always goes to `rust/target/`: the command passes+`--target-dir`, so `CARGO_TARGET_DIR` and a `build.target-dir` setting are ignored and it never+packages an older library from another build directory.++## Check it works under Bun++```sh+bun rust/smoke/run.ts+```++It runs each check and prints `ok` or `FAIL`, then exits 0 only if all passed. It covers:++- the metadata the addon reports (target, ABI, build hash, catalog version);+- a JavaScript timer still firing while a native task runs;+- typed arrays: sum, scale into a new array, scale in place, offset views, empty arrays, async+ calls copying their input before they return, and a view of a `SharedArrayBuffer` being refused;+- a panic, sync or async, becoming a normal `Error` with `code: 'internal_error'` while the next+ call still works;+- a cancelled task rejecting with `code: 'cancelled'` and `completedSteps`;+- shutdown cancelling queued tasks, waiting a bounded time for running ones, then rejecting later+ calls with `code: 'engine_shutdown'`, from the moment `shutdown()` returns;+- a pool's worker count staying between 1 and 256, and a pool collected without `shutdown()`+ stopping its workers;+- the bounded callback queue answering `queue_full` and `closing` and losing nothing it accepted;+- a child process calling `process.exit(0)` while native work runs (must exit 0 at once);+- a `bun build --compile` executable loading the addon and passing the same core checks.++It is a plain script, not a `bun test` file, because the repo's test preloads can strip+`GBRAIN_*` variables.++The same checks run in CI on Linux x64 and macOS arm64 (`.github/workflows/rust-engine.yml`).++## Everyday commands++Run these in `rust/`:++```sh+cargo fmt --check+cargo clippy --all-targets -- -D warnings+cargo test+cargo deny check # licenses, sources, advisories; needs `cargo install cargo-deny --locked`+```++## Build times++Measured on an 8-core, 30 GB Linux x64 machine with the crates already downloaded (a cold first+build also downloads them, which depends on your network):++| What | Time |+| --- | --- |+| First release build from an empty `target/` (`bun run rust:build`) | 8.7 s (20 s of CPU) |+| First `cargo test` from an empty `target/` | 7.3 s |+| First `cargo clippy --all-targets` from an empty `target/` | 3.6 s |+| Edit one source file, then `bun run rust:build` | 0.7 s |+| Edit one source file, then `cargo test` | 0.4 s |++The first rustup install of the pinned toolchain is extra and was not timed. `rust/target/` is+ignored by git.++## What `engineBuild` is++The addon reports `engineBuild`, a SHA-256 of the Rust sources it was built from, so a loader can+tell two builds apart. It hashes, in sorted path order, each file under `rust/` as+`path NUL length NUL bytes`. It leaves out `target/`, `bench/`, `smoke/`, `scripts/`, `deny.toml`,+`.gitignore` and every `*.md`, so changing the README or a smoke test does not change the build.+The rule lives in `crates/gbrain-napi/build.rs`.++## Error codes++Errors from the addon are real `Error` objects with a `code`:++| Code | When |+| --- | --- |+| `cancelled` | A queued or running task was cancelled. Carries `completedSteps` and `started`. |+| `internal_error` | Rust code panicked. Carries a `diagnosticId`; the panic text is not sent to the caller. |+| `engine_shutdown` | A call arrived after shutdown began. |++A typed-array argument of the wrong type, or a view of a `SharedArrayBuffer`, throws the+standard Node-API `InvalidArg` error before any Rust code reads it. The addon decides by asking+the runtime (`napi_is_arraybuffer` on the view's buffer): anything the runtime does not call a+plain `ArrayBuffer`, or cannot answer for, is refused, so hiding `SharedArrayBuffer` or swapping a+prototype in JavaScript changes nothing. Rust reads and writes the accepted arrays through relaxed+atomic cells and never builds a slice over them, which is only sound for memory no other thread+can reach.++## Good to know++- A pending native task keeps a process alive. If a script ends without `process.exit()` while a+ pool still has work, it exits only after that work finishes (the smoke test measures this and+ prints the result). Call `pool.shutdown(waitMs)` or `process.exit()` to leave early.+- `new Pool(workers)` starts 1 to 256 threads. If the system refuses a thread, it throws+ `internal_error` and stops the threads it started.+- The callback queue (`Sink`) holds 4 values. That size is fixed at compile time by napi-rs.+- `rust/bench/` is a separate workspace and is not part of this one.+- gbrain's addon loader (`src/core/rust-engine/addon-loader.ts`) uses `GBRAIN_RUST_ENGINE_ADDON`+ first, then an addon cached under `<gbrain home>/engines/rust/` whose SHA-256 matches this+ release's cached manifest. It does not download anything: with no cached addon it refuses with+ `rust_engine_addon_missing`, reason `not_installed`. Nothing starts the loader yet (ENGINES.md,+ "The Rust engine shell").+- To go back to the normal gbrain path, `unset GBRAIN_RUST_ENGINE_ADDON`.+- `GBRAIN_TEST_BACKEND=rust bun test <file>` arrives with the Rust test arm in a later change. It+ does not exist yet.diff --git a/rust/crates/gbrain-napi/Cargo.toml b/rust/crates/gbrain-napi/Cargo.tomlnew file mode 100644index 0000000000..e11e398801--- /dev/null+++ b/rust/crates/gbrain-napi/Cargo.toml@@ -0,0 +1,19 @@+[package]+name = "gbrain-napi"+version = "0.0.0"+edition.workspace = true+license.workspace = true+publish.workspace = true+rust-version.workspace = true+description = "Node-API binding for the gbrain Rust engine; the only crate that knows JavaScript."++[lib]+crate-type = ["cdylib", "rlib"]++[dependencies]+napi = { version = "3", features = ["napi8"] }+napi-derive = "3"++[build-dependencies]+napi-build = "2"+sha2 = "0.10"diff --git a/rust/crates/gbrain-napi/build.rs b/rust/crates/gbrain-napi/build.rsnew file mode 100644index 0000000000..649248ce0c--- /dev/null+++ b/rust/crates/gbrain-napi/build.rs@@ -0,0 +1,87 @@+//! Build script for the addon.+//!+//! 1. `napi_build::setup()` adds the linker flags Node-API addons need (on macOS, undefined+//! `napi_*` symbols are resolved when the addon is loaded).+//! 2. It computes `GBRAIN_ENGINE_BUILD`, the digest the addon reports as `engineBuild`.+//!+//! How `engineBuild` is computed: SHA-256 over every file under `rust/` that can change the+//! compiled addon, taken in sorted relative-path order, each as `path NUL length NUL bytes`.+//! Left out: `target/` (build output), `bench/` (a separate workspace that never goes into the+//! addon), `smoke/` and `scripts/` (test and build tooling), `deny.toml`, `.gitignore`, and+//! Markdown files. Two checkouts with the same Rust sources, `Cargo.lock` and+//! `rust-toolchain.toml` therefore report the same value, whatever machine builds them.++use std::fs;+use std::io;+use std::path::{Path, PathBuf};++use sha2::{Digest, Sha256};++const SKIP_DIRS: &[&str] = &["target", "bench", "smoke", "scripts", ".git"];+const SKIP_FILES: &[&str] = &["deny.toml", ".gitignore"];++fn collect(dir: &Path, root: &Path, out: &mut Vec<PathBuf>) -> io::Result<()> {+ let mut entries: Vec<_> = fs::read_dir(dir)?.collect::<Result<_, _>>()?;+ entries.sort_by_key(|entry| entry.file_name());+ for entry in entries {+ let path = entry.path();+ let name = entry.file_name().to_string_lossy().into_owned();+ if entry.file_type()?.is_dir() {+ if dir == root && SKIP_DIRS.contains(&name.as_str()) {+ continue;+ }+ collect(&path, root, out)?;+ } else if !SKIP_FILES.contains(&name.as_str()) && !name.ends_with(".md") {+ out.push(path);+ }+ }+ Ok(())+}++fn engine_build(root: &Path) -> io::Result<String> {+ let mut files = Vec::new();+ collect(root, root, &mut files)?;+ let mut relative: Vec<String> = files+ .iter()+ .map(|file| {+ file.strip_prefix(root)+ .unwrap_or(file)+ .to_string_lossy()+ .replace('\\', "/")+ })+ .collect();+ relative.sort();+ let mut hasher = Sha256::new();+ for name in &relative {+ let bytes = fs::read(root.join(name))?;+ hasher.update(name.as_bytes());+ hasher.update([0]);+ hasher.update(bytes.len().to_string().as_bytes());+ hasher.update([0]);+ hasher.update(&bytes);+ }+ Ok(hasher+ .finalize()+ .iter()+ .map(|byte| format!("{byte:02x}"))+ .collect())+}++fn main() {+ napi_build::setup();+ let manifest_dir =+ PathBuf::from(std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR"));+ // rust/crates/gbrain-napi -> rust/+ let root = manifest_dir+ .parent()+ .and_then(Path::parent)+ .expect("the crate lives in rust/crates/gbrain-napi");+ let digest = engine_build(root).expect("hash the rust/ tree");+ println!("cargo:rustc-env=GBRAIN_ENGINE_BUILD={digest}");+ println!("cargo:rerun-if-changed=build.rs");+ println!("cargo:rerun-if-changed=src");+ println!("cargo:rerun-if-changed=../../Cargo.toml");+ println!("cargo:rerun-if-changed=../../Cargo.lock");+ println!("cargo:rerun-if-changed=../../rust-toolchain.toml");+ println!("cargo:rerun-if-changed=../../crates");+}diff --git a/rust/crates/gbrain-napi/src/binding.rs b/rust/crates/gbrain-napi/src/binding.rsnew file mode 100644index 0000000000..84a6864e70--- /dev/null+++ b/rust/crates/gbrain-napi/src/binding.rs@@ -0,0 +1,637 @@+//! JavaScript-facing exports. Everything here is a thin shell around `error` and `pool`.+//!+//! Rules every export follows:+//! - the body runs inside `guard`, so a panic is a JavaScript `Error` with code `internal_error`+//! and the process keeps running;+//! - async work runs on the Rust worker pool and settles a promise, so the Bun event loop is+//! never blocked;+//! - errors are real `Error` objects with a stable `code` (and, for `cancelled`, the number of+//! `completedSteps`), never a bare message.++use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};+use std::sync::{Arc, Mutex};+use std::time::Duration;++use napi::bindgen_prelude::{+ Float32Array, FromNapiValue, Function, Object, ToNapiValue, TypeName, ValidateNapiValue,+};+use napi::threadsafe_function::ThreadsafeFunctionCallMode;+use napi::{Env, JsDeferred, JsValue, Status, ValueType, sys};+use napi_derive::napi;++use crate::error::{Detail, TaskError, guard};+use crate::pool::{self, CancelToken as Token, Task};++type TaskResult<T> = std::result::Result<T, TaskError>;++/// Build the JavaScript `Error` for a typed error: `message`, a stable `code`, and its details.+fn js_error(env: &Env, error: TaskError) -> napi::Error {+ let build = || -> napi::Result<napi::Error> {+ let mut object = env.create_error(napi::Error::new(+ Status::GenericFailure,+ error.message.clone(),+ ))?;+ object.set("code", error.code)?;+ for (key, detail) in &error.details {+ match detail {+ Detail::Count(n) => object.set(*key, *n)?,+ Detail::Flag(flag) => object.set(*key, *flag)?,+ Detail::Text(text) => object.set(*key, text.as_str())?,+ }+ }+ Ok(napi::Error::from(object.to_unknown()))+ };+ build().unwrap_or_else(|_| {+ napi::Error::new(+ Status::GenericFailure,+ format!("{}: {}", error.code, error.message),+ )+ })+}++/// Run a synchronous export: panic to `internal_error`, typed error to a thrown `Error`.+fn sync_call<T>(env: &Env, work: impl FnOnce() -> TaskResult<T>) -> napi::Result<T> {+ guard(work).map_err(|error| js_error(env, error))+}++#[napi(module_exports)]+pub fn module_exports(mut exports: Object, env: Env) -> napi::Result<()> {+ // Plain data properties, so the loader reads them without calling anything.+ exports.set("target", crate::target())?;+ exports.set("engineAbi", crate::ENGINE_ABI)?;+ exports.set("engineBuild", crate::ENGINE_BUILD)?;+ exports.set("catalogVersion", crate::CATALOG_VERSION)?;+ exports.set("formatVersions", env.create_array(0)?)?;+ exports.set("sinkMaxQueueSize", SINK_QUEUE_SIZE as u32)?;+ Ok(())+}++// ---------------------------------------------------------------------------------------------+// Typed arrays+// ---------------------------------------------------------------------------------------------++/// Adds in `f64`, starting from +0.0. (`Iterator::sum` on floats starts from -0.0, which would+/// turn an empty array into `-0` in JavaScript.)+fn sum_as_f64(values: impl IntoIterator<Item = f32>) -> f64 {+ values+ .into_iter()+ .fold(0.0, |total, v| total + f64::from(v))+}++/// A `Float32Array` argument. A view of a `SharedArrayBuffer` is refused with the same+/// `InvalidArg` error as an argument of the wrong type, because another Worker could write it+/// during the call.+///+/// That refusal is the safety argument. It asks the runtime (`napi_is_arraybuffer` on the view's+/// buffer), which reads the engine's own record of the buffer, so no JavaScript state (a replaced+/// global constructor, a swapped prototype) can change the answer, and an unclear answer is+/// treated as shared. Rust never makes a `&[f32]` or `&mut [f32]` over the caller's memory: every+/// read and write goes through `AtomicU32` cells with relaxed ordering (see [`PlainF32::cells`]),+/// which compile to plain loads and stores. Atomics do not make shared memory safe (another Worker+/// may write it with accesses of a different size), which is why shared memory is refused.+pub struct PlainF32 {+ /// Keeps the JavaScript array alive for the call.+ _array: Float32Array,+ /// First element (the view's byte offset already applied) and element count, as Node-API+ /// reported them. Null or zero for an empty array.+ data: *mut f32,+ length: usize,+}++impl PlainF32 {+ /// The caller's elements as atomic cells.+ fn cells(&self) -> &[AtomicU32] {+ if self.data.is_null() || self.length == 0 {+ return &[];+ }+ // SAFETY: `data` points at `length` elements of 4 bytes that stay allocated while+ // `_array` is held (this struct only lives for one call on the JavaScript thread).+ // `AtomicU32` has the size and alignment of `u32`, and the pointer is 4-aligned (checked+ // in `from_napi_value`). The buffer is a plain ArrayBuffer (`backed_by_shared_memory`),+ // so only this thread, blocked in the call, can reach it.+ unsafe { std::slice::from_raw_parts(self.data.cast::<AtomicU32>(), self.length) }+ }++ /// Reads every element.+ fn values(&self) -> impl Iterator<Item = f32> + '_ {+ self.cells()+ .iter()+ .map(|cell| f32::from_bits(cell.load(Ordering::Relaxed)))+ }++ /// A Rust-owned copy, for work that outlives the call.+ fn to_vec(&self) -> Vec<f32> {+ self.values().collect()+ }+}++impl TypeName for PlainF32 {+ fn type_name() -> &'static str {+ "Float32Array"+ }++ fn value_type() -> ValueType {+ ValueType::Object+ }+}++impl ValidateNapiValue for PlainF32 {}++impl FromNapiValue for PlainF32 {+ unsafe fn from_napi_value(env: sys::napi_env, value: sys::napi_value) -> napi::Result<Self> {+ // SAFETY: `env` and `value` come straight from Node-API for this call.+ if unsafe { backed_by_shared_memory(env, value) } {+ return Err(napi::Error::new(+ Status::InvalidArg,+ "a Float32Array over a SharedArrayBuffer is not accepted; copy it into a plain Float32Array first",+ ));+ }+ // SAFETY: as above.+ let array = unsafe { Float32Array::from_napi_value(env, value) }?;+ let mut kind = 0;+ let mut length = 0;+ let mut data = std::ptr::null_mut();+ let mut buffer = std::ptr::null_mut();+ let mut offset = 0;+ // SAFETY: every out pointer is a valid local; `value` is a Float32Array (checked above).+ let status = unsafe {+ sys::napi_get_typedarray_info(+ env,+ value,+ &mut kind,+ &mut length,+ &mut data,+ &mut buffer,+ &mut offset,+ )+ };+ let data = data.cast::<f32>();+ if status != sys::Status::napi_ok || (!data.is_null() && !data.is_aligned()) {+ return Err(napi::Error::new(+ Status::InvalidArg,+ "the Float32Array's memory could not be read safely",+ ));+ }+ Ok(Self {+ _array: array,+ data,+ length,+ })+ }+}++/// True when `value` is a typed array over memory that may be shared, or when that cannot be+/// told. Only the runtime's `napi_is_arraybuffer` answer counts: a buffer it does not call a plain+/// ArrayBuffer is treated as shared. A value that is not a typed array returns false, so the+/// `Float32Array` conversion reports its own wrong-type error.+///+/// # Safety+/// `env` and `value` must be live handles of the current Node-API call.+unsafe fn backed_by_shared_memory(env: sys::napi_env, value: sys::napi_value) -> bool {+ let ok = sys::Status::napi_ok;+ let mut kind = 0;+ let mut length = 0;+ let mut data = std::ptr::null_mut();+ let mut buffer = std::ptr::null_mut();+ let mut offset = 0;+ // SAFETY: every out pointer is a valid local.+ let status = unsafe {+ sys::napi_get_typedarray_info(+ env,+ value,+ &mut kind,+ &mut length,+ &mut data,+ &mut buffer,+ &mut offset,+ )+ };+ if status != ok {+ return false;+ }+ if buffer.is_null() {+ return true;+ }+ let mut plain = false;+ // SAFETY: `buffer` is the live handle the call above returned.+ let status = unsafe { sys::napi_is_arraybuffer(env, buffer, &mut plain) };+ status != ok || !plain+}++/// Sum of a `Float32Array`, added in `f64`. Reads the JavaScript memory in place for the length+/// of the call (a view with a byte offset is honoured); nothing is copied and nothing is kept.+#[napi]+pub fn sum_f32(env: &Env, values: PlainF32) -> napi::Result<f64> {+ sync_call(env, || Ok(sum_as_f64(values.values())))+}++/// A new `Float32Array` with every value multiplied by `factor`. The input is left alone and the+/// result is a separate array.+#[napi]+pub fn scale_f32(env: &Env, values: PlainF32, factor: f64) -> napi::Result<Float32Array> {+ sync_call(env, || {+ let scaled: Vec<f32> = values+ .values()+ .map(|v| (f64::from(v) * factor) as f32)+ .collect();+ Ok(Float32Array::new(scaled))+ })+}++/// Multiplies every value of the caller's array by `factor`, writing into the same memory.+/// Synchronous only: the JavaScript thread is blocked for the whole call, so nothing else can+/// touch the array while it is written.+#[napi]+pub fn scale_in_place_f32(env: &Env, values: PlainF32, factor: f64) -> napi::Result<u32> {+ sync_call(env, || {+ let cells = values.cells();+ for cell in cells {+ let v = f32::from_bits(cell.load(Ordering::Relaxed));+ cell.store(+ ((f64::from(v) * factor) as f32).to_bits(),+ Ordering::Relaxed,+ );+ }+ Ok(cells.len() as u32)+ })+}++// ---------------------------------------------------------------------------------------------+// Panics+// ---------------------------------------------------------------------------------------------++/// Panics on purpose, to prove a synchronous panic becomes a JavaScript error.+#[napi]+pub fn probe_panic_sync(env: &Env) -> napi::Result<()> {+ sync_call(env, || -> TaskResult<()> {+ panic!("probe_panic_sync panicked on purpose")+ })+}++// ---------------------------------------------------------------------------------------------+// Cancellation token+// ---------------------------------------------------------------------------------------------++/// What a JavaScript `AbortSignal` is mapped to: `signal.addEventListener('abort', () => token.cancel())`.+#[napi]+pub struct CancelToken {+ flag: Token,+}++#[napi]+impl CancelToken {+ #[napi(constructor)]+ pub fn new() -> Self {+ Self { flag: Token::new() }+ }++ #[napi]+ pub fn cancel(&self) {+ self.flag.cancel();+ }++ #[napi(getter)]+ pub fn cancelled(&self) -> bool {+ self.flag.is_cancelled()+ }+}++// ---------------------------------------------------------------------------------------------+// The worker pool+// ---------------------------------------------------------------------------------------------++type Resolver<T> = Box<dyn FnOnce(Env) -> napi::Result<T> + Send>;+type Work<T> = Box<dyn FnOnce() -> TaskResult<T> + Send>;++/// A pool task that settles a JavaScript promise: resolved with the work's value, or rejected+/// with a typed `Error`.+struct PromiseTask<T: ToNapiValue + Send + 'static> {+ deferred: JsDeferred<T, Resolver<T>>,+ work: Work<T>,+}++impl<T: ToNapiValue + Send + 'static> Task for PromiseTask<T> {+ fn run(self: Box<Self>) {+ let PromiseTask { deferred, work } = *self;+ let outcome = guard(work);+ settle(deferred, outcome);+ }++ fn cancel(self: Box<Self>, error: TaskError) {+ settle(self.deferred, Err(error));+ }+}++fn settle<T: ToNapiValue + Send + 'static>(+ deferred: JsDeferred<T, Resolver<T>>,+ outcome: TaskResult<T>,+) {+ // The error object is built on the JavaScript thread, where Node-API may be called.+ deferred.resolve(Box::new(move |env| {+ outcome.map_err(|error| js_error(&env, error))+ }));+}++/// Start `work` on the pool and return its promise. A pool that no longer takes work returns a+/// promise already rejected with `engine_shutdown`.+fn spawn<'env, T: ToNapiValue + Send + 'static>(+ env: &'env Env,+ pool: &pool::Pool,+ work: impl FnOnce() -> TaskResult<T> + Send + 'static,+) -> napi::Result<Object<'env>> {+ let (deferred, promise) = env.create_deferred::<T, Resolver<T>>()?;+ let task = Box::new(PromiseTask {+ deferred,+ work: Box::new(work) as Work<T>,+ });+ if let Err(refused) = pool.submit(task) {+ refused.cancel(TaskError::shutdown());+ }+ Ok(promise)+}++/// Worker threads still running across every pool in this process. A pool that is shut down,+/// or whose object was collected, stops counting once its threads exit.+#[napi]+pub fn live_workers() -> u32 {+ pool::live_workers()+}++/// What `shutdown` reports.+#[napi(object)]+pub struct ShutdownReport {+ /// Tasks that were queued and never started; each was rejected with `cancelled`.+ pub cancelled_queued: u32,+ /// Tasks that were running when shutdown began and finished inside the wait.+ pub finished_running: u32,+ /// Tasks still running when the wait ended; they finish on their own later.+ pub abandoned_running: u32,+}++/// A pool of Rust worker threads. Its calls return promises; the JavaScript thread only queues+/// work and settles results.+#[napi]+pub struct Pool {+ pool: pool::Pool,+}++#[napi]+impl Pool {+ /// Starts `workers` threads: at least 1, at most 256. If a thread cannot start, throws+ /// `internal_error` and stops the threads that did start.+ #[napi(constructor)]+ pub fn new(env: &Env, workers: u32) -> napi::Result<Self> {+ sync_call(env, || pool::Pool::new(workers as usize)).map(|pool| Self { pool })+ }++ /// Worker threads still running their loop.+ #[napi(getter)]+ pub fn workers(&self) -> u32 {+ self.pool.workers()+ }++ /// `running`, `shutting_down` or `closed`.+ #[napi(getter)]+ pub fn state(&self) -> String {+ self.pool.phase().as_str().to_owned()+ }++ #[napi(getter)]+ pub fn queued(&self) -> u32 {+ self.pool.queued()+ }++ #[napi(getter)]+ pub fn running(&self) -> u32 {+ self.pool.running()+ }++ /// Holds a worker for `ms` milliseconds, then resolves with `ms`. The event loop stays free.+ #[napi]+ pub fn block_for<'env>(&self, env: &'env Env, ms: u32) -> napi::Result<Object<'env>> {+ spawn(env, &self.pool, move || {+ std::thread::sleep(Duration::from_millis(u64::from(ms)));+ Ok(ms)+ })+ }++ /// `steps` steps of `step_ms` each. Resolves with the steps done. If `cancel` is cancelled+ /// after the task started, rejects with `cancelled` and `completedSteps`.+ #[napi]+ pub fn run_steps<'env>(+ &self,+ env: &'env Env,+ steps: u32,+ step_ms: u32,+ cancel: Option<&CancelToken>,+ ) -> napi::Result<Object<'env>> {+ let cancel = cancel.map(|t| t.flag.clone());+ spawn(env, &self.pool, move || {+ pool::run_steps(+ steps,+ Duration::from_millis(u64::from(step_ms)),+ cancel.as_ref(),+ )+ })+ }++ /// Async sum. The values are copied before the call returns, because the JavaScript array+ /// may change or be freed while a worker runs.+ #[napi]+ pub fn sum_f32<'env>(&self, env: &'env Env, values: PlainF32) -> napi::Result<Object<'env>> {+ let copy: Vec<f32> = values.to_vec();+ spawn(env, &self.pool, move || Ok(sum_as_f64(copy)))+ }++ /// Async scale. The result is a new `Float32Array` made on the JavaScript thread.+ #[napi]+ pub fn scale_f32<'env>(+ &self,+ env: &'env Env,+ values: PlainF32,+ factor: f64,+ ) -> napi::Result<Object<'env>> {+ let copy: Vec<f32> = values.to_vec();+ spawn(env, &self.pool, move || {+ Ok(Float32Array::new(+ copy.iter()+ .map(|v| (f64::from(*v) * factor) as f32)+ .collect(),+ ))+ })+ }++ /// Panics on a worker, to prove an async panic becomes a rejected promise and the pool lives on.+ #[napi]+ pub fn probe_panic<'env>(&self, env: &'env Env) -> napi::Result<Object<'env>> {+ spawn(env, &self.pool, || -> TaskResult<u32> {+ panic!("probe_panic panicked on purpose")+ })+ }++ /// Stop admission, cancel queued tasks, wait up to `wait_ms` for running ones, then close.+ /// Admission closes before this returns: any call made after it, even while the returned+ /// promise is pending, rejects with `engine_shutdown`.+ #[napi]+ pub fn shutdown<'env>(&self, env: &'env Env, wait_ms: u32) -> napi::Result<Object<'env>> {+ let (deferred, promise) =+ env.create_deferred::<ShutdownReport, Resolver<ShutdownReport>>()?;+ let draining = self.pool.begin_shutdown();+ let wait = Duration::from_millis(u64::from(wait_ms));+ // The thread takes the work out of this slot. If the thread cannot start, the slot still+ // holds it here, so no queued task or promise is left unsettled.+ let slot = Arc::new(Mutex::new(Some((draining, deferred))));+ let thread_slot = Arc::clone(&slot);+ // The wait blocks, so it runs on its own thread, not the JavaScript thread or a worker.+ let spawned = std::thread::Builder::new()+ .name("gbrain-shutdown".into())+ .spawn(move || {+ if let Some((draining, deferred)) = take(&thread_slot) {+ settle_shutdown(deferred, draining.finish(wait));+ }+ });+ if spawned.is_err()+ && let Some((draining, deferred)) = take(&slot)+ {+ draining.finish(Duration::ZERO);+ let error = TaskError::internal();+ deferred.resolve(Box::new(move |env| Err(js_error(&env, error))));+ }+ Ok(promise)+ }+}++/// A pool whose JavaScript object is collected without `shutdown` closes at once, so its idle+/// workers exit instead of waiting forever. Queued tasks are cancelled; running ones finish.+impl Drop for Pool {+ fn drop(&mut self) {+ self.pool.close_now();+ }+}++type PendingShutdown = (+ pool::Draining,+ JsDeferred<ShutdownReport, Resolver<ShutdownReport>>,+);++fn take(slot: &Mutex<Option<PendingShutdown>>) -> Option<PendingShutdown> {+ slot.lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner())+ .take()+}++fn settle_shutdown(+ deferred: JsDeferred<ShutdownReport, Resolver<ShutdownReport>>,+ report: pool::ShutdownReport,+) {+ deferred.resolve(Box::new(move |_| {+ Ok(ShutdownReport {+ cancelled_queued: report.cancelled_queued,+ finished_running: report.finished_running,+ abandoned_running: report.abandoned_running,+ })+ }));+}++// ---------------------------------------------------------------------------------------------+// Threadsafe-function queue+// ---------------------------------------------------------------------------------------------++/// The bounded queue size of a [`Sink`]. A const generic in napi-rs, so one fixed value.+const SINK_QUEUE_SIZE: usize = 4;++type SinkFunction = napi::threadsafe_function::ThreadsafeFunction<+ u32,+ (),+ u32,+ Status,+ false,+ true,+ SINK_QUEUE_SIZE,+>;++/// A JavaScript callback fed through a bounded threadsafe-function queue. `emit` never blocks and+/// says what the queue did with the value: `ok`, `queue_full` or `closing`.+///+/// `queue_full` comes from the runtime (Bun) itself. `closing` is reported by this crate from its+/// own closed flag after `close()`; the underlying function is released when the Sink is dropped.+#[napi]+pub struct Sink {+ function: Arc<SinkFunction>,+ closed: Arc<AtomicBool>,+}++fn status_name(status: Status) -> &'static str {+ match status {+ Status::Ok => "ok",+ Status::QueueFull => "queue_full",+ Status::Closing => "closing",+ _ => "error",+ }+}++#[napi]+impl Sink {+ #[napi(constructor)]+ pub fn new(callback: Function<'_, u32, ()>) -> napi::Result<Self> {+ let function = callback+ .build_threadsafe_function::<u32>()+ .callee_handled::<false>()+ .weak::<true>()+ .max_queue_size::<SINK_QUEUE_SIZE>()+ .build()?;+ Ok(Self {+ function: Arc::new(function),+ closed: Arc::new(AtomicBool::new(false)),+ })+ }++ /// Queue `value` for the callback without blocking.+ #[napi]+ pub fn emit(&self, value: u32) -> String {+ let status = guard(|| {+ Ok(if self.closed.load(Ordering::SeqCst) {+ Status::Closing+ } else {+ self.function+ .call(value, ThreadsafeFunctionCallMode::NonBlocking)+ })+ });+ status.map_or("error", status_name).to_owned()+ }++ /// Emit `count` values from a Rust thread instead of the JavaScript thread; resolves with+ /// the status of each.+ #[napi]+ pub fn emit_from_thread<'env>(&self, env: &'env Env, count: u32) -> napi::Result<Object<'env>> {+ let (deferred, promise) = env.create_deferred::<Vec<String>, Resolver<Vec<String>>>()?;+ let function = Arc::clone(&self.function);+ let closed = Arc::clone(&self.closed);+ let spawned = std::thread::Builder::new()+ .name("gbrain-sink-emit".into())+ .spawn(move || {+ let statuses: Vec<String> = (0..count)+ .map(|n| {+ if closed.load(Ordering::SeqCst) {+ Status::Closing+ } else {+ function.call(n, ThreadsafeFunctionCallMode::NonBlocking)+ }+ })+ .map(|status| status_name(status).to_owned())+ .collect();+ deferred.resolve(Box::new(move |_| Ok(statuses)));+ });+ if spawned.is_err() {+ return Err(js_error(env, TaskError::internal()));+ }+ Ok(promise)+ }++ /// Mark the sink closed: later `emit` calls return `closing`. Values already queued are still delivered.+ #[napi]+ pub fn close(&self) -> napi::Result<()> {+ self.closed.store(true, Ordering::SeqCst);+ Ok(())+ }+}diff --git a/rust/crates/gbrain-napi/src/error.rs b/rust/crates/gbrain-napi/src/error.rsnew file mode 100644index 0000000000..0ea738da98--- /dev/null+++ b/rust/crates/gbrain-napi/src/error.rs@@ -0,0 +1,130 @@+//! Typed errors for the binding.+//!+//! Every error that reaches JavaScript carries a stable `code` string, never just a message.+//! This file holds no JavaScript types, so the rules here are covered by plain `cargo test`.++use std::any::Any;+use std::panic::{AssertUnwindSafe, catch_unwind};+use std::sync::atomic::{AtomicU64, Ordering};++/// The caller asked for the task to stop and it did.+pub const CANCELLED: &str = "cancelled";+/// A Rust panic or an unexpected failure inside the engine. The process keeps running.+pub const INTERNAL_ERROR: &str = "internal_error";+/// The pool is shutting down or closed and takes no new work.+pub const ENGINE_SHUTDOWN: &str = "engine_shutdown";++/// Extra data an error can carry next to its code, readable as a property in JavaScript.+#[derive(Debug, Clone, PartialEq)]+pub enum Detail {+ Count(u32),+ Flag(bool),+ Text(String),+}++#[derive(Debug, Clone, PartialEq)]+pub struct TaskError {+ pub code: &'static str,+ pub message: String,+ pub details: Vec<(&'static str, Detail)>,+}++static DIAGNOSTIC: AtomicU64 = AtomicU64::new(1);++impl TaskError {+ pub fn new(code: &'static str, message: impl Into<String>) -> Self {+ Self {+ code,+ message: message.into(),+ details: Vec::new(),+ }+ }++ pub fn with(mut self, key: &'static str, detail: Detail) -> Self {+ self.details.push((key, detail));+ self+ }++ pub fn cancelled(completed_steps: u32, started: bool) -> Self {+ Self::new(CANCELLED, "the task was cancelled")+ .with("completedSteps", Detail::Count(completed_steps))+ .with("started", Detail::Flag(started))+ }++ pub fn shutdown() -> Self {+ Self::new(+ ENGINE_SHUTDOWN,+ "the engine is shut down and accepts no new work",+ )+ }++ /// The panic text goes to stderr through the panic hook, not into the error: a panic message+ /// can name paths or values the caller must not see. The diagnostic id ties the two together.+ pub fn internal() -> Self {+ let id = format!(+ "gbrain-{}-{}",+ std::process::id(),+ DIAGNOSTIC.fetch_add(1, Ordering::Relaxed)+ );+ Self::new(+ INTERNAL_ERROR,+ "the Rust engine hit an internal error; the process is still running",+ )+ .with("diagnosticId", Detail::Text(id))+ }+}++/// Run `work` and turn a panic into an `internal_error`. Every exported function and every task+/// on the worker pool goes through this, because a panic that unwinds into the Node-API+/// boundary ends the process.+pub fn guard<T>(work: impl FnOnce() -> Result<T, TaskError>) -> Result<T, TaskError> {+ match catch_unwind(AssertUnwindSafe(work)) {+ Ok(result) => result,+ Err(payload) => {+ drop_payload(payload);+ Err(TaskError::internal())+ }+ }+}++fn drop_payload(payload: Box<dyn Any + Send>) {+ // A payload's own destructor may panic; that must not escape either.+ let _ = catch_unwind(AssertUnwindSafe(move || drop(payload)));+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn a_panic_becomes_internal_error_with_a_diagnostic_id() {+ let result: Result<(), TaskError> = guard(|| panic!("boom with /home/someone/secret"));+ let error = result.expect_err("a panic is an error");+ assert_eq!(error.code, INTERNAL_ERROR);+ assert!(+ !error.message.contains("secret"),+ "the panic text must not leak"+ );+ assert!(+ error+ .details+ .iter()+ .any(|(key, detail)| *key == "diagnosticId"+ && matches!(detail, Detail::Text(id) if id.starts_with("gbrain-")))+ );+ }++ #[test]+ fn a_normal_result_and_a_typed_error_pass_through() {+ assert_eq!(guard(|| Ok::<_, TaskError>(7)), Ok(7));+ let error = guard::<()>(|| Err(TaskError::shutdown())).unwrap_err();+ assert_eq!(error.code, ENGINE_SHUTDOWN);+ }++ #[test]+ fn diagnostic_ids_are_unique() {+ let first = TaskError::internal();+ let second = TaskError::internal();+ assert_ne!(first.details, second.details);+ }+}diff --git a/rust/crates/gbrain-napi/src/lib.rs b/rust/crates/gbrain-napi/src/lib.rsnew file mode 100644index 0000000000..8a8f55f923--- /dev/null+++ b/rust/crates/gbrain-napi/src/lib.rs@@ -0,0 +1,81 @@+//! The Node-API binding for the gbrain Rust engine. This is the only crate that knows JavaScript.+//!+//! In this first version the addon has no engine in it. It reports who it is and carries the+//! probes that prove how Bun behaves around native code: async tasks off the event loop, typed+//! arrays, panics turned into errors, cancellation after a task started, shutdown with work+//! pending, process exit with work pending, and a full or closing threadsafe-function queue.+//!+//! Layout: `error` and `pool` hold the rules and have no JavaScript types (plain `cargo test`+//! covers them); `binding` is the thin layer that turns them into JavaScript values.++// The napi macros register exports at load time, so under `cargo test` they look unused.+#[cfg_attr(test, allow(dead_code))]+mod binding;+pub mod error;+pub mod pool;++/// A digest of the `rust/` sources the addon was built from. `build.rs` documents how it is+/// computed. Reported to JavaScript as `engineBuild`.+pub const ENGINE_BUILD: &str = env!("GBRAIN_ENGINE_BUILD");++/// Bumped when the binding surface changes. Reported as `engineAbi`.+pub const ENGINE_ABI: u32 = 1;++/// Version of the relation catalog the addon was built with. 0 until a catalog exists.+pub const CATALOG_VERSION: u32 = 0;++/// The target this addon was built for, in the names the loader uses: `linux-x64-glibc`,+/// `linux-arm64-musl`, `darwin-arm64`, `win32-x64`, and so on. Reported as `target`.+pub const fn target() -> &'static str {+ if cfg!(all(+ target_os = "linux",+ target_arch = "x86_64",+ target_env = "musl"+ )) {+ "linux-x64-musl"+ } else if cfg!(all(target_os = "linux", target_arch = "x86_64")) {+ "linux-x64-glibc"+ } else if cfg!(all(+ target_os = "linux",+ target_arch = "aarch64",+ target_env = "musl"+ )) {+ "linux-arm64-musl"+ } else if cfg!(all(target_os = "linux", target_arch = "aarch64")) {+ "linux-arm64-glibc"+ } else if cfg!(all(target_os = "macos", target_arch = "aarch64")) {+ "darwin-arm64"+ } else if cfg!(all(target_os = "macos", target_arch = "x86_64")) {+ "darwin-x64"+ } else if cfg!(all(target_os = "windows", target_arch = "x86_64")) {+ "win32-x64"+ } else if cfg!(all(target_os = "windows", target_arch = "aarch64")) {+ "win32-arm64"+ } else {+ "unsupported"+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn the_engine_build_is_a_sha256_hex_digest() {+ assert_eq!(ENGINE_BUILD.len(), 64);+ assert!(ENGINE_BUILD.bytes().all(|b| b.is_ascii_hexdigit()));+ }++ #[test]+ fn the_target_is_one_the_loader_knows() {+ assert_ne!(+ target(),+ "unsupported",+ "add the new target to target() and the build script"+ );+ assert!(+ target().contains('-'),+ "target names look like os-arch[-libc]"+ );+ }+}diff --git a/rust/crates/gbrain-napi/src/pool.rs b/rust/crates/gbrain-napi/src/pool.rsnew file mode 100644index 0000000000..7f73a3f3f6--- /dev/null+++ b/rust/crates/gbrain-napi/src/pool.rs@@ -0,0 +1,576 @@+//! A small worker pool with a clean shutdown, and a cancellable step runner.+//!+//! The pool is plain Rust: it knows nothing about JavaScript. The binding wraps each call in a+//! [`Task`] that settles a JavaScript promise when the work finishes or is cancelled.++use std::collections::VecDeque;+use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};+use std::sync::{Arc, Condvar, Mutex, MutexGuard};+use std::thread;+use std::time::{Duration, Instant};++use crate::error::{TaskError, guard};++/// One unit of queued work. Exactly one of `run` and `cancel` is called, exactly once.+pub trait Task: Send + 'static {+ /// Runs on a worker thread.+ fn run(self: Box<Self>);+ /// The pool shut down before the task started.+ fn cancel(self: Box<Self>, error: TaskError);+}++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum Phase {+ Running,+ ShuttingDown,+ Closed,+}++impl Phase {+ pub fn as_str(self) -> &'static str {+ match self {+ Phase::Running => "running",+ Phase::ShuttingDown => "shutting_down",+ Phase::Closed => "closed",+ }+ }+}++/// What `shutdown` found and did.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]+pub struct ShutdownReport {+ /// Tasks that were still queued; each was cancelled before it started.+ pub cancelled_queued: u32,+ /// Tasks that were running when shutdown began and finished within the wait.+ pub finished_running: u32,+ /// Tasks still running when the wait ended. They finish on their own later.+ pub abandoned_running: u32,+}++struct State {+ phase: Phase,+ queue: VecDeque<Box<dyn Task>>,+ running: u32,+ /// Worker threads that are still in their loop.+ workers: u32,+}++struct Shared {+ state: Mutex<State>,+ changed: Condvar,+}++impl Shared {+ fn lock(&self) -> MutexGuard<'_, State> {+ // A task panic is caught before it can poison this lock; if one ever does, keep going.+ self.state+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner())+ }+}++#[derive(Clone)]+pub struct Pool {+ shared: Arc<Shared>,+}++/// Worker threads in their loop across every pool in the process.+static LIVE_WORKERS: AtomicU32 = AtomicU32::new(0);++/// Worker threads still in their loop across every pool in the process.+pub fn live_workers() -> u32 {+ LIVE_WORKERS.load(Ordering::SeqCst)+}++/// The most worker threads one pool starts. A larger request is cut to this.+pub const MAX_WORKERS: usize = 256;++/// Starts one worker thread. The default uses `std::thread`; tests pass one that can fail.+type Spawner<'a> = dyn FnMut(usize, Box<dyn FnOnce() + Send>) -> std::io::Result<()> + 'a;++impl Pool {+ /// Start `workers` threads (at least 1, at most [`MAX_WORKERS`]). If the operating system+ /// refuses a thread, the threads already started stop and the call returns+ /// `internal_error`; nothing panics.+ pub fn new(workers: usize) -> Result<Self, TaskError> {+ Self::start(workers, &mut |index, work| {+ // Detached on purpose: at process exit the operating system ends the workers.+ thread::Builder::new()+ .name(format!("gbrain-worker-{index}"))+ .spawn(work)+ .map(drop)+ })+ }++ fn start(workers: usize, spawn: &mut Spawner<'_>) -> Result<Self, TaskError> {+ let shared = Arc::new(Shared {+ state: Mutex::new(State {+ phase: Phase::Running,+ queue: VecDeque::new(),+ running: 0,+ workers: 0,+ }),+ changed: Condvar::new(),+ });+ for index in 0..workers.clamp(1, MAX_WORKERS) {+ let worker_shared = Arc::clone(&shared);+ // Counted before the thread starts, so a worker that exits at once never underflows.+ shared.lock().workers += 1;+ LIVE_WORKERS.fetch_add(1, Ordering::SeqCst);+ if spawn(index, Box::new(move || worker_loop(&worker_shared))).is_err() {+ shared.lock().workers -= 1;+ LIVE_WORKERS.fetch_sub(1, Ordering::SeqCst);+ // Close the pool so the workers already started leave their loop.+ shared.lock().phase = Phase::Closed;+ shared.changed.notify_all();+ return Err(TaskError::internal());+ }+ }+ Ok(Self { shared })+ }++ pub fn phase(&self) -> Phase {+ self.shared.lock().phase+ }++ pub fn queued(&self) -> u32 {+ self.shared.lock().queue.len() as u32+ }++ pub fn running(&self) -> u32 {+ self.shared.lock().running+ }++ /// Worker threads still in their loop. It falls to 0 after the pool closes and the last+ /// running task ends.+ pub fn workers(&self) -> u32 {+ self.shared.lock().workers+ }++ /// Close the pool without waiting: queued tasks are cancelled, idle workers exit now and+ /// busy ones exit when their task ends. For an owner that goes away without `shutdown`.+ pub fn close_now(&self) {+ self.begin_shutdown().finish(Duration::ZERO);+ }++ /// Queue a task. A pool that is shutting down or closed hands the task back.+ pub fn submit(&self, task: Box<dyn Task>) -> Result<(), Box<dyn Task>> {+ let mut state = self.shared.lock();+ if state.phase != Phase::Running {+ return Err(task);+ }+ state.queue.push_back(task);+ self.shared.changed.notify_one();+ Ok(())+ }++ /// Stop admission, cancel queued tasks, wait up to `wait` for running ones, then close.+ /// Blocks the calling thread. Calling it again waits for whatever is still running and+ /// reports the later outcome.+ pub fn shutdown(&self, wait: Duration) -> ShutdownReport {+ self.begin_shutdown().finish(wait)+ }++ /// Stop admission now, without blocking: every `submit` after this returns refuses the+ /// task. Queued tasks are taken out of the queue but not yet cancelled; [`Draining::finish`]+ /// cancels them and does the bounded wait, so the binding can run that part off the+ /// JavaScript thread.+ pub fn begin_shutdown(&self) -> Draining {+ let (queued, running_at_start) = {+ let mut state = self.shared.lock();+ if state.phase == Phase::Running {+ state.phase = Phase::ShuttingDown;+ }+ (std::mem::take(&mut state.queue), state.running)+ };+ self.shared.changed.notify_all();+ Draining {+ shared: Arc::clone(&self.shared),+ queued,+ running_at_start,+ }+ }+}++/// A shutdown that has closed admission and still has to cancel and wait.+pub struct Draining {+ shared: Arc<Shared>,+ queued: VecDeque<Box<dyn Task>>,+ running_at_start: u32,+}++impl Draining {+ /// Cancel the queued tasks, wait up to `wait` for running ones, then close the pool.+ pub fn finish(self, wait: Duration) -> ShutdownReport {+ let cancelled_queued = self.queued.len() as u32;+ for task in self.queued {+ // Settling a promise must not take the pool down if it panics.+ let _ = guard(|| {+ task.cancel(TaskError::cancelled(0, false));+ Ok(())+ });+ }+ let deadline = Instant::now() + wait;+ let mut state = self.shared.lock();+ while state.running > 0 {+ let now = Instant::now();+ if now >= deadline {+ break;+ }+ state = self+ .shared+ .changed+ .wait_timeout(state, deadline - now)+ .unwrap_or_else(|poisoned| poisoned.into_inner())+ .0;+ }+ let abandoned_running = state.running;+ state.phase = Phase::Closed;+ drop(state);+ self.shared.changed.notify_all();+ ShutdownReport {+ cancelled_queued,+ finished_running: self.running_at_start.saturating_sub(abandoned_running),+ abandoned_running,+ }+ }+}++fn worker_loop(shared: &Shared) {+ run_worker(shared);+ shared.lock().workers -= 1;+ LIVE_WORKERS.fetch_sub(1, Ordering::SeqCst);+ shared.changed.notify_all();+}++fn run_worker(shared: &Shared) {+ loop {+ let task = {+ let mut state = shared.lock();+ loop {+ if let Some(task) = state.queue.pop_front() {+ state.running += 1;+ break task;+ }+ if state.phase != Phase::Running {+ return;+ }+ state = shared+ .changed+ .wait(state)+ .unwrap_or_else(|poisoned| poisoned.into_inner());+ }+ };+ // A task settles its own promise and turns its own panic into an error. This second+ // guard only keeps the worker alive if a task fails to.+ let _ = guard(|| {+ task.run();+ Ok(())+ });+ shared.lock().running -= 1;+ shared.changed.notify_all();+ }+}++/// A flag one side sets and the other checks between steps.+#[derive(Clone, Default)]+pub struct CancelToken {+ flag: Arc<AtomicBool>,+}++impl CancelToken {+ pub fn new() -> Self {+ Self::default()+ }++ pub fn cancel(&self) {+ self.flag.store(true, Ordering::SeqCst);+ }++ pub fn is_cancelled(&self) -> bool {+ self.flag.load(Ordering::SeqCst)+ }+}++/// Do `steps` steps of `step` each. The token is checked before every step, so a task cancelled+/// after it started stops at the next boundary and reports how many steps it finished.+pub fn run_steps(+ steps: u32,+ step: Duration,+ cancel: Option<&CancelToken>,+) -> Result<u32, TaskError> {+ run_steps_observed(steps, step, cancel, |_| {})+}++/// [`run_steps`] that calls `after_step` with the count after each finished step.+fn run_steps_observed(+ steps: u32,+ step: Duration,+ cancel: Option<&CancelToken>,+ mut after_step: impl FnMut(u32),+) -> Result<u32, TaskError> {+ let mut completed = 0;+ while completed < steps {+ if cancel.is_some_and(CancelToken::is_cancelled) {+ return Err(TaskError::cancelled(completed, true));+ }+ thread::sleep(step);+ completed += 1;+ after_step(completed);+ }+ Ok(completed)+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::error::{CANCELLED, Detail, ENGINE_SHUTDOWN, INTERNAL_ERROR};+ use std::sync::mpsc;++ const LONG: Duration = Duration::from_secs(5);++ /// Says "started" when a worker picks it up, holds the worker until `release` is signalled+ /// (or dropped), then says "ran". Says "cancelled" if the pool cancels it instead.+ struct Probe {+ events: mpsc::Sender<&'static str>,+ release: Option<mpsc::Receiver<()>>,+ }++ impl Probe {+ fn quick(events: &mpsc::Sender<&'static str>) -> Box<Self> {+ Box::new(Self {+ events: events.clone(),+ release: None,+ })+ }++ fn held(events: &mpsc::Sender<&'static str>) -> (Box<Self>, mpsc::Sender<()>) {+ let (release_tx, release_rx) = mpsc::channel();+ let probe = Box::new(Self {+ events: events.clone(),+ release: Some(release_rx),+ });+ (probe, release_tx)+ }+ }++ impl Task for Probe {+ fn run(self: Box<Self>) {+ let _ = self.events.send("started");+ if let Some(release) = &self.release {+ // A closed channel also releases the task.+ let _ = release.recv();+ }+ let _ = self.events.send("ran");+ }+ fn cancel(self: Box<Self>, error: TaskError) {+ assert_eq!(error.code, CANCELLED);+ let _ = self.events.send("cancelled");+ }+ }++ struct Panics;+ impl Task for Panics {+ fn run(self: Box<Self>) {+ panic!("a task panicked on purpose");+ }+ fn cancel(self: Box<Self>, _: TaskError) {}+ }++ fn pool(workers: usize) -> Pool {+ Pool::new(workers).expect("start the pool")+ }++ /// Waits until `check` holds, for at most [`LONG`].+ fn eventually(what: &str, check: impl Fn() -> bool) {+ let deadline = Instant::now() + LONG;+ while !check() {+ assert!(Instant::now() < deadline, "timed out waiting for {what}");+ thread::yield_now();+ }+ }++ #[test]+ fn steps_report_how_many_finished_when_cancelled_after_the_start() {+ let token = CancelToken::new();+ let (step_tx, step_rx) = mpsc::channel();+ let worker = {+ let token = token.clone();+ thread::spawn(move || {+ run_steps_observed(1000, Duration::from_millis(1), Some(&token), |n| {+ let _ = step_tx.send(n);+ })+ })+ };+ // Cancel only after the first step is known to be done.+ assert_eq!(step_rx.recv_timeout(LONG), Ok(1));+ token.cancel();+ let error = worker.join().unwrap().expect_err("cancelled");+ assert_eq!(error.code, CANCELLED);+ let completed = error+ .details+ .iter()+ .find_map(|(key, detail)| match (*key, detail) {+ ("completedSteps", Detail::Count(n)) => Some(*n),+ _ => None,+ });+ assert!(+ matches!(completed, Some(n) if n > 0 && n < 1000),+ "{completed:?}"+ );+ assert!(error.details.contains(&("started", Detail::Flag(true))));+ }++ #[test]+ fn steps_finish_when_nobody_cancels() {+ assert_eq!(run_steps(3, Duration::from_millis(1), None), Ok(3));+ }++ #[test]+ fn shutdown_cancels_queued_waits_for_running_and_then_refuses() {+ let pool = pool(1);+ let (tx, rx) = mpsc::channel();+ let (first, release) = Probe::held(&tx);+ assert!(pool.submit(first).is_ok());+ assert_eq!(rx.recv_timeout(LONG), Ok("started"));+ assert!(pool.submit(Probe::quick(&tx)).is_ok());+ assert!(pool.submit(Probe::quick(&tx)).is_ok());+ let shutdown = {+ let pool = pool.clone();+ thread::spawn(move || pool.shutdown(LONG))+ };+ // Both queued tasks are cancelled before the running one is let go.+ assert_eq!(rx.recv_timeout(LONG), Ok("cancelled"));+ assert_eq!(rx.recv_timeout(LONG), Ok("cancelled"));+ drop(release);+ let report = shutdown.join().unwrap();+ assert_eq!(+ report,+ ShutdownReport {+ cancelled_queued: 2,+ finished_running: 1,+ abandoned_running: 0+ }+ );+ assert_eq!(rx.recv_timeout(LONG), Ok("ran"));+ assert_eq!(pool.phase(), Phase::Closed);+ let refused = pool.submit(Probe::quick(&tx));+ assert!(refused.is_err(), "a closed pool takes no work");+ assert_eq!(TaskError::shutdown().code, ENGINE_SHUTDOWN);+ eventually("the worker to exit", || pool.workers() == 0);+ }++ #[test]+ fn shutdown_gives_up_waiting_after_the_bound() {+ let pool = pool(1);+ let (tx, rx) = mpsc::channel();+ let (held, release) = Probe::held(&tx);+ assert!(pool.submit(held).is_ok());+ assert_eq!(rx.recv_timeout(LONG), Ok("started"));+ let report = pool.shutdown(Duration::from_millis(20));+ assert_eq!(report.abandoned_running, 1);+ assert_eq!(pool.phase(), Phase::Closed);+ // The abandoned task still ends on its own, and then its worker exits.+ drop(release);+ assert_eq!(rx.recv_timeout(LONG), Ok("ran"));+ eventually("the worker to exit", || pool.workers() == 0);+ }++ #[test]+ fn admission_closes_when_shutdown_begins_not_when_it_finishes() {+ let pool = pool(1);+ let (tx, rx) = mpsc::channel();+ let (held, release) = Probe::held(&tx);+ assert!(pool.submit(held).is_ok());+ assert_eq!(rx.recv_timeout(LONG), Ok("started"));+ assert!(pool.submit(Probe::quick(&tx)).is_ok());+ let draining = pool.begin_shutdown();+ assert_eq!(pool.phase(), Phase::ShuttingDown);+ assert!(+ pool.submit(Probe::quick(&tx)).is_err(),+ "no task is admitted once shutdown has begun"+ );+ assert_eq!(+ pool.queued(),+ 0,+ "the queued task was taken out of the queue"+ );+ drop(release);+ let report = draining.finish(LONG);+ assert_eq!(report.cancelled_queued, 1);+ assert_eq!(report.finished_running, 1);+ let mut seen: Vec<_> = rx.try_iter().collect();+ seen.sort_unstable();+ assert_eq!(seen, ["cancelled", "ran"]);+ }++ #[test]+ fn close_now_stops_idle_workers_without_waiting() {+ let pool = pool(4);+ eventually("the workers to start", || pool.workers() == 4);+ let (tx, rx) = mpsc::channel();+ let (held, release) = Probe::held(&tx);+ assert!(pool.submit(held).is_ok());+ assert_eq!(rx.recv_timeout(LONG), Ok("started"));+ pool.close_now();+ assert_eq!(pool.phase(), Phase::Closed);+ assert!(pool.submit(Probe::quick(&tx)).is_err());+ eventually("the idle workers to exit", || pool.workers() == 1);+ drop(release);+ eventually("the busy worker to exit", || pool.workers() == 0);+ }++ #[test]+ fn a_worker_that_cannot_start_fails_the_pool_and_stops_the_others() {+ let mut started = Vec::new();+ let result = Pool::start(3, &mut |index, work| {+ if index == 2 {+ return Err(std::io::Error::other("no more threads"));+ }+ started.push(thread::spawn(work));+ Ok(())+ });+ let error = result.err().expect("the pool must not start");+ assert_eq!(error.code, INTERNAL_ERROR);+ let (done_tx, done_rx) = mpsc::channel();+ thread::spawn(move || {+ for worker in started {+ let _ = worker.join();+ }+ let _ = done_tx.send(());+ });+ assert_eq!(+ done_rx.recv_timeout(LONG),+ Ok(()),+ "the workers already started must leave their loop"+ );+ }++ #[test]+ fn the_worker_count_is_at_least_one_and_at_most_the_bound() {+ let mut asked = 0;+ let mut count = |workers| {+ asked = 0;+ let pool = Pool::start(workers, &mut |_, _| {+ asked += 1;+ Ok(())+ })+ .expect("start");+ pool.close_now();+ asked+ };+ assert_eq!(count(0), 1);+ assert_eq!(count(3), 3);+ assert_eq!(count(usize::MAX), MAX_WORKERS);+ }++ #[test]+ fn a_panicking_task_does_not_kill_its_worker() {+ let pool = pool(1);+ assert!(pool.submit(Box::new(Panics)).is_ok());+ let (tx, rx) = mpsc::channel();+ assert!(pool.submit(Probe::quick(&tx)).is_ok());+ assert_eq!(rx.recv_timeout(LONG), Ok("started"));+ assert_eq!(rx.recv_timeout(LONG), Ok("ran"));+ }+}diff --git a/rust/deny.toml b/rust/deny.tomlnew file mode 100644index 0000000000..9e264df01a--- /dev/null+++ b/rust/deny.toml@@ -0,0 +1,40 @@+# cargo-deny policy for the Rust engine workspace. Run with `cargo deny check` from rust/.+# `advisories` downloads the RustSec database, so that check needs network access.++[graph]+# Check what ships on the platforms the addon is built for, not every target cargo knows.+targets = [+ "x86_64-unknown-linux-gnu",+ "aarch64-unknown-linux-gnu",+ "x86_64-unknown-linux-musl",+ "aarch64-unknown-linux-musl",+ "aarch64-apple-darwin",+ "x86_64-apple-darwin",+ "x86_64-pc-windows-msvc",+ "aarch64-pc-windows-msvc",+]++[advisories]+version = 2+yanked = "deny"++[licenses]+version = 2+# Licenses of the dependencies in Cargo.lock today. Adding one here is a review decision.+allow = [+ "MIT",+ "Apache-2.0",+ "ISC",+ "Unicode-3.0",+]+confidence-threshold = 0.9++[bans]+multiple-versions = "warn"+wildcards = "deny"+allow-wildcard-paths = true++[sources]+unknown-registry = "deny"+unknown-git = "deny"+allow-registry = ["https://github.com/rust-lang/crates.io-index"]diff --git a/rust/rust-toolchain.toml b/rust/rust-toolchain.tomlnew file mode 100644index 0000000000..b17b266180--- /dev/null+++ b/rust/rust-toolchain.toml@@ -0,0 +1,4 @@+[toolchain]+channel = "1.100.0"+components = ["clippy", "rustfmt"]+profile = "minimal"diff --git a/rust/scripts/build.ts b/rust/scripts/build.tsnew file mode 100644index 0000000000..47d0183cbf--- /dev/null+++ b/rust/scripts/build.ts@@ -0,0 +1,90 @@+#!/usr/bin/env bun+/**+ * Build the Rust engine addon and copy it to a predictable place.+ *+ * bun run rust:build+ *+ * Output: rust/target/addon/gbrain_engine.<target>.node, plus the line to export so the loader+ * (and rust/smoke/run.ts) can find it:+ *+ * GBRAIN_RUST_ENGINE_ADDON=/abs/path/to/gbrain_engine.<target>.node+ *+ * Rust is optional for gbrain. This script is the only place that needs it, and when cargo is+ * missing it stops with install instructions before touching anything.+ */+import { copyFileSync, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';++const rustDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');++function fail(message: string): never {+ console.error(`rust:build: ${message}`);+ process.exit(1);+}++/** Rust host triple -> the target names the engine reports (see `target()` in the crate). */+const TARGETS: Record<string, { name: string; library: string }> = {+ 'x86_64-unknown-linux-gnu': { name: 'linux-x64-glibc', library: 'libgbrain_napi.so' },+ 'x86_64-unknown-linux-musl': { name: 'linux-x64-musl', library: 'libgbrain_napi.so' },+ 'aarch64-unknown-linux-gnu': { name: 'linux-arm64-glibc', library: 'libgbrain_napi.so' },+ 'aarch64-unknown-linux-musl': { name: 'linux-arm64-musl', library: 'libgbrain_napi.so' },+ 'aarch64-apple-darwin': { name: 'darwin-arm64', library: 'libgbrain_napi.dylib' },+ 'x86_64-apple-darwin': { name: 'darwin-x64', library: 'libgbrain_napi.dylib' },+ 'x86_64-pc-windows-msvc': { name: 'win32-x64', library: 'gbrain_napi.dll' },+ 'aarch64-pc-windows-msvc': { name: 'win32-arm64', library: 'gbrain_napi.dll' },+};++if (!Bun.which('cargo') || !Bun.which('rustc')) {+ fail(+ 'cargo was not found on PATH. The Rust engine is optional, but building it needs Rust.\n' ++ ' Install it with rustup: curl --proto "=https" --tlsv1.2 -sSf https://sh.rustup.rs | sh\n' ++ ' then open a new shell (or run `. "$HOME/.cargo/env"`) and re-run `bun run rust:build`.\n' ++ ' rustup reads rust/rust-toolchain.toml and installs the pinned Rust version by itself.',+ );+}++const version = Bun.spawnSync(['rustc', '-vV'], { cwd: rustDir, stderr: 'pipe' });+if (version.exitCode !== 0) {+ fail(`rustc -vV failed:\n${version.stderr.toString()}`);+}+const host = /^host: (\S+)$/m.exec(version.stdout.toString())?.[1];+if (!host) fail('could not read the host triple from `rustc -vV`.');+const target = TARGETS[host];+if (!target) {+ fail(`no addon target is defined for host ${host}. Add it to TARGETS here and to target() in the crate.`);+}++// Name the output directory and the target, so a CARGO_TARGET_DIR, build.target-dir,+// CARGO_BUILD_TARGET or build.target setting cannot send the build elsewhere while the copy below+// picks up an older library. With --target, cargo always writes to target/<host>/release.+const build = Bun.spawnSync(+ ['cargo', 'build', '--release', '-p', 'gbrain-napi', '--target', host, '--target-dir', join(rustDir, 'target')],+ {+ cwd: rustDir,+ stdout: 'inherit',+ stderr: 'inherit',+ },+);+if (build.exitCode !== 0) fail(`cargo build failed (exit ${build.exitCode}). No addon was written.`);++const built = join(rustDir, 'target', host, 'release', target.library);+if (!existsSync(built)) fail(`cargo succeeded but ${built} does not exist.`);++const outDir = join(rustDir, 'target', 'addon');+mkdirSync(outDir, { recursive: true });+const finalPath = join(outDir, `gbrain_engine.${target.name}.node`);+// Copy to a new file and rename over the old one. A new inode matters on macOS, where a+// previously loaded or signed file that is overwritten in place can be killed by the kernel.+const tmpPath = `${finalPath}.${process.pid}.tmp`;+try {+ copyFileSync(built, tmpPath);+ renameSync(tmpPath, finalPath);+} catch (error) {+ rmSync(tmpPath, { force: true });+ fail(`could not write ${finalPath}: ${error instanceof Error ? error.message : String(error)}`);+}++console.log(`\nBuilt ${finalPath}`);+console.log('Point gbrain at it with:\n');+console.log(` export GBRAIN_RUST_ENGINE_ADDON=${finalPath}`);diff --git a/rust/smoke/addon.ts b/rust/smoke/addon.tsnew file mode 100644index 0000000000..829a4263a2--- /dev/null+++ b/rust/smoke/addon.ts@@ -0,0 +1,66 @@+/**+ * Loads the Rust engine addon for the smoke tests. The path comes only from+ * GBRAIN_RUST_ENGINE_ADDON (printed by `bun run rust:build`); nothing is searched for.+ *+ * It uses process.dlopen with a path computed at run time. A literal `require('x.node')` would be+ * bundled by `bun build --compile`; a computed path is not, which is what the compiled-binary+ * check in selfcheck.ts depends on.+ */++export interface ShutdownReport {+ cancelledQueued: number;+ finishedRunning: number;+ abandonedRunning: number;+}++export interface CancelToken {+ cancel(): void;+ readonly cancelled: boolean;+}++export interface Pool {+ readonly state: string;+ readonly queued: number;+ readonly running: number;+ readonly workers: number;+ blockFor(ms: number): Promise<number>;+ runSteps(steps: number, stepMs: number, token?: CancelToken): Promise<number>;+ sumF32(values: Float32Array): Promise<number>;+ scaleF32(values: Float32Array, factor: number): Promise<Float32Array>;+ probePanic(): Promise<number>;+ shutdown(waitMs: number): Promise<ShutdownReport>;+}++export interface Sink {+ emit(value: number): string;+ emitFromThread(count: number): Promise<string[]>;+ close(): void;+}++export interface Addon {+ target: string;+ engineAbi: number;+ engineBuild: string;+ catalogVersion: number;+ formatVersions: unknown[];+ sinkMaxQueueSize: number;+ sumF32(values: Float32Array): number;+ scaleF32(values: Float32Array, factor: number): Float32Array;+ scaleInPlaceF32(values: Float32Array, factor: number): number;+ probePanicSync(): void;+ liveWorkers(): number;+ CancelToken: new () => CancelToken;+ Pool: new (workers: number) => Pool;+ Sink: new (callback: (value: number) => void) => Sink;+}++export function loadAddon(path: string | undefined = process.env.GBRAIN_RUST_ENGINE_ADDON): Addon {+ if (!path) {+ throw new Error(+ 'GBRAIN_RUST_ENGINE_ADDON is not set. Run `bun run rust:build` and export the path it prints.',+ );+ }+ const module = { exports: {} as unknown };+ process.dlopen(module as NodeJS.Module, path);+ return module.exports as Addon;+}diff --git a/rust/smoke/cases.ts b/rust/smoke/cases.tsnew file mode 100644index 0000000000..3ff8f9273e--- /dev/null+++ b/rust/smoke/cases.ts@@ -0,0 +1,362 @@+/**+ * The addon proofs. Each case takes the loaded addon and throws if the behavior is wrong.+ * `run.ts` runs all of them under Bun; `selfcheck.ts` runs the ones in `compiledCases` inside a+ * `bun build --compile` executable.+ */+import assert from 'node:assert/strict';+import type { Addon, Pool } from './addon.ts';++export interface Case {+ name: string;+ run(addon: Addon): Promise<void> | void;+}++const sleep = (ms: number) => new Promise<void>(resolve => setTimeout(resolve, ms));++/** Wait until `check` holds, for at most `ms`. */+async function until(what: string, check: () => boolean, ms = 5000): Promise<void> {+ const deadline = performance.now() + ms;+ while (!check()) {+ if (performance.now() > deadline) throw new assert.AssertionError({ message: `timed out waiting for ${what}` });+ await sleep(5);+ }+}++/** The error a synchronous call throws. */+function thrown(call: () => unknown): Error & Record<string, unknown> {+ try {+ call();+ } catch (error) {+ assert.ok(error instanceof Error, 'throws must be real Error objects');+ return error as Error & Record<string, unknown>;+ }+ throw new assert.AssertionError({ message: 'expected the call to throw' });+}++/** Await a promise that must reject, and return the rejection. */+async function rejection(promise: Promise<unknown>): Promise<Error & Record<string, unknown>> {+ try {+ await promise;+ } catch (error) {+ assert.ok(error instanceof Error, 'rejections must be real Error objects');+ return error as Error & Record<string, unknown>;+ }+ throw new assert.AssertionError({ message: 'expected the promise to reject' });+}++export const cases: Case[] = [+ {+ name: 'metadata: target, abi, build hash, catalog version, format versions',+ run(addon) {+ assert.match(addon.target, /^(linux|darwin|win32)-(x64|arm64)(-(glibc|musl))?$/);+ assert.equal(addon.engineAbi, 1);+ assert.match(addon.engineBuild, /^[0-9a-f]{64}$/);+ assert.equal(addon.catalogVersion, 0);+ assert.deepEqual(addon.formatVersions, []);+ },+ },+ {+ name: 'event loop stays free: a timer fires while a native task runs',+ async run(addon) {+ const pool = new addon.Pool(2);+ let ticks = 0;+ const timer = setInterval(() => ticks++, 10);+ const startedAt = performance.now();+ try {+ assert.equal(await pool.blockFor(300), 300);+ } finally {+ clearInterval(timer);+ }+ assert.ok(performance.now() - startedAt >= 290, 'the task waited for its full time');+ // A blocked loop would give 0 or 1 ticks. 300 ms at 10 ms is about 30; allow a lot of slack.+ assert.ok(ticks >= 10, `timer fired only ${ticks} times during a 300 ms native task`);+ await pool.shutdown(1000);+ },+ },+ {+ name: 'typed arrays: sync sum, scale, in-place scale, offset views, empty array',+ run(addon) {+ assert.equal(addon.sumF32(new Float32Array([1, 2, 3.5])), 6.5);+ const input = new Float32Array([1, 2, 3]);+ const scaled = addon.scaleF32(input, 2);+ assert.deepEqual([...scaled], [2, 4, 6]);+ assert.deepEqual([...input], [1, 2, 3], 'scaleF32 leaves its input alone');+ assert.notEqual(scaled.buffer, input.buffer, 'scaleF32 returns a new array');+ const mutable = new Float32Array([1, 2, 3]);+ assert.equal(addon.scaleInPlaceF32(mutable, 3), 3);+ assert.deepEqual([...mutable], [3, 6, 9], 'scaleInPlaceF32 writes into the caller array');+ const window = new Float32Array([5, 1, 2, 5]);+ addon.scaleInPlaceF32(window.subarray(1, 3), 10);+ assert.deepEqual([...window], [5, 10, 20, 5], 'an offset view only touches its own window');+ // A view into the middle of a larger buffer must read only its own window.+ const backing = new Float32Array([100, 100, 1, 2, 3, 100]);+ assert.equal(addon.sumF32(backing.subarray(2, 5)), 6);+ assert.equal(addon.sumF32(new Float32Array(0)), 0);+ assert.equal(addon.scaleF32(new Float32Array(0), 3).length, 0);+ },+ },+ {+ name: 'typed arrays: async calls copy the input before returning',+ async run(addon) {+ const pool = new addon.Pool(1);+ // Occupy the only worker so the sum is still queued when the array changes below.+ const busy = pool.blockFor(100);+ const values = new Float32Array([1, 2, 3]);+ const sum = pool.sumF32(values);+ const scaled = pool.scaleF32(values, 10);+ values.fill(1000);+ assert.equal(await sum, 6, 'the sum used the values at call time');+ assert.deepEqual([...(await scaled)], [10, 20, 30]);+ await busy;+ assert.equal(await pool.sumF32(new Float32Array(0)), 0);+ await pool.shutdown(1000);+ },+ },+ {+ name: 'panics: a sync panic is a typed Error and the process keeps working',+ run(addon) {+ let caught: (Error & Record<string, unknown>) | undefined;+ try {+ addon.probePanicSync();+ } catch (error) {+ caught = error as Error & Record<string, unknown>;+ }+ assert.ok(caught instanceof Error);+ assert.equal(caught.code, 'internal_error');+ assert.match(String(caught.diagnosticId), /^gbrain-\d+-\d+$/);+ assert.ok(!caught.message.includes('on purpose'), 'the panic text must not reach callers');+ assert.equal(addon.sumF32(new Float32Array([4])), 4, 'the next call still works');+ },+ },+ {+ name: 'panics: an async panic rejects, and the same pool runs the next task',+ async run(addon) {+ const pool = new addon.Pool(1);+ const error = await rejection(pool.probePanic());+ assert.equal(error.code, 'internal_error');+ assert.match(String(error.diagnosticId), /^gbrain-\d+-\d+$/);+ assert.equal(await pool.sumF32(new Float32Array([1, 2])), 3, 'the only worker survived');+ assert.equal(pool.state, 'running');+ await pool.shutdown(1000);+ },+ },+ {+ name: 'cancellation: a token cancelled after start rejects with completedSteps',+ async run(addon) {+ const pool = new addon.Pool(1);+ const token = new addon.CancelToken();+ const controller = new AbortController();+ // The mapping the TypeScript wrapper will use for AbortSignal.+ controller.signal.addEventListener('abort', () => token.cancel());+ const task = pool.runSteps(200, 10, token);+ await sleep(80);+ controller.abort();+ const error = await rejection(task);+ assert.equal(error.code, 'cancelled');+ assert.equal(error.started, true);+ const done = error.completedSteps as number;+ assert.ok(done > 0 && done < 200, `completedSteps was ${done}`);+ assert.equal(token.cancelled, true);+ // Not cancelled: runs to the end.+ assert.equal(await pool.runSteps(3, 5, new addon.CancelToken()), 3);+ // Cancelled before it starts: rejects with started=false and zero steps.+ const early = new addon.CancelToken();+ early.cancel();+ const earlyError = await rejection(pool.runSteps(5, 5, early));+ assert.equal(earlyError.code, 'cancelled');+ assert.equal(earlyError.completedSteps, 0);+ await pool.shutdown(1000);+ },+ },+ {+ name: 'shutdown: queued tasks cancel, running tasks are awaited, later calls reject',+ async run(addon) {+ const pool = new addon.Pool(1);+ const running = pool.blockFor(300);+ const queuedA = rejection(pool.blockFor(10));+ const queuedB = rejection(pool.blockFor(10));+ await until('the first task to start', () => pool.running === 1);+ assert.equal(pool.running, 1);+ assert.equal(pool.queued, 2);+ const startedAt = performance.now();+ const report = await pool.shutdown(5000);+ const waited = performance.now() - startedAt;+ assert.deepEqual(report, { cancelledQueued: 2, finishedRunning: 1, abandonedRunning: 0 });+ assert.ok(waited < 2000, `shutdown took ${waited.toFixed(0)} ms`);+ assert.equal(await running, 300, 'the running task finished normally');+ for (const error of await Promise.all([queuedA, queuedB])) {+ assert.equal(error.code, 'cancelled');+ assert.equal(error.started, false);+ assert.equal(error.completedSteps, 0);+ }+ assert.equal(pool.state, 'closed');+ assert.equal((await rejection(pool.blockFor(1))).code, 'engine_shutdown');+ assert.equal((await rejection(pool.sumF32(new Float32Array(1)))).code, 'engine_shutdown');+ // Shutting down again is allowed and reports nothing left to do.+ assert.deepEqual(await pool.shutdown(100), {+ cancelledQueued: 0,+ finishedRunning: 0,+ abandonedRunning: 0,+ });+ },+ },+ {+ name: 'shutdown: the wait is bounded when a task will not finish in time',+ async run(addon) {+ const pool: Pool = new addon.Pool(1);+ const slow = pool.blockFor(1500);+ await until('the slow task to start', () => pool.running === 1);+ const startedAt = performance.now();+ const report = await pool.shutdown(150);+ const waited = performance.now() - startedAt;+ assert.equal(report.abandonedRunning, 1);+ assert.equal(report.finishedRunning, 0);+ assert.ok(waited >= 140 && waited < 1000, `waited ${waited.toFixed(0)} ms for a 150 ms bound`);+ assert.equal(pool.state, 'closed');+ assert.equal(await slow, 1500, 'the abandoned task still settles its promise');+ },+ },+ {+ name: 'shutdown: admission closes before shutdown() returns, not when it settles',+ async run(addon) {+ const pool = new addon.Pool(1);+ const running = pool.blockFor(200);+ const queued = rejection(pool.blockFor(10));+ await until('the first task to start', () => pool.running === 1);+ const pending = pool.shutdown(5000);+ // The shutdown promise is still pending; nothing new may get in.+ assert.equal(pool.state, 'shutting_down');+ assert.equal((await rejection(pool.blockFor(1))).code, 'engine_shutdown');+ assert.equal((await rejection(pool.runSteps(1, 1))).code, 'engine_shutdown');+ assert.equal((await rejection(pool.sumF32(new Float32Array([1])))).code, 'engine_shutdown');+ assert.deepEqual(await pending, { cancelledQueued: 1, finishedRunning: 1, abandonedRunning: 0 });+ assert.equal((await queued).code, 'cancelled');+ assert.equal(await running, 200);+ assert.equal(pool.state, 'closed');+ await until('the worker to exit', () => pool.workers === 0);+ },+ },+ {+ name: 'pool: the worker count is bounded and a pool with no workers still gets one',+ async run(addon) {+ const one = new addon.Pool(0);+ assert.equal(one.workers, 1);+ assert.equal(await one.blockFor(1), 1);+ await one.shutdown(1000);+ const capped = new addon.Pool(100_000);+ assert.equal(capped.workers, 256);+ await capped.shutdown(1000);+ await until('the capped workers to exit', () => capped.workers === 0);+ },+ },+ {+ name: 'pool: a pool collected without shutdown stops its workers',+ async run(addon) {+ const collect = (globalThis as { Bun?: { gc(full: boolean): void } }).Bun?.gc;+ assert.ok(collect, 'this case runs under Bun, which can force a collection');+ const before = addon.liveWorkers();+ (() => {+ for (let i = 0; i < 8; i++) new addon.Pool(2);+ })();+ assert.equal(addon.liveWorkers(), before + 16);+ await until(+ 'the collected pools to stop their workers',+ () => {+ collect(true);+ return addon.liveWorkers() <= before;+ },+ 10_000,+ );+ },+ },+ {+ name: 'typed arrays: a view of a SharedArrayBuffer is refused by every entry point',+ async run(addon) {+ const shared = new Float32Array(new SharedArrayBuffer(12));+ shared.set([1, 2, 3]);+ const pool = new addon.Pool(1);+ const calls: Array<[string, () => unknown]> = [+ ['sumF32', () => addon.sumF32(shared)],+ ['scaleF32', () => addon.scaleF32(shared, 2)],+ ['scaleInPlaceF32', () => addon.scaleInPlaceF32(shared, 2)],+ ['pool.sumF32', () => pool.sumF32(shared)],+ ['pool.scaleF32', () => pool.scaleF32(shared, 2)],+ ];+ for (const [name, call] of calls) {+ const error = thrown(call);+ assert.equal(error.code, 'InvalidArg', `${name} code`);+ assert.match(error.message, /SharedArrayBuffer/, `${name} message`);+ }+ assert.deepEqual([...shared], [1, 2, 3], 'nothing wrote into the shared memory');+ assert.equal(addon.sumF32(new Float32Array([1, 2, 3])), 6, 'a plain array still works');+ assert.equal(await pool.sumF32(new Float32Array([2])), 2);+ await pool.shutdown(1000);+ },+ },+ {+ // The refusal above asks the runtime whether the buffer is a plain ArrayBuffer+ // (napi_is_arraybuffer), which reads the engine's own record of the buffer, not JavaScript+ // state. Hiding the global constructor or swapping the prototype must not change the answer.+ name: 'typed arrays: shared memory is refused even with SharedArrayBuffer hidden or a swapped prototype',+ async run(addon) {+ const realShared = globalThis.SharedArrayBuffer;+ const shared = new Float32Array(new realShared(12));+ shared.set([1, 2, 3]);+ const swapped = new Float32Array(new realShared(12));+ swapped.set([1, 2, 3]);+ Object.setPrototypeOf(swapped.buffer, ArrayBuffer.prototype);+ const pool = new addon.Pool(1);+ try {+ // @ts-expect-error hiding the global on purpose+ globalThis.SharedArrayBuffer = undefined;+ for (const [label, values] of [['hidden constructor', shared], ['swapped prototype', swapped]] as const) {+ const calls: Array<[string, () => unknown]> = [+ ['sumF32', () => addon.sumF32(values)],+ ['scaleF32', () => addon.scaleF32(values, 2)],+ ['scaleInPlaceF32', () => addon.scaleInPlaceF32(values, 2)],+ ['pool.sumF32', () => pool.sumF32(values)],+ ['pool.scaleF32', () => pool.scaleF32(values, 2)],+ ];+ for (const [name, call] of calls) {+ assert.equal(thrown(call).code, 'InvalidArg', `${label}: ${name} refuses`);+ }+ assert.deepEqual([...values], [1, 2, 3], `${label}: memory untouched`);+ }+ } finally {+ globalThis.SharedArrayBuffer = realShared;+ await pool.shutdown(1000);+ }+ },+ },+ {+ name: 'sink: a full queue says queue_full, closing says closing, nothing is lost',+ async run(addon) {+ assert.equal(addon.sinkMaxQueueSize, 4);+ const received: number[] = [];+ const sink = new addon.Sink(value => received.push(value));+ // Synchronous emits cannot drain between calls, so the fifth must be refused.+ const statuses = [0, 1, 2, 3, 4, 5, 6, 7].map(n => sink.emit(n));+ assert.deepEqual(statuses.slice(0, 4), ['ok', 'ok', 'ok', 'ok']);+ assert.ok(statuses.slice(4).every(status => status === 'queue_full'), statuses.join(','));+ await sleep(50);+ assert.deepEqual(received, [0, 1, 2, 3], 'every ok value was delivered, in order');++ // From a Rust thread the same rule holds.+ const before = received.length;+ const fromThread = await sink.emitFromThread(50);+ assert.ok(fromThread.every(status => status === 'ok' || status === 'queue_full'));+ await sleep(50);+ assert.equal(received.length - before, fromThread.filter(status => status === 'ok').length);++ sink.close();+ assert.equal(sink.emit(9), 'closing');+ assert.deepEqual(await sink.emitFromThread(2), ['closing', 'closing']);+ await sleep(20);+ },+ },+];++/** The cases that make sense inside a compiled executable (everything in-process and quick). */+export const compiledCases: Case[] = cases.filter(c =>+ /^(metadata|typed arrays|panics|cancellation|shutdown: queued|sink)/.test(c.name),+);diff --git a/rust/smoke/exit-child.ts b/rust/smoke/exit-child.tsnew file mode 100644index 0000000000..800fc248ff--- /dev/null+++ b/rust/smoke/exit-child.ts@@ -0,0 +1,27 @@+/**+ * Child process for the exit proofs, started by run.ts.+ *+ * exit start long native tasks, then call process.exit(0) while they run+ * natural start long native tasks and let the event loop finish by itself+ *+ * Prints "ready" once the tasks are running. In `exit` mode the process must end at once with code+ * 0. In `natural` mode, run.ts records whether and when it ends; that is a measurement, not a+ * pass/fail gate.+ */+import { loadAddon } from './addon.ts';++const mode = process.argv[2];+const addon = loadAddon();+const pool = new addon.Pool(2);+const received: number[] = [];+const sink = new addon.Sink(value => received.push(value));++// Never awaited: these are still running when the process leaves.+pool.blockFor(5000).catch(() => {});+pool.blockFor(5000).catch(() => {});+pool.blockFor(5000).catch(() => {}); // queued behind the two running tasks+void sink.emitFromThread(100);++await new Promise(resolve => setTimeout(resolve, 100));+console.log(`ready running=${pool.running} queued=${pool.queued}`);+if (mode === 'exit') process.exit(0);diff --git a/rust/smoke/run.ts b/rust/smoke/run.tsnew file mode 100644index 0000000000..20b1d7f7ed--- /dev/null+++ b/rust/smoke/run.ts@@ -0,0 +1,140 @@+#!/usr/bin/env bun+/**+ * The Rust engine addon smoke test. A standalone script on purpose: it is not a `bun test`+ * file, so the repo's test preloads cannot strip GBRAIN_RUST_ENGINE_ADDON.+ *+ * bun run rust:build+ * export GBRAIN_RUST_ENGINE_ADDON=<path printed by the build>+ * bun rust/smoke/run.ts+ *+ * It runs every case in cases.ts, then three process-level checks:+ * 1. a child process leaves with process.exit(0) while native tasks run (must exit 0, fast);+ * 2. the same child left to exit naturally (measured and reported, not a pass/fail gate);+ * 3. a `bun build --compile` executable loads the addon and passes its self-check.+ * Exit code 0 means every check passed.+ */+import assert from 'node:assert/strict';+import { mkdirSync, rmSync } from 'node:fs';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath } from 'node:url';+import { loadAddon } from './addon.ts';+import { cases } from './cases.ts';++const smokeDir = dirname(fileURLToPath(import.meta.url));+const addonPath = process.env.GBRAIN_RUST_ENGINE_ADDON;+if (!addonPath) {+ console.error('GBRAIN_RUST_ENGINE_ADDON is not set. Run `bun run rust:build` and export the path it prints.');+ process.exit(2);+}+const absoluteAddon = resolve(addonPath);++interface Outcome {+ name: string;+ ok: boolean;+ detail?: string;+}+const outcomes: Outcome[] = [];++async function check(name: string, body: () => Promise<void> | void): Promise<void> {+ const startedAt = performance.now();+ try {+ await body();+ outcomes.push({ name, ok: true });+ console.log(` ok ${name} (${(performance.now() - startedAt).toFixed(0)} ms)`);+ } catch (error) {+ const detail = error instanceof Error ? error.message : String(error);+ outcomes.push({ name, ok: false, detail });+ console.log(` FAIL ${name}\n ${detail.split('\n').join('\n ')}`);+ }+}++interface ChildResult {+ exitCode: number | null;+ signal: string | null;+ timedOut: boolean;+ ms: number;+ stdout: string;+ stderr: string;+}++async function runChild(cmd: string[], timeoutMs: number): Promise<ChildResult> {+ const startedAt = performance.now();+ const child = Bun.spawn(cmd, {+ cwd: smokeDir,+ env: { ...process.env, GBRAIN_RUST_ENGINE_ADDON: absoluteAddon },+ stdout: 'pipe',+ stderr: 'pipe',+ });+ let timedOut = false;+ const timer = setTimeout(() => {+ timedOut = true;+ child.kill('SIGKILL');+ }, timeoutMs);+ const [stdout, stderr] = await Promise.all([+ new Response(child.stdout).text(),+ new Response(child.stderr).text(),+ ]);+ await child.exited;+ clearTimeout(timer);+ return {+ exitCode: child.exitCode,+ signal: child.signalCode,+ timedOut,+ ms: performance.now() - startedAt,+ stdout,+ stderr,+ };+}++console.log(`addon: ${absoluteAddon}`);+console.log(`bun: ${Bun.version}`);+const addon = loadAddon(absoluteAddon);+console.log(`target ${addon.target}, abi ${addon.engineAbi}, build ${addon.engineBuild.slice(0, 12)}\n`);++console.log('in-process cases');+for (const testCase of cases) {+ await check(testCase.name, () => testCase.run(addon));+}++console.log('\nprocess-level checks');+await check('process.exit(0) while native tasks are running exits 0 without a crash', async () => {+ const result = await runChild([process.execPath, 'exit-child.ts', 'exit'], 20_000);+ assert.equal(result.timedOut, false, 'the child hung after process.exit(0)');+ assert.equal(result.exitCode, 0, `exit code ${result.exitCode}, signal ${result.signal}\n${result.stderr}`);+ assert.match(result.stdout, /ready running=2 queued=1/);+ assert.doesNotMatch(result.stderr, /panic|segmentation|crash|abort/i, result.stderr);+ // Native tasks run for 5 s; leaving while they run must not wait for them.+ assert.ok(result.ms < 4000, `child took ${result.ms.toFixed(0)} ms to exit`);+});++let naturalExit = 'not measured';+await check('natural exit with pending native tasks (measured, not a gate)', async () => {+ const result = await runChild([process.execPath, 'exit-child.ts', 'natural'], 25_000);+ assert.doesNotMatch(result.stderr, /panic|segmentation|crash/i, result.stderr);+ naturalExit = result.timedOut+ ? 'HUNG: still alive after 25 s and was killed'+ : `exited with code ${result.exitCode} after ${(result.ms / 1000).toFixed(1)} s ` ++ '(tasks were set to run 5 s, queued one 10 s)';+ console.log(` ${naturalExit}`);+});++await check('a bun build --compile executable loads the addon and passes its self-check', async () => {+ const outDir = join(smokeDir, '..', 'target', 'smoke');+ rmSync(outDir, { recursive: true, force: true });+ mkdirSync(outDir, { recursive: true });+ const exe = join(outDir, process.platform === 'win32' ? 'selfcheck.exe' : 'selfcheck');+ const compile = Bun.spawnSync(+ [process.execPath, 'build', '--compile', '--no-compile-autoload-bunfig', join(smokeDir, 'selfcheck.ts'), '--outfile', exe],+ { stdout: 'pipe', stderr: 'pipe' },+ );+ assert.equal(compile.exitCode, 0, `compile failed:\n${compile.stderr.toString()}`);+ const result = await runChild([exe], 60_000);+ assert.equal(result.timedOut, false, 'the compiled executable hung');+ assert.equal(result.exitCode, 0, `exit ${result.exitCode}\n${result.stdout}\n${result.stderr}`);+ assert.match(result.stdout, /selfcheck ok: \d+ cases/);+ rmSync(outDir, { recursive: true, force: true });+});++const failed = outcomes.filter(o => !o.ok);+console.log(`\n${outcomes.length - failed.length}/${outcomes.length} checks passed. Natural exit: ${naturalExit}`);+process.exit(failed.length === 0 ? 0 : 1);diff --git a/rust/smoke/selfcheck.ts b/rust/smoke/selfcheck.tsnew file mode 100644index 0000000000..5d295feadb--- /dev/null+++ b/rust/smoke/selfcheck.ts@@ -0,0 +1,21 @@+/**+ * Compiled by `bun build --compile --no-compile-autoload-bunfig` and run by run.ts. It proves a+ * single-file executable can load the addon with process.dlopen from a path given at run time,+ * and that the main behaviors work there too.+ */+import { loadAddon } from './addon.ts';+import { compiledCases } from './cases.ts';++const addon = loadAddon();+let failed = 0;+for (const testCase of compiledCases) {+ try {+ await testCase.run(addon);+ } catch (error) {+ failed++;+ console.error(`FAIL ${testCase.name}\n${error instanceof Error ? error.message : String(error)}`);+ }+}+if (failed > 0) process.exit(1);+console.log(`selfcheck ok: ${compiledCases.length} cases, target ${addon.target}`);+process.exit(0);diff --git a/rust/smoke/smoke.test.ts b/rust/smoke/smoke.test.tsnew file mode 100644index 0000000000..7a961bde1f--- /dev/null+++ b/rust/smoke/smoke.test.ts@@ -0,0 +1,76 @@+/**+ * The /ship test lane for the Rust addon's Bun-side files (rust/scripts/build.ts and rust/smoke/*).+ * It lives outside test/ on purpose: the unit runner only collects test/, so machines with no Rust+ * never run it. It builds the addon and runs the smoke script as child processes, the same two+ * commands the rust-engine.yml addon job runs. It needs cargo and fails, never skips, without it.+ */+import { describe, expect, test } from 'bun:test';+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';++const repo = resolve(import.meta.dir, '../..');++function run(args: string[], env: Record<string, string | undefined>) {+ const result = Bun.spawnSync(args, { cwd: repo, env, stdout: 'pipe', stderr: 'pipe' });+ return { code: result.exitCode, out: `${result.stdout.toString()}${result.stderr.toString()}` };+}++describe('rust addon smoke', () => {+ test('the addon builds and every smoke check passes', () => {+ const build = run([process.execPath, 'rust/scripts/build.ts'], { ...process.env });+ expect(build.out).toContain('Built ');+ expect(build.code).toBe(0);+ const addon = /export GBRAIN_RUST_ENGINE_ADDON=(\S+)/.exec(build.out)?.[1];+ expect(addon).toBeDefined();+ const smoke = run([process.execPath, join('rust', 'smoke', 'run.ts')], {+ ...process.env,+ GBRAIN_RUST_ENGINE_ADDON: addon,+ });+ if (smoke.code !== 0) console.error(smoke.out);+ expect(smoke.code).toBe(0);+ }, 900_000);++ test('a CARGO_TARGET_DIR setting does not make the build package an older library', () => {+ const elsewhere = mkdtempSync(join(tmpdir(), 'gbrain-cargo-target-'));+ try {+ const build = run([process.execPath, 'rust/scripts/build.ts'], { ...process.env, CARGO_TARGET_DIR: elsewhere });+ expect(build.code).toBe(0);+ // The build went to rust/target, the directory the script copies from, not to the setting.+ expect(existsSync(join(elsewhere, 'release'))).toBe(false);+ } finally {+ rmSync(elsewhere, { recursive: true, force: true });+ }+ }, 900_000);++ test('a configured build target does not make the build package an older library', () => {+ // CARGO_BUILD_TARGET (or build.target) moves cargo's output to target/<triple>/release, even+ // for the host triple. A sentinel left in target/release must never become the addon.+ const host = /^host: (\S+)$/m.exec(run(['rustc', '-vV'], { ...process.env }).out)?.[1];+ expect(host).toBeDefined();+ const library = process.platform === 'darwin' ? 'libgbrain_napi.dylib' : 'libgbrain_napi.so';+ const releaseDir = join(repo, 'rust', 'target', 'release');+ const seeded = join(releaseDir, library);+ const saved = `${seeded}.smoke-saved`;+ const hadLibrary = existsSync(seeded);+ mkdirSync(releaseDir, { recursive: true });+ if (hadLibrary) renameSync(seeded, saved);+ const sentinel = 'stale library left by an earlier default-target build';+ writeFileSync(seeded, sentinel);+ try {+ const build = run([process.execPath, 'rust/scripts/build.ts'], { ...process.env, CARGO_BUILD_TARGET: host });+ if (build.code !== 0) console.error(build.out);+ expect(build.code).toBe(0);+ const addon = /export GBRAIN_RUST_ENGINE_ADDON=(\S+)/.exec(build.out)?.[1];+ expect(addon).toBeDefined();+ expect(readFileSync(addon!).toString('latin1')).not.toBe(sentinel);+ expect(readFileSync(addon!).equals(readFileSync(join(repo, 'rust', 'target', host!, 'release', library)))).toBe(true);+ } finally {+ rmSync(seeded, { force: true });+ if (hadLibrary) {+ copyFileSync(saved, seeded);+ rmSync(saved, { force: true });+ }+ }+ }, 900_000);+});diff --git a/scripts/check-orphan-modules.mjs b/scripts/check-orphan-modules.mjsindex 8715fa2d05..409b8d846b 100644--- a/scripts/check-orphan-modules.mjs+++ b/scripts/check-orphan-modules.mjs@@ -54,6 +54,12 @@ const ALLOWLIST = new Map([// reason 'script-reachable', which the guard verifies.const PERMITTED_TEST_ONLY = [{ path: 'src/core/bootstrap/template-repo.ts', reason: 'script-reachable' },+ { path: 'src/core/rust-engine.ts', reason: "held: the Rust engine shell (plan PR 8, docs/designs/RUST_ENGINE.md); the addon loader PR on rust-engine/core wires openRustEngine into engine construction" },+ { path: 'src/core/rust-engine/members.ts', reason: 'held: the Rust engine shell member table; reached through src/core/rust-engine.ts once the addon loader wires openRustEngine' },+ { path: 'src/core/rust-engine/addon-errors.ts', reason: 'held: the Rust engine addon loader (loadRustEngineAddon); the addon release PR wires it into engine construction with the rust config value' },+ { path: 'src/core/rust-engine/addon-loader.ts', reason: 'held: the Rust engine addon loader (loadRustEngineAddon); the addon release PR wires it into engine construction with the rust config value' },+ { path: 'src/core/rust-engine/addon-manifest.ts', reason: 'held: the Rust engine addon loader (loadRustEngineAddon); the addon release PR wires it into engine construction with the rust config value' },+ { path: 'src/core/rust-engine/addon-target.ts', reason: 'held: the Rust engine addon loader (loadRustEngineAddon); the addon release PR wires it into engine construction with the rust config value' },{ path: 'src/eval/longmemeval/diagnostics.ts', reason: 'script-reachable' },{ path: 'src/eval/longmemeval/evidence-brief.ts', reason: 'held: eval-only wave 1 brief builder (10x memory advantage plan A3), loaded by path from gbrain-evals eval/runner/pilot; product wiring is plan item A8, conditional on the A5 pilot' },{ path: 'src/eval/longmemeval/evidence-packet.ts', reason: 'script-reachable' },diff --git a/scripts/check-relative-dotdot.mjs b/scripts/check-relative-dotdot.mjsindex cc6813941a..3cc00f7438 100644--- a/scripts/check-relative-dotdot.mjs+++ b/scripts/check-relative-dotdot.mjs@@ -32,9 +32,7 @@ const OPT_OUT = 'gbrain-allow-dotdot-prefix';// Temporary exception, paths relative to the scan root. Remove each entry when// its condition holds; a stale entry prints a note so the removal is not missed.-const TEMPORARY = new Map([- ['core/ops/context.ts', 'validateUploadPath; fixed by PR #9570 (garrytan/gbrain), remove this entry when either PR lands second'],-]);+const TEMPORARY = new Map([]);function walk(dir, out) {for (const name of readdirSync(dir)) {diff --git a/scripts/core-world-reads-baseline.tsv b/scripts/core-world-reads-baseline.tsvindex 8818aaaa3e..e8c730f496 100644--- a/scripts/core-world-reads-baseline.tsv+++ b/scripts/core-world-reads-baseline.tsv@@ -910,6 +910,8 @@ src/core/retry.ts process_env 1 W6: settings plane out of the coresrc/core/routing-eval.ts fs_import 1 W7: filesystem boundary moves to the local appsrc/core/runtime-build.ts fs_import 1 W7: filesystem boundary moves to the local appsrc/core/runtime-version.ts process_global 2 W7: process-wide effects move to src/cli+src/core/rust-engine/addon-loader.ts fs_import 1 Rust engine addon: reads the cached manifest and checks the cached addon file under GBRAIN_HOME/engines/rust (writes nothing); stays until the Rust engine's own storage settles (plan PR 8)+src/core/rust-engine/addon-loader.ts process_env 1 Rust engine addon: the default deps read GBRAIN_RUST_ENGINE_ADDON once; every other path takes env from the deps; stays until the Rust engine's own storage settles (plan PR 8)src/core/schema-events.ts fs_import 1 W7: filesystem boundary moves to the local appsrc/core/schema-migration-lock.ts als_store 1 stays: GBRA-467 reentrancy scope of the schema migration lock held by this process (coordination state, not a setting)src/core/schema-migration-lock.ts module_collection 1 stays: GBRA-467 per-engine in-process queue for engines without a cross-process schema lock (PGLite); coordination state, not a settingdiff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex 2c0c0ccf81..1ad145049b 100644--- a/scripts/module-size-limits.tsv+++ b/scripts/module-size-limits.tsv@@ -6,7 +6,7 @@src/cli/main.ts 2882 ratchet +32 GST-2476 G2: enforced member gate call, static-help fallback, socket and delegate skips, read/write dispatch seams and receipt recording (logic in cli/enforced-member.ts); +3 GBRA-156: thin-client page-cap line on stderr in formatResult (import and two lines; +1 #7619: the --flag=value gate call after the handler-free help printers, covering the hand-parsed search subcommands and the exact-token validation-exempt paths (logic, findUnknownFlag included, in cli/flag-equals.ts); +1 W1 belief ledger: `gbrain beliefs --help` in SELF_HELP_WITHOUT_ENGINE; +1 Cat 41 run 4: recall's SELF_HELP_WITHOUT_ENGINE table entry (a dispatch table row cannot move); moved from src/cli.ts at 3214 (cold start: src/cli.ts is now the 66-line entry with the --version/help fast path; the top-level help text moved to cli/top-help.ts and the exit seam became runCli/exitOnFatalCliError); +2 #6340: the sync status / sync unblock preflight skip (logic in commands/sync/operator.ts); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +2 retrieval feedback: answer id line on stderr and additive answer_id on --json search/query rows (logic in feedback/record.ts); +1 feedback help line and its D3 table-dispatch entry (logic in commands/feedback.ts); 6 engine graduation (GBRA-50 G3): migrate pre-connect route (logic in commands/migrate-graduation.ts), serve start refusal and degraded-reconnect identity gate (logic in persistence/graduation-serve-guard.ts), usage line; +3 engine graduation (GBRA-50 G2a): connect-path graduation check on every engine (logic in persistence/graduation-custody.ts assertGraduationConnectAllowed); P3 x engine graduation composition: both deltas re-summed at the merge; 1 Foundations 2 Lane F: sources refresh pre-connect delegation to a resident PGLite owner (logic in commands/sources-refresh-delegate.ts); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +6 engine graduation (GBRA-50 G3): migrate pre-connect route (logic in commands/migrate-graduation.ts), serve start refusal and degraded-reconnect identity gate (logic in persistence/graduation-serve-guard.ts), usage line; +3 engine graduation (GBRA-50 G2a): connect-path graduation check on every engine (logic in persistence/graduation-custody.ts assertGraduationConnectAllowed); P3 x foundations-2 composition: deltas re-summed at the merge; 1 Foundations 2 Lane F: sources refresh pre-connect delegation to a resident PGLite owner (logic in commands/sources-refresh-delegate.ts); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +6 engine graduation (GBRA-50 G3): migrate pre-connect route (logic in commands/migrate-graduation.ts), serve start refusal and degraded-reconnect identity gate (logic in persistence/graduation-serve-guard.ts), usage line; +3 engine graduation (GBRA-50 G2a): connect-path graduation check on every engine (logic in persistence/graduation-custody.ts assertGraduationConnectAllowed); GBRA-49: edge-proposals answers --help without a brain (SELF_HELP_WITHOUT_ENGINE row); P3 x P1 (v0.60.57.0) composition: deltas re-summed at the merge; 1 Foundations 2 Lane F: sources refresh pre-connect delegation to a resident PGLite owner (logic in commands/sources-refresh-delegate.ts); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +6 engine graduation (GBRA-50 G3): migrate pre-connect route (logic in commands/migrate-graduation.ts), serve start refusal and degraded-reconnect identity gate (logic in persistence/graduation-serve-guard.ts), usage line; +3 engine graduation (GBRA-50 G2a): connect-path graduation check on every engine (logic in persistence/graduation-custody.ts assertGraduationConnectAllowed); GBRA-49: edge-proposals answers --help without a brain (SELF_HELP_WITHOUT_ENGINE row); -25 agent-operator follow-up Item 3: the host connect moved to core/engine-connect.ts (throw-only connectEngineForServe, wrapped by connectEngine; the graduation connect gate moved with it); 1 Foundations 2 Lane F: sources refresh pre-connect delegation to a resident PGLite owner (logic in commands/sources-refresh-delegate.ts); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +3 agent operator gate fixes: repair-failed connect wrapper (logic in cli/cli-error.ts exitOnRepairFailed), transcripts recent through a live serve (logic in commands/transcripts.ts), pre-connect status reason (logic in commands/serve-status.ts); +23 merged from the collector (Lanes B/E/F: thin-client token reason, status-only serve hand-off, jobs/sync readiness wiring); +9 agent operator wave D3/D4: curated --help short-circuit (renderer in cli/help/render.ts), curated flag-value validation call (cli/help/validate.ts), table-dispatched SELF_HELP_WITHOUT_ENGINE entries for the selfHelp flips; +5 agent operator wave C10 (merged from the collector): serve --fail-fast in the connect-failure path; +31 #5950 (D6): connectEngine thin-client backstop, engine-free MCP-twin dispatch, recall/advisor/export refusal hints, refusal fix subcommand (lowered to 3131 by D1's renderCliError seam first); +2 agent operator wave A4: observational startup (probe-only connect for startup:observational commands; completeEngineStartup split out of connectEngine, exposed as ctx.completeStartup); +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5232: write-wait import, reporter-owned verdict in the op catch, thin-client writeWaitMs, ctx.writeWaitMs (logic in persistence/write-wait.ts); +1 #4768: serve --access help line; +4 #5433: list_pages TSV cell escaping in formatResult; +2 #lane-h pricing: help line + thin-client refusal hint for `gbrain pricing`; +2 fix wave 5 (#5401): projections drain help line and thin-client hint; +2 (#5137) key-shadow warning seam, logic in ai/key-warnings.ts; +2 System One v1: decide help line + thin-client refusal hint; refactor wave 1 split target (W4 cli); ceiling rationale: docs/architecture/key-files/entrypoints-and-docs.md entry for src/cli.ts; evidence delivery: thin-client return_unit version-skew warning (+3; logic in search/evidence-delivery.ts); put stdin recovery (#5700): stdin hint in the --content requires-a-value error and stdin usage/required text in printOpHelp (+7); logic in persistence/deactivation.ts); +36 #5827: link-command help examples, local --source vs --source-id/--all-sources conflict check, ambient-binding return from applyThinClientSourceScope (logic in cli/source-scope.ts); +4 #5433: list_pages TSV cell escaping in formatResult; +1 #5984: a strict run deadline when no progress window is set; v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (3199 measured); +6 engine graduation (GBRA-50 G3): migrate pre-connect route (logic in commands/migrate-graduation.ts), serve start refusal and degraded-reconnect identity gate (logic in persistence/graduation-serve-guard.ts), usage line; +3 engine graduation (GBRA-50 G2a): connect-path graduation check on every engine (logic in persistence/graduation-custody.ts assertGraduationConnectAllowed); GBRA-49: edge-proposals answers --help without a brain (SELF_HELP_WITHOUT_ENGINE row); -25 agent-operator follow-up Item 3: the host connect moved to core/engine-connect.ts (throw-only connectEngineForServe, wrapped by connectEngine; the graduation connect gate moved with it); +2 entity recall: the human `gbrain entity` card prints referenced_by groups and a non-complete mention coverage; cat40 entity wave merge with v0.60.61.0 (3179 measured); +3 #4772 (W14 PR3): get_health text output says the entity ratios are n/a because the schema pack did not load (entity_types_status); +1 C4: gbrain questions CLI-only dispatch row (its help line is in cli/top-help.ts); +1 #6696 (A4): a local write captures the capacity notices (one call; logic in cli/op-notices.ts captureCapacityNotices); +1 large pages A6: the stdin cap reads PAGE_MAX_BYTES from core/page-size-policy.ts; +3 Wave B PR 2: local gbrain get of a segmented page streams on the page_body_segmented refusal (logic in cli/page-render.ts streamSegmentedGet); +1 #6712 PR 3 (L7): the sync_retry_failed_deprecated notice call (logic in commands/sync/args.ts noteRetryFailedDeprecated);+1 Cat 41 run 4: recall's SELF_HELP_WITHOUT_ENGINE table entry (a dispatch table row cannot move); +1 GBRA-133 PR 2a: sync trigger through a live PGLite serve (logic in commands/sync-delegate.ts maybeTriggerThroughServe); +1 GBRA-133 PR 2a merge: master and the sync trigger serve hand-off each added a dispatch row; +1 GBRA-154 #7171: captureRetrievalNotices call after a search/query op (logic in cli/op-notices.ts); GBRA-151 operability wave x v0.60.332.0 merge: both sides added a line, re-summed (3020 measured); GBRA-151 #7147 follow-up (cold one-shot read snapshot handoff and pool cap) re-summed at the v0.60.333.0 merge (3027 measured); +1 GBRA-156 warm CLI socket: one gated dispatch call before CLI_ONLY (logic in cli/cli-socket-client.ts); -11 GBRA-156: MERGED_CONFIG_BY_ENGINE and its comment moved to core/published-config.ts (serve reads it); lowered at the v0.60.340.0 merge (3018 measured); +5 #7191: search --exact routing call (dispatch, cannot move; rule in cli/command-route.ts) and the search_exact formatter case + imports; +3 GBRA-156 warm CLI startup: page-render, volunteer and operation-load imported lazily where used, so a warm socket hit loads 169 modules instead of 709 (2955 measured); re-summed at the 0.60.484.0 merge with #7598 (2959 measured); +3 GBRA-218 local --as: the access SELF_HELP_WITHOUT_ENGINE row, the --as refusal call and the preview open (logic in cli/as-preview.ts); re-summed at the GBRA-218 merge with #7593 (2962 measured); +3 #8426: serve captures the session directory the hook launcher records (import, comment, call; logic in core/session-cwd.ts); re-summed at the train R merge with v0.60.574.0: 2965 + 2; re-summed at the memory train #8481 merge with v0.60.576.0 (2970 measured); +4 GBRA-224: the startup hook resolves the release channel and prints the one-time channel notice (logic in core/release-channel-notice.ts, core/self-upgrade.ts; fits the master ceiling at the GBRA-346 merge: master 2956 + 4 = 2960); +2 GBRA-438 PR 2: the engine-free maintain route (--schedule, --unschedule, a scheduled run beside a live serve) and its comment (logic in commands/maintain-schedule.ts); +1 GBRA-498: the --room line for a command outside the operations, which runs unchanged and says it marks nothing (logic in cli/room.ts); +1 GBRA-498: search and query render their rows from inside a --json room document (logic in cli/room.ts splitRoomDocument); +1 Wakeshift PR 2 (#8709): the thin-client hint line for wakeshift watch and accept-terms (a CLI help line cannot move); +1 Wakeshift PR 2: wakeshift emit keeps exit 0 when the brain cannot be opened (logic in commands/wakeshift.ts reportEmitConnectFailure); re-summed at the b82c23a7 (v0.60.722.0) landing merge: master 2880 + 2 = 2882src/commands/autopilot.ts 1662 ratchet refactor wave 1 split target (W4 autopilot, cut line); ceiling rationale: docs/architecture/key-files/commands-1.md entry for src/commands/autopilot.ts; +2 fix wave 5: nosemgrep justifications on the per-brain job launchctl/systemctl calls (#5195); +2 #5813: boot reconcile names attempted and running versions in log + audit; +2 #5855: Bun floor gate before the swap and the swap-refusal hold (logic in core/bun-floor.ts); +3 agent operator wave E9: --dry-run and the persistent_install consent gate before anything is written (logic in autopilot/install-consent.ts); +8 GBRA-130 C-6/A-10: the --retry-global mode row, help line and --phase value flag, and --status reading the brain-wide maintenance verdict into its JSON, text and exit code (logic in core/minions/global-maintenance-stall.ts and autopilot-retry-global.ts); +12 GBRA-133 #7003: --status grades from the daemon's heartbeat sidecar (two report fields and their doc line, the classifier's daemon input and threshold branch, the import and the showStatus read; logic in core/autopilot-heartbeat.ts)src/commands/doctor.ts 706 ratchet +2 Wave B decision #10: Check.skipped_segmented field (logic in doctor/check-fix.ts withSkippedSegmented); +19 #6696 doctor tiers: Check.elapsed_ms and DoctorReport tier/complete/unknown_sections/elapsed_ms/budget_ms fields, buildChecks/runDoctor deadline params (logic in doctor/budget.ts); +1 agent operator gate fixes: --probe consent gate (logic in doctor/probe-consent.ts); refactor wave 1 split target (W4 doctor); ceiling rationale: docs/architecture/key-files/commands-2.md entry for src/commands/doctor.ts; +4 #7142: DoctorReport.last_known_sections field and the buildChecks last-known/refresh scope params (logic in doctor/last-known.ts); +8 #7276: DoctorReport.unknown_count field and the unknown category/count lines of the text headline (scoring logic in doctor/budget.ts scoredChecks); +6 GBRA-224 W4: DoctorReport.alert field, the alert computation call and the --alert branch of runDoctor (logic in doctor/alert.ts)-src/commands/embed.ts 2306 ratchet +2 agent operator wave D2: --json failure envelope via writeCliError; lowered v0.46.26.0: embedBatchWithBackoff + retry cluster peeled to core/embed-retry.ts (core/commands layering fix); grown wave-g (#4530): per-model input-limit wiring; wave-k #3622 reimpl: --stale zero-progress failure quarantine; +29 #4668 (#4530): oversize-heal call sites in both --stale drains — kept low by peeling the healed-row remap to core/embed-oversize-heal.ts (shared with embed-stale.ts); +35 #4647 (refs #4599): per-tick timeout+abort on the single-flight lock heartbeat refresh (interval deliberately NOT unref'd); +122 refs #4599: stall-watchdog race around the drain + shared idempotent flushAndRelease + CLI stall exit mapping (watchdog machinery itself lives in core/embed-stall.ts); +12: adversarial-review hardening (healed_splits progress key + heal-tick comment); #5105: guarded derived projection preparation and read seals; #5105: conditional embedding installer wiring; archived eligibility: active-only dispatch with honest stranded-work reporting; explicit archived admission: live-source snapshots and honest refused-installation failures; +2 fw3: embed --stale --images dispatch (sweep lives in core/embed-stale-images.ts); +5 #5289: dry run reports restamp-only chunks apart from chunks to embed (count lives in core/embedding-invalidation.ts); +6 #4616: keep a partially refused batch in embedPageTexts and name the recovery command in failure samples (guard lives in core/ai/embedding-guard.ts); +5 #5226: embed summary counts distinct pages; +3 #5804: null projection snapshot counted as a failure with one batch summary in embed --stale; +18 wave 8 lane D1: #5527 mixed-space warning subtracts current-model chunks (+4), #5885 takes option/result fields and the stale-drain takes call (pass lives in core/embed-takes.ts); +9 Foundations 1 F4d: time-budget stop result fields, stdout verdict and stop recording in embed --stale (logic in core/embed-budget-stop.ts); +8 green-master lane A: chunkless install re-reads through retryProjectionConflict instead of recording an unavailable page (retry lives in core/page-state/projections.ts, failure line in core/agent-output.ts); +8 fix wave 13 P1.18: runEmbed consent parameter, cost-cap stop wiring and result fields, --slugs parsing to the next flag (cap, verdict and resume logic live in core/embed-cost-cap.ts); +28 large pages A9/T3/T16: --held listing and per-page cap metering on every embed path (logic in core/page-embedding-budget.ts meterPageBatch/spendGrant/heldEmbedArgv), approvedPageCapUsd from --max-usd on --slugs; +1 #6722: an explicit slug embed skips an embed_skip page (it keeps keyword chunks, never vectors); merge v0.60.240.0: large pages and master growth compose at 2265; +39 large pages Wave B lane 1e: segmented pages route to the keyset sweep on the slug, --all and --stale paths, with a dry-run count and provenance stamp (logic in core/page-body/segmented-embedding.ts); +2 agent operator wave D2: --json failure envelope via writeCliError+src/commands/embed.ts 2307 ratchet +2 agent operator wave D2: --json failure envelope via writeCliError; lowered v0.46.26.0: embedBatchWithBackoff + retry cluster peeled to core/embed-retry.ts (core/commands layering fix); grown wave-g (#4530): per-model input-limit wiring; wave-k #3622 reimpl: --stale zero-progress failure quarantine; +29 #4668 (#4530): oversize-heal call sites in both --stale drains — kept low by peeling the healed-row remap to core/embed-oversize-heal.ts (shared with embed-stale.ts); +35 #4647 (refs #4599): per-tick timeout+abort on the single-flight lock heartbeat refresh (interval deliberately NOT unref'd); +122 refs #4599: stall-watchdog race around the drain + shared idempotent flushAndRelease + CLI stall exit mapping (watchdog machinery itself lives in core/embed-stall.ts); +12: adversarial-review hardening (healed_splits progress key + heal-tick comment); #5105: guarded derived projection preparation and read seals; #5105: conditional embedding installer wiring; archived eligibility: active-only dispatch with honest stranded-work reporting; explicit archived admission: live-source snapshots and honest refused-installation failures; +2 fw3: embed --stale --images dispatch (sweep lives in core/embed-stale-images.ts); +5 #5289: dry run reports restamp-only chunks apart from chunks to embed (count lives in core/embedding-invalidation.ts); +6 #4616: keep a partially refused batch in embedPageTexts and name the recovery command in failure samples (guard lives in core/ai/embedding-guard.ts); +5 #5226: embed summary counts distinct pages; +3 #5804: null projection snapshot counted as a failure with one batch summary in embed --stale; +18 wave 8 lane D1: #5527 mixed-space warning subtracts current-model chunks (+4), #5885 takes option/result fields and the stale-drain takes call (pass lives in core/embed-takes.ts); +9 Foundations 1 F4d: time-budget stop result fields, stdout verdict and stop recording in embed --stale (logic in core/embed-budget-stop.ts); +8 green-master lane A: chunkless install re-reads through retryProjectionConflict instead of recording an unavailable page (retry lives in core/page-state/projections.ts, failure line in core/agent-output.ts); +8 fix wave 13 P1.18: runEmbed consent parameter, cost-cap stop wiring and result fields, --slugs parsing to the next flag (cap, verdict and resume logic live in core/embed-cost-cap.ts); +28 large pages A9/T3/T16: --held listing and per-page cap metering on every embed path (logic in core/page-embedding-budget.ts meterPageBatch/spendGrant/heldEmbedArgv), approvedPageCapUsd from --max-usd on --slugs; +1 #6722: an explicit slug embed skips an embed_skip page (it keeps keyword chunks, never vectors); merge v0.60.240.0: large pages and master growth compose at 2265; +39 large pages Wave B lane 1e: segmented pages route to the keyset sweep on the slug, --all and --stale paths, with a dry-run count and provenance stamp (logic in core/page-body/segmented-embedding.ts); +2 agent operator wave D2: --json failure envelope via writeCliError; +1 Rust engine shell (plan PR 8): sqlEngineKind import so the dimension-mismatch recipe refuses a Rust kind (logic in core/sql-engine-kind.ts)src/commands/extract-conversation-facts.ts 1957 ratchet grown v0.46.x per-provider gateway-unavailable copy; grown wave-g (#4482): expected budget/deadline caps classified apart from error halts; wave-k: save-time resolution caller (#4052/#3729 — supersedes wave-g's per-row resolveEntitySlug mapper); +1: key-aware llm-fallback default (#3813); +1: pricingOverrides wiring into the owned BudgetTracker (#4633 adoption); +3: #4869 snapshot-mismatch counts as pages_failed; merged reliability/shared-skills source integration; +19: additive skip reasons and model-free dry-run (#5364); +21 #5757: managed extraction buffers a page's rows and replaces the prior batch in one coordinator transaction (replacement helper lives in core/persistence/derived-facts.ts); +18 #5823: result diagnostics, strict explicit-cap parsing and CLI recovery/help; default-cap decision lives in facts/conversation-budget.ts; +18 fix wave 7 (#5704, #5448): --json envelope on stdout (parser flag, help line, summary block gated behind the human-output branch); +2 fix wave 10 (#6037, issue #6033): explicit-slug page failures are contained per page through one bounded failure logger (recordPageFailure) shared with the pooled path; +4 fix wave 10 (#5120): facts.default_visibility resolved once per run (resolveDefaultVisibility) and applied to extracted rows only; 2 P2 segmentObservationDate + segmentValidFrom helpers (date-grounding observation time per segment; extractor event date wins over segment start); +4: ExtractConversationFactsResult.failed_pages (interface field) and the help text exit-status paragraph; partial-success logic lives in core/facts/conversation-run-status.ts; re-summed at the master 6ccf30c3e merge (2179 master lines + 20 integration lines over base); re-summed at the #6020 merge on actual lines (as rehearsed on capy/mpw-integration-p2); re-summed at the wave 10 merge on actual lines (+1 recordPageFailure fills failed_pages); lowered at the wave-9 follow-ups merge: the three zero-result literals became emptyExtractConversationFactsResult(); lowered to 2075 at wave 15 P2.5 (#6267): segment tunables, splitIntoSegments and renderSegmentForExtraction moved to core/facts/conversation-windows.ts, the message/segment types to core/facts/conversation-types.ts (re-exported here); +12 large pages T2: the oversized-sidecar snapshot and the durable size-skip receipt (skippedForSize; the cap and the bounded sidecar read live in core/conversation-parser/body.ts, the receipt in core/extraction-watermark.ts); merge v0.60.240.0: large pages and master growth compose at 2087; -6 wave 18 lane 3 (#6731 #6764): the two extractor call sites share one input object, inference lives in core/facts/conversation-subject-infer.ts; Wave B PR 2 (kept at the master 4e29d0904 merge): +7 large pages PR 2 lane 2e2: a segmented conversation over the window cap (snapshot.window, the tail_window receipt, the window fallback date; the window read lives in core/page-body/segment-conversation.ts); +9 lane 2e2 follow-up: the lossless window rule (a page over the window with conversation facts keeps them and is skipped, the receipt names the rule; the count lives in core/facts/conversation-publication.ts); integrated at the master 4e29d0904 merge: 2097 measured; lowered to 2044 by #7013: a page's rows publish once through publishConversationFacts (core/facts/conversation-publication.ts), so the delete-first cleanup, the per-segment inserts and the row-number peek left; +1 GBRA-159: facts from a private page are private (tightenToPage per page; helper in core/facts/visibility.ts); +3 #7438: ExtractConversationFactsResult.facts_skipped_purged (interface field) and one notePurgedSkips call (the count and log live in core/facts/conversation-publication.ts); grown v0.46.x per-provider gateway-unavailable copy; re-summed at the Wave B PR 4 merge with v0.60.452.0 (1949 measured); +6 #7068: ExtractConversationFactsCoreOpts.onInterrupted (interface field and its doc) and its one call before the rethrow (the cycle keeps the committed counters in core/cycle/conversation-facts-backfill.ts); +2 GBRA-574 B2: the --dry-run paid-run estimate (one call and one print; the estimate and its line live in core/facts/conversation-budget.ts)src/commands/extract.ts 2702 ratchet +8 GBRA-130 A-1: extract --stale --retry-held flag, help lines and the managed result failure fields (logic in core/persistence/links-maintenance.ts and links-extraction-holds.ts); grown v0.46.26.0 megawave: FS-walk stamp snapshot + legacy timeline repair wiring (#3957 D4) + PR#4486 rebase onto current master; grown wave-g (#4542): --from-meetings zero-match warning + default-pass note; +29: #3478 federated-only gate on the cross-source 'default' link fallback; +44: #3908 cross_source opt-in — counted drops + deterministic cross-source pick; +36: #4611 configured-sources.default fallback (resolveLinkFallbackDefault); +14: #4890 extractStaleFromDB quiet opt + extractForSlugs jsonMode batch_error stderr fallback; +5: #4855 stroke-letter fold in link extraction; +5: #4793 by-mention scan honours link_resolution.cross_source; +18: wave review — ExtractOpts.quiet threaded through the fs-walk extractors (stdout silence decoupled from jsonMode); +77: shared buildSlugPathIndex — every per-slug extractor resolves the real on-disk path, and the sync hooks report which slugs they actually read; +10 #4999: includeFrontmatter default-resolved inside extractLinksForSlugs + extractStaleFromDB (resolveIncludeFrontmatter), --stale flag absent -> configured knob; +20: pre-landing review of #4967 — resolveSlugRelPath: index miss falls back to the legacy slug+'.md' path so admitted _-prefixed / include_hidden pages keep their edges; T2: source-qualified inference and atomic origin-scoped derived links; standard DB extraction fences captured endpoint revisions; shared authoritative attendance/source reconciliation moved to the core module; +7 A2 preview-bound attendance repair import, help and authority dispatch; bounded incomplete-attendance diagnostics and consistent basename resolution; fail closed before graph mutation when active ontology is unavailable; +16 source-selected ontology cache, type-scoped preflight and non-starving failed stale drain; +7 write-path wave: per-slug extractors replace page links + retract removed timeline rows + rename-alias resolution; +5 fw3 derived-sync: timeline --prune-orphans CLI (#4649) and full-walk page link replacement; +13 fw3 A16/A15: sync link hook reads scoped page metadata and reports per-page extraction errors; +1 fw3 managed-lifecycle: extract --stale dispatches managed brains to the coordinator-safe path; +4 fw3 integration: managed brains refuse the direct timeline orphan prune; +26 #5609: managed extract --stale publishes links, canonical timeline and watermark per page in one coordinated transaction; fix wave 3 x fix wave 2 (v0.60.5.0) composition: +4 at the merge; +6 fix wave 3 lane B: a managed brain routes the extract phase file walk through extractManagedStaleLinks instead of the refused raw timeline batch, keeping the extract.links_fs progress phase; +6 #5761: the unmanaged extract --stale sweep marks unresolved-attendance skips attendance-blocked; +2 eval-wave N9-3/N12-7: a page-type-bound pack attended rule defers to canonical attendance on the filesystem path (ownsAttendanceInference); lowered to 2528 #5904: the DB timeline walk moved to commands/extract-timeline-db.ts (coordinated publication on managed brains, honest refusal + non-zero exit); +13 entity mention index: extract --stale runs the mention pass after link work (half the budget reserved while mention-due pages exist), dry-run and JSON report mention counts, and the help documents the pass and `extract mentions --explain` (logic in core/mentions/); cat40 entity wave merge with v0.60.61.0 (2541 measured); +6 fix wave 10 lane L1 #5556: quarantined pages skipped by the file walks, slug lists and DB walks (slug lookup in quarantine.ts quarantinedSlugs); +3 #5556: the abort check stays its own statement in each quarantine-aware scan loop (cycle-abort coverage pin); 2 P5 wanted pages: both DB extract paths record unresolved authored refs with each page's links; +5 P5 line grammar: stated relation types on the filesystem link scan; +3 PGLite stale link drains refresh planner statistics before and during the drain (logic in planner-stats.ts plannerStatsForLinkDrain); +10 fix wave 12 W2.1 S4 (#6228): extract --stale flushes and stamps the pages a batch finished before an aborting page; +12 P5 wanted pages: both DB extract paths record unresolved authored refs with each page's links; +9 Q2 parser gaps: both DB extract paths read the line-grammar settings once, publish through replaceDerivedLinksUnlessSettingsChanged and report pages a mid-run settings change left stale; +25 GBRA-69: extract --source db reads snapshots and publishes derived links BATCH_SIZE pages at a time (readPageSnapshotsBatch in core/page-snapshot-batch.ts, replay in derived-links.ts replaceDerivedLinksBatchOrReplay); +2 GBRA-75 w7: the --source db links walk refreshes planner statistics (logic in planner-stats.ts plannerStatsForLinkDrain); +10 fix wave 13 P2.16 (#6272): both unmanaged DB link drains defer and count a page a concurrent writer moved (skipped_concurrent_write) instead of aborting the run (classifier and skip line in core/derived-links.ts); +3 fix wave 13 P2.18 (S4): extract all --source db stamps the pages both phases completed at one revision, in a finally (stampCompletedIntersection), instead of every links-phase page; +1 fix wave 13 P2.15 (#6273): --from-meetings exits non-zero while managed entity pages are still pending; +7 fix wave 13 PR2: extractFromDB split out of runExtract so runExtract stays under its function-size baseline; Wave B PR 2 (kept at the master 4e29d0904 merge): +3 PR 2 fix lane J1: extract --stale reads a segmented page block by block (extractSegmentedPageLinks, segmentedTimelineText) now that the stale list includes it; integrated at the master 4e29d0904 merge: 2635 measured; +23 fix wave 20 #6954: the fs walks and the slug-scoped extract collect lost link/timeline writes, stamp only the pages whose writes landed and throw extract_write_lost (helpers in core/extract-watermark.ts); fix wave 20 integration: lane 1 (#6808, +11) and lane 2 (#6954, +23) compose at 2677 measured; +16 #7394: --type/--since/--infer-dates on the file walk refuse with the --source db command beside the other --source db refusals, and the help says so; +5 GBRA-161 PR 5 (T-2, L-6): timeline retraction and the mention rebuild sweep are bound to the revision they read (PageRevisionConflictError import, the scanned-revision read and its FOR SHARE check); +2 GBRA-133: ExtractOpts.timeBudgetMs, forwarded to the managed stale-page pass so the cycle bounds a pass with no slug list; +1 #9295: the stale sweep counts only the wanted-link producers it re-resolves (wantedProducers; SQL in engine-sql/pages.ts); +1 GBRA-438 PR 2: the mention pass gets no deadline budget once the cycle signal has aborted, so idle upkeep stops at the next requestsrc/commands/jobs.ts 693 ratchet refactor wave 1 split target (W4 jobs, cut line); ceiling rationale: docs/architecture/key-files/commands-4.md entry for src/commands/jobs.ts; help lines: authorize-legacy --select (#5157 T3) and jobs cancel --select (DX-T2); submit --queue-only + PGLite work drain note (agent-first operator wave E5); +2 spend authorization: jobs submit --yes/--max-usd and jobs list --group help lines; +4 fix wave 9: supervisor stop help documents the 45 s wait, --queue and the verified-drain exit codes; +1 #7142: doctor-refresh handler registration (logic in doctor/last-known.ts); +20 #7242 jobs wait: subcommand row, import, usage lines and its --help text with the exit codes (logic in jobs/wait.ts); +6 GBRA-283 B3a: runJobs enters the local scope (withLocalScope; scope store in core/engine-scope-store.ts), the entry wrapper and its import cannot move@@ -16,12 +16,12 @@ src/commands/sync.ts 568 ratchet refactor wave 1 split target (W4 sync); ceilingsrc/core/cycle.ts 3357 ratchet +2 GBRA-130 C-2 (#6946): the sync phase reads an owned clone's pull block and reports it as pull_blocked (logic in url-clone.ts urlClonePullBlock/urlClonePullBlockSummary); +6 GBRA-130 A-1: the extract phase warns on failed or breaker-stopped stale drain pages (logic in cycle/connector-extract.ts staleDrainFailures); +1 W1 belief ledger: the extract phase runs the sampled belief drift reconcile (logic in belief/coverage-report.ts); +2 System One v1 S9: extract_facts phase tail runs the conflict sweep (ai/decide/sweep.ts) only when the slot is not off; +2 System One v1: purge phase prunes decision receipts (ai/decide/store.ts); grown v0.46.26.0 megawave (#4102 #2608) + master v0.46.26.0 cycle-start orphan recovery; +10 wave G #3974: cycle-sync uncommitted-drift warn; grown wave-g (#4416): synthesize_concepts source threading; grown wave-g (#4416): synthesize_concepts source threading (same fix absorbed as #4417 on wave-k); wave-k: ); +7: #4077 abort threading; +10: #4745 fullImplicitSourceCycle opt-in contract; +3: #4890 extract phase jsonMode/quiet + pages-not-links totals; +1: wave review — extract phase passes quiet:true + jsonMode:false; +1: extract_facts pagesFailed detail; +8 fix wave 3: one cycle date resolved in runCycle and threaded to synthesize/patterns/drift (C-15); +1 #5632: cycle sync resumes an unfinished managed cursor with its stored options; fix wave 3 x fix wave 2 (v0.60.5.0) composition: +1 at the merge; -41 #5809: anyAbortSignal peeled to abort-signals.ts; +5 #5809: extract_atoms phase gets a real abort signal; +4 #5809: cycle_already_running names the lock holder; +7 #5255: cycle sync runs a managed pull request as no-pull and reports upstream_refresh; +1 #4578: a lock steal during the last selected phase reports lock_stolen, not aborted; +3 #5536: keyless embed phase clean-skips when embedding_disabled is set; +5 F4b: planner-stats refresh after the freshness phases (logic in planner-stats.ts); +2 agent operator wave A1: PhaseResult sibling code/fix; +20 #5876: Life Chronicle phase registration (CyclePhase, ALL_PHASES, NEEDS_LOCK) and its runCycle dispatch block; v0.60.46.0 merge: re-summed to the merged line count (3224); +3 retrieval feedback retention in the purge phase (logic in feedback/store.ts pruneRetrievalFeedback); 12 Lane D: facts_drain phase registration (CyclePhase, ALL_PHASES, NEEDS_LOCK) and its runCycle dispatch line (logic in cycle/facts-drain.ts); P3 x foundations-2 composition: deltas re-summed at the merge; 12 Lane D: facts_drain phase registration (CyclePhase, ALL_PHASES, NEEDS_LOCK) and its runCycle dispatch line (logic in cycle/facts-drain.ts); +15 GBRA-49 temporal typed edges: edge_contradictions phase registration + dispatch block + extract-phase relationship sweep call (logic in cycle/edge-contradictions.ts, link-relationships.ts); P3 x P1 (v0.60.57.0) composition: deltas re-summed at the merge; +1 fix wave 9 lane P (#5151): extract_facts phase passes drain so the facts watermark drain runs (logic in facts/reconcile-watermark.ts); +10 #6188: fence_repair phase registration (CyclePhase, ALL_PHASES, NEEDS_LOCK) and its runCycle dispatch block (logic in cycle/fence-repair.ts); +19 fix wave 12 #6242: source cycles with brain-wide phases also take the shared gbrain-cycle lease (acquireDbCycleLock lease set, needsMaintenanceLease, skipBrainWidePhases, all-skipped deriveStatus case; lease logic in cycle/lock-set.ts); +16 #6377: content_repair phase registration (CyclePhase, ALL_PHASES, NEEDS_LOCK), the REPAIR_LANE_PHASES dispatch helper shared with fence_repair (logic in cycle/content-repair.ts); +10 C4 pinned questions: standing_questions phase registration (CyclePhase, ALL_PHASES, NEEDS_LOCK) and its runCycle dispatch block (logic in questions/phase.ts); +11 #6696 (A5, A4): runCycle becomes the background-origin wrapper over runCycleUnscoped and adds the capacity notices (logic in persistence/admission-origin.ts, capacity-snapshot.ts) plus the CycleReport.notices interface field; +2 #6297: CycleOpts.directPhases (operator-named phases skip the patterns cadence); +5 #6865: unindexed_files phase registration (CyclePhase, ALL_PHASES, NEEDS_LOCK) and its line in the REPAIR_LANE_PHASES dispatch helper (logic in cycle/unindexed-files.ts); +2 fix wave 20 #6954: the extract phase warns on extract_write_lost and its stale drain retries the pages left due; +5 #7241: CycleOpts.onPhaseStart and its best-effort call in timePhase, so the autopilot-cycle job writes its current phase to minion_jobs.progress; +1 GBRA-133: the extract phase passes the stale-drain budget to its targeted pass when sync gave no slug list; +7 #7630 (GBRA-207): the sync phase refuses sync_anchor_relative when no source matches its directory and default's local_path is relative; re-summed at the memory train #8481 merge with v0.60.576.0 (3348 measured); +3 GST-1856: the purge phase drops applied-capture records past 90 days (logic in ingestion/applied-captures.ts purgeStaleAppliedCaptures); +4 train C: #9145 #6770 opt-in mcp_request_log retention purge step on top of master's cycle growth; +2 GBRA-387 storage manifest: dream skips a cycle scoped to the storage shelf (check in storage-manifest/door.ts); re-summed at the merge with master 3f138e1b (3357 measured)src/core/cycle/synthesize.ts 3244 ratchet +3 #7805: each captured session synthesizes only into its own frozen source (routing import, the outer wrapper, the routing parameter; logic in cycle/synthesize-source-routing.ts); +26 System One v1 S7/S8: triage and grounding decide delegation (triage-decide.ts, grounding-decide.ts); merged waves; grown v0.46.26.0 megawave + master rolling lease via shared throttled renewer; grown wave-g (#4506): cycle summaries can stay out of the source repo; +18: expired-verdict sweep + DeepSeek judge thinking pin (#4069); +47: #4077 cooperative-abort threading; +110: eval fix wave F6 spend surfacing (withChatPhase wrap, triage/child token telemetry, zero-page counter); +32: F1b quote-verify call site + kill switch; +2: F1a/F3/F4a OUTPUT POLICY rules; +59: F2 verified-segment rescue (gate at report construction, rescue knobs, telemetry); +19: rubric v2 peak-scoring + docblock rescue branch; +50: #4337 summary link-sample cap + dream_created_cycle_date preserve-on-rerun; +5: #4348 resolveCycleDate wiring (local-day summary bucketing); +3 round-3 rebase true-up; +55: #4805 synth-v2 completion skip (findSynthV2Completion + prefix-parameterized loadSuccessfulSynthesisKeys); +10: #4886 mode-aware buildSynthesisPrompt (oneshot children drop tool-use/final-prose guidance); #5105: small legacy writer/refusal and shared revision CAS delegates; +4: merge of #5666 durable synthesis completions with the v0.59.18.0 verify-epoch wiring; +7 #5413/#5471 discovery exclusions (self-capture session ids, dream output directories); +6 fix wave 2 (v0.60.5.0) integration: W7 paid-loop breaker check before submission and released-key daily-cap count on top of the W1b discovery exclusions; +6 v0.60.5.0 master-merge true-up: the wave-2 growth (+13 W1b, +6 W7) re-summed over master v0.59.18.0 at 3222 lines with no slack; +76 fix wave 3: per-run USD gate + fail-closed daily cap (C-13), child first-write ownership for stamp/reverse-write (C-8, #5685), cycle-date prompt hint (C-15), opt-in attribution rule (#5425); fix wave 3 x fix wave 2 (v0.60.5.0) composition: +19 at the merge; +2 #5806 triageNow clock seam forwarded to triage (interface field + call-site option); +4 #5854: a postprocess or summary publish still pending after its wait is deferred (publish_pending warn, no cooldown stamp; helper in synthesize-postprocess.ts); +14 #5490 review: a triage verdict a chat_fallback_chain model gave is used for the run but not cached (TriageResult.answeredBy, judge-client marker, guarded putDreamVerdict); Foundations 2 Lane C: maintenanceTransaction import (attributed summary page); +14 #5490 review: a triage verdict a chat_fallback_chain model gave is used for the run but not cached (TriageResult.answeredBy, judge-client marker, guarded putDreamVerdict); Foundations 2 Lane C: maintenanceTransaction import (attributed summary page); +14 #5490 review: a triage verdict a chat_fallback_chain model gave is used for the run but not cached (TriageResult.answeredBy, judge-client marker, guarded putDreamVerdict); lowered to 3200 by wave 9 lane W #5145: completion-key helpers (findLegacyCompletion, findSynthV2Completion, loadSuccessfulSynthesisKeys) peeled to synthesize-completion.ts with the new pre-triage partition; +13 P2 extraction.date_grounding: transcript observation date line instead of a run-date "Today's date" (config field + prompt arg); +1 fix wave 11 #6160: oneshot_task_prefixes on the child job data; +18 fix wave 12 #6069: unreliable-verdict backoff in runTriagePass (report code, pass backoff count, triage details entry; marker logic in triage-backoff.ts); +1 fix wave 12 #6242: SYNTH_PHASE_FAIL keeps an OperationError's suggestion and code (OperationError import); +3 wave 17 #6616: slug discovery and postprocessing share the canonical committed child outputs (loadCommittedSynthesisOutputs in synthesize-postprocess.ts; one call-site line, one parameter, one lookup line); lowered to 3224 by wave 17 #6642: the summary provenance section moved to summaryProvenanceLines in dream-provenance.ts; +6 GBRA-130 B-6 (#6860): surrogate-safe triage cuts (truncateUtf8) and the per-transcript verdict-cache write call site (logic in triage-backoff.ts VerdictCacheWrites); +2 GBRA-161 PR 4 (#7065): the synthesize phase activates each synthesized transcript's outputs as its generation (activateSynthesisGenerations import and call site; logic in cycle/synthesize-generations.ts); +8 GBRA-161 PR 5 (S-2): the dream summary publishes as a single-item dream_summary generation bound to its pre-run revision (publishSinglePage with a generation_fenced skip); +1 GBRA-60: a managed synthesis child carries dream_output (verify and stamp before put_page; cycle/synthesize-child-verify.ts)src/core/cycle/extract-atoms.ts 1638 ratchet crossed the 1500 unlisted cap in the atoms/extraction fix wave: +21 embed-aware cost gate (#4878), +65 atoms-array anchor scan (#4913); peel candidate: the parse block (parseAtomsOutcome / parseArrayAtOffset / atomsFromParsedArray) into extract-atoms-parse.ts; +35: #4853 transcript-origin atoms link to their conversation page; +130: #4916 transcript failure-count/tombstone (extract_atoms_transcript_state, TODOS P2(b)); wave composition: #4916 transcript-state skip + #4948 zero-atom prompt + #4943 meetings source-id summed; +3: wave review — a later `[]` is an honest zero-yield, a non-atom-shaped array is a counted failure; +13: wave review — explicit budget keeps the cap over an unpriced embed route ($0-priced); +14: wave review — transcript-state write errors surfaced, missing table warns once; merged reliability/shared-skills source integration; +37 fix wave 3: stable undated atom dates + stale-atom retirement (C-14); +3 #5525: effectiveVisibility stamped on non-managed atoms; fix wave 3 x fix wave 2 (v0.60.5.0) composition: +3 at the merge; +6 fix wave 3 lane A (#5601): accepted-pending atom batches count as progress (helper in persistence/accepted-pending.ts); +4 fix wave 4: #5705 transcript-as-data system prompt lines and its message helper, #5627 response schema import (the atom-type list moved to extract-atoms-schema.ts); +30 #5809/#5832: drain hard/soft stop signals (ExtractAtomsOpts.signal/stopSignal, pre-commit abort checks, no strike or post-stop writes after a hard stop) and the cancellable backlog count; +1 #5812: transcript items are paste-stripped (corpusTextForExtraction import) before the input cut; +1 #5820: extract_atoms discovery passes selfCaptureSessionIds like synthesize; +10 #5856/#5854: drain attempt state (one BudgetTracker + one publish wait across batches) and the opt-in connector email/meeting exclusion (predicate in connector-atoms.ts); +1 Foundations 2 Lane C: maintenanceTransaction import (attributed stale-atom retirement); +5 fix wave 9 lane P (#5041): opt-in atom write-through hook and retired-atom slugs returned for file removal (logic in derived-write-through.ts); the parse block (parseAtomsOutcome / parseArrayAtOffset / atomsFromParsedArray) is peeled into extract-atoms-parse.ts (-193, fix wave 10 lane B); +35: #4853 transcript-origin atoms link to their conversation page; +130: #4916 transcript failure-count/tombstone (extract_atoms_transcript_state, TODOS P2(b)); wave composition: #4916 transcript-state skip + #4948 zero-atom prompt + #4943 meetings source-id summed; +3: wave review — a later `[]` is an honest zero-yield, a non-atom-shaped array is a counted failure; +13: wave review — explicit budget keeps the cap over an unpriced embed route ($0-priced); +14: wave review — transcript-state write errors surfaced, missing table warns once; merged reliability/shared-skills source integration; +37 fix wave 3: stable undated atom dates + stale-atom retirement (C-14); +3 #5525: effectiveVisibility stamped on non-managed atoms; fix wave 3 x fix wave 2 (v0.60.5.0) composition: +3 at the merge; +6 fix wave 3 lane A (#5601): accepted-pending atom batches count as progress (helper in persistence/accepted-pending.ts); +4 fix wave 4: #5705 transcript-as-data system prompt lines and its message helper, #5627 response schema import (the atom-type list moved to extract-atoms-schema.ts); +30 #5809/#5832: drain hard/soft stop signals (ExtractAtomsOpts.signal/stopSignal, pre-commit abort checks, no strike or post-stop writes after a hard stop) and the cancellable backlog count; +1 #5812: transcript items are paste-stripped (corpusTextForExtraction import) before the input cut; +1 #5820: extract_atoms discovery passes selfCaptureSessionIds like synthesize; +10 #5856/#5854: drain attempt state (one BudgetTracker + one publish wait across batches) and the opt-in connector email/meeting exclusion (predicate in connector-atoms.ts); +1 Foundations 2 Lane C: maintenanceTransaction import (attributed stale-atom retirement); +5 fix wave 9 lane P (#5041): opt-in atom write-through hook and retired-atom slugs returned for file removal (logic in derived-write-through.ts); +17 #5031: same-page case-insensitive atom adoption fallback (one page-atom scan per source page per run); +12 P2 atomsPrompt helper: extraction.date_grounding source observation date + rule in the atoms prompt; +4 GBRA-75: octet_length-bounded body-length predicate (minCompiledTruthChars) for discovery and the backlog count; GBRA-130 A-42 (#6804): dot-led atom stems and the legacy-slug adoption guard; re-measured at the Train A merge of #8948: 1633; re-measured at the Train C merge onto Train B (#9246 onto #9223): 1633 -> 1635, both sides' growth; +3 GBRA-504 guest notes: atom extraction skips guest sources (classification in guests/derived.ts)-src/core/engine.ts 2892 ratchet +5 #7191: findPages/countPagesBy signatures and type imports (SQL in engine-sql/page-lookup.ts); grown v0.46.26.0 megawave: relational/visibility/usage contract surface (#4352 #4218); grown wave-g (#4524 #4527): orphans-mode contract + removeLink deleted count; wave-k: +4 fail-closed TrajectoryOpts.remote contract doc (#3855), +2 FactListOpts.unconsolidatedOnly (#4070), +14 getAllConfig bulk-read contract (#3980); grown v0.46.26.0 megawave: relational/visibility/usage contract surface (#4352 #4218); grown wave-g (#4524 #4527): orphans-mode contract + removeLink deleted count; wave-k: +4 fail-closed TrajectoryOpts.remote contract doc (#3855), +2 FactListOpts.unconsolidatedOnly (#4070), +14 getAllConfig bulk-read contract (#3980); +1: getBacklinkCounts page-id contract doc (#4380); +9: FactListOpts.grep SQL pre-limit contract (#3851); +13: dream-verdict TTL contract (#4069); +33: softDeletePages batch soft-delete contract (#4587); +8: #4592 scoped getStats/getHealth contract doc; +5 read-time TTL validity contract docs (active vs history read semantics); +12: #4280 findOrphanPages type/quarantined metadata contract; +14: traversePathsDetailed row-cap contract (ship-review); +12: resolveSlugWithAliasDetailed owning-source contract (ship-review) | merged v0.48.1.0: master #4788 + wave traversePathsDetailed/resolveSlugWithAliasDetailed; master: | merged v0.48.1.0 true-up; corrective release: read-policy signatures and Chronicle scope; +7: #4882 listFactsSince entitySlug/sessionId composition doc; #5105: canonical page state shared module and transaction/snapshot delegates; #5105: guarded derived projection preparation and read seals; #5105: resident-stop registration and direct transaction contract; #5105: +1 raw preservation contract for legacy engine migration; merged company ingestion/schema routing changes; safety wave: fact embedding model and text identity contract; +5 write-path wave: findDuplicatePage excludeSlug + id-first ranking contract; +2 fw3 A14: addTag tagSource provenance contract; evidence delivery: getChunkWindows interface member + type import (+3); #5761: +4 markPagesAttendanceBlocked member + countStalePagesForExtraction attendance option; +4 #5888: FactListOpts.fingerprint + FactRow.fact_fingerprint contract (hot-memory duplicate collapse); +1 GBRA-49: LinkReadScope temporal opts on the link read contract; +4 #5984: upsertChunks sealChunkerVersion and createVersion preimage contract docs (round-trip diet); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2683 measured); +10 P7 relationalChainHop member + ChainHopOpts/ChainHopEdge imports (SQL in search/read-enrichment.ts); +14 contributor audit wave P0: listFactsKeyset member (delta facts keyset read contract) + FactRow.created_at_iso; +1 #5375: get_versions limit/include_body type import (GetVersionsOpts, PageVersionRows); 3 P2 speaker attribution: FactAttribution type + FactRow/NewFact.attributed_to fields + findCandidateDuplicates attributedTo option contract; +4 #5984 lane apply diet: setPageAliases inline option and upsertChunks pageId contract docs; +10 #6278: executeRaw timeoutMs contract (transaction-local statement_timeout for bounded preparation reads); +2 GBRA-69: replaceDerivedLinksBatch member; master v0.60.136.0 merge into #5575 memory trust (both sides kept); +6 GBRA-67: readPageSnapshotsBatch interface member (BrainEngine signatures cannot move); +1 GBRA-75 wave 10: optional findDuplicatePages member (batched findDuplicatePage, contract in engine-sql/pages.ts); +4 FactListOpts/TrajectoryOpts.excludePrivate fact-provenance visibility contract (interface fields cannot move); +18 GBRA-76: TransactionOptions (abort signal) interface and the transaction/transactionDirect signatures (abort logic in postgres-engine/transaction-abort.ts); +2 W14 P3.11 (#4381): LinkBatchInput.resolution_type on top of W13; +1 C2: findCandidateDuplicates arm:'keyword' contract doc (facts.candidate_fusion); re-summed at the master 6ccf30c3e merge (2708 integration + 2707 master - 2707 base); +5 Cat 40 Hard fix wave F2 (#6271): countKeywordPages/searchKeywordPages BrainEngine signatures (SQL in engine-sql/keyword-pages.ts); +6 W15 P1.2 (#6454): countStaleFrontmatterKeyPages/listStaleFrontmatterKeyPages/stripStaleFrontmatterKeys contract (SQL in engine-sql/pages.ts); +2 large pages Wave A sub-a: getChunkPage signature (get_chunks paging; SQL in engine-sql/chunks.ts); +5 #6696 B3: readEmbeddingStateCounts/listEmbeddingStateRows signatures + type import (SQL in engine-sql/chunks.ts); +2 Cat 40 next wave part 1: non-ranking link types on the relationalFanout/relationalChainHop/getBacklinkCounts/getAdjacencyBoosts contract docs (policy in link-ranking-policy.ts; re-summed at the 0.60.242.0 merge: master 2794 + 2); +26 Wave B PR 1: segmented page storage members (allocateBodyOccurrenceIds..sweepSegments) + page-body type import (SQL in engine-sql/page-body.ts); merge v0.60.248.0: Wave B PR 1 and master growth compose at 2822; +1 LHF wave 2 item 1: executeRaw opts gain jitOff/prepare (the JIT-off typed-search type check; logic in ops/search-type-filter.ts); +9 PR2 fix lane X: BrainEngine.keywordBoundedRead, one unscoped read under the keyword statement bound for the segmented-region read (interface member and its doc cannot move): 2823 + 9; +9 GBRA-177: TakesListOpts.oldestFirst/sinceOnOrBefore/ungradedFirst for the grade_takes window (interface fields cannot move; SQL in engine-sql/takes.ts): 2832 + 9; +6 GBRA-156: TransactionOptions.pipelineFirst (the declaration goes out with BEGIN behind a transaction-mode pooler; predicate in persistence/protocol.ts); interface fields cannot move; +1 GBRA-161 PR 2: deprecation notes on insertFacts({ deleteForPageFirst }), deleteFactsForPage and expireFact (interface docs cannot move); +7 GBRA-156: TransactionOptions.pipelineEarly (search read bodies go out behind BEGIN; predicate in postgres-engine/search-settings.ts); interface fields cannot move; +2 GBRA-156: TransactionOptions.readOnly (search read transactions open BEGIN READ ONLY; 2858 measured); grown v0.46.26.0 megawave: relational/visibility/usage contract surface (#4352 #4218); re-summed at the Wave B PR 4 merge with v0.60.452.0 (2866 measured); re-summed at the memory train #8481 merge with v0.60.576.0 (2874 measured); +1 GST-731: TrajectoryPoint.valid_until (interface fields cannot move); +9 #9068: deletePage/deletePages scrub contract docs (interface docs cannot move); +2 GBRA-467: optional holdSchemaMigrationLock member (interface members cannot move; logic in schema-migration-lock.ts); re-measured at the Train A merge of #8948: 2889; +1 #9295: wantedProducers option on the stale-page list signature (interface fields cannot move; SQL in engine-sql/pages.ts); +2 GBRA-574 B2: NewFact.dimension/value (the conversation fact slot; SQL in engine-sql/facts.ts)+src/core/engine.ts 2894 ratchet +5 #7191: findPages/countPagesBy signatures and type imports (SQL in engine-sql/page-lookup.ts); grown v0.46.26.0 megawave: relational/visibility/usage contract surface (#4352 #4218); grown wave-g (#4524 #4527): orphans-mode contract + removeLink deleted count; wave-k: +4 fail-closed TrajectoryOpts.remote contract doc (#3855), +2 FactListOpts.unconsolidatedOnly (#4070), +14 getAllConfig bulk-read contract (#3980); grown v0.46.26.0 megawave: relational/visibility/usage contract surface (#4352 #4218); grown wave-g (#4524 #4527): orphans-mode contract + removeLink deleted count; wave-k: +4 fail-closed TrajectoryOpts.remote contract doc (#3855), +2 FactListOpts.unconsolidatedOnly (#4070), +14 getAllConfig bulk-read contract (#3980); +1: getBacklinkCounts page-id contract doc (#4380); +9: FactListOpts.grep SQL pre-limit contract (#3851); +13: dream-verdict TTL contract (#4069); +33: softDeletePages batch soft-delete contract (#4587); +8: #4592 scoped getStats/getHealth contract doc; +5 read-time TTL validity contract docs (active vs history read semantics); +12: #4280 findOrphanPages type/quarantined metadata contract; +14: traversePathsDetailed row-cap contract (ship-review); +12: resolveSlugWithAliasDetailed owning-source contract (ship-review) | merged v0.48.1.0: master #4788 + wave traversePathsDetailed/resolveSlugWithAliasDetailed; master: | merged v0.48.1.0 true-up; corrective release: read-policy signatures and Chronicle scope; +7: #4882 listFactsSince entitySlug/sessionId composition doc; #5105: canonical page state shared module and transaction/snapshot delegates; #5105: guarded derived projection preparation and read seals; #5105: resident-stop registration and direct transaction contract; #5105: +1 raw preservation contract for legacy engine migration; merged company ingestion/schema routing changes; safety wave: fact embedding model and text identity contract; +5 write-path wave: findDuplicatePage excludeSlug + id-first ranking contract; +2 fw3 A14: addTag tagSource provenance contract; evidence delivery: getChunkWindows interface member + type import (+3); #5761: +4 markPagesAttendanceBlocked member + countStalePagesForExtraction attendance option; +4 #5888: FactListOpts.fingerprint + FactRow.fact_fingerprint contract (hot-memory duplicate collapse); +1 GBRA-49: LinkReadScope temporal opts on the link read contract; +4 #5984: upsertChunks sealChunkerVersion and createVersion preimage contract docs (round-trip diet); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2683 measured); +10 P7 relationalChainHop member + ChainHopOpts/ChainHopEdge imports (SQL in search/read-enrichment.ts); +14 contributor audit wave P0: listFactsKeyset member (delta facts keyset read contract) + FactRow.created_at_iso; +1 #5375: get_versions limit/include_body type import (GetVersionsOpts, PageVersionRows); 3 P2 speaker attribution: FactAttribution type + FactRow/NewFact.attributed_to fields + findCandidateDuplicates attributedTo option contract; +4 #5984 lane apply diet: setPageAliases inline option and upsertChunks pageId contract docs; +10 #6278: executeRaw timeoutMs contract (transaction-local statement_timeout for bounded preparation reads); +2 GBRA-69: replaceDerivedLinksBatch member; master v0.60.136.0 merge into #5575 memory trust (both sides kept); +6 GBRA-67: readPageSnapshotsBatch interface member (BrainEngine signatures cannot move); +1 GBRA-75 wave 10: optional findDuplicatePages member (batched findDuplicatePage, contract in engine-sql/pages.ts); +4 FactListOpts/TrajectoryOpts.excludePrivate fact-provenance visibility contract (interface fields cannot move); +18 GBRA-76: TransactionOptions (abort signal) interface and the transaction/transactionDirect signatures (abort logic in postgres-engine/transaction-abort.ts); +2 W14 P3.11 (#4381): LinkBatchInput.resolution_type on top of W13; +1 C2: findCandidateDuplicates arm:'keyword' contract doc (facts.candidate_fusion); re-summed at the master 6ccf30c3e merge (2708 integration + 2707 master - 2707 base); +5 Cat 40 Hard fix wave F2 (#6271): countKeywordPages/searchKeywordPages BrainEngine signatures (SQL in engine-sql/keyword-pages.ts); +6 W15 P1.2 (#6454): countStaleFrontmatterKeyPages/listStaleFrontmatterKeyPages/stripStaleFrontmatterKeys contract (SQL in engine-sql/pages.ts); +2 large pages Wave A sub-a: getChunkPage signature (get_chunks paging; SQL in engine-sql/chunks.ts); +5 #6696 B3: readEmbeddingStateCounts/listEmbeddingStateRows signatures + type import (SQL in engine-sql/chunks.ts); +2 Cat 40 next wave part 1: non-ranking link types on the relationalFanout/relationalChainHop/getBacklinkCounts/getAdjacencyBoosts contract docs (policy in link-ranking-policy.ts; re-summed at the 0.60.242.0 merge: master 2794 + 2); +26 Wave B PR 1: segmented page storage members (allocateBodyOccurrenceIds..sweepSegments) + page-body type import (SQL in engine-sql/page-body.ts); merge v0.60.248.0: Wave B PR 1 and master growth compose at 2822; +1 LHF wave 2 item 1: executeRaw opts gain jitOff/prepare (the JIT-off typed-search type check; logic in ops/search-type-filter.ts); +9 PR2 fix lane X: BrainEngine.keywordBoundedRead, one unscoped read under the keyword statement bound for the segmented-region read (interface member and its doc cannot move): 2823 + 9; +9 GBRA-177: TakesListOpts.oldestFirst/sinceOnOrBefore/ungradedFirst for the grade_takes window (interface fields cannot move; SQL in engine-sql/takes.ts): 2832 + 9; +6 GBRA-156: TransactionOptions.pipelineFirst (the declaration goes out with BEGIN behind a transaction-mode pooler; predicate in persistence/protocol.ts); interface fields cannot move; +1 GBRA-161 PR 2: deprecation notes on insertFacts({ deleteForPageFirst }), deleteFactsForPage and expireFact (interface docs cannot move); +7 GBRA-156: TransactionOptions.pipelineEarly (search read bodies go out behind BEGIN; predicate in postgres-engine/search-settings.ts); interface fields cannot move; +2 GBRA-156: TransactionOptions.readOnly (search read transactions open BEGIN READ ONLY; 2858 measured); grown v0.46.26.0 megawave: relational/visibility/usage contract surface (#4352 #4218); re-summed at the Wave B PR 4 merge with v0.60.452.0 (2866 measured); re-summed at the memory train #8481 merge with v0.60.576.0 (2874 measured); +1 GST-731: TrajectoryPoint.valid_until (interface fields cannot move); +9 #9068: deletePage/deletePages scrub contract docs (interface docs cannot move); +2 GBRA-467: optional holdSchemaMigrationLock member (interface members cannot move; logic in schema-migration-lock.ts); re-measured at the Train A merge of #8948: 2889; +1 #9295: wantedProducers option on the stale-page list signature (interface fields cannot move; SQL in engine-sql/pages.ts); +2 GBRA-574 B2: NewFact.dimension/value (the conversation fact slot; SQL in engine-sql/facts.ts); +2 Rust engine plan PR 5: BrainEngine.capabilities member and its type import (table in engine-capabilities.ts; interface members cannot move); re-summed at the rust-engine/core merge with master (2894 measured)src/core/import-file.ts 2091 ratchet +2 #7880: importFromContent's holdNoncanonicalPrivate option (interface field; the hold is screenImportContent's); +2 #7848: importFromFile holds a non-canonical private request (predicate and hold in persistence/visibility-request.ts); +2 W1 belief ledger: the legacy import is an unmanaged projection point (logic in belief/projection-point.ts); +2: pre-publication withdrawal validation; grown v0.46.26.0 megawave: OCR budget + image import + embed-retry rewire (#3973 #3374); grown wave-g (#4530): per-model chunk-token cap wiring; +24 #4548: row-level visibility-aware fence merge on remote write-back (replaces the #2044 whole-block swap + #4553/#4555 warn-only paths); +7 #4546: merge extended to the timeline-embedded fence; +5 #4107: maybeOcr gates on the OCR model's provider; +3 #3893; +7: #4702 disabled_patterns pass-through to the sanity gate; composition true-up (fix-wave multi-train); +8 #4903: importCodeFile writes source_path so the full-sync reconcile can see code pages; -11: wave review — local fence append replaced by facts-fence.replaceOrInsertFactsFence (#4756 rule); security: durable queued authority and confined filesystem dispatch; master integration: grown v0.46.26.0 megawave: OCR budget + image import + embed-retry rewire (#3973 #3374); grown wave-g (#4530): per-model chunk-token cap wiring; +24 #4548: row-level visibility-aware fence merge on remote write-back (replaces the #2044 whole-block swap + #4553/#4555 warn-only paths); +7 #4546: merge extended to the timeline-embedded fence; +5 #4107: maybeOcr gates on the OCR model's provider; +3 #3893; +7: #4702 disabled_patterns pass-through to the sanity gate; composition true-up (fix-wave multi-train); +8 #4903: importCodeFile writes source_path so the full-sync reconcile can see code pages; -11: wave review — local fence append replaced by facts-fence.replaceOrInsertFactsFence (#4756 rule); harness support: boundary wiring to shared grants, isolated setup, withdrawal and delegated guards; merged v0.49: withdrawal preservation after data-only frontmatter parsing; #5105: small legacy writer/refusal and shared revision CAS delegates; #5105: +8 prepared contextual retrieval policy and retry boundary wiring; upstream integration: preserve independently reviewed master additions with branch facade extraction; #5252 wave: shared provider-free Markdown and code preparation; merged company ingestion/schema routing changes; master retrieval/projection integration with company ingestion; shared content: prepare managed image imports without bypassing canonical publication; +29 write-path wave: identity move/collision wiring (logic in import-identity.ts), deferred embedding on provider failure, image index completeness, file-time date anchor; +22 fw3 A13: markdown re-import reuses unchanged chunk vectors under the seal/wrapper/signature/protected-fence gate; +2 fw3 A12: importFromFile firstCommitAt option; +3 fw3 A14: managed imports keep add-only tags; +4 #5675: record the file origin move inference binds to (logic in import-identity.ts); fw3 integration: A12/A13/A14 (+27) and #5675 (+4) compose; +17 wave-2 W4: safe-chunk re-seal of unchanged legacy markdown/code pages (#5050 #5247) and embedding-input provenance on inline imports (#5553); -1 fix wave 2 (v0.60.5.0) integration: W4 delta re-summed over the merged master line count; fix wave 3 x fix wave 2 (v0.60.5.0) composition: +16 at the merge; +11 #4616: markdown and code imports keep the usable vectors of a partially refused batch and leave refused chunks for embed --stale; lowered to 2230: #5621 contextual-mode resolution peeled to core/import-contextual-mode.ts (shared with gbrain repair contextual-mode); +2 wave 8 lane D1 #5158: key-order fallback equality call (comparison lives in page-state/import-guard.ts); +1 F1c: direct imports run in maintenanceTransaction (write attribution; helper in persistence/attribution.ts); lowered to 2178: #5988 content screen and content-sanity config peeled to core/import-screen.ts; +1 #6007: the prepared apply returns its page id and seal (PreparedImportApplied); +1 #5333: trusted imports drop a stale oversized embed_skip/content_flag the gate no longer sets, and an embed_skip transition defeats both unchanged fast paths; wave 10 collector: lane E (#5333) and the other lanes compose at 2183; grown #6188 (+17): fence options interface, result fields and the Tier 1 step call (logic in fence-repair/import-step.ts); +2 #5984 single-write fast path: the coordinated existingSnapshot option (interface field) composes with the lane apply diet at 2202; +1 GBRA-69: a coordinated apply defers its chunker seal to the caller (sealImportedPage in page-state/projections.ts); lowered to 2023: #5001 the edge-mapping loop moved to code-chunks.ts mapCodeEdges (shared with the prepared apply); W14 P3.13 (#5001) lowered 2049→2023 by moving the edge loop to mapCodeEdges; +2 W13 PR1 on top (2025 measured); +2 #6529: the unchanged-image skip path records source_path (refreshSourcePath, as #4588 does for Markdown); +4 large pages A6/T33: code files keep CODE_FILE_MAX_BYTES, a page over PAGE_INLINE_MAX_BYTES commits with NULL vectors for the metered stale sweep; +1 #6722: an embed_skip page is chunked and never embedded (noEmbed folds the marker); merge v0.60.240.0: large pages and master growth compose at 2032; +24 Wave B lane 1d: the segmented storage step (stage before publication, flip in the apply, seal and post-commit projection; logic in persistence/segmented-apply.ts and page-body/ingest.ts) and the streamed-import dispatch over the single-string ceiling (logic in page-body/streamed-import.ts); merge v0.60.248.0: Wave B PR 1 and master growth compose at 2056; +4 Wave B review: a rename re-preparation reuses the staged segmented body (reuseSegments option) and the remote fence merge reads an unread body as fence-free (fenceBody in page-body/page-shape.ts); +2 Wave B gem A: a coordinated demotion versions the segmented page before demoting it (createVersion order); lanes compose at 2062; +2 Wave B lane 2q: ImportResult.searchable (interface field; the value comes from SegmentedImport.afterCommit);+2: pre-publication withdrawal validation; +9 #7172: kept chunk rows move to their new index and a bounded managed publication defers its chunk replacement (logic in page-state/chunk-moves.ts and page-state/projections.ts continueDeferredProjection); merge v0.60.332.0: #7172 and master growth compose at 2075; +7 GBRA-283 B3a (#8523): the three file import entry points re-enter an embedded engine's scope (needsEngineScope in core/engine-scope.ts), importFromContent runs its screened body in that scope as a closure, and the deferred embed resumes the import's scope; re-summed at the memory train #8481 merge with v0.60.576.0 (2088 measured); +3 GST-2112: importFromContent's expectedBaseRevision option and base check (a webhook capture binds its write to its readers check)src/core/migrate.ts 618 ratchet schema-migration runner only; migrations live in src/core/schema-migrations/ (W3); +3 #5216: resumable page revision backfill runs after every migration pass while pages.knowledge_revision is nullable; re-summed at the Train A merge onto master v0.60.708.0: master 597 + #8930 hardenFunctionSearchPaths wiring 19 = 616; +2 GST-2687: each version read and write records it on the engine (noteSchemaVersion) = 618src/core/operations.ts 250 ratchet +1 #7168: graphRankOperations import (ops/graph-rank.ts; spread shares the orphans line); peel target: containment sprint C4-C7; grown v0.46.26.0 megawave op wiring; +chat-connectors wiring (master merge); +5 v0.47 gmail-loops: loopsOperations spread + OP_AREAS; #5105: receipt operation registry wiring; shared-skills integration on company-ingestion base; +2 security wave: withOutputRedaction applied at op registration; +1 #5616: pageEditOperations import (spread shares the pages line); +1 Foundations 1 F1b: attributionOperations import (spread shares the admin line); +1 agent operator wave A6: ops/notices.ts import (mute_notice); +2 agent operator closeout A1: registerOpRoutes import + call (routing logic in fix-routing.ts); +2 retrieval feedback: feedbackOperations import and spread (ops/feedback.ts); +1 #6007: pageBatchOperations import (spread shares the pages line); +1 P5: wanted_pages area row; lowered GBRA-75 W11 cold start: OP_AREAS + finalize step moved to operation-load.ts (shared with the CLI per-op loader); +1 C4 pinned questions: questionsOperations import and spread (ops/questions.ts; its areas live in operation-load.ts OP_AREAS); +1 Wave B append: pageAppendOperations import (spread shares the pages line); +1 Wave B upload sessions: pageUploadOperations import (spread shares the pages line); +1 #7191: search-exact import; +1 GBRA-156: whois import (ops/whois.ts; spread shares the chunks line); +1 GST-359 D: qmMemoryOperations import (ops/qm-memory.ts; spread shares the memory line); re-summed at the train R merge with v0.60.574.0: 246 + 1; re-summed at the memory train #8481 merge with v0.60.576.0 (248 measured); +1 Wakeshift PR 1: wakeshiftOperations import (ops/wakeshift.ts; its spread shares the jobs line); +1 GBRA-387 storage manifest: storageManifestOperations import (ops/storage-manifest.ts; its spread shares the files line)src/core/pglite-engine.ts 3103 ratchet +9 #7191: findPages/countPagesBy delegates and imports (SQL in engine-sql/page-lookup.ts); +4 GBRA-283 B1 (#8455): initSchema seeds an engine opened from settings with settings.embedding and refuses a mismatch, and its open skips the snapshot fast path (logic in embedded-engine.ts; engine methods cannot move); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); 4 Foundations 2 Lane F: autocommit write statements take the WAL checkpoint guard (classifier writesWal in pglite-engine/checkpoint-guard.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); 4 Foundations 2 Lane F: autocommit write statements take the WAL checkpoint guard (classifier writesWal in pglite-engine/checkpoint-guard.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); +1 #5984: upsertChunks guards pass the per-transaction config memo (transactionMemo in page-state/transactions.ts); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2983 measured); 4 Foundations 2 Lane F: autocommit write statements take the WAL checkpoint guard (classifier writesWal in pglite-engine/checkpoint-guard.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); E1 bootstrap moved to engine-sql/bootstrap.ts; ceiling rationale: docs/architecture/key-files/engines-1.md entry for src/core/pglite-engine.ts; evidence delivery: getChunkWindows delegate + type import (+3; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +12 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3213 #5824: searchVector SQL moved to search/vector-statement.ts (-166); lowered to 3117 #5889: searchTitles SQL moved to engine-sql/titles.ts (-108); lowered to 2915 F4a: getHealth SQL moved to engine-sql/health.ts (-202); +6 F4b: planner-sensitive reads call beforePlannerRead/plannerRead (logic in planner-stats.ts); +52 engine graduation (GBRA-50 G2a): marker/tombstone checks before and after the kernel lock (logic in persistence/graduation-custody.ts), lock-retaining close and held-lock open (engine lifecycle methods cannot move); +1 #5984: upsertChunks guards pass the per-transaction config memo (transactionMemo in page-state/transactions.ts); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2983 measured); +4 P7 relationalChainHop delegate; +8 contributor audit wave P0: listFactsKeyset delegate (SQL in engine-sql/facts.ts); +1 #5375: get_versions limit/include_body type import (GetVersionsOpts, PageVersionRows); +2 #5984 lane apply diet: putPage/setPageAliases write inline in the caller's page transaction (engine methods cannot move); +4 GBRA-69: replaceDerivedLinksBatch delegate (logic in derived-links.ts); +5 GBRA-67: readPageSnapshotsBatch delegate (batch logic in page-snapshot-batch.ts); +1 GBRA-75 wave 10: findDuplicatePages delegate (SQL in engine-sql/pages.ts); +2 GBRA-76: transaction/transactionDirect take TransactionOptions and refuse an already-aborted signal before BEGIN; +2 #4772 (W14 PR3): entityTypes HealthDeps delegate + import (policy in schema-pack/entity-types.ts, SQL in engine-sql/health.ts); +2 W14 P3.12 (#4772): entityTypes HealthDeps delegate + import on top of W13; +11 Cat 40 Hard fix wave F2 (#6271) on top: countKeywordPages/searchKeywordPages delegations (SQL in engine-sql/keyword-pages.ts) and the rankQuery score parameter (3023 measured); +3 W15 P1.2 (#6454): three one-line stale-frontmatter-key delegates (SQL in engine-sql/pages.ts); +6 large pages Wave A sub-a: getChunkPage delegate (SQL in engine-sql/chunks.ts); +11 #6696 B3: readEmbeddingStateCounts/listEmbeddingStateRows delegations + type import; +22 Wave B lane 1a: segmented page storage delegations (allocateBodyOccurrenceIds..sweepSegments, SQL in engine-sql/page-body.ts) and their imports; +7 LHF wave 2 item 5: request config snapshot delegate lines in getConfig/getAllConfig/setConfig/unsetConfig (logic in config-snapshot.ts); +3 PR2 fix lane B: logIngest stamps writer_version/writer_host_id/writer_segment_reader and getIngestLog names its columns (engine methods cannot move); integrated at the Wave B PR 2 master merge (v0.60.264.0): master 3072 + 3; +5 PR2 fix lane X: keywordBoundedRead runs the read on the engine itself (engine methods cannot move): 3075 + 5; +2 GBRA-130 B-6 (#6860): putDreamVerdict passes its payload through wellFormedJson (engine methods cannot move); +1 GBRA-130 A-1: held option on the stale-page list/count signatures (SQL in engine-sql/pages.ts); +1 GBRA-130 integration: the A-1 (links_extract_failure) and B-6 (wellFormedJson putDreamVerdict) engine hunks composed at the lane merge; +2 #6948: putPage runs assertOriginUnclaimed in its page transaction and restorePage runs assertRevivalUnclaimed (logic in persistence/origin-guard.ts; engine methods cannot move): 3080 + 2; GBRA-130 composed with #6948 at the master 0e0cd27b merge: re-summed to the merged line count (3085); +2 #7159: the frontmatter where clause in searchKeyword and its import (SQL in search/frontmatter-where.ts; engine methods cannot move); +2 GBRA-156 keyword OR rarity: the import and the searchKeyword OR retry through rankOrFallbackByRarity with an orFallback rank parameter like Postgres (logic in search/keyword-or-rarity.ts; engine methods cannot move); +5 agent operator gate fixes: repair-failed marker gate before the lock and the marker record after a failed auto-repair (logic in pglite-repair.ts, refusal in pglite-repair-consent.ts); re-summed at the Wave B PR 4 merge with v0.60.452.0 (3097 measured); +2 GBRA-283 Wave A (#8460): the ENGINE_ROOT import and field (engine identity for per-engine caches; class fields cannot move)-src/core/postgres-engine.ts 3188 ratchet +9 #7191: findPages/countPagesBy scoped-read delegates and imports (SQL in engine-sql/page-lookup.ts); +6 GBRA-283 B1 (#8455): an engine opened from settings routes its direct URL and statement-description cache from its settings, and initSchema seeds settings.embedding and refuses a mismatch (logic in embedded-engine.ts; engine methods cannot move); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); ceiling rationale: docs/architecture/key-files/engines-2.md entry for src/core/postgres-engine.ts; evidence delivery: getChunkWindows scoped-read delegate + type import (+5; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +10 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3242 #5824: searchVector SQL moved to search/vector-statement.ts, +explainVectorSearch/runVectorAttempt (-156); +6 #5730: onpoisoned wiring on the instance/module/connection-manager pools + poisonedDiscards in getPoolDiagnostics (counter in pool-gauge.ts); +5 #5801: onCheckout observer seam (fires after reserve resolution / transaction-callback entry; listeners in pool-gauge.ts); lowered to 3119 #5889: searchTitles SQL moved to engine-sql/titles.ts (-133); lowered to 2914 F4a: getHealth SQL moved to engine-sql/health.ts (-216); +2 #5984: transactions track held page guards like PGLite (withHeldPageKeys), so repeated guards in one transaction cost no round trips; +1 #5984: traceSqlOptions import for the env-gated GBRAIN_SQL_TRACE bench hook (src/core/sql-trace.ts); v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (2917 measured); +2 engine graduation (GBRA-50 G2a): initSchema sizing parameter (the source embedding layout sizes a fresh target); +1 #5984: upsertChunks guards pass the per-transaction config memo (transactionMemo in page-state/transactions.ts); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2920 measured); +4 P7 relationalChainHop delegate; +8 contributor audit wave P0: listFactsKeyset delegate (SQL in engine-sql/facts.ts); +1 #5375: get_versions limit/include_body type import (GetVersionsOpts, PageVersionRows); 6 #6085: initSchema pins advisory lock 42, bootstrap, schema replay and unlock to one reserved backend when the DDL pool has more than one slot (gauge only, no long-hold permit), released in finally; wave 10 collector: lane E (#6085), lane G (#5375) and master compose at 2939; +2 #6110: search transactions pass jitOff to withScopedReadTransaction (SET LOCAL jit = off in postgres-engine/search-settings.ts); +2 #5984 lane apply diet: putPage/setPageAliases write inline in the caller's page transaction (engine methods cannot move); +1 #5984 single-write fast path composes with the lane apply diet at 2944; +2 #5984 shared parameter types: the instance pool passes shared_types and initSchema clears them after migrations (helpers in db.ts); +2 #6276: the remote alias-resolving readPageSnapshot runs with JIT off (withScopedReadTransaction jitOff); +5 #6278: executeRaw timeoutMs delegate (statement in postgres-engine/bounded-statement.ts); +23 #6278 PR 1.5: cancelSettleMs() and the settle timer in runUnsafe that discards a reserved connection whose cancel a transaction-mode pooler never completed; +3 #6317 lane 2: getPoolDiagnostics().pool from the vendored driver (postgres-engine/pool-stats.ts) and the prepare mark; +4 GBRA-69: replaceDerivedLinksBatch delegate (logic in derived-links.ts); +1 GBRA-69 extract batching: replaceDerivedLinksBatch delegate (batch logic in derived-links.ts); +9 GBRA-75: getBacklinkCounts and getHealth statements run JIT-off through the private jitOffRead transaction helper (engine methods cannot move); +3 GBRA-75 wave 7: searchKeyword and searchVector start the once-per-engine background search statistics guard (logic in search/projection-statistics.ts); +7 GBRA-67: readPageSnapshotsBatch scoped-read delegate (batch logic in page-snapshot-batch.ts); +1 GBRA-75 wave 10: findDuplicatePages scoped-read delegate (SQL in engine-sql/pages.ts); +7 #6383: poolIncidents hooks on the instance/module/connection-manager pools (counter and lines in pool-gauge.ts, budget in db.ts) and stuckDiscards/buildFailures in getPoolDiagnostics; +3 GBRA-76: transaction/transactionDirect take TransactionOptions; transactionOn attaches the begin handle to withTransactionAbort (logic in postgres-engine/transaction-abort.ts); +2 W14 P3.12 (#4772): entityTypes HealthDeps delegate + import on top of W13; +1 #5227: schema.sql replay under withSchemaLockTimeout (wave 14 PR1); +1 driver desync tripwire: desyncDiscards in getPoolDiagnostics (counter and line in pool-gauge.ts); +11 Cat 40 Hard fix wave F2 (#6271) on top: countKeywordPages/searchKeywordPages scoped-read delegations (SQL in engine-sql/keyword-pages.ts) and the rankQuery score parameter (3027 measured); +3 W15 P1.2 (#6454): three one-line stale-frontmatter-key delegates, reads scoped (SQL in engine-sql/pages.ts); +12 wave 16 G5.1 (#6495): keywordStatementTimeout memo field, its connect/disconnect resets and the keywordStatementTimeoutSetting accessor, plus one awaited setting per keyword/chunk/CJK transaction (resolver in postgres-engine/keyword-statement-timeout.ts); wave 16 G5.1 gate fix: keywordStatementTimeoutSetting resolves the knob once per connection on the first keyword statement from the saved connect config (connect issues no statement for it; 3042 measured); +7 large pages Wave A sub-a: getChunkPage scoped-read delegate (SQL in engine-sql/chunks.ts); +11 #6696 B3: readEmbeddingStateCounts/listEmbeddingStateRows delegations + type import; +22 Wave B lane 1a: segmented page storage delegations (allocateBodyOccurrenceIds..sweepSegments, SQL in engine-sql/page-body.ts) and their imports; +3 wave 18b lane 2 (#6495): keywordTimeouts negative-cache field and the searchKeyword runner wrap (logic in postgres-engine/keyword-timeout-cache.ts); integrated at wave 18b: master 3082 + 3; +3 PR2 fix lane B: logIngest stamps writer_version/writer_host_id/writer_segment_reader and getIngestLog names its columns (engine methods cannot move); integrated at the Wave B PR 2 master merge (v0.60.264.0): master 3085 + 3; +3 PR2 fix lane E (E1): getChunks/getChunkPage/getChunkWindows run the manifest privilege probe in their scoped transaction (chunkManifestReads in search/safe-chunks.ts); integrated at the lane E merge onto b75a69a6d: 3088 + 3; +6 PR2 fix lane X: searchVector, explainVectorSearch, the hasMore witness and runVectorAttempt pick the chunk-manifest statement form inside each bounded attempt transaction, so its statement_timeout bounds the probe (form memo vectorStatementForms in search/vector-statement.ts; engine methods cannot move): 3091 + 6; +5 PR2 fix lane X: keywordBoundedRead runs the read in withScopedReadTransaction under the keyword statement timeout setting (engine methods cannot move): 3097 + 5; +2 GBRA-130 B-6 (#6860): putDreamVerdict passes its payload through wellFormedJson (engine methods cannot move); +1 GBRA-130 A-1: held option on the stale-page list/count signatures (SQL in engine-sql/pages.ts); +1 GBRA-130 integration: the A-1 (links_extract_failure) and B-6 (wellFormedJson putDreamVerdict) engine hunks composed at the lane merge; +2 #6948: putPage runs assertOriginUnclaimed in its page transaction and restorePage runs assertRevivalUnclaimed (logic in persistence/origin-guard.ts; engine methods cannot move): 3102 + 2; GBRA-130 composed with #6948 at the master 0e0cd27b merge: re-summed to the merged line count (3107); +3 #7159: the frontmatter where clause in the two keyword typesClause sites and its import (SQL in search/frontmatter-where.ts; engine methods cannot move); GBRA-156 retrieval wave (#7201) composed with #7194 at the merge: re-summed (3114 measured); +2 warm CLI socket (#7218): connectedDatabaseUrl getter (the URL the engine connected with, bound into the socket identity), composed over the GBRA-156 retrieval wave (3116 measured); +1 GBRA-133 PR 2b: transactionOn hands the outermost transaction its commit checks (page-state/transactions.ts withCommitChecks), composed with the warm CLI socket at the merge (3117 measured); +18 GBRA-156: the private readTransaction helper behind withScopedReadTransaction and jitOffRead answers a top-level read before its COMMIT settles (engine methods cannot move; 3135 measured); +1 GBRA-156: transactionOn and runUnsafe hold a per-search connection slot (import of search/connection-budget.ts; 3136 measured); +2 GBRA-156: transactionOn passes TransactionOptions.pipelineFirst to the pool begin as { first } (driver gate in vendor/postgres index.js begin); an engine method cannot move; composed with the warm CLI socket and GBRA-133 PR 2b at the master v0.60.344.0 merge (3119 measured); GBRA-151 #7183/#7187/#7188 re-summed at the v0.60.402.0 merge (3135 measured); +2 #7183 (GBRA-151) at the v0.60.412.0 merge: read-write-transactions import and transactionOn wraps its connection in readWriteTransactions (logic in postgres-engine/read-write-transactions.ts; engine methods cannot move): 3135 + 2; +7 GBRA-156: transactionOn opens readOnly transactions as BEGIN READ ONLY and a top-level read inherits its request signal, runUnsafe refuses an aborted request (logic in request-signal.ts; engine methods cannot move): 3137 + 7; +3 GBRA-156 keyword OR rarity: the import and the searchKeyword OR retry through rankOrFallbackByRarity (logic in search/keyword-or-rarity.ts; engine methods cannot move); +2 wave-b PR 4 merged with #7218 (both sides added imports); re-summed at the Wave B PR 4 merge with v0.60.452.0 (3155 measured); +2 GBRA-283 Wave A (#8460): the ENGINE_ROOT import and field (engine identity for per-engine caches; class fields cannot move); +7 GBRA-283 B1 review: the instance pool passes settings connection fields explicitly, initSchema reads the embedding identity again under the schema lock, and reconnect ends the superseded manager (engine methods cannot move); re-summed at the train R merge with v0.60.574.0: 3170 + 4; +4 #6318: withScopedReadTransaction runs a bounded preparation's read under its deadline (read-deadline.ts; reserved-connection envelope runDeadlineRead in postgres-engine/bounded-statement.ts) and adds statement_timeout to the transaction settings (engine methods cannot move): re-summed at the 0.60.583.0 merge: 3174 + 4; +2 TLS default: the pg-tls import and the instance pool builds its options through withPgTls and turns a no-TLS refusal into postgres_tls_required (logic in pg-tls.ts; engine methods cannot move): 3178 + 2; +2 #7776 (GBRA-404 salvage): the schema-client-behind import and its assertSchemaNotAhead call in initSchema, re-summed on master 78419f76 (3179 + 2); +1 #9295: wantedProducers option on the listStalePagesForExtraction delegate signature (engine methods cannot move); +6 GBRA-574 B2: mergeOntologyFact clears the slot of a conversation fact that holds the observation's exact stint key before it inserts (engine methods cannot move; predicate in chronicle/ontology.ts)+src/core/postgres-engine.ts 3190 ratchet +9 #7191: findPages/countPagesBy scoped-read delegates and imports (SQL in engine-sql/page-lookup.ts); +6 GBRA-283 B1 (#8455): an engine opened from settings routes its direct URL and statement-description cache from its settings, and initSchema seeds settings.embedding and refuses a mismatch (logic in embedded-engine.ts; engine methods cannot move); +1 System One v1 evals: search arms clamp to searchLimitCap() (import of search/eval-pool-depth.ts; eval-only --eval-pool-depth, production cap unchanged); refactor wave 1 split target (W1 engine-sql); ceiling rationale: docs/architecture/key-files/engines-2.md entry for src/core/postgres-engine.ts; evidence delivery: getChunkWindows scoped-read delegate + type import (+5; SQL in engine-sql/chunks.ts); #5761: +4 markPagesAttendanceBlocked delegate (SQL in engine-sql/pages.ts); +10 eval wave N1-2/N1-3: mergeOntologyFact same-stint noop check + ontology visibility filter in the grandfathered ontology methods; lowered to 3242 #5824: searchVector SQL moved to search/vector-statement.ts, +explainVectorSearch/runVectorAttempt (-156); +6 #5730: onpoisoned wiring on the instance/module/connection-manager pools + poisonedDiscards in getPoolDiagnostics (counter in pool-gauge.ts); +5 #5801: onCheckout observer seam (fires after reserve resolution / transaction-callback entry; listeners in pool-gauge.ts); lowered to 3119 #5889: searchTitles SQL moved to engine-sql/titles.ts (-133); lowered to 2914 F4a: getHealth SQL moved to engine-sql/health.ts (-216); +2 #5984: transactions track held page guards like PGLite (withHeldPageKeys), so repeated guards in one transaction cost no round trips; +1 #5984: traceSqlOptions import for the env-gated GBRAIN_SQL_TRACE bench hook (src/core/sql-trace.ts); v0.60.48.0 merge: #5984 growth re-summed over v0.60.47.0 (2917 measured); +2 engine graduation (GBRA-50 G2a): initSchema sizing parameter (the source embedding layout sizes a fresh target); +1 #5984: upsertChunks guards pass the per-transaction config memo (transactionMemo in page-state/transactions.ts); v0.60.58.0 merge: #5984 diet growth re-summed over v0.60.57.0 (2920 measured); +4 P7 relationalChainHop delegate; +8 contributor audit wave P0: listFactsKeyset delegate (SQL in engine-sql/facts.ts); +1 #5375: get_versions limit/include_body type import (GetVersionsOpts, PageVersionRows); 6 #6085: initSchema pins advisory lock 42, bootstrap, schema replay and unlock to one reserved backend when the DDL pool has more than one slot (gauge only, no long-hold permit), released in finally; wave 10 collector: lane E (#6085), lane G (#5375) and master compose at 2939; +2 #6110: search transactions pass jitOff to withScopedReadTransaction (SET LOCAL jit = off in postgres-engine/search-settings.ts); +2 #5984 lane apply diet: putPage/setPageAliases write inline in the caller's page transaction (engine methods cannot move); +1 #5984 single-write fast path composes with the lane apply diet at 2944; +2 #5984 shared parameter types: the instance pool passes shared_types and initSchema clears them after migrations (helpers in db.ts); +2 #6276: the remote alias-resolving readPageSnapshot runs with JIT off (withScopedReadTransaction jitOff); +5 #6278: executeRaw timeoutMs delegate (statement in postgres-engine/bounded-statement.ts); +23 #6278 PR 1.5: cancelSettleMs() and the settle timer in runUnsafe that discards a reserved connection whose cancel a transaction-mode pooler never completed; +3 #6317 lane 2: getPoolDiagnostics().pool from the vendored driver (postgres-engine/pool-stats.ts) and the prepare mark; +4 GBRA-69: replaceDerivedLinksBatch delegate (logic in derived-links.ts); +1 GBRA-69 extract batching: replaceDerivedLinksBatch delegate (batch logic in derived-links.ts); +9 GBRA-75: getBacklinkCounts and getHealth statements run JIT-off through the private jitOffRead transaction helper (engine methods cannot move); +3 GBRA-75 wave 7: searchKeyword and searchVector start the once-per-engine background search statistics guard (logic in search/projection-statistics.ts); +7 GBRA-67: readPageSnapshotsBatch scoped-read delegate (batch logic in page-snapshot-batch.ts); +1 GBRA-75 wave 10: findDuplicatePages scoped-read delegate (SQL in engine-sql/pages.ts); +7 #6383: poolIncidents hooks on the instance/module/connection-manager pools (counter and lines in pool-gauge.ts, budget in db.ts) and stuckDiscards/buildFailures in getPoolDiagnostics; +3 GBRA-76: transaction/transactionDirect take TransactionOptions; transactionOn attaches the begin handle to withTransactionAbort (logic in postgres-engine/transaction-abort.ts); +2 W14 P3.12 (#4772): entityTypes HealthDeps delegate + import on top of W13; +1 #5227: schema.sql replay under withSchemaLockTimeout (wave 14 PR1); +1 driver desync tripwire: desyncDiscards in getPoolDiagnostics (counter and line in pool-gauge.ts); +11 Cat 40 Hard fix wave F2 (#6271) on top: countKeywordPages/searchKeywordPages scoped-read delegations (SQL in engine-sql/keyword-pages.ts) and the rankQuery score parameter (3027 measured); +3 W15 P1.2 (#6454): three one-line stale-frontmatter-key delegates, reads scoped (SQL in engine-sql/pages.ts); +12 wave 16 G5.1 (#6495): keywordStatementTimeout memo field, its connect/disconnect resets and the keywordStatementTimeoutSetting accessor, plus one awaited setting per keyword/chunk/CJK transaction (resolver in postgres-engine/keyword-statement-timeout.ts); wave 16 G5.1 gate fix: keywordStatementTimeoutSetting resolves the knob once per connection on the first keyword statement from the saved connect config (connect issues no statement for it; 3042 measured); +7 large pages Wave A sub-a: getChunkPage scoped-read delegate (SQL in engine-sql/chunks.ts); +11 #6696 B3: readEmbeddingStateCounts/listEmbeddingStateRows delegations + type import; +22 Wave B lane 1a: segmented page storage delegations (allocateBodyOccurrenceIds..sweepSegments, SQL in engine-sql/page-body.ts) and their imports; +3 wave 18b lane 2 (#6495): keywordTimeouts negative-cache field and the searchKeyword runner wrap (logic in postgres-engine/keyword-timeout-cache.ts); integrated at wave 18b: master 3082 + 3; +3 PR2 fix lane B: logIngest stamps writer_version/writer_host_id/writer_segment_reader and getIngestLog names its columns (engine methods cannot move); integrated at the Wave B PR 2 master merge (v0.60.264.0): master 3085 + 3; +3 PR2 fix lane E (E1): getChunks/getChunkPage/getChunkWindows run the manifest privilege probe in their scoped transaction (chunkManifestReads in search/safe-chunks.ts); integrated at the lane E merge onto b75a69a6d: 3088 + 3; +6 PR2 fix lane X: searchVector, explainVectorSearch, the hasMore witness and runVectorAttempt pick the chunk-manifest statement form inside each bounded attempt transaction, so its statement_timeout bounds the probe (form memo vectorStatementForms in search/vector-statement.ts; engine methods cannot move): 3091 + 6; +5 PR2 fix lane X: keywordBoundedRead runs the read in withScopedReadTransaction under the keyword statement timeout setting (engine methods cannot move): 3097 + 5; +2 GBRA-130 B-6 (#6860): putDreamVerdict passes its payload through wellFormedJson (engine methods cannot move); +1 GBRA-130 A-1: held option on the stale-page list/count signatures (SQL in engine-sql/pages.ts); +1 GBRA-130 integration: the A-1 (links_extract_failure) and B-6 (wellFormedJson putDreamVerdict) engine hunks composed at the lane merge; +2 #6948: putPage runs assertOriginUnclaimed in its page transaction and restorePage runs assertRevivalUnclaimed (logic in persistence/origin-guard.ts; engine methods cannot move): 3102 + 2; GBRA-130 composed with #6948 at the master 0e0cd27b merge: re-summed to the merged line count (3107); +3 #7159: the frontmatter where clause in the two keyword typesClause sites and its import (SQL in search/frontmatter-where.ts; engine methods cannot move); GBRA-156 retrieval wave (#7201) composed with #7194 at the merge: re-summed (3114 measured); +2 warm CLI socket (#7218): connectedDatabaseUrl getter (the URL the engine connected with, bound into the socket identity), composed over the GBRA-156 retrieval wave (3116 measured); +1 GBRA-133 PR 2b: transactionOn hands the outermost transaction its commit checks (page-state/transactions.ts withCommitChecks), composed with the warm CLI socket at the merge (3117 measured); +18 GBRA-156: the private readTransaction helper behind withScopedReadTransaction and jitOffRead answers a top-level read before its COMMIT settles (engine methods cannot move; 3135 measured); +1 GBRA-156: transactionOn and runUnsafe hold a per-search connection slot (import of search/connection-budget.ts; 3136 measured); +2 GBRA-156: transactionOn passes TransactionOptions.pipelineFirst to the pool begin as { first } (driver gate in vendor/postgres index.js begin); an engine method cannot move; composed with the warm CLI socket and GBRA-133 PR 2b at the master v0.60.344.0 merge (3119 measured); GBRA-151 #7183/#7187/#7188 re-summed at the v0.60.402.0 merge (3135 measured); +2 #7183 (GBRA-151) at the v0.60.412.0 merge: read-write-transactions import and transactionOn wraps its connection in readWriteTransactions (logic in postgres-engine/read-write-transactions.ts; engine methods cannot move): 3135 + 2; +7 GBRA-156: transactionOn opens readOnly transactions as BEGIN READ ONLY and a top-level read inherits its request signal, runUnsafe refuses an aborted request (logic in request-signal.ts; engine methods cannot move): 3137 + 7; +3 GBRA-156 keyword OR rarity: the import and the searchKeyword OR retry through rankOrFallbackByRarity (logic in search/keyword-or-rarity.ts; engine methods cannot move); +2 wave-b PR 4 merged with #7218 (both sides added imports); re-summed at the Wave B PR 4 merge with v0.60.452.0 (3155 measured); +2 GBRA-283 Wave A (#8460): the ENGINE_ROOT import and field (engine identity for per-engine caches; class fields cannot move); +7 GBRA-283 B1 review: the instance pool passes settings connection fields explicitly, initSchema reads the embedding identity again under the schema lock, and reconnect ends the superseded manager (engine methods cannot move); re-summed at the train R merge with v0.60.574.0: 3170 + 4; +4 #6318: withScopedReadTransaction runs a bounded preparation's read under its deadline (read-deadline.ts; reserved-connection envelope runDeadlineRead in postgres-engine/bounded-statement.ts) and adds statement_timeout to the transaction settings (engine methods cannot move): re-summed at the 0.60.583.0 merge: 3174 + 4; +2 TLS default: the pg-tls import and the instance pool builds its options through withPgTls and turns a no-TLS refusal into postgres_tls_required (logic in pg-tls.ts; engine methods cannot move): 3178 + 2; +2 #7776 (GBRA-404 salvage): the schema-client-behind import and its assertSchemaNotAhead call in initSchema, re-summed on master 78419f76 (3179 + 2); +1 #9295: wantedProducers option on the listStalePagesForExtraction delegate signature (engine methods cannot move); +6 GBRA-574 B2: mergeOntologyFact clears the slot of a conversation fact that holds the observation's exact stint key before it inserts (engine methods cannot move; predicate in chronicle/ontology.ts); +2 Rust engine plan PR 5: capabilities field and its import (table in engine-capabilities.ts; class fields cannot move); re-summed at the rust-engine/core merge with master (3190 measured)src/core/search/hybrid.ts 1562 ratchet +5 GBRA-81 item 5 per-stage search timings: HybridSearchOpts._timings (interface field) and the timer bindings and import in hybridSearch/hybridSearchCached (collector logic in search/stage-timings.ts); +2 W5 page-unit ranking cut: HybridSearchOpts.pageRankCut (logic in search/page-rank-cut.ts); +9 W3 confidence-gated reranking: HybridSearchOpts.rerankGate and the gate/lookup threading through rerankAndPin and sizeReturnPool (logic in search/hybrid/rerank-gate.ts, crag.ts gradePreRerank); re-summed at the W3 merge onto master v0.60.168.0 (1641 measured); +2 System One v1: HybridSearchOpts.decide (search/decide-stage.ts); refactor wave 1 split target (W4 hybrid, cut line); ceiling rationale: docs/architecture/key-files/core-search-1.md entry for src/core/search/hybrid.ts; +10 #5691: per-request embedding_query_prefix read once and threaded to the embeds and cache key; +5 green master wave (embedding opt-out): HybridSearchOpts._embeddingOptedOut (interface field) read once per request and threaded to the cache-lookup embed and the keyword-only gate; +24 P2 explain RRF attribution stamp in rrfFusionWeighted, backlink_count stamp, explain_target stage observations, explain/explainTarget opts; +14 fix wave 13 P4.8 #6400: lazyQueryEmbedDeadline (the query-embed deadline starts when the embed starts) and the _queryEmbedDeadline getter; +1 query facts arm: HybridSearchOpts.onQueryEmbedding (interface field; its one-line call is paid inside the ceiling) after the vector arms, so the facts arm reuses the query embedding without a second model call; re-summed at the master a08578ca5 merge (1591 master lines + 3 integration lines: the onQueryEmbedding hook); lowered to 1562: LHF wave 2 item 3 peeled cosineReScore into search/cosine-rescore.tssrc/core/types.ts 2365 ratchet +2 GST-2951: OntologyReadOpts.excludeDiary (interface field + doc; diary rows dropped before resolution in both engines); +2 GBRA-504 slice 3: SearchResult.guest (interface field; logic in guests/marker.ts); +2 #8664 agent label: WriteAttributionView.agent_label (+ its doc line; the header, record and read live in persistence/attribution.ts and ops/attribution.ts) +3 train R: #7491 SearchOpts identifier-probe field and #7175 keywordPhrase option (interface fields); +2 GBRA-154 #7175: SearchOpts.keywordPhrase (opt-in phrase factor); +4 Wave B PR 1 (1c): Page.body_storage/body_bytes (interface fields; guard logic in page-body/page-shape.ts); +8 W3 confidence-gated reranking: HybridSearchMeta.rerank_gate (RerankGateMeta in search/hybrid/rerank-gate.ts); re-summed at the W3 merge onto master v0.60.168.0 (2279 measured); +7 fix wave 11 W6.2/W6.3 (#5989, #6132): SearchOpts.hnswIterativeScan and cjkKeyword, the keyword_candidates_incomplete stage and HybridSearchMeta.keyword_candidates (logic in engine-sql/cjk-search.ts); +5 System One v1 retrieval lane: SearchResult injection_p/injection_suspected, HybridSearchMeta answerability, egress_denied degraded reason; +4 System One v1: SearchResult rerank_score_kind/decide_evidence, HybridSearchMeta decide/rerank; +3 wave review: PAGE_SORT_SQL.updated_asc source_id + id tiebreakers (total order under federated scopes); +5 #4881: OntologyReadOpts extends PageReadScope doc; +3 #4857: PAGE_SORT_SQL.slug total-order tiebreaker comment; grown v0.46.26.0 megawave: EvidenceOpts, pacing/usage result fields, PageFilters growth (#4352 #4218); wave-k: +9 SalienceOpts/AnomaliesOpts source scope (#3867); +20 2026-09 adversarial batch 2: keyword_relaxed_carried stage + relaxed_dropped meta field docs; +16 2026-09 fix wave: SearchResult.keyword_relaxed field + full fusion-demotion doc; (#3867); +9: #4648 rerank_passthrough degraded stage + empty_result_set/malformed_shape reasons | merged v0.48.1.0 true-up; +master v0.48 merge true-up (reranker succession: no_key preflight, reranker_skipped stage, readiness); corrective release: shared internal PageReadScope and PageReadPolicy; ranker wave v0.48.4.0: HybridSearchMeta relational_rerank_pin / keyword_arm_confidence / metadata_boost_gate + SearchResult.relational_pinned (+48 over master's peel); +12: #4681 Page.updated_at_iso + keyset cursor precision docs; #5105: canonical page state shared module and transaction/snapshot delegates; #5105: public page revision fields; upstream integration: preserve independently reviewed master additions with branch facade extraction; #5252 wave: typed vector pool and readiness metadata; merged company ingestion/schema routing changes; retired provider integration removed; +1 write-path wave: 'created' effective-date source; +3 read-path wave: rerank_failed degraded stage + budget reason (closed vocabularies) and its recall classification note; +8 fw3-search: SearchOpts.source_boosts + keyword_arm_failed/title_arm_failed stages; +2 wave-2 W4: ChunkInput.embedding_input_hash (#5553); fix wave 3 x fix wave 2 (v0.60.5.0) composition: +2 at the merge; evidence delivery: optional SearchResult.delivered (+2; shape in search/evidence-delivery.ts); +2 eval wave N1-3: OntologyReadOpts.visibility (remote world-only ontology reads); +4 #5827: GraphNode.source_id and GraphPath from_source_id/to_source_id; +2 #5824: SearchOpts.vectorLegacyGuard rollback switch; +7 #5154: PageFilters.listColumnsOnly (interface field); +11 Foundations 1 F1b: WriteAttributionView + AttributedPageVersion (get_versions / get_write_attribution read shapes); +1 #5988: SearchResult.stale carries the held-file detail (interface field); +6 retrieval feedback: SearchResult feedback_boost/content_hash/relational_path_edges stamps and RelationalFanoutRow.path_edges (interface fields); +2 RelationalFanoutOpts.wide (interface field); 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); P3 x P7 (v0.60.60.0) composition: deltas re-summed at the merge; 1 GBRA-49: temporal annotation field on link rows; +44 P7 ChainHopOpts/ChainHopEdge chain-hop contract types; P7 SearchResult.relational evidence + RelationalEvidence type + relational_plan meta + planner per-call overrides; +2 P7 SearchOpts.relationalChainSlots per-call override; +1 P7 ChainHopOpts.temporal (relationship-validity policy per hop); +1 green master wave: embedding_disabled degraded reason (closed vocabulary); +2 #5951: Chunk.source_id (get_chunks names each row's source); 1 P2 SearchResult explain fields (rrf attribution, blend_norm_rrf, score_details, backlink_count) + RrfAttribution (interface fields); +11 #5575 (L1b): PageReadScope minTrust/suppressFlagged, SearchResult trust_tier/origin/unconfirmed, TimelineOpts eligibility (interface fields cannot move); +8 #4772 (W14 PR3): BrainHealth.entity_types_status field (interface fields cannot move); +1 C4: question page type row; +6 entity anchoring: optional SearchResult.entity_anchored row stamp (logic in search/entity-anchor.ts); +4 query facts arm: optional SearchResult.fact_row and superseded_claim row fields (logic in search/facts-arm.ts); +2 query facts arm: SearchResult result_type/fact_id/page_slug/follow_up (fact rows are never page-shaped); +9 Cat 40 Hard fix wave (#6271): SearchResult matched_alias/evidence_omitted/provenance, SearchOpts.rankQuery, keyword_count_unavailable stage and rerank_failed reasons; +12 fix wave 15 P2.1 (#6500): PageFilters.slugAfter (single-source slug keyset, interface field + doc) and the updated_desc tiebreaker comment (the keyset walk lives in facts/conversation-enumeration.ts); +2 wave 16 G5.1 (#6495): EngineConfig.keyword_statement_timeout_ms (interface field + doc); +2 GBRA-92: EngineConfig.pglite_shared_buffers (interface field + doc); +11 large pages (Wave A): Chunk/ChunkInput projected_byte_start/end interface fields (span logic in chunkers/recursive.ts, page-window/document.ts); +4 wave 18b lane 2 (#6495): SearchOpts.keywordTimeoutCache, the skipped_after_timeout degraded reason and the useCache doc line; integrated at wave 18b: master 2319 + 4; +2 LHF wave 2 item 3: retrieval meta cosine_rescore field (js_fallback disclosure; logic in search/cosine-rescore.ts); +14 GBRA-154 ranking wave (#4612 #7153 #7156 #7162 #7164): SearchResult collapsed/redirect_to/image_page/rank_prior/rank_score/fused_score stamps and HybridSearchMeta.collapse (interface fields; logic in search/collapse.ts, rank-priors.ts, score-contract.ts); GBRA-151 retrieval P0 x operability wave merge: both sides grew the file, re-summed (2343 measured); GBRA-156 retrieval wave (#7201) composed with #7194 at the merge: re-summed (2345 measured); GBRA-151 #7147 follow-up re-summed at the v0.60.338.0 merge (2347 measured); +2 GBRA-95 G7a follow-up: Page.withheld_source_path field; +2 #7600: SearchResult.quoted (interface field; logic in search/transcript-quote.ts); +1 #8377: ChronicleTimelineRow.trust_tier (interface field; chronicle reads quote rows by tier); re-summed at the train R merge with v0.60.574.0: 2354 + 1; re-measured at the Train A merge of #8943: 2361src/core/minions/queue.ts 2574 ratchet grown #4078 + megawave probe-liveness unlatch (#4310) + master private-queue lifecycle: recovery classifier + monotonic lease; security: durable queued authority and confined filesystem dispatch; master integration: grown #4078 + megawave probe-liveness unlatch (#4310) + master private-queue lifecycle: recovery classifier + monotonic lease; harness support: boundary wiring to shared grants, isolated setup, withdrawal and delegated guards; merged v0.49: durable authority and delegated admission both enforced; typed readiness, configuration-blocked lifecycle and bounded release; +9: prune archives completed dream synthesis keys; +18 Lane D: deferJob (a deferral returns a job to delayed with no attempt counted and no stacktrace growth); the ceiling had 17 lines of slack; +5 agent operator follow-up Item 5 merged over master: claim-time spend fence token and legacy_default stamp (logic in minions/spend-authorization.ts); +5 GBRA-130 A-30: claim excludeWatchdogSuspects option (signature, doc and the mark parameter), the releaseWatchdogClaim delegate, and the co-runner stall call site in handleStalled (logic in minions/watchdog-attribution.ts); +5 GBRA-158 #7239/#7240: failJob result parameter (the #7216 hunk), jsonbSafeJson import and its call in add (sanitizer in text-safe.ts); +2 #7242 lane reservation: claim excludeNames option (doc line and the bound array; policy in minions/lanes.ts); +1 #7241 submitter label import (job-insight.ts) + 1 queue-families type import; #7252 x #7249 merge: both sides grew the file, re-summed (2544 measured); +3 GBRA-133: the stall sweep deletes a drain-lease holder record whose lease lock is gone or expired; +1 GST-2260: retryOnStalePlan import for completeJob/failJob (helper in retry-matcher.ts); +1 persistence train: add refuses a child under a finished parent (#8909); +9 GST-2529: the claim builds its parameters once for the overdue-suspect drain (a marked job past the worker's wait stops a busy worker claiming and leads an idle one's order); +16 GST-2529: hasOverdueWatchdogSuspect and overdueSuspectSql, the probe the worker runs every 5 s so a claim with no overdue marked job keeps the claim index orderdiff --git a/scripts/persistence/crash-robot.ts b/scripts/persistence/crash-robot.tsindex b0d98a25ef..9bae7f56fc 100644--- a/scripts/persistence/crash-robot.ts+++ b/scripts/persistence/crash-robot.ts@@ -13,6 +13,7 @@ import { join } from 'node:path';import type { BrainEngine } from '../../src/core/engine.ts';import type { GBrainConfig } from '../../src/core/config.ts';import { PGLiteEngine } from '../../src/core/pglite-engine.ts';+import { sqlEngineKind } from '../../src/core/sql-engine-kind.ts';import { PostgresEngine } from '../../src/core/postgres-engine.ts';import { disposePersistenceConsumer, startPersistenceConsumer } from '../../src/core/persistence/service.ts';import { installFaultHook, type FaultDetail, type FaultPoint } from '../../src/core/persistence/fault-points.ts';@@ -94,7 +95,7 @@ export async function settlePending(world: World, model: ReferenceModel): Promis}/** Finish a schedule: drain, check drained invariants, prove a fresh write still admits, and drain that write's effects. */-export async function finish(world: World, model: ReferenceModel, label: string, drainMs: number = DRAIN_BOUND_MS[world.engine.kind]): Promise<void> {+export async function finish(world: World, model: ReferenceModel, label: string, drainMs: number = DRAIN_BOUND_MS[sqlEngineKind(world.engine.kind, 'crash robot')]): Promise<void> {const drained = await drain(world.engine, world, drainMs);if (!drained) model.violate({ class: 'wedge', detail: `${label}: requests or effects did not drain within ${drainMs / 1000} s` });await settlePending(world, model);@@ -490,7 +491,7 @@ export async function robotWorker(role: 'count' | 'run' | 'recover', config: Robmodel.beginStep(inFlight.length > 1);model.allowInFlight(inFlight); model.relaxInFlight(inFlight);await model.checkGlobal('after SIGKILL, before recovery');- const bound = DRAIN_BOUND_MS[engine.kind];+ const bound = DRAIN_BOUND_MS[sqlEngineKind(engine.kind, 'crash robot')];const drained = await drain(engine, world, bound);if (!drained) model.violate({ class: 'wedge', detail: `recovery: requests or effects did not drain within ${bound / 1000} s after restart` });await model.checkDrained('recovered');diff --git a/src/commands/doctor/checks/graph-embedding.ts b/src/commands/doctor/checks/graph-embedding.tsindex 904eff376b..4848d8ef32 100644--- a/src/commands/doctor/checks/graph-embedding.ts+++ b/src/commands/doctor/checks/graph-embedding.ts@@ -4,6 +4,7 @@* under its original name (tests and external callers import them from* doctor.ts) and buildChecks / doctorReportRemote consume them.*/+import { sqlEngineKind } from '../../../core/sql-engine-kind.ts';import { loadConfigFileOnly } from '../../../core/config.ts';import { DEFAULT_MAX_COST_USD, findUnpricedBrainstormChatModel } from '../../../core/brainstorm/cost-gate.ts';import { pricingSetCommand } from '../../../core/budget/no-pricing.ts';@@ -312,7 +313,7 @@ export async function checkEmbeddingWidthConsistency(engine: BrainEngine): PromirequestedDims: configDim,requestedModel: resolvedModel,source: 'doctor',- engineKind: engine.kind,+ engineKind: sqlEngineKind(engine.kind, 'doctor embedding check'),databasePath,});return {diff --git a/src/commands/embed.ts b/src/commands/embed.tsindex 8add4aef3b..dd7ee46673 100644--- a/src/commands/embed.ts+++ b/src/commands/embed.ts@@ -1,3 +1,4 @@+import { sqlEngineKind } from '../core/sql-engine-kind.ts';import { jsonRequested } from '../core/cli-force-exit.ts';import { prepareProseChunks } from '../core/markdown-chunks.ts';import type { FenceChunkOverlay } from '../core/eligibility/fence-overlay.ts';@@ -441,7 +442,7 @@ async function preflightDimMismatch(engine: BrainEngine, dryRun: boolean): PromirequestedDims: resolvedDims,requestedModel: resolvedModel,source: 'embed',- engineKind: engine.kind,+ engineKind: sqlEngineKind(engine.kind, 'gbrain embed'),databasePath,});throw new EmbeddingDimMismatchError(recipe);diff --git a/src/commands/eval-longmemeval.ts b/src/commands/eval-longmemeval.tsindex fc92f8b5bc..a96465d855 100644--- a/src/commands/eval-longmemeval.ts+++ b/src/commands/eval-longmemeval.ts@@ -140,7 +140,7 @@ import { resolveModel } from '../core/model-config.ts';import type { ThinkLLMClient } from '../core/think/index.ts';import { createProgress } from '../core/progress.ts';import { getCliOptions, cliOptsToProgressOptions } from '../core/cli-options.ts';-import type { PGLiteEngine } from '../core/pglite-engine.ts';+import type { BrainEngine } from '../core/engine.ts';import type { HybridSearchMeta, SearchResult } from '../core/types.ts';import { classifyIntent, type Intent } from '../eval/longmemeval/intent.ts';import { makeGatewayThinkClient } from '../eval/longmemeval/gateway-client.ts';@@ -509,10 +509,10 @@ export interface RunOpts {* call (tests amortize the PGLite cold-create across many runs). MUST be* the result of createBenchmarkBrain(); the caller owns lifecycle.*/- engine?: PGLiteEngine;+ engine?: BrainEngine;/** #5092 test seams: brain recycle interval and factory (harness-owned brain only). */brainRecycleEvery?: number;- createBrain?: () => Promise<PGLiteEngine>;+ createBrain?: () => Promise<BrainEngine>;/*** Live nightly-probe search-mode/reranker settings copied into the isolated* benchmark brain (#3676). Explicit pin flags (--mode/--reranker/--autocut/@@ -528,7 +528,7 @@ export interface RunOpts {*/embedTransport?: EmbedTransportFn | null;/** Test seam: reranker readiness probe behind `--reranker on` (default rerankerReadinessForEngine). */- rerankerReadiness?: (engine: PGLiteEngine, model: string) => Promise<EngineReadiness>;+ rerankerReadiness?: (engine: BrainEngine, model: string) => Promise<EngineReadiness>;/** Test seam: directory for the `--record` ledger (default <repo>/.gbrain-evals/). */recordDir?: string;/** Test seam: the judge chat client behind `--judge` (default: the gateway `chat`). */@@ -1145,7 +1145,7 @@ export async function runEvalLongMemEval(args: string[], runOpts: RunOpts = {}):embedTxn: (fn) => fn(),};- const configureBrain = async (engine: PGLiteEngine): Promise<void> => {+ const configureBrain = async (engine: BrainEngine): Promise<void> => {// #3676: nightly probe callers may copy audited live search config into// this isolated engine. Data tables stay hermetic.for (const [key, value] of Object.entries(runOpts.searchConfigSnapshot ?? {})) {@@ -1167,7 +1167,7 @@ export async function runEvalLongMemEval(args: string[], runOpts: RunOpts = {}):if (decideRun) await decideLane.configureDecideBrain(engine, decideRun);};- const work = async (engine: PGLiteEngine): Promise<void> => {+ const work = async (engine: BrainEngine): Promise<void> => {await configureBrain(engine);// Resolved reranker pin on (flag, --search-pin, snapshot or bundle):@@ -1362,7 +1362,7 @@ export async function runEvalLongMemEval(args: string[], runOpts: RunOpts = {}):async function runOneQuestion(- engine: PGLiteEngine,+ engine: BrainEngine,q: DatasetQuestion,ctx: RunContext,): Promise<QuestionOutcome> {diff --git a/src/commands/migrate-engine.ts b/src/commands/migrate-engine.tsindex 24ed92a787..e70774da23 100644--- a/src/commands/migrate-engine.ts+++ b/src/commands/migrate-engine.ts@@ -9,6 +9,7 @@ import { assertLegacyEngineMigration, assertUnmanagedCanonicalWriter } from '../*/import { opError } from '../core/ops/contract.ts';+import { sqlEngineKind } from '../core/sql-engine-kind.ts';import { ItemRun } from '../core/item-failure.ts';import { createEngine } from '../core/engine-factory.ts';import { loadConfig, saveConfig, toEngineConfig, gbrainPath, effectiveEnvDatabaseUrl, type GBrainConfig } from '../core/config.ts';@@ -910,8 +911,9 @@ function reportLoopRowFailures(tables: Record<string, MigrateSimpleTableResult>,export async function runMigrateEngine(sourceEngine: BrainEngine, args: string[]): Promise<void> {const opts = parseArgs(args);+ const sourceKind = sqlEngineKind(sourceEngine.kind, 'gbrain migrate'); // SQL on both sides: a Rust source refuses before any read.await assertWindowsGraduationPlatform(sourceEngine, opts);- const migration = { from: sourceEngine.kind, to: opts.targetEngine };+ const migration = { from: sourceKind, to: opts.targetEngine };await assertUnmanagedCanonicalWriter(sourceEngine, 'engine migration', { migration: { side: 'source', ...migration } });await assertLegacyEngineMigration(sourceEngine, { side: 'source', ...migration });const config = loadConfig();diff --git a/src/commands/sync/gitignore.ts b/src/commands/sync/gitignore.tsindex 212ddca1de..351356b52c 100644--- a/src/commands/sync/gitignore.ts+++ b/src/commands/sync/gitignore.ts@@ -14,7 +14,7 @@ import { discoverGitRoot } from '../../core/sync-git.ts';* consult for the repo-level db_only rules. Best-effort: falls back to the* given path when git discovery fails (manageGitignore no-ops on non-repos).*/-export function manageGitignoreAtGitRoot(path: string, engineKind?: 'pglite' | 'postgres'): void {+export function manageGitignoreAtGitRoot(path: string, engineKind?: 'pglite' | 'postgres' | 'rust'): void {let root = path;try { root = discoverGitRoot(path); } catch { /* best-effort */ }try { manageGitignore(root, engineKind); }@@ -59,7 +59,7 @@ export function __resetPGLiteTierWarn(): void {export function manageGitignore(repoPath: string,- engineKind?: 'pglite' | 'postgres',+ engineKind?: 'pglite' | 'postgres' | 'rust',): void {if (process.env.GBRAIN_NO_GITIGNORE === '1') {return;diff --git a/src/core/db-lock.ts b/src/core/db-lock.tsindex 41eb9cf75f..cb7ea50099 100644--- a/src/core/db-lock.ts+++ b/src/core/db-lock.ts@@ -24,6 +24,8 @@import { hostname } from 'os';import { randomUUID } from 'node:crypto';import type { BrainEngine } from './engine.ts';+import { capabilityMissing } from './rust-engine/errors.ts';+import { isRustEngineKind } from './sql-engine-kind.ts';import { retryReadOnlyAutocommit } from './postgres-engine/read-write-transactions.ts';import { noteDirectPoolLease } from './direct-pool-profile.ts';@@ -375,6 +377,8 @@ export async function tryAcquireDbLock(};}+ // Cycle locks live in a SQL table; the Rust engine gets typed leases later (plan, "Cycle locks").+ if (isRustEngineKind(engine.kind)) throw capabilityMissing('raw_sql', 'cycle lock');throw new Error(`Unknown engine kind for db-lock: ${engine.kind}`);};@@ -623,6 +627,8 @@ async function selectLockRows(engine: BrainEngine, opts: SelectLockRowsOpts = {}rows = (await maybePGLite.db.query(`SELECT ${LOCK_SELECT_COLS} FROM gbrain_cycle_locks ORDER BY acquired_at`)).rows as RawLockRow[];}} else {+ // Cycle locks live in a SQL table; the Rust engine gets typed leases later (plan, "Cycle locks").+ if (isRustEngineKind(engine.kind)) throw capabilityMissing('raw_sql', 'cycle lock read');throw new Error(`Unknown engine kind for selectLockRows: ${engine.kind}`);}@@ -711,6 +717,8 @@ export async function deleteLockRow();return { deleted: rows.length > 0 };}+ // Cycle locks live in a SQL table; the Rust engine gets typed leases later (plan, "Cycle locks").+ if (isRustEngineKind(engine.kind)) throw capabilityMissing('raw_sql', 'cycle lock');throw new Error(`Unknown engine kind for deleteLockRow: ${engine.kind}`);}@@ -797,6 +805,8 @@ export async function deleteLockRowIfStale(const lastRefreshed = lr == null ? null : (lr instanceof Date ? lr : new Date(lr));return { deleted: true, lastRefreshedAt: lastRefreshed };}+ // Cycle locks live in a SQL table; the Rust engine gets typed leases later (plan, "Cycle locks").+ if (isRustEngineKind(engine.kind)) throw capabilityMissing('raw_sql', 'cycle lock');throw new Error(`Unknown engine kind for deleteLockRowIfStale: ${engine.kind}`);}@@ -1123,8 +1133,8 @@ export async function buildTenantLockId(engine: BrainEngine, scope: string): Proconst dbname = rows[0]?.db || 'unknown';return `${scope}:${dbname}`;}- // PGLite is single-tenant by construction; suffix is cosmetic.- return `${scope}:pglite`;+ // PGLite and the Rust engine are single-tenant by construction; the suffix is cosmetic.+ return `${scope}:${isRustEngineKind(engine.kind) ? 'rust' : 'pglite'}`;} catch {return `${scope}:unknown`;}diff --git a/src/core/embed-backfill-submit.ts b/src/core/embed-backfill-submit.tsindex a8c36e3925..851fd162c7 100644--- a/src/core/embed-backfill-submit.ts+++ b/src/core/embed-backfill-submit.ts@@ -67,7 +67,7 @@ export type SubmitEmbedBackfillResult =| { status: 'spend_capped'; spend24hUsd: number; spendCapUsd: number }/** #6803: the last EMBED_BACKFILL_STALL_LIMIT backfills failed identically with nothing embedded, and nothing has changed since. */| { status: 'stalled'; failures: number; remaining: number; blocked: number; lastFailedAt: string }- | { status: 'no_worker_surface'; engineKind: 'pglite' | 'unknown' }+ | { status: 'no_worker_surface'; engineKind: 'pglite' | 'rust' | 'unknown' }/** The brain is keyless by choice: nothing to embed. `notice` is set only the first time for this brain state. */| { status: 'embedding_disabled'; notice: Notice | null };diff --git a/src/core/engine-capabilities.ts b/src/core/engine-capabilities.tsnew file mode 100644index 0000000000..d4b92efc45--- /dev/null+++ b/src/core/engine-capabilities.ts@@ -0,0 +1,123 @@+/**+ * Engine capabilities: what a storage engine can do, by name.+ *+ * `BrainEngine.capabilities` is the read-only set an engine reports. PGLite and+ * Postgres report everything they have today; a new engine (the optional Rust+ * engine, docs/designs/RUST_ENGINE.md "Capability gating") reports only what it+ * implements, and callers ask for a capability instead of branching on+ * `engine.kind`.+ *+ * `REQUIRED_CAPABILITIES` records what each operation, CLI command, cycle phase+ * and minion handler needs. Anything not listed needs `raw_sql`, so an engine+ * without raw SQL refuses it until its row says otherwise. On PGLite and+ * Postgres every lookup passes: both report every capability a row can name,+ * except the engine-specific `single_owner` and `postgres_admin`.+ */++export const ENGINE_CAPABILITIES = [+ // Raw SQL entry points: executeRaw, executeRawDirect, withReservedConnection.+ // The Rust engine never reports it (D18: no SQL dialect).+ 'raw_sql',++ // Subsystems that still reach the database through raw SQL.+ 'persistence_journal',+ 'minion_queue',+ 'access_control',+ 'belief_ledger',+ /** One owner process hosts the brain and other processes are its clients. */+ 'single_owner',+ /** Postgres server administration: pooler, roles, server settings and statistics. */+ 'postgres_admin',++ // Typed BrainEngine storage domains.+ 'schema',+ 'transactions',+ 'sources',+ 'config',+ 'pages',+ 'page_versions',+ 'page_body',+ 'tags',+ 'chunks',+ 'embeddings',+ 'keyword_search',+ 'vector_search',+ 'links',+ 'timeline',+ 'graph',+ 'facts',+ 'takes',+ 'files',+ 'code_edges',+ 'salience',+ 'health',+ 'raw_data',+ 'eval_capture',+ 'ingest_log',+ 'dream_verdicts',+ 'contradictions',+ 'ontology',+] as const;++export type Capability = (typeof ENGINE_CAPABILITIES)[number];++/** The read-only capability set an engine reports. */+export type EngineCapabilities = ReadonlySet<Capability>;++/** Engine kinds whose capability set is known without opening the engine. */+export type SqlEngineKind = 'pglite' | 'postgres';++const ENGINE_ONLY: Readonly<Record<SqlEngineKind, readonly Capability[]>> = {+ pglite: ['single_owner'],+ postgres: ['postgres_admin'],+};++const ENGINE_SPECIFIC = new Set<Capability>(Object.values(ENGINE_ONLY).flat());++/**+ * The full capability set PGLite or Postgres reports: every shared capability+ * plus its own engine-specific ones. Returns a fresh set, so one engine can+ * never change another engine's answer.+ */+export function capabilitiesForEngineKind(kind: SqlEngineKind): EngineCapabilities {+ const caps = new Set<Capability>(ENGINE_CAPABILITIES.filter(c => !ENGINE_SPECIFIC.has(c)));+ for (const c of ENGINE_ONLY[kind]) caps.add(c);+ return caps;+}++export function hasCapability(engine: { readonly capabilities: EngineCapabilities }, capability: Capability): boolean {+ return engine.capabilities.has(capability);+}++/** The surfaces that dispatch work onto an engine. */+export type CapabilityConsumer = 'operation' | 'command' | 'phase' | 'handler';++/**+ * What each operation (`src/core/operations.ts` name), CLI command record+ * (`src/cli/command-table.ts` name), cycle phase and minion handler needs.+ * An entry is added only once its whole path is proven to run without raw SQL;+ * until then it is absent and needs `raw_sql`.+ */+export const REQUIRED_CAPABILITIES: Readonly<Record<CapabilityConsumer, Readonly<Record<string, readonly Capability[]>>>> = {+ operation: {},+ command: {},+ phase: {},+ handler: {},+};++const RAW_SQL_ONLY: readonly Capability[] = Object.freeze(['raw_sql'] as Capability[]);++/** The capabilities `name` needs. An unlisted name needs `raw_sql`. */+export function requiredCapabilities(consumer: CapabilityConsumer, name: string): readonly Capability[] {+ const table = REQUIRED_CAPABILITIES[consumer];+ return Object.prototype.hasOwnProperty.call(table, name) ? table[name]! : RAW_SQL_ONLY;+}++/** The capabilities `name` needs that `engine` does not report, in table order. Empty means it can run. */+export function missingCapabilities(+ engine: { readonly capabilities: EngineCapabilities },+ consumer: CapabilityConsumer,+ name: string,+): Capability[] {+ return requiredCapabilities(consumer, name).filter(c => !engine.capabilities.has(c));+}diff --git a/src/core/engine.ts b/src/core/engine.tsindex 94a6c48b7e..a9aa5b1b23 100644--- a/src/core/engine.ts+++ b/src/core/engine.ts@@ -1,4 +1,5 @@import type { PageKey, PageSnapshot, PageSnapshotOptions, PageWriteOptions } from './page-state/types.ts';+import type { EngineCapabilities } from './engine-capabilities.ts';import type { GetVersionsOpts, PageVersionRows } from './page-state/version-types.ts';import type { PageSnapshotBatch } from './page-snapshot-batch.ts';import type { LinkReadScope } from './link-validity.ts';@@ -832,6 +833,7 @@ export function clampSearchLimit(limit: number | undefined, defaultLimit = 20, cexport interface BrainEngine {/** Discriminator: lets migrations and other consumers branch on engine kind without instanceof + dynamic imports. */readonly kind: 'postgres' | 'pglite';+ readonly capabilities: EngineCapabilities; // what this engine can do, by name (engine-capabilities.ts); ask it instead of branching on kind// Lifecycleconnect(config: EngineConfig): Promise<void>;diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex ec11b1072e..6794c4a498 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -14,6 +14,7 @@*/import type { Action, Actor, Effect, ErrorClass } from './agent-output.ts';import { FENCE_REASON_CODES } from './fence-repair/reasons.ts';+import { ENGINE_CAPABILITIES } from './engine-capabilities.ts';export interface CodeEntry {class: ErrorClass;@@ -77,6 +78,8 @@ export const CODES = {autopilot_pglite_daemon: { class: 'caller', summary: 'gbrain autopilot --install refused on a PGLite brain: a daemon would hold the single-writer lock all day and block every other gbrain process.', why: 'PGLite has one writer. gbrain serve owns the lock and runs the resident sweep; free upkeep runs through gbrain maintain --unattended.', suggestion: 'Run gbrain serve. Check upkeep with gbrain maintain --status. For a dedicated-brain daemon, re-run gbrain autopilot --install --force.' },cycle_already_running: { class: 'retryable', summary: 'Another maintenance cycle holds the brain cycle lock, so this run skipped instead of waiting.', why: 'Cycles serialize on the gbrain-cycle lease; the holder releases it when it finishes (or its TTL lapses after a crash).', suggestion: 'Wait for the other cycle; unattended upkeep retries on its next turn (gbrain maintain --status shows the last skip).' },engine_degraded: { class: 'unavailable', summary: 'The brain database was unreachable (the engine is in degraded mode), so background work such as unattended upkeep skipped this run.', why: 'A degraded engine answers from its last state and reconnects on its own; writing maintenance results then would be lost or refused.', suggestion: 'Run gbrain doctor --json and report the connection problem it names.' },+ rust_engine_addon_missing: { class: 'unavailable', actor: 'user', retryable: true, reasons: ['unsupported_target', 'not_installed', 'override_not_found'], summary: 'The Rust engine is selected (engine: rust), but no addon for this gbrain release is installed on this machine, or no addon is published for this platform, so gbrain opened nothing and wrote nothing.', why: 'The Rust engine ships as a separate addon file kept in the gbrain home, checked against the checksum in this release\'s manifest before it loads. Without a checked addon the engine cannot open, and gbrain refuses before touching the brain.', suggestion: 'Point GBRAIN_RUST_ENGINE_ADDON at an addon you built with bun run rust:build, or switch engine in the gbrain config back to pglite or postgres.' },+ rust_engine_addon_mismatch: { class: 'unavailable', actor: 'user', retryable: false, reasons: ['digest', 'engine_abi', 'engine_build', 'target', 'load_failed'], summary: 'The Rust engine addon on this machine does not match what this gbrain release expects (checksum, engine_abi, engine_build or target), so it was not used and gbrain wrote nothing.', why: 'A different addon build could read or write the brain with a different on-disk format, so only the addon the running release names, with the checksum in its manifest, is loaded. A file that fails the check is left as it was.', suggestion: 'Rebuild the addon with bun run rust:build and point GBRAIN_RUST_ENGINE_ADDON at the path it prints, or install the gbrain release that matches the addon, or switch engine in the gbrain config back to pglite or postgres.' },maintenance_disabled: { class: 'caller', exit: 0, summary: 'Free unattended upkeep is off on this brain (maintenance.auto is false), so nothing ran.', why: 'The person turned upkeep off; doctor reads it as off, not stale.', suggestion: 'Turn it back on with gbrain config set maintenance.auto true.' },maintenance_owned_by_serve: { class: 'caller', exit: 0, summary: 'A live gbrain serve owns this brain and runs free upkeep while idle, so the scheduled upkeep run did nothing (serve owns upkeep).', why: 'One runner at a time: the serve holds the brain (the PGLite lock, or the warm CLI socket on Postgres) and runs the same free upkeep on its idle tick.', suggestion: 'Nothing to do; gbrain maintain --status shows the last run and its runner.' },schedule_unsupported: { class: 'caller', reasons: ['windows', 'container', 'mount'], summary: 'gbrain maintain --schedule installed nothing: on Windows and in containers it has no installer, and it schedules the host brain only.', why: 'Windows gets the schtasks line to add by hand (minimal Windows support). In a container an operating-system schedule does not survive a redeploy, so the resident gbrain serve is the upkeep runner there. The scheduled job runs without --brain, so a mounted brain gets no schedule.', suggestion: 'On Windows, add the printed schtasks line yourself. In a container, keep gbrain serve running; it runs free upkeep while idle. For a mounted brain, schedule gbrain --brain <id> maintain --unattended yourself.' },@@ -348,6 +351,7 @@ export const CODES = {engine_scope_missing: { class: 'caller', summary: "An engine opened from settings made an AI call (embed, chat, expansion or rerank) through a provider its settings.ai does not name, or after it was disconnected, so nothing was sent.", why: "An embedded engine's AI calls reach only the providers and keys its host passed as values. Falling back to a process.env key, ~/.gbrain/config.json or the process-wide gateway would spend another brain's key and send this brain's text where its host never pointed it.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Pass the provider in settings.ai.providers (apiKey, and baseUrl when it is not the default) to openEngine, or point settings.ai.models (or settings.embedding) at a provider the engine has.' },engine_scope_required: { class: 'caller', summary: "An AI call (embed, chat, expansion or rerank) ran outside any engine scope while this process holds engines opened from settings, so nothing was sent.", why: "With no scope the call's brain is unknown. Using the process gateway, a process.env key or ~/.gbrain/config.json would spend a key no brain's host gave and could send one brain's text where its host never pointed it, so the call refuses whatever process gateway the host configured.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Run the call inside withEngineScope(engine, fn) for the engine it belongs to, or withLocalScope(fn) for a call that belongs to the process gateway (both exported from gbrain/engine-open).' },engine_settings_invalid: { class: 'caller', summary: "A setting passed to openEngine is missing or malformed (engine kind, database url or path, pool size, host or writer id, writer credential or lane, embedding identity), so nothing was opened or registered.", docs: 'docs/ENGINES.md#opening-an-engine-from-settings-experimental', suggestion: 'Correct the setting the message names and call again.' },+ engine_capability_missing: { class: 'caller', retryable: false, reasons: ENGINE_CAPABILITIES, summary: "The brain's engine does not implement the capability this call needs (reason names it), so the call was refused before any work and nothing was written.", why: 'The Rust engine preview grows one capability at a time. A call that needs a capability it does not report is refused up front instead of running part of the way; detail names the member, the capability and whether anything was written (written=nothing unless the outcome is partial or unknown).', docs: 'docs/ENGINES.md#the-rust-engine-shell', suggestion: 'Run the call on a pglite or postgres brain, or wait for a gbrain release whose Rust engine reports the capability.' },engine_graduated: { class: 'caller', summary: "A client opened a PGLite brain that moved to Postgres; its old path holds a tombstone.", docs: 'docs/guides/move-to-postgres.md#graduated-datastore' },// wave 18b (GBRA-106) #4772: onboarding coverage checks read entity types from the active pack(s).entity_types_unavailable: { class: 'unavailable', summary: "A schema pack in scope did not load, so the entity page types are unknown; onboarding's entity_link_coverage and timeline_coverage warn instead of grading the old hardcoded type list.",diff --git a/src/core/migrate.ts b/src/core/migrate.tsindex e737c89672..31b8c410c2 100644--- a/src/core/migrate.ts+++ b/src/core/migrate.ts@@ -544,8 +544,8 @@ async function runMigrationsLocked(engine: BrainEngine): Promise<{ applied: numb/** One migration's full body (SQL + handler + verify), extracted so the* runMigrations loop can name the failing migration in quiet-replay mode. */async function applyOneMigration(engine: BrainEngine, m: Migration): Promise<void> {- // Pick SQL: engine-specific `sqlFor` wins over engine-agnostic `sql`.- const sql = m.sqlFor?.[engine.kind] ?? m.sql;+ // Pick SQL: engine-specific `sqlFor` wins over `sql`; Rust has no dialect (D18) and its runMigration refuses raw_sql.+ const sql = (m.sqlFor as Partial<Record<string, string>> | undefined)?.[engine.kind] ?? m.sql;if (sql) {try {diff --git a/src/core/minions/embed-backfill-admission.ts b/src/core/minions/embed-backfill-admission.tsindex ca9e379ec3..dee84b2485 100644--- a/src/core/minions/embed-backfill-admission.ts+++ b/src/core/minions/embed-backfill-admission.ts@@ -6,13 +6,14 @@* config, policy, SQL, or transaction access.*/import type { BrainEngine } from '../engine.ts';+import type { EngineKind } from '../sql-engine-kind.ts';import { assertValidSourceId } from '../source-id.ts';export const EMBED_BACKFILL_JOB_NAME = 'embed-backfill';export type EmbedBackfillWorkerSurface =| { status: 'worker_backed'; engineKind: 'postgres' }- | { status: 'no_worker_surface'; engineKind: 'pglite' | 'unknown' };+ | { status: 'no_worker_surface'; engineKind: 'pglite' | 'rust' | 'unknown' };export interface EmbedBackfillAdmissionTrust {/** The caller starts and awaits an inline worker in this same process. */@@ -22,9 +23,10 @@ export interface EmbedBackfillAdmissionTrust {export function embedBackfillWorkerSurface(engine: Pick<BrainEngine, 'kind'>,): EmbedBackfillWorkerSurface {- const kind = engine.kind;+ const kind: EngineKind = engine.kind;if (kind === 'postgres') return { status: 'worker_backed', engineKind: 'postgres' };if (kind === 'pglite') return { status: 'no_worker_surface', engineKind: 'pglite' };+ if (kind === 'rust') return { status: 'no_worker_surface', engineKind: 'rust' };kind satisfies never;// Runtime defense for untyped plugins/casts whose value is outside the// declared union; the compile-time check above forces policy for new kinds.@@ -58,15 +60,17 @@ function assertEmbedBackfillSourceId(sourceId: unknown): asserts sourceId is strexport class NoEmbedBackfillWorkerSurfaceError extends Error {readonly code = 'no_worker_surface' as const;- readonly engineKind: 'pglite' | 'unknown';+ readonly engineKind: 'pglite' | 'rust' | 'unknown';readonly sourceId: string;- constructor(sourceId: string, engineKind: 'pglite' | 'unknown' = 'pglite') {+ constructor(sourceId: string, engineKind: 'pglite' | 'rust' | 'unknown' = 'pglite') {const source = sourceId || '<source-id>';const direct = embedBackfillManualDrainCommand(source);const surface = engineKind === 'pglite'? 'PGLite has no persistent worker surface'- : 'the runtime engine kind has no recognized persistent worker surface';+ : engineKind === 'rust'+ ? 'the Rust engine has no minion queue yet'+ : 'the runtime engine kind has no recognized persistent worker surface';super(`embed-backfill job rejected: ${surface}, so a queued row cannot drain. ` +`Run \`${direct}\` instead.`,diff --git a/src/core/ops/context.ts b/src/core/ops/context.tsindex 2a539da749..78e0862e35 100644--- a/src/core/ops/context.ts+++ b/src/core/ops/context.ts@@ -11,8 +11,9 @@*/import { lstatSync, realpathSync } from 'fs';-import { resolve, relative, sep } from 'path';+import { resolve, sep } from 'path';import { OperationError, opError } from './contract.ts';+import { resolvedPrefixContained } from '../path-confine.ts';import type { AuthInfo, Operation, OperationContext } from './contract.ts';import type { Action } from '../agent-output.ts';import { hostFix, invalidParam, paramUse, readFix } from './op-fix.ts';@@ -136,6 +137,16 @@ function migrationsFix(ctx: Pick<OperationContext, 'remote' | 'transport'>): Act// --- Upload validators (Fix 1 / B5 / H5 / M4) ---+/**+ * Strict-mode containment over two realpaths. Separator-aware: `..drafts/` is an+ * ordinary folder name, while `../`, another drive (Windows), a UNC share and a+ * sibling sharing the root's name prefix all fall outside. The root itself is+ * never an uploadable file. Pure, so tests can drive it with `path.win32` shapes.+ */+export function uploadPathInsideRoot(real: string, realRoot: string, sepChar: string): boolean {+ return real !== realRoot && resolvedPrefixContained(real, realRoot, sepChar);+}+/*** Validate an upload path. Two modes:* - strict (remote=true): confines the resolved path to `root` and rejects symlinks.@@ -178,7 +189,7 @@ export function validateUploadPath(filePath: string, root: string, strict = trueif (!strict) return real;- // Strict mode: confine to root via realpath + path.relative (catches parent-dir symlinks per B5).+ // Strict mode: confine to root by realpath on both sides (catches parent-dir symlinks per B5).let realRoot: string;try {realRoot = realpathSync(root);@@ -186,8 +197,7 @@ export function validateUploadPath(filePath: string, root: string, strict = truethrow opError('invalid_params', `Confinement root not accessible: ${root}`,"The upload root (the server's working directory) is unreadable on the brain host; tell the user so its operator can fix that directory.");}- const rel = relative(realRoot, real);- if (rel === '' || rel.startsWith('..') || rel.startsWith(`..${sep}`) || resolve(realRoot, rel) !== real) {+ if (!uploadPathInsideRoot(real, realRoot, sep)) {throw opError('invalid_params', `Upload path must be within the working directory: ${filePath}`,"Copy the file under the server's working directory and pass that path; a symlinked parent that resolves outside it is refused too.");}diff --git a/src/core/page-body/ingest.ts b/src/core/page-body/ingest.tsindex 495162a7e1..6d1f79c790 100644--- a/src/core/page-body/ingest.ts+++ b/src/core/page-body/ingest.ts@@ -22,7 +22,7 @@ import { readManagedMode } from '../persistence/managed-mode.ts';import { maintenanceAttribution, principalAttribution } from '../persistence/attribution.ts';import type { Principal } from '../persistence/model.ts';import { stepFenceWalk, type FenceWalk } from '../fence-scan.ts';-import { BODY_LEAD_BYTES, BODY_STAGING_HARD_MS, BODY_STAGING_IDLE_MS, PROJECTION_LOCK_HOLD_BYTES, SEGMENTED_CREATE_SEAL_MAX_BYTES, STAGE_BATCH_BYTES } from './limits.ts';+import { BODY_LEAD_BYTES, BODY_STAGING_HARD_MS, BODY_STAGING_IDLE_MS, PROJECTION_LOCK_HOLD_BYTES, SEGMENTED_CREATE_SEAL_MAX_BYTES, stageBatchBytes } from './limits.ts';import type { BodyRegion, BodyStagingKind, BodyStorage, JsonObject, ManifestRow, ManifestRowInput, SegmentChunkInput,SegmentedBodyColumns, SegmentTextInput } from './types.ts';import { regionTrust, segmentStream, SEGMENTER_VERSION, type StoredRegion } from './segmenter.ts';@@ -227,7 +227,7 @@ async function stageBody(engine: BrainEngine, input: SegmentedBodyInput, stagingif (same) same.push(row); else byKey.set(key, [row]);}const writes = await segmentWriteScope(engine, input.sourceId, { kind: input.owner.principalKind as Principal['kind'], id: input.owner.principalId });- const batchBytes = STAGE_BATCH_BYTES[engine.kind];+ const batchBytes = stageBatchBytes(engine.kind);const expectedGeneration = input.live?.generation ?? 0;const newGeneration = expectedGeneration + 1;const pageId = input.live?.id ?? 0;@@ -391,7 +391,7 @@ export async function stageOccurrenceChunks(engine: BrainEngine, input: { pageId/** The page's fence-chunk budget when one page is chunked over several calls (the re-chunk, page-body/rechunk.ts); default a new one. */fenceBudget?: FenceChunkBudget }): Promise<{ rows: number; occurrences: number; indexes: number[] }> {if (input.chunking.quarantined || !input.occurrences.length) return { rows: 0, occurrences: 0, indexes: [] };- const batchBytes = STAGE_BATCH_BYTES[engine.kind];+ const batchBytes = stageBatchBytes(engine.kind);const fenceBudget = input.fenceBudget ?? newFenceChunkBudget();let ledger: BodyLedger | undefined;let rows = 0, done = 0;@@ -467,7 +467,7 @@ export async function stageOccurrenceChunks(engine: BrainEngine, input: { pageIdexport async function* readSegmentedBody(engine: BrainEngine, pageId: number, sourceId: string,opts: { generation?: number; bodyBytes?: number } = {}): AsyncIterable<{ region: BodyRegion; bytes: Uint8Array }> {const { rows } = await readTiledManifest(engine, pageId, opts.generation, opts.bodyBytes);- const batchBytes = STAGE_BATCH_BYTES[engine.kind];+ const batchBytes = stageBatchBytes(engine.kind);for (let start = 0; start < rows.length;) {let end = start, bytes = 0;while (end < rows.length && (end === start || bytes + rows[end]!.byteLen <= batchBytes)) bytes += rows[end++]!.byteLen;diff --git a/src/core/page-body/limits.ts b/src/core/page-body/limits.tsindex a29c79e77e..27c84fd241 100644--- a/src/core/page-body/limits.ts+++ b/src/core/page-body/limits.ts@@ -12,6 +12,7 @@import type { BrainEngine } from '../engine.ts';import { PAGE_INLINE_MAX_BYTES, PAGE_MAX_BYTES } from '../page-size-policy.ts';import type { SegmentedGateWriter } from '../persistence/writer-versions.ts';+import { sqlEngineKind, type EngineKind } from '../sql-engine-kind.ts';export { PAGE_INLINE_MAX_BYTES };@@ -67,6 +68,11 @@ export const STAGE_BATCH_BYTES: Readonly<Record<'postgres' | 'pglite', number>>pglite: 4 * 1024 ** 2,};+/** STAGE_BATCH_BYTES for the engine's kind; a Rust brain stages no SQL rows, so it is refused (`engine_capability_missing`). */+export function stageBatchBytes(kind: EngineKind): number {+ return STAGE_BATCH_BYTES[sqlEngineKind(kind, 'page body staging')];+}+/*** Segment bytes one projection transaction chunks into rows while it holds the page's key lock (ingest.ts* `stageOccurrenceChunks`, guarded); an occurrence larger than this (up to SEGMENT_MAX_BYTES) goes alone, because andiff --git a/src/core/page-body/rechunk.ts b/src/core/page-body/rechunk.tsindex 7884379f1d..685b3fa57d 100644--- a/src/core/page-body/rechunk.ts+++ b/src/core/page-body/rechunk.ts@@ -20,7 +20,7 @@ import { maintenanceAttribution } from '../persistence/attribution.ts';import { applySegmentedBody, sealSegmentedPage } from '../persistence/segmented-apply.ts';import { withPageTierKept } from '../trust/fence-append.ts';import { openSegmentedStaging, segmentWriteScope, stageOccurrenceChunks } from './ingest.ts';-import { readPageBodyPolicy, STAGE_BATCH_BYTES } from './limits.ts';+import { readPageBodyPolicy, stageBatchBytes } from './limits.ts';import { SEGMENTED_CHUNKER_VERSION } from './segment-chunks.ts';import type { JsonObject, ManifestRow, SegmentChunkInput } from './types.ts';@@ -199,7 +199,7 @@ async function rechunkPage(engine: BrainEngine, id: number, apply: boolean, reti};const ref = { id: first.id, sourceId: first.source_id, slug: first.slug };const fenceBudget = newFenceChunkBudget();- const batchBytes = STAGE_BATCH_BYTES[engine.kind];+ const batchBytes = stageBatchBytes(engine.kind);const batches: ManifestRow[][] = [];for (let start = 0; start < rows.length;) {let end = start, bytes = 0;diff --git a/src/core/page-body/segment-rewrite.ts b/src/core/page-body/segment-rewrite.tsindex 22365731c9..7df1f0b620 100644--- a/src/core/page-body/segment-rewrite.ts+++ b/src/core/page-body/segment-rewrite.ts@@ -18,7 +18,7 @@ import { maintenanceAttribution } from '../persistence/attribution.ts';import { applySegmentedBody, sealSegmentedPage } from '../persistence/segmented-apply.ts';import { withPageTierKept } from '../trust/fence-append.ts';import { prepareSegmentedBody, readSegmentedBody, type SegmentedStagingOwner } from './ingest.ts';-import { FENCE_MAX_BYTES, readPageBodyPolicy, STAGE_BATCH_BYTES } from './limits.ts';+import { FENCE_MAX_BYTES, readPageBodyPolicy, stageBatchBytes } from './limits.ts';import { fenceTooLargeError } from './read-range.ts';import { pageBodySegmentedError } from './page-shape.ts';import { readEntryState } from './entry-state.ts';@@ -106,7 +106,7 @@ async function changedUnits(engine: BrainEngine, sourceId: string, rows: readonl/** One region of a generation's stored stream with the changed units replaced, read one segment batch at a time. */async function* rewrittenRegion(engine: BrainEngine, sourceId: string, rows: readonly ManifestRow[], units: readonly FenceUnit[], region: BodyRegion): AsyncIterable<Uint8Array> {const unitAt = new Map(units.map(unit => [unit.from, unit]));- const batchBytes = STAGE_BATCH_BYTES[engine.kind];+ const batchBytes = stageBatchBytes(engine.kind);let batch: ManifestRow[] = [], bytes = 0;async function* flush(): AsyncIterable<Uint8Array> {const texts = await engine.readSegmentTexts(sourceId, batch.map(row => row.sha256));diff --git a/src/core/page-body/splice.ts b/src/core/page-body/splice.tsindex 2f31fe92eb..12ba2be7c5 100644--- a/src/core/page-body/splice.ts+++ b/src/core/page-body/splice.ts@@ -27,7 +27,7 @@ import type { BrainEngine } from '../engine.ts';import { stableJson } from '../persistence/digest.ts';import { faultPoint } from '../persistence/fault-points.ts';import type { Principal } from '../persistence/model.ts';-import { BODY_LEAD_BYTES, STAGE_BATCH_BYTES } from './limits.ts';+import { BODY_LEAD_BYTES, stageBatchBytes } from './limits.ts';import type { BodyRegion, JsonObject, ManifestRow, ManifestRowInput, SegmentedBodyColumns, SegmentTextInput } from './types.ts';import { regionFlags, regionTrust, segmentStream, SEGMENTER_VERSION, type SegmentOut, type StoredRegion } from './segmenter.ts';import { isCleanResumePoint, readEntryState, timelineEntryState, type EntryState } from './entry-state.ts';@@ -159,7 +159,7 @@ async function rowAt(engine: BrainEngine, page: SplicePage, p: number): Promise<async function* virtualRegion(engine: BrainEngine, sourceId: string, rows: readonly ManifestRow[], reps: readonly BodyReplacement[], region: BodyRegion,regionOf: (r: BodyReplacement) => BodyRegion): AsyncIterable<Uint8Array> {const mine = rows.filter(row => row.region === region);- const batchBytes = STAGE_BATCH_BYTES[engine.kind];+ const batchBytes = stageBatchBytes(engine.kind);for (let i = 0; i < mine.length;) {let j = i, bytes = 0;while (j < mine.length && (j === i || bytes + mine[j]!.byteLen <= batchBytes)) bytes += mine[j++]!.byteLen;@@ -277,7 +277,7 @@ export async function spliceSegmentedBody(engine: BrainEngine, input: SegmentedSwhile (until < regionEnd && !touchedAt[until]!.touched) until++;for (let at = i; at < until;) {let to = at, bytes = 0;- while (to < until && (to === at || bytes + rows[to]!.byteLen <= STAGE_BATCH_BYTES[engine.kind])) bytes += rows[to++]!.byteLen;+ while (to < until && (to === at || bytes + rows[to]!.byteLen <= stageBatchBytes(engine.kind))) bytes += rows[to++]!.byteLen;const texts = await readTexts(engine, input.sourceId, rows.slice(at, to));for (const moved of rows.slice(at, to)) push(rowCore(moved), texts.get(hex(moved.sha256))!, { moved });at = to;diff --git a/src/core/persistence/engine-graduation.types.ts b/src/core/persistence/engine-graduation.types.tsindex c514cc9171..e1c56d656b 100644--- a/src/core/persistence/engine-graduation.types.ts+++ b/src/core/persistence/engine-graduation.types.ts@@ -92,7 +92,11 @@ export interface InventoryEntry {relation: string;kind: 'table' | 'view';class: InventoryClass;- engines: { pglite: boolean; postgres: boolean };+ /**+ * Which engines hold this relation. `rust` is false on every row until the Rust engine stores the relation+ * (docs/designs/RUST_ENGINE.md); a later PR that adds Rust storage for a relation flips its row.+ */+ engines: { pglite: boolean; postgres: boolean; rust: boolean };lossKind: LossKind;/** The only differences verify tolerates between source snapshot and target. */transforms: readonly ColumnTransform[];diff --git a/src/core/persistence/graduation-inventory.ts b/src/core/persistence/graduation-inventory.tsindex fd462b649a..54904f0d77 100644--- a/src/core/persistence/graduation-inventory.ts+++ b/src/core/persistence/graduation-inventory.ts@@ -11,11 +11,13 @@ import { LATEST_VERSION } from '../migrate.ts';import type { ColumnTransform, Inventory, InventoryClass, InventoryEntry, LossKind } from './engine-graduation.types.ts';type EngineKind = 'pglite' | 'postgres';+type InventoryEngines = InventoryEntry['engines'];-const BOTH = { pglite: true, postgres: true } as const;+// The Rust engine stores no relation yet, so every row says rust: false; a row that names its engines names all three.+const BOTH: InventoryEngines = { pglite: true, postgres: true, rust: false };function entry(relation: string, cls: InventoryClass, lossKind: LossKind, reason: string,- extra: { kind?: 'table' | 'view'; engines?: { pglite: boolean; postgres: boolean }; transforms?: ColumnTransform[]; rowFilter?: string } = {}): InventoryEntry {+ extra: { kind?: 'table' | 'view'; engines?: InventoryEngines; transforms?: ColumnTransform[]; rowFilter?: string } = {}): InventoryEntry {return {relation, kind: extra.kind ?? 'table', class: cls, engines: extra.engines ?? BOTH, lossKind,transforms: extra.transforms ?? [], ...(extra.rowFilter ? { rowFilter: extra.rowFilter } : {}), reason,@@ -232,8 +234,8 @@ export const GRADUATION_INVENTORY: Inventory = {entry('code_traversal_cache', 'rebuild', 'operational', 'Code traversal cache; regenerated on the target.'),entry('page_view_digests', 'rebuild', 'operational', 'get_page view sizes and sha256 of segmented pages per revision; recomputed by the next read on the target.'),- entry('planner_stats_deltas', 'discard', 'operational', 'PGLite-only planner accounting.', { engines: { pglite: true, postgres: false } }),- entry('planner_stats_state', 'discard', 'operational', 'PGLite-only planner accounting.', { engines: { pglite: true, postgres: false } }),+ entry('planner_stats_deltas', 'discard', 'operational', 'PGLite-only planner accounting.', { engines: { pglite: true, postgres: false, rust: false } }),+ entry('planner_stats_state', 'discard', 'operational', 'PGLite-only planner accounting.', { engines: { pglite: true, postgres: false, rust: false } }),entry('gbrain_cycle_locks', 'discard', 'operational', 'TTL run locks; every row is an orphan under the kernel lock.'),entry('budget_reservations', 'discard', 'operational', 'Daily-ledger holds (src/core/budget/daily-ledger.ts) that expire within minutes; budget_ledger carries the day\'s totals, so a hold dropped mid-graduation stays counted as reserved until its UTC day ends (only tightening that day\'s cap).'),entry('subagent_rate_leases', 'discard', 'operational', 'Job-owned concurrency leases that expire.'),@@ -243,7 +245,7 @@ export const GRADUATION_INVENTORY: Inventory = {entry('oauth_codes', 'discard', 'security', 'One-time authorization codes; an in-flight OAuth handshake restarts.'),entry('page_links', 'schema_owned', 'operational', 'View over links; each engine\'s schema defines it.', { kind: 'view' }),- entry('file_migration_ledger', 'schema_owned', 'operational', 'Postgres-only file storage migration ledger written by the target initSchema.', { engines: { pglite: false, postgres: true } }),+ entry('file_migration_ledger', 'schema_owned', 'operational', 'Postgres-only file storage migration ledger written by the target initSchema.', { engines: { pglite: false, postgres: true, rust: false } }),entry('trust_policy_state', 'schema_owned', 'operational', 'Each engine\'s own trust policy generation counter (#5575 ENG-11), seeded by its migration; caches compare it per engine, so it is never copied or compared.'),entry('persistence_graduation', 'schema_owned', 'operational', 'Each engine\'s own graduation custody row (source: quiesced/cutover; target: copying..authoritative); never copied, digested or compared.'),],diff --git a/src/core/persistence/graduation-verify.ts b/src/core/persistence/graduation-verify.tsindex b517e2deac..c03fe9b363 100644--- a/src/core/persistence/graduation-verify.ts+++ b/src/core/persistence/graduation-verify.ts@@ -8,6 +8,7 @@*/import type { BrainEngine } from '../engine.ts';import { OperationError } from '../ops/contract.ts';+import { sqlEngineKind } from '../sql-engine-kind.ts';import { admitWriteInTransaction, type WriteAdmission } from './journal.ts';import type { Principal, WriteAuthority } from './model.ts';import { readManagedMode } from './managed-mode.ts';@@ -279,7 +280,7 @@ async function chooseReplay(e: GraduationEngines, ctx: VerifyContext): Promise<Rexport async function verifyGraduation(e: GraduationEngines, ctx: VerifyContext): Promise<VerifyResult> {const failures: VerifyFailure[] = [];const batchRows = ctx.batchRows ?? DEFAULT_DIGEST_BATCH_ROWS;- for (const [engine, kind] of [[e.source, e.source.kind], [e.target, e.target.kind]] as const) {+ for (const [engine, kind] of [[e.source, sqlEngineKind(e.source.kind, 'graduation verify')], [e.target, sqlEngineKind(e.target.kind, 'graduation verify')]] as const) {try { await assertRelationSet(engine, kind, ctx.inventory); }catch (error) { failures.push({ relation: `(${kind} schema)`, kind: 'relation_set', detail: message(error) }); }}diff --git a/src/core/persistence/page-edit.ts b/src/core/persistence/page-edit.tsindex 8b164904f2..478c1730c9 100644--- a/src/core/persistence/page-edit.ts+++ b/src/core/persistence/page-edit.ts@@ -29,7 +29,7 @@ import type { StoredRegion } from '../page-body/segmenter.ts';import type { BodyReplacement, SplicePage } from '../page-body/splice.ts';import { spliceWork } from '../page-body/splice.ts';import { isSegmentedPage, withoutBody } from '../page-body/page-shape.ts';-import { STAGE_BATCH_BYTES } from '../page-body/limits.ts';+import { stageBatchBytes } from '../page-body/limits.ts';import { readEntryState } from '../page-body/entry-state.ts';import { hiddenBefore, openSegmentedBody, projectedLayout, trustedSegments, type SegmentedBody } from '../page-body/read-range.ts';import { storedWriterReadsHeld } from './page-visibility.ts';@@ -398,7 +398,7 @@ interface TextSource { sourceId: string; body?: SegmentedBody }async function* rowTexts(engine: BrainEngine, sourceId: string, rows: readonly ManifestRow[]): AsyncIterable<[ManifestRow, Uint8Array]> {for (let i = 0; i < rows.length;) {let j = i, bytes = 0;- while (j < rows.length && (j === i || bytes + rows[j]!.byteLen <= STAGE_BATCH_BYTES[engine.kind])) bytes += rows[j++]!.byteLen;+ while (j < rows.length && (j === i || bytes + rows[j]!.byteLen <= stageBatchBytes(engine.kind))) bytes += rows[j++]!.byteLen;const batch = rows.slice(i, j);const texts = await engine.readSegmentTexts(sourceId, batch.map(row => row.sha256));for (const row of batch) {diff --git a/src/core/pglite-engine.ts b/src/core/pglite-engine.tsindex 850abfe2a5..e9f68a42cc 100644--- a/src/core/pglite-engine.ts+++ b/src/core/pglite-engine.ts@@ -1,4 +1,5 @@import { registerManagedFilesystemEngine } from './persistence/filesystem-guard.ts';+import { capabilitiesForEngineKind, type EngineCapabilities } from './engine-capabilities.ts';import { writerStamp } from './persistence/writer-versions.ts';import { noteRequestConfigWrite, requestConfigRows, requestConfigValue } from './config-snapshot.ts';import { replaceDerivedLinks, replaceDerivedLinksBatch, type DerivedLinkBatchItem, type DerivedLinkOrigin, type DerivedLinkReplacementOptions } from './derived-links.ts';@@ -737,6 +738,7 @@ export class PGLiteEngine implements BrainEngine {private _chunkWritesInTransaction = false;private _checkpointGuard: PgliteCheckpointGuard | undefined;readonly kind = 'pglite' as const;+ readonly capabilities: EngineCapabilities = capabilitiesForEngineKind('pglite');private _db: PGLiteDB | null = null;private _lock: LockHandle | null = null;/** Graduation custody: a kernel lock this process already holds, adopted by the next open instead of acquired. */diff --git a/src/core/postgres-engine.ts b/src/core/postgres-engine.tsindex d699180086..1f3be53e09 100644--- a/src/core/postgres-engine.ts+++ b/src/core/postgres-engine.ts@@ -1,4 +1,5 @@import { tryAcquirePoolLongHold, PoolCapacityError } from './pool-budget.ts';+import { capabilitiesForEngineKind, type EngineCapabilities } from './engine-capabilities.ts';import { noteRequestConfigWrite, requestConfigRows, requestConfigValue } from './config-snapshot.ts';import { replaceDerivedLinks, replaceDerivedLinksBatch, type DerivedLinkBatchItem, type DerivedLinkOrigin, type DerivedLinkReplacementOptions } from './derived-links.ts';import { mutatePageTag } from './page-state/tags.ts';@@ -224,6 +225,7 @@ export class PostgresEngine implements BrainEngine {/** Transaction clones keep chunk invalidation and replacement atomic. */private _chunkWritesInTransaction = false;readonly kind = 'postgres' as const;+ readonly capabilities: EngineCapabilities = capabilitiesForEngineKind('postgres');private readonly _beforeDisconnect = new Set<() => Promise<void>>();private _disconnectPromise: Promise<void> | null = null;diff --git a/src/core/rust-engine.ts b/src/core/rust-engine.tsnew file mode 100644index 0000000000..d08cb43d41--- /dev/null+++ b/src/core/rust-engine.ts@@ -0,0 +1,98 @@+/**+ * The optional Rust engine shell (docs/designs/RUST_ENGINE.md, plan PR 8).+ *+ * `openRustEngine` is the one seam: the addon loader calls it after it has loaded and verified the native addon, and+ * gets back the engine. It has every BrainEngine member; its `kind` is `'rust'`, which `BrainEngine.kind` admits once+ * the `rust` config value lands with the addon loader. Selecting the engine, loading the addon and refusing a missing or mismatched addon live in+ * the loader, not here. The shell reports an empty capability set, so every BrainEngine member except the lifecycle+ * ones rejects with a typed `engine_capability_missing` naming the capability it needs (rust-engine/members.ts), before+ * any work. Later Rust PRs replace those refusals with typed methods one capability at a time.+ */+import type { BrainEngine } from './engine.ts';+import type { Capability, EngineCapabilities } from './engine-capabilities.ts';+import type { EngineConfig } from './types.ts';+import { capabilityMissing } from './rust-engine/errors.ts';+import { RUST_ENGINE_MEMBERS } from './rust-engine/members.ts';++/** The loaded, verified addon exports. Opaque to the shell: the typed methods later PRs add call into it. */+export type RustEngineAddonHandle = object;++export interface OpenRustEngineOptions {+ /** The addon exports, already loaded and checked (target, ABI, build) by the loader. */+ addon: RustEngineAddonHandle;+ /** Absolute path of the brain's store directory (the config's database_path). */+ databasePath: string;+}++/** Builds the Rust engine around an addon the loader has already verified. Nothing is opened or written yet. */+export function openRustEngine(opts: OpenRustEngineOptions): RustEngine {+ return new RustEngine(opts);+}++// The class implements the lifecycle members; the members it does not implement yet are installed on its prototype+// below from RUST_ENGINE_MEMBERS, so the interface half of this merge is honest about the full BrainEngine surface.+export interface RustEngine extends Omit<BrainEngine, 'kind'> {}+export class RustEngine {+ readonly kind = 'rust' as const;+ /** Empty until the Rust engine implements a capability with parity tests (plan PRs 9 onward). */+ readonly capabilities: EngineCapabilities = new Set();++ readonly addon: RustEngineAddonHandle;+ readonly databasePath: string;+ private _savedConfig: EngineConfig | null = null;+ private _connected = false;+ private readonly _beforeDisconnect = new Set<() => Promise<void>>();++ constructor(opts: OpenRustEngineOptions) {+ this.addon = opts.addon;+ this.databasePath = opts.databasePath;+ }++ /** True between `connect()` and `disconnect()`. */+ get connected(): boolean { return this._connected; }++ async connect(config: EngineConfig): Promise<void> {+ this._savedConfig = config;+ this._connected = true;+ }++ async disconnect(): Promise<void> {+ const stops = [...this._beforeDisconnect];+ this._beforeDisconnect.clear();+ for (const stop of stops) {+ try { await stop(); } catch { /* a stop barrier never blocks shutdown */ }+ }+ this._connected = false;+ }++ async reconnect(_ctx?: { error?: unknown }): Promise<void> {+ if (!this._savedConfig) return; // never connected; nothing to restore+ const config = this._savedConfig;+ await this.disconnect();+ await this.connect(config);+ }++ registerBeforeDisconnect(stop: () => Promise<void>): () => void {+ this._beforeDisconnect.add(stop);+ return () => { this._beforeDisconnect.delete(stop); };+ }+}++/** The capability a BrainEngine member needs on Rust, or null when the shell implements it. */+export function rustMemberCapability(member: string): Capability | null {+ const cls = (RUST_ENGINE_MEMBERS as Record<string, string>)[member];+ return cls === undefined || cls === 'implemented' ? null : (cls as Capability);+}++for (const [member, cls] of Object.entries(RUST_ENGINE_MEMBERS)) {+ if (cls === 'implemented') continue;+ const capability = cls as Capability;+ Object.defineProperty(RustEngine.prototype, member, {+ configurable: true,+ writable: true,+ enumerable: false,+ value: function refuse(this: RustEngine): Promise<never> {+ return Promise.reject(capabilityMissing(capability, member));+ },+ });+}diff --git a/src/core/rust-engine/addon-errors.ts b/src/core/rust-engine/addon-errors.tsnew file mode 100644index 0000000000..0403ac8481--- /dev/null+++ b/src/core/rust-engine/addon-errors.ts@@ -0,0 +1,19 @@+/**+ * The two refusals the Rust engine addon loader raises. Both are thrown before the brain is touched.+ * The suggestion is the registry's, so the CLI, the MCP envelope and the docs say the same thing.+ */+import { opError } from '../ops/contract.ts';+import { CODES } from '../error-registry.ts';++export type AddonMissingReason = (typeof CODES)['rust_engine_addon_missing']['reasons'][number];+export type AddonMismatchReason = (typeof CODES)['rust_engine_addon_mismatch']['reasons'][number];++/** Selected, but no addon for this release is installed, the override path is missing, or no addon is published for this target. */+export function addonMissing(reason: AddonMissingReason, message: string) {+ return opError('rust_engine_addon_missing', message, CODES.rust_engine_addon_missing.suggestion, { reason });+}++/** The addon is there but is not the build this release names (checksum, engine_abi, engine_build, target), or it does not load. */+export function addonMismatch(reason: AddonMismatchReason, message: string) {+ return opError('rust_engine_addon_mismatch', message, CODES.rust_engine_addon_mismatch.suggestion, { reason });+}diff --git a/src/core/rust-engine/addon-loader.ts b/src/core/rust-engine/addon-loader.tsnew file mode 100644index 0000000000..a940819572--- /dev/null+++ b/src/core/rust-engine/addon-loader.ts@@ -0,0 +1,175 @@+/**+ * Finds, checks and loads the Rust engine addon. Only the `rust` engine's open path may import it, lazily,+ * so a PGLite or Postgres brain never loads it and never creates `<gbrain home>/engines/`. The engine shell calls+ * {@link loadRustEngineAddon}.+ *+ * Order:+ * 1. GBRAIN_RUST_ENGINE_ADDON (an absolute path to a build you made with `bun run rust:build`) is the development+ * override. It skips only the release checksum pin; engine_abi and target are still checked.+ * 2. An addon at `<home>/engines/rust/<engine_build>/<target>.node` whose SHA-256 equals the cached manifest of this+ * gbrain version (`<home>/engines/rust/manifest-<version>.json`) loads. Nothing in gbrain writes that cache yet:+ * fetching the release addon into it comes later, with content-addressed paths.+ * 3. Otherwise it refuses with rust_engine_addon_missing (not_installed). It never reaches the network.+ *+ * Every failure is `rust_engine_addon_missing` or `rust_engine_addon_mismatch`, raised before the brain is touched.+ * The addon is loaded with process.dlopen from a computed path: a literal `require('x.node')` would be bundled+ * into compiled executables, and the addon must not be inside them.+ */+import { existsSync, readFileSync } from 'node:fs';+import { isAbsolute, join } from 'node:path';+import { gbrainPath } from '../config.ts';+import { VERSION } from '../../version.ts';+import { defaultComputeDigest } from '../binary-self-update.ts';+import { OperationError } from '../ops/contract.ts';+import { addonMismatch, addonMissing } from './addon-errors.ts';+import { parseRustAddonManifest, RELEASE_ADDON_TARGETS, RUST_ENGINE_ABI, type RustAddonManifest } from './addon-manifest.ts';+import { detectAddonTarget } from './addon-target.ts';++/** What the loader reads from the addon; the crate's exports (rust/crates/gbrain-napi) beyond these are for the engine. */+export interface RustAddon {+ target: string;+ engineAbi: number;+ engineBuild: string;+ catalogVersion: number;+ formatVersions: unknown[];+ [name: string]: unknown;+}++export interface RustAddonLoaderDeps {+ env: Record<string, string | undefined>;+ /** gbrain home's `engines/rust` directory. */+ rustDir: string;+ /** The running gbrain version; the cached manifest must name it. */+ version: string;+ /** This platform's addon target name, or null when it cannot be identified. */+ target: string | null;+ /** SHA-256 of a file, lowercase hex. */+ computeDigest(path: string): string;+ dlopen(path: string): unknown;+}++export function defaultRustAddonLoaderDeps(): RustAddonLoaderDeps {+ return {+ env: process.env,+ rustDir: gbrainPath('engines', 'rust'),+ version: VERSION,+ target: detectAddonTarget(),+ computeDigest: defaultComputeDigest,+ dlopen(path) {+ const module = { exports: {} as unknown };+ process.dlopen(module as NodeJS.Module, path);+ return module.exports;+ },+ };+}++/** `<home>/engines/rust/manifest-<version>.json`: the release manifest that names the cached addon. */+function cachedManifestPath(rustDir: string, version: string): string {+ return join(rustDir, `manifest-${version}.json`);+}++/** `<home>/engines/rust/<engine_build>/<target>.node` */+function addonPath(rustDir: string, engineBuild: string, target: string): string {+ return join(rustDir, engineBuild, `${target}.node`);+}++/** Reads the cached manifest, or null when it is absent, unreadable or for another version. */+function readCachedManifest(rustDir: string, version: string): RustAddonManifest | null {+ try {+ const manifest = parseRustAddonManifest(readFileSync(cachedManifestPath(rustDir, version), 'utf8'));+ return manifest && manifest.gbrain_version === version ? manifest : null;+ } catch {+ return null;+ }+}++interface Expected {+ target: string;+ /** Unset under the development override, which names no build to pin. */+ manifest?: RustAddonManifest;+}++function load(path: string, expected: Expected, deps: RustAddonLoaderDeps): RustAddon {+ let addon: RustAddon;+ try {+ addon = deps.dlopen(path) as RustAddon;+ } catch (err) {+ throw addonMismatch('load_failed', `The Rust engine addon at ${path} could not be loaded: ${err instanceof Error ? err.message : String(err)}.`);+ }+ if (addon?.engineAbi !== RUST_ENGINE_ABI) {+ throw addonMismatch('engine_abi', `The Rust engine addon at ${path} reports engine_abi ${String(addon?.engineAbi)}; this gbrain loads engine_abi ${RUST_ENGINE_ABI}.`);+ }+ if (addon.target !== expected.target) {+ throw addonMismatch('target', `The Rust engine addon at ${path} was built for ${String(addon.target)}; this machine is ${expected.target}.`);+ }+ if (expected.manifest && addon.engineBuild !== expected.manifest.engine_build) {+ throw addonMismatch('engine_build', `The Rust engine addon at ${path} is engine_build ${String(addon.engineBuild)}; the gbrain v${expected.manifest.gbrain_version} release names ${expected.manifest.engine_build}.`);+ }+ return addon;+}++/**+ * Loads the addon: the development override, else the cached addon whose SHA-256 matches the cached manifest.+ * It is async because the release fetch that comes later is; today it never waits on anything.+ */+export async function loadRustAddon(overrides: Partial<RustAddonLoaderDeps> = {}): Promise<RustAddon> {+ const deps: RustAddonLoaderDeps = { ...defaultRustAddonLoaderDeps(), ...overrides };++ const override = deps.env.GBRAIN_RUST_ENGINE_ADDON?.trim();+ if (override) {+ if (!isAbsolute(override) || !existsSync(override)) {+ throw addonMissing('override_not_found', `GBRAIN_RUST_ENGINE_ADDON is ${override}, which is not an existing absolute path to an addon file.`);+ }+ const target = deps.target;+ if (!target) throw addonMissing('unsupported_target', 'This machine\'s platform could not be identified, so no Rust engine addon can be chosen for it.');+ return load(override, { target }, deps);+ }++ const target = deps.target;+ if (!target || !RELEASE_ADDON_TARGETS.includes(target)) {+ throw addonMissing('unsupported_target', `No Rust engine addon is published for ${target ?? 'this platform'}; releases carry ${RELEASE_ADDON_TARGETS.join(' and ')}.`);+ }++ const cached = readCachedManifest(deps.rustDir, deps.version);+ const entry = cached?.targets[target];+ const path = cached && entry ? addonPath(deps.rustDir, cached.engine_build, target) : null;+ if (!cached || !entry || !path || !existsSync(path)) {+ throw addonMissing('not_installed', `No Rust engine addon for gbrain v${deps.version} on ${target} is installed in ${deps.rustDir}. Set GBRAIN_RUST_ENGINE_ADDON to a build from bun run rust:build.`);+ }+ let digest: string;+ try {+ digest = deps.computeDigest(path);+ } catch (err) {+ throw addonMismatch('digest', `The Rust engine addon at ${path} could not be read to check its SHA-256: ${err instanceof Error ? err.message : String(err)}.`);+ }+ if (digest !== entry.sha256) {+ throw addonMismatch('digest', `The Rust engine addon at ${path} has SHA-256 ${digest}; the gbrain v${deps.version} manifest names ${entry.sha256}.`);+ }+ return load(path, { target, manifest: cached }, deps);+}++/** The two refusal codes {@link loadRustEngineAddon} reports; nothing else is ever caught. */+export type RustEngineAddonRefusalCode = 'rust_engine_addon_missing' | 'rust_engine_addon_mismatch';++/** What {@link loadRustEngineAddon} returns: the loaded addon, or the refusal it raised before touching the brain. */+export type RustEngineAddonLoad =+ | { ok: true; addon: RustAddon }+ | { ok: false; code: RustEngineAddonRefusalCode; reason: string; message: string };++/**+ * The engine shell's entry point to the addon: {@link loadRustAddon} as a result, never a throw, for the two refusal+ * codes. Any other error (a bug, not a refusal) is re-thrown unchanged.+ */+export async function loadRustEngineAddon(overrides: Partial<RustAddonLoaderDeps> = {}): Promise<RustEngineAddonLoad> {+ try {+ return { ok: true, addon: await loadRustAddon(overrides) };+ } catch (err) {+ if (err instanceof OperationError) {+ const code = err.code as string;+ if (code === 'rust_engine_addon_missing' || code === 'rust_engine_addon_mismatch') {+ return { ok: false, code, reason: err.reason ?? 'unknown', message: err.message };+ }+ }+ throw err;+ }+}diff --git a/src/core/rust-engine/addon-manifest.ts b/src/core/rust-engine/addon-manifest.tsnew file mode 100644index 0000000000..196b977dd5--- /dev/null+++ b/src/core/rust-engine/addon-manifest.ts@@ -0,0 +1,57 @@+/**+ * What a release says about the Rust engine addon: the manifest asset's shape, its parser, and the+ * platform names the addon and the release use.+ *+ * Pure: no disk, no network and no dependencies, so the release scripts under rust/scripts can import it.+ * The manifest is `gbrain-engine-rust.sha256.json`, written by the `rust-engine.yml` release build and+ * attested by `release.yml` like the executables.+ */++/** The engine_abi this gbrain source loads. Bumped with the crate's ENGINE_ABI when the JS side of the binding changes. */+export const RUST_ENGINE_ABI = 1;++/** One target's entry: the release asset to download and what its bytes must hash to. */+export interface RustAddonManifestTarget {+ /** The release asset name, which is also the subject name in its build-provenance attestation. */+ asset: string;+ sha256: string;+ bytes: number;+}++export interface RustAddonManifest {+ gbrain_version: string;+ engine_abi: number;+ engine_build: string;+ /** Keyed by the addon's own target name (what `target()` reports), e.g. `linux-x64-glibc`, `darwin-arm64`. */+ targets: Record<string, RustAddonManifestTarget>;+}++/** The target names a release publishes an addon for; the keys of `targets` in a release manifest. */+export const RELEASE_ADDON_TARGETS: readonly string[] = ['linux-x64-glibc', 'darwin-arm64'];++const SHA256_HEX = /^[0-9a-f]{64}$/;++/** Parse and validate manifest text. Returns null for anything that is not a complete manifest. */+export function parseRustAddonManifest(text: string): RustAddonManifest | null {+ let raw: any;+ try {+ raw = JSON.parse(text);+ } catch {+ return null;+ }+ if (!raw || typeof raw !== 'object') return null;+ if (typeof raw.gbrain_version !== 'string' || raw.gbrain_version.length === 0) return null;+ if (!Number.isInteger(raw.engine_abi)) return null;+ if (typeof raw.engine_build !== 'string' || !/^[0-9A-Za-z._-]+$/.test(raw.engine_build)) return null;+ if (!raw.targets || typeof raw.targets !== 'object') return null;+ const targets: Record<string, RustAddonManifestTarget> = {};+ for (const [name, entry] of Object.entries<any>(raw.targets)) {+ // The target and engine_build become path segments of the cache path, so they are checked as such.+ if (!/^[0-9a-z_-]+$/.test(name)) return null;+ if (!entry || typeof entry.asset !== 'string' || entry.asset.length === 0) return null;+ if (typeof entry.sha256 !== 'string' || !SHA256_HEX.test(entry.sha256)) return null;+ if (!Number.isInteger(entry.bytes) || entry.bytes <= 0) return null;+ targets[name] = { asset: entry.asset, sha256: entry.sha256, bytes: entry.bytes };+ }+ return { gbrain_version: raw.gbrain_version, engine_abi: raw.engine_abi, engine_build: raw.engine_build, targets };+}diff --git a/src/core/rust-engine/addon-target.ts b/src/core/rust-engine/addon-target.tsnew file mode 100644index 0000000000..9d250a86e4--- /dev/null+++ b/src/core/rust-engine/addon-target.ts@@ -0,0 +1,19 @@+/** The addon target name of the machine gbrain is running on (the only place the loader reads the C runtime family). */+import { familySync, GLIBC, MUSL } from 'detect-libc';++/**+ * The addon target name for this platform, in the form the addon's `target()` reports+ * (`linux-x64-glibc`, `darwin-arm64`, ...). It names the platform whether or not a release publishes+ * an addon for it. Returns null when the platform cannot be identified (an unknown Linux C runtime).+ */+export function detectAddonTarget(+ platform: NodeJS.Platform = process.platform,+ arch: NodeJS.Architecture = process.arch,+ libc: () => string | null = familySync,+): string | null {+ if (platform === 'linux') {+ const family = libc();+ return family === GLIBC || family === MUSL ? `linux-${arch}-${family}` : null;+ }+ return `${platform}-${arch}`;+}diff --git a/src/core/rust-engine/errors.ts b/src/core/rust-engine/errors.tsnew file mode 100644index 0000000000..754393da82--- /dev/null+++ b/src/core/rust-engine/errors.ts@@ -0,0 +1,26 @@+/**+ * The capability refusal of the optional Rust engine (docs/designs/RUST_ENGINE.md, "Error contract for the Rust+ * engine", decision D2): `engine_capability_missing` means the engine opened but does not implement what the caller+ * asked for. The check runs before any work, so nothing was written. Addon states (missing, mismatched) are not+ * refused here: the addon loader owns them and refuses before an engine exists.+ *+ * `detail` is caller-safe key=value text: the member, the capability, the outcome and what was written.+ */+import { opError, type OperationError } from '../ops/contract.ts';+import type { Capability } from '../engine-capabilities.ts';++/** What a refusal left behind: `none` when the check ran before any work. */+export type CapabilityOutcome = 'none' | 'partial' | 'unknown';++/**+ * The engine does not implement `capability`, which `member` (a BrainEngine member, operation or command name) needs.+ * With the default `outcome: 'none'` nothing ran; the raw-SQL backstop passes `partial` or `unknown` when it is reached+ * after earlier steps of a caller already ran.+ */+export function capabilityMissing(capability: Capability, member: string, outcome: CapabilityOutcome = 'none'): OperationError {+ const nothingRan = outcome === 'none';+ return opError('engine_capability_missing',+ `This brain's engine does not support ${member} yet (it needs the ${capability} capability)${nothingRan ? ', so nothing ran.' : '.'}`,+ 'Run it on a pglite or postgres brain, or wait for a gbrain release whose Rust engine supports it.',+ { reason: capability, detail: `member=${member} capability=${capability} outcome=${outcome} written=${nothingRan ? 'nothing' : outcome}` });+}diff --git a/src/core/rust-engine/members.ts b/src/core/rust-engine/members.tsnew file mode 100644index 0000000000..4dd9f23885--- /dev/null+++ b/src/core/rust-engine/members.ts@@ -0,0 +1,245 @@+/**+ * Every BrainEngine member, classified for the Rust engine (docs/designs/RUST_ENGINE.md, "Capability gating").+ *+ * `implemented` members run on the Rust engine. Every other member names the capability it belongs to; until the Rust+ * engine implements it, a call rejects with `engine_capability_missing` naming that capability, before any work, so+ * nothing is written. The `satisfies` clause makes a new BrainEngine member fail to compile until it is classified here.+ */+import type { Capability } from '../engine-capabilities.ts';+import type { BrainEngine } from '../engine.ts';++export type MemberClass = 'implemented' | Capability;++export const RUST_ENGINE_MEMBERS = {+ // implemented+ kind: 'implemented',+ capabilities: 'implemented',+ connect: 'implemented',+ disconnect: 'implemented',+ reconnect: 'implemented',+ registerBeforeDisconnect: 'implemented',+ // raw_sql+ withReservedConnection: 'raw_sql',+ executeRaw: 'raw_sql',+ executeRawDirect: 'raw_sql',+ keywordBoundedRead: 'raw_sql',+ runMigration: 'raw_sql',+ // schema+ initSchema: 'schema',+ holdSchemaMigrationLock: 'schema',+ // transactions+ transaction: 'transactions',+ transactionDirect: 'transactions',+ lockPageKeys: 'transactions',+ // pages+ getPage: 'pages',+ readPageSnapshot: 'pages',+ readPageSnapshotsBatch: 'pages',+ putPage: 'pages',+ findDuplicatePage: 'pages',+ findDuplicatePages: 'pages',+ deletePage: 'pages',+ deletePages: 'pages',+ resolveSlugsByPaths: 'pages',+ softDeletePage: 'pages',+ softDeletePages: 'pages',+ restorePage: 'pages',+ purgeDeletedPages: 'pages',+ listPages: 'pages',+ findPages: 'pages',+ countPagesBy: 'pages',+ resolveSlugs: 'pages',+ getAllSlugs: 'pages',+ listAllPageRefs: 'pages',+ listPrefixSampledPages: 'pages',+ listCorpusSample: 'pages',+ getPageTimestamps: 'pages',+ getEffectiveDates: 'pages',+ getContentFlagsByPageIds: 'pages',+ getUnverifiedExtractionPageIds: 'pages',+ countStalePagesForExtraction: 'pages',+ listStalePagesForExtraction: 'pages',+ markPagesExtractedBatch: 'pages',+ markPagesAttendanceBlocked: 'pages',+ countStaleFrontmatterKeyPages: 'pages',+ listStaleFrontmatterKeyPages: 'pages',+ stripStaleFrontmatterKeys: 'pages',+ updateSlug: 'pages',+ resolveSlugWithAlias: 'pages',+ resolveSlugWithAliasDetailed: 'pages',+ resolveAliases: 'pages',+ setPageAliases: 'pages',+ updatePageContextualRetrievalState: 'pages',+ // sources+ listAllSources: 'sources',+ updateSourceConfig: 'sources',+ // config+ getConfig: 'config',+ setConfig: 'config',+ unsetConfig: 'config',+ listConfigKeys: 'config',+ getAllConfig: 'config',+ // page_versions+ createVersion: 'page_versions',+ getVersions: 'page_versions',+ revertToVersion: 'page_versions',+ // page_body+ refreshPageBody: 'page_body',+ allocateBodyOccurrenceIds: 'page_body',+ stageSegmentTexts: 'page_body',+ readSegmentTexts: 'page_body',+ stageManifestRows: 'page_body',+ readManifest: 'page_body',+ stageSegmentChunks: 'page_body',+ createSegmentedPageShell: 'page_body',+ flipBodyGeneration: 'page_body',+ openBodyStaging: 'page_body',+ setBodyStagingState: 'page_body',+ sweepSegments: 'page_body',+ readSegmentDerivations: 'page_body',+ upsertSegmentDerivations: 'page_body',+ retireSegmentDerivations: 'page_body',+ // tags+ addTag: 'tags',+ removeTag: 'tags',+ getTags: 'tags',+ // chunks+ upsertChunks: 'chunks',+ getChunks: 'chunks',+ getChunkPage: 'chunks',+ getChunkWindows: 'chunks',+ countChunklessPagesWithContent: 'chunks',+ listChunklessPagesWithContent: 'chunks',+ deleteChunks: 'chunks',+ // embeddings+ getEmbeddingsByChunkIds: 'embeddings',+ countStaleChunks: 'embeddings',+ sumStaleChunkChars: 'embeddings',+ setPageEmbeddingSignature: 'embeddings',+ invalidateStaleSignatureEmbeddings: 'embeddings',+ invalidateContentDriftEmbeddings: 'embeddings',+ listStaleChunks: 'embeddings',+ readEmbeddingStateCounts: 'embeddings',+ listEmbeddingStateRows: 'embeddings',+ getChunksWithEmbeddings: 'embeddings',+ // keyword_search+ searchKeyword: 'keyword_search',+ countKeywordPages: 'keyword_search',+ searchKeywordPages: 'keyword_search',+ searchTitles: 'keyword_search',+ searchKeywordChunks: 'keyword_search',+ findByTitleFuzzy: 'keyword_search',+ // vector_search+ searchVector: 'vector_search',+ // links+ addLink: 'links',+ addLinksBatch: 'links',+ replaceDerivedLinks: 'links',+ replaceDerivedLinksBatch: 'links',+ removeLink: 'links',+ removeLinksByPagesAndSource: 'links',+ getLinks: 'links',+ getBacklinks: 'links',+ listLinkSources: 'links',+ rewriteLinks: 'links',+ getBacklinkCounts: 'links',+ // timeline+ addTimelineEntry: 'timeline',+ addTimelineEntriesBatch: 'timeline',+ getTimeline: 'timeline',+ getTimelineForDate: 'timeline',+ getSince: 'timeline',+ getOnThisDay: 'timeline',+ getLastSeen: 'timeline',+ upsertEventProjection: 'timeline',+ // graph+ traverseGraph: 'graph',+ traversePaths: 'graph',+ traversePathsDetailed: 'graph',+ relationalFanout: 'graph',+ relationalChainHop: 'graph',+ getAdjacencyBoosts: 'graph',+ findOrphanPages: 'graph',+ // facts+ insertFact: 'facts',+ insertFacts: 'facts',+ deleteFactsForPage: 'facts',+ expireFact: 'facts',+ listFactsByEntity: 'facts',+ listFactsSince: 'facts',+ listFactsKeyset: 'facts',+ listFactsBySession: 'facts',+ listSupersessions: 'facts',+ countUnconsolidatedFacts: 'facts',+ findCandidateDuplicates: 'facts',+ consolidateFact: 'facts',+ findTrajectory: 'facts',+ getFactsHealth: 'facts',+ migrateFactsToCanonical: 'facts',+ // takes+ addTakesBatch: 'takes',+ updateTakeEmbeddings: 'takes',+ listTakes: 'takes',+ searchTakes: 'takes',+ searchTakesVector: 'takes',+ getTakeEmbeddings: 'takes',+ countStaleTakes: 'takes',+ listStaleTakes: 'takes',+ updateTake: 'takes',+ supersedeTake: 'takes',+ resolveTake: 'takes',+ getScorecard: 'takes',+ getCalibrationCurve: 'takes',+ addSynthesisEvidence: 'takes',+ listActiveTakesForPages: 'takes',+ // files+ upsertFile: 'files',+ getFile: 'files',+ listFilesForPage: 'files',+ // code_edges+ addCodeEdges: 'code_edges',+ deleteCodeEdgesForChunks: 'code_edges',+ getCallersOf: 'code_edges',+ getCalleesOf: 'code_edges',+ getEdgesByChunk: 'code_edges',+ // salience+ getSalienceScores: 'salience',+ batchLoadEmotionalInputs: 'salience',+ setEmotionalWeightBatch: 'salience',+ getRecentSalience: 'salience',+ // health+ getStats: 'health',+ getHealth: 'health',+ listEnrichCandidates: 'health',+ findAnomalies: 'health',+ // raw_data+ putRawData: 'raw_data',+ getRawData: 'raw_data',+ // eval_capture+ logEvalCandidate: 'eval_capture',+ listEvalCandidates: 'eval_capture',+ deleteEvalCandidatesBefore: 'eval_capture',+ logEvalCaptureFailure: 'eval_capture',+ listEvalCaptureFailures: 'eval_capture',+ // ingest_log+ logIngest: 'ingest_log',+ getIngestLog: 'ingest_log',+ // dream_verdicts+ getDreamVerdict: 'dream_verdicts',+ putDreamVerdict: 'dream_verdicts',+ sweepDreamVerdicts: 'dream_verdicts',+ // contradictions+ writeContradictionsRun: 'contradictions',+ loadContradictionsTrend: 'contradictions',+ getContradictionCacheEntry: 'contradictions',+ putContradictionCacheEntry: 'contradictions',+ sweepContradictionCache: 'contradictions',+ // ontology+ mergeOntologyFact: 'ontology',+ getOntology: 'ontology',+ discoverOntologyDimensions: 'ontology',+ findOntologyConflicts: 'ontology',+} as const satisfies Record<keyof BrainEngine, MemberClass>;++export type RustEngineMember = keyof typeof RUST_ENGINE_MEMBERS;+diff --git a/src/core/schema-missing-tables.ts b/src/core/schema-missing-tables.tsindex 4e0fb09a7f..56aaa385ca 100644--- a/src/core/schema-missing-tables.ts+++ b/src/core/schema-missing-tables.ts@@ -10,6 +10,7 @@ import type { BrainEngine } from './engine.ts';import { LATEST_VERSION } from './migrate.ts';import { GRADUATION_INVENTORY } from './persistence/graduation-inventory.ts';import { isRebuildableCache } from './persistence/rebuildable-cache.ts';+import { sqlEngineKind } from './sql-engine-kind.ts';import { v055 } from './schema-migrations/v055-query-cache-search-lite.ts';import { v056 } from './schema-migrations/v056-query-cache-knobs-hash.ts';import { v059 } from './schema-migrations/v059-code-traversal-cache-v0-34.ts';@@ -88,7 +89,8 @@ export async function readMissingTables(engine: BrainEngine): Promise<MissingTabconst version = parseInt((await engine.getConfig('version')) || '0', 10);if (version > LATEST_VERSION) return { status: 'skipped', reason: 'client_behind', version, latest: LATEST_VERSION };const atHead = version === LATEST_VERSION;- const expected = GRADUATION_INVENTORY.entries.filter(e => e.kind === 'table' && e.engines[engine.kind]+ const kind = sqlEngineKind(engine.kind, 'schema missing-tables check');+ const expected = GRADUATION_INVENTORY.entries.filter(e => e.kind === 'table' && e.engines[kind]&& (atHead || (recreateStep(e.relation) !== undefined && version >= CREATED_BY[e.relation]!)));const rows = await engine.executeRaw<{ relation: string }>('SELECT r AS relation FROM unnest($1::text[]) AS r WHERE to_regclass(r) IS NULL ORDER BY r',[expected.map(e => e.relation)]);diff --git a/src/core/sql-engine-kind.ts b/src/core/sql-engine-kind.tsnew file mode 100644index 0000000000..c388f60d78--- /dev/null+++ b/src/core/sql-engine-kind.ts@@ -0,0 +1,25 @@+/**+ * Narrow an engine kind to the two SQL engines before a SQL-only path picks+ * per-dialect values. A Rust brain has no SQL dialect (decision D18), so it is+ * refused with `engine_capability_missing` (reason `raw_sql`) instead of+ * falling silently into the Postgres or PGLite branch.+ */+import type { SqlEngineKind } from './engine-capabilities.ts';+import { capabilityMissing } from './rust-engine/errors.ts';++/** Every engine kind. `BrainEngine.kind` widens to it with the `rust` config value (the addon PR); until then SQL-only paths take this type so their Rust refusal is already in place. */+export type EngineKind = SqlEngineKind | 'rust';++export function isRustEngineKind(kind: EngineKind | undefined | null): boolean {+ return kind === 'rust';+}++export function isSqlEngineKind(kind: EngineKind | undefined | null): kind is SqlEngineKind {+ return kind === 'pglite' || kind === 'postgres';+}++/** `kind` when it is pglite or postgres; otherwise throws `engine_capability_missing` naming `member`. */+export function sqlEngineKind(kind: EngineKind, member: string): SqlEngineKind {+ if (isSqlEngineKind(kind)) return kind;+ throw capabilityMissing('raw_sql', member);+}diff --git a/src/eval/brainbench/adapters/claude-code.ts b/src/eval/brainbench/adapters/claude-code.tsindex 97e4a5ad00..8243a56a4a 100644--- a/src/eval/brainbench/adapters/claude-code.ts+++ b/src/eval/brainbench/adapters/claude-code.ts@@ -37,7 +37,7 @@ import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';import type { Server } from 'node:net';-import type { PGLiteEngine } from '../../../core/pglite-engine.ts';+import type { BrainEngine } from '../../../core/engine.ts';import type { GBrainConfig } from '../../../core/config.ts';import { runHook } from '../../../commands/hook.ts';import {@@ -88,7 +88,7 @@ export class ClaudeCodeAdapter implements HarnessAdapter {readonly name = 'claude-code' as const;readonly seam = 'production' as const;- private engine: PGLiteEngine | null = null;+ private engine: BrainEngine | null = null;private sourceId = 'default';private sessionId = '';private fixtureSeq = 0;@@ -164,7 +164,7 @@ export class ClaudeCodeAdapter implements HarnessAdapter {}}- async beginConversation(engine: PGLiteEngine, fixture: AdapterFixtureView): Promise<void> {+ async beginConversation(engine: BrainEngine, fixture: AdapterFixtureView): Promise<void> {if (!this.server) {// Legacy single-fixture construction (tests) — own the run lifecycle.await this.setupRun();diff --git a/src/eval/brainbench/adapters/codex.ts b/src/eval/brainbench/adapters/codex.tsindex da807cd74b..afb65e6e8e 100644--- a/src/eval/brainbench/adapters/codex.ts+++ b/src/eval/brainbench/adapters/codex.ts@@ -16,7 +16,7 @@import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';-import type { PGLiteEngine } from '../../../core/pglite-engine.ts';+import type { BrainEngine } from '../../../core/engine.ts';import { codexAdapter as codexTranscriptAdapter } from '../../../core/transcripts/codex.ts';import type {AdapterFixtureView,@@ -34,7 +34,7 @@ export class CodexAdapter implements HarnessAdapter {readonly name = 'codex' as const;readonly seam = 'contract' as const;- private engine: PGLiteEngine | null = null;+ private engine: BrainEngine | null = null;private sourceId = 'default';private preamble = '';private firstTurn = true;@@ -57,7 +57,7 @@ export class CodexAdapter implements HarnessAdapter {}}- async beginConversation(engine: PGLiteEngine, fixture: AdapterFixtureView): Promise<void> {+ async beginConversation(engine: BrainEngine, fixture: AdapterFixtureView): Promise<void> {if (!this.tmpDir) await this.setupRun();this.engine = engine;this.sourceId = fixture.active_source;diff --git a/src/eval/brainbench/adapters/openclaw.ts b/src/eval/brainbench/adapters/openclaw.tsindex 815e29227b..624eba50dc 100644--- a/src/eval/brainbench/adapters/openclaw.ts+++ b/src/eval/brainbench/adapters/openclaw.ts@@ -14,7 +14,7 @@* gate, heartbeat, timeout — stay deliberately ungraded, see BRAINBENCH.md).*/-import type { PGLiteEngine } from '../../../core/pglite-engine.ts';+import type { BrainEngine } from '../../../core/engine.ts';import { DEFAULT_MAX_POINTERS } from '../../../core/context/retrieval-reflex.ts';import { volunteerContext, VOLUNTEER_DEFAULT_MAX_PAGES } from '../../../core/context/volunteer.ts';import { DEFAULT_WINDOW_TURNS, renderReflexAddition } from '../../../core/context/reflex.ts';@@ -31,11 +31,11 @@ export class OpenClawAdapter implements HarnessAdapter {readonly name = 'openclaw' as const;readonly seam = 'production' as const;- private engine: PGLiteEngine | null = null;+ private engine: BrainEngine | null = null;private sourceId = 'default';private window: WindowTurn[] = [];- async beginConversation(engine: PGLiteEngine, fixture: AdapterFixtureView): Promise<void> {+ async beginConversation(engine: BrainEngine, fixture: AdapterFixtureView): Promise<void> {this.engine = engine;this.sourceId = fixture.active_source;this.window = [];diff --git a/src/eval/brainbench/adapters/shared.ts b/src/eval/brainbench/adapters/shared.tsindex 49b4700d93..1b4f5db72d 100644--- a/src/eval/brainbench/adapters/shared.ts+++ b/src/eval/brainbench/adapters/shared.ts@@ -20,7 +20,7 @@ import {resolveEntitiesToPointers,type PointerBlock,} from '../../../core/context/retrieval-reflex.ts';-import type { PGLiteEngine } from '../../../core/pglite-engine.ts';+import type { BrainEngine } from '../../../core/engine.ts';import type { HarnessTurnResult, PublicTurn } from '../types.ts';export interface ReflexPipelineCfg {@@ -42,7 +42,7 @@ export function estimateTokens(text: string | null): number {}export async function runReflexPipeline(- engine: PGLiteEngine,+ engine: BrainEngine,sourceId: string,turn: PublicTurn,priorContextText: string,diff --git a/src/eval/brainbench/harness.ts b/src/eval/brainbench/harness.tsindex 1d82603875..b054d79d3f 100644--- a/src/eval/brainbench/harness.ts+++ b/src/eval/brainbench/harness.ts@@ -24,7 +24,7 @@import { BudgetTracker } from '../../core/budget/budget-tracker.ts';import { createBenchmarkBrain, resetTables } from '../longmemeval/harness.ts';-import type { PGLiteEngine } from '../../core/pglite-engine.ts';+import type { BrainEngine } from '../../core/engine.ts';import { ClaudeCodeAdapter } from './adapters/claude-code.ts';import { CodexAdapter } from './adapters/codex.ts';import { OpenClawAdapter } from './adapters/openclaw.ts';@@ -122,7 +122,7 @@ function crossSourceSlugs(* external re-scorers see self-contained rows.*/async function replayFixture(- engine: PGLiteEngine,+ engine: BrainEngine,adapter: HarnessAdapter,lf: LoadedFixture,seed: SeedOutcome,diff --git a/src/eval/brainbench/metrics/continuity.ts b/src/eval/brainbench/metrics/continuity.tsindex 18bdeb56b2..127a3ae31e 100644--- a/src/eval/brainbench/metrics/continuity.ts+++ b/src/eval/brainbench/metrics/continuity.ts@@ -13,7 +13,7 @@* continuity_rate per harness = mean over pairs where that harness READ.*/-import type { PGLiteEngine } from '../../../core/pglite-engine.ts';+import type { BrainEngine } from '../../../core/engine.ts';import type { ContinuityDecisionGold, TurnRow } from '../types.ts';export interface ContinuityPairScore {@@ -25,7 +25,7 @@ export interface ContinuityPairScore {}export async function scoreContinuityPair(- engine: PGLiteEngine,+ engine: BrainEngine,activeSource: string,pairId: string,readerRows: TurnRow[],@@ -55,7 +55,7 @@ export async function scoreContinuityPair(/** True when an active (non-expired) fact in the source contains every keyword. */export async function factKeywordProbe(- engine: PGLiteEngine,+ engine: BrainEngine,sourceId: string,keywords: string[],): Promise<boolean> {diff --git a/src/eval/brainbench/metrics/write-back.ts b/src/eval/brainbench/metrics/write-back.tsindex 5e6fed5800..77559d1aed 100644--- a/src/eval/brainbench/metrics/write-back.ts+++ b/src/eval/brainbench/metrics/write-back.ts@@ -29,7 +29,7 @@ import {runExtractConversationFactsCore,} from '../../../commands/extract-conversation-facts.ts';import { importFromContent } from '../../../core/import-file.ts';-import type { PGLiteEngine } from '../../../core/pglite-engine.ts';+import type { BrainEngine } from '../../../core/engine.ts';import type { BrainBenchFixture, FixtureGold, GoldFactSpec } from '../types.ts';import { SeedError } from '../seed.ts';@@ -136,7 +136,7 @@ interface StoredFactRow {}export async function runWriteBack(- engine: PGLiteEngine,+ engine: BrainEngine,fixture: BrainBenchFixture,gold: FixtureGold,opts: {diff --git a/src/eval/brainbench/seed.ts b/src/eval/brainbench/seed.tsindex 36f87b1d86..f036fbc8d6 100644--- a/src/eval/brainbench/seed.ts+++ b/src/eval/brainbench/seed.ts@@ -14,7 +14,7 @@*/import { importFromContent } from '../../core/import-file.ts';-import type { PGLiteEngine } from '../../core/pglite-engine.ts';+import type { BrainEngine } from '../../core/engine.ts';import type { BrainBenchFixture } from './types.ts';export class SeedError extends Error {@@ -43,7 +43,7 @@ export interface SeedOutcome {const DEFAULT_SOURCE = 'default';/** Idempotent: creates any non-default sources the fixture declares. */-async function ensureSources(engine: PGLiteEngine, fixture: BrainBenchFixture): Promise<void> {+async function ensureSources(engine: BrainEngine, fixture: BrainBenchFixture): Promise<void> {const wanted = new Set<string>();for (const s of fixture.sources ?? []) wanted.add(s);if (fixture.active_source && fixture.active_source !== DEFAULT_SOURCE) {@@ -64,7 +64,7 @@ async function ensureSources(engine: PGLiteEngine, fixture: BrainBenchFixture):}}-export async function seedBrain(engine: PGLiteEngine, fixture: BrainBenchFixture): Promise<SeedOutcome> {+export async function seedBrain(engine: BrainEngine, fixture: BrainBenchFixture): Promise<SeedOutcome> {await ensureSources(engine, fixture);const slugSource = new Map<string, Set<string>>();diff --git a/src/eval/brainbench/trust-scenario.ts b/src/eval/brainbench/trust-scenario.tsindex bd74d271ba..fe3e707d01 100644--- a/src/eval/brainbench/trust-scenario.ts+++ b/src/eval/brainbench/trust-scenario.ts@@ -101,14 +101,14 @@ export interface TrustFixtureRun {sourceIds: string[];connector?: ConnectorSource;repoDir: string;- engine: PGLiteEngine;+ engine: BrainEngine;remote: OperationContext;local: OperationContext;steps: Map<string, StepRecord>;}export interface TrustBrain {- engine: PGLiteEngine;+ engine: BrainEngine;root: string;close(): Promise<void>;}diff --git a/src/eval/brainbench/types.ts b/src/eval/brainbench/types.tsindex 497bcf43fd..4e4a1d31ec 100644--- a/src/eval/brainbench/types.ts+++ b/src/eval/brainbench/types.ts@@ -17,7 +17,7 @@*/import type { ReflexPointer } from '../../core/context/retrieval-reflex.ts';-import type { PGLiteEngine } from '../../core/pglite-engine.ts';+import type { BrainEngine } from '../../core/engine.ts';export const FIXTURE_SCHEMA_VERSION = 1;export const RESULT_SCHEMA_VERSION = 1;@@ -310,7 +310,7 @@ export interface HarnessAdapter {setupRun?(): Promise<void>;teardownRun?(): Promise<void>;/** Called once per (fixture, adapter) before any turn. */- beginConversation(engine: PGLiteEngine, fixture: AdapterFixtureView): Promise<void>;+ beginConversation(engine: BrainEngine, fixture: AdapterFixtureView): Promise<void>;/*** Replay one turn. `priorContextText` is the joined text of PRIOR turns +* prior injections — adapters whose seam has no conversation memory (e.g.diff --git a/src/eval/longmemeval/decide-lane.ts b/src/eval/longmemeval/decide-lane.tsindex d761a2440c..fe4716a754 100644--- a/src/eval/longmemeval/decide-lane.ts+++ b/src/eval/longmemeval/decide-lane.ts@@ -16,7 +16,7 @@** All-off: every helper is a no-op when no slot is on or shadow.*/-import type { PGLiteEngine } from '../../core/pglite-engine.ts';+import type { BrainEngine } from '../../core/engine.ts';import type { HybridSearchMeta } from '../../core/types.ts';import type { ReaderAnswer } from './reader.ts';import { EVAL_POOL_DEPTH_MAX, setEvalPoolDepth } from '../../core/search/eval-pool-depth.ts';@@ -70,7 +70,7 @@ export function prepareLmeDecide<Q extends { question_id: string }>(opts: LmeDec}/** decide_spend totals before a question's search (null when no arm is active). */-export async function lmeSpendBefore(engine: PGLiteEngine, run: DecideEvalRun | null | undefined): Promise<DecideSpend | null> {+export async function lmeSpendBefore(engine: BrainEngine, run: DecideEvalRun | null | undefined): Promise<DecideSpend | null> {return run ? decideSpendTotals(engine) : null;}@@ -80,7 +80,7 @@ export function lmeDecideSearchOpts(run: DecideEvalRun | null | undefined): { de}/** The row's `decide` field (absent on all-off rows). */-export async function lmeDecideRow(engine: PGLiteEngine, run: DecideEvalRun | null | undefined, meta: HybridSearchMeta | undefined, before: DecideSpend | null): Promise<Record<string, unknown>> {+export async function lmeDecideRow(engine: BrainEngine, run: DecideEvalRun | null | undefined, meta: HybridSearchMeta | undefined, before: DecideSpend | null): Promise<Record<string, unknown>> {if (!run || !before) return {};const receipt = decideRowReceipt(run, meta?.decide, spendDelta(before, await decideSpendTotals(engine)));return { decide: { ...receipt, ...(meta?.answerability ? { answerability: meta.answerability } : {}), ...(lmeAbstention(run, meta) ? { reader_abstained: true } : {}) } };diff --git a/src/eval/longmemeval/diagnostics.ts b/src/eval/longmemeval/diagnostics.tsindex 11e66ca474..bab4f08a56 100644--- a/src/eval/longmemeval/diagnostics.ts+++ b/src/eval/longmemeval/diagnostics.ts@@ -63,7 +63,7 @@ import {type ResolvedSearchKnobs,type SearchMode,} from '../../core/search/mode.ts';-import type { PGLiteEngine } from '../../core/pglite-engine.ts';+import type { BrainEngine } from '../../core/engine.ts';import type { HybridSearchMeta, SearchOpts, SearchResult } from '../../core/types.ts';import { haystackToPages, type LongMemEvalQuestion } from './adapter.ts';import { resetTables } from './harness.ts';@@ -843,7 +843,7 @@ export function renderDiagnosticsMarkdown(rows: readonly MissDiagnosticsRow[], sexport interface DiagnosticsRunOpts {/** Caller-owned benchmark brain (createBenchmarkBrain()); config table survives resetTables. */- engine: PGLiteEngine;+ engine: BrainEngine;receipt: ParsedReceipt;questions: readonly LongMemEvalQuestion[];splits?: Record<string, unknown> | null;@@ -872,7 +872,7 @@ export interface DiagnosticsRunResult {}/** Mirror the harness: explicit pins land in the benchmark brain's config table. */-export async function applyPins(engine: PGLiteEngine, pins: DiagnosticsPins): Promise<void> {+export async function applyPins(engine: BrainEngine, pins: DiagnosticsPins): Promise<void> {if (pins.mode) await engine.setConfig('search.mode', pins.mode);if (pins.reranker !== undefined) await engine.setConfig('search.reranker.enabled', pins.reranker ? 'true' : 'false');if (pins.autocut !== undefined) await engine.setConfig('search.autocut', pins.autocut ? 'true' : 'false');@@ -1054,7 +1054,7 @@ export function errorRow(}interface DiagnoseOneCtx {- engine: PGLiteEngine;+ engine: BrainEngine;q: LongMemEvalQuestion;receiptRow: ReceiptRow;k: number;diff --git a/src/eval/longmemeval/harness.ts b/src/eval/longmemeval/harness.tsindex ca3a4a3dc9..5061bcd460 100644--- a/src/eval/longmemeval/harness.ts+++ b/src/eval/longmemeval/harness.ts@@ -11,6 +11,7 @@*/import { PGLiteEngine } from '../../core/pglite-engine.ts';+import type { BrainEngine } from '../../core/engine.ts';interface PgTablesRow {tablename: string;@@ -43,7 +44,7 @@ export async function createBenchmarkBrain(): Promise<PGLiteEngine> {return engine;}-export async function resetTables(engine: PGLiteEngine): Promise<void> {+export async function resetTables(engine: BrainEngine): Promise<void> {const rows = await engine.executeRaw<PgTablesRow>(`SELECT tablename FROM pg_tables WHERE schemaname = 'public'`,);@@ -57,7 +58,7 @@ export async function resetTables(engine: PGLiteEngine): Promise<void> {}export async function withBenchmarkBrain<T>(- fn: (engine: PGLiteEngine) => Promise<T>,+ fn: (engine: BrainEngine) => Promise<T>,): Promise<T> {const engine = await createBenchmarkBrain();try {@@ -78,12 +79,12 @@ export const LME_BRAIN_RECYCLE_EVERY = 40;* fresh, re-configured one every `every` questions (0 = never). `close()`* disconnects a replacement; the first brain stays its owner's to close.*/-export function brainRecycler(- first: PGLiteEngine,+export function brainRecycler<E extends BrainEngine>(+ first: E,every: number,- create: () => Promise<PGLiteEngine>,- configure: (engine: PGLiteEngine) => Promise<void>,-): { next(): Promise<PGLiteEngine>; close(): Promise<void> } {+ create: () => Promise<E>,+ configure: (engine: E) => Promise<void>,+): { next(): Promise<E>; close(): Promise<void> } {let brain = first;let served = 0;return {diff --git a/src/eval/longmemeval/trajectory-route.ts b/src/eval/longmemeval/trajectory-route.tsindex 95abacb1f9..8e91c74345 100644--- a/src/eval/longmemeval/trajectory-route.ts+++ b/src/eval/longmemeval/trajectory-route.ts@@ -9,7 +9,7 @@* "no block injected" — a routing failure never fails the question.*/-import type { PGLiteEngine } from '../../core/pglite-engine.ts';+import type { BrainEngine } from '../../core/engine.ts';import type { TrajectoryPoint } from '../../core/engine.ts';import { extractCandidateEntities } from '../../core/think/entity-extract.ts';import { resolveEntitySlugWithSource, type ResolutionSource } from '../../core/entities/resolve.ts';@@ -28,7 +28,7 @@ export interface TrajectoryRoute {export const EMPTY_TRAJECTORY_ROUTE: TrajectoryRoute = { block: '', points: 0, entityResolved: null, resolutionSource: null };export async function routeTrajectory(- engine: PGLiteEngine,+ engine: BrainEngine,question: string,retrievedSlugs: readonly string[],intent: Intent,diff --git a/test/brainbench-trust-mutations.serial.test.ts b/test/brainbench-trust-mutations.serial.test.tsindex 3be77018d8..5e4f85a44d 100644--- a/test/brainbench-trust-mutations.serial.test.ts+++ b/test/brainbench-trust-mutations.serial.test.ts@@ -22,7 +22,7 @@ import { assembleTrustCell, runTrustSuites, type RunTrustSuitesOpts } from '../simport { TRUST_SUITES, type LoadedFixture, type TrustStep, type TrustSuite } from '../src/eval/brainbench/types.ts';import { withCoordinatedWrite } from '../src/core/persistence/context.ts';import { __setWriteGateDetectorForTests } from '../src/core/write-gate.ts';-import type { PGLiteEngine } from '../src/core/pglite-engine.ts';+import type { BrainEngine } from '../src/core/engine.ts';import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';const ROOT = join(import.meta.dir, '..', 'evals', 'brainbench');@@ -40,7 +40,7 @@ const SLICE = {type Metrics = Partial<Record<TrustSuite, Record<string, number>>>;interface Mutation {- setup?: (engine: PGLiteEngine) => Promise<void>;+ setup?: (engine: BrainEngine) => Promise<void>;beforeStep?: RunTrustSuitesOpts['beforeStep'];fixtures?: (lf: LoadedFixture) => LoadedFixture;}@@ -71,7 +71,7 @@ async function runSlice(suites: readonly TrustSuite[], mutation: Mutation = {}):afterEach(() => __setWriteGateDetectorForTests(null));/** The default-mode poisoning arm (shipped defaults: flag / allow) with `setup` applied to its brain. */-async function runDefaultSlice(setup: (engine: PGLiteEngine) => Promise<void>): Promise<Record<string, number> | undefined> {+async function runDefaultSlice(setup: (engine: BrainEngine) => Promise<void>): Promise<Record<string, number> | undefined> {const fixtures = SLICE.poisoning.map(id => byId.get(id)!);// One brain open per GBRAIN_HOME at a time: the protection brain runTrustSuites opens nests inside this one and closes first.const defaultBrain = await createTrustBrain({ protections: false });@@ -170,7 +170,7 @@ describe('poisoning default mode: break the labels and flags it guarantees', ()});describe('poisoning: turn each defense off', () => {- const config = (key: string, value: string) => async (engine: PGLiteEngine) => { await engine.setConfig(key, value); };+ const config = (key: string, value: string) => async (engine: BrainEngine) => { await engine.setConfig(key, value); };test('external gate off: external payloads persist', async () => {const m = await runSlice(['poisoning'], { setup: config('write_gate.external_mode', 'off') });diff --git a/test/cli-socket.test.ts b/test/cli-socket.test.tsindex 61777cb53e..d17b4ff55d 100644--- a/test/cli-socket.test.ts+++ b/test/cli-socket.test.ts@@ -108,6 +108,9 @@ const NOT_READ_BEHAVIOR = new Set(['GBRAIN_REMOTE_CLIENT_ID', 'GBRAIN_REMOTE_CLIENT_SECRET', 'GBRAIN_REMOTE_ISSUER_URL', 'GBRAIN_REMOTE_MCP_URL', 'GBRAIN_REMOTE_TOKEN', 'GBRAIN_REMOTE_TOKEN_ENV','GBRAIN_THIN_CLIENT_NAME', 'GBRAIN_TAILSCALE_LOGIN_TIMEOUT_MS', 'GBRAIN_ADMIN_BOOTSTRAP_TOKEN','GBRAIN_OPENCLAW_GATEWAY_URL', 'GBRAIN_OPENCLAW_GATEWAY_TOKEN',+ // Rust engine addon path: only the addon loader reads it, and no read path calls the loader yet.+ // Move it to READ_BEHAVIOR_ENV when a brain can be served by the Rust engine.+ 'GBRAIN_RUST_ENGINE_ADDON','GBRAIN_SCHEMA_AUDIT_VERBOSE', 'GBRAIN_SCHEMA_LOCK_TIMEOUT_SECONDS', 'GBRAIN_SCHEMA_PACK_MAX_BYTES', 'GBRAIN_SCHEMA_PACK_WARN_BYTES','GBRAIN_INITSCHEMA_LOCK_TIMEOUT_SECONDS', 'GBRAIN_INIT_SKIP_EMBED_CHECK', 'GBRAIN_IN_AGENT_SETUP', 'GBRAIN_INTERACTIVE', 'GBRAIN_NON_INTERACTIVE','GBRAIN_BOOTSTRAP_ABORT_AFTER', 'GBRAIN_SEAT', 'GBRAIN_CORE', 'GBRAIN_PRESSURE', 'GBRAIN_PAYLOAD', 'GBRAIN_DESCRIPTION', 'GBRAIN_HARNESS_MARKER_VALUE',diff --git a/test/engine-capabilities.test.ts b/test/engine-capabilities.test.tsnew file mode 100644index 0000000000..3c7dc5920e--- /dev/null+++ b/test/engine-capabilities.test.ts@@ -0,0 +1,93 @@+/**+ * Engine capability set (docs/designs/RUST_ENGINE.md "Capability gating", plan PR 5).+ * PGLite and Postgres report everything they have today, so no existing caller+ * can be refused; an unlisted operation needs raw_sql.+ */+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';+import {+ ENGINE_CAPABILITIES,+ REQUIRED_CAPABILITIES,+ capabilitiesForEngineKind,+ hasCapability,+ missingCapabilities,+ requiredCapabilities,+ type Capability,+} from '../src/core/engine-capabilities.ts';+import { PGLiteEngine } from '../src/core/pglite-engine.ts';+import { PostgresEngine } from '../src/core/postgres-engine.ts';++const shared = ENGINE_CAPABILITIES.filter(c => c !== 'single_owner' && c !== 'postgres_admin');++describe('engine capabilities', () => {+ // Never connected: capabilities are known without opening a database.+ let pglite: PGLiteEngine;+ let postgres: PostgresEngine;+ beforeAll(() => {+ pglite = new PGLiteEngine();+ postgres = new PostgresEngine();+ });+ afterAll(async () => {+ await pglite.disconnect();+ await postgres.disconnect();+ });++ test('PGLite reports every shared capability, raw_sql and single_owner, and no Postgres administration', () => {+ const engine = pglite;+ for (const c of shared) expect(engine.capabilities.has(c)).toBe(true);+ expect(hasCapability(engine, 'raw_sql')).toBe(true);+ expect(hasCapability(engine, 'single_owner')).toBe(true);+ expect(hasCapability(engine, 'postgres_admin')).toBe(false);+ expect(engine.capabilities.size).toBe(shared.length + 1);+ });++ test('Postgres reports every shared capability, raw_sql and postgres_admin, and is not single-owner', () => {+ const engine = postgres;+ for (const c of shared) expect(engine.capabilities.has(c)).toBe(true);+ expect(hasCapability(engine, 'raw_sql')).toBe(true);+ expect(hasCapability(engine, 'postgres_admin')).toBe(true);+ expect(hasCapability(engine, 'single_owner')).toBe(false);+ expect(engine.capabilities.size).toBe(shared.length + 1);+ });++ test('a transaction clone reports the same set as its engine', () => {+ const clone = Object.create(pglite) as PGLiteEngine;+ expect(clone.capabilities).toBe(pglite.capabilities);+ });++ test('each engine gets its own set: changing one never changes another', () => {+ const a = capabilitiesForEngineKind('pglite') as Set<Capability>;+ const b = capabilitiesForEngineKind('pglite');+ a.delete('pages');+ expect(b.has('pages')).toBe(true);+ expect(pglite.capabilities.has('pages')).toBe(true);+ });++ test('an unlisted operation, command, phase or handler needs raw_sql', () => {+ expect(requiredCapabilities('operation', 'put_page')).toEqual(['raw_sql']);+ expect(requiredCapabilities('command', 'doctor')).toEqual(['raw_sql']);+ expect(requiredCapabilities('phase', 'extract')).toEqual(['raw_sql']);+ expect(requiredCapabilities('handler', 'embed')).toEqual(['raw_sql']);+ // Object prototype names are not table rows.+ expect(requiredCapabilities('operation', 'toString')).toEqual(['raw_sql']);+ });++ test('every row in the table names known capabilities, and both SQL engines can run every name', () => {+ const known = new Set<string>(ENGINE_CAPABILITIES);+ const engines = [pglite, postgres];+ for (const [consumer, rows] of Object.entries(REQUIRED_CAPABILITIES)) {+ for (const [name, caps] of Object.entries(rows)) {+ for (const c of caps) expect(known.has(c)).toBe(true);+ for (const e of engines) {+ if (caps.includes('single_owner') || caps.includes('postgres_admin')) continue;+ expect(missingCapabilities(e, consumer as keyof typeof REQUIRED_CAPABILITIES, name)).toEqual([]);+ }+ }+ }+ for (const e of engines) expect(missingCapabilities(e, 'operation', 'put_page')).toEqual([]);+ });++ test('an engine without raw SQL is refused an unlisted operation, naming raw_sql', () => {+ const typedOnly = { capabilities: new Set<Capability>(['pages', 'chunks']) as ReadonlySet<Capability> };+ expect(missingCapabilities(typedOnly, 'operation', 'put_page')).toEqual(['raw_sql']);+ });+});diff --git a/test/eval-longmemeval-mixedcase.slow.test.ts b/test/eval-longmemeval-mixedcase.slow.test.tsindex 80e1793ae8..a2eaf2fe92 100644--- a/test/eval-longmemeval-mixedcase.slow.test.ts+++ b/test/eval-longmemeval-mixedcase.slow.test.ts@@ -48,6 +48,7 @@ import { rerankerReadiness } from '../src/core/ai/reranker-readiness.ts';import { __setEmbedTransportForTests, configureGateway, resetGateway } from '../src/core/ai/gateway.ts';import { fnv1a } from '../src/eval/deterministic-embed.ts';import type { PGLiteEngine } from '../src/core/pglite-engine.ts';+import type { BrainEngine } from '../src/core/engine.ts';const FIXTURE = join(import.meta.dir, 'fixtures', 'longmemeval-mixedcase.jsonl');const BASE = ['--keyword-only', '--retrieval-only', '--no-trajectory', '--by-type', '--top-k', '5'];@@ -538,7 +539,7 @@ describe('silent vector-arm / expansion degradation is a gate (mirrors --rerankedescribe('reranker preflight keys on the RESOLVED pin', () => {const NON_KW = [FIXTURE, '--retrieval-only', '--no-trajectory', '--by-type', '--top-k', '5'];- const notReady = async (_engine: PGLiteEngine, model: string) => ({ plane: 'config' as const, readiness: rerankerReadiness(model, {}) }); // no provider key → not ready+ const notReady = async (_engine: BrainEngine, model: string) => ({ plane: 'config' as const, readiness: rerankerReadiness(model, {}) }); // no provider key → not readytest('--reranker on + a not-ready reranker exits 2 with the fix text before any question runs', async () => {const out = join(tmp, 'preflight.jsonl');@@ -550,7 +551,7 @@ describe('reranker preflight keys on the RESOLVED pin', () => {test('NO --reranker flag: the balanced bundle turns the reranker on → the same preflight fires (exit 2); --reranker off skips it', async () => {const out = join(tmp, 'preflight-bundle.jsonl');let probes = 0;- const probe = async (e: PGLiteEngine, model: string) => { probes++; return notReady(e, model); };+ const probe = async (e: BrainEngine, model: string) => { probes++; return notReady(e, model); };const code = await runCapturingExit([...NON_KW, '--mode', 'balanced', '--output', out], { engine, rerankerReadiness: probe });expect(code).toBe(2);expect(probes).toBe(1);diff --git a/test/file-upload-security.test.ts b/test/file-upload-security.test.tsindex 5e4b2a78fc..52a314aa09 100644--- a/test/file-upload-security.test.ts+++ b/test/file-upload-security.test.ts@@ -1,6 +1,6 @@import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'bun:test';import { mkdtempSync, rmSync, writeFileSync, symlinkSync, mkdirSync, realpathSync } from 'fs';-import { join } from 'path';+import { join, win32 } from 'path';import { tmpdir } from 'os';import {validateUploadPath,@@ -8,6 +8,7 @@ import {validateFilename,OperationError,} from '../src/core/operations.ts';+import { uploadPathInsideRoot } from '../src/core/ops/context.ts';// --- validateUploadPath ---@@ -61,6 +62,63 @@ describe('validateUploadPath', () => {}});+ it('allows a file under a folder whose name starts with two dots', () => {+ // `..drafts` is an ordinary name, not a parent-dir step: the confinement+ // check must compare path components, not a `..` string prefix.+ const dir = join(root, '..drafts');+ mkdirSync(dir, { recursive: true });+ const p = join(dir, 'report.pdf');+ writeFileSync(p, 'pdf');+ try {+ expect(validateUploadPath(p, root)).toBe(realpathSync(p));+ expect(validateUploadPath(p, root, true)).toBe(realpathSync(p));+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it('allows a file under a folder named exactly ... (three dots)', () => {+ const dir = join(root, '...');+ mkdirSync(dir, { recursive: true });+ const p = join(dir, 'note.txt');+ writeFileSync(p, 'hi');+ try {+ expect(validateUploadPath(p, root)).toBe(realpathSync(p));+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });++ it('rejects the confinement root itself', () => {+ expect(() => validateUploadPath(root, root)).toThrow(/within the working directory/i);+ });++ it('rejects a sibling directory that shares the root name as a prefix', () => {+ const sibling = `${root}-sibling`;+ mkdirSync(sibling, { recursive: true });+ const p = join(sibling, 'x.txt');+ writeFileSync(p, 'x');+ try {+ expect(() => validateUploadPath(p, root)).toThrow(/within the working directory/i);+ } finally {+ rmSync(sibling, { recursive: true, force: true });+ }+ });++ it('rejects a ..-named folder reached through a parent-dir step', () => {+ // `<root>/../..drafts-escape/x` leaves the root even though the folder+ // name itself only starts with two dots.+ const dir = join(root, '..', `..drafts-escape-${process.pid}`);+ mkdirSync(dir, { recursive: true });+ const p = join(dir, 'x.txt');+ writeFileSync(p, 'x');+ try {+ expect(() => validateUploadPath(p, root)).toThrow(/within the working directory/i);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+ });+it('rejects /etc/passwd (absolute path outside root)', () => {expect(() => validateUploadPath('/etc/passwd', root)).toThrow(OperationError);});@@ -238,3 +296,43 @@ describe('validateFilename', () => {expect(() => validateFilename('foo/bar.txt')).toThrow(OperationError);});});++// --- strict upload containment, Windows path shapes ---+// No Windows runner exists, and validateUploadPath's realpathSync never returns+// backslash paths on POSIX, so these drive the pure comparison it uses with+// path.win32 shapes. The old check (relative + round trip) accepted another+// drive and a UNC share, because path.win32.relative across drives returns an+// absolute path that does not start with '..'.++describe('uploadPathInsideRoot — win32 shapes', () => {+ const root = 'C:\\work';+ const inside = (p: string) => uploadPathInsideRoot(p, root, win32.sep);++ it('the old relative-path check accepted another drive and a UNC share', () => {+ const oldCheck = (real: string) => {+ const rel = win32.relative(root, real);+ return !(rel === '' || rel.startsWith('..') || win32.resolve(root, rel) !== real);+ };+ expect(oldCheck('D:\\x.txt')).toBe(true);+ expect(oldCheck('\\\\srv\\share\\x.txt')).toBe(true);+ });++ it('refuses a file on another drive', () => {+ expect(inside('D:\\x.txt')).toBe(false);+ expect(inside('D:\\work\\x.txt')).toBe(false);+ });++ it('refuses a file on a UNC share', () => {+ expect(inside('\\\\srv\\share\\x.txt')).toBe(false);+ });++ it('refuses a sibling folder sharing the root name, and the root itself', () => {+ expect(inside('C:\\work-sibling\\x.txt')).toBe(false);+ expect(inside('C:\\work')).toBe(false);+ });++ it('accepts a file under a folder whose name starts with two dots', () => {+ expect(inside('C:\\work\\..drafts\\report.pdf')).toBe(true);+ expect(inside('C:\\work\\a.txt')).toBe(true);+ });+});diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.jsonindex 67c1997457..4bdd753ce3 100644--- a/test/fixtures/goldens/exports/types.json+++ b/test/fixtures/goldens/exports/types.json@@ -190,6 +190,7 @@"readPageSnapshotsBatch: (refs: ReadonlyArray<{ slug: string; sourceId: string; }>, opts?: { maxBytes?: number; includeDeleted?: boolean; absentIsNull?: boolean; }) => Promise<PageSnapshotBatch>","readSegmentDerivations: (pageId: number, opts?: { kind?: SegmentDerivationKind; occurrenceIds?: readonly number[]; }) => Promise<SegmentDerivationRow[]>","readSegmentTexts: (sourceId: string, sha256s: readonly Uint8Array[]) => Promise<Map<string, Uint8Array>>",+ "readonly capabilities: EngineCapabilities","readonly kind: \"postgres\" | \"pglite\"","reconnect: (ctx?: { error?: unknown; }) => Promise<void>","refreshPageBody: (slug: string, sourceId: string, compiledTruth: string, timeline: string, contentHash: string) => Promise<void>",@@ -1252,6 +1253,7 @@"readSegmentDerivations: (pageId: number, opts?: { kind?: SegmentDerivationKind; occurrenceIds?: readonly number[]; }) => Promise<SegmentDerivationRow[]>","readSegmentTexts: (sourceId: string, sha256s: readonly Uint8Array[]) => Promise<Map<string, Uint8Array>>","readonly [ENGINE_ROOT]: object",+ "readonly capabilities: EngineCapabilities","readonly kind: \"postgres\"","reconnect: (ctx?: { error?: unknown; }) => Promise<void>","refreshPageBody: (slug: string, sourceId: string, compiledTruth: string, timeline: string, contentHash: string) => Promise<void>",@@ -3764,6 +3766,7 @@"readPageSnapshotsBatch: (refs: ReadonlyArray<{ slug: string; sourceId: string; }>, opts?: { maxBytes?: number; includeDeleted?: boolean; absentIsNull?: boolean; }) => Promise<PageSnapshotBatch>","readSegmentDerivations: (pageId: number, opts?: { kind?: SegmentDerivationKind; occurrenceIds?: readonly number[]; }) => Promise<SegmentDerivationRow[]>","readSegmentTexts: (sourceId: string, sha256s: readonly Uint8Array[]) => Promise<Map<string, Uint8Array>>",+ "readonly capabilities: EngineCapabilities","readonly kind: \"postgres\" | \"pglite\"","reconnect: (ctx?: { error?: unknown; }) => Promise<void>","refreshPageBody: (slug: string, sourceId: string, compiledTruth: string, timeline: string, contentHash: string) => Promise<void>",@@ -6012,7 +6015,7 @@"kind": "type","name": "ParsedMarkdownFields","signature": [- "{ title: string; slug: string; type: PageType; typeExplicit?: boolean | undefined; inferredSubtype?: { type: string; name: string; } | undefined; tags: string[]; errors?: ParseValidationError[] | undefined; warnings?: ParseValidationWarning[] | undefined; recovery?: FrontmatterRecovery | undefined; }"+ "{ title: string; slug: string; type: PageType; tags: string[]; typeExplicit?: boolean | undefined; inferredSubtype?: { type: string; name: string; } | undefined; errors?: ParseValidationError[] | undefined; warnings?: ParseValidationWarning[] | undefined; recovery?: FrontmatterRecovery | undefined; }"]},{@@ -6879,7 +6882,7 @@{"kind": "class","members": [- "canonical?: \"unknown\" | \"timeout\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"rate_limited\" | \"embedding_disabled\" | \"writer_lock_unavailable\" | \"writer_pool_capacity\" | \"owner_unavailable\" | \"recovery_required\" | \"queue_capacity\" | \"write_quota_exhausted\" | \"write_quota_insufficient\" | \"write_capacity_backpressure\" | \"revision_required\" | \"revision_conflict\" | \"idempotency_conflict\" | \"source_changed\" | \"write_pending\" | \"storage_error\" | \"cancelled\" | \"permission_denied\" | \"scope_denied\" | \"invalid_params\" | \"not_found\" | \"page_not_found\" | \"page_identity_changed\" | \"write_claim_lost\" | \"request_too_large\" | \"response_too_large\" | \"writer_registration_required\" | \"writer_identity_invalid\" | \"writer_not_initialized\" | \"writer_coordinator_required\" | \"fact_already_expired\" | \"source_writeback_required\" | \"unsupported_mutation_protocol\" | \"writer_upgrade_required\" | \"writer_not_quiesced\" | \"skill_bundle_required\" | \"take_row_collision\" | \"invalid_source_uri\" | \"writer_admin_locked\" | \"connector_account_changed\" | \"connector_intent_outdated\" | \"checkpoint_validation_timeout\" | \"invalid_connector_text\" | \"connector_holds_exhausted\" | \"connector_fence_below_timeline\" | \"core_budget_exceeded\" | \"core_mark_owner_only\" | \"core_remote_edit_refused\" | \"core_delete_owner_only\" | \"timeline_rows_would_be_removed\" | \"purged_content\" | \"preparation_stalled\" | \"fence_unrenderable\" | \"page_body_segmented\" | \"page_body_rows_unreadable\" | \"revision_changed\" | \"tail_changed\" | \"write_outcome_unknown\" | \"write_interrupted\" | \"connection_inherited_read_only\" | \"owner_marker_missing\" | \"embedding_failed\" | \"bucket_not_found\" | \"database_error\" | \"unknown_transport\" | \"extraction_failed\" | \"fact_not_found\" | \"provenance_required\" | \"unavailable\" | \"budget_unsatisfiable\" | \"embedding_budget_below_worst_case\" | \"absent_from_worktree\" | \"access_command_failed\" | \"access_identity_unavailable\" | \"access_member_disabled\" | \"archive_audience_unproven\" | \"archive_gateway_unreachable\" | \"archive_gateway_auth\" | \"archive_gateway_failed\" | \"archive_owner_unset\" | \"archive_redaction_failed\" | \"archive_run_busy\" | \"autopilot_no_repo\" | \"autopilot_pglite_daemon\" | \"cycle_already_running\" | \"engine_degraded\" | \"maintenance_disabled\" | \"maintenance_owned_by_serve\" | \"schedule_unsupported\" | \"schedule_install_failed\" | \"maintenance_owned_by_autopilot\" | \"on_behalf_of_invalid_audience\" | \"on_behalf_of_unknown_member\" | \"on_behalf_of_not_permitted\" | \"actor_not_attested\" | \"actor_unlinked\" | \"on_behalf_of_in_arguments\" | \"access_policy_invalid\" | \"access_policy_pending\" | \"access_policy_widening_held\" | \"access_policy_history_unreadable\" | \"access_policy_store_mismatch\" | \"access_rule_invalid\" | \"requester_scope_required\" | \"requester_scope_unknown\" | \"credential_scope_required\" | \"access_serves_roster_empty\" | \"access_serves_key_dir_in_git\" | \"repair_propose_dir_in_git\" | \"access_member_id_retired\" | \"access_labelled_only_owner\" | \"access_labelled_only_unnamed\" | \"access_member_invalid\" | \"access_denied_test_user\" | \"access_env_missing\" | \"acknowledgment_unavailable\" | \"admin_policy_enforced\" | \"admission_paused\" | \"ambient_capture_off\" | \"ambiguous_id\" | \"ambiguous_ref\" | \"ambiguous_skill\" | \"answer_not_yours\" | \"answer_pending\" | \"answer_unavailable\" | \"api_not_enabled\" | \"append_links_fence\" | \"approval_required\" | \"atom_drain_incomplete\" | \"atom_drain_no_progress\" | \"atom_drain_provider_failure\" | \"autopilot_job_owned_by_other_brain\" | \"body_staging_expired\" | \"budget_below_recent_runtime\" | \"backup_dump_failed\" | \"backup_too_large\" | \"belief_coverage_required\" | \"belief_stale_preparation\" | \"benchmark_duplicate_task_id\" | \"benchmark_empty\" | \"benchmark_exists\" | \"benchmark_judge_llm_no_rubric\" | \"benchmark_judge_qrels_no_expected\" | \"benchmark_judge_rule_no_checks\" | \"benchmark_judge_unknown_kind\" | \"benchmark_malformed\" | \"benchmark_missing_judge\" | \"benchmark_missing_task\" | \"benchmark_missing_task_id\" | \"benchmark_not_found\" | \"benchmark_rule_check_bad_arg\" | \"benchmark_rule_check_malformed\" | \"benchmark_rule_check_unknown_op\" | \"bootstrap_cleanup_pending\" | \"bootstrap_empty\" | \"bootstrap_pending_review\" | \"bridge_ownership_conflict\" | \"valid_time_undeclared\" | \"coverage_from\" | \"coverage_gap\" | \"clock_mismatch\" | \"extract_write_lost\" | \"item_failures_systemic\" | \"known_as_of_unproven\" | \"cache_quota_exceeded\" | \"calendar_unreadable\" | \"capacity_paused\" | \"catalog_capacity_exceeded\" | \"catalog_unavailable\" | \"host_upgrade_required\" | \"change_reason_rejected\" | \"changed_since_preview\" | \"chronicle_skipped\" | \"no_pricing\" | \"checkout_not_a_source\" | \"checkpoint_missing\" | \"claim_already_used\" | \"client_behind\" | \"client_json_unreadable\" | \"client_json_wrong_type\" | \"client_not_found\" | \"client_shape_invalid\" | \"code_callees_requires_symbol\" | \"code_callers_requires_symbol\" | \"code_def_requires_symbol\" | \"code_refs_requires_symbol\" | \"code_reused\" | \"colon_slug_windows_write_through\" | \"command_failed\" | \"commit_lock_busy\" | \"commit_base_moved\" | \"commit_paths_unmerged\" | \"commit_paths_invalid\" | \"commit_paths_skipped\" | \"commit_prestaged_paths\" | \"commit_outside_source_root\" | \"concurrent_write\" | \"config_error\" | \"confirmation_required\" | \"conflicting_source_scope\" | \"connection_lost\" | \"connector_access_denied\" | \"connector_auth_required\" | \"connector_binding_missing\" | \"connector_item_too_large\" | \"connector_response_too_large\" | \"connector_shape_drift\" | \"chunkless_pages_healable\" | \"consent_required\" | \"consent_timeout\" | \"consumers_without_heartbeat\" | \"content_repair_needs_human\" | \"content_filter_owned\" | \"content_null_bytes\" | \"content_rejected\" | \"continuation_unproven\" | \"corpus_chat_unavailable\" | \"corpus_window_backoff\" | \"corpus_window_dead_lettered\" | \"convergence_read_failed\" | \"cost_cap_exceeded\" | \"cost_preview_requires_yes\" | \"cursor_incarnation_retired\" | \"cycle_failed\" | \"d_sel_too_small\" | \"delta_cursor_upgrade_required\" | \"deleted_page_chunks_overdue\" | \"demo_graph_failed\" | \"downgrade_blocked_deferred_writes\" | \"demo_import_failed\" | \"demo_verification_failed\" | \"derived_cap_exhausted\" | \"destination_not_ready\" | \"drain_holder_stalled\" | \"drain_stalled\" | \"managed_sync_not_moving\" | \"dream_breaker_tripped\" | \"dirty_tree\" | \"doctor_alert_act\" | \"doctor_alert_unknown\" | \"doctor_tier_unavailable\" | \"effect_not_failed\" | \"embed_backfill_stalled\" | \"embedding_auth_failed\" | \"embedding_configuration\" | \"embedding_identity_unqualified\" | \"embedding_model_mismatch\" | \"embedding_plane_split\" | \"embedding_state_unknown\" | \"embedding_storage_unavailable\" | \"embedding_unavailable\" | \"embedding_unconfigured\" | \"embedding_width_mismatch\" | \"embedded_core_required\" | \"enforced_member_refused\" | \"engine_embedding_mismatch\" | \"embedded_engine_required\" | \"engine_closed\" | \"engine_host_missing\" | \"engine_scope_missing\" | \"engine_scope_required\" | \"engine_settings_invalid\" | \"engine_graduated\" | \"entity_types_unavailable\" | \"eval_suite_unwired\" | \"explicit_tasks_conflict\" | \"export_limit\" | \"extractor_identity_mismatch\" | \"fact_withdrawn\" | \"fact_rows_collide\" | \"fence_row_changed\" | \"facts_absorb_write_refused\" | \"facts_backstop_skipped\" | \"facts_drain_deferred\" | \"facts_drain_job_failed\" | \"facts_payload_expired\" | \"feedback_disabled\" | \"feedback_not_authorized\" | \"fetch_failed\" | \"file_database_drift\" | \"fix_not_writable\" | \"file_drift\" | \"file_drift_mixed_selection\" | \"file_drift_state_required\" | \"file_removed_during_scan\" | \"file_unreadable\" | \"file_wins_rewrite\" | \"file_too_large\" | \"follow_approval_required\" | \"foreign_table\" | \"forget_requires_owner\" | \"reserved_frontmatter_key\" | \"generation_fenced\" | \"generation_held\" | \"generation_live_conflict\" | \"frontmatter_slug_conflict\" | \"full_resync_required\" | \"gate_failed\" | \"ghost_mass_delete_refused\" | \"notifier_stalled\" | \"moved_pages_mass_fold_refused\" | \"origin_twin_mass_merge_refused\" | \"ghost_storage_unknown\" | \"git_branch_unborn\" | \"git_durability_not_enabled\" | \"git_checkout_required\" | \"git_worktree_link_broken\" | \"hosted_repo_refused\" | \"git_detached_head\" | \"git_index_conflict\" | \"git_index_locked\" | \"git_index_stale\" | \"git_target_pending\" | \"git_operation_in_progress\" | \"git_push_unavailable\" | \"git_target_changed\" | \"git_target_ignored\" | \"git_target_unsafe\" | \"git_command_stopped\" | \"git_unavailable\" | \"git_object_missing\" | \"git_conversion_blocked\" | \"git_conversion_delta\" | \"conversion_file_in_source_root\" | \"git_conversion_incomplete\" | \"git_home_required\" | \"git_private_commit_refused\" | \"git_protocol_required\" | \"git_lfs_not_enabled\" | \"gitlink_not_followed\" | \"graduation_drain_timeout\" | \"graduation_embedding_dimension_mismatch\" | \"graduation_foreign_host_binding\" | \"graduation_in_progress\" | \"graduation_interrupted\" | \"graduation_rollback_writes_lost\" | \"graduation_source_writer_held\" | \"graduation_split_brain\" | \"graduation_target_auth_failed\" | \"graduation_target_ddl_unreachable\" | \"graduation_target_not_empty\" | \"graduation_target_unsupported\" | \"graduation_unclassified_table\" | \"graduation_unsupported_platform\" | \"graduation_verify_failed\" | \"grant_scope\" | \"graph_incomplete\" | \"host_identity_mismatch\" | \"harness_hook_duplicates\" | \"harness_hook_unowned\" | \"head_blocked\" | \"held_failed\" | \"held_out_overlaps_benchmark\" | \"held_out_required_for_bundled\" | \"independent_principal_required\" | \"insufficient_scope\" | \"integrate_conflict\" | \"internal\" | \"internal_error\" | \"interrupted\" | \"invalid_acknowledgment\" | \"invalid_client\" | \"invalid_fence\" | \"unclosed_ambiguous_tail\" | \"tail_exposure_approval\" | \"sync_in_progress\" | \"invalid_frontmatter\" | \"invalid_grant_clock_skew\" | \"invalid_grant_revoked\" | \"invalid_grant_testing_expiry\" | \"invalid_rating\" | \"invalid_receipt\" | \"invalid_receipt_transition\" | \"invalid_request\" | \"invalid_source\" | \"invalid_source_pin\" | \"invalid_token\" | \"invalid_write_wait\" | \"ipc_path_too_long\" | \"legacy_twin_mass_merge_refused\" | \"legacy_twins_storage_unknown\" | \"legacy_job_selection_invalid\" | \"legacy_jobs_active\" | \"legacy_lock_removal_refused\" | \"link_cursor_invalid\" | \"link_dates_unattributed\" | \"local_conflict\" | \"lock_busy\" | \"loops_extraction_skipped\" | \"maintenance_backpressure\" | \"maintenance_lock_busy\" | \"managed_failure_unsettled\" | \"managed_remedy_unavailable\" | \"memory_setting_write_outcome_unknown\" | \"merge_recommended\" | \"movement_unknown\" | \"managed_sync_flag_refused\" | \"managed_pull_skipped\" | \"manual_only_skipped\" | \"membership_inactive\" | \"membership_not_found\" | \"method_not_allowed\" | \"migration_lease_lost\" | \"migration_declined\" | \"migration_failed\" | \"migration_host_work_pending\" | \"migration_host_work_owed\" | \"migrations_pending\" | \"migrations_running\" | \"missing_source_scope\" | \"missing_source_value\" | \"models_strict_violation\" | \"no_context_ceiling\" | \"no_refresh_token\" | \"no_routing_eval\" | \"no_skill_md\" | \"no_worker\" | \"no_worker_surface\" | \"not_a_git_repo\" | \"not_converged\" | \"not_owner_host\" | \"not_connected\" | \"no_brain\" | \"overlapping_path\" | \"page_projection_conflict\" | \"page_projection_stale\" | \"label_edit_refused\" | \"page_shrink_refused\" | \"page_too_large_for_inline\" | \"parse_error\" | \"part_splits_code_point\" | \"part_too_large\" | \"frontmatter_alias_limit\" | \"parser_regression\" | \"pasted_wrong_url\" | \"payload_too_large\" | \"path_not_utf8\" | \"pattern_claims_pending\" | \"patterns_min_interval\" | \"pending_verify\" | \"pending_writes\" | \"persistence_restart_required\" | \"pool_inflight_over_budget\" | \"deep_health_probe_failed\" | \"refresh_required\" | \"serve_self_exit_suppressed\" | \"serve_unhealthy_exit\" | \"persistence_write_stall\" | \"publish_secret_found\" | \"publish_scan_unreadable\" | \"push_unconfirmed\" | \"schema_lock_blocked\" | \"postgres_tls_required\" | \"pg_connection_recovery_failed\" | \"pg_connection_stuck\" | \"pg_pool_stalled\" | \"pg_statement_build_failed\" | \"pglite_busy\" | \"pglite_vector_index_too_large\" | \"plan_output_failed\" | \"plan_stale\" | \"port_in_use\" | \"preview_changed\" | \"profile_incompatible\" | \"projection_owner_resident\" | \"knock_on_exhausted\" | \"keyword_skipped_after_timeout\" | \"proposal_closed\" | \"proposal_expired\" | \"proposals_pending_limit\" | \"provider_response_unparseable\" | \"publication_pending\" | \"pull_blocked_local_changes\" | \"purge_blocked_pending_recovery\" | \"purge_lookup_timeout\" | \"purge_mirror_unwritable\" | \"purge_replay_incomplete\" | \"question_not_found\" | \"question_owner_only\" | \"rank_entities_timeout\" | \"read_budget_exhausted\" | \"reason_purge_scan_capped\" | \"reason_purge_scan_failed\" | \"reason_scan_capped\" | \"reason_scan_failed\" | \"reason_trailer_secret\" | \"receipt_conflict\" | \"receipt_fence_changed\" | \"receipt_fence_required\" | \"receipt_identity_mismatch\" | \"pat_file_unreadable\" | \"reconcile_host_required\" | \"reconcile_read_incomplete\" | \"recovery_prior_stage_unavailable\" | \"recovery_version_unsupported\" | \"redirect_uri_mismatch\" | \"ref_not_in_answer\" | \"refresh_dirty\" | \"refresh_diverged\" | \"refresh_drain_timeout\" | \"refresh_lock_timeout\" | \"refresh_no_upstream\" | \"refresh_not_managed\" | \"refresh_not_owner\" | \"pending_import_expired\" | \"refresh_barrier_expired\" | \"refresh_source_changed\" | \"refresh_sync_timeout\" | \"relay_disabled\" | \"relay_session_expired\" | \"relay_unreachable\" | \"rename_held\" | \"rename_identity_unreadable\" | \"rename_reconcile_failed\" | \"repair_preview_timeout\" | \"request_already_submitted\" | \"requirements_changed\" | \"requires_local_engine\" | \"restart_refused\" | \"restart_unverified\" | \"runtime_build_skew\" | \"reset_upstream_refused\" | \"resume_spec_mismatch\" | \"result_too_large\" | \"revision_backfill_pending\" | \"revision_unavailable\" | \"schema_owner_required\" | \"scope_missing\" | \"search_cursor_requires_keyword\" | \"search_mode_local_only\" | \"scorecard_group_by_local_only\" | \"search_offset_over_cap\" | \"segmented_mirror_writer_gate\" | \"serve_build_drift\" | \"serve_port_in_use\" | \"serve_status_only\" | \"settle_mismatch\" | \"openclaw_not_found\" | \"setup_harness_unsupported\" | \"setup_hosted_connection\" | \"setup_owner_conflict\" | \"setup_serves_several\" | \"setup_history_choice_required\" | \"setup_serves_unreadable\" | \"hook_session_cwd\" | \"turn_hook_not_loaded\" | \"shared_skills_unavailable\" | \"shared_skills_unmanifested\" | \"shared_skills_unsupported\" | \"skill_asset_not_found\" | \"skill_candidate_invalid\" | \"skill_not_found\" | \"skill_catalog_mismatch\" | \"skill_catalog_too_large\" | \"skill_catalog_unknown\" | \"skill_index_incompatible\" | \"skill_index_locked\" | \"skill_index_missing\" | \"skill_index_removed\" | \"skill_resolve_invalid_input\" | \"skill_resolve_no_input\" | \"skill_resolve_timeout\" | \"skill_resolver_config_invalid\" | \"skill_resolver_config_unreadable\" | \"skill_resolver_setup_incomplete\" | \"skill_resolver_plugin_not_installed\" | \"skill_resolver_host_not_local\" | \"skill_resolver_selftest_failed\" | \"skill_resolver_pin_unknown\" | \"skill_resolver_library_missing\" | \"skill_resolver_library_mismatch\" | \"skill_resolver_library_skew\" | \"skill_resolver_worker_crash\" | \"skill_resolver_worker_stuck\" | \"skill_resolver_worker_unavailable\" | \"skill_resolver_state_missing\" | \"skill_resolver_host_load_cut\" | \"skill_resolver_internal\" | \"skill_source_invalid\" | \"skill_source_unreadable\" | \"skill_retention_capacity\" | \"skill_unavailable\" | \"skillpack_backup_corrupt\" | \"skillpack_journal_not_found\" | \"skillpack_restore_conflict\" | \"skillpack_state_locked\" | \"skillpack_update_incomplete\" | \"skillpack_workspace_locked\" | \"slug_page_mismatch\" | \"slug_root_mode_mismatch\" | \"source_binding_required\" | \"source_id_taken\" | \"source_mismatch\" | \"source_not_ready\" | \"source_profile_no_backfill\" | \"source_pages_remain\" | \"source_referenced\" | \"source_retire_superseded\" | \"source_root_conflict\" | \"source_root_unreadable\" | \"sources_not_readable\" | \"split_bad_ratio\" | \"split_unparseable\" | \"stable_channel_unresolved\" | \"stable_invalid\" | \"stable_missing\" | \"stable_unreadable\" | \"stale_unavailable\" | \"state_mismatch\" | \"store_unavailable\" | \"storage_adopt_field_refused\" | \"storage_adopt_unverified\" | \"storage_card_exists\" | \"storage_manifest_missing\" | \"storage_record_invalid\" | \"storage_record_secret\" | \"storage_revision_conflict\" | \"storage_source_managed\" | \"strict_requires_managed\" | \"sync_anchor_relative\" | \"sync_not_applicable\" | \"sync_admission_restricted\" | \"sync_deadline_stalled\" | \"sync_drain_lease_held\" | \"content_receipt_stale\" | \"sync_first_run_in_progress\" | \"sync_no_successful_sync\" | \"sync_cursor_replaced\" | \"sync_pass_superseded\" | \"sync_parser_regression\" | \"tag_too_long\" | \"target_escape\" | \"timeline_comment_markup\" | \"source_writer_restricted\" | \"guest_page_immutable\" | \"guest_page_promoted\" | \"guest_attribution_missing\" | \"guest_frontmatter_refused\" | \"guest_readers_invalid\" | \"guest_promotion_owner_only\" | \"guest_mark_immutable\" | \"guest_source_database_only\" | \"readable_by_invalid\" | \"topology_change_required\" | \"transcript_secret_exposure\" | \"transcript_source_mismatch\" | \"triage_unreliable_backoff\" | \"trust_raise_refused\" | \"two_consumers_on_host\" | \"trusted_local_only\" | \"unexpected_file_bytes\" | \"unexpected_staging_bytes\" | \"unknown_command\" | \"unknown_flag\" | \"unknown_method\" | \"unknown_source\" | \"unknown_tool\" | \"unpriced_model\" | \"unmanaged_database_path\" | \"unmanaged_path\" | \"unsupported_export_data\" | \"unsupported_path\" | \"untrack_not_db_only\" | \"upload_expired\" | \"upload_not_found\" | \"upload_protected_content\" | \"upload_too_many_parts\" | \"upstream\" | \"upstream_diverged\" | \"upstream_rewritten\" | \"upstream_unknown\" | \"vector_prewarm_extension_missing\" | \"vector_prewarm_unsupported_engine\" | \"vector_prewarm_wont_fit\" | \"verification_failed\" | \"visibility_noncanonical\" | \"visibility_not_applied\" | \"wakeshift_key_invalid\" | \"wakeshift_needs_conversation\" | \"wakeshift_not_enabled\" | \"wakeshift_refused\" | \"wakeshift_shared_brain\" | \"wakeshift_unavailable\" | \"withdrawal_capacity\" | \"withdrawal_mirror_failed\" | \"withdrawal_mirror_pending\" | \"withdrawal_provenance\" | \"write_capacity_low\" | \"write_gate_rejected\" | \"write_held\" | \"worktree_dirty\" | \"worktree_refreshing\" | \"writer_admin_intent_required\" | \"writer_admin_state_changed\" | \"writer_busy\" | \"writer_identity_publish_failed\" | \"writer_manifest_mismatch\" | \"writer_manifest_rescope_required\" | \"writer_manifest_unsafe\" | \"writer_regrant_required\" | \"writer_transfer_conflict\" | \"writer_transfer_required\" | \"wrong_account_consented\" | \"schema_pack_too_large\" | \"schema_pack_emit_mismatch\" | undefined",+ "canonical?: \"unknown\" | \"timeout\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"rate_limited\" | \"embedding_disabled\" | \"writer_lock_unavailable\" | \"writer_pool_capacity\" | \"owner_unavailable\" | \"recovery_required\" | \"queue_capacity\" | \"write_quota_exhausted\" | \"write_quota_insufficient\" | \"write_capacity_backpressure\" | \"revision_required\" | \"revision_conflict\" | \"idempotency_conflict\" | \"source_changed\" | \"write_pending\" | \"storage_error\" | \"cancelled\" | \"permission_denied\" | \"scope_denied\" | \"invalid_params\" | \"not_found\" | \"page_not_found\" | \"page_identity_changed\" | \"write_claim_lost\" | \"request_too_large\" | \"response_too_large\" | \"writer_registration_required\" | \"writer_identity_invalid\" | \"writer_not_initialized\" | \"writer_coordinator_required\" | \"fact_already_expired\" | \"source_writeback_required\" | \"unsupported_mutation_protocol\" | \"writer_upgrade_required\" | \"writer_not_quiesced\" | \"skill_bundle_required\" | \"take_row_collision\" | \"invalid_source_uri\" | \"writer_admin_locked\" | \"connector_account_changed\" | \"connector_intent_outdated\" | \"checkpoint_validation_timeout\" | \"invalid_connector_text\" | \"connector_holds_exhausted\" | \"connector_fence_below_timeline\" | \"core_budget_exceeded\" | \"core_mark_owner_only\" | \"core_remote_edit_refused\" | \"core_delete_owner_only\" | \"timeline_rows_would_be_removed\" | \"purged_content\" | \"preparation_stalled\" | \"fence_unrenderable\" | \"page_body_segmented\" | \"page_body_rows_unreadable\" | \"revision_changed\" | \"tail_changed\" | \"write_outcome_unknown\" | \"write_interrupted\" | \"connection_inherited_read_only\" | \"owner_marker_missing\" | \"embedding_failed\" | \"bucket_not_found\" | \"database_error\" | \"unknown_transport\" | \"extraction_failed\" | \"fact_not_found\" | \"provenance_required\" | \"unavailable\" | \"budget_unsatisfiable\" | \"embedding_budget_below_worst_case\" | \"absent_from_worktree\" | \"access_command_failed\" | \"access_identity_unavailable\" | \"access_member_disabled\" | \"archive_audience_unproven\" | \"archive_gateway_unreachable\" | \"archive_gateway_auth\" | \"archive_gateway_failed\" | \"archive_owner_unset\" | \"archive_redaction_failed\" | \"archive_run_busy\" | \"autopilot_no_repo\" | \"autopilot_pglite_daemon\" | \"cycle_already_running\" | \"engine_degraded\" | \"rust_engine_addon_missing\" | \"rust_engine_addon_mismatch\" | \"maintenance_disabled\" | \"maintenance_owned_by_serve\" | \"schedule_unsupported\" | \"schedule_install_failed\" | \"maintenance_owned_by_autopilot\" | \"on_behalf_of_invalid_audience\" | \"on_behalf_of_unknown_member\" | \"on_behalf_of_not_permitted\" | \"actor_not_attested\" | \"actor_unlinked\" | \"on_behalf_of_in_arguments\" | \"access_policy_invalid\" | \"access_policy_pending\" | \"access_policy_widening_held\" | \"access_policy_history_unreadable\" | \"access_policy_store_mismatch\" | \"access_rule_invalid\" | \"requester_scope_required\" | \"requester_scope_unknown\" | \"credential_scope_required\" | \"access_serves_roster_empty\" | \"access_serves_key_dir_in_git\" | \"repair_propose_dir_in_git\" | \"access_member_id_retired\" | \"access_labelled_only_owner\" | \"access_labelled_only_unnamed\" | \"access_member_invalid\" | \"access_denied_test_user\" | \"access_env_missing\" | \"acknowledgment_unavailable\" | \"admin_policy_enforced\" | \"admission_paused\" | \"ambient_capture_off\" | \"ambiguous_id\" | \"ambiguous_ref\" | \"ambiguous_skill\" | \"answer_not_yours\" | \"answer_pending\" | \"answer_unavailable\" | \"api_not_enabled\" | \"append_links_fence\" | \"approval_required\" | \"atom_drain_incomplete\" | \"atom_drain_no_progress\" | \"atom_drain_provider_failure\" | \"autopilot_job_owned_by_other_brain\" | \"body_staging_expired\" | \"budget_below_recent_runtime\" | \"backup_dump_failed\" | \"backup_too_large\" | \"belief_coverage_required\" | \"belief_stale_preparation\" | \"benchmark_duplicate_task_id\" | \"benchmark_empty\" | \"benchmark_exists\" | \"benchmark_judge_llm_no_rubric\" | \"benchmark_judge_qrels_no_expected\" | \"benchmark_judge_rule_no_checks\" | \"benchmark_judge_unknown_kind\" | \"benchmark_malformed\" | \"benchmark_missing_judge\" | \"benchmark_missing_task\" | \"benchmark_missing_task_id\" | \"benchmark_not_found\" | \"benchmark_rule_check_bad_arg\" | \"benchmark_rule_check_malformed\" | \"benchmark_rule_check_unknown_op\" | \"bootstrap_cleanup_pending\" | \"bootstrap_empty\" | \"bootstrap_pending_review\" | \"bridge_ownership_conflict\" | \"valid_time_undeclared\" | \"coverage_from\" | \"coverage_gap\" | \"clock_mismatch\" | \"extract_write_lost\" | \"item_failures_systemic\" | \"known_as_of_unproven\" | \"cache_quota_exceeded\" | \"calendar_unreadable\" | \"capacity_paused\" | \"catalog_capacity_exceeded\" | \"catalog_unavailable\" | \"host_upgrade_required\" | \"change_reason_rejected\" | \"changed_since_preview\" | \"chronicle_skipped\" | \"no_pricing\" | \"checkout_not_a_source\" | \"checkpoint_missing\" | \"claim_already_used\" | \"client_behind\" | \"client_json_unreadable\" | \"client_json_wrong_type\" | \"client_not_found\" | \"client_shape_invalid\" | \"code_callees_requires_symbol\" | \"code_callers_requires_symbol\" | \"code_def_requires_symbol\" | \"code_refs_requires_symbol\" | \"code_reused\" | \"colon_slug_windows_write_through\" | \"command_failed\" | \"commit_lock_busy\" | \"commit_base_moved\" | \"commit_paths_unmerged\" | \"commit_paths_invalid\" | \"commit_paths_skipped\" | \"commit_prestaged_paths\" | \"commit_outside_source_root\" | \"concurrent_write\" | \"config_error\" | \"confirmation_required\" | \"conflicting_source_scope\" | \"connection_lost\" | \"connector_access_denied\" | \"connector_auth_required\" | \"connector_binding_missing\" | \"connector_item_too_large\" | \"connector_response_too_large\" | \"connector_shape_drift\" | \"chunkless_pages_healable\" | \"consent_required\" | \"consent_timeout\" | \"consumers_without_heartbeat\" | \"content_repair_needs_human\" | \"content_filter_owned\" | \"content_null_bytes\" | \"content_rejected\" | \"continuation_unproven\" | \"corpus_chat_unavailable\" | \"corpus_window_backoff\" | \"corpus_window_dead_lettered\" | \"convergence_read_failed\" | \"cost_cap_exceeded\" | \"cost_preview_requires_yes\" | \"cursor_incarnation_retired\" | \"cycle_failed\" | \"d_sel_too_small\" | \"delta_cursor_upgrade_required\" | \"deleted_page_chunks_overdue\" | \"demo_graph_failed\" | \"downgrade_blocked_deferred_writes\" | \"demo_import_failed\" | \"demo_verification_failed\" | \"derived_cap_exhausted\" | \"destination_not_ready\" | \"drain_holder_stalled\" | \"drain_stalled\" | \"managed_sync_not_moving\" | \"dream_breaker_tripped\" | \"dirty_tree\" | \"doctor_alert_act\" | \"doctor_alert_unknown\" | \"doctor_tier_unavailable\" | \"effect_not_failed\" | \"embed_backfill_stalled\" | \"embedding_auth_failed\" | \"embedding_configuration\" | \"embedding_identity_unqualified\" | \"embedding_model_mismatch\" | \"embedding_plane_split\" | \"embedding_state_unknown\" | \"embedding_storage_unavailable\" | \"embedding_unavailable\" | \"embedding_unconfigured\" | \"embedding_width_mismatch\" | \"embedded_core_required\" | \"enforced_member_refused\" | \"engine_embedding_mismatch\" | \"embedded_engine_required\" | \"engine_closed\" | \"engine_host_missing\" | \"engine_scope_missing\" | \"engine_scope_required\" | \"engine_settings_invalid\" | \"engine_capability_missing\" | \"engine_graduated\" | \"entity_types_unavailable\" | \"eval_suite_unwired\" | \"explicit_tasks_conflict\" | \"export_limit\" | \"extractor_identity_mismatch\" | \"fact_withdrawn\" | \"fact_rows_collide\" | \"fence_row_changed\" | \"facts_absorb_write_refused\" | \"facts_backstop_skipped\" | \"facts_drain_deferred\" | \"facts_drain_job_failed\" | \"facts_payload_expired\" | \"feedback_disabled\" | \"feedback_not_authorized\" | \"fetch_failed\" | \"file_database_drift\" | \"fix_not_writable\" | \"file_drift\" | \"file_drift_mixed_selection\" | \"file_drift_state_required\" | \"file_removed_during_scan\" | \"file_unreadable\" | \"file_wins_rewrite\" | \"file_too_large\" | \"follow_approval_required\" | \"foreign_table\" | \"forget_requires_owner\" | \"reserved_frontmatter_key\" | \"generation_fenced\" | \"generation_held\" | \"generation_live_conflict\" | \"frontmatter_slug_conflict\" | \"full_resync_required\" | \"gate_failed\" | \"ghost_mass_delete_refused\" | \"notifier_stalled\" | \"moved_pages_mass_fold_refused\" | \"origin_twin_mass_merge_refused\" | \"ghost_storage_unknown\" | \"git_branch_unborn\" | \"git_durability_not_enabled\" | \"git_checkout_required\" | \"git_worktree_link_broken\" | \"hosted_repo_refused\" | \"git_detached_head\" | \"git_index_conflict\" | \"git_index_locked\" | \"git_index_stale\" | \"git_target_pending\" | \"git_operation_in_progress\" | \"git_push_unavailable\" | \"git_target_changed\" | \"git_target_ignored\" | \"git_target_unsafe\" | \"git_command_stopped\" | \"git_unavailable\" | \"git_object_missing\" | \"git_conversion_blocked\" | \"git_conversion_delta\" | \"conversion_file_in_source_root\" | \"git_conversion_incomplete\" | \"git_home_required\" | \"git_private_commit_refused\" | \"git_protocol_required\" | \"git_lfs_not_enabled\" | \"gitlink_not_followed\" | \"graduation_drain_timeout\" | \"graduation_embedding_dimension_mismatch\" | \"graduation_foreign_host_binding\" | \"graduation_in_progress\" | \"graduation_interrupted\" | \"graduation_rollback_writes_lost\" | \"graduation_source_writer_held\" | \"graduation_split_brain\" | \"graduation_target_auth_failed\" | \"graduation_target_ddl_unreachable\" | \"graduation_target_not_empty\" | \"graduation_target_unsupported\" | \"graduation_unclassified_table\" | \"graduation_unsupported_platform\" | \"graduation_verify_failed\" | \"grant_scope\" | \"graph_incomplete\" | \"host_identity_mismatch\" | \"harness_hook_duplicates\" | \"harness_hook_unowned\" | \"head_blocked\" | \"held_failed\" | \"held_out_overlaps_benchmark\" | \"held_out_required_for_bundled\" | \"independent_principal_required\" | \"insufficient_scope\" | \"integrate_conflict\" | \"internal\" | \"internal_error\" | \"interrupted\" | \"invalid_acknowledgment\" | \"invalid_client\" | \"invalid_fence\" | \"unclosed_ambiguous_tail\" | \"tail_exposure_approval\" | \"sync_in_progress\" | \"invalid_frontmatter\" | \"invalid_grant_clock_skew\" | \"invalid_grant_revoked\" | \"invalid_grant_testing_expiry\" | \"invalid_rating\" | \"invalid_receipt\" | \"invalid_receipt_transition\" | \"invalid_request\" | \"invalid_source\" | \"invalid_source_pin\" | \"invalid_token\" | \"invalid_write_wait\" | \"ipc_path_too_long\" | \"legacy_twin_mass_merge_refused\" | \"legacy_twins_storage_unknown\" | \"legacy_job_selection_invalid\" | \"legacy_jobs_active\" | \"legacy_lock_removal_refused\" | \"link_cursor_invalid\" | \"link_dates_unattributed\" | \"local_conflict\" | \"lock_busy\" | \"loops_extraction_skipped\" | \"maintenance_backpressure\" | \"maintenance_lock_busy\" | \"managed_failure_unsettled\" | \"managed_remedy_unavailable\" | \"memory_setting_write_outcome_unknown\" | \"merge_recommended\" | \"movement_unknown\" | \"managed_sync_flag_refused\" | \"managed_pull_skipped\" | \"manual_only_skipped\" | \"membership_inactive\" | \"membership_not_found\" | \"method_not_allowed\" | \"migration_lease_lost\" | \"migration_declined\" | \"migration_failed\" | \"migration_host_work_pending\" | \"migration_host_work_owed\" | \"migrations_pending\" | \"migrations_running\" | \"missing_source_scope\" | \"missing_source_value\" | \"models_strict_violation\" | \"no_context_ceiling\" | \"no_refresh_token\" | \"no_routing_eval\" | \"no_skill_md\" | \"no_worker\" | \"no_worker_surface\" | \"not_a_git_repo\" | \"not_converged\" | \"not_owner_host\" | \"not_connected\" | \"no_brain\" | \"overlapping_path\" | \"page_projection_conflict\" | \"page_projection_stale\" | \"label_edit_refused\" | \"page_shrink_refused\" | \"page_too_large_for_inline\" | \"parse_error\" | \"part_splits_code_point\" | \"part_too_large\" | \"frontmatter_alias_limit\" | \"parser_regression\" | \"pasted_wrong_url\" | \"payload_too_large\" | \"path_not_utf8\" | \"pattern_claims_pending\" | \"patterns_min_interval\" | \"pending_verify\" | \"pending_writes\" | \"persistence_restart_required\" | \"pool_inflight_over_budget\" | \"deep_health_probe_failed\" | \"refresh_required\" | \"serve_self_exit_suppressed\" | \"serve_unhealthy_exit\" | \"persistence_write_stall\" | \"publish_secret_found\" | \"publish_scan_unreadable\" | \"push_unconfirmed\" | \"schema_lock_blocked\" | \"postgres_tls_required\" | \"pg_connection_recovery_failed\" | \"pg_connection_stuck\" | \"pg_pool_stalled\" | \"pg_statement_build_failed\" | \"pglite_busy\" | \"pglite_vector_index_too_large\" | \"plan_output_failed\" | \"plan_stale\" | \"port_in_use\" | \"preview_changed\" | \"profile_incompatible\" | \"projection_owner_resident\" | \"knock_on_exhausted\" | \"keyword_skipped_after_timeout\" | \"proposal_closed\" | \"proposal_expired\" | \"proposals_pending_limit\" | \"provider_response_unparseable\" | \"publication_pending\" | \"pull_blocked_local_changes\" | \"purge_blocked_pending_recovery\" | \"purge_lookup_timeout\" | \"purge_mirror_unwritable\" | \"purge_replay_incomplete\" | \"question_not_found\" | \"question_owner_only\" | \"rank_entities_timeout\" | \"read_budget_exhausted\" | \"reason_purge_scan_capped\" | \"reason_purge_scan_failed\" | \"reason_scan_capped\" | \"reason_scan_failed\" | \"reason_trailer_secret\" | \"receipt_conflict\" | \"receipt_fence_changed\" | \"receipt_fence_required\" | \"receipt_identity_mismatch\" | \"pat_file_unreadable\" | \"reconcile_host_required\" | \"reconcile_read_incomplete\" | \"recovery_prior_stage_unavailable\" | \"recovery_version_unsupported\" | \"redirect_uri_mismatch\" | \"ref_not_in_answer\" | \"refresh_dirty\" | \"refresh_diverged\" | \"refresh_drain_timeout\" | \"refresh_lock_timeout\" | \"refresh_no_upstream\" | \"refresh_not_managed\" | \"refresh_not_owner\" | \"pending_import_expired\" | \"refresh_barrier_expired\" | \"refresh_source_changed\" | \"refresh_sync_timeout\" | \"relay_disabled\" | \"relay_session_expired\" | \"relay_unreachable\" | \"rename_held\" | \"rename_identity_unreadable\" | \"rename_reconcile_failed\" | \"repair_preview_timeout\" | \"request_already_submitted\" | \"requirements_changed\" | \"requires_local_engine\" | \"restart_refused\" | \"restart_unverified\" | \"runtime_build_skew\" | \"reset_upstream_refused\" | \"resume_spec_mismatch\" | \"result_too_large\" | \"revision_backfill_pending\" | \"revision_unavailable\" | \"schema_owner_required\" | \"scope_missing\" | \"search_cursor_requires_keyword\" | \"search_mode_local_only\" | \"scorecard_group_by_local_only\" | \"search_offset_over_cap\" | \"segmented_mirror_writer_gate\" | \"serve_build_drift\" | \"serve_port_in_use\" | \"serve_status_only\" | \"settle_mismatch\" | \"openclaw_not_found\" | \"setup_harness_unsupported\" | \"setup_hosted_connection\" | \"setup_owner_conflict\" | \"setup_serves_several\" | \"setup_history_choice_required\" | \"setup_serves_unreadable\" | \"hook_session_cwd\" | \"turn_hook_not_loaded\" | \"shared_skills_unavailable\" | \"shared_skills_unmanifested\" | \"shared_skills_unsupported\" | \"skill_asset_not_found\" | \"skill_candidate_invalid\" | \"skill_not_found\" | \"skill_catalog_mismatch\" | \"skill_catalog_too_large\" | \"skill_catalog_unknown\" | \"skill_index_incompatible\" | \"skill_index_locked\" | \"skill_index_missing\" | \"skill_index_removed\" | \"skill_resolve_invalid_input\" | \"skill_resolve_no_input\" | \"skill_resolve_timeout\" | \"skill_resolver_config_invalid\" | \"skill_resolver_config_unreadable\" | \"skill_resolver_setup_incomplete\" | \"skill_resolver_plugin_not_installed\" | \"skill_resolver_host_not_local\" | \"skill_resolver_selftest_failed\" | \"skill_resolver_pin_unknown\" | \"skill_resolver_library_missing\" | \"skill_resolver_library_mismatch\" | \"skill_resolver_library_skew\" | \"skill_resolver_worker_crash\" | \"skill_resolver_worker_stuck\" | \"skill_resolver_worker_unavailable\" | \"skill_resolver_state_missing\" | \"skill_resolver_host_load_cut\" | \"skill_resolver_internal\" | \"skill_source_invalid\" | \"skill_source_unreadable\" | \"skill_retention_capacity\" | \"skill_unavailable\" | \"skillpack_backup_corrupt\" | \"skillpack_journal_not_found\" | \"skillpack_restore_conflict\" | \"skillpack_state_locked\" | \"skillpack_update_incomplete\" | \"skillpack_workspace_locked\" | \"slug_page_mismatch\" | \"slug_root_mode_mismatch\" | \"source_binding_required\" | \"source_id_taken\" | \"source_mismatch\" | \"source_not_ready\" | \"source_profile_no_backfill\" | \"source_pages_remain\" | \"source_referenced\" | \"source_retire_superseded\" | \"source_root_conflict\" | \"source_root_unreadable\" | \"sources_not_readable\" | \"split_bad_ratio\" | \"split_unparseable\" | \"stable_channel_unresolved\" | \"stable_invalid\" | \"stable_missing\" | \"stable_unreadable\" | \"stale_unavailable\" | \"state_mismatch\" | \"store_unavailable\" | \"storage_adopt_field_refused\" | \"storage_adopt_unverified\" | \"storage_card_exists\" | \"storage_manifest_missing\" | \"storage_record_invalid\" | \"storage_record_secret\" | \"storage_revision_conflict\" | \"storage_source_managed\" | \"strict_requires_managed\" | \"sync_anchor_relative\" | \"sync_not_applicable\" | \"sync_admission_restricted\" | \"sync_deadline_stalled\" | \"sync_drain_lease_held\" | \"content_receipt_stale\" | \"sync_first_run_in_progress\" | \"sync_no_successful_sync\" | \"sync_cursor_replaced\" | \"sync_pass_superseded\" | \"sync_parser_regression\" | \"tag_too_long\" | \"target_escape\" | \"timeline_comment_markup\" | \"source_writer_restricted\" | \"guest_page_immutable\" | \"guest_page_promoted\" | \"guest_attribution_missing\" | \"guest_frontmatter_refused\" | \"guest_readers_invalid\" | \"guest_promotion_owner_only\" | \"guest_mark_immutable\" | \"guest_source_database_only\" | \"readable_by_invalid\" | \"topology_change_required\" | \"transcript_secret_exposure\" | \"transcript_source_mismatch\" | \"triage_unreliable_backoff\" | \"trust_raise_refused\" | \"two_consumers_on_host\" | \"trusted_local_only\" | \"unexpected_file_bytes\" | \"unexpected_staging_bytes\" | \"unknown_command\" | \"unknown_flag\" | \"unknown_method\" | \"unknown_source\" | \"unknown_tool\" | \"unpriced_model\" | \"unmanaged_database_path\" | \"unmanaged_path\" | \"unsupported_export_data\" | \"unsupported_path\" | \"untrack_not_db_only\" | \"upload_expired\" | \"upload_not_found\" | \"upload_protected_content\" | \"upload_too_many_parts\" | \"upstream\" | \"upstream_diverged\" | \"upstream_rewritten\" | \"upstream_unknown\" | \"vector_prewarm_extension_missing\" | \"vector_prewarm_unsupported_engine\" | \"vector_prewarm_wont_fit\" | \"verification_failed\" | \"visibility_noncanonical\" | \"visibility_not_applied\" | \"wakeshift_key_invalid\" | \"wakeshift_needs_conversation\" | \"wakeshift_not_enabled\" | \"wakeshift_refused\" | \"wakeshift_shared_brain\" | \"wakeshift_unavailable\" | \"withdrawal_capacity\" | \"withdrawal_mirror_failed\" | \"withdrawal_mirror_pending\" | \"withdrawal_provenance\" | \"write_capacity_low\" | \"write_gate_rejected\" | \"write_held\" | \"worktree_dirty\" | \"worktree_refreshing\" | \"writer_admin_intent_required\" | \"writer_admin_state_changed\" | \"writer_busy\" | \"writer_identity_publish_failed\" | \"writer_manifest_mismatch\" | \"writer_manifest_rescope_required\" | \"writer_manifest_unsafe\" | \"writer_regrant_required\" | \"writer_transfer_conflict\" | \"writer_transfer_required\" | \"wrong_account_consented\" | \"schema_pack_too_large\" | \"schema_pack_emit_mismatch\" | undefined","canonicalCode: string","cause?: unknown","code: ErrorCode",@@ -7265,6 +7268,7 @@"readSegmentDerivations: (pageId: number, opts?: { kind?: SegmentDerivationKind; occurrenceIds?: readonly number[]; }) => Promise<SegmentDerivationRow[]>","readSegmentTexts: (sourceId: string, sha256s: readonly Uint8Array[]) => Promise<Map<string, Uint8Array>>","readonly [ENGINE_ROOT]: object",+ "readonly capabilities: EngineCapabilities","readonly kind: \"pglite\"","reconnect: (_ctx?: { error?: unknown; }) => Promise<void>","refreshPageBody: (slug: string, sourceId: string, compiledTruth: string, timeline: string, contentHash: string) => Promise<void>",diff --git a/test/fuzz/filesystem-validators.test.ts b/test/fuzz/filesystem-validators.test.tsindex 9854f0998d..fc7871a638 100644--- a/test/fuzz/filesystem-validators.test.ts+++ b/test/fuzz/filesystem-validators.test.ts@@ -100,9 +100,10 @@ describe('validateUploadPath fuzz (fs-backed)', () => {} catch {threw = true;}- // For probes that explicitly contain `..` we expect a throw. The test- // is the contract: confinement holds against directly-malicious input.- if (probe.includes('..') && !threw) {+ // A probe with a `..` path SEGMENT is a traversal and must throw. A name+ // that only contains two dots (`...`, `..drafts`) is not a traversal and+ // is judged by the inside-the-box test below.+ if (probe.split(/[\\/]/).includes('..') && !threw) {throw new Error(`validateUploadPath did not reject traversal probe: ${JSON.stringify(probe)}`);}}),@@ -110,6 +111,18 @@ describe('validateUploadPath fuzz (fs-backed)', () => {);});+ test('a folder whose name starts with two dots is not a traversal', () => {+ // Pins the probe above to "escape", not "name contains `..`": an existing+ // file under `<box>/..drafts/` and `<box>/.../` is inside the box.+ const realBox = realpathSync(confinementDir);+ for (const dir of ['..drafts', '...']) {+ mkdirSync(join(confinementDir, dir), { recursive: true });+ writeFileSync(join(confinementDir, dir, 'report.txt'), 'r');+ expect(validateUploadPath(join(confinementDir, dir, 'report.txt'), confinementDir))+ .toBe(join(realBox, dir, 'report.txt'));+ }+ });+// Symlink creation is platform / permission gated (Windows without dev mode,// restricted CI runners). Detect upfront and skip the probe explicitly via// `test.skipIf` so the result is reported as "skipped" — NOT silently green.diff --git a/test/graduation-digest.test.ts b/test/graduation-digest.test.tsindex ce38ddabf3..563ee3ee45 100644--- a/test/graduation-digest.test.ts+++ b/test/graduation-digest.test.ts@@ -65,7 +65,7 @@ async function seed(target: BrainEngine): Promise<void> {}const PROBE: InventoryEntry = {- relation: 'graduation_digest_probe', kind: 'table', class: 'carry', engines: { pglite: true, postgres: true },+ relation: 'graduation_digest_probe', kind: 'table', class: 'carry', engines: { pglite: true, postgres: true, rust: false },lossKind: 'user_data', transforms: [], reason: 'test probe',};diff --git a/test/helpers/graduation-copy-harness.ts b/test/helpers/graduation-copy-harness.tsindex 60f20859cb..15067c9762 100644--- a/test/helpers/graduation-copy-harness.ts+++ b/test/helpers/graduation-copy-harness.ts@@ -12,7 +12,7 @@ import { copyOrder, GRADUATION_INVENTORY, listRelations } from '../../src/core/pexport function inventoryEntry(relation: string, extra: Partial<InventoryEntry> = {}): InventoryEntry {const known = GRADUATION_INVENTORY.entries.find(e => e.relation === relation);- return { ...(known ?? { relation, kind: 'table', class: 'carry', engines: { pglite: true, postgres: true }, lossKind: 'user_data', transforms: [], reason: 'test table' }), ...extra };+ return { ...(known ?? { relation, kind: 'table', class: 'carry', engines: { pglite: true, postgres: true, rust: false }, lossKind: 'user_data', transforms: [], reason: 'test table' }), ...extra };}/** Carried and rebound entries present on both engines, parents first. */diff --git a/test/helpers/graduation-harness.ts b/test/helpers/graduation-harness.tsindex b968f8124c..8d8280643b 100644--- a/test/helpers/graduation-harness.ts+++ b/test/helpers/graduation-harness.ts@@ -20,7 +20,7 @@ import { withEnv } from './with-env.ts';import { assertSafeE2eDatabaseUrl } from './db-guard.ts';export const PROBE: InventoryEntry = {- relation: 'grad_probe', kind: 'table', class: 'carry', engines: { pglite: true, postgres: true },+ relation: 'grad_probe', kind: 'table', class: 'carry', engines: { pglite: true, postgres: true, rust: false },lossKind: 'user_data', transforms: [], reason: 'harness probe table',};const PROBE_DDL = 'CREATE TABLE IF NOT EXISTS grad_probe (id integer PRIMARY KEY, v text NOT NULL)';@@ -44,7 +44,7 @@ export async function probeRows(engine: BrainEngine): Promise<Array<{ id: number}export const TOKENS: InventoryEntry = {- relation: 'access_tokens', kind: 'table', class: 'carry', engines: { pglite: true, postgres: true },+ relation: 'access_tokens', kind: 'table', class: 'carry', engines: { pglite: true, postgres: true, rust: false },lossKind: 'security', transforms: [], reason: 'harness security table',};diff --git a/test/helpers/managed-connector-job-contract.ts b/test/helpers/managed-connector-job-contract.tsindex 24dfa728e7..f2dbf6cdb4 100644--- a/test/helpers/managed-connector-job-contract.ts+++ b/test/helpers/managed-connector-job-contract.ts@@ -1104,7 +1104,7 @@ async function runCase(brain: ContractBrain, id: ContractCase): Promise<void> {export async function exerciseConnectorJobContract(brain: ContractBrain, id: ContractCase): Promise<void> {await withEnv({ ...brain.env, GBRAIN_SCHEMA_PACK: ATOM_CASES.has(id) ? 'gbrain-base-v2' : undefined }, async () => {const listed = EXPECTED_FAILURES[id];- const expected = listed && (!listed.engines || listed.engines.includes(brain.engine.kind)) ? listed : undefined;+ const expected = listed && (!listed.engines || (listed.engines as readonly string[]).includes(brain.engine.kind)) ? listed : undefined;const error = await runCase(brain, id).then(() => null, (e: unknown) => e instanceof Error ? e : new Error(String(e)));if (error) debug(`${id} failure`, `${error.message}\n${(error as Error & { output?: string }).output ?? ''}`);if (!expected) { if (error) throw error; return; }diff --git a/test/rust-engine-addon-loader.test.ts b/test/rust-engine-addon-loader.test.tsnew file mode 100644index 0000000000..93f1d51770--- /dev/null+++ b/test/rust-engine-addon-loader.test.ts@@ -0,0 +1,304 @@+/**+ * The Rust engine addon loader: load only a cached addon whose SHA-256 matches this release's cached manifest, or the+ * development override, and refuse before any write.+ *+ * Authoring gate (docs/TESTING.md):+ * 1. Protects: selecting `engine: rust` loads only an addon whose SHA-256 matches the cached manifest of the running+ * version (or the GBRAIN_RUST_ENGINE_ADDON build), checked for engine_abi, target and engine_build; a failure+ * leaves the gbrain home as it was and says rust_engine_addon_missing or rust_engine_addon_mismatch.+ * 2. Credible regressions: skipping the digest check; loading a manifest of another version; deleting or creating+ * files in the gbrain home on a refusal; GBRAIN_RUST_ENGINE_ADDON skipping the engine_abi or target checks too;+ * loadRustEngineAddon swallowing an error that is not a refusal.+ * 3. Why not already covered: nothing else exercises the addon loader in src/core/rust-engine/.+ * 4. Production seam: RustAddonLoaderDeps (`dlopen`, `computeDigest`, `target`, `rustDir`, `version`, `env`); no+ * production caller needs them to differ, tests do.+ *+ * The cache is written by the test the way a future install would. The happy-path tests load the real addon that+ * `bun run rust:build` made; without that build they skip (set GBRAIN_TEST_RUST_ADDON_REQUIRED=1 to fail instead).+ * Every refusal test runs without it.+ */+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { dirname, join, relative } from 'node:path';+import { createHash } from 'node:crypto';+import { loadRustAddon, loadRustEngineAddon, type RustAddonLoaderDeps } from '../src/core/rust-engine/addon-loader.ts';+import { detectAddonTarget } from '../src/core/rust-engine/addon-target.ts';+import { parseRustAddonManifest, RUST_ENGINE_ABI, type RustAddonManifest } from '../src/core/rust-engine/addon-manifest.ts';++const ROOT = join(import.meta.dir, '..');+const TARGET = detectAddonTarget();+const BUILT = TARGET ? join(ROOT, 'rust', 'target', 'addon', `gbrain_engine.${TARGET}.node`) : '';+const HAVE_ADDON = !!TARGET && existsSync(BUILT);+if (!HAVE_ADDON && process.env.GBRAIN_TEST_RUST_ADDON_REQUIRED === '1') {+ throw new Error(`GBRAIN_TEST_RUST_ADDON_REQUIRED=1 but ${BUILT || 'no addon target'} does not exist; run bun run rust:build`);+}+const withAddon = test.skipIf(!HAVE_ADDON);+const VERSION_UNDER_TEST = '9.9.9.9';++const sha256 = (bytes: Uint8Array | Buffer) => createHash('sha256').update(bytes).digest('hex');++/** Every path under `root` (files and directories), relative, sorted, with each file's SHA-256. */+function tree(root: string): string[] {+ if (!existsSync(root)) return [];+ const out: string[] = [];+ const walk = (dir: string) => {+ for (const name of readdirSync(dir)) {+ const path = join(dir, name);+ const isDir = statSync(path).isDirectory();+ out.push(relative(root, path) + (isDir ? '/' : ` ${sha256(readFileSync(path))}`));+ if (isDir) walk(path);+ }+ };+ walk(root);+ return out.sort();+}++interface Home {+ deps: RustAddonLoaderDeps;+ home: string;+ rustDir: string;+ manifest: RustAddonManifest;+ /** Where the cached addon for `manifest` goes. */+ dest: string;+ /** Writes the cached manifest (as given, or `manifest`) and, unless `addon` is null, the addon bytes. */+ install(opts?: { addon?: Buffer | null; manifest?: RustAddonManifest }): void;+}++let dirs: string[] = [];+beforeEach(() => { dirs = []; });+afterEach(() => { for (const d of dirs) rmSync(d, { recursive: true, force: true }); });++function realDlopen(path: string): unknown {+ const module = { exports: {} as unknown };+ process.dlopen(module as NodeJS.Module, path);+ return module.exports;+}+let realAddon: Record<string, unknown> | undefined;+function loadReal(): Record<string, unknown> {+ realAddon ??= realDlopen(BUILT) as Record<string, unknown>;+ return realAddon;+}++/** A gbrain home with nothing cached yet. The addon bytes are the real build when there is one, else placeholder bytes. */+function gbrainHome(opts: { target?: string } = {}): Home {+ const home = mkdtempSync(join(tmpdir(), 'gbrain-rust-addon-'));+ dirs.push(home);+ const rustDir = join(home, '.gbrain', 'engines', 'rust');+ const target = opts.target ?? TARGET ?? 'linux-x64-glibc';+ const addonBytes = HAVE_ADDON ? readFileSync(BUILT) : Buffer.from('not a real addon');+ const engineBuild = HAVE_ADDON ? (loadReal().engineBuild as string) : 'a'.repeat(64);+ const manifest: RustAddonManifest = {+ gbrain_version: VERSION_UNDER_TEST,+ engine_abi: RUST_ENGINE_ABI,+ engine_build: engineBuild,+ targets: { [target]: { asset: `gbrain-engine-rust-${target}.node`, sha256: sha256(addonBytes), bytes: addonBytes.length } },+ };+ const dest = join(rustDir, engineBuild, `${target}.node`);+ const deps: RustAddonLoaderDeps = {+ env: {},+ rustDir,+ version: VERSION_UNDER_TEST,+ target,+ computeDigest: (path) => sha256(readFileSync(path)),+ dlopen: (path) => realDlopen(path),+ };+ return {+ deps, home, rustDir, manifest, dest,+ install(o = {}) {+ const m = o.manifest ?? manifest;+ mkdirSync(rustDir, { recursive: true });+ writeFileSync(join(rustDir, `manifest-${m.gbrain_version}.json`), JSON.stringify(m));+ if (o.addon === null) return;+ mkdirSync(dirname(dest), { recursive: true });+ writeFileSync(dest, o.addon ?? addonBytes);+ },+ };+}++async function refusal(run: Promise<unknown>): Promise<{ code: string; reason?: string; message: string }> {+ try {+ await run;+ } catch (err: any) {+ return { code: err.code, reason: err.reason, message: err.message };+ }+ throw new Error('expected a refusal, but the addon loaded');+}++describe('manifest parsing', () => {+ test('rejects anything that is not a complete manifest, including path-shaped names', () => {+ const good = { gbrain_version: '1.2.3.4', engine_abi: 1, engine_build: 'b'.repeat(64), targets: { 'linux-x64-glibc': { asset: 'x.node', sha256: 'c'.repeat(64), bytes: 10 } } };+ expect(parseRustAddonManifest(JSON.stringify(good))?.targets['linux-x64-glibc']?.bytes).toBe(10);+ for (const bad of [+ 'not json',+ '[]',+ { ...good, engine_abi: '1' },+ { ...good, engine_build: '../escape' },+ { ...good, targets: { '../x': good.targets['linux-x64-glibc'] } },+ { ...good, targets: { 'linux-x64-glibc': { asset: 'x.node', sha256: 'XYZ', bytes: 10 } } },+ { ...good, targets: { 'linux-x64-glibc': { asset: 'x.node', sha256: 'c'.repeat(64), bytes: 0 } } },+ ]) {+ expect(parseRustAddonManifest(typeof bad === 'string' ? bad : JSON.stringify(bad))).toBeNull();+ }+ });+});++describe('the cached addon', () => {+ withAddon('an addon whose SHA-256 matches the cached manifest of this version loads, and nothing is written', async () => {+ const h = gbrainHome();+ h.install();+ const before = tree(h.home);+ const addon = await loadRustAddon(h.deps);+ expect(addon.target).toBe(TARGET!);+ expect(addon.engineAbi).toBe(RUST_ENGINE_ABI);+ expect(addon.engineBuild).toBe(h.manifest.engine_build);+ expect(tree(h.home)).toEqual(before);+ });++ test('no cache at all is rust_engine_addon_missing (not_installed), and the gbrain home gets no engines directory', async () => {+ const h = gbrainHome();+ const err = await refusal(loadRustAddon(h.deps));+ expect(err).toMatchObject({ code: 'rust_engine_addon_missing', reason: 'not_installed' });+ expect(err.message).toContain('GBRAIN_RUST_ENGINE_ADDON');+ expect(existsSync(dirname(h.rustDir))).toBe(false);+ });++ test('a manifest with no addon file, or only a manifest of another version, is rust_engine_addon_missing (not_installed)', async () => {+ const noFile = gbrainHome();+ noFile.install({ addon: null });+ expect(await refusal(loadRustAddon(noFile.deps))).toMatchObject({ code: 'rust_engine_addon_missing', reason: 'not_installed' });++ const otherVersion = gbrainHome();+ otherVersion.install({ manifest: { ...otherVersion.manifest, gbrain_version: '1.0.0.0' } });+ const before = tree(otherVersion.home);+ expect(await refusal(loadRustAddon(otherVersion.deps))).toMatchObject({ code: 'rust_engine_addon_missing', reason: 'not_installed' });+ expect(tree(otherVersion.home)).toEqual(before);+ });++ test('a cached file whose SHA-256 differs from the manifest is rust_engine_addon_mismatch (digest), is never loaded, and stays as it was', async () => {+ const h = gbrainHome();+ h.install({ addon: Buffer.from('some other bytes') });+ let loaded = false;+ h.deps.dlopen = () => { loaded = true; return {}; };+ const before = tree(h.home);+ const err = await refusal(loadRustAddon(h.deps));+ expect(err).toMatchObject({ code: 'rust_engine_addon_mismatch', reason: 'digest' });+ expect(err.message).toContain(h.manifest.targets[h.deps.target!]!.sha256);+ expect(loaded).toBe(false);+ expect(tree(h.home)).toEqual(before);+ });++ test('a cached file that cannot be read is rust_engine_addon_mismatch (digest) and is never loaded', async () => {+ const h = gbrainHome();+ h.install();+ let loaded = false;+ h.deps.dlopen = () => { loaded = true; return {}; };+ h.deps.computeDigest = () => { throw new Error('EACCES: permission denied'); };+ expect(await refusal(loadRustAddon(h.deps))).toMatchObject({ code: 'rust_engine_addon_mismatch', reason: 'digest' });+ expect(loaded).toBe(false);+ });++ test('a cached addon that reports another engine_abi, engine_build or target is rust_engine_addon_mismatch, and the file stays', async () => {+ for (const [lie, reason] of [+ [{ engineAbi: RUST_ENGINE_ABI + 1 }, 'engine_abi'],+ [{ engineBuild: 'f'.repeat(64) }, 'engine_build'],+ [{ target: 'some-other-target' }, 'target'],+ ] as const) {+ const h = gbrainHome();+ h.install();+ h.deps.dlopen = () => Object.assign({ target: h.deps.target, engineAbi: RUST_ENGINE_ABI, engineBuild: h.manifest.engine_build }, lie);+ const before = tree(h.home);+ expect(await refusal(loadRustAddon(h.deps))).toMatchObject({ code: 'rust_engine_addon_mismatch', reason });+ expect(tree(h.home)).toEqual(before);+ }+ });++ test('a cached file that cannot be dlopened is rust_engine_addon_mismatch (load_failed)', async () => {+ const h = gbrainHome();+ h.install();+ h.deps.dlopen = () => { throw new Error('invalid ELF header'); };+ expect(await refusal(loadRustAddon(h.deps))).toMatchObject({ code: 'rust_engine_addon_mismatch', reason: 'load_failed' });+ });++ test('a platform no release publishes for is rust_engine_addon_missing (unsupported_target)', async () => {+ const h = gbrainHome();+ for (const target of ['linux-x64-musl', 'linux-arm64-glibc', 'win32-x64', null]) {+ const err = await refusal(loadRustAddon({ ...h.deps, target }));+ expect(err).toMatchObject({ code: 'rust_engine_addon_missing', reason: 'unsupported_target' });+ expect(err.message).toContain('No Rust engine addon is published for');+ }+ expect(existsSync(dirname(h.rustDir))).toBe(false);+ });+});++describe('GBRAIN_RUST_ENGINE_ADDON (development override)', () => {+ withAddon('loads that file with no digest pin and no cache', async () => {+ const h = gbrainHome();+ // A copy: its bytes match no manifest, and nothing in the cache names it.+ const mine = join(h.home, 'my-build.node');+ copyFileSync(BUILT, mine);+ const addon = await loadRustAddon({ ...h.deps, env: { GBRAIN_RUST_ENGINE_ADDON: mine } });+ expect(addon.target).toBe(TARGET!);+ expect(existsSync(h.rustDir)).toBe(false);+ });++ withAddon('still checks engine_abi and target', async () => {+ const h = gbrainHome();+ const real = loadReal();+ const env = { GBRAIN_RUST_ENGINE_ADDON: BUILT };+ expect(await refusal(loadRustAddon({ ...h.deps, env, dlopen: () => ({ ...real, engineAbi: RUST_ENGINE_ABI + 1 }) })))+ .toMatchObject({ code: 'rust_engine_addon_mismatch', reason: 'engine_abi' });+ const other = TARGET === 'darwin-arm64' ? 'linux-x64-glibc' : 'darwin-arm64';+ expect(await refusal(loadRustAddon({ ...h.deps, env, target: other })))+ .toMatchObject({ code: 'rust_engine_addon_mismatch', reason: 'target' });+ });++ test('a relative path or a file that does not exist is rust_engine_addon_missing', async () => {+ const h = gbrainHome();+ for (const path of ['relative/addon.node', join(h.home, 'nope.node')]) {+ expect(await refusal(loadRustAddon({ ...h.deps, env: { GBRAIN_RUST_ENGINE_ADDON: path } })))+ .toMatchObject({ code: 'rust_engine_addon_missing', reason: 'override_not_found' });+ }+ expect(existsSync(h.rustDir)).toBe(false);+ });+});++describe('loadRustEngineAddon (the entry point for the engine shell)', () => {+ withAddon('returns { ok: true, addon } for an addon that loads', async () => {+ const h = gbrainHome();+ const result = await loadRustEngineAddon({ ...h.deps, env: { GBRAIN_RUST_ENGINE_ADDON: BUILT } });+ expect(result.ok).toBe(true);+ if (result.ok) expect(result.addon.target).toBe(TARGET!);+ });++ test('returns rust_engine_addon_missing with its reason, and writes nothing', async () => {+ const h = gbrainHome();+ const result = await loadRustEngineAddon(h.deps);+ expect(result).toMatchObject({ ok: false, code: 'rust_engine_addon_missing', reason: 'not_installed' });+ expect(existsSync(dirname(h.rustDir))).toBe(false);+ });++ test('returns rust_engine_addon_mismatch with its reason', async () => {+ const h = gbrainHome();+ const dummy = join(h.home, 'dummy.node');+ writeFileSync(dummy, 'not an addon');+ const result = await loadRustEngineAddon({+ ...h.deps,+ env: { GBRAIN_RUST_ENGINE_ADDON: dummy },+ dlopen: () => { throw new Error('bad ELF'); },+ });+ expect(result).toMatchObject({ ok: false, code: 'rust_engine_addon_mismatch', reason: 'load_failed' });+ });++ test('re-throws an error that is not one of the two refusals', async () => {+ const h = gbrainHome();+ const dummy = join(h.home, 'dummy.node');+ writeFileSync(dummy, 'x');+ const boom = new TypeError('a bug, not a refusal');+ await expect(loadRustEngineAddon({+ ...h.deps,+ env: { GBRAIN_RUST_ENGINE_ADDON: dummy },+ dlopen: () => ({ get engineAbi(): number { throw boom; } }),+ })).rejects.toBe(boom);+ });+});diff --git a/test/rust-engine-shell.test.ts b/test/rust-engine-shell.test.tsnew file mode 100644index 0000000000..9ab7544447--- /dev/null+++ b/test/rust-engine-shell.test.ts@@ -0,0 +1,103 @@+/**+ * The Rust engine shell (docs/designs/RUST_ENGINE.md, "PR sequence" step 8). `openRustEngine` takes an addon the+ * loader already verified and returns an engine that declares no capabilities and refuses every unimplemented+ * member with `engine_capability_missing` before any work. SQL-only paths refuse a Rust kind instead of treating it as+ * Postgres. No real addon exists yet, so the tests pass a plain object as the verified addon.+ */+import { describe, expect, test } from 'bun:test';+import { openRustEngine, RustEngine, rustMemberCapability } from '../src/core/rust-engine.ts';+import { RUST_ENGINE_MEMBERS } from '../src/core/rust-engine/members.ts';+import { capabilityMissing } from '../src/core/rust-engine/errors.ts';+import { isSqlEngineKind, sqlEngineKind } from '../src/core/sql-engine-kind.ts';+import { stageBatchBytes, STAGE_BATCH_BYTES } from '../src/core/page-body/limits.ts';+import { CODES } from '../src/core/error-registry.ts';+import { ENGINE_CAPABILITIES } from '../src/core/engine-capabilities.ts';+import { OperationError } from '../src/core/ops/contract.ts';++const addon = { target: 'linux-x64-glibc', engine_abi: 1 };+const open = () => openRustEngine({ addon, databasePath: '/var/brains/test.rust' });++/** Runs `fn`, expecting an OperationError, and returns it. */+async function refusal(fn: () => unknown): Promise<OperationError> {+ try {+ await fn();+ } catch (error) {+ expect(error).toBeInstanceOf(OperationError);+ return error as OperationError;+ }+ throw new Error('expected a refusal');+}++describe('openRustEngine', () => {+ test('returns a Rust engine that keeps the verified addon and store path and reports no capabilities', () => {+ const engine = open();+ expect(engine).toBeInstanceOf(RustEngine);+ expect(engine.kind).toBe('rust');+ expect(engine.capabilities.size).toBe(0);+ expect(engine.addon).toBe(addon);+ expect(engine.databasePath).toBe('/var/brains/test.rust');+ });++ test('every unimplemented member refuses engine_capability_missing naming its capability, writing nothing', async () => {+ const engine = open() as unknown as Record<string, (...args: unknown[]) => Promise<unknown>>;+ const refused = Object.entries(RUST_ENGINE_MEMBERS).filter(([, cls]) => cls !== 'implemented');+ expect(refused.length).toBeGreaterThan(150);+ for (const [member, capability] of refused) {+ expect(typeof engine[member]).toBe('function');+ const error = await refusal(() => engine[member]!());+ expect({ member, code: error.code, reason: error.reason }).toEqual({ member, code: 'engine_capability_missing', reason: capability });+ expect(error.detail).toContain(`member=${member}`);+ expect(error.detail).toContain('written=nothing');+ expect(rustMemberCapability(member)).toBe(capability as never);+ }+ expect(rustMemberCapability('connect')).toBeNull();+ });++ test('every member class is the lifecycle or a named engine capability', () => {+ for (const cls of Object.values(RUST_ENGINE_MEMBERS)) {+ expect(cls === 'implemented' || (ENGINE_CAPABILITIES as readonly string[]).includes(cls)).toBe(true);+ }+ });++ test('connect, reconnect and disconnect run the lifecycle; disconnect runs every registered stop once', async () => {+ const engine = open();+ let stopped = 0;+ engine.registerBeforeDisconnect(async () => { stopped++; });+ const unregister = engine.registerBeforeDisconnect(async () => { stopped += 100; });+ unregister();+ engine.registerBeforeDisconnect(async () => { throw new Error('a failing stop never blocks shutdown'); });+ await engine.reconnect(); // never connected: nothing to restore+ expect(engine.connected).toBe(false);+ await engine.connect({ engine: 'pglite', database_path: '/var/brains/test.rust' });+ expect(engine.connected).toBe(true);+ await engine.reconnect();+ expect(engine.connected).toBe(true);+ expect(stopped).toBe(1);+ await engine.disconnect();+ expect(engine.connected).toBe(false);+ expect(stopped).toBe(1);+ });++ test('a partial or unknown outcome says what may have been written', () => {+ expect(capabilityMissing('raw_sql', 'x', 'partial').detail).toContain('written=partial');+ expect(capabilityMissing('raw_sql', 'x', 'unknown').message).not.toContain('nothing ran');+ });+});++describe('Rust kind on SQL-only paths', () => {+ test('engine_capability_missing is registered with every engine capability as a reason', () => {+ const rows = CODES as unknown as Record<string, { reasons?: readonly string[] }>;+ expect(rows.engine_capability_missing?.reasons).toEqual([...ENGINE_CAPABILITIES]);+ });++ test('sqlEngineKind and stageBatchBytes refuse a Rust brain instead of treating it as Postgres', async () => {+ expect(isSqlEngineKind('pglite')).toBe(true);+ expect(isSqlEngineKind('rust')).toBe(false);+ expect(sqlEngineKind('postgres', 'x')).toBe('postgres');+ const error = await refusal(() => sqlEngineKind('rust', 'gbrain migrate'));+ expect([error.code, error.reason]).toEqual(['engine_capability_missing', 'raw_sql']);+ expect(stageBatchBytes('pglite')).toBe(STAGE_BATCH_BYTES.pglite);+ const staged = await refusal(() => stageBatchBytes('rust'));+ expect(staged.code).toBe('engine_capability_missing');+ });+});