Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Match the purge set by source and slug on a brain without managed persistence

garrytan74e69e33641e
diff --git a/changelog.d/capy-gbra438-upkeep-core.md b/changelog.d/capy-gbra438-upkeep-core.md
index f2dd83559a..22aaeb9611 100644
--- a/changelog.d/capy-gbra438-upkeep-core.md
+++ b/changelog.d/capy-gbra438-upkeep-core.md
@@ -4,7 +4,7 @@
- `gbrain maintain --status` shows when upkeep last ran, what each step did, what failed, and when the next run is due.
- A new doctor check, `unattended_maintenance`, reports the same thing. It warns when upkeep hasn't run for 48 hours or a step keeps failing, and its fix is `gbrain maintain --unattended`. A brain where `maintenance.auto` is `false`, or where autopilot runs upkeep, reads as ok.
-- `gbrain maintain --purge` previews which soft-deleted pages are past their 72-hour window. `--yes --expect <hash>` purges exactly the previewed set, and refuses with `preview_changed` when the set moved since the preview. Upkeep never purges pages on its own.
+- `gbrain maintain --purge` previews which soft-deleted pages are past their 72-hour window. `--yes --expect <hash>` purges exactly the previewed set, matching each page by source and slug, and refuses with `preview_changed` when the set moved since the preview. Upkeep never purges pages on its own.
### Smaller changes
diff --git a/src/commands/maintain.ts b/src/commands/maintain.ts
index 043374b93c..e62f970181 100644
--- a/src/commands/maintain.ts
+++ b/src/commands/maintain.ts
@@ -349,9 +349,8 @@ async function runPurgeCli(engine: BrainEngine, opts: MaintainOptions): Promise<
import('../core/persistence/purge-deleted.ts'), import('../core/sync-reconcile.ts')]);
const retention = await readPurgeRetentionHours(engine);
const selection = await selectPurgeCandidates(engine, retention, { automatic: true });
- const pages: Array<{ source_id?: string; slug: string }> = selection.managed
- ? selection.candidates.map((c) => ({ source_id: c.source_id, slug: c.slug }))
- : selection.slugs.map((slug) => ({ slug }));
+ const pages: Array<{ source_id: string; slug: string }> = (selection.managed ? selection.candidates : selection.pages ?? [])
+ .map((p) => ({ source_id: p.source_id, slug: p.slug }));
const hash = purgePreviewHash(retention, pages);
const apply = ['gbrain', 'maintain', '--purge', '--yes', '--expect', hash];
if (!opts.yes) {
@@ -360,7 +359,7 @@ async function runPurgeCli(engine: BrainEngine, opts: MaintainOptions): Promise<
why: `Permanently deletes the ${pages.length} page(s) listed (soft-deleted more than ${retention}h ago); gbrain restore cannot bring them back.` }, cliRenderContext()) } : {}) };
if (opts.json) { console.log(JSON.stringify(preview, null, 2)); return; }
console.log(`${pages.length} soft-deleted page(s) are past the ${retention}h recovery window.`);
- for (const p of pages.slice(0, 50)) console.log(` ${p.source_id ?? 'default'}/${p.slug}`);
+ for (const p of pages.slice(0, 50)) console.log(` ${p.source_id}/${p.slug}`);
if (pages.length > 50) console.log(` ...and ${pages.length - 50} more`);
if (pages.length) console.log(`Nothing was deleted. To purge exactly these, run: ${apply.join(' ')}`);
return;
@@ -371,9 +370,8 @@ async function runPurgeCli(engine: BrainEngine, opts: MaintainOptions): Promise<
setCliExitVerdict(writeCliError(opError('preview_changed', why, 'Preview again: gbrain maintain --purge', { fix, detail: `current hash ${hash}` }), 'maintain', { json: !!opts.json }));
return;
}
- const previewed = new Set(pages.map((p) => p.source_id ? `${p.source_id}/${p.slug}` : p.slug));
- const result = await purgeDeletedPagesCoordinated(engine, retention, {
- automatic: true, only: (p) => previewed.has(selection.managed ? `${p.source_id}/${p.slug}` : p.slug) });
+ const previewed = new Set(pages.map((p) => `${p.source_id}/${p.slug}`));
+ const result = await purgeDeletedPagesCoordinated(engine, retention, { automatic: true, only: (p) => previewed.has(`${p.source_id}/${p.slug}`) });
if (result.error) setCliExitVerdict(1);
if (opts.json) { console.log(JSON.stringify({ mode: 'applied', purged: result.count, slugs: result.slugs, blocked: result.blocked, deferred: result.deferred, ...(result.error ? { error: result.error } : {}) }, null, 2)); return; }
console.log(`Purged ${result.count} page(s).${result.blocked.length ? ` ${result.blocked.length} blocked; see --json.` : ''}`);
diff --git a/src/core/engine-sql/pages.ts b/src/core/engine-sql/pages.ts
index 5f5a4b7092..26c89c2862 100644
--- a/src/core/engine-sql/pages.ts
+++ b/src/core/engine-sql/pages.ts
@@ -318,7 +318,7 @@ export async function purgeDeletedPages(
exec: SqlExecutor,
olderThanHours: number,
opts?: { dryRun?: boolean; excludeIds?: number[] },
-): Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date }[] }> {
+): Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date }[] }> {
// Clamp to non-negative integer; runaway purge protection. The DELETE
// cascades through content_chunks, page_links, chunk_relations via FKs.
const hours = Math.max(0, Math.floor(olderThanHours));
@@ -330,8 +330,8 @@ export async function purgeDeletedPages(
// SAME WHERE predicate as the DELETE below (same cutoff arithmetic,
// same DB now() clock source) — only the verb differs, so preview and
// purge agree modulo rows crossing the cutoff between statements.
- const { rows } = await exec.run<{ slug: string; deleted_at: Date | string }>(sqlFragment`
- SELECT slug, deleted_at FROM pages
+ const { rows } = await exec.run<{ slug: string; source_id: string; deleted_at: Date | string }>(sqlFragment`
+ SELECT slug, source_id, deleted_at FROM pages
WHERE deleted_at IS NOT NULL
AND deleted_at < now() - (${hours} || ' hours')::interval
AND NOT EXISTS (SELECT 1 FROM op_checkpoints dg WHERE dg.op = 'sync-identity-downgrade' AND dg.fingerprint = pages.id::text
@@ -342,6 +342,7 @@ export async function purgeDeletedPages(
`);
const pages = rows.map((r) => ({
slug: r.slug,
+ source_id: r.source_id,
deleted_at: r.deleted_at instanceof Date ? r.deleted_at : new Date(r.deleted_at),
}));
return { slugs: pages.map((p) => p.slug), count: pages.length, pages };
diff --git a/src/core/engine.ts b/src/core/engine.ts
index 1c7c846989..fc01aa4275 100644
--- a/src/core/engine.ts
+++ b/src/core/engine.ts
@@ -1063,7 +1063,7 @@ export interface BrainEngine {
* cutoff arithmetic, same DB `now()` clock source) instead of the DELETE,
* so the preview and a subsequent real run agree up to whatever crosses
* the cutoff (or is soft-deleted/restored) between the two statements.
- * Dry-run responses additionally carry `pages` (slug + deleted_at) for
+ * Dry-run responses additionally carry `pages` (slug, source_id, deleted_at) for
* display; the destructive path leaves `pages` undefined.
* `opts.excludeIds` keeps those page ids out of both (GBRA-130 A-49: the
* tombstones the unmanaged belief-ledger expiry failed or parked).
@@ -1071,7 +1071,7 @@ export interface BrainEngine {
purgeDeletedPages(
olderThanHours: number,
opts?: { dryRun?: boolean; excludeIds?: number[] },
- ): Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date }[] }>;
+ ): Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date }[] }>;
/**
* v0.26.5: by default `listPages` excludes soft-deleted rows. Set
* `filters.includeDeleted: true` to surface them.
diff --git a/src/core/persistence/purge-deleted.ts b/src/core/persistence/purge-deleted.ts
index 0a5cd49698..52a1056fd5 100644
--- a/src/core/persistence/purge-deleted.ts
+++ b/src/core/persistence/purge-deleted.ts
@@ -193,7 +193,7 @@ export interface PurgeSelection {
count: number;
slugs: string[];
/** Unmanaged only: the engine's preview rows. */
- pages?: Array<{ slug: string; deleted_at: Date }>;
+ pages?: Array<{ slug: string; source_id: string; deleted_at: Date }>;
candidates: PurgeCandidate[];
/** Tombstones not submitted: their source's writer needs recovery (`writer_not_active`) or they are parked (`purge_parked`). */
blocked: DeletedPagePurge['blocked'];
diff --git a/src/core/pglite-engine.ts b/src/core/pglite-engine.ts
index 1e424a3b99..4e02d153bc 100644
--- a/src/core/pglite-engine.ts
+++ b/src/core/pglite-engine.ts
@@ -1317,7 +1317,7 @@ export class PGLiteEngine implements BrainEngine {
async purgeDeletedPages(
olderThanHours: number,
opts?: { dryRun?: boolean; excludeIds?: number[] },
- ): Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date }[] }> {
+ ): Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date }[] }> {
return pagesImpl.purgeDeletedPages(this.engineSql, olderThanHours, opts);
}
diff --git a/src/core/postgres-engine.ts b/src/core/postgres-engine.ts
index d9d95ac7d8..618da58e2d 100644
--- a/src/core/postgres-engine.ts
+++ b/src/core/postgres-engine.ts
@@ -945,7 +945,7 @@ export class PostgresEngine implements BrainEngine {
async purgeDeletedPages(
olderThanHours: number,
opts?: { dryRun?: boolean; excludeIds?: number[] },
- ): Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date }[] }> {
+ ): Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date }[] }> {
return pagesImpl.purgeDeletedPages(this.engineSql, olderThanHours, opts);
}
diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.json
index 99796413ed..3619c27857 100644
--- a/test/fixtures/goldens/exports/types.json
+++ b/test/fixtures/goldens/exports/types.json
@@ -179,7 +179,7 @@
"mergeOntologyFact: (obs: OntologyObservationInput) => Promise<OntologyMergeResult>",
"migrateFactsToCanonical: (phantomSlug: string, canonicalSlug: string, sourceId: string) => Promise<{ migrated: number; }>",
"openBodyStaging: (input: BodyStagingInput) => Promise<void>",
- "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date; }[]; }>",
+ "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date; }[]; }>",
"putContradictionCacheEntry: (opts: { chunk_a_hash: string; chunk_b_hash: string; model_id: string; prompt_version: string; truncation_policy: string; verdict: Record<string, unknown>; ttl_seconds?: number; }) => Promise<void>",
"putDreamVerdict: (filePath: string, contentHash: string, verdict: DreamVerdictInput) => Promise<void>",
"putPage: (slug: string, page: PageInput, opts?: PageWriteOptions) => Promise<Page>",
@@ -1239,7 +1239,7 @@
"private vectorIterativeScanSupported",
"private vectorScope",
"private withScopedReadTransaction",
- "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date; }[]; }>",
+ "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date; }[]; }>",
"putContradictionCacheEntry: (opts: { chunk_a_hash: string; chunk_b_hash: string; model_id: string; prompt_version: string; truncation_policy: string; verdict: Record<string, unknown>; ttl_seconds?: number; }) => Promise<void>",
"putDreamVerdict: (filePath: string, contentHash: string, verdict: DreamVerdictInput) => Promise<void>",
"putPage: (slug: string, page: PageInput, opts?: PageWriteOptions) => Promise<Page>",
@@ -3749,7 +3749,7 @@
"mergeOntologyFact: (obs: OntologyObservationInput) => Promise<OntologyMergeResult>",
"migrateFactsToCanonical: (phantomSlug: string, canonicalSlug: string, sourceId: string) => Promise<{ migrated: number; }>",
"openBodyStaging: (input: BodyStagingInput) => Promise<void>",
- "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date; }[]; }>",
+ "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date; }[]; }>",
"putContradictionCacheEntry: (opts: { chunk_a_hash: string; chunk_b_hash: string; model_id: string; prompt_version: string; truncation_policy: string; verdict: Record<string, unknown>; ttl_seconds?: number; }) => Promise<void>",
"putDreamVerdict: (filePath: string, contentHash: string, verdict: DreamVerdictInput) => Promise<void>",
"putPage: (slug: string, page: PageInput, opts?: PageWriteOptions) => Promise<Page>",
@@ -7244,7 +7244,7 @@
"private getBulkRetryOpts",
"private vectorIterativeScan",
"private vectorScope",
- "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; deleted_at: Date; }[]; }>",
+ "purgeDeletedPages: (olderThanHours: number, opts?: { dryRun?: boolean; excludeIds?: number[]; }) => Promise<{ slugs: string[]; count: number; pages?: { slug: string; source_id: string; deleted_at: Date; }[]; }>",
"putContradictionCacheEntry: (opts: { chunk_a_hash: string; chunk_b_hash: string; model_id: string; prompt_version: string; truncation_policy: string; verdict: Record<string, unknown>; ttl_seconds?: number; }) => Promise<void>",
"putDreamVerdict: (filePath: string, contentHash: string, verdict: DreamVerdictInput) => Promise<void>",
"putPage: (slug: string, page: PageInput, opts?: PageWriteOptions) => Promise<Page>",
diff --git a/test/maintenance-unattended.test.ts b/test/maintenance-unattended.test.ts
index 6e119a994b..0cbe25d715 100644
--- a/test/maintenance-unattended.test.ts
+++ b/test/maintenance-unattended.test.ts
@@ -170,6 +170,32 @@ for (const kind of testBackends()) {
expect(await remaining()).toEqual(['notes/recent']);
});
+ test('maintain --purge --expect purges the previewed page, not a same-slug page in another source that became eligible after the preview', async () => {
+ const purgeModule = await import('../src/core/persistence/purge-deleted.ts');
+ await engine.executeRaw("INSERT INTO sources (id, name) VALUES ('source-b', 'source-b')");
+ await engine.putPage('notes/twin', { type: 'concept', title: 'Twin', compiled_truth: 'Deleted long ago.' });
+ await engine.putPage('notes/twin', { type: 'concept', title: 'Twin', compiled_truth: 'Deleted an hour ago.' }, { sourceId: 'source-b' });
+ await engine.softDeletePage('notes/twin');
+ await engine.softDeletePage('notes/twin', { sourceId: 'source-b' });
+ await engine.executeRaw("UPDATE pages SET deleted_at = now() - interval '100 hours' WHERE slug = 'notes/twin' AND source_id = 'default'");
+ const preview = await maintainJson(['--purge', '--json']);
+ expect(preview).toMatchObject({ mode: 'preview', count: 1, pages: [{ slug: 'notes/twin' }] });
+ let raced = 0;
+ const purge = purgeModule.purgeDeletedPagesCoordinated;
+ const spy = spyOn(purgeModule, 'purgeDeletedPagesCoordinated').mockImplementation(async (e, hours, opts) => {
+ await e.executeRaw("UPDATE pages SET deleted_at = now() - interval '100 hours' WHERE slug = 'notes/twin' AND source_id = 'source-b'");
+ raced += 1;
+ return purge(e, hours, opts);
+ });
+ _resetCliExitVerdictForTests();
+ try {
+ await maintainJson(['--purge', '--yes', '--expect', String(preview.hash), '--json']);
+ } finally { spy.mockRestore(); }
+ expect(raced).toBe(1);
+ expect(await engine.executeRaw("SELECT source_id, slug FROM pages WHERE slug = 'notes/twin'")).toEqual([{ source_id: 'source-b', slug: 'notes/twin' }]);
+ expect(preview.pages).toEqual([{ source_id: 'default', slug: 'notes/twin' }]);
+ });
+
test('stamp honesty: a keyed brain keeps last_full_cycle_at and last_source_cycle_at', async () => {
await keyed();
await engine.setConfig('maintenance.embed_daily_usd', '0');