Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Tell the owner how to finish a purge that was held to keep derived pages private

garrytanc7609f6299be
diff --git a/docs/architecture/key-files/commands-2-continued.md b/docs/architecture/key-files/commands-2-continued.md
index 719e3e323f..b2455bee54 100644
--- a/docs/architecture/key-files/commands-2-continued.md
+++ b/docs/architecture/key-files/commands-2-continued.md
@@ -41,7 +41,7 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/commands/doctor/checks/rename-identity-downgrades.ts` — `rename_identity_downgrades` (#6729): warn while a downgraded rename record is open (`sync-identity-downgrades.ts`), naming up to 5 pairs with their facts and links; fix = the first pair's `gbrain repair rename-identity` apply (destructive, `ask_user`, `preview_argv`, `plan_hash`; `--close` on a managed brain), so unbound classic Postgres pairs get an actionable fix too; `gbrain restore <old-slug> --source-id <id> --force` is named as the alternative in its text only where `restore_available !== false`, and `restore_unavailable_sources` lists the rest.
-- `src/commands/doctor/checks/purge-parks.ts` — `purge_parked_pages` (#6741 C): names parked purges with their last error (only this version's parks, `isParked`); fix `gbrain pages purge-deleted --retry-parked --yes` (preview `--dry-run --json`), consent destructive, ask_user. Also `derived_origin_parked` (GST-2689, `checkDerivedOriginParked`): names each origin `persistence/derived-origin-hold.ts` parked with the page that blocks it and the reason (`details.origins`); fix the read-only `gbrain repair visibility --source <id> --slug <blocking page>` preview.
+- `src/commands/doctor/checks/purge-parks.ts` — `purge_parked_pages` (#6741 C): names parked purges with their last error (only this version's parks, `isParked`); fix `gbrain pages purge-deleted --retry-parked --yes` (preview `--dry-run --json`), consent destructive, ask_user. Also `derived_origin_parked` (GST-2689, `checkDerivedOriginParked`): names each origin `persistence/derived-origin-hold.ts` parked with the page that blocks it and the reason (`details.origins`); fix the read-only `gbrain repair visibility --source <id> --slug <blocking page>` preview. An origin whose owner purge was held (`held_request_id`) also gets `finish_argv` (`gbrain delete <slug> --purge --source-id <id>`, a new request), named in the message, since the automatic purge removes it without the purge tombstones.
- `src/commands/doctor/checks/unlinked-facts.ts` — `unlinked_facts` (#5836), registered before `search_mode` and mirrored in `doctorReportRemote`: per the doctor's source scope (`--source`, else every source; the caller's grant remotely), the unlinked share of the newest 100,000 active facts per source (`idx_facts_since` LATERAL walk), the 7-day unlinked share of new facts, `no_subject` judgments and the 7-day `linked` tiers from `fact_relink_attempts`, fence-owned unlinked rows (row_num or source_markdown_slug set, conversation rows excluded), the conversation extractor's unlinked derived rows (`cli:extract-conversation-facts*`, #6764: count, origin `conversation`, and `details.conversation` naming the source with the most and its pages, most rows first, up to `CONVERSATION_FIX_SLUGS` = 50), origins and 7-day write-time inferred links by tier (`entity inferred from <tier>` context, bare or after ` — `). Warns when over 25% of at least 20 new facts are unlinked, facts judged `no_subject` and conversation rows memoized `conversation_unresolved` excluded (`new_7d.conversation_unresolved`); the fix is `gbrain facts relink --dry-run`; when conversation rows are unlinked the envelope `fix` (`details.conversation.fix`) is, for rows the free conversation relink has not tried, `gbrain facts relink --conversation --source <id> --slugs <csv>` (preview `--dry-run`, consent none, actor agent, host operator remotely; test `test/conversation-relink-6764.test.ts`) and, once only rows it memoized `conversation_unresolved` remain (a memo that a page created later re-arms unless the reason is memoized, `core/facts/conversation-memo.ts`), a bounded re-extraction of those pages not yet re-extracted on their current content (`gbrain extract-conversation-facts --source-id <id> --slugs <csv> --force --max-cost-usd <N>`, input `N` the approved USD, preview `--dry-run`, consent paid + egress, ask_user; test `test/conversation-facts-unlinked-6764.test.ts`), both verified by `gbrain doctor --only unlinked_facts --json`, because plain relink never examines derived rows; the remote report asks the brain host operator to run it. When only rows on pages already re-extracted on their current content remain, `details.conversation.fix` is `manual`: no envelope `fix`, and the message names linking by hand with `--entity` (test `test/conversation-memo-6764.test.ts`). Without `fact_relink_attempts` the relink figures are null and nothing is excluded. Non-user facts are skipped (#7270). Tests: `test/doctor-unlinked-facts.test.ts`, `test/relink-attribution-7270.test.ts`.
- `src/commands/doctor/checks/unattended-maintenance.ts` — `unattended_maintenance` (GBRA-438): `readUpkeepStatus` as a check; off and autopilot-owned are ok, a brain under 48h with no run is info, a run older than 48h, a step failing 3 runs in a row or an item serve parked (`details.parked`) warns with `gbrain maintain --unattended` (`consent: []` unless an embedding key and a non-zero cap make it paid); on an overdue brain `details.alternative_fix` renders `gbrain maintain --schedule` as the second fix.
diff --git a/docs/architecture/key-files/memory-purge.md b/docs/architecture/key-files/memory-purge.md
index f21a428ecb..6c9a8f81c7 100644
--- a/docs/architecture/key-files/memory-purge.md
+++ b/docs/architecture/key-files/memory-purge.md
@@ -34,6 +34,6 @@ User-facing contract: [expire versus purge](../../guides/memory-boundaries.md#pu
- `src/commands/doctor/checks/atom-fence-rows.ts` — doctor `atom_fence_rows` (BRAIN, a host-only `WAVE_CHECKS` repair entry cleared by the explicit-only `atom-fence-rows`, so remediation classifies it `explicit_kind_required`): runs `findAtomFenceRows` per source, each statement bounded by `PLAN_STATEMENT_MS`; `warn` names the count per source and the read-only preview `gbrain repair atom-fence-rows --source <id> --json` as an agent `fix`, never a slug or row text; an overrun reports the count as unknown.
- `src/core/persistence/purge-parks.ts` — #6741 C: per-tombstone purge parks in op_checkpoints (op `purge-deleted-park`, key source+slug+deleted_at, so a re-deleted page starts fresh); park at `PURGE_PARK_LIMIT` (5) non-deferral failures, a success clears it, and parks of a source seen inactive rearm the first run its writer is active again (`notePurgeSourceWriter`). `purgeStaleCheckpoints` exempts the op; `prunePurgeParks` drops parks whose tombstone is gone. A park records the gbrain `version` of its last failure; `isParked` (the managed and unmanaged selection, doctor `purge_parked_pages`) counts only the running version's, so a park another version wrote (or one with no version) gets one automatic attempt and a failure re-parks it under the running version. Tests: `test/purge-deleted-parks.test.ts`, `test/purge-parks-version.test.ts` (Postgres: `test/e2e/purge-parks-version-postgres.test.ts`).
-- `src/core/persistence/derived-origin-hold.ts` + `src/core/repair/origin-carry.ts` — GST-2689: a page that reads as world by its own label but is hidden from remote callers only through a private origin (`derived_from`, an atom's `source_slug`, followed through `slug_aliases` and `slug_rename_history`, or a concept's provenance atom) keeps that privacy once the origin row is gone. `origin-carry.ts` finds the dependents with `private-labels.ts` `dependentsSql('remove')` (it reads only the pages whose frontmatter names a removed slug, or a slug a rename moved to it, through `idx_pages_frontmatter`, one jsonpath scan per 100 slugs of a source, so its cost does not grow with the source; the postimage drops the origin rows; a page that names readers is returned when its listed readers would gain it, and gets the label with its `readable_by` kept; a life-chronicle event is returned when the removal opens it, never when its `event.depth` page is removed, since it then fails closed) and gives each `visibility: private` through the label door (`publishMaintenancePages` with `keepTrust` and the label edit on a managed brain, batch `derived-origin-carry:<request_id>`; `writeLabelFile` or `importAtRevision` otherwise). `deletePageCarryingPrivate` is the `delete_page` handler body: a soft delete (local or remote) labels after it committed and returns the unchanged receipt; a purge labels first and, when that fails, soft-deletes instead (an existing tombstone stays), parks the origin and returns `purge_held`. `carryPrivateBeforePurge` runs before every expiry over all the origins (`type = 'atom'` or hidden by `privacyPartSql`) expired or expiring within `CARRY_LEAD_HOURS` (24) at once, so a page private through two of them is found and none crosses the cutoff mid-run uncarried; it publishes the labels 200 per maintenance batch, parks the blocked ones and returns the ones whose park no longer applies, which `purgeDeletedPagesCoordinated` clears only after its purge, so an origin parked when the purge was previewed stays that run; a consented manual purge (`gbrain pages purge-deleted`, `purge_deleted_pages`) previews with `forecastCarry` (read-only: the parked origins the carry would free, `released_origins`, and the origins it would park, both judged as `carryPrivate` judges them) passed to `selectPurgeCandidates`, so `--dry-run` and the consent list exactly what `--yes` purges and nothing is labelled before the consent; the run passes the freed ids as `release`, and `purgeDeletedPagesCoordinated` clears those parks once its carry landed, before it purges. A soft-deleted dependent is returned too but never labelled: it blocks its origin (`dependent_soft_deleted`) until it is purged or restored, since a restore would bring it back with the origin row gone; a removed origin tied to another removed origin counts as such a dependent (judged on its own row), since another hold may keep it. Inside each delete transaction `parkUncarriedInPurge` rechecks the origins about to go (the page purge for an explicit or managed retention purge, the unmanaged bulk delete, and each recorded tombstone): an origin a page written after the carry still depends on is parked in that transaction and its row is kept (a live page is soft-deleted instead, and the receipt carries `purge_held` naming no page), so the next purge labels the page and the one after removes the origin. The origin is looked up by the lowercased slug, as `submitPageMutation` deletes it. `derived-origin-hold.ts` is the park (op_checkpoints op `derived-origin-park`, fingerprint the page id, with `blocking_slug`, `code` and `reason`), `derivedOriginPurgeHold` (no engine-sql imports), prune of restored or purged pages, and `readDerivedOriginParks` for doctor `derived_origin_parked`; `purgeStaleCheckpoints` exempts the op. Tests: `test/derived-origin-carry-private.test.ts` (repo-less, minted tokens), `test/derived-origin-carry-managed.test.ts` (managed Git brain), `test/derived-origin-recheck-plan.test.ts` (pages rows the recheck visits).
+- `src/core/persistence/derived-origin-hold.ts` + `src/core/repair/origin-carry.ts` — GST-2689: a page that reads as world by its own label but is hidden from remote callers only through a private origin (`derived_from`, an atom's `source_slug`, followed through `slug_aliases` and `slug_rename_history`, or a concept's provenance atom) keeps that privacy once the origin row is gone. `origin-carry.ts` finds the dependents with `private-labels.ts` `dependentsSql('remove')` (it reads only the pages whose frontmatter names a removed slug, or a slug a rename moved to it, through `idx_pages_frontmatter`, one jsonpath scan per 100 slugs of a source, so its cost does not grow with the source; the postimage drops the origin rows; a page that names readers is returned when its listed readers would gain it, and gets the label with its `readable_by` kept; a life-chronicle event is returned when the removal opens it, never when its `event.depth` page is removed, since it then fails closed) and gives each `visibility: private` through the label door (`publishMaintenancePages` with `keepTrust` and the label edit on a managed brain, batch `derived-origin-carry:<request_id>`; `writeLabelFile` or `importAtRevision` otherwise). `deletePageCarryingPrivate` is the `delete_page` handler body: a soft delete (local or remote) labels after it committed and returns the unchanged receipt; a purge labels first and, when that fails, soft-deletes instead (an existing tombstone stays), parks the origin and returns `purge_held`, whose message (like an owner purge the in-transaction recheck or the failed origin lookup held) names `gbrain delete <slug> --purge --source-id <id>` to run as a new request once the page is labelled, since only an explicit purge writes the purge tombstones; the park records the held request (`held_request_id`, kept by a later park of the page) and doctor names the command (`finish_argv`). `carryPrivateBeforePurge` runs before every expiry over all the origins (`type = 'atom'` or hidden by `privacyPartSql`) expired or expiring within `CARRY_LEAD_HOURS` (24) at once, so a page private through two of them is found and none crosses the cutoff mid-run uncarried; it publishes the labels 200 per maintenance batch, parks the blocked ones and returns the ones whose park no longer applies, which `purgeDeletedPagesCoordinated` clears only after its purge, so an origin parked when the purge was previewed stays that run; a consented manual purge (`gbrain pages purge-deleted`, `purge_deleted_pages`) previews with `forecastCarry` (read-only: the parked origins the carry would free, `released_origins`, and the origins it would park, both judged as `carryPrivate` judges them) passed to `selectPurgeCandidates`, so `--dry-run` and the consent list exactly what `--yes` purges and nothing is labelled before the consent; the run passes the freed ids as `release`, and `purgeDeletedPagesCoordinated` clears those parks once its carry landed, before it purges. A soft-deleted dependent is returned too but never labelled: it blocks its origin (`dependent_soft_deleted`) until it is purged or restored, since a restore would bring it back with the origin row gone; a removed origin tied to another removed origin counts as such a dependent (judged on its own row), since another hold may keep it. Inside each delete transaction `parkUncarriedInPurge` rechecks the origins about to go (the page purge for an explicit or managed retention purge, the unmanaged bulk delete, and each recorded tombstone): an origin a page written after the carry still depends on is parked in that transaction and its row is kept (a live page is soft-deleted instead, and the receipt carries `purge_held` naming no page), so the next purge labels the page and the one after removes the origin. The origin is looked up by the lowercased slug, as `submitPageMutation` deletes it. `derived-origin-hold.ts` is the park (op_checkpoints op `derived-origin-park`, fingerprint the page id, with `blocking_slug`, `code` and `reason`), `derivedOriginPurgeHold` (no engine-sql imports), prune of restored or purged pages, and `readDerivedOriginParks` for doctor `derived_origin_parked`; `purgeStaleCheckpoints` exempts the op. Tests: `test/derived-origin-carry-private.test.ts` (repo-less, minted tokens), `test/derived-origin-carry-managed.test.ts` (managed Git brain), `test/derived-origin-recheck-plan.test.ts` (pages rows the recheck visits).
- `src/core/repair/segmented-mirror.ts` — `gbrain repair segmented-mirror` (LPH a), explicit-only, preview-bound, destructive consent, `checks: []` (no doctor scan: detection reads every segmented file). `scanSegmentedMirrors` (read-only, owner host; a non-owner source is held `not_owner_host`) walks live `body_storage='segmented'` pages of sources with a worktree binding whose snapshot ledger applies (`ledgerApplies`), runs `prepareFileTarget(..., null, { allowMissing })` (the mirror's own drift check; `file_database_drift` or any other `OperationError` is held, never rewritten), then lists the page only when overlaying the ledger on the file's facts fences changes its region digests (`fileBodyDigests` vs `overlaidFileBodyDigests` over `FileBytes`, bounded memory) and the streamed render (`unreadPageFile`) hashes differently. The hash (`segmented-mirror-v1`) binds source selection, slug, page id, revision, path and both SHA-256s; the approved set lives in `op_checkpoints`. Apply re-checks revision and file hash of every page not yet admitted (`preview_changed`), then per page admits and commits, in one transaction like a withdrawal, a `repair_segmented_mirror` request (request id derived from the hash; its receipt) that inserts a version-2 targeted `withdrawal-mirror` + `git` effect (no embedding) whose `data.approved_file` carries the preview's file and render SHA-256 (`mirrorPage` skips the target `preview_changed` when the file's before-hash or the streamed render differs, before the gate or any recovery record; `publishGitPage` skips it when the file is not the approved render; the outcome is `refused` `preview_changed` with a read-only fix re-running the preview); it wakes this process's consumer and waits up to the write wait for them (`mirrored` / `mirror_queued` / `held` / `failed`; a replay is `replayed`). Test: `test/pathological/lp-a-segmented-mirror.test.ts`.
diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md
index 89b0022b10..e67e818df5 100644
--- a/docs/guides/troubleshooting.md
+++ b/docs/guides/troubleshooting.md
@@ -75,7 +75,7 @@
| [`owner_unavailable`, reason `binding_missing`, `incarnation_changed`, `local_path_missing` or `coordination_path_missing`](#owner-unavailable) | `gbrain sources writer status --source <id> --json`; the registration is missing or outdated and re-binding or re-registering the checkout is the host administrator's decision | brain host | none | the same status read shows an active binding for this host |
| Background work (autopilot, jobs, connector syncs) refused `owner_unavailable` "Background writes to source <id> are paused: its canonical owner could not be verified" or "its worktree is recovering" | run the fix, `gbrain sources writer status --source <id> --json`, which names what the source waits on; a deleted owner marker (`.gbrain-owner.json`) is repaired by a writer self-transfer, the user's decision. Nothing was submitted and no request id was used; interactive writes are unaffected | agent; the self-transfer after the user agrees | none to inspect | the same status read shows an active binding; the next background run admits |
| Doctor warns `purge_parked_pages` | a park an older gbrain wrote is retried once by the next purge run after an upgrade and is not counted; for the rest, fix the cause each page's last error names, preview `gbrain pages purge-deleted --retry-parked --dry-run --json`, then with the user's agreement run `gbrain pages purge-deleted --retry-parked --yes` | agent, after the user agrees | `destructive` | `gbrain doctor --only purge_parked_pages --json` |
-| Doctor warns `derived_origin_parked` | a soft-deleted page is kept from the purge because a page derived from it could not be labelled private; fix the cause the reason names, or preview the blocking page's own label with the fix's `gbrain repair visibility --source <id> --slug <page>`; the next purge labels the rest and frees the page, and the purge after removes it (a consented `gbrain pages purge-deleted --yes` does both) | agent | none (the preview writes nothing) | `gbrain doctor --only derived_origin_parked --json` |
+| Doctor warns `derived_origin_parked` | a soft-deleted page is kept from the purge because a page derived from it could not be labelled private; fix the cause the reason names, or preview the blocking page's own label with the fix's `gbrain repair visibility --source <id> --slug <page>`; the next purge labels the rest and frees the page, and the purge after removes it (a consented `gbrain pages purge-deleted --yes` does both). A page whose own `gbrain delete <slug> --purge` was held is named with `gbrain delete <slug> --purge --source-id <id>`: run it again as a new request once the blocking page is labelled, so the purge tombstones are written | agent | none (the preview writes nothing) | `gbrain doctor --only derived_origin_parked --json` |
| [`gbrain repair fences` skipped a file `sync_in_progress` while a sync runs](repair.md#fence-repair-during-a-sync) | nothing: a write in flight or the running sync's frozen manifest still names that file; every other candidate repairs now and the next run picks this one up (`gbrain sync --source <id> --no-pull` finishes the sync) | agent | none | `gbrain doctor --only fence_integrity --json` |
| [A Google or GitHub item is held (`connector_held_items`)](#held-connector-items) | `gbrain sources status <id>`, fix the cause, then `gbrain sources retry-held <id>` and `gbrain sync --source <id>` | agent, after the user agrees | `egress` (fetches from the provider again) | `gbrain doctor --only connector_held_items --json` |
| `gbrain google status` exits 1 naming `calendar_unreadable`, doctor warns `google_calendar_readable`, or the sync log prints `[google] calendar_unreadable` (calendar pages stop arriving) | `gbrain google calendars --account <email>` lists the calendars the account can read; then `gbrain sources set-calendar <source> <calendar-id>` and `gbrain sync --source <source>` ([unreadable calendar](google-connect.md#unreadable-calendar)) | agent, after the user agrees which calendar | none (on a managed brain whose source also syncs Gmail or Contacts, the change re-reads their history: `confirmation_required`, re-run with `--yes` after the user agrees) | `gbrain doctor --only google_calendar_readable --json` is ok |
diff --git a/llms-full.txt b/llms-full.txt
index 209bd070b3..3b4ab9febb 100644
--- a/llms-full.txt
+++ b/llms-full.txt
@@ -9064,7 +9064,7 @@ Source: https://raw.githubusercontent.com/garrytan/gbrain/master/docs/guides/tro
| [`owner_unavailable`, reason `binding_missing`, `incarnation_changed`, `local_path_missing` or `coordination_path_missing`](#owner-unavailable) | `gbrain sources writer status --source <id> --json`; the registration is missing or outdated and re-binding or re-registering the checkout is the host administrator's decision | brain host | none | the same status read shows an active binding for this host |
| Background work (autopilot, jobs, connector syncs) refused `owner_unavailable` "Background writes to source <id> are paused: its canonical owner could not be verified" or "its worktree is recovering" | run the fix, `gbrain sources writer status --source <id> --json`, which names what the source waits on; a deleted owner marker (`.gbrain-owner.json`) is repaired by a writer self-transfer, the user's decision. Nothing was submitted and no request id was used; interactive writes are unaffected | agent; the self-transfer after the user agrees | none to inspect | the same status read shows an active binding; the next background run admits |
| Doctor warns `purge_parked_pages` | a park an older gbrain wrote is retried once by the next purge run after an upgrade and is not counted; for the rest, fix the cause each page's last error names, preview `gbrain pages purge-deleted --retry-parked --dry-run --json`, then with the user's agreement run `gbrain pages purge-deleted --retry-parked --yes` | agent, after the user agrees | `destructive` | `gbrain doctor --only purge_parked_pages --json` |
-| Doctor warns `derived_origin_parked` | a soft-deleted page is kept from the purge because a page derived from it could not be labelled private; fix the cause the reason names, or preview the blocking page's own label with the fix's `gbrain repair visibility --source <id> --slug <page>`; the next purge labels the rest and frees the page, and the purge after removes it (a consented `gbrain pages purge-deleted --yes` does both) | agent | none (the preview writes nothing) | `gbrain doctor --only derived_origin_parked --json` |
+| Doctor warns `derived_origin_parked` | a soft-deleted page is kept from the purge because a page derived from it could not be labelled private; fix the cause the reason names, or preview the blocking page's own label with the fix's `gbrain repair visibility --source <id> --slug <page>`; the next purge labels the rest and frees the page, and the purge after removes it (a consented `gbrain pages purge-deleted --yes` does both). A page whose own `gbrain delete <slug> --purge` was held is named with `gbrain delete <slug> --purge --source-id <id>`: run it again as a new request once the blocking page is labelled, so the purge tombstones are written | agent | none (the preview writes nothing) | `gbrain doctor --only derived_origin_parked --json` |
| [`gbrain repair fences` skipped a file `sync_in_progress` while a sync runs](repair.md#fence-repair-during-a-sync) | nothing: a write in flight or the running sync's frozen manifest still names that file; every other candidate repairs now and the next run picks this one up (`gbrain sync --source <id> --no-pull` finishes the sync) | agent | none | `gbrain doctor --only fence_integrity --json` |
| [A Google or GitHub item is held (`connector_held_items`)](#held-connector-items) | `gbrain sources status <id>`, fix the cause, then `gbrain sources retry-held <id>` and `gbrain sync --source <id>` | agent, after the user agrees | `egress` (fetches from the provider again) | `gbrain doctor --only connector_held_items --json` |
| `gbrain google status` exits 1 naming `calendar_unreadable`, doctor warns `google_calendar_readable`, or the sync log prints `[google] calendar_unreadable` (calendar pages stop arriving) | `gbrain google calendars --account <email>` lists the calendars the account can read; then `gbrain sources set-calendar <source> <calendar-id>` and `gbrain sync --source <source>` ([unreadable calendar](google-connect.md#unreadable-calendar)) | agent, after the user agrees which calendar | none (on a managed brain whose source also syncs Gmail or Contacts, the change re-reads their history: `confirmation_required`, re-run with `--yes` after the user agrees) | `gbrain doctor --only google_calendar_readable --json` is ok |
diff --git a/src/commands/doctor/checks/purge-parks.ts b/src/commands/doctor/checks/purge-parks.ts
index 2f95bce236..3553c830bf 100644
--- a/src/commands/doctor/checks/purge-parks.ts
+++ b/src/commands/doctor/checks/purge-parks.ts
@@ -8,7 +8,7 @@
import type { Check } from '../../doctor.ts';
import type { BrainEngine } from '../../../core/engine.ts';
import { isParked, PURGE_PARK_LIMIT, readPurgeParks } from '../../../core/persistence/purge-parks.ts';
-import { readDerivedOriginParks } from '../../../core/persistence/derived-origin-hold.ts';
+import { finishPurgeArgv, readDerivedOriginParks } from '../../../core/persistence/derived-origin-hold.ts';
import { agentFix, checkError, doctorVerify } from '../check-fix.ts';
import { connectedEngine, type DoctorContext, type DoctorEntry } from '../context.ts';
@@ -47,7 +47,9 @@ export const purgeParkedPagesEntry: DoctorEntry = { name: 'purge_parked_pages',
/**
* GST-2689: doctor `derived_origin_parked`. A soft-deleted page that is the only privacy of a page derived from it is kept
* from every purge while that page could not be labelled private (persistence/derived-origin-hold.ts). Each is named
- * with the page that blocks it and the reason; the fix previews the label on the first blocking page.
+ * with the page that blocks it and the reason; the fix previews the label on the first blocking page. An origin whose
+ * owner purge was held is named with the command that finishes that purge (`finish_argv`), a new request that writes the
+ * purge tombstones the automatic purge does not.
*/
const ORIGIN_NAME = 'derived_origin_parked';
@@ -59,13 +61,16 @@ export async function checkDerivedOriginParked(engine: BrainEngine): Promise<Che
return checkError(ORIGIN_NAME, 'read the parked derived-page origins', error);
}
if (!parks.length) return { name: ORIGIN_NAME, status: 'ok', message: 'No soft-deleted page is kept from the purge to keep a page derived from it private.', details: { parked: 0, origins: [] } };
- const origins = parks.slice(0, SAMPLE).map(park => ({ source_id: park.source_id, slug: park.slug, blocking_slug: park.blocking_slug, code: park.code, reason: park.reason, parked_at: park.parked_at }));
+ const origins = parks.slice(0, SAMPLE).map(park => ({ source_id: park.source_id, slug: park.slug, blocking_slug: park.blocking_slug, code: park.code, reason: park.reason, parked_at: park.parked_at,
+ ...(park.held_request_id ? { held_request_id: park.held_request_id, finish_argv: finishPurgeArgv(park.source_id, park.slug) } : {}) }));
+ const finish = origins.filter(origin => origin.finish_argv).map(origin => `${origin.finish_argv!.join(' ')} (held request_id ${origin.held_request_id})`);
const listed = origins.map(origin => `${origin.source_id}/${origin.slug} (blocked by ${origin.blocking_slug ?? 'a derived page that could not be read'}: ${origin.code ?? 'error'}: ${origin.reason})`).join(', ');
const first = origins.find(origin => origin.blocking_slug);
return {
name: ORIGIN_NAME, status: 'warn', details: { parked: parks.length, truncated: parks.length > origins.length, origins },
message: `${parks.length} soft-deleted page(s) are kept from the purge, because a page derived from each reads as private only through it and could not be labelled private: ${listed}`
- + `${parks.length > origins.length ? ` (first ${origins.length} of ${parks.length} shown)` : ''}. Fix the cause each reason names, or give the blocking page its own visibility label; the next purge labels the rest and frees the origin, and the purge after removes it (a consented gbrain pages purge-deleted does both).`,
+ + `${parks.length > origins.length ? ` (first ${origins.length} of ${parks.length} shown)` : ''}. Fix the cause each reason names, or give the blocking page its own visibility label; the next purge labels the rest and frees the origin, and the purge after removes it (a consented gbrain pages purge-deleted does both).`
+ + `${finish.length ? ` An owner purge of ${finish.length} of them was held: once its blocking page is labelled, finish it as a new request with ${finish.join('; ')}, which writes the purge tombstones the automatic purge does not.` : ''}`,
...(first ? { fix: agentFix(['gbrain', 'repair', 'visibility', '--source', first.source_id, '--slug', first.blocking_slug!],
'Previews giving the blocking page its own visibility label; nothing is written.', ORIGIN_NAME) } : {}),
};
diff --git a/src/core/persistence/derived-origin-hold.ts b/src/core/persistence/derived-origin-hold.ts
index 4e6f67d963..0d84be4683 100644
--- a/src/core/persistence/derived-origin-hold.ts
+++ b/src/core/persistence/derived-origin-hold.ts
@@ -13,8 +13,19 @@ import type { SqlEngine } from './model.ts';
export const DERIVED_ORIGIN_PARK_OP = 'derived-origin-park';
export const DERIVED_ORIGIN_PARKED_CODE = 'derived_origin_parked';
-/** `blocking_slug`: the derived page whose label write failed; null when its dependents could not be read. */
-export interface DerivedOriginPark { source_id: string; slug: string; page_id: number; blocking_slug: string | null; code: string | null; reason: string; parked_at: string }
+/**
+ * `blocking_slug`: the derived page whose label write failed; null when its dependents could not be read. `held_request_id`: the owner's
+ * explicit purge this park held (a retention purge leaves it unset); a later park of the same page keeps it.
+ */
+export interface DerivedOriginPark { source_id: string; slug: string; page_id: number; blocking_slug: string | null; code: string | null; reason: string; parked_at: string; held_request_id?: string }
+
+/** The command that finishes an owner purge a park held: `gbrain delete` makes a new request_id, and an explicit purge writes the purge tombstones. */
+export const finishPurgeArgv = (sourceId: string, slug: string): string[] => ['gbrain', 'delete', slug, '--purge', '--source-id', sourceId];
+
+/** The receipt clause of a held owner purge, after its condition ("Once ..., "): the command that finishes it, as a new request. */
+export function finishPurgeNote(sourceId: string, slug: string, requestId: string): string {
+ return `finish this purge with ${finishPurgeArgv(sourceId, slug).join(' ')} as a new request (not a replay of request_id ${requestId}): it writes the purge tombstones, which the automatic purge that otherwise removes the page does not.`;
+}
/** SQL predicate for a purge scan over `pages` aliased `alias`: the page is not a parked origin. */
export function derivedOriginPurgeHold(alias: string): string {
@@ -24,7 +35,8 @@ export function derivedOriginPurgeHold(alias: string): string {
export async function parkDerivedOrigin(engine: SqlEngine, park: Omit<DerivedOriginPark, 'parked_at'>): Promise<void> {
const row: DerivedOriginPark = { ...park, parked_at: new Date().toISOString() };
await engine.executeRaw(`INSERT INTO op_checkpoints(op,fingerprint,completed_keys) VALUES($1,$2,$3::text::jsonb)
- ON CONFLICT (op,fingerprint) DO UPDATE SET updated_at=now(), completed_keys=EXCLUDED.completed_keys`, [DERIVED_ORIGIN_PARK_OP, String(park.page_id), JSON.stringify([row])]);
+ ON CONFLICT (op,fingerprint) DO UPDATE SET updated_at=now(), completed_keys=CASE WHEN (op_checkpoints.completed_keys->0) ? 'held_request_id' AND NOT (EXCLUDED.completed_keys->0) ? 'held_request_id'
+ THEN jsonb_set(EXCLUDED.completed_keys, '{0,held_request_id}', op_checkpoints.completed_keys->0->'held_request_id') ELSE EXCLUDED.completed_keys END`, [DERIVED_ORIGIN_PARK_OP, String(park.page_id), JSON.stringify([row])]);
}
export async function clearDerivedOriginParks(engine: SqlEngine, pageIds: readonly number[]): Promise<void> {
diff --git a/src/core/persistence/page-purge.ts b/src/core/persistence/page-purge.ts
index af72b8f7ab..d0b6a1b367 100644
--- a/src/core/persistence/page-purge.ts
+++ b/src/core/persistence/page-purge.ts
@@ -281,10 +281,11 @@ const TIMELINE_RECEIPT_CAP = 10_000;
export async function purgePageInTransaction(tx: BrainEngine, row: WriteRequest, snapshot: PageSnapshot, prepared: PreparedPagePurge): Promise<Record<string, unknown>> {
const page = snapshot.page, sourceId = row.source_id, slug = page.slug;
// GST-2689: a page derived from this one written after the purge's carry keeps it: soft-deleted (a live page) and parked.
- const { MID_PURGE_HOLD, parkUncarriedInPurge } = await import('../repair/origin-carry.ts');
- if ((await parkUncarriedInPurge(tx, [Number(page.id)], { recheckParked: true })).length) {
+ const { midPurgeHold, parkUncarriedInPurge } = await import('../repair/origin-carry.ts');
+ const owner = prepared.retention ? undefined : { sourceId, slug, requestId: row.request_id };
+ if ((await parkUncarriedInPurge(tx, [Number(page.id)], { recheckParked: true, ...(owner ? { heldRequestId: owner.requestId } : {}) })).length) {
if (!page.deleted_at) { await tx.createVersion(slug, { sourceId }); await withTrustKeep(tx, ['pages'], () => tx.softDeletePage(slug, { sourceId })); }
- return { status: 'soft_deleted', slug, source_id: sourceId, noop: !!page.deleted_at, ...(prepared.retention ? { retention: true } : {}), purge_held: MID_PURGE_HOLD };
+ return { status: 'soft_deleted', slug, source_id: sourceId, noop: !!page.deleted_at, ...(prepared.retention ? { retention: true } : {}), purge_held: midPurgeHold(owner) };
}
const actor = `${row.principal_kind}:${row.principal_id}`;
const [stored] = await tx.executeRaw<{ content_hash: string | null; body_generation: number | string }>('SELECT content_hash,body_generation FROM pages WHERE id=$1', [page.id]);
diff --git a/src/core/repair/origin-carry.ts b/src/core/repair/origin-carry.ts
index b6df9baa26..6108e7ff68 100644
--- a/src/core/repair/origin-carry.ts
+++ b/src/core/repair/origin-carry.ts
@@ -21,7 +21,7 @@ import { serializePageToMarkdown } from '../markdown.ts';
import { isSegmentedPage } from '../page-body/page-shape.ts';
import type { LabelEdit } from '../persistence/label-edit.ts';
import { maintenancePreflight, publishMaintenancePages } from '../persistence/prepared-maintenance.ts';
-import { clearDerivedOriginParks, DERIVED_ORIGIN_PARKED_CODE, derivedOriginPurgeHold, parkDerivedOrigin, pruneDerivedOriginParks, readDerivedOriginParks, type DerivedOriginPark } from '../persistence/derived-origin-hold.ts';
+import { clearDerivedOriginParks, DERIVED_ORIGIN_PARKED_CODE, derivedOriginPurgeHold, finishPurgeNote, parkDerivedOrigin, pruneDerivedOriginParks, readDerivedOriginParks, type DerivedOriginPark } from '../persistence/derived-origin-hold.ts';
import { privacyPartSql, readHonorAliases, withoutCallerAccess } from '../search/private-visibility.ts';
import { faultPoint } from '../persistence/fault-points.ts';
import { filesInCheckout, importAtRevision, writeLabelFile } from './label-write.ts';
@@ -154,7 +154,7 @@ export async function deletePageCarryingPrivate(ctx: OperationContext, p: Record
try { origin = slug ? await originOf(ctx.engine, sourceId, slug) : null; }
catch {
const held = await submitPageMutation(ctx, { operation: 'delete_page', params: { ...p, purge: false, request_id: derivedRequestId(String(p.request_id)) } });
- return { ...held, purge_held: ORIGIN_UNCHECKED_HOLD };
+ return { ...held, purge_held: originUncheckedHold(sourceId, slug ?? String(p.slug), String(p.request_id)) };
}
const block = origin ? (await carryPrivate(ctx.engine, [origin], batch)).get(origin.id) : undefined;
if (!origin || !block) {
@@ -164,12 +164,13 @@ export async function deletePageCarryingPrivate(ctx: OperationContext, p: Record
if (origin && result.status === 'purged') await clearDerivedOriginParks(ctx.engine, [origin.id]);
return result;
}
- await parkDerivedOrigin(ctx.engine, parked(origin, block));
+ await parkDerivedOrigin(ctx.engine, { ...parked(origin, block), held_request_id: String(p.request_id) });
const result = origin.deleted ? { status: 'held', slug: origin.slug, source_id: sourceId, request_id: p.request_id }
: await submitPageMutation(ctx, { operation: 'delete_page', params: { ...p, purge: false, request_id: derivedRequestId(String(p.request_id)) } });
return { ...result, purge_held: { code: DERIVED_ORIGIN_PARKED_CODE,
message: `Not purged: ${block.slug ?? 'a page derived from it'} is private only through ${origin.slug} and could not be labelled private (${block.code ?? 'error'}: ${block.reason}). `
- + `${origin.slug} is soft-deleted and parked: no purge removes it until that page carries its own label; gbrain doctor names it as derived_origin_parked.` } };
+ + `${origin.slug} is soft-deleted and parked: no purge removes it until that page carries its own label; gbrain doctor names it as derived_origin_parked. `
+ + `Once it does, ${finishPurgeNote(sourceId, origin.slug, String(p.request_id))}` } };
}
/** Hours before its cutoff a tombstone is carried, so none crosses the cutoff while the carry runs and is purged uncarried. */
@@ -237,12 +238,18 @@ export async function forecastCarry(engine: BrainEngine, olderThanHours: number)
}
/** The receipt note of an explicit purge held because its origin lookup failed; it names no page and counts none. */
-export const ORIGIN_UNCHECKED_HOLD = { code: 'derived_origin_unchecked',
- message: 'Not purged: whether a page derived from this one would open without it could not be checked, so this page is kept soft-deleted (a parked page stays parked); purge it again once that read works, and the automatic purge checks it before it removes it.' };
+export const originUncheckedHold = (sourceId: string, slug: string, requestId: string) => ({ code: 'derived_origin_unchecked',
+ message: `Not purged: whether a page derived from this one would open without it could not be checked, so this page is kept soft-deleted (a parked page stays parked). Once that read works, ${finishPurgeNote(sourceId, slug, requestId)}` });
-/** The receipt note of a purge the in-transaction recheck held; it names no page and counts none. */
-export const MID_PURGE_HOLD = { code: DERIVED_ORIGIN_PARKED_CODE,
- message: 'Not purged: a page derived from this one was written during the purge and is not labelled private yet, so this page is kept soft-deleted and parked; the next purge labels it and frees this page, and the one after removes it (gbrain doctor: derived_origin_parked).' };
+/**
+ * The receipt note of a purge the in-transaction recheck held; it names no page and counts none. A retention purge's
+ * note says the next purges finish it; an owner purge's (`owner`) names the command that finishes it as a new request.
+ */
+export function midPurgeHold(owner?: { sourceId: string; slug: string; requestId: string }): { code: string; message: string } {
+ const held = 'Not purged: a page derived from this one was written during the purge and is not labelled private yet, so this page is kept soft-deleted and parked (gbrain doctor: derived_origin_parked)';
+ return { code: DERIVED_ORIGIN_PARKED_CODE, message: owner ? `${held}; the next purge labels that page. Once it does, ${finishPurgeNote(owner.sourceId, owner.slug, owner.requestId)}`
+ : `${held}; the next purge labels it and frees this page, and the one after removes it.` };
+}
/**
* Inside a purge's delete transaction, after the carry: the origins among `ids` (the bulk paths skip parked ones; the
@@ -252,7 +259,7 @@ export const MID_PURGE_HOLD = { code: DERIVED_ORIGIN_PARKED_CODE,
* parked here, in the same transaction, and the caller skips its row delete; the next purge labels the page and the one
* after removes the origin. The parks written, by origin.
*/
-export async function parkUncarriedInPurge(tx: BrainEngine, ids: readonly number[], opts: { recheckParked?: boolean } = {}): Promise<DerivedOriginPark[]> {
+export async function parkUncarriedInPurge(tx: BrainEngine, ids: readonly number[], opts: { recheckParked?: boolean; heldRequestId?: string } = {}): Promise<DerivedOriginPark[]> {
if (!ids.length) return [];
return withoutCallerAccess(async () => {
await readHonorAliases(tx);
@@ -267,7 +274,8 @@ export async function parkUncarriedInPurge(tx: BrainEngine, ids: readonly number
const page = first.get(origin.id);
if (!page) continue;
const park = { source_id: origin.source_id, slug: origin.slug, page_id: origin.id, blocking_slug: page.slug, code: 'dependent_written_mid_purge',
- reason: `${page.slug} was written while ${origin.slug} was being purged and is private only through it; the next purge labels it.` };
+ reason: `${page.slug} was written while ${origin.slug} was being purged and is private only through it; the next purge labels it.`,
+ ...(opts.heldRequestId ? { held_request_id: opts.heldRequestId } : {}) };
await parkDerivedOrigin(tx, park);
parks.push({ ...park, parked_at: new Date().toISOString() });
}
diff --git a/test/derived-origin-carry-private.test.ts b/test/derived-origin-carry-private.test.ts
index f705edf522..dec391cfe3 100644
--- a/test/derived-origin-carry-private.test.ts
+++ b/test/derived-origin-carry-private.test.ts
@@ -445,6 +445,37 @@ for (const kind of testBackends()) {
await expectCarriedHidden(k);
}, 240_000);
+ test('a held owner purge names gbrain delete <slug> --purge in its receipt and in doctor; finished through it as a new request, it writes the purge tombstones', async () => {
+ const k = 'finish';
+ await seed(k);
+ const origin = slugOf(k, 'origin');
+ const command = `gbrain delete ${origin} --purge --source-id ${SRC}`;
+ const tombstones = async () => (await engine.executeRaw<{ request_id: string }>(`SELECT r.request_id::text AS request_id FROM page_purges t
+ JOIN persistence_requests r ON r.id = t.request_id WHERE t.source_id=$1 AND t.slug=$2`, [SRC, origin])).map(r => r.request_id);
+ const first = randomUUID();
+ const failing = spyOn(labelWrite, 'importAtRevision').mockImplementation(async () => { throw new Error('forced label failure'); });
+ let held: Record<string, any>;
+ try { held = JSON.parse((await localCall('delete_page', { slug: origin, purge: true, request_id: first, expected_revision: await revision(origin) })).text); }
+ finally { failing.mockRestore(); }
+ expect(held.purge_held?.code).toBe('derived_origin_parked');
+ expect(held.purge_held.message).toContain(command);
+ expect(held.purge_held.message).toContain(first);
+ const doctor = await checkDerivedOriginParked(engine);
+ expect(doctor.message).toContain(command);
+ expect((doctor.details as { origins: Array<{ slug: string; finish_argv?: string[] }> }).origins.find(o => o.slug === origin)?.finish_argv)
+ .toEqual(['gbrain', 'delete', origin, '--purge', '--source-id', SRC]);
+ expect(await tombstones()).toEqual([]);
+ const second = randomUUID();
+ const done = JSON.parse((await localCall('delete_page', { slug: origin, purge: true, request_id: second, expected_revision: await revision(origin) })).text);
+ expect(done.status).toBe('purged');
+ expect(done.retention).toBeUndefined();
+ const written = await tombstones();
+ expect(written.length).toBeGreaterThan(0);
+ expect(new Set(written)).toEqual(new Set([second]));
+ await nothingKept(origin);
+ await expectCarriedHidden(k);
+ }, 240_000);
+
test('an explicit purge rechecks inside its transaction: a derived page written after the carry keeps the origin soft-deleted and parked', async () => {
const k = 'midsingle';
await seed(k);
@@ -457,6 +488,7 @@ for (const kind of testBackends()) {
const receipt = JSON.parse(out.text);
expect(receipt.status).not.toBe('purged');
expect(receipt.purge_held?.code).toBe('derived_origin_parked');
+ expect(receipt.purge_held.message).toContain(`gbrain delete ${origin} --purge --source-id ${SRC}`);
expect((await row(origin))?.deleted_at).not.toBeNull();
await expectLateHidden(k, late);
await backdate(origin);