Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

Review fixes for the owner's private forget: judge the owner again under the publication's locks, name the brain host when the fact's page turned private, and cover stdio and other members' copies (GST-2346)

garrytan849c50a4a7cc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 645e99e963..6528e1b6b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,12 +12,12 @@ identifiers and attribution are available in the pre-removal Git revision
## [Unreleased]
-**The brain owner's own agents can now withdraw a private fact the brain host saved.** A credential bound to the brain owner (`gbrain access owner set`) reads private facts, but its `forget` refused one the host had saved with `visibility: "private"` and said only the brain host could withdraw it. Now, speaking for itself, the owner's credential withdraws a private fact it reads when the page that holds it is one the credential can already write. The fact is struck in the page's file on a brain with a Git repository, and on a strict source a fact held for an entity with no page is struck in `memory/unattributed`, so a rebuild from Git keeps it withdrawn. Three things stay as they were. A fact on a `visibility: private` page, on a page that names readers or on another member's page is still withdrawn on the brain host (`gbrain forget <id>`). A fact the owner confirmed or curated still asks the owner first (`forget_requires_owner`). Member credentials, attested calls (`x-qm-actor`), audiences, subagent jobs, slug-fenced clients and unbound connections get exactly the answers they got before.
+**The brain owner's own agents can now withdraw a private fact the brain host saved.** A credential bound to the brain owner (`gbrain access owner set`) reads private facts, but its `forget` refused one the host had saved with `visibility: "private"` and said only the brain host could withdraw it. Now, speaking for itself, the owner's credential (or a stdio server started with `--stdio-member <owner>`) withdraws a private fact it reads when the page that holds it is one the credential can already write. The fact is struck in the page's file on a brain with a Git repository, and on a strict source a fact held for an entity with no page is struck in `memory/unattributed`, so a rebuild from Git keeps it withdrawn. Three things stay as they were. A fact on a `visibility: private` page, on a page that names readers or on another member's page is still withdrawn on the brain host (`gbrain forget <id>`). A fact the owner confirmed or curated still asks the owner first (`forget_requires_owner`). Member credentials, attested calls (`x-qm-actor`), audiences, subagent jobs, slug-fenced clients and unbound connections get exactly the answers they got before.
### Itemized changes
- `src/core/persistence/memory-mutations.ts`: `forget` and `forget_fact` let the owner speaking for itself through for a private fact off every member and scope page, on a page no remote writer is kept from, and mark the stored request. The refusal that names the brain host now tells the owner what its credential does withdraw.
-- `src/core/persistence/forget-prepare.ts`, `src/core/persistence/page-visibility.ts`: preparation judges the owner again from the stored principal (`storedOwnerSpeaksForItself`). A writer that is no longer the enabled owner, or that named an actor, an audience, a subagent or a slug fence, reads the fact as any remote caller does and gets `not_found`.
+- `src/core/persistence/forget-prepare.ts`, `src/core/persistence/page-visibility.ts`: preparation judges the owner again from the stored principal (`storedOwnerSpeaksForItself`), and once more under the publication's locks. A writer that is no longer the enabled owner, or that named an actor, an audience, a subagent or a slug fence, reads the fact as any remote caller does and gets `not_found`.
- Guards kept: the same claim active on a page kept from remote writers refuses `claim_linked` and withdraws nothing; a more trusted fact files the `forget_requires_owner` proposal, which stores the fact's id and tier only.
- Docs: access designations, `MEMORY_VERBS_v1.md`, the access key-files entry; behavior-change notice.
- Tests: `test/owner-facts-d1-gst2346.test.ts` (the owner's forget and forget_fact, every other caller shape unchanged, the trust proposal and its accept, preparation from the stored principal, the managed-brain file) and `test/remember-strict-held-gst2492.test.ts` (a held private fact on a strict source, with a rebuild); PGLite and Postgres.
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 4e731c5dda..2f7913fd9f 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1545,7 +1545,7 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.685.0', id: 'strict_held_facts_gst2492', text: 'On a source whose pages are canonical in Git (`canonical: git`), a `remember` whose `entity` slug has no page no longer stores the fact in the database alone, where a rebuild from Git would lose it: it is committed as a row of `memory/unattributed` with a new `entity` column naming the entity, and the reply reads `page: memory/unattributed`, `persistence.mode: filesystem` and `write_through: {written: true, held_for: <entity>}`. Once the entity has a page, the extract_facts maintenance phase moves the row into it in one commit (same fact id) and strikes the held row (a restricted page\'s held row is removed); forget and replaces strike it too, and `purge_fact` removes it from `memory/unattributed`. An entity under a folder access rule is not held. A gbrain older than this one cannot read a `memory/unattributed` file that carries the `entity` column: it holds the file as a malformed fence, so upgrade every host of a strict source together. Other sources and brains with no Git repository are unchanged.' },
{ since: '0.60.685.0', id: 'remember_pageless_reply_gst2446', text: 'A `remember` whose `entity` slug has no page still saves to the database, and its reply now says so: it no longer carries `page` (it used to name the entity slug, a page that does not exist), and where the source has a checkout `write_through.skipped` reads `entity_page_missing` instead of `no_repo_configured`, in the reply and in the write receipt. Each `items` entry of a batch now carries `persistence` and `write_through`, as the single form does. Where the source\'s pages are in Git, the reply adds one `entity_page_missing` notice with the `put_page` call that creates the page. What is stored is unchanged.' },
{ since: '0.60.685.0', id: 'owner_facts_shared_gst2346', text: 'A credential bound to the brain owner (`gbrain access owner set`), or a stdio server started with `--stdio-member <owner>`, speaking for itself, now saves `remember` facts the way a credential bound to no member does: with no `visibility`, a fact is shared on its subject\'s page and every reader of the source recalls it, where it used to be kept private on the owner\'s member page. It stays private on that page when the call passes `visibility: "private"` or the subject\'s page or `facts.default_visibility` keeps facts private, and the reply names the `page` and `visibility` either way. Its `visibility: "world"` is saved instead of refused (`member_share_required`), except onto a page whose facts are kept private (`share_target_restricted`, as `share: true`), and its `forget` withdraws a shared fact it reads instead of saying only the brain host can. An owner agent that follows a planted instruction can therefore share a fact without passing any flag; to keep a fact private, pass `visibility: "private"`. Member credentials, attested QM calls (`x-qm-actor`), audiences (`X-Gbrain-On-Behalf-Of`), subagent jobs and slug-fenced clients are unchanged, and with writeback on the owner\'s credential is no longer told its saves stay private.' },
- { since: 'TBD', id: 'owner_forget_private_gst2346', text: 'A credential bound to the brain owner (`gbrain access owner set`), speaking for itself, now withdraws with `forget` or `forget_fact` a private fact it reads on a page its credential can write (one the brain host saved with `visibility: "private"`), where it used to be told only the brain host could. A fact on a `visibility: private` page, on a page that names readers or on another member\'s page is still withdrawn on the brain host, and a fact the owner confirmed or curated still files a `forget_requires_owner` proposal. Member credentials, attested QM calls (`x-qm-actor`), audiences (`X-Gbrain-On-Behalf-Of`), subagent jobs, slug-fenced clients and unbound connections are unchanged.' },
+ { since: 'TBD', id: 'owner_forget_private_gst2346', text: 'A credential bound to the brain owner (`gbrain access owner set`), or a stdio server started with `--stdio-member <owner>`, speaking for itself, now withdraws with `forget` or `forget_fact` a private fact it reads on a page its credential can write (one the brain host saved with `visibility: "private"`), where it used to be told only the brain host could. A fact on a `visibility: private` page, on a page that names readers or on another member\'s page is still withdrawn on the brain host, and a fact the owner confirmed or curated still files a `forget_requires_owner` proposal. Member credentials, attested QM calls (`x-qm-actor`), audiences (`X-Gbrain-On-Behalf-Of`), subagent jobs, slug-fenced clients and unbound connections are unchanged.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/persistence/forget-prepare.ts b/src/core/persistence/forget-prepare.ts
index 937a314501..31cc43dec9 100644
--- a/src/core/persistence/forget-prepare.ts
+++ b/src/core/persistence/forget-prepare.ts
@@ -169,7 +169,7 @@ export async function prepareForgetMutation(engine: BrainEngine, row: WriteReque
validate: async tx => {
// Under the publication's locks: the fact is still visible, no more trusted than a remote caller, and reaches no other copy.
const current = await readForgetTarget(tx, id, sourceId, worldOnly, excludePrivate, true, ownPage);
- if (!current) throw missing();
+ if (!current || (ownerReach && !await storedOwnerSpeaksForItself(tx, row.authority))) throw missing();
if (remote && supersessionGuarded('agent_written', current.trust_tier)) throw remoteForgetRaced(id);
if (!ownPage) await refuseForgetReachingOtherCopies(tx, sourceId, current, worldOnly, excludePrivate);
await held?.validate?.(tx);
diff --git a/src/core/persistence/memory-mutations.ts b/src/core/persistence/memory-mutations.ts
index 306930e6f0..3f5355ea30 100644
--- a/src/core/persistence/memory-mutations.ts
+++ b/src/core/persistence/memory-mutations.ts
@@ -430,7 +430,9 @@ export async function submitForgetMutation(ctx: OperationContext, operation: 'fo
if (!ownPage) await refuseForgetReachingOtherCopies(ctx.engine, sourceId, fact, worldOnly, hidePrivate);
const slug = fact.source_markdown_slug ?? fact.entity_slug ?? UNATTRIBUTED_MEMORY_SLUG;
enforceClientSlugFence(ctx, slug, operation); enforceSubagentSlugFence(ctx, slug, operation);
- const authority = await submissionAuthority(ctx, operation, sourceId, source.incarnation, slug);
+ // A page the fact is about that turned private since is one this credential may not write: the brain host withdraws that fact.
+ const authority = await submissionAuthority(ctx, operation, sourceId, source.incarnation, slug)
+ .catch((error: unknown) => { throw ownerReach && error instanceof OperationError && error.code === 'page_not_found' ? hostWithdraws() : error; });
if (ownerReach && !await storedOwnerSpeaksForItself(ctx.engine, authority)) throw hostWithdraws();
const snapshot = await ctx.engine.readPageSnapshot(slug, { sourceId, includeDeleted: true });
const sandbox = ctx.viaSubagent === true && !(ctx.allowedSlugPrefixes?.length);
diff --git a/test/owner-facts-d1-gst2346.test.ts b/test/owner-facts-d1-gst2346.test.ts
index e026e90907..22bbcd1069 100644
--- a/test/owner-facts-d1-gst2346.test.ts
+++ b/test/owner-facts-d1-gst2346.test.ts
@@ -344,10 +344,11 @@ for (const kind of testBackends()) {
test("preparation judges the owner again from the stored principal: a stored request from any other writer reads the fact as not found", async () => {
const id = await hostFact('Acme host kept a dated note canaryhostprepare');
const [page] = await engine.executeRaw<{ id: number }>('SELECT id FROM pages WHERE source_id=$1 AND slug=$2', [SRC, ACME]);
- const prepare = async (who: string, authority: Record<string, unknown> = {}, intent: Record<string, unknown> = { owner_reach: true }) => prepareForgetMutation(engine, {
+ const stored = async (who: string, authority: Record<string, unknown> = {}, intent: Record<string, unknown> = { owner_reach: true }) => ({
operation: 'forget', id: randomUUID(), request_id: randomUUID(), source_id: SRC, slug: ACME, page_id: page!.id, worktree_id: null, intent: { id, ...intent },
authority: { version: 1, remote: true, principal: (await h.auth(who) as unknown as { principal: unknown }).principal, sourceId: SRC, slugPrefixes: null, ...authority },
- } as never, {} as never).then(() => 'prepared', (error: { code?: string }) => error.code);
+ }) as never;
+ const prepare = async (...row: Parameters<typeof stored>) => prepareForgetMutation(engine, await stored(...row), {} as never).then(() => 'prepared', (error: { code?: string }) => error.code);
expect(await prepare('owner')).toBe('prepared');
expect(await prepare('owner', {}, {})).toBe('not_found');
expect(await prepare('alice')).toBe('not_found');
@@ -355,14 +356,52 @@ for (const kind of testBackends()) {
expect(await prepare('owner', { actingFor: ['member:' + OWNER] })).toBe('not_found');
expect(await prepare('owner', { restrictedNamespace: true })).toBe('not_found');
expect(await prepare('owner', { slugPrefixes: ['companies/'] })).toBe('not_found');
+ // A request prepared while its writer was the owner is judged once more under the publication's locks.
+ const prepared = await prepareForgetMutation(engine, await stored('owner'), {} as never);
+ await prepared.validate!(engine);
await setOwner(engine, 'bob-example');
try {
expect(await prepare('owner')).toBe('not_found');
expect(await prepare('bob')).toBe('prepared');
+ await expect(prepared.validate!(engine)).rejects.toMatchObject({ code: 'not_found' });
} finally { await setOwner(engine, OWNER); __resetPrivateVisibilityCacheForTests(); }
expect((await h.row('canaryhostprepare'))!.active).toBe(true);
}, 120_000);
+ test("a stdio server bound to the owner withdraws a host-written private fact the same way; one bound to a member does not", async () => {
+ const stdio = async (id: string, stdioMember: string) => {
+ const out = await dispatchToolCall(engine, 'forget', { id }, { remote: true, transport: 'stdio', sourceId: SRC, takesHoldersAllowList: ['world'], stdioMember });
+ let json: Record<string, any> = {};
+ try { json = JSON.parse(out.content[0]?.text ?? ''); } catch { /* prose */ }
+ return { isError: out.isError === true, json };
+ };
+ const id = await hostFact('Acme host kept a stdio note canaryhoststdio');
+ expect((await stdio(id, 'alice-example')).json.error).toBe('not_found');
+ expect((await h.row('canaryhoststdio'))!.active).toBe(true);
+ const out = await stdio(id, OWNER);
+ expect(out.isError ? JSON.stringify(out.json) : 'ok').toBe('ok');
+ expect((await h.row('canaryhoststdio'))!.active).toBe(false);
+ }, 120_000);
+
+ test("the owner's forget never reaches a copy its credential cannot write: another member's copy, a page that turned private, a page that names readers", async () => {
+ const active = async (canary: string) => (await engine.executeRaw<{ active: boolean }>('SELECT expired_at IS NULL AS active FROM facts WHERE fact LIKE $1 ORDER BY id', ['%' + canary + '%'])).map(r => r.active);
+ // Another member holds the same private claim about the same entity: the withdrawal would cover it, so nothing is withdrawn.
+ await h.remember('alice', 'Acme pays a quiet bonus canaryhostcopy');
+ const copy = await h.call('owner', 'forget', { id: await hostFact('Acme pays a quiet bonus canaryhostcopy') });
+ expect([copy.isError, copy.text.includes('claim_linked'), copy.text.includes('canaryhostcopy')]).toEqual([true, true, false]);
+ expect(await active('canaryhostcopy')).toEqual([true, true]);
+ // The fact's page was made private after the host saved it: the refusal names the brain host, as for any page kept from remote writers.
+ const hooli = await hostFact('Hooli runs a quiet lab canaryhostturned', { entity: 'companies/hooli-example' });
+ await importFromContent(engine, 'companies/hooli-example', '---\ntype: company\ntitle: Hooli Example\nvisibility: private\n---\n# Hooli Example\n\nHooli example.', { sourceId: SRC });
+ const turned = await h.call('owner', 'forget', { id: hooli });
+ expect([turned.isError, turned.json.error, turned.text.includes('brain host')]).toEqual([true, 'scope_denied', true]);
+ expect(await active('canaryhostturned')).toEqual([true]);
+ // A page that names the owner as a reader: a write does not use the owner's read rule for such pages, so forget answers not_found.
+ const globex = await h.call('owner', 'forget', { id: await hostFact('Globex pilot is quiet canaryhostglobex', { entity: GLOBEX }) });
+ expect([globex.isError, globex.json.error]).toEqual([true, 'not_found']);
+ expect(await active('canaryhostglobex')).toEqual([true]);
+ }, 120_000);
+
test("an unbound connection never reads or withdraws the owner's private fact", async () => {
const kept = await h.remember('owner', 'Acme private owner note canaryunboundhidden', { visibility: 'private' });
expect((await h.call('plain', 'recall', { entity: ACME })).text).not.toContain('canaryunboundhidden');