Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Keep readers-only pages derived from a deleted private origin closed to their listed readers

garrytan76514e558772
diff --git a/changelog.d/derived-origin-delete-carry-private.md b/changelog.d/derived-origin-delete-carry-private.md
index cfb3a4f0dd..c3e27ad546 100644
--- a/changelog.d/derived-origin-delete-carry-private.md
+++ b/changelog.d/derived-origin-delete-carry-private.md
@@ -10,6 +10,6 @@ important: security
- 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.
+- Pages that are already private, pinned questions and pages that do not derive from the deleted page are never changed. A page that names readers (`readable_by`) and was hidden from them only through its private origin gets the label too and keeps its readers, so its listed readers still can't read it. The owner, a `granted_sources` credential and a listed reader read exactly the same pages as before.
- 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/memory-purge.md b/docs/architecture/key-files/memory-purge.md
index edea8e2b04..df65485c74 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')` (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/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; a page that names readers is returned when its listed readers would gain it, and gets the label with its `readable_by` kept; 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.md
index a5779b320d..5aeb3abd7c 100644
--- a/docs/guides/access-designations.md
+++ b/docs/guides/access-designations.md
@@ -125,8 +125,8 @@ 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
+`visibility: private` label, so it stays hidden once the deleted page's row is gone (a page that names readers keeps its
+`readable_by` and gets the label too, so its listed readers don't gain it). 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
diff --git a/src/core/repair/origin-carry.ts b/src/core/repair/origin-carry.ts
index 0d4e1650ba..717adc488d 100644
--- a/src/core/repair/origin-carry.ts
+++ b/src/core/repair/origin-carry.ts
@@ -3,9 +3,9 @@
* private (a declared derived_from origin, an atom's source_slug origin, a concept whose provenance atom has one) opens
* once the origin row is gone. So before an origin row is removed, every live same-source page that would gain a reader
* gets `visibility: private` through the label door (repair/label-write.ts): tighten-only, the trust tier kept, no lowering
- * proposal filed, a managed file changed in that one line. The dependents are private-labels.ts dependentsSql('remove'):
- * a page already private, naming readers, pinned or not lineage-dependent is never returned, and a life-chronicle event
- * already fails closed, so it is skipped.
+ * proposal filed, a managed file changed in that one line, readable_by kept. The dependents are private-labels.ts
+ * dependentsSql('remove'): a page already private, pinned or not lineage-dependent is never returned, a page that names
+ * readers is returned when its listed readers would gain it, and a life-chronicle event already fails closed, so it is skipped.
*
* Two places run it. delete_page (deletePageCarryingPrivate): a soft delete, local or remote, labels the dependents once
* the delete committed, as a maintenance write whose batch names the delete's request id (on a managed brain); a failure
diff --git a/src/core/repair/private-labels.ts b/src/core/repair/private-labels.ts
index e9c9b5dca8..2802f18902 100644
--- a/src/core/repair/private-labels.ts
+++ b/src/core/repair/private-labels.ts
@@ -236,7 +236,8 @@ async function planRestore(engine: BrainEngine, scope: RepairScope, selection: S
*
* GST-2689 `remove`: the postimage is the pages table with the cleared pages removed instead (their rows, so the links to
* them go too), `keys` is unused, an atom also ties to the page a rename moved its `source_slug` to (slug_aliases and
- * slug_rename_history, read before a purge scrubs them), and a page that names readers is never returned.
+ * slug_rename_history, read before a purge scrubs them). A page that names readers is judged by the same privacy rules,
+ * since readable_by never relaxes them: it is returned when the removal would open it to its listed readers.
*/
export function dependentsSql(mode: 'clear' | 'remove' = 'clear'): string {
const remove = mode === 'remove';
@@ -271,7 +272,7 @@ export function dependentsSql(mode: 'clear' | 'remove' = 'clear'): string {
SELECT cand.id, cand.cleared_id, CASE WHEN p.type = 'event' AND p.frontmatter->>'captured_via' LIKE 'life-chronicle:%' THEN 'life_chronicle'
WHEN p.type = 'atom' THEN 'atom' WHEN p.type = 'concept' AND p.frontmatter->>'synthesized_by' IS NOT NULL THEN 'concept' ELSE 'derived_from' END AS category
FROM candidates cand JOIN pages p ON p.id = cand.id
- WHERE cand.id IN (SELECT id FROM public_after) AND NOT ${privacyPartSql('p')}${remove ? " AND NOT (p.frontmatter ? 'readable_by')" : ''}
+ WHERE cand.id IN (SELECT id FROM public_after) AND NOT ${privacyPartSql('p')}
ORDER BY cand.id, cand.cleared_id`;
}
diff --git a/test/derived-origin-carry-private.test.ts b/test/derived-origin-carry-private.test.ts
index c6b2877579..d3fe696980 100644
--- a/test/derived-origin-carry-private.test.ts
+++ b/test/derived-origin-carry-private.test.ts
@@ -9,7 +9,7 @@
* list_pages and search. The owner, a granted_sources credential and a listed member read the same before and after.
* Pages already private, naming readers, pinned or not lineage-dependent are never changed; trust tiers are kept and
* no lowering proposal is filed. A remote delete's response names no stamped page and counts none. A page that names
- * readers is never changed, so its listed reader gains it once the origin goes (the one read that changes). When the stamp
+ * readers gets the label too (its readable_by kept), so its listed reader does not gain it either. When the stamp
* fails, the origin is parked (never purged), doctor names it with the page that blocks it, and the derived page
* stays hidden; once the cause is fixed the next purge stamps and purges. Nothing of a purged origin is kept.
* 2. Fails when: any of those reads opens to a non-owner after the origin goes, a read changes for a reader who had it,
@@ -46,9 +46,9 @@ const OWNER = 'owner-example';
const ALICE = 'alice-example';
/** Pages that gain a reader once the origin goes, then the pages the stamp must never change. */
const CARRIED = ['digest', 'atom', 'concept'] as const;
-const UNTOUCHED = ['own', 'listed', 'pinned', 'plain'] as const;
-type Shape = 'origin' | typeof CARRIED[number] | typeof UNTOUCHED[number];
-const SHAPES: Shape[] = ['origin', ...CARRIED, ...UNTOUCHED];
+const UNTOUCHED = ['own', 'pinned', 'plain'] as const;
+type Shape = 'origin' | typeof CARRIED[number] | 'listed' | typeof UNTOUCHED[number];
+const SHAPES: Shape[] = ['origin', ...CARRIED, 'listed', ...UNTOUCHED];
const CALLERS = ['owner', 'granted', 'alice', 'unbound'] as const;
type Caller = typeof CALLERS[number];
@@ -141,15 +141,17 @@ for (const kind of testBackends()) {
async function expectCarried(k: string, before: Record<string, unknown>, beforeState: Record<string, any>, beforeProposals: number): Promise<void> {
__resetPrivateVisibilityCacheForTests();
const others = SHAPES.filter(s => s !== 'origin');
- // Pages that name readers are never stamped: the listed member reads 'listed' once its private origin is gone.
- const expected = { ...Object.fromEntries(Object.entries(before).filter(([key]) => !key.endsWith(':origin'))), 'alice:listed': every };
expect(before['alice:listed']).toEqual(none);
- expect(await readsOf(k, others)).toEqual(expected);
+ expect(await readsOf(k, others)).toEqual(Object.fromEntries(Object.entries(before).filter(([key]) => !key.endsWith(':origin'))));
const after = await state(k);
for (const shape of CARRIED) {
expect({ shape, visibility: after[shape].fm.visibility }).toEqual({ shape, visibility: 'private' });
expect({ shape, tier: after[shape].tier }).toEqual({ shape, tier: beforeState[shape].tier });
}
+ // A page that names readers gets the label and keeps its readers: its listed member reads it neither before nor after.
+ expect({ ...after.listed, fm: { ...after.listed.fm, visibility: undefined } }).toEqual({ ...beforeState.listed, fm: { ...beforeState.listed.fm, visibility: undefined } });
+ expect(after.listed.fm.visibility).toBe('private');
+ expect(after.listed.fm.readable_by).toEqual([ALICE]);
for (const shape of UNTOUCHED) expect({ shape, ...after[shape] }).toEqual({ shape, ...beforeState[shape] });
expect(await proposals()).toBe(beforeProposals);
}