Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: pre-landing review fixes

garrytan7ff6b32e1821
diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsv
index 6145d4af15..2835eb0911 100644
--- a/docs/architecture/canonical-writers.tsv
+++ b/docs/architecture/canonical-writers.tsv
@@ -31,7 +31,7 @@ src/commands/reconcile-links.ts 2 engine_guard Canonical table SQL trigger requi
src/commands/reindex-aliases.ts 1 engine_guard Canonical table SQL trigger requires coordinator capability; legacy calls fail before canonical DB publication.
src/core/persistence/twin-merge.ts 10 coordinator The #6948 twin merge (links in every role, link transitions, timeline, raw data, files, user tags, aliases and facts move onto the canonical page; the twin is marked origin_twin and soft-deleted) runs only inside the managed_maintenance_resolve_origin_twin preparer's coordinated transaction on managed brains, or one maintenanceTransaction on unmanaged brains, after the group verdict is rechecked under both page locks; it writes no file, so there is no filesystem ordering to keep.
src/core/repair/origin-twins.ts 1 coordinator gbrain repair origin-twins and the post-sync heal resolve each verified twin as a receipted managed_maintenance_resolve_origin_twin request (submitDatabaseMaintenanceIntent, owner host only) on managed brains and in one maintenanceTransaction on unmanaged brains; the verdict is recomputed inside the write and any drift holds the file instead of merging.
-src/core/repair/unwithdrawn-facts.ts 1 coordinator `gbrain repair unwithdrawn-facts` (#8819) puts the ledger before-state back on preview-approved facts a fact_fence generation retired though no fence held them. On a managed brain the UPDATE runs only inside the managed_maintenance_restore_unwithdrawn_facts publication; unmanaged and repo-less brains run it in one maintenanceTransaction under the page lock after the revision recheck.
+src/core/repair/unwithdrawn-facts.ts 1 coordinator `gbrain repair unwithdrawn-facts` (#8819) puts the ledger before-state back on preview-approved facts a fact_fence generation retired though no fence held them. On a managed brain the UPDATE runs only inside the managed_maintenance_restore_unwithdrawn_facts publication; an unmanaged or repo-less brain classifies every candidate excluded (unmanaged_reconcile), so a set previewed while it was managed is reclassified in one maintenanceTransaction under the page lock after the revision recheck and restores nothing.
src/core/search-vector-backfill.ts 2 projection backfillPageVectors (reindex-search-vector, the fts_cjk_boundary migration) rewrites only pages.search_vector, through the seal's pageSearchVectorSql over the sanitized timeline and guarded by the knowledge revision it read (its read is an UPDATE-to-self of id); canonical fields are untouched and the managed writer guard passes search_vector-only updates.
src/commands/sources-set-path.ts 1 coordinator Managed rebind uses native exclusion, exact manifest verification and a retained source-incarnation receipt; unmanaged pointer repair remains explicit.
src/commands/sources.ts 10 coordinator Managed add/archive/restore/remove/purge/reclone route through source lifecycle; remaining legacy canonical SQL stays fenced.
diff --git a/docs/architecture/generations.md b/docs/architecture/generations.md
index 82aaa5f542..2620ab7df8 100644
--- a/docs/architecture/generations.md
+++ b/docs/architecture/generations.md
@@ -73,9 +73,12 @@ refuses a fence edited since (`edited_since`, `section_moved`).
#8819: a published fact generation retires only rows a fence of the page held at the same row number, claim and
visibility (`generations/fence-evidence.ts`): a `fact_fence` generation recorded it, the body the writer replaced carried
it, or a stored version of the page did. A row the fence never held (a fact a `put_page` writer attached to the page)
-stays active, and an incoming fence row that claims its number takes it while the row moves above the page's rows. The
-managed `extract_facts` reconcile applies the same rule; an unmanaged brain's reconcile still treats rows its fence lacks
-as drift. Rows an earlier release retired this way are restored by `gbrain repair unwithdrawn-facts`.
+stays active, and an incoming fence row that claims its number takes it while the row moves above the page's rows. A
+row whose claim the incoming fence states, at any number or visibility, still retires, so no wider copy of a claim the
+fence narrowed stays readable. The managed `extract_facts` reconcile applies the same rule; an unmanaged brain's
+reconcile still treats rows its fence lacks as drift. Rows an earlier release retired this way on a managed brain are
+restored by `gbrain repair unwithdrawn-facts`; on an unmanaged brain it lists them as `excluded:unmanaged_reconcile`,
+since the next reconcile would retire a restored row again.
The dream consolidate phase records each cluster (`consolidation`, key `entity:<slug>:cluster:<ids>`,
`adapters/fact-rows.ts`): a strict chain records each member's `valid_until`, `consolidated_at` and
diff --git a/docs/architecture/key-files/core-cycle.md b/docs/architecture/key-files/core-cycle.md
index 9a4bbd28d2..1891a1231f 100644
--- a/docs/architecture/key-files/core-cycle.md
+++ b/docs/architecture/key-files/core-cycle.md
@@ -28,7 +28,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
Both paths prevent LLM-chosen titles that drift between extractions from piling up.
Atom identity: page-derived atoms fold the source-page slug into the slug hash (8 chars, NUL-separated) so two same-date pages emitting the same title get DISTINCT slugs; the source CONTENT hash is deliberately NOT folded (a reworded source still upserts rather than duping); transcript atoms keep the legacy title-only 6-char hash. `resolvePageAtomSlug` adopts a legacy-slug atom with a compatible binding in place on re-extraction (upgrade idempotency — no migration, no duplicate), while `assertAtomImportBinding` fail-closed refuses to reuse a slug bound to a DIFFERENT source locator. Both share `isCompatibleAtomBinding(frontmatter, sourcePageSlug)` — the ONE definition of compatible: bound to THIS source page, or carrying no `source_slug`/`source_path` at all (pre-binding-era adoption, not a clobber); a `source_path`-bound legacy transcript atom or a different `source_slug` is a different origin, and a non-atom page squatting on the slug is refused. `source_quote` is verified at extraction time against the exact `truncateUtf8` prompt prefix the model saw (`locateQuote` advances by full code points): located quotes persist original characters + [start,end) offsets + `source_quote_verified`; unlocatable quotes are dropped with the atom kept. Edges write before the completion flip; per-item drain failures stay typed (bounded, sanitized, reconcilable). Transcript items carry the same failure-count/tombstone machinery as pages, in the `extract_atoms_transcript_state` table (keyed `(source_id, file_path, content_hash)`, 16-char hash prefix, so an edit is a new row): `recordItemFailureCount` counts a transcript's malformed output or prompt-level provider block (`providerContentBlockReason`; never feeds the outage halt) toward `MAX_DETERMINISTIC_FAILURES`, a zero-yield transcript tombstones immediately (as pages do), and `tombstonedTranscriptsForHashes` is the batch read-side gate mirroring `atomsExistingForHashes` (fail-open on error). Reported as `tombstoned_transcripts` (paths), separate from the page-slug `tombstoned_for_failures`. Malformed managed output requires a newly approved protected-job retry identity; publication retry reuses retained output and original/current grants.
-- `src/core/cycle/extract-facts.ts` — source-scoped `## Facts` fence reconciliation. Rows are keyed by fence row number, never by claim text: a DB row whose `(row_num, claim)` is still in the fence keeps its id and has its other cells updated in place (ids from recall stay valid for forget; `source_session`, `created_at`, consolidation state and vectors survive), a row whose number left the fence or whose claim was rewritten is expired and detached (`row_num` NULL), never deleted, and only new row numbers insert. Duplicate ACTIVE rows with the same claim and source index once; a struck history row never collapses onto an active row with the same text, so a claim that reverts (NYC → SF → NYC) stays active. `superseded by #N` links resolve on every hop of a chain (`supersede-resolve.ts`; forgotten targets and cycles still resolve to NULL with a warning). Each run first fences the source's unfenced rows (`row_num IS NULL`, live entity page, never ontology observations: `dimension IS NULL`, #6264) through `facts/unfenced-facts.ts` and adds those pages to the run's reconcile set (`unfencedRowsFenced`); rows it cannot fence this run (canonical file not on this host, malformed fence, held page lock, a claim the fence codec cannot render) are named as `FACTS_FENCE_FAILED: <slug> (<reason>)` and keep their own page out of the destructive reconcile (the empty-fence guard, per page since #6278: `pendingLegacyRows` lists the pages, `legacyRowsPending` and `legacyPages` report them, and every other page of the source still reconciles; the page keeps its fact index because reconciliation would classify its `row_num IS NULL` rows as stale and expire them). The phantom-redirect pass moves rows by fence position and so still waits until the source has no unfenced rows. `runPhaseExtractFacts` (`cycle.ts`) then reports the reconcile counts of the pages that did reconcile and names the skipped pages in its summary. Rows with no backing page or checkout, and ontology observations, never gate. It then expires (without detaching) the active fence-owned rows of soft-deleted pages in the source; restoring the page re-activates them on its next reconcile. Previously embedded fact rows and their text/provenance remain intact when a full valid replacement embedding batch is unavailable; old vectors are never transplanted to changed text/model. Restrictive fence changes still expire removed/withdrawn claims and tighten visibility before deferral. Provider cancellation within database writes rolls back rather than publishing half a replacement. Keyless initial fact insertion remains supported; conversation-origin facts without a fence are not wiped by fence reconciliation. Each page reconciles in isolation: a page whose writes the database rejects rolls back, is reported as `<slug>: FACTS_RECONCILE_FAILED: …` (counted in `pagesFailed`, booked as a halt in the rollup), and later pages still reconcile. `facts.superseded_by` is `ON DELETE SET NULL`. On an unmanaged brain each reconcile records its outcome in `page_facts_reconcile` (`src/core/facts/reconcile-watermark.ts`): a complete reconcile (including a no-op) stamps the page's `knowledge_revision` inside the write transaction, after a `FOR SHARE` lock and a revision recheck (a moved page writes nothing and stays due); `deferred` (lock, stale cache, embedding deferral, rejected write), `invalid` (malformed or misplaced fence, not retried until the page changes) and `cancelled` leave it due. The dream cycle passes `drain`, so an incremental run also reconciles up to 250 due pages within 60 s, never-attempted first then oldest attempt, after settling in bulk the due pages with no fence marker and no fence rows; a fence imported by a standalone sync or removed from a page is therefore reconciled even when the cycle's own sync changed nothing. A direct call with `slugs: []` and no `drain` still reconciles nothing. Doctor's `extract_health` names unreconciled fence pages and unreadable fences on unmanaged brains. Tests: `test/extract-facts-reconcile-drain.test.ts` (Postgres race through `test/e2e/extract-facts-reconcile-drain-postgres.test.ts`), `test/e2e/fact-vector-repair-parity.test.ts`, `test/extract-facts-phase.test.ts`, `test/extract-facts-unfenced-rows.test.ts` (a mixed page, on PGLite and through the Postgres E2E), `test/extract-facts-poison-page.test.ts`, `test/extract-facts-stable-identity.test.ts`. On a managed brain the same reconcile runs after `managedDerivedFactsPreflight` (local writer, active source, before any embedding call): each page transaction and the deleted-page expiry commit inside `withDerivedFactsWrite` (coordinator source capability, page key locked); the facts receipt page is skipped, the rollup is still booked. Each deleted page's expiry is one item (ItemRun site `extract_facts.expire_deleted`, src/core/item-failure.ts): a refused expiry is a `FACTS_EXPIRE_FAILED: <slug>: <code>: …` warning (the phase warns) retried by the next run, a page the refusal breaker holds back is a `FACTS_EXPIRE_SKIPPED` warning, and run-scoped errors or most pages failing (`item_failures_systemic`) still fail the phase; test `test/pathological/a21-facts-expire-deleted.test.ts`. It is distinct from the coordinated `extract_facts` operation and durable page backstop. Tests: `test/managed-facts-writers.test.ts`. Wave B PR 2 (lane 2e2): a segmented page reconciles like an inline one, its fences read from its marker segments (`segmentedFactsFenceView`), its write guarded by content hash and size, and its stale-cache check streamed against the canonical file (`segmentedBodyMatchesFile`, page-body/segment-facts.ts); test `test/large-pages/segmented-facts-reconcile.test.ts`. #6259: it and `extract-takes.ts` (both the DB walk and the file walk, which checks the stored page) skip a quarantined page, leaving rows projected before it was quarantined as they are. Test: `test/quarantine-fence-projection.test.ts`. #6946: a gbrain-owned `--url` clone on an unmanaged brain never gates the empty-fence guard (its facts are database-only by design). #8819: on a managed brain `planFenceReconcile` keeps stale positioned rows no fence of the page held (`generations/fence-evidence.ts`) out of the retirements (`kept`), and `writeFenceReconcile` moves one whose number a new fence row needs (`moveKeptRows`); an unmanaged brain's reconcile still retires rows its fence lacks as drift.
+- `src/core/cycle/extract-facts.ts` — source-scoped `## Facts` fence reconciliation. Rows are keyed by fence row number, never by claim text: a DB row whose `(row_num, claim)` is still in the fence keeps its id and has its other cells updated in place (ids from recall stay valid for forget; `source_session`, `created_at`, consolidation state and vectors survive), a row whose number left the fence or whose claim was rewritten is expired and detached (`row_num` NULL), never deleted, and only new row numbers insert. Duplicate ACTIVE rows with the same claim and source index once; a struck history row never collapses onto an active row with the same text, so a claim that reverts (NYC → SF → NYC) stays active. `superseded by #N` links resolve on every hop of a chain (`supersede-resolve.ts`; forgotten targets and cycles still resolve to NULL with a warning). Each run first fences the source's unfenced rows (`row_num IS NULL`, live entity page, never ontology observations: `dimension IS NULL`, #6264) through `facts/unfenced-facts.ts` and adds those pages to the run's reconcile set (`unfencedRowsFenced`); rows it cannot fence this run (canonical file not on this host, malformed fence, held page lock, a claim the fence codec cannot render) are named as `FACTS_FENCE_FAILED: <slug> (<reason>)` and keep their own page out of the destructive reconcile (the empty-fence guard, per page since #6278: `pendingLegacyRows` lists the pages, `legacyRowsPending` and `legacyPages` report them, and every other page of the source still reconciles; the page keeps its fact index because reconciliation would classify its `row_num IS NULL` rows as stale and expire them). The phantom-redirect pass moves rows by fence position and so still waits until the source has no unfenced rows. `runPhaseExtractFacts` (`cycle.ts`) then reports the reconcile counts of the pages that did reconcile and names the skipped pages in its summary. Rows with no backing page or checkout, and ontology observations, never gate. It then expires (without detaching) the active fence-owned rows of soft-deleted pages in the source; restoring the page re-activates them on its next reconcile. Previously embedded fact rows and their text/provenance remain intact when a full valid replacement embedding batch is unavailable; old vectors are never transplanted to changed text/model. Restrictive fence changes still expire removed/withdrawn claims and tighten visibility before deferral. Provider cancellation within database writes rolls back rather than publishing half a replacement. Keyless initial fact insertion remains supported; conversation-origin facts without a fence are not wiped by fence reconciliation. Each page reconciles in isolation: a page whose writes the database rejects rolls back, is reported as `<slug>: FACTS_RECONCILE_FAILED: …` (counted in `pagesFailed`, booked as a halt in the rollup), and later pages still reconcile. `facts.superseded_by` is `ON DELETE SET NULL`. On an unmanaged brain each reconcile records its outcome in `page_facts_reconcile` (`src/core/facts/reconcile-watermark.ts`): a complete reconcile (including a no-op) stamps the page's `knowledge_revision` inside the write transaction, after a `FOR SHARE` lock and a revision recheck (a moved page writes nothing and stays due); `deferred` (lock, stale cache, embedding deferral, rejected write), `invalid` (malformed or misplaced fence, not retried until the page changes) and `cancelled` leave it due. The dream cycle passes `drain`, so an incremental run also reconciles up to 250 due pages within 60 s, never-attempted first then oldest attempt, after settling in bulk the due pages with no fence marker and no fence rows; a fence imported by a standalone sync or removed from a page is therefore reconciled even when the cycle's own sync changed nothing. A direct call with `slugs: []` and no `drain` still reconciles nothing. Doctor's `extract_health` names unreconciled fence pages and unreadable fences on unmanaged brains. Tests: `test/extract-facts-reconcile-drain.test.ts` (Postgres race through `test/e2e/extract-facts-reconcile-drain-postgres.test.ts`), `test/e2e/fact-vector-repair-parity.test.ts`, `test/extract-facts-phase.test.ts`, `test/extract-facts-unfenced-rows.test.ts` (a mixed page, on PGLite and through the Postgres E2E), `test/extract-facts-poison-page.test.ts`, `test/extract-facts-stable-identity.test.ts`. On a managed brain the same reconcile runs after `managedDerivedFactsPreflight` (local writer, active source, before any embedding call): each page transaction and the deleted-page expiry commit inside `withDerivedFactsWrite` (coordinator source capability, page key locked); the facts receipt page is skipped, the rollup is still booked. Each deleted page's expiry is one item (ItemRun site `extract_facts.expire_deleted`, src/core/item-failure.ts): a refused expiry is a `FACTS_EXPIRE_FAILED: <slug>: <code>: …` warning (the phase warns) retried by the next run, a page the refusal breaker holds back is a `FACTS_EXPIRE_SKIPPED` warning, and run-scoped errors or most pages failing (`item_failures_systemic`) still fail the phase; test `test/pathological/a21-facts-expire-deleted.test.ts`. It is distinct from the coordinated `extract_facts` operation and durable page backstop. Tests: `test/managed-facts-writers.test.ts`. Wave B PR 2 (lane 2e2): a segmented page reconciles like an inline one, its fences read from its marker segments (`segmentedFactsFenceView`), its write guarded by content hash and size, and its stale-cache check streamed against the canonical file (`segmentedBodyMatchesFile`, page-body/segment-facts.ts); test `test/large-pages/segmented-facts-reconcile.test.ts`. #6259: it and `extract-takes.ts` (both the DB walk and the file walk, which checks the stored page) skip a quarantined page, leaving rows projected before it was quarantined as they are. Test: `test/quarantine-fence-projection.test.ts`. #6946: a gbrain-owned `--url` clone on an unmanaged brain never gates the empty-fence guard (its facts are database-only by design). #8819: on a managed brain `planFenceReconcile` keeps stale positioned rows no fence of the page held (`generations/fence-evidence.ts`) and whose claim the fence does not state out of the retirements (`kept`), and `writeFenceReconcile` moves one whose number a new fence row needs (`moveKeptRows`); an unmanaged brain's reconcile still retires rows its fence lacks as drift.
- `src/core/cycle/inline-drain.ts` — the dream cycle's private-queue drain. `runSubagentsInline(engine, queue, queueName, yieldDuringPhase?, handler?, lockMs?, concurrency?)` runs N independent `drainLoop`s (`dream.synthesize.inline_concurrency`, clamp [1,8], PGLite forced serial at the callsite) sharing the queue via the same SKIP-LOCKED claim fencing workers use — everything job-scoped (lockToken, abort, timeout timer, keepalive, renewTimer, outcome recording) stays loop-local. Pool hygiene: global housekeeping sweeps are leader-only (loop 0) while `promoteDelayed` runs in every loop; idle claim-poll backs off 1s→5s; a NON-retryable loop-level failure aborts siblings after their current child (a failing child is a job outcome, never a drain crash). Exit only when the queue holds no active/waiting/delayed child (a lease-full bounce's delayed backoff must not strand a child). Outcome routing mirrors the worker: `UnrecoverableError` → dead immediately; `RateLeaseUnavailableError` → `releaseLeaseFullJob` requeue without burning an attempt; timeout terminal. Handler invocation is wrapped in `withChatPhase('job:<name>')` (worker.ts parity) so each drained child's gateway spend is attributed to the CHILD — a bare `await handler(context)` inherits the caller's AsyncLocalStorage phase, and a cycle phase that wraps its own work (dream synthesize wraps `phase:synthesize`) would absorb every child's spend into the phase tag. `runDrainRenewalTick` (per-call AbortSignal + timeout + re-entrancy guard) and the null-safe nearest-rank `percentile()` telemetry helper are exported. Pinned by `test/cycle-synthesize-inline-concurrency.test.ts` (loop semantics) + `test/e2e/dream-synthesize-concurrency-postgres.test.ts` (real-Postgres exact-once + lease-ceiling). #7239: a child that throws a deterministic refusal (minions/refusal.ts) is dead after one attempt with the refusal on its result.
diff --git a/docs/architecture/key-files/generations.md b/docs/architecture/key-files/generations.md
index e7752367f4..1a4770693a 100644
--- a/docs/architecture/key-files/generations.md
+++ b/docs/architecture/key-files/generations.md
@@ -4,8 +4,8 @@
Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
- `src/core/generations/{contract,plan,publish,proofs,config,repair,ledger-scrub}.ts` + `adapters/{page,atoms,index}.ts` (GBRA-161) — the generation primitive: one ledger row per derived key generation (`derived_generations`, items and bounded preimages in `derived_generation_items`); `publishGeneration` holds a shrunk, oversize, unproven-empty, valve or segmented result and otherwise writes, completes, rechecks, retires (versioned, stamped) and activates in one transaction. `gbrain repair generations` restores or releases from previews; doctor `generation_retirements` / `generation_held`. Reference: [generations](../generations.md). Tests: `test/pathological/g1-generations.test.ts`, `test/pathological/g1-atom-generations.test.ts`.
-- `src/core/generations/fence-evidence.ts` (#8819) — `factsFenceHeld`: which positioned fact rows of a page some fence held at the same row number, claim and visibility (a non-retired item of any `fact_fence` generation of the page, the replaced body's rows from `pageFenceRowKeys`, which reads a segmented page from its marker segments, or a stored `page_versions` body, newest first, at most 1000; `complete` is false past that or when a version has no body, as a segmented snapshot has none). The page projection (`projectFactFenceGeneration`, which returns `retireIds` and `kept`) retires only held rows and conversation-extractor rows a fence row displaces; the managed `extract_facts` reconcile keeps unheld stale rows out of its retirements. `moveKeptRows` moves a kept row whose number an incoming fence row claims above every row of the page. The projection's evidence is also why `canonical-projections.ts` reads the prior fence before publication. Tests: `test/fence-first-generation-8819.test.ts` (PGLite and Postgres).
-- `src/core/repair/unwithdrawn-facts.ts` — `gbrain repair unwithdrawn-facts` (#8819), explicit-only and preview-bound. `classifyUnwithdrawnFacts` (read-only; also the doctor check's count) takes each fact a `fact_fence` generation retired (a `retired` ledger item with a fact preimage that was active and positioned) whose row is still as the retirement left it (expired at the generation's instant, `row_num` NULL, same claim and visibility; conversation-extractor rows excluded), and classes it `evidenced` (no fence ever held it: `generations/fence-evidence.ts` over the ledger, the current page and its stored versions), `ambiguous` (`version_history_gap_at` set, or versions left unread) or `excluded:<reason>` (page missing, superseded, withdrawn, changed since retirement, `fence_held`, active duplicate, duplicate candidate). The preview saves one item per page with its revision through `preview-approval.ts`; the apply restores the preimage's lifecycle (`expired_at`, `valid_until`, `superseded_by`, consolidation marks) on the same id at its recorded row number when free, else above the page's rows, after reclassifying under the page key: managed, one database-only `managed_maintenance_restore_unwithdrawn_facts` request per page bound to the previewed revision (`prepareUnwithdrawnFactsRestore`, refusing `revision_conflict`); unmanaged, a page-locked `maintenanceTransaction` that refuses a changed revision. Doctor `unwithdrawn_facts` (`commands/doctor/checks/unwithdrawn-facts.ts`). Tests: `test/repair-unwithdrawn-facts-8819.test.ts` (PGLite and Postgres).
+- `src/core/generations/fence-evidence.ts` (#8819) — `factsFenceHeld`: which positioned fact rows of a page some fence held at the same row number, claim and visibility (a non-retired item of any `fact_fence` generation of the page, the replaced body's rows from `pageFenceRowKeys`, which reads a segmented page from its marker segments, or a stored `page_versions` body, newest first, at most 1000; `complete` is false past that or when a version has no body, as a segmented snapshot has none). The page projection (`projectFactFenceGeneration`, which returns `retireIds` and `kept`) retires only held rows, rows whose claim the incoming fence states, and conversation-extractor rows a fence row displaces; the managed `extract_facts` reconcile keeps the other unheld stale rows out of its retirements. `moveKeptRows` moves a kept row whose number an incoming fence row claims above every row of the page. The projection's evidence is also why `canonical-projections.ts` reads the prior fence before publication. Tests: `test/fence-first-generation-8819.test.ts` (PGLite and Postgres).
+- `src/core/repair/unwithdrawn-facts.ts` — `gbrain repair unwithdrawn-facts` (#8819), explicit-only and preview-bound. `classifyUnwithdrawnFacts` (read-only; also the doctor check's count) takes each fact a `fact_fence` generation retired (a `retired` ledger item with a fact preimage that was active and positioned) whose row is still as the retirement left it (expired at the generation's instant, `row_num` NULL, same claim and visibility; conversation-extractor rows excluded), and classes it `evidenced` (no fence ever held it: `generations/fence-evidence.ts` over the ledger, the current page and its stored versions), `ambiguous` (`version_history_gap_at` set, or versions left unread) or `excluded:<reason>` (page missing, superseded, withdrawn, changed since retirement, `fence_held`, active duplicate at any visibility, duplicate candidate, `unmanaged_reconcile` on an unmanaged brain, whose reconcile would retire a restored row again). The preview saves one item per page with its revision through `preview-approval.ts`; the apply restores the preimage's lifecycle (`expired_at`, `valid_until`, `superseded_by`, consolidation marks) on the same id at its recorded row number when free, else above the page's rows, after reclassifying under the page key: managed, one database-only `managed_maintenance_restore_unwithdrawn_facts` request per page bound to the previewed revision (`prepareUnwithdrawnFactsRestore`, refusing `revision_conflict`); unmanaged, a page-locked `maintenanceTransaction` that refuses a changed revision and reclassifies (so restores nothing). Doctor `unwithdrawn_facts` (`commands/doctor/checks/unwithdrawn-facts.ts`). Tests: `test/repair-unwithdrawn-facts-8819.test.ts` (PGLite and Postgres).
- `src/commands/doctor/checks/unwithdrawn-facts.ts` — doctor `unwithdrawn_facts` (#8819): counts those retirements by class through `classifyUnwithdrawnFacts` (`excluded` reported, never a finding) and names the `gbrain repair unwithdrawn-facts` preview. Read-only.
- `src/core/generations/adapters/synthesis.ts`, `src/core/generations/synthesis-coverage.ts`, `src/core/generations/managed-retire.ts`, `src/core/cycle/synthesize-generations.ts` (GBRA-161 PR 4, #7065) — synthesis on the primitive: each re-synthesized transcript's outputs become its `synthesis` generation after postprocess; an earlier output retires (versioned, `synthesis-resynthesis`) only when it is an exact duplicate or the same subject with every claim, quote and citation covered (pure match in `synthesis-coverage.ts`); others stay live and `gbrain repair generations --kind synthesis --mode cleanup` lists and, on apply, retires them (`synthesis-cleanup`). A chunk failure, deferral or `generations.synthesis.retire_previous=false` makes the generation partial. Managed brains admit the activation plus one `managed_generation_retire` delete per retirement (`managed-retire.ts`). Reference: [generations](../generations.md#synthesis). Tests: `test/pathological/g4-synthesis-resynthesis-7065.test.ts`.
- `src/core/generations/adapters/single-page.ts` (GBRA-161 PR 5) — dream summary, `think` page and drift report as single-item generations: revision-bound, versioned first, restorable. Reference: [generations](../generations.md#single-page-kinds-and-fence-only-writers-pr-5). Tests: `test/pathological/g5-*` to `g7-*`.
diff --git a/docs/architecture/system-of-record.md b/docs/architecture/system-of-record.md
index 83cb33ce29..c16e814c2d 100644
--- a/docs/architecture/system-of-record.md
+++ b/docs/architecture/system-of-record.md
@@ -326,7 +326,7 @@ or a physical projection that leaves attribution untouched):
- `src/core/repair/take-supersession.ts` (1): `gbrain repair take-supersession` reprojection: a receipted `managed_maintenance_take_reproject` request on managed brains, `maintenanceTransaction` on unmanaged ones; fence edits go through a revision-bound `put_page`.
- `src/core/repair/timeline-comments.ts` (1): `gbrain repair timeline-comments` row cleanup: `withCoordinatedWrite` under the page key on managed brains, `maintenanceTransaction` otherwise.
- `src/core/repair/url-clone-fences.ts` (2): `gbrain repair url-clone-fences` (#6946), unmanaged brains only (a managed brain previews nothing); keeping the appended fence rows database-only (clearing `row_num`, inserting a row the database lost) runs in one `maintenanceTransaction` under the page lock after the preview recheck; HEAD's bytes then import through `importFromContent` (a HEAD that asks for private in a spelling page privacy does not read is held: not imported, and the apply reports `held`, #7897).
-- `src/core/repair/unwithdrawn-facts.ts` (1): `gbrain repair unwithdrawn-facts` (#8819) puts back the ledger preimage of each preview-approved fact a fence generation retired though no fence held it: a database-only `managed_maintenance_restore_unwithdrawn_facts` request on managed brains, one `maintenanceTransaction` under the page lock on unmanaged and repo-less brains.
+- `src/core/repair/unwithdrawn-facts.ts` (1): `gbrain repair unwithdrawn-facts` (#8819) puts back the ledger preimage of each preview-approved fact a fence generation retired though no fence held it: a database-only `managed_maintenance_restore_unwithdrawn_facts` request on managed brains; unmanaged and repo-less brains list every candidate as `excluded:unmanaged_reconcile`, so their page-locked `maintenanceTransaction` only reclassifies a set previewed while the brain was managed and restores nothing.
- `src/core/repair/visibility.ts` (1): `gbrain repair visibility --apply` tightening of database-only world facts from a private source: a receipted `managed_maintenance_tighten_fact_visibility` request on managed brains, `maintenanceTransaction` on unmanaged ones; fenced rows change through a revision-bound `put_page`.
- `src/core/schema-pack/page-to-alias.ts` (1): the page-to-alias conversion soft-deletes each converted page in `maintenanceTransaction`.
- `src/core/schema-pack/page-to-link.ts` (1): the page-to-link conversion soft-deletes each converted page in `maintenanceTransaction`.
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index d162fb2a4c..83feec03e0 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -2150,7 +2150,10 @@ fence could expire them (`expired_at` set, `row_num` cleared, no
`gbrain repair generations --kind fact_fence` has no earlier generation to
return to. `gbrain repair unwithdrawn-facts` restores these rows from the
before-state the generation ledger recorded. It is explicit-only and
-preview-bound, and it works on a brain with or without a repository.
+preview-bound. On an unmanaged brain, with or without a repository, the
+`extract_facts` reconcile still treats a numbered row its fence lacks as drift
+and would retire a restored row again, so the preview lists those candidates
+as `excluded:unmanaged_reconcile` and restores none.
```bash
gbrain doctor # unwithdrawn_facts
@@ -2168,7 +2171,7 @@ facts are left to [Extractor facts](#extractor-facts).
| --- | --- | --- |
| `evidenced` | No fence of the page ever held the fact: no facts-fence generation recorded it, and neither the page nor any stored version of it carries it at the same row number, claim and visibility. | By `--apply --expect <hash>` |
| `ambiguous` | The page's version history has a gap (pruned versions, or an import that consumed several commits), or it has more stored versions than one preview reads, so an earlier fence holding the fact cannot be ruled out. | Only with `--include-ambiguous` and that preview's hash |
-| `excluded:<reason>` | Page missing or deleted, superseded, withdrawn (`forget`), changed since the retirement, held by a fence (`fence_held`: an edit of the fence removed it, a genuine withdrawal), an active fact with the same text and entity already on the page, or an earlier candidate with the same text and entity. | Never |
+| `excluded:<reason>` | Page missing or deleted, superseded, withdrawn (`forget`), changed since the retirement, held by a fence (`fence_held`: an edit of the fence removed it, a genuine withdrawal), an active fact with the same text and entity already on the page at any visibility, an earlier candidate with the same text and entity, or an unmanaged brain (`unmanaged_reconcile`). | Never |
The preview binds each page's revision. If the page was written after the
preview, the apply restores nothing for it and reports
@@ -2177,10 +2180,10 @@ reports `changed_since_preview` and stays expired. A restored fact keeps its id
and gets back its recorded `expired_at` (cleared), `valid_until`,
`superseded_by` and consolidation marks, at its recorded row number, or at a
fresh number above the page's rows when a fence row has taken it. No page or
-file is written. On a managed brain each page publishes one database-only
-`managed_maintenance_restore_unwithdrawn_facts` request; an unmanaged brain
-writes under the page lock. Page writes and managed `extract_facts` runs from
-this release on keep these rows active.
+file is written. Each page publishes one database-only
+`managed_maintenance_restore_unwithdrawn_facts` request. Page writes and
+managed `extract_facts` runs from this release on keep these rows active,
+except a row whose claim the page's fence now states, which still retires.
<a id="conversation-labels"></a>
### Conversation labels
diff --git a/src/core/cycle/extract-facts.ts b/src/core/cycle/extract-facts.ts
index 81ff383ad8..c52f0ee742 100644
--- a/src/core/cycle/extract-facts.ts
+++ b/src/core/cycle/extract-facts.ts
@@ -464,8 +464,10 @@ async function planFenceReconcile(db: BrainEngine, page: PageFenceInput, slug: s
});
const toInsert = extracted.filter(f => !matched.has(f.row_num));
// #8819: on a managed brain, a stale row whose number and claim no fence of the page ever held was never in the fence,
- // so no edit of it withdrew the row: it stays active, and a new fence row claiming its number takes that position.
- const positioned = managed ? stale.filter(fact => fact.row_num != null)
+ // so no edit of it withdrew the row: it stays active, and a new fence row claiming its number takes that position. A
+ // row whose claim the fence states, at any number or visibility, still retires, so no wider copy of it stays active.
+ const claims = new Set(extracted.map(f => f.fact));
+ const positioned = managed ? stale.filter(fact => fact.row_num != null && !claims.has(fact.fact))
.map(fact => ({ id: Number(fact.id), row_num: Number(fact.row_num), fact: fact.fact, visibility: fact.visibility })) : [];
const { held } = await factsFenceHeld(db, { sourceId, slug, rows: positioned });
const kept = positioned.filter(row => !held.has(row.id)).map(row => row.id);
diff --git a/src/core/generations/adapters/fact-rows.ts b/src/core/generations/adapters/fact-rows.ts
index b06a14882b..194ea2f0db 100644
--- a/src/core/generations/adapters/fact-rows.ts
+++ b/src/core/generations/adapters/fact-rows.ts
@@ -60,7 +60,8 @@ export async function factPreimages(db: BrainEngine, sourceId: string, ids: read
* The page publication's fence projection (persistence/canonical-projections.ts): the rows it would expire and detach
* are those attached to the page that the incoming fence no longer holds at the same number and claim (conversation
* extractor rows only when a fence row claims their number, #5731). #8819: of the others, only a row some fence of the
- * page held retires (fence-evidence.ts); a row the fence never held is `kept` active, since no fence edit withdrew it.
+ * page held, or whose claim the incoming fence states, retires (fence-evidence.ts); a row the fence never held is `kept`
+ * active, since no fence edit withdrew it.
* Held: the caller expires nothing.
*/
export async function projectFactFenceGeneration(tx: BrainEngine, input: { sourceId: string; slug: string; read: FenceRead; incoming: string;
@@ -75,7 +76,8 @@ export async function projectFactFenceGeneration(tx: BrainEngine, input: { sourc
ORDER BY f.row_num, f.id`, [input.sourceId, input.slug, input.incoming])).map(row => row.preimage);
const extractor = (row: FactPreimage) => (row.source ?? '').startsWith('cli:extract-conversation-facts');
const { held } = await factsFenceHeld(tx, { sourceId: input.sourceId, slug: input.slug, rows: candidates.filter(row => !extractor(row)), prior: input.prior });
- const retire = candidates.filter(row => extractor(row) || held.has(Number(row.id)));
+ const claims = new Set(input.rows.map(row => row.fact));
+ const retire = candidates.filter(row => extractor(row) || held.has(Number(row.id)) || claims.has(row.fact));
const outcome = await publishFenceGeneration(tx, { kind: FACT_FENCE_KIND, sourceId: input.sourceId, slug: input.slug, read: input.read,
items: factFenceItems(input.rows), retire: retire.map(factRetireItem), writer: input.writer });
return { ...outcome, retiring: retire.length, retireIds: retire.map(row => Number(row.id)),
diff --git a/src/core/repair/unwithdrawn-facts.ts b/src/core/repair/unwithdrawn-facts.ts
index 1924133608..c3f38b51d5 100644
--- a/src/core/repair/unwithdrawn-facts.ts
+++ b/src/core/repair/unwithdrawn-facts.ts
@@ -14,7 +14,9 @@
* - excluded (listed, never restored): the page is missing or deleted; the fact was superseded or withdrawn
* (`fact_withdrawals`); a fence held it (a fact_fence generation recorded it, or the page or a stored version of it
* carries it at the same row number, claim and visibility: a genuine withdrawal); an active fact with the same
- * text, visibility and entity is on the page; or another candidate with the same text is restored instead.
+ * text and entity is on the page, at any visibility; another candidate with the same text is restored instead; or
+ * the brain is unmanaged, whose extract_facts reconcile retires a row its fence lacks as drift and would retire a
+ * restored row again.
* - ambiguous (restored only with `--include-ambiguous` and that preview's hash): the page's version history has a
* gap (pruned, or an import that consumed several commits) or was not read whole, so an earlier fence holding the
* row cannot be ruled out.
@@ -22,8 +24,8 @@
*
* The preview binds each page's revision. The apply restores exactly the approved set under the page key: a managed
* brain publishes one database-only `managed_maintenance_restore_unwithdrawn_facts` request per page bound to the
- * previewed revision; an unmanaged (or repo-less) brain checks the revision and writes in one page-locked maintenance
- * transaction. A changed page refuses whole (`changed_since_preview`); each fact is reclassified and restored only when
+ * previewed revision; on an unmanaged (or repo-less) brain, where nothing is restorable, an approved set from a preview
+ * taken while it was managed is reclassified in one page-locked maintenance transaction after the revision check. A changed page refuses whole (`changed_since_preview`); each fact is reclassified and restored only when
* its class and evidence are unchanged. A restored fact keeps its id and gets back its recorded lifecycle (`expired_at`,
* `valid_until`, `superseded_by`, consolidation marks) and its row number, or a fresh number above the page's rows
* when a fence row took it. No page is rewritten; the fix keeps restored rows active on later writes.
@@ -107,7 +109,7 @@ export async function classifyUnwithdrawnFacts(db: BrainEngine, sourceIds: strin
EXISTS (SELECT 1 FROM fact_withdrawals w WHERE w.source_id = f.source_id AND w.visibility = f.visibility
AND w.fact_hash IN (gbrain_fact_fingerprint(f.fact), gbrain_fact_fingerprint_v1(f.fact))
AND (w.subject = '*' OR w.subject = f.entity_slug)) AS withdrawn,
- EXISTS (SELECT 1 FROM facts a WHERE a.source_id = f.source_id AND a.visibility = f.visibility AND a.source_markdown_slug = r.slug
+ EXISTS (SELECT 1 FROM facts a WHERE a.source_id = f.source_id AND a.source_markdown_slug = r.slug
AND a.expired_at IS NULL AND gbrain_fact_fingerprint(a.fact) = gbrain_fact_fingerprint(f.fact)
AND a.entity_slug IS NOT DISTINCT FROM f.entity_slug) AS active_duplicate
FROM retired r
@@ -129,7 +131,8 @@ export async function classifyUnwithdrawnFacts(db: BrainEngine, sourceIds: strin
prior: current ? await pageFenceRowKeys(db, current, row.slug, row.source_id) : null,
rows: page.map(other => ({ id: Number(other.id), row_num: Number(other.preimage.row_num), fact: other.preimage.fact, visibility: other.preimage.visibility })) }));
}
- const base = rows.map(row => classify(row, evidence.get(`${row.source_id}\u0000${row.slug}`)));
+ const managed = await managedPersistenceEnabled(db);
+ const base = rows.map(row => classify(row, evidence.get(`${row.source_id}\u0000${row.slug}`), managed));
const key = (row: CandidateRow) => JSON.stringify([row.source_id, row.slug, row.visibility, row.entity_slug, row.fingerprint]);
const representative = new Map<string, number>();
for (const klass of ['evidenced', 'ambiguous'] as const) rows.forEach((row, i) => { if (base[i]![0] === klass && !representative.has(key(row))) representative.set(key(row), i); });
@@ -141,13 +144,14 @@ export async function classifyUnwithdrawnFacts(db: BrainEngine, sourceIds: strin
});
}
-function classify(row: CandidateRow, evidence: { held: Set<number>; complete: boolean } | undefined): [UnwithdrawnFactClass, string] {
+function classify(row: CandidateRow, evidence: { held: Set<number>; complete: boolean } | undefined, managed: boolean): [UnwithdrawnFactClass, string] {
if (row.page_id === null || row.page_deleted || !evidence) return ['excluded', 'page_missing'];
if (row.superseded) return ['excluded', 'superseded'];
if (row.withdrawn) return ['excluded', 'withdrawn'];
if (row.expired_at !== row.retired_at) return ['excluded', 'changed_since_retirement'];
if (evidence.held.has(Number(row.id))) return ['excluded', 'fence_held'];
if (row.active_duplicate) return ['excluded', 'active_duplicate'];
+ if (!managed) return ['excluded', 'unmanaged_reconcile'];
if (row.history_gap) return ['ambiguous', 'version_history_gap'];
if (!evidence.complete) return ['ambiguous', 'version_history_unread'];
return ['evidenced', 'never_in_fence'];
@@ -161,6 +165,7 @@ const DETAILS: Record<string, string> = {
fence_held: 'a fence of the page held it, so an edit of the fence withdrew it',
active_duplicate: 'an active fact with the same text and entity is already on the page',
duplicate_candidate: 'another candidate of the page with the same text and entity is restored instead',
+ unmanaged_reconcile: "this brain is unmanaged: its extract_facts reconcile treats a numbered row the page's fence lacks as drift and would retire a restored row again",
version_history_gap: "the page's version history has a gap, so an earlier fence holding it cannot be ruled out",
version_history_unread: "the page has more stored versions than one preview reads, so an earlier fence holding it cannot be ruled out",
};
diff --git a/test/fence-first-generation-8819.test.ts b/test/fence-first-generation-8819.test.ts
index 86a052a523..d007976050 100644
--- a/test/fence-first-generation-8819.test.ts
+++ b/test/fence-first-generation-8819.test.ts
@@ -123,6 +123,31 @@ describe('#8819 first managed facts-fence generation', () => {
});
}, 120_000);
+ test(`[${backend}] a fence row restating a kept row's claim at another visibility retires the kept row, so no wider copy stays active`, async () => {
+ await managedSource(databaseUrl, async s => {
+ await seedPage(s, FACTS_FENCE(FOUNDED), [[1, 'Alice founded acme-example', 'chat']]);
+ await s.engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, row_num, source_markdown_slug)
+ VALUES ($1, $2, 'Alice plays chess', 'fact', 'world', 'mcp:put_page', 2, $2)`, [s.sourceId, SLUG]);
+ }, async ({ engine, sourceId, put }) => {
+ await put(SLUG, PERSON('Alice Example', FACTS_FENCE([FOUNDED, CHESS].join('\n'))));
+ expect(await engine.executeRaw('SELECT visibility FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 AND fact=$3 AND expired_at IS NULL',
+ [sourceId, SLUG, 'Alice plays chess'])).toEqual([{ visibility: 'private' }]);
+ });
+ }, 120_000);
+
+ test(`[${backend}] the extract_facts reconcile retires a never-held row whose claim the fence restates at another number`, async () => {
+ await managedSource(databaseUrl, async s => {
+ await s.put(SLUG, PERSON('Alice Example', FACTS_FENCE([FOUNDED, ROW(4, 'Alice plays chess')].join('\n'))));
+ await seedPage(s, FACTS_FENCE([FOUNDED, ROW(4, 'Alice plays chess')].join('\n')), [[1, 'Alice founded acme-example', 'chat'], [4, 'Alice plays chess', 'chat']]);
+ await s.engine.executeRaw(`INSERT INTO facts (source_id, entity_slug, fact, kind, visibility, source, row_num, source_markdown_slug)
+ VALUES ($1, $2, 'Alice plays chess', 'fact', 'world', 'mcp:put_page', 2, $2)`, [s.sourceId, SLUG]);
+ }, async ({ engine, sourceId }) => {
+ await runExtractFacts(engine, { sourceId });
+ expect(await engine.executeRaw('SELECT visibility, row_num FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 AND fact=$3 AND expired_at IS NULL',
+ [sourceId, SLUG, 'Alice plays chess'])).toEqual([{ visibility: 'private', row_num: 4 }]);
+ });
+ }, 120_000);
+
test(`[${backend}] the extract_facts reconcile keeps rows the fence never held and still retires a withdrawn one`, async () => {
await managedSource(databaseUrl, async s => {
await s.put(SLUG, PERSON('Alice Example', FACTS_FENCE([FOUNDED, CHESS, ROW(5, 'Alice ran a marathon')].join('\n'))));
diff --git a/test/repair-unwithdrawn-facts-8819.test.ts b/test/repair-unwithdrawn-facts-8819.test.ts
index 65702bf36b..ea62ca7eb7 100644
--- a/test/repair-unwithdrawn-facts-8819.test.ts
+++ b/test/repair-unwithdrawn-facts-8819.test.ts
@@ -4,8 +4,9 @@
* Protects: facts a facts-fence generation retired although no fence of their page held them come back with their
* original ids and lifecycle, also when that generation was the page's first (no predecessor to restore); a row a
* stored version's fence held (a genuine withdrawal) is never restored; the apply restores exactly the previewed set,
- * bound to the page revision the preview saw, so a page written since restores nothing; a managed brain and an
- * unmanaged brain with a database-only page (no repository) both restore; doctor names the lane and clears after it.
+ * bound to the page revision the preview saw, so a page written since restores nothing; an unmanaged brain (a
+ * database-only page, no repository) lists nothing restorable, since its extract_facts reconcile would retire a restored
+ * row again; doctor names the lane and clears after it.
* Seam: the pre-fix projection's retirement is reproduced by its effect, as it ran: a fact_fence generation recorded
* through publishFenceGeneration with each row's before-state, and the rows expired and detached in that transaction.
*/
@@ -19,6 +20,7 @@ import { publishFenceGeneration, readFenceBlocks, FACT_FENCE_KIND } from '../src
import { factFenceItems, factPreimages, factRetireItem } from '../src/core/generations/adapters/fact-rows.ts';
import { unwithdrawnFactsCheck } from '../src/commands/doctor/checks/unwithdrawn-facts.ts';
import { isolatedSharedSkillsEngine } from './helpers/shared-skills-engine.ts';
+import { runExtractFacts } from '../src/core/cycle/extract-facts.ts';
const SLUG = 'people/alice-example';
const ROW = (n: number, claim: string) => `| ${n} | ${claim} | fact | 1.0 | private | medium | 2020-01-01 | | chat | |`;
@@ -68,6 +70,32 @@ async function seed(s: ManagedSource): Promise<{ chess: number; lisbon: number;
return ids;
}
+/**
+ * A managed brain's page whose fence holds row 1, its fact ledger cleared and row 1 attached; a segmented one also has a
+ * body-less stored version. `seed` writes its rows before the brain turns managed (raw fact writes are refused after);
+ * `run` gets what it returned.
+ */
+async function managedPage<T>(databaseUrl: string | undefined, seed: (engine: BrainEngine, sourceId: string) => Promise<T>,
+ run: (engine: BrainEngine, sourceId: string, seeded: T) => Promise<void>, segmented = false): Promise<void> {
+ let seeded: T;
+ await managedSource(databaseUrl, async s => {
+ await s.put(SLUG, PERSON('Alice Example', FACTS_FENCE(FOUNDED)));
+ await s.engine.executeRaw("DELETE FROM derived_generations WHERE source_id=$1 AND kind='fact_fence'", [s.sourceId]);
+ await s.engine.executeRaw('DELETE FROM facts WHERE source_id=$1 AND source_markdown_slug=$2', [s.sourceId, SLUG]);
+ if (segmented) await s.engine.executeRaw(`INSERT INTO page_versions (page_id, compiled_truth, timeline, body_storage, body_generation)
+ SELECT id, NULL, NULL, 'segmented', 1 FROM pages WHERE source_id=$1 AND slug=$2`, [s.sourceId, SLUG]);
+ await factRow(s.engine, s.sourceId, 1, 'Alice founded acme-example', 'chat');
+ seeded = await seed(s.engine, s.sourceId);
+ }, ({ engine, sourceId }) => run(engine, sourceId, seeded));
+}
+
+/** Seeds one retired put_page row, 'Alice plays chess' at row 2. */
+async function retiredChess(engine: BrainEngine, sourceId: string): Promise<number> {
+ const chess = await factRow(engine, sourceId, 2, 'Alice plays chess');
+ await prefixRetire(engine, sourceId, [chess]);
+ return chess;
+}
+
describe('gbrain repair unwithdrawn-facts (#8819)', () => {
for (const { backend, databaseUrl } of pathologicalArms()) {
test(`[${backend}] managed: restores first-generation retirements no fence withdrew, never a withdrawn one, bound to the previewed revision`, async () => {
@@ -101,7 +129,7 @@ describe('gbrain repair unwithdrawn-facts (#8819)', () => {
}
for (const { backend, databaseUrl } of pathologicalArms()) {
- test(`[${backend}] unmanaged brain, database-only page: the same restore with no repository`, async () => {
+ test(`[${backend}] unmanaged brain, database-only page: nothing is restorable, since its reconcile would retire a restored row again`, async () => {
const { engine, close } = await isolatedSharedSkillsEngine(databaseUrl);
try {
await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
@@ -111,30 +139,23 @@ describe('gbrain repair unwithdrawn-facts (#8819)', () => {
const chess = await factRow(engine, sourceId, 2, 'Alice plays chess');
await prefixRetire(engine, sourceId, [chess]);
const preview = await repair(engine, sourceId);
- expect(preview.listing!.map(row => row.class)).toEqual(['evidenced']);
- expect((await repair(engine, sourceId, { expect: hashOf(preview) })).applied).toBe(1);
- expect(await state(engine, [chess])).toEqual([[chess, 2, true]]);
+ expect(preview.listing!.map(row => row.class)).toEqual(['excluded:unmanaged_reconcile']);
+ expect((await unwithdrawnFactsCheck(engine, [sourceId])).status).toBe('ok');
+ await runExtractFacts(engine, { sourceId, slugs: [SLUG] });
+ expect(await state(engine, [chess])).toEqual([[chess, null, false]]);
+ expect((await unwithdrawnFactsCheck(engine, [sourceId])).status).toBe('ok');
} finally { await close(); }
}, 120_000);
}
for (const { backend, databaseUrl } of pathologicalArms()) {
test(`[${backend}] a stored version kept without a body (a segmented snapshot) leaves the row ambiguous, never restored by default`, async () => {
- const { engine, close } = await isolatedSharedSkillsEngine(databaseUrl);
- try {
- await engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
- const sourceId = 'default';
- await engine.putPage(SLUG, { type: 'person', title: 'Alice Example', compiled_truth: FACTS_FENCE(FOUNDED) }, { sourceId });
- await engine.executeRaw(`INSERT INTO page_versions (page_id, compiled_truth, timeline, body_storage, body_generation)
- SELECT id, NULL, NULL, 'segmented', 1 FROM pages WHERE source_id=$1 AND slug=$2`, [sourceId, SLUG]);
- await factRow(engine, sourceId, 1, 'Alice founded acme-example', 'chat');
- const chess = await factRow(engine, sourceId, 2, 'Alice plays chess');
- await prefixRetire(engine, sourceId, [chess]);
+ await managedPage(databaseUrl, retiredChess, async (engine, sourceId, chess) => {
const preview = await repair(engine, sourceId);
expect(preview.listing!.map(row => row.class)).toEqual(['ambiguous']);
expect((await unwithdrawnFactsCheck(engine, [sourceId])).details).toMatchObject({ evidenced: 0, ambiguous: 1 });
expect(await state(engine, [chess])).toEqual([[chess, null, false]]);
- } finally { await close(); }
+ }, true);
}, 120_000);
}
});
@@ -142,24 +163,12 @@ describe('gbrain repair unwithdrawn-facts (#8819)', () => {
/*
* Coverage pass (/ship 8830 Step 7), generated by Capy.
* Value: protects=classify never restores superseded, withdrawn, changed_since_retirement, active_duplicate or duplicate_candidate rows; fails_when=a classify guard is dropped or reordered; why_new=existing tests only reach fence_held and ambiguous; seam=none; no_claim=page_missing (needs a second page's generation; not seeded here)
- * Value: protects=--apply without --expect is invalid_params, an include_ambiguous mismatch is preview_changed, a taken row_num moves to max+1; fails_when=the expect guard, mismatch check or row_num CASE regresses; why_new=no test applies ambiguous rows or a taken row_num; seam=none; no_claim=managed-brain path of these branches (unmanaged PGLite/Postgres only)
+ * Value: protects=--apply without --expect is invalid_params, an include_ambiguous mismatch is preview_changed, a taken row_num moves to max+1; fails_when=the expect guard, mismatch check or row_num CASE regresses; why_new=no test applies ambiguous rows or a taken row_num; seam=none; no_claim=unmanaged brains, where nothing is restorable (the unmanaged test above)
*/
describe('gbrain repair unwithdrawn-facts (#8819) coverage pass', () => {
- async function unmanagedPage(databaseUrl: string | undefined, segmented = false) {
- const handle = await isolatedSharedSkillsEngine(databaseUrl);
- await handle.engine.executeRaw('UPDATE persistence_brain SET enabled=false WHERE singleton=1');
- await handle.engine.putPage(SLUG, { type: 'person', title: 'Alice Example', compiled_truth: FACTS_FENCE(FOUNDED) }, { sourceId: 'default' });
- if (segmented) await handle.engine.executeRaw(`INSERT INTO page_versions (page_id, compiled_truth, timeline, body_storage, body_generation)
- SELECT id, NULL, NULL, 'segmented', 1 FROM pages WHERE source_id='default' AND slug=$1`, [SLUG]);
- await factRow(handle.engine, 'default', 1, 'Alice founded acme-example', 'chat');
- return handle;
- }
-
for (const { backend, databaseUrl } of pathologicalArms()) {
test(`[${backend}] exclusions: superseded, withdrawn, changed, active duplicate and duplicate candidate are listed, never restored`, async () => {
- const { engine, close } = await unmanagedPage(databaseUrl);
- try {
- const s = 'default';
+ await managedPage(databaseUrl, async (engine, s) => {
const ids = { chess: await factRow(engine, s, 2, 'Alice plays chess'), sailsA: await factRow(engine, s, 3, 'Alice sails'), sailsB: await factRow(engine, s, 4, 'Alice sails'),
superseded: await factRow(engine, s, 5, 'Alice owns a boat'), withdrawn: await factRow(engine, s, 6, 'Alice likes jazz'),
changed: await factRow(engine, s, 7, 'Alice speaks French'), activeDup: await factRow(engine, s, 8, 'Alice runs') };
@@ -168,6 +177,8 @@ describe('gbrain repair unwithdrawn-facts (#8819) coverage pass', () => {
await engine.executeRaw('UPDATE facts SET superseded_by=$2 WHERE id=$1', [ids.superseded, ids.chess]);
await engine.executeRaw("INSERT INTO fact_withdrawals (source_id, visibility, fact_hash) SELECT source_id, visibility, gbrain_fact_fingerprint(fact) FROM facts WHERE id=$1", [ids.withdrawn]);
await engine.executeRaw("UPDATE facts SET expired_at = expired_at + interval '1 second' WHERE id=$1", [ids.changed]);
+ return ids;
+ }, async (engine, s, ids) => {
const preview = await repair(engine, s);
expect(preview.listing!.map(row => [row.item, row.class])).toEqual([
[`${s}:${SLUG}#${ids.chess}`, 'evidenced'], [`${s}:${SLUG}#${ids.sailsA}`, 'evidenced'], [`${s}:${SLUG}#${ids.sailsB}`, 'excluded:duplicate_candidate'],
@@ -176,42 +187,70 @@ describe('gbrain repair unwithdrawn-facts (#8819) coverage pass', () => {
expect((await repair(engine, s, { expect: hashOf(preview) })).applied).toBe(1);
const active = (await state(engine, Object.values(ids))).filter(([, , on]) => on).map(([id]) => id);
expect(active).toEqual([ids.chess, ids.sailsA]);
- } finally { await close(); }
+ });
}, 120_000);
}
for (const { backend, databaseUrl } of pathologicalArms()) {
test(`[${backend}] --apply needs --expect; a taken row number moves the restored row to max+1`, async () => {
- const { engine, close } = await unmanagedPage(databaseUrl);
- try {
- const chess = await factRow(engine, 'default', 2, 'Alice plays chess');
- await prefixRetire(engine, 'default', [chess]);
- await factRow(engine, 'default', 2, 'Alice paints');
- const scope = await resolveRepairScope(engine, 'default');
- await expect((await repairRunner(engine, { apply: true, noEmbed: true, logger: quiet })).run('unwithdrawn-facts', scope, { explicit: true, sourceFlag: 'default' }))
+ await managedPage(databaseUrl, async (engine, sourceId) => {
+ const chess = await retiredChess(engine, sourceId);
+ await factRow(engine, sourceId, 2, 'Alice paints');
+ return chess;
+ }, async (engine, sourceId, chess) => {
+ const scope = await resolveRepairScope(engine, sourceId);
+ await expect((await repairRunner(engine, { apply: true, noEmbed: true, logger: quiet })).run('unwithdrawn-facts', scope, { explicit: true, sourceFlag: sourceId }))
.rejects.toMatchObject({ code: 'invalid_params' });
- const preview = await repair(engine, 'default');
- expect((await repair(engine, 'default', { expect: hashOf(preview) })).applied).toBe(1);
+ const preview = await repair(engine, sourceId);
+ expect((await repair(engine, sourceId, { expect: hashOf(preview) })).applied).toBe(1);
expect(await state(engine, [chess])).toEqual([[chess, 3, true]]);
- const [{ n }] = await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM facts WHERE source_id='default' AND source_markdown_slug=$1 AND expired_at IS NULL AND row_num=2", [SLUG]);
+ const [{ n }] = await engine.executeRaw<{ n: number }>("SELECT count(*)::int AS n FROM facts WHERE source_id=$2 AND source_markdown_slug=$1 AND expired_at IS NULL AND row_num=2", [SLUG, sourceId]);
expect(Number(n)).toBe(1);
- } finally { await close(); }
+ });
}, 120_000);
}
for (const { backend, databaseUrl } of pathologicalArms()) {
test(`[${backend}] --include-ambiguous restores ambiguous rows only under the matching flag`, async () => {
- const { engine, close } = await unmanagedPage(databaseUrl, true);
- try {
- const chess = await factRow(engine, 'default', 2, 'Alice plays chess');
- await prefixRetire(engine, 'default', [chess]);
- const preview = await repair(engine, 'default', { includeAmbiguous: true });
+ await managedPage(databaseUrl, retiredChess, async (engine, sourceId, chess) => {
+ const preview = await repair(engine, sourceId, { includeAmbiguous: true });
expect(preview.listing!.map(row => row.class)).toEqual(['ambiguous']);
- await expect(repair(engine, 'default', { expect: hashOf(preview) })).rejects.toMatchObject({ code: 'preview_changed' });
+ await expect(repair(engine, sourceId, { expect: hashOf(preview) })).rejects.toMatchObject({ code: 'preview_changed' });
expect(await state(engine, [chess])).toEqual([[chess, null, false]]);
- expect((await repair(engine, 'default', { expect: hashOf(preview), includeAmbiguous: true })).applied).toBe(1);
+ expect((await repair(engine, sourceId, { expect: hashOf(preview), includeAmbiguous: true })).applied).toBe(1);
expect(await state(engine, [chess])).toEqual([[chess, 2, true]]);
- } finally { await close(); }
+ }, true);
+ }, 120_000);
+ }
+ for (const { backend, databaseUrl } of pathologicalArms()) {
+ test(`[${backend}] a fact withdrawn after the preview stays retired; the rest of the page is restored`, async () => {
+ await managedPage(databaseUrl, async (engine, sourceId) => {
+ const ids = { chess: await factRow(engine, sourceId, 2, 'Alice plays chess'), lisbon: await factRow(engine, sourceId, 3, 'Alice lives in Lisbon') };
+ await prefixRetire(engine, sourceId, [ids.chess, ids.lisbon]);
+ return ids;
+ }, async (engine, sourceId, { chess, lisbon }) => {
+ const preview = await repair(engine, sourceId);
+ expect(preview.listing!.map(row => row.class)).toEqual(['evidenced', 'evidenced']);
+ await engine.executeRaw("INSERT INTO fact_withdrawals (source_id, visibility, fact_hash) SELECT source_id, visibility, gbrain_fact_fingerprint(fact) FROM facts WHERE id=$1", [chess]);
+ expect((await repair(engine, sourceId, { expect: hashOf(preview) })).applied).toBe(1);
+ expect(await state(engine, [chess, lisbon])).toEqual([[chess, null, false], [lisbon, 3, true]]);
+ });
+ }, 120_000);
+ }
+
+ for (const { backend, databaseUrl } of pathologicalArms()) {
+ test(`[${backend}] a retired row whose claim is active on the page at another visibility is excluded as an active duplicate`, async () => {
+ await managedPage(databaseUrl, async (engine, sourceId) => {
+ const chess = await factRow(engine, sourceId, 2, 'Alice plays chess');
+ await engine.executeRaw("UPDATE facts SET visibility='world' WHERE id=$1", [chess]);
+ await prefixRetire(engine, sourceId, [chess]);
+ await factRow(engine, sourceId, 2, 'Alice plays chess');
+ return chess;
+ }, async (engine, sourceId, chess) => {
+ const preview = await repair(engine, sourceId);
+ expect(preview.listing!.map(row => row.class)).toEqual(['excluded:active_duplicate']);
+ expect(await state(engine, [chess])).toEqual([[chess, null, false]]);
+ });
}, 120_000);
}
/*
@@ -221,15 +260,15 @@ describe('gbrain repair unwithdrawn-facts (#8819) coverage pass', () => {
for (const { backend, databaseUrl } of pathologicalArms()) {
test(`[${backend}] a deleted page excludes its retirements; a version-history gap makes them ambiguous`, async () => {
for (const [column, klass] of [['deleted_at', 'excluded:page_missing'], ['version_history_gap_at', 'ambiguous']] as const) {
- const { engine, close } = await unmanagedPage(databaseUrl);
- try {
- const chess = await factRow(engine, 'default', 2, 'Alice plays chess');
- await prefixRetire(engine, 'default', [chess]);
- await engine.executeRaw(`UPDATE pages SET ${column}=now() WHERE source_id='default' AND slug=$1`, [SLUG]);
- const preview = await repair(engine, 'default');
+ await managedPage(databaseUrl, async (engine, sourceId) => {
+ const chess = await retiredChess(engine, sourceId);
+ await engine.executeRaw(`UPDATE pages SET ${column}=now() WHERE source_id=$2 AND slug=$1`, [SLUG, sourceId]);
+ return chess;
+ }, async (engine, sourceId, chess) => {
+ const preview = await repair(engine, sourceId);
expect(preview.listing!.map(row => row.class)).toEqual([klass]);
expect(await state(engine, [chess])).toEqual([[chess, null, false]]);
- } finally { await close(); }
+ });
}
}, 120_000);
}