Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
48.2 KB
Raw Blame

Key files: memory purge

Subsystem index. Read only the entries relevant to your change. Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG. User-facing contract: expire versus purge.

  • src/core/facts/purge.ts — submitPurgeFactMutation, the handler of the owner-only purge_fact op (gbrain forget <id> --purge). Refuses every caller whose ctx.remote !== false with trusted_local_only (purgeHostOnly, actor user, the exact host command). planFactPurge (read-only) computes the scope: every fact row with the same gbrain_fact_fingerprint in the fact's source, visibility and subject (the fact's entity_slug, '*' with all_subjects) except extraction outcome rows (outcomeMarkerSql; the receipt's fact probes, purgeCompletion and the restore replay skip them too, #7831), verbatim takes (facts.consolidated_into plus same-fingerprint takes on the subject's page), affected pages from discoverWithdrawalTargets, page_versions carrying the text, terminal request intents carrying it (findRequestsCarrying behind the purge:carrying_lookup seam; its 57014 is the typed purge_lookup_timeout, nothing planned or purged, pinned by test/fact-purge-lookup-timeout-6511.test.ts), derived rows from derivation_inputs, the fact's P8 review rows, and a revision digest. A dry run returns the receipt, confirm_token (fingerprint's first 8 hex) and expected_revision; a real run requires confirm === token and, when given, an unchanged revision. The journaled intent is {id, reason, all_subjects, fact_hash}, never claim text; replay by request id returns the stored outcome. One transaction in the global lock order: source FOR UPDATE (serializes with the guards' FOR SHARE), counters for the purge and every redacted request, admission, then inside withCoordinatedWrite: pending-publication refusal (purge_blocked_pending_recovery), intent redaction, page locks, derived rows hidden before evidence goes, fact_purges/take_purges tombstones, deletes (takes, review rows, open loops by fact id, take proposals by fingerprint, facts), core-notice base text nulled, page bodies rewritten through the purge overlay, chunks deleted, versions redacted in place, legacy query_cache cleared, and withdrawal-mirror/git/embedding effects with mode: 'purge' and commit_subject: gbrain: purge fact <hash8>. Chunks are rebuilt before acknowledging; similar_active is computed before deletion. Pinned by test/purge-fact.test.ts (both engines) and test/forget-purge-cli.test.ts; the segmented preimage version by test/large-pages/purge-fact-segmented-preimage.test.ts (inline twin parity, both engines). Segmented pages (Wave B): live bodies are rewritten fence by fence through rewriteLiveSegmentedFences (a new generation; only the rewritten occurrences' chunks change, an unsealed page is projected after commit), and each rewritten page gets the preimage version an inline page gets: a segmented version of the revision the flip moved off, read before the flip and referencing the new generation (the body a reader of that revision sees under the purge's tombstone, as the inline preimage is read), so no generation holding the claim stays pinned; retained generations are rebuilt through rewriteSegmentedGeneration; the plan (and its digest) also lists open, sealed or prepared stagings whose staged texts or parts hold the claim plus the queued requests whose body_ref names them (stagingsHoldingClaim, which also reads page_body_staging_texts; findRequestsHoldingStagings): the stagings are aborted with their parts deleted, the requests cancelled with purged_content (a running or recovering one refuses with purge_blocked_pending_recovery), and the segment texts no manifest row references any more are deleted in the same transaction, never left to GC (purgeSegmentStorage, which the restore-time replay also runs).

  • src/core/facts/purge-verify.ts — receipts and verification. verifyFactPurge runs one bounded adapter per store (row bound, per-statement statement_timeout, a total deadline; __setPurgeProbeLimitsForTests): swept stores report deleted, incomplete (still holds the claim) or unverified (bound hit); page-text stores report remaining text as out_of_scope: source_prose; every probed_reported inventory table is probed and listed; derived rows are retained_inactive; model-derived pages without edges are derived_legacy: unverified. On-disk: page files (canonical_markdown), a quarantined <file>.tmp carrying the claim is deleted, the facts write-failure log is reported. gitResidualCommits scans git log --all -p -- <page paths> output in-process (the pattern never enters argv; byte and time bounded) and lists commits; OUT_OF_REACH_RESIDUALS lead every receipt. Links, timeline entries and raw data that still carry the claim are named row by row (link:<id> <from> -> <to>, timeline:<id> <slug> <date>, raw_data:<id> <slug> <source>, up to 20); queued persistence_effects whose data, outcome or recovery carry it are reported; belief_events and fact_context get ledger reports. The vector probe returns same-model neighbours as paraphrase candidates and is never a gate. purgeCompletion derives committed | complete | incomplete from effects (failed or parked = incomplete), a fingerprint probe and the receipt, with exit codes 10/0/75. A segmented page or version is probed segment by segment (segmentedBodyContains, a needle split by a cut is found; row and time bounded) and reported with the page stores; page_segment_texts gets an exact-bytes probe (an unreferenced text holding the claim is incomplete, a referenced one out_of_scope); the page purge probes the texts its manifests referenced (PagePurgeContext.segmentShas).

  • src/core/belief/purge.ts — the purge half of the belief ledger (BELIEF_LEDGER.md 6.5). Every fact or page purge bumps sources.purge_epoch (bumpPurgeEpoch; an append prepared at an older epoch with preparedEpoch refuses belief_stale_preparation) and runs three passes inside the purge transaction: redactPurgedKeys (the purged keys, by claim_fp and page lifetime, keep skeletons: value, value_hash and prior_hash null, purged), redactCarryingFields (keyset batches of 1000 reading only the carrying fields of fact, take and link events, matched in JS by quotes over claimForms, never SQL lower()/strpos: each carrying field from CARRYING_FIELDS that quotes a purged claim, plain or fence-escaped, becomes REDACTION_MARKER(<purge request>) and is listed in redacted_fields; a later event's prior_hash naming the old hash names the new one) with registerLiveCarriers (a surviving row whose field quotes the claim enters belief_redactions with its field hash, so its next event writes the marker until an explicit owner edit sets a different value: publicationBeliefOptions marks ownerEdit only on a local put_page, edit_page, takes_update or takes_resolve with no internal intent kind, and append still needs OWNER_TIER_FLOOR) and, for a fact purge, registerVersionCarriers (the retained versions still quoting the claim, registered under the keys the backfill gives them). A claim shorter than 8 characters quotes a field only as a word in spaced scripts (ceo does not match herbaceous; CJK and markup still match), and appendDerivedHidden (one derived.hidden per key the derivation walk hid; readBeliefHistory then hides that key's earlier events and every backfill event of it). A page purge's claims come from pagePurgeClaims: the page's facts and takes, every retained version's fence rows and every claim in its lifetimes' events, unbounded. releaseSuppressedFields is the owner release trust confirm runs (belief_redactions.released_hash); every release, there or in an owner-edit append, appends one redaction.released (redactionReleasedDraft: fields, purge requests and released hashes, never the text) in the publication released_by names. The receipt's ledger block reports the counts and derived_walk; a truncated walk withholds certification of its coverage interval (coverage-report.ts). Purge-verify's ledger report is a JS keyset scan too: a missed carrying field is incomplete, another subject's recorded value quoting the claim is out_of_scope with field@key items. Seam: __setPurgeRedactionFaultForTests. Probes: test/belief-ledger-purge.test.ts (both engines).

  • src/core/belief/purge-mirror.ts — the text-free purge mirror <brain home>/.gbrain/purge-events.jsonl (0600, fsynced): an intent line before the purge commits (appendPurgeIntent; request, source and incarnation, scope, fingerprints, content hashes, lifetimes, epoch; never claim text; an unwritable mirror refuses the purge with the typed purge_mirror_unwritable, with or without a ledger) and a committed line after (appendPurgeCommitted, best effort; a page purge writes it from the coordinator's afterCommit, so it does not depend on the op handler finishing). restorePgliteBackup (gbrain backup restore --purge-mirror <absolute path> names a mirror other than the brain home's) replays every committed purge newer than the archive inside its transaction (replayPurgesInRestore: tombstones, row removal (a fact-scope replay rewrites page bodies and versions through rewritePageBodies / redactPageVersions, then runs purgeSegmentStorage with each claim's stagingsHoldingClaim; a page-scope replay deletes the page through deletePageWithSegments, so segment texts that held the purged content go in the replay, as in the purge), the three passes, the derived rows hidden again with derived.hidden cause restore_replay, one fact.purged/page.purged with cause restore_replay; a page-scope replay matches pages by content hash or lifetime, never by slug alone; an archive from before the ledger, no belief_events, replays tombstones and row removal and reports ledger: 'absent'; an intent whose request already has tombstones is skipped), records each as complete, partial (no restored row held the text, or the derivation walk could not run) or unverified (intent without committed line, not replayed), returns purge_replay in the receipt and adds a reconnect warning unless the state is none or complete; an unreadable mirror is unavailable. coverage.restored carries the outcome, which readRestorePurgeReplay reads back for the doctor. A Postgres restore runs gbrain beliefs replay-purges --archived-at <iso> (--purge-mirror <abs path> | --from-url-env <VAR>) [--apply] (src/commands/beliefs-replay-purges.ts; dry run by default: replayPurges runs the replay in a transaction that rolls back), whose database source purgeLinesFromDatabase rebuilds the intents from every pre-restore tombstone (not bounded by purged_at, the purge transaction's start) and skips those the archive already holds. #9469: a page-scope replay runs the live purge's sweep (page-purge.ts sweepPurgedPage, then deletePurgedPage), with one uncapped journal census per source per replay run (replayRun), and stops with purge_replay_incomplete naming the request when a sweep cannot complete (a missing table aside). Seam: __setPurgeReplayFaultForTests (fault incomplete_census). Probes: test/belief-ledger-restore.test.ts; segment storage after a replay: test/large-pages/purge-replay-segments.test.ts (both engines).

  • src/commands/doctor/checks/purge-mirror.ts — purge_mirror (#9469): compares the request ids of the last 30 days' page_purges, fact_purges and take_purges (capped at 10,000, details.capped) with the intent lines of this process's purge mirror (configDir()), and warns when any is missing; never a failure, never reads the request journal, prints counts and the mirror path only (no slug, title or text). Fix: one durable GBRAIN_HOME for every writer (memory boundaries). Test: test/doctor-purge-mirror.test.ts.

  • src/core/facts/gone-page-facts.ts — expireGonePageFacts(exec, pages): in the transaction that removes a page row for good, expires (never deletes) the active facts filed on the page (ontology observations excluded: their source_markdown_slug is provenance) and the active facts about it that no page row holds (a soft-deleted holder keeps its fact for a restore), so they don't come back for readers once the tombstone is gone and a new page at the slug starts clean. A conversation fact's slot (dimension set on a numbered row, GBRA-574 B2) counts as filed on the page: the row is expired and gives up its slot. Two updates, one per slug index. Facts have no foreign key to pages. Called by the bulk retention purge (engine-sql/pages.ts purgeDeletedPages) and the belief-ledger purge of a recorded source (persistence/purge-deleted.ts expireRecordedTombstones).

  • src/core/facts/purge-overlay.ts — purge mode of the import overlay: dropPurgedFenceRows drops facts-fence rows matching fact_purges and takes-fence rows matching take_purges (the takes fence re-renders with its reservation rows plus the dropped numbers reserved, so a purged number is never reused; pinned by test/purge-overlay-reservations.test.ts) (subject = page slug; malformed fences left to the withdrawal diagnostics, which refuse a purged claim inside one). Called first by preserveWithdrawnFenceRows, so import-file.ts needs no change; the snapshot overlay (page-state/snapshot.ts) and export (export-snapshot.ts) carry purge tombstones as PageWithdrawal.purged, which overlayWithdrawalBody drops instead of striking.

  • src/core/facts/purge-schema.ts — MEMORY_PURGE_SCHEMA_SQL (schema.sql fragment: fact_purges, take_purges, page_purges keyed (source_id, content_hash), derivation_inputs, needs_rederive) and MEMORY_PURGE_GUARD_SQL (migration only): facts_refuse_purged, takes_refuse_purged and pages_refuse_purged raise P0001 purged_content: … (mapped to typed purged_content by persistence/publication-failure.ts) instead of skipping the row, whatever expired_at says. The pages guard has no column list so it never pins columns. Since migration v264 facts_refuse_purged fires on UPDATE only; the facts insert check runs once per statement in facts/insert-guard-schema.ts. FACT_PURGE_LOOKUP_INDEX_SQL (migration v231, CONCURRENTLY on Postgres) adds fact_purges_subject_idx (a page's own tombstones, the '' lookup by fingerprint) and the partial fact_purges_all_subjects_idx (subject '' only, for the snapshot marker count).

  • src/core/facts/insert-guard-schema.ts — FACT_INSERT_GUARD_SQL (migration v264, #7105): one statement-level facts_guard_inserted trigger (AFTER INSERT ... REFERENCING NEW TABLE AS inserted_facts, function gbrain_guard_inserted_facts) runs the purge refusal, and the withdrawal stamp of deferred inserts, once per statement instead of once per row. It takes FOR SHARE on each inserted source row, refuses a statement whose rows match a fact_purges tombstone with the same P0001 purged_content message and {table, hash8} detail (the first matching row in insertion order, whatever its expired_at), then stamps inserted active rows still matching fact_withdrawals (v2 or v1 fingerprint) with expired_at = min(withdrawn_at) and a clamped valid_until, by an UPDATE of just those rows, run under the transaction-local gbrain.fact_withdrawal_stamp setting (FACT_WITHDRAWAL_STAMP_SETTING, reset after the UPDATE) so gbrain_stamp_write_attribution keeps the last_write_* and last_written_at the INSERT stamped or supplied. By default an insert is stamped before it is written by the per-row facts_preserve_withdrawal_insert (BEFORE INSERT ... WHEN (NEW.expired_at IS NULL AND <deferral off>), the original function), so INSERT ... RETURNING reads the stamp; the bulk fence insert (engine-sql/facts.ts insertFactRows) sets gbrain.fact_withdrawal_stamp_deferred (FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING) around its INSERTs, so the WHEN clause, which calls no function, skips the trigger and the statement guard stamps instead. The setting moves the stamp and never skips it: the guard stamps every still-matching active row whoever set it. A ledger with no row for the inserted sources costs one index probe. Transition tables cannot take a column list, so facts_refuse_purged and facts_preserve_withdrawal stay per-row for UPDATE (BEFORE UPDATE OF ...). Differences from the per-row insert guards: (1) a row ON CONFLICT DO NOTHING skips is not checked (it is not written either); (2) a row that another per-row BEFORE trigger (for example managed_writer_guard) or a constraint also refuses reports that refusal first; (3) a deferred insert is stamped after its RETURNING, so INSERT ... RETURNING expired_at, valid_until (or a CTE reading it in the same query) made under the deferral setting sees a withdrawn row unstamped while storage and every later statement see the stamp (insertFactRows returns only ids, slugs and row numbers). Pinned by test/facts-insert-guards-7105.test.ts (guard calls and firings per statement, RETURNING with and without deferral, and the same refusals, stamps and attribution as the per-row guards re-installed in a rolled-back transaction, both engines). #7778 (migration v279, FACT_INSERT_GUARD_FUNCTION_SQL): the purge refusal skips an extraction outcome row (isOutcomeMarker / outcomeMarkerSql in facts/audit-sources.ts: a conversation-facts audit source AND the exact text EXTRACTION_COMPLETE or EXTRACTION_NOT_APPLICABLE), so a wildcard tombstone a page purge wrote before the fix no longer keeps pages from completing; a user claim with that text is still refused. Pinned by test/conversation-facts-outcome-marker-purge-7778.test.ts.

  • src/core/page-state/snapshot.ts — a page snapshot lists only the page's own fact_purges tombstones; subject-'' ones come back as PageSnapshot.globalPurges (count, latest purged_at, world-only flag; absent at count 0). resolveGlobalPurges turns the marker into purge withdrawals for the fence rows of whatever text is overlaid (stored page, incoming file in page-prepare.ts, overlayCanonicalBodies), on the caller's query. Reconcile pins/preimages and extract-atoms page-state hashing carry the marker, so a new '' purge invalidates them and an artifact without it reads stale. Alias resolution: readPageSnapshot with resolveAlias first runs the exact-slug statement (an exact hit outranks every alias), then, on a miss or for requireUnambiguous, one WITH chosen statement whose candidates are a UNION ALL of the exact-slug probe and an alias-join probe (slug_aliases → pages on (source_id, canonical_slug), p.slug<>$1 keeps the branches disjoint so count(*) OVER () still counts pages). #6281: never slug=$1 OR EXISTS(alias), which read every page of every readable source; page-snapshot-alias-plan.test.ts pins fewer than 100 pages rows per statement from EXPLAIN on both engines.

  • src/core/facts/derivation-inputs.ts — recordDerivationInputs(tx, {table, id, sourceId}, inputs): complete derived-row → input edges, written by derivers in the deriving transaction (write_origin keeps only a display sample). derivedRowsFrom walks edges breadth-first (bounded, reports truncated); hideDerivedRows expires facts, deactivates takes, soft-deletes pages and upserts needs_rederive.

  • src/core/deletion-inventory.ts — the deletion-target registry: every table with a text, JSON, bytes, array, lexeme or vector column, classed swept, retained_inactive or out_of_scope (probed_reported with probe columns, text_free_ledger, secret_material, no_memory_text), plus on-disk stores and out-of-reach residuals. test/deletion-inventory.test.ts fails on any unlisted text-bearing column of a fresh schema and pins the AGENTS.md "never promise physical erasure" line.

  • src/core/persistence/intent-redaction.ts — accounting-aware intent redaction: findRequestsCarrying (intent, outcome, error detail or message, compacted rows included; the fact purge's planning read) / findRequestsForSlugs (index-served by persistence_requests_slug_intent), the page purge's preparation-time journal census sweepRequestsCarrying (#6511: a keyset walk of the source's journal in JOURNAL_SWEEP_CHUNK_ROWS chunks, every needle in raw and JSON-escaped form against intent, outcome, error detail and message, compacted rows included, the purge's own row excluded, stopped by the claim clock between chunks and at JOURNAL_SWEEP_MATCH_CAP; returns the carrying ids, the ids pending at the scan, the sequence ceiling as text and complete; #6884: sweepRequestsForGroups runs it once for several needle groups, each row read and lowered once and every hit attributed to the groups carrying that needle, the match cap per group, and after starts past an earlier ceiling) with recheckRequestsCarrying for the publication's bounded re-check of the tail past the ceiling and of the rows that were pending, redactRequestIntents locks counters then request rows, refuses on a non-terminal or recovering request (unless skipPending), nulls intent/error_message and replaces every outcome or error-detail string carrying a needle with "[purged]" (redactJson), with compaction's terminal-byte accounting, so replay keeps returning the (redacted) stored outcome. findRequestsHoldingStagings / cancelRequestsHoldingStagings: the unclaimed requests (queued, or deferred behind a refresh: GST-1602, test/refresh-barrier-purge-gst1602.test.ts) whose intent.body_ref.staging_id names a staging a fact purge aborts are completed cancelled with purged_content; a claimed one refuses purge_blocked_pending_recovery.

  • src/core/persistence/purged-intent.ts — intentCarriesPurgedContent: completeWrite (journal.ts) nulls the intent of any terminal request whose content (fact, claim, page fence rows, or the page's content hash) matches a subject-scoped purge tombstone, and of any refusal coded purged_content; a write refused for another reason, or committed as a no-op after the overlay dropped purged rows, keeps no copy. Only content-bearing intents are checked, and whether the source holds any tombstone is selected by completeWrite's terminal statement itself (PURGE_PRESENCE_COLUMNS), so the hook adds no statement to a write on a source without tombstones (#6007 budget). purged_content is a write error code, so receipts and the frozen verb path (wire invalid_params, canonical purged_content) keep it typed.

  • src/core/persistence/page-purge.ts — #6884: preparePagePurge takes its census from sweepForPurge: a purge an earlier batch sweep covered for all of its current claims scans only the tail past that sweep's ceiling (journal_sweep.watermark); otherwise it sweeps once for its own claims and those of the next queued purges of the source (up to PURGE_SWEEP_BATCH_MEMBERS, PURGE_SWEEP_BATCH_NEEDLES claim forms) and caches each member's result in process memory (never in the journal; journal_sweep.batch counts the purges one sweep covered). Rows a member's cached census saw as pending, the leader's own row included, are re-tested at publication. Tests: test/page-purge-batch-sweep-6884.test.ts. purgePageInTransaction, called by the delete_page purge:true apply in page-prepare.ts: records in page_purges the content hash of the page and of every retained version (up to 1000), each as imported and as purge-overlaid, so an older version is refused too; drops the decide rows, trust proposals, gate holds (by slug) and gate receipts naming the page or its rows and clears legacy query_cache; tombstones and deletes facts filed on the page, tombstones its takes, deletes take proposals, open loops, core notices and files rows, the page's page_aliases and the slug_aliases redirects whose canonical_slug is the page (#6619; a redirect from this slug to another page stays; counted in removed and checked by slug in the receipt), redacts finished intents for the slug and the carrying ids the preparation sweep found plus the publication's tail and pending re-check (#6511: preparePagePurge runs readPurgeClaims and sweepRequestsCarrying under the preparation budget at steps purge_claims / purge_journal_sweep, so the O(journal) substring scan is a charged preparation_deadline release and preparation_stalled at the attempt limit, never a transaction timeout; the lookups that stay inside the transaction go through lookup, which maps a 57014 to the terminal, non-retryable purge_lookup_timeout naming gbrain repair request-indexes only when persistence_requests_slug_intent is missing or INVALID; the receipt's journal_sweep reports ceiling, scanned, tail, pending_rechecked and complete), then deletes the page (FK cascades). PURGE_RESIDUALS names what stays out of reach. finishPagePurge deletes stored blobs after commit, lists any left by storage path, and attaches receipt, the store-by-store receipt from verifyPagePurge (same shape as the fact receipt: residuals first, every swept inventory store, other pages' prose naming a purged claim as source_prose); the page's claims used as needles live only in process memory, and a same-id replay returns the result built when the purge ran. residuals stays the prose string. readPagePurgeTombstones feeds screenImportContent({ purgedPages }) from managed sync's freeze-time screen (sync-screen.ts, one read per run) and publication (sync-prepare.ts), which hold a matching file as purged_content; direct imports and put_page hit the pages guard instead; listPagePurges / unpurgePage (also clears the fact and take tombstones of the same request) back the owner-only ops. Pinned by test/page-purge.test.ts and test/page-purge-journal-timeout-6511.test.ts (both engines; seams purge:* in fault-points.ts). #6368: a purge of a tombstone whose file matches sync.exclude (discovery's globs via syncExcludePatterns in sync-discovery.ts, matched relative to the source root) owns no file: prepareFileTarget's excludeTombstone option returns no target, the purge is database-only and the receipt says write_through.skipped: 'sync_excluded'; the file is neither compared nor removed (an unchanged excluded file used to be deleted, an edited one refused forever). The apply re-reads the exclusion inside the publication transaction and refuses source_changed if it was removed meanwhile. Live-page purges and soft deletes are unchanged. A segmented page or version is never loaded whole: its stored content_hash and the purge-overlaid hash streamed by rewrittenContentHash are tombstoned; its stagings (by slug or page id) and the segment texts its manifests referenced or its stagings recorded in page_body_staging_texts (LPH (h), N14-5: a text an earlier write's sweep dropped from the manifest stays unreferenced for the GC grace window, and only the page's staging still names it) that no manifest row references, plus the source's unreferenced texts holding one of the page's claims (every fact filed on it, withdrawn ones included, and every take, not the journal sweep's first 32, tested in batches of CLAIM_FORMS_BATCH forms; plain or as a fence cell stores it, claimTextForms in fence-shared.ts: a text another page's write reused outlives this page's 24-hour staging record), are deleted in the purge transaction with the page (deletePageWithSegments, shared with the restore-time page-scope replay; removed.page_body_manifest / page_body_stagings / page_segment_texts), except a text another page's live staging recorded in page_body_staging_texts (an unpublished create or replace still needs it; stagingNeedsTextSql, also applied by the 72-hour hard delete and the receipt's text probe). #7778: the page's tombstones, mirror facts and journal and segment sweeps leave out its extraction outcome rows (outcomeMarkerSql); a subject-'*' tombstone on the shared marker text would keep every page of the source from recording its outcome. #9469: the in-transaction sweep is sweepPurgedPage (its stores are PURGE_SWEEP_STORES) and the delete deletePurgedPage, both shared with the restore-time page-scope replay.

  • src/core/ops/purge.ts — purge_fact, list_page_purges, unpurge_page: admin scope, cliOnly (every MCP route gets trusted_local_only). The resident owner runs them only for its verified local CLI registration (LOCAL_CLI_OWNER_OPERATIONS in persistence/ipc.ts, checked in persistence/provider.ts).

  • src/commands/forget-purge.ts + src/commands/pages-purges.ts — the CLI fronts. runForgetPurge always runs the dry run, then a typed token on a terminal or --yes plus --request-id without one; --match lists ids, --status polls completion; PURGE_FAMILY_HELP is the purge-family table shown by gbrain forget --help. gbrain pages purges list and gbrain pages unpurge <slug> run the page-tombstone ops as the trusted CLI.

  • Withdrawn-claim refusal on remember (persistence/memory-mutations.ts, memory-prepare.ts) — admission refuses a withdrawn claim (fact_withdrawn, FACT_WITHDRAWN_MESSAGE/_SUGGESTION in src/core/facts/withdrawal.ts) before a request exists, and preparation re-checks it; writeFailureDiagnostic allowlists that prefix, so a failed receipt and get_write_request name it. replaces accepts a target saved without an entity (links it by supersession). Test: test/remember-withdrawn-claim.test.ts. (R1, Cat 40 Hard.) The refusal carries an additive withdrawn object (factWithdrawnRefusal in facts/single-prepare.ts, from fact_withdrawals only: the named entity's row over all_entities, then the newest, omitted when the caller cannot read the forgotten rows); withdrawalFailureDetail/withdrawnFromDetail in facts/withdrawal.ts keep it in the failed receipt's error_detail for get_write_request and replay. Tests: test/withdrawn-detail.test.ts, test/e2e/withdrawn-detail-postgres.test.ts.

  • src/core/persistence/purge-deleted.ts — purgeDeletedPagesCoordinated backs the cycle purge phase, the purge job, purge_deleted_pages and gbrain pages purge-deleted. Unmanaged brains keep the engine bulk delete, after the belief-ledger expiry of recorded sources' tombstones: each is its own transaction and item (ItemRun site purge.recorded_tombstones), a run-scoped failure or a systemic run stops the purge, and any other failure lists the tombstone in blocked with its classified code, counts it in failed (no error, so the phase warns) and keeps it out of the bulk delete (purgeDeletedPages excludeIds); a content failure counts toward the same park as the managed purge, a transient one is retried next run, and parked tombstones are skipped as purge_parked unless retryParked (the unmanaged preview excludes them too). A managed brain purges each tombstone older than the window (skipping archived sources, which the source lifecycle purges) through delete_page with purge: true and the internal retention: true bound to its revision (retention is not an owner purge; see belief ledger). Writer state is read once per run (writerOnboardingPreflight): a source whose writer is recovery_required submits nothing and its tombstones are listed in blocked as writer_not_active (counted in inactive). Revision races are deferred to the next run; a parked tombstone (purge-parks.ts) is skipped as purge_parked (counted in parked) unless retryParked, and any other failure is listed in blocked and sets error. selectPurgeCandidates is the one eligibility selector (preview, consent, purge_deleted_pages op, run), and its holds are purgeHoldsSql (archived source, rename-identity, restorable-atom and derived-retirement holds), which doctor embedding_state also counts with; #6884: the run submits only while the writer has outstanding-request room (readOutstandingRoom in journal.ts, at persistence.capacity.background_pause_pct of the cap for a background run); the rest, and the rest after a queue_capacity refusal, is blocked as write_capacity_deferred and counted in capacity_deferred, never a failure or a park. purgePhaseStatus/purgePhaseNote shape the cycle purge phase (fail on error; warn on writer_not_active, parked, capacity-deferred or an unmanaged failed tombstone). The engine bulk delete (engine-sql/pages.ts purgeDeletedPages) also deletes, in its transaction, the purged pages' stagings (by source and slug) and the segment texts only their manifests referenced. GST-2689: every run first calls repair/origin-carry.ts carryPrivateBeforePurge (both branches); the origins it parks are listed in blocked as derived_origin_parked and counted in origin_parked (the phase warns), and derivedOriginPurgeHold is in purgeHoldsSql, the recorded-tombstone scan and delete, and the engine bulk delete. GST-2766: a page whose owner purge was held is owed that purge (derived-origin-hold.ts recordOwedPurge, op owed-page-purge, keyed by page id, no slug, live only while that tombstone exists); a managed run submits it as the owner purge, and an unmanaged run keeps it out of both bulk expiries and submits it through purgeOwedPages as an explicit delete_page purge, so the purge tombstones are written whichever run removes the page. The purge transaction (page-purge.ts deletePurgedPage), engine-sql/pages.ts restorePage and the restore_page apply clear the record. Tests: test/managed-writers-w3.test.ts, test/purge-deleted-parks.test.ts, test/purge-deleted-capacity-6884.test.ts, test/pathological/a49-unmanaged-purge-tombstones.test.ts, test/derived-origin-carry-private.test.ts.

  • src/core/persistence/derived-retirement-hold.ts — GBRA-161: the purge hold for every derived retirement. DERIVED_RETIRED_BY lists the retired_by stamps derived writers put on the pages they retire (extract-atoms, managed-reextract, stale-atoms, life-chronicle); derivedRetirementPurgeHold(alias) keeps a stamped page out of every purge route (engine bulk purge and its preview, the coordinated selection and delete) until DERIVED_RETIREMENT_HOLD_DAYS (30) after deleted_at (the database clock, never the retired_at text); retireDerivedPages versions, soft-deletes and stamps a batch in one attributed transaction (unmanaged extract_atoms). stampDerivedRetirement is the one retirement stamp every derived writer calls inside its own write (managed atom and generation retirements, gbrain repair stale-atoms, a journaled chronicle retire); it runs under withTrustKeep, so the page keeps its stored trust tier and write origin (#9456, test/atom-retirement-keeps-trust-9456.test.ts). assertRetirementStampUnchanged is the page preparer's refusal (reserved_frontmatter_key) of a remote write that adds or changes one of RESERVED_RETIREMENT_KEYS. The hold length follows generations.restore_days (RESTORE_DAYS_SQL, read inside the purge statement; 30 by default) and retireDerivedPagesInTransaction is the in-transaction form generation adapters retire through. An explicit gbrain delete --purge is not held.

  • src/core/generations/ledger-scrub.ts — GBRA-161: purge reaches the generation ledger. A page purge (page-purge.ts) nulls the purged item's preimages in derived_generation_items and every held proposal in derived_generations naming it, and deletes the page's fence holds (FENCE_GENERATION_KINDS under page:<slug>, whose rows the purge deletes; test/generations-purge-fence-hold-7774.test.ts); a fact purge (facts/purge.ts) nulls every preimage, proposal and held context carrying the claim. Both are swept (generation_ledger) in the deletion inventory, so the verification probes them; gbrain repair generations then refuses a scrubbed item with no_preimage.

  • src/core/persistence/purge-name-stores.ts — #9068: scrubPurgedNameStores(engine, sourceId, slugs) deletes the source's context_volunteer_events rows (whose rationale quotes the matched name) and mention_gazetteer_entries rows (name_norm -> target_slug) for purged slugs. Every hard delete of a page calls it inside its transaction (purgePageInTransaction, purgeDeletedPages, expireRecordedTombstones, the restore purge replay in belief/purge-mirror.ts, and the engines' batch deletePages); removing a source deletes the source's volunteer rows (removedSourceScrubCtes in source-delete.ts) and its gazetteer rows by cascade; a soft delete keeps both. Both tables are swept (page_names) in the deletion inventory; the page receipt checks them by slug, and the fact receipt probes them (rationale, name_norm) and reports a match as probed_reported, because a fact purge sweeps neither.

  • src/core/persistence/purge-slug-stores.ts — #9146: scrubPurgedSlugStores(engine, sourceId, slugs, { ifPresent }) deletes the six stores keyed to a page by source and slug with no foreign key to pages (take_proposals, open_loops, core_edit_notices, page_aliases, slug_aliases by canonical_slug, slug_rename_history by new_slug) and returns rows removed per store; scrubPurgedSlugHolds deletes the slug's write_gate_holds and their write_gate_receipts, and on a tombstone expiry (deletedAt given) keeps a hold created or last seen after the soft delete. Every hard delete calls them inside its transaction (purgePageInTransaction for the stores, expireRecordedTombstones, the engines' batch deletePages and purge path, the restore purge replay in belief/purge-mirror.ts with ifPresent); a soft delete keeps them. Source removal deletes core_edit_notices and the holds with their receipts in removedSourceScrubCtes; the other five cascade from sources. Test: test/purge-slug-stores-9146.test.ts.

  • src/core/persistence/atom-retirement-hold.ts — #7013: the one SQL rule for atoms gbrain repair atoms-restore restores. atomRetirementsSql(scope) is set-based (CTEs over pages joined on source and origin key, linear in the atoms in scope) and returns every non-imported atom soft-deleted with retired_by: managed-reextract with origin_live (a live page origin in its source, or a transcript), replaced (a live atom of the same origin carries another stripped source hash), latest (its hash is the hash of the origin's latest managed-reextract retirement) and restorable (all three right); atomOriginScopeSql narrows it to one atom's source and origin through the frontmatter GIN index for the apply recheck; atomRetirementPurgeHold, which keeps such an atom out of every batch purge selection (engine purgeDeletedPages preview and delete, the belief-ledger expiry, selectPurgeCandidates) for ATOM_RESTORE_HOLD_DAYS (30) after deleted_at, next to the #6729 identityDowngradePurgeHold. An explicit delete --purge is not held. Static strings only, so engine-sql/pages.ts imports it.

  • src/core/repair/atoms-restore.ts — gbrain repair atoms-restore (#7013), explicit-only and preview-bound: lists atoms an empty managed re-extraction retired (retired_by: managed-reextract) that atomRetirementsSql (persistence/atom-retirement-hold.ts) marks restorable, each with origin, stripped source hash and retired_at, and residuals restorable, origins, origin_gone, replaced, older_generation; --apply --expect <hash> restores the approved set, rechecking each atom (id, incarnation, revision, origin, hash, retired_at, rule match) and reporting changed_since_preview otherwise. Managed: one managed_maintenance_restore_reextract_atom request per atom (deleted_page: true, bound to the deleted revision, request id in the outcome detail); prepareAtomRestore (dispatched from prepared-maintenance.ts) rechecks the rule under the atom and origin page locks and publishes a revision-bound revert_version to version_id, the newest live version of the atom at its source hash without retired_by (the one the coordinated delete archived; file written back, allowMissingFile); none is no_version, lowered to the derive:atoms tier of its origin with taint edges. Unmanaged: createVersion, restorePage and the two keys dropped in one maintenanceTransaction. Extraction state is not touched. Test: test/pathological/h5-atoms-restore.test.ts.

  • src/core/repair/atom-fence-rows.ts — gbrain repair atom-fence-rows, explicit-only and preview-bound: findAtomFenceRows lists live page-bound visibility: world atoms whose title, body or source_quote contains (case and whitespace folded, claims of at least MIN_CLAIM_CHARS) the claim of a facts row of their live source page whose visibility is not world or a takes row whose holder is not world, absent from the page's publicBody; keyset pages of 500 atoms whose source page names a facts or takes fence, each source page read once, segmented source pages counted origin_unread. The preview lists atom, source page and row kinds and numbers (never row text) under a saved hash; --apply --expect <hash> rechecks each atom and sets visibility: private through a revision-bound put_page (narrowed), else changed_since_preview. Doctor atom_fence_rows shares the scan. Test: test/repair-atom-fence-rows.test.ts (unmanaged and managed, PGLite and Postgres).

  • src/commands/doctor/checks/atom-fence-rows.ts — doctor atom_fence_rows (BRAIN, a host-only WAVE_CHECKS repair entry cleared by the explicit-only atom-fence-rows, so remediation classifies it explicit_kind_required): runs findAtomFenceRows per source, each statement bounded by PLAN_STATEMENT_MS; warn names the count per source and the read-only preview gbrain repair atom-fence-rows --source <id> --json as an agent fix, never a slug or row text; an overrun reports the count as unknown.

  • src/core/persistence/purge-parks.ts — #6741 C: per-tombstone purge parks in op_checkpoints (op purge-deleted-park, key source+slug+deleted_at, so a re-deleted page starts fresh); park at PURGE_PARK_LIMIT (5) non-deferral failures, a success clears it, and parks of a source seen inactive rearm the first run its writer is active again (notePurgeSourceWriter). purgeStaleCheckpoints exempts the op; prunePurgeParks drops parks whose tombstone is gone. A park records the gbrain version of its last failure; isParked (the managed and unmanaged selection, doctor purge_parked_pages) counts only the running version's, so a park another version wrote (or one with no version) gets one automatic attempt and a failure re-parks it under the running version. Tests: test/purge-deleted-parks.test.ts, test/purge-parks-version.test.ts (Postgres: test/e2e/purge-parks-version-postgres.test.ts).

  • src/core/persistence/derived-origin-hold.ts + src/core/repair/origin-carry.ts — GST-2689: a page that reads as world by its own label but is hidden from remote callers only through a private origin (derived_from, an atom's source_slug, followed through slug_aliases and slug_rename_history, or a concept's provenance atom) keeps that privacy once the origin row is gone. origin-carry.ts finds the dependents with private-labels.ts dependentsSql('remove') (it reads only the pages whose frontmatter names a removed slug, or a slug a rename moved to it, through idx_pages_frontmatter, one jsonpath scan per 100 slugs of a source, so its cost does not grow with the source; the postimage drops the origin rows; a page that names readers is returned when its listed readers would gain it, and gets the label with its readable_by kept; a life-chronicle event is returned when the removal opens it, never when its event.depth page is removed, since it then fails closed) and gives each visibility: private through the label door (publishMaintenancePages with keepTrust and the label edit on a managed brain, batch derived-origin-carry:<request_id>; writeLabelFile or importAtRevision otherwise). deletePageCarryingPrivate is the delete_page handler body: a soft delete (local or remote) labels after it committed and returns the unchanged receipt; a purge labels first and, when that fails, soft-deletes instead (an existing tombstone stays), parks the origin and returns purge_held, whose message (like an owner purge the in-transaction recheck or the failed origin lookup held) names gbrain delete <slug> --purge --source-id <id> to run as a new request once the page is labelled, since only an explicit purge writes the purge tombstones; the park records the held request (held_request_id, kept by a later park of the page) and doctor names the command (finish_argv). carryPrivateBeforePurge runs before every expiry over all the origins (type = 'atom' or hidden by privacyPartSql) expired or expiring within CARRY_LEAD_HOURS (24) at once, so a page private through two of them is found and none crosses the cutoff mid-run uncarried; it publishes the labels 200 per maintenance batch, parks the blocked ones and returns the ones whose park no longer applies, which purgeDeletedPagesCoordinated clears only after its purge, so an origin parked when the purge was previewed stays that run; a consented manual purge (gbrain pages purge-deleted, purge_deleted_pages) previews with forecastCarry (read-only: the parked origins the carry would free, released_origins, and the origins it would park, both judged as carryPrivate judges them) passed to selectPurgeCandidates, so --dry-run and the consent list exactly what --yes purges and nothing is labelled before the consent; the run passes the freed ids as release, and purgeDeletedPagesCoordinated clears those parks once its carry landed, before it purges. A soft-deleted dependent is returned too but never labelled: it blocks its origin (dependent_soft_deleted) until it is purged or restored, since a restore would bring it back with the origin row gone; a removed origin tied to another removed origin counts as such a dependent (judged on its own row), since another hold may keep it. Inside each delete transaction parkUncarriedInPurge rechecks the origins about to go (the page purge for an explicit or managed retention purge, the unmanaged bulk delete, and each recorded tombstone): an origin a page written after the carry still depends on is parked in that transaction and its row is kept (a live page is soft-deleted instead, and the receipt carries purge_held naming no page), so the next purge labels the page and the one after removes the origin. The origin is looked up by the lowercased slug, as submitPageMutation deletes it. derived-origin-hold.ts is the park (op_checkpoints op derived-origin-park, fingerprint the page id, with blocking_slug, code and reason), derivedOriginPurgeHold (no engine-sql imports), prune of restored or purged pages, and readDerivedOriginParks for doctor derived_origin_parked; purgeStaleCheckpoints exempts the op. Tests: test/derived-origin-carry-private.test.ts (repo-less, minted tokens), test/derived-origin-carry-managed.test.ts (managed Git brain), test/derived-origin-recheck-plan.test.ts (pages rows the recheck visits).

  • src/core/repair/segmented-mirror.ts — gbrain repair segmented-mirror (LPH a), explicit-only, preview-bound, destructive consent, checks: [] (no doctor scan: detection reads every segmented file). scanSegmentedMirrors (read-only, owner host; a non-owner source is held not_owner_host) walks live body_storage='segmented' pages of sources with a worktree binding whose snapshot ledger applies (ledgerApplies), runs prepareFileTarget(..., null, { allowMissing }) (the mirror's own drift check; file_database_drift or any other OperationError is held, never rewritten), then lists the page only when overlaying the ledger on the file's facts fences changes its region digests (fileBodyDigests vs overlaidFileBodyDigests over FileBytes, bounded memory) and the streamed render (unreadPageFile) hashes differently. The hash (segmented-mirror-v1) binds source selection, slug, page id, revision, path and both SHA-256s; the approved set lives in op_checkpoints. Apply re-checks revision and file hash of every page not yet admitted (preview_changed), then per page admits and commits, in one transaction like a withdrawal, a repair_segmented_mirror request (request id derived from the hash; its receipt) that inserts a version-2 targeted withdrawal-mirror + git effect (no embedding) whose data.approved_file carries the preview's file and render SHA-256 (mirrorPage skips the target preview_changed when the file's before-hash or the streamed render differs, before the gate or any recovery record; publishGitPage skips it when the file is not the approved render; the outcome is refused preview_changed with a read-only fix re-running the preview); it wakes this process's consumer and waits up to the write wait for them (mirrored / mirror_queued / held / failed; a replay is replayed). Test: test/pathological/lp-a-segmented-mirror.test.ts.