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.mdindex 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.mdindex 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.mdindex 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.txtindex 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.tsindex 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<Chereturn 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.tsindex 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.tsindex 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.tsindex 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: Recordtry { 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: Recordif (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 numberconst 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.tsindex 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);