Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Restore repaired facts and takes at no more trust than they had
garrytan6a1f97f410a7
diff --git a/docs/guides/repair.md b/docs/guides/repair.mdindex 7f0e3325e4..fdf351d1b9 100644--- a/docs/guides/repair.md+++ b/docs/guides/repair.md@@ -2124,8 +2124,14 @@ 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 eachpage through one revision-bound page write that adds only those rows; a pagechanged 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+fact is a new facts row (the expired row stays as history). A restored row+never gets more trust than it had: a fact comes back at the tier the expired+row had, and a take, or a fact with no recorded tier, at the lowest tier+(`external_untrusted`); the preview says which on each row. If the apply+stops because its page write is still pending, rerun the same apply command:+it finishes lowering the tiers.++It is explicit-only and nothing runs on upgrade: show theuser the preview before running the apply.### Extractor factsdiff --git a/src/core/repair/lost-fence-rows.ts b/src/core/repair/lost-fence-rows.tsindex f97f2aa274..61c0cbfd53 100644--- a/src/core/repair/lost-fence-rows.ts+++ b/src/core/repair/lost-fence-rows.ts@@ -29,7 +29,7 @@ import { heldFenceFactRows } from '../facts/unfenced-facts.ts';import { isFactWithdrawn } from '../facts/withdrawal.ts';import { readFenceBlocks } from '../generations/fence.ts';import { serializePageToMarkdown } from '../markdown.ts';-import { opError } from '../ops/contract.ts';+import { OperationError, 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';@@ -39,7 +39,7 @@ 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 { compareTrust, isTrustTier, storedTrustTier, type TrustTier } 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';@@ -189,7 +189,36 @@ async function plannedPage(engine: BrainEngine, entry: { source_id: string; slugconst 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})`;+const describeRow = (row: LostRow) => `${row.kind} #${row.row_num} "${row.claim}" (retired ${row.retired_at}, restored from page version ${row.version_id}, `+ + `${restoreTier(row) === 'external_untrusted' && !(row.kind === 'fact' && row.trust_tier === 'external_untrusted') ? 'at the lowest trust tier: no record of its earlier tier' : `at trust tier ${restoreTier(row)}`})`;++/**+ * The tier a restored row may have at most: the tier the expired fact had, or the lowest tier when no record holds one (a+ * fact with no stored tier, every take: a deleted take's tier is in no record). A repair never hands a row more trust.+ */+const restoreTier = (row: LostRow): TrustTier => row.kind === 'fact' && isTrustTier(row.trust_tier) ? row.trust_tier : 'external_untrusted';++/**+ * Lowers each restored row of `page` (live at its planned number with its claim) to `restoreTier`. With `onlyIfAll`, does+ * nothing and returns false unless every row is already live: the rerun of an apply whose page write was left pending.+ */+async function lowerRestoredTiers(engine: BrainEngine, page: LostRowsPage, onlyIfAll: boolean): Promise<boolean> {+ const live = await Promise.all(page.rows.map(async row => (row.kind === 'fact'+ ? await engine.executeRaw<{ id: number; trust_tier: string | null }>(`SELECT id::int AS id, trust_tier FROM facts+ WHERE source_id=$1 AND source_markdown_slug=$2 AND row_num=$3 AND fact=$4 AND expired_at IS NULL`, [page.source_id, page.slug, row.row_num, row.claim])+ : await engine.executeRaw<{ id: number; trust_tier: string | null }>('SELECT id::int AS id, trust_tier FROM takes WHERE page_id=$1 AND row_num=$2 AND claim=$3',+ [page.page_id, row.row_num, row.claim]))[0]));+ if (onlyIfAll && live.some(row => !row)) return false;+ for (const [index, row] of page.rows.entries()) {+ const restored = live[index];+ const tier = restoreTier(row);+ if (restored && compareTrust(storedTrustTier(restored.trust_tier), tier) > 0) {+ await setRowTier(engine, { table: row.kind === 'fact' ? 'facts' : 'takes', id: Number(restored.id), sourceId: page.source_id, tier,+ note: { repair: 'lost-fence-rows', [row.kind]: row.id } });+ }+ }+ return true;+}export const lostFenceRowsRepair: RepairHandler = {kind: 'lost-fence-rows',@@ -201,7 +230,7 @@ export const lostFenceRowsRepair: RepairHandler = {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.'] } : {}),+ ...(scan.pages.length ? { warnings: ['A restored fact comes back as a new facts row; the expired row stays as history. A restored row never gets more trust than it had: a take, or a fact with no recorded tier, comes back at the lowest tier.'] } : {}),details: { docs: DOCS } };}if (!opts.expect) {@@ -216,25 +245,27 @@ export const lostFenceRowsRepair: RepairHandler = {},async apply(ctx, entry): Promise<RepairItemOutcome> {const { page, hash, last } = entry as LostRowsItem;+ let pending = false;+ const detail = { facts: page.rows.filter(r => r.kind === 'fact').length, takes: page.rows.filter(r => r.kind === 'take').length };try {+ // A rerun after this repair's own page write was left pending finds the rows live at their numbers: it only lowers their tiers.+ if (await lowerRestoredTiers(ctx.engine, page, true)) return { applied: true, outcome: 'restored', detail };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 } });- }+ try {+ 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) } });+ } catch (error) {+ pending = error instanceof OperationError && error.code === 'write_pending';+ throw error;}- return { applied: true, outcome: 'restored', detail: { facts: page.rows.filter(r => r.kind === 'fact').length, takes: page.rows.filter(r => r.kind === 'take').length } };+ await lowerRestoredTiers(ctx.engine, page, false);+ return { applied: true, outcome: 'restored', detail };} finally {- if (last) await clearApprovedSet(ctx.engine, { command: 'lost-fence-rows', hash });+ if (last && !pending) await clearApprovedSet(ctx.engine, { command: 'lost-fence-rows', hash });}},render(details) {diff --git a/src/core/repair/registry.ts b/src/core/repair/registry.tsindex 6d6ca6f52f..99262a6292 100644--- a/src/core/repair/registry.ts+++ b/src/core/repair/registry.ts@@ -686,7 +686,7 @@ const SPECS: Record<RepairKind, Omit<RepairKindSpec, 'kind'>> = {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. A section rebuilt by hand without a row looks the same, so check the list.',- 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.',+ 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 row never gets more trust than it had: a fact comes back at the tier the expired row had, and a take, or a fact with no recorded tier, at the lowest tier. If the page write is left pending, rerun the same apply to finish lowering the tiers. 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 'diff --git a/test/repair-lost-fence-rows.test.ts b/test/repair-lost-fence-rows.test.tsindex 3ac80ddc86..217f4e6fe3 100644--- a/test/repair-lost-fence-rows.test.ts+++ b/test/repair-lost-fence-rows.test.ts@@ -17,7 +17,10 @@ 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 { withCoordinatedWrite } from '../src/core/persistence/context.ts';import { durableGitRepo } from './helpers/git-publication.ts';+import { withEnv } from './helpers/with-env.ts';+import { TEST_WRITE_ATTRIBUTION } from './helpers/write-attribution.ts';import { managedBrain, settleManagedGitEffects } from './helpers/managed-brain.ts';import { requirePostgresTestDatabase, testBackends } from './helpers/test-backends.ts';@@ -41,6 +44,8 @@ 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),});+const tierOf = async (engine: BrainEngine, table: 'facts' | 'takes', claim: string) => (await engine.executeRaw<{ trust_tier: string }>(table === 'facts'+ ? "SELECT trust_tier FROM facts WHERE source_id='default' AND fact=$1 AND expired_at IS NULL" : 'SELECT trust_tier FROM takes WHERE claim=$1', [claim]))[0]?.trust_tier;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,@@ -138,6 +143,36 @@ for (const backend of testBackends()) {expect((await repair(engine)).affected).toBe(0);}, opts), 180_000);+ test('a restored fact whose expired row has no stored tier comes back at the lowest tier, and the preview says so', () => managedBrain(async ({ engine, ctx }) => {+ await loseRows(ctx);+ await engine.transaction(tx => withCoordinatedWrite(tx, ['default'], () => tx.executeRaw("DELETE FROM facts WHERE source_id='default' AND fact=$1 AND expired_at IS NOT NULL", [A]), TEST_WRITE_ATTRIBUTION));+ const preview = await repair(engine);+ expect(preview.affected).toBe(1);+ expect(JSON.stringify(preview.listing)).toContain('at the lowest trust tier: no record of its earlier tier');+ await repair(engine, preview.preview_hash);+ expect(await tierOf(engine, 'facts', A)).toBe('external_untrusted');+ }, opts), 180_000);++ test('a restored take comes back at the lowest tier: a deleted take keeps no record of its tier', () => managedBrain(async ({ engine, ctx }) => {+ await loseRows(ctx);+ const preview = await repair(engine);+ await repair(engine, preview.preview_hash);+ expect(await tierOf(engine, 'takes', TA)).toBe('external_untrusted');+ }, opts), 180_000);++ test('an apply whose page write is left pending lowers the restored tiers when it is rerun', () => managedBrain(async ({ engine, ctx }) => {+ await loseRows(ctx);+ const preview = await repair(engine);+ const first = await withEnv({ GBRAIN_WRITE_WAIT_MS: '0' }, () => repair(engine, preview.preview_hash));+ await settleManagedGitEffects(engine);+ for (let i = 0; i < 100 && !(await live(engine)).facts.includes(A); i++) await Bun.sleep(100);+ const now = await live(engine);+ expect({ facts: now.facts.sort(), takes: now.takes.sort() }).toEqual({ facts: [A, B].sort(), takes: [TA, TB].sort() });+ if (first.stopped?.reason === 'write_pending') await repair(engine, preview.preview_hash);+ expect(await tierOf(engine, 'takes', TA)).toBe('external_untrusted');+ expect(first.stopped?.reason).toBe('write_pending');+ }, 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);