Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

fix: ingest undo binds every page it deletes, the source document included, to the revision the attempt wrote and the apply verified

garrytan76aa18bfa072
diff --git a/docs/guides/ingest.md b/docs/guides/ingest.md
index bf8eab25b6..812b6c2128 100644
--- a/docs/guides/ingest.md
+++ b/docs/guides/ingest.md
@@ -154,7 +154,10 @@ one, still owns everything it wrote:
no other attempt uses it.
It keeps anything edited, promoted or linked from another page since, support it counted for a claim that already
-existed, and claims another attempt counts as support, with their page and the source page they cite. Apply runs under the source's publication guard and refuses
+existed, and claims another attempt counts as support, with their page and the source page they cite. Each page it
+deletes, the source page included, must still be at the revision the attempt wrote (a source document the owner
+replaced is kept as `edited`), and the delete, like the strike of that page's rows, carries the revision the apply
+verified, so an edit that lands while undo runs keeps the page. Apply runs under the source's publication guard and refuses
`preview_changed` when the plan moved since the preview. A repeat is a no-op. After a rebuild that renumbered the
facts, or without the attempt record, undo refuses `ingest_undo_unverifiable` rather than guess. A page whose body is segmented keeps its rows
(reported `segmented`).
diff --git a/src/core/ingest/report.ts b/src/core/ingest/report.ts
index f890375753..2f4f2dc42a 100644
--- a/src/core/ingest/report.ts
+++ b/src/core/ingest/report.ts
@@ -134,6 +134,8 @@ export interface ReportEvidence {
source_id: string;
source_slug: string;
source_created: boolean;
+ /** The source page's revision as the attempt wrote it; undo keeps the page when it moved since. */
+ source_revision?: string | null;
storage: IngestStorage;
created_pages: Array<{ slug: string; request_id: string; revision: string | null; proposed: boolean }>;
created_facts: Array<{ id: number; entity_slug: string; request_id: string }>;
diff --git a/src/core/ops/ingest.ts b/src/core/ops/ingest.ts
index ca6dd41fcb..6361f15754 100644
--- a/src/core/ops/ingest.ts
+++ b/src/core/ops/ingest.ts
@@ -357,6 +357,7 @@ async function commitPlan(ctx: OperationContext, state: IngestAttemptState, plan
report.write_requests.push({ slug: state.source_slug, request_id: r.request_id, state: r.pending ? 'pending' : 'committed' });
evidence.source_created = true;
evidence.source_request_id = r.request_id;
+ if (!r.pending) evidence.source_revision = await snapshotRevision(ctx, sourceId, state.source_slug);
await saveAttempt(ctx.engine, state);
}
await writeReport();
@@ -473,6 +474,7 @@ async function commitPlan(ctx: OperationContext, state: IngestAttemptState, plan
report.facts.push(row);
}
for (const p of evidence.created_pages) p.revision ??= await snapshotRevision(ctx, sourceId, p.slug);
+ if (evidence.source_created) evidence.source_revision ??= await snapshotRevision(ctx, sourceId, state.source_slug);
}
async function runIngest(ctx: OperationContext, p: Params): Promise<Record<string, unknown>> {
@@ -595,7 +597,7 @@ async function runIngest(ctx: OperationContext, p: Params): Promise<Record<strin
interface UndoPlan {
retract: Array<{ fact_id: number; entity_slug: string; row_num: number }>;
- delete: Array<{ slug: string }>;
+ delete: Array<{ slug: string; revision: string }>;
skipped: Array<{ kind: 'fact' | 'page'; ref: string; reason: string }>;
}
@@ -643,35 +645,43 @@ async function planUndo(ctx: OperationContext, state: IngestAttemptState, ev: Re
const snap = await ctx.engine.readPageSnapshot(pg.slug, { sourceId });
if (!snap || snap.page.deleted_at) { out.skipped.push({ kind: 'page', ref: pg.slug, reason: 'not_found' }); continue; }
if (pg.proposed && !isUnverifiedExtraction(asRecord(snap.page.frontmatter))) { out.skipped.push({ kind: 'page', ref: pg.slug, reason: 'promoted' }); continue; }
- if (pg.revision && snap.revision !== pg.revision) { out.skipped.push({ kind: 'page', ref: pg.slug, reason: 'edited' }); continue; }
+ if (pg.revision ? snap.revision !== pg.revision : asRecord(snap.page.frontmatter).ingest_attempt !== state.attempt_id) { out.skipped.push({ kind: 'page', ref: pg.slug, reason: 'edited' }); continue; }
// A claim another attempt relies on keeps its page, and the source page it cites.
if (supportedOn.has(pg.slug) || (await referencedFrom(pg.slug)).length) { out.skipped.push({ kind: 'page', ref: pg.slug, reason: 'referenced' }); continue; }
- out.delete.push({ slug: pg.slug });
+ out.delete.push({ slug: pg.slug, revision: snap.revision });
}
if (ev.source_created) {
+ // The source page is deleted only as the attempt wrote it (its revision, or its document hash when none was recorded).
+ const snap = await ctx.engine.readPageSnapshot(ev.source_slug, { sourceId });
const others = await attemptsOfDocument(ctx.engine, sourceId, state.document_hash, state.attempt_id);
- if (others.length) out.skipped.push({ kind: 'page', ref: ev.source_slug, reason: 'used_by_other_attempt' });
+ if (!snap || snap.page.deleted_at) out.skipped.push({ kind: 'page', ref: ev.source_slug, reason: 'not_found' });
+ else if (ev.source_revision ? snap.revision !== ev.source_revision : asRecord(snap.page.frontmatter).ingest_document !== state.document_hash) out.skipped.push({ kind: 'page', ref: ev.source_slug, reason: 'edited' });
+ else if (others.length) out.skipped.push({ kind: 'page', ref: ev.source_slug, reason: 'used_by_other_attempt' });
else if (supportedOn.size || (await referencedFrom(ev.source_slug)).length) out.skipped.push({ kind: 'page', ref: ev.source_slug, reason: 'referenced' });
- else out.delete.push({ slug: ev.source_slug });
+ else out.delete.push({ slug: ev.source_slug, revision: snap.revision });
}
return out;
}
const undoHash = (state: IngestAttemptState, plan: UndoPlan) => createHash('sha256').update(JSON.stringify({ a: state.attempt_id, r: plan.retract, d: plan.delete })).digest('hex').slice(0, 32);
-/** Strike the attempt's fence rows on one page through the door (valid_until today, no withdrawal), so a later write never re-projects them. */
-async function strikeRows(ctx: OperationContext, sourceId: string, slug: string, rowNums: number[], today: string): Promise<'struck' | 'changed' | 'segmented'> {
+/**
+ * Strike the attempt's fence rows on one page through the door (valid_until today, no withdrawal), so a later write never
+ * re-projects them. A page undo also deletes is struck only at the revision undo verified, and its new revision comes back.
+ */
+async function strikeRows(ctx: OperationContext, sourceId: string, slug: string, rowNums: number[], today: string, verified?: string): Promise<{ outcome: 'struck' | 'changed' | 'segmented'; revision?: string }> {
const snap = await ctx.engine.readPageSnapshot(slug, { sourceId });
- if (!snap || snap.page.deleted_at) return 'changed';
- try { assertInlineBody(snap.page, 'ingest_undo'); } catch { return 'segmented'; }
+ if (!snap || snap.page.deleted_at || (verified && snap.revision !== verified)) return { outcome: 'changed' };
+ try { assertInlineBody(snap.page, 'ingest_undo'); } catch { return { outcome: 'segmented' }; }
let body: string | null = snap.page.compiled_truth;
for (const n of rowNums) {
body = body === null ? null : strikeFenceRow(body, n, f => ({ ...f, active: false, validUntil: today, context: ['ingest undone', f.context?.trim()].filter(Boolean).join(' | ') }));
}
- if (body === null) return 'changed';
+ if (body === null) return { outcome: 'changed' };
const content = serializePageToMarkdown({ ...snap.page, compiled_truth: body } as Page, snap.tags);
const r = await publish(ctx, sourceId, { slug, content, expected_revision: snap.revision });
- return r.ok ? 'struck' : 'changed';
+ if (!r.ok) return { outcome: 'changed' };
+ return { outcome: 'struck', ...(typeof r.response.revision === 'string' ? { revision: r.response.revision } : {}) };
}
async function runUndo(ctx: OperationContext, p: Params): Promise<Record<string, unknown>> {
@@ -703,16 +713,19 @@ async function runUndo(ctx: OperationContext, p: Params): Promise<Record<string,
for (const r of current.retract) byPage.set(r.entity_slug, [...(byPage.get(r.entity_slug) ?? []), r.row_num]);
let retracted = 0;
const skipped = [...current.skipped];
+ // Every delete is bound to the revision this apply verified (#8562), or to the revision its own strike published.
+ const verified = new Map(current.delete.map(d => [d.slug, d.revision]));
for (const [slug, rowNums] of byPage) {
- const outcome = await strikeRows(ctx, sourceId, slug, rowNums, today);
+ const { outcome, revision } = await strikeRows(ctx, sourceId, slug, rowNums, today, verified.get(slug));
if (outcome === 'struck') retracted += rowNums.length;
else for (const n of rowNums) skipped.push({ kind: 'fact', ref: slug + '#' + n, reason: outcome });
+ if (verified.has(slug) && outcome !== 'segmented') verified.set(slug, revision ?? '');
}
const { submitPageMutation } = await import('../persistence/page-mutations.ts');
let deleted = 0;
for (const d of current.delete) {
- const revision = await snapshotRevision(ctx, sourceId, d.slug);
- if (!revision) continue;
+ const revision = verified.get(d.slug);
+ if (!revision) { skipped.push({ kind: 'page', ref: d.slug, reason: 'changed' }); continue; }
try {
await submitPageMutation(ctx, { operation: 'delete_page', params: { slug: d.slug, source_id: sourceId, expected_revision: revision, request_id: randomUUID() } });
deleted++;
diff --git a/test/e2e/ingest-postgres.test.ts b/test/e2e/ingest-postgres.test.ts
index e62563e8a5..4e68103a96 100644
--- a/test/e2e/ingest-postgres.test.ts
+++ b/test/e2e/ingest-postgres.test.ts
@@ -85,6 +85,7 @@ d('ingest and ingest_undo (live Postgres)', () => {
test('ambiguous namesake (' + label + ')', async () => { fx = await fixture(storage); await S.ambiguousNamesakeScenario(engine); }, 60_000);
test('failed commit resumed keeps ownership (' + label + ')', async () => { fx = await fixture(storage); await S.failedCommitResumeUndoScenario(engine); }, 90_000);
test('pending page write resumes (' + label + ')', async () => { fx = await fixture(storage); await S.pendingPageResumeScenario(engine); }, 90_000);
+ test('undo keeps a replaced source document (' + label + ')', async () => { fx = await fixture(storage); await S.undoKeepsReplacedSourceScenario(engine); }, 90_000);
}
test('Git target unavailable refuses before writes', async () => { fx = await fixture('git'); await S.storageUnavailableScenario(engine); }, 60_000);
});
diff --git a/test/helpers/ingest-scenarios.ts b/test/helpers/ingest-scenarios.ts
index ccba632795..07cc34b829 100644
--- a/test/helpers/ingest-scenarios.ts
+++ b/test/helpers/ingest-scenarios.ts
@@ -786,3 +786,43 @@ export async function failedCommitResumeUndoScenario(engine: BrainEngine): Promi
expect(await engine.getPage('companies/zentrix')).toBeNull();
} finally { stub.restore(); }
}
+
+/**
+ * Item D (and #8562): undo binds every page it deletes to the revision the attempt wrote. An owner who replaced the
+ * ingested document keeps it (skipped as edited), and an entity page edited after the undo re-checked it is kept too.
+ */
+export async function undoKeepsReplacedSourceScenario(engine: BrainEngine): Promise<void> {
+ const report = await goldenRun(engine);
+ const sourceSlug = report.source_page.slug;
+ const snap = (await engine.readPageSnapshot(sourceSlug, { sourceId: 'default' }))!;
+ await operationsByName.put_page!.handler(reviewCtx(engine), { slug: sourceSlug, expected_revision: snap.revision,
+ content: '---\ntype: note\ntitle: Owner notes\n---\n\nThe owner rewrote this page by hand.\n' });
+ await drain(engine);
+ const preview = await undo(engine, { attempt_id: report.attempt_id });
+ expect(preview.skipped).toEqual(expect.arrayContaining([{ kind: 'page', ref: sourceSlug, reason: 'edited' }]));
+ expect(preview.delete.map((d: Report) => d.slug)).not.toContain(sourceSlug);
+ // #8562: an owner edit of companies/acmx that lands right after the apply step re-checked the page. The re-check is
+ // made to read the page as it was before the edit, so the apply believes the revision the preview saw: neither the
+ // strike of its claim nor the delete may land on the edited page.
+ const before = (await undo(engine, { attempt_id: report.attempt_id })).plan_hash;
+ const stale = (await engine.readPageSnapshot('companies/acmx', { sourceId: 'default' }))!;
+ await operationsByName.edit_page!.handler(reviewCtx(engine), { slug: 'companies/acmx', expected_revision: stale.revision,
+ edits: [{ old_text: 'ACMX announced a new product line for small offices.', new_text: 'ACMX notes the owner wrote mid-undo.' }] });
+ await drain(engine);
+ const original = engine.readPageSnapshot;
+ let staleReads = 0;
+ // A transaction's engine inherits this wrapper, so the real read keeps its own receiver.
+ engine.readPageSnapshot = async function (this: BrainEngine, slug: string, opts?: Record<string, unknown>) {
+ if (slug === 'companies/acmx' && new Error().stack!.includes('planUndo')) { staleReads++; return stale; }
+ return original.call(this, slug, opts as never);
+ } as typeof engine.readPageSnapshot;
+ let applied: Report;
+ try {
+ applied = await undo(engine, { attempt_id: report.attempt_id, yes: true, expect: before });
+ } finally { delete (engine as Partial<BrainEngine>).readPageSnapshot; }
+ expect(staleReads).toBe(2);
+ await drain(engine);
+ expect(applied.status).toBe('undone');
+ expect((await engine.getPage(sourceSlug))!.compiled_truth).toContain('The owner rewrote this page by hand.');
+ expect((await engine.getPage('companies/acmx'))!.compiled_truth).toContain('ACMX notes the owner wrote mid-undo.');
+}
diff --git a/test/ingest.serial.test.ts b/test/ingest.serial.test.ts
index 07f901867e..8449ef74ae 100644
--- a/test/ingest.serial.test.ts
+++ b/test/ingest.serial.test.ts
@@ -140,6 +140,10 @@ for (const storage of ['git', 'database'] as ReviewStorage[]) {
fx = await reviewDoorFixture(engine, storage);
await S.failedCommitResumeUndoScenario(engine);
}, 90_000);
+ test('undo keeps a replaced source document and a page edited after its re-check', async () => {
+ fx = await reviewDoorFixture(engine, storage);
+ await S.undoKeepsReplacedSourceScenario(engine);
+ }, 90_000);
});
}