Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Document how deletes keep derived pages private (GST-2689)
garrytan8d66e3a0a4f2
diff --git a/behavior-changes.d/derived_origin_carry_private_gst2689.md b/behavior-changes.d/derived_origin_carry_private_gst2689.mdnew file mode 100644index 0000000000..2cd48da5b4--- /dev/null+++ b/behavior-changes.d/derived_origin_carry_private_gst2689.md@@ -0,0 +1 @@+Deleting a page that keeps other pages private now writes a visibility: private label on each page that was private only because of it (a summary whose derived_from names it, an atom extracted from it, a synthesized concept built from such an atom), before the deleted page's row is removed. On a brain with Git the derived page's file gains that one label line. The label stays if you restore the deleted page later. If a label cannot be written, the purge keeps the deleted page soft-deleted and gbrain doctor reports it as derived_origin_parked with the page that blocks it; an explicit gbrain delete --purge then returns purge_held instead of purging.diff --git a/changelog.d/derived-origin-delete-carry-private.md b/changelog.d/derived-origin-delete-carry-private.mdnew file mode 100644index 0000000000..cfb3a4f0dd--- /dev/null+++ b/changelog.d/derived-origin-delete-carry-private.md@@ -0,0 +1,15 @@+---+important: security+---++**Deleting a private page no longer opens the pages derived from it: each page that was private only because of the deleted page now gets its own `visibility: private` label before the deleted page's row goes.**++<!-- behavior-change: derived_origin_carry_private_gst2689 -->++### Fixed++- A summary whose `derived_from` names a private page, an atom extracted from a private page, and a synthesized concept built from such an atom read as private to remote callers even when their own label says world, because their origin is private. Once the origin's row was removed (an explicit `gbrain delete --purge`, or the purge after the 72-hour recovery window, including after a remote delete or a `git rm`), nothing kept them private any more, and every remote caller that is not the owner could read them through `get_page`, `get_versions`, `list_pages` and search.+- Now gbrain gives each such page `visibility: private` first, as a label-only write: the page keeps its trust tier, no lowering proposal is filed, and on a brain with Git only the label line of its file changes. A soft delete (local or over MCP) writes the label once the delete committed, as a maintenance write (on a managed brain its batch names the delete's request id); if that write fails, the delete still goes through and the purge writes the label later. The delete's response is unchanged and names none of the labelled pages. Every purge writes the label again for each expired origin before it removes any row, so an origin removed outside gbrain is covered from the next cycle.+- Pages that are already private, that name readers (`readable_by`), pinned questions and pages that do not derive from the deleted page are never changed. The owner, a `granted_sources` credential and a listed reader read the same pages as before, except that a page naming readers that was hidden only through its private origin becomes readable to its listed readers once the origin is gone.+- When a label cannot be written (for example a file in the checkout that gbrain may not write), the deleted page is kept soft-deleted instead of purged. An explicit purge returns `purge_held`, the purge phase lists the page as `derived_origin_parked` and warns, and the new doctor check `derived_origin_parked` names the page with the derived page that blocks it and the reason. Once the cause is fixed, the next purge writes the label and purges the page.+- A deleted page that is restored and later made world leaves its derived pages private until the owner relabels them. (GST-2689)diff --git a/docs/architecture/key-files/commands-2-continued.md b/docs/architecture/key-files/commands-2-continued.mdindex 3a7d492c13..9a1fa7ffd1 100644--- a/docs/architecture/key-files/commands-2-continued.md+++ b/docs/architecture/key-files/commands-2-continued.md@@ -39,7 +39,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.+- `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/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/core-persistence-continued.md b/docs/architecture/key-files/core-persistence-continued.mdindex 4a0ca51f9f..c6fc24bf1e 100644--- a/docs/architecture/key-files/core-persistence-continued.md+++ b/docs/architecture/key-files/core-persistence-continued.md@@ -43,5 +43,5 @@ The #6188 fence check and fence repair live in [fence repair](core-fence-repair.- `src/core/postgres-engine/reserved-transactions.ts` with `isPersistenceDeclaration` (`src/core/persistence/protocol.ts`) — BEGIN pipelining. `isPersistenceDeclaration` (GBRA-156) accepts exactly the `protocol.ts` declarations (transaction-local `set_config` calls and the brain row FOR SHARE). Admission, the FIFO claim, the effect claims and source guards, the receipt true-up, the single publication (`coordinator.ts`) and the consumer's lent lane transactions (`consumer.ts` `onLane`, through `reservedTransactions`) pass it as `TransactionOptions.pipelineFirst`, so behind a transaction-mode pooler the declaration goes out with BEGIN (one round trip less per transaction) while every later statement still waits for BEGIN's answer; if BEGIN fails, only the declaration has run, in autocommit, where it changes nothing. A reserved transaction gates every statement its body can reach, savepoint and nested-transaction bodies and `file()` included. A sync lane group's publication passes none: its begun mark must follow BEGIN's answer (`sync-lanes.ts` `awaitLaneBegin`). Tests: `test/persistence-pipeline-first.test.ts` (the predicate and the reviewed call sites), `test/e2e/pgbouncer-transaction-pipeline-6930.test.ts`.- `src/core/links-fence.ts` + `src/core/links-fence-projection.ts` — the `## Links` fence (G5): the markdown form of authored (manual) edges, `<!--- gbrain:links:begin -->` / `end` around `| to | type | source | valid_from | valid_until | context |`, one row per (to, type, source), source defaulting to `manual`; a reconciliation-managed provenance (`MANAGED_LINK_SOURCES`, exported here and re-exported by `ops/links.ts`), a bad date or a duplicate key is a skipped row with a warning. `parseLinksFence` (state `absent` / `parsed` / `malformed`), the deterministic `renderLinksFence` (rows sorted by key), `upsertLinksFenceRow` (omitted context and dates keep the stored ones; identical row = unchanged body), `removeLinksFenceRows` (leaves an empty fence), `replaceOrInsertLinksFence` (a `## Links` section at the end of compiled_truth, above an unclosed code block) and `maskLinksFence`, which `extractBodyLinks` applies so the fence cells are never also extracted as markdown, wikilink or bare-slug edges. A rewrite of a fence that parses with warnings throws `LinksFenceRewriteRefusal`. Cells use `escapeFenceCell` plus the same one-level marker encoding for `gbrain:links:*`. `projectLinksFence(tx, page, rows)` reconciles only what the page's fence owns: edges with origin_page_id = the page and origin_field `links_fence` (deleted, context-updated, inserted by key) and `manual` transitions with origin_page_id = the page, compared per row by (to, type, link_source, kind, date) and written with the row's source in `link_source`, then refreshes the touched relationships; a row whose target is not a live page in the source yields no edge. `linksFenceProjectionRows` returns null for an absent or malformed fence, so such a body changes no edge (an absent fence retires nothing, as for facts; unlike facts no held generation is recorded, so after a hand deletion of the whole section the database keeps edges git no longer has until `remove_link` or the G3 indexer), and drops rows typed with a link type the active pack does not declare. Callers: `prepareCanonicalProjections` (every projected page publication, quarantined and segmented-unread bodies excepted), `prepareAutomaticLinks` (put_page auto-links and the managed links maintenance, so `extract --stale` restores a lost fence edge) and `persistence/manual-links.ts`. Database-only manual edges (origin_field NULL) are never touched by any of them. Pinned by `test/links-fence.test.ts` and `test/managed-links-fence.test.ts`.- `src/core/persistence/source-lifecycle.ts` retire batches with `topology-transaction.ts` (#7702/#8905) — every `topologyTransaction` runs under `statement_timeout=5s` and `lock_timeout=1s` and maps SQLSTATE 57014/55P03 to `write_pending`, so a managed `remove` or `purge` first deletes the source's pages in batches of `SOURCE_RETIRE_BATCH_PAGES` (500; about 110 ms per batch with chunks and links on Postgres) under the native locks `withTopologyLocks` holds, each batch its own `topologyTransaction`. A batch re-checks the final transaction's preconditions (admin state, `lockTopologyRows`, the incarnation read before the locks, archived or `EXPIRED_ARCHIVE_SQL` due, no prior receipt other than this request's own admission, no `oauth_clients` reference, `assertTopologyRequestsSettled` from `topology-locks.ts`, `lockTopologyPrincipal`, and on the first batch `admitTopologyRetire` from `topology-receipts.ts`, which checks the receipt quotas at the largest receipt and records the admission) and, when one would refuse or replay, stops without deleting so the final transaction reports it, or throws that refusal before deleting; a batch that fails `write_pending` is retried at half the size (floor 1), so heavy pages still fit the bound; a refusal after some batches committed says how many pages that run already deleted; a dry run, a missing checkout, an unconfirmed operation and an admission-hooked call never batch. The final transaction's `sources` delete runs `removedSourceScrubCtes` (#9068: the source's retrieval and volunteer rows, and its slugs in eval candidates), so a run that stops after some batches leaves those rows until a retry commits. Each batch deletes inside `withCoordinatedWrite` with local-CLI attribution (the `pages` guard needs the source in `gbrain.write_sources`; only the final `sources` delete sets `gbrain.topology_change`). Committed batches are durable: a retry (same or new request_id) resumes, and the receipt's `pages_deleted` counts the pages deleted by the run that commits it. #8984: the first batch's transaction records the admission, a `persistence_topology_changes` row in state `recovering` with no recovery record, bound to the source incarnation it deletes from (`isRetireAdmission`); `recordTopologyChange` settles it `committed`, and a remove or purge that deletes that incarnation under another request, or any other lifecycle operation that commits a change to it (archive, restore, rebind, claim), settles it `failed` (`supersedeTopologyRetires`, which skips only the caller's own principal and request_id pair). A retry of the request_id against another incarnation (the source was removed and re-added) refuses `source_retire_superseded`, settles the admission `failed` and deletes nothing, also when a since-replaced CLI registration (another principal) admitted that request_id for a remove or purge, since idempotency is per principal; an admission bound to the current incarnation still resumes under the new registration; deactivation and graduation list an unsettled admission as a blocker that names its request_id and asks the user whether to finish it or keep what is left; an automatic expired-archive purge's admission (`expired_only` in its outcome) is left to the next automatic run with `needsUser: false`, and `sources writer status --json` lists the stopped and superseded requests (`topology_requests`). Tests: `test/source-retire-batched.test.ts` (PGLite), `test/e2e/source-retire-batched-postgres.test.ts` (60,000 pages), `test/source-retire-incarnation.test.ts` and `test/e2e/source-retire-incarnation-postgres.test.ts`.-- `src/core/persistence/label-edit.ts` + `src/core/repair/label-write.ts` (GST-2468) — the label-only page write of operator repairs (`repair visibility`, `repair private-labels`). `label-edit.ts`: `LABEL_KEYS` (visibility, access, confidentiality), `readLabelEdit` validates a `managed_maintenance_page` intent's `label_edit` (`set` plain-word values, `remove` keys), `spliceLabelLines` removes, replaces or appends label lines in a file's frontmatter text and declines (null) a block or multi-line value, a duplicate key or a file with no frontmatter block. `page-prepare.ts` `labelEditFile` uses it in `compareFileTarget` when the file matches the snapshot: the edited file (or its edited head over the write's body, for a fence row) must read back as the file the write would render, else the write refuses `label_edit_refused` (GST-2603; reason `file_differs` with the differing keys in `detail`, or `label_line`); the file is never re-rendered under a label edit. GST-2603: `labelEditFit` (also used by `writeLabelFile`) aligns the file with the stored page before comparing, and `align-stored.ts` `keepStoredOnlyStamps` (used by `alignWithStored` and sync's `keepStoredStamps`) keeps the stamps gbrain holds only in the database (the `validate: false` grandfather stamp and a stored `legacy_type` whose aligned type is the page's), so they never count as a difference; `fileSnapshotDifference` lists the differing keys (frontmatter keys, title, type, tags, body, timeline) for the raw and inferred reading and `fileMatchesSnapshot` is its empty case. `label-write.ts` `labelFileRefusal` is a write-free preflight (managed: `prepareFileTarget`, with the drift's keys from `error.localEdit` and `gbrain sources reconcile <id> <slug> --preview` as next step; unmanaged: `ownerRepairFile`, next step `gbrain sync --source <id>`; repo-less or no file: null); `visibility.ts` holds refusing pages in the preview (`details.held`, `residuals.held_file_drift` / `held_label_edit`, outside the hash and approved set) and `labelWrite` / `private-labels.ts` `prepareWrite` throw only its `label_edit_refused` before writing. `repair/core.ts` counts `label_edit_refused` as declined and never toward `item_failures_systemic`. Test: `test/label-repair-derived-stamps-gst2603.test.ts`. `label-write.ts`: `writeLabelPage` publishes through the maintenance door with `keep_trust` and the edit on a managed brain, else `importAtRevision` (maintenance transaction, page lock, `withTrustKeep`); `filesInCheckout` names the unmanaged pages whose checkout file would undo a database-only write; for those, `writeLabelFile` applies `labelEditFile` to the file's own bytes (it must still hold the page, `ownerRepairFile`), imports it under `withTrustKeep` and writes it back through `writePageThrough` (`fileText`, preimage checked) in one transaction; drift or a file edited mid-write throws `source_changed`, and a file it cannot write (`sync.write_through` off, `url_clone`, an unresolvable target, a write error) returns a held `file_backed` outcome with the import rolled back. `repair visibility` calls it directly; `private-labels` still holds those pages as `file_backed`. GST-2476: `label-edit.ts` also edits `readable_by` (`READERS_KEY`, `EDIT_KEYS`; `set` takes a plain-word list, rendered `readable_by: [a, b]`), and `writeLabelPage` takes a maintenance `batch` (then `publishMaintenancePages([page], {batch})`). `src/core/repair/readers.ts` is `repair visibility --readers`: `checkedReaders` (members exist and are enabled, groups exist, else `access_member_invalid`; a list that leaves out the owner refuses unless `allowWithoutOwner`), `planReaders` (named pages or a `--slugs-file`, up to `READERS_MAX_PAGES`, approved set bound to each page's live readers) `readersWrite` (re-checks a page, holds a segmented one, renders the edit) and `applyReaders` (phase `READERS_PHASE`, one label-only write); `visibility.ts` `applyBatch` admits a managed source's run of readers items together through `publishMaintenancePages` under the run's batch (Postgres publishes them in groups of up to 8), so the Git effect commits a window's ready files together; `readersGitCounts` reports the run's Git effect states. `visibility.ts` `labelWrite` holds a managed page with no canonical file outside `storage.db_only` as `canonical_file_missing`. GST-2519, labels under `storage.db_only`: `sync-classify.ts` `gitVerdict` keeps a strict source's `db_ahead` path when `state.dbOnly` (a label repair on a page whose file Git still tracks there survives later syncs; a commit that moved still imports); `sync-prepare.ts` imports a db_only file over a live page through `withStoredLabels(text, stored, incoming)`, which adds each `EDIT_KEYS` label the row holds and the file does not state, so an import there never widens (a label the file states applies, wider included); `page-prepare.ts` `prepareFileTarget` lets a label repair of a strict page stamped `git_ignored`, with no recorded file and a path Git still ignores, write the database only instead of holding it `canonical_file_missing`. Tests: `test/db-only-labels-gst2519.test.ts`, `test/sync-classify-strict-g3.test.ts`.+- `src/core/persistence/label-edit.ts` + `src/core/repair/label-write.ts` (GST-2468) — the label-only page write of operator repairs (`repair visibility`, `repair private-labels`). `label-edit.ts`: `LABEL_KEYS` (visibility, access, confidentiality), `readLabelEdit` validates a `managed_maintenance_page` intent's `label_edit` (`set` plain-word values, `remove` keys), `spliceLabelLines` removes, replaces or appends label lines in a file's frontmatter text and declines (null) a block or multi-line value, a duplicate key or a file with no frontmatter block. `page-prepare.ts` `labelEditFile` uses it in `compareFileTarget` when the file matches the snapshot: the edited file (or its edited head over the write's body, for a fence row) must read back as the file the write would render, else the write refuses `label_edit_refused` (GST-2603; reason `file_differs` with the differing keys in `detail`, or `label_line`); the file is never re-rendered under a label edit. GST-2603: `labelEditFit` (also used by `writeLabelFile`) aligns the file with the stored page before comparing, and `align-stored.ts` `keepStoredOnlyStamps` (used by `alignWithStored` and sync's `keepStoredStamps`) keeps the stamps gbrain holds only in the database (the `validate: false` grandfather stamp and a stored `legacy_type` whose aligned type is the page's), so they never count as a difference; `fileSnapshotDifference` lists the differing keys (frontmatter keys, title, type, tags, body, timeline) for the raw and inferred reading and `fileMatchesSnapshot` is its empty case. `label-write.ts` `labelFileRefusal` is a write-free preflight (managed: `prepareFileTarget`, with the drift's keys from `error.localEdit` and `gbrain sources reconcile <id> <slug> --preview` as next step; unmanaged: `ownerRepairFile`, next step `gbrain sync --source <id>`; repo-less or no file: null); `visibility.ts` holds refusing pages in the preview (`details.held`, `residuals.held_file_drift` / `held_label_edit`, outside the hash and approved set) and `labelWrite` / `private-labels.ts` `prepareWrite` throw only its `label_edit_refused` before writing. `repair/core.ts` counts `label_edit_refused` as declined and never toward `item_failures_systemic`. Test: `test/label-repair-derived-stamps-gst2603.test.ts`. `label-write.ts`: `writeLabelPage` publishes through the maintenance door with `keep_trust` and the edit on a managed brain, else `importAtRevision` (maintenance transaction, page lock, `withTrustKeep`); `filesInCheckout` names the unmanaged pages whose checkout file would undo a database-only write; for those, `writeLabelFile` applies `labelEditFile` to the file's own bytes (it must still hold the page, `ownerRepairFile`), imports it under `withTrustKeep` and writes it back through `writePageThrough` (`fileText`, preimage checked) in one transaction; drift or a file edited mid-write throws `source_changed`, and a file it cannot write (`sync.write_through` off, `url_clone`, an unresolvable target, a write error) returns a held `file_backed` outcome with the import rolled back. `repair visibility` calls it directly; `private-labels` still holds those pages as `file_backed`; `repair/origin-carry.ts` (GST-2689) uses `writeLabelFile`, `importAtRevision` and `publishMaintenancePages` the same way to label derived pages private before their origin row goes, and parks the origin when one returns held or throws. GST-2476: `label-edit.ts` also edits `readable_by` (`READERS_KEY`, `EDIT_KEYS`; `set` takes a plain-word list, rendered `readable_by: [a, b]`), and `writeLabelPage` takes a maintenance `batch` (then `publishMaintenancePages([page], {batch})`). `src/core/repair/readers.ts` is `repair visibility --readers`: `checkedReaders` (members exist and are enabled, groups exist, else `access_member_invalid`; a list that leaves out the owner refuses unless `allowWithoutOwner`), `planReaders` (named pages or a `--slugs-file`, up to `READERS_MAX_PAGES`, approved set bound to each page's live readers) `readersWrite` (re-checks a page, holds a segmented one, renders the edit) and `applyReaders` (phase `READERS_PHASE`, one label-only write); `visibility.ts` `applyBatch` admits a managed source's run of readers items together through `publishMaintenancePages` under the run's batch (Postgres publishes them in groups of up to 8), so the Git effect commits a window's ready files together; `readersGitCounts` reports the run's Git effect states. `visibility.ts` `labelWrite` holds a managed page with no canonical file outside `storage.db_only` as `canonical_file_missing`. GST-2519, labels under `storage.db_only`: `sync-classify.ts` `gitVerdict` keeps a strict source's `db_ahead` path when `state.dbOnly` (a label repair on a page whose file Git still tracks there survives later syncs; a commit that moved still imports); `sync-prepare.ts` imports a db_only file over a live page through `withStoredLabels(text, stored, incoming)`, which adds each `EDIT_KEYS` label the row holds and the file does not state, so an import there never widens (a label the file states applies, wider included); `page-prepare.ts` `prepareFileTarget` lets a label repair of a strict page stamped `git_ignored`, with no recorded file and a path Git still ignores, write the database only instead of holding it `canonical_file_missing`. Tests: `test/db-only-labels-gst2519.test.ts`, `test/sync-classify-strict-g3.test.ts`.- `src/core/persistence/page-edit.ts` — `edit_page` (#5616): splits the canonical serialization into editable text and protected takes/facts segments whose remote view matches get_page's sanitized `content` byte for byte; `applyPageEdits` applies ordered exact-once replacements inside editable text only (typed `edit_no_match`/`edit_ambiguous_match`/`edit_protected_span`/`edit_invalid`), so canonical fences never move; `editDiff` caps the caller-view diff at 8 KB; `boundedUnifiedDiff` keeps its LCS table under `EDIT_PAGE_DIFF_CELL_BUDGET` (4M cells) by diffing only the window between common leading/trailing lines, and a window still over budget becomes one coarse hunk flagged `diff_coarse` (pinned by `test/large-pages/edit-diff-bounded.test.ts`). Called at submission (`page-mutations.ts`, before admission; skipped for a segmented page) and again on the locked snapshot in `page-prepare.ts`, which gives edit_page put_page's revision-bound `editing` timeline semantics. Pinned by `test/edit-page.test.ts`. `within` and the segmented path: [large page writes](core-services-2-continued.md#large-page-writes).diff --git a/docs/architecture/key-files/memory-purge.md b/docs/architecture/key-files/memory-purge.mdindex 677e56762c..edea8e2b04 100644--- a/docs/architecture/key-files/memory-purge.md+++ b/docs/architecture/key-files/memory-purge.md@@ -23,7 +23,7 @@ User-facing contract: [expire versus purge](../../guides/memory-boundaries.md#pu- Withdrawn-claim refusal on `remember` (`persistence/memory-mutations.ts`, `memory-prepare.ts`) — admission refuses a withdrawn claim (`fact_withdrawn`, `FACT_WITHDRAWN_MESSAGE`/`_SUGGESTION` in `src/core/facts/withdrawal.ts`) before a request exists, and preparation re-checks it; `writeFailureDiagnostic` allowlists that prefix, so a failed receipt and `get_write_request` name it. `replaces` accepts a target saved without an entity (links it by supersession). Test: `test/remember-withdrawn-claim.test.ts`. (R1, Cat 40 Hard.) The refusal carries an additive `withdrawn` object (`factWithdrawnRefusal` in `facts/single-prepare.ts`, from `fact_withdrawals` only: the named entity's row over `all_entities`, then the newest, omitted when the caller cannot read the forgotten rows); `withdrawalFailureDetail`/`withdrawnFromDetail` in `facts/withdrawal.ts` keep it in the failed receipt's `error_detail` for `get_write_request` and replay. Tests: `test/withdrawn-detail.test.ts`, `test/e2e/withdrawn-detail-postgres.test.ts`.-- `src/core/persistence/purge-deleted.ts` — `purgeDeletedPagesCoordinated` backs the cycle `purge` phase, the purge job, `purge_deleted_pages` and `gbrain pages purge-deleted`. Unmanaged brains keep the engine bulk delete, after the belief-ledger expiry of recorded sources' tombstones: each is its own transaction and item (ItemRun site `purge.recorded_tombstones`), a run-scoped failure or a systemic run stops the purge, and any other failure lists the tombstone in `blocked` with its classified code, counts it in `failed` (no `error`, so the phase warns) and keeps it out of the bulk delete (`purgeDeletedPages` `excludeIds`); a content failure counts toward the same park as the managed purge, a transient one is retried next run, and parked tombstones are skipped as `purge_parked` unless `retryParked` (the unmanaged preview excludes them too). A managed brain purges each tombstone older than the window (skipping archived sources, which the source lifecycle purges) through `delete_page` with `purge: true` and the internal `retention: true` bound to its revision (retention is not an owner purge; see [belief ledger](belief-ledger.md)). Writer state is read once per run (`writerOnboardingPreflight`): a source whose writer is `recovery_required` submits nothing and its tombstones are listed in `blocked` as `writer_not_active` (counted in `inactive`). Revision races are deferred to the next run; a parked tombstone (`purge-parks.ts`) is skipped as `purge_parked` (counted in `parked`) unless `retryParked`, and any other failure is listed in `blocked` and sets `error`. `selectPurgeCandidates` is the one eligibility selector (preview, consent, `purge_deleted_pages` op, run), and its holds are `purgeHoldsSql` (archived source, rename-identity, restorable-atom and derived-retirement holds), which doctor `embedding_state` also counts with; #6884: the run submits only while the writer has outstanding-request room (`readOutstandingRoom` in `journal.ts`, at `persistence.capacity.background_pause_pct` of the cap for a background run); the rest, and the rest after a `queue_capacity` refusal, is `blocked` as `write_capacity_deferred` and counted in `capacity_deferred`, never a failure or a park. `purgePhaseStatus`/`purgePhaseNote` shape the cycle purge phase (fail on `error`; warn on `writer_not_active`, parked, capacity-deferred or an unmanaged `failed` tombstone). The engine bulk delete (`engine-sql/pages.ts` `purgeDeletedPages`) also deletes, in its transaction, the purged pages' stagings (by source and slug) and the segment texts only their manifests referenced. Tests: `test/managed-writers-w3.test.ts`, `test/purge-deleted-parks.test.ts`, `test/purge-deleted-capacity-6884.test.ts`, `test/pathological/a49-unmanaged-purge-tombstones.test.ts`.+- `src/core/persistence/purge-deleted.ts` — `purgeDeletedPagesCoordinated` backs the cycle `purge` phase, the purge job, `purge_deleted_pages` and `gbrain pages purge-deleted`. Unmanaged brains keep the engine bulk delete, after the belief-ledger expiry of recorded sources' tombstones: each is its own transaction and item (ItemRun site `purge.recorded_tombstones`), a run-scoped failure or a systemic run stops the purge, and any other failure lists the tombstone in `blocked` with its classified code, counts it in `failed` (no `error`, so the phase warns) and keeps it out of the bulk delete (`purgeDeletedPages` `excludeIds`); a content failure counts toward the same park as the managed purge, a transient one is retried next run, and parked tombstones are skipped as `purge_parked` unless `retryParked` (the unmanaged preview excludes them too). A managed brain purges each tombstone older than the window (skipping archived sources, which the source lifecycle purges) through `delete_page` with `purge: true` and the internal `retention: true` bound to its revision (retention is not an owner purge; see [belief ledger](belief-ledger.md)). Writer state is read once per run (`writerOnboardingPreflight`): a source whose writer is `recovery_required` submits nothing and its tombstones are listed in `blocked` as `writer_not_active` (counted in `inactive`). Revision races are deferred to the next run; a parked tombstone (`purge-parks.ts`) is skipped as `purge_parked` (counted in `parked`) unless `retryParked`, and any other failure is listed in `blocked` and sets `error`. `selectPurgeCandidates` is the one eligibility selector (preview, consent, `purge_deleted_pages` op, run), and its holds are `purgeHoldsSql` (archived source, rename-identity, restorable-atom and derived-retirement holds), which doctor `embedding_state` also counts with; #6884: the run submits only while the writer has outstanding-request room (`readOutstandingRoom` in `journal.ts`, at `persistence.capacity.background_pause_pct` of the cap for a background run); the rest, and the rest after a `queue_capacity` refusal, is `blocked` as `write_capacity_deferred` and counted in `capacity_deferred`, never a failure or a park. `purgePhaseStatus`/`purgePhaseNote` shape the cycle purge phase (fail on `error`; warn on `writer_not_active`, parked, capacity-deferred or an unmanaged `failed` tombstone). The engine bulk delete (`engine-sql/pages.ts` `purgeDeletedPages`) also deletes, in its transaction, the purged pages' stagings (by source and slug) and the segment texts only their manifests referenced. GST-2689: every run first calls `repair/origin-carry.ts` `carryPrivateBeforePurge` (both branches); the origins it parks are listed in `blocked` as `derived_origin_parked` and counted in `origin_parked` (the phase warns), and `derivedOriginPurgeHold` is in `purgeHoldsSql`, the recorded-tombstone scan and delete, and the engine bulk delete. Tests: `test/managed-writers-w3.test.ts`, `test/purge-deleted-parks.test.ts`, `test/purge-deleted-capacity-6884.test.ts`, `test/pathological/a49-unmanaged-purge-tombstones.test.ts`, `test/derived-origin-carry-private.test.ts`.- `src/core/persistence/derived-retirement-hold.ts` — GBRA-161: the purge hold for every derived retirement. `DERIVED_RETIRED_BY` lists the `retired_by` stamps derived writers put on the pages they retire (extract-atoms, managed-reextract, stale-atoms, life-chronicle); `derivedRetirementPurgeHold(alias)` keeps a stamped page out of every purge route (engine bulk purge and its preview, the coordinated selection and delete) until `DERIVED_RETIREMENT_HOLD_DAYS` (30) after `deleted_at` (the database clock, never the `retired_at` text); `retireDerivedPages` versions, soft-deletes and stamps a batch in one attributed transaction (unmanaged extract_atoms). `assertRetirementStampUnchanged` is the page preparer's refusal (`reserved_frontmatter_key`) of a remote write that adds or changes one of `RESERVED_RETIREMENT_KEYS`. The hold length follows `generations.restore_days` (`RESTORE_DAYS_SQL`, read inside the purge statement; 30 by default) and `retireDerivedPagesInTransaction` is the in-transaction form generation adapters retire through. An explicit `gbrain delete --purge` is not held.- `src/core/generations/ledger-scrub.ts` — GBRA-161: purge reaches the generation ledger. A page purge (`page-purge.ts`) nulls the purged item's preimages in `derived_generation_items` and every held proposal in `derived_generations` naming it, and deletes the page's fence holds (`FENCE_GENERATION_KINDS` under `page:<slug>`, whose rows the purge deletes; `test/generations-purge-fence-hold-7774.test.ts`); a fact purge (`facts/purge.ts`) nulls every preimage, proposal and held context carrying the claim. Both are `swept` (`generation_ledger`) in the deletion inventory, so the verification probes them; `gbrain repair generations` then refuses a scrubbed item with `no_preimage`.- `src/core/persistence/purge-name-stores.ts` — #9068: `scrubPurgedNameStores(engine, sourceId, slugs)` deletes the source's `context_volunteer_events` rows (whose rationale quotes the matched name) and `mention_gazetteer_entries` rows (`name_norm -> target_slug`) for purged slugs. Every hard delete of a page calls it inside its transaction (`purgePageInTransaction`, `purgeDeletedPages`, `expireRecordedTombstones`, the restore purge replay in `belief/purge-mirror.ts`, and the engines' batch `deletePages`); removing a source deletes the source's volunteer rows (`removedSourceScrubCtes` in `source-delete.ts`) and its gazetteer rows by cascade; a soft delete keeps both. Both tables are `swept` (`page_names`) in the deletion inventory; the page receipt checks them by slug, and the fact receipt probes them (rationale, name_norm) and reports a match as `probed_reported`, because a fact purge sweeps neither.@@ -34,5 +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')` (the postimage drops the origin rows; pages that name readers and life-chronicle events are never returned) 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 the expired origins (`type = 'atom'` or hidden by `privacyPartSql`), 200 at a time, parks the blocked ones and clears the rest. `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).- `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/access-designations.md b/docs/guides/access-designations.mdindex df6cf27e4d..a5779b320d 100644--- a/docs/guides/access-designations.md+++ b/docs/guides/access-designations.md@@ -124,6 +124,15 @@ These rules follow the origin, so nobody writes them by hand:`gbrain repair visibility` stamps the explicit value on derived pages (tighten-only). The owner reads them all.+When you delete a page that keeps others private, gbrain gives each page whose only privacy came from it its own+`visibility: private` label, so it stays hidden once the deleted page's row is gone (a page that names readers is left as+it is). The label stays after that: if you restore the deleted page and later make it world, the pages derived from it+stay private until the owner relabels them.++A file removed with `git rm` outside gbrain is covered only from the next cycle: the next sync soft-deletes its page and+the cycle's purge labels the derived pages before it removes any row. If a label cannot be written, the purge keeps the+deleted page and `gbrain doctor` names it as `derived_origin_parked`, with the page that blocks it.+### `pinned_question`Pinned-question pages are the owner's own and read as private. The owner reads them; a `--private-pages granted-sources` grant never widens them.diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.mdindex b82ebb4653..7f43615927 100644--- a/docs/guides/troubleshooting.md+++ b/docs/guides/troubleshooting.md@@ -75,6 +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 purges the page | 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 |@@ -460,7 +461,7 @@ derived from the rows against the active embedding column (no stored status):| `keyword_only` | The page carries `embed_skip`: the import gate found its body over `content_sanity.bytes_block` (info, by design; its chunks still feed keyword search and are never purged). Removing the marker alone is undone on the next import. | A marker under the current `bytes_block` (written by an older release under its 500 KB default): `gbrain reindex --oversized --source <id>` clears it for free. Otherwise split the page, or, after the operator approves, `gbrain config set content_sanity.bytes_block <bytes>` then `gbrain sync --source <id> --full`, which re-imports and embeds it. || `quarantined` | The content-quality gate hid the page as junk; it has no searchable chunks. Doctor `quarantined_pages` owns its warning. | Review with `gbrain quarantine list --json`; clear a false positive with `gbrain quarantine clear <slug> --source-id <id> --force` (the owner's call). || `empty` | A live page with nothing to index: no body text, or a body its writer chunked to nothing at the current revision (for example one holding only a protected takes fence). | Nothing for a page whose content is kept out of search on purpose. For a blank stub: write content to it, or delete it (`gbrain delete <slug> --source <id> --force`, restorable) after the user agrees. |-| `deleted_page_chunks` | Chunks of a soft-deleted page. Search never reads them; the purge lifecycle removes them after 72 h (info until then, a warning past it, code `deleted_page_chunks_overdue`). Chunks the purge holds stay info past 72 h: a derived retirement for `generations.restore_days` (30 days by default), a restorable atom, an open rename-identity pair or an archived source. | `gbrain pages purge-deleted --dry-run --json`, then `gbrain pages purge-deleted --yes` once the user agrees (brain-wide, irreversible). |+| `deleted_page_chunks` | Chunks of a soft-deleted page. Search never reads them; the purge lifecycle removes them after 72 h (info until then, a warning past it, code `deleted_page_chunks_overdue`). Chunks the purge holds stay info past 72 h: a derived retirement for `generations.restore_days` (30 days by default), a restorable atom, an open rename-identity pair, a page whose derived pages could not be labelled private (`derived_origin_parked`) or an archived source. | `gbrain pages purge-deleted --dry-run --json`, then `gbrain pages purge-deleted --yes` once the user agrees (brain-wide, irreversible). || `chunkless_healable` | A live page with body text but no chunk rows (written without the chunking step, or an `embed_skip` page an older gbrain stored without chunks or whose `reindex --oversized` rewrite failed). Keyword search cannot find it. Doctor warns on a keyed brain (code `chunkless_pages_healable`). | `gbrain embed --stale --catch-up --source <id> --yes` chunks and embeds it (paid); an `embed_skip` page gets chunks and no vectors. The cycle's embed phase runs the same safety net. |`unsearchable` sums `pending`, `quarantined`, `empty` and `chunkless_healable`;diff --git a/llms-full.txt b/llms-full.txtindex 345bbf9944..d5dadcd61c 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -9060,6 +9060,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 purges the page | 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 |@@ -9445,7 +9446,7 @@ derived from the rows against the active embedding column (no stored status):| `keyword_only` | The page carries `embed_skip`: the import gate found its body over `content_sanity.bytes_block` (info, by design; its chunks still feed keyword search and are never purged). Removing the marker alone is undone on the next import. | A marker under the current `bytes_block` (written by an older release under its 500 KB default): `gbrain reindex --oversized --source <id>` clears it for free. Otherwise split the page, or, after the operator approves, `gbrain config set content_sanity.bytes_block <bytes>` then `gbrain sync --source <id> --full`, which re-imports and embeds it. || `quarantined` | The content-quality gate hid the page as junk; it has no searchable chunks. Doctor `quarantined_pages` owns its warning. | Review with `gbrain quarantine list --json`; clear a false positive with `gbrain quarantine clear <slug> --source-id <id> --force` (the owner's call). || `empty` | A live page with nothing to index: no body text, or a body its writer chunked to nothing at the current revision (for example one holding only a protected takes fence). | Nothing for a page whose content is kept out of search on purpose. For a blank stub: write content to it, or delete it (`gbrain delete <slug> --source <id> --force`, restorable) after the user agrees. |-| `deleted_page_chunks` | Chunks of a soft-deleted page. Search never reads them; the purge lifecycle removes them after 72 h (info until then, a warning past it, code `deleted_page_chunks_overdue`). Chunks the purge holds stay info past 72 h: a derived retirement for `generations.restore_days` (30 days by default), a restorable atom, an open rename-identity pair or an archived source. | `gbrain pages purge-deleted --dry-run --json`, then `gbrain pages purge-deleted --yes` once the user agrees (brain-wide, irreversible). |+| `deleted_page_chunks` | Chunks of a soft-deleted page. Search never reads them; the purge lifecycle removes them after 72 h (info until then, a warning past it, code `deleted_page_chunks_overdue`). Chunks the purge holds stay info past 72 h: a derived retirement for `generations.restore_days` (30 days by default), a restorable atom, an open rename-identity pair, a page whose derived pages could not be labelled private (`derived_origin_parked`) or an archived source. | `gbrain pages purge-deleted --dry-run --json`, then `gbrain pages purge-deleted --yes` once the user agrees (brain-wide, irreversible). || `chunkless_healable` | A live page with body text but no chunk rows (written without the chunking step, or an `embed_skip` page an older gbrain stored without chunks or whose `reindex --oversized` rewrite failed). Keyword search cannot find it. Doctor warns on a keyed brain (code `chunkless_pages_healable`). | `gbrain embed --stale --catch-up --source <id> --yes` chunks and embeds it (paid); an `embed_skip` page gets chunks and no vectors. The cycle's embed phase runs the same safety net. |`unsearchable` sums `pending`, `quarantined`, `empty` and `chunkless_healable`;diff --git a/plugin-variants/gbrain-coding/skills/data-loss-gate/SKILL.md b/plugin-variants/gbrain-coding/skills/data-loss-gate/SKILL.mdindex e3e3fcfe80..bebff54988 100644--- a/plugin-variants/gbrain-coding/skills/data-loss-gate/SKILL.md+++ b/plugin-variants/gbrain-coding/skills/data-loss-gate/SKILL.md@@ -84,7 +84,7 @@ Brain / database level (gbrain-specific):the files" or "remove it from Git" is not a go to purge database pages. Afterthe go, purge one page at a time (never a parallel `xargs` or a backgroundloop), confirm each one is gone (`gbrain get <slug> --include-deleted` reports- `page_not_found`) before the next, and stop the batch at the first refusal. A purge batch that was+ `page_not_found`; a receipt with `purge_held` was kept soft-deleted to keep its derived pages private) before the next, and stop the batch at the first refusal. A purge batch that wasstopped (SIGTERM, a write freeze, a timeout) stays stopped: report whatfinished and ask again before relaunching it.- **`gbrain pages purge-deleted`** — permanently removes soft-deleted pagesdiff --git a/plugin/skills/data-loss-gate/SKILL.md b/plugin/skills/data-loss-gate/SKILL.mdindex e3e3fcfe80..bebff54988 100644--- a/plugin/skills/data-loss-gate/SKILL.md+++ b/plugin/skills/data-loss-gate/SKILL.md@@ -84,7 +84,7 @@ Brain / database level (gbrain-specific):the files" or "remove it from Git" is not a go to purge database pages. Afterthe go, purge one page at a time (never a parallel `xargs` or a backgroundloop), confirm each one is gone (`gbrain get <slug> --include-deleted` reports- `page_not_found`) before the next, and stop the batch at the first refusal. A purge batch that was+ `page_not_found`; a receipt with `purge_held` was kept soft-deleted to keep its derived pages private) before the next, and stop the batch at the first refusal. A purge batch that wasstopped (SIGTERM, a write freeze, a timeout) stays stopped: report whatfinished and ask again before relaunching it.- **`gbrain pages purge-deleted`** — permanently removes soft-deleted pagesdiff --git a/skills/data-loss-gate/SKILL.md b/skills/data-loss-gate/SKILL.mdindex 3bb82c7c7c..4fcdf116d8 100644--- a/skills/data-loss-gate/SKILL.md+++ b/skills/data-loss-gate/SKILL.md@@ -83,7 +83,7 @@ Brain / database level (gbrain-specific):the files" or "remove it from Git" is not a go to purge database pages. Afterthe go, purge one page at a time (never a parallel `xargs` or a backgroundloop), confirm each one is gone (`gbrain get <slug> --include-deleted` reports- `page_not_found`) before the next, and stop the batch at the first refusal. A purge batch that was+ `page_not_found`; a receipt with `purge_held` was kept soft-deleted to keep its derived pages private) before the next, and stop the batch at the first refusal. A purge batch that wasstopped (SIGTERM, a write freeze, a timeout) stays stopped: report whatfinished and ask again before relaunching it.- **`gbrain pages purge-deleted`** — permanently removes soft-deleted pagesdiff --git a/skills/skills.lock.history.json b/skills/skills.lock.history.jsonindex 8f296b5f6f..f84faf223c 100644--- a/skills/skills.lock.history.json+++ b/skills/skills.lock.history.json@@ -426,6 +426,7 @@"6cddc796a128ddeea8c622de79dde1ec1e6c214203bce51ea5e751719e291d46","790407f6a91dba74d6ca1f482bb2eaa28977e79a5cf9a8e642f71691cab69652","8628ca47c450c8e4563565a1dfa264db8b909161c6bbb9b9a0ead124e4870dad",+ "8eb7ac6fc67151497f493d42ec3221f1deae69e0e1e66777a900996b154b444d","95ed4cf41deec4df50a56a1d28efb43738f0d76792392693d1b0956c93bcb3e7","c1736e0985121e60ffeba993b68b5c722c9285220057b5ef72059f111aabcb18"],diff --git a/skills/skills.lock.json b/skills/skills.lock.jsonindex ba3ec304d1..9bd51f4629 100644--- a/skills/skills.lock.json+++ b/skills/skills.lock.json@@ -72,7 +72,7 @@"daily-task-manager/SKILL.md": "d1968b1284b2284691b15c3d7430df7c47b83b59703177a36f49d973ea24ff22","daily-task-manager/routing-eval.jsonl": "e98b2592e65c26952242436a960d8b2061e375b269004a18c230cbcf1d692ff9","daily-task-prep/SKILL.md": "5ea839012b48761ed8d7a9bab056a2566587d6f7fe044e3907d77b20f8eec5ac",- "data-loss-gate/SKILL.md": "8628ca47c450c8e4563565a1dfa264db8b909161c6bbb9b9a0ead124e4870dad",+ "data-loss-gate/SKILL.md": "8eb7ac6fc67151497f493d42ec3221f1deae69e0e1e66777a900996b154b444d","data-loss-gate/routing-eval.jsonl": "825358a5600641061a02b25097cd84c1c28bb0359a7608a10b9f25f661bd88f9","data-research/SKILL.md": "39f9648a21a7074d6ad7db789e93e6d7085449a6cdaffacf8b1660eb68636b9d","db-repair/SKILL.md": "87a34fe18812f3b6ec37381ae69c205e30747300098ebe3fe41f8460d0ba8346",@@ -226,7 +226,7 @@"skillpack-check/SKILL.md": "0d2d2d201ed72e19b47d7e3743b5bbdfb5c2655d1f34d29447c601fca3908f9e","skillpack-harvest/SKILL.md": "0f86314b58d25b5511809f567c04aedc3fba6fe35ed642ac52d8216ae365b6eb","skillpack-harvest/routing-eval.jsonl": "cb4783288e95af3132b32ecb40a54cffc095f57b36240f96a25c2d2adf5e68c6",- "skills.lock.history.json": "ac900fd266e707da08a83c204b00dfc03e7634499ebd574a6f39fb3a224e8101",+ "skills.lock.history.json": "45b5b94835215c67be9379f1e168030cd24c367c284201f7a5c178e46a0015cf","smoke-test/SKILL.md": "f5099e1d2ab9dc6827096249e68414f7ae357c29b39fb069a54bb7fb74f414a5","soul-audit/SKILL.md": "7a48e180849f7502d332878c443397f90a3756f45caa94f76bcfcc7c997469c8","strategic-reading/SKILL.md": "ab2cd3adc79289374cfbc5cb3d5ee17f962fd8f7f3c997a1da708da0ed67797c",