Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Expire a purged page's facts in the purge transaction

garrytan3513020fc4a9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bc451da828..575b88d47f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,16 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+**A purged page's facts no longer come back.** When the 72-hour retention purge removed a soft-deleted page's row, it left the page's facts active, because facts have no foreign key to pages. Once the tombstone was gone, those facts showed up again for every reader, local and remote, and a new page written at the same slug picked them up. The purge now expires those facts in the same transaction as the page delete: the facts filed on the page, and the facts about it that no other live page holds. The rows are kept, expired, never deleted. Facts another live page holds about the slug stay active.
+
+### Itemized changes
+
+- `src/core/facts/gone-page-facts.ts`: `expireGonePageFacts`, the one predicate for the facts a page takes with it.
+- `src/core/engine-sql/pages.ts` (`purgeDeletedPages`, the bulk purge) and `src/core/persistence/purge-deleted.ts` (`expireRecordedTombstones`, the belief-ledger purge of a recorded source) call it in the purge transaction. The managed purge already sweeps the facts filed on the page.
+- Tests: `test/purge-expires-page-facts.test.ts` (PGLite and Postgres), which fails before the fix on the bulk and recorded purges.
+
## [0.60.637.0] - 2026-11-10
**A file Git puts back after sync deleted its page brings the page back, and the retention purge never deletes a committed file.** On a managed brain, a commit that removed a Markdown file made sync soft-delete its page. When the same file came back (a `git revert`, switching to a branch and back, a collaborator's delete-then-restore, a file missing from disk for one working-tree sync), sync settled the path as "deleted, file unchanged" and left the page out of get, search and recall while `gbrain sync status` said synced. `gbrain pages purge-deleted --yes` then deleted the restored file from the checkout. Sync now tells a tombstone it made from a missing file apart from a person's delete and imports the file over it, so the same page comes back; a brain an older version left in that state heals on its next sync. The purge leaves a file committed at the source's last synced commit or at HEAD alone, unless a person's delete of the page never removed the file (for example because another page shared it). A page purge also stops leaving timeline text in the write journal.
diff --git a/docs/architecture/key-files/memory-purge.md b/docs/architecture/key-files/memory-purge.md
index e751a343f0..5bc5a84f09 100644
--- a/docs/architecture/key-files/memory-purge.md
+++ b/docs/architecture/key-files/memory-purge.md
@@ -8,6 +8,7 @@ User-facing contract: [expire versus purge](../../guides/memory-boundaries.md#pu
- `src/core/facts/purge-verify.ts` — receipts and verification. `verifyFactPurge` runs one bounded adapter per store (row bound, per-statement `statement_timeout`, a total deadline; `__setPurgeProbeLimitsForTests`): swept stores report `deleted`, `incomplete` (still holds the claim) or `unverified` (bound hit); page-text stores report remaining text as `out_of_scope: source_prose`; every `probed_reported` inventory table is probed and listed; derived rows are `retained_inactive`; model-derived pages without edges are `derived_legacy: unverified`. On-disk: page files (`canonical_markdown`), a quarantined `<file>.tmp` carrying the claim is deleted, the facts write-failure log is reported. `gitResidualCommits` scans `git log --all -p -- <page paths>` output in-process (the pattern never enters argv; byte and time bounded) and lists commits; `OUT_OF_REACH_RESIDUALS` lead every receipt. Links, timeline entries and raw data that still carry the claim are named row by row (`link:<id> <from> -> <to>`, `timeline:<id> <slug> <date>`, `raw_data:<id> <slug> <source>`, up to 20); queued `persistence_effects` whose data, outcome or recovery carry it are reported; `belief_events` and `fact_context` get ledger reports. The vector probe returns same-model neighbours as paraphrase candidates and is never a gate. `purgeCompletion` derives `committed | complete | incomplete` from effects (failed or parked = incomplete), a fingerprint probe and the receipt, with exit codes 10/0/75. A segmented page or version is probed segment by segment (`segmentedBodyContains`, a needle split by a cut is found; row and time bounded) and reported with the page stores; `page_segment_texts` gets an exact-bytes probe (an unreferenced text holding the claim is `incomplete`, a referenced one `out_of_scope`); the page purge probes the texts its manifests referenced (`PagePurgeContext.segmentShas`).
- `src/core/belief/purge.ts` — the purge half of the belief ledger (BELIEF_LEDGER.md 6.5). Every fact or page purge bumps `sources.purge_epoch` (`bumpPurgeEpoch`; an append prepared at an older epoch with `preparedEpoch` refuses `belief_stale_preparation`) and runs three passes inside the purge transaction: `redactPurgedKeys` (the purged keys, by `claim_fp` and page lifetime, keep skeletons: value, value_hash and prior_hash null, `purged`), `redactCarryingFields` (keyset batches of 1000 reading only the carrying fields of fact, take and link events, matched in JS by `quotes` over `claimForms`, never SQL `lower()`/`strpos`: each carrying field from `CARRYING_FIELDS` that quotes a purged claim, plain or fence-escaped, becomes `REDACTION_MARKER(<purge request>)` and is listed in `redacted_fields`; a later event's prior_hash naming the old hash names the new one) with `registerLiveCarriers` (a surviving row whose field quotes the claim enters `belief_redactions` with its field hash, so its next event writes the marker until an explicit owner edit sets a different value: `publicationBeliefOptions` marks `ownerEdit` only on a local `put_page`, `edit_page`, `takes_update` or `takes_resolve` with no internal intent kind, and append still needs `OWNER_TIER_FLOOR`) and, for a fact purge, `registerVersionCarriers` (the retained versions still quoting the claim, registered under the keys the backfill gives them). A claim shorter than 8 characters quotes a field only as a word in spaced scripts (`ceo` does not match `herbaceous`; CJK and markup still match), and `appendDerivedHidden` (one `derived.hidden` per key the derivation walk hid; `readBeliefHistory` then hides that key's earlier events and every backfill event of it). A page purge's claims come from `pagePurgeClaims`: the page's facts and takes, every retained version's fence rows and every claim in its lifetimes' events, unbounded. `releaseSuppressedFields` is the owner release `trust confirm` runs (`belief_redactions.released_hash`); every release, there or in an owner-edit append, appends one `redaction.released` (`redactionReleasedDraft`: fields, purge requests and released hashes, never the text) in the publication `released_by` names. The receipt's `ledger` block reports the counts and `derived_walk`; a truncated walk withholds certification of its coverage interval (`coverage-report.ts`). Purge-verify's ledger report is a JS keyset scan too: a missed carrying field is `incomplete`, another subject's recorded value quoting the claim is `out_of_scope` with `field@key` items. Seam: `__setPurgeRedactionFaultForTests`. Probes: `test/belief-ledger-purge.test.ts` (both engines).
- `src/core/belief/purge-mirror.ts` — the text-free purge mirror `<brain home>/.gbrain/purge-events.jsonl` (0600, fsynced): an `intent` line before the purge commits (`appendPurgeIntent`; request, source and incarnation, scope, fingerprints, content hashes, lifetimes, epoch; never claim text; an unwritable mirror refuses the purge with the typed `purge_mirror_unwritable`, with or without a ledger) and a `committed` line after (`appendPurgeCommitted`, best effort; a page purge writes it from the coordinator's `afterCommit`, so it does not depend on the op handler finishing). `restorePgliteBackup` (`gbrain backup restore --purge-mirror <absolute path>` names a mirror other than the brain home's) replays every committed purge newer than the archive inside its transaction (`replayPurgesInRestore`: tombstones, row removal (a fact-scope replay rewrites page bodies and versions through `rewritePageBodies` / `redactPageVersions`, then runs `purgeSegmentStorage` with each claim's `stagingsHoldingClaim`; a page-scope replay deletes the page through `deletePageWithSegments`, so segment texts that held the purged content go in the replay, as in the purge), the three passes, the derived rows hidden again with `derived.hidden` cause `restore_replay`, one `fact.purged`/`page.purged` with cause `restore_replay`; a page-scope replay matches pages by content hash or lifetime, never by slug alone; an archive from before the ledger, no `belief_events`, replays tombstones and row removal and reports `ledger: 'absent'`; an intent whose request already has tombstones is skipped), records each as `complete`, `partial` (no restored row held the text, or the derivation walk could not run) or `unverified` (intent without committed line, not replayed), returns `purge_replay` in the receipt and adds a reconnect warning unless the state is `none` or `complete`; an unreadable mirror is `unavailable`. `coverage.restored` carries the outcome, which `readRestorePurgeReplay` reads back for the doctor. A Postgres restore runs `gbrain beliefs replay-purges --archived-at <iso> (--purge-mirror <abs path> | --from-url-env <VAR>) [--apply]` (`src/commands/beliefs-replay-purges.ts`; dry run by default: `replayPurges` runs the replay in a transaction that rolls back), whose database source `purgeLinesFromDatabase` rebuilds the intents from every pre-restore tombstone (not bounded by `purged_at`, the purge transaction's start) and skips those the archive already holds. Seam: `__setPurgeReplayFaultForTests`. Probes: `test/belief-ledger-restore.test.ts`; segment storage after a replay: `test/large-pages/purge-replay-segments.test.ts` (both engines).
+- `src/core/facts/gone-page-facts.ts` — `expireGonePageFacts(exec, pages)`: in the transaction that removes a page row for good, expires (never deletes) the active facts filed on the page and the active facts about it no other live page holds, so they don't come back for readers once the tombstone is gone and a new page at the slug starts clean. Facts have no foreign key to pages. Called by the bulk retention purge (`engine-sql/pages.ts` `purgeDeletedPages`) and the belief-ledger purge of a recorded source (`persistence/purge-deleted.ts` `expireRecordedTombstones`).
- `src/core/facts/purge-overlay.ts` — purge mode of the import overlay: `dropPurgedFenceRows` drops facts-fence rows matching `fact_purges` and takes-fence rows matching `take_purges` (the takes fence re-renders with its reservation rows plus the dropped numbers reserved, so a purged number is never reused; pinned by `test/purge-overlay-reservations.test.ts`) (subject = page slug; malformed fences left to the withdrawal diagnostics, which refuse a purged claim inside one). Called first by `preserveWithdrawnFenceRows`, so `import-file.ts` needs no change; the snapshot overlay (`page-state/snapshot.ts`) and export (`export-snapshot.ts`) carry purge tombstones as `PageWithdrawal.purged`, which `overlayWithdrawalBody` drops instead of striking.
- `src/core/facts/purge-schema.ts` — `MEMORY_PURGE_SCHEMA_SQL` (schema.sql fragment: `fact_purges`, `take_purges`, `page_purges` keyed `(source_id, content_hash)`, `derivation_inputs`, `needs_rederive`) and `MEMORY_PURGE_GUARD_SQL` (migration only): `facts_refuse_purged`, `takes_refuse_purged` and `pages_refuse_purged` raise `P0001 purged_content: …` (mapped to typed `purged_content` by `persistence/publication-failure.ts`) instead of skipping the row, whatever `expired_at` says. The pages guard has no column list so it never pins columns. Since migration v264 `facts_refuse_purged` fires on UPDATE only; the facts insert check runs once per statement in `facts/insert-guard-schema.ts`. `FACT_PURGE_LOOKUP_INDEX_SQL` (migration v231, CONCURRENTLY on Postgres) adds `fact_purges_subject_idx` (a page's own tombstones, the '*' lookup by fingerprint) and the partial `fact_purges_all_subjects_idx` (subject '*' only, for the snapshot marker count).
- `src/core/facts/insert-guard-schema.ts` — `FACT_INSERT_GUARD_SQL` (migration v264, #7105): one statement-level `facts_guard_inserted` trigger (`AFTER INSERT ... REFERENCING NEW TABLE AS inserted_facts`, function `gbrain_guard_inserted_facts`) runs the purge refusal, and the withdrawal stamp of deferred inserts, once per statement instead of once per row. It takes `FOR SHARE` on each inserted source row, refuses a statement whose rows match a `fact_purges` tombstone with the same `P0001 purged_content` message and `{table, hash8}` detail (the first matching row in insertion order, whatever its `expired_at`), then stamps inserted active rows still matching `fact_withdrawals` (v2 or v1 fingerprint) with `expired_at = min(withdrawn_at)` and a clamped `valid_until`, by an UPDATE of just those rows, run under the transaction-local `gbrain.fact_withdrawal_stamp` setting (`FACT_WITHDRAWAL_STAMP_SETTING`, reset after the UPDATE) so `gbrain_stamp_write_attribution` keeps the `last_write_*` and `last_written_at` the INSERT stamped or supplied. By default an insert is stamped before it is written by the per-row `facts_preserve_withdrawal_insert` (`BEFORE INSERT ... WHEN (NEW.expired_at IS NULL AND <deferral off>)`, the original function), so `INSERT ... RETURNING` reads the stamp; the bulk fence insert (`engine-sql/facts.ts` `insertFactRows`) sets `gbrain.fact_withdrawal_stamp_deferred` (`FACT_WITHDRAWAL_STAMP_DEFERRED_SETTING`) around its INSERTs, so the WHEN clause, which calls no function, skips the trigger and the statement guard stamps instead. The setting moves the stamp and never skips it: the guard stamps every still-matching active row whoever set it. A ledger with no row for the inserted sources costs one index probe. Transition tables cannot take a column list, so `facts_refuse_purged` and `facts_preserve_withdrawal` stay per-row for UPDATE (`BEFORE UPDATE OF ...`). Differences from the per-row insert guards: (1) a row ON CONFLICT DO NOTHING skips is not checked (it is not written either); (2) a row that another per-row BEFORE trigger (for example `managed_writer_guard`) or a constraint also refuses reports that refusal first; (3) a deferred insert is stamped after its RETURNING, so `INSERT ... RETURNING expired_at, valid_until` (or a CTE reading it in the same query) made under the deferral setting sees a withdrawn row unstamped while storage and every later statement see the stamp (`insertFactRows` returns only ids, slugs and row numbers). Pinned by `test/facts-insert-guards-7105.test.ts` (guard calls and firings per statement, RETURNING with and without deferral, and the same refusals, stamps and attribution as the per-row guards re-installed in a rolled-back transaction, both engines). #7778 (migration v279, `FACT_INSERT_GUARD_FUNCTION_SQL`): the purge refusal skips an extraction outcome row (`isOutcomeMarker` / `outcomeMarkerSql` in `facts/audit-sources.ts`: a conversation-facts audit source AND the exact text `EXTRACTION_COMPLETE` or `EXTRACTION_NOT_APPLICABLE`), so a wildcard tombstone a page purge wrote before the fix no longer keeps pages from completing; a user claim with that text is still refused. Pinned by `test/conversation-facts-outcome-marker-purge-7778.test.ts`.
diff --git a/src/core/engine-sql/pages.ts b/src/core/engine-sql/pages.ts
index 5d63fbe41f..b93425499f 100644
--- a/src/core/engine-sql/pages.ts
+++ b/src/core/engine-sql/pages.ts
@@ -40,6 +40,7 @@ import { renderFragment, sqlFragment, trustedSql, type SqlFragment } from './fra
import { frontmatterWhereFragment } from '../search/frontmatter-where.ts';
import { quoteIdentifier, resolveWriteColumnFromConfigRows } from '../search/embedding-column.ts';
import { pickCanonicalOrigin } from '../persistence/origin-guard.ts';
+import { expireGonePageFacts } from '../facts/gone-page-facts.ts';
/**
* PGLite can return zero rows from `INSERT ... ON CONFLICT DO UPDATE ...
@@ -353,6 +354,7 @@ export async function purgeDeletedPages(
AND ${trustedSql(derivedRetirementPurgeHold('pages'))}${excluded}
RETURNING slug, source_id
`);
+ await expireGonePageFacts(tx, rows);
if (rows.length) await tx.run(sqlFragment`DELETE FROM page_body_stagings s USING unnest(${rows.map(r => r.source_id)}::text[], ${rows.map(r => r.slug)}::text[]) AS d(source_id, slug)
WHERE s.source_id = d.source_id AND s.slug = d.slug`);
if (texts.length) await tx.run(sqlFragment`DELETE FROM page_segment_texts t
diff --git a/src/core/facts/gone-page-facts.ts b/src/core/facts/gone-page-facts.ts
new file mode 100644
index 0000000000..2e880cb315
--- /dev/null
+++ b/src/core/facts/gone-page-facts.ts
@@ -0,0 +1,23 @@
+/**
+ * The facts a page takes with it when its row goes away for good, or a new page replaces its tombstone: the active
+ * facts filed on the page, and the active facts about it that no other live page holds. They are expired (kept, never
+ * deleted), because facts have no foreign key to pages: left active, they would come back for every reader once the
+ * tombstone that hid them is gone, and a new page at the slug would inherit them. Facts another live page holds about
+ * the slug stay that page's. One predicate for every caller (the retention purges here, and a put over a tombstone).
+ */
+
+/** `$1` source ids and `$2` slugs, paired by position. */
+const EXPIRE_GONE_PAGE_FACTS_SQL = `UPDATE facts f SET expired_at = now(), row_num = NULL
+ FROM unnest($1::text[], $2::text[]) AS g(source_id, slug)
+ WHERE f.source_id = g.source_id AND f.expired_at IS NULL
+ AND (f.source_markdown_slug = g.slug OR (f.entity_slug = g.slug AND NOT EXISTS (SELECT 1 FROM pages lp
+ WHERE lp.source_id = f.source_id AND lp.slug = f.source_markdown_slug AND lp.slug <> g.slug AND lp.deleted_at IS NULL)))`;
+
+/** Expires the gone pages' facts; run it in the transaction that removes or replaces the pages. */
+export async function expireGonePageFacts(
+ exec: { executeRaw(sql: string, params?: unknown[]): Promise<unknown[]> },
+ pages: ReadonlyArray<{ source_id: string; slug: string }>,
+): Promise<void> {
+ if (!pages.length) return;
+ await exec.executeRaw(EXPIRE_GONE_PAGE_FACTS_SQL, [pages.map(p => p.source_id), pages.map(p => p.slug)]);
+}
diff --git a/src/core/persistence/purge-deleted.ts b/src/core/persistence/purge-deleted.ts
index 66ca381397..081606f3ad 100644
--- a/src/core/persistence/purge-deleted.ts
+++ b/src/core/persistence/purge-deleted.ts
@@ -18,6 +18,7 @@ import { writerOnboardingPreflight } from './onboarding.ts';
import { clearPurgePark, isParked, notePurgeSourceWriter, PURGE_PARK_LIMIT, purgeParkKey, prunePurgeParks, readPurgeParks, recordPurgeFailure, type PurgePark } from './purge-parks.ts';
import { ItemRun, type ItemFailure } from '../item-failure.ts';
import { readUnreviewedSyncTombstones, syncDeleteHeld } from './sync-delete-tombstones.ts';
+import { expireGonePageFacts } from '../facts/gone-page-facts.ts';
/** A tombstone that moved under a concurrent writer; the next run retries it. */
const DEFERRAL_CODES = new Set(['revision_conflict', 'page_not_found', 'page_identity_changed']);
@@ -130,8 +131,12 @@ async function expireRecordedTombstones(engine: BrainEngine, olderThanHours: num
const slugs = [...new Set([row.slug, ...await linkStreamSlugs(tx, row.source_id, row.id)])].sort();
await tx.lockPageKeys(slugs.map(slug => ({ sourceId: row.source_id, slug })));
return withBeliefBatch(tx, { sourceId: row.source_id, slugs, publicationId, op: 'purge_deleted_pages', hardDeleteEvent: 'page.expired', report },
- async () => (await tx.executeRaw(`DELETE FROM pages WHERE id = $1 AND deleted_at IS NOT NULL AND deleted_at < now() - ($2 || ' hours')::interval AND ${identityDowngradePurgeHold('pages')} AND ${atomRetirementPurgeHold('pages')} AND ${derivedRetirementPurgeHold('pages')} RETURNING id`,
- [row.id, hours])).length > 0);
+ async () => {
+ const gone = await tx.executeRaw<{ source_id: string; slug: string }>(`DELETE FROM pages WHERE id = $1 AND deleted_at IS NOT NULL AND deleted_at < now() - ($2 || ' hours')::interval AND ${identityDowngradePurgeHold('pages')} AND ${atomRetirementPurgeHold('pages')} AND ${derivedRetirementPurgeHold('pages')} RETURNING source_id, slug`,
+ [row.id, hours]);
+ await expireGonePageFacts(tx, gone);
+ return gone.length > 0;
+ });
});
run.succeed();
if (report.appended) await markBeliefCommits(engine, [publicationId]).catch(() => undefined);
diff --git a/test/postgres-unit-arms.txt b/test/postgres-unit-arms.txt
index 9964a2a016..7869797bca 100644
--- a/test/postgres-unit-arms.txt
+++ b/test/postgres-unit-arms.txt
@@ -457,6 +457,7 @@ test/persistence-writer-fences.test.ts
test/physical-root-birth-tolerance-6501.test.ts
test/provenance-drift-7891.test.ts
test/provenance-stamps-7873.test.ts
+test/purge-expires-page-facts.test.ts
test/purge-fact.test.ts
test/purge-global-marker.test.ts
test/purge-missing-cache-6911.test.ts
diff --git a/test/purge-expires-page-facts.test.ts b/test/purge-expires-page-facts.test.ts
new file mode 100644
index 0000000000..df53fec847
--- /dev/null
+++ b/test/purge-expires-page-facts.test.ts
@@ -0,0 +1,152 @@
+/**
+ * A retention purge of a soft-deleted page expires that page's active facts, in the same transaction as the purge.
+ *
+ * 1. Protects: after the purge removes a deleted page's row, the facts the page held and the facts about it that no live
+ * page holds are expired (kept, never deleted), so they don't come back for any reader, local or remote, and a new
+ * page written at the slug starts clean. A fact a live page holds about the slug stays active, and so do facts about
+ * other pages.
+ * 2. Fails when: a purge deletes the page row and leaves its facts with expired_at NULL (facts have no foreign key to
+ * pages), on the bulk purge (purgeDeletedPages) or the belief-ledger purge of a recorded source
+ * (expireRecordedTombstones); or the fix deletes a fact row instead of expiring it. The managed purge, which already
+ * sweeps the facts filed on the page, is pinned alongside.
+ * 3. Real seams: writes and reads dispatched through MCP dispatch, remote reads with a minted token verified by the
+ * OAuth provider; a repo-less source, an unmanaged source the belief ledger records, and a managed brain; embeddings stubbed.
+ */
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import type { BrainEngine } from '../src/core/engine.ts';
+import { PGLiteEngine } from '../src/core/pglite-engine.ts';
+import { configureGateway, resetGateway, __setEmbedTransportForTests } from '../src/core/ai/gateway.ts';
+import { GBrainOAuthProvider } from '../src/core/oauth-provider.ts';
+import { sqlQueryForEngine } from '../src/core/sql-query.ts';
+import { mintLegacyToken } from '../src/core/token-mint.ts';
+import { dispatchToolCall } from '../src/mcp/dispatch.ts';
+import { purgeDeletedPagesCoordinated } from '../src/core/persistence/purge-deleted.ts';
+import { __resetPrivateVisibilityCacheForTests } from '../src/core/search/private-visibility.ts';
+import type { AuthInfo } from '../src/core/ops/contract.ts';
+import { testBackends } from './helpers/test-backends.ts';
+import { isolatedPersistencePostgres } from './helpers/persistence-postgres.ts';
+import { managedBrain } from './helpers/managed-brain.ts';
+import { beliefBrain } from './helpers/belief-ledger.ts';
+
+const DIMS = 1536;
+function vectorFor(text: string): number[] {
+ const v = new Array<number>(DIMS).fill(0);
+ for (const w of text.toLowerCase().match(/[a-z]+/g) ?? []) {
+ let h = 0;
+ for (const ch of w) h = (h * 31 + ch.charCodeAt(0)) >>> 0;
+ v[h % DIMS] += 1;
+ }
+ const n = Math.hypot(...v) || 1;
+ return v.map(x => x / n);
+}
+const text = (out: { content: Array<{ text: string }> }) => out.content.map(c => c.text).join('\n');
+
+const SLUG = 'people/carol-example', OTHER = 'people/dan-example';
+const person = (title: string, body: string) => `---\ntype: person\ntitle: ${title}\n---\n# ${title}\n\n${body}`;
+
+/** A fixture write outside coordination; on a managed brain the writer guard is paused around it. */
+async function fixture(engine: BrainEngine, sql: string, params: unknown[]): Promise<void> {
+ const [brain] = await engine.executeRaw<{ enabled: boolean }>('SELECT enabled FROM persistence_brain WHERE singleton = 1');
+ if (brain?.enabled) await engine.executeRaw('UPDATE persistence_brain SET enabled = false WHERE singleton = 1');
+ try { await engine.executeRaw(sql, params); }
+ finally { if (brain?.enabled) await engine.executeRaw('UPDATE persistence_brain SET enabled = true WHERE singleton = 1'); }
+}
+
+/**
+ * Seeds a page with a fact about it, a fact a live page holds about it and a fact about another page, deletes the page,
+ * ages the tombstone past the window and runs `purge`; then checks every reader and a new page at the slug.
+ */
+async function purgedPageScenario(engine: BrainEngine, source: string, purge: () => Promise<string[]>, opts: { remoteReader?: boolean; sweepsFiled?: boolean } = {}) {
+ const remoteReader = opts.remoteReader === true;
+ __resetPrivateVisibilityCacheForTests();
+ const local = async (op: string, params: Record<string, unknown>) =>
+ dispatchToolCall(engine, op, { ...params }, { remote: false, sourceId: source }) as Promise<{ isError?: boolean; content: Array<{ text: string }> }>;
+ const write = async (op: string, params: Record<string, unknown>) => {
+ const out = await local(op, params);
+ if (out.isError) throw new Error(`fixture ${op}: ${text(out)}`);
+ return text(out);
+ };
+ let token = '';
+ const remote = async (op: string, params: Record<string, unknown>) => {
+ const provider = new GBrainOAuthProvider({ sql: sqlQueryForEngine(engine), transaction: fn => engine.transaction(tx => fn(sqlQueryForEngine(tx))) });
+ const auth = await provider.verifyAccessToken(token) as unknown as AuthInfo;
+ return dispatchToolCall(engine, op, { ...params }, { remote: true, transport: 'http', auth, sourceId: auth.sourceId ?? source,
+ takesHoldersAllowList: ['world'], sessionId: 'purge-expires-page-facts' }) as Promise<{ content: Array<{ text: string }> }>;
+ };
+ if (remoteReader) token = (await mintLegacyToken(engine, { name: 'reader', scopes: ['read'], takesHolders: ['world'], sourceGrant: [source] })).token;
+ const revision = async () => (JSON.parse(await write('get_page', { slug: SLUG, include_deleted: true })) as { revision: string }).revision;
+ const facts = () => engine.executeRaw<{ fact: string; expired: boolean }>(
+ 'SELECT fact, expired_at IS NOT NULL AS expired FROM facts WHERE source_id = $1 ORDER BY fact', [source]);
+
+ await write('put_page', { slug: OTHER, content: person('Dan Example', 'Dan notes.') });
+ await write('put_page', { slug: SLUG, content: person('Carol Example', 'Carol notes.') });
+ await write('remember', { fact: 'Carol Example harbor canarypurgedfact', entity: SLUG, provenance: 'fixture', visibility: 'world' });
+ await write('remember', { fact: 'Carol Example harbor canaryheldelsewhere', entity: SLUG, provenance: 'fixture', visibility: 'world' });
+ await write('remember', { fact: 'Dan Example harbor canaryotherpage', entity: OTHER, provenance: 'fixture', visibility: 'world' });
+ // A fact the live page OTHER holds about SLUG.
+ await fixture(engine, "UPDATE facts SET source_markdown_slug = $2 WHERE source_id = $1 AND fact LIKE '%canaryheldelsewhere'", [source, OTHER]);
+ expect((await facts()).map(f => f.expired)).toEqual([false, false, false]);
+
+ await write('delete_page', { slug: SLUG, expected_revision: await revision() });
+ await fixture(engine, "UPDATE pages SET deleted_at = deleted_at - interval '100 hours' WHERE source_id = $1 AND slug = $2", [source, SLUG]);
+ expect(await purge()).toContain(SLUG);
+ expect((await engine.executeRaw('SELECT 1 FROM pages WHERE source_id = $1 AND slug = $2', [source, SLUG])).length).toBe(0);
+
+ // The managed purge sweeps the facts filed on the page (page-purge.ts); the other purges keep the row, expired.
+ const expected = [
+ { fact: 'Carol Example harbor canaryheldelsewhere', expired: false },
+ ...(opts.sweepsFiled ? [] : [{ fact: 'Carol Example harbor canarypurgedfact', expired: true }]),
+ { fact: 'Dan Example harbor canaryotherpage', expired: false },
+ ];
+ expect(await facts()).toEqual(expected);
+ const reads = async () => {
+ const out = [['local', text(await local('recall', { entity: SLUG }))]];
+ if (remoteReader) out.push(['remote', text(await remote('recall', { entity: SLUG }))]);
+ return out;
+ };
+ for (const [who, seen] of await reads()) {
+ expect({ who, purged: seen.includes('canarypurgedfact') }).toEqual({ who, purged: false });
+ expect({ who, held: seen.includes('canaryheldelsewhere') }).toEqual({ who, held: true });
+ }
+
+ await write('put_page', { slug: SLUG, content: person('Carol Two', 'A different page. canarynewpage') });
+ for (const [who, seen] of await reads()) expect({ who, purged: seen.includes('canarypurgedfact') }).toEqual({ who, purged: false });
+ expect(await facts()).toEqual(expected);
+}
+
+for (const kind of testBackends()) {
+ const databaseUrl = kind === 'postgres' ? process.env.DATABASE_URL! : undefined;
+ describe(`a purged page's facts stay expired (${kind})`, () => {
+ beforeAll(() => {
+ configureGateway({ embedding_model: 'openai:text-embedding-3-small', embedding_dimensions: DIMS, env: { OPENAI_API_KEY: 'test' } });
+ __setEmbedTransportForTests((async ({ values }: { values: string[] }) => ({ embeddings: values.map(vectorFor) })) as never);
+ });
+ afterAll(() => { __setEmbedTransportForTests(null); resetGateway(); });
+
+ test('repo-less source, bulk purge: the page\'s facts are expired with it, for local and remote readers and a new page at the slug', async () => {
+ let engine: BrainEngine, close: () => Promise<void>;
+ if (databaseUrl) ({ engine, close } = await isolatedPersistencePostgres(databaseUrl));
+ else { const pglite = new PGLiteEngine(); await pglite.connect({ engine: 'pglite' } as never); await pglite.initSchema(); engine = pglite; close = () => pglite.disconnect(); }
+ try {
+ await engine.executeRaw("INSERT INTO sources (id, name) VALUES ('source-a', 'source-a') ON CONFLICT (id) DO NOTHING");
+ await purgedPageScenario(engine, 'source-a', async () => (await engine.purgeDeletedPages(72)).slugs, { remoteReader: true });
+ } finally { await close(); }
+ }, 240_000);
+
+ test('unmanaged source the belief ledger records: the per-tombstone purge expires the page\'s facts too', async () => {
+ await beliefBrain(async b => {
+ await purgedPageScenario(b.engine, b.sourceId, async () => {
+ const result = await purgeDeletedPagesCoordinated(b.engine, 72);
+ expect((await b.events()).some(e => e.slug === SLUG && e.event_type === 'page.expired')).toBe(true);
+ return result.slugs;
+ });
+ }, { managed: false, databaseUrl });
+ }, 240_000);
+
+ test('managed source: the purge sweeps the facts filed on the page and leaves none active', async () => {
+ await managedBrain(async ({ engine }) => {
+ await purgedPageScenario(engine, 'default', async () => (await purgeDeletedPagesCoordinated(engine, 72)).slugs, { sweepsFiled: true });
+ }, databaseUrl ? { databaseUrl } : {});
+ }, 240_000);
+ });
+}