Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix(generations): a page purge drops the purged page's fence holds (#7774)

garrytanbb6a95638a72
diff --git a/docs/architecture/generations.md b/docs/architecture/generations.md
index 059a172feb..da3c9d2ed7 100644
--- a/docs/architecture/generations.md
+++ b/docs/architecture/generations.md
@@ -195,8 +195,8 @@ count), `generation_held` (warn) and `generation_pending` (warn).
## Purge
-A page purge nulls the purged item's preimages and every held proposal naming it; a fact purge nulls every preimage and
-proposal carrying the claim (`ledger-scrub.ts`). Restore then refuses that item (`no_preimage`).
+A page purge nulls the purged item's preimages and every held proposal naming it, and drops the page's fence holds (it
+deletes every row they would retire); a fact purge nulls every preimage and proposal carrying the claim (`ledger-scrub.ts`). Restore then refuses that item (`no_preimage`).
## Census
diff --git a/docs/architecture/key-files/memory-purge.md b/docs/architecture/key-files/memory-purge.md
index 528974ee76..97f90bd2ee 100644
--- a/docs/architecture/key-files/memory-purge.md
+++ b/docs/architecture/key-files/memory-purge.md
@@ -24,7 +24,7 @@ User-facing contract: [expire versus purge](../../guides/memory-boundaries.md#pu
- `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](belief-ledger.md)). 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. 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`.
- `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). `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; 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/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/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`.
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index fbfc157404..9f5219e590 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -1824,7 +1824,10 @@ once to an instant the preview and apply carry), `--key <owner>`
- `--mode release-held` publishes a held result once: `shrunk`, `valve` and
`attempts_exhausted` always, `oversize` after `generations.max_items` was
raised. `no_proof`, `fence_absent`, `segmented_unsupported` and `tie` are
- refused, because releasing them would supply the proof they lack.
+ refused, because releasing them would supply the proof they lack. On a
+ managed brain, purging the page (`gbrain delete --purge`, or the purge of an
+ expired tombstone) drops its fence holds, since the purge deletes the rows
+ they would retire.
The preview saves the set under its hash; `--apply --expect <hash> --yes`
applies exactly that set and rechecks each key under its locks
diff --git a/src/core/generations/ledger-scrub.ts b/src/core/generations/ledger-scrub.ts
index 2d250762c9..34163c5ea2 100644
--- a/src/core/generations/ledger-scrub.ts
+++ b/src/core/generations/ledger-scrub.ts
@@ -7,12 +7,18 @@
* a purge of the page, or of a claim those blocks carry, drops them, and that restore then refuses `no_preimage` too.
*/
import type { BrainEngine } from '../engine.ts';
+import { FENCE_GENERATION_KINDS } from './fence.ts';
export interface LedgerScrub { derived_generation_items: number; derived_generations: number }
-/** Nulls the preimages and held proposals that carry the purged page (`slug`) or text (`needles`) in `sourceId`. */
+/**
+ * Nulls the preimages and held proposals that carry the purged page (`slug`) or text (`needles`) in `sourceId`. A page
+ * purge also drops the page's fence holds: it deletes every row they would retire, so no fence write can settle them.
+ */
export async function scrubGenerationLedger(tx: BrainEngine, sourceId: string, target: { slug: string } | { needles: readonly string[] }): Promise<LedgerScrub> {
if ('slug' in target) {
+ const fenceHolds = await tx.executeRaw(`DELETE FROM derived_generations WHERE source_id=$1 AND kind=ANY($2::text[]) AND owner_key='page:' || $3::text
+ AND state='held' RETURNING 1`, [sourceId, [...FENCE_GENERATION_KINDS], target.slug]);
const items = await tx.executeRaw(`UPDATE derived_generation_items i SET preimage=NULL FROM derived_generations g
WHERE g.id=i.generation_id AND g.source_id=$1 AND i.item_key=$2 AND i.preimage IS NOT NULL RETURNING 1`, [sourceId, target.slug]);
const held = await tx.executeRaw(`UPDATE derived_generations SET proposal=NULL, updated_at=now()
@@ -20,7 +26,7 @@ export async function scrubGenerationLedger(tx: BrainEngine, sourceId: string, t
RETURNING 1`, [sourceId, target.slug]);
const fences = await tx.executeRaw(`UPDATE derived_generations SET completeness=completeness - 'fence'::text, updated_at=now()
WHERE source_id=$1 AND owner_key='page:' || $2::text AND completeness->'fence' IS NOT NULL RETURNING 1`, [sourceId, target.slug]);
- return { derived_generation_items: items.length, derived_generations: held.length + fences.length };
+ return { derived_generation_items: items.length, derived_generations: fenceHolds.length + held.length + fences.length };
}
const needles = target.needles.filter(Boolean).flatMap(needle => [needle.toLowerCase(), JSON.stringify(needle).slice(1, -1).toLowerCase()]);
if (!needles.length) return { derived_generation_items: 0, derived_generations: 0 };
diff --git a/test/generations-purge-fence-hold-7774.test.ts b/test/generations-purge-fence-hold-7774.test.ts
new file mode 100644
index 0000000000..04ebd4c967
--- /dev/null
+++ b/test/generations-purge-fence-hold-7774.test.ts
@@ -0,0 +1,43 @@
+/**
+ * #7774: a deleted page's fence hold (`no_proof`: its rows were not proven to come from a fence) used to survive the
+ * page's purge. The purge deletes every fact row filed on the page and its takes, so the held retirement has nothing
+ * left to act on, yet doctor `generation_held` kept warning with no reachable remedy. A purge now drops the fence holds
+ * keyed to the purged page; a hold on a page that still exists (deleted, not purged) stays.
+ */
+import { expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import type { BrainEngine } from '../src/core/engine.ts';
+import type { OperationContext } from '../src/core/ops/contract.ts';
+import { submitPageMutation } from '../src/core/persistence/page-mutations.ts';
+import { FACT_FENCE_KIND, publishFenceGeneration } from '../src/core/generations/fence.ts';
+import { generationHeldCheck } from '../src/commands/doctor/checks/generations.ts';
+import { managedBrain } from './helpers/managed-brain.ts';
+
+const held = (engine: BrainEngine) => engine.executeRaw<{ owner_key: string; held_reason: string }>(
+ "SELECT owner_key, held_reason FROM derived_generations WHERE source_id='default' AND state='held' ORDER BY owner_key");
+
+async function deletedWithHold(engine: BrainEngine, ctx: OperationContext, slug: string): Promise<void> {
+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug, source_id: 'default', request_id: randomUUID(),
+ content: '---\ntype: note\ntitle: Example\n---\nA synthetic page.\n' } });
+ const live = await engine.readPageSnapshot(slug, { sourceId: 'default' });
+ await submitPageMutation(ctx, { operation: 'delete_page', params: { slug, source_id: 'default', request_id: randomUUID(), expected_revision: live!.revision } });
+ const outcome = await engine.transaction(tx => publishFenceGeneration(tx, { kind: FACT_FENCE_KIND, sourceId: 'default', slug, read: { state: 'absent' },
+ items: [], originGone: true, retire: [{ key: `${slug}#1`, identityHash: 'synthetic' }] as never, writer: 'deleted_page' }));
+ expect(outcome).toMatchObject({ state: 'held', reason: 'no_proof' });
+}
+
+test('purging a deleted page drops its fence hold; a hold on a page not purged stays', () => managedBrain(async ({ engine, ctx }) => {
+ await deletedWithHold(engine, ctx, 'notes/alpha-example');
+ await deletedWithHold(engine, ctx, 'notes/beta-example');
+ expect(await held(engine)).toEqual([{ owner_key: 'page:notes/alpha-example', held_reason: 'no_proof' }, { owner_key: 'page:notes/beta-example', held_reason: 'no_proof' }]);
+
+ const snapshot = await engine.readPageSnapshot('notes/alpha-example', { sourceId: 'default', includeDeleted: true });
+ await submitPageMutation(ctx, { operation: 'delete_page', params: { slug: 'notes/alpha-example', source_id: 'default', purge: true,
+ request_id: randomUUID(), expected_revision: snapshot!.revision } });
+ expect(await engine.readPageSnapshot('notes/alpha-example', { sourceId: 'default', includeDeleted: true })).toBeNull();
+
+ expect(await held(engine)).toEqual([{ owner_key: 'page:notes/beta-example', held_reason: 'no_proof' }]);
+ const check = await generationHeldCheck(engine);
+ expect(check.status).toBe('warn');
+ expect(check.message).toContain('default/fact_fence no_proof: 1');
+}), 120_000);