Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
5.2 KB
Raw Blame

Key files: Derived generations

Subsystem index. Read only the entries relevant to your change. 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. 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, 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. 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. Tests: test/pathological/g5-* to g7-*.