Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
WIP G4 wave 2: docs, behavior notes, inventories for git-first forget
garrytana632bf4d4735
diff --git a/docs/architecture/canonical-writers.tsv b/docs/architecture/canonical-writers.tsvindex facebef3f8..865192c236 100644--- a/docs/architecture/canonical-writers.tsv+++ b/docs/architecture/canonical-writers.tsv@@ -115,7 +115,8 @@ src/core/page-state/image-seal.ts 1 projection The explicit image seal (#6803) ssrc/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.-src/core/persistence/memory-mutations.ts 1 coordinator Publication is transaction-scoped under admitted authority, source/page guards and revision checks.+src/core/persistence/memory-mutations.ts 0 coordinator Submits remember and forget as admitted requests; the coordinator publishes them (memory-prepare.ts, forget-prepare.ts) under admitted authority, source/page guards and revision checks.+src/core/persistence/forget-prepare.ts 1 coordinator forget/forget_fact preparer (GBRA-190 G4): every page file carrying the claim is struck and published in one coordinated publication (one recovery record, one Git commit) before its transaction writes the ledger row, the expiries and the forget reason on the fact row.src/core/persistence/memory-prepare.ts 2 coordinator Publication is transaction-scoped under admitted authority, source/page guards and revision checks.src/core/persistence/page-prepare.ts 13 coordinator Publication, including versioned tombstone restoration, is transaction-scoped under admitted authority, source/page guards and revision checks; the sixth SQL site reconciles trusted first-write provenance with prepared canonical frontmatter and the seventh records canonical source_path in that same guarded transaction. Identical canonical no-ops do not heal physical metadata. The added local-CLI purge deletePage call runs in the prepared publication callback after recorded-artifact removal, under the same source/page identity, revision and durable authority guards as receipt completion; permanent journal IDs and outcomes survive the hard delete. The ninth site pins an inferred slug_root_mode on sources in the same publication transaction as the first bound origin. Its importFromContent calls carry prepare and run inside the coordinator publication. The segmented tag flip (prepareSegmentedTagMutation: createVersion, removeTag/addTag and the content_hash update) runs in the prepared publication callback under the same admitted authority, source/page guards and revision check as the inline tag write.src/core/persistence/segmented-apply.ts 2 coordinator Wave B segmented apply inside the page write's publication transaction: sealSegmentedPage stamps only projection state (text_projection_revision, chunker_version, search_vector); demoteSegmentedPage turns a segmented row inline with an empty body that the same transaction's inline write fills, under the request's revision and page guards.diff --git a/docs/architecture/system-of-record.md b/docs/architecture/system-of-record.mdindex 9d3d486c2d..e33379a287 100644--- a/docs/architecture/system-of-record.md+++ b/docs/architecture/system-of-record.md@@ -283,7 +283,7 @@ or a physical projection that leaves attribution untouched):- `src/core/persistence/grandfather.ts` (2): request preparer.- `src/core/persistence/links-maintenance.ts` (1): coordinated maintenance.- `src/core/persistence/loop-fact-retirement.ts` (1): request preparer.-- `src/core/persistence/memory-mutations.ts` (1): `forget` inside its request's coordinated write.+- `src/core/persistence/forget-prepare.ts` (1): `forget` / `forget_fact` request preparer; the struck page files publish first, then the withdrawal's rows in the same publication.- `src/core/persistence/memory-prepare.ts` (2): `remember` request preparer; the fence row and its facts row go through `prepareFenceFactAppend`.- `src/core/persistence/page-append.ts` (1): segmented `append_page` / `edit_page` request preparer; the splice versions the page inside its request's publication.- `src/core/persistence/page-prepare.ts` (12): page request preparer (including the restore of a segmented page over 24 MiB, which flips `deleted_at` without re-serializing, and the tag flip of a segmented page, which versions it and changes its tag rows and `content_hash` without re-serializing).diff --git a/docs/guides/memory-boundaries.md b/docs/guides/memory-boundaries.mdindex f7bbe88078..c715ca48ae 100644--- a/docs/guides/memory-boundaries.md+++ b/docs/guides/memory-boundaries.md@@ -229,10 +229,12 @@ dies).`purge_fact` on a page stored in segments, on a source backed by files,rewrite its canonical file as they rewrite an inline page's: the file shows therow forgotten, or loses the purged row, and holds the bytes `gbrain export`-writes for the page; the withdrawal's Git effect commits it. The file is-streamed from the segments into its staging file, one segment at a time, and-never held whole. Its recovery record names that staging file by path and-SHA-256 instead of holding the file, so the mirror reserves the file once in+writes for the page. The file is streamed from the segments into its staging+file, one segment at a time, and never held whole. `forget` and `forget_fact`+publish the struck file in their own write, before the withdrawal commits;+`purge_fact`'s mirror writes it afterwards and its Git effect commits it. The+mirror's recovery record names that staging file by path and SHA-256 instead+of holding the file, so the mirror reserves the file once inthe recovery budget. A mirror interrupted before, during or after writing thestaging file finishes on the writer's next pass: a staging file a crash cutshort is discarded and written again.@@ -410,6 +412,17 @@ and [isolated local backup guide](in-agent-setup.md#6-back-up-the-complete-localthe same source and visibility, and its row is struck in the page's Markdown.The text stays in the row, the file, page history and backups.+The struck rows are written first: every page file that carries the claim is+published in one write (one Git commit on a source that commits through+gbrain), and the withdrawal commits with it. A forget waits for the source's+writer like any other write, so while that writer is unavailable the forget is+accepted and pending, and the fact is still recalled. A brain rebuilt from Git+keeps the withdrawal: a sync or import from the owner's checkout, or a local+write, of a struck row dated in `valid_until` with a `forgotten:` context+records it again. A row like that arriving in a remote page write is only an+expired row; it withdraws nothing. A fact saved without an entity is a row of+the `memory/unattributed` page, so its withdrawal has a file too.+Automatic extraction (sync import, `put_page`, `extract_facts`, the sweep)skips a candidate whose exact claim was forgotten in that source and visibilityand still saves the other facts it found about the same entity; the entity anddiff --git a/docs/protocol/MEMORY_VERBS_v1.md b/docs/protocol/MEMORY_VERBS_v1.mdindex cd9d3682ed..a160fe31ce 100644--- a/docs/protocol/MEMORY_VERBS_v1.md+++ b/docs/protocol/MEMORY_VERBS_v1.md@@ -311,7 +311,9 @@ A claim that was forgotten is refused with `invalid_params` and the messageprefix `fact_withdrawn`: remembering the same text again does not restore it,and a claim forgotten without an entity is withdrawn for every entity. To linka fact saved without an entity, do not forget it; remember it with `entity`-and `replaces` set to its id.+and `replaces` set to its id. In gbrain, a fact saved without an entity is a+row of the `memory/unattributed` page's `## Facts` table, created on first+use; linking it strikes that row in the same write.#### remember withdrawn refusal detail (additive)@@ -716,6 +718,16 @@ says to keep them, or to forget them first to withdraw the claim everywhere.A forget never withdraws an active fact the caller cannot read; when onewould be reached, the refusal keeps the `claim_linked:` prefix and names no fact.+#### forget publishes like a page write (additive note)++In gbrain, a forget is a write of the pages that carry the claim: each row is+struck (`~~claim~~`, a `valid_until` date and `forgotten: <reason>`) and every+such file is published, in one commit, before the withdrawal commits. It is+admitted and published like `remember`, so when the source's writer cannot+publish yet the call returns the pending-write error with a receipt, and the+fact stays recallable until the withdrawal publishes. The response shape is+unchanged.+#### forget and purge (additive note)`forget` keeps this contract: it expires, never deletes. Removing a claim'sdiff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.tsindex 1e72ef858b..7d6d51c393 100644--- a/src/core/behavior-change-notice.ts+++ b/src/core/behavior-change-notice.ts@@ -1304,6 +1304,9 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;{ since: '0.60.460.0', text: 'Dream consolidation on a managed brain now closes a fenced fact in its page: the closing `valid_until` is written into the fact\'s row in the entity page\'s `## Facts` fence, published with the take, and the database row takes its value from that cell, so a later sync or re-import keeps the fact closed. Before, only the database row was closed and the next re-import of the page reopened it. A fact with no fence row is still closed in the database. A fenced fact whose fence row is on another page is left open. Facts an earlier release closed in the database only are not changed (GBRA-190).' },{ since: 'TBD', text: 'An `extract_facts` run whose empty-fence guard holds a page (a fact row of it is not in the page\'s `## Facts` table yet) is now booked in `gbrain extract status` and doctor `extract_health` as a completed round instead of an `integrity_guard` halt. The guard holds only that page while every other page reconciles, so one held page no longer reads as a facts halt on every cycle; doctor `fence_integrity` still names the held rows (GBRA-190).' },{ since: 'TBD', text: 'Doctor `fence_integrity` now points a legacy fact row that copies a claim its page\'s `## Facts` table already carries (`duplicate_claim`) at the read-only `gbrain repair duplicate-facts --source <id>` preview, which keeps the fence row and supersedes the copy onto it after the user agrees. Before, every unadoptable row got only a report with no command (GBRA-190).' },+ { since: 'TBD', text: '`forget` and `forget_fact` now write the page files first: every page whose `## Facts` table carries the claim has its row struck (`~~claim~~`, a `valid_until` date and `forgotten: <reason>`) and all of them publish in one write, one Git commit on a source that commits through gbrain, before the withdrawal commits in the same transaction. Before, the database withdrew the fact at once and a later effect rewrote the files. A forget now waits for the source\'s writer like `remember`: while that writer is unavailable it returns the pending-write receipt and the fact is still recalled until it publishes. The page history gets one change for the withdrawal instead of a second materialization change. Withdrawals queued by an older release still drain (GBRA-190).' },+ { since: 'TBD', text: 'A fact remembered without an entity is now a row of the `memory/unattributed` page\'s `## Facts` table (created on first use) instead of a database-only row, so it is in Git, `recall` and search can return that page, and a forget of it strikes the row there. Remembering the same claim with an entity links it and strikes the `memory/unattributed` row in the same write. No placeholder entity page is created (GBRA-190).' },+ { since: 'TBD', text: 'A brain rebuilt from Git keeps its withdrawals: a sync or import from the owner\'s checkout, or a local page write, of a struck `## Facts` row with a `valid_until` date and a `forgotten:` context records that withdrawal again (for the page\'s entity, or every entity on `memory/unattributed`), so the claim cannot be remembered again. The same row arriving in a remote page write only imports as an expired row and withdraws nothing; remote callers still withdraw through `forget` (GBRA-190).' },];/** The newest disclosed change's release: the notice id moves only when a release adds rows. */diff --git a/src/core/persistence/staging.ts b/src/core/persistence/staging.tsindex 1e8fbd8364..8257f4c1ff 100644--- a/src/core/persistence/staging.ts+++ b/src/core/persistence/staging.ts@@ -113,7 +113,8 @@ export function cleanupRecoveryStaging(record: StagedRecovery, opts: { keepBefor}/**- * Recovery's restoration of a version 3 record: the verified copy of the prior file is renamed over the canonical+ * Recovery's restoration of a file record whose prior is staged (`staging.before`, a prior over the single-string+ * ceiling): the verified copy of the prior file is renamed over the canonical* path with its recorded mode. A missing copy refuses (`unexpected_staging_bytes`): the bytes cannot be guessed.*/export function restoreBeforeStage(record: StagedRecovery & { mode: number | null }, boundary?: (phase: 'file_replaced' | 'directory_flushed') => void): void {diff --git a/test/trust-write-gate-drift.test.ts b/test/trust-write-gate-drift.test.tsindex d3383eac06..b5ed82bea5 100644--- a/test/trust-write-gate-drift.test.ts+++ b/test/trust-write-gate-drift.test.ts@@ -52,6 +52,7 @@ const EXEMPT: Record<string, string> = {'src/core/persistence/links-maintenance.ts': 'link extraction from stored page text','src/core/persistence/loop-fact-retirement.ts': 'expires a loop fact (lifecycle)','src/core/persistence/memory-mutations.ts': 'forget (lifecycle); remember is gated in memory-prepare.ts',+ 'src/core/persistence/forget-prepare.ts': 'forget (lifecycle): strikes withdrawn rows and records the withdrawal; it writes no new claim','src/core/repair/captured-facts.ts': 'owner repair of existing rows','src/core/repair/consolidate-ties.ts': 'owner repair reopening the validity of existing facts (lifecycle)','src/core/repair/duplicate-facts.ts': 'owner repair behind a preview hash: supersedes exact copies of an existing fact with its oldest row (expired_at, superseded_by; lifecycle, no new text); fenced copies are struck through put_page, which runs the gate',