Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Add gbrain repair lost-fence-rows to restore rows an older gbrain lost

garrytan9538105e331d
diff --git a/docs/guides/repair.md b/docs/guides/repair.md
index 5184f4732f..2a634269d9 100644
--- a/docs/guides/repair.md
+++ b/docs/guides/repair.md
@@ -2075,6 +2075,41 @@ the whole section on purpose, or an edit may have lost it: ask which.
write retires every row on it. For facts it is:
```markdown
+### Lost fence rows
+
+A page rewrite that drops its `## Facts` or takes section is safe on its
+own: the section's rows stay live, held `fence_absent`, until you put the
+section back or write an empty one. Before this release, a later `remember`,
+`takes add`, fact extraction or `gbrain facts relink` on that page built a
+new section holding only its own rows, and the next ordinary write (a tag, a
+timeline entry, an append, a get and put) read that section as your answer:
+the held facts expired and the held takes were deleted. Those writers now put
+the held rows back into the section they create. `gbrain repair
+lost-fence-rows` brings back the rows an older gbrain already lost.
+
+```bash
+gbrain repair lost-fence-rows --json # preview; writes nothing
+gbrain repair lost-fence-rows --source <id> --json # one source
+gbrain repair lost-fence-rows --apply --expect <hash> --yes
+```
+
+A row is listed only when the records prove this shape: a facts or takes
+generation retired it without an empty-section proof, no row with the same
+claim is on the page now, and page history shows the row in a section that
+then vanished before the retirement. A row you removed by editing a section
+that stayed in place, a row retired by an explicit empty section, and a
+forgotten fact are never listed. `gbrain repair generations --mode restore`
+does not cover this case, because the retiring write published a fence that
+parsed; this kind reads page history instead.
+
+Each row comes back byte for byte from the newest page version that held it,
+at its old row number when that number is free. The apply republishes each
+page through one revision-bound page write that adds only those rows; a page
+changed since the preview is skipped and asks for a new preview. A restored
+fact is a new facts row at the trust tier the expired one had (the expired row
+stays as history). It is explicit-only and nothing runs on upgrade: show the
+user the preview before running the apply.
+
## Facts
<!--- gbrain:facts:begin -->
diff --git a/src/core/persistence/preview-approval.ts b/src/core/persistence/preview-approval.ts
index 517d1114fb..8994c75558 100644
--- a/src/core/persistence/preview-approval.ts
+++ b/src/core/persistence/preview-approval.ts
@@ -40,7 +40,7 @@ export const PREVIEW_APPROVAL_OP = 'repair-approval';
/** The default `purgeStaleCheckpoints` TTL; an older approved set may already be gone. */
export const APPROVAL_MAX_AGE_DAYS = 7;
-export type PreviewApprovalCommand = 'authorize-legacy' | 'jobs-cancel' | 'stale-atoms' | 'atoms-restore' | 'extractor-facts' | 'unwithdrawn-facts' | 'conversation-labels' | 'captured-facts' | 'agent-session-facts' | 'redacted-facts' | 'loop-facts' | 'ontology-facts' | 'facts-rehome' | 'consolidate-ties' | 'duplicate-facts' | 'failed-writes' | 'split-facts' | 'frontmatter' | 'fences' | 'slug-conflicts' | 'managed-sync-orphans' | 'frontmatter-keys' | 'file-drift' | 'stuck-recovery' | 'ghost-pages' | 'origin-twins' | 'receipt-compaction' | 'accepted-takes' | 'rename-identity' | 'overwritten-edits' | 'legacy-twins' | 'missing-tables' | 'segmented-mirror' | 'segmented-tiling' | 'uncommitted-deletions' | 'visibility' | 'generations' | 'fact-claim-dates' | 'timeline-order' | 'contact-rows' | 'provenance' | 'secret-spans' | 'rows-behind' | 'private-labels';
+export type PreviewApprovalCommand = 'authorize-legacy' | 'jobs-cancel' | 'stale-atoms' | 'atoms-restore' | 'extractor-facts' | 'unwithdrawn-facts' | 'conversation-labels' | 'captured-facts' | 'agent-session-facts' | 'redacted-facts' | 'loop-facts' | 'ontology-facts' | 'facts-rehome' | 'consolidate-ties' | 'duplicate-facts' | 'failed-writes' | 'split-facts' | 'frontmatter' | 'fences' | 'slug-conflicts' | 'managed-sync-orphans' | 'frontmatter-keys' | 'file-drift' | 'stuck-recovery' | 'ghost-pages' | 'origin-twins' | 'receipt-compaction' | 'accepted-takes' | 'rename-identity' | 'overwritten-edits' | 'legacy-twins' | 'missing-tables' | 'segmented-mirror' | 'segmented-tiling' | 'uncommitted-deletions' | 'visibility' | 'generations' | 'fact-claim-dates' | 'timeline-order' | 'contact-rows' | 'provenance' | 'secret-spans' | 'rows-behind' | 'private-labels' | 'lost-fence-rows';
export interface ApprovedSetKey {
command: PreviewApprovalCommand;
diff --git a/src/core/repair/core.ts b/src/core/repair/core.ts
index 346ed9c9d5..1a8e2d4dc3 100644
--- a/src/core/repair/core.ts
+++ b/src/core/repair/core.ts
@@ -52,7 +52,7 @@ import type { ProgressReporter } from '../progress.ts';
import type { GenerationsSelection } from '../generations/repair.ts';
import type { PrivateLabelsLedger } from './private-labels.ts';
-export const REPAIR_KINDS = ['timeline', 'visibility', 'safe-chunks', 'contextual-mode', 'connector-checkpoints', 'request-indexes', 'connector-fences', 'take-supersession', 'accepted-takes', 'orphan-bindings', 'embedding-effects', 'attribution-backfill', 'planner-stats', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'unwithdrawn-facts', 'conversation-labels', 'captured-facts', 'agent-session-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'fences', 'slug-conflicts', 'timeline-comments', 'timeline-order', 'contact-rows', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'segmented-tiling', 'uncommitted-deletions', 'generations', 'fact-claim-dates', 'provenance', 'secret-spans', 'rows-behind', 'access', 'private-labels'] as const;
+export const REPAIR_KINDS = ['timeline', 'visibility', 'safe-chunks', 'contextual-mode', 'connector-checkpoints', 'request-indexes', 'connector-fences', 'take-supersession', 'accepted-takes', 'orphan-bindings', 'embedding-effects', 'attribution-backfill', 'planner-stats', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'unwithdrawn-facts', 'conversation-labels', 'captured-facts', 'agent-session-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'fences', 'slug-conflicts', 'timeline-comments', 'timeline-order', 'contact-rows', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'segmented-tiling', 'uncommitted-deletions', 'generations', 'lost-fence-rows', 'fact-claim-dates', 'provenance', 'secret-spans', 'rows-behind', 'access', 'private-labels'] as const;
export type RepairKind = typeof REPAIR_KINDS[number];
export interface RepairScope { brain_id: string; source_ids: string[] }
diff --git a/src/core/repair/lost-fence-rows.ts b/src/core/repair/lost-fence-rows.ts
new file mode 100644
index 0000000000..414142843b
--- /dev/null
+++ b/src/core/repair/lost-fence-rows.ts
@@ -0,0 +1,211 @@
+/**
+ * `gbrain repair lost-fence-rows`: put back the fact and take rows an older gbrain retired after a page rewrite dropped
+ * their `## Facts` or takes section. The rewrite itself was safe: the rows stayed live, held `fence_absent`. But the
+ * next `remember`, `takes_add`, fact extraction or `facts relink` built a new section holding only its own rows, and the write
+ * after that read the new section as the user's answer: the facts expired and the takes were deleted, with no receipt.
+ * Those writers now carry the held rows (unfenced-facts.ts `withHeldFactsFence`, takes-prepare.ts); this repair brings
+ * back the rows they already lost.
+ *
+ * A row is listed only when the records prove that shape:
+ * 1. a fact_fence or take_fence generation retired it (`derived_generation_items`, action `retired`) without an
+ * empty-fence or deleted-page proof, and the fact was live when it did (a take is deleted outright);
+ * 2. no live fact with the same claim and visibility (no take with the same claim) is on the page now;
+ * 3. page history holds the row in a fence, and the newest version holding it is followed by one with no fence of
+ * that kind at all: the section vanished, then came back without the row. A row an edit removed from
+ * a fence that stayed in place is a deliberate removal and is never listed.
+ * The fence cell comes from the newest version that held it, byte for byte; a row number now taken gets the next free
+ * one. A page with no fence of that kind today also carries its held rows, as the append does.
+ *
+ * Explicit-only and preview-bound: the preview lists each page with the rows it would restore and writes nothing but the
+ * approval checkpoint; `--apply --expect <hash> --yes` republishes exactly that set, one revision-bound `put_page` per
+ * page, so the page projection re-derives the rows. A restored fact is a new facts row (the expired one stays as
+ * history), lowered to the trust tier the expired row had; a restored take's earlier tier is in no record.
+ */
+import type { BrainEngine } from '../engine.ts';
+import { factsFenceSection, parseFactsFence, renderFactsTable, replaceOrInsertFactsFence, type ParsedFact } from '../facts-fence.ts';
+import { heldFenceFactRows } from '../facts/unfenced-facts.ts';
+import { readFenceBlocks } from '../generations/fence.ts';
+import { serializePageToMarkdown } from '../markdown.ts';
+import { opError } from '../ops/contract.ts';
+import { readFix } from '../ops/op-fix.ts';
+import { stableJson } from '../persistence/digest.ts';
+import { submitPageMutation } from '../persistence/page-mutations.ts';
+import { clearApprovedSet, loadApprovedSet, previewHash, saveApprovedSet } from '../persistence/preview-approval.ts';
+import { materializedSnapshot, segmentedOverCeiling } from '../persistence/segmented-apply.ts';
+import { heldTakeRows } from '../persistence/takes-prepare.ts';
+import { parseTakesFence, upsertTakeRow, type ParsedTake } from '../takes-fence.ts';
+import { takesPreparation } from '../takes-write.ts';
+import { setRowTier } from '../trust/page-handlers.ts';
+import { compareTrust, storedTrustTier } from '../trust/tier.ts';
+import { afterCursor, repairRequestId, type RepairHandler, type RepairItem, type RepairItemOutcome, type RepairListing, type RepairScope } from './core.ts';
+
+const DOCS = 'docs/guides/repair.md#lost-fence-rows';
+const COMMAND = 'gbrain repair lost-fence-rows';
+
+/** One retired row the records prove was lost to a re-created section, with the cell to restore. */
+interface LostRow { kind: 'fact' | 'take'; id: number; row_num: number; claim: string; version_id: number; retired_at: string; fact?: ParsedFact; take?: ParsedTake; trust_tier?: string | null }
+/** One page to republish: its revision at the preview and the rows it gets back, at the numbers they take. */
+export interface LostRowsPage { source_id: string; slug: string; page_id: number; revision: string; rows: LostRow[] }
+interface LostRowsItem extends RepairItem { page: LostRowsPage; hash: string; last: boolean }
+type Residual = 'no_history' | 'page_missing' | 'fence_unreadable';
+
+interface Retired { kind: 'fact_fence' | 'take_fence'; source_id: string; slug: string; retired_at: string; preimage: Record<string, unknown> }
+
+const hasFence = (body: { compiled_truth: string | null; timeline: string | null }, fence: 'facts' | 'takes') => readFenceBlocks(body, fence).state !== 'absent';
+
+/**
+ * The newest page version whose fence holds the row, when the first version after it has no fence of that kind at all;
+ * `removed` when that version kept the fence without the row, or no later version exists (the write that retired it
+ * replaced the holding body itself: an edit inside the fence); null when no version holds it. Versions are read in write
+ * order (id), not by timestamp: a version's snapshot time and its write's generation time are not ordered alike on
+ * every engine.
+ */
+async function lostIn(engine: BrainEngine, pageId: number, fence: 'facts' | 'takes', holds: (body: string) => ParsedFact | ParsedTake | undefined) {
+ const versions = await engine.executeRaw<{ id: number; compiled_truth: string; timeline: string | null }>(`SELECT id::int AS id, compiled_truth, timeline FROM page_versions
+ WHERE page_id=$1 AND compiled_truth IS NOT NULL ORDER BY id`, [pageId]);
+ let held: { version_id: number; cell: ParsedFact | ParsedTake } | null = null;
+ let next: 'absent' | 'fence' | null = null;
+ for (const version of versions) {
+ const cell = holds(`${version.compiled_truth}\n${version.timeline ?? ''}`);
+ if (cell) { held = { version_id: Number(version.id), cell }; next = null; } else if (held && next === null) next = hasFence(version, fence) ? 'fence' : 'absent';
+ }
+ return !held ? null : next === 'absent' ? held : 'removed' as const;
+}
+
+/** Every lost row of the selected sources, grouped by page with the numbers they take, and the count of each reason a row is not listed. */
+export async function scanLostFenceRows(engine: BrainEngine, sourceIds: readonly string[], only?: { source_id: string; slug: string }): Promise<{ pages: LostRowsPage[]; residuals: Record<Residual, number> }> {
+ const residuals: Record<Residual, number> = { no_history: 0, page_missing: 0, fence_unreadable: 0 };
+ const retired = await engine.executeRaw<Retired>(`SELECT g.kind, g.source_id, substr(g.owner_key, 6) AS slug, g.created_at::text AS retired_at, i.preimage
+ FROM derived_generation_items i JOIN derived_generations g ON g.id = i.generation_id
+ WHERE g.source_id = ANY($1::text[]) AND g.kind IN ('fact_fence','take_fence') AND g.state <> 'held' AND left(g.owner_key, 5) = 'page:'
+ AND i.action = 'retired' AND i.preimage IS NOT NULL AND COALESCE(g.completeness->>'proof', '') = ''
+ AND ($2::text IS NULL OR (g.source_id = $2 AND g.owner_key = 'page:' || $3))
+ ORDER BY g.source_id, g.owner_key, g.id, i.item_key`, [[...sourceIds], only?.source_id ?? null, only?.slug ?? null]);
+ const byPage = new Map<string, { source_id: string; slug: string; rows: LostRow[] }>();
+ for (const r of retired) {
+ const p = r.preimage;
+ const fact = r.kind === 'fact_fence';
+ if (fact && p.expired_at != null) continue;
+ const [page] = await engine.executeRaw<{ id: number }>('SELECT id::int AS id FROM pages WHERE source_id=$1 AND slug=$2 AND deleted_at IS NULL', [r.source_id, r.slug]);
+ if (!page) { residuals.page_missing++; continue; }
+ const back = fact
+ ? await engine.executeRaw(`SELECT 1 FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 AND expired_at IS NULL AND fact=$3 AND visibility=$4`, [r.source_id, r.slug, p.fact, p.visibility])
+ : await engine.executeRaw('SELECT 1 FROM takes WHERE page_id=$1 AND claim=$2', [page.id, p.claim]);
+ if (back.length) continue;
+ const rowNum = Number(p.row_num);
+ const found = fact
+ ? await lostIn(engine, page.id, 'facts', body => parseFactsFence(body).facts.find(f => f.rowNum === rowNum && f.claim === p.fact && f.visibility === p.visibility && f.active))
+ : await lostIn(engine, page.id, 'takes', body => parseTakesFence(body).takes.find(t => t.rowNum === rowNum && t.claim === p.claim));
+ if (found === 'removed') continue;
+ if (!found) { residuals.no_history++; continue; }
+ const key = `${r.source_id}\u0000${r.slug}`;
+ const entry = byPage.get(key) ?? { source_id: r.source_id, slug: r.slug, rows: [] };
+ if (entry.rows.some(row => row.kind === (fact ? 'fact' : 'take') && row.claim === String(fact ? p.fact : p.claim))) continue;
+ const tier = fact ? (await engine.executeRaw<{ trust_tier: string | null }>('SELECT trust_tier FROM facts WHERE id=$1', [p.id]))[0]?.trust_tier ?? null : null;
+ entry.rows.push({ kind: fact ? 'fact' : 'take', id: Number(p.id), row_num: rowNum, claim: String(fact ? p.fact : p.claim), version_id: found.version_id,
+ retired_at: r.retired_at, ...(fact ? { fact: found.cell as ParsedFact, trust_tier: tier } : { take: found.cell as ParsedTake }) });
+ byPage.set(key, entry);
+ }
+ const pages: LostRowsPage[] = [];
+ for (const entry of byPage.values()) {
+ const planned = await plannedPage(engine, entry);
+ if (typeof planned === 'string') { residuals[planned]++; continue; }
+ pages.push(planned.page);
+ }
+ return { pages, residuals };
+}
+
+/** The page as it is now with the lost rows at the numbers they take, and the content that republishes it. */
+async function plannedPage(engine: BrainEngine, entry: { source_id: string; slug: string; rows: LostRow[] }): Promise<{ page: LostRowsPage; content: string } | Residual> {
+ const raw = await engine.readPageSnapshot(entry.slug, { sourceId: entry.source_id });
+ if (!raw || raw.page.deleted_at) return 'page_missing';
+ if (segmentedOverCeiling(raw.page as never)) return 'fence_unreadable';
+ const snapshot = (await materializedSnapshot(engine, raw))!;
+ const pageId = Number(snapshot.page.id);
+ const halves = { compiled_truth: snapshot.page.compiled_truth, timeline: snapshot.page.timeline ?? '' };
+ const rows: LostRow[] = [];
+ const facts = entry.rows.filter(row => row.kind === 'fact');
+ if (facts.length) {
+ const section = factsFenceSection(halves);
+ const parsed = parseFactsFence(halves[section]);
+ if (parsed.warnings.length) return 'fence_unreadable';
+ const current = hasFence(halves, 'facts') ? parsed.facts : await heldFenceFactRows(engine, entry.source_id, entry.slug);
+ const stored = (await engine.executeRaw<{ n: number }>('SELECT row_num AS n FROM facts WHERE source_id=$1 AND source_markdown_slug=$2 AND row_num IS NOT NULL', [entry.source_id, entry.slug])).map(r => Number(r.n));
+ const taken = new Set([...current.map(f => f.rowNum), ...stored]);
+ let next = Math.max(0, ...taken) + 1;
+ const placed = facts.map(row => { const n = taken.has(row.row_num) ? next++ : row.row_num; taken.add(n); return { ...row, row_num: n, fact: { ...row.fact!, rowNum: n } }; });
+ rows.push(...placed);
+ halves[section] = replaceOrInsertFactsFence(halves[section], renderFactsTable([...current, ...placed.map(row => row.fact)].sort((a, b) => a.rowNum - b.rowNum)));
+ }
+ let content = serializePageToMarkdown({ ...snapshot.page, ...halves }, snapshot.tags);
+ const takes = entry.rows.filter(row => row.kind === 'take');
+ if (takes.length) {
+ const parsed = parseTakesFence(content);
+ if (parsed.warnings.length) return 'fence_unreadable';
+ const current = hasFence(halves, 'takes') ? parsed.takes : await heldTakeRows(engine, entry.source_id, entry.slug, pageId);
+ const stored = (await engine.executeRaw<{ n: number }>('SELECT row_num AS n FROM takes WHERE page_id=$1', [pageId])).map(r => Number(r.n));
+ const taken = new Set([...current.map(t => t.rowNum), ...parsed.reservedRowNums, ...stored]);
+ let next = Math.max(0, ...taken) + 1;
+ const placed = takes.map(row => { const n = taken.has(row.row_num) ? next++ : row.row_num; taken.add(n); return { ...row, row_num: n, take: { ...row.take!, rowNum: n } }; });
+ rows.push(...placed);
+ const all = [...current, ...placed.map(row => row.take)].sort((a, b) => a.rowNum - b.rowNum);
+ content = takesPreparation.replaceFence(hasFence(halves, 'takes') ? content : upsertTakeRow(content, all[0]!).body, all);
+ }
+ return { page: { source_id: entry.source_id, slug: entry.slug, page_id: pageId, revision: snapshot.revision, rows }, content };
+}
+
+const hashParts = (scope: RepairScope, pages: LostRowsPage[]) => ({ kind: 'lost-fence-rows-v1', brain_id: scope.brain_id, source_ids: scope.source_ids, pages });
+const item = (page: LostRowsPage, hash: string, last: boolean): LostRowsItem => ({ cursor: { phase: 1, id: page.page_id }, source_id: page.source_id, slug: page.slug,
+ chars: 0, action: `restore_rows:${page.rows.length}`, page, hash, last });
+const describeRow = (row: LostRow) => `${row.kind} #${row.row_num} "${row.claim}" (retired ${row.retired_at}, restored from page version ${row.version_id})`;
+
+export const lostFenceRowsRepair: RepairHandler = {
+ kind: 'lost-fence-rows',
+ async plan(engine, scope, after, opts) {
+ if (!opts?.apply) {
+ const scan = await scanLostFenceRows(engine, scope.source_ids);
+ const hash = previewHash(hashParts(scope, scan.pages));
+ if (scan.pages.length) await saveApprovedSet(engine, { command: 'lost-fence-rows', hash }, scan.pages);
+ const listing: RepairListing[] = scan.pages.map(page => ({ item: `${page.source_id}:${page.slug} (revision ${page.revision})`, class: 'restore',
+ detail: page.rows.map(describeRow).join('; ') }));
+ return { items: scan.pages.map((page, index) => item(page, hash, index === scan.pages.length - 1)), preview_hash: hash, residuals: scan.residuals, listing,
+ ...(scan.pages.length ? { warnings: ['A restored fact comes back as a new facts row; the expired row stays as history. A restored take\'s earlier trust tier is in no record.'] } : {}),
+ details: { docs: DOCS } };
+ }
+ if (!opts.expect) {
+ throw opError('invalid_params', `${COMMAND} --apply restores only the set a preview printed.`,
+ `Preview first: ${COMMAND} — show the user the listing, then run the apply command it prints: ${COMMAND} --apply --expect <preview-hash> --yes`,
+ { fix: readFix('Previews the fact and take rows lost after a page rewrite dropped their section; writes nothing.', { argv: ['gbrain', 'repair', 'lost-fence-rows', '--json'] }), docs: DOCS });
+ }
+ const approved = await loadApprovedSet<LostRowsPage>(engine, { command: 'lost-fence-rows', hash: opts.expect, previewCommand: COMMAND,
+ emptyHash: async () => previewHash(hashParts(scope, [])) });
+ const items = approved.items.map((page, index) => item(page, opts.expect!, index === approved.items.length - 1));
+ return { items: items.filter(entry => afterCursor(entry.cursor, after)), preview_hash: opts.expect, residuals: {} };
+ },
+ async apply(ctx, entry): Promise<RepairItemOutcome> {
+ const { page, hash, last } = entry as LostRowsItem;
+ try {
+ const changed = (reason: string): RepairItemOutcome => ({ applied: false, outcome: 'changed_since_preview', reason: `${page.slug}: ${reason}; run ${COMMAND} again for a new preview.` });
+ const [now] = (await scanLostFenceRows(ctx.engine, [page.source_id], page)).pages;
+ if (!now || now.revision !== page.revision || stableJson(now.rows) !== stableJson(page.rows)) return changed('the page or its lost rows changed since the preview');
+ const planned = await plannedPage(ctx.engine, page);
+ if (typeof planned === 'string') return changed(planned);
+ await submitPageMutation(ctx, { operation: 'put_page', params: { slug: page.slug, source_id: page.source_id, content: planned.content, expected_revision: page.revision,
+ request_id: await repairRequestId(ctx, 'lost-fence-rows', entry, page.revision) } });
+ for (const row of page.rows.filter(r => r.kind === 'fact' && r.trust_tier)) {
+ const [restored] = await ctx.engine.executeRaw<{ id: number; trust_tier: string }>(`SELECT id::int AS id, trust_tier FROM facts
+ WHERE source_id=$1 AND source_markdown_slug=$2 AND row_num=$3 AND expired_at IS NULL`, [page.source_id, page.slug, row.row_num]);
+ const tier = storedTrustTier(row.trust_tier!);
+ if (restored && compareTrust(storedTrustTier(restored.trust_tier), tier) > 0) {
+ await setRowTier(ctx.engine, { table: 'facts', id: Number(restored.id), sourceId: page.source_id, tier, note: { repair: 'lost-fence-rows', fact: row.id } });
+ }
+ }
+ return { applied: true, outcome: 'restored', detail: { facts: page.rows.filter(r => r.kind === 'fact').length, takes: page.rows.filter(r => r.kind === 'take').length } };
+ } finally {
+ if (last) await clearApprovedSet(ctx.engine, { command: 'lost-fence-rows', hash });
+ }
+ },
+ render(details) {
+ return [` each page: republished with the rows page history last held, through a revision-bound put_page; guide: ${details.docs}`];
+ },
+};
diff --git a/src/core/repair/registry.ts b/src/core/repair/registry.ts
index 5df44750c1..60502da7c7 100644
--- a/src/core/repair/registry.ts
+++ b/src/core/repair/registry.ts
@@ -94,6 +94,7 @@ import { secretSpansRepair } from './secret-spans.ts';
import { rowsBehindRepair } from './rows-behind.ts';
import { privateLabelsRepair, type PrivateLabelsLedger } from './private-labels.ts';
import { generationsRepair, generationsSelectionArgv, type GenerationsSelection } from '../generations/repair.ts';
+import { lostFenceRowsRepair } from './lost-fence-rows.ts';
import { restoreDaysHint } from '../generations/config.ts';
import { ERROR_CATALOGUE, catalogueError } from '../error-catalogue.ts';
import { shellQuote } from '../shell-quote.ts';
@@ -680,6 +681,21 @@ const SPECS: Record<RepairKind, Omit<RepairKindSpec, 'kind'>> = {
+ 'and saves the set under its hash; --apply --expect <hash> --yes applies exactly that set, refusing a key edited since or with no stored preimage. '
+ 'Runs only when named; never on upgrade.',
},
+ 'lost-fence-rows': {
+ handler: lostFenceRowsRepair, embeds: 'effect', checks: [], explicit_only: true, preview_bound: true, consent: 'destructive',
+ consentText: {
+ what: 'Put the previewed fact and take rows back into their pages\' Facts and Takes sections',
+ why: 'The preview listed each row an older gbrain expired or deleted after a page rewrite dropped its section and a later remember or takes add re-created the section without it; page history holds each row.',
+ risk: 'Each listed page is republished through a revision-bound put_page with the rows added and nothing else changed; a page that changed since the preview is skipped. A restored fact is a new facts row at the trust tier the expired one had. Page history keeps the earlier revision, and a managed source commits the file, so git revert undoes it.',
+ user_message: 'Put the previewed facts and takes back into their pages? Only those rows are added',
+ },
+ summary: 'Restore fact and take rows an older gbrain retired after a page rewrite dropped their Facts or Takes section: the next remember or takes add '
+ + 're-created the section with only its own row, and the write after that expired the facts and deleted the takes. Lists only rows the records '
+ + 'prove: a fence generation retired the row without an empty-section proof, nothing on the page carries it now, and page history holds it in a '
+ + 'section that then vanished before the retirement (a row an edit removed from a section that stayed is a deliberate removal and is not listed). '
+ + 'Each cell comes back byte for byte from the newest version that held it, at its row number when free. --source narrows. The preview lists each '
+ + 'page; --apply --expect <hash> --yes republishes exactly that set, one revision-bound put_page per page. Runs only when named; never on upgrade.',
+ },
};
export const REPAIR_REGISTRY: readonly RepairKindSpec[] = REPAIR_KINDS.map(kind => ({ kind, ...SPECS[kind] }));
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index 5204d12ad7..129701311b 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -97,6 +97,7 @@ test/facts-entity-moved-7602.test.ts
test/facts-insert-guards-7105.test.ts
test/facts-publication-large-fence-6898.test.ts
test/facts-subject-infer-7405.test.ts
+test/fence-absent-append-keeps-rows.test.ts
test/fence-fact-append.test.ts
test/fence-first-generation-8819.test.ts
test/fence-repair-receipts.test.ts
@@ -486,6 +487,7 @@ test/repair-file-drift-provenance-gbra133.test.ts
test/repair-frontmatter-keys-sweep-6454.test.ts
test/repair-frontmatter.test.ts
test/repair-ghost-database-ahead-gbra133.test.ts
+test/repair-lost-fence-rows.test.ts
test/repair-quoted-markers-8059.test.ts
test/repair-receipt-compaction.test.ts
test/repair-rename-identity-6729.test.ts
diff --git a/test/repair-explicit-only.test.ts b/test/repair-explicit-only.test.ts
index 1f7d773808..8e38d1d91a 100644
--- a/test/repair-explicit-only.test.ts
+++ b/test/repair-explicit-only.test.ts
@@ -24,7 +24,7 @@ import { REPAIR_HELP, parseRepairArgs, runRepairCommand } from '../src/commands/
import { _resetCliExitVerdictForTests, currentExitCode } from '../src/core/cli-force-exit.ts';
import { withEnv } from './helpers/with-env.ts';
-const EXPLICIT: RepairKind[] = ['accepted-takes', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'unwithdrawn-facts', 'conversation-labels', 'captured-facts', 'agent-session-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'timeline-comments', 'timeline-order', 'contact-rows', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'segmented-tiling', 'uncommitted-deletions', 'generations', 'fact-claim-dates', 'provenance', 'secret-spans', 'rows-behind', 'private-labels'];
+const EXPLICIT: RepairKind[] = ['accepted-takes', 'google-file-modes', 'stale-atoms', 'atoms-restore', 'extractor-facts', 'unwithdrawn-facts', 'conversation-labels', 'captured-facts', 'agent-session-facts', 'redacted-facts', 'loop-facts', 'ontology-facts', 'facts-rehome', 'consolidate-ties', 'duplicate-facts', 'orphan-children', 'failed-writes', 'split-facts', 'frontmatter', 'timeline-comments', 'timeline-order', 'contact-rows', 'managed-sync-orphans', 'content-receipt-root', 'frontmatter-keys', 'file-drift', 'stuck-recovery', 'ghost-pages', 'origin-twins', 'receipt-compaction', 'aliases', 'rename-identity', 'overwritten-edits', 'legacy-twins', 'missing-tables', 'url-clone-fences', 'segmented-mirror', 'segmented-tiling', 'uncommitted-deletions', 'generations', 'lost-fence-rows', 'fact-claim-dates', 'provenance', 'secret-spans', 'rows-behind', 'private-labels'];
// GBRA-161: the generations preview carries its ledger kind and the restore window, so the printed command runs as is.
const PREVIEW = (kind: RepairKind): string => kind === 'generations' ? 'gbrain repair generations --kind atom --since 30d' : `gbrain repair ${kind}`;
let engine: PGLiteEngine;
diff --git a/test/repair-lost-fence-rows.test.ts b/test/repair-lost-fence-rows.test.ts
new file mode 100644
index 0000000000..6033cff459
--- /dev/null
+++ b/test/repair-lost-fence-rows.test.ts
@@ -0,0 +1,126 @@
+/**
+ * `gbrain repair lost-fence-rows` brings back fact and take rows an older gbrain retired after a page rewrite dropped
+ * their section and a later write re-created the section without them. The lost state is built with page writes:
+ * a section with the rows, a rewrite without it (the rows stay held), then a section holding only a new row (what
+ * remember or takes_add used to write), which retires them. A row removed by an edit inside a section that stayed, or by
+ * an explicit empty section, is a deliberate removal and is never listed. Nothing is restored without a preview.
+ * Managed brain, repo-less and Git-backed; PGLite, and Postgres from test/postgres-unit-arms.txt.
+ */
+import { describe, expect, test } from 'bun:test';
+import { randomUUID } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { BrainEngine } from '../src/core/engine.ts';
+import type { OperationContext } from '../src/core/ops/contract.ts';
+import { operationsByName } from '../src/core/operations.ts';
+import { renderTakesFence } from '../src/core/takes-fence.ts';
+import { emptyFenceBlock } from '../src/core/generations/fence.ts';
+import { resolveRepairScope, type RepairResult } from '../src/core/repair/core.ts';
+import { repairRunner } from '../src/core/repair/registry.ts';
+import { durableGitRepo } from './helpers/git-publication.ts';
+import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';
+import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';
+
+const gitSetup = ({ root }: { root: string }) => { writeFileSync(join(root, '.gitignore'), '\n'); durableGitRepo(root, ['.gitignore']); };
+const HEADER = '| # | claim | kind | confidence | visibility | notability | valid_from | valid_until | source | context |\n|---|-------|------|------------|------------|------------|------------|-------------|--------|---------|\n';
+const ROW = (n: number, claim: string) => `| ${n} | ${claim} | fact | 1.0 | world | medium | 2026-01-01 | | user said so | |`;
+const FACTS = (...rows: string[]) => `## Facts\n\n<!--- gbrain:facts:begin -->\n\n${HEADER}${rows.join('\n')}\n<!--- gbrain:facts:end -->\n`;
+const TAKES = (...rows: Array<[number, string]>) => `## Takes\n\n${renderTakesFence(rows.map(([rowNum, claim]) => ({ rowNum, claim, kind: 'bet', holder: 'world', weight: 0.5, active: true })))}\n`;
+const PAGE = (body: string) => `---\ntype: person\ntitle: Alice Example\n---\n\n# Alice Example\n\n${body}`;
+const SLUG = 'people/alice-example';
+const A = 'Alice Example is allergic to peanuts';
+const B = 'Alice Example rides a bike to work';
+const TA = 'Acme Example reaches profitability in 2027';
+const TB = 'Acme Example hires a finance lead this year';
+
+const put = async (ctx: OperationContext, content: string) => {
+ const prior = await ctx.engine.readPageSnapshot(SLUG, { sourceId: 'default' });
+ await operationsByName.put_page!.handler(ctx, { slug: SLUG, content, request_id: randomUUID(), ...(prior ? { expected_revision: prior.revision } : {}) });
+};
+const live = async (engine: BrainEngine) => ({
+ facts: (await engine.executeRaw<{ fact: string }>("SELECT fact FROM facts WHERE source_id='default' AND source_markdown_slug=$1 AND expired_at IS NULL ORDER BY row_num", [SLUG])).map(r => r.fact),
+ takes: (await engine.executeRaw<{ claim: string }>("SELECT t.claim FROM takes t JOIN pages p ON p.id=t.page_id WHERE p.source_id='default' AND p.slug=$1 ORDER BY t.row_num", [SLUG])).map(r => r.claim),
+});
+async function repair(engine: BrainEngine, expectHash?: string): Promise<RepairResult> {
+ const scope = await resolveRepairScope(engine, 'default');
+ return (await repairRunner(engine, { apply: expectHash !== undefined, noEmbed: true, logger: { info() {}, warn() {}, error() {} } })).run('lost-fence-rows', scope,
+ { explicit: true, sourceFlag: 'default', ...(expectHash ? { expect: expectHash } : {}) });
+}
+/** The section with the rows, a rewrite without it (held), then a section holding only a new row: the rows are retired. */
+async function loseRows(ctx: OperationContext) {
+ await put(ctx, PAGE(`Alice v1.\n\n${FACTS(ROW(1, A))}\n${TAKES([1, TA])}`));
+ await put(ctx, PAGE('Alice v2, rewritten without its sections.\n'));
+ expect(await live(ctx.engine)).toEqual({ facts: [A], takes: [TA] });
+ await put(ctx, PAGE(`Alice v2, rewritten without its sections.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ await put(ctx, PAGE(`Alice v3, tagged.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ expect(await live(ctx.engine)).toEqual({ facts: [B], takes: [TB] });
+}
+
+for (const backend of testBackends()) {
+ const databaseUrl = backend === 'postgres' ? requirePostgresTestDatabase() : undefined;
+ for (const storage of ['repo-less', 'git'] as const) {
+ const opts = { databaseUrl, ...(storage === 'git' ? { setup: gitSetup } : {}) };
+ describe(`gbrain repair lost-fence-rows (${backend}, ${storage})`, () => {
+ test('lists the rows a re-created section retired, writes nothing on preview, and restores exactly that set on apply', () => managedBrain(async ({ engine, ctx, root }) => {
+ await loseRows(ctx);
+ const revision = (await engine.readPageSnapshot(SLUG, { sourceId: 'default' }))!.revision;
+ const preview = await repair(engine);
+ expect(preview.affected).toBe(1);
+ expect(preview.listing?.map(l => l.class)).toEqual(['restore']);
+ expect(preview.listing?.[0]?.detail).toContain(A);
+ expect(preview.listing?.[0]?.detail).toContain(TA);
+ expect((await engine.readPageSnapshot(SLUG, { sourceId: 'default' }))!.revision).toBe(revision);
+ expect(await live(engine)).toEqual({ facts: [B], takes: [TB] });
+ const applied = await repair(engine, preview.preview_hash);
+ expect(applied.applied).toBe(1);
+ expect(await live(engine)).toEqual({ facts: [A, B], takes: [TA, TB] });
+ const rows = await engine.executeRaw<{ fact: string; row_num: number | null; expired: boolean }>(
+ "SELECT fact, row_num, expired_at IS NOT NULL AS expired FROM facts WHERE source_id='default' AND source_markdown_slug=$1 ORDER BY id", [SLUG]);
+ expect(rows.map(r => [r.fact, r.row_num, r.expired])).toEqual([[A, null, true], [B, 2, false], [A, 1, false]]);
+ if (storage === 'git') await settleManagedGitEffects(engine);
+ const file = readFileSync(join(root, `${SLUG}.md`), 'utf8');
+ for (const claim of [A, B, TA, TB]) expect(file).toContain(claim);
+ expect((await repair(engine)).affected).toBe(0);
+ }, opts), 180_000);
+
+ test('a row removed by an edit inside a section that stayed is not listed', () => managedBrain(async ({ engine, ctx }) => {
+ await put(ctx, PAGE(`Alice v1.\n\n${FACTS(ROW(1, A), ROW(2, B))}\n${TAKES([1, TA], [2, TB])}`));
+ await put(ctx, PAGE(`Alice v2.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ expect(await live(engine)).toEqual({ facts: [B], takes: [TB] });
+ await put(ctx, PAGE('Alice v3, rewritten without its sections.\n'));
+ await put(ctx, PAGE(`Alice v3.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ expect((await repair(engine)).affected).toBe(0);
+ }, opts), 180_000);
+
+ test('rows retired by an explicit empty section are not listed', () => managedBrain(async ({ engine, ctx }) => {
+ await put(ctx, PAGE(`Alice v1.\n\n${FACTS(ROW(1, A))}\n${TAKES([1, TA])}`));
+ await put(ctx, PAGE('Alice v2, rewritten without its sections.\n'));
+ await put(ctx, PAGE(`Alice v2.\n\n${emptyFenceBlock('facts')}\n${emptyFenceBlock('takes')}`));
+ expect(await live(engine)).toEqual({ facts: [], takes: [] });
+ await put(ctx, PAGE(`Alice v3.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ expect((await repair(engine)).affected).toBe(0);
+ }, opts), 180_000);
+
+ test('a forgotten fact and a removed take are not listed', () => managedBrain(async ({ engine, ctx }) => {
+ await put(ctx, PAGE(`Alice v1.\n\n${FACTS(ROW(1, A))}\n${TAKES([1, TA])}`));
+ const [{ id }] = await engine.executeRaw<{ id: number }>("SELECT id FROM facts WHERE source_id='default' AND fact=$1", [A]);
+ await operationsByName.forget!.handler(ctx, { id: String(id), reason: 'the user withdrew it' });
+ await operationsByName.takes_remove!.handler(ctx, { slug: SLUG, row_num: 1 });
+ await put(ctx, PAGE('Alice v2, rewritten without its sections.\n'));
+ await put(ctx, PAGE(`Alice v3.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ await put(ctx, PAGE(`Alice v4, tagged.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ expect(await live(engine)).toEqual({ facts: [B], takes: [TB] });
+ expect((await repair(engine)).affected).toBe(0);
+ }, opts), 180_000);
+
+ test('an apply after the page changed restores nothing and asks for a new preview', () => managedBrain(async ({ engine, ctx }) => {
+ await loseRows(ctx);
+ const preview = await repair(engine);
+ await put(ctx, PAGE(`Alice v4, edited after the preview.\n\n${FACTS(ROW(2, B))}\n${TAKES([2, TB])}`));
+ const applied = await repair(engine, preview.preview_hash);
+ expect(applied.applied).toBe(0);
+ expect(await live(engine)).toEqual({ facts: [B], takes: [TB] });
+ }, opts), 180_000);
+ });
+ }
+}
diff --git a/test/takes-reservation-callers.test.ts b/test/takes-reservation-callers.test.ts
index 37366b4e5d..aa23074abd 100644
--- a/test/takes-reservation-callers.test.ts
+++ b/test/takes-reservation-callers.test.ts
@@ -26,6 +26,7 @@ const REVIEWED: Record<string, string> = {
'src/core/persistence/takes-prepare.ts': 'allocates with nextFreeRowNum, re-renders through upsertTakeRow/supersedeRow/replaceFence, and remove adds the reservation',
'src/core/repair/accepted-takes.ts': 'reads the archived row at a removed take\'s number (reservations are never takes) and requires the live fence to reserve that number; it re-renders with renderTakesFence keeping every other reservation',
'src/core/repair/agent-session-facts.ts': 'marks previewed take rows inactive and re-renders through replaceFence, which keeps the reservations of the body it replaces',
+ 'src/core/repair/lost-fence-rows.ts': 'reads a lost take\'s cell from page history (reservations are never takes), numbers it past the live fence\'s rows and reservations and every stored take, and re-renders through replaceFence, which keeps the reservations',
'src/core/repair/connector-fences.ts': 'moves fence blocks verbatim, reservations included',
'src/core/repair/take-supersession.ts': 're-renders through replaceFence, which keeps the reservations of the body it replaces',
'src/core/shared-skills/migration-projection.ts': 'compares stored takes with fence takes; neither holds a reservation',