Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Check every engine method on PGLite and Postgres, add a typed sealChunks, and stop raw SQL growing outside the engines (#9641)
Garry Tana64fb58b9d40
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7b83faaa27..d8416c6315 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -434,7 +434,7 @@ to a sibling module. Every row also adds a behavior test of its own; the| Change kind | Create or edit | Registry to touch | Regenerate | Smallest test ||---|---|---|---|---|-| Storage method (a `BrainEngine` method) | The signature in `src/core/engine.ts`; the SQL once in `src/core/engine-sql/<domain>.ts`; a one-line delegation in `src/core/pglite-engine.ts` and `src/core/postgres-engine.ts` (copy a sibling read's shape, e.g. `getAllSlugs`) | `scripts/module-size-limits.tsv`: raise the `engine.ts`, `pglite-engine.ts` and `postgres-engine.ts` ceilings by the lines you added. A new SQL-bearing engine member fails `check:engine-sql-ratchet`; `scripts/engine-sql-baseline.tsv` rows only shrink | Nothing | `test/engine-sql-<domain>-<topic>.test.ts` on PGLite (seed with `engine.putPage(slug, { type, title, compiled_truth })`; the default source id is `'default'`); for a write, a case in `test/helpers/engine-sql-rollback-cases.ts`, run by `bun test test/engine-sql-transaction.test.ts` |+| Storage method (a `BrainEngine` method) | The signature in `src/core/engine.ts`; the SQL once in `src/core/engine-sql/<domain>.ts`; a one-line delegation in `src/core/pglite-engine.ts` and `src/core/postgres-engine.ts` (copy a sibling read's shape, e.g. `getAllSlugs`) | `scripts/module-size-limits.tsv`: raise the `engine.ts`, `pglite-engine.ts` and `postgres-engine.ts` ceilings by the lines you added. A new SQL-bearing engine member fails `check:engine-sql-ratchet`; `scripts/engine-sql-baseline.tsv` rows only shrink. The method also needs a family in `FAMILIES` (`test/engine-parity/coverage.ts`) and a `parityTest` case in `test/engine-parity/`; a new parity file also gets a row in `test/postgres-unit-arms.txt` | `bun test/engine-parity/coverage.ts --write` (refreshes `test/engine-parity/coverage.tsv`; `test/engine-parity/coverage.test.ts` fails until you do) | `test/engine-sql-<domain>-<topic>.test.ts` on PGLite (seed with `engine.putPage(slug, { type, title, compiled_truth })`; the default source id is `'default'`); for a write, a case in `test/helpers/engine-sql-rollback-cases.ts`, run by `bun test test/engine-sql-transaction.test.ts` || Schema migration | `bun run new:migration <snake_name>` writes `src/core/schema-migrations/v<NNN>-<name>.ts`; fresh-install DDL in `src/schema.sql` (or the TS fragment its region banner names); a forward-reference probe in `src/core/engine-sql/bootstrap.ts` only when the schema blob references a column older brains lack | `src/core/schema-migrations/registry.generated.ts` (generated) | `new:migration` already regenerates the registry; rerun `bun run build:schema-migrations` only after editing or renaming a migration file. `bun run build:schema` whenever `schema.sql` or a fragment changed. Every object a fresh install should have goes in `schema.sql` (or its fragment) as well as the migration; grep `src/schema.sql` first so you do not add a second index on the same columns. A migration that updates a page column the revision trigger watches, or writes `tags`, empties search for every page it touches until the rebuild (#9192): `bun run check:migration-projection` fails until `scripts/migration-projection-baseline.tsv` says how search keeps answering | `bun test test/scripts/build-schema-migrations.test.ts test/migrate.test.ts`, then `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/migrations-golden.test.ts test/schema-catalog-golden.test.ts` and review the golden diff || Doctor check | A `{ name, emits, run }` entry in the topic module under `src/commands/doctor/checks/` (a new topic gets a new file): `name` and `emits` are string literals, and `run` names a top-level `async function run<X>(ctx): Promise<Check[]>` in the same file that builds `const checks: Check[] = []` and calls `checks.push({ name: '<literal>', ... })` directly (the `emits` test walks that AST; helpers and returned array literals are invisible to it) | `DOCTOR_CHECK_REGISTRY` in `src/commands/doctor/registry.ts` (position = output order; `test/doctor-registry-golden.test.ts` pins `dangling_aliases` as the last check, so insert before `searchModeEntry`) and every emitted name in `src/core/doctor-categories.ts` | The doctor goldens, deliberately: `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/doctor-registry-golden.test.ts test/doctor-json-golden.test.ts` | `test/doctor-<name>.test.ts` on in-memory PGLite (copy `test/doctor-slug-collisions.test.ts`), plus `bun test test/doctor-registry.test.ts` || CLI-only command | The implementation in `src/commands/<name>.ts`; the dispatch module `src/cli/commands/<name>.ts`; a help line in `printHelp` (`src/cli.ts`, so raise its `module-size-limits.tsv` ceiling by one) | A record in `CLI_COMMANDS` (`src/cli/command-table.ts`): `phase: 'pre-connect'` when the command never touches the database, `'post-connect'` when its `run(engine, args, ctx)` needs an engine; `thinClient: 'none'` unless remote brains must refuse it (`'refuse'`, or `'route-then-refuse'` for subcommand routing); `selfHelp: true` when the command has flags or subcommands (its `run` then prints its own `--help`); optional `skipStartupHooks`; `load: () => import('<literal>')` | `bun run build:flag-registry`; the CLI goldens, deliberately: `GBRAIN_TEST_UPDATE_GOLDENS=1 bun test test/cli-goldens.test.ts test/cli-dispatch-phase.test.ts test/cli-dispatch-thin-client.test.ts` | `test/<name>.test.ts` spawning `bun src/cli.ts <name>` and asserting output and exit code, plus `bun test test/cli-command-table.test.ts test/cli-flag-validation.test.ts` |@@ -472,6 +472,8 @@ why the output changed. Regenerate generated files instead of merging them| A built-in Minion job handler | `src/core/minions/handlers/<name>.ts`, registered in `registerBuiltinHandlers` (`src/commands/jobs.ts`) | the body of `jobs.ts` || A hybrid search step | the stage module in `src/core/search/hybrid/` that owns it | the body of `hybridSearch` |+`bun run verify` also counts raw SQL outside the engines (`check:engine-raw-sql-ratchet`) and two-way engine-kind branches (`check:engine-kind-branches`), per file. Prefer a typed `BrainEngine` method, a capability check, or a switch over every engine kind that ends in a `never` check. A new or higher count needs a row with a reason in `scripts/engine-raw-sql-baseline.tsv` or `scripts/engine-kind-branches-baseline.tsv`; after you remove sites, lower the row with the script's `--prune`. See [CI guards](docs/ci-guards.md#engine-raw-sql-ratchet).+### Worked example: an engine-sql read and writeSay the salience domain needs a count of salient pages (a read) and a way todiff --git a/changelog.d/engine-parity-decisions.md b/changelog.d/engine-parity-decisions.mdnew file mode 100644index 0000000000..0baf49b73c--- /dev/null+++ b/changelog.d/engine-parity-decisions.md@@ -0,0 +1,8 @@+**Both engines gain a typed way to replace and seal a page's chunks, and the engine parity suite now covers every engine method.**++### Added+- `BrainEngine.sealChunks(slug, chunks, { sourceId, expectedRevision })` replaces a page's chunks and seals its search text in one transaction. It refuses a missing or deleted page, a segmented page, an archived source and a stale `expectedRevision`. The engine parity suite seals its fixture chunks through it, so no parity case needs raw SQL.++### Tests+- The parity suite now covers every BrainEngine method (198 of 198). Raw-SQL methods (`executeRaw`, `executeRawDirect`, `runMigration`, `keywordBoundedRead`) run on the SQL engines and are marked `refuses:raw_sql` for the planned Rust engine; `holdSchemaMigrationLock` runs on Postgres only. A case declares the capability it needs with `requires`, and `test/engine-parity/arm-capabilities.ts` says which engine has it.+- The eval-capture cutoff cases derive their cutoff from stored timestamps and wait for the wall clock to pass it; the anomaly case uses the date stored by the database rather than the JS clock date.diff --git a/changelog.d/engine-parity-review-fixes.md b/changelog.d/engine-parity-review-fixes.mdnew file mode 100644index 0000000000..21d2fbcbfc--- /dev/null+++ b/changelog.d/engine-parity-review-fixes.md@@ -0,0 +1,7 @@+**Four engine parity cases are now deterministic or stricter: two no longer depend on timing or tie order, and a new case checks that a failed chunk replacement rolls back.**++### Tests+- The `listFactsKeyset` paging case no longer fails when two back-to-back facts get the same timestamp, which happened in about one run in five on PGLite. It now spaces its inserts until the clock moves and makes two rows share a timestamp on purpose, so it also checks that the cursor's id breaks the tie.+- The take vector-search case no longer has two takes with the same score. Search orders by distance only, so tied takes could come back in either order.+- A new `sealChunks` case checks that a chunk write that fails after the old chunks were deleted leaves the old sealed chunks in place and searchable.+- The `withReservedConnection` case declares that it needs raw SQL, so the planned Rust engine is expected to refuse it.diff --git a/changelog.d/engine-parity-suite.md b/changelog.d/engine-parity-suite.mdnew file mode 100644index 0000000000..5970eae281--- /dev/null+++ b/changelog.d/engine-parity-suite.md@@ -0,0 +1,7 @@+**A new test suite now checks that the PGLite and Postgres engines give the same answers, method by method, on every CI run.**++### Tests+- `test/engine-parity/` runs one scenario on every engine arm and fails when the arms disagree. PGLite runs in every unit lane, with no skip. Postgres runs wherever `DATABASE_URL` is set, including the `unit-postgres-arms` lane, which now lists each parity file. A future engine joins through `test/engine-parity/harness.ts` with no change to the cases.+- `test/engine-parity/coverage.tsv` is a generated list of every BrainEngine method, whether a parity case calls it, and what each engine arm (PGLite, Postgres and the planned Rust engine) must do for it. It covers all 198 methods. Regenerate it with `bun test/engine-parity/coverage.ts --write`; `test/engine-parity/coverage.test.ts` fails when the list is stale.+- Each case must call every method it declares, so the coverage number cannot claim a method that no case actually calls.+- `rewriteLinks` left the shrink-only uncalled list in `test/engine-surface-coverage.test.ts`, because a parity case now calls it. Its smoke stays as a shape pin.diff --git a/changelog.d/engine-raw-sql-ratchet.md b/changelog.d/engine-raw-sql-ratchet.mdnew file mode 100644index 0000000000..c12e137d26--- /dev/null+++ b/changelog.d/engine-raw-sql-ratchet.md@@ -0,0 +1,6 @@+**Raw SQL outside the database engines can no longer grow unseen: two new checks count it per file, and a count goes up only with a written reason.**++### For contributors+- `bun run check:engine-raw-sql-ratchet` (in `bun run verify`) counts, per file under `src/` outside the engines, `executeRaw` / `executeRawDirect` / `executeRawJsonb` calls, SQL tagged templates and direct driver calls with SQL text. The baseline is `scripts/engine-raw-sql-baseline.tsv` (5,606 sites in 1,205 files at this commit). A new site fails; call or add a typed engine method instead, with its SQL in `src/core/engine-sql/<domain>.ts`. When a count falls, lower its row (`--prune`). When a fix must add a site before its area moves into the engines, raise the row in the same pull request with a note saying why.+- `bun run check:engine-kind-branches` (in `bun run verify`) does the same for two-way `'pglite'` / `'postgres'` comparisons on an engine kind (397 in 223 files), so a third engine never falls silently into one of them. Ask a capability question, or switch over every engine kind with a default clause that opens with a `never` check on the switched value (such a switch does not count).+- Both checks share one runner, `scripts/lib/count-ratchet.ts`. See docs/ci-guards.md, "Engine raw-SQL ratchet" and "Engine-kind branches".diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsvindex e71fc7dd29..342a8c9e0c 100644--- a/docs/architecture/canonical-writers.tsv+++ b/docs/architecture/canonical-writers.tsv@@ -118,9 +118,10 @@ src/core/ops/pages.ts 0 coordinator Page mutations delegate to persistence modulsrc/core/output/writer.ts 6 engine_guard Canonical table SQL trigger requires coordinator capability; legacy calls fail before canonical DB publication.src/core/page-state/materialize.ts 1 coordinator Publication is transaction-scoped under admitted authority, source/page guards and revision checks.src/core/page-state/projection-schema.ts 2 schema Schema installation and forward-reference DDL; coordinated activation quiesces canonical writers. #9192: the activation also assigns a first knowledge_revision to pages written before v150 (no content column changes).-src/core/page-state/projections.ts 3 projection Derived indexing, retrieval telemetry, or source settings; canonical fields remain guarded by SQL triggers.+src/core/page-state/projections.ts 2 projection Derived indexing, retrieval telemetry, or source settings; canonical fields remain guarded by SQL triggers.src/core/page-state/versions.ts 2 projection GBRA-217: stamps only pages.version_history_gap_at (history metadata outside the canonical trigger's guarded fields) in the caller's versioning transaction, when an import reports a multi-commit gap or a prune drops snapshots; no canonical field or body is written.src/core/page-state/image-seal.ts 1 projection The explicit image seal (#6803) sets only text_projection_revision on an importer-attested image page, under its page guard with a revision compare-and-set; no canonical field or body is written.+src/core/page-state/text-seal.ts 1 projection The page text seal moved out of projections.ts (which lost one reference): it sets only text_projection_revision and search_vector on the page at the revision it read, with a knowledge_revision compare-and-set, after the sanitized chunks are installed; no canonical field or body is written.src/core/page-state/schema.ts 3 schema Schema installation and forward-reference DDL; coordinated activation quiesces canonical writers. The pages DO block constrains an empty pages table only; populated tables are finalized by revision-backfill-schema.ts.src/core/page-state/revision-backfill-schema.ts 2 schema Migration-pass backfill of pages.knowledge_revision for rows written before the column (#5216): only NULL revisions are assigned, in committed id batches; canonical content is never written, and the revision trigger treats a NULL old revision without reading bodies.src/core/page-state/tags.ts 5 engine_guard Canonical table SQL trigger requires coordinator capability; legacy calls fail before canonical DB publication. The frontmatter-claim and explicit-add inserts are two branches of one guarded statement. #5984: addPageTags is the same two-branch statement for many tags of a page the import wrote in its guarded transaction.diff --git a/docs/architecture/key-files/core-services-2-continued.md b/docs/architecture/key-files/core-services-2-continued.mdindex cc92eb106b..581ce278d1 100644--- a/docs/architecture/key-files/core-services-2-continued.md+++ b/docs/architecture/key-files/core-services-2-continued.md@@ -8,7 +8,7 @@ The page-state concurrency foundation under `src/core/page-state/` and the share- `src/core/page-state/` — Canonical page concurrency foundation shared by both engines. `schema.ts` (migration 150) adds source incarnation UUIDs, logical page revisions, text-projection revisions, and persistent guards for absent pages. `guards.ts` locks sorted sources then page identities in an existing transaction; a transaction or savepoint never re-acquires a key it holds, which covers absent pages because the only pages INSERT runs after `putPage` takes the same guard (`test/e2e/page-guards-postgres.test.ts`); callers lock sources before authority/request/fact rows. `snapshot.ts` computes the normalized body/timeline fingerprints only for a page with fact withdrawals, page-subject purges or a source '*' purge marker (they feed only the withdrawal overlay), as `page-snapshot-batch.ts` does. `snapshot.ts` reads page/tags/withdrawals in one MVCC statement and applies withdrawals using database-normalized text. `transactions.ts` makes helper transaction APIs compose through savepoints. `versions.ts` records the complete canonical snapshot; `rename-alias.ts` records `slug_aliases(old -> new)` inside both engines' `updateSlug` transaction, repoints aliases that named the old slug and drops one spelled like the new slug, and keeps every move (and any alias it drops) in `slug_rename_history` (v285), which only the folder-rule lineage test reads; `moveSlugBindings` moves the page's facts (`entity_slug`, `source_markdown_slug`) and `page_aliases` in the same transaction, letting a purged page's leftovers at the new slug yield (`test/rename-slug-alias.test.ts`); `movePageIdReferences` (#5431) moves the page-id-keyed rows of a stale rename row onto the surviving row (`links` from/to/origin, `timeline_entries` page and event, `page_versions`), dropping stale-side duplicates on the `links` composite key and the timeline dedup indexes (`test/rename-slug-alias.test.ts`); `materialize.ts` persists only verified canonical overlay bytes without another logical revision. `types.ts` defines revision preconditions: no revision is create-only (an existing page refuses `revision_required`, #5385, its own code since the omission is the caller's and not a race), a stale revision or a page another writer created where an internal writer asserted none (`expectedRevision: null`) is `revision_conflict`, explicit force overwrites. Plain legacy `putPage` calls keep compatibility until their owning operation adopts the managed write protocol. `projection-schema.ts` (migration 153) invalidates unverified prior projections once and queues durable work, but a Markdown or code page at or after the safe-chunk fence with no facts or takes fence, private-key text or quarantine marker keeps its old index in search until rebuilt (`servedTextProjectionFilter`); `projections.ts` rebuilds Markdown without a worktree/provider and installs only matching canonical revisions. Embedding installs also compare exact chunk identities/text. Source importers seal code/image projections; all read arms hide unsealed projections.-- `src/core/page-state/projections.ts` — `sealPageTextProjection` and `sealImportedPage` write the page keyword vector through `pageSearchVectorSql` (`fts-language.ts`: title weight A, sanitized timeline weight C, both through `gbrain_fts_input`), the same expression `search-vector-backfill.ts` uses. Captures canonical revision, source incarnation, page identity, the complete raw chunk inventory and resolved indexing inputs before preparing derived work. Embedding reads require a current text seal; healing/rebuild capture can explicitly include unsealed pages. Projection installation compares its originating seal, chunk identities/text/source/completion state, chunker version and indexing context (including stored corpus generation) under the page guard before replacing any row. A same-revision re-chunk may replace the snapshot it actually captured; a delayed older installation cannot discard newer chunks or vectors. Rebuild also rechecks its queued job before capture so a completed job from an old listing stays completed. Chunkless healing sanitizes complete body/timeline fences before splitting, preserving withdrawn history in direct page reads while excluding it from retrieval. Tests: `page-projection-origin.test.ts`, `page-projection-vector-preservation.test.ts` (PGLite and isolated Postgres), `embed-stale-chunkless-pages.serial.test.ts` (public healing entry). Shared `markdown-chunks.ts` and `code-chunks.ts` preserve fenced code and source-language metadata. A preserving rebuild keeps a vector only when its `content_chunks.embedding_input_hash` (`src/core/embedding-input-hash.ts`) equals one recomputed from the current page, or, with no recorded hash, when the page is non-contextual and the legacy model/text-hash checks pass; a contextual chunk without provenance is nulled once. `installPageEmbeddings` records the hash in the vector's UPDATE (the plain re-embed tier by default, or the caller's `built` tier and corpus generation), and returns `{ installed, complete }`: it matches each offered vector to the page's current chunk by source and exact text (not index) and writes it only when its input hash for the captured context is one the current context accepts, in batched `jsonb_to_recordset` UPDATEs, so a page that changed under the provider call keeps the vectors of its unchanged chunks; the embedding signature is stamped only when `complete` (same chunk sequence, nothing dropped). A preserving rebuild likewise keys kept vectors by chunk content, so a top insert shifts vectors with their chunks (tests: `page-embedding-content-validity.test.ts`). Also `stampEmbeddingInputs` does the same for full imports. `resealSafeChunks` re-seals a page below the safe-chunk fence from its unchanged body with no canonical write; `projectionBelowSafeFence` is its predicate. Tests add `projection-embedding-input-hash.test.ts` and `safe-chunk-reseal.test.ts`. It replaces outgoing code edges without deleting incoming edges to retained chunks and clears backfill watermarks. Failed jobs rotate with a retained diagnostic; successful drain refreshes planner statistics. `rebuildPendingPageProjections(engine, limit, { deadlineMs, now, notAfter, retryCooldown, onFailure })` (#5401) checks an injectable clock between pages, bounds a run to rows queued at or before its start (`notAfter`, cast from text in SQL so microseconds survive the driver), applies the 30 s `rebuild_failed` cooldown for the resident, and treats a lock or snapshot error as that page's failure instead of aborting the batch; `projectionBacklog` returns counts only (pending, failed, oldest age) for the drain command and the resident's `projection_status` IPC reply. A same-revision conflict throws `PageProjectionConflictError` naming the fields that changed (`text_projection_revision`, `chunk_digest`, `indexing_context`), the slug and source; `retryProjectionConflict(attempt)` re-runs an attempt that captures a fresh snapshot at most three more times with jitter, then rethrows (`page_projection_conflict` on the wire). Tests: `page-projection-origin.test.ts` (resident rebuild race, two-writer progress, exhausted-retry CLI/JSON output).+- `src/core/page-state/projections.ts` — `sealPageTextProjection` (defined in the light `page-state/text-seal.ts`, re-exported here, so `engine-sql/chunks.ts` `sealChunks` can run it without loading the projection pipeline) and `sealImportedPage` write the page keyword vector through `pageSearchVectorSql` (`fts-language.ts`: title weight A, sanitized timeline weight C, both through `gbrain_fts_input`), the same expression `search-vector-backfill.ts` uses. Captures canonical revision, source incarnation, page identity, the complete raw chunk inventory and resolved indexing inputs before preparing derived work. Embedding reads require a current text seal; healing/rebuild capture can explicitly include unsealed pages. Projection installation compares its originating seal, chunk identities/text/source/completion state, chunker version and indexing context (including stored corpus generation) under the page guard before replacing any row. A same-revision re-chunk may replace the snapshot it actually captured; a delayed older installation cannot discard newer chunks or vectors. Rebuild also rechecks its queued job before capture so a completed job from an old listing stays completed. Chunkless healing sanitizes complete body/timeline fences before splitting, preserving withdrawn history in direct page reads while excluding it from retrieval. Tests: `page-projection-origin.test.ts`, `page-projection-vector-preservation.test.ts` (PGLite and isolated Postgres), `embed-stale-chunkless-pages.serial.test.ts` (public healing entry). Shared `markdown-chunks.ts` and `code-chunks.ts` preserve fenced code and source-language metadata. A preserving rebuild keeps a vector only when its `content_chunks.embedding_input_hash` (`src/core/embedding-input-hash.ts`) equals one recomputed from the current page, or, with no recorded hash, when the page is non-contextual and the legacy model/text-hash checks pass; a contextual chunk without provenance is nulled once. `installPageEmbeddings` records the hash in the vector's UPDATE (the plain re-embed tier by default, or the caller's `built` tier and corpus generation), and returns `{ installed, complete }`: it matches each offered vector to the page's current chunk by source and exact text (not index) and writes it only when its input hash for the captured context is one the current context accepts, in batched `jsonb_to_recordset` UPDATEs, so a page that changed under the provider call keeps the vectors of its unchanged chunks; the embedding signature is stamped only when `complete` (same chunk sequence, nothing dropped). A preserving rebuild likewise keys kept vectors by chunk content, so a top insert shifts vectors with their chunks (tests: `page-embedding-content-validity.test.ts`). Also `stampEmbeddingInputs` does the same for full imports. `resealSafeChunks` re-seals a page below the safe-chunk fence from its unchanged body with no canonical write; `projectionBelowSafeFence` is its predicate. Tests add `projection-embedding-input-hash.test.ts` and `safe-chunk-reseal.test.ts`. It replaces outgoing code edges without deleting incoming edges to retained chunks and clears backfill watermarks. Failed jobs rotate with a retained diagnostic; successful drain refreshes planner statistics. `rebuildPendingPageProjections(engine, limit, { deadlineMs, now, notAfter, retryCooldown, onFailure })` (#5401) checks an injectable clock between pages, bounds a run to rows queued at or before its start (`notAfter`, cast from text in SQL so microseconds survive the driver), applies the 30 s `rebuild_failed` cooldown for the resident, and treats a lock or snapshot error as that page's failure instead of aborting the batch; `projectionBacklog` returns counts only (pending, failed, oldest age) for the drain command and the resident's `projection_status` IPC reply. A same-revision conflict throws `PageProjectionConflictError` naming the fields that changed (`text_projection_revision`, `chunk_digest`, `indexing_context`), the slug and source; `retryProjectionConflict(attempt)` re-runs an attempt that captures a fresh snapshot at most three more times with jitter, then rethrows (`page_projection_conflict` on the wire). Tests: `page-projection-origin.test.ts` (resident rebuild race, two-writer progress, exhausted-retry CLI/JSON output).- `src/core/page-state/chunk-moves.ts` — #7172: `CHUNK_VECTOR_WRITE_BUDGET` (5), the most new `content_chunks` row versions carrying a vector (inserts, and non-HOT updates of `chunk_index`, text or vector; each adds an HNSW entry) one transaction of a managed chunk replacement makes, with its derivation from the publication's 5 s statement bound (a version without a vector is not counted); `planMoveWaves` plans the in-place renumbering of kept rows within a budget (one UPDATE per wave, a cycle parks one row at `-1 - target`), `applyMoveWaves` runs it. `import-file.ts` (with `boundedChunkWrites`, set by page-prepare, import-prepare and sync-prepare) commits a page whose replacement exceeds the budget with its projection pending (queue reason `chunk_replacement_deferred`), and `projections.ts` `continueDeferredProjection` finishes it after commit in steps of at most the budget; `rebuildPendingPageProjections` resumes an interrupted one.- `src/core/page-state/projection-class.ts` — #6803: `projectionClassSql(p, s)`, the one CASE that puts each queued page in exactly one class (`archived`, `text` for Markdown/code and segmented pages, `protected` for a protected fence, `sealable` per `sealableImageSql`, else `reimport`), shared by `projectionBacklog`, the drain probe, search readiness and `embed --stale --images`. `sealableImageSql`: an image page at or after the safe-chunk fence whose one chunk (index 0, `image_asset`) carries the page's own text.- `src/core/page-state/image-seal.ts` — #6803: `sealImageProjections` restores the importer's seal on `sealable` images in groups of 500: a primary-key window of queue rows probed by each page's unique key (a statistics-less PGLite planner otherwise probes through `pages_dedup_idx`), then under the page guard a revision compare-and-set with the class rechecked; no chunk write, the visual vector untouched, a text vector whose recorded input no longer matches nulled for `embed --stale`. `IMAGE_SEAL_PAGES_PER_SECOND` is the measured rate (its comment names the run); `projectionDrainLimit(textPending)` sizes doctor's `--limit` to half `AGENT_TOOL_LIMIT_MS` at that rate, or at the measured `TEXT_REBUILD_PAGES_PER_SECOND` (`rebuild-estimate.ts`; it also times v153's notice) while queued text waits (the drain takes text first).diff --git a/docs/architecture/key-files/engines-2.md b/docs/architecture/key-files/engines-2.mdindex 491de87f56..c6e1c308ed 100644--- a/docs/architecture/key-files/engines-2.md+++ b/docs/architecture/key-files/engines-2.md@@ -37,7 +37,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL- `src/core/engine-sql/health.ts` — `BrainEngine.getHealth` once for both engines (`migrated health`). Three statements, no per-page rows returned: the counters (pages, chunks, links, embedding coverage, missing embeddings, dead links, entity link/timeline coverage), the linkable scope grouped by page type with islanded and with-timeline counts (the orphan policy rendered in SQL by `orphanExclusionSql`; the brain_score timeline grading applies per type), and `most_connected` as live, in-scope link endpoints grouped per entity page (ties break by slug in code-point order; a link whose far endpoint is soft-deleted does not count, #6940). The linkable groups are a separate statement because folding them into the counters crosses Postgres's JIT cost thresholds at about 20k pages. Per-page and per-link checks that misplan without planner statistics (PGLite before its first ANALYZE) are primary-key lookups the planner cannot reorder (scalar subqueries, a LATERAL fenced with `OFFSET 0`), so the statements stay linear with or without statistics. Scope rules: `sourceIds` > `sourceId` > brain-wide, duplicate ids count once, a link counts only when both endpoints are in scope, endpoint liveness in both directions, quarantined pages out of the entity denominators and the linkable scope. Entity pages (#4772) are the types the active schema pack(s) declare as entities, resolved per source by `HealthDeps.entityTypes` (`src/core/schema-pack/entity-types.ts`) and bound as `text[]` parameters (`entityTypePredicateSql`: one list, or a `CASE p.source_id` when sources' packs disagree); a pack that does not load binds an empty list and the result carries `entity_types_status: 'pack_unavailable'`, never the old hardcoded list. Reads take `LegacyUnscopedRead` (pool, no scope transaction). Engine deps are four functions (`embeddingColumn`, `countStalePagesForExtraction`, `getConfig`, `entityTypes`). Pinned field by field against the pre-F4a implementation (`test/helpers/legacy-get-health.ts`, whose `most_connected` was corrected for #6940 as an intended change) by `test/engine-sql-health-equality.test.ts` and `test/e2e/engine-sql-health-parity.test.ts` (direct Postgres and PgBouncer); the pack-driven entity predicate by `test/health-entity-types-pack.test.ts` and `test/e2e/health-entity-types-pack.test.ts`; `most_connected` liveness by `test/health-most-connected-liveness-6940.test.ts` (+ Postgres twin).- `src/core/engine-sql/graph-rank.ts` — #7168: `rankEntitiesStatement(opts)`, the one `rank_entities` aggregate for both engines (a statement builder: the op runs it through `executeRaw` with its statement deadline, like `extractionLagStatement`). Edges are distinct `(from, to, link_type)` triples between live, in-scope endpoints (both endpoints scoped by `sourceIds`), self-links, non-ranking types (`rankingLinkSql`) and, unless `includeMentions`, mention rows excluded. Retired pages (`retiredPageSql`) fold into their `superseded_by`/`merged_into` target in the same source through a recursive chain over retired pages only, capped at `MAX_RETIREMENT_HOPS`; edges dedupe after folding and folded self-links drop. With `remote` every endpoint, chain hop, fold target and non-null link origin must be in scope, live, unquarantined, in an unarchived source and (with `excludePrivate`) not private, so a hidden target never folds. Ordered by the direction's count, then slug and source id (`COLLATE "C"`), LIMIT after folding. Tests: `test/rank-entities.test.ts`.- `src/core/engine-sql/exact-identity.ts` — GBRA-156: `exactIdentityStatement(opts)`, the `whois` candidate read (a statement builder the op runs through `executeRaw`): a UNION of equality probes each served by an existing index, `lower(title)` (`idx_pages_source_title_lower`; the raw query is also lowered by the database), the slug basename (`idx_pages_slug_basename`, accent-folded by the slug grammar), `page_aliases.alias_norm`, and one GIN containment arm per address and shape (`email: x`, `email: [x]`, `emails: x`, `emails: [x]`; one OR of them plans a scan). Every probe and row stays in `sourceIds`; rows are live, in an unarchived source, of a type the `EntityTypeFilter` admits, and with `remote` unquarantined and (with `excludePrivate`) not private. The rows are candidates; the op verifies each. Accent-insensitive titles are found only through the lowered title (same accents, or none in the title) or the slug basename; a case-insensitive frontmatter email only through its as-written or lowercase value or a declared alias. Closing those gaps needs expression indexes (a migration). Tests: the index-plan case in `test/whois.test.ts` and `test/e2e/whois-postgres.test.ts`.-- `src/core/engine-sql/chunks.ts` `upsertChunksOnce` — a chunk replacement inside the caller's transaction: the batched `chunkWriteInvalidations` guard, then one prune (`moveDisplacedChunksAndPrune`: a row whose vector still matches its text (`movableChunkSql`) and whose exact text and source reappear at another index is parked at a negative index and moved there; rows outside the new set are deleted), then one multi-row INSERT per `jsonRowBatches` batch (at most `ROW_BATCH_MAX_ROWS` rows and `ROW_BATCH_MAX_BYTES` encoded bytes; the first is pipelined with the seal). A failure in any batch rolls back the prune and every earlier batch. Tests: `engine-sql-chunks-batched-write.test.ts`, the multi-batch case in `helpers/engine-sql-rollback-cases.ts`.+- `src/core/engine-sql/chunks.ts` `upsertChunksOnce` — a chunk replacement inside the caller's transaction: the batched `chunkWriteInvalidations` guard, then one prune (`moveDisplacedChunksAndPrune`: a row whose vector still matches its text (`movableChunkSql`) and whose exact text and source reappear at another index is parked at a negative index and moved there; rows outside the new set are deleted), then one multi-row INSERT per `jsonRowBatches` batch (at most `ROW_BATCH_MAX_ROWS` rows and `ROW_BATCH_MAX_BYTES` encoded bytes; the first is pipelined with the seal). A failure in any batch rolls back the prune and every earlier batch. Tests: `engine-sql-chunks-batched-write.test.ts`, the multi-batch case in `helpers/engine-sql-rollback-cases.ts`. Its `sealChunks` is `BrainEngine.sealChunks`, run inside the engine's page transaction: lock and read the live page, refuse a missing, deleted or segmented page, an archived source and a stale `expectedRevision`, then delete the chunks, insert the new ones with the seal chunker version, set the search vector and `text_projection_revision`, and drop the page's queued projection job. Both engines delegate to it; the engine parity suite seals its fixture chunks through it.- `src/core/pglite-resetwal.ts` — pg_resetwal for PGLite NodeFS data dirs, in TypeScript (a port of the electric-sql/pglite pg_resetwal contribution, PR #994, Apache-2.0). Validates the PG17 pg_control layout fail-closed (`WalResetUnsupportedError` on any unsupported shape — PG_VERSION ≠ 17, control ≠ 8192 bytes, control version ≠ 1700, bad seg/block size), removes stale postmaster.pid + old WAL segments + archive_status/summaries entries, writes a replacement shutdown-checkpoint WAL segment + CRC32C'd pg_control. Both file writes are atomic + durable (tmp cleared then opened `'wx'` so a pre-planted symlink at the predictable tmp name can never redirect the write, + fsync(tmp) + rename + fsync(parent dir)); write order is segment-first/control-last so a mid-write kill leaves a state that still fails startup and the next attempt re-runs (idempotent — a torn pair can never claim success). WAL segment size is capped at 64MB (pglite ships 16MB; the Postgres-general 1GB bound would let a corrupt-but-plausible control field drive a 1GB allocation on the repair path). Exports the shared PG17 layout literals (`PG_CONTROL_FILE_SIZE`, `isWalSegmentName`) consumed by pglite-repair.ts. LAYOUT COUPLING: any pglite bump past PG17 must revisit this file together with the `./vector` export blocker (TODOS.md "pglite upgrade blocker" entry). Pinned by `test/pglite-resetwal.test.ts`.diff --git a/docs/ci-guards.md b/docs/ci-guards.mdindex faaff95c28..eba6d76818 100644--- a/docs/ci-guards.md+++ b/docs/ci-guards.md@@ -115,6 +115,56 @@ remain. Rows only shrink. The guard fails on:When a domain moves, delete its members' rows and add its `migrated` row inthe same commit.+### Engine raw-SQL ratchet++`scripts/check-engine-raw-sql-ratchet.ts` (`bun run check:engine-raw-sql-ratchet`,+in `bun run verify`) keeps raw SQL outside the engines from growing while it+moves behind typed engine methods (D6 in `docs/designs/RUST_ENGINE.md`, "Track 2+rules"). It parses every `.ts` file under `src/` except the engines+(`src/core/engine.ts`, `src/core/pglite-engine.ts`, `src/core/postgres-engine.ts`,+`src/core/pglite-engine/`, `src/core/postgres-engine/` and+`src/core/engine-sql/`) and counts, per file:++- `execute_raw`: calls named `executeRaw`, `executeRawDirect` or+ `executeRawJsonb`, whatever the receiver (the engine, a transaction, a helper+ that takes `Pick<BrainEngine, 'executeRaw'>`, an executor), with a dot or a+ literal bracket (`e['executeRaw'](...)`);+- `sql_template`: tagged templates whose literal text has SQL structure;+- `driver_call`: `.unsafe(...)`, and `.query(...)` or `.exec(...)` with an+ argument whose literal text has SQL structure.++SQL structure is the engine-sql ratchet's test, so comments and prose never+count. A SQL string held in a variable and passed to `.query(v)` is not seen.++`scripts/engine-raw-sql-baseline.tsv` holds `path<TAB>metric<TAB>count` rows,+with an optional fourth `note` column, generated from the tree (`--print`). A+higher count or a file with no row fails, and so does a lower count until its+row is lowered (`bun scripts/check-engine-raw-sql-ratchet.ts --prune` lowers+stale rows, keeps their notes and never raises one). Instead of a new site,+call a typed engine method, or add one with its SQL in+`src/core/engine-sql/<domain>.ts` (CONTRIBUTING.md "Storage method"). When a+fix must add a site before its area is converted, raise the row (or add it) in+the same PR and write the reason in the note column, as+`scripts/module-size-limits.tsv` does; a reviewer sees the baseline change. A+moved or split file carries its rows with it in the same PR.++### Engine-kind branches++`scripts/check-engine-kind-branches.ts` (`bun run check:engine-kind-branches`,+in `bun run verify`) counts two-way engine branches per file over the same+files: `kind_compare` (`x === 'pglite'`, `x !== 'postgres'`, either side,+where `x` ends in `kind`, `engineKind`, `engine_kind` or `engine`) and+`kind_case` (`case 'pglite':` in a switch over such `x`). A third engine must+not fall silently into one of these branches, so new code asks a capability+question or switches over every engine kind with a `default` clause whose+first statement hands the switched value to a `never` check+(`const unreachable: never = kind;`, `kind satisfies never;`,+`assertNever(kind);`, or `return` / `throw assertNever(kind);`). Such an+exhaustive switch never counts: a third engine fails typecheck there instead.+A check after other statements, inside a nested function, on a shadowing name+or through a cast (`kind as never`) does not exempt a switch. Baseline+`scripts/engine-kind-branches-baseline.tsv`, same rules as above.+### Page body readers`bun run check:page-body-readers` (in verify): every site that reads or writesdiff --git a/package.json b/package.jsonindex 6b69441de4..4848c851f8 100644--- a/package.json+++ b/package.json@@ -175,6 +175,8 @@"check:dynamic-ci": "bun scripts/check-dynamic-ci.ts","check:windows-hide": "bun scripts/check-windows-hide.ts","check:engine-sql-ratchet": "bun scripts/check-engine-sql-ratchet.ts",+ "check:engine-raw-sql-ratchet": "bun scripts/check-engine-raw-sql-ratchet.ts",+ "check:engine-kind-branches": "bun scripts/check-engine-kind-branches.ts","check:core-world-reads": "bun scripts/check-core-world-reads.ts","check:derived-census": "bun scripts/check-derived-census.ts","check:chunk-visibility": "bun scripts/check-chunk-visibility.ts",diff --git a/scripts/check-engine-kind-branches.ts b/scripts/check-engine-kind-branches.tsnew file mode 100644index 0000000000..a543cc26a1--- /dev/null+++ b/scripts/check-engine-kind-branches.ts@@ -0,0 +1,175 @@+#!/usr/bin/env bun+/**+ * Engine-kind branch ratchet (D6 of docs/designs/RUST_ENGINE.md, "Engine+ * selection"; docs/ci-guards.md#engine-kind-branches).+ *+ * A third engine must never fall silently into a two-way `pglite` / `postgres`+ * branch. New code asks a capability question or uses an exhaustive switch+ * over every engine kind instead. This guard counts, per file under src/+ * (TypeScript compiler API), outside the engines:+ *+ * kind_compare `x === 'pglite'`, `x !== 'postgres'` (and `==` / `!=`, either+ * side) where x ends in the name kind, engineKind,+ * engine_kind or engine (`engine.kind`, `cfg.engine`)+ * kind_case `case 'pglite':` / `case 'postgres':` in a switch over such x,+ * unless the switch is exhaustive (its default clause opens+ * with a `never` check on the switched value; see isExhaustive)+ *+ * Outside the engines is the same set as the raw-SQL ratchet+ * (scripts/check-engine-raw-sql-ratchet.ts `isEngineFile`).+ *+ * Baseline: scripts/engine-kind-branches-baseline.tsv, rows+ * path<TAB>metric<TAB>count[<TAB>note]. Counts fall (scripts/lib/count-ratchet.ts);+ * a raise edits the row in the same PR with a note saying why;+ * `--prune` lowers stale rows, `--print` prints the current counts.+ *+ * Seam: GBRAIN_GUARD_ROOT (fixture tree root; baseline read from+ * <root>/scripts/engine-kind-branches-baseline.tsv).+ */+import { readFileSync } from 'node:fs';+import { join, relative } from 'node:path';+import ts from 'typescript';+import { isEngineFile } from './check-engine-raw-sql-ratchet.ts';+import { runCountRatchet, tsFiles } from './lib/count-ratchet.ts';++const ROOT = process.env.GBRAIN_GUARD_ROOT ?? join(import.meta.dir, '..');+export const METRICS = ['kind_compare', 'kind_case'] as const;+export type Metric = (typeof METRICS)[number];++const KINDS = new Set(['pglite', 'postgres']);+const KIND_NAMES = new Set(['kind', 'engineKind', 'engine_kind', 'engine']);+const EQUALITY = new Set([+ ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsEqualsToken,+ ts.SyntaxKind.EqualsEqualsToken, ts.SyntaxKind.ExclamationEqualsToken,+]);++function isKindLiteral(node: ts.Expression): boolean {+ return (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) && KINDS.has(node.text);+}++function isKindExpr(node: ts.Expression): boolean {+ if (ts.isParenthesizedExpression(node) || ts.isNonNullExpression(node) || ts.isAsExpression(node)) return isKindExpr(node.expression);+ if (ts.isIdentifier(node)) return KIND_NAMES.has(node.text);+ if (ts.isPropertyAccessExpression(node)) return KIND_NAMES.has(node.name.text);+ if (ts.isElementAccessExpression(node)) {+ const key = node.argumentExpression;+ return (ts.isStringLiteral(key) || ts.isNoSubstitutionTemplateLiteral(key)) && KIND_NAMES.has(key.text);+ }+ return false;+}++/**+ * An exhaustive switch is the recommended form, so it never counts: the first+ * statement of its `default` clause (or of a block that is the clause's first+ * statement) hands the switched value itself to a compile-time `never` check+ * (`const unreachable: never = kind;`, `kind satisfies never;`,+ * `assertNever(kind);`, `return assertNever(kind);` or `throw assertNever(kind);`),+ * so a third engine fails typecheck instead of falling into a branch.+ * Nothing counts that the first statement does not prove: a check after other+ * statements (an earlier `if (kind) return` narrows the value to `never`), a+ * check inside a nested function, a cast (`kind as never`), a check on some+ * other value, or a switch whose clauses declare a name that shadows the+ * switched value's root identifier.+ */+function isExhaustive(node: ts.SwitchStatement): boolean {+ const def = node.caseBlock.clauses.find(ts.isDefaultClause);+ if (!def) return false;+ const subjectExpr = unwrap(node.expression);+ const root = rootName(subjectExpr);+ if (root === undefined) return false;+ const subject = subjectExpr.getText();+ const isSubject = (e: ts.Expression | undefined): boolean => e !== undefined && unwrap(e).getText() === subject;+ const isAssertNever = (e: ts.Expression | undefined): boolean => {+ if (e === undefined) return false;+ const c = unwrap(e);+ return ts.isCallExpression(c) && ts.isIdentifier(c.expression) && c.expression.text === 'assertNever'+ && c.arguments.length === 1 && isSubject(c.arguments[0]);+ };+ let first: ts.Statement | undefined = def.statements[0];+ const scopes: ts.NodeArray<ts.Statement>[] = node.caseBlock.clauses.map(c => c.statements);+ if (first && ts.isBlock(first)) {+ scopes.push(first.statements);+ first = first.statements[0];+ }+ for (const statements of scopes) {+ for (const st of statements) if (declaredNames(st).includes(root)) return false;+ }+ if (!first) return false;+ if (ts.isVariableStatement(first)) {+ const decls = first.declarationList.declarations;+ return decls.length === 1 && decls[0].type?.kind === ts.SyntaxKind.NeverKeyword && isSubject(decls[0].initializer);+ }+ if (ts.isExpressionStatement(first)) {+ const e = unwrap(first.expression);+ if (ts.isSatisfiesExpression(e)) return e.type.kind === ts.SyntaxKind.NeverKeyword && isSubject(e.expression);+ return isAssertNever(e);+ }+ if (ts.isReturnStatement(first) || ts.isThrowStatement(first)) return isAssertNever(first.expression);+ return false;+}++/** The leftmost identifier of `kind`, `engine.kind` or `cfg['engine']`; undefined for anything else. */+function rootName(e: ts.Expression): string | undefined {+ const x = unwrap(ts.isAsExpression(e) ? e.expression : e);+ if (ts.isIdentifier(x)) return x.text;+ if (x.kind === ts.SyntaxKind.ThisKeyword) return 'this';+ if (ts.isPropertyAccessExpression(x) || ts.isElementAccessExpression(x)) return rootName(x.expression);+ return undefined;+}++/** Names a statement declares in the scope it sits in (variables, functions, classes). */+function declaredNames(st: ts.Statement): string[] {+ const out: string[] = [];+ const bind = (n: ts.BindingName): void => {+ if (ts.isIdentifier(n)) out.push(n.text);+ else for (const el of n.elements) if (!ts.isOmittedExpression(el)) bind(el.name);+ };+ if (ts.isVariableStatement(st)) st.declarationList.declarations.forEach(d => bind(d.name));+ else if ((ts.isFunctionDeclaration(st) || ts.isClassDeclaration(st)) && st.name) out.push(st.name.text);+ return out;+}++function unwrap(e: ts.Expression): ts.Expression {+ return ts.isParenthesizedExpression(e) || ts.isNonNullExpression(e) ? unwrap(e.expression) : e;+}++export function countFile(text: string, fileName = 'file.ts'): Record<Metric, number> {+ const sf = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);+ const counts: Record<Metric, number> = { kind_compare: 0, kind_case: 0 };+ const visit = (node: ts.Node): void => {+ if (ts.isBinaryExpression(node) && EQUALITY.has(node.operatorToken.kind)) {+ if ((isKindLiteral(node.right) && isKindExpr(node.left)) || (isKindLiteral(node.left) && isKindExpr(node.right))) counts.kind_compare++;+ } else if (ts.isSwitchStatement(node) && isKindExpr(node.expression) && !isExhaustive(node)) {+ for (const clause of node.caseBlock.clauses) {+ if (ts.isCaseClause(clause) && isKindLiteral(clause.expression)) counts.kind_case++;+ }+ }+ ts.forEachChild(node, visit);+ };+ visit(sf);+ return counts;+}++export function scanTree(root: string): Map<string, number> {+ const out = new Map<string, number>();+ for (const abs of tsFiles(join(root, 'src'))) {+ const rel = relative(root, abs).replace(/\\/g, '/');+ if (isEngineFile(rel)) continue;+ const counts = countFile(readFileSync(abs, 'utf8'), abs);+ for (const m of METRICS) if (counts[m] > 0) out.set(rel + '\t' + m, counts[m]);+ }+ return out;+}++if (import.meta.main) {+ runCountRatchet({+ name: 'check-engine-kind-branches',+ script: 'scripts/check-engine-kind-branches.ts',+ baselineRel: 'scripts/engine-kind-branches-baseline.tsv',+ anchor: 'docs/ci-guards.md#engine-kind-branches',+ metrics: METRICS,+ why: 'a third engine must never fall into a two-way pglite/postgres branch; these branches fall, and a raise needs a written reason (D6, docs/designs/RUST_ENGINE.md "Engine selection").',+ riseFix: 'ask a capability question (engine.capabilities) or switch over every engine kind with a default clause whose first statement is a never check on the switched value (`const unreachable: never = kind;`; that switch never counts) instead of comparing with \'pglite\' / \'postgres\'; a moved file carries its row with it in the same PR',+ scan: scanTree,+ }, ROOT, process.argv);+}diff --git a/scripts/check-engine-raw-sql-ratchet.ts b/scripts/check-engine-raw-sql-ratchet.tsnew file mode 100644index 0000000000..8061d922f4--- /dev/null+++ b/scripts/check-engine-raw-sql-ratchet.ts@@ -0,0 +1,140 @@+#!/usr/bin/env bun+/**+ * Raw-SQL ratchet (D6 of docs/designs/RUST_ENGINE.md; docs/ci-guards.md#engine-raw-sql-ratchet).+ *+ * Raw SQL outside the engines moves behind typed engine methods, one+ * subsystem at a time, and never grows back. This guard counts, per file+ * under src/ (TypeScript compiler API), the raw-SQL call sites outside the+ * engines:+ *+ * execute_raw calls named executeRaw, executeRawDirect or executeRawJsonb+ * (on the engine, a transaction, a `Pick<BrainEngine,+ * 'executeRaw'>` helper or an executor; any receiver)+ * sql_template tagged templates whose literal text has SQL structure+ * (postgres.js `sql\`...\``, sqlQueryForEngine tags)+ * driver_call `.unsafe(...)`, and `.query(...)` / `.exec(...)` whose+ * argument literal text has SQL structure (driver handles)+ *+ * SQL structure is the same test as the engine-sql ratchet (`isSqlText`), so+ * comments and prose never count. A SQL string held in a variable and passed+ * to `.query(v)` is not seen; executeRaw calls are counted whatever their+ * argument.+ *+ * Outside the engines means every .ts file under src/ except+ * src/core/engine.ts, src/core/pglite-engine.ts, src/core/postgres-engine.ts,+ * src/core/pglite-engine/**, src/core/postgres-engine/** and+ * src/core/engine-sql/** (where SQL belongs; the engine-sql ratchet guards+ * the engines themselves).+ *+ * Baseline: scripts/engine-raw-sql-baseline.tsv, rows path<TAB>metric<TAB>count[<TAB>note].+ * Counts fall; a raise edits the row in the same PR with a note saying why+ * (scripts/lib/count-ratchet.ts): a rise or a new file+ * fails, a lower count fails until its row is lowered (`--prune` lowers stale+ * rows and never raises one). `--print` prints the current counts.+ *+ * Seam: GBRAIN_GUARD_ROOT (fixture tree root; baseline read from+ * <root>/scripts/engine-raw-sql-baseline.tsv).+ */+import { readFileSync } from 'node:fs';+import { join, relative } from 'node:path';+import ts from 'typescript';+import { isSqlText } from './check-engine-sql-ratchet.ts';+import { runCountRatchet, tsFiles } from './lib/count-ratchet.ts';++const ROOT = process.env.GBRAIN_GUARD_ROOT ?? join(import.meta.dir, '..');+export const METRICS = ['execute_raw', 'sql_template', 'driver_call'] as const;+export type Metric = (typeof METRICS)[number];++const EXECUTE_RAW = new Set(['executeRaw', 'executeRawDirect', 'executeRawJsonb']);+const SQL_ARG_DRIVER = new Set(['query', 'exec']);+const ENGINE_FILES = new Set(['src/core/engine.ts', 'src/core/pglite-engine.ts', 'src/core/postgres-engine.ts']);+const ENGINE_DIRS = ['src/core/pglite-engine/', 'src/core/postgres-engine/', 'src/core/engine-sql/'];++export function isEngineFile(rel: string): boolean {+ return ENGINE_FILES.has(rel) || ENGINE_DIRS.some((d) => rel.startsWith(d));+}++function literalText(node: ts.Node): string | null {+ if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;+ if (ts.isTemplateExpression(node)) {+ let text = node.head.text;+ for (const span of node.templateSpans) text += (text.endsWith('$') ? '0' : ' _sub_ ') + span.literal.text;+ return text;+ }+ if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {+ const parts: string[] = [];+ const flatten = (n: ts.Expression): void => {+ if (ts.isBinaryExpression(n) && n.operatorToken.kind === ts.SyntaxKind.PlusToken) {+ flatten(n.left);+ flatten(n.right);+ } else parts.push(literalText(n) ?? ' _sub_ ');+ };+ flatten(node);+ return parts.join('');+ }+ if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node)) return literalText(node.expression);+ return null;+}++function calleeName(expr: ts.Expression): string | null {+ if (ts.isIdentifier(expr)) return expr.text;+ if (ts.isPropertyAccessExpression(expr)) return expr.name.text;+ if (ts.isElementAccessExpression(expr)) {+ const key = expr.argumentExpression;+ return ts.isStringLiteral(key) || ts.isNoSubstitutionTemplateLiteral(key) ? key.text : null;+ }+ if (ts.isNonNullExpression(expr) || ts.isParenthesizedExpression(expr)) return calleeName(expr.expression);+ return null;+}++/** `db.unsafe(...)` or `db['unsafe'](...)`: a member call, never a bare function named the same. */+function isMemberCall(expr: ts.Expression): boolean {+ if (ts.isNonNullExpression(expr) || ts.isParenthesizedExpression(expr)) return isMemberCall(expr.expression);+ return ts.isPropertyAccessExpression(expr) || ts.isElementAccessExpression(expr);+}++export function countFile(text: string, fileName = 'file.ts'): Record<Metric, number> {+ const sf = ts.createSourceFile(fileName, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);+ const counts: Record<Metric, number> = { execute_raw: 0, sql_template: 0, driver_call: 0 };+ const visit = (node: ts.Node): void => {+ if (ts.isCallExpression(node)) {+ const name = calleeName(node.expression);+ if (name !== null && EXECUTE_RAW.has(name)) counts.execute_raw++;+ else if (name === 'unsafe' && isMemberCall(node.expression)) counts.driver_call++;+ else if (name !== null && SQL_ARG_DRIVER.has(name) && isMemberCall(node.expression)+ && node.arguments.some((a) => { const t = literalText(a); return t !== null && isSqlText(t); })) counts.driver_call++;+ } else if (ts.isTaggedTemplateExpression(node)) {+ const name = calleeName(node.tag);+ const text = literalText(node.template);+ if (name !== null && EXECUTE_RAW.has(name)) counts.execute_raw++;+ else if (text !== null && isSqlText(text)) counts.sql_template++;+ }+ ts.forEachChild(node, visit);+ };+ visit(sf);+ return counts;+}++export function scanTree(root: string): Map<string, number> {+ const out = new Map<string, number>();+ for (const abs of tsFiles(join(root, 'src'))) {+ const rel = relative(root, abs).replace(/\\/g, '/');+ if (isEngineFile(rel)) continue;+ const counts = countFile(readFileSync(abs, 'utf8'), abs);+ for (const m of METRICS) if (counts[m] > 0) out.set(rel + '\t' + m, counts[m]);+ }+ return out;+}++if (import.meta.main) {+ runCountRatchet({+ name: 'check-engine-raw-sql-ratchet',+ script: 'scripts/check-engine-raw-sql-ratchet.ts',+ baselineRel: 'scripts/engine-raw-sql-baseline.tsv',+ anchor: 'docs/ci-guards.md#engine-raw-sql-ratchet',+ metrics: METRICS,+ why: 'raw SQL outside the engines falls, and a raise needs a written reason; it moves behind typed engine methods (D6, docs/designs/RUST_ENGINE.md "Track 2 rules").',+ riseFix: 'call a typed engine method instead (add one: SQL in src/core/engine-sql/<domain>.ts, both engines delegate; CONTRIBUTING.md "Storage method"); a moved file carries its row with it in the same PR',+ scan: scanTree,+ }, ROOT, process.argv);+}diff --git a/scripts/engine-kind-branches-baseline.tsv b/scripts/engine-kind-branches-baseline.tsvnew file mode 100644index 0000000000..5e09f70c73--- /dev/null+++ b/scripts/engine-kind-branches-baseline.tsv@@ -0,0 +1,231 @@+# Engine-kind branch ratchet baseline (D6, docs/designs/RUST_ENGINE.md "Engine selection"). Enforced by+# scripts/check-engine-kind-branches.ts via `bun run check:engine-kind-branches` (in verify).+# Rows: path<TAB>metric<TAB>count[<TAB>note]. Two-way pglite/postgres comparisons per file under src/, outside the engines.+# Generated from the tree at its own commit (`bun scripts/check-engine-kind-branches.ts --print`).+# Counts fall; a raise edits the row in the same PR with a note saying why. --prune lowers stale rows. docs/ci-guards.md#engine-kind-branches+src/cli/cli-socket-client.ts kind_compare 1+src/cli/commands/append.ts kind_compare 1+src/cli/commands/projections.ts kind_compare 1+src/cli/main.ts kind_compare 3+src/commands/apply-migrations-schema.ts kind_compare 2+src/commands/apply-migrations.ts kind_compare 3+src/commands/autopilot-dispatch.ts kind_compare 1+src/commands/autopilot-fanout.ts kind_compare 1+src/commands/autopilot-health.ts kind_compare 1+src/commands/autopilot-refusals.ts kind_compare 1+src/commands/autopilot.ts kind_compare 1+src/commands/beliefs-replay-purges.ts kind_compare 1+src/commands/config.ts kind_compare 1+src/commands/connectors/sync.ts kind_compare 1+src/commands/db-repair.ts kind_compare 1+src/commands/diag.ts kind_compare 1+src/commands/doctor.ts kind_compare 1+src/commands/doctor/checks/backup-coverage.ts kind_compare 1 came from master #9625 (shared company brains: owner setup, member keys), which landed after this ratchet was cut+src/commands/doctor/checks/core-health.ts kind_compare 1+src/commands/doctor/checks/database-encoding.ts kind_compare 1+src/commands/doctor/checks/db-connection.ts kind_compare 2+src/commands/doctor/checks/embedding-health.ts kind_compare 3+src/commands/doctor/checks/engine-fit.ts kind_compare 1+src/commands/doctor/checks/graph-embedding.ts kind_compare 1+src/commands/doctor/checks/guard-ledger-checks.ts kind_compare 1+src/commands/doctor/checks/harness-wiring.ts kind_compare 3+src/commands/doctor/checks/keyword-plan.ts kind_compare 1+src/commands/doctor/checks/mcp-request-log.ts kind_compare 4+src/commands/doctor/checks/persistence-consumers.ts kind_compare 3+src/commands/doctor/checks/persistence-requests.ts kind_compare 3+src/commands/doctor/checks/pglite-worker.ts kind_compare 2+src/commands/doctor/checks/planner-stats.ts kind_compare 4+src/commands/doctor/checks/postgres-cancellation.ts kind_compare 1+src/commands/doctor/checks/postgres-tls.ts kind_compare 1+src/commands/doctor/checks/projection-readiness.ts kind_compare 1+src/commands/doctor/checks/queue-assets.ts kind_compare 1+src/commands/doctor/checks/queue-jobs.ts kind_compare 4+src/commands/doctor/checks/schema-function-bodies.ts kind_compare 1+src/commands/doctor/checks/schema-health.ts kind_compare 2+src/commands/doctor/checks/segmented-storage.ts kind_compare 1+src/commands/doctor/checks/session-lane.ts kind_compare 1+src/commands/doctor/checks/vector-plan.ts kind_compare 1+src/commands/doctor/checks/verbs-reflex.ts kind_compare 3+src/commands/doctor/last-known.ts kind_compare 1+src/commands/doctor/registry.ts kind_compare 2+src/commands/doctor/remediate.ts kind_compare 1+src/commands/doctor/report-remote.ts kind_compare 2+src/commands/embed-facts-delegate.ts kind_compare 1+src/commands/embeddings.ts kind_compare 2+src/commands/engine-status.ts kind_compare 6+src/commands/enrich.ts kind_compare 1+src/commands/extract-attendance-repair.ts kind_compare 3+src/commands/extract-stale-delegate.ts kind_compare 1+src/commands/git.ts kind_compare 1 came from master #9627 (held private facts, database-only untrack), which landed after this ratchet was cut+src/commands/import.ts kind_compare 2+src/commands/init.ts kind_compare 1+src/commands/integrity.ts kind_compare 1+src/commands/jobs/run-child.ts kind_compare 1+src/commands/jobs/stats.ts kind_compare 1+src/commands/jobs/submit.ts kind_compare 1+src/commands/jobs/supervisor.ts kind_compare 1+src/commands/jobs/wait.ts kind_compare 1+src/commands/jobs/work.ts kind_compare 1+src/commands/mcp-expose.ts kind_compare 6+src/commands/migrate-engine.ts kind_compare 3+src/commands/migrations/run-engine.ts kind_compare 1+src/commands/migrations/v0_11_0-install.ts kind_compare 2+src/commands/migrations/v0_11_0.ts kind_compare 1+src/commands/migrations/v0_18_0.ts kind_compare 1+src/commands/mounts.ts kind_compare 2+src/commands/pglite-repair.ts kind_compare 1+src/commands/reindex-code-delegate.ts kind_compare 1+src/commands/reindex-vectors.ts kind_compare 1+src/commands/reinit-pglite.ts kind_compare 1+src/commands/repair-jsonb.ts kind_compare 2+src/commands/serve-status.ts kind_compare 1+src/commands/serve.ts kind_compare 5+src/commands/setup.ts kind_compare 3+src/commands/skillopt.ts kind_compare 1+src/commands/sources-lifecycle.ts kind_compare 1+src/commands/sources-refresh-delegate.ts kind_compare 1+src/commands/storage.ts kind_compare 1+src/commands/sync-delegate.ts kind_compare 2+src/commands/sync-persistence-delegate.ts kind_compare 1+src/commands/sync.ts kind_compare 1+src/commands/sync/gitignore.ts kind_compare 1+src/commands/sync/imports.ts kind_compare 2+src/commands/trust.ts kind_compare 1+src/commands/upgrade-restart.ts kind_compare 1+src/commands/wakeshift.ts kind_compare 2+src/core/access/open-pages.ts kind_compare 1+src/core/agent-install/setup.ts kind_compare 1+src/core/analyze-lock.ts kind_compare 1+src/core/backfill-base.ts kind_compare 3+src/core/backfill-effective-date.ts kind_compare 1+src/core/backup/coverage.ts kind_compare 1+src/core/backup/snapshot.ts kind_compare 3 came from master #9625 (shared company brains: owner setup, member keys), which landed after this ratchet was cut+src/core/bootstrap/harness-pending-verify.ts kind_compare 1+src/core/bootstrap/harness.ts kind_compare 2+src/core/brain-registry.ts kind_compare 4+src/core/chronicle/upgrade-notice.ts kind_compare 1+src/core/cli-options.ts kind_compare 1+src/core/cli-socket/probe.ts kind_compare 1+src/core/cli-socket/server.ts kind_compare 1+src/core/connectors/sync.ts kind_compare 1+src/core/context-engine.ts kind_compare 2+src/core/context/openclaw-core.ts kind_compare 1+src/core/context/reflex.ts kind_compare 2+src/core/context/resolve-ipc.ts kind_compare 4+src/core/cycle.ts kind_compare 1+src/core/cycle/facts-drain.ts kind_compare 1+src/core/cycle/synthesize.ts kind_compare 1+src/core/db-lock.ts kind_compare 9+src/core/direct-pool-profile.ts kind_compare 1+src/core/embed-concurrency.ts kind_compare 1+src/core/embedding-ann-build.ts kind_compare 1+src/core/embedding-dim-check.ts kind_compare 2+src/core/engine-connect.ts kind_compare 1+src/core/engine-open.ts kind_compare 4+src/core/facts/drain-scheduler.ts kind_compare 2+src/core/facts/drain.ts kind_compare 2+src/core/facts/fts-index.ts kind_compare 1+src/core/facts/held-fact-move.ts kind_compare 1+src/core/facts/purge-verify.ts kind_compare 5+src/core/function-search-path.ts kind_compare 1+src/core/link-source-check-repair.ts kind_compare 1+src/core/maintenance/run.ts kind_compare 2+src/core/mcp-request-log-retention.ts kind_compare 2+src/core/mentions/policy.ts kind_compare 2+src/core/migrate.ts kind_compare 4+src/core/migration-orchestration-lock.ts kind_compare 2+src/core/migration-preludes.ts kind_compare 3+src/core/minions/budget-meter.ts kind_compare 2+src/core/minions/db-probe.ts kind_compare 1+src/core/minions/embed-backfill-admission.ts kind_compare 4+src/core/minions/no-worker.ts kind_compare 2+src/core/minions/sync-queue-wake.ts kind_compare 1+src/core/minions/worker.ts kind_compare 1+src/core/notifier/handoff.ts kind_compare 1+src/core/notifier/resident.ts kind_compare 1+src/core/notifier/status.ts kind_compare 1+src/core/onboard/checks.ts kind_compare 2+src/core/ops/jobs.ts kind_compare 1+src/core/page-body/ingest.ts kind_compare 2+src/core/page-body/limits.ts kind_compare 1+src/core/page-body/projection.ts kind_compare 1+src/core/page-state/projections.ts kind_compare 1+src/core/page-state/rebuild-estimate.ts kind_compare 1+src/core/page-state/transactions.ts kind_compare 1+src/core/persistence/bounded-reads.ts kind_compare 2+src/core/persistence/checkpoint-validation.ts kind_compare 1+src/core/persistence/consumer-diagnostics.ts kind_compare 4+src/core/persistence/consumer-election.ts kind_compare 2+src/core/persistence/consumer-heartbeat.ts kind_compare 3+src/core/persistence/consumer-lane.ts kind_compare 2+src/core/persistence/consumer.ts kind_compare 11+src/core/persistence/diagnostics.ts kind_compare 1+src/core/persistence/effect-journal.ts kind_compare 1+src/core/persistence/engine-graduation.ts kind_compare 5+src/core/persistence/graduation-drain.ts kind_compare 1+src/core/persistence/group-publish.ts kind_compare 1+src/core/persistence/journal.ts kind_compare 2+src/core/persistence/limits.ts kind_compare 1+src/core/persistence/links-maintenance.ts kind_compare 1+src/core/persistence/local-client.ts kind_compare 2+src/core/persistence/origin-index.ts kind_compare 2+src/core/persistence/owner-activity.ts kind_compare 2+src/core/persistence/page-advisories.ts kind_compare 1+src/core/persistence/pool-capacity.ts kind_compare 2+src/core/persistence/preadmit-cache.ts kind_compare 1+src/core/persistence/publication-deadline.ts kind_compare 2+src/core/persistence/service.ts kind_compare 3+src/core/persistence/sync-group.ts kind_compare 1+src/core/persistence/sync-pass-fold.ts kind_compare 1+src/core/persistence/sync-pass.ts kind_compare 8+src/core/persistence/sync-run.ts kind_compare 1+src/core/persistence/unbound-source.ts kind_compare 1+src/core/persistence/worktree-refresh.ts kind_compare 1+src/core/pglite-leftovers-check.ts kind_compare 1+src/core/pglite-repair-consent.ts kind_compare 1+src/core/planner-stats.ts kind_compare 6+src/core/readiness.ts kind_compare 5+src/core/remediation/run.ts kind_compare 2+src/core/repair/missing-tables.ts kind_compare 2+src/core/schema-migrations/helpers.ts kind_compare 3+src/core/schema-migrations/v014-pages-updated-at-index.ts kind_compare 1+src/core/schema-migrations/v023-files-source-id-page-id-ledger.ts kind_compare 1+src/core/schema-migrations/v034-destructive-guard-columns.ts kind_compare 1+src/core/schema-migrations/v039-multimodal-dual-column-v0-27-1.ts kind_compare 2+src/core/schema-migrations/v041-pages-recency-columns.ts kind_compare 1+src/core/schema-migrations/v045-facts-hot-memory-v0-31.ts kind_compare 2+src/core/schema-migrations/v055-query-cache-search-lite.ts kind_compare 1+src/core/schema-migrations/v066-embed-stale-partial-index.ts kind_compare 1+src/core/schema-migrations/v072-takes-resolved-at-trend-idx-v0-36.ts kind_compare 1+src/core/schema-migrations/v091-pages-generation-trigger-and-bookmark.ts kind_compare 1+src/core/schema-migrations/v096-facts-extract-conversation-session-index.ts kind_compare 1+src/core/schema-migrations/v097-pages-dedup-partial-index.ts kind_compare 1+src/core/schema-migrations/v103-migration-impact-log-and-priority-recent-idx.ts kind_compare 1+src/core/schema-migrations/v104-pages-atom-source-hash-idx.ts kind_compare 1+src/core/schema-migrations/v112-pages-links-extracted-at.ts kind_compare 1+src/core/schema-migrations/v134-restore-chunks-embedding-null-partial-indexes.ts kind_compare 1+src/core/schema-migrations/v165-index-database-only-pending-writes.ts kind_compare 2+src/core/schema-migrations/v170-index-parked-persistence-effects.ts kind_compare 2+src/core/schema-migrations/v172-pages-safe-chunk-pending-index.ts kind_compare 2+src/core/schema-migrations/v173-minion-jobs-dead-subagent-finished-index.ts kind_compare 2+src/core/schema-migrations/v187-fact-relink-attempts.ts kind_compare 2+src/core/schema-migrations/v223-persistence-serve-loop-indexes.ts kind_compare 1+src/core/schema-migrations/v224-page-retrievals.ts kind_compare 1+src/core/schema-migrations/v225-drop-duplicate-embedding-null-index.ts kind_compare 1+src/core/schema-migrations/v248-segmented-page-storage.ts kind_compare 1+src/core/schema-migrations/v275-rls-backfill-unguarded-tables.ts kind_compare 1+src/core/schema-migrations/v292-refresh-write-barrier.ts kind_compare 1+src/core/schema-migrations/v302-link-transitions-source.ts kind_compare 2+src/core/search/projection-statistics.ts kind_compare 7+src/core/search/safe-chunks.ts kind_compare 1+src/core/search/vector-pool.ts kind_compare 2+src/core/shared-skills/restore.ts kind_compare 1+src/core/skillpack/shared-brain-bridge.ts kind_compare 1+src/core/sql-engine-kind.ts kind_compare 2 came from #9631 (the Rust engine shell): the one helper that narrows an engine kind to pglite or postgres and refuses rust; joined at the #9641 merge with 56a9547a+src/core/statement-deadline.ts kind_compare 1+src/core/sync-concurrency.ts kind_compare 2+src/core/sync-identity-downgrades.ts kind_compare 1+src/core/vector-index.ts kind_compare 5+src/core/vector-prewarm.ts kind_compare 2+src/mcp/resolve-ipc-binding.ts kind_compare 1+src/mcp/status-mode.ts kind_compare 1diff --git a/scripts/engine-raw-sql-baseline.tsv b/scripts/engine-raw-sql-baseline.tsvnew file mode 100644index 0000000000..5f7aee661c--- /dev/null+++ b/scripts/engine-raw-sql-baseline.tsv@@ -0,0 +1,1239 @@+# Raw-SQL ratchet baseline (D6, docs/designs/RUST_ENGINE.md "Track 2 rules"). Enforced by+# scripts/check-engine-raw-sql-ratchet.ts via `bun run check:engine-raw-sql-ratchet` (in verify).+# Rows: path<TAB>metric<TAB>count[<TAB>note]. Raw-SQL call sites per file under src/, outside the engines.+# Generated from the tree at its own commit (`bun scripts/check-engine-raw-sql-ratchet.ts --print`).+# Counts fall; a raise edits the row in the same PR with a note saying why. --prune lowers stale rows. docs/ci-guards.md#engine-raw-sql-ratchet+src/cli/enforced-commit-push.ts execute_raw 1+src/cli/enforced-member.ts execute_raw 6+src/commands/access-read-by-nobody.ts execute_raw 2+src/commands/access-rules.ts execute_raw 4+src/commands/access-serves.ts execute_raw 8 came from master #9625 (shared company brains: owner setup, member keys), which landed after this ratchet was cut+src/commands/access.ts execute_raw 6+src/commands/agent-logs.ts execute_raw 1+src/commands/agent-register.ts execute_raw 4+src/commands/agent-register.ts sql_template 8+src/commands/agent.ts execute_raw 1+src/commands/auth-client-rows.ts execute_raw 6+src/commands/auth.ts execute_raw 1+src/commands/auth.ts sql_template 6+src/commands/autopilot-daemon.ts execute_raw 1+src/commands/autopilot-dispatch.ts execute_raw 4+src/commands/autopilot-fanout.ts execute_raw 2+src/commands/autopilot-health.ts execute_raw 1+src/commands/autopilot-retry-global.ts execute_raw 1+src/commands/autopilot.ts execute_raw 1+src/commands/autopilot/install-repo.ts execute_raw 1+src/commands/calibration.ts execute_raw 1+src/commands/code-def.ts execute_raw 2+src/commands/code-refs.ts execute_raw 1+src/commands/code-scope.ts execute_raw 1+src/commands/config.ts execute_raw 1+src/commands/core.ts execute_raw 6+src/commands/db-repair.ts execute_raw 5+src/commands/decide/claims-sweep.ts execute_raw 1+src/commands/decide/proposals.ts execute_raw 2+src/commands/diag.ts execute_raw 4+src/commands/doctor/checks/access-lineage.ts execute_raw 2+src/commands/doctor/checks/agent-session-facts.ts execute_raw 1+src/commands/doctor/checks/atom-body-recheck.ts execute_raw 3+src/commands/doctor/checks/atom-fence-rows.ts execute_raw 1+src/commands/doctor/checks/atom-retirements.ts execute_raw 3+src/commands/doctor/checks/attest-read-access.ts execute_raw 1+src/commands/doctor/checks/calibration.ts execute_raw 10+src/commands/doctor/checks/captured-facts.ts execute_raw 1+src/commands/doctor/checks/connectors.ts execute_raw 1+src/commands/doctor/checks/consolidation-cycle.ts execute_raw 2+src/commands/doctor/checks/content-quality.ts execute_raw 9+src/commands/doctor/checks/conversation-outcomes.ts execute_raw 3+src/commands/doctor/checks/coordination-lock.ts execute_raw 1+src/commands/doctor/checks/core-health.ts execute_raw 9+src/commands/doctor/checks/core-memory.ts execute_raw 1+src/commands/doctor/checks/data-integrity.ts execute_raw 4+src/commands/doctor/checks/database-encoding.ts execute_raw 1+src/commands/doctor/checks/db-ahead-of-git.ts execute_raw 1+src/commands/doctor/checks/db-connection.ts execute_raw 1+src/commands/doctor/checks/default-source-path.ts execute_raw 5+src/commands/doctor/checks/derivation-pricing.ts execute_raw 1+src/commands/doctor/checks/derivation-purge-sweeps.ts execute_raw 1+src/commands/doctor/checks/derived-visibility.ts execute_raw 2+src/commands/doctor/checks/edge-validity.ts execute_raw 4+src/commands/doctor/checks/embed-backfill-stalled.ts execute_raw 2+src/commands/doctor/checks/embedding-health.ts execute_raw 4+src/commands/doctor/checks/embedding-identity.ts execute_raw 1+src/commands/doctor/checks/embedding-plane.ts execute_raw 1+src/commands/doctor/checks/entity-duplicates.ts execute_raw 3+src/commands/doctor/checks/extraction-input.ts execute_raw 2+src/commands/doctor/checks/extraction-sync.ts execute_raw 12+src/commands/doctor/checks/extractor-facts.ts execute_raw 1+src/commands/doctor/checks/facts-pages.ts execute_raw 1+src/commands/doctor/checks/facts-redaction-marker.ts execute_raw 1+src/commands/doctor/checks/fence-integrity.ts execute_raw 1+src/commands/doctor/checks/folder-access.ts execute_raw 3+src/commands/doctor/checks/foreign-writers.ts execute_raw 2+src/commands/doctor/checks/frontmatter-hook.ts execute_raw 1+src/commands/doctor/checks/frontmatter-keys.ts execute_raw 1+src/commands/doctor/checks/function-search-path.ts execute_raw 1+src/commands/doctor/checks/generations.ts execute_raw 3+src/commands/doctor/checks/git-convergence.ts execute_raw 3+src/commands/doctor/checks/git-holds.ts execute_raw 4+src/commands/doctor/checks/git-index-lag.ts execute_raw 1+src/commands/doctor/checks/global-maintenance-timeouts.ts execute_raw 2+src/commands/doctor/checks/google-api-access.ts execute_raw 1+src/commands/doctor/checks/google-calendar.ts execute_raw 1+src/commands/doctor/checks/grant-new-ops.ts execute_raw 2+src/commands/doctor/checks/graph-embedding.ts execute_raw 5+src/commands/doctor/checks/graph-health.ts execute_raw 3+src/commands/doctor/checks/graph-health.ts sql_template 3+src/commands/doctor/checks/guest-source.ts execute_raw 4+src/commands/doctor/checks/image-embedding-coverage.ts execute_raw 2+src/commands/doctor/checks/keyword-plan.ts execute_raw 3+src/commands/doctor/checks/knowledge-health.ts execute_raw 7+src/commands/doctor/checks/landing-gaps.ts execute_raw 1+src/commands/doctor/checks/legacy-job-authority.ts execute_raw 5+src/commands/doctor/checks/legacy-token-grants.ts execute_raw 1+src/commands/doctor/checks/local-audits.ts execute_raw 2+src/commands/doctor/checks/local-edit-adoptions.ts execute_raw 1+src/commands/doctor/checks/loop-facts.ts execute_raw 1+src/commands/doctor/checks/maintenance-drift.ts execute_raw 4+src/commands/doctor/checks/managed-guard.ts execute_raw 2+src/commands/doctor/checks/managed-sync-convergence.ts execute_raw 1+src/commands/doctor/checks/managed-sync-movement.ts execute_raw 1+src/commands/doctor/checks/mcp-request-log.ts execute_raw 4+src/commands/doctor/checks/member-access.ts execute_raw 4+src/commands/doctor/checks/memory-writeback.ts execute_raw 2+src/commands/doctor/checks/missing-recorded-files.ts execute_raw 1+src/commands/doctor/checks/ontology-facts.ts execute_raw 1+src/commands/doctor/checks/origin-twins.ts execute_raw 1+src/commands/doctor/checks/orphan-bindings.ts execute_raw 3+src/commands/doctor/checks/orphan-estimate.ts execute_raw 2+src/commands/doctor/checks/outside-content-fences.ts execute_raw 1+src/commands/doctor/checks/overwritten-edits.ts execute_raw 1+src/commands/doctor/checks/owner-host-stale.ts execute_raw 2+src/commands/doctor/checks/parked-effects.ts execute_raw 2+src/commands/doctor/checks/persistence-capacity.ts execute_raw 3+src/commands/doctor/checks/persistence-compaction.ts execute_raw 2+src/commands/doctor/checks/persistence-requests.ts execute_raw 7+src/commands/doctor/checks/pglite-worker.ts sql_template 1+src/commands/doctor/checks/postgres-tls.ts execute_raw 1+src/commands/doctor/checks/privacy-label-ignored.ts execute_raw 1+src/commands/doctor/checks/projection-readiness.ts execute_raw 1+src/commands/doctor/checks/provenance-stamp-drift.ts execute_raw 1+src/commands/doctor/checks/purge-mirror.ts execute_raw 1+src/commands/doctor/checks/purged-page-facts.ts execute_raw 1+src/commands/doctor/checks/queue-assets.ts execute_raw 3+src/commands/doctor/checks/queue-assets.ts sql_template 1+src/commands/doctor/checks/queue-jobs.ts execute_raw 12+src/commands/doctor/checks/routing-federation.ts execute_raw 7+src/commands/doctor/checks/rows-behind.ts execute_raw 1+src/commands/doctor/checks/runtime-build-skew.ts execute_raw 1+src/commands/doctor/checks/safe-index.ts execute_raw 1+src/commands/doctor/checks/schema-function-bodies.ts execute_raw 1+src/commands/doctor/checks/schema-health.ts execute_raw 1+src/commands/doctor/checks/schema-health.ts sql_template 3+src/commands/doctor/checks/search-eval.ts execute_raw 2+src/commands/doctor/checks/shared-agent-access.ts execute_raw 2+src/commands/doctor/checks/shared-skills.ts execute_raw 1+src/commands/doctor/checks/slug-collisions.ts execute_raw 2+src/commands/doctor/checks/slug-path-mismatch.ts execute_raw 2+src/commands/doctor/checks/stale-embedding-effects.ts execute_raw 2+src/commands/doctor/checks/storage-manifest.ts execute_raw 2+src/commands/doctor/checks/strict-facts-outside-git.ts execute_raw 1+src/commands/doctor/checks/supervisor-health.ts execute_raw 1+src/commands/doctor/checks/sync-failures.ts execute_raw 1+src/commands/doctor/checks/timeline-history.ts execute_raw 2+src/commands/doctor/checks/transcript-archive.ts execute_raw 1+src/commands/doctor/checks/transcript-secrets.ts execute_raw 1+src/commands/doctor/checks/trust-release-unpreviewed.ts execute_raw 1+src/commands/doctor/checks/trust-sources-unclaimed.ts execute_raw 1+src/commands/doctor/checks/unbound-source.ts execute_raw 1+src/commands/doctor/checks/uncommitted-sync-deletions.ts execute_raw 1+src/commands/doctor/checks/unindexed-files.ts execute_raw 1+src/commands/doctor/checks/unlinked-facts.ts execute_raw 6+src/commands/doctor/checks/unscoped-multi-user-token.ts execute_raw 2+src/commands/doctor/checks/unwithdrawn-facts.ts execute_raw 1+src/commands/doctor/checks/vector-coverage.ts execute_raw 2+src/commands/doctor/checks/vector-plan.ts execute_raw 4+src/commands/doctor/checks/wakeshift.ts execute_raw 3+src/commands/doctor/checks/writer-version.ts execute_raw 1+src/commands/doctor/last-known.ts execute_raw 2+src/commands/doctor/registry.ts execute_raw 1+src/commands/doctor/report-remote.ts execute_raw 2+src/commands/doctor/schema-pack-checks.ts execute_raw 3+src/commands/doctor/skill-checks.ts execute_raw 5+src/commands/dream-retriage.ts execute_raw 3+src/commands/edge-proposals.ts execute_raw 6+src/commands/edges-backfill.ts execute_raw 1+src/commands/embed.ts execute_raw 1+src/commands/embeddings.ts execute_raw 1+src/commands/engine-status.ts execute_raw 1+src/commands/enrich.ts execute_raw 1+src/commands/eval-suspected-contradictions.ts execute_raw 1+src/commands/eval-whoknows.ts execute_raw 1+src/commands/export.ts execute_raw 3+src/commands/extract-conversation-facts.ts execute_raw 2+src/commands/extract-explain.ts execute_raw 1+src/commands/extract-mentions-explain.ts execute_raw 6+src/commands/extract-stale-options.ts execute_raw 1+src/commands/extract-status.ts execute_raw 1+src/commands/extract-timeline-db.ts execute_raw 2+src/commands/extract.ts execute_raw 4+src/commands/files.ts execute_raw 4+src/commands/files.ts sql_template 6+src/commands/frontmatter-install-hook.ts execute_raw 3+src/commands/google-attachments.ts execute_raw 3+src/commands/google-setup-tail.ts execute_raw 1+src/commands/google.ts execute_raw 1+src/commands/graph-query.ts execute_raw 1+src/commands/guests.ts execute_raw 1+src/commands/import-calls.ts execute_raw 2+src/commands/import.ts execute_raw 6+src/commands/init-embedding-plane.ts execute_raw 1+src/commands/init-prefer-postgres.ts execute_raw 5+src/commands/init.ts execute_raw 1+src/commands/init.ts sql_template 2+src/commands/integrity.ts execute_raw 1+src/commands/jobs-watch.ts execute_raw 2+src/commands/jobs/smoke.ts execute_raw 2+src/commands/jobs/stats.ts execute_raw 5+src/commands/jobs/work.ts execute_raw 1+src/commands/loops.ts execute_raw 1+src/commands/mcp-provision.ts sql_template 4+src/commands/migrate-embeddings.ts execute_raw 6+src/commands/migrate-engine.ts execute_raw 26+src/commands/migrations/v0_14_0.ts execute_raw 2+src/commands/migrations/v0_16_0.ts execute_raw 1+src/commands/migrations/v0_18_0-storage-backfill.ts execute_raw 6+src/commands/migrations/v0_18_0.ts execute_raw 4+src/commands/migrations/v0_28_0.ts execute_raw 1+src/commands/migrations/v0_29_1.ts execute_raw 1+src/commands/migrations/v0_31_0.ts execute_raw 1+src/commands/migrations/v0_32_2.ts execute_raw 3+src/commands/onboard.ts execute_raw 1+src/commands/orphans.ts execute_raw 2+src/commands/pages-status.ts execute_raw 2+src/commands/quarantine.ts execute_raw 1+src/commands/recall.ts execute_raw 1+src/commands/reconcile-links.ts execute_raw 1+src/commands/reindex-code.ts execute_raw 2+src/commands/reindex-multimodal.ts sql_template 5+src/commands/reindex-search-vector.ts execute_raw 4+src/commands/reindex-synopsis.ts execute_raw 2+src/commands/reindex-vectors.ts execute_raw 2+src/commands/reindex.ts execute_raw 4+src/commands/repair-jsonb.ts driver_call 4+src/commands/repair-propose.ts execute_raw 1+src/commands/serve-health.ts execute_raw 1+src/commands/serve-http-access.ts execute_raw 1+src/commands/serve-http-admin-api.ts execute_raw 4+src/commands/serve-http-admin-api.ts sql_template 12+src/commands/serve-http-api-keys.ts execute_raw 2+src/commands/serve-http-clients.ts execute_raw 1+src/commands/serve-http-mcp.ts execute_raw 6+src/commands/serve-http-metrics.ts execute_raw 2+src/commands/serve-http-registration.ts execute_raw 2+src/commands/serve-http-registration.ts sql_template 3+src/commands/serve-http-webhooks.ts execute_raw 5+src/commands/serve-http.ts sql_template 1+src/commands/sources-add-next.ts execute_raw 2+src/commands/sources-canonical.ts execute_raw 1+src/commands/sources-git-gap.ts execute_raw 15+src/commands/sources-git-reconcile.ts execute_raw 1+src/commands/sources-harden.ts execute_raw 5+src/commands/sources-lifecycle.ts execute_raw 1+src/commands/sources-mirror.ts execute_raw 2+src/commands/sources-pull-strategy.ts execute_raw 1+src/commands/sources-reindex.ts execute_raw 1+src/commands/sources-reset-upstream.ts execute_raw 1+src/commands/sources-retry-held.ts execute_raw 2+src/commands/sources-set-calendar.ts execute_raw 1+src/commands/sources-set-path.ts execute_raw 2+src/commands/sources-strategy.ts execute_raw 3+src/commands/sources-sync-enabled.ts execute_raw 1+src/commands/sources-trust.ts execute_raw 2+src/commands/sources-writers.ts execute_raw 1+src/commands/sources.ts execute_raw 15+src/commands/status.ts execute_raw 7+src/commands/storage.ts execute_raw 1+src/commands/sweep.ts execute_raw 2+src/commands/sync/connector.ts execute_raw 1+src/commands/sync/full.ts execute_raw 2+src/commands/sync/holds.ts execute_raw 5+src/commands/sync/perform.ts execute_raw 1+src/commands/sync/plain-directory.ts execute_raw 2+src/commands/sync/preflight.ts execute_raw 4+src/commands/sync/rename-collision.ts execute_raw 2+src/commands/sync/rename-reconcile.ts execute_raw 1+src/commands/sync/renames.ts execute_raw 1+src/commands/sync/run.ts execute_raw 3+src/commands/takes.ts execute_raw 2+src/commands/trust.ts execute_raw 1+src/commands/upgrade.ts execute_raw 2+src/commands/wakeshift.ts execute_raw 6+src/core/access/actor.ts execute_raw 7+src/core/access/attest-sources.ts sql_template 8+src/core/access/caller.ts execute_raw 9+src/core/access/federation-exposure.ts execute_raw 1+src/core/access/implicit-placement.ts execute_raw 1 came from master #9625 (shared company brains: owner setup, member keys), which landed after this ratchet was cut+src/core/access/labelled-only.ts execute_raw 4+src/core/access/member-facts.ts execute_raw 1+src/core/access/member-sources.ts execute_raw 8+src/core/access/members.ts execute_raw 25+src/core/access/members.ts sql_template 1+src/core/access/open-pages.ts execute_raw 8 came from master #9625 (shared company brains: owner setup, member keys), which landed after this ratchet was cut+src/core/access/open-twins.ts execute_raw 1+src/core/access/owner.ts execute_raw 1+src/core/access/policy-migrate.ts execute_raw 4+src/core/access/policy-transfer.ts execute_raw 1+src/core/access/policy.ts execute_raw 31+src/core/access/requester-scope.ts execute_raw 4+src/core/access/room.ts execute_raw 2+src/core/access/serves.ts execute_raw 2+src/core/access/token-member-status.ts sql_template 1+src/core/advisor/collect-chronicle.ts execute_raw 1+src/core/advisor/collect-mcp-client-fit.ts execute_raw 1+src/core/advisor/collect-stalled-jobs.ts execute_raw 2+src/core/agent-install/setup.ts execute_raw 2+src/core/agent-install/shared-skills.ts execute_raw 1+src/core/ai/chat-usage.ts execute_raw 1+src/core/ai/decide/egress.ts execute_raw 1+src/core/ai/decide/proposals-store.ts execute_raw 16+src/core/ai/decide/review-lane.ts execute_raw 17+src/core/ai/decide/store.ts execute_raw 19+src/core/analyze-lock.ts execute_raw 1+src/core/attendance-repair.ts execute_raw 17+src/core/backfill-base.ts execute_raw 12+src/core/backfill-effective-date.ts execute_raw 6+src/core/backfill-skips.ts execute_raw 2+src/core/backup/coverage.ts execute_raw 2+src/core/backup/quarantine.ts execute_raw 9+src/core/backup/snapshot.ts execute_raw 5+src/core/behavior-change-notice.ts execute_raw 1+src/core/belief/append.ts execute_raw 7+src/core/belief/backfill.ts execute_raw 8+src/core/belief/changes.ts execute_raw 2+src/core/belief/coverage-report.ts execute_raw 13+src/core/belief/coverage.ts execute_raw 5+src/core/belief/history.ts execute_raw 2+src/core/belief/identity.ts execute_raw 2+src/core/belief/ledger.ts execute_raw 2+src/core/belief/lifetimes.ts execute_raw 6+src/core/belief/page-at-time.ts execute_raw 8+src/core/belief/preimages.ts execute_raw 2+src/core/belief/purge-mirror.ts execute_raw 24+src/core/belief/purge.ts execute_raw 19+src/core/belief/retier.ts execute_raw 3+src/core/belief/state.ts execute_raw 4+src/core/belief/writers.ts execute_raw 2+src/core/bootstrap/harness-cleanup.ts execute_raw 1+src/core/bootstrap/harness-skills.ts execute_raw 1+src/core/bootstrap/verify.ts execute_raw 6+src/core/brain-writer.ts execute_raw 3+src/core/brainstorm/domain-bank.ts execute_raw 1+src/core/brainstorm/orchestrator.ts execute_raw 1+src/core/budget/daily-ledger.ts execute_raw 6+src/core/by-mention.ts execute_raw 6+src/core/calibration/domain-aggregators.ts execute_raw 4+src/core/calibration/think-ab.ts execute_raw 2+src/core/calibration/undo-wave.ts execute_raw 9+src/core/chronicle/backfill.ts execute_raw 1+src/core/chronicle/campaign.ts execute_raw 3+src/core/chronicle/event-identity.ts execute_raw 1+src/core/chronicle/execute.ts execute_raw 9+src/core/chronicle/ledger-stats.ts execute_raw 5+src/core/chronicle/ledger.ts execute_raw 10+src/core/chronicle/publish.ts execute_raw 4+src/core/chunkers/symbol-resolver.ts execute_raw 8+src/core/claw-test/seed-pglite.ts driver_call 1+src/core/code-chunks.ts execute_raw 3+src/core/code-graph-readiness.ts execute_raw 2+src/core/code-intel/recursive-walk.ts execute_raw 4+src/core/code-intel/traversal-cache.ts execute_raw 4+src/core/company-brain/admission.ts execute_raw 12+src/core/company-brain/demo.ts execute_raw 2+src/core/company-brain/evidence.ts execute_raw 3+src/core/company-brain/profile.ts execute_raw 4+src/core/company-brain/receipts.ts execute_raw 9+src/core/company-brain/runtime.ts execute_raw 14+src/core/company-brain/status.ts execute_raw 1+src/core/company-brain/verification.ts execute_raw 3+src/core/config-db-merge.ts execute_raw 1+src/core/connection-manager.ts sql_template 3+src/core/connectors/api-source.ts execute_raw 2+src/core/connectors/connector-hold-session.ts execute_raw 1+src/core/connectors/db-cursor.ts execute_raw 2+src/core/connectors/item-holds-store.ts execute_raw 12+src/core/content-drift-sweep.ts execute_raw 2+src/core/context/compile-view.ts execute_raw 1+src/core/context/corpus-source.ts execute_raw 2+src/core/context/proactive-brief.ts execute_raw 10+src/core/context/retrieval-reflex.ts execute_raw 6+src/core/context/session-state.ts execute_raw 7+src/core/context/volunteer-events.ts execute_raw 2+src/core/context/volunteer.ts execute_raw 1+src/core/contextual-retrieval-service.ts execute_raw 4+src/core/conversation-parser/llm-base.ts execute_raw 2+src/core/core-memory.ts execute_raw 2+src/core/cycle.ts execute_raw 2+src/core/cycle/calibration-profile.ts execute_raw 2+src/core/cycle/chronicle.ts execute_raw 4+src/core/cycle/concept-publication.ts execute_raw 3+src/core/cycle/concept-redirects.ts execute_raw 2+src/core/cycle/derived-write-through.ts execute_raw 5+src/core/cycle/dream-breaker.ts execute_raw 5+src/core/cycle/dream-provenance.ts execute_raw 3+src/core/cycle/dream-write-deferral.ts execute_raw 4+src/core/cycle/drift.ts execute_raw 2+src/core/cycle/edge-contradictions.ts execute_raw 13+src/core/cycle/edge-contradictions.ts sql_template 1+src/core/cycle/extract-atoms-generation.ts execute_raw 4+src/core/cycle/extract-atoms-input.ts execute_raw 6+src/core/cycle/extract-atoms-page-state.ts execute_raw 4+src/core/cycle/extract-atoms-stamp.ts execute_raw 1+src/core/cycle/extract-atoms.ts execute_raw 6+src/core/cycle/extract-facts.ts execute_raw 13+src/core/cycle/extract-takes.ts execute_raw 10+src/core/cycle/filing-rules.ts execute_raw 1+src/core/cycle/grade-takes.ts execute_raw 4+src/core/cycle/inline-drain.ts execute_raw 3+src/core/cycle/pattern-claim-sources.ts execute_raw 1+src/core/cycle/patterns-plan.ts execute_raw 1+src/core/cycle/patterns.ts execute_raw 11+src/core/cycle/phantom-redirect-managed.ts execute_raw 7+src/core/cycle/phantom-redirect.ts execute_raw 9+src/core/cycle/phases/consolidate.ts execute_raw 10+src/core/cycle/propose-takes-failures.ts execute_raw 5+src/core/cycle/propose-takes.ts execute_raw 5+src/core/cycle/source-window.ts execute_raw 4+src/core/cycle/synthesize-completion.ts execute_raw 4+src/core/cycle/synthesize-concepts.ts execute_raw 1+src/core/cycle/synthesize-generations.ts execute_raw 1+src/core/cycle/synthesize-postprocess.ts execute_raw 3+src/core/cycle/synthesize-verify-epochs.ts execute_raw 3+src/core/cycle/synthesize.ts execute_raw 6+src/core/cycle/transcript-discovery.ts execute_raw 2+src/core/cycle/unindexed-files.ts execute_raw 1+src/core/db-lock.ts driver_call 10+src/core/db-lock.ts execute_raw 3+src/core/db-lock.ts sql_template 9+src/core/db.ts driver_call 2+src/core/db.ts sql_template 4+src/core/derived-links.ts execute_raw 10+src/core/destructive-guard.ts execute_raw 17+src/core/eligibility/activation.ts execute_raw 2+src/core/eligibility/explain.ts execute_raw 4+src/core/eligibility/fence-overlay.ts execute_raw 3 came from master #9627 (held private facts, database-only untrack), which landed after this ratchet was cut+src/core/eligibility/generation.ts execute_raw 1+src/core/eligibility/scan.ts execute_raw 7+src/core/eligibility/stamp.ts execute_raw 5 came from master #9574 (held private restatements), which landed before this ratchet+src/core/embed-backfill-stall.ts execute_raw 1+src/core/embed-backfill-submit.ts execute_raw 2+src/core/embed-consent.ts execute_raw 2+src/core/embed-facts.ts execute_raw 8+src/core/embed-stale-images.ts execute_raw 2+src/core/embed-stale.ts execute_raw 3+src/core/embed-takes.ts execute_raw 1+src/core/embedding-ann-build.ts execute_raw 8+src/core/embedding-dim-check.ts execute_raw 4+src/core/embedding-invalidation.ts execute_raw 8+src/core/embedding-migration-budget.ts execute_raw 2+src/core/embedding-migration-retention.ts execute_raw 6+src/core/embedding-migration-worst-case.ts execute_raw 3+src/core/embedding-migration.ts execute_raw 34+src/core/embedding-readiness.ts execute_raw 5+src/core/embedding-restamp.ts execute_raw 2+src/core/embedding-state.ts execute_raw 1+src/core/enrichment-service.ts execute_raw 2+src/core/entities/near-name.ts execute_raw 1+src/core/entities/resolve.ts execute_raw 13+src/core/entity-identity.ts execute_raw 6+src/core/eval-contradictions/cost-prompt.ts execute_raw 1+src/core/eval-contradictions/scoped-read.ts execute_raw 2+src/core/export-publish.ts driver_call 3+src/core/export-snapshot.ts execute_raw 4+src/core/export-stage.ts driver_call 3+src/core/extract-ner.ts execute_raw 1+src/core/extract-ner.ts sql_template 1+src/core/extract-takes-from-pages.ts execute_raw 1+src/core/extract-timeline-from-meetings.ts execute_raw 5+src/core/extract/receipt-writer.ts execute_raw 2+src/core/extract/rollup-writer.ts execute_raw 3+src/core/extraction-lag.ts execute_raw 2+src/core/extraction-watermark.ts execute_raw 5+src/core/facts/absorb-log.ts execute_raw 1+src/core/facts/backstop.ts execute_raw 1+src/core/facts/bulk-days.ts execute_raw 1+src/core/facts/capture-dedup.ts execute_raw 4+src/core/facts/claim-conflicts.ts execute_raw 3+src/core/facts/contested-claims.ts execute_raw 1+src/core/facts/conversation-entity-hints.ts execute_raw 1+src/core/facts/conversation-incremental.ts execute_raw 1+src/core/facts/conversation-memo.ts execute_raw 4+src/core/facts/conversation-publication.ts execute_raw 24+src/core/facts/conversation-relink-carry.ts execute_raw 1+src/core/facts/conversation-relink.ts execute_raw 6+src/core/facts/dead-absorb-retry.ts execute_raw 2+src/core/facts/derivation-inputs.ts execute_raw 6+src/core/facts/drain.ts execute_raw 2+src/core/facts/embedding-identity.ts execute_raw 2+src/core/facts/facts-home.ts execute_raw 4+src/core/facts/fence-fact-append.ts execute_raw 4+src/core/facts/fence-write.ts execute_raw 2+src/core/facts/file-body-guard.ts execute_raw 2+src/core/facts/forget.ts execute_raw 4+src/core/facts/fts-index.ts execute_raw 3+src/core/facts/gone-page-facts.ts execute_raw 4+src/core/facts/held-fact-move.ts execute_raw 12+src/core/facts/meta-hook.ts execute_raw 1+src/core/facts/ontology-rekey.ts execute_raw 4+src/core/facts/proposal-review.ts execute_raw 3+src/core/facts/proposal-supersede.ts execute_raw 4+src/core/facts/purge-overlay.ts execute_raw 3+src/core/facts/purge-reasons.ts execute_raw 8+src/core/facts/purge-verify.ts execute_raw 22+src/core/facts/purge.ts execute_raw 39+src/core/facts/question-recall.ts execute_raw 1+src/core/facts/reconcile-watermark.ts execute_raw 6+src/core/facts/relink-publish.ts execute_raw 8+src/core/facts/relink.ts execute_raw 5+src/core/facts/retire.ts execute_raw 1+src/core/facts/similar-active.ts execute_raw 2+src/core/facts/single-prepare.ts execute_raw 7+src/core/facts/subject-infer.ts execute_raw 1+src/core/facts/unfenced-facts.ts execute_raw 8+src/core/facts/withdrawal-discovery.ts execute_raw 9+src/core/facts/withdrawal.ts execute_raw 17+src/core/facts/write-single.ts execute_raw 3+src/core/facts/writeback-settings.ts execute_raw 2+src/core/feedback/store.ts execute_raw 19+src/core/fence-repair/attempts.ts execute_raw 3+src/core/fence-repair/census-store.ts execute_raw 9+src/core/fence-repair/census.ts execute_raw 6+src/core/fence-repair/hold-fix.ts execute_raw 2+src/core/fence-repair/import-step.ts execute_raw 2+src/core/fence-repair/repair-io.ts execute_raw 1+src/core/fence-repair/uncommitted.ts execute_raw 3+src/core/forecast-journal.ts execute_raw 3+src/core/function-search-path.ts execute_raw 3+src/core/generations/adapters/atoms.ts execute_raw 3+src/core/generations/adapters/chronicle-events.ts execute_raw 13+src/core/generations/adapters/extracted-facts.ts execute_raw 4+src/core/generations/adapters/fact-rows.ts execute_raw 7+src/core/generations/adapters/page.ts execute_raw 2+src/core/generations/adapters/single-page.ts execute_raw 1+src/core/generations/adapters/synthesis.ts execute_raw 1+src/core/generations/adapters/take-rows.ts execute_raw 2+src/core/generations/fence-evidence.ts execute_raw 4+src/core/generations/fence-restore.ts execute_raw 3+src/core/generations/fence.ts execute_raw 5+src/core/generations/ledger-scrub.ts execute_raw 7+src/core/generations/managed.ts execute_raw 7+src/core/generations/publish.ts execute_raw 19+src/core/generations/repair.ts execute_raw 6+src/core/ghost-pages.ts execute_raw 4+src/core/git/untrack-admission.ts execute_raw 3 came from master #9627 (held private facts, database-only untrack), which landed after this ratchet was cut+src/core/github-source.ts execute_raw 3+src/core/google/attachment-backfill.ts execute_raw 2+src/core/google/counterparty.ts execute_raw 2+src/core/google/file-modes.ts execute_raw 2+src/core/google/google-source.ts execute_raw 4+src/core/google/loop-catchup.ts execute_raw 8+src/core/google/loops-exclusion.ts execute_raw 4+src/core/google/loops-extract.ts execute_raw 1+src/core/google/loops-reciprocity.ts execute_raw 1+src/core/google/people-calendar-sweep.ts execute_raw 3+src/core/google/sweep-shared.ts execute_raw 2+src/core/grants/legacy-token.ts execute_raw 9+src/core/grants/legacy-token.ts sql_template 3+src/core/grants/lifecycle.ts sql_template 7+src/core/grants/migration.ts execute_raw 1+src/core/grants/migration.ts sql_template 5+src/core/grants/model.ts execute_raw 1+src/core/grants/rescope.ts sql_template 7+src/core/grants/service.ts sql_template 11+src/core/grants/shared-exposure.ts execute_raw 1+src/core/guard-ledger-checks.ts execute_raw 3+src/core/guests/admission.ts execute_raw 4+src/core/guests/marker.ts execute_raw 2+src/core/guests/note.ts execute_raw 1+src/core/guests/owner-credentials.ts execute_raw 1+src/core/guests/promote.ts execute_raw 4+src/core/guests/sources.ts execute_raw 9 came from master #9625 (shared company brains: owner setup, member keys), which landed after this ratchet was cut+src/core/guests/stamp-readable.ts execute_raw 1+src/core/harness/client-setup.ts execute_raw 1+src/core/harness/client-setup.ts sql_template 1+src/core/heal-audit.ts execute_raw 3+src/core/health-memo.ts execute_raw 1+src/core/held-embedding.ts execute_raw 2+src/core/import-chunk-reuse.ts execute_raw 2+src/core/import-file.ts execute_raw 7+src/core/import-identity.ts execute_raw 1+src/core/ingestion/applied-captures.ts execute_raw 5+src/core/last-retrieved.ts execute_raw 1+src/core/line-grammar-config.ts execute_raw 2+src/core/link-extraction.ts execute_raw 1+src/core/link-reconciliation.ts execute_raw 5+src/core/link-relationship-notes.ts execute_raw 1+src/core/link-relationships.ts execute_raw 10+src/core/link-single-value.ts execute_raw 2+src/core/link-source-check-repair.ts execute_raw 3+src/core/link-temporal-apply.ts execute_raw 8+src/core/links-fence-projection.ts execute_raw 8+src/core/loops/loops-store.ts execute_raw 15+src/core/maintenance/run.ts execute_raw 1+src/core/maintenance/status.ts execute_raw 1+src/core/mcp-request-log-retention.ts execute_raw 4+src/core/mcp-usage.ts execute_raw 3+src/core/meetings/meetings-source.ts execute_raw 3+src/core/mentions/coverage.ts execute_raw 4+src/core/mentions/newer-mentions.ts execute_raw 1+src/core/mentions/pass.ts execute_raw 37+src/core/mentions/policy.ts execute_raw 1+src/core/mentions/referrers.ts execute_raw 11+src/core/mentions/siblings.ts execute_raw 4+src/core/mentions/stale.ts execute_raw 2+src/core/migrate.ts execute_raw 2+src/core/migration-preludes.ts execute_raw 12+src/core/minions/admission.ts execute_raw 1+src/core/minions/authorize-legacy.ts execute_raw 7+src/core/minions/budget-meter.ts sql_template 14+src/core/minions/db-probe.ts execute_raw 2+src/core/minions/delegated-admission.ts execute_raw 4+src/core/minions/delegated-policy.ts execute_raw 1+src/core/minions/delegated-spend.ts execute_raw 1+src/core/minions/global-maintenance-stall.ts execute_raw 1+src/core/minions/handlers/autopilot-cycle.ts execute_raw 1+src/core/minions/handlers/contextual-reindex-per-chunk.ts execute_raw 1+src/core/minions/handlers/embed-backfill.ts execute_raw 2+src/core/minions/handlers/facts-absorb.ts execute_raw 1+src/core/minions/handlers/ingest-capture.ts execute_raw 3+src/core/minions/handlers/subagent-oneshot.ts execute_raw 5+src/core/minions/handlers/subagent-persistence.ts execute_raw 10+src/core/minions/handlers/subagent.ts execute_raw 6+src/core/minions/handlers/sync-job-drain.ts execute_raw 1+src/core/minions/handlers/sync.ts execute_raw 3+src/core/minions/idempotency-coalesce.ts execute_raw 6+src/core/minions/job-context.ts execute_raw 2+src/core/minions/job-insight.ts execute_raw 8+src/core/minions/job-list-page.ts execute_raw 1+src/core/minions/lease-pressure-audit.ts execute_raw 3+src/core/minions/legacy-cancel.ts execute_raw 4+src/core/minions/legacy-selection.ts execute_raw 2+src/core/minions/queue-families.ts execute_raw 1+src/core/minions/queue.ts execute_raw 86+src/core/minions/rate-leases.ts execute_raw 6+src/core/minions/source-filesystem.ts execute_raw 1+src/core/minions/spend-authorization.ts execute_raw 5+src/core/minions/submission-authority.ts execute_raw 7+src/core/minions/supervisor.ts execute_raw 2+src/core/minions/sync-queue-wake.ts execute_raw 2+src/core/minions/terminal-events.ts execute_raw 1+src/core/minions/terminal-hook.ts execute_raw 1+src/core/minions/tools/read-budget.ts execute_raw 1+src/core/minions/transcript.ts execute_raw 2+src/core/minions/watchdog-attribution.ts execute_raw 5+src/core/minions/worker-shutdown.ts execute_raw 1+src/core/minions/worker.ts execute_raw 7+src/core/multi-source-drift.ts execute_raw 1+src/core/notifier/nudge.ts execute_raw 1+src/core/notifier/resident.ts execute_raw 3+src/core/notifier/status.ts execute_raw 3+src/core/notifier/store.ts execute_raw 15+src/core/oauth-grants.ts sql_template 16+src/core/oauth-provider.ts sql_template 22+src/core/onboard/checks.ts execute_raw 5+src/core/onboard/checks.ts sql_template 2+src/core/onboard/impact-capture.ts execute_raw 3+src/core/onboard/mcp-onboarding.ts execute_raw 2+src/core/onboard/mcp-onboarding.ts sql_template 3+src/core/op-checkpoint.ts execute_raw 7+src/core/ops/admin.ts execute_raw 4+src/core/ops/attribution.ts execute_raw 8+src/core/ops/backlinks-paged.ts execute_raw 3+src/core/ops/chronicle.ts execute_raw 1+src/core/ops/chunks.ts execute_raw 1 came from master #9574 (held private restatements), which landed before this ratchet+src/core/ops/context.ts execute_raw 1+src/core/ops/extraction.ts execute_raw 1+src/core/ops/facts.ts execute_raw 1+src/core/ops/files.ts execute_raw 13+src/core/ops/get-page-body.ts execute_raw 2+src/core/ops/get-page-projection.ts execute_raw 1+src/core/ops/graph-rank.ts execute_raw 3+src/core/ops/jobs.ts execute_raw 4+src/core/ops/known-as-of.ts execute_raw 3+src/core/ops/links.ts execute_raw 1+src/core/ops/loops.ts execute_raw 6+src/core/ops/page-upload.ts execute_raw 3+src/core/ops/pages.ts execute_raw 1+src/core/ops/persistence.ts execute_raw 4+src/core/ops/put-page-revision-source.ts execute_raw 1+src/core/ops/qm-memory.ts execute_raw 2+src/core/ops/request-tools.ts execute_raw 2+src/core/ops/search-exact.ts execute_raw 2 came from master #9574 (held private restatements), which landed before this ratchet+src/core/ops/search-type-filter.ts execute_raw 1+src/core/ops/search.ts execute_raw 2+src/core/ops/skills-catalog.ts execute_raw 2+src/core/ops/storage-manifest.ts execute_raw 2+src/core/ops/tags.ts execute_raw 1+src/core/ops/takes.ts execute_raw 1+src/core/ops/trust.ts execute_raw 1+src/core/ops/usage.ts execute_raw 2+src/core/ops/valid-time-read.ts execute_raw 6+src/core/ops/wakeshift.ts execute_raw 5+src/core/ops/whois.ts execute_raw 2+src/core/output/writer.ts execute_raw 1+src/core/oversized-backfill.ts execute_raw 6+src/core/page-body/body-tiling.ts execute_raw 4+src/core/page-body/ingest.ts execute_raw 3+src/core/page-body/projection.ts execute_raw 11+src/core/page-body/read-range.ts execute_raw 6+src/core/page-body/rechunk.ts execute_raw 8+src/core/page-body/segment-blocks.ts execute_raw 2+src/core/page-body/segment-conversation.ts execute_raw 3+src/core/page-body/segment-derive.ts execute_raw 33+src/core/page-body/segment-facts.ts execute_raw 1+src/core/page-body/segment-ledger.ts execute_raw 1+src/core/page-body/segment-rewrite.ts execute_raw 9+src/core/page-body/segmented-embedding.ts execute_raw 8+src/core/page-body/splice.ts execute_raw 2+src/core/page-body/streamed-import.ts execute_raw 1+src/core/page-body/tail-digest.ts execute_raw 1+src/core/page-embedding-budget.ts execute_raw 13+src/core/page-embedding-lease.ts execute_raw 4+src/core/page-searchability.ts execute_raw 3+src/core/page-spend.ts execute_raw 4+src/core/page-state/chunk-moves.ts execute_raw 1+src/core/page-state/contextual-proof.ts execute_raw 3+src/core/page-state/credential-reseal.ts execute_raw 6+src/core/page-state/guards.ts execute_raw 11+src/core/page-state/image-seal.ts execute_raw 5+src/core/page-state/materialize.ts execute_raw 5+src/core/page-state/projection-status.ts execute_raw 1+src/core/page-state/projections.ts execute_raw 43+src/core/page-state/rebuild-estimate.ts execute_raw 1+src/core/page-state/rename-alias.ts execute_raw 11+src/core/page-state/revision-backfill-schema.ts execute_raw 12+src/core/page-state/tags.ts execute_raw 4+src/core/page-state/text-seal.ts execute_raw 1+src/core/page-state/versions.ts execute_raw 9+src/core/page-window/bounded-lead.ts execute_raw 2+src/core/page-window/segmented.ts execute_raw 5+src/core/pages-upsert-arbiter.ts execute_raw 6+src/core/persistence/activation.ts execute_raw 9+src/core/persistence/admin-intent.ts execute_raw 3+src/core/persistence/admin-lock.ts execute_raw 7+src/core/persistence/administration.ts execute_raw 8+src/core/persistence/admission-origin.ts execute_raw 1+src/core/persistence/applied-watermark.ts execute_raw 4+src/core/persistence/atom-maintenance.ts execute_raw 21+src/core/persistence/authority.ts execute_raw 11+src/core/persistence/blocking-effects.ts execute_raw 2+src/core/persistence/bounded-reads.ts execute_raw 10+src/core/persistence/canonical-projections.ts execute_raw 16+src/core/persistence/capacity-forecast.ts execute_raw 8+src/core/persistence/capacity-view.ts execute_raw 1+src/core/persistence/change-reason.ts execute_raw 4+src/core/persistence/checkpoint-validation.ts execute_raw 5+src/core/persistence/compaction-pass.ts execute_raw 2+src/core/persistence/config-snapshot.ts execute_raw 2+src/core/persistence/connector-account-mismatch.ts execute_raw 2+src/core/persistence/connector-checkpoint-migration.ts execute_raw 13+src/core/persistence/connector-google-receipts.ts execute_raw 1+src/core/persistence/connector-path.ts execute_raw 3+src/core/persistence/connector-reset.ts execute_raw 1+src/core/persistence/connector-state.ts execute_raw 7+src/core/persistence/connector-status.ts execute_raw 2+src/core/persistence/connector-sync.ts execute_raw 26+src/core/persistence/consumer-diagnostics.ts execute_raw 3+src/core/persistence/consumer-heartbeat.ts execute_raw 4+src/core/persistence/consumer-lane.ts execute_raw 2+src/core/persistence/consumer.ts execute_raw 6+src/core/persistence/context.ts execute_raw 5+src/core/persistence/control.ts execute_raw 2+src/core/persistence/coordination-lock.ts execute_raw 2+src/core/persistence/coordinator.ts execute_raw 9+src/core/persistence/core-guard.ts execute_raw 2+src/core/persistence/database-write.ts execute_raw 2+src/core/persistence/deactivation.ts execute_raw 21+src/core/persistence/derived-origin-hold.ts execute_raw 10+src/core/persistence/derived-retirement-hold.ts execute_raw 1+src/core/persistence/detached-pages.ts execute_raw 4+src/core/persistence/diagnostics.ts execute_raw 7+src/core/persistence/drift-conflicts.ts execute_raw 9+src/core/persistence/effect-catchup.ts execute_raw 1+src/core/persistence/effect-facts.ts execute_raw 8+src/core/persistence/effect-journal.ts execute_raw 24+src/core/persistence/effect-links.ts execute_raw 8+src/core/persistence/effect-recovery-scan.ts execute_raw 1+src/core/persistence/effect-recovery.ts execute_raw 19+src/core/persistence/effect-retry.ts execute_raw 14+src/core/persistence/effect-settle.ts execute_raw 7+src/core/persistence/effect-targets.ts execute_raw 8+src/core/persistence/effects.ts execute_raw 19+src/core/persistence/embedding-noop-settle.ts execute_raw 5+src/core/persistence/embedding-settlement.ts execute_raw 7+src/core/persistence/engine-graduation.ts execute_raw 18+src/core/persistence/facts-maintenance.ts execute_raw 4+src/core/persistence/facts-prepare.ts execute_raw 5+src/core/persistence/file-claims.ts execute_raw 2+src/core/persistence/file-repair.ts execute_raw 4+src/core/persistence/filesystem-guard.ts execute_raw 3+src/core/persistence/forget-prepare.ts execute_raw 6+src/core/persistence/git-conversion.ts execute_raw 16+src/core/persistence/git-declared.ts execute_raw 7+src/core/persistence/git-door.ts execute_raw 1+src/core/persistence/git-durability-administration.ts execute_raw 4+src/core/persistence/git-durability-policy.ts execute_raw 2+src/core/persistence/git-gap.ts execute_raw 5+src/core/persistence/git-push-holds.ts execute_raw 1+src/core/persistence/graduation-copy.ts execute_raw 36+src/core/persistence/graduation-custody.ts execute_raw 1+src/core/persistence/graduation-digest.ts execute_raw 4+src/core/persistence/graduation-drain.ts execute_raw 11+src/core/persistence/graduation-inventory.ts execute_raw 3+src/core/persistence/graduation-losses.ts execute_raw 5+src/core/persistence/graduation-schema.ts execute_raw 10+src/core/persistence/graduation-target.ts driver_call 2+src/core/persistence/graduation-target.ts execute_raw 5+src/core/persistence/graduation-verify.ts execute_raw 15+src/core/persistence/group-publish.ts execute_raw 11+src/core/persistence/head-blocker.ts execute_raw 2+src/core/persistence/held-reads.ts execute_raw 3+src/core/persistence/hosted-repo.ts execute_raw 4+src/core/persistence/housekeeping-turn.ts execute_raw 2+src/core/persistence/identity.ts execute_raw 8+src/core/persistence/import-deferral.ts execute_raw 1+src/core/persistence/import-mutations.ts execute_raw 3+src/core/persistence/import-prepare.ts execute_raw 1+src/core/persistence/import-reads.ts execute_raw 7+src/core/persistence/intent-redaction.ts execute_raw 10+src/core/persistence/journal.ts execute_raw 65+src/core/persistence/landing-gaps.ts execute_raw 3+src/core/persistence/large-page-guard.ts execute_raw 1+src/core/persistence/legacy-locks.ts execute_raw 1+src/core/persistence/legacy-sync-failures.ts execute_raw 1+src/core/persistence/limits.ts execute_raw 7+src/core/persistence/links-extraction-holds.ts execute_raw 2+src/core/persistence/links-preparation.ts execute_raw 4+src/core/persistence/local-edit-adoption.ts execute_raw 6+src/core/persistence/loop-fact-retirement.ts execute_raw 7+src/core/persistence/maintenance.ts execute_raw 4+src/core/persistence/managed-mode.ts execute_raw 3+src/core/persistence/managed-sources.ts execute_raw 1+src/core/persistence/managed-sync-orphans.ts execute_raw 14+src/core/persistence/manual-links.ts execute_raw 8+src/core/persistence/memory-mutations.ts execute_raw 5+src/core/persistence/memory-prepare.ts execute_raw 4+src/core/persistence/memory-proposals.ts execute_raw 16+src/core/persistence/mirror-read-only.ts execute_raw 4+src/core/persistence/moved-pages.ts execute_raw 7+src/core/persistence/noop-kernel.ts execute_raw 2+src/core/persistence/onboarding.ts execute_raw 1+src/core/persistence/origin-guard.ts execute_raw 9+src/core/persistence/origin-index.ts execute_raw 5+src/core/persistence/origin-twins.ts execute_raw 2+src/core/persistence/orphan-bindings.ts execute_raw 2+src/core/persistence/overwritten-edits.ts execute_raw 3+src/core/persistence/owner-activity.ts execute_raw 1+src/core/persistence/ownership.ts execute_raw 25+src/core/persistence/page-advisories.ts execute_raw 1+src/core/persistence/page-append.ts execute_raw 3+src/core/persistence/page-batch.ts execute_raw 2+src/core/persistence/page-mutations.ts execute_raw 6+src/core/persistence/page-prepare.ts execute_raw 11+src/core/persistence/page-purge.ts execute_raw 30+src/core/persistence/page-upload.ts execute_raw 16+src/core/persistence/page-visibility.ts execute_raw 14+src/core/persistence/parked-groups.ts execute_raw 1+src/core/persistence/pending-import.ts execute_raw 1+src/core/persistence/physical-root.ts execute_raw 15+src/core/persistence/pre-activation-release.ts execute_raw 7+src/core/persistence/preadmit-cache.ts execute_raw 4+src/core/persistence/preparation-budget.ts execute_raw 1+src/core/persistence/prepared-maintenance.ts execute_raw 13+src/core/persistence/preview-approval.ts execute_raw 3+src/core/persistence/protocol.ts execute_raw 3+src/core/persistence/provider.ts execute_raw 1+src/core/persistence/publication-deadline.ts execute_raw 1+src/core/persistence/purge-deleted.ts execute_raw 7+src/core/persistence/purge-name-stores.ts execute_raw 1+src/core/persistence/purge-parks.ts execute_raw 6+src/core/persistence/purge-slug-stores.ts execute_raw 4+src/core/persistence/purged-intent.ts execute_raw 2+src/core/persistence/put-page-screen.ts execute_raw 1+src/core/persistence/rebuildable-cache.ts execute_raw 2+src/core/persistence/receipt-true-up.ts execute_raw 3+src/core/persistence/reconcile-audit.ts execute_raw 2+src/core/persistence/reconcile-backup.ts execute_raw 4+src/core/persistence/reconcile-prepare.ts execute_raw 1+src/core/persistence/reconcile-state.ts execute_raw 5+src/core/persistence/reconcile.ts execute_raw 3+src/core/persistence/recovery-resolve.ts execute_raw 10+src/core/persistence/refresh-barrier.ts execute_raw 9+src/core/persistence/refresh-retry-hint.ts execute_raw 1+src/core/persistence/refusal-breaker.ts execute_raw 2+src/core/persistence/repair-busy.ts execute_raw 4+src/core/persistence/resolve-paths.ts execute_raw 5+src/core/persistence/rows-behind.ts execute_raw 4+src/core/persistence/schema-admission.ts execute_raw 3+src/core/persistence/searchable.ts execute_raw 2+src/core/persistence/segmented-apply.ts execute_raw 13+src/core/persistence/segmented-mirror-gate.ts execute_raw 1+src/core/persistence/semantic-pages.ts execute_raw 2+src/core/persistence/skill-activation.ts execute_raw 12+src/core/persistence/soak-counters.ts execute_raw 4+src/core/persistence/source-lifecycle.ts execute_raw 33+src/core/persistence/staging.ts execute_raw 4+src/core/persistence/switches.ts execute_raw 1+src/core/persistence/sync-administration.ts execute_raw 1+src/core/persistence/sync-admission.ts execute_raw 4+src/core/persistence/sync-admitted.ts execute_raw 1+src/core/persistence/sync-authority.ts execute_raw 2+src/core/persistence/sync-blocked.ts execute_raw 2+src/core/persistence/sync-concurrent-write.ts execute_raw 2+src/core/persistence/sync-cursor-key.ts execute_raw 7+src/core/persistence/sync-delete-tombstones.ts execute_raw 2+src/core/persistence/sync-discovery.ts execute_raw 6+src/core/persistence/sync-drain.ts execute_raw 4+src/core/persistence/sync-dry-run-writer.ts execute_raw 1+src/core/persistence/sync-failures.ts execute_raw 9+src/core/persistence/sync-freshness.ts execute_raw 3+src/core/persistence/sync-ghosts.ts execute_raw 3+src/core/persistence/sync-group.ts execute_raw 1+src/core/persistence/sync-held-deletions.ts execute_raw 1+src/core/persistence/sync-holds-carried.ts execute_raw 1+src/core/persistence/sync-holds.ts execute_raw 31+src/core/persistence/sync-idle-skips.ts execute_raw 1+src/core/persistence/sync-lanes.ts execute_raw 1+src/core/persistence/sync-lease.ts execute_raw 5+src/core/persistence/sync-markers.ts execute_raw 9+src/core/persistence/sync-movement.ts execute_raw 5+src/core/persistence/sync-origin.ts execute_raw 1+src/core/persistence/sync-page-fault.ts execute_raw 9+src/core/persistence/sync-pass-apply.ts execute_raw 3+src/core/persistence/sync-pass-batch.ts execute_raw 3+src/core/persistence/sync-pass-carried.ts execute_raw 2+src/core/persistence/sync-pass-confirm.ts execute_raw 8+src/core/persistence/sync-pass-episode.ts execute_raw 2+src/core/persistence/sync-pass-fold.ts execute_raw 3+src/core/persistence/sync-pass-readers.ts execute_raw 1+src/core/persistence/sync-pass-row.ts execute_raw 4+src/core/persistence/sync-pass-run.ts execute_raw 14+src/core/persistence/sync-pass-status.ts execute_raw 3+src/core/persistence/sync-pass.ts execute_raw 14+src/core/persistence/sync-prepare.ts execute_raw 15+src/core/persistence/sync-prescreen.ts execute_raw 2+src/core/persistence/sync-run.ts execute_raw 28+src/core/persistence/sync-screen.ts execute_raw 1+src/core/persistence/sync-slices.ts execute_raw 2+src/core/persistence/sync-slug-mode.ts execute_raw 3+src/core/persistence/sync-status.ts execute_raw 11+src/core/persistence/sync-stop-class.ts execute_raw 1+src/core/persistence/sync-streamed.ts execute_raw 1+src/core/persistence/sync-tail-record.ts execute_raw 3+src/core/persistence/sync-tail.ts execute_raw 2+src/core/persistence/sync-waivers.ts execute_raw 8+src/core/persistence/sync-window.ts execute_raw 2+src/core/persistence/takes-prepare.ts execute_raw 9+src/core/persistence/terminal-failures.ts execute_raw 5+src/core/persistence/topology-clone.ts execute_raw 19+src/core/persistence/topology-locks.ts execute_raw 20+src/core/persistence/topology-receipts.ts execute_raw 16+src/core/persistence/topology-recovery.ts execute_raw 17+src/core/persistence/topology-transaction.ts execute_raw 1+src/core/persistence/transfer-administration.ts execute_raw 1+src/core/persistence/transient-retry.ts execute_raw 1+src/core/persistence/twin-merge.ts execute_raw 16+src/core/persistence/unbound-source.ts execute_raw 4+src/core/persistence/unimported-file.ts execute_raw 1+src/core/persistence/unindexed-files.ts execute_raw 8+src/core/persistence/upload-streamed.ts execute_raw 1+src/core/persistence/valid-time-advisory.ts execute_raw 1+src/core/persistence/worktree-refresh.ts execute_raw 32+src/core/persistence/write-applied.ts execute_raw 1+src/core/persistence/writer-versions.ts execute_raw 3+src/core/pglite-statements.ts driver_call 1+src/core/planner-stats.ts execute_raw 14+src/core/post-upgrade-reembed.ts execute_raw 1+src/core/quarantine-override.ts execute_raw 1+src/core/quarantine.ts execute_raw 1+src/core/questions/auto-think-migration.ts execute_raw 1+src/core/questions/freshness.ts execute_raw 3+src/core/questions/pages.ts execute_raw 1+src/core/questions/receipt.ts execute_raw 1+src/core/questions/refresh.ts execute_raw 14+src/core/questions/service.ts execute_raw 1+src/core/questions/store.ts execute_raw 7+src/core/readiness.ts execute_raw 2+src/core/reason-trailers.ts execute_raw 2+src/core/reindex-consent.ts execute_raw 1+src/core/remediation/context.ts execute_raw 2+src/core/remediation/run.ts execute_raw 1+src/core/repair/accepted-takes.ts execute_raw 4+src/core/repair/access.ts execute_raw 2+src/core/repair/agent-session-facts.ts execute_raw 11+src/core/repair/aliases.ts execute_raw 3+src/core/repair/atom-fence-rows.ts execute_raw 3+src/core/repair/atoms-restore.ts execute_raw 5+src/core/repair/attribution-backfill.ts execute_raw 7+src/core/repair/captured-facts.ts execute_raw 7+src/core/repair/connector-fences.ts execute_raw 2+src/core/repair/consolidate-ties.ts execute_raw 3+src/core/repair/contact-rows.ts execute_raw 4+src/core/repair/content-receipt-root.ts execute_raw 4+src/core/repair/contextual-mode.ts execute_raw 1+src/core/repair/conversation-labels.ts execute_raw 14+src/core/repair/core.ts execute_raw 6+src/core/repair/duplicate-facts.ts execute_raw 6+src/core/repair/extractor-facts.ts execute_raw 9+src/core/repair/fact-claim-dates.ts execute_raw 3+src/core/repair/facts-rehome.ts execute_raw 4+src/core/repair/failed-writes.ts execute_raw 19+src/core/repair/fences.ts execute_raw 4+src/core/repair/file-drift.ts execute_raw 6+src/core/repair/frontmatter.ts execute_raw 8+src/core/repair/ghost-pages.ts execute_raw 1+src/core/repair/label-write.ts execute_raw 1+src/core/repair/legacy-twins.ts execute_raw 9+src/core/repair/loop-facts.ts execute_raw 2+src/core/repair/lost-fence-rows.ts execute_raw 10+src/core/repair/missing-tables.ts execute_raw 2+src/core/repair/moved-pages.ts execute_raw 4+src/core/repair/ontology-facts.ts execute_raw 4+src/core/repair/open-facts.ts execute_raw 11+src/core/repair/origin-carry.ts execute_raw 4+src/core/repair/origin-twins-heal.ts execute_raw 4+src/core/repair/origin-twins.ts execute_raw 11+src/core/repair/orphan-children.ts execute_raw 6+src/core/repair/overwritten-edits.ts execute_raw 3+src/core/repair/private-labels.ts execute_raw 5+src/core/repair/provenance.ts execute_raw 3+src/core/repair/purged-change-reasons.ts execute_raw 7+src/core/repair/purged-page-facts.ts execute_raw 6+src/core/repair/readers.ts execute_raw 3+src/core/repair/receipt-compaction.ts execute_raw 3+src/core/repair/redacted-facts.ts execute_raw 6+src/core/repair/rename-identity.ts execute_raw 7+src/core/repair/rotation.ts execute_raw 3+src/core/repair/rows-behind.ts execute_raw 1+src/core/repair/safe-chunks.ts execute_raw 1+src/core/repair/secret-spans.ts execute_raw 24+src/core/repair/segmented-mirror.ts execute_raw 5+src/core/repair/segmented-tiling.ts execute_raw 7+src/core/repair/settle.ts execute_raw 1+src/core/repair/slug-autoheal.ts execute_raw 1+src/core/repair/slug-conflicts.ts execute_raw 5+src/core/repair/split-facts.ts execute_raw 3+src/core/repair/stale-atoms.ts execute_raw 3+src/core/repair/take-supersession.ts execute_raw 4+src/core/repair/timeline-comments.ts execute_raw 5+src/core/repair/timeline-order.ts execute_raw 4+src/core/repair/timeline.ts execute_raw 6+src/core/repair/unwithdrawn-facts.ts execute_raw 6+src/core/repair/url-clone-fences.ts execute_raw 5+src/core/repair/visibility.ts execute_raw 11+src/core/restore-target.ts execute_raw 4+src/core/review-lists.ts execute_raw 1+src/core/schema-migrations/helpers.ts execute_raw 12+src/core/schema-migrations/v039-multimodal-dual-column-v0-27-1.ts execute_raw 1+src/core/schema-migrations/v045-facts-hot-memory-v0-31.ts execute_raw 2+src/core/schema-migrations/v055-query-cache-search-lite.ts execute_raw 2+src/core/schema-migrations/v123-configurable-fts-language.ts execute_raw 4+src/core/schema-migrations/v124-page-search-vector-drop-compiled-truth.ts execute_raw 1+src/core/schema-migrations/v142-takes-embedding-dimension-matches-config.ts execute_raw 8+src/core/schema-migrations/v144-open-loops.ts execute_raw 7+src/core/schema-migrations/v153-verified-text-projection-activation.ts execute_raw 1+src/core/schema-migrations/v164-shared-brain-skills-and-membership.ts execute_raw 1+src/core/schema-migrations/v191-alias-source-cascade.ts execute_raw 2+src/core/schema-migrations/v210-clamp-oauth-token-ttl.ts sql_template 6+src/core/schema-migrations/v225-drop-duplicate-embedding-null-index.ts execute_raw 1+src/core/schema-migrations/v232-fts-cjk-boundary.ts execute_raw 3+src/core/schema-migrations/v234-persistence-git-durability.ts execute_raw 1+src/core/schema-migrations/v245-page-search-vector-bounded-timeline.ts execute_raw 1+src/core/schema-migrations/v275-rls-backfill-unguarded-tables.ts execute_raw 4+src/core/schema-migrations/v281-derived-state-maintainers-fail-closed.ts execute_raw 1+src/core/schema-migrations/v302-link-transitions-source.ts execute_raw 5+src/core/schema-missing-tables.ts execute_raw 1+src/core/schema-pack/detect.ts execute_raw 3+src/core/schema-pack/engine-resolution.ts execute_raw 1+src/core/schema-pack/entity-types.ts execute_raw 1+src/core/schema-pack/field-usage.ts execute_raw 2+src/core/schema-pack/lint-rules.ts execute_raw 3+src/core/schema-pack/page-to-alias.ts execute_raw 3+src/core/schema-pack/page-to-link.ts execute_raw 1+src/core/schema-pack/query-cache-invalidator.ts execute_raw 1+src/core/schema-pack/retype.ts execute_raw 3+src/core/schema-pack/review.ts execute_raw 2+src/core/schema-pack/stats.ts execute_raw 2+src/core/schema-pack/sync.ts execute_raw 3+src/core/schema-pack/unify-types-handler.ts execute_raw 1+src/core/schema-verify.ts execute_raw 2+src/core/search-vector-backfill.ts execute_raw 3+src/core/search/alias-fanout.ts execute_raw 4+src/core/search/collapse.ts execute_raw 2+src/core/search/cosine-rescore.ts execute_raw 1+src/core/search/dedup.ts execute_raw 1+src/core/search/embedding-column.ts execute_raw 1+src/core/search/entity-anchor.ts execute_raw 5+src/core/search/entity-facts.ts execute_raw 1+src/core/search/evidence-date.ts execute_raw 3+src/core/search/evidence-delivery.ts execute_raw 2+src/core/search/exact-scan.ts execute_raw 2+src/core/search/fact-relevance.ts execute_raw 13 came from master #9627 (held private facts, database-only untrack), which landed after this ratchet was cut+src/core/search/facts-arm.ts execute_raw 3+src/core/search/feedback-boost.ts execute_raw 1+src/core/search/frontmatter-where.ts execute_raw 1+src/core/search/hybrid.ts execute_raw 2+src/core/search/hybrid/alias-resolved.ts execute_raw 1+src/core/search/ignored-privacy-labels.ts execute_raw 3+src/core/search/image-vector-presence.ts execute_raw 1+src/core/search/private-visibility.ts execute_raw 4+src/core/search/projection-readiness.ts execute_raw 2+src/core/search/projection-statistics.ts execute_raw 11+src/core/search/provenance-demotion.ts execute_raw 3+src/core/search/query-cache-gate.ts execute_raw 2+src/core/search/query-cache.ts execute_raw 9+src/core/search/relational-chain.ts execute_raw 1+src/core/search/relational-recall.ts execute_raw 3+src/core/search/retrieval-coverage.ts execute_raw 2+src/core/search/safe-chunks.ts execute_raw 2+src/core/search/saved-facts-match.ts execute_raw 2+src/core/search/telemetry.ts execute_raw 2+src/core/search/transcript-quote.ts execute_raw 3+src/core/search/two-pass.ts execute_raw 5+src/core/serve-sync-runner.ts execute_raw 1+src/core/session-lane.ts execute_raw 3+src/core/shared-skills/adopted-packs.ts execute_raw 1+src/core/shared-skills/catalog.ts execute_raw 3+src/core/shared-skills/compatibility.ts execute_raw 2+src/core/shared-skills/content-freshness.ts execute_raw 1+src/core/shared-skills/knowledge-guard.ts execute_raw 6+src/core/shared-skills/membership-authority.ts execute_raw 4+src/core/shared-skills/membership.ts execute_raw 17+src/core/shared-skills/migration-export.ts execute_raw 7+src/core/shared-skills/migration-members.ts execute_raw 1+src/core/shared-skills/migration-projection.ts execute_raw 2+src/core/shared-skills/migration.ts execute_raw 4+src/core/shared-skills/optimizer.ts execute_raw 1+src/core/shared-skills/policy.ts execute_raw 11+src/core/shared-skills/publication.ts execute_raw 14+src/core/shared-skills/receipt-root.ts execute_raw 2+src/core/shared-skills/restore.ts execute_raw 27+src/core/shared-skills/retention.ts execute_raw 12+src/core/shared-skills/setup-source-policy.ts execute_raw 1+src/core/shared-skills/setup.ts execute_raw 6+src/core/shared-skills/source-opt-out.ts execute_raw 3+src/core/similar-pages.ts execute_raw 1+src/core/skillpack/shared-brain-bridge.ts execute_raw 4+src/core/slack/slack-source.ts execute_raw 4+src/core/source-default-search.ts execute_raw 2+src/core/source-delete.ts execute_raw 2+src/core/source-health.ts execute_raw 6+src/core/source-resolver.ts execute_raw 15+src/core/sources-load.ts execute_raw 4+src/core/sources-not-readable.ts execute_raw 1+src/core/sources-ops.ts execute_raw 15+src/core/spend-log.ts sql_template 2+src/core/sql-query.ts execute_raw 2+src/core/storage-manifest/adopt.ts execute_raw 4+src/core/storage-manifest/door.ts execute_raw 1+src/core/storage-manifest/find.ts execute_raw 4+src/core/storage-manifest/source.ts execute_raw 4+src/core/stored-embedding-identity.ts execute_raw 3+src/core/surface-audit.ts execute_raw 1+src/core/sweep.ts execute_raw 3+src/core/sync-anchor.ts execute_raw 11+src/core/sync-applicability.ts execute_raw 1+src/core/sync-attempt.ts execute_raw 1+src/core/sync-cost-gate.ts execute_raw 1+src/core/sync-dispatch-read.ts execute_raw 1+src/core/sync-git.ts execute_raw 3+src/core/sync-identity-downgrades.ts execute_raw 8+src/core/sync-pending.ts execute_raw 3+src/core/sync-policy.ts execute_raw 1+src/core/sync-rename-identity.ts execute_raw 4+src/core/sync-status-report.ts execute_raw 3+src/core/sync-upstream-rewrite.ts execute_raw 2+src/core/sync-upstream.ts execute_raw 2+src/core/sync.ts execute_raw 1+src/core/synopsis-sweep.ts execute_raw 4+src/core/take-proposals.ts execute_raw 8+src/core/takes-horizon.ts execute_raw 5+src/core/takes-quality-eval/receipt-write.ts execute_raw 1+src/core/takes-quality-eval/replay.ts execute_raw 1+src/core/takes-quality-eval/runner.ts execute_raw 1+src/core/takes-quality-eval/trend.ts execute_raw 1+src/core/takes-write.ts execute_raw 5+src/core/think/index.ts execute_raw 2+src/core/think/persist-take.ts execute_raw 1+src/core/timeline-dedup-repair.ts execute_raw 11+src/core/timeline-extract.ts execute_raw 11+src/core/timeline-write-through.ts execute_raw 1+src/core/token-mint.ts execute_raw 3+src/core/token-mint.ts sql_template 1+src/core/transcripts/archive.ts execute_raw 15+src/core/transcripts/discover.ts execute_raw 2+src/core/transcripts/hermes.ts driver_call 1+src/core/transcripts/ingest.ts execute_raw 3+src/core/transcripts/recover.ts execute_raw 1+src/core/transcripts/secret-audit.ts execute_raw 1+src/core/trust/allow-rules.ts execute_raw 6+src/core/trust/backfill.ts execute_raw 15+src/core/trust/channel.ts execute_raw 2+src/core/trust/claim-state.ts execute_raw 1+src/core/trust/claim.ts execute_raw 9+src/core/trust/derived-gate.ts execute_raw 1+src/core/trust/fence-append.ts execute_raw 3+src/core/trust/fence-guard.ts execute_raw 9+src/core/trust/held-removals.ts execute_raw 4+src/core/trust/label-lowerings.ts execute_raw 1+src/core/trust/marker-repair.ts execute_raw 4+src/core/trust/min-trust.ts execute_raw 3+src/core/trust/owner-actions.ts execute_raw 7+src/core/trust/page-handlers.ts execute_raw 7+src/core/trust/page-write.ts execute_raw 9+src/core/trust/privacy-hold-reply.ts execute_raw 1 came from master #9627 (held private facts, database-only untrack), which landed after this ratchet was cut+src/core/trust/propagation.ts execute_raw 4+src/core/trust/proposals.ts execute_raw 7+src/core/trust/provenance-drift.ts execute_raw 3+src/core/trust/refs.ts execute_raw 1+src/core/trust/release-publish.ts execute_raw 2+src/core/trust/review.ts execute_raw 18+src/core/trust/supersede-handlers.ts execute_raw 12+src/core/trust/taint.ts execute_raw 5+src/core/trust/timeline-projection.ts execute_raw 2+src/core/uncommitted-deletions.ts execute_raw 1+src/core/url-clone.ts execute_raw 2+src/core/url-source-origin.ts execute_raw 4+src/core/vector-index.ts driver_call 2+src/core/vector-index.ts execute_raw 9+src/core/vector-prewarm.ts execute_raw 4+src/core/verbs/entity-card-identity.ts execute_raw 1+src/core/verbs/entity-card.ts execute_raw 7+src/core/verbs/entity-names.ts execute_raw 1+src/core/verbs/entity-references.ts execute_raw 1+src/core/verbs/entity-source.ts execute_raw 1+src/core/verbs/entity-text-mentions.ts execute_raw 1+src/core/verbs/entity-variants.ts execute_raw 4+src/core/wakeshift/drain.ts execute_raw 10+src/core/wakeshift/forget.ts sql_template 6+src/core/wakeshift/spool.ts execute_raw 3+src/core/wakeshift/terms.ts execute_raw 2+src/core/wanted-links-store.ts execute_raw 6+src/core/write-gate-scan.ts execute_raw 2+src/core/write-gate-store.ts execute_raw 8+src/core/write-through.ts execute_raw 3+src/eval/brainbench/adapters/codex.ts execute_raw 1+src/eval/brainbench/metrics/continuity.ts execute_raw 1+src/eval/brainbench/metrics/deletion.ts execute_raw 2+src/eval/brainbench/metrics/state-resolution.ts execute_raw 2+src/eval/brainbench/metrics/trust-reads.ts execute_raw 7+src/eval/brainbench/metrics/write-back.ts execute_raw 1+src/eval/brainbench/seed.ts execute_raw 1+src/eval/brainbench/trust-scenario.ts execute_raw 13+src/eval/brainbench/trust-suites.ts execute_raw 1+src/eval/decide-eval-flags.ts execute_raw 1+src/eval/longmemeval/harness.ts execute_raw 2+src/eval/longmemeval/retrieval-arms.ts execute_raw 2+src/eval/shared/embed-cache.ts driver_call 4+src/mcp/http-transport.ts sql_template 3+src/mcp/source-preflight.ts execute_raw 1diff --git a/scripts/guards-manifest.tsv b/scripts/guards-manifest.tsvindex c69bd82203..b80b23e949 100644--- a/scripts/guards-manifest.tsv+++ b/scripts/guards-manifest.tsv@@ -72,6 +72,8 @@ check-module-size.sh scanner yes committed per-file line ceilings (module-size-lcheck-function-size.ts scanner yes W5 per-function line ratchet (TS compiler API): new >300-line function, growth, shrink-below-limit, stale slack, missing row, raise without issue/TODO id; baseline scripts/function-size-baseline.tsv keyed by path + name path; --transfer for verified move-only commitscheck-item-allowlist-catches.ts scanner yes GBRA-130 per-item allowlist-catch ratchet (TS compiler API): a catch in a loop body or forEach/map callback that tests the caught error code against a set/list/literal and rethrows it; per-file counts in scripts/item-allowlist-catches-baseline.tsv only shrink (growth, stale row, zero/missing-file row, malformed rows fail); --update rewrites for shrinkscheck-engine-sql-ratchet.ts scanner yes goal (a) engine-sql ratchet (TS AST): SQL-bearing engine members (façade classes + pglite-engine/ and postgres-engine/ modules) need a baseline row or an engine-sql-ok marker; stale/duplicate rows and unbacked migrated domains fail; baseline scripts/engine-sql-baseline.tsv; --prune drops stale rows only+check-engine-raw-sql-ratchet.ts scanner yes D6 raw-SQL ratchet (TS AST): per-file counts under src/ outside the engines of executeRaw/executeRawDirect/executeRawJsonb calls, SQL tagged templates and driver unsafe/query/exec calls with SQL text; rises, new files and stale rows fail; baseline scripts/engine-raw-sql-baseline.tsv; --prune lowers stale rows only+check-engine-kind-branches.ts scanner yes D6 engine-kind branch ratchet (TS AST): per-file counts under src/ outside the engines of two-way pglite/postgres comparisons and switch cases on kind/engineKind/engine; rises, new files and stale rows fail; baseline scripts/engine-kind-branches-baseline.tsv; --prune lowers stale rows onlycheck-core-world-reads.ts scanner yes GBRA-248 W1 embeddable-core ratchet (TS AST): per-file counts in src/core of loadConfig calls, process.env/Bun.env, fs imports, module-level mutable collections, spawn-wrapper/child_process imports, process-wide hooks and AsyncLocalStorage stores; rises and stale rows fail; baseline scripts/core-world-reads-baseline.tsv; --prune lowers stale rows onlycheck-page-body-readers.ts scanner yes Wave B segmented storage (spec 1.5 layer 4, TS AST): src units reading .compiled_truth/.timeline, SQL literals naming the body columns or p.* from pages, and whole-body calls (serializePageToMarkdown, putPage, ...) need a baseline row with an action code; stale/duplicate/malformed rows fail; boundedBodyPrefixSql allowed by name; baseline scripts/page-body-readers-baseline.tsv; --prune drops stale rows onlycheck-engine-sql-dynamic.ts scanner yes CQ3/EO17 dynamic SQL in src/core/engine-sql/** (TS AST; fragment.ts exempt as the renderer): trustedSql args and composed .query/.unsafe/.executeRaw/executeRawJsonb SQL splice only literals, as-const/allowlisted constants, VETTED_BUILDERS calls or Number.isFinite-checked numbers; no $<digit> in composed strings; no expanded IN listsdiff --git a/scripts/lib/count-ratchet.ts b/scripts/lib/count-ratchet.tsnew file mode 100644index 0000000000..09d3afc0ee--- /dev/null+++ b/scripts/lib/count-ratchet.ts@@ -0,0 +1,150 @@+/**+ * Shared runner for per-file count ratchets (D6 of docs/designs/RUST_ENGINE.md):+ * scripts/check-engine-raw-sql-ratchet.ts and scripts/check-engine-kind-branches.ts.+ *+ * A guard supplies a scanner that returns `path<TAB>metric -> count` for the+ * tree. The baseline holds rows `path<TAB>metric<TAB>count[<TAB>note]`. Counts+ * fall by default:+ * 1. a count above its row (no row = 0) -> FAIL+ * 2. a count below its row (stale) -> FAIL+ * 3. a duplicate or malformed row -> FAIL+ * A row goes up only by a reviewer-visible edit in the same PR that raises the+ * count and writes the reason in the note column (as+ * scripts/module-size-limits.tsv does). `--prune` lowers stale rows to the+ * actual count, keeps their notes and drops rows at zero; it never raises a row+ * or adds one. `--print` writes the current counts as rows to stdout (used to+ * generate a baseline from the tree at its commit).+ */+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';+import { join } from 'node:path';++export interface CountRatchet {+ /** Guard name used in output, e.g. `check-engine-raw-sql-ratchet`. */+ name: string;+ /** Script path for fix hints, e.g. `scripts/check-engine-raw-sql-ratchet.ts`. */+ script: string;+ baselineRel: string;+ anchor: string;+ metrics: readonly string[];+ /** One line: why the counts only fall. */+ why: string;+ /** What to do instead of adding a new site. */+ riseFix: string;+ scan(root: string): Map<string, number>;+}++export function tsFiles(dir: string): string[] {+ if (!existsSync(dir)) return [];+ const out: string[] = [];+ for (const entry of readdirSync(dir).sort()) {+ const full = join(dir, entry);+ if (statSync(full).isDirectory()) out.push(...tsFiles(full));+ else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) out.push(full);+ }+ return out;+}++interface Row { lineNo: number; key: string; count: number; note: string | undefined; malformed: string | null }++function parseBaseline(text: string, metrics: readonly string[]): Row[] {+ const rows: Row[] = [];+ text.split('\n').forEach((raw, i) => {+ if (raw.trim() === '' || raw.startsWith('#')) return;+ const cols = raw.split('\t');+ const [path, metric, count, note] = cols;+ let malformed: string | null = null;+ if (cols.length < 3 || cols.length > 4 || !path) malformed = "want 'path<TAB>metric<TAB>count' with an optional '<TAB>note'";+ else if (cols.length === 4 && note.trim() === '') malformed = 'the note column is empty (drop it, or say why the row was raised)';+ else if (!metrics.includes(metric)) malformed = 'unknown metric ' + JSON.stringify(metric) + ' (one of ' + metrics.join(', ') + ')';+ else if (!/^[1-9]\d*$/.test(count)) malformed = 'count must be a positive integer';+ rows.push({ lineNo: i + 1, key: path + '\t' + metric, count: Number(count), note, malformed });+ });+ return rows;+}++export function totals(actual: Map<string, number>, metrics: readonly string[]): { byMetric: Record<string, number>; all: number; files: number } {+ const byMetric = Object.fromEntries(metrics.map((m) => [m, 0])) as Record<string, number>;+ const files = new Set<string>();+ let all = 0;+ for (const [key, n] of actual) {+ const [path, metric] = key.split('\t');+ byMetric[metric] += n;+ all += n;+ files.add(path);+ }+ return { byMetric, all, files: files.size };+}++const RAISE_HINT = '\n If the site must stay until its area is converted: raise the row (or add it) in this PR with a note column saying why.';++export function runCountRatchet(guard: CountRatchet, root: string, argv: string[]): never {+ const actual = guard.scan(root);+ if (argv.includes('--print')) {+ const keys = [...actual.keys()].sort();+ for (const key of keys) console.log(key + '\t' + actual.get(key));+ process.exit(0);+ }+ const prune = argv.includes('--prune');+ const baselinePath = join(root, guard.baselineRel);+ if (!existsSync(baselinePath)) {+ console.error('FAIL: ' + guard.baselineRel + ':1 baseline file missing');+ console.error('Fix: git checkout ' + guard.baselineRel);+ console.error('See: ' + guard.anchor);+ process.exit(1);+ }+ const baselineText = readFileSync(baselinePath, 'utf8');+ const rows = parseBaseline(baselineText, guard.metrics);+ const violations: string[] = [];+ const rewrite = new Map<number, string | null>();+ const seen = new Set<string>();+ const pruneHint = '(or: bun ' + guard.script + ' --prune)';++ for (const row of rows) {+ const where = guard.baselineRel + ':' + row.lineNo;+ if (row.malformed) {+ violations.push('FAIL: ' + where + ' malformed row: ' + row.malformed);+ continue;+ }+ const [path, metric] = row.key.split('\t');+ if (seen.has(row.key)) {+ rewrite.set(row.lineNo, null);+ violations.push('FAIL: ' + where + ' duplicate row for ' + path + ' ' + metric + '\n Fix: delete this line ' + pruneHint);+ continue;+ }+ seen.add(row.key);+ const now = actual.get(row.key) ?? 0;+ if (now > row.count) {+ violations.push('FAIL: ' + path + ' ' + metric + ': baseline ' + row.count + ', actual ' + now + '\n Fix: ' + guard.riseFix + RAISE_HINT);+ } else if (now < row.count) {+ rewrite.set(row.lineNo, now === 0 ? null : [path, metric, String(now), ...(row.note === undefined ? [] : [row.note])].join('\t'));+ violations.push('FAIL: ' + where + ' stale row: ' + path + ' ' + metric + ': baseline ' + row.count + ', actual ' + now+ + '\n Fix: lower the row to ' + now + (now === 0 ? ' (delete it)' : '') + '; counts only fall ' + pruneHint);+ }+ }+ for (const [key, now] of actual) {+ if (seen.has(key)) continue;+ const [path, metric] = key.split('\t');+ violations.push('FAIL: ' + path + ' ' + metric + ': baseline 0, actual ' + now + '\n Fix: ' + guard.riseFix + RAISE_HINT);+ }++ if (prune) {+ const kept: string[] = [];+ baselineText.split('\n').forEach((line, i) => {+ if (!rewrite.has(i + 1)) kept.push(line);+ else if (rewrite.get(i + 1) !== null) kept.push(rewrite.get(i + 1)!);+ });+ writeFileSync(baselinePath, kept.join('\n'));+ console.log(guard.name + ': pruned ' + rewrite.size + ' row(s) in ' + guard.baselineRel);+ process.exit(0);+ }+ if (violations.length) {+ for (const v of violations) console.error(v);+ console.error('Why: ' + guard.why);+ console.error('See: ' + guard.anchor);+ console.error(guard.name + ': ' + violations.length + ' violation(s)');+ process.exit(1);+ }+ const t = totals(actual, guard.metrics);+ console.log(guard.name + ': ok (' + t.all + ' sites in ' + t.files + ' files: ' + guard.metrics.map((m) => m + ' ' + t.byMetric[m]).join(', ') + ')');+ process.exit(0);+}diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsvindex 1ad145049b..e37a997332 100644--- a/scripts/module-size-limits.tsv+++ b/scripts/module-size-limits.tsv@@ -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 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/engine.ts 2900 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); +6 W6 engine parity: typed sealChunks member and its doc (a test arm seals chunks without executeRaw; SQL in engine-sql/chunks.ts; interface members cannot move); +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 #9641 merge with #9631's head 56a9547a (2900 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 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/postgres-engine.ts 3193 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); +3 W6 engine parity: typed sealChunks delegate (SQL in engine-sql/chunks.ts) and disconnect runs the shutdown hooks once, as PGLite does (engine methods cannot move); +2 Rust engine plan PR 5: capabilities field and its import (table in engine-capabilities.ts; class fields cannot move); re-summed at the #9641 merge with #9631's head 56a9547a (3193 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/page-body-readers-baseline.tsv b/scripts/page-body-readers-baseline.tsvindex bf6c6ec16d..9db65c4121 100644--- a/scripts/page-body-readers-baseline.tsv+++ b/scripts/page-body-readers-baseline.tsv@@ -418,12 +418,12 @@ src/core/page-state/projection-schema.ts PAGE_SEARCH_VECTOR_TRIGGER_SQL sql STREsrc/core/page-state/projections.ts preparePageProjection call:prepareMarkdownChunks STREAMsrc/core/page-state/projections.ts readGuardedProjectionSnapshot field STREAMsrc/core/page-state/projections.ts sealImportedPage field STREAM-src/core/page-state/projections.ts sealPageTextProjection field STREAMsrc/core/page-state/schema.ts PAGE_STATE_SCHEMA_STATEMENTS sql STREAM revision trigger tuple (lane 1a adds body_generation)src/core/page-state/snapshot.ts overlayCanonicalBodies field STREAM overlays a caller-supplied body string (file bytes), not a stored segmented bodysrc/core/page-state/snapshot.ts overlayCanonicalBodies sql STREAM normalizes the caller-supplied bodysrc/core/page-state/snapshot.ts readSnapshotStatement field STREAM withdrawal overlay runs on inline pages only; segmented page skips it (per-window overlay in PR 2)src/core/page-state/snapshot.ts readSnapshotStatement sql STREAM p.* feeds rowToPage (projects body_storage/body_bytes); the fingerprint over a NULL body is empty+src/core/page-state/text-seal.ts sealPageTextProjection field STREAM moved from projections.ts unchanged; BrainEngine.sealChunks reuses it after refusing a segmented pagesrc/core/page-state/versions.ts createPageVersion field SEGW lane 1e file: segmented versions reference a generationsrc/core/page-state/versions.ts createPageVersion sql SEGW lane 1e file: segmented versions reference a generationsrc/core/page-window/bounded-lead.ts overlaidBoundedPrefix field LEAD see overlaidBoundedRowsdiff --git a/scripts/run-verify-parallel.sh b/scripts/run-verify-parallel.shindex f978e9a6f8..d1fd688735 100755--- a/scripts/run-verify-parallel.sh+++ b/scripts/run-verify-parallel.sh@@ -206,6 +206,11 @@ CHECKS=(# Goal (a) (refactor wave 1): engine SQL only shrinks; baseline# scripts/engine-sql-baseline.tsv."check:engine-sql-ratchet"+ # D6 (docs/designs/RUST_ENGINE.md): raw SQL outside the engines and two-way+ # pglite/postgres branches only fall; baselines scripts/engine-raw-sql-baseline.tsv+ # and scripts/engine-kind-branches-baseline.tsv.+ "check:engine-raw-sql-ratchet"+ "check:engine-kind-branches"# GBRA-248 W1: world reads in src/core (loadConfig, env, fs, module state,# spawn, process hooks) only fall; baseline scripts/core-world-reads-baseline.tsv."check:core-world-reads"diff --git a/scripts/structural-suites.tsv b/scripts/structural-suites.tsvindex 7de0cc4f0d..3718d8dd48 100644--- a/scripts/structural-suites.tsv+++ b/scripts/structural-suites.tsv@@ -345,6 +345,7 @@ test/scripts/e2e-runner.test.ts second 5 readFileSynctest/scripts/e2e-runner.test.ts sequential E2E runner (GITHUB_ACTIONS=${githubActions}) 9 readFileSynctest/scripts/e2e-shard-budget.test.ts E2E shard-time budget 3 readFileSynctest/scripts/e2e-wiring.test.ts (file-level) 14 readFileSync+test/scripts/engine-raw-sql-ratchet.test.ts check-engine-raw-sql-ratchet.ts: shrink-only baseline 11 readFileSynctest/scripts/fix-wave-gate.test.ts fix-wave gate workflow 3 readFileSynctest/scripts/full-ci-workflow.test.ts full CI on pull requests 7 readFileSynctest/scripts/full-ci-workflow.test.ts master-push reuse of a passed full-suite run 2 readFileSyncdiff --git a/src/core/engine-sql/chunks.ts b/src/core/engine-sql/chunks.tsindex ee1f00f4fb..fd0fc7b5b6 100644--- a/src/core/engine-sql/chunks.ts+++ b/src/core/engine-sql/chunks.ts@@ -46,6 +46,7 @@ import type { LegacyUnscopedRead, ScopedRead } from './brands.ts';import { joinFragments, renderFragment, sqlFragment, trustedSql, type SqlFragment } from './fragment.ts';import { pipelined } from '../page-state/transactions.ts';import { compileRowNormalizer } from './normalize.ts';+import { sealPageTextProjection } from '../page-state/text-seal.ts';/** The engine's page-state guards, run on the same (transaction) engine. */export interface ChunkPageGuards {@@ -1045,6 +1046,35 @@ export async function listEmbeddingStateRows(exec: ScopedRead, column: string,return rows.map(row => normalizeStateRow(row));}+/** The transaction engine's own steps `sealChunks` runs (its page guard, chunk delete and sealing chunk insert). */+export interface ChunkSealSteps extends ChunkPageGuards, Pick<BrainEngine, 'executeRaw'> {+ deleteChunks(slug: string, opts: { sourceId: string }): Promise<void>;+ upsertChunks(slug: string, chunks: ChunkInput[], opts: { sourceId: string; sealChunkerVersion: number }): Promise<void>;+}++/**+ * BrainEngine.sealChunks, run inside the caller's page transaction: replace a page's chunks and seal its text+ * projection at its current revision, the projection write `installPageProjection` makes with `seal: true`+ * (page-state/projections.ts) without its embedding-context conflict checks. It refuses a missing or deleted page,+ * a page in an archived source, a segmented page (its projection is built from its segments) and a stale+ * `expectedRevision`. The text seal is `sealPageTextProjection` (page-state/text-seal.ts).+ */+export async function sealChunks(exec: SqlExecutor, steps: ChunkSealSteps, slug: string, chunks: ChunkInput[],+ opts?: { sourceId?: string; expectedRevision?: string }): Promise<void> {+ slug = validateSlug(slug);+ const sourceId = opts?.sourceId ?? 'default';+ await steps.lockPageKeys([{ sourceId, slug }]);+ const current = await steps.readPageSnapshot(slug, { sourceId, requireLiveSource: true });+ if (!current || current.page.deleted_at) throw new Error(`Page not found: ${slug} (source=${sourceId})`);+ if (current.page.body_storage === 'segmented') throw new Error(`sealChunks refuses segmented page ${slug} (source=${sourceId}): its projection is built from its segments`);+ if (opts?.expectedRevision !== undefined) assertPageRevision(current, { expectedRevision: opts.expectedRevision });+ await steps.deleteChunks(slug, { sourceId });+ await steps.upsertChunks(slug, chunks, { sourceId, sealChunkerVersion: SAFE_FENCE_CHUNKER_VERSION });+ await sealPageTextProjection(steps, slug, sourceId, current);+ await exec.run(sqlFragment`DELETE FROM page_projection_jobs+ WHERE source_incarnation = ${current.sourceIncarnation}::uuid AND slug = ${slug} AND revision = ${current.revision}::uuid`);+}+export async function deleteChunks(exec: SqlExecutor, slug: string, opts?: { sourceId?: string }): Promise<void> {const sourceId = opts?.sourceId ?? 'default';// Source-qualify the page-id subquery; slugs are only unique per source.diff --git a/src/core/engine.ts b/src/core/engine.tsindex a9aa5b1b23..e194bec32f 100644--- a/src/core/engine.ts+++ b/src/core/engine.ts@@ -1271,6 +1271,12 @@ export interface BrainEngine {* insert are sent together and the seal's page is checked against it (`deferSeal`: by the caller, sealImportedPage).*/upsertChunks(slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; embeddingColumn?: ResolvedColumn; expectedRevision?: string; sealChunkerVersion?: number; pageId?: number; deferSeal?: true } & BatchOpts): Promise<void>;+ /**+ * Replace a page's chunks and seal its text projection at its current revision in one transaction, so search and+ * `getChunks` serve them (upsertChunks alone leaves the projection unsealed). Refuses a missing, deleted or+ * segmented page, an archived source and a stale `expectedRevision` (SQL in engine-sql/chunks.ts).+ */+ sealChunks(slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; expectedRevision?: string }): Promise<void>;/*** Read every chunk for a page. Scope precedence mirrors getPage (#2555):* a federated grant (`sourceIds[]`) wins over scalar `sourceId`; withdiff --git a/src/core/page-state/projections.ts b/src/core/page-state/projections.tsindex 88eedfa10e..3f94e99588 100644--- a/src/core/page-state/projections.ts+++ b/src/core/page-state/projections.ts@@ -30,19 +30,8 @@ import { chunkModelMatchesSql } from '../embedding-invalidation.ts';import { isRetryableConnError } from '../retry-matcher.ts';import { ACTIVATION_SERVED_REVISION } from '../search/safe-chunks.ts';-/**- * Complete the searchable snapshot only after its sanitized chunks are installed.- * `guarded` is this transaction's own read of the page under its guard, when- * the caller has one and has not changed the page's revision or timeline since.- */-export async function sealPageTextProjection(engine: BrainEngine, slug: string, sourceId: string, guarded?: PageSnapshot): Promise<void> {- const current = guarded ?? await engine.readPageSnapshot(slug, { sourceId });- if (!current) return;- await engine.executeRaw(`UPDATE pages SET text_projection_revision=knowledge_revision,- search_vector=${pageSearchVectorSql('title', '$3')}- WHERE source_id=$1 AND slug=$2 AND knowledge_revision=$4::uuid`,- [sourceId, slug, sanitizeRemoteBody(current.page.timeline), current.revision]);-}+export { sealPageTextProjection } from './text-seal.ts';+import { sealPageTextProjection } from './text-seal.ts';/*** A coordinated import's one closing page write: the chunker version its applydiff --git a/src/core/page-state/text-seal.ts b/src/core/page-state/text-seal.tsnew file mode 100644index 0000000000..936f6cedf1--- /dev/null+++ b/src/core/page-state/text-seal.ts@@ -0,0 +1,23 @@+/**+ * The page text seal, kept apart from projections.ts so the engine-sql chunk+ * code can run it without loading the projection pipeline's provider closure.+ */+import type { BrainEngine } from '../engine.ts';+import type { PageSnapshot } from './types.ts';+import { sanitizeRemoteBody } from '../remote-body.ts';+import { pageSearchVectorSql } from '../fts-language.ts';++/**+ * Complete the searchable snapshot only after its sanitized chunks are installed.+ * `guarded` is this transaction's own read of the page under its guard, when+ * the caller has one and has not changed the page's revision or timeline since.+ */+export async function sealPageTextProjection(engine: Pick<BrainEngine, 'executeRaw' | 'readPageSnapshot'>, slug: string, sourceId: string,+ guarded?: PageSnapshot): Promise<void> {+ const current = guarded ?? await engine.readPageSnapshot(slug, { sourceId });+ if (!current) return;+ await engine.executeRaw(`UPDATE pages SET text_projection_revision=knowledge_revision,+ search_vector=${pageSearchVectorSql('title', '$3')}+ WHERE source_id=$1 AND slug=$2 AND knowledge_revision=$4::uuid`,+ [sourceId, slug, sanitizeRemoteBody(current.page.timeline), current.revision]);+}diff --git a/src/core/pglite-engine.ts b/src/core/pglite-engine.tsindex e9f68a42cc..5e6305e563 100644--- a/src/core/pglite-engine.ts+++ b/src/core/pglite-engine.ts@@ -1903,6 +1903,10 @@ export class PGLiteEngine implements BrainEngine {return chunksImpl.listEmbeddingStateRows(scopedRead(this.engineSql), column, opts);}+ async sealChunks(slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; expectedRevision?: string }): Promise<void> {+ await this.transaction(tx => { const e = tx as PGLiteEngine; return chunksImpl.sealChunks(e.engineSql, e, slug, chunks, opts); });+ }+async deleteChunks(slug: string, opts?: { sourceId?: string }): Promise<void> {return chunksImpl.deleteChunks(this.engineSql, slug, opts);}diff --git a/src/core/postgres-engine.ts b/src/core/postgres-engine.tsindex 1f3be53e09..5560869b33 100644--- a/src/core/postgres-engine.ts+++ b/src/core/postgres-engine.ts@@ -1722,6 +1722,10 @@ export class PostgresEngine implements BrainEngine {return this.withScopedReadTransaction(opts.sourceIds, undefined, tx => chunksImpl.listEmbeddingStateRows(scopedRead(this.engineSqlOn(tx)), column, opts));}+ async sealChunks(slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; expectedRevision?: string }): Promise<void> {+ await this.transaction(tx => { const e = tx as PostgresEngine; return chunksImpl.sealChunks(e.engineSql, e, slug, chunks, opts); });+ }+async deleteChunks(slug: string, opts?: { sourceId?: string }): Promise<void> {return chunksImpl.deleteChunks(this.engineSql, slug, opts);}diff --git a/src/core/rust-engine/members.ts b/src/core/rust-engine/members.tsindex 4dd9f23885..dab6a95771 100644--- a/src/core/rust-engine/members.ts+++ b/src/core/rust-engine/members.ts@@ -105,6 +105,7 @@ export const RUST_ENGINE_MEMBERS = {getTags: 'tags',// chunksupsertChunks: 'chunks',+ sealChunks: 'chunks',getChunks: 'chunks',getChunkPage: 'chunks',getChunkWindows: 'chunks',diff --git a/test/engine-parity/arm-capabilities.ts b/test/engine-parity/arm-capabilities.tsnew file mode 100644index 0000000000..2ce4be9fad--- /dev/null+++ b/test/engine-parity/arm-capabilities.ts@@ -0,0 +1,77 @@+/**+ * Which engine capabilities each parity arm has, and what a parity case that+ * needs a missing capability expects on that arm.+ *+ * Pure data: no engine and no `bun:test` import, so `coverage.ts` (a plain+ * script) and `harness.ts` share one table. The arm list includes `rust`+ * before the Rust arm exists, so the coverage list can already say what the+ * Rust arm must do for every method.+ *+ * Two kinds of missing capability (RUST_ENGINE.md, D18):+ * - `refuses`: the arm must throw `engine_capability_missing` naming the+ * capability. The Rust engine has no SQL dialect, so every raw-SQL entry+ * point refuses with reason `raw_sql`.+ * - `n/a`: the arm has no such member at all and the case does not run there.+ * `holdSchemaMigrationLock` is an optional member only Postgres implements;+ * PGLite (and Rust) serialize schema migrations in-process instead+ * (src/core/schema-migration-lock.ts).+ *+ * When `BrainEngine.capabilities` and `src/core/engine-capabilities.ts` land+ * (plan PR 5), `armCapabilities` reads the engine's own set instead of this+ * table, and the parity cases keep their `requires` declarations.+ */++/** Every engine arm a parity case can run on, present or planned. */+export const PARITY_ARMS = ['pglite', 'postgres', 'rust'] as const;+export type ParityArmName = typeof PARITY_ARMS[number];++/** Capabilities a parity case can require (a subset of the planned engine capability set). */+export type EngineCapability = 'raw_sql' | 'schema_migration_lock';++export interface MissingCapability {+ /** `refuses`: the arm throws `engine_capability_missing`; `n/a`: the case does not run on the arm. */+ kind: 'refuses' | 'n/a';+ /** The coverage-list cell for an arm without the capability. */+ label: string;+}++export function missingCapability(capability: EngineCapability): MissingCapability {+ switch (capability) {+ case 'raw_sql': return { kind: 'refuses', label: 'refuses:raw_sql' };+ case 'schema_migration_lock': return { kind: 'n/a', label: 'n/a:postgres-only' };+ default: return assertNever(capability);+ }+}++export function armCapabilities(arm: ParityArmName): ReadonlySet<EngineCapability> {+ switch (arm) {+ case 'pglite': return new Set<EngineCapability>(['raw_sql']);+ case 'postgres': return new Set<EngineCapability>(['raw_sql', 'schema_migration_lock']);+ case 'rust': return new Set<EngineCapability>();+ default: return assertNever(arm);+ }+}++export function armHas(arm: ParityArmName, capability: EngineCapability | undefined): boolean {+ return capability === undefined || armCapabilities(arm).has(capability);+}++/**+ * True when `error` is the typed refusal for `capability`: code+ * `engine_capability_missing` and that capability as its reason. The code and+ * reason may sit on the error, its `detail`, or a structured `envelope`+ * (src/core/errors.ts), because the Rust error class is not written yet.+ */+export function isCapabilityRefusal(error: unknown, capability: EngineCapability): boolean {+ if (typeof error !== 'object' || error === null) return false;+ const holders = [error, (error as { detail?: unknown }).detail, (error as { envelope?: unknown }).envelope,+ ((error as { envelope?: { detail?: unknown } }).envelope)?.detail]+ .filter((h): h is Record<string, unknown> => typeof h === 'object' && h !== null);+ const code = holders.some((h) => h.code === 'engine_capability_missing');+ const reason = holders.some((h) => h.reason === capability || h.capability === capability);+ return code && reason;+}++function assertNever(value: never): never {+ throw new Error(`engine-parity: unhandled value ${String(value)}`);+}diff --git a/test/engine-parity/chunk-fixtures.ts b/test/engine-parity/chunk-fixtures.tsnew file mode 100644index 0000000000..a998793d92--- /dev/null+++ b/test/engine-parity/chunk-fixtures.ts@@ -0,0 +1,32 @@+/**+ * Shared seeding for the chunks / search / extraction parity files.+ *+ * `putPage` + `upsertChunks` leave a page's text projection UNSEALED, and+ * search (and `getChunks` by default) only serves sealed pages. `installChunks`+ * seals through the typed `BrainEngine.sealChunks`, so every arm (a Rust arm+ * too) seeds through its own engine method and no case reaches `executeRaw`.+ */+import type { BrainEngine } from '../../src/core/engine.ts';+import type { ChunkInput, PageInput } from '../../src/core/types.ts';++export interface SeedPage {+ slug: string;+ input: PageInput;+ chunks?: ChunkInput[];+}++/** Write a page and install its chunks as a sealed (searchable) projection. */+export async function seedPage(engine: BrainEngine, page: SeedPage, opts?: { sourceId?: string }): Promise<void> {+ await engine.putPage(page.slug, page.input, opts);+ if (page.chunks) await installChunks(engine, page.slug, page.chunks, opts);+}++/** Replace a page's chunks with a sealed projection. */+export async function installChunks(engine: BrainEngine, slug: string, chunks: ChunkInput[], opts?: { sourceId?: string }): Promise<void> {+ await engine.sealChunks(slug, chunks, opts);+}++/** A compiled_truth chunk input. */+export function chunk(chunk_index: number, chunk_text: string, extra: Partial<ChunkInput> = {}): ChunkInput {+ return { chunk_index, chunk_text, chunk_source: 'compiled_truth', ...extra };+}diff --git a/test/engine-parity/chunks.test.ts b/test/engine-parity/chunks.test.tsnew file mode 100644index 0000000000..4a7f4f30b4--- /dev/null+++ b/test/engine-parity/chunks.test.ts@@ -0,0 +1,512 @@+/**+ * BrainEngine parity — chunks family (chunk storage, paging, stale/embedding+ * bookkeeping, signatures, chunkless-page healing, embedding state).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every chunk read/write/bookkeeping method returns the same+ * observable result on every engine arm (PGLite always; Postgres with+ * DATABASE_URL; a Rust arm later through test/engine-parity/harness.ts).+ * - Regression: an engine that drifts on chunk replacement, the stale-embedding+ * predicate, the model-swap signature sweeps or the chunkless-page safety net+ * (what `embed --stale` and `gbrain doctor` read) silently leaves pages+ * un-embedded or re-embeds a whole brain.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * without Postgres and covers search/graph; the per-engine chunk tests never+ * compare two engines on one scenario.+ * - Seam: none for the cases. Typed methods only (no executeRaw: D18); the+ * sealed-projection fixture goes through chunk-fixtures.ts (see its header).+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import type { Chunk, ChunkInput } from '../../src/core/types.ts';+import { basisEmbedding, createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';+import { chunk, installChunks, seedPage } from './chunk-fixtures.ts';++const { parityTest } = parityArms(testBackends());++const CHUNK_KEYS = ['chunk_index', 'chunk_text', 'chunk_source', 'token_count', 'embedded_at', 'embedding_is_null', 'modality', 'language', 'symbol_name', 'symbol_type'] as const;++function view(rows: Chunk[]) {+ return rows.map((c) => pick(c, CHUNK_KEYS));+}++/** Index of a unit vector's hot axis, or null (null vector / not a unit vector). */+function axis(v: Float32Array | null | undefined): number | null {+ if (!v) return null;+ let hot = -1;+ for (let i = 0; i < v.length; i++) {+ if (v[i] === 1) {+ if (hot !== -1) return null;+ hot = i;+ } else if (v[i] !== 0) return null;+ }+ return hot === -1 ? null : hot;+}++const PAGE = (title: string, body: string, timeline = '') => ({ type: 'note' as const, title, compiled_truth: body, timeline });++describe('engine parity: chunks', () => {+ parityTest(+ 'upsertChunks stores chunks that getChunks serves only once the projection is sealed',+ { methods: ['putPage', 'upsertChunks', 'getChunks'] },+ async (engine) => {+ await engine.putPage('notes/chunky', PAGE('Chunky', 'first body text. second body text.', '- 2026-01-01: a timeline line'));+ const inputs: ChunkInput[] = [+ chunk(0, 'first body text.', { embedding: basisEmbedding(5), token_count: 4 }),+ chunk(1, 'second body text.'),+ { chunk_index: 2, chunk_text: '- 2026-01-01: a timeline line', chunk_source: 'timeline' },+ { chunk_index: 3, chunk_text: 'function f() {}', chunk_source: 'fenced_code', language: 'typescript', symbol_name: 'f', symbol_type: 'function' },+ ];+ await engine.upsertChunks('notes/chunky', inputs);+ const hidden = await engine.getChunks('notes/chunky');+ expect(hidden).toEqual([]);+ const unsealed = view(await engine.getChunks('notes/chunky', { includeUnsealed: true }));+ expect(unsealed.map((c) => c.chunk_index)).toEqual([0, 1, 2, 3]);+ expect(unsealed[0]!.embedding_is_null).toBe(false);+ expect(unsealed[1]!.embedding_is_null).toBe(true);+ expect(unsealed[3]).toMatchObject({ chunk_source: 'fenced_code', language: 'typescript', symbol_name: 'f', symbol_type: 'function' });++ await installChunks(engine, 'notes/chunky', inputs);+ const sealed = view(await engine.getChunks('notes/chunky'));+ expect(sealed).toEqual(unsealed);+ const missing = await engine.getChunks('notes/nobody');+ expect(missing).toEqual([]);+ return { hidden, unsealed, sealed, missing };+ },+ );++ parityTest(+ 'sealChunks replaces and seals chunks at the current revision; it refuses a stale revision, a deleted page and an unknown page',+ { methods: ['putPage', 'readPageSnapshot', 'sealChunks', 'getChunks', 'searchKeyword', 'softDeletePage'] },+ async (engine) => {+ await engine.putPage('notes/sealed', PAGE('Sealed', 'a heliotrope paragraph. a second line.'));+ const first = await engine.readPageSnapshot('notes/sealed');+ await engine.sealChunks('notes/sealed', [chunk(0, 'a heliotrope paragraph.'), chunk(1, 'a second line.')], { expectedRevision: first!.revision });+ const sealed = view(await engine.getChunks('notes/sealed'));+ expect(sealed.map((c) => c.chunk_text)).toEqual(['a heliotrope paragraph.', 'a second line.']);+ const found = (await engine.searchKeyword('heliotrope', { limit: 5 })).map((r) => [r.slug, r.chunk_text]);+ expect(found).toEqual([['notes/sealed', 'a heliotrope paragraph.']]);++ await engine.putPage('notes/sealed', PAGE('Sealed', 'a marigold paragraph only.'));+ const refusal = async (run: () => Promise<void>) => {+ try { await run(); return 'sealed'; } catch (e) { return e instanceof Error && /changed after it was read|not found/i.test(e.message) ? 'refused' : String(e); }+ };+ const stale = await refusal(() => engine.sealChunks('notes/sealed', [chunk(0, 'stale text')], { expectedRevision: first!.revision }));+ const afterStale = view(await engine.getChunks('notes/sealed', { includeUnsealed: true })).map((c) => c.chunk_text);+ expect([stale, afterStale]).toEqual(['refused', ['a heliotrope paragraph.', 'a second line.']]);+ // The page edit unsealed the projection, so search serves nothing until the new chunks are sealed.+ const unsealedSearch = (await engine.searchKeyword('heliotrope', { limit: 5 })).map((r) => r.slug);+ await engine.sealChunks('notes/sealed', [chunk(0, 'a marigold paragraph only.')]);+ const resealed = (await engine.searchKeyword('marigold', { limit: 5 })).map((r) => [r.slug, r.chunk_text]);+ const oldText = (await engine.searchKeyword('heliotrope', { limit: 5 })).map((r) => r.slug);+ expect([resealed, oldText]).toEqual([[['notes/sealed', 'a marigold paragraph only.']], []]);++ const unknown = await refusal(() => engine.sealChunks('notes/nobody', [chunk(0, 'x')]));+ await engine.softDeletePage('notes/sealed');+ const deleted = await refusal(() => engine.sealChunks('notes/sealed', [chunk(0, 'x')]));+ expect([unknown, deleted]).toEqual(['refused', 'refused']);+ return { sealed, found, stale, afterStale, unsealedSearch, resealed, oldText, unknown, deleted };+ },+ );++ parityTest(+ 'sealChunks rolls back as one unit: a chunk write that fails after the old chunks were deleted leaves the old sealed set searchable',+ { methods: ['putPage', 'readPageSnapshot', 'sealChunks', 'getChunks', 'searchKeyword'] },+ async (engine) => {+ await engine.putPage('notes/rollback', PAGE('Rollback', 'a periwinkle paragraph. a second line.'));+ await engine.sealChunks('notes/rollback', [chunk(0, 'a periwinkle paragraph.'), chunk(1, 'a second line.')]);+ const before = view(await engine.getChunks('notes/rollback', { includeUnsealed: true }));+ const revision = (await engine.readPageSnapshot('notes/rollback'))!.revision;++ // sealChunks deletes the old chunks before it writes the new ones; an embedding of the wrong+ // width makes that write fail, so only the transaction can bring the old chunks back.+ let failed = false;+ try {+ await engine.sealChunks('notes/rollback', [chunk(0, 'a cerulean replacement.', { embedding: basisEmbedding(0, 8) })]);+ } catch {+ failed = true;+ }+ const after = view(await engine.getChunks('notes/rollback', { includeUnsealed: true }));+ const sealedAfter = view(await engine.getChunks('notes/rollback'));+ const found = (await engine.searchKeyword('periwinkle', { limit: 5 })).map((r) => [r.slug, r.chunk_text]);+ const leaked = (await engine.searchKeyword('cerulean', { limit: 5 })).map((r) => r.slug);+ const revisionAfter = (await engine.readPageSnapshot('notes/rollback'))!.revision;+ expect(failed).toBe(true);+ expect(after).toEqual(before);+ expect(sealedAfter).toEqual(before);+ expect(found).toEqual([['notes/rollback', 'a periwinkle paragraph.']]);+ expect(leaked).toEqual([]);+ expect(revisionAfter).toBe(revision);++ // The engine stays usable: a valid seal on the same page still lands.+ await engine.sealChunks('notes/rollback', [chunk(0, 'a cerulean replacement.')]);+ const replaced = (await engine.searchKeyword('cerulean', { limit: 5 })).map((r) => [r.slug, r.chunk_text]);+ expect(replaced).toEqual([['notes/rollback', 'a cerulean replacement.']]);+ return { before, after, sealedAfter, found, leaked, sameRevision: revisionAfter === revision, replaced };+ },+ );++ parityTest(+ 'upsertChunks replaces a page chunk set: edited text, new indexes, dropped tail',+ { methods: ['upsertChunks', 'getChunks', 'getChunkPage'] },+ async (engine) => {+ await seedPage(engine, {+ slug: 'notes/replace',+ input: PAGE('Replace', 'one two three'),+ chunks: [chunk(0, 'one', { embedding: basisEmbedding(1) }), chunk(1, 'two', { embedding: basisEmbedding(2) }), chunk(2, 'three', { embedding: basisEmbedding(3) })],+ });+ const before = view(await engine.getChunks('notes/replace'));+ expect(before.map((c) => c.chunk_text)).toEqual(['one', 'two', 'three']);++ // Same index, edited text, no vector: the stale vector must not survive on the edited chunk.+ await engine.upsertChunks('notes/replace', [chunk(0, 'one'), chunk(1, 'two EDITED')]);+ const after = await engine.getChunks('notes/replace', { includeUnsealed: true, includeEmbedding: true });+ const afterView = after.map((c) => ({ ...pick(c, ['chunk_index', 'chunk_text', 'embedding_is_null'] as const), axis: axis(c.embedding) }));+ const page = await engine.getChunkPage('notes/replace', { fromIndex: 0, limit: 10 });+ expect(afterView).toEqual([+ { chunk_index: 0, chunk_text: 'one', embedding_is_null: false, axis: 1 },+ { chunk_index: 1, chunk_text: 'two EDITED', embedding_is_null: true, axis: null },+ ]);+ expect([page.total_chunks, page.max_chunk_index]).toEqual([2, 1]);+ return { before, afterView, pageTotal: page.total_chunks, pageMax: page.max_chunk_index };+ },+ );++ parityTest(+ 'getChunks includeEmbedding returns stored vectors; getChunksWithEmbeddings reads the full rows',+ { methods: ['getChunks', 'getChunksWithEmbeddings'] },+ async (engine) => {+ await seedPage(engine, {+ slug: 'notes/vectors',+ input: PAGE('Vectors', 'alpha beta'),+ chunks: [chunk(0, 'alpha', { embedding: basisEmbedding(11) }), chunk(1, 'beta')],+ });+ const without = await engine.getChunks('notes/vectors');+ expect(without.every((c) => c.embedding === null)).toBe(true);+ const withVec = await engine.getChunks('notes/vectors', { includeEmbedding: true });+ expect(axis(withVec[0]!.embedding)).toBe(11);+ expect(withVec[1]!.embedding).toBeNull();+ const full = await engine.getChunksWithEmbeddings('notes/vectors');+ expect(axis(full[0]!.embedding)).toBe(11);+ const none = await engine.getChunksWithEmbeddings('notes/nobody');+ expect(none).toEqual([]);+ return {+ without: without.map((c) => c.embedding),+ withVec: withVec.map((c) => ({ chunk_index: c.chunk_index, axis: axis(c.embedding) })),+ full: full.map((c) => ({ chunk_index: c.chunk_index, chunk_text: c.chunk_text, axis: axis(c.embedding) })),+ none,+ };+ },+ );++ parityTest(+ 'getChunkPage pages by chunk_index range and reports total and max index',+ { methods: ['getChunkPage'] },+ async (engine) => {+ await seedPage(engine, {+ slug: 'notes/paged',+ input: PAGE('Paged', 'a b c d e'),+ chunks: ['a', 'b', 'c', 'd', 'e'].map((t, i) => chunk(i, `chunk ${t}`)),+ });+ const first = await engine.getChunkPage('notes/paged', { fromIndex: 0, limit: 2 });+ const second = await engine.getChunkPage('notes/paged', { fromIndex: 2, limit: 2 });+ const tail = await engine.getChunkPage('notes/paged', { fromIndex: 4, limit: 10 });+ const past = await engine.getChunkPage('notes/paged', { fromIndex: 50, limit: 10 });+ const absent = await engine.getChunkPage('notes/nobody', { fromIndex: 0, limit: 10 });+ const shape = (p: typeof first) => ({ texts: p.chunks.map((c) => c.chunk_text), total: p.total_chunks, max: p.max_chunk_index });+ expect(shape(first)).toEqual({ texts: ['chunk a', 'chunk b'], total: 5, max: 4 });+ expect(shape(tail)).toEqual({ texts: ['chunk e'], total: 5, max: 4 });+ expect(shape(absent)).toEqual({ texts: [], total: 0, max: null });+ return { first: shape(first), second: shape(second), tail: shape(tail), past: shape(past), absent: shape(absent) };+ },+ );++ parityTest(+ 'getChunkWindows reads requested chunk ranges for authorized sealed pages only',+ { methods: ['putPage', 'getChunkWindows', 'softDeletePage'] },+ async (engine) => {+ const alpha = await engine.putPage('notes/win-alpha', PAGE('Win alpha', 'a0 a1 a2 a3'));+ await installChunks(engine, 'notes/win-alpha', [0, 1, 2, 3].map((i) => chunk(i, `alpha chunk ${i}`)));+ const beta = await engine.putPage('notes/win-beta', PAGE('Win beta', 'b0 b1'));+ await installChunks(engine, 'notes/win-beta', [chunk(0, 'beta chunk 0'), { chunk_index: 1, chunk_text: '- beta timeline', chunk_source: 'timeline' }]);+ const gone = await engine.putPage('notes/win-gone', PAGE('Win gone', 'g0'));+ await installChunks(engine, 'notes/win-gone', [chunk(0, 'gone chunk 0')]);+ await engine.softDeletePage('notes/win-gone');++ const slugOf = new Map([[alpha.id, 'win-alpha'], [beta.id, 'win-beta'], [gone.id, 'win-gone']]);+ const view = (pages: Awaited<ReturnType<typeof engine.getChunkWindows>>) => sorted(+ pages.map((p) => ({+ slug: slugOf.get(p.page_id),+ sealed: p.sealed,+ max_chunk_index: p.max_chunk_index,+ row_limited: p.row_limited,+ compiled_truth: p.compiled_truth,+ chunks: p.chunks.map((c) => `${c.chunk_index}:${c.chunk_source}:${c.chunk_text}`),+ })),+ (p) => String(p.slug),+ );+ const requests = [+ { page_id: alpha.id, from_index: 1, to_index: 2, priority: 0 },+ { page_id: beta.id, from_index: 0, to_index: 5, priority: 1 },+ { page_id: gone.id, from_index: 0, to_index: 5, priority: 2 },+ ];+ const all = view(await engine.getChunkWindows(requests, { chunkSources: ['compiled_truth', 'timeline'], maxRows: 50 }));+ expect(all.map((p) => p.slug)).toEqual(['win-alpha', 'win-beta']);+ expect(all[0]!.chunks).toEqual(['1:compiled_truth:alpha chunk 1', '2:compiled_truth:alpha chunk 2']);+ const lowDetail = view(await engine.getChunkWindows(requests, { chunkSources: ['compiled_truth'], maxRows: 50 }));+ expect(lowDetail[1]!.chunks).toEqual(['0:compiled_truth:beta chunk 0']);+ const capped = view(await engine.getChunkWindows(requests, { chunkSources: ['compiled_truth', 'timeline'], maxRows: 2 }));+ expect(capped.some((p) => p.row_limited)).toBe(true);+ const empty = await engine.getChunkWindows([], { chunkSources: ['compiled_truth'], maxRows: 10 });+ expect(empty).toEqual([]);+ return { all, lowDetail, capped, empty };+ },+ );++ parityTest(+ 'countStaleChunks, sumStaleChunkChars and listStaleChunks agree on which chunks lack a vector',+ { methods: ['countStaleChunks', 'sumStaleChunkChars', 'listStaleChunks'] },+ async (engine) => {+ await seedPage(engine, {+ slug: 'notes/stale-a',+ input: PAGE('Stale A', 'x'),+ chunks: [chunk(0, 'aaaa', { embedding: basisEmbedding(1) }), chunk(1, 'bbbbbb'), chunk(2, 'cc')],+ });+ await seedPage(engine, {+ slug: 'notes/stale-b',+ input: PAGE('Stale B', 'x'),+ chunks: [chunk(0, 'dddddddd'), chunk(1, 'eeeeeeeeee', { embedding: basisEmbedding(2) })],+ });+ await seedPage(engine, { slug: 'notes/fully-embedded', input: PAGE('Fully embedded', 'x'), chunks: [chunk(0, 'ffff', { embedding: basisEmbedding(3) })] });++ const count = await engine.countStaleChunks();+ const chars = await engine.sumStaleChunkChars();+ const rows = await engine.listStaleChunks();+ const rowView = rows.map((r) => ({ slug: r.slug, chunk_index: r.chunk_index, chunk_text: r.chunk_text, source_id: r.source_id }));+ expect(count).toBe(3);+ expect(chars).toBe('bbbbbb'.length + 'cc'.length + 'dddddddd'.length);+ expect(sorted(rowView, (r) => `${r.slug}/${r.chunk_index}`).map((r) => `${r.slug}/${r.chunk_index}`)).toEqual(['notes/stale-a/1', 'notes/stale-a/2', 'notes/stale-b/0']);++ // Keyset paging walks the same rows in (page_id, chunk_index) order, one at a time.+ const walked: string[] = [];+ let cursor: { afterPageId?: number; afterChunkIndex?: number } = {};+ for (let guard = 0; guard < 10; guard++) {+ const batch = await engine.listStaleChunks({ batchSize: 1, ...cursor });+ if (batch.length === 0) break;+ walked.push(`${batch[0]!.slug}/${batch[0]!.chunk_index}`);+ cursor = { afterPageId: batch[0]!.page_id, afterChunkIndex: batch[0]!.chunk_index };+ }+ expect(walked).toEqual(['notes/stale-a/1', 'notes/stale-a/2', 'notes/stale-b/0']);++ const scopedMiss = await engine.countStaleChunks({ sourceId: 'no-such-source' });+ const scopedHit = await engine.countStaleChunks({ sourceId: 'default' });+ const scopedChars = await engine.sumStaleChunkChars({ sourceId: 'no-such-source' });+ expect([scopedMiss, scopedHit, scopedChars]).toEqual([0, 3, 0]);+ return { count, chars, walked, scopedMiss, scopedHit, scopedChars };+ },+ );++ parityTest(+ 'setPageEmbeddingSignature drives signature-aware stale counts and invalidateStaleSignatureEmbeddings',+ { methods: ['setPageEmbeddingSignature', 'countStaleChunks', 'sumStaleChunkChars', 'invalidateStaleSignatureEmbeddings', 'getChunks'] },+ async (engine) => {+ const NEW = 'model-new:1536';+ const embedded = (text: string, axisIdx: number) => [chunk(0, text, { embedding: basisEmbedding(axisIdx) })];+ await seedPage(engine, { slug: 'notes/sig-current', input: PAGE('Sig current', 'x'), chunks: embedded('current', 1) });+ await seedPage(engine, { slug: 'notes/sig-old', input: PAGE('Sig old', 'x'), chunks: embedded('oldmodel', 2) });+ await seedPage(engine, { slug: 'notes/sig-null', input: PAGE('Sig null', 'x'), chunks: embedded('nullsig', 3) });+ await seedPage(engine, { slug: 'notes/sig-pending', input: PAGE('Sig pending', 'x'), chunks: [chunk(0, 'pending')] });+ await engine.setPageEmbeddingSignature('notes/sig-current', { signature: NEW });+ await engine.setPageEmbeddingSignature('notes/sig-old', { signature: 'model-old:768' });+ await engine.setPageEmbeddingSignature('notes/sig-pending', { signature: NEW });+ // No-op for a page that does not exist.+ await engine.setPageEmbeddingSignature('notes/nobody', { signature: NEW });++ const plain = await engine.countStaleChunks();+ const drift = await engine.countStaleChunks({ signature: NEW });+ const driftWithNull = await engine.countStaleChunks({ signature: NEW, includeNullSignature: true });+ const driftChars = await engine.sumStaleChunkChars({ signature: NEW });+ const driftCharsWithNull = await engine.sumStaleChunkChars({ signature: NEW, includeNullSignature: true });+ // plain: only the unembedded chunk. drift: + the old-model page. NULL signature is grandfathered unless asked for.+ expect({ plain, drift, driftWithNull }).toEqual({ plain: 1, drift: 2, driftWithNull: 3 });+ expect({ driftChars, driftCharsWithNull }).toEqual({ driftChars: 'pending'.length + 'oldmodel'.length, driftCharsWithNull: 'pending'.length + 'oldmodel'.length + 'nullsig'.length });++ const scopedMiss = await engine.invalidateStaleSignatureEmbeddings({ signature: NEW, sourceId: 'no-such-source' });+ const invalidated = await engine.invalidateStaleSignatureEmbeddings({ signature: NEW });+ const again = await engine.invalidateStaleSignatureEmbeddings({ signature: NEW });+ const afterDrift = await engine.countStaleChunks({ signature: NEW });+ const invalidatedNull = await engine.invalidateStaleSignatureEmbeddings({ signature: NEW, includeNullSignature: true });+ const afterNull = await engine.countStaleChunks({ signature: NEW, includeNullSignature: true });+ expect({ scopedMiss, invalidated, again, afterDrift, invalidatedNull, afterNull }).toEqual({ scopedMiss: 0, invalidated: 1, again: 0, afterDrift: 2, invalidatedNull: 1, afterNull: 3 });++ const state = async (slug: string) => view(await engine.getChunks(slug)).map((c) => ({ embedding_is_null: c.embedding_is_null, embedded_at: c.embedded_at }));+ const states = {+ current: await state('notes/sig-current'),+ old: await state('notes/sig-old'),+ nullsig: await state('notes/sig-null'),+ };+ expect(states.current[0]!.embedding_is_null).toBe(false);+ expect(states.old).toEqual([{ embedding_is_null: true, embedded_at: null }]);+ expect(states.nullsig).toEqual([{ embedding_is_null: true, embedded_at: null }]);+ return { plain, drift, driftWithNull, driftChars, driftCharsWithNull, scopedMiss, invalidated, again, afterDrift, invalidatedNull, afterNull, states };+ },+ );++ parityTest(+ 'invalidateContentDriftEmbeddings leaves vectors whose text still matches their embed-time hash',+ { methods: ['invalidateContentDriftEmbeddings', 'countStaleChunks', 'upsertChunks'] },+ async (engine) => {+ await seedPage(engine, { slug: 'notes/drift', input: PAGE('Drift', 'x'), chunks: [chunk(0, 'steady text', { embedding: basisEmbedding(4) }), chunk(1, 'no vector yet')] });+ // Rewriting a chunk through upsertChunks re-stamps its hash (or clears its vector), so typed writes never drift.+ await engine.upsertChunks('notes/drift', [chunk(0, 'steady text', { embedding: basisEmbedding(4) }), chunk(1, 'rewritten', { embedding: basisEmbedding(6) })]);+ const before = await engine.countStaleChunks();+ const swept = await engine.invalidateContentDriftEmbeddings();+ const sweptScoped = await engine.invalidateContentDriftEmbeddings({ sourceId: 'default' });+ const after = await engine.countStaleChunks();+ expect({ before, swept, sweptScoped, after }).toEqual({ before: 0, swept: 0, sweptScoped: 0, after: 0 });+ return { before, swept, sweptScoped, after };+ },+ );++ parityTest(+ 'countChunklessPagesWithContent and listChunklessPagesWithContent find pages that were never chunked',+ { methods: ['putPage', 'countChunklessPagesWithContent', 'listChunklessPagesWithContent', 'softDeletePage'] },+ async (engine) => {+ const withBody = await engine.putPage('notes/never-chunked', PAGE('Never chunked', 'has body text'));+ const timelineOnly = await engine.putPage('notes/timeline-only', PAGE('Timeline only', '', '- 2026-02-02: only a timeline'));+ const skipped = await engine.putPage('notes/embed-skipped', { ...PAGE('Embed skipped', 'big body'), frontmatter: { embed_skip: { reason: 'oversize', bytes: 10 } } });+ await engine.putPage('notes/empty-body', PAGE('Empty body', ''));+ await seedPage(engine, { slug: 'notes/chunked', input: PAGE('Chunked', 'chunked body'), chunks: [chunk(0, 'chunked body')] });+ await engine.putPage('notes/deleted-chunkless', PAGE('Deleted chunkless', 'deleted body'));+ await engine.softDeletePage('notes/deleted-chunkless');+ await engine.putPage('notes/quarantined', { ...PAGE('Quarantined', 'quarantined body'), frontmatter: { quarantine: { reason: 'test' } } });++ const slugOf = new Map([[withBody.id, 'notes/never-chunked'], [timelineOnly.id, 'notes/timeline-only'], [skipped.id, 'notes/embed-skipped']]);+ const count = await engine.countChunklessPagesWithContent();+ const rows = await engine.listChunklessPagesWithContent();+ const names = rows.map((r) => r.slug);+ expect(count).toBe(3);+ expect(sorted(names)).toEqual(['notes/embed-skipped', 'notes/never-chunked', 'notes/timeline-only']);+ const timelineRow = rows.find((r) => r.slug === 'notes/timeline-only')!;+ expect(pick(timelineRow, ['source_id', 'compiled_truth', 'timeline'] as const)).toEqual({ source_id: 'default', compiled_truth: '', timeline: '- 2026-02-02: only a timeline' });++ // Keyset paging in page-id order, one page per call.+ const walked: string[] = [];+ let afterPageId: number | undefined;+ for (let guard = 0; guard < 10; guard++) {+ const batch = await engine.listChunklessPagesWithContent({ batchSize: 1, afterPageId });+ if (batch.length === 0) break;+ walked.push(slugOf.get(batch[0]!.id)!);+ afterPageId = batch[0]!.id;+ }+ expect(walked).toEqual(['notes/never-chunked', 'notes/timeline-only', 'notes/embed-skipped']);++ const scopedMiss = await engine.countChunklessPagesWithContent({ sourceId: 'no-such-source' });+ const scopedMissList = await engine.listChunklessPagesWithContent({ sourceId: 'no-such-source' });+ const scopedHit = await engine.countChunklessPagesWithContent({ sourceId: 'default' });+ expect([scopedMiss, scopedMissList.length, scopedHit]).toEqual([0, 0, 3]);+ return { count, names: sorted(names), timelineRow: pick(timelineRow, ['source_id', 'compiled_truth', 'timeline'] as const), walked, scopedMiss, scopedHit };+ },+ );++ parityTest(+ 'readEmbeddingStateCounts and listEmbeddingStateRows classify every chunk and chunkless page',+ { methods: ['putPage', 'softDeletePage', 'readEmbeddingStateCounts', 'listEmbeddingStateRows'] },+ async (engine) => {+ await seedPage(engine, { slug: 'notes/st-embedded', input: PAGE('St embedded', 'x'), chunks: [chunk(0, 'embedded text', { embedding: basisEmbedding(1) })] });+ await seedPage(engine, { slug: 'notes/st-mixed', input: PAGE('St mixed', 'x'), chunks: [chunk(0, 'mixed a', { embedding: basisEmbedding(2) }), chunk(1, 'mixed b')] });+ await seedPage(engine, { slug: 'notes/st-pending', input: PAGE('St pending', 'x'), chunks: [chunk(0, 'pending text')] });+ await seedPage(engine, {+ slug: 'notes/st-keyword-only',+ input: { ...PAGE('St keyword only', 'x'), frontmatter: { embed_skip: { reason: 'oversize', bytes: 99 } } },+ chunks: [chunk(0, 'keyword only text')],+ });+ await seedPage(engine, {+ slug: 'notes/st-quarantined',+ input: { ...PAGE('St quarantined', 'x'), frontmatter: { quarantine: { reason: 'junk' } } },+ chunks: [chunk(0, 'quarantined text')],+ });+ await seedPage(engine, { slug: 'notes/st-deleted', input: PAGE('St deleted', 'x'), chunks: [chunk(0, 'deleted text', { embedding: basisEmbedding(3) })] });+ await engine.softDeletePage('notes/st-deleted');+ await engine.putPage('notes/st-chunkless', PAGE('St chunkless', 'body with text'));+ await engine.putPage('notes/st-empty', PAGE('St empty', ''));++ const full = await engine.readEmbeddingStateCounts({ mode: 'full', purgeWindowHours: 72 });+ const fullView = { basis: full.basis, counts: full.counts, omitted: full.omitted, eligible_embedded: full.eligible_embedded, deleted_overdue: full.deleted_overdue, embed_skip_pages: full.embed_skip_pages, embed_skip_marker_bytes: full.embed_skip_marker_bytes };+ expect(full.counts).toEqual({ embedded: 2, pending: 2, keyword_only: 1, quarantined: 1, empty: 1, deleted_page_chunks: 1, chunkless_healable: 1 });+ const ops = await engine.readEmbeddingStateCounts({ mode: 'ops', purgeWindowHours: 72 });+ // ops mode reads only index-backed counts; `embedded` is the planner's row estimate, so it is not compared.+ const { embedded: _estimated, ...opsCounts } = ops.counts;+ const opsView = { basis: ops.basis, omitted: ops.omitted, opsCounts, active_column: ops.active_column };+ const scoped = await engine.readEmbeddingStateCounts({ mode: 'full', sourceIds: ['no-such-source'], purgeWindowHours: 72 });+ expect(Object.values(scoped.counts).every((n) => n === 0)).toBe(true);++ const rows = await engine.listEmbeddingStateRows({ states: ['embedded', 'pending', 'keyword_only', 'quarantined', 'empty', 'deleted_page_chunks', 'chunkless_healable'], limit: 50, purgeWindowHours: 72 });+ const rowView = rows.map((r) => pick(r, ['slug', 'source_id', 'state', 'chunks', 'bytes', 'embed_skip_reason', 'marker_bytes', 'quarantine_reason', 'deleted_at', 'overdue'] as const));+ const pendingOnly = await engine.listEmbeddingStateRows({ states: ['pending'], limit: 50, purgeWindowHours: 72 });+ const bySlug = await engine.listEmbeddingStateRows({ slugs: ['notes/st-mixed'], states: ['embedded', 'pending'], limit: 50, purgeWindowHours: 72 });+ const limited = await engine.listEmbeddingStateRows({ states: ['embedded', 'pending'], limit: 2, purgeWindowHours: 72 });+ expect(pendingOnly.map((r) => r.slug)).toEqual(['notes/st-mixed', 'notes/st-pending']);+ expect(bySlug.map((r) => `${r.state}:${r.chunks}`)).toEqual(['embedded:1', 'pending:1']);+ expect(limited.length).toBe(2);+ return { fullView, opsView, scopedCounts: scoped.counts, rows: rowView, pendingOnly: pendingOnly.map((r) => r.slug), bySlug: bySlug.map((r) => `${r.state}:${r.chunks}`), limited: limited.map((r) => `${r.state}:${r.slug}`) };+ },+ );++ parityTest(+ 'deleteChunks removes every chunk of one page and leaves the others',+ { methods: ['deleteChunks', 'getChunks', 'countStaleChunks', 'countChunklessPagesWithContent'] },+ async (engine) => {+ await seedPage(engine, { slug: 'notes/del-a', input: PAGE('Del A', 'a body'), chunks: [chunk(0, 'a0', { embedding: basisEmbedding(1) }), chunk(1, 'a1')] });+ await seedPage(engine, { slug: 'notes/del-b', input: PAGE('Del B', 'b body'), chunks: [chunk(0, 'b0')] });+ await engine.deleteChunks('notes/del-a');+ const a = await engine.getChunks('notes/del-a', { includeUnsealed: true });+ const b = view(await engine.getChunks('notes/del-b'));+ // The page is chunkless again, so the safety net sees it; the other page keeps its chunk.+ const chunkless = await engine.countChunklessPagesWithContent();+ const stale = await engine.countStaleChunks();+ expect({ a, bTexts: b.map((c) => c.chunk_text), chunkless, stale }).toEqual({ a: [], bTexts: ['b0'], chunkless: 1, stale: 1 });+ // Deleting from a missing page or a missing source is a harmless no-op.+ await engine.deleteChunks('notes/nobody');+ await engine.deleteChunks('notes/del-b', { sourceId: 'no-such-source' });+ const bAfter = (await engine.getChunks('notes/del-b')).map((c) => c.chunk_text);+ expect(bAfter).toEqual(['b0']);+ return { a, b: b.map((c) => c.chunk_text), chunkless, stale, bAfter };+ },+ );++ parityTest(+ 'the same slug in two sources keeps separate chunk sets under sourceId scoping',+ { methods: ['getChunks', 'getChunkPage', 'deleteChunks', 'countStaleChunks', 'listStaleChunks', 'countChunklessPagesWithContent'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'work');+ await seedPage(engine, { slug: 'notes/shared', input: PAGE('Shared default', 'default body'), chunks: [chunk(0, 'default zero'), chunk(1, 'default one', { embedding: basisEmbedding(1) })] });+ await seedPage(engine, { slug: 'notes/shared', input: PAGE('Shared work', 'work body'), chunks: [chunk(0, 'work zero')] }, { sourceId: 'work' });++ const texts = async (opts?: { sourceId?: string; sourceIds?: string[] }) => (await engine.getChunks('notes/shared', opts)).map((c) => c.chunk_text);+ const implicitDefault = await texts();+ const work = await texts({ sourceId: 'work' });+ const federated = sorted(await texts({ sourceIds: ['default', 'work'] }));+ const workPage = await engine.getChunkPage('notes/shared', { sourceId: 'work', fromIndex: 0, limit: 10 });+ expect(implicitDefault).toEqual(['default zero', 'default one']);+ expect(work).toEqual(['work zero']);+ expect(federated).toEqual(['default one', 'default zero', 'work zero']);+ expect(workPage.total_chunks).toBe(1);++ const staleDefault = await engine.countStaleChunks({ sourceId: 'default' });+ const staleWork = await engine.countStaleChunks({ sourceId: 'work' });+ const staleAll = await engine.countStaleChunks();+ const staleRows = (await engine.listStaleChunks({ sourceId: 'work' })).map((r) => `${r.source_id}:${r.slug}/${r.chunk_index}`);+ expect({ staleDefault, staleWork, staleAll, staleRows }).toEqual({ staleDefault: 1, staleWork: 1, staleAll: 2, staleRows: ['work:notes/shared/0'] });++ await engine.deleteChunks('notes/shared', { sourceId: 'work' });+ const workAfter = await texts({ sourceId: 'work' });+ const defaultAfter = await texts();+ const chunklessWork = await engine.countChunklessPagesWithContent({ sourceId: 'work' });+ const chunklessDefault = await engine.countChunklessPagesWithContent({ sourceId: 'default' });+ expect({ workAfter, defaultAfter, chunklessWork, chunklessDefault }).toEqual({ workAfter: [], defaultAfter: ['default zero', 'default one'], chunklessWork: 1, chunklessDefault: 0 });+ return { implicitDefault, work, federated, staleDefault, staleWork, staleAll, staleRows, workAfter, defaultAfter, chunklessWork, chunklessDefault };+ },+ );+});diff --git a/test/engine-parity/code-eval-salience.test.ts b/test/engine-parity/code-eval-salience.test.tsnew file mode 100644index 0000000000..6638d0d095--- /dev/null+++ b/test/engine-parity/code-eval-salience.test.ts@@ -0,0 +1,419 @@+/**+ * BrainEngine parity — code_edges, eval_capture, salience_enrich families.+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: code-edge storage and traversal, eval candidate/failure+ * capture, and the salience / enrich-candidate / anomaly reads return the+ * same observable result on every engine arm (PGLite always; Postgres+ * with DATABASE_URL; a Rust arm later through test/engine-parity/harness.ts).+ * - Regression: an engine that drops the resolved/unresolved split of code+ * edges, mis-scopes callers by source, loses eval fields, mis-orders+ * salience, or counts inbound links across sources — code-callers,+ * `gbrain eval export`, `get_recent_salience`, `enrich --thin` and+ * `find_anomalies` all depend on these reads.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and covers none of these; the per-engine unit+ * tests (test/code-edges.test.ts etc.) never compare two engines.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ * Chunk and row ids are sequence-generated and never returned: edges are+ * mapped to `slug#chunk_index` labels, eval rows drop id/created_at.+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import type { CodeEdgeResult, EvalCandidateInput } from '../../src/core/types.ts';+import { createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';+import { installChunks } from './chunk-fixtures.ts';++const { parityTest } = parityArms(testBackends());++/** Create a code page with N chunks and return `chunk id -> slug#index` labels. */+async function seedCodePage(engine: BrainEngine, slug: string, symbols: string[], opts?: { sourceId?: string }) {+ await engine.putPage(slug, {+ type: 'code', page_kind: 'code', title: `${slug} (typescript)`, compiled_truth: symbols.map((s) => `function ${s}() {}`).join('\n'), timeline: '',+ }, opts);+ const inputs = symbols.map((s, i) => ({+ chunk_index: i,+ chunk_text: `function ${s}() {}`,+ chunk_source: 'compiled_truth' as const,+ language: 'typescript',+ symbol_name: s,+ symbol_type: 'function',+ symbol_name_qualified: s,+ }));+ await engine.upsertChunks(slug, inputs, opts);+ // Code-edge reads only serve sealed projections; the shared fixture seals them (see chunk-fixtures.ts).+ await installChunks(engine, slug, inputs, opts);+ const chunks = await engine.getChunks(slug, opts);+ return new Map(chunks.map((c) => [c.id, `${slug}#${c.chunk_index}`]));+}++function edgeView(labels: Map<number, string>, e: CodeEdgeResult): string {+ const from = labels.get(e.from_chunk_id) ?? `?${e.from_chunk_id}`;+ const to = e.to_chunk_id == null ? 'null' : (labels.get(e.to_chunk_id) ?? `?${e.to_chunk_id}`);+ return `${from} -[${e.edge_type}]-> ${to} (${e.from_symbol_qualified} => ${e.to_symbol_qualified}) resolved=${e.resolved} source=${e.source_id ?? 'null'}`;+}++describe('engine parity: code edges', () => {+ parityTest(+ 'addCodeEdges splits resolved and unresolved edges, is idempotent, and getCallers/getCallees/getEdgesByChunk read them',+ { methods: ['putPage', 'upsertChunks', 'getChunks', 'addCodeEdges', 'getCallersOf', 'getCalleesOf', 'getEdgesByChunk'] },+ async (engine) => {+ const a = await seedCodePage(engine, 'src-a-ts', ['run', 'main']);+ const b = await seedCodePage(engine, 'src-b-ts', ['helper']);+ const labels = new Map([...a, ...b]);+ const id = (label: string) => [...labels.entries()].find(([, l]) => l === label)![0];+ const runId = id('src-a-ts#0');+ const mainId = id('src-a-ts#1');+ const helperId = id('src-b-ts#0');+ const edges = [+ { from_chunk_id: runId, to_chunk_id: helperId, from_symbol_qualified: 'run', to_symbol_qualified: 'helper', edge_type: 'calls' },+ { from_chunk_id: runId, to_chunk_id: null, from_symbol_qualified: 'run', to_symbol_qualified: 'external.fetch', edge_type: 'calls' },+ { from_chunk_id: mainId, to_chunk_id: null, from_symbol_qualified: 'main', to_symbol_qualified: 'helper', edge_type: 'calls' },+ { from_chunk_id: mainId, to_chunk_id: runId, from_symbol_qualified: 'main', to_symbol_qualified: 'run', edge_type: 'imports' },+ ];+ const inserted = await engine.addCodeEdges(edges);+ const again = await engine.addCodeEdges(edges);+ const empty = await engine.addCodeEdges([]);+ expect(inserted).toBe(4);+ expect(again).toBe(0);+ expect(empty).toBe(0);+ const view = (rows: CodeEdgeResult[]) => sorted(rows.map((e) => edgeView(labels, e)));+ const callersOfHelper = view(await engine.getCallersOf('helper', { allSources: true }));+ const callersLimited = (await engine.getCallersOf('helper', { allSources: true, limit: 1 })).length;+ const callersNone = await engine.getCallersOf('nobody', { allSources: true });+ const calleesOfRun = view(await engine.getCalleesOf('run', { allSources: true }));+ const calleesLimited = (await engine.getCalleesOf('run', { allSources: true, limit: 1 })).length;+ const outOfRun = view(await engine.getEdgesByChunk(runId, { direction: 'out' }));+ const inToRun = view(await engine.getEdgesByChunk(runId, { direction: 'in' }));+ const bothRun = view(await engine.getEdgesByChunk(runId, { direction: 'both' }));+ const importsOnly = view(await engine.getEdgesByChunk(runId, { direction: 'both', edgeType: 'imports' }));+ const inToHelper = view(await engine.getEdgesByChunk(helperId, { direction: 'in' }));+ expect(callersOfHelper).toHaveLength(2);+ expect(callersLimited).toBe(1);+ expect(calleesLimited).toBe(1);+ expect(callersNone).toEqual([]);+ expect(outOfRun).toHaveLength(2);+ expect(importsOnly).toHaveLength(1);+ return { inserted, again, empty, callersOfHelper, callersLimited, callersNone: callersNone.length, calleesOfRun, calleesLimited, outOfRun, inToRun, bothRun, importsOnly, inToHelper };+ },+ );++ parityTest(+ 'getCallersOf/getCalleesOf scope by the anchor chunk source unless allSources is set',+ { methods: ['putPage', 'upsertChunks', 'getChunks', 'addCodeEdges', 'getCallersOf', 'getCalleesOf'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'code-other');+ const d = await seedCodePage(engine, 'src-d-ts', ['caller']);+ const o = await seedCodePage(engine, 'src-o-ts', ['caller'], { sourceId: 'code-other' });+ const labels = new Map([...d, ...o]);+ const idOf = (label: string) => [...labels.entries()].find(([, l]) => l === label)![0];+ await engine.addCodeEdges([+ { from_chunk_id: idOf('src-d-ts#0'), to_chunk_id: null, from_symbol_qualified: 'caller', to_symbol_qualified: 'shared.target', edge_type: 'calls', source_id: 'default' },+ { from_chunk_id: idOf('src-o-ts#0'), to_chunk_id: null, from_symbol_qualified: 'caller', to_symbol_qualified: 'shared.target', edge_type: 'calls', source_id: 'code-other' },+ ]);+ const view = (rows: CodeEdgeResult[]) => sorted(rows.map((e) => edgeView(labels, e)));+ const all = view(await engine.getCallersOf('shared.target', { allSources: true }));+ const defaultOnly = view(await engine.getCallersOf('shared.target', { sourceId: 'default' }));+ const otherOnly = view(await engine.getCallersOf('shared.target', { sourceId: 'code-other' }));+ const calleesDefault = view(await engine.getCalleesOf('caller', { sourceId: 'default' }));+ const calleesOther = view(await engine.getCalleesOf('caller', { sourceId: 'code-other' }));+ expect(all).toHaveLength(2);+ expect(defaultOnly).toHaveLength(1);+ expect(otherOnly).toHaveLength(1);+ return { all, defaultOnly, otherOnly, calleesDefault, calleesOther };+ },+ );++ parityTest(+ 'deleteCodeEdgesForChunks wipes edges in both directions across resolved and unresolved tables',+ { methods: ['putPage', 'upsertChunks', 'getChunks', 'addCodeEdges', 'deleteCodeEdgesForChunks', 'getEdgesByChunk', 'getCallersOf'] },+ async (engine) => {+ const a = await seedCodePage(engine, 'src-del-a-ts', ['alpha']);+ const b = await seedCodePage(engine, 'src-del-b-ts', ['beta']);+ const c = await seedCodePage(engine, 'src-del-c-ts', ['gamma']);+ const labels = new Map([...a, ...b, ...c]);+ const idOf = (label: string) => [...labels.entries()].find(([, l]) => l === label)![0];+ const alpha = idOf('src-del-a-ts#0');+ const beta = idOf('src-del-b-ts#0');+ const gamma = idOf('src-del-c-ts#0');+ await engine.addCodeEdges([+ { from_chunk_id: alpha, to_chunk_id: beta, from_symbol_qualified: 'alpha', to_symbol_qualified: 'beta', edge_type: 'calls' },+ { from_chunk_id: gamma, to_chunk_id: alpha, from_symbol_qualified: 'gamma', to_symbol_qualified: 'alpha', edge_type: 'calls' },+ { from_chunk_id: alpha, to_chunk_id: null, from_symbol_qualified: 'alpha', to_symbol_qualified: 'ext.one', edge_type: 'calls' },+ { from_chunk_id: gamma, to_chunk_id: beta, from_symbol_qualified: 'gamma', to_symbol_qualified: 'beta', edge_type: 'calls' },+ ]);+ const view = (rows: CodeEdgeResult[]) => sorted(rows.map((e) => edgeView(labels, e)));+ const before = view(await engine.getEdgesByChunk(alpha, { direction: 'both' }));+ await engine.deleteCodeEdgesForChunks([alpha]);+ await engine.deleteCodeEdgesForChunks([]);+ const afterAlpha = view(await engine.getEdgesByChunk(alpha, { direction: 'both' }));+ const survivor = view(await engine.getEdgesByChunk(gamma, { direction: 'both' }));+ const callersOfExt = await engine.getCallersOf('ext.one', { allSources: true });+ expect(before).toHaveLength(3);+ expect(afterAlpha).toEqual([]);+ expect(survivor).toHaveLength(1);+ expect(callersOfExt).toEqual([]);+ return { before, afterAlpha, survivor, callersOfExt: callersOfExt.length };+ },+ );+});++const CANDIDATE: EvalCandidateInput = {+ tool_name: 'query',+ query: 'who runs acme',+ retrieved_slugs: ['people/alice', 'companies/acme'],+ retrieved_chunk_ids: [],+ source_ids: ['default'],+ expand_enabled: true,+ detail: 'medium',+ detail_resolved: 'high',+ vector_enabled: true,+ expansion_applied: false,+ latency_ms: 42,+ remote: false,+ job_id: null,+ subagent_id: null,+ embedding_column: 'embedding',+};++const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));++/**+ * A cutoff just after the newest stored timestamp (the database's own clock,+ * so no JS/DB skew on the old side), then a bounded wait until the wall clock+ * passes it, so the next row is stamped after the cutoff.+ */+async function cutoffAfter(stamps: readonly Date[]): Promise<Date> {+ const cutoff = new Date(Math.max(...stamps.map((d) => d.getTime())) + 1);+ const deadline = Date.now() + 2_000;+ while (Date.now() <= cutoff.getTime()) {+ if (Date.now() > deadline) throw new Error(`wall clock did not pass ${cutoff.toISOString()} within 2 s`);+ await delay(2);+ }+ return cutoff;+}++describe('engine parity: eval capture', () => {+ parityTest(+ 'logEvalCandidate round-trips every field through listEvalCandidates, with tool filter and limit',+ { methods: ['logEvalCandidate', 'listEvalCandidates'] },+ async (engine) => {+ const first = await engine.logEvalCandidate(CANDIDATE);+ await delay(20);+ await engine.logEvalCandidate({+ ...CANDIDATE, tool_name: 'search', query: 'acme widgets', expand_enabled: null, detail: null, detail_resolved: null,+ vector_enabled: false, retrieved_slugs: ['companies/acme'], source_ids: ['default', 'other'], latency_ms: 7, remote: true, embedding_column: null,+ });+ await delay(20);+ await engine.logEvalCandidate({ ...CANDIDATE, query: 'third query', latency_ms: 99, job_id: null });+ expect(typeof first).toBe('number');+ const view = (c: Awaited<ReturnType<typeof engine.listEvalCandidates>>[number]) => {+ const { id: _id, created_at, ...rest } = c;+ expect(created_at).toBeInstanceOf(Date);+ return rest;+ };+ const all = await engine.listEvalCandidates();+ const queries = await engine.listEvalCandidates({ tool: 'query' });+ const searches = await engine.listEvalCandidates({ tool: 'search' });+ const limited = await engine.listEvalCandidates({ limit: 2 });+ expect(all).toHaveLength(3);+ expect(queries).toHaveLength(2);+ expect(searches).toHaveLength(1);+ expect(limited).toHaveLength(2);+ return {+ all: sorted(all.map(view), (c) => c.query),+ queries: sorted(queries.map((c) => c.query)),+ searches: searches.map(view),+ limitedCount: limited.length,+ // Newest-first is the documented export order; the two newest are the last two inserted.+ newestFirst: all.map((c) => c.query),+ };+ },+ );++ parityTest(+ 'listEvalCandidates since-window and deleteEvalCandidatesBefore split old from new rows',+ { methods: ['logEvalCandidate', 'listEvalCandidates', 'deleteEvalCandidatesBefore'] },+ async (engine) => {+ await engine.logEvalCandidate({ ...CANDIDATE, query: 'old one' });+ await engine.logEvalCandidate({ ...CANDIDATE, query: 'old two' });+ const cutoff = await cutoffAfter((await engine.listEvalCandidates()).map((c) => c.created_at));+ await engine.logEvalCandidate({ ...CANDIDATE, query: 'new one' });+ const sinceCutoff = (await engine.listEvalCandidates({ since: cutoff })).map((c) => c.query);+ const future = await engine.listEvalCandidates({ since: new Date(Date.now() + 3_600_000) });+ const deletedNone = await engine.deleteEvalCandidatesBefore(new Date(Date.now() - 3_600_000));+ const deleted = await engine.deleteEvalCandidatesBefore(cutoff);+ const remaining = (await engine.listEvalCandidates()).map((c) => c.query);+ const deletedRest = await engine.deleteEvalCandidatesBefore(new Date(Date.now() + 3_600_000));+ expect(sinceCutoff).toEqual(['new one']);+ expect(deleted).toBe(2);+ expect(remaining).toEqual(['new one']);+ return { sinceCutoff, future: future.length, deletedNone, deleted, remaining, deletedRest, afterAll: (await engine.listEvalCandidates()).length };+ },+ );++ parityTest(+ 'logEvalCaptureFailure records reasons; listEvalCaptureFailures filters by since',+ { methods: ['logEvalCaptureFailure', 'listEvalCaptureFailures'] },+ async (engine) => {+ const none = await engine.listEvalCaptureFailures();+ await engine.logEvalCaptureFailure('db_down');+ await engine.logEvalCaptureFailure('scrubber_exception');+ const cutoff = await cutoffAfter((await engine.listEvalCaptureFailures()).map((f) => new Date(f.ts)));+ await engine.logEvalCaptureFailure('other');+ const all = await engine.listEvalCaptureFailures();+ const recent = await engine.listEvalCaptureFailures({ since: cutoff });+ const future = await engine.listEvalCaptureFailures({ since: new Date(Date.now() + 3_600_000) });+ expect(all).toHaveLength(3);+ expect(recent.map((f) => f.reason)).toEqual(['other']);+ return {+ none: none.length,+ all: sorted(all.map((f) => pick(f, ['reason', 'ts'] as const)), (f) => f.reason),+ recent: recent.map((f) => f.reason),+ future: future.length,+ };+ },+ );+});++describe('engine parity: salience + enrich + anomalies', () => {+ parityTest(+ 'batchLoadEmotionalInputs returns tags and active takes per page; slug filter narrows',+ { methods: ['putPage', 'addTag', 'addTakesBatch', 'batchLoadEmotionalInputs'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'sal-other');+ const alice = await engine.putPage('people/sal-alice', { type: 'person', title: 'Alice', compiled_truth: 'A.', timeline: '' });+ await engine.putPage('people/sal-bob', { type: 'person', title: 'Bob', compiled_truth: 'B.', timeline: '' });+ await engine.putPage('people/sal-bob', { type: 'person', title: 'Bob Other', compiled_truth: 'B2.', timeline: '' }, { sourceId: 'sal-other' });+ await engine.addTag('people/sal-alice', 'family');+ await engine.addTag('people/sal-alice', 'founder');+ await engine.addTag('people/sal-bob', 'founder');+ await engine.addTakesBatch([+ { page_id: alice.id, row_num: 1, claim: 'Alice cares a lot', kind: 'belief', holder: 'garry', weight: 0.9 },+ { page_id: alice.id, row_num: 2, claim: 'Alice is busy', kind: 'fact', holder: 'garry', weight: 0.4 },+ { page_id: alice.id, row_num: 3, claim: 'Retired claim', kind: 'belief', holder: 'garry', weight: 0.8, active: false },+ ]);+ const view = (rows: Awaited<ReturnType<typeof engine.batchLoadEmotionalInputs>>) =>+ sorted(rows.map((r) => ({+ id: `${r.source_id}:${r.slug}`,+ tags: sorted(r.tags),+ takes: sorted(r.takes.map((t) => `${t.kind}|${t.holder}|${t.weight}|${t.active}`)),+ })), (r) => r.id);+ const everything = view(await engine.batchLoadEmotionalInputs());+ const one = view(await engine.batchLoadEmotionalInputs(['people/sal-alice']));+ const none = await engine.batchLoadEmotionalInputs(['people/missing']);+ expect(everything).toHaveLength(3);+ expect(one).toHaveLength(1);+ expect(one[0]!.takes).toHaveLength(2);+ expect(none).toEqual([]);+ return { everything, one, none };+ },+ );++ parityTest(+ 'setEmotionalWeightBatch counts changed rows only, is source-keyed, and feeds getRecentSalience ordering',+ { methods: ['putPage', 'addTakesBatch', 'setEmotionalWeightBatch', 'getRecentSalience'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'sal2-other');+ const calm = await engine.putPage('notes/sal-calm', { type: 'note', title: 'Calm', compiled_truth: 'Calm.', timeline: '' });+ await engine.putPage('notes/sal-charged', { type: 'note', title: 'Charged', compiled_truth: 'Charged.', timeline: '' });+ await engine.putPage('notes/sal-charged', { type: 'note', title: 'Charged Other', compiled_truth: 'Charged other.', timeline: '' }, { sourceId: 'sal2-other' });+ await engine.putPage('briefings/daily', { type: 'note', title: 'Briefing', compiled_truth: 'Briefing.', timeline: '' });+ await engine.putPage('people/sal-person', { type: 'person', title: 'Person', compiled_truth: 'Person.', timeline: '' });+ await engine.addTakesBatch([+ { page_id: calm.id, row_num: 1, claim: 'c1', kind: 'fact', holder: 'garry', weight: 0.5 },+ { page_id: calm.id, row_num: 2, claim: 'c2', kind: 'fact', holder: 'garry', weight: 0.7 },+ ]);+ const changed = await engine.setEmotionalWeightBatch([+ { slug: 'notes/sal-charged', source_id: 'default', weight: 0.9 },+ { slug: 'people/sal-person', source_id: 'default', weight: 0.2 },+ { slug: 'notes/sal-charged', source_id: 'sal2-other', weight: 0.4 },+ { slug: 'notes/not-a-page', source_id: 'default', weight: 1 },+ ]);+ const unchanged = await engine.setEmotionalWeightBatch([+ { slug: 'notes/sal-charged', source_id: 'default', weight: 0.9 },+ ]);+ const empty = await engine.setEmotionalWeightBatch([]);+ expect(changed).toBe(3);+ expect(unchanged).toBe(0);+ expect(empty).toBe(0);+ // score = emotional_weight*5 + ln(1+takes) + a recency term that drifts with wall time: round it.+ const view = (rows: Awaited<ReturnType<typeof engine.getRecentSalience>>) =>+ rows.map((r) => ({ id: `${r.source_id}:${r.slug}`, title: r.title, type: r.type, ew: Math.round(r.emotional_weight * 100) / 100, takes: r.take_count, avg: Math.round(r.take_avg_weight * 100) / 100, score: Math.round(r.score) }));+ const all = view(await engine.getRecentSalience({ days: 7 }));+ const scoped = view(await engine.getRecentSalience({ days: 7, sourceId: 'sal2-other' }));+ const prefixed = view(await engine.getRecentSalience({ days: 7, slugPrefix: 'people/' }));+ const limited = view(await engine.getRecentSalience({ days: 7, limit: 2 }));+ const noWindow = await engine.getRecentSalience({ days: 0 });+ expect(all.map((r) => r.id)).not.toContain('default:briefings/daily');+ expect(all[0]!.id).toBe('default:notes/sal-charged');+ expect(scoped.map((r) => r.id)).toEqual(['sal2-other:notes/sal-charged']);+ expect(prefixed.map((r) => r.id)).toEqual(['default:people/sal-person']);+ expect(limited).toHaveLength(2);+ return { changed, unchanged, empty, all, scoped, prefixed, limitedKeys: limited.map((r) => r.id), noWindow: noWindow.length };+ },+ );++ parityTest(+ 'listEnrichCandidates picks thin pages by type, counts inbound links, orders and limits, and scopes by source',+ { methods: ['putPage', 'addLink', 'listEnrichCandidates'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'enrich-other');+ const thin = { compiled_truth: 'Stub.', timeline: '' };+ await engine.putPage('people/enrich-a', { type: 'person', title: 'Alpha', ...thin });+ await engine.putPage('people/enrich-b', { type: 'person', title: 'Beta', ...thin });+ await engine.putPage('people/enrich-c', { type: 'person', title: 'Gamma', ...thin });+ await engine.putPage('companies/enrich-co', { type: 'company', title: 'Co', ...thin });+ await engine.putPage('people/enrich-thick', { type: 'person', title: 'Thick', compiled_truth: 'x'.repeat(400), timeline: '' });+ await engine.putPage('people/enrich-dream', { type: 'person', title: 'Dream', ...thin, frontmatter: { dream_generated: true } });+ await engine.putPage('people/enrich-o', { type: 'person', title: 'Other', ...thin }, { sourceId: 'enrich-other' });+ await engine.putPage('notes/enrich-linker', { type: 'note', title: 'Linker', compiled_truth: 'Links to people.', timeline: '' });+ await engine.addLink('notes/enrich-linker', 'people/enrich-b', '', 'mentions_person');+ await engine.addLink('notes/enrich-linker', 'people/enrich-c', '', 'mentions_person');+ await engine.addLink('companies/enrich-co', 'people/enrich-c', '', 'works_at');+ const view = (rows: Awaited<ReturnType<typeof engine.listEnrichCandidates>>) =>+ rows.map((r) => `${r.source_id}:${r.slug}|${r.type}|${r.title}|${r.body_len}|${r.inbound_count}`);+ const base = { types: ['person' as const], thinThreshold: 100, order: 'inbound-links' as const, limit: 50 };+ const byInbound = view(await engine.listEnrichCandidates(base));+ const limited = view(await engine.listEnrichCandidates({ ...base, limit: 2 }));+ const bySlugScoped = view(await engine.listEnrichCandidates({ ...base, sourceId: 'enrich-other' }));+ const federated = view(await engine.listEnrichCandidates({ ...base, sourceIds: ['default'] }));+ const twoTypes = view(await engine.listEnrichCandidates({ ...base, types: ['person', 'company'] }));+ const noTypes = await engine.listEnrichCandidates({ ...base, types: [] });+ const thickToo = view(await engine.listEnrichCandidates({ ...base, thinThreshold: 1000 }));+ const updated = view(await engine.listEnrichCandidates({ ...base, order: 'updated' }));+ expect(byInbound[0]).toContain('people/enrich-c');+ expect(byInbound.some((r) => r.includes('enrich-thick'))).toBe(false);+ expect(byInbound.some((r) => r.includes('enrich-dream'))).toBe(false);+ expect(noTypes).toEqual([]);+ expect(limited).toHaveLength(2);+ return { byInbound, limited, bySlugScoped, federated, twoTypes, noTypes: noTypes.length, thickToo, updatedCount: updated.length };+ },+ );++ parityTest(+ 'findAnomalies flags a cohort with unusual activity today and respects source scope and sigma',+ { methods: ['putPage', 'addTag', 'findAnomalies'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'anom-other');+ for (let i = 0; i < 4; i++) {+ await engine.putPage(`notes/anom-${i}`, { type: 'note', title: `Anom ${i}`, compiled_truth: `Anomaly ${i}.`, timeline: '' });+ await engine.addTag(`notes/anom-${i}`, 'launch');+ }+ await engine.putPage('people/anom-solo', { type: 'person', title: 'Solo', compiled_truth: 'Solo.', timeline: '' });+ await engine.putPage('notes/anom-o', { type: 'note', title: 'Other', compiled_truth: 'Other.', timeline: '' }, { sourceId: 'anom-other' });+ // The day the pages were stamped by the database, not the JS clock, so a run across UTC midnight still matches.+ const today = new Date((await engine.getPage('notes/anom-3'))!.updated_at).toISOString().slice(0, 10);+ const view = (rows: Awaited<ReturnType<typeof engine.findAnomalies>>) =>+ rows.map((r) => ({ ...pick(r, ['cohort_kind', 'cohort_value', 'count'] as const), baseline_mean: r.baseline_mean, baseline_stddev: r.baseline_stddev, page_slugs: sorted(r.page_slugs) }));+ const found = view(await engine.findAnomalies({ since: today, lookback_days: 7 }));+ const scoped = view(await engine.findAnomalies({ since: today, lookback_days: 7, sourceId: 'anom-other' }));+ const strict = view(await engine.findAnomalies({ since: today, lookback_days: 7, sigma: 50 }));+ const otherDay = await engine.findAnomalies({ since: '2020-01-01', lookback_days: 7 });+ expect(found.find((r) => r.cohort_kind === 'tag' && r.cohort_value === 'launch')?.count).toBe(4);+ expect(otherDay).toEqual([]);+ return { found, scoped, strict, otherDay: otherDay.length };+ },+ );+});diff --git a/test/engine-parity/config-ingest.test.ts b/test/engine-parity/config-ingest.test.tsnew file mode 100644index 0000000000..cea7edffbf--- /dev/null+++ b/test/engine-parity/config-ingest.test.ts@@ -0,0 +1,232 @@+/**+ * BrainEngine parity — config + stats/ingest families.+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: config reads/writes, brain stats/health counters and the+ * ingest log return the same observable result on every engine arm+ * (PGLite always; Postgres with DATABASE_URL; a Rust arm later through+ * test/engine-parity/harness.ts).+ * - Regression: an engine that drifts on config upsert/unset/prefix-listing+ * (LIKE escaping), on counter arithmetic in getStats/getHealth, or on+ * ingest-log scoping — the surfaces `gbrain stats`, `doctor` and every+ * config-driven feature read.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and does not exercise config or ingest log;+ * per-engine unit tests never compare two engines on one scenario.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ * A fresh brain already holds config rows from initSchema, so config+ * cases compare only keys under a prefix the scenario owns.+ */+import { describe, expect } from 'bun:test';+import { basisEmbedding, createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const OWN = 'parity.cfg.';++describe('engine parity: config', () => {+ parityTest(+ 'setConfig upserts and getConfig reads back; missing keys are null',+ { methods: ['setConfig', 'getConfig'] },+ async (engine) => {+ const before = await engine.getConfig(`${OWN}alpha`);+ await engine.setConfig(`${OWN}alpha`, 'one');+ const first = await engine.getConfig(`${OWN}alpha`);+ await engine.setConfig(`${OWN}alpha`, 'two');+ const second = await engine.getConfig(`${OWN}alpha`);+ await engine.setConfig(`${OWN}empty`, '');+ const empty = await engine.getConfig(`${OWN}empty`);+ await engine.setConfig(`${OWN}json`, JSON.stringify({ a: [1, 2], b: 'x' }));+ const json = await engine.getConfig(`${OWN}json`);+ expect(before).toBeNull();+ expect(first).toBe('one');+ expect(second).toBe('two');+ expect(JSON.parse(json!)).toEqual({ a: [1, 2], b: 'x' });+ return { before, first, second, empty, json, missing: await engine.getConfig(`${OWN}missing`) };+ },+ );++ parityTest(+ 'unsetConfig returns the deleted row count and is a no-op for a missing key',+ { methods: ['setConfig', 'getConfig', 'unsetConfig'] },+ async (engine) => {+ await engine.setConfig(`${OWN}gone`, 'x');+ const removed = await engine.unsetConfig(`${OWN}gone`);+ const removedAgain = await engine.unsetConfig(`${OWN}gone`);+ const never = await engine.unsetConfig(`${OWN}never-set`);+ expect(removed).toBe(1);+ expect(removedAgain).toBe(0);+ return { removed, removedAgain, never, after: await engine.getConfig(`${OWN}gone`) };+ },+ );++ parityTest(+ 'listConfigKeys matches a literal prefix, sorted, and escapes LIKE wildcards',+ { methods: ['setConfig', 'listConfigKeys'] },+ async (engine) => {+ for (const key of ['pfx.a.one', 'pfx.a.two', 'pfx.b.one', 'pfxXa.one', 'pf_x.one', 'pf%x.one', 'other.key']) {+ await engine.setConfig(key, 'v');+ }+ const a = await engine.listConfigKeys('pfx.a.');+ const all = await engine.listConfigKeys('pfx');+ const underscore = await engine.listConfigKeys('pf_');+ const percent = await engine.listConfigKeys('pf%');+ const none = await engine.listConfigKeys('nothing-here-');+ expect(a).toEqual(['pfx.a.one', 'pfx.a.two']);+ expect(underscore).toEqual(['pf_x.one']);+ expect(percent).toEqual(['pf%x.one']);+ expect(none).toEqual([]);+ return { a, all, underscore, percent, none };+ },+ );++ parityTest(+ 'getAllConfig returns every row as a key->value map reflecting set and unset',+ { methods: ['setConfig', 'unsetConfig', 'getAllConfig', 'listConfigKeys'] },+ async (engine) => {+ await engine.setConfig(`${OWN}x`, '1');+ await engine.setConfig(`${OWN}y`, '2');+ await engine.setConfig(`${OWN}z`, '3');+ await engine.unsetConfig(`${OWN}y`);+ const everything = await engine.getAllConfig();+ const owned = Object.fromEntries(Object.entries(everything).filter(([k]) => k.startsWith(OWN)).sort(([a], [b]) => (a < b ? -1 : 1)));+ expect(owned).toEqual({ [`${OWN}x`]: '1', [`${OWN}z`]: '3' });+ // The map and the prefix listing agree about the whole key set.+ const listed = await engine.listConfigKeys('');+ expect(sorted(Object.keys(everything))).toEqual(sorted(listed));+ return { owned };+ },+ );+});++describe('engine parity: stats + ingest log', () => {+ parityTest(+ 'getStats counts pages, chunks, embeddings, links, tags and timeline entries',+ { methods: ['putPage', 'upsertChunks', 'addLink', 'addTag', 'addTimelineEntry', 'getStats'] },+ async (engine) => {+ const empty = await engine.getStats();+ await engine.putPage('people/stats-alice', { type: 'person', title: 'Alice', compiled_truth: 'Alice at acme.', timeline: '' });+ await engine.putPage('companies/stats-acme', { type: 'company', title: 'Acme', compiled_truth: 'Acme makes widgets.', timeline: '' });+ await engine.putPage('notes/stats-note', { type: 'note', title: 'Note', compiled_truth: 'A plain note.', timeline: '' });+ await engine.upsertChunks('people/stats-alice', [+ { chunk_index: 0, chunk_text: 'Alice at acme.', chunk_source: 'compiled_truth', embedding: basisEmbedding(1) },+ { chunk_index: 1, chunk_text: 'Alice timeline.', chunk_source: 'timeline' },+ ]);+ await engine.upsertChunks('companies/stats-acme', [+ { chunk_index: 0, chunk_text: 'Acme makes widgets.', chunk_source: 'compiled_truth', embedding: basisEmbedding(2) },+ ]);+ await engine.addLink('people/stats-alice', 'companies/stats-acme', 'works at', 'works_at');+ await engine.addTag('people/stats-alice', 'founder');+ await engine.addTag('people/stats-alice', 'advisor');+ await engine.addTag('companies/stats-acme', 'founder');+ await engine.addTimelineEntry('people/stats-alice', { date: '2026-01-02', summary: 'Joined acme', detail: '' });+ const stats = await engine.getStats();+ expect(empty.page_count).toBe(0);+ expect(stats.page_count).toBe(3);+ expect(stats.chunk_count).toBe(3);+ expect(stats.embedded_count).toBe(2);+ expect(stats.link_count).toBe(1);+ expect(stats.tag_count).toBe(2); // distinct tags+ expect(stats.timeline_entry_count).toBe(1);+ expect(stats.pages_by_type).toEqual({ person: 1, company: 1, note: 1 });+ return { empty, stats };+ },+ );++ parityTest(+ 'getStats and getHealth confine to a source scope',+ { methods: ['putPage', 'upsertChunks', 'getStats', 'getHealth'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'stats-other');+ await engine.putPage('people/scope-a', { type: 'person', title: 'A', compiled_truth: 'A.', timeline: '' });+ await engine.putPage('people/scope-b', { type: 'person', title: 'B', compiled_truth: 'B.', timeline: '' }, { sourceId: 'stats-other' });+ await engine.putPage('notes/scope-c', { type: 'note', title: 'C', compiled_truth: 'C.', timeline: '' }, { sourceId: 'stats-other' });+ await engine.upsertChunks('notes/scope-c', [+ { chunk_index: 0, chunk_text: 'C.', chunk_source: 'compiled_truth', embedding: basisEmbedding(3) },+ ], { sourceId: 'stats-other' });+ const whole = await engine.getStats();+ const def = await engine.getStats({ sourceId: 'default' });+ const other = await engine.getStats({ sourceId: 'stats-other' });+ const both = await engine.getStats({ sourceIds: ['default', 'stats-other'] });+ const healthDefault = await engine.getHealth({ sourceId: 'default' });+ const healthOther = await engine.getHealth({ sourceId: 'stats-other' });+ expect(whole.page_count).toBe(3);+ expect(def.page_count).toBe(1);+ expect(other.page_count).toBe(2);+ expect(both.page_count).toBe(3);+ expect(other.embedded_count).toBe(1);+ expect(healthDefault.page_count).toBe(1);+ expect(healthOther.page_count).toBe(2);+ const healthKeys = ['page_count', 'embed_coverage', 'missing_embeddings', 'orphan_pages', 'dead_links', 'entity_page_count'] as const;+ return {+ whole, def, other, both,+ healthDefault: pick(healthDefault, healthKeys),+ healthOther: pick(healthOther, healthKeys),+ };+ },+ );++ parityTest(+ 'getHealth reports coverage, orphans, missing embeddings and the score parts',+ { methods: ['putPage', 'upsertChunks', 'addLink', 'getHealth'] },+ async (engine) => {+ const empty = await engine.getHealth();+ await engine.putPage('people/health-alice', { type: 'person', title: 'Alice', compiled_truth: 'Alice.', timeline: '' });+ await engine.putPage('companies/health-acme', { type: 'company', title: 'Acme', compiled_truth: 'Acme.', timeline: '' });+ await engine.putPage('people/health-loner', { type: 'person', title: 'Loner', compiled_truth: 'Alone.', timeline: '' });+ await engine.upsertChunks('people/health-alice', [+ { chunk_index: 0, chunk_text: 'Alice.', chunk_source: 'compiled_truth', embedding: basisEmbedding(4) },+ ]);+ await engine.upsertChunks('companies/health-acme', [+ { chunk_index: 0, chunk_text: 'Acme.', chunk_source: 'compiled_truth' },+ ]);+ await engine.addLink('people/health-alice', 'companies/health-acme', '', 'works_at');+ const health = await engine.getHealth();+ expect(health.page_count).toBe(3);+ expect(health.missing_embeddings).toBe(1);+ expect(health.orphan_pages).toBe(1);+ expect(health.dead_links).toBe(0);+ const keys = [+ 'page_count', 'linkable_page_count', 'embed_coverage', 'stale_pages', 'orphan_pages', 'missing_embeddings',+ 'brain_score', 'dead_links', 'entity_page_count', 'entity_types_status', 'link_coverage', 'timeline_coverage',+ 'embed_coverage_score', 'link_density_score', 'timeline_coverage_score', 'no_orphans_score', 'no_dead_links_score',+ ] as const;+ return {+ empty: pick(empty, ['page_count', 'missing_embeddings', 'orphan_pages', 'dead_links'] as const),+ health: pick(health, keys),+ mostConnected: sorted(health.most_connected.map((m) => `${m.slug}:${m.link_count}`)),+ };+ },+ );++ parityTest(+ 'logIngest then getIngestLog returns entries newest-first with a limit and source scope',+ { methods: ['logIngest', 'getIngestLog'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'ingest-other');+ const empty = await engine.getIngestLog();+ await engine.logIngest({ source_type: 'markdown', source_ref: 'a.md', pages_updated: ['people/a', 'people/b'], summary: 'first' });+ await engine.logIngest({ source_id: 'ingest-other', source_type: 'git', source_ref: 'repo@1', pages_updated: [], summary: 'second' });+ await engine.logIngest({ source_type: 'markdown', source_ref: 'c.md', pages_updated: ['notes/c'], summary: 'third' });+ const view = (e: { source_id: string; source_type: string; source_ref: string; pages_updated: string[]; summary: string; created_at: Date }) =>+ pick(e, ['source_id', 'source_type', 'source_ref', 'pages_updated', 'summary', 'created_at'] as const);+ const all = await engine.getIngestLog();+ const limited = await engine.getIngestLog({ limit: 2 });+ const scopedDefault = await engine.getIngestLog({ sourceIds: ['default'] });+ const scopedOther = await engine.getIngestLog({ sourceIds: ['ingest-other'] });+ expect(empty).toEqual([]);+ expect(all).toHaveLength(3);+ expect(limited).toHaveLength(2);+ expect(scopedDefault.map((e) => e.summary).sort()).toEqual(['first', 'third']);+ expect(scopedOther.map((e) => e.summary)).toEqual(['second']);+ return {+ // created_at ties inside one transaction-less burst are not ordered by contract: compare as sets.+ all: sorted(all.map(view), (e) => e.summary),+ limitedCount: limited.length,+ scopedDefault: sorted(scopedDefault.map(view), (e) => e.summary),+ scopedOther: scopedOther.map(view),+ };+ },+ );+});diff --git a/test/engine-parity/coverage.test.ts b/test/engine-parity/coverage.test.tsnew file mode 100644index 0000000000..dc8b4506c2--- /dev/null+++ b/test/engine-parity/coverage.test.ts@@ -0,0 +1,79 @@+/**+ * BrainEngine parity coverage list stays current.+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: test/engine-parity/coverage.tsv equals the generator output,+ * so the parity number (covered N/198) in review is real.+ * - Regression: a new parity case, a new or renamed BrainEngine method, or+ * a hand edit of the list that leaves the checked-in number stale.+ * - Why existing coverage misses it: test/engine-surface-coverage.test.ts+ * asks "is the method called anywhere in test/", not "is it compared+ * across engine arms".+ * Also pins that every parity file selects its arms with `testBackends()`+ * and has a row in test/postgres-unit-arms.txt, so its Postgres arm runs+ * in CI (the unit lanes unset DATABASE_URL and run only the PGLite arm).+ * Also self-tests test/engine-parity/arm-capabilities.ts: no arm lacks+ * raw_sql yet, so the harness's refusal check has no live caller until the+ * Rust arm lands, and these assertions keep it honest meanwhile.+ * - Seam: none (pure file generation).+ */+import { describe, expect, test } from 'bun:test';+import { readdirSync, readFileSync } from 'node:fs';+import { join } from 'node:path';+import { buildCoverage, COVERAGE_FILE, FAMILIES, parityDeclarations } from './coverage.ts';+import { armCapabilities, isCapabilityRefusal, missingCapability, PARITY_ARMS } from './arm-capabilities.ts';++describe('engine parity coverage list', () => {+ test('coverage.tsv is fresh (regenerate: bun test/engine-parity/coverage.ts --write)', () => {+ const report = buildCoverage();+ expect(readFileSync(COVERAGE_FILE, 'utf8')).toBe(report.text);+ });++ test('every family member is a BrainEngine method and every method has one family', () => {+ const report = buildCoverage();+ const assigned = Object.values(FAMILIES).flat();+ expect([...assigned].sort()).toEqual([...report.methods].sort());+ expect(new Set(assigned).size).toBe(assigned.length);+ });++ test('every parity case declares at least one method, with no duplicates', () => {+ for (const decl of parityDeclarations()) {+ expect({ name: decl.name, empty: decl.methods.length === 0 }).toEqual({ name: decl.name, empty: false });+ expect({ name: decl.name, dupes: decl.methods.length - new Set(decl.methods).size }).toEqual({ name: decl.name, dupes: 0 });+ }+ });+ test('every parity file runs every arm: testBackends() and a Postgres lane row', () => {+ const dir = import.meta.dir;+ const files = readdirSync(dir).filter((f) => f.endsWith('.test.ts') && f !== 'coverage.test.ts').sort();+ expect(files.length).toBeGreaterThan(0);+ const lanes = new Set(readFileSync(join(dir, '..', 'postgres-unit-arms.txt'), 'utf8').split('\n').map((l) => l.trim()));+ for (const file of files) {+ const text = readFileSync(join(dir, file), 'utf8');+ const row = `test/engine-parity/${file}`;+ expect({ file, selectsArms: text.includes('parityArms(testBackends())'), laned: lanes.has(row) })+ .toEqual({ file, selectsArms: true, laned: true });+ }+ });++ test('arm capabilities: SQL arms run raw SQL, only Postgres holds the schema lock, Rust has neither yet', () => {+ expect(PARITY_ARMS.map((arm) => [arm, [...armCapabilities(arm)].sort()])).toEqual([+ ['pglite', ['raw_sql']], ['postgres', ['raw_sql', 'schema_migration_lock']], ['rust', []],+ ]);+ expect([missingCapability('raw_sql'), missingCapability('schema_migration_lock')]).toEqual([+ { kind: 'refuses', label: 'refuses:raw_sql' }, { kind: 'n/a', label: 'n/a:postgres-only' },+ ]);+ });++ test('isCapabilityRefusal accepts only engine_capability_missing naming that capability', () => {+ const refusal = Object.assign(new Error('raw SQL is not available on this engine'), { code: 'engine_capability_missing', reason: 'raw_sql' });+ const viaEnvelope = Object.assign(new Error('x'), { envelope: { code: 'engine_capability_missing', detail: { reason: 'raw_sql' } } });+ expect([+ isCapabilityRefusal(refusal, 'raw_sql'),+ isCapabilityRefusal(viaEnvelope, 'raw_sql'),+ isCapabilityRefusal(refusal, 'schema_migration_lock'),+ isCapabilityRefusal(Object.assign(new Error('x'), { code: 'engine_unavailable', reason: 'raw_sql' }), 'raw_sql'),+ isCapabilityRefusal(new Error('engine_capability_missing raw_sql'), 'raw_sql'),+ isCapabilityRefusal(null, 'raw_sql'),+ ]).toEqual([true, true, false, false, false, false]);+ });+});diff --git a/test/engine-parity/coverage.ts b/test/engine-parity/coverage.tsnew file mode 100644index 0000000000..6c64cde1ba--- /dev/null+++ b/test/engine-parity/coverage.ts@@ -0,0 +1,228 @@+/**+ * BrainEngine parity coverage list generator.+ *+ * bun test/engine-parity/coverage.ts # print the list+ * bun test/engine-parity/coverage.ts --write # refresh test/engine-parity/coverage.tsv+ *+ * Reads the BrainEngine interface (src/core/engine.ts) with the TypeScript+ * compiler API, reads every `parityTest(name, { methods: [...] }, ...)` call+ * in test/engine-parity/*.test.ts, and writes one row per callable interface+ * member: its family, how many parity cases cover it, and whether the legacy+ * Postgres-gated suite (test/e2e/engine-parity*.test.ts) calls it.+ * `coverage.test.ts` fails when the checked-in list is stale.+ *+ * A method counts as covered only through a harness case: those run on every+ * arm (PGLite always, Postgres with DATABASE_URL, Rust later) and the harness+ * proves each declared method was really called.+ *+ * The per-arm columns say what each arm must do for the method: `yes` (runs+ * and is compared), `same` (the Rust arm, once it exists, must return the same+ * answer), `refuses:<capability>` (the arm must throw the typed+ * `engine_capability_missing` refusal) or `n/a:<why>` (the method does not+ * exist on that arm). They come from each case's `requires` declaration and+ * test/engine-parity/arm-capabilities.ts.+ */+import ts from 'typescript';+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';+import { join, relative } from 'node:path';+import { PARITY_ARMS, armHas, missingCapability, type EngineCapability, type ParityArmName } from './arm-capabilities.ts';++const REPO = join(import.meta.dir, '..', '..');+const PARITY_DIR = import.meta.dir;+const LEGACY_DIR = join(REPO, 'test', 'e2e');+// test-reads-source-ok[structural]: the coverage denominator is the declared BrainEngine member list.+const ENGINE_FILE = join(REPO, 'src', 'core', 'engine.ts');+export const COVERAGE_FILE = join(PARITY_DIR, 'coverage.tsv');++/**+ * Method families (research 01 grouping). Every callable BrainEngine member+ * must appear exactly once; the generator throws otherwise, so a new engine+ * method forces a visible family assignment here.+ */+export const FAMILIES: Record<string, readonly string[]> = {+ lifecycle: ['connect', 'disconnect', 'reconnect', 'initSchema', 'holdSchemaMigrationLock', 'transaction', 'transactionDirect',+ 'registerBeforeDisconnect', 'withReservedConnection'],+ pages: ['getPage', 'readPageSnapshot', 'readPageSnapshotsBatch', 'lockPageKeys', 'putPage', 'findDuplicatePage', 'findDuplicatePages',+ 'deletePage', 'deletePages', 'resolveSlugsByPaths', 'softDeletePage', 'softDeletePages', 'restorePage', 'purgeDeletedPages',+ 'listPages', 'findPages', 'countPagesBy', 'resolveSlugs', 'getAllSlugs', 'listAllPageRefs', 'listAllSources', 'updateSourceConfig',+ 'listPrefixSampledPages', 'listCorpusSample'],+ search: ['searchKeyword', 'countKeywordPages', 'searchKeywordPages', 'searchTitles', 'searchVector', 'getEmbeddingsByChunkIds',+ 'searchKeywordChunks'],+ chunks: ['upsertChunks', 'sealChunks', 'getChunks', 'getChunkPage', 'getChunkWindows', 'countStaleChunks', 'sumStaleChunkChars',+ 'setPageEmbeddingSignature', 'invalidateStaleSignatureEmbeddings', 'invalidateContentDriftEmbeddings', 'listStaleChunks',+ 'countChunklessPagesWithContent', 'listChunklessPagesWithContent', 'readEmbeddingStateCounts', 'listEmbeddingStateRows',+ 'deleteChunks', 'getChunksWithEmbeddings'],+ extraction: ['countStalePagesForExtraction', 'listStalePagesForExtraction', 'markPagesExtractedBatch', 'markPagesAttendanceBlocked',+ 'countStaleFrontmatterKeyPages', 'listStaleFrontmatterKeyPages', 'stripStaleFrontmatterKeys'],+ links: ['addLink', 'addLinksBatch', 'replaceDerivedLinks', 'replaceDerivedLinksBatch', 'removeLink', 'removeLinksByPagesAndSource',+ 'getLinks', 'getBacklinks', 'listLinkSources', 'findByTitleFuzzy', 'traverseGraph', 'traversePaths', 'traversePathsDetailed',+ 'relationalFanout', 'relationalChainHop', 'getBacklinkCounts', 'getAdjacencyBoosts', 'getContentFlagsByPageIds',+ 'getUnverifiedExtractionPageIds', 'getPageTimestamps', 'getEffectiveDates', 'getSalienceScores', 'findOrphanPages'],+ tags: ['addTag', 'removeTag', 'getTags'],+ timeline: ['addTimelineEntry', 'addTimelineEntriesBatch', 'getTimeline', 'getTimelineForDate', 'getSince', 'getOnThisDay',+ 'getLastSeen', 'upsertEventProjection'],+ ontology: ['mergeOntologyFact', 'getOntology', 'discoverOntologyDimensions', 'findOntologyConflicts'],+ raw_files: ['putRawData', 'getRawData', 'upsertFile', 'getFile', 'listFilesForPage'],+ takes: ['addTakesBatch', 'updateTakeEmbeddings', 'listTakes', 'searchTakes', 'searchTakesVector', 'getTakeEmbeddings',+ 'countStaleTakes', 'listStaleTakes', 'updateTake', 'supersedeTake', 'resolveTake', 'getScorecard', 'getCalibrationCurve',+ 'addSynthesisEvidence', 'listActiveTakesForPages'],+ dream: ['getDreamVerdict', 'putDreamVerdict', 'sweepDreamVerdicts'],+ contradictions: ['writeContradictionsRun', 'loadContradictionsTrend', 'getContradictionCacheEntry', 'putContradictionCacheEntry',+ 'sweepContradictionCache'],+ facts: ['insertFact', 'insertFacts', 'deleteFactsForPage', 'expireFact', 'listFactsByEntity', 'listFactsSince', 'listFactsKeyset',+ 'listFactsBySession', 'listSupersessions', 'countUnconsolidatedFacts', 'findCandidateDuplicates', 'consolidateFact',+ 'findTrajectory', 'getFactsHealth'],+ segmented_body: ['allocateBodyOccurrenceIds', 'stageSegmentTexts', 'readSegmentTexts', 'stageManifestRows', 'readManifest',+ 'stageSegmentChunks', 'createSegmentedPageShell', 'flipBodyGeneration', 'openBodyStaging', 'setBodyStagingState', 'sweepSegments',+ 'readSegmentDerivations', 'upsertSegmentDerivations', 'retireSegmentDerivations'],+ versions: ['createVersion', 'getVersions', 'revertToVersion'],+ stats_ingest: ['getStats', 'getHealth', 'logIngest', 'getIngestLog'],+ sync_aliases: ['updateSlug', 'rewriteLinks', 'resolveSlugWithAlias', 'resolveSlugWithAliasDetailed', 'resolveAliases',+ 'setPageAliases', 'refreshPageBody', 'updatePageContextualRetrievalState', 'migrateFactsToCanonical'],+ config: ['getConfig', 'setConfig', 'unsetConfig', 'listConfigKeys', 'getAllConfig'],+ raw_sql: ['runMigration', 'executeRaw', 'executeRawDirect', 'keywordBoundedRead'],+ code_edges: ['addCodeEdges', 'deleteCodeEdgesForChunks', 'getCallersOf', 'getCalleesOf', 'getEdgesByChunk'],+ eval_capture: ['logEvalCandidate', 'listEvalCandidates', 'deleteEvalCandidatesBefore', 'logEvalCaptureFailure',+ 'listEvalCaptureFailures'],+ salience_enrich: ['batchLoadEmotionalInputs', 'setEmotionalWeightBatch', 'getRecentSalience', 'listEnrichCandidates', 'findAnomalies'],+};++/** Callable members of `interface BrainEngine`, in declaration order (`kind` excluded). */+export function interfaceMethods(): string[] {+ const text = readFileSync(ENGINE_FILE, 'utf8'); // test-reads-source-ok[structural]: parse the interface member names only.+ const sf = ts.createSourceFile(ENGINE_FILE, text, ts.ScriptTarget.Latest, true);+ const names: string[] = [];+ sf.forEachChild((node) => {+ if (!ts.isInterfaceDeclaration(node) || node.name.text !== 'BrainEngine') return;+ for (const member of node.members) {+ if (!member.name || !ts.isIdentifier(member.name)) continue;+ const callable = ts.isMethodSignature(member)+ || (ts.isPropertySignature(member) && member.type !== undefined && ts.isFunctionTypeNode(member.type));+ if (callable && !names.includes(member.name.text)) names.push(member.name.text);+ }+ });+ if (names.length === 0) throw new Error('engine-parity coverage: BrainEngine interface not found in src/core/engine.ts');+ return names;+}++export interface ParityDeclaration { file: string; name: string; methods: string[]; requires?: EngineCapability }++function stringValue(node: ts.Node): string | null {+ return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : null;+}++/** Every `parityTest(name, { methods: [...] }, fn)` declaration in the parity files. */+export function parityDeclarations(dir = PARITY_DIR): ParityDeclaration[] {+ const out: ParityDeclaration[] = [];+ for (const entry of readdirSync(dir).filter((f) => f.endsWith('.test.ts')).sort()) {+ const path = join(dir, entry);+ const sf = ts.createSourceFile(path, readFileSync(path, 'utf8'), ts.ScriptTarget.Latest, true);+ const visit = (node: ts.Node) => {+ if (ts.isCallExpression(node) && ts.isIdentifier(node.expression) && node.expression.text === 'parityTest') {+ const [nameArg, optsArg] = node.arguments;+ const where = `${relative(REPO, path)}:${sf.getLineAndCharacterOfPosition(node.getStart()).line + 1}`;+ const methodsProp = optsArg && ts.isObjectLiteralExpression(optsArg)+ ? optsArg.properties.find((p) => p.name && ts.isIdentifier(p.name) && p.name.text === 'methods')+ : undefined;+ if (!methodsProp || !ts.isPropertyAssignment(methodsProp) || !ts.isArrayLiteralExpression(methodsProp.initializer)) {+ throw new Error(`${where}: parityTest needs an inline { methods: [...] } array literal`);+ }+ const methods = methodsProp.initializer.elements.map((e) => {+ const value = stringValue(e);+ if (value === null) throw new Error(`${where}: parityTest methods must be string literals`);+ return value;+ });+ const requiresProp = (optsArg as ts.ObjectLiteralExpression).properties+ .find((p) => p.name && ts.isIdentifier(p.name) && p.name.text === 'requires');+ let requires: EngineCapability | undefined;+ if (requiresProp) {+ const value = ts.isPropertyAssignment(requiresProp) ? stringValue(requiresProp.initializer) : null;+ if (value === null) throw new Error(`${where}: parityTest requires must be a string literal`);+ missingCapability(value as EngineCapability); // throws on an unknown capability+ requires = value as EngineCapability;+ }+ out.push({ file: relative(REPO, path), name: (nameArg && stringValue(nameArg)) ?? '<dynamic>', methods, ...(requires && { requires }) });+ }+ ts.forEachChild(node, visit);+ };+ visit(sf);+ }+ return out;+}++/** Interface methods the legacy Postgres-gated parity suite calls (`.name(`). */+export function legacyMethods(methods: readonly string[]): Set<string> {+ const called = new Set<string>();+ const files = readdirSync(LEGACY_DIR).filter((f) => /^engine-parity.*\.test\.ts$/.test(f));+ for (const f of files) {+ const text = readFileSync(join(LEGACY_DIR, f), 'utf8');+ for (const m of methods) if (new RegExp(`\\.${m}\\s*[!?]?\\.?\\s*[(<]`).test(text)) called.add(m);+ }+ return called;+}++export interface CoverageReport { methods: string[]; covered: string[]; text: string }++export function buildCoverage(): CoverageReport {+ const methods = interfaceMethods();+ const family = new Map<string, string>();+ for (const [name, members] of Object.entries(FAMILIES)) {+ for (const m of members) {+ if (family.has(m)) throw new Error(`engine-parity coverage: ${m} is in two families`);+ family.set(m, name);+ }+ }+ const unassigned = methods.filter((m) => !family.has(m));+ const stale = [...family.keys()].filter((m) => !methods.includes(m));+ if (unassigned.length || stale.length) {+ throw new Error(`engine-parity coverage: FAMILIES out of date. Unassigned: ${unassigned.join(', ') || '-'}; not in BrainEngine: ${stale.join(', ') || '-'}`);+ }+ const cases = new Map<string, number>();+ const requirements = new Map<string, Array<EngineCapability | undefined>>();+ for (const decl of parityDeclarations()) {+ for (const m of decl.methods) {+ if (!family.has(m)) throw new Error(`${decl.file} "${decl.name}": ${m} is not a BrainEngine method`);+ cases.set(m, (cases.get(m) ?? 0) + 1);+ requirements.set(m, [...(requirements.get(m) ?? []), decl.requires]);+ }+ }+ /** What `arm` must do for `m`: it runs when any covering case runs there, else the first missing capability's label. */+ const armCell = (m: string, arm: ParityArmName): string => {+ const reqs = requirements.get(m);+ if (!reqs) return '-';+ if (reqs.some((r) => armHas(arm, r))) return arm === 'rust' ? 'same' : 'yes';+ return missingCapability(reqs.find((r) => r !== undefined)!).label;+ };+ const legacy = legacyMethods(methods);+ const covered = methods.filter((m) => cases.has(m));+ const familyOrder = Object.keys(FAMILIES);+ const rows = [...methods].sort((a, b) =>+ familyOrder.indexOf(family.get(a)!) - familyOrder.indexOf(family.get(b)!) || methods.indexOf(a) - methods.indexOf(b));+ const perFamily = familyOrder.map((f) => {+ const members = methods.filter((m) => family.get(m) === f);+ return `# ${f}: ${members.filter((m) => cases.has(m)).length}/${members.length}`;+ });+ const lines = [+ '# BrainEngine parity coverage. GENERATED by `bun test/engine-parity/coverage.ts --write`; do not edit.',+ '# covered = called by a test/engine-parity harness case; the per-arm columns say where that case runs.',+ '# legacy_e2e = called by the Postgres-gated test/e2e/engine-parity*.test.ts suite (informational).',+ '# pglite/postgres/rust = what each arm must do: yes (runs, compared), same (Rust must match once its arm exists),',+ '# refuses:<capability> (throws engine_capability_missing), n/a:<why> (no such member on that arm), - (not covered).',+ `# covered: ${covered.length}/${methods.length}`,+ ...perFamily,+ ['method', 'family', 'covered', 'parity_cases', 'legacy_e2e', ...PARITY_ARMS].join('\t'),+ ...rows.map((m) => [m, family.get(m), cases.has(m) ? 'yes' : 'no', cases.get(m) ?? 0, legacy.has(m) ? 'yes' : 'no',+ ...PARITY_ARMS.map((arm) => armCell(m, arm))].join('\t')),+ ];+ return { methods, covered, text: `${lines.join('\n')}\n` };+}++if (import.meta.main) {+ const report = buildCoverage();+ if (process.argv.includes('--write')) {+ writeFileSync(COVERAGE_FILE, report.text);+ console.log(`wrote ${relative(REPO, COVERAGE_FILE)}: covered ${report.covered.length}/${report.methods.length}`);+ } else {+ process.stdout.write(report.text);+ }+}diff --git a/test/engine-parity/coverage.tsv b/test/engine-parity/coverage.tsvnew file mode 100644index 0000000000..03198cc3fe--- /dev/null+++ b/test/engine-parity/coverage.tsv@@ -0,0 +1,228 @@+# BrainEngine parity coverage. GENERATED by `bun test/engine-parity/coverage.ts --write`; do not edit.+# covered = called by a test/engine-parity harness case; the per-arm columns say where that case runs.+# legacy_e2e = called by the Postgres-gated test/e2e/engine-parity*.test.ts suite (informational).+# pglite/postgres/rust = what each arm must do: yes (runs, compared), same (Rust must match once its arm exists),+# refuses:<capability> (throws engine_capability_missing), n/a:<why> (no such member on that arm), - (not covered).+# covered: 198/198+# lifecycle: 9/9+# pages: 24/24+# search: 7/7+# chunks: 17/17+# extraction: 7/7+# links: 23/23+# tags: 3/3+# timeline: 8/8+# ontology: 4/4+# raw_files: 5/5+# takes: 15/15+# dream: 3/3+# contradictions: 5/5+# facts: 14/14+# segmented_body: 14/14+# versions: 3/3+# stats_ingest: 4/4+# sync_aliases: 9/9+# config: 5/5+# raw_sql: 4/4+# code_edges: 5/5+# eval_capture: 5/5+# salience_enrich: 5/5+method family covered parity_cases legacy_e2e pglite postgres rust+connect lifecycle yes 1 yes yes yes same+disconnect lifecycle yes 1 yes yes yes same+reconnect lifecycle yes 1 no yes yes same+initSchema lifecycle yes 2 yes yes yes same+holdSchemaMigrationLock lifecycle yes 1 no n/a:postgres-only yes n/a:postgres-only+transaction lifecycle yes 8 no yes yes same+transactionDirect lifecycle yes 1 no yes yes same+registerBeforeDisconnect lifecycle yes 2 no yes yes same+withReservedConnection lifecycle yes 1 no yes yes refuses:raw_sql+getPage pages yes 24 yes yes yes same+readPageSnapshot pages yes 6 no yes yes same+readPageSnapshotsBatch pages yes 1 no yes yes same+lockPageKeys pages yes 1 no yes yes same+putPage pages yes 88 yes yes yes same+findDuplicatePage pages yes 1 no yes yes same+findDuplicatePages pages yes 1 no yes yes same+deletePage pages yes 2 yes yes yes same+deletePages pages yes 1 yes yes yes same+resolveSlugsByPaths pages yes 1 yes yes yes same+softDeletePage pages yes 16 yes yes yes same+softDeletePages pages yes 1 yes yes yes same+restorePage pages yes 5 yes yes yes same+purgeDeletedPages pages yes 1 no yes yes same+listPages pages yes 4 yes yes yes same+findPages pages yes 1 no yes yes same+countPagesBy pages yes 1 no yes yes same+resolveSlugs pages yes 2 no yes yes same+getAllSlugs pages yes 4 no yes yes same+listAllPageRefs pages yes 1 yes yes yes same+listAllSources pages yes 2 no yes yes same+updateSourceConfig pages yes 1 no yes yes same+listPrefixSampledPages pages yes 1 no yes yes same+listCorpusSample pages yes 1 no yes yes same+searchKeyword search yes 8 yes yes yes same+countKeywordPages search yes 1 no yes yes same+searchKeywordPages search yes 1 no yes yes same+searchTitles search yes 1 yes yes yes same+searchVector search yes 2 yes yes yes same+getEmbeddingsByChunkIds search yes 1 no yes yes same+searchKeywordChunks search yes 1 yes yes yes same+upsertChunks chunks yes 11 yes yes yes same+sealChunks chunks yes 2 no yes yes same+getChunks chunks yes 14 yes yes yes same+getChunkPage chunks yes 3 no yes yes same+getChunkWindows chunks yes 1 no yes yes same+countStaleChunks chunks yes 5 no yes yes same+sumStaleChunkChars chunks yes 2 no yes yes same+setPageEmbeddingSignature chunks yes 1 no yes yes same+invalidateStaleSignatureEmbeddings chunks yes 1 no yes yes same+invalidateContentDriftEmbeddings chunks yes 1 no yes yes same+listStaleChunks chunks yes 2 no yes yes same+countChunklessPagesWithContent chunks yes 3 yes yes yes same+listChunklessPagesWithContent chunks yes 1 yes yes yes same+readEmbeddingStateCounts chunks yes 1 no yes yes same+listEmbeddingStateRows chunks yes 1 no yes yes same+deleteChunks chunks yes 2 no yes yes same+getChunksWithEmbeddings chunks yes 1 no yes yes same+countStalePagesForExtraction extraction yes 4 yes yes yes same+listStalePagesForExtraction extraction yes 3 yes yes yes same+markPagesExtractedBatch extraction yes 4 yes yes yes same+markPagesAttendanceBlocked extraction yes 1 no yes yes same+countStaleFrontmatterKeyPages extraction yes 1 no yes yes same+listStaleFrontmatterKeyPages extraction yes 1 no yes yes same+stripStaleFrontmatterKeys extraction yes 1 no yes yes same+addLink links yes 17 yes yes yes same+addLinksBatch links yes 1 yes yes yes same+replaceDerivedLinks links yes 1 no yes yes same+replaceDerivedLinksBatch links yes 1 no yes yes same+removeLink links yes 1 no yes yes same+removeLinksByPagesAndSource links yes 1 yes yes yes same+getLinks links yes 9 yes yes yes same+getBacklinks links yes 3 yes yes yes same+listLinkSources links yes 1 yes yes yes same+findByTitleFuzzy links yes 1 no yes yes same+traverseGraph links yes 3 yes yes yes same+traversePaths links yes 3 yes yes yes same+traversePathsDetailed links yes 1 yes yes yes same+relationalFanout links yes 1 yes yes yes same+relationalChainHop links yes 1 no yes yes same+getBacklinkCounts links yes 1 no yes yes same+getAdjacencyBoosts links yes 1 no yes yes same+getContentFlagsByPageIds links yes 1 no yes yes same+getUnverifiedExtractionPageIds links yes 1 no yes yes same+getPageTimestamps links yes 1 no yes yes same+getEffectiveDates links yes 1 no yes yes same+getSalienceScores links yes 1 yes yes yes same+findOrphanPages links yes 1 yes yes yes same+addTag tags yes 5 yes yes yes same+removeTag tags yes 1 no yes yes same+getTags tags yes 1 yes yes yes same+addTimelineEntry timeline yes 5 yes yes yes same+addTimelineEntriesBatch timeline yes 1 no yes yes same+getTimeline timeline yes 3 yes yes yes same+getTimelineForDate timeline yes 2 no yes yes same+getSince timeline yes 1 no yes yes same+getOnThisDay timeline yes 1 no yes yes same+getLastSeen timeline yes 1 no yes yes same+upsertEventProjection timeline yes 4 no yes yes same+mergeOntologyFact ontology yes 4 no yes yes same+getOntology ontology yes 2 no yes yes same+discoverOntologyDimensions ontology yes 1 no yes yes same+findOntologyConflicts ontology yes 1 no yes yes same+putRawData raw_files yes 2 yes yes yes same+getRawData raw_files yes 2 yes yes yes same+upsertFile raw_files yes 2 no yes yes same+getFile raw_files yes 2 no yes yes same+listFilesForPage raw_files yes 1 no yes yes same+addTakesBatch takes yes 19 yes yes yes same+updateTakeEmbeddings takes yes 1 no yes yes same+listTakes takes yes 11 no yes yes same+searchTakes takes yes 1 no yes yes same+searchTakesVector takes yes 1 no yes yes same+getTakeEmbeddings takes yes 1 no yes yes same+countStaleTakes takes yes 1 no yes yes same+listStaleTakes takes yes 1 no yes yes same+updateTake takes yes 1 no yes yes same+supersedeTake takes yes 1 no yes yes same+resolveTake takes yes 5 no yes yes same+getScorecard takes yes 1 no yes yes same+getCalibrationCurve takes yes 1 no yes yes same+addSynthesisEvidence takes yes 1 no yes yes same+listActiveTakesForPages takes yes 2 no yes yes same+getDreamVerdict dream yes 1 yes yes yes same+putDreamVerdict dream yes 1 yes yes yes same+sweepDreamVerdicts dream yes 1 no yes yes same+writeContradictionsRun contradictions yes 1 no yes yes same+loadContradictionsTrend contradictions yes 1 no yes yes same+getContradictionCacheEntry contradictions yes 1 no yes yes same+putContradictionCacheEntry contradictions yes 1 no yes yes same+sweepContradictionCache contradictions yes 1 no yes yes same+insertFact facts yes 20 yes yes yes same+insertFacts facts yes 4 no yes yes same+deleteFactsForPage facts yes 2 no yes yes same+expireFact facts yes 8 no yes yes same+listFactsByEntity facts yes 10 yes yes yes same+listFactsSince facts yes 3 yes yes yes same+listFactsKeyset facts yes 2 no yes yes same+listFactsBySession facts yes 2 yes yes yes same+listSupersessions facts yes 4 yes yes yes same+countUnconsolidatedFacts facts yes 2 yes yes yes same+findCandidateDuplicates facts yes 3 yes yes yes same+consolidateFact facts yes 3 no yes yes same+findTrajectory facts yes 1 yes yes yes same+getFactsHealth facts yes 2 yes yes yes same+allocateBodyOccurrenceIds segmented_body yes 1 no yes yes same+stageSegmentTexts segmented_body yes 1 no yes yes same+readSegmentTexts segmented_body yes 2 no yes yes same+stageManifestRows segmented_body yes 1 no yes yes same+readManifest segmented_body yes 3 no yes yes same+stageSegmentChunks segmented_body yes 1 no yes yes same+createSegmentedPageShell segmented_body yes 1 no yes yes same+flipBodyGeneration segmented_body yes 2 no yes yes same+openBodyStaging segmented_body yes 2 no yes yes same+setBodyStagingState segmented_body yes 1 no yes yes same+sweepSegments segmented_body yes 1 no yes yes same+readSegmentDerivations segmented_body yes 1 no yes yes same+upsertSegmentDerivations segmented_body yes 1 no yes yes same+retireSegmentDerivations segmented_body yes 1 no yes yes same+createVersion versions yes 4 no yes yes same+getVersions versions yes 3 no yes yes same+revertToVersion versions yes 2 no yes yes same+getStats stats_ingest yes 2 yes yes yes same+getHealth stats_ingest yes 2 yes yes yes same+logIngest stats_ingest yes 1 no yes yes same+getIngestLog stats_ingest yes 1 no yes yes same+updateSlug sync_aliases yes 4 no yes yes same+rewriteLinks sync_aliases yes 1 no yes yes same+resolveSlugWithAlias sync_aliases yes 1 yes yes yes same+resolveSlugWithAliasDetailed sync_aliases yes 1 yes yes yes same+resolveAliases sync_aliases yes 1 no yes yes same+setPageAliases sync_aliases yes 1 no yes yes same+refreshPageBody sync_aliases yes 1 no yes yes same+updatePageContextualRetrievalState sync_aliases yes 1 no yes yes same+migrateFactsToCanonical sync_aliases yes 1 no yes yes same+getConfig config yes 4 no yes yes same+setConfig config yes 7 no yes yes same+unsetConfig config yes 2 no yes yes same+listConfigKeys config yes 2 no yes yes same+getAllConfig config yes 1 no yes yes same+runMigration raw_sql yes 1 no yes yes refuses:raw_sql+executeRaw raw_sql yes 2 yes yes yes refuses:raw_sql+executeRawDirect raw_sql yes 1 no yes yes refuses:raw_sql+keywordBoundedRead raw_sql yes 1 no yes yes refuses:raw_sql+addCodeEdges code_edges yes 3 yes yes yes same+deleteCodeEdgesForChunks code_edges yes 1 no yes yes same+getCallersOf code_edges yes 3 no yes yes same+getCalleesOf code_edges yes 2 yes yes yes same+getEdgesByChunk code_edges yes 2 no yes yes same+logEvalCandidate eval_capture yes 2 no yes yes same+listEvalCandidates eval_capture yes 2 no yes yes same+deleteEvalCandidatesBefore eval_capture yes 1 no yes yes same+logEvalCaptureFailure eval_capture yes 1 no yes yes same+listEvalCaptureFailures eval_capture yes 1 no yes yes same+batchLoadEmotionalInputs salience_enrich yes 1 no yes yes same+setEmotionalWeightBatch salience_enrich yes 2 yes yes yes same+getRecentSalience salience_enrich yes 1 yes yes yes same+listEnrichCandidates salience_enrich yes 1 yes yes yes same+findAnomalies salience_enrich yes 1 yes yes yes samediff --git a/test/engine-parity/extraction.test.ts b/test/engine-parity/extraction.test.tsnew file mode 100644index 0000000000..159d598d15--- /dev/null+++ b/test/engine-parity/extraction.test.ts@@ -0,0 +1,326 @@+/**+ * BrainEngine parity — extraction family (link/timeline extraction freshness+ * watermark, attendance-blocked marker, stale reserved frontmatter keys).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every extraction-watermark method returns the same observable+ * result on every engine arm (PGLite always; Postgres with DATABASE_URL; a+ * Rust arm later through test/engine-parity/harness.ts): which pages are+ * stale, how a stamp or an attendance block changes that, and which pages+ * still carry a parser-reserved frontmatter key.+ * - Regression: an engine that drifts on the stale predicate (NULL stamp,+ * older than the extractor version, edited since the stamp, soft-deleted or+ * quarantined pages) makes `gbrain extract --stale` and the+ * `links_extraction_lag` doctor check re-extract a whole brain or never+ * extract an edited page.+ * - Why existing coverage misses it: the per-engine extraction tests never+ * compare two engines on one scenario, and test/e2e/engine-parity.test.ts+ * does not touch the watermark.+ * - Seam: none. Typed methods only (no executeRaw: D18). Timestamps are fixed+ * far-future ISO strings so the cases do not depend on the wall clock.+ * A `held` failure record and `wanted_links` rows have no typed writer, so+ * those arms of the predicate are covered only as "no effect when absent".+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import type { PageInput } from '../../src/core/types.ts';+import { createSource, parityArms, pick } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++/** Stamped far in the future: always at or after updated_at, so the page reads fresh. */+const FRESH = '2099-01-01T00:00:00.000Z';+/** Stamped far in the past: always before updated_at, so the page reads edited-since-stamp. */+const OLD = '2000-01-01T00:00:00.000Z';+/** An extractor version newer than FRESH, then older than FRESH. */+const VERSION_AFTER_FRESH = '2100-01-01T00:00:00.000Z';+const VERSION_BEFORE_FRESH = '2098-01-01T00:00:00.000Z';+const NO_SUCH_REVISION = '00000000-0000-0000-0000-000000000000';++const page = (title: string, body = `${title} body`, frontmatter: Record<string, unknown> = {}): PageInput => ({+ type: 'note',+ title,+ compiled_truth: body,+ timeline: '',+ frontmatter,+});++async function put(engine: BrainEngine, slug: string, input: PageInput, sourceId?: string) {+ return engine.putPage(slug, input, sourceId ? { sourceId } : undefined);+}++describe('engine parity: extraction', () => {+ parityTest(+ 'countStalePagesForExtraction: NULL stamp, older-than-version and edited-since-stamp are stale; deleted and quarantined are not',+ { methods: ['putPage', 'markPagesExtractedBatch', 'softDeletePage', 'countStalePagesForExtraction', 'listStalePagesForExtraction'] },+ async (engine) => {+ await put(engine, 'notes/never', page('Never'));+ await put(engine, 'notes/fresh', page('Fresh'));+ await put(engine, 'notes/edited', page('Edited'));+ await put(engine, 'notes/gone', page('Gone'));+ await put(engine, 'notes/quarantined', page('Quarantined', 'q body', { quarantine: { reason: 'junk' } }));+ await engine.softDeletePage('notes/gone');++ const stale = async (versionTs?: string) => ({+ count: await engine.countStalePagesForExtraction(versionTs ? { versionTs } : undefined),+ slugs: (await engine.listStalePagesForExtraction({ batchSize: 50, ...(versionTs ? { versionTs } : {}) })).map((r) => r.slug),+ });++ // Nothing stamped: every live, non-quarantined page is stale.+ const unstamped = await stale();+ expect(unstamped).toEqual({ count: 3, slugs: ['notes/never', 'notes/fresh', 'notes/edited'] });++ const stamped = await engine.markPagesExtractedBatch(+ [{ slug: 'notes/fresh', source_id: 'default' }, { slug: 'notes/edited', source_id: 'default', extractedAt: OLD }],+ FRESH,+ );+ expect(stamped).toBe(2);++ // A far-future stamp is fresh; a far-past stamp is "edited since the stamp".+ const afterStamp = await stale();+ expect(afterStamp).toEqual({ count: 2, slugs: ['notes/never', 'notes/edited'] });+ // With an extractor version: the future stamp is still fresh against an older version...+ const olderVersion = await stale(VERSION_BEFORE_FRESH);+ expect(olderVersion).toEqual({ count: 2, slugs: ['notes/never', 'notes/edited'] });+ // ...and stale against a newer one.+ const newerVersion = await stale(VERSION_AFTER_FRESH);+ expect(newerVersion).toEqual({ count: 3, slugs: ['notes/never', 'notes/fresh', 'notes/edited'] });++ // Re-stamping the edited page clears it.+ expect(await engine.markPagesExtractedBatch([{ slug: 'notes/edited', source_id: 'default' }], FRESH)).toBe(1);+ const restamped = await stale();+ expect(restamped).toEqual({ count: 1, slugs: ['notes/never'] });++ return { unstamped, stamped, afterStamp, olderVersion, newerVersion, restamped };+ },+ );++ parityTest(+ 'listStalePagesForExtraction pages by id keyset, scopes by source and carries the page content',+ { methods: ['putPage', 'markPagesExtractedBatch', 'countStalePagesForExtraction', 'listStalePagesForExtraction'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'work');+ const a = await put(engine, 'notes/a', { ...page('A', 'alpha body', { mood: 'calm' }), timeline: '- 2026-01-01: alpha line' });+ await put(engine, 'notes/b', page('B'));+ await put(engine, 'notes/c', page('C'));+ await put(engine, 'notes/work-only', page('Work only'), 'work');++ const rows = await engine.listStalePagesForExtraction({ batchSize: 50 });+ const first = rows.find((r) => r.slug === 'notes/a')!;+ expect(first.id).toBe(a.id);+ const view = pick(first, ['slug', 'source_id', 'type', 'title', 'compiled_truth', 'timeline', 'frontmatter']);+ expect(view).toEqual({+ slug: 'notes/a',+ source_id: 'default',+ type: 'note',+ title: 'A',+ compiled_truth: 'alpha body',+ timeline: '- 2026-01-01: alpha line',+ frontmatter: { mood: 'calm' },+ });+ // The stamp-back string is a full-precision UTC ISO string.+ const isoShape = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z$/.test(first.updated_at_iso);+ expect(isoShape).toBe(true);++ const slugsOf = (list: Array<{ slug: string }>) => list.map((r) => r.slug);+ const pageOne = await engine.listStalePagesForExtraction({ batchSize: 2 });+ const pageTwo = await engine.listStalePagesForExtraction({ batchSize: 2, afterPageId: pageOne[pageOne.length - 1]!.id });+ const pageThree = await engine.listStalePagesForExtraction({ batchSize: 2, afterPageId: pageTwo[pageTwo.length - 1]!.id });+ expect([slugsOf(pageOne), slugsOf(pageTwo), slugsOf(pageThree)]).toEqual([+ ['notes/a', 'notes/b'],+ ['notes/c', 'notes/work-only'],+ [],+ ]);++ const work = slugsOf(await engine.listStalePagesForExtraction({ batchSize: 50, sourceId: 'work' }));+ const defaultSource = slugsOf(await engine.listStalePagesForExtraction({ batchSize: 50, sourceId: 'default' }));+ const counts = {+ all: await engine.countStalePagesForExtraction(),+ work: await engine.countStalePagesForExtraction({ sourceId: 'work' }),+ default: await engine.countStalePagesForExtraction({ sourceId: 'default' }),+ };+ expect(work).toEqual(['notes/work-only']);+ expect(defaultSource).toEqual(['notes/a', 'notes/b', 'notes/c']);+ expect(counts).toEqual({ all: 4, work: 1, default: 3 });++ // `held: 'exclude'` and `wantedProducers` change nothing while no page is held and no wanted link exists.+ const heldExclude = await engine.countStalePagesForExtraction({ held: 'exclude' });+ const noWanted = await engine.countStalePagesForExtraction({ wantedProducers: ['nobody'] });+ const heldOnly = await engine.countStalePagesForExtraction({ held: 'only' });+ expect({ heldExclude, noWanted, heldOnly }).toEqual({ heldExclude: 4, noWanted: 4, heldOnly: 0 });++ // A stamp in one source leaves the other alone.+ await engine.markPagesExtractedBatch([{ slug: 'notes/work-only', source_id: 'work' }], FRESH);+ const afterWorkStamp = {+ all: await engine.countStalePagesForExtraction(),+ work: await engine.countStalePagesForExtraction({ sourceId: 'work' }),+ };+ expect(afterWorkStamp).toEqual({ all: 3, work: 0 });+ return { view, pages: [slugsOf(pageOne), slugsOf(pageTwo), slugsOf(pageThree)], work, defaultSource, counts, heldExclude, noWanted, heldOnly, afterWorkStamp };+ },+ );++ parityTest(+ 'markPagesExtractedBatch returns the rows stamped: wrong-source and unknown refs match nothing, empty input is 0',+ { methods: ['putPage', 'markPagesExtractedBatch', 'countStalePagesForExtraction'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'work');+ await put(engine, 'notes/shared', page('Shared'));+ await put(engine, 'notes/shared', page('Shared (work)'), 'work');+ await put(engine, 'notes/solo', page('Solo'));++ const empty = await engine.markPagesExtractedBatch([], FRESH);+ const wrongSource = await engine.markPagesExtractedBatch([{ slug: 'notes/solo', source_id: 'work' }], FRESH);+ const unknown = await engine.markPagesExtractedBatch([{ slug: 'notes/nope', source_id: 'default' }], FRESH);+ const beforeAny = {+ all: await engine.countStalePagesForExtraction(),+ };+ // One real ref, one wrong-source ref, one unknown ref: only the real one stamps.+ const mixed = await engine.markPagesExtractedBatch(+ [+ { slug: 'notes/solo', source_id: 'default' },+ { slug: 'notes/solo', source_id: 'work' },+ { slug: 'notes/nope', source_id: 'default' },+ ],+ FRESH,+ );+ // The same slug in two sources stamps per (slug, source_id), not per slug.+ const oneSource = await engine.markPagesExtractedBatch([{ slug: 'notes/shared', source_id: 'work' }], FRESH);+ const after = {+ all: await engine.countStalePagesForExtraction(),+ default: await engine.countStalePagesForExtraction({ sourceId: 'default' }),+ work: await engine.countStalePagesForExtraction({ sourceId: 'work' }),+ };+ expect({ empty, wrongSource, unknown, beforeAny, mixed, oneSource, after }).toEqual({+ empty: 0,+ wrongSource: 0,+ unknown: 0,+ beforeAny: { all: 3 },+ mixed: 1,+ oneSource: 1,+ after: { all: 1, default: 1, work: 0 },+ });+ return { empty, wrongSource, unknown, beforeAny, mixed, oneSource, after };+ },+ );++ parityTest(+ 'markPagesAttendanceBlocked marks a page at its revision; attendance narrows the stale set and an edit releases it',+ {+ methods: ['putPage', 'markPagesAttendanceBlocked', 'markPagesExtractedBatch', 'softDeletePage', 'countStalePagesForExtraction', 'listStalePagesForExtraction'],+ },+ async (engine) => {+ const a = await put(engine, 'notes/a', page('A'));+ const b = await put(engine, 'notes/b', page('B'));+ const c = await put(engine, 'notes/c', page('C'));+ await put(engine, 'notes/d', page('D'));+ for (const p of [a, b, c]) expect(typeof p.knowledge_revision).toBe('string');++ const counts = async () => ({+ all: await engine.countStalePagesForExtraction(),+ exclude: await engine.countStalePagesForExtraction({ attendance: 'exclude' }),+ blocked: await engine.countStalePagesForExtraction({ attendance: 'blocked' }),+ });+ const slugsExcluding = async () => (await engine.listStalePagesForExtraction({ batchSize: 50 })).map((r) => r.slug);+ const before = await counts();+ expect(before).toEqual({ all: 4, exclude: 4, blocked: 0 });++ // A stale revision marks nothing; an empty list marks nothing.+ const staleRevision = await engine.markPagesAttendanceBlocked([{ slug: 'notes/a', source_id: 'default', revision: NO_SUCH_REVISION }]);+ const empty = await engine.markPagesAttendanceBlocked([]);+ expect({ staleRevision, empty }).toEqual({ staleRevision: 0, empty: 0 });++ // Current revisions mark; a wrong-source ref and an unknown ref do not.+ const marked = await engine.markPagesAttendanceBlocked([+ { slug: 'notes/a', source_id: 'default', revision: a.knowledge_revision! },+ { slug: 'notes/b', source_id: 'default', revision: b.knowledge_revision! },+ { slug: 'notes/c', source_id: 'other', revision: c.knowledge_revision! },+ { slug: 'notes/nope', source_id: 'default', revision: a.knowledge_revision! },+ ]);+ expect(marked).toBe(2);+ const afterMark = await counts();+ expect(afterMark).toEqual({ all: 4, exclude: 2, blocked: 2 });+ // Plain listing (extraction itself) still sees the blocked pages.+ const listed = await slugsExcluding();+ expect(listed).toEqual(['notes/a', 'notes/b', 'notes/c', 'notes/d']);++ // A soft-deleted page cannot be marked.+ await engine.softDeletePage('notes/c');+ const deletedMark = await engine.markPagesAttendanceBlocked([{ slug: 'notes/c', source_id: 'default', revision: c.knowledge_revision! }]);+ expect(deletedMark).toBe(0);++ // An edit moves the revision past the marker: the page is stale and unblocked again.+ await put(engine, 'notes/a', page('A', 'A body, edited'));+ const afterEdit = await counts();+ expect(afterEdit).toEqual({ all: 3, exclude: 2, blocked: 1 });++ // Stamping publishes the page's links, which clears the marker with the watermark.+ const stamped = await engine.markPagesExtractedBatch([{ slug: 'notes/b', source_id: 'default' }], FRESH);+ expect(stamped).toBe(1);+ const afterStamp = await counts();+ expect(afterStamp).toEqual({ all: 2, exclude: 2, blocked: 0 });+ return { before, staleRevision, empty, marked, afterMark, listed, deletedMark, afterEdit, stamped, afterStamp };+ },+ );++ parityTest(+ 'countStaleFrontmatterKeyPages, listStaleFrontmatterKeyPages and stripStaleFrontmatterKeys sweep parser-reserved keys per source',+ {+ methods: ['putPage', 'softDeletePage', 'getPage', 'countStaleFrontmatterKeyPages', 'listStaleFrontmatterKeyPages', 'stripStaleFrontmatterKeys'],+ },+ async (engine, backend) => {+ await createSource(engine, backend, 'work');+ const typed = await put(engine, 'notes/typed', page('Typed', 'b', { type: 'person', mood: 'calm' }));+ const multi = await put(engine, 'notes/multi', page('Multi', 'b', { title: 'T', tags: ['x'], slug: 's', keep: 1 }));+ await put(engine, 'notes/clean', page('Clean', 'b', { mood: 'calm' }));+ const gone = await put(engine, 'notes/gone', page('Gone', 'b', { slug: 'x' }));+ const work = await put(engine, 'notes/work-typed', page('Work typed', 'b', { tags: ['w'] }), 'work');+ await engine.softDeletePage('notes/gone');+ const slugById = new Map<number, string>([+ [typed.id, 'notes/typed'],+ [multi.id, 'notes/multi'],+ [gone.id, 'notes/gone'],+ [work.id, 'notes/work-typed'],+ ]);++ const counts = await engine.countStaleFrontmatterKeyPages({ sourceIds: ['default', 'work', 'absent'] });+ const noSources = await engine.countStaleFrontmatterKeyPages({ sourceIds: [] });+ expect({ counts, noSources }).toEqual({+ counts: [{ source_id: 'default', n: 2 }, { source_id: 'work', n: 1 }],+ noSources: [],+ });++ const listed = await engine.listStaleFrontmatterKeyPages({ sourceId: 'default', afterId: 0, limit: 10 });+ const view = listed.map((r) => ({ slug: r.slug, keys: r.keys, mapped: slugById.get(r.id) }));+ expect(view).toEqual([+ { slug: 'notes/typed', keys: ['type'], mapped: 'notes/typed' },+ { slug: 'notes/multi', keys: ['slug', 'tags', 'title'], mapped: 'notes/multi' },+ ]);+ const firstOnly = await engine.listStaleFrontmatterKeyPages({ sourceId: 'default', afterId: 0, limit: 1 });+ const rest = await engine.listStaleFrontmatterKeyPages({ sourceId: 'default', afterId: firstOnly[0]!.id, limit: 10 });+ const paged = [firstOnly.map((r) => r.slug), rest.map((r) => r.slug)];+ expect(paged).toEqual([['notes/typed'], ['notes/multi']]);++ // Stripping is source-scoped: an id from another source, a soft-deleted page and an empty list change nothing.+ const crossSource = await engine.stripStaleFrontmatterKeys({ sourceId: 'default', ids: [work.id] });+ const deleted = await engine.stripStaleFrontmatterKeys({ sourceId: 'default', ids: [gone.id] });+ const emptyIds = await engine.stripStaleFrontmatterKeys({ sourceId: 'default', ids: [] });+ expect({ crossSource, deleted, emptyIds }).toEqual({ crossSource: 0, deleted: 0, emptyIds: 0 });++ const stripped = await engine.stripStaleFrontmatterKeys({ sourceId: 'default', ids: [typed.id, multi.id] });+ expect(stripped).toBe(2);+ const afterStrip = await engine.countStaleFrontmatterKeyPages({ sourceIds: ['default', 'work'] });+ expect(afterStrip).toEqual([{ source_id: 'work', n: 1 }]);+ // Only the reserved keys go; other keys stay.+ const typedPage = await engine.getPage('notes/typed');+ const multiPage = await engine.getPage('notes/multi');+ const frontmatter = { typed: typedPage?.frontmatter, multi: multiPage?.frontmatter };+ expect(frontmatter).toEqual({ typed: { mood: 'calm' }, multi: { keep: 1 } });+ // A second sweep finds nothing left to change.+ const again = await engine.stripStaleFrontmatterKeys({ sourceId: 'default', ids: [typed.id, multi.id] });+ expect(again).toBe(0);+ return { counts, noSources, view, paged, crossSource, deleted, emptyIds, stripped, afterStrip, frontmatter, again };+ },+ );+});diff --git a/test/engine-parity/facts.test.ts b/test/engine-parity/facts.test.tsnew file mode 100644index 0000000000..545e683f16--- /dev/null+++ b/test/engine-parity/facts.test.ts@@ -0,0 +1,791 @@+/**+ * BrainEngine parity — facts family (the `remember` / `forget` memory verbs).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every hot-memory fact method (insert, supersede/expire, the+ * list-by-entity/since/session reads, keyset paging, fence batch insert,+ * candidate search, consolidation, trajectory, health) returns the same+ * observable result on every engine arm (PGLite always; Postgres with+ * DATABASE_URL; a Rust arm later through test/engine-parity/harness.ts).+ * - Regression: an engine that drifts on which facts a `recall` sees (active+ * vs expired vs validity-lapsed), on the order or paging of a list, or on+ * what `forget` / supersede leaves behind: the memory a personal brain+ * answers from.+ * - Why existing coverage misses it: the per-engine fact tests each run one+ * engine, and test/e2e/engine-parity*.test.ts skips without Postgres and+ * has no facts scenario; nothing compares two engines on one fact history.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine, FactRow } from '../../src/core/engine.ts';+import { basisEmbedding, parityArms, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const SRC = 'default';+const iso = (d: Date | null | undefined) => (d ? d.toISOString() : null);+const at = (s: string) => new Date(s);++/** Fact ids are not comparable across arms (sequences are not reset): name them by fact text. */+function namer(rows: Array<{ id: number; fact: string }>) {+ const names = new Map<number, string>();+ for (const r of rows) names.set(r.id, r.fact);+ return (id: number | null | undefined) => (id == null ? null : (names.get(id) ?? '<unknown-id>'));+}++function view(row: FactRow, name: (id: number | null) => string | null) {+ return {+ fact: row.fact,+ entity: row.entity_slug,+ kind: row.kind,+ visibility: row.visibility,+ notability: row.notability,+ context: row.context,+ valid_from: iso(row.valid_from),+ valid_until: iso(row.valid_until),+ expired: row.expired_at instanceof Date,+ superseded_by: name(row.superseded_by),+ consolidated: row.consolidated_at instanceof Date,+ source: row.source,+ session: row.source_session,+ confidence: row.confidence,+ attributed_to: row.attributed_to ?? null,+ };+}++const texts = (rows: FactRow[]) => rows.map((r) => r.fact);++/** Insert facts one by one (so created_at and ids follow the array order). */+async function remember(+ engine: BrainEngine,+ entity: string | null,+ facts: Array<Partial<Parameters<BrainEngine['insertFact']>[0]> & { fact: string }>,+) {+ const ids = new Map<string, number>();+ for (const f of facts) {+ const r = await engine.insertFact({ entity_slug: entity, source: 'mcp:remember', ...f }, { source_id: SRC });+ expect(r.status).toBe('inserted');+ ids.set(f.fact, r.id);+ }+ return ids;+}++describe('engine parity: facts', () => {+ parityTest(+ 'insertFact stores defaults and every supplied field; listFactsByEntity reads it back',+ { methods: ['insertFact', 'listFactsByEntity'] },+ async (engine) => {+ const plain = await engine.insertFact({ fact: 'Alice prefers async standups', entity_slug: 'people/alice-example', source: 'mcp:remember', valid_from: at('2026-01-15T00:00:00Z') }, { source_id: SRC });+ expect(plain.status).toBe('inserted');+ const full = await engine.insertFact(+ {+ fact: 'Alice owns the Q3 roadmap',+ entity_slug: 'people/alice-example',+ kind: 'commitment',+ visibility: 'world',+ notability: 'high',+ context: 'said in the Monday sync',+ valid_from: at('2026-02-01T00:00:00Z'),+ source: 'cli:think',+ source_session: 'sess-1',+ confidence: 0.75,+ attributed_to: 'user',+ },+ { source_id: SRC },+ );+ const rows = await engine.listFactsByEntity(SRC, 'people/alice-example');+ const name = namer([+ { id: plain.id, fact: 'Alice prefers async standups' },+ { id: full.id, fact: 'Alice owns the Q3 roadmap' },+ ]);+ const byText = Object.fromEntries(rows.map((r) => [r.fact, view(r, name)]));+ // defaults+ expect(byText['Alice prefers async standups']).toMatchObject({+ kind: 'fact', visibility: 'private', notability: 'medium', context: null, valid_until: null,+ expired: false, superseded_by: null, consolidated: false, session: null, confidence: 1, attributed_to: null,+ });+ // supplied+ expect(byText['Alice owns the Q3 roadmap']).toMatchObject({+ kind: 'commitment', visibility: 'world', notability: 'high', context: 'said in the Monday sync',+ valid_from: '2026-02-01T00:00:00.000Z', source: 'cli:think', session: 'sess-1', confidence: 0.75, attributed_to: 'user',+ });+ // another entity and another source see nothing+ expect(await engine.listFactsByEntity(SRC, 'people/bob-example')).toEqual([]);+ return { byText, order: texts(rows) };+ },+ );++ parityTest(+ 'listFactsByEntity orders newest valid_from first and pages with limit/offset',+ { methods: ['insertFact', 'listFactsByEntity'] },+ async (engine) => {+ await remember(engine, 'companies/acme-example', [+ { fact: 'f-jan', valid_from: at('2026-01-01T00:00:00Z') },+ { fact: 'f-mar', valid_from: at('2026-03-01T00:00:00Z') },+ { fact: 'f-feb', valid_from: at('2026-02-01T00:00:00Z') },+ { fact: 'f-apr', valid_from: at('2026-04-01T00:00:00Z') },+ ]);+ const all = texts(await engine.listFactsByEntity(SRC, 'companies/acme-example'));+ expect(all).toEqual(['f-apr', 'f-mar', 'f-feb', 'f-jan']);+ const page1 = texts(await engine.listFactsByEntity(SRC, 'companies/acme-example', { limit: 2 }));+ const page2 = texts(await engine.listFactsByEntity(SRC, 'companies/acme-example', { limit: 2, offset: 2 }));+ const past = texts(await engine.listFactsByEntity(SRC, 'companies/acme-example', { limit: 2, offset: 4 }));+ expect(page1).toEqual(['f-apr', 'f-mar']);+ expect(page2).toEqual(['f-feb', 'f-jan']);+ expect(past).toEqual([]);+ return { all, page1, page2, past };+ },+ );++ parityTest(+ 'listFactsByEntity filters by kind, visibility, session, grep (wildcards literal) and consolidation',+ { methods: ['insertFact', 'listFactsByEntity', 'consolidateFact', 'addTakesBatch', 'putPage', 'listTakes'] },+ async (engine) => {+ const ent = 'people/carol-example';+ const ids = await remember(engine, ent, [+ { fact: 'Carol likes tea', kind: 'preference', visibility: 'private', source_session: 's-a', valid_from: at('2026-01-01T00:00:00Z') },+ { fact: 'Carol shipped v2', kind: 'event', visibility: 'world', source_session: 's-b', valid_from: at('2026-01-02T00:00:00Z') },+ { fact: 'Carol is 100% remote', kind: 'fact', visibility: 'world', source_session: 's-a', valid_from: at('2026-01-03T00:00:00Z') },+ { fact: 'Carol is 1000 miles away', kind: 'fact', visibility: 'private', valid_from: at('2026-01-04T00:00:00Z') },+ { fact: 'Carol under_score name', kind: 'belief', visibility: 'private', valid_from: at('2026-01-05T00:00:00Z') },+ ]);+ const q = async (opts?: Parameters<BrainEngine['listFactsByEntity']>[2]) => texts(await engine.listFactsByEntity(SRC, ent, opts));+ const kindPref = await q({ kinds: ['preference'] });+ const kindTwo = await q({ kinds: ['event', 'belief'] });+ const world = await q({ visibility: ['world'] });+ const priv = await q({ visibility: ['private'] });+ const session = await q({ sessionId: 's-a' });+ const grepCase = await q({ grep: 'SHIPPED' });+ const grepPercent = await q({ grep: '100%' });+ const grepUnderscore = await q({ grep: 'under_score' });+ const grepBlank = await q({ grep: ' ' });+ expect(kindPref).toEqual(['Carol likes tea']);+ expect(kindTwo).toEqual(['Carol under_score name', 'Carol shipped v2']);+ expect(world).toEqual(['Carol is 100% remote', 'Carol shipped v2']);+ expect(priv).toEqual(['Carol under_score name', 'Carol is 1000 miles away', 'Carol likes tea']);+ expect(session).toEqual(['Carol is 100% remote', 'Carol likes tea']);+ expect(grepCase).toEqual(['Carol shipped v2']);+ expect(grepPercent).toEqual(['Carol is 100% remote']);+ expect(grepUnderscore).toEqual(['Carol under_score name']);+ expect(grepBlank).toHaveLength(5);++ // consolidation: promote one fact into a take, then hide consolidated rows+ const page = await engine.putPage('people/carol-example', { type: 'person', title: 'Carol Example', compiled_truth: 'Carol.', timeline: '' });+ await engine.addTakesBatch([{ page_id: page.id, row_num: 1, claim: 'Carol prefers tea', kind: 'fact', holder: 'people/carol-example' }]);+ const [take] = await engine.listTakes({ page_id: page.id });+ await engine.consolidateFact(ids.get('Carol likes tea')!, take.id);+ const unconsolidated = await q({ unconsolidatedOnly: true });+ const everything = await engine.listFactsByEntity(SRC, ent);+ const tea = everything.find((r) => r.fact === 'Carol likes tea')!;+ expect(unconsolidated).not.toContain('Carol likes tea');+ expect(unconsolidated).toHaveLength(4);+ expect(tea.consolidated_at).toBeInstanceOf(Date);+ expect(tea.consolidated_into).toBe(take.id);+ return { kindPref, kindTwo, world, priv, session, grepCase, grepPercent, grepUnderscore, grepBlank: grepBlank.length, unconsolidated };+ },+ );++ parityTest(+ 'expireFact (forget) hides a fact from active reads, keeps history, and is idempotent',+ { methods: ['insertFact', 'expireFact', 'listFactsByEntity', 'getFactsHealth'] },+ async (engine) => {+ const ent = 'people/dana-example';+ const ids = await remember(engine, ent, [+ { fact: 'Dana lives in Austin', valid_from: at('2026-01-01T00:00:00Z') },+ { fact: 'Dana works at Acme', valid_from: at('2026-01-02T00:00:00Z') },+ { fact: 'Dana likes jazz', valid_from: at('2026-01-03T00:00:00Z') },+ ]);+ const name = namer([...ids].map(([fact, id]) => ({ id, fact })));+ const first = await engine.expireFact(ids.get('Dana lives in Austin')!, { at: at('2026-06-01T00:00:00Z') });+ const second = await engine.expireFact(ids.get('Dana lives in Austin')!);+ const missing = await engine.expireFact(999999999);+ expect([first, second, missing]).toEqual([true, false, false]);++ const active = texts(await engine.listFactsByEntity(SRC, ent));+ const history = (await engine.listFactsByEntity(SRC, ent, { activeOnly: false })).map((r) => view(r, name));+ expect(active).toEqual(['Dana likes jazz', 'Dana works at Acme']);+ expect(history.map((h) => h.fact)).toEqual(['Dana likes jazz', 'Dana works at Acme', 'Dana lives in Austin']);+ expect(history.find((h) => h.fact === 'Dana lives in Austin')).toMatchObject({ expired: true, superseded_by: null, valid_until: null });++ const health = await engine.getFactsHealth(SRC);+ expect(health).toMatchObject({ source_id: SRC, total_active: 2, total_expired: 1 });+ return { active, history, expireResults: [first, second, missing] };+ },+ );++ parityTest(+ 'expireFact with supersededBy/successorFrom records the successor and ends validity',+ { methods: ['insertFact', 'expireFact', 'listFactsByEntity', 'listSupersessions'] },+ async (engine) => {+ const ent = 'people/eli-example';+ const ids = await remember(engine, ent, [+ { fact: 'Eli is a PM', valid_from: at('2026-01-01T00:00:00Z') },+ { fact: 'Eli is a director', valid_from: at('2026-04-01T00:00:00Z') },+ ]);+ const name = namer([...ids].map(([fact, id]) => ({ id, fact })));+ const ok = await engine.expireFact(ids.get('Eli is a PM')!, {+ supersededBy: ids.get('Eli is a director')!,+ at: at('2026-04-02T00:00:00Z'),+ successorFrom: at('2026-04-01T00:00:00Z'),+ });+ expect(ok).toBe(true);+ const history = (await engine.listFactsByEntity(SRC, ent, { activeOnly: false })).map((r) => view(r, name));+ const old = history.find((h) => h.fact === 'Eli is a PM')!;+ expect(old).toMatchObject({ expired: true, superseded_by: 'Eli is a director', valid_until: '2026-04-01T00:00:00.000Z' });+ const sup = (await engine.listSupersessions(SRC)).map((r) => view(r, name));+ expect(sup.map((s) => s.fact)).toEqual(['Eli is a PM']);+ return { history, sup };+ },+ );++ parityTest(+ 'insertFact with supersedeId inserts the successor and closes the old fact atomically',+ { methods: ['insertFact', 'listFactsByEntity', 'listSupersessions'] },+ async (engine) => {+ const ent = 'people/fay-example';+ const old = await engine.insertFact(+ { fact: 'Fay lives in Boston', entity_slug: ent, source: 'mcp:remember', valid_from: at('2026-01-01T00:00:00Z') },+ { source_id: SRC },+ );+ const next = await engine.insertFact(+ { fact: 'Fay lives in Denver', entity_slug: ent, source: 'mcp:remember', valid_from: at('2026-05-01T00:00:00Z') },+ { source_id: SRC, supersedeId: old.id },+ );+ expect(next.status).toBe('superseded');+ expect(next.id).not.toBe(old.id);+ const name = namer([{ id: old.id, fact: 'Fay lives in Boston' }, { id: next.id, fact: 'Fay lives in Denver' }]);+ const active = texts(await engine.listFactsByEntity(SRC, ent));+ const history = (await engine.listFactsByEntity(SRC, ent, { activeOnly: false })).map((r) => view(r, name));+ expect(active).toEqual(['Fay lives in Denver']);+ expect(history.find((h) => h.fact === 'Fay lives in Boston')).toMatchObject({+ expired: true, superseded_by: 'Fay lives in Denver', valid_until: '2026-05-01T00:00:00.000Z',+ });+ const sup = (await engine.listSupersessions(SRC)).map((r) => ({ fact: r.fact, by: name(r.superseded_by) }));+ expect(sup).toEqual([{ fact: 'Fay lives in Boston', by: 'Fay lives in Denver' }]);+ // superseding an already-superseded fact does not rewrite it+ const again = await engine.insertFact(+ { fact: 'Fay lives in Miami', entity_slug: ent, source: 'mcp:remember', valid_from: at('2026-06-01T00:00:00Z') },+ { source_id: SRC, supersedeId: old.id },+ );+ expect(again.status).toBe('superseded');+ const afterAgain = (await engine.listSupersessions(SRC)).map((r) => ({ fact: r.fact, by: r.superseded_by === old.id ? 'old' : name(r.superseded_by) ?? 'miami' }));+ return { active, history, sup, afterAgain: sorted(afterAgain, (r) => r.fact) };+ },+ );++ parityTest(+ 'listSupersessions filters by since, visibility and limit, newest supersession first',+ { methods: ['insertFact', 'expireFact', 'listSupersessions'] },+ async (engine) => {+ const ent = 'people/gus-example';+ const ids = await remember(engine, ent, [+ { fact: 'g-old-1', visibility: 'private', valid_from: at('2026-01-01T00:00:00Z') },+ { fact: 'g-old-2', visibility: 'world', valid_from: at('2026-01-02T00:00:00Z') },+ { fact: 'g-old-3', visibility: 'world', valid_from: at('2026-01-03T00:00:00Z') },+ { fact: 'g-new', visibility: 'world', valid_from: at('2026-02-01T00:00:00Z') },+ ]);+ await engine.expireFact(ids.get('g-old-1')!, { supersededBy: ids.get('g-new')!, at: at('2026-03-01T00:00:00Z') });+ await engine.expireFact(ids.get('g-old-2')!, { supersededBy: ids.get('g-new')!, at: at('2026-04-01T00:00:00Z') });+ await engine.expireFact(ids.get('g-old-3')!, { supersededBy: ids.get('g-new')!, at: at('2026-05-01T00:00:00Z') });+ const all = texts(await engine.listSupersessions(SRC));+ const since = texts(await engine.listSupersessions(SRC, { since: at('2026-04-01T00:00:00Z') }));+ const worldOnly = texts(await engine.listSupersessions(SRC, { visibility: ['world'] }));+ const limited = texts(await engine.listSupersessions(SRC, { limit: 1 }));+ expect(all).toEqual(['g-old-3', 'g-old-2', 'g-old-1']);+ expect(since).toEqual(['g-old-3', 'g-old-2']);+ expect(worldOnly).toEqual(['g-old-3', 'g-old-2']);+ expect(limited).toEqual(['g-old-3']);+ return { all, since, worldOnly, limited };+ },+ );++ parityTest(+ 'activeOnly reads drop validity-lapsed rows; activeOnly:false keeps them',+ { methods: ['insertFact', 'listFactsByEntity', 'listFactsSince', 'listFactsBySession', 'countUnconsolidatedFacts'] },+ async (engine) => {+ const ent = 'people/hal-example';+ await remember(engine, ent, [+ { fact: 'h-open', valid_from: at('2026-01-01T00:00:00Z'), source_session: 'hs' },+ { fact: 'h-lapsed', valid_from: at('2026-01-02T00:00:00Z'), valid_until: at('2026-02-01T00:00:00Z'), source_session: 'hs' },+ { fact: 'h-future', valid_from: at('2026-01-03T00:00:00Z'), valid_until: at('2999-01-01T00:00:00Z'), source_session: 'hs' },+ ]);+ const since = at('2000-01-01T00:00:00Z');+ const byEntity = texts(await engine.listFactsByEntity(SRC, ent));+ const byEntityAll = texts(await engine.listFactsByEntity(SRC, ent, { activeOnly: false }));+ const bySince = texts(await engine.listFactsSince(SRC, since));+ const bySinceAll = texts(await engine.listFactsSince(SRC, since, { activeOnly: false }));+ const bySession = texts(await engine.listFactsBySession(SRC, 'hs'));+ const bySessionAll = texts(await engine.listFactsBySession(SRC, 'hs', { activeOnly: false }));+ const pending = await engine.countUnconsolidatedFacts(SRC);+ expect(byEntity).toEqual(['h-future', 'h-open']);+ expect(byEntityAll).toHaveLength(3);+ expect(bySince.sort()).toEqual(['h-future', 'h-open']);+ expect(bySinceAll).toHaveLength(3);+ expect(bySession.sort()).toEqual(['h-future', 'h-open']);+ expect(bySessionAll).toHaveLength(3);+ expect(pending).toBe(2);+ return { byEntity, byEntityAll, bySince: sorted(bySince), bySinceAll: sorted(bySinceAll), bySession: sorted(bySession), bySessionAll: sorted(bySessionAll), pending };+ },+ );++ parityTest(+ 'listFactsSince windows on creation time, or on event time with eventTime',+ { methods: ['insertFact', 'listFactsSince'] },+ async (engine) => {+ const ent = 'people/ivy-example';+ // inserted in this order; created_at is "now" for all, valid_from is the event time+ await remember(engine, ent, [+ { fact: 'i-old-event', valid_from: at('2025-06-01T00:00:00Z') },+ { fact: 'i-mid-event', valid_from: at('2026-01-15T00:00:00Z') },+ { fact: 'i-new-event', valid_from: at('2026-03-15T00:00:00Z') },+ ]);+ const longAgo = at('2000-01-01T00:00:00Z');+ const future = at('2999-01-01T00:00:00Z');+ const created = texts(await engine.listFactsSince(SRC, longAgo));+ const createdFuture = texts(await engine.listFactsSince(SRC, future));+ const eventAll = texts(await engine.listFactsSince(SRC, longAgo, { eventTime: true }));+ const eventSince = texts(await engine.listFactsSince(SRC, at('2026-01-01T00:00:00Z'), { eventTime: true }));+ const eventPaged = texts(await engine.listFactsSince(SRC, longAgo, { eventTime: true, limit: 1, offset: 1 }));+ expect(created).toEqual(['i-new-event', 'i-mid-event', 'i-old-event']); // newest created first = reverse insert order+ expect(createdFuture).toEqual([]);+ expect(eventAll).toEqual(['i-new-event', 'i-mid-event', 'i-old-event']);+ expect(eventSince).toEqual(['i-new-event', 'i-mid-event']);+ expect(eventPaged).toEqual(['i-mid-event']);+ return { created, createdFuture, eventAll, eventSince, eventPaged };+ },+ );++ parityTest(+ 'listFactsSince narrows by entity, session, kind, visibility, grep and audit rows before the limit',+ { methods: ['insertFact', 'listFactsSince'] },+ async (engine) => {+ await remember(engine, 'people/jo-example', [+ { fact: 'jo likes rust', kind: 'preference', visibility: 'world', source_session: 'js1' },+ { fact: 'jo shipped beta', kind: 'event', visibility: 'private', source_session: 'js2' },+ ]);+ await remember(engine, 'people/kim-example', [+ { fact: 'kim likes rust too', kind: 'preference', visibility: 'world', source_session: 'js1' },+ { fact: 'EXTRACTION_COMPLETE', source: 'cli:extract-conversation-facts:terminal:v2', source_session: 'js1' },+ ]);+ const since = at('2000-01-01T00:00:00Z');+ const q = async (opts?: Parameters<BrainEngine['listFactsSince']>[2]) => sorted(texts(await engine.listFactsSince(SRC, since, opts)));+ const all = await q();+ const entity = await q({ entitySlug: 'people/jo-example' });+ const session = await q({ sessionId: 'js1' });+ const entityAndSession = await q({ entitySlug: 'people/kim-example', sessionId: 'js1' });+ const kinds = await q({ kinds: ['event'] });+ const world = await q({ visibility: ['world'] });+ const grep = await q({ grep: 'RUST' });+ const noAudit = await q({ excludeAuditRows: true });+ const fingerprinted = await engine.listFactsSince(SRC, since, { fingerprint: true, entitySlug: 'people/jo-example' });+ expect(all).toHaveLength(4);+ expect(entity).toEqual(['jo likes rust', 'jo shipped beta']);+ expect(session).toEqual(['EXTRACTION_COMPLETE', 'jo likes rust', 'kim likes rust too']);+ expect(entityAndSession).toEqual(['EXTRACTION_COMPLETE', 'kim likes rust too']);+ expect(kinds).toEqual(['jo shipped beta']);+ expect(world).toEqual(['jo likes rust', 'kim likes rust too']);+ expect(grep).toEqual(['jo likes rust', 'kim likes rust too']);+ expect(noAudit).toEqual(['jo likes rust', 'jo shipped beta', 'kim likes rust too']);+ expect(fingerprinted.every((r) => typeof r.fact_fingerprint === 'string' && r.fact_fingerprint.length > 0)).toBe(true);+ // the same fact text fingerprints identically on every engine+ return { all, entity, session, entityAndSession, kinds, world, grep, noAudit, fingerprints: sorted(fingerprinted.map((r) => `${r.fact}=${r.fact_fingerprint}`)) };+ },+ );++ parityTest(+ 'listFactsBySession returns a session newest first and honors filters and paging',+ { methods: ['insertFact', 'listFactsBySession'] },+ async (engine) => {+ await remember(engine, 'people/lee-example', [+ { fact: 's1-a', source_session: 'sess-x', kind: 'event' },+ { fact: 's1-b', source_session: 'sess-x', kind: 'preference', visibility: 'world' },+ { fact: 's1-c', source_session: 'sess-x', kind: 'event', visibility: 'world' },+ { fact: 's2-a', source_session: 'sess-y' },+ ]);+ await remember(engine, null, [+ { fact: 's1-d-no-entity', source_session: 'sess-x' },+ { fact: 'audit', source_session: 'sess-x', source: 'cli:extract-conversation-facts:non-extractable:v2' },+ ]);+ const q = async (sid: string, opts?: Parameters<BrainEngine['listFactsBySession']>[2]) => texts(await engine.listFactsBySession(SRC, sid, opts));+ const all = await q('sess-x');+ const kinds = await q('sess-x', { kinds: ['event'] });+ const world = await q('sess-x', { visibility: ['world'] });+ const noAudit = await q('sess-x', { excludeAuditRows: true });+ const page = await q('sess-x', { limit: 2, offset: 1 });+ const grep = await q('sess-x', { grep: 's1-' });+ const none = await q('sess-nope');+ expect(all).toEqual(['audit', 's1-d-no-entity', 's1-c', 's1-b', 's1-a']);+ expect(kinds).toEqual(['s1-c', 's1-a']);+ expect(world).toEqual(['s1-c', 's1-b']);+ expect(noAudit).toEqual(['s1-d-no-entity', 's1-c', 's1-b', 's1-a']);+ expect(page).toEqual(['s1-d-no-entity', 's1-c']);+ expect(grep).toEqual(['s1-d-no-entity', 's1-c', 's1-b', 's1-a']);+ expect(none).toEqual([]);+ return { all, kinds, world, noAudit, page, grep, none, other: await q('sess-y') };+ },+ );++ parityTest(+ 'listFactsKeyset pages oldest-first by (created_at, id) with no gaps or repeats, across two rows that share a timestamp',+ { methods: ['insertFact', 'expireFact', 'listFactsKeyset', 'transaction'] },+ async (engine) => {+ const ent = 'people/max-example';+ // created_at is the database clock (millisecond steps on PGLite), so back-to-back inserts can+ // share a timestamp. Space the inserts until the clock moves, and make k3 and k4 tie on purpose:+ // one transaction stamps both with the same now(), which is what the id half of the cursor is for.+ const ids = new Map<string, number>();+ const add = async (e: BrainEngine, fact: string) => {+ for (const [k, v] of await remember(e, ent, [{ fact }])) ids.set(k, v);+ };+ const nextTick = async () => {+ const stamped = Date.now();+ while (Date.now() <= stamped) await new Promise((resolve) => setTimeout(resolve, 1));+ };+ for (const fact of ['k1', 'k2']) { await add(engine, fact); await nextTick(); }+ await engine.transaction(async (tx) => { await add(tx, 'k3'); await add(tx, 'k4'); });+ await nextTick();+ await add(engine, 'k5');+ const everything = await engine.listFactsKeyset(SRC, null);+ expect(texts(everything)).toEqual(['k1', 'k2', 'k3', 'k4', 'k5']);+ const stamps = everything.map((r) => r.created_at_iso);+ expect([stamps[2] === stamps[3], new Set(stamps).size]).toEqual([true, 4]);+ expect(everything.every((r) => /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{6}Z$/.test(r.created_at_iso ?? ''))).toBe(true);++ // page through with limit 2, advancing the keyset by the last delivered row+ const pages: string[][] = [];+ let cursor: { createdAt: string; id: number | null } | null = null;+ for (let i = 0; i < 5; i++) {+ const rows: FactRow[] = await engine.listFactsKeyset(SRC, cursor, { limit: 2 });+ if (rows.length === 0) break;+ pages.push(texts(rows));+ const last = rows[rows.length - 1];+ cursor = { createdAt: last.created_at_iso!, id: last.id };+ }+ expect(pages).toEqual([['k1', 'k2'], ['k3', 'k4'], ['k5']]);++ // id:null means strictly after the timestamp: k3 and k4, which share it, are both excluded;+ // a cursor with k3's id keeps k4, the later row inside the same timestamp+ const k3 = everything[2];+ const afterTs = texts(await engine.listFactsKeyset(SRC, { createdAt: k3.created_at_iso!, id: null }));+ const afterId = texts(await engine.listFactsKeyset(SRC, { createdAt: k3.created_at_iso!, id: k3.id }));+ const beforeAll = texts(await engine.listFactsKeyset(SRC, { createdAt: '2000-01-01T00:00:00.000000Z', id: 0 }));+ const afterAll = texts(await engine.listFactsKeyset(SRC, { createdAt: '2999-01-01T00:00:00.000000Z', id: null }));+ expect(afterTs).toEqual(['k5']);+ expect(afterId).toEqual(['k4', 'k5']);+ expect(beforeAll).toHaveLength(5);+ expect(afterAll).toEqual([]);++ // expired rows disappear from the default read and come back with activeOnly:false+ await engine.expireFact(ids.get('k2')!);+ const active = texts(await engine.listFactsKeyset(SRC, null));+ const withExpired = texts(await engine.listFactsKeyset(SRC, null, { activeOnly: false }));+ expect(active).toEqual(['k1', 'k3', 'k4', 'k5']);+ expect(withExpired).toEqual(['k1', 'k2', 'k3', 'k4', 'k5']);+ return { pages, afterTs, afterId, beforeAll: beforeAll.length, afterAll, active, withExpired };+ },+ );++ parityTest(+ 'listFactsKeyset applies visibility, entity, session, grep and audit narrowing before the limit',+ { methods: ['insertFact', 'listFactsKeyset'] },+ async (engine) => {+ await remember(engine, 'people/nia-example', [+ { fact: 'n-private rust', visibility: 'private', source_session: 'ns1' },+ { fact: 'n-world rust', visibility: 'world', source_session: 'ns2' },+ ]);+ await remember(engine, 'people/oz-example', [+ { fact: 'o-world go', visibility: 'world', source_session: 'ns1' },+ { fact: 'EXTRACTION_COMPLETE', visibility: 'world', source: 'cli:extract-conversation-facts:terminal:v2', source_session: 'ns1' },+ ]);+ const q = async (opts?: Parameters<BrainEngine['listFactsKeyset']>[2]) => texts(await engine.listFactsKeyset(SRC, null, opts));+ const world = await q({ visibility: ['world'] });+ const worldLimited = await q({ visibility: ['world'], limit: 1 });+ const entity = await q({ entitySlug: 'people/oz-example' });+ const session = await q({ sessionId: 'ns1' });+ const grep = await q({ grep: 'RUST' });+ const noAudit = await q({ excludeAuditRows: true });+ const fp = await engine.listFactsKeyset(SRC, null, { fingerprint: true });+ expect(world).toEqual(['n-world rust', 'o-world go', 'EXTRACTION_COMPLETE']);+ expect(worldLimited).toEqual(['n-world rust']);+ expect(entity).toEqual(['o-world go', 'EXTRACTION_COMPLETE']);+ expect(session).toEqual(['n-private rust', 'o-world go', 'EXTRACTION_COMPLETE']);+ expect(grep).toEqual(['n-private rust', 'n-world rust']);+ expect(noAudit).toEqual(['n-private rust', 'n-world rust', 'o-world go']);+ expect(fp.every((r) => !!r.fact_fingerprint)).toBe(true);+ return { world, worldLimited, entity, session, grep, noAudit, fingerprints: fp.map((r) => `${r.fact}=${r.fact_fingerprint}`) };+ },+ );++ parityTest(+ 'insertFacts stores fence rows in order, resolves superseded-by row refs, and skips duplicate row numbers',+ { methods: ['insertFacts', 'listFactsByEntity', 'listSupersessions', 'deleteFactsForPage'] },+ async (engine) => {+ const slug = 'people/pat-example';+ const rows = [+ { row_num: 1, source_markdown_slug: slug, fact: 'Pat joined Acme', entity_slug: slug, source: 'fence', valid_from: at('2026-01-01T00:00:00Z'), expired_at: at('2026-06-01T00:00:00Z'), superseded_by_row: 2 },+ { row_num: 2, source_markdown_slug: slug, fact: 'Pat leads Acme platform', entity_slug: slug, source: 'fence', valid_from: at('2026-06-01T00:00:00Z'), kind: 'event' as const },+ { row_num: 3, source_markdown_slug: slug, fact: 'Pat dangling ref', entity_slug: slug, source: 'fence', valid_from: at('2026-07-01T00:00:00Z'), superseded_by_row: 99 },+ { row_num: 4, source_markdown_slug: slug, fact: 'Pat self ref', entity_slug: slug, source: 'fence', valid_from: at('2026-08-01T00:00:00Z'), superseded_by_row: 4 },+ ];+ const first = await engine.insertFacts(rows, { source_id: SRC });+ expect(first.inserted).toBe(4);+ expect(first.ids).toHaveLength(4);+ expect(first.deleted).toBe(0);+ const name = namer(first.ids.map((id, i) => ({ id, fact: rows[i].fact })));++ // same (slug,row_num) again is skipped, not duplicated+ const again = await engine.insertFacts([{ ...rows[1], fact: 'Pat leads Acme platform (dup)' }, { row_num: 5, source_markdown_slug: slug, fact: 'Pat new row', entity_slug: slug, source: 'fence', valid_from: at('2026-09-01T00:00:00Z') }], { source_id: SRC });+ expect(again.inserted).toBe(1);++ const history = (await engine.listFactsByEntity(SRC, slug, { activeOnly: false })).map((r) => view(r, name));+ const sup = (await engine.listSupersessions(SRC)).map((r) => ({ fact: r.fact, by: name(r.superseded_by) }));+ expect(sup).toEqual([{ fact: 'Pat joined Acme', by: 'Pat leads Acme platform' }]);+ expect(first.warnings.length).toBe(2); // dangling + self reference+ expect(await engine.insertFacts([], { source_id: SRC })).toEqual({ inserted: 0, ids: [], warnings: [], deleted: 0 });++ const wiped = await engine.deleteFactsForPage(slug, SRC);+ const none = await engine.deleteFactsForPage(slug, SRC);+ expect(wiped.deleted).toBe(5);+ expect(none.deleted).toBe(0);+ expect(await engine.listFactsByEntity(SRC, slug, { activeOnly: false })).toEqual([]);+ return {+ history: sorted(history, (h) => h.fact), sup, warningCount: first.warnings.length, againInserted: again.inserted,+ wiped: wiped.deleted, none: none.deleted,+ };+ },+ );++ parityTest(+ 'insertFacts deleteForPageFirst replaces a page atomically; deleteFactsForPage spares excluded source prefixes and other pages',+ { methods: ['insertFacts', 'deleteFactsForPage', 'listFactsByEntity', 'insertFact'] },+ async (engine) => {+ const slug = 'notes/standup';+ const other = 'notes/retro';+ const mk = (page: string, n: number, fact: string, source: string) => ({+ row_num: n, source_markdown_slug: page, fact, entity_slug: 'people/quinn-example', source,+ valid_from: at(`2026-01-0${n}T00:00:00Z`),+ });+ await engine.insertFacts([mk(slug, 1, 'a-fence', 'fence'), mk(slug, 2, 'a-cli', 'cli:conversation'), mk(slug, 3, 'a-mcp', 'mcp:put_page')], { source_id: SRC });+ await engine.insertFacts([mk(other, 1, 'b-fence', 'fence')], { source_id: SRC });+ const ent = 'people/quinn-example';+ const left = async () => sorted(texts(await engine.listFactsByEntity(SRC, ent, { activeOnly: false })));++ // exclude `cli:` rows from the wipe+ const partial = await engine.deleteFactsForPage(slug, SRC, { excludeSourcePrefixes: ['cli:'] });+ expect(partial.deleted).toBe(2);+ const afterPartial = await left();+ expect(afterPartial).toEqual(['a-cli', 'b-fence']);++ // atomic reconcile keeping `cli:` rows: nothing deleted, row 2 collides with the survivor and is skipped+ const keepCli = await engine.insertFacts(+ [mk(slug, 1, 'a-fence-v2', 'fence'), mk(slug, 2, 'a-cli-v2', 'cli:conversation')],+ { source_id: SRC },+ { deleteForPageFirst: { slug, excludeSourcePrefixes: ['cli:'] } },+ );+ expect([keepCli.deleted, keepCli.inserted]).toEqual([0, 1]);+ const afterKeepCli = await left();++ // full atomic reconcile: wipe the page's rows and insert the new ones in one call+ const replaced = await engine.insertFacts(+ [mk(slug, 1, 'a-fence-v3', 'fence'), mk(slug, 2, 'a-cli-v3', 'cli:conversation')],+ { source_id: SRC },+ { deleteForPageFirst: { slug } },+ );+ expect([replaced.deleted, replaced.inserted]).toEqual([2, 2]);+ const afterReplace = await left();+ expect(afterReplace).toEqual(['a-cli-v3', 'a-fence-v3', 'b-fence']);++ // a fact with no fence coordinate is never touched by a page wipe+ await engine.insertFact({ fact: 'legacy-no-slug', entity_slug: ent, source: 'mcp:remember' }, { source_id: SRC });+ const wipeAll = await engine.deleteFactsForPage(slug, SRC);+ const afterWipe = await left();+ expect(afterWipe).toEqual(['b-fence', 'legacy-no-slug']);+ return { partialDeleted: partial.deleted, afterPartial, keepCli: [keepCli.deleted, keepCli.inserted], afterKeepCli, replaced: [replaced.deleted, replaced.inserted], afterReplace, wipeAll: wipeAll.deleted, afterWipe };+ },+ );++ parityTest(+ 'countUnconsolidatedFacts counts active entity-bound facts and ignores audit rows',+ { methods: ['insertFact', 'expireFact', 'consolidateFact', 'countUnconsolidatedFacts', 'addTakesBatch', 'putPage', 'listTakes'] },+ async (engine) => {+ const ent = 'people/rae-example';+ const ids = await remember(engine, ent, [{ fact: 'r1' }, { fact: 'r2' }, { fact: 'r3' }, { fact: 'r4', valid_until: at('2026-01-01T00:00:00Z'), valid_from: at('2025-01-01T00:00:00Z') }]);+ await remember(engine, null, [{ fact: 'no-entity' }]);+ await remember(engine, ent, [{ fact: 'audit', source: 'cli:extract-conversation-facts:terminal:v2' }]);+ const initial = await engine.countUnconsolidatedFacts(SRC);+ expect(initial).toBe(3); // r4 lapsed, no-entity excluded, audit excluded++ await engine.expireFact(ids.get('r1')!);+ const afterExpire = await engine.countUnconsolidatedFacts(SRC);+ const page = await engine.putPage('people/rae-example', { type: 'person', title: 'Rae Example', compiled_truth: 'Rae.', timeline: '' });+ await engine.addTakesBatch([{ page_id: page.id, row_num: 1, claim: 'Rae claim', kind: 'fact', holder: 'people/rae-example' }]);+ const [take] = await engine.listTakes({ page_id: page.id });+ await engine.consolidateFact(ids.get('r2')!, take.id);+ const afterConsolidate = await engine.countUnconsolidatedFacts(SRC);+ expect([initial, afterExpire, afterConsolidate]).toEqual([3, 2, 1]);+ const other = await engine.countUnconsolidatedFacts('some-other-source');+ expect(other).toBe(0);+ return { initial, afterExpire, afterConsolidate, other };+ },+ );++ parityTest(+ 'findCandidateDuplicates (recency arm) returns active same-entity facts newest first, capped by k',+ { methods: ['insertFact', 'expireFact', 'findCandidateDuplicates'] },+ async (engine) => {+ const ent = 'people/sam-example';+ const ids = await remember(engine, ent, [+ { fact: 'c1 likes coffee', attributed_to: 'user' },+ { fact: 'c2 likes tea', attributed_to: 'assistant' },+ { fact: 'c3 likes water' },+ { fact: 'c4 likes juice', valid_until: at('2026-01-01T00:00:00Z'), valid_from: at('2025-01-01T00:00:00Z') },+ { fact: 'c5 forgotten' },+ { fact: 'c6 audit', source: 'cli:extract-conversation-facts:terminal:v2' },+ ]);+ await remember(engine, 'people/other-example', [{ fact: 'other entity' }]);+ await engine.expireFact(ids.get('c5 forgotten')!);+ const q = async (opts?: Parameters<BrainEngine['findCandidateDuplicates']>[3]) => texts(await engine.findCandidateDuplicates(SRC, ent, 'sam drinks coffee', opts));+ const def = await q();+ const k2 = await q({ k: 2 });+ const speakerUser = await q({ attributedTo: 'user' });+ const speakerAssistant = await q({ attributedTo: 'assistant' });+ const missingEntity = texts(await engine.findCandidateDuplicates(SRC, 'people/nobody', 'x'));+ // audit rows are not filtered by the recency arm (only the embedding/keyword arms drop them)+ expect(def).toContain('c3 likes water');+ expect(def).not.toContain('c5 forgotten');+ expect(def).not.toContain('c4 likes juice');+ expect(k2).toEqual(def.slice(0, 2));+ expect(speakerUser).not.toContain('c2 likes tea');+ expect(speakerAssistant).not.toContain('c1 likes coffee');+ expect(missingEntity).toEqual([]);+ return { def, k2, speakerUser, speakerAssistant, missingEntity };+ },+ );++ parityTest(+ 'findCandidateDuplicates (embedding arm) ranks by cosine and only compares same-model current vectors',+ { methods: ['insertFact', 'findCandidateDuplicates'] },+ async (engine) => {+ const ent = 'people/tess-example';+ await remember(engine, ent, [+ { fact: 'e-axis0', embedding: basisEmbedding(0), embedding_model: 'm1' },+ { fact: 'e-axis1', embedding: basisEmbedding(1), embedding_model: 'm1' },+ { fact: 'e-axis2-other-model', embedding: basisEmbedding(2), embedding_model: 'm2' },+ { fact: 'e-no-embedding' },+ { fact: 'e-audit', embedding: basisEmbedding(0), embedding_model: 'm1', source: 'cli:extract-conversation-facts:terminal:v2' },+ ]);+ const near0 = new Float32Array(1536);+ near0[0] = 1;+ near0[1] = 0.2;+ const hits = texts(await engine.findCandidateDuplicates(SRC, ent, 'whatever', { embedding: near0, embeddingModel: 'm1' }));+ const hitsK1 = texts(await engine.findCandidateDuplicates(SRC, ent, 'whatever', { embedding: near0, embeddingModel: 'm1', k: 1 }));+ const otherModel = texts(await engine.findCandidateDuplicates(SRC, ent, 'whatever', { embedding: basisEmbedding(2), embeddingModel: 'm2' }));+ const noModel = texts(await engine.findCandidateDuplicates(SRC, ent, 'whatever', { embedding: near0 }));+ expect(hits).toEqual(['e-axis0', 'e-axis1']);+ expect(hitsK1).toEqual(['e-axis0']);+ expect(otherModel).toEqual(['e-axis2-other-model']);+ expect(noModel).toEqual([]);+ return { hits, hitsK1, otherModel, noModel };+ },+ );++ parityTest(+ 'findCandidateDuplicates (keyword arm) ranks the entity bucket by shared terms',+ { methods: ['insertFact', 'findCandidateDuplicates'] },+ async (engine) => {+ const ent = 'people/uma-example';+ await remember(engine, ent, [+ { fact: 'Uma pays 50 dollars for the rust workshop' },+ { fact: 'Uma likes hiking on weekends' },+ { fact: 'Uma bought a rust book' },+ ]);+ const q = async (text: string, opts: Parameters<BrainEngine['findCandidateDuplicates']>[3] = {}) =>+ texts(await engine.findCandidateDuplicates(SRC, ent, text, { arm: 'keyword', ...opts }));+ const rust = await q('rust workshop');+ const rustOne = await q('rust workshop', { k: 1 });+ const hiking = await q('hiking');+ const noMatch = await q('zzzzqqqq');+ const stopwordsOnly = await q('the');+ expect(rust[0]).toBe('Uma pays 50 dollars for the rust workshop');+ expect(sorted(rust)).toEqual(['Uma bought a rust book', 'Uma pays 50 dollars for the rust workshop']);+ expect(rustOne).toEqual(['Uma pays 50 dollars for the rust workshop']);+ expect(hiking).toEqual(['Uma likes hiking on weekends']);+ expect(noMatch).toEqual([]);+ expect(stopwordsOnly).toEqual([]);+ return { rust, rustOne, hiking, noMatch, stopwordsOnly };+ },+ );++ parityTest(+ 'findTrajectory returns the typed-claim history chronologically, world-only unless local',+ { methods: ['insertFact', 'insertFacts', 'expireFact', 'findTrajectory'] },+ async (engine) => {+ const ent = 'companies/vela-example';+ const ids = await remember(engine, ent, [+ { fact: 'MRR 10k', claim_metric: 'mrr', claim_value: 10000, claim_unit: 'usd', claim_period: 'month', valid_from: at('2026-01-01T00:00:00Z'), visibility: 'world', source_session: 'tr-1' },+ { fact: 'MRR 20k', claim_metric: 'mrr', claim_value: 20000, claim_unit: 'usd', claim_period: 'month', valid_from: at('2026-02-01T00:00:00Z'), visibility: 'private' },+ { fact: 'MRR 15k', claim_metric: 'mrr', claim_value: 15000, claim_unit: 'usd', claim_period: 'month', valid_from: at('2026-03-01T00:00:00Z'), visibility: 'world' },+ { fact: 'Headcount 12', claim_metric: 'headcount', claim_value: 12, claim_unit: 'people', valid_from: at('2026-02-15T00:00:00Z'), visibility: 'world' },+ { fact: 'untyped note', valid_from: at('2026-02-21T00:00:00Z'), visibility: 'world' },+ { fact: 'MRR forgotten', claim_metric: 'mrr', claim_value: 1, valid_from: at('2026-04-01T00:00:00Z'), visibility: 'world' },+ ]);+ await engine.expireFact(ids.get('MRR forgotten')!);+ // insertFact has no event_type; the fence batch insert does+ await engine.insertFacts(+ [{ row_num: 1, source_markdown_slug: ent, fact: 'Met the founder', entity_slug: ent, source: 'fence', event_type: 'meeting', valid_from: at('2026-02-20T00:00:00Z'), visibility: 'world' }],+ { source_id: SRC },+ );+ const pts = (rows: Awaited<ReturnType<BrainEngine['findTrajectory']>>) =>+ rows.map((p) => ({ text: p.text, metric: p.metric, value: p.value, unit: p.unit, period: p.period, event: p.event_type, from: iso(p.valid_from), until: iso(p.valid_until), session: p.source_session }));+ const local = await engine.findTrajectory({ entitySlug: ent, remote: false });+ const remoteDefault = await engine.findTrajectory({ entitySlug: ent });+ const mrr = await engine.findTrajectory({ entitySlug: ent, remote: false, metric: 'mrr' });+ const metrics = await engine.findTrajectory({ entitySlug: ent, remote: false, kind: 'metric' });+ const events = await engine.findTrajectory({ entitySlug: ent, remote: false, kind: 'event' });+ const window = await engine.findTrajectory({ entitySlug: ent, remote: false, since: '2026-02-01', until: '2026-02-28' });+ const capped = await engine.findTrajectory({ entitySlug: ent, remote: false, limit: 2 });+ const otherSource = await engine.findTrajectory({ entitySlug: ent, remote: false, sourceId: 'nope' });+ const arraySource = await engine.findTrajectory({ entitySlug: ent, remote: false, sourceIds: [SRC] });+ expect(local.map((p) => p.text)).toEqual(['MRR 10k', 'MRR 20k', 'Headcount 12', 'Met the founder', 'untyped note', 'MRR 15k']);+ expect(remoteDefault.map((p) => p.text)).toEqual(['MRR 10k', 'Headcount 12', 'Met the founder', 'untyped note', 'MRR 15k']);+ expect(mrr.map((p) => p.value)).toEqual([10000, 20000, 15000]);+ expect(metrics.map((p) => p.text)).toEqual(['MRR 10k', 'MRR 20k', 'Headcount 12', 'MRR 15k']);+ expect(events.map((p) => p.text)).toEqual(['Met the founder']);+ expect(window.map((p) => p.text)).toEqual(['MRR 20k', 'Headcount 12', 'Met the founder', 'untyped note']);+ expect(capped.map((p) => p.text)).toEqual(['untyped note', 'MRR 15k']);+ expect(otherSource).toEqual([]);+ expect(arraySource).toHaveLength(6);+ expect(local.every((p) => p.embedding === null)).toBe(true);+ return {+ local: pts(local), remoteDefault: remoteDefault.map((p) => p.text), mrr: pts(mrr), metrics: metrics.map((p) => p.text),+ events: pts(events), window: window.map((p) => p.text), capped: capped.map((p) => p.text), otherSource, arraySource: arraySource.length,+ };+ },+ );++ parityTest(+ 'getFactsHealth partitions active/expired/consolidated and ranks top entities',+ { methods: ['insertFact', 'expireFact', 'consolidateFact', 'getFactsHealth', 'addTakesBatch', 'putPage', 'listTakes'] },+ async (engine) => {+ const ids = await remember(engine, 'people/wes-example', [{ fact: 'w1' }, { fact: 'w2' }, { fact: 'w3' }]);+ await remember(engine, 'people/xia-example', [{ fact: 'x1' }, { fact: 'x2' }]);+ await remember(engine, 'people/yan-example', [{ fact: 'y1' }]);+ await remember(engine, 'people/zed-example', [{ fact: 'z-lapsed', valid_from: at('2025-01-01T00:00:00Z'), valid_until: at('2025-02-01T00:00:00Z') }]);+ await remember(engine, null, [{ fact: 'free-floating' }]);+ await engine.expireFact(ids.get('w3')!);+ const page = await engine.putPage('people/wes-example', { type: 'person', title: 'Wes Example', compiled_truth: 'Wes.', timeline: '' });+ await engine.addTakesBatch([{ page_id: page.id, row_num: 1, claim: 'Wes claim', kind: 'fact', holder: 'people/wes-example' }]);+ const [take] = await engine.listTakes({ page_id: page.id });+ await engine.consolidateFact(ids.get('w1')!, take.id);+ const health = await engine.getFactsHealth(SRC);+ expect(health.total_active + health.total_expired).toBe(8);+ const empty = await engine.getFactsHealth('empty-source');+ expect(empty).toMatchObject({ total_active: 0, total_expired: 0, top_entities: [] });+ return {+ source_id: health.source_id, total_active: health.total_active, total_today: health.total_today, total_week: health.total_week,+ total_expired: health.total_expired, total_consolidated: health.total_consolidated, top_entities: health.top_entities,+ };+ },+ );+});diff --git a/test/engine-parity/harness.ts b/test/engine-parity/harness.tsnew file mode 100644index 0000000000..38523b6d7b--- /dev/null+++ b/test/engine-parity/harness.ts@@ -0,0 +1,280 @@+/**+ * BrainEngine parity harness: one scenario, every engine arm, same answer.+ *+ * `parityArms(testBackends())` opens one engine per selected backend:+ * PGLite on every run, Postgres too when DATABASE_URL is set. A future Rust+ * arm slots into `openArm()`/`resetArm()` (the exhaustive switch below): no+ * parity case changes.+ *+ * `const { parityTest } = parityArms(testBackends());` then+ * `parityTest(name, { methods }, scenario)` runs `scenario` on each arm in+ * turn, from a reset brain, and then:+ * 1. fails when a method named in `methods` was not called on the engine+ * handle (a coverage declaration has to be backed by a real call);+ * 2. fails when two arms returned different observables (`toEqual`).+ * Scenarios assert engine-independent expectations inline and return only+ * stable, comparable data (no timestamps, no generated ids unless reset+ * makes them deterministic). Assertions go through typed BrainEngine+ * methods, never `executeRaw` (D18: the Rust engine has no SQL dialect).+ *+ * A case that needs a capability some arm lacks declares `requires`+ * (arm-capabilities.ts): raw SQL runs on the SQL arms and must be refused by+ * the Rust arm; the Postgres-only schema migration lock runs on Postgres only.+ *+ * `methods` is read statically by `test/engine-parity/coverage.ts` to build+ * `test/engine-parity/coverage.tsv`, so it must be an array literal of+ * string literals.+ */+import { afterAll, beforeAll, expect, test } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import { PostgresEngine } from '../../src/core/postgres-engine.ts';+import type { EngineConfig } from '../../src/core/types.ts';+import { PGLiteEngine } from '../../src/core/pglite-engine.ts';+import { isolatedPersistencePostgres } from '../helpers/persistence-postgres.ts';+import { resetPgliteState, truncateCascade } from '../helpers/reset-pglite.ts';+import { disposePersistenceConsumer } from '../../src/core/persistence/service.ts';+import type { TestBackend } from '../helpers/test-backends.ts';+import { armHas, isCapabilityRefusal, missingCapability, type EngineCapability } from './arm-capabilities.ts';++/** A callable BrainEngine member name. */+export type EngineMethod = {+ [K in keyof BrainEngine]-?: NonNullable<BrainEngine[K]> extends (...args: never[]) => unknown ? K : never;+}[keyof BrainEngine];++export interface ParityArm {+ backend: TestBackend;+ engine: BrainEngine;+ close: () => Promise<void>;+ /** Build a second, not yet connected engine of this arm and the config `connect` takes. */+ unconnected: () => { engine: BrainEngine; config: EngineConfig };+}++/** Per-case facilities beyond the arm's engine. */+export interface ParityContext {+ /**+ * A second engine of the case's arm, not connected yet, with the config to+ * connect it (PGLite: a new in-memory brain; Postgres: the arm's database).+ * Calls on it count toward `methods`. The harness disconnects it after the+ * case, so lifecycle cases (connect, disconnect) never touch the shared arm.+ */+ unconnectedEngine(): { engine: BrainEngine; config: EngineConfig };+}++export interface ParityCaseOpts {+ /** BrainEngine methods this case covers. Each must be called on every arm. */+ methods: readonly EngineMethod[];+ /**+ * A capability the scenario needs (test/engine-parity/arm-capabilities.ts).+ * Arms with it run the scenario and compare answers. On an arm without it,+ * a `refuses` capability means the scenario must throw the typed+ * `engine_capability_missing` refusal, and an `n/a` capability skips the arm.+ */+ requires?: EngineCapability;+ timeout?: number;+}++export type ParityScenario<T> = (engine: BrainEngine, backend: TestBackend, ctx: ParityContext) => Promise<T>;++function assertNever(value: never): never {+ throw new Error(`engine-parity: unhandled test backend ${String(value)}`);+}++async function openArm(backend: TestBackend): Promise<ParityArm> {+ switch (backend) {+ case 'pglite': {+ const engine = new PGLiteEngine();+ await engine.connect({ engine: 'pglite' } as never);+ await engine.initSchema();+ return { backend, engine, close: () => engine.disconnect(),+ unconnected: () => ({ engine: new PGLiteEngine(), config: { engine: 'pglite' } }) };+ }+ case 'postgres': {+ const { engine, databaseUrl, close } = await isolatedPersistencePostgres(process.env.DATABASE_URL!);+ return { backend, engine, close,+ unconnected: () => ({ engine: new PostgresEngine(), // An instance pool, never the module-level singleton other code shares.+ config: { engine: 'postgres', database_url: databaseUrl, poolSize: 2 } as EngineConfig }) };+ }+ default:+ return assertNever(backend);+ }+}++/** Infrastructure rows every reset keeps (mirrors test/helpers/reset-pglite.ts). */+const PRESERVED_TABLES = ['schema_version', 'page_generation_clock', 'persistence_brain'];++/**+ * Postgres: the schema's enabled event trigger sends resetPgliteState down its+ * TRUNCATE path (~2.8 s a test). Delete every row under replica role instead+ * (truncateCascade, ~ms); sequences keep counting, so cases never compare ids.+ */+async function resetPostgres(engine: BrainEngine): Promise<void> {+ await disposePersistenceConsumer(engine);+ const tables = await engine.executeRaw<{ relname: string }>(+ `SELECT c.relname FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace+ WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p') AND NOT (c.relname = ANY($1::text[]))`,+ [PRESERVED_TABLES],+ );+ if (tables.length > 0) await truncateCascade(engine, tables.map((t) => t.relname));+ await engine.executeRaw(+ `UPDATE persistence_brain SET brain_id = gen_random_uuid(), enabled = false, activated_at = NULL WHERE singleton = 1`,+ );+ await engine.executeRaw(+ `INSERT INTO sources (id, name, config) VALUES ('default', 'default', '{"federated": true}'::jsonb) ON CONFLICT (id) DO NOTHING`,+ );+}++/** Return the arm to an empty brain (default source only). Harness-only SQL: cases never use it. */+async function resetArm(arm: ParityArm): Promise<void> {+ switch (arm.backend) {+ case 'pglite':+ await resetPgliteState(arm.engine as PGLiteEngine);+ return;+ case 'postgres':+ await resetPostgres(arm.engine);+ return;+ default:+ return assertNever(arm.backend);+ }+}++/**+ * Fixture: register a second source (BrainEngine has no typed "create source"+ * method). Harness-only SQL behind the backend switch; a Rust arm supplies its+ * own path here. Cases call this instead of executeRaw.+ */+export async function createSource(engine: BrainEngine, backend: TestBackend, id: string, config: Record<string, unknown> = {}): Promise<void> {+ switch (backend) {+ case 'pglite':+ case 'postgres':+ await engine.executeRaw(+ `INSERT INTO sources (id, name, config) VALUES ($1, $1, $2::text::jsonb) ON CONFLICT (id) DO NOTHING`,+ [id, JSON.stringify(config)],+ );+ return;+ default:+ return assertNever(backend);+ }+}++/** Wrap an engine so every direct method call on the handle is recorded. */+function recordingEngine(engine: BrainEngine, calls: Set<string>): BrainEngine {+ return new Proxy(engine, {+ get(target, prop, receiver) {+ const value = Reflect.get(target, prop, receiver);+ if (typeof value !== 'function' || typeof prop !== 'string') return value;+ return (...args: unknown[]) => {+ calls.add(prop);+ // The transaction handle is an engine too: record the calls made on it.+ if (prop === 'transaction' && typeof args[0] === 'function') {+ const fn = args[0] as (tx: BrainEngine) => unknown;+ args = [(tx: BrainEngine) => fn(recordingEngine(tx, calls)), ...args.slice(1)];+ }+ return (value as (...a: unknown[]) => unknown).apply(target, args);+ };+ },+ });+}++export interface ParitySuite {+ /** Run `scenario` on every arm from a reset brain; compare the returned observables. */+ parityTest<T>(name: string, opts: ParityCaseOpts, scenario: ParityScenario<T>): void;+ /** The open arms (valid inside tests). */+ arms(): readonly ParityArm[];+}++/**+ * Register arm setup/teardown for the current test file and return its+ * `parityTest`. Call once at the top level of a parity file:+ * `const { parityTest } = parityArms(testBackends());`+ * Each file makes the zero-argument `testBackends()` call itself, so+ * `scripts/check-postgres-lane-coverage.ts` sees the file's Postgres arm and+ * requires its row in `test/postgres-unit-arms.txt` (the lane that runs the+ * Postgres arm in CI). `test/engine-parity/coverage.test.ts` pins that call.+ */+export function parityArms(backends: readonly TestBackend[]): ParitySuite {+ let arms: ParityArm[] = [];+ beforeAll(async () => {+ const opened: ParityArm[] = [];+ try {+ for (const backend of backends) opened.push(await openArm(backend));+ } catch (error) {+ for (const arm of opened) await arm.close();+ throw error;+ }+ arms = opened;+ }, 120_000);+ afterAll(async () => {+ const closing = arms;+ arms = [];+ for (const arm of closing) await arm.close();+ }, 60_000);++ function parityTest<T>(name: string, opts: ParityCaseOpts, scenario: ParityScenario<T>): void {+ test(name, async () => {+ expect(arms.length).toBeGreaterThan(0);+ const results: Array<{ backend: TestBackend; value: T }> = [];+ for (const arm of arms) {+ await resetArm(arm);+ const calls = new Set<string>();+ const extra: BrainEngine[] = [];+ const ctx: ParityContext = {+ unconnectedEngine: () => {+ const { engine, config } = arm.unconnected();+ extra.push(engine);+ return { engine: recordingEngine(engine, calls), config };+ },+ };+ const runs = armHas(arm.backend, opts.requires);+ if (!runs && missingCapability(opts.requires!).kind === 'n/a') continue;+ let value: T;+ try {+ if (!runs) {+ // The arm lacks a `refuses` capability: the scenario must stop on the typed refusal.+ const refusal = await scenario(recordingEngine(arm.engine, calls), arm.backend, ctx).then(() => null, (e: unknown) => e);+ expect({ backend: arm.backend, refused: isCapabilityRefusal(refusal, opts.requires!) })+ .toEqual({ backend: arm.backend, refused: true });+ continue;+ }+ value = await scenario(recordingEngine(arm.engine, calls), arm.backend, ctx);+ } catch (error) {+ if (error instanceof Error) error.message = `[${arm.backend}] ${error.message}`;+ throw error;+ } finally {+ // A case may already have disconnected it; a second disconnect is harmless or refused.+ for (const engine of extra) await engine.disconnect().catch(() => undefined);+ }+ const missing = opts.methods.filter((m) => !calls.has(m));+ expect({ backend: arm.backend, declaredButNotCalled: missing }).toEqual({ backend: arm.backend, declaredButNotCalled: [] });+ results.push({ backend: arm.backend, value });+ }+ const [first, ...rest] = results;+ for (const other of rest) {+ expect({ backend: other.backend, value: other.value }).toEqual({ backend: other.backend, value: first!.value });+ }+ }, opts.timeout ?? 60_000);+ }++ return { parityTest, arms: () => arms };+}++/** Sorted copy, for order-free comparisons. */+export function sorted<T>(values: Iterable<T>, key: (v: T) => string = (v) => String(v)): T[] {+ return [...values].sort((a, b) => (key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0));+}++/** Pick listed keys from a row, mapping Dates to a fixed marker so arms compare. */+export function pick<T extends object, K extends keyof T>(row: T, keys: readonly K[]): Pick<T, K> {+ const out = {} as Pick<T, K>;+ for (const k of keys) {+ const v = row[k];+ (out as Record<K, unknown>)[k] = v instanceof Date ? '<date>' : v;+ }+ return out;+}++/** A 1536-d unit vector on axis `idx`: deterministic, engine-independent. */+export function basisEmbedding(idx: number, dim = 1536): Float32Array {+ const emb = new Float32Array(dim);+ emb[idx % dim] = 1;+ return emb;+}diff --git a/test/engine-parity/lifecycle.test.ts b/test/engine-parity/lifecycle.test.tsnew file mode 100644index 0000000000..03d509a236--- /dev/null+++ b/test/engine-parity/lifecycle.test.ts@@ -0,0 +1,316 @@+/**+ * BrainEngine parity — lifecycle family (transactions, schema re-init,+ * reconnect, shutdown hooks, reserved connections).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: transaction commit / rollback-on-throw behaviour, idempotent+ * schema initialisation, reconnect data survival and the shutdown-hook+ * registration contract are the same on every engine arm (PGLite always;+ * Postgres with DATABASE_URL; a Rust arm later through+ * test/engine-parity/harness.ts).+ * - Regression: an engine whose transaction leaks writes after a throw,+ * swallows the thrown error, loses data when initSchema runs on an+ * initialised brain (every CLI start does this), or drops data on+ * reconnect — the failure modes behind half-applied sync/import writes.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and has no lifecycle cases; per-engine+ * tests never compare two engines on one scenario.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ *+ * connect / disconnect run on a second engine from the harness's+ * `unconnectedEngine()`, never on the shared arm engine.+ *+ * holdSchemaMigrationLock is optional on the interface and only Postgres+ * implements it (PGLite serializes migrations in-process,+ * src/core/schema-migration-lock.ts), so its case declares+ * `requires: 'schema_migration_lock'` and runs on the Postgres arm only.+ *+ * Skipped on purpose:+ * - withReservedConnection with a connection query: ReservedConnection only+ * exposes executeRaw, which cases may not call. Only the pass-through+ * contract (return value, error propagation) is checked.+ */+import { describe, expect } from 'bun:test';+import { parityArms } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const NOTE = (title: string, body: string) => ({ type: 'note' as const, title, compiled_truth: body, timeline: '' });++describe('engine parity: lifecycle', () => {+ parityTest(+ 'transaction commits writes made through the tx handle and returns the callback value',+ { methods: ['transaction', 'getPage'] },+ async (engine) => {+ const result = await engine.transaction(async (tx) => {+ await tx.putPage('notes/tx-commit-a', NOTE('A', 'Committed A.'));+ await tx.putPage('notes/tx-commit-b', NOTE('B', 'Committed B.'));+ // Read-your-writes inside the transaction.+ const inside = await tx.getPage('notes/tx-commit-a');+ expect(inside?.compiled_truth).toBe('Committed A.');+ return { inside: inside?.title, marker: 42 };+ });+ const a = await engine.getPage('notes/tx-commit-a');+ const b = await engine.getPage('notes/tx-commit-b');+ expect(a?.compiled_truth).toBe('Committed A.');+ expect(b?.compiled_truth).toBe('Committed B.');+ return { result, a: a?.title, b: b?.title };+ },+ );++ parityTest(+ 'transaction rolls back every write when the callback throws and rethrows the same error',+ { methods: ['putPage', 'transaction', 'getPage', 'listPages'] },+ async (engine) => {+ await engine.putPage('notes/tx-keep', NOTE('Keep', 'Original.'));+ let caught = '';+ try {+ await engine.transaction(async (tx) => {+ await tx.putPage('notes/tx-new', NOTE('New', 'Should vanish.'));+ await tx.putPage('notes/tx-keep', NOTE('Keep', 'Edited inside tx.'));+ throw new Error('boom: abort the transaction');+ });+ } catch (error) {+ caught = (error as Error).message.replace(/^\[[a-z]+\]\s*/, '');+ }+ expect(caught).toContain('boom: abort the transaction');+ const created = await engine.getPage('notes/tx-new');+ const kept = await engine.getPage('notes/tx-keep');+ const slugs = (await engine.listPages()).map((p) => p.slug);+ expect(created).toBeNull();+ expect(kept?.compiled_truth).toBe('Original.');+ expect(slugs).toEqual(['notes/tx-keep']);+ return { caught, created, kept: kept?.compiled_truth, slugs };+ },+ );++ parityTest(+ 'a failed transaction leaves the engine usable for the next transaction',+ { methods: ['transaction', 'getPage'] },+ async (engine) => {+ const failures: string[] = [];+ for (let i = 0; i < 2; i++) {+ try {+ await engine.transaction(async (tx) => {+ await tx.putPage(`notes/tx-fail-${i}`, NOTE('F', 'Never lands.'));+ throw new Error(`fail-${i}`);+ });+ } catch (error) {+ failures.push((error as Error).message.replace(/^\[[a-z]+\]\s*/, ''));+ }+ }+ await engine.transaction(async (tx) => {+ await tx.putPage('notes/tx-after', NOTE('After', 'Lands.'));+ });+ const after = await engine.getPage('notes/tx-after');+ expect(after?.compiled_truth).toBe('Lands.');+ return {+ failures,+ leaked: [await engine.getPage('notes/tx-fail-0'), await engine.getPage('notes/tx-fail-1')],+ after: after?.title,+ };+ },+ );++ parityTest(+ 'transactionDirect commits on success and rolls back on throw',+ { methods: ['transactionDirect', 'getPage', 'putPage'] },+ async (engine) => {+ const value = await engine.transactionDirect(async (tx) => {+ await tx.putPage('notes/direct-commit', NOTE('Direct', 'Direct commit.'));+ return 'done';+ });+ await engine.putPage('notes/direct-keep', NOTE('Keep', 'Original.'));+ let caught = '';+ try {+ await engine.transactionDirect(async (tx) => {+ await tx.putPage('notes/direct-keep', NOTE('Keep', 'Edited inside direct tx.'));+ await tx.putPage('notes/direct-new', NOTE('New', 'Vanishes.'));+ throw new Error('direct boom');+ });+ } catch (error) {+ caught = (error as Error).message.replace(/^\[[a-z]+\]\s*/, '');+ }+ const committed = await engine.getPage('notes/direct-commit');+ const kept = await engine.getPage('notes/direct-keep');+ const created = await engine.getPage('notes/direct-new');+ expect(value).toBe('done');+ expect(caught).toContain('direct boom');+ expect(committed?.compiled_truth).toBe('Direct commit.');+ expect(kept?.compiled_truth).toBe('Original.');+ expect(created).toBeNull();+ return { value, caught, committed: committed?.title, kept: kept?.compiled_truth, created };+ },+ );++ parityTest(+ 'a nested transaction joins the outer one: an outer throw rolls back inner writes too',+ { methods: ['transaction', 'getPage'] },+ async (engine) => {+ let caught = '';+ try {+ await engine.transaction(async (outer) => {+ await outer.putPage('notes/nest-outer', NOTE('Outer', 'Outer write.'));+ await outer.transaction(async (inner) => {+ await inner.putPage('notes/nest-inner', NOTE('Inner', 'Inner write.'));+ });+ const insideInner = await outer.getPage('notes/nest-inner');+ expect(insideInner?.compiled_truth).toBe('Inner write.');+ throw new Error('outer abort');+ });+ } catch (error) {+ caught = (error as Error).message.replace(/^\[[a-z]+\]\s*/, '');+ }+ expect(caught).toContain('outer abort');+ const outer = await engine.getPage('notes/nest-outer');+ const inner = await engine.getPage('notes/nest-inner');+ expect(outer).toBeNull();+ expect(inner).toBeNull();+ return { caught, outer, inner };+ },+ );++ parityTest(+ 'registerBeforeDisconnect returns an unregister function and does not run the hook until shutdown',+ { methods: ['registerBeforeDisconnect'] },+ async (engine) => {+ let stops = 0;+ const unregister = engine.registerBeforeDisconnect(async () => {+ stops += 1;+ });+ const kind = typeof unregister;+ unregister();+ // Unregistering twice is harmless.+ unregister();+ const second = engine.registerBeforeDisconnect(async () => {+ stops += 1;+ });+ second();+ expect(kind).toBe('function');+ expect(stops).toBe(0);+ return { kind, stops, secondKind: typeof second };+ },+ );++ parityTest(+ 'withReservedConnection passes the callback value through, propagates errors, and leaves the engine usable',+ { methods: ['withReservedConnection', 'putPage', 'getPage'], requires: 'raw_sql' },+ async (engine) => {+ // The connection itself is not queried: ReservedConnection only offers executeRaw (forbidden in cases).+ const value = await engine.withReservedConnection(async (conn) => {+ expect(typeof conn.executeRaw).toBe('function');+ return { ok: true };+ });+ let caught = '';+ try {+ await engine.withReservedConnection(async () => {+ throw new Error('reserved boom');+ });+ } catch (error) {+ caught = (error as Error).message.replace(/^\[[a-z]+\]\s*/, '');+ }+ await engine.putPage('notes/reserved-after', NOTE('After', 'Still works.'));+ const after = await engine.getPage('notes/reserved-after');+ expect(caught).toContain('reserved boom');+ expect(after?.compiled_truth).toBe('Still works.');+ return { value, caught, after: after?.title };+ },+ );++ parityTest(+ 'initSchema on an initialised brain is idempotent: pages, config and links survive',+ { methods: ['putPage', 'setConfig', 'addLink', 'initSchema', 'getPage', 'getConfig', 'getLinks'] },+ async (engine) => {+ await engine.putPage('people/init-alice', { type: 'person', title: 'Alice', compiled_truth: 'Alice body.', timeline: '' });+ await engine.putPage('companies/init-acme', { type: 'company', title: 'Acme', compiled_truth: 'Acme body.', timeline: '' });+ await engine.addLink('people/init-alice', 'companies/init-acme', '', 'works_at');+ await engine.setConfig('parity.lifecycle.marker', 'before-init');+ // A brain made by `gbrain init` records its embedding model; initSchema on an existing brain refuses to+ // run when the stored model is unknown (same refusal on both engines), so record the default model first.+ await engine.setConfig('embedding_model', 'voyage:voyage-4');+ await engine.initSchema();+ await engine.initSchema();+ const page = await engine.getPage('people/init-alice');+ const marker = await engine.getConfig('parity.lifecycle.marker');+ const links = await engine.getLinks('people/init-alice');+ expect(page?.compiled_truth).toBe('Alice body.');+ expect(marker).toBe('before-init');+ expect(links.map((l) => l.to_slug)).toEqual(['companies/init-acme']);+ // The engine still accepts writes afterwards.+ await engine.putPage('people/init-bob', { type: 'person', title: 'Bob', compiled_truth: 'Bob body.', timeline: '' });+ const bob = await engine.getPage('people/init-bob');+ return { page: page?.title, marker, links: links.map((l) => `${l.from_slug}->${l.to_slug}:${l.link_type}`), bob: bob?.title };+ },+ );++ parityTest(+ 'reconnect keeps stored data and leaves the engine writable',+ { methods: ['putPage', 'setConfig', 'reconnect', 'getPage', 'getConfig'] },+ async (engine) => {+ await engine.putPage('notes/recon-a', NOTE('Recon', 'Before reconnect.'));+ await engine.setConfig('parity.lifecycle.recon', 'kept');+ await engine.reconnect();+ const before = await engine.getPage('notes/recon-a');+ const config = await engine.getConfig('parity.lifecycle.recon');+ await engine.putPage('notes/recon-b', NOTE('After', 'After reconnect.'));+ const after = await engine.getPage('notes/recon-b');+ expect(before?.compiled_truth).toBe('Before reconnect.');+ expect(config).toBe('kept');+ expect(after?.compiled_truth).toBe('After reconnect.');+ return { before: before?.title, config, after: after?.title };+ },+ );+ parityTest(+ 'connect, initSchema, write, then disconnect runs the shutdown hooks and closes the engine',+ { methods: ['connect', 'initSchema', 'putPage', 'getPage', 'registerBeforeDisconnect', 'disconnect', 'setConfig'] },+ async (engine, _backend, ctx) => {+ // The Postgres second engine opens the arm's own database; record its embedding model as `gbrain init` would.+ await engine.setConfig('embedding_model', 'voyage:voyage-4');+ const { engine: second, config } = ctx.unconnectedEngine();+ await second.connect(config);+ await second.initSchema();+ await second.putPage('notes/second-engine', NOTE('Second', 'Written by a second engine.'));+ const read = await second.getPage('notes/second-engine');+ expect(read?.title).toBe('Second');+ const hooks: string[] = [];+ second.registerBeforeDisconnect(async () => { hooks.push('kept'); });+ const unregister = second.registerBeforeDisconnect(async () => { hooks.push('unregistered'); });+ unregister();+ expect(hooks).toEqual([]);+ await second.disconnect();+ expect(hooks).toEqual(['kept']);+ const hooksAfterFirst = [...hooks];+ // A second disconnect of a closed engine is a no-op on every engine: the shutdown hooks ran once.+ await second.disconnect();+ expect(hooks).toEqual(hooksAfterFirst);+ let afterDisconnect: string;+ try {+ await second.getPage('notes/second-engine');+ afterDisconnect = 'served';+ } catch {+ afterDisconnect = 'refused';+ }+ // The shared arm engine is untouched by the second engine's lifecycle.+ const armStillServes = (await engine.getConfig('embedding_model')) === 'voyage:voyage-4';+ expect(armStillServes).toBe(true);+ return { title: read?.title, hooks: hooksAfterFirst, hooksAfterSecond: [...hooks], afterDisconnect, armStillServes };+ },+ );++ parityTest(+ 'holdSchemaMigrationLock runs the callback under the held lock, returns its value, and releases on a throw',+ { methods: ['holdSchemaMigrationLock', 'getPage'], requires: 'schema_migration_lock' },+ async (engine) => {+ const hold = engine.holdSchemaMigrationLock!.bind(engine);+ const value = await hold(async (assertHeld) => { await assertHeld(); return 'migrated'; });+ const thrown = await hold(async () => { throw new Error('migration failed'); })+ .then(() => 'no error', (e: unknown) => (e instanceof Error ? e.message : String(e)));+ // The throw released the lock: a second hold gets it again at once, and the engine still serves reads.+ const again = await hold(async (assertHeld) => { await assertHeld(); return 'again'; });+ const read = await engine.getPage('notes/nobody');+ expect([value, thrown, again, read]).toEqual(['migrated', 'migration failed', 'again', null]);+ return { value, thrown, again, read };+ },+ );+});diff --git a/test/engine-parity/links.test.ts b/test/engine-parity/links.test.tsnew file mode 100644index 0000000000..c25f4e497d--- /dev/null+++ b/test/engine-parity/links.test.ts@@ -0,0 +1,635 @@+/**+ * BrainEngine parity — links family (edges, derived-link replacement, graph+ * traversal, relational fan-out, backlink/adjacency signals, page-id signal+ * reads, orphans).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every link write, link read, traversal and page-id signal read+ * returns the same observable result on every engine arm (PGLite always;+ * Postgres with DATABASE_URL; a Rust arm later through+ * test/engine-parity/harness.ts).+ * - Regression: an engine that drifts on edge dedup, removal counts, link+ * provenance, traversal order/cycle handling, source isolation, backlink+ * counts or orphan detection — the graph layer search ranking, `gbrain+ * graph-query` and `gbrain orphans` read from.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and its graph cases hand-roll each engine; the+ * per-engine unit tests never compare two engines on one scenario.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ * Page ids come from putPage's returned Page and are mapped back to slugs+ * before anything is returned (sequences are not reset on Postgres).+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine, LinkBatchInput } from '../../src/core/engine.ts';+import type { Link, PageInput, PageType } from '../../src/core/types.ts';+import { linkFamily } from '../../src/core/search/relational-chain.ts';+import { createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const LINK_KEYS = ['from_slug', 'from_source_id', 'to_slug', 'to_source_id', 'link_type', 'context', 'link_source', 'origin_slug', 'origin_source_id', 'origin_field'] as const;++const linkView = (l: Link) => pick(l, LINK_KEYS);+const linkViews = (rows: Link[]) => rows.map(linkView);+const linkKey = (l: { from_slug: string; to_slug: string; link_type: string; link_source?: string | null }) =>+ `${l.from_slug}>${l.to_slug}:${l.link_type}:${l.link_source ?? ''}`;+const sortedLinks = (rows: Link[]) => sorted(linkViews(rows), (l) => `${linkKey(l)}|${l.origin_slug ?? ''}`);++function page(title: string, extra: Partial<PageInput> = {}): PageInput {+ return { type: 'note', title, compiled_truth: `${title} body`, timeline: '', ...extra };+}++async function seedPages(engine: BrainEngine, slugs: string[], type: PageType = 'note', opts?: { sourceId?: string }) {+ const ids = new Map<string, number>();+ for (const slug of slugs) ids.set(slug, (await engine.putPage(slug, page(slug, { type }), opts)).id);+ return ids;+}++/** Map a page-id keyed Map back to slug keys, sorted. */+function bySlug<V>(ids: Map<string, number>, m: Map<number, V>): Array<[string, V]> {+ const slugOf = new Map([...ids].map(([slug, id]) => [id, slug]));+ return sorted([...m].map(([id, v]) => [slugOf.get(id) ?? `<unknown ${id}>`, v] as [string, V]), ([s]) => s);+}++/** Seed: a -> b -> a (cycle), b -> c -> d chain. */+async function seedChain(engine: BrainEngine) {+ await seedPages(engine, ['tg/a', 'tg/b', 'tg/c', 'tg/d']);+ await engine.addLink('tg/a', 'tg/b', 'fwd-ctx', 'cycle-fwd', 'manual');+ await engine.addLink('tg/b', 'tg/a', 'back-ctx', 'cycle-back', 'manual');+ await engine.addLink('tg/b', 'tg/c', 'step-ctx', 'step', 'manual');+ await engine.addLink('tg/c', 'tg/d', 'deep-ctx', 'deep', 'manual');+}++describe('engine parity: links', () => {+ parityTest(+ 'addLink then getLinks/getBacklinks round-trip with provenance; duplicates are idempotent',+ { methods: ['addLink', 'getLinks', 'getBacklinks', 'putPage'] },+ async (engine) => {+ await seedPages(engine, ['people/alice', 'companies/acme', 'notes/memo']);+ await engine.addLink('people/alice', 'companies/acme', 'Alice works at Acme', 'works_at', 'manual');+ await engine.addLink('people/alice', 'companies/acme', 'Alice works at Acme', 'works_at', 'manual');+ await engine.addLink('people/alice', 'companies/acme', 'invested', 'invested_in', 'manual');+ // Defaults: link_type '' and link_source 'markdown'.+ await engine.addLink('notes/memo', 'people/alice', 'memo mentions alice');+ await engine.addLink('companies/acme', 'people/alice', 'fm', 'key_people', 'frontmatter', 'companies/acme', 'key_people');++ const out = sortedLinks(await engine.getLinks('people/alice'));+ const back = sortedLinks(await engine.getBacklinks('people/alice'));+ expect(out.map(linkKey)).toEqual(['people/alice>companies/acme:invested_in:manual', 'people/alice>companies/acme:works_at:manual']);+ expect(back.map((l) => l.from_slug)).toEqual(['companies/acme', 'notes/memo']);+ const fm = back.find((l) => l.link_source === 'frontmatter');+ expect(fm).toMatchObject({ origin_slug: 'companies/acme', origin_field: 'key_people' });+ const memo = back.find((l) => l.from_slug === 'notes/memo');+ expect(memo?.link_source).toBe('markdown');+ expect(await engine.getLinks('companies/nobody')).toEqual([]);+ return { out, back, none: await engine.getBacklinks('notes/memo') };+ },+ );++ parityTest(+ 'addLinksBatch inserts new edges, dedups conflicts and drops edges to missing pages',+ { methods: ['addLinksBatch', 'getLinks', 'putPage'] },+ async (engine) => {+ await seedPages(engine, ['b/one', 'b/two', 'b/three']);+ const batch: LinkBatchInput[] = [+ { from_slug: 'b/one', to_slug: 'b/two', link_type: 'cites', context: 'c1', link_source: 'manual' },+ { from_slug: 'b/one', to_slug: 'b/three', link_type: 'cites', context: 'c2', link_source: 'manual' },+ { from_slug: 'b/one', to_slug: 'b/missing', link_type: 'cites', link_source: 'manual' },+ { from_slug: 'b/two', to_slug: 'b/three' },+ ];+ const first = await engine.addLinksBatch(batch);+ const replay = await engine.addLinksBatch(batch);+ const empty = await engine.addLinksBatch([]);+ expect(first).toBe(3);+ expect(replay).toBe(0);+ expect(empty).toBe(0);+ const one = sortedLinks(await engine.getLinks('b/one'));+ const two = sortedLinks(await engine.getLinks('b/two'));+ return { first, replay, empty, one, two };+ },+ );++ parityTest(+ 'removeLink honors link type and provenance and returns the deleted row count',+ { methods: ['removeLink', 'addLink', 'getLinks', 'putPage'] },+ async (engine) => {+ await seedPages(engine, ['r/from', 'r/to']);+ const seed = async () => {+ await engine.addLink('r/from', 'r/to', 'x', 'cites', 'manual');+ await engine.addLink('r/from', 'r/to', 'y', 'cites', 'markdown');+ await engine.addLink('r/from', 'r/to', 'z', 'mentions', 'manual');+ };+ await seed();+ const typo = await engine.removeLink('r/from', 'r/typo');+ const wrongType = await engine.removeLink('r/from', 'r/to', 'nope');+ const wrongSource = await engine.removeLink('r/from', 'r/to', 'cites', 'frontmatter');+ expect(typo).toBe(0);+ expect(wrongType).toBe(0);+ expect(wrongSource).toBe(0);+ const typed = await engine.removeLink('r/from', 'r/to', 'cites', 'manual');+ expect(typed).toBe(1);+ const afterTyped = sortedLinks(await engine.getLinks('r/from')).map(linkKey);+ const allTypes = await engine.removeLink('r/from', 'r/to');+ expect(allTypes).toBe(2);+ const afterAll = await engine.getLinks('r/from');+ expect(afterAll).toEqual([]);+ const again = await engine.removeLink('r/from', 'r/to');+ await seed();+ const bySource = await engine.removeLink('r/from', 'r/to', undefined, 'manual');+ const left = sortedLinks(await engine.getLinks('r/from')).map(linkKey);+ return { typo, wrongType, wrongSource, typed, afterTyped, allTypes, again, bySource, left };+ },+ );++ parityTest(+ 'removeLinksByPagesAndSource deletes only the named provenance for the named pages',+ { methods: ['removeLinksByPagesAndSource', 'addLink', 'getLinks', 'putPage'] },+ async (engine) => {+ await seedPages(engine, ['m/a', 'm/b', 'm/c']);+ await engine.addLink('m/a', 'm/b', '', 'mentions', 'mentions');+ await engine.addLink('m/a', 'm/c', '', 'mentions', 'mentions');+ await engine.addLink('m/a', 'm/c', '', 'cites', 'manual');+ await engine.addLink('m/b', 'm/c', '', 'mentions', 'mentions');+ const none = await engine.removeLinksByPagesAndSource([], { linkSource: 'mentions' });+ const wrongSource = await engine.removeLinksByPagesAndSource([{ slug: 'm/a', source_id: 'nope' }], { linkSource: 'mentions' });+ expect(none).toBe(0);+ expect(wrongSource).toBe(0);+ // A keep list only protects typed_ner rows; mentions rows are removed regardless.+ const removed = await engine.removeLinksByPagesAndSource(+ [{ slug: 'm/a', source_id: 'default' }],+ { linkSource: 'mentions', keepTypedNerPairs: [{ from_slug: 'm/a', from_source_id: 'default', to_slug: 'm/b', to_source_id: 'default' }] },+ );+ expect(removed).toBe(2);+ return {+ none, wrongSource, removed,+ a: sortedLinks(await engine.getLinks('m/a')).map(linkKey),+ b: sortedLinks(await engine.getLinks('m/b')).map(linkKey),+ };+ },+ );++ parityTest(+ 'listLinkSources counts edges per provenance, count DESC then name ASC',+ { methods: ['listLinkSources', 'addLink', 'putPage'] },+ async (engine) => {+ await seedPages(engine, ['ls/a', 'ls/b', 'ls/c']);+ await engine.addLink('ls/a', 'ls/b', '', 'cites', 'citation-graph');+ await engine.addLink('ls/a', 'ls/c', '', 'cites', 'citation-graph');+ await engine.addLink('ls/b', 'ls/c', '', 'rel', 'manual');+ await engine.addLink('ls/c', 'ls/a', '', 'rel', 'markdown');+ const scoped = await engine.listLinkSources({ sourceId: 'default' });+ const federated = await engine.listLinkSources({ sourceIds: ['default'] });+ const other = await engine.listLinkSources({ sourceId: 'no-such-source' });+ expect(scoped.map((r) => r.link_source)).toEqual(['citation-graph', 'manual', 'markdown']);+ expect(other).toEqual([]);+ return { scoped, federated, other };+ },+ );++ parityTest(+ 'findByTitleFuzzy returns the best title match above the threshold, honoring prefix and source',+ { methods: ['findByTitleFuzzy', 'putPage'] },+ async (engine) => {+ await engine.putPage('people/alice-example', page('Alice Example', { type: 'person' }));+ await engine.putPage('people/alicia-example', page('Alicia Exampel', { type: 'person' }));+ await engine.putPage('companies/acme-example', page('Acme Example', { type: 'company' }));+ const exact = await engine.findByTitleFuzzy('Alice Example');+ const typo = await engine.findByTitleFuzzy('Alice Exmple', 'people');+ const wrongPrefix = await engine.findByTitleFuzzy('Alice Example', 'companies', 0.9);+ const none = await engine.findByTitleFuzzy('Totally Unrelated Zebra');+ const scoped = await engine.findByTitleFuzzy('Acme Example', 'companies', 0.55, 'default');+ const otherSource = await engine.findByTitleFuzzy('Acme Example', undefined, 0.55, 'no-such-source');+ expect(exact?.slug).toBe('people/alice-example');+ expect(exact?.similarity).toBeGreaterThan(0.9);+ expect(none).toBeNull();+ expect(otherSource).toBeNull();+ return {+ exact: exact && { slug: exact.slug, similarity: Math.round(exact.similarity * 1000) / 1000 },+ typo: typo?.slug,+ wrongPrefix: wrongPrefix?.slug ?? null,+ none,+ scoped: scoped?.slug,+ otherSource,+ };+ },+ );++ parityTest(+ 'replaceDerivedLinks swaps one origin\'s derived edges and leaves manual edges alone',+ { methods: ['replaceDerivedLinks', 'readPageSnapshot', 'addLink', 'getLinks', 'putPage'] },+ async (engine) => {+ await seedPages(engine, ['d/origin', 'd/one', 'd/two', 'd/three']);+ await engine.addLink('d/origin', 'd/three', 'manual keep', 'cites', 'manual');+ const origin = async () => {+ const snap = await engine.readPageSnapshot('d/origin', { sourceId: 'default' });+ expect(snap).not.toBeNull();+ return { slug: 'd/origin', sourceId: 'default', expectedRevision: snap!.revision, sourceIncarnation: snap!.sourceIncarnation };+ };+ const first = await engine.replaceDerivedLinks(await origin(), [+ { from_slug: 'd/origin', to_slug: 'd/one', link_type: 'cites', context: 'one', link_source: 'markdown' },+ { from_slug: 'd/origin', to_slug: 'd/two', link_type: 'cites', context: 'two', link_source: 'markdown' },+ { from_slug: 'd/origin', to_slug: 'd/two', link_type: 'cites', context: 'dup', link_source: 'markdown' },+ ]);+ const afterFirst = sortedLinks(await engine.getLinks('d/origin')).map(linkKey);+ const second = await engine.replaceDerivedLinks(await origin(), [+ { from_slug: 'd/origin', to_slug: 'd/one', link_type: 'cites', context: 'one', link_source: 'markdown' },+ ]);+ const afterSecond = sortedLinks(await engine.getLinks('d/origin')).map(linkKey);+ const cleared = await engine.replaceDerivedLinks(await origin(), []);+ const afterClear = sortedLinks(await engine.getLinks('d/origin')).map(linkKey);+ expect(first).toEqual({ created: 2, removed: 0 });+ expect(afterClear).toEqual(['d/origin>d/three:cites:manual']);+ return { first, afterFirst, second, afterSecond, cleared, afterClear };+ },+ );++ parityTest(+ 'replaceDerivedLinksBatch replaces many origins in one call',+ { methods: ['replaceDerivedLinksBatch', 'readPageSnapshot', 'getLinks', 'putPage'] },+ async (engine) => {+ await seedPages(engine, ['e/a', 'e/b', 'e/t1', 'e/t2']);+ const origin = async (slug: string) => {+ const snap = await engine.readPageSnapshot(slug, { sourceId: 'default' });+ return { slug, sourceId: 'default', expectedRevision: snap!.revision, sourceIncarnation: snap!.sourceIncarnation };+ };+ const items = [+ { origin: await origin('e/a'), links: [{ from_slug: 'e/a', to_slug: 'e/t1', link_type: 'cites', link_source: 'markdown' }] },+ { origin: await origin('e/b'), links: [+ { from_slug: 'e/b', to_slug: 'e/t1', link_type: 'cites', link_source: 'markdown' },+ { from_slug: 'e/b', to_slug: 'e/t2', link_type: 'cites', link_source: 'markdown' },+ ] },+ ];+ const results = await engine.replaceDerivedLinksBatch(items);+ const empty = await engine.replaceDerivedLinksBatch([]);+ expect(results).toEqual([{ created: 1, removed: 0 }, { created: 2, removed: 0 }]);+ const rerun = await engine.replaceDerivedLinksBatch([{ origin: await origin('e/b'), links: [] }]);+ return {+ results, empty, rerun,+ a: sortedLinks(await engine.getLinks('e/a')).map(linkKey),+ b: sortedLinks(await engine.getLinks('e/b')).map(linkKey),+ };+ },+ );++ parityTest(+ 'getLinks/getBacklinks hide soft-deleted endpoints and respect source scope',+ { methods: ['getLinks', 'getBacklinks', 'addLink', 'softDeletePage', 'restorePage', 'putPage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'alt');+ await seedPages(engine, ['s/from', 's/to']);+ await seedPages(engine, ['s/alt-doc'], 'note', { sourceId: 'alt' });+ await engine.addLink('s/from', 's/to', 'ctx', 'wikilink');+ await engine.addLink('s/from', 's/alt-doc', 'cross', 'cites', 'manual', undefined, undefined, { fromSourceId: 'default', toSourceId: 'alt' });+ const unscoped = sortedLinks(await engine.getLinks('s/from')).map(linkKey);+ const scalar = sortedLinks(await engine.getLinks('s/from', { sourceId: 'default' })).map(linkKey);+ // A federated grant constrains BOTH endpoints: the alt target must not leak.+ const grant = sortedLinks(await engine.getLinks('s/from', { sourceIds: ['default'] })).map(linkKey);+ const altBack = linkViews(await engine.getBacklinks('s/alt-doc', { sourceId: 'alt' }));+ const grantBack = await engine.getBacklinks('s/alt-doc', { sourceIds: ['alt'] });+ expect(grant).toEqual(['s/from>s/to:wikilink:markdown']);+ expect(grantBack).toEqual([]);+ await engine.softDeletePage('s/from');+ const hiddenOut = await engine.getLinks('s/from');+ const hiddenBack = await engine.getBacklinks('s/to');+ expect(hiddenOut).toEqual([]);+ expect(hiddenBack).toEqual([]);+ await engine.restorePage('s/from');+ const restoredBack = (await engine.getBacklinks('s/to')).map(linkKey);+ return { unscoped, scalar, grant, altBack, grantBack, hiddenOut, hiddenBack, restoredBack };+ },+ );+});++describe('engine parity: graph traversal', () => {+ const nodeShape = (nodes: Awaited<ReturnType<BrainEngine['traverseGraph']>>) =>+ sorted(nodes.map((n) => `${n.source_id}:${n.slug}@${n.depth}[${n.links.map((l) => `${l.to_slug}:${l.link_type}`).sort().join(',')}]`));+ // Not sorted: ORDER BY depth, from_slug, to_slug is part of the traversePaths contract.+ const edgeShape = (paths: Awaited<ReturnType<BrainEngine['traversePaths']>>) =>+ paths.map((p) => `${p.from_slug}>${p.to_slug}:${p.link_type}@${p.depth}`);++ parityTest(+ 'traverseGraph returns identical nodes for depth 1..3 and survives a cycle',+ { methods: ['traverseGraph'] },+ async (engine) => {+ await seedChain(engine);+ const byDepth: Record<number, string[]> = {};+ for (const depth of [1, 2, 3]) byDepth[depth] = nodeShape(await engine.traverseGraph('tg/a', depth));+ const deep = nodeShape(await engine.traverseGraph('tg/a', 10));+ const missing = await engine.traverseGraph('tg/nope', 3);+ expect(deep.map((n) => n.split('@')[0])).toEqual(['default:tg/a', 'default:tg/b', 'default:tg/c', 'default:tg/d']);+ expect(missing).toEqual([]);+ return { byDepth, deep, missing };+ },+ );++ parityTest(+ 'traverseGraph source scope keeps cross-source nodes out of a scoped walk',+ { methods: ['traverseGraph', 'addLink', 'putPage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'tg-alt');+ await seedChain(engine);+ await seedPages(engine, ['tg/x'], 'note', { sourceId: 'tg-alt' });+ await engine.addLink('tg/b', 'tg/x', 'x-ctx', 'xsrc', 'manual', undefined, undefined, { fromSourceId: 'default', toSourceId: 'tg-alt' });+ const unscoped = nodeShape(await engine.traverseGraph('tg/a', 3));+ const scalar = nodeShape(await engine.traverseGraph('tg/a', 3, { sourceId: 'default' }));+ const federated = nodeShape(await engine.traverseGraph('tg/a', 3, { sourceIds: ['default'] }));+ const both = nodeShape(await engine.traverseGraph('tg/a', 3, { sourceIds: ['default', 'tg-alt'] }));+ expect(unscoped.some((n) => n.includes('tg-alt:tg/x'))).toBe(true);+ expect(scalar.some((n) => n.includes('tg/x'))).toBe(false);+ expect(federated).toEqual(scalar);+ return { unscoped, scalar, federated, both };+ },+ );++ parityTest(+ 'traversePaths returns ordered edges across depth and direction, with link type filter',+ { methods: ['traversePaths'] },+ async (engine) => {+ await seedChain(engine);+ const out: Record<string, string[]> = {};+ for (const depth of [1, 2, 3]) {+ for (const direction of ['in', 'out', 'both'] as const) {+ out[`${direction}@${depth}`] = edgeShape(await engine.traversePaths('tg/b', { depth, direction }));+ }+ }+ const typed = edgeShape(await engine.traversePaths('tg/a', { depth: 5, direction: 'out', linkType: 'cycle-fwd' }));+ const typedMiss = await engine.traversePaths('tg/a', { depth: 5, direction: 'out', linkType: 'no-such-type' });+ const context = (await engine.traversePaths('tg/c', { depth: 1, direction: 'out' })).map((p) => pick(p, ['from_slug', 'to_slug', 'link_type', 'context', 'depth', 'from_source_id', 'to_source_id']));+ expect(out['out@1']).toEqual(['tg/b>tg/a:cycle-back@1', 'tg/b>tg/c:step@1']);+ expect(typed).toEqual(['tg/a>tg/b:cycle-fwd@1']);+ expect(typedMiss).toEqual([]);+ return { out, typed, typedMiss, context };+ },+ );++ parityTest(+ 'traversePaths source scope: scalar and federated grants stop at the source boundary',+ { methods: ['traversePaths', 'addLink', 'putPage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'tg-alt');+ await seedChain(engine);+ await seedPages(engine, ['tg/x'], 'note', { sourceId: 'tg-alt' });+ await engine.addLink('tg/b', 'tg/x', 'x-ctx', 'xsrc', 'manual', undefined, undefined, { fromSourceId: 'default', toSourceId: 'tg-alt' });+ const unscoped = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out' }));+ const scalar = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out', sourceId: 'default' }));+ const federated = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out', sourceIds: ['default'] }));+ expect(unscoped.some((e) => e.includes('tg/x'))).toBe(true);+ expect(scalar.some((e) => e.includes('tg/x'))).toBe(false);+ return { unscoped, scalar, federated };+ },+ );++ parityTest(+ 'traversePathsDetailed reports the paths and an untruncated walk',+ { methods: ['traversePathsDetailed'] },+ async (engine) => {+ await seedChain(engine);+ const shallow = await engine.traversePathsDetailed('tg/a', { depth: 1, direction: 'both' });+ const deep = await engine.traversePathsDetailed('tg/a', { depth: 4, direction: 'out' });+ const scoped = await engine.traversePathsDetailed('tg/a', { depth: 4, direction: 'out', sourceIds: ['default'], linkType: 'step' });+ expect(shallow.truncated).toBe(false);+ expect(deep.truncated).toBe(false);+ return { shallow: edgeShape(shallow.paths), deep: edgeShape(deep.paths), scoped: edgeShape(scoped.paths), truncated: [shallow.truncated, deep.truncated, scoped.truncated] };+ },+ );++ parityTest(+ 'traversal hides soft-deleted pages and recovers them after restore',+ { methods: ['traverseGraph', 'traversePaths', 'softDeletePage', 'restorePage'] },+ async (engine) => {+ await seedChain(engine);+ await engine.softDeletePage('tg/b');+ const graph = nodeShape(await engine.traverseGraph('tg/a', 3));+ const paths = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'both' }));+ const fromDeleted = await engine.traversePaths('tg/b', { depth: 3, direction: 'out' });+ expect(paths).toEqual([]);+ expect(fromDeleted).toEqual([]);+ await engine.restorePage('tg/b');+ const restored = edgeShape(await engine.traversePaths('tg/a', { depth: 3, direction: 'out' }));+ expect(restored.length).toBeGreaterThan(0);+ return { graph, paths, fromDeleted, restored };+ },+ );+});++describe('engine parity: relational fan-out', () => {+ async function seedRelational(engine: BrainEngine) {+ const ids = new Map<string, number>();+ const pages: Array<[string, PageType]> = [+ ['companies/ep-widget', 'company'], ['companies/ep-other', 'company'],+ ['people/ep-inv-a', 'person'], ['people/ep-inv-b', 'person'], ['people/ep-emp-c', 'person'], ['people/ep-mentioner', 'person'],+ ];+ for (const [slug, type] of pages) ids.set(slug, (await engine.putPage(slug, page(slug, { type }))).id);+ await engine.addLink('people/ep-inv-a', 'companies/ep-widget', '', 'invested_in', 'manual');+ await engine.addLink('people/ep-inv-b', 'companies/ep-widget', '', 'invested_in', 'manual');+ await engine.addLink('people/ep-emp-c', 'companies/ep-widget', '', 'works_at', 'manual');+ await engine.addLink('people/ep-mentioner', 'companies/ep-widget', '', 'mentions', 'mentions');+ await engine.addLink('people/ep-inv-a', 'companies/ep-other', '', 'invested_in', 'manual');+ return ids;+ }+ // canonical_chunk_id is a serial id: compare its presence only.+ const shape = (rows: Awaited<ReturnType<BrainEngine['relationalFanout']>>) =>+ rows.map((r) => `${r.source_id}:${r.slug}:${r.hop}:${r.edge_count}:${r.via_link_types.join(',')}:${r.path.join('>')}:${r.canonical_chunk_id != null ? 'chunk' : 'nochunk'}`);++ parityTest(+ 'relationalFanout walks typed edges, excludes mentions by default and orders deterministically',+ { methods: ['relationalFanout', 'upsertChunks'] },+ async (engine) => {+ await seedRelational(engine);+ await engine.upsertChunks('people/ep-inv-b', [{ chunk_index: 0, chunk_text: 'inv b chunk', chunk_source: 'compiled_truth', token_count: 3 }]);+ const typed = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', linkTypes: ['invested_in'] }));+ const agnostic = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in' }));+ const withMentions = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', includeMentions: true }));+ const connects = shape(await engine.relationalFanout(['companies/ep-widget', 'companies/ep-other'], { direction: 'both' }));+ const limited = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', limit: 1 }));+ const scoped = shape(await engine.relationalFanout(['companies/ep-widget'], { direction: 'in', sourceIds: ['no-such-source'] }));+ expect(typed.map((r) => r.split(':')[1])).toEqual(['people/ep-inv-a', 'people/ep-inv-b']);+ expect(agnostic.some((r) => r.includes('ep-mentioner'))).toBe(false);+ expect(withMentions.some((r) => r.includes('ep-mentioner'))).toBe(true);+ expect(limited.length).toBe(1);+ expect(scoped).toEqual([]);+ return { typed, agnostic, withMentions, connects, limited, scoped };+ },+ );++ parityTest(+ 'relationalChainHop orients and collapses edges from frontier page ids',+ { methods: ['relationalChainHop', 'addLink'] },+ async (engine) => {+ const ids = await seedRelational(engine);+ await engine.addLink('companies/ep-widget', 'people/ep-emp-c', 'founded by c', 'founded', 'markdown');+ const slugOf = new Map([...ids].map(([slug, id]) => [id, slug]));+ const edgeView = (edges: Awaited<ReturnType<BrainEngine['relationalChainHop']>>) => edges.map((e) => ({+ from: slugOf.get(e.from_page_id),+ to: e.to_slug,+ to_type: e.to_type,+ link_type: e.link_type,+ orientation: e.orientation,+ link_count: e.link_ids.length,+ stored_from: e.stored_from_slug,+ stored_to: e.stored_to_slug,+ context: e.context,+ from_degree: e.from_degree,+ neighbor_cap_hit: e.neighbor_cap_hit,+ }));+ const toObject = edgeView(await engine.relationalChainHop([ids.get('people/ep-inv-a')!], {+ linkTypes: linkFamily('invested_in'), toward: 'object', subjectTypes: ['company', 'person'],+ objectTypes: ['company', 'deal'], degreeLinkTypes: ['invested_in', 'founded'], neighborCap: 100,+ }));+ const toSubject = edgeView(await engine.relationalChainHop([ids.get('companies/ep-widget')!], {+ linkTypes: ['founded'], toward: 'subject', subjectTypes: ['person'], objectTypes: ['company'],+ degreeLinkTypes: ['founded'], neighborCap: 100,+ }));+ const capped = edgeView(await engine.relationalChainHop([ids.get('companies/ep-widget')!], {+ linkTypes: linkFamily('invested_in'), toward: 'subject', subjectTypes: ['person', 'company'],+ objectTypes: ['company', 'deal'], degreeLinkTypes: ['invested_in'], neighborCap: 1,+ }));+ const empty = await engine.relationalChainHop([], {+ linkTypes: ['founded'], toward: 'object', subjectTypes: ['person'], objectTypes: ['company'], degreeLinkTypes: ['founded'], neighborCap: 5,+ });+ expect(toObject.map((e) => e.to).sort()).toEqual(['companies/ep-other', 'companies/ep-widget']);+ expect(toSubject.map((e) => e.to)).toEqual(['people/ep-emp-c']);+ expect(empty).toEqual([]);+ return { toObject: sorted(toObject, (e) => e.to), toSubject, capped, empty };+ },+ );+});++describe('engine parity: backlink and page signal reads', () => {+ parityTest(+ 'getBacklinkCounts counts distinct linkers per page id, excluding mentions',+ { methods: ['getBacklinkCounts', 'addLink'] },+ async (engine) => {+ const ids = await seedPages(engine, ['bc/hub', 'bc/leaf', 'bc/one', 'bc/two', 'bc/three']);+ await engine.addLink('bc/one', 'bc/hub', '', 'cites', 'manual');+ await engine.addLink('bc/two', 'bc/hub', '', 'cites', 'manual');+ await engine.addLink('bc/two', 'bc/hub', '', 'related', 'manual');+ await engine.addLink('bc/three', 'bc/hub', '', 'mentions', 'mentions');+ await engine.addLink('bc/hub', 'bc/leaf', '', 'cites', 'manual');+ const counts = await engine.getBacklinkCounts([...ids.values()]);+ const scoped = await engine.getBacklinkCounts([ids.get('bc/hub')!, ids.get('bc/leaf')!], { sourceIds: ['default'] });+ const none = await engine.getBacklinkCounts([]);+ expect(counts.get(ids.get('bc/hub')!)).toBe(2);+ expect(none.size).toBe(0);+ return { counts: bySlug(ids, counts), scoped: bySlug(ids, scoped), none: none.size };+ },+ );++ parityTest(+ 'getAdjacencyBoosts aggregates in-set linkers only',+ { methods: ['getAdjacencyBoosts', 'addLink'] },+ async (engine) => {+ const ids = await seedPages(engine, ['adj/a', 'adj/b', 'adj/c', 'adj/outside']);+ await engine.addLink('adj/a', 'adj/c', '', 'cites', 'manual');+ await engine.addLink('adj/b', 'adj/c', '', 'cites', 'manual');+ await engine.addLink('adj/outside', 'adj/c', '', 'cites', 'manual');+ await engine.addLink('adj/a', 'adj/b', '', 'mentions', 'mentions');+ const inSet = [ids.get('adj/a')!, ids.get('adj/b')!, ids.get('adj/c')!];+ const boosts = await engine.getAdjacencyBoosts(inSet);+ const scoped = await engine.getAdjacencyBoosts(inSet, { sourceIds: ['default'] });+ const empty = await engine.getAdjacencyBoosts([]);+ expect(boosts.get(ids.get('adj/c')!)?.hits).toBe(2);+ expect(empty.size).toBe(0);+ return { boosts: bySlug(ids, boosts), scoped: bySlug(ids, scoped), empty: empty.size };+ },+ );++ parityTest(+ 'getContentFlagsByPageIds and getUnverifiedExtractionPageIds read frontmatter markers',+ { methods: ['getContentFlagsByPageIds', 'getUnverifiedExtractionPageIds', 'putPage'] },+ async (engine) => {+ const ids = new Map<string, number>();+ const put = async (slug: string, frontmatter: Record<string, unknown>) => {+ ids.set(slug, (await engine.putPage(slug, page(slug, { frontmatter }))).id);+ };+ await put('fm/flagged', { content_flag: { reason: 'markup_heavy', detail: '80% tags' } });+ await put('fm/stub', { provenance: 'auto-extracted', status: 'unverified' });+ await put('fm/verified', { provenance: 'auto-extracted', status: 'verified' });+ await put('fm/draft', { status: 'draft' });+ await put('fm/plain', {});+ const all = [...ids.values()];+ const flags = await engine.getContentFlagsByPageIds(all);+ const unverified = await engine.getUnverifiedExtractionPageIds(all);+ const emptyFlags = await engine.getContentFlagsByPageIds([]);+ const emptyUnverified = await engine.getUnverifiedExtractionPageIds([]);+ expect(flags.size).toBe(1);+ expect(emptyFlags.size).toBe(0);+ expect(emptyUnverified.size).toBe(0);+ return { flags: bySlug(ids, flags), unverified: bySlug(ids, unverified) };+ },+ );++ parityTest(+ 'getPageTimestamps and getEffectiveDates return dates only for existing live pages',+ { methods: ['getPageTimestamps', 'getEffectiveDates', 'putPage', 'softDeletePage'] },+ async (engine) => {+ await engine.putPage('ts/dated', page('dated', { effective_date: new Date('2024-03-05T00:00:00Z'), effective_date_source: 'date' }));+ await engine.putPage('ts/undated', page('undated'));+ await engine.putPage('ts/gone', page('gone'));+ await engine.softDeletePage('ts/gone');+ const stamps = await engine.getPageTimestamps(['ts/dated', 'ts/undated', 'ts/missing']);+ const refs = ['ts/dated', 'ts/undated', 'ts/missing', 'ts/gone'].map((slug) => ({ slug, source_id: 'default' }));+ const dates = await engine.getEffectiveDates(refs);+ const wrongSource = await engine.getEffectiveDates([{ slug: 'ts/dated', source_id: 'no-such-source' }]);+ const none = await engine.getEffectiveDates([]);+ expect(dates.get('default::ts/dated')?.toISOString()).toBe('2024-03-05T00:00:00.000Z');+ expect(dates.has('default::ts/missing')).toBe(false);+ expect(wrongSource.size).toBe(0);+ expect(none.size).toBe(0);+ return {+ stampSlugs: sorted([...stamps.keys()]),+ stampsAreDates: [...stamps.values()].every((d) => d instanceof Date),+ dateKeys: sorted([...dates.keys()]),+ dated: dates.get('default::ts/dated')?.toISOString(),+ wrongSource: wrongSource.size,+ };+ },+ );++ parityTest(+ 'getSalienceScores combines emotional weight and take count',+ { methods: ['getSalienceScores', 'setEmotionalWeightBatch', 'addTakesBatch', 'putPage'] },+ async (engine) => {+ const ids = await seedPages(engine, ['sal/plain', 'sal/weighted', 'sal/taken']);+ await engine.setEmotionalWeightBatch([{ slug: 'sal/weighted', source_id: 'default', weight: 0.4 }]);+ await engine.addTakesBatch([+ { page_id: ids.get('sal/taken')!, row_num: 1, claim: 'a take', kind: 'take', holder: 'garry' },+ { page_id: ids.get('sal/taken')!, row_num: 2, claim: 'another take', kind: 'take', holder: 'garry' },+ ]);+ const refs = ['sal/plain', 'sal/weighted', 'sal/taken', 'sal/missing'].map((slug) => ({ slug, source_id: 'default' }));+ const scores = await engine.getSalienceScores(refs);+ const none = await engine.getSalienceScores([]);+ const round = (n: number | undefined) => (n === undefined ? null : Math.round(n * 1e6) / 1e6);+ expect(none.size).toBe(0);+ return {+ keys: sorted([...scores.keys()]),+ plain: round(scores.get('default::sal/plain')),+ weighted: round(scores.get('default::sal/weighted')),+ taken: round(scores.get('default::sal/taken')),+ missing: round(scores.get('default::sal/missing')),+ };+ },+ );++ parityTest(+ 'findOrphanPages: islanded default vs inbound mode, with source scope',+ { methods: ['findOrphanPages', 'addLink', 'putPage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'orphan-src');+ await seedPages(engine, ['people/op-island', 'people/op-target', 'people/op-linker'], 'person');+ await seedPages(engine, ['people/op-alt-island'], 'person', { sourceId: 'orphan-src' });+ await engine.addLink('people/op-linker', 'people/op-target', '', 'cites', 'manual');+ const view = async (opts?: Parameters<BrainEngine['findOrphanPages']>[0]) =>+ sorted((await engine.findOrphanPages(opts)).map((r) => `${r.source_id ?? 'default'}:${r.slug}`));+ const islanded = await view();+ const inbound = await view({ mode: 'inbound' });+ const scopedDefault = await view({ sourceId: 'default' });+ const scopedAlt = await view({ sourceId: 'orphan-src' });+ const federated = await view({ sourceIds: ['default', 'orphan-src'] });+ expect(islanded).toEqual(['default:people/op-island', 'orphan-src:people/op-alt-island']);+ expect(inbound).toEqual(['default:people/op-island', 'default:people/op-linker', 'orphan-src:people/op-alt-island']);+ return { islanded, inbound, scopedDefault, scopedAlt, federated };+ },+ );+});diff --git a/test/engine-parity/pages.test.ts b/test/engine-parity/pages.test.tsnew file mode 100644index 0000000000..8475f63382--- /dev/null+++ b/test/engine-parity/pages.test.ts@@ -0,0 +1,360 @@+/**+ * BrainEngine parity — pages family (CRUD, soft delete, listing, slugs, tags).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every page read/write method returns the same observable+ * result on every engine arm (PGLite always; Postgres with DATABASE_URL;+ * a Rust arm later through test/engine-parity/harness.ts).+ * - Regression: an engine that drifts on page round-trip, soft-delete+ * visibility, slug resolution, listing order or tag sets — the read+ * paths every brain query starts from.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and covers mostly search/graph; the+ * per-engine unit tests never compare two engines on one scenario.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import { parseFindPattern } from '../../src/core/page-find.ts';+import type { Page, PageInput } from '../../src/core/types.ts';+import { createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const PAGE_KEYS = ['slug', 'type', 'title', 'compiled_truth', 'timeline', 'frontmatter'] as const;++function view(page: Page | null) {+ return page ? pick(page, PAGE_KEYS) : null;+}++async function seed(engine: BrainEngine, pages: Array<[string, PageInput]>, opts?: { sourceId?: string }) {+ for (const [slug, input] of pages) await engine.putPage(slug, input, opts);+}++const ALICE: PageInput = {+ type: 'person',+ title: 'Alice Example',+ compiled_truth: 'Alice runs product at acme-example.',+ timeline: '- 2026-01-02: joined acme-example',+ frontmatter: { role: 'pm', tags: ['founder'] },+};+const ACME: PageInput = { type: 'company', title: 'Acme Example', compiled_truth: 'Acme builds widgets.', timeline: '' };+const NOTE: PageInput = { type: 'note', title: 'Weekly note', compiled_truth: 'Met alice-example about widgets.', timeline: '' };++describe('engine parity: pages', () => {+ parityTest('putPage then getPage round-trips the page', { methods: ['putPage', 'getPage'] }, async (engine) => {+ const written = await engine.putPage('people/alice-example', ALICE);+ expect(written.slug).toBe('people/alice-example');+ const read = await engine.getPage('people/alice-example');+ expect(read?.title).toBe('Alice Example');+ expect(read?.frontmatter.role).toBe('pm');+ const missing = await engine.getPage('people/nobody');+ expect(missing).toBeNull();+ return { written: view(written), read: view(read), missing };+ });++ parityTest('putPage on an existing slug updates in place', { methods: ['putPage', 'getPage', 'listPages'] }, async (engine) => {+ const first = await engine.putPage('companies/acme-example', ACME);+ const second = await engine.putPage('companies/acme-example', { ...ACME, compiled_truth: 'Acme builds better widgets.' });+ expect(second.id).toBe(first.id);+ const read = await engine.getPage('companies/acme-example');+ expect(read?.compiled_truth).toBe('Acme builds better widgets.');+ const all = await engine.listPages();+ expect(all.map((p) => p.slug)).toEqual(['companies/acme-example']);+ return { read: view(read), count: all.length };+ });++ parityTest(+ 'softDeletePage hides a page; restorePage brings it back',+ { methods: ['softDeletePage', 'restorePage', 'getPage', 'listPages', 'getAllSlugs'] },+ async (engine) => {+ await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME]]);+ const deleted = await engine.softDeletePage('people/alice-example');+ expect(deleted).toEqual({ slug: 'people/alice-example' });+ const again = await engine.softDeletePage('people/alice-example');+ const hidden = await engine.getPage('people/alice-example');+ expect(hidden).toBeNull();+ const visibleWithFlag = await engine.getPage('people/alice-example', { includeDeleted: true });+ expect(visibleWithFlag?.deleted_at).toBeInstanceOf(Date);+ const listed = (await engine.listPages()).map((p) => p.slug);+ const slugsWhileDeleted = sorted(await engine.getAllSlugs());+ const restored = await engine.restorePage('people/alice-example');+ expect(restored).toBe(true);+ const restoredAgain = await engine.restorePage('people/alice-example');+ expect(restoredAgain).toBe(false);+ const back = await engine.getPage('people/alice-example');+ expect(back?.deleted_at ?? null).toBeNull();+ return { again, listed, slugsWhileDeleted, back: view(back) };+ },+ );++ parityTest('deletePage removes the page for good', { methods: ['deletePage', 'getPage', 'getAllSlugs'] }, async (engine) => {+ await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME]]);+ await engine.deletePage('people/alice-example');+ const gone = await engine.getPage('people/alice-example', { includeDeleted: true });+ expect(gone).toBeNull();+ const slugs = sorted(await engine.getAllSlugs());+ expect(slugs).toEqual(['companies/acme-example']);+ return { slugs };+ });++ parityTest('listPages filters by type, tag, prefix and limit', { methods: ['listPages', 'addTag'] }, async (engine) => {+ await seed(engine, [+ ['people/alice-example', ALICE],+ ['people/charlie-example', { ...ALICE, title: 'Charlie Example', frontmatter: {} }],+ ['companies/acme-example', ACME],+ ['notes/weekly', NOTE],+ ]);+ await engine.addTag('companies/acme-example', 'portfolio');+ const byType = sorted((await engine.listPages({ type: 'person' })).map((p) => p.slug));+ expect(byType).toEqual(['people/alice-example', 'people/charlie-example']);+ const byTag = (await engine.listPages({ tag: 'portfolio' })).map((p) => p.slug);+ expect(byTag).toEqual(['companies/acme-example']);+ const byPrefix = sorted((await engine.listPages({ slugPrefix: 'people/' })).map((p) => p.slug));+ expect(byPrefix).toEqual(byType);+ const limited = await engine.listPages({ limit: 2 });+ expect(limited.length).toBe(2);+ return { byType, byTag, byPrefix, limitedCount: limited.length };+ });++ parityTest('resolveSlugs matches exact and partial slugs', { methods: ['resolveSlugs'] }, async (engine) => {+ await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME], ['notes/weekly', NOTE]]);+ const exact = await engine.resolveSlugs('people/alice-example');+ expect(exact).toEqual(['people/alice-example']);+ const partial = sorted(await engine.resolveSlugs('example'));+ const none = await engine.resolveSlugs('zzz-no-such-page');+ return { exact, partial, none };+ });++ parityTest('addTag, getTags and removeTag keep a set per page', { methods: ['addTag', 'getTags', 'removeTag'] }, async (engine) => {+ await seed(engine, [['companies/acme-example', ACME]]);+ await engine.addTag('companies/acme-example', 'portfolio');+ await engine.addTag('companies/acme-example', 'b2b');+ await engine.addTag('companies/acme-example', 'portfolio');+ const tags = sorted(await engine.getTags('companies/acme-example'));+ expect(tags).toEqual(['b2b', 'portfolio']);+ await engine.removeTag('companies/acme-example', 'b2b');+ const after = await engine.getTags('companies/acme-example');+ expect(after).toEqual(['portfolio']);+ return { tags, after };+ });++ parityTest('pages are scoped per source', { methods: ['putPage', 'getPage', 'getAllSlugs', 'listAllSources'] }, async (engine) => {+ const sources = (await engine.listAllSources()).map((s) => s.id);+ expect(sources).toContain('default');+ await seed(engine, [['people/alice-example', ALICE]]);+ const defaultSlugs = sorted(await engine.getAllSlugs({ sourceId: 'default' }));+ const otherSlugs = sorted(await engine.getAllSlugs({ sourceId: 'no-such-source' }));+ expect(otherSlugs).toEqual([]);+ const scopedMiss = await engine.getPage('people/alice-example', { sourceId: 'no-such-source' });+ expect(scopedMiss).toBeNull();+ return { sources: sorted(sources), defaultSlugs, otherSlugs };+ });+ parityTest(+ 'readPageSnapshot and readPageSnapshotsBatch return page, tags and a revision',+ { methods: ['readPageSnapshot', 'readPageSnapshotsBatch'] },+ async (engine) => {+ await seed(engine, [['people/alice-example', ALICE], ['companies/acme-example', ACME]]);+ await engine.addTag('people/alice-example', 'founder');+ const snap = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });+ expect(snap?.page.slug).toBe('people/alice-example');+ expect(typeof snap?.revision).toBe('string');+ const missing = await engine.readPageSnapshot('people/nobody', { sourceId: 'default' });+ expect(missing).toBeNull();+ const batch = await engine.readPageSnapshotsBatch([+ { slug: 'people/alice-example', sourceId: 'default' },+ { slug: 'people/nobody', sourceId: 'default' },+ { slug: 'companies/acme-example', sourceId: 'default' },+ ]);+ expect(batch.covered).toBe(3);+ const keys = sorted([...batch.snapshots.values()].map((v) => v.page.slug));+ expect(keys).toEqual(['companies/acme-example', 'people/alice-example']);+ const sameRevision = [...batch.snapshots.values()].find((v) => v.page.slug === 'people/alice-example')?.revision === snap?.revision;+ expect(sameRevision).toBe(true);+ await engine.putPage('people/alice-example', { ...ALICE, compiled_truth: 'Alice now runs design.' }, { expectedRevision: snap!.revision });+ const after = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });+ expect(after?.revision).not.toBe(snap?.revision);+ return { page: view(snap!.page), tags: snap!.tags, withdrawals: snap!.withdrawals, keys, covered: batch.covered, sameRevision };+ },+ );++ parityTest('putPage refuses a stale expectedRevision', { methods: ['putPage', 'readPageSnapshot'] }, async (engine) => {+ await seed(engine, [['people/alice-example', ALICE]]);+ const snap = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });+ await engine.putPage('people/alice-example', { ...ALICE, compiled_truth: 'first edit' }, { expectedRevision: snap!.revision });+ let code: string | null = null;+ try {+ await engine.putPage('people/alice-example', { ...ALICE, compiled_truth: 'second edit' }, { expectedRevision: snap!.revision });+ } catch (error) {+ code = (error as { code?: string }).code ?? 'threw';+ }+ expect(code).toBe('revision_conflict');+ const read = await engine.readPageSnapshot('people/alice-example', { sourceId: 'default' });+ expect(read?.page.compiled_truth).toBe('first edit');+ return { code, body: read?.page.compiled_truth };+ });++ parityTest('lockPageKeys holds keys inside a transaction', { methods: ['lockPageKeys', 'transaction'] }, async (engine) => {+ await seed(engine, [['people/alice-example', ALICE]]);+ const result = await engine.transaction(async (tx) => {+ await tx.lockPageKeys([{ sourceId: 'default', slug: 'people/alice-example' }, { sourceId: 'default', slug: 'people/absent' }]);+ return (await tx.getPage('people/alice-example'))?.title ?? null;+ });+ // The recorded call must be on the handle too: lock nothing outside a transaction is a refusal.+ let outside: string | null = null;+ try {+ await engine.lockPageKeys([{ sourceId: 'default', slug: 'people/alice-example' }]);+ outside = 'ok';+ } catch {+ outside = 'refused';+ }+ expect(result).toBe('Alice Example');+ return { result, outside };+ });++ parityTest(+ 'findDuplicatePage(s) match by content hash or frontmatter id, never the page itself',+ { methods: ['findDuplicatePage', 'findDuplicatePages'] },+ async (engine) => {+ const a = await engine.putPage('notes/a', { ...NOTE, frontmatter: { id: 'ext-1' } });+ await engine.putPage('notes/b', { ...NOTE, title: 'Other', compiled_truth: 'different body' });+ const byHash = await engine.findDuplicatePage!('default', { hash: a.content_hash! });+ expect(byHash?.slug).toBe('notes/a');+ const self = await engine.findDuplicatePage!('default', { hash: a.content_hash!, excludeSlug: 'notes/a' });+ expect(self).toBeNull();+ const byId = await engine.findDuplicatePage!('default', { hash: 'no-such-hash', frontmatterId: 'ext-1' });+ expect(byId?.slug).toBe('notes/a');+ const many = await engine.findDuplicatePages!('default', [+ { hash: a.content_hash! },+ { hash: 'no-such-hash' },+ { hash: 'no-such-hash', frontmatterId: 'ext-1', excludeSlug: 'notes/a' },+ ]);+ expect(many.map((m) => m?.slug ?? null)).toEqual(['notes/a', null, null]);+ return { byHash: byHash?.slug, self, byId: byId?.slug, many: many.map((m) => m?.slug ?? null) };+ },+ );++ parityTest('deletePages and softDeletePages report only real transitions', { methods: ['deletePages', 'softDeletePages', 'getAllSlugs'] }, async (engine) => {+ await seed(engine, [['notes/a', NOTE], ['notes/b', NOTE], ['notes/c', NOTE], ['notes/d', NOTE]]);+ const soft = sorted(await engine.softDeletePages(['notes/a', 'notes/b', 'notes/missing'], { sourceId: 'default' }));+ expect(soft).toEqual(['notes/a', 'notes/b']);+ const softAgain = await engine.softDeletePages(['notes/a'], { sourceId: 'default' });+ expect(softAgain).toEqual([]);+ const softEmpty = await engine.softDeletePages([], { sourceId: 'default' });+ const hard = sorted(await engine.deletePages(['notes/a', 'notes/c', 'notes/missing'], { sourceId: 'default' }));+ expect(hard).toEqual(['notes/a', 'notes/c']);+ const remaining = sorted(await engine.getAllSlugs());+ return { soft, softAgain, softEmpty, hard, remaining };+ });++ parityTest('purgeDeletedPages only purges tombstones past the cutoff', { methods: ['purgeDeletedPages', 'softDeletePage'] }, async (engine) => {+ await seed(engine, [['notes/a', NOTE], ['notes/b', NOTE]]);+ await engine.softDeletePage('notes/a');+ const notYet = await engine.purgeDeletedPages(72);+ expect(notYet.count).toBe(0);+ const dry = await engine.purgeDeletedPages(0, { dryRun: true });+ expect(dry.slugs).toEqual(['notes/a']);+ const stillThere = (await engine.getPage('notes/a', { includeDeleted: true }))?.slug ?? null;+ const real = await engine.purgeDeletedPages(0);+ expect(real.slugs).toEqual(['notes/a']);+ const gone = await engine.getPage('notes/a', { includeDeleted: true });+ expect(gone).toBeNull();+ return {+ notYet: { slugs: notYet.slugs, count: notYet.count },+ dry: { slugs: dry.slugs, count: dry.count, pages: dry.pages?.map((p) => ({ slug: p.slug, source_id: p.source_id })) },+ stillThere,+ real: { slugs: real.slugs, count: real.count },+ };+ });++ parityTest('resolveSlugsByPaths maps stored source paths to slugs', { methods: ['resolveSlugsByPaths'] }, async (engine) => {+ await seed(engine, [['notes/a', { ...NOTE, source_path: 'Notes/A File.md' }], ['notes/b', NOTE]]);+ const empty = await engine.resolveSlugsByPaths([], { sourceId: 'default' });+ expect(empty.size).toBe(0);+ const found = await engine.resolveSlugsByPaths(['Notes/A File.md', 'notes/zzz.md'], { sourceId: 'default' });+ expect([...found]).toEqual([['Notes/A File.md', 'notes/a']]);+ const otherSource = await engine.resolveSlugsByPaths(['Notes/A File.md'], { sourceId: 'no-such-source' });+ expect(otherSource.size).toBe(0);+ return { empty: [...empty], found: [...found], otherSource: [...otherSource] };+ });++ parityTest('findPages matches name, prefix and glob patterns', { methods: ['findPages'] }, async (engine) => {+ await seed(engine, [['people/alice-example', ALICE], ['people/charlie-example', { ...ALICE, title: 'Charlie Example' }], ['companies/acme-example', ACME]]);+ const run = async (raw: string, types?: string[]) => {+ const found = await engine.findPages({ pattern: parseFindPattern(raw), limit: 10, types, excludeSlugPrefixes: [] });+ return { total: found.total, rows: sorted(found.rows.map((r) => `${r.source_id}:${r.slug}:${r.type}`)) };+ };+ const name = await run('alice');+ expect(name.rows).toEqual(['default:people/alice-example:person']);+ const prefix = await run('people/');+ expect(prefix.total).toBe(2);+ const glob = await run('*example', ['company']);+ expect(glob.rows).toEqual(['default:companies/acme-example:company']);+ return { name, prefix, glob };+ });++ parityTest('countPagesBy counts live pages per source and type', { methods: ['countPagesBy'] }, async (engine) => {+ await seed(engine, [['people/alice-example', ALICE], ['people/charlie-example', ALICE], ['companies/acme-example', ACME], ['notes/a', NOTE]]);+ await engine.softDeletePage('notes/a');+ const plain = await engine.countPagesBy({});+ const grouped = await engine.countPagesBy({}, (types) => types.map((t) => (t === 'person' ? 'people' : 'other')));+ expect(plain.total).toEqual({ pages: 3, distinct_slugs: 3 });+ return {+ bySourceType: sorted(plain.bySourceType, (r) => `${r.source_id}:${r.type}`),+ total: plain.total,+ byTypeGroup: sorted(grouped.byTypeGroup, (r) => r.group),+ };+ });++ parityTest('listAllPageRefs lists every (source, slug) pair in order', { methods: ['listAllPageRefs'] }, async (engine, backend) => {+ await createSource(engine, backend, 'work');+ await seed(engine, [['notes/b', NOTE], ['notes/a', NOTE]]);+ await seed(engine, [['notes/a', NOTE]], { sourceId: 'work' });+ const refs = (await engine.listAllPageRefs()).map((r) => ({ source_id: r.source_id, slug: r.slug, dated: r.updated_at instanceof Date }));+ expect(refs.map((r) => `${r.source_id}:${r.slug}`)).toEqual(['default:notes/a', 'default:notes/b', 'work:notes/a']);+ return refs;+ });++ parityTest('listAllSources and updateSourceConfig merge config', { methods: ['listAllSources', 'updateSourceConfig'] }, async (engine, backend) => {+ await createSource(engine, backend, 'work', { keep: 1 });+ const updated = await engine.updateSourceConfig('work', { last_full_cycle_at: '2026-11-01T00:00:00Z' });+ expect(updated).toBe(true);+ const unknown = await engine.updateSourceConfig('no-such-source', { a: 1 });+ expect(unknown).toBe(false);+ const work = (await engine.listAllSources()).find((s) => s.id === 'work');+ expect(work?.config).toMatchObject({ keep: 1, last_full_cycle_at: '2026-11-01T00:00:00Z' });+ const ids = sorted((await engine.listAllSources()).map((s) => s.id));+ const localOnly = (await engine.listAllSources({ localPathOnly: true })).map((s) => s.id);+ return { ids, config: work?.config, localOnly };+ });++ parityTest('same slug in two sources stays separate', { methods: ['putPage', 'getPage', 'deletePage', 'resolveSlugs'] }, async (engine, backend) => {+ await createSource(engine, backend, 'work');+ await engine.putPage('notes/a', NOTE);+ await engine.putPage('notes/a', { ...NOTE, title: 'Work note' }, { sourceId: 'work' });+ const home = await engine.getPage('notes/a', { sourceId: 'default' });+ const work = await engine.getPage('notes/a', { sourceId: 'work' });+ expect(home?.title).toBe('Weekly note');+ expect(work?.title).toBe('Work note');+ const scoped = await engine.resolveSlugs('notes/a', { sourceId: 'work' });+ await engine.deletePage('notes/a', { sourceId: 'work' });+ const afterDelete = { home: (await engine.getPage('notes/a', { sourceId: 'default' }))?.title ?? null, work: await engine.getPage('notes/a', { sourceId: 'work' }) };+ expect(afterDelete).toEqual({ home: 'Weekly note', work: null });+ return { scoped, afterDelete };+ });++ parityTest('listPrefixSampledPages and listCorpusSample sample live pages', { methods: ['listPrefixSampledPages', 'listCorpusSample'] }, async (engine) => {+ await seed(engine, [+ ['wiki/vc/one', NOTE], ['wiki/vc/two', NOTE], ['wiki/bio/one', NOTE], ['notes/a', NOTE],+ ]);+ await engine.softDeletePage('wiki/vc/two');+ const prefixed = await engine.listPrefixSampledPages({ prefixes: ['wiki/vc', 'wiki/bio'] });+ const prefixedView = sorted(prefixed.map((r) => `${r.prefix}:${r.slug}:${r.connection_count}`));+ expect(prefixedView).toEqual(['wiki/bio:wiki/bio/one:0', 'wiki/vc:wiki/vc/one:0']);+ const sample = await engine.listCorpusSample({ n: 10, excludeSlugs: ['notes/a'], seed: 7 });+ const sampleSlugs = sorted(sample.map((r) => r.slug));+ expect(sampleSlugs).toEqual(['wiki/bio/one', 'wiki/vc/one']);+ return { prefixedView, sampleSlugs };+ });+});diff --git a/test/engine-parity/raw-sql.test.ts b/test/engine-parity/raw-sql.test.tsnew file mode 100644index 0000000000..e7b33e8fee--- /dev/null+++ b/test/engine-parity/raw-sql.test.ts@@ -0,0 +1,94 @@+/**+ * BrainEngine parity — raw_sql family (runMigration, executeRaw,+ * executeRawDirect, keywordBoundedRead).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: the raw-SQL entry points answer the same rows on every SQL+ * arm (PGLite always; Postgres with DATABASE_URL), see the writes the+ * typed methods made, and keep their transaction and parameter contract.+ * Every case declares `requires: 'raw_sql'`, so a Rust arm must refuse+ * each call with `engine_capability_missing` reason `raw_sql` (D18) and+ * is never compared on rows (test/engine-parity/arm-capabilities.ts).+ * - Regression: an engine whose raw read misses a committed typed write,+ * binds parameters differently, returns numbers as strings, runs a+ * migration's statements partly, or leaks keywordBoundedRead's read+ * transaction; the minion queue, migrations and doctor read through these.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts calls+ * executeRaw only on Postgres, as a fixture, and never compares arms.+ * - Seam: none. Real engines. Raw SQL is the method under test here, the one+ * family where a case may call it.+ */+import { describe, expect } from 'bun:test';+import { parityArms } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const PAGE = (title: string, body: string) => ({ type: 'note' as const, title, compiled_truth: body, timeline: '' });++describe('engine parity: raw_sql', () => {+ parityTest(+ 'executeRaw binds parameters, returns typed rows and sees the typed writes',+ { methods: ['putPage', 'executeRaw'], requires: 'raw_sql' },+ async (engine) => {+ await engine.putPage('notes/raw-a', PAGE('Raw A', 'first'));+ await engine.putPage('notes/raw-b', PAGE('Raw B', 'second'));+ const scalar = await engine.executeRaw<{ n: number; s: string; nothing: null }>(+ 'SELECT $1::int + 1 AS n, $2::text AS s, NULL AS nothing', [41, 'text'],+ );+ expect(scalar).toEqual([{ n: 42, s: 'text', nothing: null }]);+ const pages = await engine.executeRaw<{ slug: string; title: string }>(+ `SELECT slug, title FROM pages WHERE slug LIKE $1 AND deleted_at IS NULL ORDER BY slug`, ['notes/raw-%'],+ );+ const none = await engine.executeRaw('SELECT slug FROM pages WHERE slug = $1', ['notes/nobody']);+ return { scalar, pages, none };+ },+ );++ parityTest(+ 'executeRawDirect answers like executeRaw and joins an open transaction',+ { methods: ['putPage', 'executeRawDirect', 'transaction'], requires: 'raw_sql' },+ async (engine) => {+ await engine.putPage('notes/direct', PAGE('Direct', 'body'));+ const direct = await engine.executeRawDirect<{ slug: string }>('SELECT slug FROM pages WHERE slug = $1', ['notes/direct']);+ // Inside a transaction the tx handle's direct read sees the tx's own uncommitted write.+ const inTx = await engine.transaction(async (tx) => {+ await tx.putPage('notes/direct-tx', PAGE('Direct tx', 'body'));+ return tx.executeRawDirect<{ slug: string }>('SELECT slug FROM pages WHERE slug = $1', ['notes/direct-tx']);+ });+ expect([direct, inTx]).toEqual([[{ slug: 'notes/direct' }], [{ slug: 'notes/direct-tx' }]]);+ return { direct, inTx };+ },+ );++ parityTest(+ 'runMigration runs every statement of a multi-statement script',+ { methods: ['runMigration', 'executeRaw'], requires: 'raw_sql' },+ async (engine) => {+ await engine.runMigration(9_000_001, `+ CREATE TABLE IF NOT EXISTS parity_raw_probe (id int PRIMARY KEY, label text NOT NULL);+ INSERT INTO parity_raw_probe (id, label) VALUES (1, 'one'), (2, 'two');+ `);+ const rows = await engine.executeRaw<{ id: number; label: string }>('SELECT id, label FROM parity_raw_probe ORDER BY id');+ await engine.runMigration(9_000_002, 'DROP TABLE parity_raw_probe;');+ const gone = await engine.executeRaw<{ present: boolean }>(`SELECT to_regclass('parity_raw_probe') IS NOT NULL AS present`);+ expect([rows, gone]).toEqual([[{ id: 1, label: 'one' }, { id: 2, label: 'two' }], [{ present: false }]]);+ return { rows, gone };+ },+ );++ parityTest(+ 'keywordBoundedRead runs the read and returns its value; a throw propagates and the engine stays usable',+ { methods: ['putPage', 'keywordBoundedRead', 'getPage'], requires: 'raw_sql' },+ async (engine) => {+ await engine.putPage('notes/bounded', PAGE('Bounded', 'body'));+ const read = await engine.keywordBoundedRead((db) =>+ db.executeRaw<{ slug: string }>('SELECT slug FROM pages WHERE slug = $1', ['notes/bounded']));+ const thrown = await engine.keywordBoundedRead(async () => { throw new Error('read refused'); })+ .then(() => 'no error', (e: unknown) => (e instanceof Error ? e.message : String(e)));+ const after = (await engine.getPage('notes/bounded'))?.title ?? null;+ expect([read, thrown, after]).toEqual([[{ slug: 'notes/bounded' }], 'read refused', 'Bounded']);+ return { read, thrown, after };+ },+ );+});diff --git a/test/engine-parity/search.test.ts b/test/engine-parity/search.test.tsnew file mode 100644index 0000000000..9989e668d6--- /dev/null+++ b/test/engine-parity/search.test.ts@@ -0,0 +1,340 @@+/**+ * BrainEngine parity — search family (keyword, keyword paging, title arm,+ * vector, embedding hydration, chunk-grain keyword).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every search method returns the same ranked slugs (and the same+ * rounded scores where the score is a pure function of the data) on every+ * engine arm (PGLite always; Postgres with DATABASE_URL; a Rust arm later+ * through test/engine-parity/harness.ts).+ * - Regression: an engine whose keyword/vector ranking, filters (type, slug+ * excludes, soft delete, quarantine), paging or AND-to-OR fallback drifts:+ * `query` and `search` return different pages depending on the backend.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * without Postgres and compares only top slugs; it never pins filters,+ * paging windows or hydration.+ * - Seam: none for the cases. Typed methods only (no executeRaw: D18); the+ * sealed-projection fixture goes through chunk-fixtures.ts (see its header).+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import type { SearchResult } from '../../src/core/types.ts';+import { basisEmbedding, createSource, parityArms, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';+import { chunk, installChunks, seedPage } from './chunk-fixtures.ts';++const { parityTest } = parityArms(testBackends());++/** Order-significant, engine-independent view of a result row. */+function hit(r: SearchResult) {+ return { slug: r.slug, chunk_index: r.chunk_index, type: r.type, title: r.title, source_id: r.source_id };+}++/** Scores that are a pure function of the seeded data, rounded so float noise cannot split arms. */+const round = (n: number) => Math.round(n * 1e4) / 1e4;++/** Unit vector pair mix: `cos` on axis `a`, the rest on axis `b`. */+function mix(a: number, cos: number, b: number): Float32Array {+ const e = new Float32Array(1536);+ e[a] = cos;+ e[b] = Math.sqrt(Math.max(0, 1 - cos * cos));+ return e;+}++async function seedCorpus(engine: BrainEngine): Promise<void> {+ await seedPage(engine, {+ slug: 'originals/talks/article-outline-fat-code',+ input: { type: 'writing', title: 'Fat Code Thin Harness — Part 3', compiled_truth: 'fat code thin harness pattern part 3 production case studies', timeline: '' },+ chunks: [chunk(0, 'fat code thin harness pattern part 3 production case studies', { embedding: basisEmbedding(7) })],+ });+ await seedPage(engine, {+ slug: 'concepts/fat-code-thin-harness',+ input: { type: 'concept', title: 'Fat Code Thin Harness', compiled_truth: 'reusable concept fat code thin harness architecture', timeline: '' },+ chunks: [chunk(0, 'reusable concept fat code thin harness architecture', { embedding: basisEmbedding(14) })],+ });+ const swamp = (day: string, axis: number) => ({+ slug: `openclaw/chat/2026-04-${day}`,+ input: {+ type: 'note' as const,+ title: `2026-04-${day} chat`,+ compiled_truth: 'fat code thin harness fat code thin harness discussion went on at length, fat code thin harness fat code thin harness.',+ timeline: '',+ },+ chunks: [chunk(0, 'fat code thin harness fat code thin harness discussion went on at length, fat code thin harness fat code thin harness.', { embedding: basisEmbedding(axis) })],+ });+ await seedPage(engine, swamp('15', 8));+ await seedPage(engine, swamp('16', 9));+ await seedPage(engine, {+ slug: 'people/example-founder',+ input: { type: 'person', title: 'Example Founder', compiled_truth: 'example founder unrelated content for distraction', timeline: '' },+ chunks: [chunk(0, 'example founder unrelated content for distraction', { embedding: basisEmbedding(50) })],+ });+ await seedPage(engine, {+ slug: 'notes/zephyr-handbook',+ input: { type: 'note', title: 'Zephyr Quartz Handbook', compiled_truth: 'plain words about nothing in particular', timeline: '' },+ chunks: [chunk(0, 'plain words about nothing in particular', { embedding: basisEmbedding(60) })],+ });+}++describe('engine parity: search', () => {+ parityTest(+ 'searchKeyword ranks the same pages for the same query',+ { methods: ['searchKeyword'] },+ async (engine) => {+ await seedCorpus(engine);+ const out: Record<string, unknown> = {};+ for (const q of ['fat code thin harness', 'fat code thin harness part 3', 'fat code production', 'distraction', 'nonexistentwordzzz']) {+ const rows = await engine.searchKeyword(q, { limit: 5 });+ out[q] = rows.map((r) => ({ ...hit(r), score: round(r.score) }));+ }+ const top = (out['fat code thin harness part 3'] as Array<{ slug: string }>)[0]!;+ expect(top.slug).toBe('originals/talks/article-outline-fat-code');+ expect(out['nonexistentwordzzz']).toEqual([]);+ expect((out['distraction'] as unknown[]).length).toBe(1);+ return out;+ },+ );++ parityTest(+ 'searchKeyword honors limit, offset, type, types and slug excludes',+ { methods: ['searchKeyword'] },+ async (engine) => {+ await seedCorpus(engine);+ const q = 'fat code thin harness';+ const slugs = async (opts: Parameters<BrainEngine['searchKeyword']>[1]) => (await engine.searchKeyword(q, opts)).map((r) => r.slug);+ const all = await slugs({ limit: 10 });+ expect(all).toContain('concepts/fat-code-thin-harness');+ expect(all.length).toBe(4);+ const limited = await slugs({ limit: 2 });+ const offset = await slugs({ limit: 2, offset: 2 });+ expect([...limited, ...offset]).toEqual(all);+ const excluded = await slugs({ limit: 10, exclude_slugs: ['concepts/fat-code-thin-harness'] });+ expect(excluded).not.toContain('concepts/fat-code-thin-harness');+ const prefixExcluded = await slugs({ limit: 10, exclude_slug_prefixes: ['openclaw/'] });+ expect(prefixExcluded.some((s) => s.startsWith('openclaw/'))).toBe(false);+ const typed = (await engine.searchKeyword(q, { limit: 10, type: 'concept' })).map((r) => r.type);+ expect(typed).toEqual(['concept']);+ const multiType = sorted((await engine.searchKeyword(q, { limit: 10, types: ['concept', 'writing'] })).map((r) => r.type));+ expect(multiType).toEqual(['concept', 'writing']);+ return { all, limited, offset, excluded, prefixExcluded, typed, multiType };+ },+ );++ parityTest(+ 'searchKeyword hides soft-deleted, quarantined and hard-excluded pages; include_slug_prefixes opts back in',+ { methods: ['searchKeyword', 'softDeletePage', 'restorePage'] },+ async (engine) => {+ const body = 'glimmerwort marker phrase';+ const page = (title: string, frontmatter?: Record<string, unknown>) => ({ type: 'note' as const, title, compiled_truth: body, timeline: '', ...(frontmatter ? { frontmatter } : {}) });+ await seedPage(engine, { slug: 'notes/visible', input: page('Visible'), chunks: [chunk(0, body)] });+ await seedPage(engine, { slug: 'notes/gone', input: page('Gone'), chunks: [chunk(0, body)] });+ await seedPage(engine, { slug: 'notes/quarantined', input: page('Quarantined', { quarantine: { reason: 'junk' } }), chunks: [chunk(0, body)] });+ await seedPage(engine, { slug: 'test/hard-excluded', input: page('Hard excluded'), chunks: [chunk(0, body)] });+ await engine.softDeletePage('notes/gone');++ const slugs = async (opts?: Parameters<BrainEngine['searchKeyword']>[1]) => sorted((await engine.searchKeyword('glimmerwort', opts)).map((r) => r.slug));+ const defaults = await slugs();+ const optedIn = await slugs({ include_slug_prefixes: ['test/'] });+ await engine.restorePage('notes/gone');+ // A restored page's text projection is unsealed until it is re-indexed: search skips it, then serves it again.+ const restoredUnsealed = await slugs();+ await installChunks(engine, 'notes/gone', [chunk(0, body)]);+ const restored = await slugs();+ expect(defaults).toEqual(['notes/visible']);+ expect(optedIn).toEqual(['notes/visible', 'test/hard-excluded']);+ expect(restoredUnsealed).toEqual(['notes/visible']);+ expect(restored).toEqual(['notes/gone', 'notes/visible']);+ return { defaults, optedIn, restoredUnsealed, restored };+ },+ );++ parityTest(+ 'searchKeyword scopes by sourceId and sourceIds',+ { methods: ['searchKeyword'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'work');+ const body = 'tangerine ledger entry';+ await seedPage(engine, { slug: 'notes/ledger-default', input: { type: 'note', title: 'Ledger default', compiled_truth: body, timeline: '' }, chunks: [chunk(0, body)] });+ await seedPage(engine, { slug: 'notes/ledger-work', input: { type: 'note', title: 'Ledger work', compiled_truth: body, timeline: '' }, chunks: [chunk(0, body)] }, { sourceId: 'work' });+ const view = async (opts?: Parameters<BrainEngine['searchKeyword']>[1]) => sorted((await engine.searchKeyword('tangerine', opts)).map((r) => `${r.source_id}:${r.slug}`));+ const unscoped = await view();+ const defaultOnly = await view({ sourceId: 'default' });+ const workOnly = await view({ sourceId: 'work' });+ const federated = await view({ sourceIds: ['default', 'work'] });+ const none = await view({ sourceId: 'no-such-source' });+ expect(unscoped).toEqual(['default:notes/ledger-default', 'work:notes/ledger-work']);+ expect(defaultOnly).toEqual(['default:notes/ledger-default']);+ expect(workOnly).toEqual(['work:notes/ledger-work']);+ expect(none).toEqual([]);+ return { unscoped, defaultOnly, workOnly, federated, none };+ },+ );++ parityTest(+ 'searchKeyword orFallback retries with OR terms and tags the rows keyword_relaxed',+ { methods: ['searchKeyword'] },+ async (engine) => {+ await seedCorpus(engine);+ // 'studies' lives only in the article page, 'distraction' only in the founder page: no chunk has both.+ const q = 'studies distraction';+ const strict = await engine.searchKeyword(q, { limit: 5 });+ const relaxed = await engine.searchKeyword(q, { limit: 5, orFallback: true });+ expect(strict).toEqual([]);+ expect(relaxed.length).toBe(2);+ expect(relaxed.every((r) => r.keyword_relaxed === true)).toBe(true);+ // A strict hit wins: no relaxed rows when the AND query matches.+ const strictWins = await engine.searchKeyword('fat code', { limit: 5, orFallback: true });+ expect(strictWins.length).toBeGreaterThan(0);+ expect(strictWins.some((r) => r.keyword_relaxed === true)).toBe(false);+ return { strict: strict.length, relaxed: sorted(relaxed.map((r) => r.slug)), strictWins: strictWins.map((r) => r.slug) };+ },+ );++ parityTest(+ 'countKeywordPages and searchKeywordPages page through strict keyword matches',+ { methods: ['countKeywordPages', 'searchKeywordPages'] },+ async (engine) => {+ await seedCorpus(engine);+ const q = 'fat code thin harness';+ const count = await engine.countKeywordPages(q);+ const miss = await engine.countKeywordPages('nonexistentwordzzz');+ const typedCount = await engine.countKeywordPages(q, { type: 'concept' });+ expect({ count, miss, typedCount }).toEqual({ count: 4, miss: 0, typedCount: 1 });++ const everything = await engine.searchKeywordPages(q, undefined, { limit: 10 });+ const slugsOf = (rows: SearchResult[]) => rows.map((r) => r.slug);+ expect(everything.length).toBe(4);+ // Keyset order is (score DESC, page_id ASC): offset windows partition it, `after` resumes from a row.+ const first = await engine.searchKeywordPages(q, undefined, { limit: 2 });+ const second = await engine.searchKeywordPages(q, undefined, { limit: 2, offset: 2 });+ expect([...slugsOf(first), ...slugsOf(second)]).toEqual(slugsOf(everything));+ const resumed = await engine.searchKeywordPages(q, undefined, { limit: 10, after: { score: first[1]!.score, page_id: first[1]!.page_id } });+ expect(slugsOf(resumed)).toEqual(slugsOf(everything).slice(2));+ const typed = await engine.searchKeywordPages(q, { type: 'writing' }, { limit: 10 });+ expect(slugsOf(typed)).toEqual(['originals/talks/article-outline-fat-code']);+ return { count, miss, typedCount, everything: slugsOf(everything), first: slugsOf(first), second: slugsOf(second), resumed: slugsOf(resumed), typed: slugsOf(typed) };+ },+ );++ parityTest(+ 'searchKeywordChunks returns chunk-grain rows where searchKeyword returns one row per page',+ { methods: ['searchKeyword', 'searchKeywordChunks'] },+ async (engine) => {+ await seedPage(engine, {+ slug: 'notes/many-chunks',+ input: { type: 'note', title: 'Many chunks', compiled_truth: 'x', timeline: '' },+ chunks: [chunk(0, 'quasar one in the first chunk'), chunk(1, 'nothing relevant here'), chunk(2, 'quasar two in the third chunk')],+ });+ await seedPage(engine, {+ slug: 'notes/one-chunk',+ input: { type: 'note', title: 'One chunk', compiled_truth: 'x', timeline: '' },+ chunks: [chunk(0, 'a lone quasar')],+ });+ const pageGrain = await engine.searchKeyword('quasar', { limit: 10 });+ const chunkGrain = await engine.searchKeywordChunks('quasar', { limit: 10 });+ const key = (rows: SearchResult[]) => sorted(rows.map((r) => `${r.slug}#${r.chunk_index}`));+ expect(key(chunkGrain)).toEqual(['notes/many-chunks#0', 'notes/many-chunks#2', 'notes/one-chunk#0']);+ expect(sorted(pageGrain.map((r) => r.slug))).toEqual(['notes/many-chunks', 'notes/one-chunk']);+ return { pageGrain: sorted(pageGrain.map((r) => r.slug)), chunkGrain: key(chunkGrain) };+ },+ );++ parityTest(+ 'searchTitles finds pages by title, falls back to relaxed OR, and honors filters',+ { methods: ['searchTitles'] },+ async (engine) => {+ await seedCorpus(engine);+ const view = (rows: SearchResult[]) => rows.map((r) => ({ slug: r.slug, relaxed: r.keyword_relaxed === true }));+ const exact = view(await engine.searchTitles('Zephyr Quartz Handbook', { limit: 5 }));+ expect(exact).toEqual([{ slug: 'notes/zephyr-handbook', relaxed: false }]);+ const strictTitle = sorted(view(await engine.searchTitles('fat code thin harness', { limit: 5 })), (r) => r.slug);+ expect(strictTitle.map((r) => r.slug)).toEqual(['concepts/fat-code-thin-harness', 'originals/talks/article-outline-fat-code']);+ // Title tokens that never share a title: strict recall is zero, the always-on OR fallback fires and tags rows.+ const relaxed = sorted(view(await engine.searchTitles('outline founder', { limit: 5 })), (r) => r.slug);+ expect(relaxed.length).toBeGreaterThan(0);+ expect(relaxed.every((r) => r.relaxed)).toBe(true);+ const typed = view(await engine.searchTitles('fat code thin harness', { limit: 5, type: 'concept' }));+ expect(typed.map((r) => r.slug)).toEqual(['concepts/fat-code-thin-harness']);+ const excluded = view(await engine.searchTitles('fat code thin harness', { limit: 5, exclude_slugs: ['concepts/fat-code-thin-harness'] }));+ const none = await engine.searchTitles('qqqqzzzz', { limit: 5 });+ expect(none).toEqual([]);+ return { exact, strictTitle, relaxed, typed, excluded, none };+ },+ );++ parityTest(+ 'searchVector ranks by cosine similarity and applies filters and paging',+ { methods: ['searchVector'] },+ async (engine) => {+ await seedCorpus(engine);+ const rank = async (query: Float32Array, opts?: Parameters<BrainEngine['searchVector']>[1]) =>+ (await engine.searchVector(query, { limit: 5, ...opts })).map((r) => ({ slug: r.slug, score: round(r.score) }));+ const article = await rank(basisEmbedding(7));+ expect(article[0]!.slug).toBe('originals/talks/article-outline-fat-code');+ // 0.8 on the article axis, 0.6 on the concept axis: article first, concept second, in that exact order.+ const blended = await rank(mix(7, 0.8, 14));+ expect(blended.slice(0, 2).map((r) => r.slug)).toEqual(['originals/talks/article-outline-fat-code', 'concepts/fat-code-thin-harness']);+ const limited = await rank(mix(7, 0.8, 14), { limit: 1 });+ const paged = await rank(mix(7, 0.8, 14), { limit: 1, offset: 1 });+ expect(paged.map((r) => r.slug)).toEqual([blended[1]!.slug]);+ const typed = await rank(mix(7, 0.8, 14), { type: 'concept' });+ expect(typed.map((r) => r.slug)).toEqual(['concepts/fat-code-thin-harness']);+ const excluded = await rank(basisEmbedding(7), { exclude_slugs: ['originals/talks/article-outline-fat-code'] });+ expect(excluded.some((r) => r.slug === 'originals/talks/article-outline-fat-code')).toBe(false);+ const detail = (await engine.searchVector(basisEmbedding(14), { limit: 3, detail: 'high' })).map((r) => r.slug);+ expect(detail[0]).toBe('concepts/fat-code-thin-harness');+ return { article, blended, limited, paged, typed, excluded, detail };+ },+ );++ parityTest(+ 'searchVector: a dense page cannot starve the page-grain result',+ { methods: ['searchVector'] },+ async (engine) => {+ // One page with 120 chunks nearest the query plus 8 sparse pages behind it: the page-grain collapse+ // must still return `limit` distinct pages.+ const denseDim = 900;+ await seedPage(engine, {+ slug: 'notes/parity-dense',+ input: { type: 'note', title: 'Parity Dense', compiled_truth: 'd.', timeline: '' },+ chunks: Array.from({ length: 120 }, (_, i) => chunk(i, `pd ${i}`, { embedding: mix(denseDim, 0.99 - i * 0.0005, 1000 + i), token_count: 2 })),+ });+ for (let p = 0; p < 8; p++) {+ await seedPage(engine, {+ slug: `notes/parity-sparse-${p}`,+ input: { type: 'note', title: `Parity Sparse ${p}`, compiled_truth: 's.', timeline: '' },+ chunks: [chunk(0, `ps ${p}`, { embedding: mix(denseDim, 0.6 - p * 0.001, 1200 + p), token_count: 2 })],+ });+ }+ const rows = await engine.searchVector(basisEmbedding(denseDim), { limit: 6, detail: 'high' });+ const slugs = rows.map((r) => r.slug);+ expect(new Set(slugs).size).toBe(6);+ expect(slugs[0]).toBe('notes/parity-dense');+ return { slugs };+ },+ );++ parityTest(+ 'getEmbeddingsByChunkIds returns stored vectors keyed by chunk id',+ { methods: ['putPage', 'getChunks', 'getEmbeddingsByChunkIds'] },+ async (engine) => {+ await engine.putPage('notes/hydrate', { type: 'note', title: 'Hydrate', compiled_truth: 'x', timeline: '' });+ await installChunks(engine, 'notes/hydrate', [+ chunk(0, 'hydrate zero', { embedding: basisEmbedding(21) }),+ chunk(1, 'hydrate one'),+ chunk(2, 'hydrate two', { embedding: basisEmbedding(23) }),+ ]);+ const chunks = await engine.getChunks('notes/hydrate');+ const indexOf = new Map(chunks.map((c) => [c.id, c.chunk_index]));+ const vectors = await engine.getEmbeddingsByChunkIds(chunks.map((c) => c.id));+ const hotAxis = (v: Float32Array) => v.findIndex((x) => x === 1);+ const byIndex = sorted([...vectors].map(([id, v]) => ({ chunk_index: indexOf.get(id)!, axis: hotAxis(v), dims: v.length })), (r) => String(r.chunk_index));+ expect(byIndex).toEqual([{ chunk_index: 0, axis: 21, dims: 1536 }, { chunk_index: 2, axis: 23, dims: 1536 }]);+ const named = await engine.getEmbeddingsByChunkIds([chunks[0]!.id], 'embedding');+ expect(named.size).toBe(1);+ const empty = await engine.getEmbeddingsByChunkIds([]);+ expect(empty.size).toBe(0);+ return { byIndex, namedSize: named.size, emptySize: empty.size };+ },+ );+});diff --git a/test/engine-parity/segmented-body.test.ts b/test/engine-parity/segmented-body.test.tsnew file mode 100644index 0000000000..077dd24b90--- /dev/null+++ b/test/engine-parity/segmented-body.test.ts@@ -0,0 +1,226 @@+/**+ * BrainEngine parity — segmented page bodies (Wave B storage: segment texts,+ * manifest generations, stagings, the generation flip, GC sweep and+ * per-segment derivation watermarks).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: building, replacing and sweeping a segmented page gives the+ * same manifest, texts, chunks, refusals and sweep counts on every engine+ * arm (PGLite always; Postgres with DATABASE_URL; Rust later through+ * test/engine-parity/harness.ts).+ * - Regression: an engine that publishes a different live generation,+ * accepts a stale flip, keeps or drops the wrong rows in a sweep, or+ * loses a derivation watermark: large-page reads and incremental+ * pipelines then disagree between engines.+ * - Why existing coverage misses it: test/large-pages/segment-gc.test.ts and+ * test/e2e/segment-gc-parity.test.ts run the same cases per engine but+ * never compare the two engines' observables; the e2e arm skips without+ * Postgres.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ * Occurrence and page ids come from sequences that a reset does not+ * rewind on Postgres, so observables map them to ordinals.+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import type { ManifestRow, SegmentTextInput } from '../../src/core/page-body/types.ts';+import { testBackends } from '../helpers/test-backends.ts';+import { chunk, flipInput, hexOf, manifestRow, pageMeta, segmentText, sha256, stagingInput } from '../helpers/page-body-fixtures.ts';+import { parityArms, sorted } from './harness.ts';++const { parityTest } = parityArms(testBackends());++const ONE = segmentText('# Intro\nfirst segment of the page\n');+const TWO = segmentText('## Middle\nsecond segment, kept across the replace\n');+const THREE = segmentText('## End\nthird segment, retired by the replace\n');+const FOUR = segmentText('## New end\nfourth segment, added by the replace\n');++/** Manifest rows with ids mapped to ordinals of `occurrences` and bytes to hex. */+function manifestView(rows: readonly ManifestRow[], occurrences: readonly number[]) {+ return rows.map((r) => ({+ occurrence: occurrences.indexOf(Number(r.occurrenceId)),+ genFrom: Number(r.genFrom),+ genTo: r.genTo === null ? null : Number(r.genTo),+ seq: Number(r.seq),+ region: r.region,+ sha256: hexOf(r.sha256),+ byteStart: Number(r.byteStart),+ byteLen: Number(r.byteLen),+ cutKind: r.cutKind,+ entryState: r.entryState,+ outline: r.outline,+ dateMin: r.dateMin,+ dateMax: r.dateMax,+ staged: r.stagingId !== null,+ }));+}++/** Stage `texts` (in order) as a generation of `pageId` inside one transaction; returns the staging id. */+async function stage(engine: BrainEngine, input: { pageId: number; slug: string; genFrom: number; texts: readonly SegmentTextInput[];+ occurrences: readonly number[]; chunks?: boolean }) {+ const staging = stagingInput({ slug: input.slug, pageId: input.pageId, mode: input.genFrom === 1 ? 'create' : 'replace' });+ const inserted = await engine.transaction(async (tx) => {+ await tx.openBodyStaging(staging);+ const { inserted: n } = await tx.stageSegmentTexts('default', input.texts, { stagingId: staging.id });+ let byteStart = 0;+ await tx.stageManifestRows(input.texts.map((text, seq) => {+ const row = manifestRow({ pageId: input.pageId, occurrenceId: input.occurrences[seq]!, genFrom: input.genFrom, seq, text, byteStart, stagingId: staging.id });+ byteStart += text.body.byteLength;+ return row;+ }));+ if (input.chunks) {+ const indexes = await tx.stageSegmentChunks(input.pageId, input.genFrom,+ input.texts.map((text, i) => chunk(input.occurrences[i]!, 0, new TextDecoder().decode(text.body))));+ expect(indexes.length).toBe(input.texts.length);+ }+ return n;+ });+ return { stagingId: staging.id, inserted };+}++/** Publish ONE, TWO, THREE as generation 1 of `notes/big`. */+async function publish(engine: BrainEngine, opts: { chunks?: boolean } = {}) {+ const { id: pageId } = await engine.createSegmentedPageShell('notes/big', pageMeta('Big page'), { sourceId: 'default' });+ const occurrences = await engine.allocateBodyOccurrenceIds(3);+ const texts = [ONE, TWO, THREE];+ const { stagingId, inserted } = await stage(engine, { pageId, slug: 'notes/big', genFrom: 1, texts, occurrences, chunks: opts.chunks });+ const flip = await engine.transaction(async (tx) => {+ const result = await tx.flipBodyGeneration(flipInput(pageId, 0, stagingId, texts));+ await tx.setBodyStagingState(stagingId, 'committed');+ return result;+ });+ return { pageId, occurrences, inserted, flip };+}++describe('engine parity: segmented page bodies', () => {+ parityTest(+ 'a segmented page publishes generation 1 from staged texts and manifest rows',+ { methods: ['createSegmentedPageShell', 'allocateBodyOccurrenceIds', 'openBodyStaging', 'stageSegmentTexts', 'stageManifestRows',+ 'flipBodyGeneration', 'setBodyStagingState', 'readManifest', 'readSegmentTexts', 'transaction'] },+ async (engine) => {+ const shellOnly = await engine.createSegmentedPageShell('notes/shell', pageMeta('Shell'), { sourceId: 'default' });+ const shellManifest = await engine.readManifest(shellOnly.id);+ const { pageId, occurrences, inserted, flip } = await publish(engine);+ const ids = new Set(occurrences);+ expect(ids.size).toBe(3);+ const live = manifestView(await engine.readManifest(pageId), occurrences);+ expect(live.map((r) => r.occurrence)).toEqual([0, 1, 2]);+ expect(live.every((r) => r.genTo === null && !r.staged)).toBe(true);+ const tail = manifestView(await engine.readManifest(pageId, { lastN: 1 }), occurrences);+ const gen1 = manifestView(await engine.readManifest(pageId, { generation: 1 }), occurrences);+ const timeline = await engine.readManifest(pageId, { region: 'timeline' });+ const texts = await engine.readSegmentTexts('default', [ONE.sha256, THREE.sha256, sha256('absent')]);+ expect(sorted([...texts.keys()])).toEqual(sorted([hexOf(ONE.sha256), hexOf(THREE.sha256)]));+ expect(new TextDecoder().decode(texts.get(hexOf(ONE.sha256))!)).toBe('# Intro\nfirst segment of the page\n');+ const again = await engine.stageSegmentTexts('default', [ONE, FOUR]);+ expect(again.inserted).toBe(1);+ const otherSource = await engine.readSegmentTexts('no-such-source', [ONE.sha256]);+ const page = await engine.getPage('notes/big');+ return {+ shellManifest: shellManifest.length,+ inserted,+ flip,+ live,+ tail,+ gen1Matches: JSON.stringify(gen1) === JSON.stringify(live),+ timeline: timeline.length,+ texts: sorted([...texts].map(([k, v]) => `${k}:${v.byteLength}`)),+ again,+ otherSource: otherSource.size,+ page: page ? { slug: page.slug, title: page.title, type: page.type } : null,+ };+ },+ );++ parityTest(+ 'a replace flips to generation 2, closes retired rows and refuses a stale generation',+ { methods: ['flipBodyGeneration', 'readManifest', 'stageSegmentChunks', 'getChunks'] },+ async (engine) => {+ const { pageId, occurrences } = await publish(engine, { chunks: true });+ const chunksBefore = (await engine.getChunks('notes/big')).map((c) => c.chunk_text);+ const [newOcc] = await engine.allocateBodyOccurrenceIds(1);+ const all = [...occurrences, newOcc!];+ // Keep ONE and TWO (same occurrences, same offsets), retire THREE, add FOUR.+ const staging = stagingInput({ slug: 'notes/big', pageId, mode: 'replace', baseGeneration: 1 });+ await engine.transaction(async (tx) => {+ await tx.openBodyStaging(staging);+ await tx.stageSegmentTexts('default', [FOUR]);+ await tx.stageManifestRows([manifestRow({ pageId, occurrenceId: newOcc!, genFrom: 2, seq: 2, text: FOUR,+ byteStart: ONE.body.byteLength + TWO.body.byteLength, stagingId: staging.id })]);+ await tx.stageSegmentChunks(pageId, 2, [chunk(newOcc!, 0, new TextDecoder().decode(FOUR.body))]);+ });+ let stale: string | null = null;+ try {+ await engine.transaction((tx) => tx.flipBodyGeneration(flipInput(pageId, 0, staging.id, [ONE, TWO, FOUR])));+ } catch (error) {+ stale = (error as { code?: string }).code ?? (error instanceof Error ? error.constructor.name : 'threw');+ }+ expect(stale).not.toBeNull();+ const flip = await engine.transaction(async (tx) => {+ const result = await tx.flipBodyGeneration(flipInput(pageId, 1, staging.id, [ONE, TWO, FOUR],+ { closeOccurrences: [occurrences[2]!], retireChunkOccurrences: [occurrences[2]!] }));+ await tx.setBodyStagingState(staging.id, 'committed');+ return result;+ });+ const live = manifestView(await engine.readManifest(pageId), all);+ expect(live.map((r) => r.occurrence)).toEqual([0, 1, 3]);+ const gen1 = manifestView(await engine.readManifest(pageId, { generation: 1 }), all);+ const chunksAfter = sorted((await engine.getChunks('notes/big')).map((c) => c.chunk_text));+ return { chunksBefore: sorted(chunksBefore), stale, flip, live, gen1, chunksAfter };+ },+ );++ parityTest(+ 'sweepSegments deletes closed rows and unreferenced texts and expires stale stagings',+ { methods: ['sweepSegments', 'readSegmentTexts', 'openBodyStaging', 'readManifest'] },+ async (engine) => {+ const { pageId, occurrences } = await publish(engine);+ const orphan = segmentText('orphan text no manifest row references\n');+ await engine.stageSegmentTexts('default', [orphan]);+ const inGrace = await engine.sweepSegments({ sourceId: 'default' });+ const graceKept = (await engine.readSegmentTexts('default', [orphan.sha256])).size;+ const swept = await engine.sweepSegments({ sourceId: 'default', graceMs: 0 });+ const orphanGone = (await engine.readSegmentTexts('default', [orphan.sha256])).size;+ const liveKept = (await engine.readSegmentTexts('default', [ONE.sha256, TWO.sha256, THREE.sha256])).size;+ // An open staging past its deadlines expires; its staged rows go with it.+ const [occ] = await engine.allocateBodyOccurrenceIds(1);+ const staging = stagingInput({ slug: 'notes/big', pageId, mode: 'replace', baseGeneration: 1 });+ await engine.openBodyStaging(staging);+ await engine.stageSegmentTexts('default', [FOUR], { stagingId: staging.id });+ await engine.stageManifestRows([manifestRow({ pageId, occurrenceId: occ!, genFrom: 2, seq: 3, text: FOUR, byteStart: 999, stagingId: staging.id })]);+ const stagedBefore = (await engine.readManifest(pageId, { stagingId: staging.id })).length;+ const notExpired = await engine.sweepSegments({ sourceId: 'default', expireStagings: true });+ const expired = await engine.sweepSegments({ sourceId: 'default', expireStagings: true, now: new Date(Date.now() + 30 * 86_400_000) });+ const stagedAfter = (await engine.readManifest(pageId, { stagingId: staging.id })).length;+ const live = manifestView(await engine.readManifest(pageId), occurrences).map((r) => r.occurrence);+ return { inGrace, graceKept, swept, orphanGone, liveKept, stagedBefore, notExpired, expired, stagedAfter, live };+ },+ );++ parityTest(+ 'segment derivations upsert by (page, kind, occurrence), read in order and retire dead occurrences',+ { methods: ['upsertSegmentDerivations', 'readSegmentDerivations', 'retireSegmentDerivations'] },+ async (engine) => {+ const { pageId, occurrences } = await publish(engine);+ const row = (kind: 'links' | 'timeline', i: number, state: 'done' | 'failed', output: unknown) => ({+ pageId, kind, occurrenceId: occurrences[i]!, version: 1, segmentSha256: sha256(`seg:${i}`), contextHash: sha256(`ctx:${kind}`),+ state, output, receipt: { n: i },+ });+ await engine.upsertSegmentDerivations([row('links', 0, 'done', ['a']), row('links', 1, 'failed', []), row('links', 2, 'done', ['c']),+ row('timeline', 0, 'done', { dates: 1 })]);+ await engine.upsertSegmentDerivations([{ ...row('links', 1, 'done', ['b']), version: 2 }]);+ const view = (rows: Awaited<ReturnType<BrainEngine['readSegmentDerivations']>>) => rows.map((r) => ({+ kind: r.kind, occurrence: occurrences.indexOf(Number(r.occurrenceId)), version: Number(r.version), state: r.state,+ output: r.output, receipt: r.receipt, sha: hexOf(r.segmentSha256), ctx: hexOf(r.contextHash), stamped: typeof r.createdAt === 'string' && typeof r.updatedAt === 'string',+ }));+ const all = view(await engine.readSegmentDerivations(pageId));+ const links = view(await engine.readSegmentDerivations(pageId, { kind: 'links', occurrenceIds: [occurrences[1]!] }));+ expect(links).toHaveLength(1);+ expect(links[0]).toMatchObject({ version: 2, state: 'done', output: ['b'] });+ const retiredLinks = await engine.retireSegmentDerivations(pageId, [occurrences[0]!], { kind: 'links' });+ expect(retiredLinks).toBe(2);+ const retiredAll = await engine.retireSegmentDerivations(pageId, []);+ const left = view(await engine.readSegmentDerivations(pageId));+ return { all, links, retiredLinks, retiredAll, left };+ },+ );+});diff --git a/test/engine-parity/sync-aliases.test.ts b/test/engine-parity/sync-aliases.test.tsnew file mode 100644index 0000000000..cf223e513f--- /dev/null+++ b/test/engine-parity/sync-aliases.test.ts@@ -0,0 +1,246 @@+/**+ * BrainEngine parity — sync_aliases family (rename, slug/page aliases,+ * narrow page updates, fact migration).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: sync's rename path, the slug-alias and page-alias layers, the+ * narrow body/CR-state refreshes and the phantom-fact migration return the+ * same observable result on every engine arm (PGLite always; Postgres+ * with DATABASE_URL; a Rust arm later through test/engine-parity/harness.ts).+ * - Regression: an engine that renames the wrong source's row, loses chunks+ * on rename, forgets the old-slug alias, mis-scopes alias resolution+ * across sources, or moves expired facts — the paths `gbrain sync`,+ * wikilink resolution, search alias hops and the phantom redirect rely on.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and has no sync/alias cases;+ * test/phantom-redirect-engine-parity.test.ts seeds through executeRaw and+ * compares against fixed expectations, not between engines.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ * rewriteLinks is deliberately not called here.+ */+import { describe, expect } from 'bun:test';+import { createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++describe('engine parity: sync + aliases', () => {+ parityTest(+ 'updateSlug renames a page in place, keeps its chunks, and returns 0 when the old slug is absent',+ { methods: ['putPage', 'upsertChunks', 'getChunks', 'getPage', 'updateSlug'] },+ async (engine) => {+ await engine.putPage('notes/old-name', { type: 'note', title: 'Movable', compiled_truth: 'Content.', timeline: '' });+ await engine.upsertChunks('notes/old-name', [+ { chunk_index: 0, chunk_text: 'Content.', chunk_source: 'compiled_truth' },+ { chunk_index: 1, chunk_text: 'More.', chunk_source: 'timeline' },+ ]);+ const moved = await engine.updateSlug('notes/old-name', 'notes/new-name');+ const missing = await engine.updateSlug('notes/never-existed', 'notes/whatever');+ expect(moved).toBe(1);+ expect(missing).toBe(0);+ const oldPage = await engine.getPage('notes/old-name');+ const newPage = await engine.getPage('notes/new-name');+ const chunks = await engine.getChunks('notes/new-name', { includeUnsealed: true });+ expect(chunks).toHaveLength(2);+ expect(oldPage).toBeNull();+ expect(newPage?.title).toBe('Movable');+ return {+ moved, missing, oldPage,+ newPage: pick(newPage!, ['slug', 'type', 'title', 'compiled_truth'] as const),+ chunks: chunks.map((c) => `${c.chunk_index}:${c.chunk_text}`),+ oldChunks: await engine.getChunks('notes/old-name', { includeUnsealed: true }),+ };+ },+ );++ parityTest(+ 'updateSlug is source-scoped and rejects a path-traversal new slug',+ { methods: ['putPage', 'getPage', 'updateSlug'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'rename-other');+ await engine.putPage('notes/twin', { type: 'note', title: 'D', compiled_truth: 'D.', timeline: '' });+ await engine.putPage('notes/twin', { type: 'note', title: 'O', compiled_truth: 'O.', timeline: '' }, { sourceId: 'rename-other' });+ const moved = await engine.updateSlug('notes/twin', 'notes/twin-renamed', { sourceId: 'rename-other' });+ const defaultStill = await engine.getPage('notes/twin', { sourceId: 'default' });+ const otherNew = await engine.getPage('notes/twin-renamed', { sourceId: 'rename-other' });+ const otherOld = await engine.getPage('notes/twin', { sourceId: 'rename-other' });+ const wrongSource = await engine.updateSlug('notes/twin-renamed', 'notes/x', { sourceId: 'default' });+ let invalid = false;+ try {+ await engine.updateSlug('notes/twin', 'notes/../escape');+ } catch {+ invalid = true;+ }+ expect(moved).toBe(1);+ expect(defaultStill?.title).toBe('D');+ expect(otherNew?.title).toBe('O');+ expect(otherOld).toBeNull();+ expect(wrongSource).toBe(0);+ expect(invalid).toBe(true);+ return { moved, wrongSource, invalid, defaultStill: defaultStill?.title, otherNew: otherNew?.title, otherOld };+ },+ );++ parityTest(+ 'a rename records an alias: resolveSlugWithAlias maps the old slug to the new one, per source',+ { methods: ['putPage', 'updateSlug', 'resolveSlugWithAlias', 'resolveSlugWithAliasDetailed'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'alias-other');+ await engine.putPage('concepts/before', { type: 'concept', title: 'Idea', compiled_truth: 'Idea.', timeline: '' });+ await engine.updateSlug('concepts/before', 'concepts/after');+ const viaAlias = await engine.resolveSlugWithAlias('concepts/before', 'default');+ const detailed = await engine.resolveSlugWithAliasDetailed('concepts/before', 'default');+ const notAliased = await engine.resolveSlugWithAlias('concepts/after', 'default');+ const unknown = await engine.resolveSlugWithAlias('concepts/unknown', 'default');+ const otherSource = await engine.resolveSlugWithAlias('concepts/before', 'alias-other');+ const federated = await engine.resolveSlugWithAlias('concepts/before', ['alias-other', 'default']);+ const federatedDetailed = await engine.resolveSlugWithAliasDetailed('concepts/before', ['alias-other', 'default']);+ const noMatch = await engine.resolveSlugWithAliasDetailed('concepts/unknown', 'default');+ const emptySources = await engine.resolveSlugWithAliasDetailed('concepts/before', []);+ expect(viaAlias).toBe('concepts/after');+ expect(detailed).toEqual({ canonical_slug: 'concepts/after', source_id: 'default' });+ expect(otherSource).toBe('concepts/before');+ return { viaAlias, detailed, notAliased, unknown, otherSource, federated, federatedDetailed, noMatch, emptySources };+ },+ );++ parityTest(+ 'setPageAliases replaces a page alias set; resolveAliases maps normalized aliases to slugs with source scope',+ { methods: ['putPage', 'setPageAliases', 'resolveAliases'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'palias-other');+ await engine.putPage('people/pa-alice', { type: 'person', title: 'Alice', compiled_truth: 'A.', timeline: '' });+ await engine.putPage('people/pa-alice-two', { type: 'person', title: 'Alice Two', compiled_truth: 'A2.', timeline: '' });+ await engine.putPage('people/pa-other', { type: 'person', title: 'Other', compiled_truth: 'O.', timeline: '' }, { sourceId: 'palias-other' });+ await engine.setPageAliases('people/pa-alice', 'default', ['ally', 'alice example', 'ally', '']);+ await engine.setPageAliases('people/pa-alice-two', 'default', ['ally']);+ await engine.setPageAliases('people/pa-other', 'palias-other', ['ally', 'only other']);+ const flat = (m: Map<string, Array<{ slug: string; source_id: string }>>) =>+ Object.fromEntries([...m.entries()].sort(([a], [b]) => (a < b ? -1 : 1)).map(([k, v]) => [k, sorted(v.map((r) => `${r.source_id}:${r.slug}`))]));+ const query = ['ally', 'alice example', 'only other', 'nobody'];+ const inDefault = flat(await engine.resolveAliases(query, { sourceId: 'default' }));+ const inOther = flat(await engine.resolveAliases(query, { sourceId: 'palias-other' }));+ const inBoth = flat(await engine.resolveAliases(query, { sourceIds: ['default', 'palias-other'] }));+ const empty = await engine.resolveAliases([], { sourceId: 'default' });+ // Replacing the set drops aliases that are no longer declared.+ await engine.setPageAliases('people/pa-alice', 'default', ['alice example']);+ const afterReplace = flat(await engine.resolveAliases(query, { sourceId: 'default' }));+ await engine.setPageAliases('people/pa-alice', 'default', []);+ const afterClear = flat(await engine.resolveAliases(query, { sourceId: 'default' }));+ expect(inDefault.ally).toEqual(['default:people/pa-alice', 'default:people/pa-alice-two']);+ expect(inOther.ally).toEqual(['palias-other:people/pa-other']);+ expect(empty.size).toBe(0);+ expect(afterReplace['alice example']).toEqual(['default:people/pa-alice']);+ expect(afterClear['alice example']).toBeUndefined();+ return { inDefault, inOther, inBoth, emptySize: empty.size, afterReplace, afterClear };+ },+ );++ parityTest(+ 'refreshPageBody rewrites body, timeline and content hash; skips soft-deleted pages and other sources',+ { methods: ['putPage', 'refreshPageBody', 'getPage', 'softDeletePage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'refresh-other');+ await engine.putPage('people/refresh-a', { type: 'person', title: 'A', compiled_truth: 'Original.', timeline: '' });+ await engine.putPage('people/refresh-a', { type: 'person', title: 'A', compiled_truth: 'Other original.', timeline: '' }, { sourceId: 'refresh-other' });+ await engine.putPage('people/refresh-gone', { type: 'person', title: 'Gone', compiled_truth: 'Gone body.', timeline: '' });+ await engine.refreshPageBody('people/refresh-a', 'default', 'New body.', '- 2026-02-02: updated', 'hash-new');+ await engine.softDeletePage('people/refresh-gone');+ await engine.refreshPageBody('people/refresh-gone', 'default', 'Should not land.', '', 'hash-gone');+ await engine.refreshPageBody('people/refresh-missing', 'default', 'Nothing here.', '', 'hash-none');+ const refreshed = await engine.getPage('people/refresh-a', { sourceId: 'default' });+ const other = await engine.getPage('people/refresh-a', { sourceId: 'refresh-other' });+ const gone = await engine.getPage('people/refresh-gone', { includeDeleted: true });+ expect(refreshed?.compiled_truth).toBe('New body.');+ expect(refreshed?.content_hash).toBe('hash-new');+ expect(other?.compiled_truth).toBe('Other original.');+ expect(gone?.compiled_truth).toBe('Gone body.');+ expect(gone?.content_hash).not.toBe('hash-gone');+ return {+ refreshed: pick(refreshed!, ['compiled_truth', 'timeline', 'content_hash', 'title'] as const),+ other: other?.compiled_truth,+ goneBody: gone?.compiled_truth,+ missing: await engine.getPage('people/refresh-missing'),+ };+ },+ );++ parityTest(+ 'updatePageContextualRetrievalState stamps the CR mode without touching the body',+ { methods: ['putPage', 'updatePageContextualRetrievalState', 'getPage', 'softDeletePage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'cr-other');+ await engine.putPage('notes/cr-a', { type: 'note', title: 'CR', compiled_truth: 'CR body.', timeline: '' });+ await engine.putPage('notes/cr-a', { type: 'note', title: 'CR', compiled_truth: 'CR other.', timeline: '' }, { sourceId: 'cr-other' });+ await engine.putPage('notes/cr-gone', { type: 'note', title: 'Gone', compiled_truth: 'Gone.', timeline: '' });+ const before = await engine.getPage('notes/cr-a');+ await engine.updatePageContextualRetrievalState('notes/cr-a', 'default', 'title', 'gen-1');+ const titled = await engine.getPage('notes/cr-a');+ await engine.updatePageContextualRetrievalState('notes/cr-a', 'default', 'none', null);+ const none = await engine.getPage('notes/cr-a');+ const other = await engine.getPage('notes/cr-a', { sourceId: 'cr-other' });+ await engine.softDeletePage('notes/cr-gone');+ await engine.updatePageContextualRetrievalState('notes/cr-gone', 'default', 'title', 'gen-x');+ const gone = await engine.getPage('notes/cr-gone', { includeDeleted: true });+ // corpus_generation is written by this method but no typed read projects it (getPage omits the column;+ // only SQL readers see it), so only the mode and the untouched body are observable here.+ const keys = ['compiled_truth', 'contextual_retrieval_mode'] as const;+ expect(titled?.contextual_retrieval_mode).toBe('title');+ expect(titled?.compiled_truth).toBe('CR body.');+ expect(none?.contextual_retrieval_mode).toBe('none');+ return {+ before: pick(before!, keys),+ titled: pick(titled!, keys),+ none: pick(none!, keys),+ other: pick(other!, keys),+ gone: pick(gone!, keys),+ };+ },+ );++ parityTest(+ 'migrateFactsToCanonical moves active phantom facts, leaves expired ones, and is idempotent',+ { methods: ['putPage', 'insertFacts', 'migrateFactsToCanonical', 'listFactsByEntity'] },+ async (engine) => {+ await engine.putPage('alice', { type: 'person', title: 'alice', compiled_truth: '# alice', timeline: '' });+ await engine.putPage('people/alice-example', { type: 'person', title: 'Alice Example', compiled_truth: '# Alice Example', timeline: '' });+ const base = { kind: 'fact' as const, visibility: 'private' as const, source: 'parity', notability: 'high' as const, confidence: 0.9 };+ await engine.insertFacts([+ { ...base, fact: 'Canonical fact', entity_slug: 'people/alice-example', row_num: 1, source_markdown_slug: 'people/alice-example' },+ { ...base, fact: 'Phantom one', entity_slug: 'alice', row_num: 1, source_markdown_slug: 'alice', context: 'ctx' },+ { ...base, fact: 'Phantom two', entity_slug: 'alice', row_num: 2, source_markdown_slug: 'alice' },+ { ...base, fact: 'Phantom expired', entity_slug: 'alice', row_num: 3, source_markdown_slug: 'alice', expired_at: new Date('2026-01-01T00:00:00Z') },+ ], { source_id: 'default' });+ const view = (rows: Awaited<ReturnType<typeof engine.listFactsByEntity>>) =>+ sorted(rows.map((r) => `${r.fact}|${r.entity_slug}|${r.visibility}|${r.notability}|${r.confidence}|${r.context ?? ''}`));+ const phantomBefore = view(await engine.listFactsByEntity('default', 'alice'));+ const first = await engine.migrateFactsToCanonical('alice', 'people/alice-example', 'default');+ const second = await engine.migrateFactsToCanonical('alice', 'people/alice-example', 'default');+ const unrelated = await engine.migrateFactsToCanonical('nobody', 'people/alice-example', 'default');+ const phantomAfter = view(await engine.listFactsByEntity('default', 'alice'));+ const phantomAll = view(await engine.listFactsByEntity('default', 'alice', { activeOnly: false }));+ const canonical = view(await engine.listFactsByEntity('default', 'people/alice-example'));+ expect(first).toEqual({ migrated: 2 });+ expect(second).toEqual({ migrated: 0 });+ expect(phantomAfter).toEqual([]);+ return { phantomBefore, first, second, unrelated, phantomAfter, phantomAll, canonical };+ },+ );+ parityTest(+ 'rewriteLinks after updateSlug is a no-op: links follow the page id, not the slug',+ { methods: ['updateSlug', 'rewriteLinks', 'addLink', 'getLinks', 'getBacklinks'] },+ async (engine) => {+ await engine.putPage('people/alice-example', { type: 'person', title: 'Alice Example', compiled_truth: 'Works at acme-example.' });+ await engine.putPage('companies/acme-example', { type: 'company', title: 'Acme Example', compiled_truth: 'A company.' });+ await engine.addLink('people/alice-example', 'companies/acme-example', 'employee', 'works_at');+ await engine.updateSlug('companies/acme-example', 'companies/acme-renamed');+ const out = await engine.rewriteLinks('companies/acme-example', 'companies/acme-renamed');+ expect(out).toBeUndefined();+ const links = (await engine.getLinks('people/alice-example')).map((l) => `${l.to_slug}:${l.link_type}`);+ expect(links).toEqual(['companies/acme-renamed:works_at']);+ const backlinks = (await engine.getBacklinks('companies/acme-renamed')).map((l) => l.from_slug);+ const unknown = await engine.rewriteLinks('notes/never-existed', 'notes/whatever');+ return { out: out ?? null, links, backlinks, unknown: unknown ?? null };+ },+ );+});diff --git a/test/engine-parity/takes.test.ts b/test/engine-parity/takes.test.tsnew file mode 100644index 0000000000..74a7cc877d--- /dev/null+++ b/test/engine-parity/takes.test.ts@@ -0,0 +1,662 @@+/**+ * BrainEngine parity — takes family (+ contradiction probe cache and dream+ * verdict cache, which hang off the same tables' lifecycle).+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every takes method (batch write, list/search, embeddings and+ * their staleness, update/supersede/resolve, scorecard and calibration,+ * synthesis evidence), the contradiction-probe run/cache methods and the+ * dream-verdict cache return the same observable result on every engine+ * arm (PGLite always; Postgres with DATABASE_URL; a Rust arm later through+ * test/engine-parity/harness.ts).+ * - Regression: an engine that drifts on take ordering and filters, on which+ * holder rows an allow-list hides, on resolve/supersede immutability, on+ * scorecard/Brier/calibration math, or on cache hit/miss semantics: the+ * numbers `gbrain takes` and the dream cycle report.+ * - Why existing coverage misses it: the takes and cache tests each run one+ * engine; test/e2e/takes-postgres.test.ts needs Postgres and never diffs it+ * against PGLite on one scenario.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine, Take, TakeBatchInput, TakeHit } from '../../src/core/engine.ts';+import { basisEmbedding, createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const TAKE_KEYS = [+ 'page_slug', 'row_num', 'claim', 'kind', 'holder', 'weight', 'since_date', 'until_date', 'source',+ 'superseded_by', 'active', 'resolved_quality', 'resolved_outcome', 'resolved_value', 'resolved_unit',+ 'resolved_source', 'resolved_by',+] as const;++const tv = (t: Take) => ({ ...pick(t, TAKE_KEYS), resolved: t.resolved_at !== null });+const claims = (rows: Array<{ claim: string }>) => rows.map((r) => r.claim);+const round = (n: number | null | undefined, places = 4) => (n == null ? n : Number(n.toFixed(places)));++/** Run `fn` and return the error's GBrainError `problem` code, or null when it did not throw. */+async function errorCode(fn: () => Promise<unknown>): Promise<string | null> {+ try {+ await fn();+ return null;+ } catch (e) {+ return (e as { problem?: string }).problem ?? `non-gbrain:${(e as Error).constructor.name}`;+ }+}++async function page(engine: BrainEngine, slug: string, opts?: { sourceId?: string }) {+ const type = slug.startsWith('people/') ? 'person' : slug.startsWith('companies/') ? 'company' : 'note';+ return engine.putPage(slug, { type, title: slug, compiled_truth: `Page ${slug}.`, timeline: '' }, opts);+}++const take = (page_id: number, row_num: number, claim: string, extra: Partial<TakeBatchInput> = {}): TakeBatchInput => ({+ page_id, row_num, claim, kind: 'take', holder: 'garry', ...extra,+});++/** Map take ids to their claim text: ids are sequence-dependent and never compared across arms. */+// listTakes defaults to active rows only (`active ?? true`), so list both halves+async function allTakes(engine: BrainEngine, pageId: number) {+ return [...(await engine.listTakes({ page_id: pageId, active: true })), ...(await engine.listTakes({ page_id: pageId, active: false }))];+}++async function takeIds(engine: BrainEngine, pageId: number): Promise<Map<string, number>> {+ const rows = await allTakes(engine, pageId);+ return new Map(rows.map((r) => [r.claim, r.id]));+}++describe('engine parity: takes', () => {+ parityTest(+ 'addTakesBatch inserts rows, is idempotent per (page, row_num), updates changed rows in place, clamps weight',+ { methods: ['putPage', 'addTakesBatch', 'listTakes'] },+ async (engine) => {+ const alice = await page(engine, 'people/alice-example');+ expect(await engine.addTakesBatch([])).toBe(0);+ const first = await engine.addTakesBatch([+ take(alice.id, 1, 'Alice will ship in Q3', { kind: 'bet', weight: 0.7, since_date: '2026-01-10', source: 'meeting' }),+ take(alice.id, 2, 'Alice prefers async work', { kind: 'take', weight: 0.4, holder: 'alice' }),+ take(alice.id, 3, 'Alice is in Austin', { kind: 'fact', weight: 1 }),+ take(alice.id, 4, 'Over-confident', { weight: 7 }),+ take(alice.id, 5, 'Under-confident', { weight: -3 }),+ take(alice.id, 6, 'Default weight'),+ take(alice.id, 7, 'Already inactive', { active: false, superseded_by: 6 }),+ ]);+ const initial = (await allTakes(engine, alice.id)).map(tv);+ // identical re-add counts every row and changes nothing+ const same = await engine.addTakesBatch([take(alice.id, 1, 'Alice will ship in Q3', { kind: 'bet', weight: 0.7, since_date: '2026-01-10', source: 'meeting' })]);+ // a changed claim/weight updates in place; still one row at that coordinate+ const changed = await engine.addTakesBatch([take(alice.id, 1, 'Alice will ship in Q4', { kind: 'bet', weight: 0.55, since_date: '2026-01-10', source: 'meeting' })]);+ const after = (await allTakes(engine, alice.id)).map(tv);+ expect([first, same, changed]).toEqual([7, 1, 1]);+ expect(initial.find((t) => t.row_num === 4)?.weight).toBe(1);+ expect(initial.find((t) => t.row_num === 5)?.weight).toBe(0);+ expect(initial.find((t) => t.row_num === 6)?.weight).toBe(0.5);+ expect(after.filter((t) => t.row_num === 1)).toHaveLength(1);+ expect(after.find((t) => t.row_num === 1)).toMatchObject({ claim: 'Alice will ship in Q4', weight: 0.55 });+ return { first, same, changed, initial: sorted(initial, (t) => String(t.row_num).padStart(3, '0')), after: sorted(after, (t) => String(t.row_num).padStart(3, '0')) };+ },+ );++ parityTest(+ 'listTakes filters by page, holder, kind, active, resolved and holder allow-list',+ { methods: ['putPage', 'addTakesBatch', 'listTakes', 'resolveTake'] },+ async (engine) => {+ const alice = await page(engine, 'people/alice-example');+ const acme = await page(engine, 'companies/acme-example');+ await engine.addTakesBatch([+ take(alice.id, 1, 'a1 bet', { kind: 'bet', holder: 'garry', weight: 0.9 }),+ take(alice.id, 2, 'a2 take', { kind: 'take', holder: 'alice', weight: 0.3 }),+ take(alice.id, 3, 'a3 inactive', { kind: 'take', holder: 'garry', active: false }),+ ]);+ await engine.addTakesBatch([+ take(acme.id, 1, 'c1 fact', { kind: 'fact', holder: 'world', weight: 1 }),+ take(acme.id, 2, 'c2 bet', { kind: 'bet', holder: 'garry', weight: 0.6 }),+ ]);+ await engine.resolveTake(acme.id, 2, { quality: 'correct', resolvedBy: 'garry' });+ const q = async (opts?: Parameters<BrainEngine['listTakes']>[0]) => sorted(claims(await engine.listTakes(opts)));+ const out = {+ defaultActive: await q(),+ inactive: await q({ active: false }),+ activeUndefinedIsActive: await q({ active: undefined }),+ byPageId: await q({ page_id: alice.id }),+ byPageSlug: await q({ page_slug: 'companies/acme-example' }),+ byHolder: await q({ holder: 'garry' }),+ byKind: await q({ kind: 'bet' }),+ resolved: await q({ resolved: true }),+ unresolved: await q({ resolved: false }),+ allowGarry: await q({ takesHoldersAllowList: ['garry'] }),+ allowNobody: await q({ takesHoldersAllowList: [] }),+ allowWorldAlice: await q({ takesHoldersAllowList: ['world', 'alice'] }),+ missingSlug: await q({ page_slug: 'people/nobody' }),+ };+ expect(out.defaultActive).toEqual(['a1 bet', 'a2 take', 'c1 fact', 'c2 bet']);+ expect(out.inactive).toEqual(['a3 inactive']);+ expect(out.resolved).toEqual(['c2 bet']);+ expect(out.allowNobody).toEqual([]);+ return out;+ },+ );++ parityTest(+ 'listTakes orders newest-first by default and by weight or since_date on request; pages with limit/offset',+ { methods: ['putPage', 'addTakesBatch', 'listTakes'] },+ async (engine) => {+ const p = await page(engine, 'notes/standup');+ await engine.addTakesBatch([+ take(p.id, 1, 't-low', { weight: 0.2, since_date: '2026-03-01' }),+ take(p.id, 2, 't-high', { weight: 0.9, since_date: '2025-12-31' }),+ take(p.id, 3, 't-mid', { weight: 0.5, since_date: '2026-06-15' }),+ take(p.id, 4, 't-undated', { weight: 0.5 }),+ take(p.id, 5, 't-month', { weight: 0.1, since_date: '2026-02' }),+ ]);+ const q = async (opts?: Parameters<BrainEngine['listTakes']>[0]) => claims(await engine.listTakes(opts));+ const byDefault = await q();+ const byWeight = await q({ sortBy: 'weight' });+ const sinceNewest = await q({ sortBy: 'since_date' });+ const sinceOldest = await q({ sortBy: 'since_date', oldestFirst: true });+ const onOrBefore = sorted(await q({ sinceOnOrBefore: '2026-03-01' }));+ const paged = await q({ sortBy: 'since_date', limit: 2, offset: 1 });+ expect(byWeight[0]).toBe('t-high');+ expect(byWeight[4]).toBe('t-month');+ expect(sinceNewest).toEqual(['t-mid', 't-low', 't-month', 't-high', 't-undated']);+ expect(sinceOldest).toEqual(['t-high', 't-month', 't-low', 't-mid', 't-undated']);+ expect(onOrBefore).toEqual(['t-high', 't-low', 't-month']);+ expect(paged).toEqual(['t-low', 't-month']);+ return { byDefault, byWeight, sinceNewest, sinceOldest, onOrBefore, paged };+ },+ );++ parityTest(+ 'listTakes scopes to a source through the take page',+ { methods: ['putPage', 'addTakesBatch', 'listTakes'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'notes-src');+ const main = await page(engine, 'people/alice-example');+ const side = await page(engine, 'people/alice-example', { sourceId: 'notes-src' });+ await engine.addTakesBatch([take(main.id, 1, 'main source take')]);+ await engine.addTakesBatch([take(side.id, 1, 'side source take')]);+ const q = async (opts?: Parameters<BrainEngine['listTakes']>[0]) => sorted(claims(await engine.listTakes(opts)));+ const all = await q();+ const onlyMain = await q({ sourceId: 'default' });+ const onlySide = await q({ sourceId: 'notes-src' });+ const arrayWins = await q({ sourceId: 'default', sourceIds: ['notes-src'] });+ expect(all).toEqual(['main source take', 'side source take']);+ expect(onlyMain).toEqual(['main source take']);+ expect(onlySide).toEqual(['side source take']);+ expect(arrayWins).toEqual(['side source take']);+ return { all, onlyMain, onlySide, arrayWins };+ },+ );++ parityTest(+ 'updateTake changes weight/since_date/source only, clamps weight, and rejects a missing row',+ { methods: ['putPage', 'addTakesBatch', 'updateTake', 'listTakes'] },+ async (engine) => {+ const p = await page(engine, 'people/alice-example');+ await engine.addTakesBatch([take(p.id, 1, 'Alice likes tea', { weight: 0.4, since_date: '2026-01-01', source: 'chat', holder: 'alice', kind: 'take' })]);+ const read = async () => tv((await engine.listTakes({ page_id: p.id }))[0]);+ await engine.updateTake(p.id, 1, { weight: 0.8 });+ const afterWeight = await read();+ await engine.updateTake(p.id, 1, { since_date: '2026-02-02', source: 'email' });+ const afterDateSource = await read();+ await engine.updateTake(p.id, 1, { weight: 9 });+ const afterClamp = await read();+ await engine.updateTake(p.id, 1, {});+ const afterNoop = await read();+ const missing = await errorCode(() => engine.updateTake(p.id, 99, { weight: 0.1 }));+ expect(afterWeight).toMatchObject({ weight: 0.8, since_date: '2026-01-01', source: 'chat', claim: 'Alice likes tea', holder: 'alice', kind: 'take' });+ expect(afterDateSource).toMatchObject({ weight: 0.8, since_date: '2026-02-02', source: 'email' });+ expect(afterClamp.weight).toBe(1);+ expect(afterNoop).toEqual(afterClamp);+ expect(missing).toBe('TAKE_ROW_NOT_FOUND');+ return { afterWeight, afterDateSource, afterClamp, afterNoop, missing };+ },+ );++ parityTest(+ 'supersedeTake appends the new row, deactivates the old one, and refuses missing or resolved rows',+ { methods: ['putPage', 'addTakesBatch', 'supersedeTake', 'resolveTake', 'listTakes', 'listActiveTakesForPages'] },+ async (engine) => {+ const p = await page(engine, 'people/alice-example');+ await engine.addTakesBatch([+ take(p.id, 1, 'Alice will raise a seed', { kind: 'bet', weight: 0.6 }),+ take(p.id, 2, 'Alice likes tea'),+ take(p.id, 4, 'Row four exists already'),+ ]);+ const res = await engine.supersedeTake(p.id, 1, { claim: 'Alice will raise a Series A', kind: 'bet', holder: 'garry', weight: 0.8, since_date: '2026-05-01', source: 'update' });+ // next row_num is max+1, so it lands after the gap+ expect(res).toEqual({ oldRow: 1, newRow: 5 });+ const all = (await allTakes(engine, p.id)).map(tv);+ const active = claims(await engine.listTakes({ page_id: p.id }));+ const activeMap = await engine.listActiveTakesForPages([p.id]);+ expect(all.find((t) => t.row_num === 1)).toMatchObject({ active: false, superseded_by: 5 });+ expect(all.find((t) => t.row_num === 5)).toMatchObject({ active: true, claim: 'Alice will raise a Series A', weight: 0.8, superseded_by: null });+ expect(sorted(active)).toEqual(['Alice likes tea', 'Alice will raise a Series A', 'Row four exists already']);+ expect(claims(activeMap.get(p.id)!)).toEqual(['Alice likes tea', 'Row four exists already', 'Alice will raise a Series A']);++ await engine.resolveTake(p.id, 2, { quality: 'incorrect', resolvedBy: 'garry' });+ const resolvedErr = await errorCode(() => engine.supersedeTake(p.id, 2, { claim: 'x', kind: 'take', holder: 'garry' }));+ const missingErr = await errorCode(() => engine.supersedeTake(p.id, 77, { claim: 'x', kind: 'take', holder: 'garry' }));+ expect(resolvedErr).toBe('TAKE_RESOLVED_IMMUTABLE');+ expect(missingErr).toBe('TAKE_ROW_NOT_FOUND');+ return { res, all: sorted(all, (t) => String(t.row_num).padStart(3, '0')), resolvedErr, missingErr };+ },+ );++ parityTest(+ 'resolveTake derives quality/outcome, stores resolution metadata, and is immutable',+ { methods: ['putPage', 'addTakesBatch', 'resolveTake', 'listTakes'] },+ async (engine) => {+ const p = await page(engine, 'companies/acme-example');+ await engine.addTakesBatch(+ [1, 2, 3, 4, 5, 6].map((n) => take(p.id, n, `bet ${n}`, { kind: 'bet', weight: 0.5 })),+ );+ await engine.resolveTake(p.id, 1, { quality: 'correct', value: 1200000, unit: 'usd', source: 'press release', resolvedBy: 'garry' });+ await engine.resolveTake(p.id, 2, { quality: 'incorrect', resolvedBy: 'garry' });+ await engine.resolveTake(p.id, 3, { quality: 'partial', resolvedBy: 'people/alice-example' });+ await engine.resolveTake(p.id, 4, { quality: 'unresolvable', resolvedBy: 'garry' });+ await engine.resolveTake(p.id, 5, { outcome: true, resolvedBy: 'garry' });+ await engine.resolveTake(p.id, 6, { outcome: false, resolvedBy: 'garry' });+ const rows = (await engine.listTakes({ page_id: p.id })).map(tv);+ const again = await errorCode(() => engine.resolveTake(p.id, 1, { quality: 'incorrect', resolvedBy: 'garry' }));+ const missing = await errorCode(() => engine.resolveTake(p.id, 42, { quality: 'correct', resolvedBy: 'garry' }));+ const noVerdict = await errorCode(() => engine.resolveTake(p.id, 1, { resolvedBy: 'garry' }));+ expect(again).toBe('TAKE_ALREADY_RESOLVED');+ expect(missing).toBe('TAKE_ROW_NOT_FOUND');+ const byRow = Object.fromEntries(rows.map((r) => [r.row_num, r]));+ expect(byRow[1]).toMatchObject({ resolved_quality: 'correct', resolved_outcome: true, resolved_value: 1200000, resolved_unit: 'usd', resolved_source: 'press release', resolved_by: 'garry', resolved: true });+ expect(byRow[2]).toMatchObject({ resolved_quality: 'incorrect', resolved_outcome: false });+ expect(byRow[3]).toMatchObject({ resolved_quality: 'partial', resolved_outcome: null, resolved_by: 'people/alice-example' });+ expect(byRow[4]).toMatchObject({ resolved_quality: 'unresolvable', resolved_outcome: null });+ expect(byRow[5]).toMatchObject({ resolved_quality: 'correct', resolved_outcome: true });+ expect(byRow[6]).toMatchObject({ resolved_quality: 'incorrect', resolved_outcome: false });+ return { rows: sorted(rows, (t) => String(t.row_num).padStart(3, '0')), again, missing, noVerdict };+ },+ );++ parityTest(+ 'getScorecard counts bets, accuracy, Brier and partial/unresolvable rates, scoped by holder, domain, dates, allow-list and source',+ { methods: ['putPage', 'addTakesBatch', 'resolveTake', 'getScorecard'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'side');+ const acme = await page(engine, 'companies/acme-example');+ const alice = await page(engine, 'people/alice-example');+ const side = await page(engine, 'companies/side-example', { sourceId: 'side' });+ await engine.addTakesBatch([+ take(acme.id, 1, 'acme b1', { kind: 'bet', holder: 'garry', weight: 0.9, since_date: '2026-01-10' }),+ take(acme.id, 2, 'acme b2', { kind: 'bet', holder: 'garry', weight: 0.7, since_date: '2026-02-10' }),+ take(acme.id, 3, 'acme b3', { kind: 'bet', holder: 'garry', weight: 0.2, since_date: '2026-03-10' }),+ take(acme.id, 4, 'acme b4', { kind: 'bet', holder: 'garry', weight: 0.5, since_date: '2026-04-10' }),+ take(acme.id, 5, 'acme b5', { kind: 'bet', holder: 'garry', weight: 0.5, since_date: '2026-05-10' }),+ take(acme.id, 6, 'acme take (not a bet)', { kind: 'take', holder: 'garry', weight: 0.5 }),+ ]);+ await engine.addTakesBatch([+ take(alice.id, 1, 'alice b1', { kind: 'bet', holder: 'alice', weight: 0.6, since_date: '2026-02-20' }),+ take(alice.id, 2, 'alice b2', { kind: 'bet', holder: 'alice', weight: 0.4, since_date: '2026-06-01' }),+ ]);+ await engine.addTakesBatch([take(side.id, 1, 'side b1', { kind: 'bet', holder: 'garry', weight: 0.8, since_date: '2026-02-01' })]);+ await engine.resolveTake(acme.id, 1, { quality: 'correct', resolvedBy: 'garry' });+ await engine.resolveTake(acme.id, 2, { quality: 'incorrect', resolvedBy: 'garry' });+ await engine.resolveTake(acme.id, 3, { quality: 'correct', resolvedBy: 'garry' });+ await engine.resolveTake(acme.id, 4, { quality: 'partial', resolvedBy: 'garry' });+ await engine.resolveTake(acme.id, 5, { quality: 'unresolvable', resolvedBy: 'garry' });+ await engine.resolveTake(alice.id, 1, { quality: 'correct', resolvedBy: 'garry' });+ await engine.resolveTake(side.id, 1, { quality: 'incorrect', resolvedBy: 'garry' });+ const card = async (opts: Parameters<BrainEngine['getScorecard']>[0], allow?: string[]) => {+ const c = await engine.getScorecard(opts, allow);+ return { ...c, accuracy: round(c.accuracy), brier: round(c.brier), partial_rate: round(c.partial_rate), unresolvable_rate: round(c.unresolvable_rate) };+ };+ const all = await card({}, undefined);+ const holderGarry = await card({ holder: 'garry' }, undefined);+ const holderAlice = await card({ holder: 'alice' }, undefined);+ const domain = await card({ domainPrefix: 'companies/' }, undefined);+ const since = await card({ since: '2026-03-01' }, undefined);+ const until = await card({ until: '2026-02-28' }, undefined);+ const allowAlice = await card({}, ['alice']);+ const allowNobody = await card({}, []);+ const mainSource = await card({ sourceId: 'default' }, undefined);+ const sideSource = await card({ sourceId: 'side' }, undefined);+ const bothSources = await card({ sourceIds: ['default', 'side'] }, undefined);+ const emptyBrainHolder = await card({ holder: 'nobody' }, undefined);+ // 8 bets total (5 acme + 2 alice + 1 side); acme resolved 1+2+3+4 (partial) ; correct 3 incl. alice+ expect(all).toMatchObject({ total_bets: 8, resolved: 6, correct: 3, incorrect: 2, partial: 1, unresolvable_count: 1 });+ expect(all.accuracy).toBe(round(3 / 5));+ expect(allowNobody).toMatchObject({ total_bets: 0, resolved: 0, accuracy: null, brier: null });+ expect(emptyBrainHolder).toMatchObject({ total_bets: 0, accuracy: null, brier: null });+ return { all, holderGarry, holderAlice, domain, since, until, allowAlice, allowNobody, mainSource, sideSource, bothSources, emptyBrainHolder };+ },+ );++ parityTest(+ 'getCalibrationCurve bins resolved correct/incorrect bets by weight and honors holder, bucket size and allow-list',+ { methods: ['putPage', 'addTakesBatch', 'resolveTake', 'getCalibrationCurve'] },+ async (engine) => {+ const p = await page(engine, 'companies/acme-example');+ const weights: Array<[number, 'correct' | 'incorrect' | 'partial', string]> = [+ [0.9, 'correct', 'garry'], [0.95, 'correct', 'garry'], [0.9, 'incorrect', 'garry'],+ [0.7, 'correct', 'garry'], [0.7, 'incorrect', 'alice'], [0.3, 'incorrect', 'garry'],+ [0.35, 'correct', 'alice'], [0.5, 'partial', 'garry'], [1, 'correct', 'garry'], [0, 'incorrect', 'garry'],+ ];+ await engine.addTakesBatch(weights.map(([w, , holder], i) => take(p.id, i + 1, `cal ${i + 1}`, { kind: 'bet', weight: w, holder })));+ await engine.addTakesBatch([take(p.id, 50, 'unresolved bet', { kind: 'bet', weight: 0.6 })]);+ for (const [i, [, quality]] of weights.entries()) await engine.resolveTake(p.id, i + 1, { quality, resolvedBy: 'garry' });+ const norm = (rows: Awaited<ReturnType<BrainEngine['getCalibrationCurve']>>) =>+ rows.map((r) => ({ lo: round(r.bucket_lo), hi: round(r.bucket_hi), n: r.n, observed: round(r.observed), predicted: round(r.predicted) }));+ const dflt = norm(await engine.getCalibrationCurve({}, undefined));+ const coarse = norm(await engine.getCalibrationCurve({ bucketSize: 0.5 }, undefined));+ const garry = norm(await engine.getCalibrationCurve({ holder: 'garry' }, undefined));+ const allow = norm(await engine.getCalibrationCurve({}, ['alice']));+ const none = norm(await engine.getCalibrationCurve({}, []));+ const badSize = norm(await engine.getCalibrationCurve({ bucketSize: 5 }, undefined));+ expect(dflt.reduce((a, b) => a + b.n, 0)).toBe(9); // partial and unresolved excluded+ expect(dflt.find((b) => b.lo === 0.9)).toMatchObject({ hi: 1, n: 4 }); // 0.9,0.95,0.9 and 1 (final bucket is inclusive of 1.0)+ expect(none).toEqual([]);+ expect(badSize).toEqual(dflt);+ return { dflt, coarse, garry, allow, none, badSize };+ },+ );++ parityTest(+ 'addSynthesisEvidence inserts provenance rows once per (synthesis, take page, take row)',+ { methods: ['putPage', 'addTakesBatch', 'addSynthesisEvidence'] },+ async (engine) => {+ const synthesis = await page(engine, 'notes/think-2026-07');+ const source = await page(engine, 'people/alice-example');+ await engine.addTakesBatch([take(source.id, 1, 'cited one'), take(source.id, 2, 'cited two'), take(source.id, 3, 'cited three')]);+ expect(await engine.addSynthesisEvidence([])).toBe(0);+ const first = await engine.addSynthesisEvidence([+ { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 1, citation_index: 1 },+ { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 2, citation_index: 2 },+ ]);+ const repeat = await engine.addSynthesisEvidence([+ { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 1, citation_index: 9 },+ ]);+ const mixed = await engine.addSynthesisEvidence([+ { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 2, citation_index: 5 },+ { synthesis_page_id: synthesis.id, take_page_id: source.id, take_row_num: 3, citation_index: 3 },+ ]);+ expect([first, repeat, mixed]).toEqual([2, 0, 1]);+ return { first, repeat, mixed };+ },+ );++ parityTest(+ 'listActiveTakesForPages groups active takes per page in row order, filters by allow-list, and keys empty pages',+ { methods: ['putPage', 'addTakesBatch', 'listActiveTakesForPages'] },+ async (engine) => {+ const a = await page(engine, 'people/alice-example');+ const b = await page(engine, 'people/bob-example');+ const empty = await page(engine, 'people/empty-example');+ await engine.addTakesBatch([+ take(a.id, 2, 'a second', { holder: 'alice' }),+ take(a.id, 1, 'a first', { holder: 'garry' }),+ take(a.id, 3, 'a inactive', { active: false }),+ take(b.id, 1, 'b only', { holder: 'garry' }),+ ]);+ const slugOf = new Map([[a.id, 'alice'], [b.id, 'bob'], [empty.id, 'empty'], [123456789, 'missing']]);+ const shape = (m: Map<number, Take[]>) => sorted([...m.entries()].map(([id, ts]) => `${slugOf.get(id)}=${claims(ts).join('|')}`));+ const all = shape(await engine.listActiveTakesForPages([a.id, b.id, empty.id, 123456789]));+ const garryOnly = shape(await engine.listActiveTakesForPages([a.id, b.id], { takesHoldersAllowList: ['garry'] }));+ const nobody = shape(await engine.listActiveTakesForPages([a.id], { takesHoldersAllowList: [] }));+ const none = (await engine.listActiveTakesForPages([])).size;+ expect(all).toEqual(['alice=a first|a second', 'bob=b only', 'empty=', 'missing=']);+ expect(none).toBe(0);+ return { all, garryOnly, nobody, none };+ },+ );++ parityTest(+ 'searchTakes ranks active takes by trigram similarity and applies holder allow-list, source and limit',+ { methods: ['putPage', 'addTakesBatch', 'searchTakes'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'side');+ const a = await page(engine, 'people/alice-example');+ const s = await page(engine, 'people/side-example', { sourceId: 'side' });+ await engine.addTakesBatch([+ take(a.id, 1, 'Alice loves rust programming', { holder: 'garry', weight: 0.5 }),+ take(a.id, 2, 'Bob writes rust daily', { holder: 'alice', weight: 0.9 }),+ take(a.id, 3, 'Gardening is relaxing', { holder: 'garry' }),+ take(a.id, 4, 'Retired rust opinion', { holder: 'garry', active: false }),+ ]);+ await engine.addTakesBatch([take(s.id, 1, 'Side project in rust', { holder: 'garry', weight: 0.1 })]);+ const norm = (hits: TakeHit[]) => hits.map((h) => ({ slug: h.page_slug, row: h.row_num, claim: h.claim, holder: h.holder, weight: h.weight, score: round(h.score) }));+ const rust = norm(await engine.searchTakes('rust'));+ const limited = norm(await engine.searchTakes('rust', { limit: 1 }));+ const allow = norm(await engine.searchTakes('rust', { takesHoldersAllowList: ['alice'] }));+ const noOne = norm(await engine.searchTakes('rust', { takesHoldersAllowList: [] }));+ const side = norm(await engine.searchTakes('rust', { sourceId: 'side' }));+ const miss = norm(await engine.searchTakes('zzzzqqqq'));+ expect(rust.map((h) => h.claim)).not.toContain('Retired rust opinion');+ expect(rust.map((h) => h.claim)).not.toContain('Gardening is relaxing');+ expect(rust).toHaveLength(3);+ expect(allow.map((h) => h.claim)).toEqual(['Bob writes rust daily']);+ expect(noOne).toEqual([]);+ expect(side.map((h) => h.claim)).toEqual(['Side project in rust']);+ expect(miss).toEqual([]);+ return { rust, limited, allow, noOne, side, miss };+ },+ );++ parityTest(+ 'take embeddings: write, read back, vector search, and staleness accounting',+ {+ methods: [+ 'putPage', 'addTakesBatch', 'listTakes', 'updateTakeEmbeddings', 'getTakeEmbeddings', 'searchTakesVector',+ 'countStaleTakes', 'listStaleTakes',+ ],+ },+ async (engine, backend) => {+ await createSource(engine, backend, 'side');+ const a = await page(engine, 'people/alice-example');+ const s = await page(engine, 'people/side-example', { sourceId: 'side' });+ await engine.addTakesBatch([+ take(a.id, 1, 'axis zero take', { holder: 'garry', weight: 0.5 }),+ take(a.id, 2, 'axis one take', { holder: 'alice', weight: 0.5 }),+ take(a.id, 3, 'never embedded take'),+ take(a.id, 4, 'inactive take', { active: false }),+ ]);+ await engine.addTakesBatch([take(s.id, 1, 'side axis zero take')]);+ const ids = await takeIds(engine, a.id);+ const sideIds = await takeIds(engine, s.id);+ const nameOf = new Map<number, string>([...ids, ...sideIds].map(([claim, id]) => [id, claim]));+ const staleClaims = async (opts?: Parameters<BrainEngine['listStaleTakes']>[0]) => (await engine.listStaleTakes(opts)).map((r) => r.claim);++ const beforeAll = await engine.countStaleTakes();+ expect(beforeAll).toBe(4); // active takes only: 3 on alice + 1 on side+ expect(await engine.updateTakeEmbeddings([])).toBe(0);++ // the takes.embedding column is the configured embedding width (1536 on a default brain)+ // The side take leans a little toward axis 2, so no two takes tie on cosine score: vector+ // search orders by distance alone (the shape its HNSW index serves), and an exact tie may come+ // back in either order. Its largest component stays on axis 0.+ const sideVector = basisEmbedding(0);+ sideVector[2] = 0.3;+ const written = await engine.updateTakeEmbeddings([+ { take_id: ids.get('axis zero take')!, embedding: basisEmbedding(0), claim: 'axis zero take', model: 'embed-m1' },+ { take_id: ids.get('axis one take')!, embedding: basisEmbedding(1), claim: 'axis one take', model: 'embed-m1' },+ { take_id: sideIds.get('side axis zero take')!, embedding: sideVector, claim: 'side axis zero take', model: 'embed-m1' },+ // claim drifted while the vector was in flight: discarded+ { take_id: ids.get('never embedded take')!, embedding: basisEmbedding(2), claim: 'an older claim text', model: 'embed-m1' },+ // inactive rows are ignored+ { take_id: ids.get('inactive take')!, embedding: basisEmbedding(3), claim: 'inactive take', model: 'embed-m1' },+ ]);+ expect(written).toBe(3);++ const stored = await engine.getTakeEmbeddings([...ids.values(), ...sideIds.values(), 987654321]);+ const storedView = sorted([...stored.entries()].map(([id, v]) => `${nameOf.get(id)}:${v.length}:${v.indexOf(1)}`));+ expect(storedView).toEqual(['axis one take:1536:1', 'axis zero take:1536:0', 'side axis zero take:1536:0']);+ expect((await engine.getTakeEmbeddings([])).size).toBe(0);++ const stale = {+ count: await engine.countStaleTakes(),+ claims: await staleClaims(),+ otherModel: await engine.countStaleTakes({ model: 'embed-m2' }),+ sameModel: await engine.countStaleTakes({ model: 'embed-m1' }),+ wrongDims: await engine.countStaleTakes({ dims: 768 }),+ rightDims: await engine.countStaleTakes({ dims: 1536 }),+ sideOnly: await staleClaims({ sourceId: 'side' }),+ defaultOnly: await staleClaims({ sourceId: 'default' }),+ };+ expect(stale.claims).toEqual(['never embedded take']);+ expect(stale.otherModel).toBe(4);+ expect(stale.sameModel).toBe(1);+ expect(stale.wrongDims).toBe(4);+ expect(stale.rightDims).toBe(1);+ expect(stale.sideOnly).toEqual([]);++ // vector search: cosine against the stored vectors, active + embedded rows only+ // scores against the query: axis zero 0.995, side 0.953, axis one 0.0995 (strictly ordered)+ const hit = (hits: TakeHit[]) => hits.map((h) => ({ claim: h.claim, score: round(h.score) }));+ const nearZero = new Float32Array(1536);+ nearZero[0] = 1;+ nearZero[1] = 0.1;+ const nearest = hit(await engine.searchTakesVector(nearZero));+ const nearestOne = hit(await engine.searchTakesVector(nearZero, { limit: 1 }));+ const allow = hit(await engine.searchTakesVector(nearZero, { takesHoldersAllowList: ['alice'] }));+ const sideScoped = hit(await engine.searchTakesVector(nearZero, { sourceId: 'side' }));+ const noOne = hit(await engine.searchTakesVector(nearZero, { takesHoldersAllowList: [] }));+ expect(nearest.map((h) => h.claim)).toEqual(['axis zero take', 'side axis zero take', 'axis one take']);+ expect(nearestOne.map((h) => h.claim)).toEqual(['axis zero take']);+ expect(allow.map((h) => h.claim)).toEqual(['axis one take']);+ expect(sideScoped.map((h) => h.claim)).toEqual(['side axis zero take']);+ expect(noOne).toEqual([]);++ // editing a claim through the batch upsert clears its vector (stale again); an unchanged claim keeps it+ await engine.addTakesBatch([+ take(a.id, 1, 'axis zero take, reworded', { holder: 'garry', weight: 0.5 }),+ take(a.id, 2, 'axis one take', { holder: 'alice', weight: 0.5 }),+ ]);+ const afterEdit = {+ stale: sorted(await staleClaims()),+ embeddings: sorted([...(await engine.getTakeEmbeddings([...ids.values()])).keys()].map((id) => nameOf.get(id)!)),+ };+ expect(afterEdit.stale).toEqual(['axis zero take, reworded', 'never embedded take']);+ expect(afterEdit.embeddings).toEqual(['axis one take']);++ const dupErr = await errorCode(() => engine.updateTakeEmbeddings([+ { take_id: ids.get('axis one take')!, embedding: basisEmbedding(1), claim: 'axis one take', model: 'embed-m1' },+ { take_id: ids.get('axis one take')!, embedding: basisEmbedding(1), claim: 'axis one take', model: 'embed-m1' },+ ]));+ expect(dupErr).not.toBeNull();+ return { beforeAll, written, storedView, stale, nearest, nearestOne, allow, sideScoped, noOne, afterEdit, rejectsDuplicateIds: dupErr !== null };+ },+ );+});++describe('engine parity: contradiction probe runs and judge cache', () => {+ const runRow = (id: string, over: Record<string, unknown> = {}) => ({+ run_id: id, judge_model: 'judge-m1', prompt_version: 'v1', queries_evaluated: 20, queries_with_contradiction: 4,+ total_contradictions_flagged: 6, wilson_ci_lower: 0.08, wilson_ci_upper: 0.42, judge_errors_total: 1, cost_usd_total: 0.37,+ duration_ms: 1234, source_tier_breakdown: { curated: 3, bulk: 1 }, report_json: { notes: ['a', 'b'], nested: { ok: true } }, ...over,+ });+ type Run = ReturnType<typeof runRow>;++ parityTest(+ 'writeContradictionsRun is idempotent on run_id; loadContradictionsTrend returns runs newest first with parsed JSON',+ { methods: ['writeContradictionsRun', 'loadContradictionsTrend'] },+ async (engine) => {+ // ran_at defaults to the database clock's now(), and loadContradictionsTrend keeps rows with+ // ran_at >= a cutoff taken from the JS clock. Wait until the JS clock is strictly past the+ // newest stored ran_at (millisecond ISO) before the next write or the days=0 read, so neither+ // newest-first order nor the empty window depends on how fast the calls ran.+ const waitPastNewestRun = async () => {+ const newest = Date.parse((await engine.loadContradictionsTrend(7))[0]!.ran_at);+ expect(Number.isFinite(newest)).toBe(true);+ while (Date.now() <= newest) await new Promise((r) => setTimeout(r, 1));+ };+ const wrote: boolean[] = [];+ wrote.push(await engine.writeContradictionsRun(runRow('run-a') as Run));+ await waitPastNewestRun();+ wrote.push(await engine.writeContradictionsRun(runRow('run-b', { queries_evaluated: 30, cost_usd_total: 1.5, report_json: {} }) as Run));+ await waitPastNewestRun();+ wrote.push(await engine.writeContradictionsRun(runRow('run-a', { queries_evaluated: 999 }) as Run)); // same run_id: no-op+ wrote.push(await engine.writeContradictionsRun(runRow('run-c', { judge_model: 'judge-m2', source_tier_breakdown: {} }) as Run));+ expect(wrote).toEqual([true, true, false, true]);+ const trend = await engine.loadContradictionsTrend(7);+ expect(trend.map((r) => r.run_id)).toEqual(['run-c', 'run-b', 'run-a']);+ expect(trend.find((r) => r.run_id === 'run-a')?.queries_evaluated).toBe(20); // not overwritten+ expect(typeof trend[0].ran_at).toBe('string');+ await waitPastNewestRun();+ const nothing = await engine.loadContradictionsTrend(0);+ expect(nothing).toEqual([]);+ return {+ wrote,+ trend: trend.map(({ ran_at: _ranAt, ...rest }) => rest),+ nothing,+ };+ },+ );++ const key = { chunk_a_hash: 'hash-a', chunk_b_hash: 'hash-b', model_id: 'judge-m1', prompt_version: 'v1', truncation_policy: 'head-2k' };++ parityTest(+ 'judge cache: put/get by the full 5-part key, upsert refreshes the verdict, other keys miss',+ { methods: ['putContradictionCacheEntry', 'getContradictionCacheEntry', 'sweepContradictionCache'] },+ async (engine) => {+ const empty = await engine.getContradictionCacheEntry(key);+ await engine.putContradictionCacheEntry({ ...key, verdict: { contradicts: true, confidence: 0.9, axes: ['date', 'amount'] } });+ const hit = await engine.getContradictionCacheEntry(key);+ await engine.putContradictionCacheEntry({ ...key, verdict: { contradicts: false } });+ const updated = await engine.getContradictionCacheEntry(key);+ const misses = {+ otherA: await engine.getContradictionCacheEntry({ ...key, chunk_a_hash: 'hash-z' }),+ otherB: await engine.getContradictionCacheEntry({ ...key, chunk_b_hash: 'hash-z' }),+ otherModel: await engine.getContradictionCacheEntry({ ...key, model_id: 'judge-m2' }),+ otherPrompt: await engine.getContradictionCacheEntry({ ...key, prompt_version: 'v2' }),+ otherTruncation: await engine.getContradictionCacheEntry({ ...key, truncation_policy: 'tail-2k' }),+ };+ // a second key lives beside the first; a short ttl is floored to 60s, so it is still live+ await engine.putContradictionCacheEntry({ ...key, prompt_version: 'v2', verdict: { contradicts: true }, ttl_seconds: 1 });+ const shortTtl = await engine.getContradictionCacheEntry({ ...key, prompt_version: 'v2' });+ // nothing has expired, so a sweep removes nothing and the entries stay readable+ const swept = await engine.sweepContradictionCache();+ const stillThere = await engine.getContradictionCacheEntry(key);+ expect(empty).toBeNull();+ expect(hit).toEqual({ contradicts: true, confidence: 0.9, axes: ['date', 'amount'] });+ expect(updated).toEqual({ contradicts: false });+ expect(Object.values(misses).every((m) => m === null)).toBe(true);+ expect(shortTtl).toEqual({ contradicts: true });+ expect(swept).toBe(0);+ return { empty, hit, updated, misses, shortTtl, swept, stillThere };+ },+ );+});++describe('engine parity: dream verdict cache', () => {+ const verdict = (over: Record<string, unknown> = {}) => ({+ worth_processing: true, reasons: ['mentions a decision', 'names a person'], score: 0.82, content_type: 'meeting',+ segments: [{ quote: 'we will ship in Q3', note: 'commitment' }, { quote: 'Alice owns it' }],+ entities: ['people/alice-example', 'companies/acme-example'], model: 'triage-m1', triage_version: 1, ...over,+ });+ type Verdict = ReturnType<typeof verdict>;++ parityTest(+ 'putDreamVerdict/getDreamVerdict round-trip by (file, hash); a re-put replaces; sweep spares live rows',+ { methods: ['putDreamVerdict', 'getDreamVerdict', 'sweepDreamVerdicts'] },+ async (engine) => {+ const miss = await engine.getDreamVerdict('transcripts/a.md', 'h1');+ await engine.putDreamVerdict('transcripts/a.md', 'h1', verdict() as Verdict);+ const hit = await engine.getDreamVerdict('transcripts/a.md', 'h1');+ await engine.putDreamVerdict('transcripts/a.md', 'h1', verdict({ worth_processing: false, reasons: [], score: 0.1, content_type: null, segments: [], entities: [], model: 'triage-m2', triage_version: 2 }) as Verdict);+ const replaced = await engine.getDreamVerdict('transcripts/a.md', 'h1');+ // a backoff marker: no score, still stored+ await engine.putDreamVerdict('transcripts/b.md', 'h9', verdict({ score: null, worth_processing: false }) as Verdict);+ const backoff = await engine.getDreamVerdict('transcripts/b.md', 'h9');+ const otherHash = await engine.getDreamVerdict('transcripts/a.md', 'h2');+ const otherFile = await engine.getDreamVerdict('transcripts/c.md', 'h1');+ const swept = await engine.sweepDreamVerdicts();+ const afterSweep = await engine.getDreamVerdict('transcripts/a.md', 'h1');+ const strip = <T extends { judged_at: string } | null>(v: T) => (v ? { ...v, judged_at: typeof v.judged_at === 'string' && v.judged_at.length > 0 ? '<ts>' : v.judged_at } : v);+ expect(miss).toBeNull();+ expect(hit).toMatchObject({ worth_processing: true, reasons: ['mentions a decision', 'names a person'], score: 0.82, content_type: 'meeting', model: 'triage-m1', triage_version: 1 });+ expect(hit?.segments).toEqual([{ quote: 'we will ship in Q3', note: 'commitment' }, { quote: 'Alice owns it' }]);+ expect(replaced).toMatchObject({ worth_processing: false, reasons: [], score: 0.1, segments: [], entities: [], model: 'triage-m2', triage_version: 2 });+ expect(backoff?.score).toBeNull();+ expect(otherHash).toBeNull();+ expect(otherFile).toBeNull();+ expect(swept).toBe(0);+ expect(afterSweep).not.toBeNull();+ return { miss, hit: strip(hit), replaced: strip(replaced), backoff: strip(backoff), otherHash, otherFile, swept, afterSweep: strip(afterSweep) };+ },+ );+});diff --git a/test/engine-parity/timeline.test.ts b/test/engine-parity/timeline.test.tsnew file mode 100644index 0000000000..dce8213400--- /dev/null+++ b/test/engine-parity/timeline.test.ts@@ -0,0 +1,323 @@+/**+ * BrainEngine parity — timeline family (timeline entries, Life Chronicle date+ * reads, event projections) and the per-entity ontology that rides `facts`.+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: every timeline write/read and every ontology merge/read+ * returns the same observable result on every engine arm (PGLite always;+ * Postgres with DATABASE_URL; a Rust arm later through+ * test/engine-parity/harness.ts).+ * - Regression: an engine that drifts on timeline dedup, date-window+ * filtering, intra-day ordering, "on this day" / last-seen date math,+ * event-projection upsert, or ontology supersession and conflict+ * detection — the reads behind `gbrain timeline`, the chronicle and+ * "what do I know about X".+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and covers only getTimeline windows; the+ * chronicle/ontology unit tests run on PGLite alone.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ * Entry ids and page ids are never returned.+ */+import { describe, expect } from 'bun:test';+import type { BrainEngine } from '../../src/core/engine.ts';+import type { ChronicleTimelineRow, OntologyConflict } from '../../src/core/types.ts';+import { createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++const ENTRY_KEYS = ['date', 'source', 'summary', 'detail'] as const;+const CHRONICLE_KEYS = ['date', 'summary', 'detail', 'source', 'page_slug', 'event_slug', 'effective_date', 'kind'] as const;+const chronicle = (rows: ChronicleTimelineRow[]) => rows.map((r) => pick(r, CHRONICLE_KEYS));++async function putPlain(engine: BrainEngine, slug: string, opts?: { sourceId?: string }) {+ return engine.putPage(slug, { type: 'note', title: slug, compiled_truth: `${slug} body`, timeline: '' }, opts);+}++/** An event page the chronicle reads order by its effective_date. */+async function putEvent(engine: BrainEngine, slug: string, effective: string, event: { kind: string; who?: string[] }, opts?: { sourceId?: string }) {+ return engine.putPage(slug, {+ type: 'event', title: slug, compiled_truth: `${slug} body`, timeline: '',+ frontmatter: { event },+ effective_date: new Date(effective), effective_date_source: 'event_date',+ }, opts);+}++/** Depth pages + three events across three days; projections via upsertEventProjection. */+async function seedChronicle(engine: BrainEngine) {+ await putPlain(engine, 'life/diary/2026-06-18');+ await putPlain(engine, 'life/diary/2026-06-20');+ await putEvent(engine, 'life/events/2026-06-18-001', '2026-06-18T09:00:00Z', { kind: 'meeting', who: ['people/sarah-chen'] });+ await putEvent(engine, 'life/events/2026-06-18-002', '2026-06-18T15:00:00Z', { kind: 'commitment', who: ['people/sarah-chen'] });+ await putEvent(engine, 'life/events/2026-06-20-001', '2026-06-20T10:00:00Z', { kind: 'meeting', who: ['people/bob-jones'] });+ // Insert the later event first: reads must still order by effective_date.+ await engine.upsertEventProjection({ depthSlug: 'life/diary/2026-06-18', eventSlug: 'life/events/2026-06-18-002', date: '2026-06-18', summary: 'Promised the deck', detail: 'd2' });+ await engine.upsertEventProjection({ depthSlug: 'life/diary/2026-06-18', eventSlug: 'life/events/2026-06-18-001', date: '2026-06-18', summary: 'Met Sarah', detail: 'd1' });+ await engine.upsertEventProjection({ depthSlug: 'life/diary/2026-06-20', eventSlug: 'life/events/2026-06-20-001', date: '2026-06-20', summary: 'Call with Bob', detail: 'd3' });+}++describe('engine parity: timeline entries', () => {+ parityTest(+ 'addTimelineEntry inserts, dedups on (date, summary) and reports whether a row was written',+ { methods: ['addTimelineEntry', 'getTimeline', 'putPage'] },+ async (engine) => {+ await putPlain(engine, 'people/alice');+ const first = await engine.addTimelineEntry('people/alice', { date: '2026-01-02', source: 'cal', summary: 'Joined Acme', detail: 'day one' });+ const dup = await engine.addTimelineEntry('people/alice', { date: '2026-01-02', source: 'cal', summary: 'Joined Acme', detail: 'day one' });+ const later = await engine.addTimelineEntry('people/alice', { date: '2026-03-04', summary: 'Promoted' });+ await engine.addTimelineEntry('people/alice', { date: '2025-12-31', source: 'note', summary: 'Interviewed', detail: 'phone screen' });+ expect(first).toBe(true);+ expect(dup).toBe(false);+ expect(later).toBe(true);+ let missingPage = 'no error';+ try {+ await engine.addTimelineEntry('people/nobody', { date: '2026-01-01', summary: 'ghost' });+ } catch (error) {+ missingPage = 'threw';+ }+ expect(missingPage).toBe('threw');+ const skipped = await engine.addTimelineEntry('people/nobody', { date: '2026-01-01', summary: 'ghost' }, { skipExistenceCheck: true });+ const entries = (await engine.getTimeline('people/alice')).map((e) => pick(e, ENTRY_KEYS));+ return { first, dup, later, missingPage, skipped, entries };+ },+ );++ parityTest(+ 'getTimeline orders newest first and applies limit and the after/before window',+ { methods: ['getTimeline', 'addTimelineEntry', 'putPage'] },+ async (engine) => {+ await putPlain(engine, 'people/bob');+ for (const [date, summary] of [['2026-01-10', 'jan'], ['2026-02-10', 'feb'], ['2026-03-10', 'mar'], ['2026-04-10', 'apr']]) {+ await engine.addTimelineEntry('people/bob', { date: date!, summary: summary! });+ }+ const summaries = async (opts?: Parameters<BrainEngine['getTimeline']>[1]) => (await engine.getTimeline('people/bob', opts)).map((e) => e.summary);+ const all = await summaries();+ const limited = await summaries({ limit: 2 });+ const after = await summaries({ after: '2026-02-10' });+ const before = await summaries({ before: '2026-03-10' });+ const window = await summaries({ after: '2026-01-15', before: '2026-04-01' });+ const missing = await summaries({ sourceId: 'no-such-source' });+ expect(missing).toEqual([]);+ expect(await engine.getTimeline('people/nobody')).toEqual([]);+ return { all, limited, after, before, window, missing };+ },+ );++ parityTest(+ 'addTimelineEntriesBatch counts inserted rows, drops missing pages and replays as no-ops',+ { methods: ['addTimelineEntriesBatch', 'getTimeline', 'putPage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'alt');+ await putPlain(engine, 'batch/one');+ await putPlain(engine, 'batch/two');+ await putPlain(engine, 'batch/one', { sourceId: 'alt' });+ const batch = [+ { slug: 'batch/one', date: '2026-05-01', summary: 'one-a', detail: 'x', source: 'import' },+ { slug: 'batch/one', date: '2026-05-02', summary: 'one-b' },+ { slug: 'batch/two', date: '2026-05-01', summary: 'two-a' },+ { slug: 'batch/missing', date: '2026-05-01', summary: 'ghost' },+ { slug: 'batch/one', date: '2026-05-03', summary: 'alt-only', source_id: 'alt' },+ ];+ const first = await engine.addTimelineEntriesBatch(batch);+ const replay = await engine.addTimelineEntriesBatch(batch);+ const empty = await engine.addTimelineEntriesBatch([]);+ expect(first).toBe(4);+ expect(replay).toBe(0);+ const one = (await engine.getTimeline('batch/one', { sourceId: 'default' })).map((e) => pick(e, ENTRY_KEYS));+ const alt = (await engine.getTimeline('batch/one', { sourceId: 'alt' })).map((e) => e.summary);+ const two = (await engine.getTimeline('batch/two')).map((e) => e.summary);+ return { first, replay, empty, one, alt, two };+ },+ );+});++describe('engine parity: chronicle reads and event projection', () => {+ parityTest(+ 'upsertEventProjection updates in place on the same (event, date) and refuses missing pages',+ { methods: ['upsertEventProjection', 'getTimelineForDate', 'putPage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'alt');+ await putPlain(engine, 'life/diary/2026-06-01');+ await putEvent(engine, 'life/events/2026-06-01-standup', '2026-06-01T09:00:00Z', { kind: 'standup', who: ['people/alice'] });+ const base = { depthSlug: 'life/diary/2026-06-01', eventSlug: 'life/events/2026-06-01-standup', date: '2026-06-01' };+ const first = await engine.upsertEventProjection({ ...base, summary: 'Standup', detail: 'v1' });+ const again = await engine.upsertEventProjection({ ...base, summary: 'Standup (revised)', detail: 'v2' });+ const nextDay = await engine.upsertEventProjection({ ...base, date: '2026-06-02', summary: 'Standup follow-up' });+ const noDepth = await engine.upsertEventProjection({ ...base, depthSlug: 'life/diary/nope', summary: 'x' });+ const noEvent = await engine.upsertEventProjection({ ...base, eventSlug: 'life/events/nope', summary: 'x' });+ const wrongSource = await engine.upsertEventProjection({ ...base, summary: 'x', sourceId: 'alt' });+ expect([first, again, nextDay]).toEqual([{ projected: true }, { projected: true }, { projected: true }]);+ expect([noDepth, noEvent, wrongSource]).toEqual([{ projected: false }, { projected: false }, { projected: false }]);+ const day1 = chronicle(await engine.getTimelineForDate('2026-06-01'));+ const day2 = chronicle(await engine.getTimelineForDate('2026-06-02'));+ expect(day1).toHaveLength(1);+ return { first, again, nextDay, noDepth, noEvent, wrongSource, day1, day2 };+ },+ );++ parityTest(+ 'getTimelineForDate returns one day or its ISO week, ordered by event effective_date',+ { methods: ['getTimelineForDate', 'upsertEventProjection', 'putPage'] },+ async (engine) => {+ await seedChronicle(engine);+ const day = chronicle(await engine.getTimelineForDate('2026-06-18'));+ const week = chronicle(await engine.getTimelineForDate('2026-06-18', { week: true }));+ const limited = chronicle(await engine.getTimelineForDate('2026-06-18', { limit: 1 }));+ const empty = await engine.getTimelineForDate('2026-06-19');+ const otherSource = await engine.getTimelineForDate('2026-06-18', { sourceId: 'no-such-source' });+ expect(day.map((r) => r.event_slug)).toEqual(['life/events/2026-06-18-001', 'life/events/2026-06-18-002']);+ expect(week.map((r) => r.date)).toEqual(['2026-06-18', '2026-06-18', '2026-06-20']);+ expect(empty).toEqual([]);+ expect(otherSource).toEqual([]);+ return { day, week, limited, empty, otherSource };+ },+ );++ parityTest(+ 'getSince filters by lower-bound date and event kind',+ { methods: ['getSince', 'upsertEventProjection', 'putPage'] },+ async (engine) => {+ await seedChronicle(engine);+ const since19 = chronicle(await engine.getSince('2026-06-19'));+ const since18 = chronicle(await engine.getSince('2026-06-18'));+ const commitments = chronicle(await engine.getSince('2026-06-18', { kind: 'commitment' }));+ const meetings = chronicle(await engine.getSince('2026-06-01', { kind: 'meeting', limit: 1 }));+ const future = await engine.getSince('2030-01-01');+ expect(since19.map((r) => r.event_slug)).toEqual(['life/events/2026-06-20-001']);+ expect(commitments.map((r) => r.event_slug)).toEqual(['life/events/2026-06-18-002']);+ expect(future).toEqual([]);+ return { since19, since18, commitments, meetings, future };+ },+ );++ parityTest(+ 'getOnThisDay returns the same month-day from prior years only',+ { methods: ['getOnThisDay', 'addTimelineEntry', 'putPage'] },+ async (engine) => {+ await putPlain(engine, 'life/diary/history');+ for (const [date, summary] of [+ ['2024-06-18', 'two years ago'], ['2025-06-18', 'last year'], ['2026-06-18', 'this year'],+ ['2025-06-19', 'wrong day'], ['2023-06-18', 'three years ago'],+ ]) await engine.addTimelineEntry('life/diary/history', { date: date!, source: 'diary', summary: summary! });+ const rows = chronicle(await engine.getOnThisDay({ date: '2026-06-18' }));+ const limited = chronicle(await engine.getOnThisDay({ date: '2026-06-18', limit: 2 }));+ const otherSource = await engine.getOnThisDay({ date: '2026-06-18', sourceId: 'no-such-source' });+ const noMatch = await engine.getOnThisDay({ date: '2026-12-25' });+ expect(rows.map((r) => r.date)).not.toContain('2026-06-18');+ expect(rows.map((r) => r.date)).not.toContain('2025-06-19');+ expect(otherSource).toEqual([]);+ expect(noMatch).toEqual([]);+ return { rows, limited, otherSource, noMatch };+ },+ );++ parityTest(+ 'getLastSeen finds an entity via its own page or an event who, bounded by asof',+ { methods: ['getLastSeen', 'upsertEventProjection', 'addTimelineEntry', 'putPage'] },+ async (engine) => {+ await seedChronicle(engine);+ await putPlain(engine, 'people/own-page');+ await engine.addTimelineEntry('people/own-page', { date: '2026-06-10', summary: 'Own entry' });+ const viaEvent = await engine.getLastSeen('people/sarah-chen', { asof: '2026-06-25' });+ const viaOwn = await engine.getLastSeen('people/own-page', { asof: '2026-06-25' });+ const beforeLatest = await engine.getLastSeen('people/bob-jones', { asof: '2026-06-19' });+ const never = await engine.getLastSeen('people/nobody', { asof: '2026-06-25' });+ const otherSource = await engine.getLastSeen('people/sarah-chen', { asof: '2026-06-25', sourceId: 'no-such-source' });+ expect(viaEvent).toEqual({ entity_slug: 'people/sarah-chen', last_date: '2026-06-18', last_event_slug: 'life/events/2026-06-18-002', days_ago: 7 });+ expect(never.last_date).toBeNull();+ expect(never.days_ago).toBeNull();+ return { viaEvent, viaOwn, beforeLatest, never, otherSource };+ },+ );+});++describe('engine parity: ontology', () => {+ const SARAH = 'people/sarah-chen';+ const values = (rows: Awaited<ReturnType<BrainEngine['getOntology']>>) =>+ sorted(rows.map((r) => pick(r, ['dimension', 'value', 'confidence', 'source', 'valid_from', 'valid_to', 'status'])), (r) => r.dimension);+ const conflictView = (rows: OntologyConflict[]) =>+ rows.map((c) => ({ entity_slug: c.entity_slug, dimension: c.dimension, values: sorted(c.values.map((v) => `${v.value}|${v.source}|${v.confidence}`)) }));++ parityTest(+ 'mergeOntologyFact inserts, dedups, corroborates and forward-supersedes; getOntology reads asof',+ { methods: ['mergeOntologyFact', 'getOntology'] },+ async (engine) => {+ const inserted = await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'founder', source: 'meetings/a', validFrom: '2024-01-01', confidence: 0.8 });+ const noop = await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'founder', source: 'meetings/a', validFrom: '2024-01-01', confidence: 0.8 });+ const corroborated = await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'founder', source: 'meetings/b', validFrom: '2024-01-01' });+ const superseded = await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'advisor', source: 'meetings/c', validFrom: '2026-05-01' });+ const alias = await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'job_role', value: 'advisor', source: 'meetings/d', validFrom: '2026-05-01' });+ const actions = [inserted, noop, corroborated, superseded, alias].map((r) => ({ action: r.action, hasFact: r.factId !== null, hasSuperseded: r.supersededId !== null }));+ expect(actions.map((a) => a.action).slice(0, 4)).toEqual(['inserted', 'noop', 'corroborated', 'superseded_prior']);+ const now = values(await engine.getOntology(SARAH));+ const past = values(await engine.getOntology(SARAH, { asof: '2025-01-01' }));+ const beforeAll = values(await engine.getOntology(SARAH, { asof: '2020-01-01' }));+ const highConfidence = values(await engine.getOntology(SARAH, { minConfidence: 0.99 }));+ const unknown = await engine.getOntology('people/nobody');+ expect(now[0]).toMatchObject({ dimension: 'role', value: 'advisor' });+ expect(past[0]).toMatchObject({ dimension: 'role', value: 'founder' });+ expect(unknown).toEqual([]);+ return { actions, now, past, beforeAll, highConfidence, unknown };+ },+ );++ parityTest(+ 'novel dimensions quarantine; includeQuarantined and visibility filters change what getOntology returns',+ { methods: ['mergeOntologyFact', 'getOntology'] },+ async (engine) => {+ const vibe = await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'vibe', value: 'chaotic', source: 'meetings/a' });+ const explicit = await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'investor', source: 'meetings/a', status: 'quarantined' });+ await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'location', value: 'SF', source: 'meetings/b', visibility: 'private' });+ await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'employer', value: 'Acme', source: 'meetings/b', visibility: 'world' });+ const current = values(await engine.getOntology(SARAH));+ const withQuarantined = values(await engine.getOntology(SARAH, { includeQuarantined: true }));+ const worldOnly = values(await engine.getOntology(SARAH, { visibility: ['world'] }));+ const scoped = values(await engine.getOntology(SARAH, { sourceId: 'no-such-source' }));+ expect(current.map((r) => r.dimension)).not.toContain('vibe');+ expect(withQuarantined.find((r) => r.dimension === 'vibe')?.status).toBe('quarantined');+ return { vibe: vibe.action, explicit: explicit.action, current, withQuarantined, worldOnly, scoped };+ },+ );++ parityTest(+ 'findOntologyConflicts surfaces a backdated disagreement but not a forward supersession',+ { methods: ['findOntologyConflicts', 'mergeOntologyFact'] },+ async (engine) => {+ // Forward supersession: not a conflict.+ await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'founder', source: 'm/a', validFrom: '2024-01-01' });+ await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'advisor', source: 'm/b', validFrom: '2026-05-01' });+ // Backdated conflicting value: inserted without rewriting the prior, surfaces as a conflict.+ const bob = 'people/bob-jones';+ await engine.mergeOntologyFact({ entitySlug: bob, dimension: 'role', value: 'advisor', source: 'm/a', validFrom: '2026-05-01', confidence: 0.9 });+ const backdated = await engine.mergeOntologyFact({ entitySlug: bob, dimension: 'role', value: 'founder', source: 'm/b', validFrom: '2026-01-01', confidence: 0.6 });+ expect(backdated.action).toBe('inserted');+ const conflicts = conflictView(await engine.findOntologyConflicts());+ const confident = conflictView(await engine.findOntologyConflicts({ minConfidence: 0.8 }));+ const worldOnly = conflictView(await engine.findOntologyConflicts({ visibility: ['world'] }));+ const otherSource = conflictView(await engine.findOntologyConflicts({ sourceId: 'no-such-source' }));+ expect(conflicts.map((c) => c.entity_slug)).toEqual([bob]);+ expect(otherSource).toEqual([]);+ return { conflicts, confident, worldOnly, otherSource };+ },+ );++ parityTest(+ 'discoverOntologyDimensions rolls up entities and observations per dimension',+ { methods: ['discoverOntologyDimensions', 'mergeOntologyFact'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'alt');+ await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'founder', source: 'meetings/a' });+ await engine.mergeOntologyFact({ entitySlug: 'people/bob-jones', dimension: 'role', value: 'advisor', source: 'meetings/b' });+ await engine.mergeOntologyFact({ entitySlug: 'people/bob-jones', dimension: 'employer', value: 'Acme', source: 'meetings/b' });+ await engine.mergeOntologyFact({ entitySlug: SARAH, dimension: 'role', value: 'partner', source: 'meetings/z', sourceId: 'alt' });+ const view = (rows: Awaited<ReturnType<BrainEngine['discoverOntologyDimensions']>>) => sorted(rows, (r) => r.dimension);+ const all = view(await engine.discoverOntologyDimensions());+ const defaultOnly = view(await engine.discoverOntologyDimensions({ sourceId: 'default' }));+ const federated = view(await engine.discoverOntologyDimensions({ sourceIds: ['alt'] }));+ const missing = await engine.discoverOntologyDimensions({ sourceId: 'no-such-source' });+ expect(defaultOnly.find((d) => d.dimension === 'role')?.entities).toBe(2);+ expect(missing).toEqual([]);+ return { all, defaultOnly, federated, missing };+ },+ );+});diff --git a/test/engine-parity/versions-raw.test.ts b/test/engine-parity/versions-raw.test.tsnew file mode 100644index 0000000000..f5e6ea1b96--- /dev/null+++ b/test/engine-parity/versions-raw.test.ts@@ -0,0 +1,247 @@+/**+ * BrainEngine parity — versions + raw_files families.+ *+ * Authoring gate (docs/TESTING.md#authoring-gate):+ * - Contract: page version snapshots (create / list / revert), raw sidecar+ * data and file metadata rows behave identically on every engine arm+ * (PGLite always; Postgres with DATABASE_URL; a Rust arm later through+ * test/engine-parity/harness.ts).+ * - Regression: an engine that snapshots the wrong fields, orders history+ * differently, reverts the wrong source's row, or drifts on+ * (source, storage_path) upsert identity — page history, `gbrain+ * revert`, enrichment sidecars and image assets all read these.+ * - Why existing coverage misses it: test/e2e/engine-parity.test.ts skips+ * entirely without Postgres and has no versions/raw/files cases;+ * per-engine unit tests never compare two engines on one scenario.+ * - Seam: none. Real engines, typed methods only (no executeRaw: D18).+ * Version/file ids are sequence-generated, so observables map them to+ * body text or storage paths and never return the raw id.+ */+import { describe, expect } from 'bun:test';+import type { FileRow } from '../../src/core/engine.ts';+import { createSource, parityArms, pick, sorted } from './harness.ts';+import { testBackends } from '../helpers/test-backends.ts';++const { parityTest } = parityArms(testBackends());++// FileRow.size_bytes is a JS number on every engine (the files.size_bytes column is BIGINT; Postgres used to+// return it as a BigInt). It is part of the compared view, and `sizeOf` refuses any other type.+const FILE_KEYS = ['source_id', 'page_slug', 'filename', 'storage_path', 'mime_type', 'size_bytes', 'content_hash', 'metadata', 'created_at'] as const;+const fileView = (f: FileRow | null) => (f ? pick(f, FILE_KEYS) : null);+const sizeOf = (f: FileRow | null) => {+ if (f?.size_bytes == null) return null;+ expect(typeof f.size_bytes).toBe('number');+ return f.size_bytes;+};++describe('engine parity: versions', () => {+ parityTest(+ 'createVersion snapshots the current page; getVersions lists snapshots newest-first',+ { methods: ['putPage', 'createVersion', 'getVersions'] },+ async (engine) => {+ await engine.putPage('notes/ver-a', {+ type: 'note', title: 'Draft one', compiled_truth: 'Body v1.', timeline: '- 2026-01-01: started', frontmatter: { stage: 'draft' },+ });+ const v1 = await engine.createVersion('notes/ver-a');+ await engine.putPage('notes/ver-a', {+ type: 'note', title: 'Draft two', compiled_truth: 'Body v2.', timeline: '- 2026-01-01: started', frontmatter: { stage: 'final' },+ });+ const v2 = await engine.createVersion('notes/ver-a');+ expect(v1.compiled_truth).toBe('Body v1.');+ expect(v2.compiled_truth).toBe('Body v2.');+ expect(v2.id).not.toBe(v1.id);+ const list = await engine.getVersions('notes/ver-a');+ const body = list.map((v) => v.compiled_truth);+ // The two explicit snapshots are in the history, newest first.+ expect(body.indexOf('Body v2.')).toBeLessThan(body.indexOf('Body v1.'));+ const limited = await engine.getVersions('notes/ver-a', { limit: 1 });+ expect(limited).toHaveLength(1);+ const meta = await engine.getVersions('notes/ver-a', { includeBody: false });+ expect('compiled_truth' in meta[0]!).toBe(false);+ const view = (v: (typeof list)[number]) => ({ ...pick(v, ['title', 'type', 'compiled_truth', 'timeline', 'frontmatter', 'tags', 'snapshot_at'] as const) });+ return {+ created: [view(v1), view(v2)],+ list: list.map(view),+ limited: limited.map(view),+ metaTitles: meta.map((m) => m.title),+ };+ },+ );++ parityTest(+ 'createVersion on a missing page throws; getVersions of a missing page is empty',+ { methods: ['createVersion', 'getVersions'] },+ async (engine) => {+ let threw = false;+ try {+ await engine.createVersion('notes/no-such-page');+ } catch (error) {+ threw = true;+ expect(String((error as Error).message)).toContain('not found');+ }+ expect(threw).toBe(true);+ return { threw, versions: await engine.getVersions('notes/no-such-page') };+ },+ );++ parityTest(+ 'revertToVersion restores body and frontmatter from the snapshot',+ { methods: ['putPage', 'createVersion', 'revertToVersion', 'getPage'] },+ async (engine) => {+ await engine.putPage('notes/rev-a', {+ type: 'note', title: 'Revertable', compiled_truth: 'Original body.', timeline: '', frontmatter: { stage: 'one' },+ });+ const snap = await engine.createVersion('notes/rev-a');+ await engine.putPage('notes/rev-a', {+ type: 'note', title: 'Revertable', compiled_truth: 'Edited body.', timeline: '', frontmatter: { stage: 'two' },+ });+ const edited = await engine.getPage('notes/rev-a');+ expect(edited?.compiled_truth).toBe('Edited body.');+ await engine.revertToVersion('notes/rev-a', snap.id);+ const reverted = await engine.getPage('notes/rev-a');+ expect(reverted?.compiled_truth).toBe('Original body.');+ expect(reverted?.frontmatter.stage).toBe('one');+ return { edited: pick(edited!, ['compiled_truth', 'frontmatter'] as const), reverted: pick(reverted!, ['slug', 'title', 'compiled_truth', 'frontmatter'] as const) };+ },+ );++ parityTest(+ 'versions are source-scoped: a same-slug page in another source keeps its own history and revert target',+ { methods: ['putPage', 'createVersion', 'getVersions', 'revertToVersion', 'getPage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'ver-other');+ await engine.putPage('notes/shared', { type: 'note', title: 'Default', compiled_truth: 'Default v1.', timeline: '' });+ await engine.putPage('notes/shared', { type: 'note', title: 'Other', compiled_truth: 'Other v1.', timeline: '' }, { sourceId: 'ver-other' });+ await engine.createVersion('notes/shared', { sourceId: 'default' });+ const otherSnap = await engine.createVersion('notes/shared', { sourceId: 'ver-other' });+ await engine.putPage('notes/shared', { type: 'note', title: 'Default', compiled_truth: 'Default v2.', timeline: '' });+ await engine.putPage('notes/shared', { type: 'note', title: 'Other', compiled_truth: 'Other v2.', timeline: '' }, { sourceId: 'ver-other' });+ const defaultBodies = (await engine.getVersions('notes/shared', { sourceId: 'default' })).map((v) => v.compiled_truth);+ const otherBodies = (await engine.getVersions('notes/shared', { sourceId: 'ver-other' })).map((v) => v.compiled_truth);+ expect(defaultBodies).toContain('Default v1.');+ expect(defaultBodies).not.toContain('Other v1.');+ expect(otherBodies).toContain('Other v1.');+ expect(otherBodies).not.toContain('Default v1.');+ await engine.revertToVersion('notes/shared', otherSnap.id, { sourceId: 'ver-other' });+ const defaultPage = await engine.getPage('notes/shared', { sourceId: 'default' });+ const otherPage = await engine.getPage('notes/shared', { sourceId: 'ver-other' });+ expect(defaultPage?.compiled_truth).toBe('Default v2.');+ expect(otherPage?.compiled_truth).toBe('Other v1.');+ return {+ defaultBodies: sorted(defaultBodies),+ otherBodies: sorted(otherBodies),+ defaultPage: defaultPage?.compiled_truth,+ otherPage: otherPage?.compiled_truth,+ };+ },+ );+});++describe('engine parity: raw data + files', () => {+ parityTest(+ 'putRawData upserts per (page, source); getRawData filters by source',+ { methods: ['putPage', 'putRawData', 'getRawData'] },+ async (engine) => {+ await engine.putPage('people/raw-alice', { type: 'person', title: 'Alice', compiled_truth: 'Alice.', timeline: '' });+ await engine.putRawData('people/raw-alice', 'crustdata', { headline: 'CEO', followers: 10 });+ await engine.putRawData('people/raw-alice', 'linkedin', { title: 'Founder', skills: ['a', 'b'] });+ await engine.putRawData('people/raw-alice', 'crustdata', { headline: 'CEO at Acme', followers: 11 });+ const all = await engine.getRawData('people/raw-alice');+ const one = await engine.getRawData('people/raw-alice', 'crustdata');+ const none = await engine.getRawData('people/raw-alice', 'unknown-source');+ const noPage = await engine.getRawData('people/raw-nobody');+ expect(all).toHaveLength(2);+ expect(one).toHaveLength(1);+ expect(one[0]!.data).toEqual({ headline: 'CEO at Acme', followers: 11 });+ expect(none).toEqual([]);+ expect(noPage).toEqual([]);+ const view = (r: (typeof all)[number]) => pick(r, ['source', 'data', 'fetched_at'] as const);+ return { all: sorted(all.map(view), (r) => r.source), one: one.map(view), none, noPage };+ },+ );++ parityTest(+ 'raw data follows the page soft-delete; includeDeleted opts in; sources scope same-slug pages',+ { methods: ['putPage', 'putRawData', 'getRawData', 'softDeletePage', 'restorePage'] },+ async (engine, backend) => {+ await createSource(engine, backend, 'raw-other');+ await engine.putPage('notes/raw-shared', { type: 'note', title: 'D', compiled_truth: 'D.', timeline: '' });+ await engine.putPage('notes/raw-shared', { type: 'note', title: 'O', compiled_truth: 'O.', timeline: '' }, { sourceId: 'raw-other' });+ await engine.putRawData('notes/raw-shared', 'feed', { who: 'default' }, { sourceId: 'default' });+ await engine.putRawData('notes/raw-shared', 'feed', { who: 'other' }, { sourceId: 'raw-other' });+ const defaultRows = await engine.getRawData('notes/raw-shared', 'feed', { sourceId: 'default' });+ const otherRows = await engine.getRawData('notes/raw-shared', 'feed', { sourceId: 'raw-other' });+ await engine.softDeletePage('notes/raw-shared', { sourceId: 'default' });+ const hidden = await engine.getRawData('notes/raw-shared', 'feed', { sourceId: 'default' });+ const shown = await engine.getRawData('notes/raw-shared', 'feed', { sourceId: 'default', includeDeleted: true });+ const otherStill = await engine.getRawData('notes/raw-shared', 'feed', { sourceId: 'raw-other' });+ await engine.restorePage('notes/raw-shared', { sourceId: 'default' });+ const restored = await engine.getRawData('notes/raw-shared', 'feed', { sourceId: 'default' });+ expect(defaultRows.map((r) => r.data)).toEqual([{ who: 'default' }]);+ expect(otherRows.map((r) => r.data)).toEqual([{ who: 'other' }]);+ expect(hidden).toEqual([]);+ expect(shown.map((r) => r.data)).toEqual([{ who: 'default' }]);+ expect(restored.map((r) => r.data)).toEqual([{ who: 'default' }]);+ return {+ defaultRows: defaultRows.map((r) => r.data),+ otherRows: otherRows.map((r) => r.data),+ hidden: hidden.map((r) => r.data),+ shown: shown.map((r) => r.data),+ otherStill: otherStill.map((r) => r.data),+ restored: restored.map((r) => r.data),+ };+ },+ );++ parityTest(+ 'upsertFile creates then no-ops on same hash, updates in place on a new hash; getFile reads by identity',+ { methods: ['upsertFile', 'getFile'] },+ async (engine) => {+ const spec = {+ filename: 'photo.png', storage_path: 'assets/photo.png', mime_type: 'image/png', size_bytes: 1234,+ content_hash: 'hash-1', metadata: { width: 10, height: 20 },+ };+ const created = await engine.upsertFile(spec);+ const same = await engine.upsertFile(spec);+ const replaced = await engine.upsertFile({ ...spec, content_hash: 'hash-2', size_bytes: 4321, metadata: { width: 11, height: 21 } });+ const read = await engine.getFile('default', 'assets/photo.png');+ const missing = await engine.getFile('default', 'assets/missing.png');+ const wrongSource = await engine.getFile('other-source', 'assets/photo.png');+ expect(created.created).toBe(true);+ expect(same.created).toBe(false);+ expect(replaced.created).toBe(false);+ expect(same.id).toBe(created.id);+ expect(replaced.id).toBe(created.id);+ expect(read?.content_hash).toBe('hash-2');+ expect(Number(read?.size_bytes)).toBe(4321);+ return { created: created.created, same: same.created, replaced: replaced.created, read: fileView(read), size: sizeOf(read), missing, wrongSource };+ },+ );++ parityTest(+ 'listFilesForPage returns the files attached to that page only',+ { methods: ['putPage', 'upsertFile', 'listFilesForPage', 'getFile'] },+ async (engine) => {+ const alice = await engine.putPage('people/file-alice', { type: 'person', title: 'Alice', compiled_truth: 'A.', timeline: '' });+ const bob = await engine.putPage('people/file-bob', { type: 'person', title: 'Bob', compiled_truth: 'B.', timeline: '' });+ await engine.upsertFile({ page_slug: 'people/file-alice', page_id: alice.id, filename: 'b.png', storage_path: 'a/b.png', content_hash: 'h-b', mime_type: 'image/png', size_bytes: 2 });+ await engine.upsertFile({ page_slug: 'people/file-alice', page_id: alice.id, filename: 'a.png', storage_path: 'a/a.png', content_hash: 'h-a', mime_type: 'image/png', size_bytes: 1 });+ await engine.upsertFile({ page_slug: 'people/file-bob', page_id: bob.id, filename: 'c.png', storage_path: 'a/c.png', content_hash: 'h-c' });+ await engine.upsertFile({ filename: 'orphan.png', storage_path: 'a/orphan.png', content_hash: 'h-o' });+ const forAlice = await engine.listFilesForPage(alice.id);+ const forBob = await engine.listFilesForPage(bob.id);+ const orphan = await engine.getFile('default', 'a/orphan.png');+ expect(forAlice).toHaveLength(2);+ expect(forBob).toHaveLength(1);+ expect(orphan?.page_id).toBeNull();+ expect(forAlice.map(sizeOf).sort()).toEqual([1, 2]);+ return {+ alice: sorted(forAlice.map(fileView), (f) => f!.storage_path),+ aliceSizes: forAlice.map((f) => `${f.storage_path}:${sizeOf(f)}`).sort(),+ bob: forBob.map(fileView),+ orphan: fileView(orphan),+ empty: await engine.listFilesForPage(-1),+ };+ },+ );+});diff --git a/test/engine-surface-coverage.test.ts b/test/engine-surface-coverage.test.tsindex c0be8302cd..c8789082a9 100644--- a/test/engine-surface-coverage.test.ts+++ b/test/engine-surface-coverage.test.ts@@ -56,7 +56,7 @@ const INTERFACE_METHODS: readonly string[] = [// Search'searchKeyword', 'countKeywordPages', 'searchKeywordPages', 'searchTitles', 'searchVector', 'getEmbeddingsByChunkIds',// Chunks- 'upsertChunks', 'getChunks', 'getChunkPage', 'getChunkWindows', 'countStaleChunks', 'sumStaleChunkChars', 'setPageEmbeddingSignature',+ 'upsertChunks', 'sealChunks', 'getChunks', 'getChunkPage', 'getChunkWindows', 'countStaleChunks', 'sumStaleChunkChars', 'setPageEmbeddingSignature','invalidateStaleSignatureEmbeddings', 'invalidateContentDriftEmbeddings', 'listStaleChunks','countChunklessPagesWithContent', 'listChunklessPagesWithContent', 'readEmbeddingStateCounts', 'listEmbeddingStateRows', 'deleteChunks',// Extraction watermark@@ -163,10 +163,11 @@ const ENGINE_INTERNAL_HELPERS: readonly string[] = [* list in refactor wave 1 W0: the Postgres SQL-text goldens* (test/helpers/postgres-engine-sql-cases.ts) call them. Their PGLite* smokes stay below, unchanged, as ex-UNCALLED shape pins.+ * - rewriteLinks left the list when the BrainEngine parity suite+ * (test/engine-parity/sync-aliases.test.ts) began calling it on every+ * engine arm. Its PGLite smoke stays below as an ex-UNCALLED shape pin.*/-const UNCALLED: readonly string[] = [- 'rewriteLinks', // documented no-op stub; callers exist (migrate.ts, cycle/phantom-redirect.ts)-];+const UNCALLED: readonly string[] = [];function methodNames(): string[] {return Object.getOwnPropertyNames(PGLiteEngine.prototype).filter((n) => n !== 'constructor');@@ -303,10 +304,8 @@ const EX_UNCALLED_SHAPE_PINS: Record<string, () => Promise<void>> = {// Empty input short-circuits to an empty map.expect((await engine.getPageTimestamps([])).size).toBe(0);},-};--const SMOKES: Record<string, () => Promise<void>> = {rewriteLinks: async () => {+ // Ex-UNCALLED: test/engine-parity/sync-aliases.test.ts calls it on every arm.// Documented no-op stub on PGLite: links key on integer page_id FKs, so// they are already correct after updateSlug. Pin the no-op contract —// resolves undefined and leaves the link table untouched.@@ -319,6 +318,8 @@ const SMOKES: Record<string, () => Promise<void>> = {},};+const SMOKES: Record<string, () => Promise<void>> = {};+describe('uncovered-method smokes (seeded PGLite)', () => {beforeAll(async () => {configureGateway({diff --git a/test/fixtures/goldens/exports/runtime.json b/test/fixtures/goldens/exports/runtime.jsonindex 4509dfe652..799a1e72bd 100644--- a/test/fixtures/goldens/exports/runtime.json+++ b/test/fixtures/goldens/exports/runtime.json@@ -175,6 +175,7 @@"revertToVersion","rewriteLinks","runMigration",+ "sealChunks","searchKeyword","searchKeywordChunks","searchKeywordPages",@@ -395,6 +396,7 @@"runMigration","runUnsafe","runVectorAttempt",+ "sealChunks","searchKeyword","searchKeywordChunks","searchKeywordPages",diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.jsonindex 4bdd753ce3..4218c46567 100644--- a/test/fixtures/goldens/exports/types.json+++ b/test/fixtures/goldens/exports/types.json@@ -213,6 +213,7 @@"revertToVersion: (slug: string, versionId: number, opts?: { sourceId?: string; }) => Promise<void>","rewriteLinks: (oldSlug: string, newSlug: string) => Promise<void>","runMigration: (version: number, sql: string) => Promise<void>",+ "sealChunks: (slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; expectedRevision?: string; }) => Promise<void>","searchKeyword: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordChunks: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordPages: (query: string, opts: SearchOpts | undefined, page: KeywordPageWindow) => Promise<SearchResult[]>",@@ -1276,6 +1277,7 @@"revertToVersion: (slug: string, versionId: number, opts?: { sourceId?: string; }) => Promise<void>","rewriteLinks: (_oldSlug: string, _newSlug: string) => Promise<void>","runMigration: (_version: number, sqlStr: string) => Promise<void>",+ "sealChunks: (slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; expectedRevision?: string; }) => Promise<void>","searchKeyword: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordChunks: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordPages: (query: string, opts: SearchOpts | undefined, page: KeywordPageWindow) => Promise<SearchResult[]>",@@ -3789,6 +3791,7 @@"revertToVersion: (slug: string, versionId: number, opts?: { sourceId?: string; }) => Promise<void>","rewriteLinks: (oldSlug: string, newSlug: string) => Promise<void>","runMigration: (version: number, sql: string) => Promise<void>",+ "sealChunks: (slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; expectedRevision?: string; }) => Promise<void>","searchKeyword: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordChunks: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordPages: (query: string, opts: SearchOpts | undefined, page: KeywordPageWindow) => Promise<SearchResult[]>",@@ -7291,6 +7294,7 @@"revertToVersion: (slug: string, versionId: number, opts?: { sourceId?: string; }) => Promise<void>","rewriteLinks: (_oldSlug: string, _newSlug: string) => Promise<void>","runMigration: (_version: number, sql: string) => Promise<void>",+ "sealChunks: (slug: string, chunks: ChunkInput[], opts?: { sourceId?: string; expectedRevision?: string; }) => Promise<void>","searchKeyword: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordChunks: (query: string, opts?: SearchOpts) => Promise<SearchResult[]>","searchKeywordPages: (query: string, opts: SearchOpts | undefined, page: KeywordPageWindow) => Promise<SearchResult[]>",diff --git a/test/fixtures/goldens/postgres-engine-gauge/acquires-by-case.json b/test/fixtures/goldens/postgres-engine-gauge/acquires-by-case.jsonindex c2a2e27e10..37a4671e63 100644--- a/test/fixtures/goldens/postgres-engine-gauge/acquires-by-case.json+++ b/test/fixtures/goldens/postgres-engine-gauge/acquires-by-case.json@@ -351,6 +351,14 @@},"revertToVersion#default": {},"revertToVersion#sourceId": {},+ "sealChunks#default": {+ "raw": 5,+ "tx": 1+ },+ "sealChunks#expectedRevision": {+ "raw": 5,+ "tx": 1+ },"searchKeyword#cjk": {"raw": 2,"tx": 1diff --git a/test/fixtures/goldens/rls-scope-inventory.json b/test/fixtures/goldens/rls-scope-inventory.jsonindex bb89cec20a..8341dcfc82 100644--- a/test/fixtures/goldens/rls-scope-inventory.json+++ b/test/fixtures/goldens/rls-scope-inventory.json@@ -2945,6 +2945,34 @@],"flagOnScopes": []},+ "sealChunks#default": {+ "flagOffLanes": [+ "tx"+ ],+ "flagOffOpensTransaction": true,+ "flagOn": "scoped",+ "flagOnLanes": [+ "tx",+ "tx>sp"+ ],+ "flagOnScopes": [+ "default"+ ]+ },+ "sealChunks#expectedRevision": {+ "flagOffLanes": [+ "tx"+ ],+ "flagOffOpensTransaction": true,+ "flagOn": "scoped",+ "flagOnLanes": [+ "tx",+ "tx>sp"+ ],+ "flagOnScopes": [+ "src-a"+ ]+ },"searchKeyword#cjk": {"flagOffLanes": ["pool",@@ -3820,6 +3848,7 @@"runMigration": "none","runUnsafe": "none","runVectorAttempt": "direct",+ "sealChunks": "none","searchKeyword": "direct","searchKeywordChunks": "direct","searchKeywordPages": "direct",diff --git a/test/fixtures/goldens/sql-text/_classification.json b/test/fixtures/goldens/sql-text/_classification.jsonindex 64916b3a6f..ed648c3974 100644--- a/test/fixtures/goldens/sql-text/_classification.json+++ b/test/fixtures/goldens/sql-text/_classification.json@@ -1,7 +1,7 @@{"golden": {"counts": {- "chunks": 17,+ "chunks": 18,"cjk-search": 2,"code-edges": 5,"facts": 19,@@ -206,6 +206,7 @@"runMigration": "out-of-scope:lifecycle (connection, pool, transaction, raw seams)","runUnsafe": "out-of-scope:internal-helper (private; exercised through public callers)","runVectorAttempt": "out-of-scope:internal-helper (private; exercised through public callers)",+ "sealChunks": "chunks","searchKeyword": "cjk-search","searchKeywordChunks": "cjk-search","searchKeywordPages": "out-of-scope:search (FTS/vector hot paths, dialect-specific, not a W1 domain)",diff --git a/test/fixtures/goldens/sql-text/_driver.json b/test/fixtures/goldens/sql-text/_driver.jsonindex 253452addf..9e94ddb221 100644--- a/test/fixtures/goldens/sql-text/_driver.json+++ b/test/fixtures/goldens/sql-text/_driver.json@@ -841,6 +841,190 @@}]},+ "sealChunks": {+ "default": [+ {+ "paramCount": 1,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 3,+ "unsafeOptions": {+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 0,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 3,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 4,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 3,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ }+ ],+ "expectedRevision": [+ {+ "paramCount": 1,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 3,+ "unsafeOptions": {+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 2,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 3,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 4,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ },+ {+ "paramCount": 3,+ "unsafeOptions": {+ "cancelFence": false,+ "prepare": true,+ "simple": false+ },+ "via": "unsafe"+ }+ ]+ },"setPageEmbeddingSignature": {"default": [{diff --git a/test/fixtures/goldens/sql-text/chunks.json b/test/fixtures/goldens/sql-text/chunks.jsonindex bafe6ce433..250e8a1151 100644--- a/test/fixtures/goldens/sql-text/chunks.json+++ b/test/fixtures/goldens/sql-text/chunks.json@@ -792,6 +792,215 @@}]},+ "sealChunks": {+ "default": [+ {+ "event": "begin",+ "lane": "tx"+ },+ {+ "lane": "tx",+ "params": [+ "string"+ ],+ "sql": "SELECT incarnation FROM sources WHERE id=$1 FOR SHARE",+ "textSha256": "414efa2a18b3a4ac2f6f6675b6f7273b71c262a6bab8a44f82963606fed221d7"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "INSERT INTO page_write_guards(source_incarnation,slug) SELECT incarnation,$1 FROM sources WHERE id=$2 ON CONFLICT DO NOTHING",+ "textSha256": "91584b13aae786f054e246bcc667c9ebe8c065d61b42d5ae775634739bce9f54"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "SELECT g.slug FROM page_write_guards g JOIN sources s ON s.incarnation=g.source_incarnation WHERE s.id=$1 AND g.slug=$2 FOR UPDATE OF g",+ "textSha256": "becdf4418f95796c9bab86a61f0f6e9d42bba2f74baedfe40ba9d9705977d77a"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "SELECT id FROM pages WHERE source_id=$1 AND slug=$2 FOR UPDATE",+ "textSha256": "6c2eb61492fe7470a32169e89b9f04d471f3311d55ff790ad08f4736af483a2c"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string",+ "string",+ "string"+ ],+ "sql": "WITH chosen AS ( SELECT p.* FROM pages p WHERE p.slug=$1 AND p.source_id=$2 AND p.deleted_at IS NULL AND EXISTS (SELECT 1 FROM sources s WHERE s.id=p.source_id AND NOT s.archived) ORDER BY (p.slug=$3) DESC, (p.source_id=$4) DESC, p.source_id ASC LIMIT 1 ) SELECT p.*, (SELECT s.incarnation FROM sources s WHERE s.id=p.source_id) AS source_incarnation, COALESCE((SELECT jsonb_agg(t.tag ORDER BY t.tag) FROM tags t WHERE t.page_id=p.id), '[]'::jsonb) AS snapshot_tags, wd.snapshot_withdrawals, wd.snapshot_global_purges, CASE WHEN wd.snapshot_withdrawals <> '[]'::jsonb OR (wd.snapshot_global_purges->>'count')::int > 0 THEN (SELECT string_agg(regexp_replace(lower(line), '[[:space:]]+', ' ', 'g'), chr(10) ORDER BY ord) FROM unnest(string_to_array(p.compiled_truth,chr(10))) WITH ORDINALITY AS lines(line,ord)) END AS fingerprint_body, CASE WHEN wd.snapshot_withdrawals <> '[]'::jsonb OR (wd.snapshot_global_purges->>'count')::int > 0 THEN (SELECT string_agg(regexp_replace(lower(line), '[[:space:]]+', ' ', 'g'), chr(10) ORDER BY ord) FROM unnest(string_to_array(p.timeline,chr(10))) WITH ORDINALITY AS lines(line,ord)) END AS fingerprint_timeline FROM chosen p CROSS JOIN LATERAL (SELECT COALESCE((SELECT jsonb_agg(jsonb_build_object('visibility',w.visibility,'fact_hash',w.fact_hash,'withdrawn_at',w.withdrawn_at) ORDER BY w.visibility,w.fact_hash) FROM (SELECT visibility,fact_hash,min(withdrawn_at) AS withdrawn_at FROM fact_withdrawals WHERE source_id=p.source_id AND (subject='*' OR subject=p.slug) GROUP BY visibility,fact_hash) w), '[]'::jsonb) || COALESCE((SELECT jsonb_agg(jsonb_build_object('visibility',x.visibility,'fact_hash',x.fact_hash,'withdrawn_at',x.purged_at,'purged',true) ORDER BY x.visibility,x.fact_hash) FROM (SELECT visibility,fact_hash,min(purged_at) AS purged_at FROM fact_purges WHERE source_id=p.source_id AND subject=p.slug GROUP BY visibility,fact_hash) x), '[]'::jsonb) AS snapshot_withdrawals, (SELECT jsonb_build_object('count',count(*),'latest',max(g.purged_at)) FROM fact_purges g WHERE g.source_id=p.source_id AND g.subject='*' ) AS snapshot_global_purges) wd",+ "textSha256": "51974c9b58998a0c2601892313e337c96b72c1ffdff0dc8697a98fa91c175192"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "WITH page AS (SELECT id FROM pages WHERE slug = $1 AND source_id = $2 FOR UPDATE), gone AS ( DELETE FROM content_chunks WHERE page_id = (SELECT id FROM page) RETURNING page_id ) UPDATE pages SET text_projection_revision = NULL WHERE id = (SELECT page_id FROM gone LIMIT 1) AND text_projection_revision IS NOT NULL",+ "textSha256": "a3c4aafe1c57c1d8c273b7d8b5223e856ecf6f1523684268b1e9050959a51f15"+ },+ {+ "lane": "tx",+ "params": [],+ "sql": "SELECT key, value FROM config WHERE key IN ('search_embedding_column', 'embedding_columns', 'embedding_model')",+ "textSha256": "52b14422ab398f9e070b5981b6726357ba3dff2ad574a15e7b5b7a2679c6d582"+ },+ {+ "lane": "tx",+ "params": [+ "number",+ "string",+ "string"+ ],+ "sql": "UPDATE pages SET chunker_version = $1 WHERE slug = $2 AND source_id = $3 RETURNING id",+ "textSha256": "d0c507d848da5b877f3ef1a3220a37b63b16e555679023932675f7bdf49655b0"+ },+ {+ "lane": "tx",+ "params": [+ "number",+ "string"+ ],+ "sql": "INSERT INTO content_chunks (page_id, chunk_index, chunk_text, chunk_source, \"embedding\", model, token_count, embedded_at, embedded_text_hash, embedding_input_hash, language, symbol_name, symbol_type, start_line, end_line, parent_symbol_path, doc_comment, symbol_name_qualified, modality, embedding_image, embedding_pending_since, projected_byte_start, projected_byte_end) SELECT $1::int, c.chunk_index, c.chunk_text, c.chunk_source, c.embedding::vector, c.model, c.token_count, CASE WHEN c.embedding IS NULL THEN NULL ELSE now() END, CASE WHEN c.embedding IS NULL THEN NULL ELSE md5(c.chunk_text) END, c.embedding_input_hash, c.language, c.symbol_name, c.symbol_type, c.start_line, c.end_line, c.parent_symbol_path, c.doc_comment, c.symbol_name_qualified, c.modality, c.embedding_image::vector, CASE WHEN c.embedding IS NULL THEN now() ELSE NULL END, c.projected_byte_start, c.projected_byte_end FROM jsonb_to_recordset($2::text::jsonb) AS c(chunk_index int, chunk_text text, chunk_source text, embedding text, model text, token_count int, embedding_input_hash text, language text, symbol_name text, symbol_type text, start_line int, end_line int, parent_symbol_path text[], doc_comment text, symbol_name_qualified text, modality text, embedding_image text, projected_byte_start bigint, projected_byte_end bigint) ON CONFLICT (page_id, chunk_index) DO UPDATE SET chunk_text = EXCLUDED.chunk_text, chunk_source = EXCLUDED.chunk_source, \"embedding\" = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.\"embedding\" WHEN content_chunks.\"embedding\" IS NULL THEN EXCLUDED.\"embedding\" WHEN EXCLUDED.embedded_at IS NOT NULL AND (content_chunks.embedded_at IS NULL OR EXCLUDED.embedded_at > content_chunks.embedded_at) THEN EXCLUDED.\"embedding\" ELSE content_chunks.\"embedding\" END, model = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.model WHEN content_chunks.\"embedding\" IS NULL THEN EXCLUDED.model WHEN EXCLUDED.embedded_at IS NOT NULL AND (content_chunks.embedded_at IS NULL OR EXCLUDED.embedded_at > content_chunks.embedded_at) THEN EXCLUDED.model ELSE content_chunks.model END, token_count = EXCLUDED.token_count, embedded_at = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text AND EXCLUDED.\"embedding\" IS NULL THEN NULL WHEN content_chunks.\"embedding\" IS NULL AND EXCLUDED.\"embedding\" IS NOT NULL THEN EXCLUDED.embedded_at WHEN EXCLUDED.embedded_at IS NOT NULL AND (content_chunks.embedded_at IS NULL OR EXCLUDED.embedded_at > content_chunks.embedded_at) THEN EXCLUDED.embedded_at ELSE content_chunks.embedded_at END, embedded_text_hash = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.embedded_text_hash WHEN content_chunks.\"embedding\" IS NULL THEN EXCLUDED.embedded_text_hash WHEN EXCLUDED.embedded_at IS NOT NULL AND (content_chunks.embedded_at IS NULL OR EXCLUDED.embedded_at > content_chunks.embedded_at) THEN EXCLUDED.embedded_text_hash ELSE content_chunks.embedded_text_hash END, embedding_input_hash = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.embedding_input_hash WHEN content_chunks.\"embedding\" IS NULL THEN EXCLUDED.embedding_input_hash WHEN EXCLUDED.embedded_at IS NOT NULL AND (content_chunks.embedded_at IS NULL OR EXCLUDED.embedded_at > content_chunks.embedded_at) THEN EXCLUDED.embedding_input_hash ELSE content_chunks.embedding_input_hash END, language = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.language ELSE COALESCE(EXCLUDED.language, content_chunks.language) END, symbol_name = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_name ELSE COALESCE(EXCLUDED.symbol_name, content_chunks.symbol_name) END, symbol_type = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_type ELSE COALESCE(EXCLUDED.symbol_type, content_chunks.symbol_type) END, start_line = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.start_line ELSE COALESCE(EXCLUDED.start_line, content_chunks.start_line) END, end_line = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.end_line ELSE COALESCE(EXCLUDED.end_line, content_chunks.end_line) END, parent_symbol_path = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.parent_symbol_path ELSE COALESCE(EXCLUDED.parent_symbol_path, content_chunks.parent_symbol_path) END, doc_comment = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.doc_comment ELSE COALESCE(EXCLUDED.doc_comment, content_chunks.doc_comment) END, symbol_name_qualified = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.symbol_name_qualified ELSE COALESCE(EXCLUDED.symbol_name_qualified, content_chunks.symbol_name_qualified) END, modality = EXCLUDED.modality, projected_byte_start = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.projected_byte_start ELSE COALESCE(EXCLUDED.projected_byte_start, content_chunks.projected_byte_start) END, projected_byte_end = CASE WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN EXCLUDED.projected_byte_end ELSE COALESCE(EXCLUDED.projected_byte_end, content_chunks.projected_byte_end) END, embedding_image = COALESCE(EXCLUDED.embedding_image, content_chunks.embedding_image), embedding_pending_since = CASE WHEN EXCLUDED.\"embedding\" IS NOT NULL THEN NULL WHEN content_chunks.\"embedding\" IS NULL THEN COALESCE(content_chunks.embedding_pending_since, now()) WHEN EXCLUDED.chunk_text != content_chunks.chunk_text THEN now() ELSE content_chunks.embedding_pending_since END",+ "textSha256": "93b71e8498c895b12be40e3501b5018c799d0f6f2f140df96ce8cc269e47c62b"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string",+ "string",+ "string"+ ],+ "sql": "UPDATE pages SET text_projection_revision=knowledge_revision, search_vector=setweight(to_tsvector('english',gbrain_fts_input(COALESCE(title,''))),'A') || setweight(to_tsvector('english',gbrain_fts_input(left($1::text,65536))),'C') WHERE source_id=$2 AND slug=$3 AND knowledge_revision=$4::uuid",+ "textSha256": "807734544a900996576755062b917d5952531fea05b94cc68cfc73675c03ed7e"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string",+ "string"+ ],+ "sql": "DELETE FROM page_projection_jobs WHERE source_incarnation = $1::uuid AND slug = $2 AND revision = $3::uuid",+ "textSha256": "ba1c792d1a39cdce65c8fb05a1c034ef7ea72031895b62eed2c03ea8a7eb0d28"+ },+ {+ "event": "commit",+ "lane": "tx"+ }+ ],+ "expectedRevision": [+ {+ "event": "begin",+ "lane": "tx"+ },+ {+ "lane": "tx",+ "params": [+ "string"+ ],+ "sql": "SELECT incarnation FROM sources WHERE id=$1 FOR SHARE",+ "textSha256": "414efa2a18b3a4ac2f6f6675b6f7273b71c262a6bab8a44f82963606fed221d7"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "INSERT INTO page_write_guards(source_incarnation,slug) SELECT incarnation,$1 FROM sources WHERE id=$2 ON CONFLICT DO NOTHING",+ "textSha256": "91584b13aae786f054e246bcc667c9ebe8c065d61b42d5ae775634739bce9f54"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "SELECT g.slug FROM page_write_guards g JOIN sources s ON s.incarnation=g.source_incarnation WHERE s.id=$1 AND g.slug=$2 FOR UPDATE OF g",+ "textSha256": "becdf4418f95796c9bab86a61f0f6e9d42bba2f74baedfe40ba9d9705977d77a"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "SELECT id FROM pages WHERE source_id=$1 AND slug=$2 FOR UPDATE",+ "textSha256": "6c2eb61492fe7470a32169e89b9f04d471f3311d55ff790ad08f4736af483a2c"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string",+ "string",+ "string"+ ],+ "sql": "WITH chosen AS ( SELECT p.* FROM pages p WHERE p.slug=$1 AND p.source_id=$2 AND p.deleted_at IS NULL AND EXISTS (SELECT 1 FROM sources s WHERE s.id=p.source_id AND NOT s.archived) ORDER BY (p.slug=$3) DESC, (p.source_id=$4) DESC, p.source_id ASC LIMIT 1 ) SELECT p.*, (SELECT s.incarnation FROM sources s WHERE s.id=p.source_id) AS source_incarnation, COALESCE((SELECT jsonb_agg(t.tag ORDER BY t.tag) FROM tags t WHERE t.page_id=p.id), '[]'::jsonb) AS snapshot_tags, wd.snapshot_withdrawals, wd.snapshot_global_purges, CASE WHEN wd.snapshot_withdrawals <> '[]'::jsonb OR (wd.snapshot_global_purges->>'count')::int > 0 THEN (SELECT string_agg(regexp_replace(lower(line), '[[:space:]]+', ' ', 'g'), chr(10) ORDER BY ord) FROM unnest(string_to_array(p.compiled_truth,chr(10))) WITH ORDINALITY AS lines(line,ord)) END AS fingerprint_body, CASE WHEN wd.snapshot_withdrawals <> '[]'::jsonb OR (wd.snapshot_global_purges->>'count')::int > 0 THEN (SELECT string_agg(regexp_replace(lower(line), '[[:space:]]+', ' ', 'g'), chr(10) ORDER BY ord) FROM unnest(string_to_array(p.timeline,chr(10))) WITH ORDINALITY AS lines(line,ord)) END AS fingerprint_timeline FROM chosen p CROSS JOIN LATERAL (SELECT COALESCE((SELECT jsonb_agg(jsonb_build_object('visibility',w.visibility,'fact_hash',w.fact_hash,'withdrawn_at',w.withdrawn_at) ORDER BY w.visibility,w.fact_hash) FROM (SELECT visibility,fact_hash,min(withdrawn_at) AS withdrawn_at FROM fact_withdrawals WHERE source_id=p.source_id AND (subject='*' OR subject=p.slug) GROUP BY visibility,fact_hash) w), '[]'::jsonb) || COALESCE((SELECT jsonb_agg(jsonb_build_object('visibility',x.visibility,'fact_hash',x.fact_hash,'withdrawn_at',x.purged_at,'purged',true) ORDER BY x.visibility,x.fact_hash) FROM (SELECT visibility,fact_hash,min(purged_at) AS purged_at FROM fact_purges WHERE source_id=p.source_id AND subject=p.slug GROUP BY visibility,fact_hash) x), '[]'::jsonb) AS snapshot_withdrawals, (SELECT jsonb_build_object('count',count(*),'latest',max(g.purged_at)) FROM fact_purges g WHERE g.source_id=p.source_id AND g.subject='*' ) AS snapshot_global_purges) wd",+ "textSha256": "51974c9b58998a0c2601892313e337c96b72c1ffdff0dc8697a98fa91c175192"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string"+ ],+ "sql": "WITH page AS (SELECT id FROM pages WHERE slug = $1 AND source_id = $2 FOR UPDATE), gone AS ( DELETE FROM content_chunks WHERE page_id = (SELECT id FROM page) RETURNING page_id ) UPDATE pages SET text_projection_revision = NULL WHERE id = (SELECT page_id FROM gone LIMIT 1) AND text_projection_revision IS NOT NULL",+ "textSha256": "a3c4aafe1c57c1d8c273b7d8b5223e856ecf6f1523684268b1e9050959a51f15"+ },+ {+ "lane": "tx",+ "params": [+ "number",+ "string",+ "string"+ ],+ "sql": "UPDATE pages SET chunker_version = $1 WHERE slug = $2 AND source_id = $3 RETURNING id",+ "textSha256": "d0c507d848da5b877f3ef1a3220a37b63b16e555679023932675f7bdf49655b0"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string",+ "string",+ "string"+ ],+ "sql": "UPDATE pages SET text_projection_revision=knowledge_revision, search_vector=setweight(to_tsvector('english',gbrain_fts_input(COALESCE(title,''))),'A') || setweight(to_tsvector('english',gbrain_fts_input(left($1::text,65536))),'C') WHERE source_id=$2 AND slug=$3 AND knowledge_revision=$4::uuid",+ "textSha256": "807734544a900996576755062b917d5952531fea05b94cc68cfc73675c03ed7e"+ },+ {+ "lane": "tx",+ "params": [+ "string",+ "string",+ "string"+ ],+ "sql": "DELETE FROM page_projection_jobs WHERE source_incarnation = $1::uuid AND slug = $2 AND revision = $3::uuid",+ "textSha256": "ba1c792d1a39cdce65c8fb05a1c034ef7ea72031895b62eed2c03ea8a7eb0d28"+ },+ {+ "event": "commit",+ "lane": "tx"+ }+ ]+ },"setPageEmbeddingSignature": {"default": [{diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/scripts/engine-kind-branches-baseline.tsv b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/scripts/engine-kind-branches-baseline.tsvnew file mode 100644index 0000000000..bca3001ecb--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/scripts/engine-kind-branches-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts kind_compare 1diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/a.ts b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/a.tsnew file mode 100644index 0000000000..681b2f517d--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/a.ts@@ -0,0 +1 @@+export function pick(engine: { kind: string }) { return engine.kind === 'pglite' ? 1 : 2; }diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/b.ts b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/b.tsnew file mode 100644index 0000000000..63f30e4765--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/b.ts@@ -0,0 +1 @@+export function sw(engine: { kind: string }) { switch (engine.kind) { case 'postgres': return 1; default: return 0; } }diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/pglite-engine.ts b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/pglite-engine.tsnew file mode 100644index 0000000000..bf6269a6f8--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad-new/src/core/pglite-engine.ts@@ -0,0 +1 @@+export const self = (e: { kind: string }) => e.kind === 'pglite';diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/scripts/engine-kind-branches-baseline.tsv b/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/scripts/engine-kind-branches-baseline.tsvnew file mode 100644index 0000000000..baaa8ae44c--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/scripts/engine-kind-branches-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts kind_compare 2diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/src/core/a.ts b/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/src/core/a.tsnew file mode 100644index 0000000000..681b2f517d--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/src/core/a.ts@@ -0,0 +1 @@+export function pick(engine: { kind: string }) { return engine.kind === 'pglite' ? 1 : 2; }diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/src/core/pglite-engine.ts b/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/src/core/pglite-engine.tsnew file mode 100644index 0000000000..bf6269a6f8--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad-stale/src/core/pglite-engine.ts@@ -0,0 +1 @@+export const self = (e: { kind: string }) => e.kind === 'pglite';diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad/scripts/engine-kind-branches-baseline.tsv b/test/fixtures/guards/check-engine-kind-branches.ts/bad/scripts/engine-kind-branches-baseline.tsvnew file mode 100644index 0000000000..bca3001ecb--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad/scripts/engine-kind-branches-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts kind_compare 1diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad/src/core/a.ts b/test/fixtures/guards/check-engine-kind-branches.ts/bad/src/core/a.tsnew file mode 100644index 0000000000..a7394e693a--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad/src/core/a.ts@@ -0,0 +1,2 @@+export function pick(engine: { kind: string }) { return engine.kind === 'pglite' ? 1 : 2; }+export function other(cfg: { engine: string }) { return cfg.engine !== 'postgres'; }diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/bad/src/core/pglite-engine.ts b/test/fixtures/guards/check-engine-kind-branches.ts/bad/src/core/pglite-engine.tsnew file mode 100644index 0000000000..bf6269a6f8--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/bad/src/core/pglite-engine.ts@@ -0,0 +1 @@+export const self = (e: { kind: string }) => e.kind === 'pglite';diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/good/scripts/engine-kind-branches-baseline.tsv b/test/fixtures/guards/check-engine-kind-branches.ts/good/scripts/engine-kind-branches-baseline.tsvnew file mode 100644index 0000000000..bca3001ecb--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/good/scripts/engine-kind-branches-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts kind_compare 1diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/a.ts b/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/a.tsnew file mode 100644index 0000000000..681b2f517d--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/a.ts@@ -0,0 +1 @@+export function pick(engine: { kind: string }) { return engine.kind === 'pglite' ? 1 : 2; }diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/exhaustive.ts b/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/exhaustive.tsnew file mode 100644index 0000000000..4def35b0c0--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/exhaustive.ts@@ -0,0 +1,7 @@+export function pick(engine: { kind: 'pglite' | 'postgres' }) {+ switch (engine.kind) {+ case 'pglite': return 1;+ case 'postgres': return 2;+ default: { const unreachable: never = engine.kind; throw new Error(String(unreachable)); }+ }+}diff --git a/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/pglite-engine.ts b/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/pglite-engine.tsnew file mode 100644index 0000000000..bf6269a6f8--- /dev/null+++ b/test/fixtures/guards/check-engine-kind-branches.ts/good/src/core/pglite-engine.ts@@ -0,0 +1 @@+export const self = (e: { kind: string }) => e.kind === 'pglite';diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/scripts/engine-raw-sql-baseline.tsv b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/scripts/engine-raw-sql-baseline.tsvnew file mode 100644index 0000000000..5af5ebba9f--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/scripts/engine-raw-sql-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts execute_raw 1diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/a.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/a.tsnew file mode 100644index 0000000000..dee47e83e9--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/a.ts@@ -0,0 +1,4 @@+export async function read(engine: { executeRaw(q: string): Promise<unknown[]> }) {+ // engine.executeRaw('SELECT 1') in a comment never counts+ return engine.executeRaw('SELECT id FROM pages WHERE slug = $1');+}diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/b.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/b.tsnew file mode 100644index 0000000000..0c6e9436df--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/b.ts@@ -0,0 +1,2 @@+declare const sql: (s: TemplateStringsArray, ...v: unknown[]) => unknown;+export const rows = (slug: string) => sql`SELECT id FROM pages WHERE slug = ${slug}`;diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/c.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/c.tsnew file mode 100644index 0000000000..11d40c0478--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/c.ts@@ -0,0 +1,2 @@+declare const e: Record<string, (q: string) => unknown>;+export const r = () => e['executeRaw']('SELECT id FROM pages');diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/engine-sql/pages.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/engine-sql/pages.tsnew file mode 100644index 0000000000..b8c40e5395--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-new/src/core/engine-sql/pages.ts@@ -0,0 +1 @@+export const q = (e: { executeRaw(q: string): unknown }) => e.executeRaw('SELECT id FROM pages');diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/scripts/engine-raw-sql-baseline.tsv b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/scripts/engine-raw-sql-baseline.tsvnew file mode 100644index 0000000000..044a112a4e--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/scripts/engine-raw-sql-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts execute_raw 2diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/src/core/a.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/src/core/a.tsnew file mode 100644index 0000000000..dee47e83e9--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/src/core/a.ts@@ -0,0 +1,4 @@+export async function read(engine: { executeRaw(q: string): Promise<unknown[]> }) {+ // engine.executeRaw('SELECT 1') in a comment never counts+ return engine.executeRaw('SELECT id FROM pages WHERE slug = $1');+}diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/src/core/engine-sql/pages.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/src/core/engine-sql/pages.tsnew file mode 100644index 0000000000..b8c40e5395--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad-stale/src/core/engine-sql/pages.ts@@ -0,0 +1 @@+export const q = (e: { executeRaw(q: string): unknown }) => e.executeRaw('SELECT id FROM pages');diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/scripts/engine-raw-sql-baseline.tsv b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/scripts/engine-raw-sql-baseline.tsvnew file mode 100644index 0000000000..5af5ebba9f--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/scripts/engine-raw-sql-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts execute_raw 1diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/src/core/a.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/src/core/a.tsnew file mode 100644index 0000000000..ce080f8197--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/src/core/a.ts@@ -0,0 +1,5 @@+export async function read(engine: { executeRaw(q: string): Promise<unknown[]> }) {+ // engine.executeRaw('SELECT 1') in a comment never counts+ return engine.executeRaw('SELECT id FROM pages WHERE slug = $1');+}+export async function more(engine: { executeRaw(q: string): Promise<unknown[]> }) { return engine.executeRaw('DELETE FROM pages WHERE id = $1'); }diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/src/core/engine-sql/pages.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/src/core/engine-sql/pages.tsnew file mode 100644index 0000000000..b8c40e5395--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/bad/src/core/engine-sql/pages.ts@@ -0,0 +1 @@+export const q = (e: { executeRaw(q: string): unknown }) => e.executeRaw('SELECT id FROM pages');diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/scripts/engine-raw-sql-baseline.tsv b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/scripts/engine-raw-sql-baseline.tsvnew file mode 100644index 0000000000..5af5ebba9f--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/scripts/engine-raw-sql-baseline.tsv@@ -0,0 +1,2 @@+# fixture baseline+src/core/a.ts execute_raw 1diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/src/core/a.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/src/core/a.tsnew file mode 100644index 0000000000..dee47e83e9--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/src/core/a.ts@@ -0,0 +1,4 @@+export async function read(engine: { executeRaw(q: string): Promise<unknown[]> }) {+ // engine.executeRaw('SELECT 1') in a comment never counts+ return engine.executeRaw('SELECT id FROM pages WHERE slug = $1');+}diff --git a/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/src/core/engine-sql/pages.ts b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/src/core/engine-sql/pages.tsnew file mode 100644index 0000000000..b8c40e5395--- /dev/null+++ b/test/fixtures/guards/check-engine-raw-sql-ratchet.ts/good/src/core/engine-sql/pages.ts@@ -0,0 +1 @@+export const q = (e: { executeRaw(q: string): unknown }) => e.executeRaw('SELECT id FROM pages');diff --git a/test/helpers/postgres-engine-sql-cases.ts b/test/helpers/postgres-engine-sql-cases.tsindex 951eb2f53b..b1498f9662 100644--- a/test/helpers/postgres-engine-sql-cases.ts+++ b/test/helpers/postgres-engine-sql-cases.ts@@ -114,7 +114,7 @@ export const DOMAIN_OF: Record<string, string> = {// files'upsertFile': 'files', 'getFile': 'files', 'listFilesForPage': 'files',// chunks- 'upsertChunks': 'chunks', 'getChunks': 'chunks', 'getChunkPage': 'chunks', 'getChunkWindows': 'chunks', 'countStaleChunks': 'chunks', 'sumStaleChunkChars': 'chunks',+ 'upsertChunks': 'chunks', 'sealChunks': 'chunks', 'getChunks': 'chunks', 'getChunkPage': 'chunks', 'getChunkWindows': 'chunks', 'countStaleChunks': 'chunks', 'sumStaleChunkChars': 'chunks','setPageEmbeddingSignature': 'chunks', 'invalidateStaleSignatureEmbeddings': 'chunks','invalidateContentDriftEmbeddings': 'chunks', 'listStaleChunks': 'chunks','countChunklessPagesWithContent': 'chunks', 'listChunklessPagesWithContent': 'chunks', 'deleteChunks': 'chunks',@@ -272,6 +272,8 @@ const EMB = new Float32Array([0.1, 0.2, 0.3]);const page = { type: 'person', title: 'Alice Example', compiled_truth: 'Alice Example body.', timeline: '', frontmatter: { tags: [] } };const pageRet: Rule = [/^\s*INSERT INTO pages \(source_id, slug/, [PAGE_ROW]];const pageId: Rule = [/SELECT id FROM pages/i, [{ id: 1 }]];+/** The sealing chunk insert stamps the page's chunker version and needs the page row back. */+const sealedPage: Rule = [/UPDATE pages SET chunker_version/, [{ id: 1 }]];function variants(method: string, list: Array<[string, (e: any) => Promise<unknown>, Rule[]?]>): SqlCase[] {return list.map(([variant, run, rows]) => ({ method, variant, run, rows }));@@ -542,6 +544,10 @@ export const SQL_CASES: SqlCase[] = [['expectedRevision', (e) => e.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'x', chunk_source: 'compiled_truth' }], { sourceId: SRC, expectedRevision: REVISION }), [pageId]],['embeddingColumn', (e) => e.upsertChunks(SLUG, [{ chunk_index: 0, chunk_text: 'x', chunk_source: 'compiled_truth', embedding: EMB }], { embeddingColumn: { name: 'embedding_voyage', dimensions: 3, embeddingModel: 'voyage-test', vectorType: 'halfvec' } }), [pageId]],]),+ ...variants('sealChunks', [+ ['default', (e) => e.sealChunks(SLUG, [{ chunk_index: 0, chunk_text: 'Alice Example body.', chunk_source: 'compiled_truth' }]), [pageId, sealedPage]],+ ['expectedRevision', (e) => e.sealChunks(SLUG, [], { sourceId: SRC, expectedRevision: REVISION }), [pageId, sealedPage]],+ ]),...variants('getChunks', [['default', (e) => e.getChunks(SLUG)],['sourceIds', (e) => e.getChunks(SLUG, { sourceIds: SRCS })],diff --git a/test/postgres-rls-scope-inventory.test.ts b/test/postgres-rls-scope-inventory.test.tsindex b9937e5f15..b978ae4da2 100644--- a/test/postgres-rls-scope-inventory.test.ts+++ b/test/postgres-rls-scope-inventory.test.ts@@ -154,6 +154,7 @@ const SCOPED_THROUGH_NON_THIS_CALLEE: Record<string, string> = {updateSlug: 'engine-sql/pages.ts updateSlug versions the page first through tx.readPageSnapshot (belief ledger W2 rename preimage)',replaceDerivedLinks: 'derived-links.ts replaceDerivedLinks reads the origin via readPageSnapshot',replaceDerivedLinksBatch: 'derived-links.ts replaceDerivedLinksBatch reads the origins via tx.readPageSnapshotsBatch',+ sealChunks: 'engine-sql/chunks.ts sealChunks reads the page through tx.readPageSnapshot on the transaction clone',};const INVENTORY_NORMALIZER = defineNormalizer<{ ast: Record<string, AstMember>; runtime: Record<string, RuntimeObservation> }>(diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txtindex 88f73bc48f..ce1babfe9f 100644--- a/test/postgres-unit-arms.txt+++ b/test/postgres-unit-arms.txt@@ -121,6 +121,21 @@ test/embedding-completion-atomic.serial.test.tstest/enforced-member-writes-setting.serial.test.tstest/enforced-member-writes.serial.test.tstest/enforced-member.serial.test.ts+test/engine-parity/chunks.test.ts+test/engine-parity/code-eval-salience.test.ts+test/engine-parity/config-ingest.test.ts+test/engine-parity/extraction.test.ts+test/engine-parity/facts.test.ts+test/engine-parity/lifecycle.test.ts+test/engine-parity/links.test.ts+test/engine-parity/pages.test.ts+test/engine-parity/raw-sql.test.ts+test/engine-parity/search.test.ts+test/engine-parity/segmented-body.test.ts+test/engine-parity/sync-aliases.test.ts+test/engine-parity/takes.test.ts+test/engine-parity/timeline.test.ts+test/engine-parity/versions-raw.test.tstest/engine-sql-facts-keyset.test.tstest/extract-all-stamp-intersection.serial.test.tstest/extract-atoms-concurrent-run-7923.test.tsdiff --git a/test/scripts/engine-raw-sql-ratchet.test.ts b/test/scripts/engine-raw-sql-ratchet.test.tsnew file mode 100644index 0000000000..f56aa0b3da--- /dev/null+++ b/test/scripts/engine-raw-sql-ratchet.test.ts@@ -0,0 +1,331 @@+/**+ * D6 (docs/designs/RUST_ENGINE.md): scripts/check-engine-raw-sql-ratchet.ts+ * counts raw SQL per file under src/ outside the engines and fails when a+ * count rises above its baseline row, when a file has no row, or when a count+ * falls without its row falling too. The engine-kind branch ratchet shares the+ * same runner (scripts/lib/count-ratchet.ts) and is covered here too.+ */+import { afterEach, describe, expect, test } from 'bun:test';+import { spawnSync } from 'node:child_process';+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join, resolve } from 'node:path';+import { countFile, isEngineFile } from '../../scripts/check-engine-raw-sql-ratchet.ts';+import { countFile as countKinds } from '../../scripts/check-engine-kind-branches.ts';++const REPO = resolve(import.meta.dir, '..', '..');+const RAW = { guard: join(REPO, 'scripts', 'check-engine-raw-sql-ratchet.ts'), baseline: 'scripts/engine-raw-sql-baseline.tsv' };+const KIND = { guard: join(REPO, 'scripts', 'check-engine-kind-branches.ts'), baseline: 'scripts/engine-kind-branches-baseline.tsv' };+const dirs: string[] = [];+afterEach(() => {+ for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true });+});++function tree(baselineRel: string, files: Record<string, string>): string {+ const root = mkdtempSync(join(tmpdir(), 'gbrain-engine-raw-sql-ratchet-'));+ dirs.push(root);+ for (const [rel, body] of Object.entries({ [baselineRel]: '# baseline\n', ...files })) {+ mkdirSync(join(root, rel, '..'), { recursive: true });+ writeFileSync(join(root, rel), body);+ }+ return root;+}++function run(guard: string, root: string, args: string[] = []) {+ const r = spawnSync('bun', [guard, ...args], { encoding: 'utf8', env: { ...process.env, GBRAIN_GUARD_ROOT: root } });+ return { code: r.status, out: `${r.stdout}\n${r.stderr}` };+}++describe('check-engine-raw-sql-ratchet.ts: what counts', () => {+ test('executeRaw, executeRawDirect and executeRawJsonb count on any receiver', () => {+ const c = countFile([+ 'declare const engine: any, tx: any, exec: any;',+ 'engine.executeRaw("SELECT 1");',+ 'tx.executeRawDirect(q);',+ 'exec.executeRawJsonb("UPDATE pages SET frontmatter = $1::jsonb", [o]);',+ 'const f = engine.executeRaw;',+ ].join('\n'));+ expect(c.execute_raw).toBe(3);+ });++ test('literal bracket-access calls count like the dot spelling', () => {+ const c = countFile([+ 'declare const e: any, db: any;',+ 'e["executeRaw"]("SELECT 1");',+ 'e[`executeRawJsonb`]("UPDATE pages SET frontmatter = $1::jsonb", [o]);',+ 'db["unsafe"](text);',+ 'db["query"]("SELECT id FROM pages");',+ 'e[name]("SELECT 1");',+ ].join('\n'));+ expect(c.execute_raw).toBe(2);+ expect(c.driver_call).toBe(2);+ });++ test('an executeRaw tag counts once, as execute_raw', () => {+ expect(countFile('declare const e: any;\ne.executeRaw`SELECT id FROM pages`;')).toEqual({ execute_raw: 1, sql_template: 0, driver_call: 0 });+ });++ test('SQL tagged templates count; non-SQL templates and comments do not', () => {+ const c = countFile([+ 'declare const sql: any, html: any;',+ 'sql`SELECT id FROM pages WHERE slug = ${s}`;',+ 'html`<p>select a page from the list</p>`;',+ '// sql`SELECT id FROM pages`',+ 'const plain = `SELECT id FROM pages`;',+ ].join('\n'));+ expect(c.sql_template).toBe(1);+ expect(c.execute_raw).toBe(0);+ });++ test('driver_call: unsafe always, query and exec only with SQL text', () => {+ const c = countFile([+ 'declare const db: any, re: any;',+ 'db.unsafe(text);',+ 'db.query("SELECT id FROM pages WHERE id = $1", [1]);',+ 'db.exec("CREATE TABLE t (a int)");',+ 'db.query(text);',+ 're.exec("hello world");',+ ].join('\n'));+ expect(c.driver_call).toBe(3);+ });++ // Value: protects=SQL built by concatenation, interpolation, casts or wrapped callees still counts; fails_when=literalText or calleeName stops unwrapping a supported form; why_new=earlier cases use direct literals and plain callees only; seam=none+ test('concatenated, interpolated and wrapped SQL still counts; non-SQL text does not', () => {+ const c = countFile([+ 'declare const db: any, e: any, t: string;',+ 'db.query("SELECT id " + "FROM pages WHERE slug = " + t);',+ 'db.query(`SELECT ${t} FROM pages`);',+ 'db.query(("SELECT 1") as string);',+ '(db.query)("SELECT 1");',+ 'db!.unsafe(t);',+ '(e!.executeRaw)("SELECT 1");',+ 'db.query("hello " + t);',+ 'db.exec(`say ${t} twice`);',+ ].join('\n'));+ expect(c).toEqual({ execute_raw: 1, sql_template: 0, driver_call: 5 });+ });++ test('the engines are out of scope; everything else under src/ is in', () => {+ for (const rel of [+ 'src/core/engine.ts', 'src/core/pglite-engine.ts', 'src/core/postgres-engine.ts',+ 'src/core/pglite-engine/pages.ts', 'src/core/postgres-engine/facts.ts', 'src/core/engine-sql/pages.ts',+ ]) expect(isEngineFile(rel)).toBe(true);+ for (const rel of ['src/core/search/hybrid.ts', 'src/commands/doctor.ts', 'src/core/engine-factory.ts'])+ expect(isEngineFile(rel)).toBe(false);+ });+});++describe('check-engine-raw-sql-ratchet.ts: shrink-only baseline', () => {+ const site = 'declare const e: any;\nexport const a = () => e.executeRaw("SELECT 1");\n';++ test('a matching baseline passes and engine files are never counted', () => {+ const root = tree(RAW.baseline, {+ [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\n',+ 'src/core/a.ts': site,+ 'src/core/engine-sql/pages.ts': site + site,+ 'src/core/pglite-engine.ts': site,+ });+ const r = run(RAW.guard, root);+ expect(r.code).toBe(0);+ expect(r.out).toContain('check-engine-raw-sql-ratchet: ok (1 sites in 1 files: execute_raw 1, sql_template 0, driver_call 0)');+ });++ test('a rise above the row fails with the fix', () => {+ const root = tree(RAW.baseline, {+ [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\n',+ 'src/core/a.ts': site + 'export const b = () => e.executeRaw("SELECT 2");\n',+ });+ const r = run(RAW.guard, root);+ expect(r.code).toBe(1);+ expect(r.out).toContain('FAIL: src/core/a.ts execute_raw: baseline 1, actual 2');+ expect(r.out).toContain('typed engine method');+ });++ test('a new file with no row fails', () => {+ const root = tree(RAW.baseline, { 'src/commands/new.ts': site });+ const r = run(RAW.guard, root);+ expect(r.code).toBe(1);+ expect(r.out).toContain('FAIL: src/commands/new.ts execute_raw: baseline 0, actual 1');+ });++ test('a stale row fails, and --prune lowers it without raising anything', () => {+ const root = tree(RAW.baseline, {+ [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t3\nsrc/core/gone.ts\tsql_template\t2\n',+ 'src/core/a.ts': site,+ });+ const r = run(RAW.guard, root);+ expect(r.code).toBe(1);+ expect(r.out).toContain('stale row: src/core/a.ts execute_raw: baseline 3, actual 1');+ expect(r.out).toContain('stale row: src/core/gone.ts sql_template: baseline 2, actual 0');+ const p = run(RAW.guard, root, ['--prune']);+ expect(p.out).toContain('pruned 2 row(s)');+ expect(readFileSync(join(root, RAW.baseline), 'utf8')).toBe('# baseline\nsrc/core/a.ts\texecute_raw\t1\n');+ expect(run(RAW.guard, root).code).toBe(0);+ });++ test('--prune never adds a row for a rise', () => {+ const root = tree(RAW.baseline, { 'src/core/a.ts': site });+ run(RAW.guard, root, ['--prune']);+ expect(readFileSync(join(root, RAW.baseline), 'utf8')).toBe('# baseline\n');+ expect(run(RAW.guard, root).code).toBe(1);+ });++ test('a missing baseline fails closed', () => {+ const root = tree(RAW.baseline, { 'src/core/a.ts': site });+ rmSync(join(root, RAW.baseline));+ const r = run(RAW.guard, root);+ expect(r.code).toBe(1);+ expect(r.out).toContain('baseline file missing');+ });++ test('duplicate and malformed rows fail', () => {+ const root = tree(RAW.baseline, {+ [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\nsrc/core/a.ts\texecute_raw\t1\nsrc/core/b.ts\tnot_a_metric\t1\n',+ 'src/core/a.ts': site,+ });+ const r = run(RAW.guard, root);+ expect(r.code).toBe(1);+ expect(r.out).toContain('duplicate row for src/core/a.ts execute_raw');+ expect(r.out).toContain('malformed row');+ });++ // Value: protects=a baseline row with a bad count or shape fails instead of loosening the ratchet; fails_when=parseRows accepts zero, negative, fractional or text counts, wrong columns or an empty path; why_new=the malformed case above covers unknown metrics only; seam=none+ test('rows with a bad count, the wrong column count or an empty path are malformed', () => {+ for (const row of ['src/core/a.ts\texecute_raw\t0', 'src/core/a.ts\texecute_raw\t-1', 'src/core/a.ts\texecute_raw\t1.5',+ 'src/core/a.ts\texecute_raw\tone', 'src/core/a.ts\texecute_raw', 'src/core/a.ts\texecute_raw\t1\twhy\textra', '\texecute_raw\t1']) {+ const root = tree(RAW.baseline, { [RAW.baseline]: `# baseline\nsrc/core/a.ts\texecute_raw\t1\n${row}\n`, 'src/core/a.ts': site });+ const r = run(RAW.guard, root);+ expect(r.code, row).toBe(1);+ expect(r.out, row).toContain('malformed row');+ }+ });++ test('a raised row with a note passes; --prune keeps the note; an empty note is malformed', () => {+ const raised = tree(RAW.baseline, {+ [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\tfix #1: needs one read until links move\n',+ 'src/core/a.ts': site,+ });+ expect(run(RAW.guard, raised).code).toBe(0);+ const stale = tree(RAW.baseline, {+ [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t3\tfix #1: why\n',+ 'src/core/a.ts': site,+ });+ run(RAW.guard, stale, ['--prune']);+ expect(readFileSync(join(stale, RAW.baseline), 'utf8')).toBe('# baseline\nsrc/core/a.ts\texecute_raw\t1\tfix #1: why\n');+ const empty = tree(RAW.baseline, {+ [RAW.baseline]: '# baseline\nsrc/core/a.ts\texecute_raw\t1\t \n',+ 'src/core/a.ts': site,+ });+ const r = run(RAW.guard, empty);+ expect(r.code).toBe(1);+ expect(r.out).toContain('the note column is empty');+ });++ test('a rise names both ways out: a typed method, or a raised row with a note', () => {+ const root = tree(RAW.baseline, { 'src/core/a.ts': site });+ const r = run(RAW.guard, root);+ expect(r.code).toBe(1);+ expect(r.out).toContain('call a typed engine method');+ expect(r.out).toContain('with a note column saying why');+ });++ test('--print emits the current rows in the baseline format', () => {+ const root = tree(RAW.baseline, { 'src/core/a.ts': site, 'src/b.ts': 'declare const sql: any;\nsql`DELETE FROM pages`;\n' });+ const r = spawnSync('bun', [RAW.guard, '--print'], { encoding: 'utf8', env: { ...process.env, GBRAIN_GUARD_ROOT: root } });+ expect(r.stdout).toBe('src/b.ts\tsql_template\t1\nsrc/core/a.ts\texecute_raw\t1\n');+ });+});++describe('check-engine-kind-branches.ts', () => {+ test('counts two-way comparisons and switch cases on engine-kind names only', () => {+ const c = countKinds([+ 'declare const engine: any, cfg: any, kind: string, opts: any, mode: string;',+ 'engine.kind === "pglite";',+ '"postgres" !== cfg.engine;',+ 'kind == "pglite";',+ 'opts.engineKind != "postgres";',+ 'mode === "pglite";',+ 'engine.kind === "sqlite";',+ 'switch (engine.kind) { case "pglite": break; case "postgres": break; default: break; }',+ 'switch (mode) { case "pglite": break; }',+ ].join('\n'));+ expect(c.kind_compare).toBe(4);+ expect(c.kind_case).toBe(2);+ });++ // Value: protects=bracket, backtick and wrapped spellings of an engine-kind branch still count; fails_when=isKindExpr or isKindLiteral stops unwrapping one of these forms; why_new=the case above uses dot access and quoted literals only; seam=none+ test('bracket access, backtick literals and wrapped subjects count too', () => {+ const c = countKinds([+ 'declare const e: any, kind: any;',+ 'e["kind"] === "pglite";',+ 'e[`engineKind`] === "postgres";',+ 'kind === `postgres`;',+ '(e.kind as string) === "pglite";',+ 'e!.engine !== "postgres";',+ 'e["mode"] === "pglite";',+ 'switch ((e.kind)) { case `pglite`: break; }',+ ].join('\n'));+ expect(c).toEqual({ kind_compare: 5, kind_case: 1 });+ });++ test('an exhaustive switch whose default asserts never does not count; an incomplete one does', () => {+ const exhaustive = (tail: string) => countKinds([+ "type Kind = 'pglite' | 'postgres'; declare const kind: Kind; declare function assertNever(x: never): never;",+ `switch (kind) { case 'pglite': break; case 'postgres': break; default: ${tail} }`,+ ].join('\n')).kind_case;+ expect(exhaustive('{ const unreachable: never = kind; throw new Error(String(unreachable)); }')).toBe(0);+ expect(exhaustive('assertNever(kind);')).toBe(0);+ expect(exhaustive('kind satisfies never; throw new Error("unreachable");')).toBe(0);+ expect(exhaustive('return assertNever(kind);')).toBe(0);+ expect(exhaustive('throw assertNever(kind);')).toBe(0);+ expect(exhaustive('throw new Error("unknown engine");')).toBe(2);+ // A cast or a never check on another value proves nothing.+ expect(exhaustive('void (kind as never);')).toBe(2);+ expect(exhaustive('{ declare const other: never; const x: never = other; }')).toBe(2);+ expect(exhaustive('assertNever(other as never);')).toBe(2);+ // The check must be the clause's first statement: earlier control flow can+ // narrow the value to never after an unknown kind has already escaped.+ expect(exhaustive('{ if (kind) return 2; const unreachable: never = kind; return unreachable; }')).toBe(2);+ expect(exhaustive('console.log(kind); assertNever(kind);')).toBe(2);+ expect(exhaustive('throw new Error(String(kind satisfies never));')).toBe(2);+ // A never check in a nested function, or on a name that shadows the+ // switched value, says nothing about the outer switch.+ expect(exhaustive('{ const check = (kind: never) => kind satisfies never; return 2; }')).toBe(2);+ expect(exhaustive('{ const check = (kind: never) => { const u: never = kind; }; return 2; }')).toBe(2);+ expect(countKinds([+ "type Kind = 'pglite' | 'postgres'; declare const kind: Kind;",+ "switch (kind) { case 'pglite': const kind2 = 1; break; case 'postgres': { break; } default: { const unreachable: never = kind; const kind = 0 as never; } }",+ ].join('\n')).kind_case).toBe(2);+ expect(countKinds([+ "declare const engine: { kind: 'pglite' | 'postgres' };",+ "switch (engine.kind) { case 'pglite': let engine = { kind: 0 as never }; break; case 'postgres': break; default: const u: never = engine.kind; }",+ ].join('\n')).kind_case).toBe(2);+ expect(countKinds([+ "declare const engine: { kind: 'pglite' | 'postgres' };",+ "switch (engine.kind) { case 'pglite': break; case 'postgres': break; default: const u: never = engine.kind; }",+ ].join('\n')).kind_case).toBe(0);+ // A switch that leaves a kind out keeps counting even with a never check that does not compile.+ expect(countKinds("declare const kind: 'pglite' | 'postgres';\nswitch (kind) { case 'pglite': break; default: break; }").kind_case).toBe(1);+ expect(countKinds("declare const kind: string;\nswitch (kind) { case 'pglite': break; case 'postgres': break; }").kind_case).toBe(2);+ });++ test('a new branch outside the engines fails; inside the engines it is ignored', () => {+ const root = tree(KIND.baseline, {+ 'src/core/pglite-engine.ts': 'declare const e: any;\nexport const x = e.kind === "pglite";\n',+ 'src/core/b.ts': 'declare const e: any;\nexport const x = e.kind === "postgres";\n',+ });+ const r = run(KIND.guard, root);+ expect(r.code).toBe(1);+ expect(r.out).toContain('FAIL: src/core/b.ts kind_compare: baseline 0, actual 1');+ expect(r.out).toContain('capability');+ });++ test('a matching baseline passes', () => {+ const root = tree(KIND.baseline, {+ [KIND.baseline]: '# baseline\nsrc/core/b.ts\tkind_compare\t1\n',+ 'src/core/b.ts': 'declare const e: any;\nexport const x = e.kind === "postgres";\n',+ });+ expect(run(KIND.guard, root).code).toBe(0);+ });+});+