Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

QM can read a room's context pack as its audience, and the owner sets attest_read over HTTP (GST-2407)

garrytand31a658f4bdd
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 927b2836bc..f88af9d380 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,17 @@ credits are retained; no result has been reassigned to another provider. Origina
identifiers and attribution are available in the pre-removal Git revision
`6040075c6cb95be5881cc2e1b76ef7d71f4e5d29` (retained on 2026-09-23).
+## [Unreleased]
+
+### QM can read a room's context pack, and the owner sets how a client reads named sources from another machine
+
+**context_pack reads a room as its audience.** A QM client that reads named sources as the scope used to be refused when it asked `context_pack` for a room's source, so QM had no session brief in shared conversations. Now a call that names `source_id` reads only that source: its entities and `entity_refs`, the core block, the counterparty brief and hot facts. Nothing from the person's own member page or from pages kept to named readers comes back, and privacy is never relaxed.
+- A scope call is refused with `invalid_params` before anything is read when it sends `entity_refs` without `source_id`, names an `entity_refs` entry in another source, or sends `session_id` (a session's thread rows are the person's).
+- A client set `--attest-read person` keeps reading as the person.
+- Contract `docs/contracts/qm-memory-provider/v5.json` marks `context_pack` `scope_read: true`. v1 to v4 stay byte for byte as published, and v4's markings are frozen in the builder.
+
+**`gbrain mcp admin attest <client> --attest-read person|scope|none`** sets the same `attest_read` that `gbrain auth rescope --attest-read` sets, over the owner session (`attestRead` on `/admin/api/access/attest`). It refuses what the local command refuses, previews with `--dry-run`, and logs `attest_read` in the `access_admin` row.
+
## [0.60.699.0] - 2026-11-12
### The Ubicloud gate VMs run a current git
diff --git a/docs/architecture/key-files/access.md b/docs/architecture/key-files/access.md
index 1c7cb22888..de5ac31701 100644
--- a/docs/architecture/key-files/access.md
+++ b/docs/architecture/key-files/access.md
@@ -3,9 +3,9 @@
[Subsystem index](../KEY_FILES.md). Read only the entries relevant to your change.
Current behavior and load-bearing invariants; history belongs in Git and CHANGELOG.
-- `src/core/access/` (GBRA-218) — per-member read access inside one source. `principals.ts` normalizes frontmatter `readable_by` (bare id = `member:<id>`, `group:<g>`, ASCII case fold, space trim; anything malformed is `['!nobody']`); it is the row twin of the SQL `gbrain_access_readers()` (`test/access-principals.test.ts` holds them equal). A BEFORE trigger keeps `pages.page_readers` equal to that function (direct writes to the column are recomputed), and predicates test the array, never the function, which costs ~0.2 ms per row. A page that names readers with no derived value yet (written before the migration) reads as nobody until `gbrain repair access` (`repair/access.ts`). `members.ts` (members, groups, tombstoned ids never reused, bindings), `token-binding.ts` (the verifiers' join; a credential bound to a disabled, tombstoned or missing member is refused with `access_member_disabled`) and `caller.ts` (`remoteCallerAccess`: the identity dispatch puts on the caller-access record; stdio binds through `serve --stdio-member`, else `mcp.stdio_member`; publication re-resolves from the stored principal). In `search/private-visibility.ts` every page fragment is `accessAllowedSql` AND the privacy part: plain fragments use the empty identity (over-hide, never leak), `*ForCaller` fragments the caller's, and `GBRAIN_REMOTE_PRIVATE_PAGES`, `search.remote_private_pages` and `granted_sources` relax only the privacy part (`privacyForCaller`). GST-2490: an owner read (`CallerAccess.lineage` with `owner`, read-only ops only) uses `lineageAccessSql`: the owner's readers and folder rules as for any member, with `gbrain_access_origin_hidden_for()` (v304; per origin `gbrain_access_origin_closed_for()`) in place of the every-caller lineage, so a derivative or fact passes when the owner reads every origin; `ownerReadsRestricted` (config `access.owner_reads_restricted`, `owner.ts` `setOwnerReadsRestricted`, local only) also passes pages kept to other members except another member's own member page and pending coverage. `access check`, `who-can-read`, `whoami` (`ownerReadsRestrictedNotice`) and doctor `access_owner_reads_restricted` report it; test `test/owner-reads-restricted.test.ts` (both engines, database and access.yml rules). GBRA-108 (migration v305, `v305-access-lineage-designs.ts`): `access_rules.covers_derived` (default true) — a raw-only rule (`folder-rules.ts` `covers_derived: false`, `rule add --raw-only`; digest unchanged for covering rules; true→false is the held widening `derived_released`, false→true the narrowing `derived_covered`) is dropped from an origin's rule set by the SQL function `gbrain_access_lineage_rules()` inside `gbrain_access_origin_restricted()` and the 10-argument `gbrain_access_origin_closed_for()`, so it keeps its pages but not their lineage (a page's own readers still close it; fact provenance filters judge with `derived = true`). `access_members.kind` (`person` | `audience`, `members.ts` `setMemberKind`, local only): an owner read carries `CallerAccess.audienceKindMembers`, whose member pages pass the readers test and the member-page exemptions (`audiencePages`, `notOtherMemberPageSql`, the `p_audience_pages` argument of the 9-argument `gbrain_access_origin_hidden_for()`). Config `access.members_read_lineage` (`lineage.ts`, local only) sets `CallerAccess.lineage` for any member read speaking for itself (`caller.ts`; never an audience of several or an unbound credential; `withCallerAccess` drops it for several identities and keeps the owner opt-in and audience members owner-only). Cache keys: `knobsHash` `xol=3` and `xak=`, `callerIdentityKey` `owner_reads`/`audience_kind`. Doctor `access_lineage` (`checks/access-lineage.ts`). Tests: `test/access-raw-only-rules.test.ts`, `test/access-audience-members.test.ts`, `test/access-members-read-lineage.test.ts` (both engines, both stores; fixture `test/helpers/access-lineage-fixture.ts`). A derivative of a page that names readers is otherwise hidden from every remote caller (`originAllowedSql`, which calls the SQL function `gbrain_access_origin_restricted()` only for atom, question, concept, event or `derived_from` rows, so each read plans one call instead of four subplans). Both parts lead with column tests (`page_readers IS NULL`, `type`) so row estimates follow column statistics; an expression test such as `->'readable_by' IS NULL` estimates almost no rows and sent restricted vector searches into nested-loop sequential scans. The index walk's page probe (`INDEX_WALK_PAGE_COLUMNS`) projects `page_readers`. Config `access.restrictions_present` (set by a trigger, sticky) keeps every pre-A1 path on a brain with no restriction. `check:remote-privacy-reads` keeps the two relaxations read only in `private-visibility.ts`. Tests: `test/member-read-access.test.ts` (remote matrix, both engines), `test/access-*.test.ts`. Folder rules (A2) keep whole folders of a source to named members. `folder-rules.ts` is the grammar (`.gbrain/access.yml`: `rules:` of `id`, `prefix`, `readable_by`), `classifyRulebook` (each change is narrowing or widening; the target installs only the narrowing part) and `matchingRuleIds`. `policy.ts` owns the one applied rulebook for both stores: `access_rules` (source-qualified ids), the append-only `access_policy_revisions` log, `access_pending_coverage` (prefixes that read as nobody while a narrowing restamps, or while a committed file is invalid) and `sources.config.access_store`, persisted at the first rule and changed only by `policy-migrate.ts` (journaled in `access_policy_migrations`). `proposeRevision` installs narrowing at once under a per-source row lock and holds widening for `applyApproved` (`plan_hash`, `preview_changed`); `restampSource` rewrites `pages.folder_rule_ids` in id windows, then clears pending coverage under the lock; re-proposing the same rulebook finishes an interrupted restamp. A trigger stamps `folder_rule_ids` from the SQL function `gbrain_access_folder_rules()` on insert and on slug or source change, never from git on the serve path. `policy-git.ts` is the git store (files committed through the commit door, applied by `syncAccessPolicyAt` from sync preflight and before and after every managed pass (`performManagedSync`: sync, drain, `sources refresh`, git conversion), read with `git show` at the synced commit (GST-2331: every read under `HARDENED_GIT_ARGS` and `NO_LAZY_FETCH_ENV`, so a partial clone fetches nothing; a policy file the commit names that the clone lacks, or a history the replay cannot read, makes the source read as nobody until the objects are fetched: the problem names the exact `git cat-file -p` or `git log --first-parent -p` that fetches them, and the next sync applies the rules and clears the mark); a database with no revision yet replays each committed `access.yml` since the `access.approved` baseline, so a rebuild holds a removal a plain commit made); `policy-transfer.ts` carries the applied rulebook through `gbrain export` and installs it before any page in `gbrain import`; `policy-notice.ts` is the `access_policy_pending` degraded notice. In `private-visibility.ts`, `folderRulesAllowedSql` sits inside `accessAllowedSql` (`folder_rule_ids IS NULL OR folder_rule_ids <@ <satisfied ids>` plus coverage conjuncts), so no hatch, grant or `--as` relaxes it, and the unrestricted short form tests `folder_rule_ids IS NULL` next to `page_readers IS NULL` (v283 triggers set `access.restrictions_present` on the first rule or pending prefix); `caller.ts`'s `folderAccessFor` fails closed to whole-source coverage. CLI: `src/commands/access-rules.ts`; doctor: `src/commands/doctor/checks/folder-access.ts`. Tests: `test/access-folder-rules.test.ts` (database store, both engines), `test/access-folder-rules-git.test.ts`, `test/access-folder-transfer.test.ts`, `test/access-folder-doctor.test.ts`. Shared agents (B, GBRA-231): `audience.ts` parses the audience a harness asserts (`X-Gbrain-On-Behalf-Of` or request-level `_meta.on_behalf_of`, 1-50 principals, `guest` = the empty identity; the same key inside tool arguments is refused) and appends each assertion to `access-audience-YYYY-Www.jsonl`. Dispatch resolves it on every remote call through `caller.ts` (`resolveAudienceIdentities`: every entry must be in the credential's live `may_act_for`, then name an enabled member or existing group); the caller-access record then carries `audienceIdentities`, and `accessAllowedForAllSql` needs one readers conjunct per identity, folder rules the intersection of each entry's satisfied set (`folderAccessForAll`). Privacy relaxes only for a one-member audience. Writes carry the audience as `WriteAuthority.actingFor` (re-resolved at publication) and agent jobs as `grant.actingFor`. Every remote response carries `_meta.access` (`appliedAccessSummary`), which `whoami` returns as `access.applied`; doctor `access_may_act_for_wildcard` (`checks/shared-agent-access.ts`) warns on `*`. Tests: `test/access-on-behalf-of.test.ts` (both engines), `test/e2e/serve-http-on-behalf-of.test.ts`. Attested actor (C1, GST-359): `actor-model.ts` (dependency-free: `x-qm-actor`, `acting_user`, `EXTERNAL_ID_RE` = 1-256 visible ASCII, `attestRightFrom`: the right counts only for a member-less credential whose token is legacy or `client_credentials`, read from `oauth_tokens.grant_type`) and `actor.ts`. `resolveAttestedActor` runs in dispatch before any work: an invalid id refuses `actor_not_attested` (`invalid_actor_id`) before any lookup, then the right, the op list (`attest_ops`, default `get_write_request,memory_recall,memory_write`), `acting_user` = header (stripped), and `actorCoverage` (the one coverage test: live right plus a live link in `access_member_links` to an enabled member, compared exactly) or `actor_unlinked`. GST-1158: `scope-read.ts` holds `SCOPE_READ_ACCESS` (no identity, actor or audience; privacy never relaxed) and `SCOPE_READ_OPS`; dispatch runs an attested call to one of those ops that names `source_id`/`source_ids` under that record (`attestedReadMode`, which refuses `__all__`/`all_sources`), or as the person when the right's `attest_read` (v298, `--attest-read`) is `person`, and handlers read the mode with `currentReadMode`. `attest_read = 'scope'` refuses a call that names no actor (`actor_required`). Tests: `test/qm-scope-read.test.ts` (both engines), `test/doctor-attest-read-shared-scope.test.ts`. GBRA-284: `member-sources.ts` binds a source to its member (`access_member_sources`, v299; `gbrain access member source add|remove|list`); `attestedReadScope`, called in dispatch for every attested call and in `minions/tools/brain-allowlist.ts` for an attested job's tool calls, replaces the call's read grant with the grant minus personal sources bound to another member (every personal source under a scope read), so every resolver refuses or skips them like out-of-grant sources and nothing is added. Test: `test/qm-personal-sources.test.ts` (both engines). `ACTOR_DEFERRED_OPS` (`capture`, `extract_facts`, take writes, `list_write_conflicts`, and since GST-2249 W1 every page write; `test/qm-attest-write-boundary.test.ts` classifies every attestable mutating operation) are never attestable: refused by `parseAttestOps`, `bindCredential`, every call and the stored re-check, which also re-checks `attest_ops` for a queued write's operation and each job tool call. Under the header serve-http lists only attested tools and refuses `resources/read`. `attestedCallerAccess` is a one-member audience with privacy never relaxed (no granted sources, no hatch), never B's `may_act_for` path. Writes store `WriteAuthority.actingFor = {system, external_id, member}` and jobs `grant.actor`; `storedActorIdentity` re-resolves both through `actorCoverage` and refuses when the member changed. `linkMember` / `unlinkMember` / `listMemberLinks` back `gbrain access member link|unlink|links`; `linkMemberByEmail` (GST-1158) finds the member by its declared email (`members.ts` `memberByEmail`: `access_members.email`, migration v301, case-folded, unique, cleared on removal; `not_found` when none, `email_ambiguous` when several) and then links exactly as `linkMember`, from the local CLI and the owner-session routes in `src/commands/serve-http-access.ts` only; `--attest-actor` / `--attest-ops` on `auth rescope` (`members.ts`) only for a member-less legacy token or confidential client-credentials client. Migration v286. Tests: `test/access-qm-actor.test.ts` (both engines), `test/e2e/serve-http-qm-actor.test.ts`. Member facts (C2, GST-359): `member-facts.ts`. A remote `remember` from an attested actor or a lone-member credential (`callerMember`, never an audience of several) writes to `memory/members/<member>` (`memberFactPage`; `persistence/memory-prepare.ts` creates the page with `readable_by: [member:<id>]`), `visibility: private`, `infer_entity` off, the entity kept as `entity_slug`, unless the call passes `share: true` (GST-2243), which takes the ordinary world route to the subject's page; a member's explicit `visibility: "world"` is refused in `remember`'s validation (`member_share_required`), so a batch with one such item saves nothing. GST-2346 D1: the owner speaking for itself (`ownerSpeaksForItself`: `CallerAccess.owner`, no actor or audience, no subagent, no slug fence) takes the world route unless it passes `visibility: "private"` or the page or `facts.default_visibility` makes the default private (then its member page), is never refused `member_share_required`, and its `forget` of a fact off its member page takes the ordinary remote path when that path reads the fact. A fact off every member and scope page, on a page the owner reads under the GST-2490 rule with the opt-in off (`ownerReadPolicyFragment`) and may write as a member, a page whose readers name it included, with the fact's entity page judged the same way (`ownerReachesFact`, `forget-prepare.ts`), is withdrawn too: submission marks the request `owner_reach`, and preparation judges the owner again from the stored authority (`storedOwnerSpeaksForItself`, `page-visibility.ts`), so a writer that is no longer the owner gets `not_found`; a more trusted fact files the `forget_requires_owner` proposal. A member id whose page slug `slugifyPath` would change (`a--b`, `zed-`) is refused (`invalid_params`). The page must name that member alone (`memberPageIsOwn`, checked at submission and again in preparation, `memberPageNotOwned`), and remote writes under `memory/members/` go only to the caller's own page (`assertMemberPageWriter`, called from `ops/context.ts` `enforceClientSlugFence`, so every remote page write passes it; trusted local callers are unaffected). Reads widen a world-only fact list only by `memberFactAdmitSql` (a private fact on the caller's own live member page whose readers and folder rules admit the caller; `factVisibilitySql` in `engine-sql/facts.ts` and `search/fact-relevance.ts`), and `privateProvenanceFilterUnderPolicy` judges a member-page fact's source page as the caller (every other fact keeps the empty identity, so a fact from a page that names readers stays hidden from every remote caller). Writers never cross pages: `facts/single-prepare.ts` (`SingleFactIntent.page_slug`) and `trust/supersede-handlers.ts` dedup, supersede and contest only within the member page, and no other write matches a fact there (`onMemberPageSql`); a remote save there meets only the page's own withdrawals and those of a claim its member reads (`memberPageWithdrawal`), and the insert guards mark a member-page row only by its page's own withdrawals (`schema-migrations/*-member-page-withdrawal-scope.ts`), so a claim the member never read cannot refuse or expire its save; consolidation skips facts whose page names readers (`readersSourcedFactSql`). Per-person keys: `callerIdentityKey` joins the hot-memory cache key (`facts/meta-hook.ts`, `::xid=`), `callerSessionKey` the `delta` cursor (`ops/facts.ts`), `sameAttestedActor` gates receipts (`persistence/authority.ts` `ownRequestAccessible`) and replays (`persistence/journal.ts`) on the stored actor, else the stored audience, and `get_agent_job` and the owner-fenced `get_job`, `wait_job`, `get_job_progress`, `list_jobs` and `cancel_job` match the job's `grant.actor` (system, external id, member) and `grant.actingFor` (the same distinct audience entries; `jobActorSql` in `minions/types.ts`), so a job or receipt with an actor or audience reads as missing to the bare client and to other actors and audiences, and one with neither to every actor and audience. Tests: `test/access-member-facts.test.ts` (both engines), `test/access-member-sweep.test.ts` (every attestable op as Bob, the bare client and an unbound credential; `test/helpers/member-sweep.ts`), `test/e2e/serve-http-member-sweep.test.ts` (two members over a real `serve --http` on a keyless repo-less brain).
+- `src/core/access/` (GBRA-218) — per-member read access inside one source. `principals.ts` normalizes frontmatter `readable_by` (bare id = `member:<id>`, `group:<g>`, ASCII case fold, space trim; anything malformed is `['!nobody']`); it is the row twin of the SQL `gbrain_access_readers()` (`test/access-principals.test.ts` holds them equal). A BEFORE trigger keeps `pages.page_readers` equal to that function (direct writes to the column are recomputed), and predicates test the array, never the function, which costs ~0.2 ms per row. A page that names readers with no derived value yet (written before the migration) reads as nobody until `gbrain repair access` (`repair/access.ts`). `members.ts` (members, groups, tombstoned ids never reused, bindings), `token-binding.ts` (the verifiers' join; a credential bound to a disabled, tombstoned or missing member is refused with `access_member_disabled`) and `caller.ts` (`remoteCallerAccess`: the identity dispatch puts on the caller-access record; stdio binds through `serve --stdio-member`, else `mcp.stdio_member`; publication re-resolves from the stored principal). In `search/private-visibility.ts` every page fragment is `accessAllowedSql` AND the privacy part: plain fragments use the empty identity (over-hide, never leak), `*ForCaller` fragments the caller's, and `GBRAIN_REMOTE_PRIVATE_PAGES`, `search.remote_private_pages` and `granted_sources` relax only the privacy part (`privacyForCaller`). GST-2490: an owner read (`CallerAccess.lineage` with `owner`, read-only ops only) uses `lineageAccessSql`: the owner's readers and folder rules as for any member, with `gbrain_access_origin_hidden_for()` (v304; per origin `gbrain_access_origin_closed_for()`) in place of the every-caller lineage, so a derivative or fact passes when the owner reads every origin; `ownerReadsRestricted` (config `access.owner_reads_restricted`, `owner.ts` `setOwnerReadsRestricted`, local only) also passes pages kept to other members except another member's own member page and pending coverage. `access check`, `who-can-read`, `whoami` (`ownerReadsRestrictedNotice`) and doctor `access_owner_reads_restricted` report it; test `test/owner-reads-restricted.test.ts` (both engines, database and access.yml rules). GBRA-108 (migration v305, `v305-access-lineage-designs.ts`): `access_rules.covers_derived` (default true) — a raw-only rule (`folder-rules.ts` `covers_derived: false`, `rule add --raw-only`; digest unchanged for covering rules; true→false is the held widening `derived_released`, false→true the narrowing `derived_covered`) is dropped from an origin's rule set by the SQL function `gbrain_access_lineage_rules()` inside `gbrain_access_origin_restricted()` and the 10-argument `gbrain_access_origin_closed_for()`, so it keeps its pages but not their lineage (a page's own readers still close it; fact provenance filters judge with `derived = true`). `access_members.kind` (`person` | `audience`, `members.ts` `setMemberKind`, local only): an owner read carries `CallerAccess.audienceKindMembers`, whose member pages pass the readers test and the member-page exemptions (`audiencePages`, `notOtherMemberPageSql`, the `p_audience_pages` argument of the 9-argument `gbrain_access_origin_hidden_for()`). Config `access.members_read_lineage` (`lineage.ts`, local only) sets `CallerAccess.lineage` for any member read speaking for itself (`caller.ts`; never an audience of several or an unbound credential; `withCallerAccess` drops it for several identities and keeps the owner opt-in and audience members owner-only). Cache keys: `knobsHash` `xol=3` and `xak=`, `callerIdentityKey` `owner_reads`/`audience_kind`. Doctor `access_lineage` (`checks/access-lineage.ts`). Tests: `test/access-raw-only-rules.test.ts`, `test/access-audience-members.test.ts`, `test/access-members-read-lineage.test.ts` (both engines, both stores; fixture `test/helpers/access-lineage-fixture.ts`). A derivative of a page that names readers is otherwise hidden from every remote caller (`originAllowedSql`, which calls the SQL function `gbrain_access_origin_restricted()` only for atom, question, concept, event or `derived_from` rows, so each read plans one call instead of four subplans). Both parts lead with column tests (`page_readers IS NULL`, `type`) so row estimates follow column statistics; an expression test such as `->'readable_by' IS NULL` estimates almost no rows and sent restricted vector searches into nested-loop sequential scans. The index walk's page probe (`INDEX_WALK_PAGE_COLUMNS`) projects `page_readers`. Config `access.restrictions_present` (set by a trigger, sticky) keeps every pre-A1 path on a brain with no restriction. `check:remote-privacy-reads` keeps the two relaxations read only in `private-visibility.ts`. Tests: `test/member-read-access.test.ts` (remote matrix, both engines), `test/access-*.test.ts`. Folder rules (A2) keep whole folders of a source to named members. `folder-rules.ts` is the grammar (`.gbrain/access.yml`: `rules:` of `id`, `prefix`, `readable_by`), `classifyRulebook` (each change is narrowing or widening; the target installs only the narrowing part) and `matchingRuleIds`. `policy.ts` owns the one applied rulebook for both stores: `access_rules` (source-qualified ids), the append-only `access_policy_revisions` log, `access_pending_coverage` (prefixes that read as nobody while a narrowing restamps, or while a committed file is invalid) and `sources.config.access_store`, persisted at the first rule and changed only by `policy-migrate.ts` (journaled in `access_policy_migrations`). `proposeRevision` installs narrowing at once under a per-source row lock and holds widening for `applyApproved` (`plan_hash`, `preview_changed`); `restampSource` rewrites `pages.folder_rule_ids` in id windows, then clears pending coverage under the lock; re-proposing the same rulebook finishes an interrupted restamp. A trigger stamps `folder_rule_ids` from the SQL function `gbrain_access_folder_rules()` on insert and on slug or source change, never from git on the serve path. `policy-git.ts` is the git store (files committed through the commit door, applied by `syncAccessPolicyAt` from sync preflight and before and after every managed pass (`performManagedSync`: sync, drain, `sources refresh`, git conversion), read with `git show` at the synced commit (GST-2331: every read under `HARDENED_GIT_ARGS` and `NO_LAZY_FETCH_ENV`, so a partial clone fetches nothing; a policy file the commit names that the clone lacks, or a history the replay cannot read, makes the source read as nobody until the objects are fetched: the problem names the exact `git cat-file -p` or `git log --first-parent -p` that fetches them, and the next sync applies the rules and clears the mark); a database with no revision yet replays each committed `access.yml` since the `access.approved` baseline, so a rebuild holds a removal a plain commit made); `policy-transfer.ts` carries the applied rulebook through `gbrain export` and installs it before any page in `gbrain import`; `policy-notice.ts` is the `access_policy_pending` degraded notice. In `private-visibility.ts`, `folderRulesAllowedSql` sits inside `accessAllowedSql` (`folder_rule_ids IS NULL OR folder_rule_ids <@ <satisfied ids>` plus coverage conjuncts), so no hatch, grant or `--as` relaxes it, and the unrestricted short form tests `folder_rule_ids IS NULL` next to `page_readers IS NULL` (v283 triggers set `access.restrictions_present` on the first rule or pending prefix); `caller.ts`'s `folderAccessFor` fails closed to whole-source coverage. CLI: `src/commands/access-rules.ts`; doctor: `src/commands/doctor/checks/folder-access.ts`. Tests: `test/access-folder-rules.test.ts` (database store, both engines), `test/access-folder-rules-git.test.ts`, `test/access-folder-transfer.test.ts`, `test/access-folder-doctor.test.ts`. Shared agents (B, GBRA-231): `audience.ts` parses the audience a harness asserts (`X-Gbrain-On-Behalf-Of` or request-level `_meta.on_behalf_of`, 1-50 principals, `guest` = the empty identity; the same key inside tool arguments is refused) and appends each assertion to `access-audience-YYYY-Www.jsonl`. Dispatch resolves it on every remote call through `caller.ts` (`resolveAudienceIdentities`: every entry must be in the credential's live `may_act_for`, then name an enabled member or existing group); the caller-access record then carries `audienceIdentities`, and `accessAllowedForAllSql` needs one readers conjunct per identity, folder rules the intersection of each entry's satisfied set (`folderAccessForAll`). Privacy relaxes only for a one-member audience. Writes carry the audience as `WriteAuthority.actingFor` (re-resolved at publication) and agent jobs as `grant.actingFor`. Every remote response carries `_meta.access` (`appliedAccessSummary`), which `whoami` returns as `access.applied`; doctor `access_may_act_for_wildcard` (`checks/shared-agent-access.ts`) warns on `*`. Tests: `test/access-on-behalf-of.test.ts` (both engines), `test/e2e/serve-http-on-behalf-of.test.ts`. Attested actor (C1, GST-359): `actor-model.ts` (dependency-free: `x-qm-actor`, `acting_user`, `EXTERNAL_ID_RE` = 1-256 visible ASCII, `attestRightFrom`: the right counts only for a member-less credential whose token is legacy or `client_credentials`, read from `oauth_tokens.grant_type`) and `actor.ts`. `resolveAttestedActor` runs in dispatch before any work: an invalid id refuses `actor_not_attested` (`invalid_actor_id`) before any lookup, then the right, the op list (`attest_ops`, default `get_write_request,memory_recall,memory_write`), `acting_user` = header (stripped), and `actorCoverage` (the one coverage test: live right plus a live link in `access_member_links` to an enabled member, compared exactly) or `actor_unlinked`. GST-1158: `scope-read.ts` holds `SCOPE_READ_ACCESS` (no identity, actor or audience; privacy never relaxed) and `SCOPE_READ_OPS`; dispatch runs an attested call to one of those ops that names `source_id`/`source_ids` under that record (`attestedReadMode`, which refuses `__all__`/`all_sources`), or as the person when the right's `attest_read` (v298, `--attest-read`; over HTTP `attestRead` on `/admin/api/access/attest`) is `person`, and handlers read the mode with `currentReadMode`. GST-2407: `context_pack` is a scope read too: its `entity_refs` count as naming sources, `assertPackConfined` refuses before any read a scope call without `source_id`, with an `entity_refs` entry in another source or with `session_id`, and the handler reads the named source as home (core block, pull brief, hot facts). `attest_read = 'scope'` refuses a call that names no actor (`actor_required`). Tests: `test/qm-scope-read.test.ts` (both engines), `test/doctor-attest-read-shared-scope.test.ts`. GBRA-284: `member-sources.ts` binds a source to its member (`access_member_sources`, v299; `gbrain access member source add|remove|list`); `attestedReadScope`, called in dispatch for every attested call and in `minions/tools/brain-allowlist.ts` for an attested job's tool calls, replaces the call's read grant with the grant minus personal sources bound to another member (every personal source under a scope read), so every resolver refuses or skips them like out-of-grant sources and nothing is added. Test: `test/qm-personal-sources.test.ts` (both engines). `ACTOR_DEFERRED_OPS` (`capture`, `extract_facts`, take writes, `list_write_conflicts`, and since GST-2249 W1 every page write; `test/qm-attest-write-boundary.test.ts` classifies every attestable mutating operation) are never attestable: refused by `parseAttestOps`, `bindCredential`, every call and the stored re-check, which also re-checks `attest_ops` for a queued write's operation and each job tool call. Under the header serve-http lists only attested tools and refuses `resources/read`. `attestedCallerAccess` is a one-member audience with privacy never relaxed (no granted sources, no hatch), never B's `may_act_for` path. Writes store `WriteAuthority.actingFor = {system, external_id, member}` and jobs `grant.actor`; `storedActorIdentity` re-resolves both through `actorCoverage` and refuses when the member changed. `linkMember` / `unlinkMember` / `listMemberLinks` back `gbrain access member link|unlink|links`; `linkMemberByEmail` (GST-1158) finds the member by its declared email (`members.ts` `memberByEmail`: `access_members.email`, migration v301, case-folded, unique, cleared on removal; `not_found` when none, `email_ambiguous` when several) and then links exactly as `linkMember`, from the local CLI and the owner-session routes in `src/commands/serve-http-access.ts` only; `--attest-actor` / `--attest-ops` on `auth rescope` (`members.ts`) only for a member-less legacy token or confidential client-credentials client. Migration v286. Tests: `test/access-qm-actor.test.ts` (both engines), `test/e2e/serve-http-qm-actor.test.ts`. Member facts (C2, GST-359): `member-facts.ts`. A remote `remember` from an attested actor or a lone-member credential (`callerMember`, never an audience of several) writes to `memory/members/<member>` (`memberFactPage`; `persistence/memory-prepare.ts` creates the page with `readable_by: [member:<id>]`), `visibility: private`, `infer_entity` off, the entity kept as `entity_slug`, unless the call passes `share: true` (GST-2243), which takes the ordinary world route to the subject's page; a member's explicit `visibility: "world"` is refused in `remember`'s validation (`member_share_required`), so a batch with one such item saves nothing. GST-2346 D1: the owner speaking for itself (`ownerSpeaksForItself`: `CallerAccess.owner`, no actor or audience, no subagent, no slug fence) takes the world route unless it passes `visibility: "private"` or the page or `facts.default_visibility` makes the default private (then its member page), is never refused `member_share_required`, and its `forget` of a fact off its member page takes the ordinary remote path when that path reads the fact. A fact off every member and scope page, on a page the owner reads under the GST-2490 rule with the opt-in off (`ownerReadPolicyFragment`) and may write as a member, a page whose readers name it included, with the fact's entity page judged the same way (`ownerReachesFact`, `forget-prepare.ts`), is withdrawn too: submission marks the request `owner_reach`, and preparation judges the owner again from the stored authority (`storedOwnerSpeaksForItself`, `page-visibility.ts`), so a writer that is no longer the owner gets `not_found`; a more trusted fact files the `forget_requires_owner` proposal. A member id whose page slug `slugifyPath` would change (`a--b`, `zed-`) is refused (`invalid_params`). The page must name that member alone (`memberPageIsOwn`, checked at submission and again in preparation, `memberPageNotOwned`), and remote writes under `memory/members/` go only to the caller's own page (`assertMemberPageWriter`, called from `ops/context.ts` `enforceClientSlugFence`, so every remote page write passes it; trusted local callers are unaffected). Reads widen a world-only fact list only by `memberFactAdmitSql` (a private fact on the caller's own live member page whose readers and folder rules admit the caller; `factVisibilitySql` in `engine-sql/facts.ts` and `search/fact-relevance.ts`), and `privateProvenanceFilterUnderPolicy` judges a member-page fact's source page as the caller (every other fact keeps the empty identity, so a fact from a page that names readers stays hidden from every remote caller). Writers never cross pages: `facts/single-prepare.ts` (`SingleFactIntent.page_slug`) and `trust/supersede-handlers.ts` dedup, supersede and contest only within the member page, and no other write matches a fact there (`onMemberPageSql`); a remote save there meets only the page's own withdrawals and those of a claim its member reads (`memberPageWithdrawal`), and the insert guards mark a member-page row only by its page's own withdrawals (`schema-migrations/*-member-page-withdrawal-scope.ts`), so a claim the member never read cannot refuse or expire its save; consolidation skips facts whose page names readers (`readersSourcedFactSql`). Per-person keys: `callerIdentityKey` joins the hot-memory cache key (`facts/meta-hook.ts`, `::xid=`), `callerSessionKey` the `delta` cursor (`ops/facts.ts`), `sameAttestedActor` gates receipts (`persistence/authority.ts` `ownRequestAccessible`) and replays (`persistence/journal.ts`) on the stored actor, else the stored audience, and `get_agent_job` and the owner-fenced `get_job`, `wait_job`, `get_job_progress`, `list_jobs` and `cancel_job` match the job's `grant.actor` (system, external id, member) and `grant.actingFor` (the same distinct audience entries; `jobActorSql` in `minions/types.ts`), so a job or receipt with an actor or audience reads as missing to the bare client and to other actors and audiences, and one with neither to every actor and audience. Tests: `test/access-member-facts.test.ts` (both engines), `test/access-member-sweep.test.ts` (every attestable op as Bob, the bare client and an unbound credential; `test/helpers/member-sweep.ts`), `test/e2e/serve-http-member-sweep.test.ts` (two members over a real `serve --http` on a keyless repo-less brain).
- `src/core/access/federation-exposure.ts` (#8982) — `remotePagesFederationExposes(engine, source)`: the live pages of a source that name no readers and no folder rule, that the read paths' privacy rules (`privacyPartSql`) do not hide from a no-grant connection (#9068; skipped when `remotePrivacyRelaxed` says an operator opted out), and whose live revision (`pages.revision_principal_*`) or any version (`page_versions.write_principal_*`) a token or OAuth client wrote (revoked or deleted included; no record keeps a credential's member at write time, so an unbound, rebound or deleted one counts and each example names its member now; a tag change moves the revision attribution without a version, hiding the earlier author): count, the first five slugs, and shell-quoted `who-can-read` / `access rule add` commands. `remotePagesFederationExposesOrWarn` runs it, after the change commits, only for a change that added the source to the no-grant floor (federate reads the prior state under the source row lock), and turns a failed read into a stderr warning, so the caller's federation never changes. Read by `sources federate`, the unmanaged `sources restore` (stderr; `--json` as `pages_exposed`) and the managed `source_lifecycle` restore result. Pinned by `test/sources-federate-member-pages.test.ts` and `test/federation-exposure-private-9068.test.ts`.
- `src/core/access/serves.ts` + `src/commands/access-serves.ts` (GST-363 PR 1) — whether a brain serves several people (`brainServes`: config `access.serves` `one`|`several` wins, else 2+ enabled members) and `gbrain access serves [several --members a,b [--yes]]`: preview, then config, members (kept when present), one folder rule `people/<member>/` per member through `addFolderRules` (`access-rules.ts`, the `rule add` preview-then-write path; a git store commits `.gbrain/access.yml` through the commit door), and one read-write token `member-<id>` per member through `auth-mint.ts` (the `auth create` mint) written to `<configDir>/member-keys/<id>.key` (0600, dir 0700, refused inside a git work tree: `access_serves_key_dir_in_git`). Idempotent on the member id; a token whose file is gone is reported, never re-minted. `GBRAIN_SETUP_ABORT_AFTER=serves-members|serves-rules|serves-key` is the crash seam. Doctor: `checks/unlabeled-people-folders.ts` fails a `people/<x>/` folder with pages no rule covers on a several-person brain. Tests: `test/setup-serves-several.test.ts` (both engines).
- `gbrain serve --stdio-member <id>` (GST-363 PR 3) — `parseStdioMemberFlag`, `registeredStdioMember` and `withStdioMember` live in `src/core/stdio-member-flag.ts` (kept out of `mcp-registration.ts` so serve and doctor pick up no registration flags); serve passes the value to `startMcpServer`, dispatch sets `OperationContext.stdioMember` only for an unauthenticated stdio call, and `caller.ts` resolves it live ahead of config `mcp.stdio_member` (a disabled or unknown member reads as nobody, no fallback). Stored writes stamp it on `WriteAuthority.stdioMember` (jsonb, no migration); a stdio watch uses principal id `registration` so the wake drain re-checks that member. Setup writes it into one claude-code or codex entry (`ClaudeSetupPlan`/`CodexSetupPlan.stdioMember`); inspection reports an owned entry's member so setup re-runs and `refreshHookLaunchers` carry it, and `setupRerunArgv` never names it.
-- `src/core/ops/qm-memory.ts` (GST-359 D) — QM's memory provider pair. `memory_recall` reads the attested person's own last-24-hour facts on their member page (`listFactsSince` with `sourceMarkdownSlug`), then `rankFactsByQuestion` over the facts they may read, renders one plain line per fact (`plainFactText` strips fence and heading markers) and cuts at a line within `max_chars` (`boundFactLines`). A call that names `source_id` or `source_ids` (full surface only) reads as that scope instead: `recallSources` resolves them through `requestSourceScope` (a source outside the credential's grant is `permission_denied`), `SCOPE_READ_ACCESS` empties identity, actor and audience, so no own facts and no member-page fact are read, restricted pages stay hidden and privacy is never relaxed; the query is ranked on its first 2,000 characters (`MEMORY_RECALL_QUERY_CHARS`). `memory_write` validates 1-20 facts, derives each request id from uuidv5(member, idempotency_key) (`memoryWriteRequestId`) and saves through `remember`'s handler with `ctx.attestedOp = 'memory_write'`, which the stored write authority keeps (`WriteAuthority.attestedOp`) so publication and receipt reads re-check that operation's attest right. `qmMemoryToolResult` (dispatch) moves the result into `structuredContent` and leaves the model text in `content`; GST-1158 F2 does the same for an attested call to a contract v3 personal tool (`QM_PERSONAL_OPS`), keeping its JSON in `content` (a list as `structuredContent.results`; context_pack's text alone, like memory_recall), and dispatch measures that frame against the result cap again; each memory_recall fact carries `arm` (`own` or `ranked`, F5) and `own_page` (GST-2407: `member-facts.ts` `ownMemberFactIds`, the one set forget_fact's ownership gate also reads); `unlinkedRecallResult` is the empty success dispatch's `actorRefusal` returns for an unlinked person. Contract fixture: `scripts/build-qm-memory-contract.ts` writes `docs/contracts/qm-memory-provider/v1.json` (frozen, byte-identical) and `v2.json` (the scope read and write; `regen:all` artifacts; `v3.json` adds the personal tools with frozen result shapes; `v4.json` adds memory_propose, each personal tool's `scope_read` marking and `own_page`). Scope writes (GST-1113): `memory_write {source_id}` saves on `memory/scope` in a scope source listed in the credential's `attest_sources` (migration v293, on `access_tokens` and `oauth_clients`); `access/attest-sources.ts` holds `perCallWriteSource` (the one exemption from the one-write-source checks in `page-mutations.ts`, `memory-mutations.ts` and `persistence/authority.ts`, keyed to that slug and re-checked at publication through `actorCoverage(..., source)`), the sticky mark `sources.config.qm_scope` (set by `applyAttestSources` under row locks; `isSourceFederated` ignores federation on it), `assertScopeSourceGrant` (in `insertClientGrant`, `persistGrant`, `writeTokenGrant` and `insertUnifiedToken`) and `withoutScopeSources` (a person recall never reads a scope source). `member-facts.ts` `assertScopePageWriter` keeps other remote writers off `memory/scope`. Tests: `test/qm-scope-writes.test.ts` (both engines), `test/qm-memory-tools.test.ts` (both engines), `test/qm-personal-tools.test.ts` (v3 tools over dispatch, both engines), `test/qm-memory-contract.test.ts` (drift), `test/e2e/serve-http-qm-memory.test.ts` (keyless `serve --http`).
+- `src/core/ops/qm-memory.ts` (GST-359 D) — QM's memory provider pair. `memory_recall` reads the attested person's own last-24-hour facts on their member page (`listFactsSince` with `sourceMarkdownSlug`), then `rankFactsByQuestion` over the facts they may read, renders one plain line per fact (`plainFactText` strips fence and heading markers) and cuts at a line within `max_chars` (`boundFactLines`). A call that names `source_id` or `source_ids` (full surface only) reads as that scope instead: `recallSources` resolves them through `requestSourceScope` (a source outside the credential's grant is `permission_denied`), `SCOPE_READ_ACCESS` empties identity, actor and audience, so no own facts and no member-page fact are read, restricted pages stay hidden and privacy is never relaxed; the query is ranked on its first 2,000 characters (`MEMORY_RECALL_QUERY_CHARS`). `memory_write` validates 1-20 facts, derives each request id from uuidv5(member, idempotency_key) (`memoryWriteRequestId`) and saves through `remember`'s handler with `ctx.attestedOp = 'memory_write'`, which the stored write authority keeps (`WriteAuthority.attestedOp`) so publication and receipt reads re-check that operation's attest right. `qmMemoryToolResult` (dispatch) moves the result into `structuredContent` and leaves the model text in `content`; GST-1158 F2 does the same for an attested call to a contract v3 personal tool (`QM_PERSONAL_OPS`), keeping its JSON in `content` (a list as `structuredContent.results`; context_pack's text alone, like memory_recall), and dispatch measures that frame against the result cap again; each memory_recall fact carries `arm` (`own` or `ranked`, F5) and `own_page` (GST-2407: `member-facts.ts` `ownMemberFactIds`, the one set forget_fact's ownership gate also reads); `unlinkedRecallResult` is the empty success dispatch's `actorRefusal` returns for an unlinked person. Contract fixture: `scripts/build-qm-memory-contract.ts` writes `docs/contracts/qm-memory-provider/v1.json` (frozen, byte-identical) and `v2.json` (the scope read and write; `regen:all` artifacts; `v3.json` adds the personal tools with frozen result shapes; `v4.json` adds memory_propose, each personal tool's `scope_read` marking and `own_page`; `v5.json` marks context_pack `scope_read`, v4's markings frozen as `V4_SCOPE_READ_OPS`). Scope writes (GST-1113): `memory_write {source_id}` saves on `memory/scope` in a scope source listed in the credential's `attest_sources` (migration v293, on `access_tokens` and `oauth_clients`); `access/attest-sources.ts` holds `perCallWriteSource` (the one exemption from the one-write-source checks in `page-mutations.ts`, `memory-mutations.ts` and `persistence/authority.ts`, keyed to that slug and re-checked at publication through `actorCoverage(..., source)`), the sticky mark `sources.config.qm_scope` (set by `applyAttestSources` under row locks; `isSourceFederated` ignores federation on it), `assertScopeSourceGrant` (in `insertClientGrant`, `persistGrant`, `writeTokenGrant` and `insertUnifiedToken`) and `withoutScopeSources` (a person recall never reads a scope source). `member-facts.ts` `assertScopePageWriter` keeps other remote writers off `memory/scope`. Tests: `test/qm-scope-writes.test.ts` (both engines), `test/qm-memory-tools.test.ts` (both engines), `test/qm-personal-tools.test.ts` (v3 tools over dispatch, both engines), `test/qm-memory-contract.test.ts` (drift), `test/e2e/serve-http-qm-memory.test.ts` (keyless `serve --http`).
- `src/cli/enforced-member.ts` + `src/cli/enforced-member-classes.ts` + `src/cli/enforced-commit-push.ts`: enforced member mode ([guide](../../guides/enforced-member.md)). With `GBRAIN_ENFORCED_MEMBER` set, `enforcedGate` in `src/cli/main.ts` classifies the command before any dispatch (`enforcedClassOf`: read, write, allowed, silent or refused; anything unclassified is refused, exit 3, `enforced_member_refused`). An empty value, an unknown member or the owner id refuses everything. The gate classifies before help: a refused command refuses with `--help` too, and an allowed one prints only its static help. `checkEnforcedOpArgs` refuses a named source (`--source`, `--source-id`, `--source-ids`) the member cannot read or that is not registered, alike. Reads go through `dispatchToolCall` (with only the operation's declared params; the source travels as the call's `sourceId`) with `remote: true`, `transport: 'stdio'`, `stdioMember` and `enforcedMember: true` (dispatch forces `hidePrivate`, `owner: false` and no private-readable sources), minus other members' personal sources (`hiddenPersonalSources`; an explicit `--source` naming one refuses), and `namesHiddenPage` withholds any output that still names a hidden page. Writes stay trusted local writes (`ctx.remote` false): `checkEnforcedWrite` refuses a target the member cannot read (`memberPageView`) and any label change, and `remember` needs `--entity` naming a readable page (`checkEnforcedRemember`, the one decision point). `write-request` answers only ids in the member's receipt ledger (`recordEnforcedReceipts`, `configDir()/enforced-member/<member>.receipts`); any other id is swapped for a fresh one, so it answers as unknown. sync, `sources refresh` and `git commit-push` (checked by `checkEnforcedCommitPush`: every named path readable, no label or `.gbrain/` change, refused modes) run with output replaced by one line (`withWithheldOutput`, which also captures the fd-1 chain through `setStdoutCapture`); `doctor` prints only check names, statuses and counts (`withDoctorCounts`); sync and `sources refresh` take only their listed flags and a readable source (`syncSourceArg`); `entity` and every coverage notice drop the mention coverage count (`withoutCoverageCounts`); `timeline-add` refuses a gbrain fence marker; `hook` succeeds silently. The warm CLI socket, the persistence delegate and the skill-resolver fast path are skipped under the mode. Tests: `test/enforced-member.serial.test.ts` (CLI subprocesses, both engines, repo-less and git), `test/enforced-member-classes.test.ts` (every command and operation classified once).
diff --git a/docs/contracts/qm-memory-provider/README.md b/docs/contracts/qm-memory-provider/README.md
index 0cb2ff09f1..1ca1abcc2f 100644
--- a/docs/contracts/qm-memory-provider/README.md
+++ b/docs/contracts/qm-memory-provider/README.md
@@ -30,6 +30,15 @@ answers, the proposal states (a state not listed means unknown, not published) a
never as the person. Each `memory_recall` fact carries `own_page`, true when the fact
sits on the person's own member page, which is exactly when `forget_fact` accepts it on
ownership (it can still ask the owner for a fact more trusted than the person's own writes).
+`x-qm-audience` is not an input in v4: a request carrying it is refused
+(`actor_not_attested`, reason `audience_not_supported`), with or without `x-qm-actor`.
+
+`v5.json` keeps all of v4 and marks `context_pack` `scope_read: true`: a call that
+names `source_id` reads only that source (entities, cards, core memory, the
+counterparty brief and hot facts) as its audience. Each `entity_refs` entry must
+carry that same `source_id`, and `entity_refs` without `source_id`, an entry in
+another source, or `session_id` is refused with `invalid_params` before anything
+is read.
They are generated from the live operation registry by
`bun scripts/build-qm-memory-contract.ts` (part of `bun run regen:all`), and
diff --git a/docs/contracts/qm-memory-provider/v5.json b/docs/contracts/qm-memory-provider/v5.json
new file mode 100644
index 0000000000..7fde8f263b
--- /dev/null
+++ b/docs/contracts/qm-memory-provider/v5.json
@@ -0,0 +1,1715 @@
+{
+ "contract": "gbrain.qm-memory-provider",
+ "version": 5,
+ "transport": {
+ "protocol": "mcp",
+ "session": "stateless",
+ "session_header_issued": false,
+ "success_codes_in": "structuredContent",
+ "unknown_arguments": "an argument a read tool does not declare is refused with invalid_params, and nothing is read, when its nearest declared argument is a source scope or a filter (source for source_id, sources for source_ids, type for types) or its own name is in a scope or filter family the tool declares (source_name on a tool that declares source_id); any other argument a read tool does not declare is ignored and reported only in _meta.warnings ([{code: \"unknown_param\", param, suggestion?}]), never in content, unless the brain sets mcp.strict_params to reject; a write tool refuses every argument it does not declare with invalid_params"
+ },
+ "actor": {
+ "header": "x-qm-actor",
+ "argument": "acting_user",
+ "argument_rule": "optional; on an attested call it must equal the header; with no header it is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it), and the call then runs exactly as the credential; never chooses the person on its own",
+ "actor_id": {
+ "pattern": "^[\\x21-\\x7e]{1,256}$",
+ "case_folding": false
+ },
+ "system": "qm",
+ "default_attest_ops": [
+ "get_write_request",
+ "memory_recall",
+ "memory_write"
+ ],
+ "deferred_ops": [
+ "abort_page_upload",
+ "add_link",
+ "add_tag",
+ "add_timeline_entry",
+ "append_page",
+ "begin_page_upload",
+ "capture",
+ "commit_page_upload",
+ "confirm_memory",
+ "delete_page",
+ "edit_page",
+ "extract_entities",
+ "extract_facts",
+ "list_write_conflicts",
+ "log_ingest",
+ "loops_close",
+ "loops_mute",
+ "loops_unmute",
+ "ontology_propose",
+ "put_page",
+ "put_pages",
+ "put_raw_data",
+ "questions_pin",
+ "questions_refresh",
+ "questions_unpin",
+ "rate_answer",
+ "remove_link",
+ "remove_tag",
+ "restore_page",
+ "revert_version",
+ "takes_add",
+ "takes_resolve",
+ "takes_supersede",
+ "takes_update",
+ "upload_page_part"
+ ],
+ "audit": "the audit trail and stored writes record the canonical external id as sent, with its linked member"
+ },
+ "tools": [
+ {
+ "name": "memory_propose",
+ "description": "Propose one timeline entry or link on a shared page for the person this call serves; the brain owner approves it before it is written. Needs an attested person. Poll get_write_request with the request_id; the same idempotency_key replays.",
+ "scope": "write",
+ "mutating": true,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "kind": {
+ "type": "string",
+ "description": "timeline (date, summary) or link (to).",
+ "enum": [
+ "timeline",
+ "link"
+ ]
+ },
+ "target": {
+ "type": "string",
+ "description": "Slug the write lands on (a link's from page)."
+ },
+ "idempotency_key": {
+ "type": "string",
+ "description": "1-128 visible ASCII characters; the same key replays this proposal."
+ },
+ "expected_revision": {
+ "type": "string",
+ "description": "The revision shown to the person; refused when the page moved."
+ },
+ "date": {
+ "type": "string",
+ "description": "timeline: YYYY-MM-DD."
+ },
+ "summary": {
+ "type": "string",
+ "description": "timeline: one line."
+ },
+ "detail": {
+ "type": "string",
+ "description": "timeline: details."
+ },
+ "source": {
+ "type": "string",
+ "description": "timeline: where it came from."
+ },
+ "to": {
+ "type": "string",
+ "description": "link: the page it points to."
+ },
+ "link_type": {
+ "type": "string",
+ "description": "link: a type the schema pack declares."
+ },
+ "context": {
+ "type": "string",
+ "description": "link: context."
+ },
+ "valid_from": {
+ "type": "string",
+ "description": "link: YYYY-MM-DD."
+ },
+ "valid_until": {
+ "type": "string",
+ "description": "link: YYYY-MM-DD."
+ },
+ "acting_user": {
+ "type": "string",
+ "description": "Set by the trusted system: equal to the x-qm-actor header, or omit."
+ }
+ },
+ "required": [
+ "kind",
+ "target",
+ "idempotency_key"
+ ]
+ }
+ },
+ {
+ "name": "memory_recall",
+ "description": "Facts for the person this call serves, one per line: their own recent facts first, then facts matching query. Never page bodies. For QM; agents use recall.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "What the turn is about; ranks the facts."
+ },
+ "max_chars": {
+ "type": "integer",
+ "description": "Text cap in UTF-16 code units, 200-12000 (default 6000)."
+ },
+ "query_keep": {
+ "type": "string",
+ "description": "Which end of a query over 2000 characters ranks the facts: head (the default) or tail. Sending it adds query_truncated.",
+ "enum": [
+ "head",
+ "tail"
+ ]
+ },
+ "acting_user": {
+ "type": "string",
+ "description": "Set by the trusted system: equal to the x-qm-actor header, or omit."
+ },
+ "source_id": {
+ "type": "string",
+ "description": "Read this one source as its audience (a shared scope): never the person's own facts."
+ },
+ "source_ids": {
+ "type": "array",
+ "description": "Read only these sources as their audience (a shared scope): never the person's own facts.",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "required": [
+ "query"
+ ]
+ }
+ },
+ {
+ "name": "memory_write",
+ "description": "Save facts for the person this call serves, readable by them alone. Needs an attested person. The same idempotency_key replays the first receipt. For QM; agents use remember.",
+ "scope": "write",
+ "mutating": true,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "facts": {
+ "type": "array",
+ "description": "1-20 facts.",
+ "items": {
+ "type": "object",
+ "properties": {
+ "fact": {
+ "type": "string",
+ "description": "One claim."
+ },
+ "provenance": {
+ "type": "string",
+ "description": "Where it came from (<=200 chars)."
+ },
+ "kind": {
+ "type": "string",
+ "description": "Default fact.",
+ "enum": [
+ "event",
+ "preference",
+ "commitment",
+ "belief",
+ "fact"
+ ]
+ },
+ "valid_from": {
+ "type": "string",
+ "description": "When it became true (ISO 8601)."
+ }
+ },
+ "required": [
+ "fact",
+ "provenance"
+ ],
+ "additionalProperties": false
+ }
+ },
+ "idempotency_key": {
+ "type": "string",
+ "description": "1-128 visible ASCII characters; the same key replays this write."
+ },
+ "acting_user": {
+ "type": "string",
+ "description": "Set by the trusted system: equal to the x-qm-actor header, or omit."
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One of this credential's scope sources: save on its shared memory/scope page."
+ }
+ },
+ "required": [
+ "facts",
+ "idempotency_key"
+ ]
+ }
+ }
+ ],
+ "personal_tools": {
+ "read_as": "the attested person (x-qm-actor): what that person may read, their own restricted pages included, so use these tools only in the person's own conversations; a tool marked scope_read: true reads as the scope instead when the call names sources (scope_read below)",
+ "opt_in": "only get_write_request is in default_attest_ops: the brain operator lists each other tool in the client's --attest-ops (gbrain auth rescope --client <id> --attest-actor qm --attest-ops <list>), or it is refused with actor_not_attested reason op_not_attested",
+ "structured_content": "an attested success carries the result in structuredContent and keeps it as JSON in content (notice blocks follow it); a list arrives as structuredContent.results; context_pack's text alone fills content, as memory_recall's does; an unattested call to the same tool gets no structuredContent",
+ "result_rule": "each result lists the fields every success carries; other fields may appear and must be ignored",
+ "scope_read": {
+ "marked": "scope_read: true: a call that names sources (source_id, source_ids or all_sources, where the tool's input_schema declares them) reads those sources as their audience, never as the person, as memory_recall's scope_read does: no member-page fact, no page restricted to named readers, and privacy is never relaxed",
+ "every_source": "under a scope read, source_id '__all__', '__all__' in source_ids and all_sources: true are refused with invalid_params; nothing is read",
+ "unmarked": "scope_read: false: the tool reads as the person whatever the call names",
+ "context_pack": "a context_pack scope read names one source in source_id and reads only it: entities, cards, core memory, the counterparty brief and hot facts; entity_refs also name sources, and each must carry that same source_id; a call with entity_refs and no source_id, an entity_refs entry in another source, or session_id is refused with invalid_params, and nothing is read",
+ "as_person": "a credential the brain operator binds with --attest-read person reads named sources as the person instead, narrowed to those sources",
+ "without_sources": "the person read (read_as above)"
+ },
+ "tools": [
+ {
+ "name": "context_pack",
+ "description": "Core memory, budget-packed cards, open threads and hot facts for up to 8 entities, zero LLM. Call at session start and after compaction.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "entities": {
+ "type": "string",
+ "description": "Comma-separated names or slugs (max 8)."
+ },
+ "budget_tokens": {
+ "type": "number",
+ "description": "Token budget; cards pack first."
+ },
+ "since": {
+ "type": "string",
+ "description": "Open-thread events after this ISO time."
+ },
+ "session_id": {
+ "type": "string",
+ "description": "Opaque session id."
+ },
+ "include_private": {
+ "type": "boolean",
+ "description": "Local trusted callers only."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "include_quarantined": {
+ "type": "boolean",
+ "description": "Admin or memory_confirm: quarantined cards."
+ },
+ "counterparty": {
+ "type": "string",
+ "description": "Person or company (name or slug): adds a pulled brief of dated items about them."
+ },
+ "intent": {
+ "type": "string",
+ "description": "With counterparty: the task the brief is for.",
+ "enum": [
+ "meeting",
+ "reply"
+ ]
+ },
+ "source_id": {
+ "type": "string",
+ "description": "Resolve entities in this source only. Default: your source first, then every source you can read."
+ },
+ "entity_refs": {
+ "type": "array",
+ "description": "Source-qualified entities: [{\"source_id\":\"wiki\",\"slug\":\"people/alice-example\"}].",
+ "items": {
+ "type": "object",
+ "properties": {
+ "source_id": {
+ "type": "string"
+ },
+ "slug": {
+ "type": "string"
+ }
+ },
+ "required": [],
+ "additionalProperties": false
+ }
+ },
+ "prefer_source_id": {
+ "type": "string",
+ "description": "Source to try first (thin clients send .gbrain-source here); never narrows."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "content": "the rendered pack text alone, as memory_recall's; it is not repeated in structuredContent",
+ "structured_content": {
+ "protocol_version": "number",
+ "entities": [
+ "string"
+ ],
+ "cards": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string"
+ }
+ ],
+ "open_threads": "array",
+ "facts": [
+ {
+ "fact": "string",
+ "kind": "string",
+ "fact_id": "string"
+ }
+ ],
+ "entity_facts": "array"
+ }
+ }
+ },
+ {
+ "name": "entity",
+ "description": "Person/company/account card, zero LLM. Previews are not evidence: fetch the page before stating status or dates. Miss: found:false with near matches (create_safety). Facts: recall.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "name": {
+ "type": "string",
+ "description": "Name, alias or slug."
+ },
+ "names": {
+ "type": "array",
+ "description": "Or up to 50 names/codes at once: compact rows.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "source_id": {
+ "type": "string",
+ "description": "Read only this source. Default: your source first, then every source you can read."
+ },
+ "prefer_source_id": {
+ "type": "string",
+ "description": "Source to try first (thin clients send .gbrain-source here); never narrows."
+ },
+ "variants": {
+ "type": "boolean",
+ "description": "false: exact names only. Default true: with no exact match, one unambiguous name variant (card.match says which)."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "protocol_version": "number",
+ "found": "boolean"
+ },
+ "optional": {
+ "card": "object when found: card.entity holds slug, source_id, title and type",
+ "suggestions": "array of {slug, title} when not found",
+ "ambiguous": "true: the name matched several entities"
+ },
+ "with_names": {
+ "protocol_version": "number",
+ "results": [
+ {
+ "name": "string",
+ "found": "boolean"
+ }
+ ]
+ }
+ }
+ },
+ {
+ "name": "find_experts",
+ "description": "Answers 'who in my brain knows about <topic>'. Returns ranked person/company pages by expertise depth (sub-linear match score), relationship recency (exp decay with 6-month half-life), and salience. Use this for questions like 'who should I talk to about X', 'who knows about Y', 'find me someone who's worked on Z', or any expertise-routing intent. Filters at SQL to person + company pages — does NOT return notes or articles. Pair with --explain (CLI) to surface the per-result factor breakdown.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "topic": {
+ "type": "string",
+ "description": "The topic to route. Free-form natural language."
+ },
+ "limit": {
+ "type": "number",
+ "description": "Max results (default 5)."
+ },
+ "explain": {
+ "type": "boolean",
+ "description": "Include factor breakdown per result (expertise, recency, salience)."
+ },
+ "source_ids": {
+ "type": "array",
+ "description": "Narrow to these sources (omit or [] for all you can read).",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string",
+ "score": "number"
+ }
+ ]
+ }
+ }
+ },
+ {
+ "name": "forget_fact",
+ "description": "Forget a fact by recording a durable withdrawal in its source and visibility. Strikes the Markdown facts fence when writable; otherwise keeps the withdrawal in the database. Stale imports cannot reactivate the same normalized claim. This retracts memory; original prose, files and backups may retain the text. Idempotent on already-expired or unknown ids.",
+ "scope": "write",
+ "mutating": true,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "request_id": {
+ "type": "string",
+ "description": "Reuse only to retry."
+ },
+ "id": {
+ "type": "number",
+ "description": "Fact id to forget."
+ },
+ "reason": {
+ "type": "string",
+ "description": "Optional reason; written to the fence row's context cell as \"forgotten: <reason>\". Default: \"forgotten\"."
+ }
+ },
+ "required": [
+ "id"
+ ]
+ },
+ "personal_only": true,
+ "scope_read": false,
+ "result": {
+ "structured_content": {
+ "id": "number",
+ "request_id": "string",
+ "state": "\"queued\" | \"running\" | \"recovering\" | \"committed\" | \"conflict\" | \"failed\" | \"cancelled\""
+ },
+ "optional": {
+ "expired": "boolean: the fact is withdrawn"
+ },
+ "note": "withdraws only a fact on the person's own member page (any other id is fact_not_found); send request_id (a UUID) so a retry replays the same withdrawal; a state other than committed is read with get_write_request"
+ }
+ },
+ {
+ "name": "get_backlinks",
+ "description": "Links to a page, ≤500/call; group:\"page\" by referrer, newest first.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "slug": {
+ "type": "string",
+ "description": "Page slug."
+ },
+ "status": {
+ "type": "string",
+ "description": "Default live.",
+ "enum": [
+ "live",
+ "all"
+ ]
+ },
+ "as_of": {
+ "type": "string",
+ "description": "YYYY-MM-DD"
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source, or '__all__'."
+ },
+ "all_sources": {
+ "type": "boolean",
+ "description": "Same as source_id __all__."
+ },
+ "type": {
+ "type": "string",
+ "description": "Referrer type."
+ },
+ "group": {
+ "type": "string",
+ "description": "Per page.",
+ "enum": [
+ "page"
+ ]
+ },
+ "limit": {
+ "type": "number",
+ "description": "≤5000"
+ },
+ "cursor": {
+ "type": "string",
+ "description": "Next."
+ },
+ "all": {
+ "type": "boolean",
+ "description": "Local CLI only: every row, paging internally."
+ }
+ },
+ "required": [
+ "slug"
+ ]
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "from_slug": "string",
+ "from_source_id": "string",
+ "to_slug": "string",
+ "to_source_id": "string",
+ "link_type": "string"
+ }
+ ]
+ },
+ "optional": {
+ "results[].truncated": "true on the last row when more remain",
+ "results[].next_cursor": "string on that row: pass it as cursor"
+ },
+ "with_group_page": {
+ "rows": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string"
+ }
+ ],
+ "total": "number",
+ "truncated": "boolean",
+ "cursor": "string | null"
+ }
+ }
+ },
+ {
+ "name": "get_page",
+ "description": "Read a page; `section`/`grep` reads one part. Window selector order: cursor, around_chunk_id, lines, bytes (context only with grep). Edit: include_content:true, `content` to put_page, or edit_page. >256 KB: outline+window, then `next`.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "slug": {
+ "type": "string",
+ "description": "Page slug."
+ },
+ "fuzzy": {
+ "type": "boolean",
+ "description": "Fuzzy match."
+ },
+ "include_content": {
+ "type": "boolean",
+ "description": "Markdown + revision."
+ },
+ "content_only": {
+ "type": "boolean",
+ "description": "Round-trip fields."
+ },
+ "body": {
+ "type": "string",
+ "description": "auto: whole up to 256 KB, else outline + window; a window's edit_target is edit_page `within`. none: revision + size + tail_sha256 (append_page expected_tail_sha256).",
+ "enum": [
+ "auto",
+ "full",
+ "none",
+ "outline",
+ "window"
+ ]
+ },
+ "lines": {
+ "type": "object",
+ "description": "Window: 1-based lines.",
+ "properties": {
+ "from": {
+ "type": "number"
+ },
+ "count": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "from",
+ "count"
+ ],
+ "additionalProperties": false
+ },
+ "bytes": {
+ "type": "object",
+ "description": "Window: UTF-8 bytes of size.total_bytes, not body_bytes (snapped to a line start).",
+ "properties": {
+ "offset": {
+ "type": "number"
+ },
+ "length": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "offset",
+ "length"
+ ],
+ "additionalProperties": false
+ },
+ "around_chunk_id": {
+ "type": "number",
+ "description": "Window around a search hit chunk_id."
+ },
+ "context_lines": {
+ "type": "number",
+ "description": "Lines around around_chunk_id (20)."
+ },
+ "cursor": {
+ "type": "string",
+ "description": "next_cursor: read on."
+ },
+ "max_bytes": {
+ "type": "number",
+ "description": "Window bytes (40000)."
+ },
+ "view": {
+ "type": "string",
+ "description": "markdown: page the round-trip content.",
+ "enum": [
+ "read",
+ "markdown"
+ ]
+ },
+ "outline_from": {
+ "type": "number",
+ "description": "Outline next_from_index."
+ },
+ "section": {
+ "type": "string",
+ "description": "Only the section under this heading (case-insensitive, first match), with its heading_path."
+ },
+ "grep": {
+ "type": "string",
+ "description": "Only the paragraphs containing this text (case-insensitive substring, not a regex), with line numbers and total_matches."
+ },
+ "context": {
+ "type": "number",
+ "description": "Applies only with grep (ignored without it): paragraphs of context either side (default 1, max 5)."
+ },
+ "include_deleted": {
+ "type": "boolean",
+ "description": "Soft-deleted too."
+ },
+ "include_timeline_entries": {
+ "type": "boolean",
+ "description": "Timeline rows."
+ },
+ "grammar_diagnostics": {
+ "type": "boolean",
+ "description": "Also return every line-grammar finding for the page."
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source, or '__all__'."
+ },
+ "include_quarantined": {
+ "type": "boolean",
+ "description": "Admin: quarantined body."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "known_as_of": {
+ "type": "string",
+ "description": "Recorded time: the page as this brain had recorded it at this ISO 8601 instant (2026-10-01T12:00:00Z), from the belief ledger. Not as_of, which is valid time (a date)."
+ },
+ "as_of": {
+ "type": "string",
+ "description": "YYYY-MM-DD: edition in force then. No valid_time in reply: current page."
+ }
+ },
+ "required": [
+ "slug"
+ ]
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "slug": "string",
+ "source_id": "string",
+ "type": "string",
+ "title": "string",
+ "revision": "string"
+ },
+ "optional": {
+ "compiled_truth": "string: a whole read",
+ "timeline": "string: a whole read",
+ "body": "\"none\" | \"outline\" | \"window\": a partial read (a page over the inline size, or the body argument); it carries no compiled_truth",
+ "truncated": "boolean: a partial read left text out",
+ "resolved_slug": "string: the slug an alias resolved to"
+ },
+ "note": "a page the person may not read answers page_not_found, the same as a missing one"
+ }
+ },
+ {
+ "name": "get_timeline",
+ "description": "Get timeline entries for a page, optionally filtered by date window. To change or remove an entry, edit its bullet in the page's Timeline section with edit_page (expected_revision from get_page include_content:true): the row follows the page.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "slug": {
+ "type": "string",
+ "description": "Slug of the page whose timeline entries to return."
+ },
+ "after": {
+ "type": "string",
+ "description": "Return entries on or after this date (YYYY-MM-DD)"
+ },
+ "before": {
+ "type": "string",
+ "description": "Return entries on or before this date (YYYY-MM-DD)"
+ },
+ "since": {
+ "type": "string",
+ "description": "Alias for after; accepted for agent callers"
+ },
+ "until": {
+ "type": "string",
+ "description": "Alias for before; accepted for agent callers"
+ },
+ "limit": {
+ "type": "number",
+ "description": "Maximum number of timeline entries to return"
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "source_id": {
+ "type": "string",
+ "description": "Read only this source."
+ },
+ "source_ids": {
+ "type": "array",
+ "description": "Narrow to these sources (omit or [] for all you can read).",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "required": [
+ "slug"
+ ]
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "id": "number",
+ "date": "string",
+ "summary": "string",
+ "source": "string",
+ "detail": "string"
+ }
+ ]
+ },
+ "note": "a page the person may not read answers an empty list"
+ }
+ },
+ {
+ "name": "get_write_request",
+ "description": "Your write's receipt by request_id (after write_pending or a lost reply). Poll at retry_after_ms until final.",
+ "scope": "write",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "request_id": {
+ "type": "string",
+ "description": "The id you sent, or the receipt's."
+ },
+ "applied": {
+ "type": "boolean",
+ "description": "Also return applied: searchable yet, the gap, the write watermark."
+ }
+ },
+ "required": [
+ "request_id"
+ ]
+ },
+ "personal_only": true,
+ "scope_read": false,
+ "result": {
+ "structured_content": {
+ "request_id": "string",
+ "state": "\"queued\" | \"running\" | \"recovering\" | \"committed\" | \"conflict\" | \"failed\" | \"cancelled\"",
+ "retry_after_ms": "number | null",
+ "operation": "string",
+ "source_id": "string",
+ "slug": "string | null",
+ "created_at": "string",
+ "updated_at": "string"
+ },
+ "optional": {
+ "write_error": "string: why a write ended without publishing",
+ "outcome": "object: the published write's result"
+ },
+ "states": {
+ "known": [
+ "queued",
+ "running",
+ "recovering",
+ "committed",
+ "conflict",
+ "failed",
+ "cancelled"
+ ],
+ "terminal": [
+ "committed",
+ "conflict",
+ "failed",
+ "cancelled"
+ ],
+ "published": "committed",
+ "unknown": "a state not listed here means unknown, not published: never report the write as saved; poll again or report it as unknown",
+ "poll": "until a terminal state, after retry_after_ms when it is set"
+ }
+ },
+ "proposal_receipt": "the fields and states in result are a write's receipt; a request_id from memory_propose that no write holds yet answers memory_propose.receipt instead, with its own fields and states (awaiting_owner, denied, expired, cancelled, failed, conflict)"
+ },
+ {
+ "name": "query",
+ "description": "Hybrid search for concept/landscape questions and people/companies/projects by topic; adds fact rows. expand: one LLM call (expansion recovers synonyms; rarely helps). Still top-K; return_unit: sections or conversations. Lists: list_pages. Exact tokens: `search` is cheaper. Personal: get_recent_salience, find_anomalies; transcripts: `gbrain transcripts recent`. Do NOT assume 'crazy' means impressive (often difficult or emotionally charged). Needs an embedding key (else keyword-only); expansion needs a chat key. Fact rows: use follow_up. fields: \"full\" adds diagnostics.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Question or topic (required unless image)."
+ },
+ "image": {
+ "type": "string",
+ "description": "Base64 image."
+ },
+ "image_mime": {
+ "type": "string",
+ "description": "MIME type of image."
+ },
+ "limit": {
+ "type": "number",
+ "description": "Default 10/25/50 by search mode."
+ },
+ "offset": {
+ "type": "number",
+ "description": "Rows to skip."
+ },
+ "types": {
+ "type": "array",
+ "description": "Page types, e.g. ['person'].",
+ "items": {
+ "type": "string"
+ }
+ },
+ "where": {
+ "type": "object",
+ "description": "Frontmatter equality, e.g. {status: \"active\"}; a list matches any."
+ },
+ "snippet_chars": {
+ "type": "number",
+ "description": "Chars per row (0 = full)."
+ },
+ "return_unit": {
+ "type": "string",
+ "description": "Default auto: whole conversations.",
+ "enum": [
+ "chunk",
+ "window",
+ "section",
+ "page",
+ "auto"
+ ]
+ },
+ "return_window": {
+ "type": "number",
+ "description": "Window radius 1-3."
+ },
+ "token_budget": {
+ "type": "number",
+ "description": "Evidence token cap."
+ },
+ "expand": {
+ "type": "boolean",
+ "description": "Default off; one LLM call, rarely helps."
+ },
+ "detail": {
+ "type": "string",
+ "description": "low (compiled truth), medium (default) or high (all chunks)."
+ },
+ "fields": {
+ "type": "string",
+ "description": "lean (remote default) or full.",
+ "enum": [
+ "lean",
+ "full"
+ ]
+ },
+ "mode": {
+ "type": "string",
+ "description": "Local callers only."
+ },
+ "lang": {
+ "type": "string",
+ "description": "Code language."
+ },
+ "symbol_kind": {
+ "type": "string",
+ "description": "Code symbol type."
+ },
+ "near_symbol": {
+ "type": "string",
+ "description": "Anchor code symbol."
+ },
+ "walk_depth": {
+ "type": "number",
+ "description": "Code walk depth 1-2."
+ },
+ "salience": {
+ "type": "string",
+ "description": "Boost emotional pages.",
+ "enum": [
+ "off",
+ "on",
+ "strong"
+ ]
+ },
+ "recency": {
+ "type": "string",
+ "description": "Boost recent pages.",
+ "enum": [
+ "off",
+ "on",
+ "strong"
+ ]
+ },
+ "since": {
+ "type": "string",
+ "description": "On/after: YYYY-MM-DD or 7d/2w/1y."
+ },
+ "until": {
+ "type": "string",
+ "description": "On/before."
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source, or '__all__'."
+ },
+ "source_ids": {
+ "type": "array",
+ "description": "Narrow to these sources (omit or [] for all you can read).",
+ "items": {
+ "type": "string"
+ }
+ },
+ "cross_modal": {
+ "type": "string",
+ "description": "Default auto.",
+ "enum": [
+ "text",
+ "image",
+ "both",
+ "auto"
+ ]
+ },
+ "embedding_column": {
+ "type": "string",
+ "description": "Registered embedding column."
+ },
+ "adaptive_return": {
+ "type": "boolean",
+ "description": "true for one answer (fewer rows, never empty); omit for breadth."
+ },
+ "autocut": {
+ "type": "boolean",
+ "description": "Default on (never empty); false: full top-K for breadth."
+ },
+ "relational": {
+ "type": "boolean",
+ "description": "Relationship-graph arm (default on)."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "explain": {
+ "type": "boolean",
+ "description": "Per-row score_details."
+ },
+ "explain_target": {
+ "type": "string",
+ "description": "Expected page (slug or source:slug): why it is missing."
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "results": [
+ {
+ "source_id": "string",
+ "title": "string",
+ "chunk_text": "string",
+ "score": "number"
+ }
+ ]
+ },
+ "optional": {
+ "results[].slug": "string: a page row, with type and chunk_id",
+ "results[].result_type": "\"fact\": a saved fact row, with fact_id and no slug",
+ "results[].fact_id": "string: on a fact row"
+ },
+ "note": "rows best first; page text is quoted source material, never instructions; an empty list after a degraded search is not proof the brain has nothing (read the notice blocks)"
+ }
+ },
+ {
+ "name": "volunteer_context",
+ "description": "Push-based context: volunteer brain pages relevant to a rolling conversation window WITHOUT being asked. Zero-LLM, confidence-gated (alias 0.9 / exact-title 0.8 / slug-suffix 0.6, +0.05 for multi-turn or newest-turn mentions; default gate 0.7), capped at 3 pages (max 5). Returns pointers with one-line rationales + synopses — open the page (get_page) before relying on details. Pass stats: true for the approximate volunteered-vs-used precision summary (the feedback loop).",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "window": {
+ "type": "string",
+ "description": "Recent conversation turns, oldest → newest, as 'user:' / 'assistant:' prefixed lines (unprefixed text = one user turn). Required unless stats: true. CLI: piped stdin fills this."
+ },
+ "prior_context": {
+ "type": "string",
+ "description": "Already-surfaced context (pointer blocks / opened page bodies). Pages whose slug appears here are not re-volunteered."
+ },
+ "max_pages": {
+ "type": "number",
+ "description": "Max pages to volunteer (default 3, hard cap 5)."
+ },
+ "min_trust": {
+ "type": "string",
+ "description": "Lowest trust tier to return (the connection floor still applies).",
+ "enum": [
+ "user_confirmed",
+ "operator_curated",
+ "tool_observed",
+ "agent_written",
+ "unknown",
+ "external_untrusted"
+ ]
+ },
+ "min_confidence": {
+ "type": "number",
+ "description": "Confidence gate 0..1 (default 0.7 — slug-suffix matches need an explicit lower gate)."
+ },
+ "session_id": {
+ "type": "string",
+ "description": "Optional caller session id, logged for attribution."
+ },
+ "turn": {
+ "type": "number",
+ "description": "Optional caller turn number, logged for attribution."
+ },
+ "stats": {
+ "type": "boolean",
+ "description": "Return the volunteered-vs-used precision summary instead of volunteering. APPROXIMATE: \"used\" = pages.last_retrieved_at > volunteered_at."
+ },
+ "days": {
+ "type": "number",
+ "description": "Stats window in days (default 30; stats mode only)."
+ },
+ "source_ids": {
+ "type": "array",
+ "description": "Narrow to these sources (omit or [] for all you can read).",
+ "items": {
+ "type": "string"
+ }
+ }
+ },
+ "required": []
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "pages": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "display": "string",
+ "confidence": "number",
+ "rationale": "string"
+ }
+ ],
+ "count": "number",
+ "window_turns": "number"
+ },
+ "note": "stats: true answers a usage summary instead, which this contract does not freeze"
+ }
+ },
+ {
+ "name": "whois",
+ "description": "Exact identity lookup: entity pages whose email, title or declared alias equals an email address or name, ignoring case, accents and quotes. Never fuzzy: empty matches means no exact match; ambiguous means several.",
+ "scope": "read",
+ "mutating": false,
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Email address or name, e.g. '[email protected]'."
+ },
+ "types": {
+ "type": "array",
+ "description": "Page types; default: the schema pack's entity types.",
+ "items": {
+ "type": "string"
+ }
+ },
+ "source_id": {
+ "type": "string",
+ "description": "One source; '__all__' spans your sources."
+ }
+ },
+ "required": [
+ "query"
+ ]
+ },
+ "personal_only": true,
+ "scope_read": true,
+ "result": {
+ "structured_content": {
+ "query": "string",
+ "query_kind": "\"email\" | \"name\"",
+ "matches": [
+ {
+ "slug": "string",
+ "source_id": "string",
+ "title": "string",
+ "type": "string",
+ "match": "string"
+ }
+ ],
+ "ambiguous": "boolean"
+ },
+ "optional": {
+ "truncated": "true: more candidates share the key than were returned",
+ "note": "string"
+ },
+ "note": "exact, never fuzzy: no matches means no exact match; ambiguous: true means several, so ask which one and never take the first"
+ }
+ }
+ ]
+ },
+ "memory_recall": {
+ "limits": {
+ "max_chars": {
+ "min": 200,
+ "max": 12000,
+ "default": 6000,
+ "whole_number": true,
+ "unit": "UTF-16 code units (JavaScript string length)"
+ },
+ "query_chars_ranked": 2000,
+ "own_recent_window_hours": 24
+ },
+ "arguments_checked": "query, max_chars and query_keep are checked before any read, also for an unlinked person (invalid_params); a longer query is never refused (recall's question is refused over 2000: invalid_params reason question_too_long) and is ranked on its first 2000 characters, or on its last 2000 with query_keep tail; a call that sends query_keep gets structuredContent.query_truncated, true when the query was cut",
+ "content": {
+ "line": "- <fact> (<YYYY-MM-DD>; <kind>)",
+ "never": [
+ "page bodies",
+ "fence markers",
+ "heading markers",
+ "line breaks or control characters inside a fact"
+ ],
+ "bounded_by": "max_chars: as many whole lines as fit; facts left out set structuredContent.truncated, with no marker line, because every line is one fact"
+ },
+ "order": [
+ "own facts from the last 24 hours, newest first",
+ "facts the person may read, ranked by query"
+ ],
+ "ranking": "keyword-only unless an embedding provider is configured (no embedding call on a keyless brain)",
+ "structured_content": {
+ "facts": [
+ {
+ "id": "string",
+ "text": "string",
+ "date": "YYYY-MM-DD",
+ "kind": "string",
+ "arm": "\"own\" | \"ranked\"",
+ "own_page": "boolean"
+ }
+ ],
+ "truncated": "boolean",
+ "query_truncated": "boolean, only when the call sent query_keep",
+ "code": "actor_unlinked (only on unlinked_recall)"
+ },
+ "arm": "own: the person's own fact from the last 24 hours; ranked: matched by query (a fact found both ways is own); a call that names sources answers ranked rows only, unless the credential reads named sources as the person (--attest-read person)",
+ "own_page": "true: the fact sits on the person's own member page in the connection's source, the same test forget_fact applies, so forget_fact accepts it on ownership; false: forget_fact for this person answers fact_not_found. Independent of arm (an own-page fact older than 24 hours is ranked); false on every row of a scope read (a call that names sources, unless the credential reads them as the person)",
+ "scope_read": {
+ "arguments": [
+ "source_id",
+ "source_ids"
+ ],
+ "rule": "a call that names sources is read as their audience, never as the person: no own facts first and no member-page fact; a page restricted to named readers stays hidden; privacy is never relaxed",
+ "sources": "narrowed inside the credential's read grant like recall's source_ids; a source outside it is permission_denied; source_id and source_ids together read their intersection, and an empty intersection reads nothing",
+ "without_sources": "the person read above (own recent facts, then what the person may read across the read grant): use it only for the person's own conversations"
+ }
+ },
+ "unlinked_recall": {
+ "isError": false,
+ "content": [
+ {
+ "type": "text",
+ "text": ""
+ }
+ ],
+ "structuredContent": {
+ "facts": [],
+ "truncated": false,
+ "code": "actor_unlinked"
+ }
+ },
+ "memory_write": {
+ "limits": {
+ "facts": {
+ "min": 1,
+ "max": 20
+ },
+ "provenance_chars": 200,
+ "idempotency_key": {
+ "pattern": "^[\\x21-\\x7e]{1,128}$"
+ },
+ "kinds": [
+ "event",
+ "preference",
+ "commitment",
+ "belief",
+ "fact"
+ ],
+ "provenance": "one line: no line breaks or control characters, and not starting with qm: (gbrain adds qm:<actor id> itself)",
+ "valid_from": "YYYY-MM-DD or YYYY-MM-DDTHH:MM[:SS[.fraction]][Z|±HH:MM], a real calendar day in years 0001-9999"
+ },
+ "validation": "every fact is checked before any is saved: one bad fact refuses the whole call with invalid_params and the idempotency_key stays unused",
+ "saved_as": {
+ "page": "memory/members/<member>",
+ "readers": [
+ "member:<member>"
+ ],
+ "visibility": "private",
+ "provenance": "qm:<actor id>; <caller provenance>"
+ },
+ "request_id": "uuidv5(uuidv5(namespace, \"member:<member>\"), idempotency_key) for the first fact; later facts derive from it",
+ "replay": "the same idempotency_key from the same person returns the first receipt; from another person it is a separate write",
+ "retries": "never retried server-side; a write still publishing answers pending",
+ "committed": {
+ "content": "Saved <N> fact(s).",
+ "structuredContent": {
+ "status": "committed",
+ "request_id": "uuid",
+ "fact_ids": [
+ "string"
+ ]
+ },
+ "fact_ids": "distinct; facts repeating one claim in a call share one id, and <N> counts distinct facts"
+ },
+ "pending": {
+ "content": "Accepted <N> fact(s); <M> still publishing.",
+ "structuredContent": {
+ "status": "pending",
+ "request_id": "uuid",
+ "fact_ids": [
+ "string"
+ ],
+ "pending_request_ids": [
+ "uuid"
+ ]
+ },
+ "poll": "get_write_request {request_id}"
+ },
+ "scope_write": {
+ "argument": "source_id",
+ "rule": "names one of the credential's scope sources (attest_sources, which the brain operator sets on the host); checked on the call and again when the write publishes, so a source the operator drops refuses queued writes; omit it to save for the person alone, exactly as without it",
+ "saved_as": {
+ "page": "memory/scope",
+ "readers": "none: whoever holds read on the scope source, which only scope credentials may",
+ "visibility": "world",
+ "provenance": "qm:<actor id>; <caller provenance>"
+ },
+ "request_id": "uuidv5(uuidv5(namespace, \"member:<member>#source:<source_id>\"), idempotency_key) for the first fact; later facts derive from it; without source_id the member derivation above is unchanged",
+ "replay": "per person and source: the same idempotency_key in another source is a separate write",
+ "pending": "a scope source with a repository publishes git-first through its writer and answers pending until it commits; a source without one commits to the database",
+ "recall": "read it with memory_recall source_id (read as the scope); a memory_recall without sources never reads a scope source",
+ "withdrawal": "forget and forget_fact reach only the person's own member page, so a scope fact is not_found remotely"
+ }
+ },
+ "memory_propose": {
+ "opt_in": "not a default attested operation: the brain operator grants it with cancel_write_request beside it (gbrain auth rescope --client <id> --attest-actor qm --attest-ops cancel_write_request,get_write_request,memory_propose,memory_recall,memory_write); the client's bound_slug_prefixes must cover the pages it proposes to, and its allowed_operations must not list add_timeline_entry, add_link, put_page or edit_page",
+ "needs": "an attested person (x-qm-actor; with none, actor_not_attested reason actor_required) who may read the target and a link's to page (else page_not_found)",
+ "kinds": {
+ "timeline": {
+ "required": [
+ "date",
+ "summary"
+ ],
+ "optional": [
+ "detail",
+ "source"
+ ],
+ "date": "YYYY-MM-DD",
+ "summary": "one line",
+ "source": "one line"
+ },
+ "link": {
+ "required": [
+ "to"
+ ],
+ "optional": [
+ "link_type",
+ "context",
+ "valid_from",
+ "valid_until"
+ ],
+ "link_type": "a type the schema pack declares",
+ "context": "one line",
+ "valid_from": "YYYY-MM-DD",
+ "valid_until": "YYYY-MM-DD"
+ },
+ "other_kind_fields": "refused: invalid_params reason proposal_kind_field"
+ },
+ "expected_revision": "optional: the revision shown to the person (get_page revision); a page that moved since is refused with invalid_params reason proposal_revision_changed",
+ "limits": {
+ "payload_chars": {
+ "max": 1000,
+ "config": "proposals.max_payload_chars",
+ "counts": "summary, detail and source together, or a link's context",
+ "refusal": "invalid_params reason proposal_too_large"
+ },
+ "pending_per_actor": {
+ "default": 10,
+ "config": "proposals.max_pending_per_actor",
+ "refusal": "proposals_pending_limit reason actor"
+ },
+ "pending_per_credential": {
+ "default": 50,
+ "config": "proposals.max_pending_per_credential",
+ "refusal": "proposals_pending_limit reason credential"
+ },
+ "ttl_hours": {
+ "default": 168,
+ "config": "proposals.ttl_hours",
+ "min": 1,
+ "max": 720
+ },
+ "idempotency_key": {
+ "pattern": "^[\\x21-\\x7e]{1,128}$"
+ }
+ },
+ "held": "nothing is written until the brain owner approves; while it waits the proposed text is never in search, recall, git or an export, and no receipt carries it",
+ "request_id": "derived from the credential, the person and idempotency_key: one request id from proposal to publication",
+ "replay": "the same idempotency_key with the same fields, from the same person and credential, returns that proposal's current state in status; with other fields it is idempotency_conflict; from another person or credential it is a separate proposal",
+ "retention": "a closed proposal (denied, expired, cancelled, failed, conflict or approved) is deleted proposals.retention_days days after it closed (default 30); after that its request_id answers not_found while no write holds it, an approved write's receipt no longer carries proposal, and the same idempotency_key starts a new proposal under the same request_id, so never resend an old key to learn how a proposal ended",
+ "awaiting": {
+ "content": "the result as JSON",
+ "structuredContent": {
+ "status": "awaiting_owner",
+ "request_id": "uuid",
+ "kind": "\"timeline\" | \"link\"",
+ "target": "string",
+ "expires_at": "string (ISO 8601)",
+ "text": "string"
+ }
+ },
+ "receipt": {
+ "read": "get_write_request {request_id}",
+ "structured_content": {
+ "request_id": "string",
+ "state": "\"awaiting_owner\" | \"denied\" | \"expired\" | \"cancelled\" | \"failed\" | \"conflict\"",
+ "retry_after_ms": "number | null",
+ "operation": "\"add_timeline_entry\" | \"add_link\"",
+ "source_id": "string",
+ "slug": "string",
+ "created_at": "string",
+ "updated_at": "string",
+ "proposal": {
+ "kind": "\"timeline\" | \"link\"",
+ "target": "string",
+ "expires_at": "string"
+ }
+ },
+ "optional": {
+ "proposal.to": "string: a link's to page",
+ "decision": "object {reason, decided_at} once the proposal is closed: denied carries the owner's reason",
+ "write_error": "string: why approval closed it (failed: actor_unlinked, actor_not_attested, permission_denied, page_not_found or source_changed; conflict: revision_changed or link_target_changed)"
+ },
+ "states": {
+ "known": [
+ "awaiting_owner",
+ "approved",
+ "denied",
+ "expired",
+ "cancelled",
+ "failed",
+ "conflict"
+ ],
+ "held": "awaiting_owner",
+ "closed": [
+ "denied",
+ "expired",
+ "cancelled",
+ "failed",
+ "conflict"
+ ],
+ "approved": "get_write_request answers the write's own receipt (personal_tools get_write_request, published when committed) plus proposal {kind, target, to?, decided_at} until the proposal row is deleted (retention)",
+ "unknown": "a state not listed here means unknown, not published: never report the proposal as written; poll again or report it as unknown",
+ "poll": "while awaiting_owner, after retry_after_ms (300000, or the time to expiry when sooner)"
+ },
+ "visibility": "only the person it was made for, through the same credential; anyone else gets not_found. The proposer still reads and cancels held proposals after memory_propose is revoked; the owner's upkeep then closes them failed actor_not_attested"
+ },
+ "cancel": "cancel_write_request {request_id}: the proposer's cancel. An awaiting_owner proposal becomes cancelled; a closed one is answered unchanged. The answer is the proposal receipt as JSON in content, with no structuredContent"
+ },
+ "errors": {
+ "shape": {
+ "isError": true,
+ "content": "one JSON text block with top-level code, message, suggestion and optional reason and fix",
+ "structuredContent": {
+ "error": {
+ "code": "string",
+ "message": "string",
+ "reason": "string?",
+ "write_error": "string?",
+ "fix": "object?"
+ }
+ }
+ },
+ "applies_to": "every refusal of memory_recall, memory_write and memory_propose, and of a personal tool called with x-qm-actor, including the transport's scope and unknown-tool refusals",
+ "codes": [
+ {
+ "code": "actor_not_attested",
+ "class": "host_only",
+ "summary": "A call named the person it serves (the x-qm-actor header or the acting_user argument) in a way gbrain does not honour: the credential holds no attest right, the operation is not in its attested operations, the argument differs from the header, names anyone but a member-bound credential's own member, or comes without an attested header from a credential bound to no member, or the id is not 1-256 visible ASCII characters; or a write that saves only as an attested person (memory_write) named none; or the request carries x-qm-audience, a channel audience gbrain does not serve yet. Nothing was read or written.",
+ "suggestion": "Read reason: no_attest_right and op_not_attested are the brain operator's call (gbrain auth rescope --client <id> --attest-actor qm [--attest-ops <list>]); argument_mismatch, argument_without_attestation, invalid_actor_id, actor_required and audience_not_supported are fixed in the calling harness.",
+ "docs": "docs/guides/write-refusals.md#actor_not_attested",
+ "reasons": [
+ {
+ "reason": "no_attest_right",
+ "fixed_by": "brain_operator",
+ "fix": "gbrain auth rescope --client <id> --attest-actor qm on the brain host; a client that already holds the right takes a new token with grant_type=client_credentials."
+ },
+ {
+ "reason": "op_not_attested",
+ "fixed_by": "brain_operator",
+ "fix": "gbrain auth rescope --client <id> --attest-actor qm --attest-ops <list>; a deferred operation cannot be attested yet."
+ },
+ {
+ "reason": "argument_mismatch",
+ "fixed_by": "calling_harness",
+ "fix": "Send acting_user equal to the x-qm-actor header (with no header, on a credential bound to a member: that member id or a canonical id linked to it), or omit it."
+ },
+ {
+ "reason": "argument_without_attestation",
+ "fixed_by": "calling_harness",
+ "fix": "Remove acting_user, or send the x-qm-actor header from a credential holding the attest right; a credential bound to no member never sends acting_user alone. detail missing=<attest_right|x-qm-actor, comma-separated> names what this call lacked."
+ },
+ {
+ "reason": "invalid_actor_id",
+ "fixed_by": "calling_harness",
+ "fix": "Send the canonical id unchanged: 1-256 visible ASCII characters, no spaces."
+ },
+ {
+ "reason": "actor_required",
+ "fixed_by": "calling_harness",
+ "fix": "memory_write and memory_propose save only as an attested person: send x-qm-actor from a credential holding the attest right."
+ },
+ {
+ "reason": "audience_not_supported",
+ "fixed_by": "calling_harness",
+ "fix": "Send the call without x-qm-audience; channel turns are refused until wave 2 and nothing is read or written."
+ }
+ ],
+ "note": "With no x-qm-actor header, acting_user is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it); the call then runs exactly as the credential."
+ },
+ {
+ "code": "actor_unlinked",
+ "class": "host_only",
+ "summary": "An attested call named a person whose canonical id is not linked to an enabled member of this brain (never linked, unlinked, or the member is disabled or removed), so nothing was read or written.",
+ "suggestion": "The brain operator links the id to its member: gbrain access member link <member> --qm <id> (or enables the member).",
+ "docs": "docs/guides/write-refusals.md#actor_unlinked",
+ "note": "Refuses memory_write. memory_recall answers it as a success instead (unlinked_recall)."
+ },
+ {
+ "code": "on_behalf_of_invalid_audience",
+ "class": "caller",
+ "summary": "A shared agent's request named its audience (the X-Gbrain-On-Behalf-Of header or request-level _meta.on_behalf_of) in a form gbrain does not accept: empty, more than 50 entries, an entry that is not a member id, group:<id> or guest, or a header and _meta that name different audiences. Nothing was read.",
+ "suggestion": "Fix the harness code that sets the audience: 1-50 entries, each a member id, group:<id> or guest, the same in the header and _meta when both are sent.",
+ "docs": "docs/guides/write-refusals.md#on_behalf_of_invalid_audience",
+ "note": "Sent when x-qm-actor is combined with an on_behalf_of audience (X-Gbrain-On-Behalf-Of or request-level _meta.on_behalf_of). QM classifies it as a failed call."
+ },
+ {
+ "code": "invalid_params",
+ "class": "caller",
+ "summary": "A parameter is missing, has the wrong type, or has an invalid value.",
+ "docs": "docs/guides/error-codes.md#invalid_params",
+ "note": "Bad arguments, refused before anything is saved. A reused idempotency_key with different facts carries write_error idempotency_conflict; a claim the person forgot carries the fact_withdrawn message. A memory_write whose source_id is the credential's own source carries reason source_is_member_source (omit source_id instead). recall refuses a question over 2000 UTF-16 code units with reason question_too_long and detail max_chars=2000 received_chars=<n>; nothing is read and the question is never cut, so shorten it and retry. memory_propose refuses a field of the other kind (reason proposal_kind_field), proposed text over proposals.max_payload_chars (reason proposal_too_large) and an expected_revision the page has moved past (reason proposal_revision_changed: show the person the page again and propose against its current revision); nothing is saved."
+ },
+ {
+ "code": "scope_denied",
+ "class": "host_only",
+ "summary": "The connection lacks the scope this memory verb requires.",
+ "docs": "docs/guides/error-codes.md#scope_denied",
+ "note": "The write is not authorized, including a member page whose readers name anyone but its member (squatted or widened): nothing is saved."
+ },
+ {
+ "code": "insufficient_scope",
+ "class": "host_only",
+ "summary": "The connection lacks the OAuth scope the operation requires.",
+ "docs": "docs/guides/error-codes.md#insufficient_scope",
+ "note": "The credential lacks the OAuth scope the tool needs (memory_write needs write); refused by the transport before the call runs."
+ },
+ {
+ "code": "unknown_tool",
+ "class": "caller",
+ "summary": "The named tool does not exist or is not callable on this connection.",
+ "docs": "docs/guides/error-codes.md#unknown_tool",
+ "note": "The tool is not callable on this connection (its surface or bound-operation list leaves it out)."
+ },
+ {
+ "code": "not_found",
+ "class": "caller",
+ "summary": "The requested resource does not exist or is not visible to this caller.",
+ "docs": "docs/guides/error-codes.md#not_found",
+ "note": "get_write_request or cancel_write_request for a request id (a write or a proposal) that is not this person's, or forget for a fact that is not on this person's own member page."
+ },
+ {
+ "code": "fact_not_found",
+ "class": "caller",
+ "summary": "Fact not found.",
+ "docs": "docs/guides/error-codes.md#fact_not_found",
+ "note": "forget_fact for a fact that is not on this person's own member page."
+ },
+ {
+ "code": "unavailable",
+ "class": "unavailable",
+ "summary": "A required dependency or capability cannot serve this request.",
+ "docs": "docs/guides/error-codes.md#unavailable",
+ "note": "memory_recall could not read the fact candidates (a database failure); retry the same call."
+ },
+ {
+ "code": "permission_denied",
+ "class": "host_only",
+ "summary": "This caller is not authorized for the operation.",
+ "docs": "docs/guides/error-codes.md#permission_denied",
+ "note": "memory_recall named a source (source_id or source_ids) outside the credential's read grant; nothing was read. memory_write named a source_id that is not one of the credential's scope sources (reason source_not_attested, also at publication after the operator drops it), or the scope page names readers (reason scope_page_not_shared); nothing was saved. memory_propose to a page outside the credential's bound_slug_prefixes or write visibility; nothing was saved."
+ },
+ {
+ "code": "page_not_found",
+ "class": "caller",
+ "summary": "No page with that slug exists in the selected source.",
+ "docs": "docs/guides/error-codes.md#page_not_found",
+ "note": "get_page for a page that does not exist or that the person may not read; one answer for both. memory_propose for a target or link to page that does not exist or that the person may not read; nothing was saved."
+ },
+ {
+ "code": "result_too_large",
+ "class": "caller",
+ "summary": "The tool's result is larger than this connection can carry in one response, so it was replaced by this error; nothing was cut.",
+ "suggestion": "Ask for less in one call: a window (get_page body: 'window'), a page of rows (limit / from_index), or metadata only (get_versions include_body: false).",
+ "docs": "docs/guides/windowed-reads.md#result_too_large",
+ "note": "A personal read whose answer, with structuredContent, is over the connection's result cap; nothing was returned. Ask for less: get_page body: \"outline\" or \"window\", or a smaller limit."
+ },
+ {
+ "code": "idempotency_conflict",
+ "class": "caller",
+ "summary": "The request_id already belongs to a different accepted operation.",
+ "docs": "docs/guides/error-codes.md#idempotency_conflict",
+ "note": "memory_propose with an idempotency_key this person already used for a different proposal; nothing was saved and the earlier proposal keeps its receipt. Send the new proposal with a new key."
+ },
+ {
+ "code": "proposals_pending_limit",
+ "class": "retryable",
+ "summary": "Too many memory proposals already await the owner for this person (proposals.max_pending_per_actor) or this credential (proposals.max_pending_per_credential), so this one was not saved.",
+ "suggestion": "Wait for the owner to decide or for a proposal to expire, or cancel one with cancel_write_request; the operator sets the caps.",
+ "docs": "docs/guides/qm.md#proposed-writes",
+ "note": "memory_propose when this person (reason actor, proposals.max_pending_per_actor, default 10) or this credential (reason credential, proposals.max_pending_per_credential, default 50) already has that many proposals awaiting the owner; nothing was saved. Wait for the owner, or cancel one with cancel_write_request."
+ },
+ {
+ "code": "source_changed",
+ "class": "caller",
+ "summary": "The source changed during the operation; nothing was committed.",
+ "docs": "docs/guides/error-codes.md#source_changed",
+ "note": "memory_propose when the connection's write source is archived or not registered; nothing was saved."
+ }
+ ]
+ },
+ "wave_2": {
+ "audience_header": "x-qm-audience",
+ "encoding": "base64url of a JSON array of canonical ids",
+ "status": "refused until wave 2",
+ "refusal": {
+ "code": "actor_not_attested",
+ "reason": "audience_not_supported",
+ "tools_call": "errors.shape, with or without x-qm-actor",
+ "other_methods": "JSON-RPC error -32600 whose data carries code and reason (tools/list, resources/list, resources/read)"
+ }
+ }
+}
diff --git a/docs/guides/qm.md b/docs/guides/qm.md
index 54ce27c713..acd9bbe72c 100644
--- a/docs/guides/qm.md
+++ b/docs/guides/qm.md
@@ -4,7 +4,7 @@ QM, a trusted system that already knows who each person is, keeps per-person
memory in a brain through two MCP tools: `memory_recall` reads what the person may
read, and `memory_write` saves facts only they read back. Both run as the person QM
names in the `x-qm-actor` header. The wire contract QM vendors is
-[`docs/contracts/qm-memory-provider/v1.json`](../contracts/qm-memory-provider/README.md); `v2.json` adds scope reads and writes, `v3.json` the personal tools for the person's own DM, and `v4.json` owner-approved proposals (`memory_propose`), which personal tools are scope reads, and each recalled fact's `own_page`.
+[`docs/contracts/qm-memory-provider/v1.json`](../contracts/qm-memory-provider/README.md); `v2.json` adds scope reads and writes, `v3.json` the personal tools for the person's own DM, `v4.json` owner-approved proposals (`memory_propose`), which personal tools are scope reads, and each recalled fact's `own_page`, and `v5.json` marks `context_pack` as a scope read.
## Set up on the brain host
@@ -65,10 +65,12 @@ person's restricted pages and their member page read as missing, a source outsid
the grant is refused, and `__all__` or `all_sources` is refused (`invalid_params`).
`volunteer_context` refuses `stats: true` there. An agent job submitted for the
person reads the same way. List the ops a client needs with `--attest-ops`.
-`context_pack` is not a scope read yet: on a client that reads named sources as the
-scope it is refused (`invalid_params`) when it names `source_id`, `source_ids`,
-`all_sources` or `entity_refs`, so keep it off a client that serves shared turns.
-Contract v4 marks each personal tool `scope_read: true` or `false` to match.
+`context_pack` that names `source_id` reads that one source the same way: its entities,
+the core block, the counterparty brief and hot facts all come from that source. Each
+`entity_refs` entry must name the same `source_id`; `entity_refs` without `source_id`,
+an entry in another source, or `session_id` is refused (`invalid_params`) before
+anything is read. Contract v4 marks each personal tool `scope_read: true` or `false`;
+v5 adds `context_pack` to the marked tools.
Set how each client reads named sources with `--attest-read`:
diff --git a/docs/mcp/ADMIN.md b/docs/mcp/ADMIN.md
index ba0346dc71..62f7c6ebdd 100644
--- a/docs/mcp/ADMIN.md
+++ b/docs/mcp/ADMIN.md
@@ -302,6 +302,8 @@ gbrain mcp admin memory-proposals approve <request_id> --dry-run --url … --adm
```
The other commands are `--attest-actor none` (clear the right),
+`attest CLIENT_ID --attest-read person|scope|none` (how a call that names sources reads them,
+as `gbrain auth rescope --attest-read` sets it),
`member-set ID --email ADDR|none`, `member-disable|member-enable ID`, `members [--all]`,
`unlink --qm ID` and `links [--member ID]`. A member's email is optional,
stored lower-case and unique per brain; `link --email` finds the one member that
diff --git a/scripts/build-qm-memory-contract.ts b/scripts/build-qm-memory-contract.ts
index df9d8ef394..bcfdbd4fc1 100644
--- a/scripts/build-qm-memory-contract.ts
+++ b/scripts/build-qm-memory-contract.ts
@@ -1,6 +1,6 @@
#!/usr/bin/env bun
/**
- * GST-359 D: docs/contracts/qm-memory-provider/v1.json to v4.json, the QM memory-provider contracts, generated from the
+ * GST-359 D: docs/contracts/qm-memory-provider/v1.json to v5.json, the QM memory-provider contracts, generated from the
* live operation registry, the actor model and the error catalogue. test/qm-memory-contract.test.ts fails on drift.
* bun scripts/build-qm-memory-contract.ts write every fixture
* bun scripts/build-qm-memory-contract.ts --check exit 1 when a committed fixture is stale
@@ -9,6 +9,7 @@
* GST-1158 F1 v3 adds the personal tools (own DM, read as the attested person) with frozen result shapes, forget_fact
* among them, and each memory_recall fact's arm (F5). GST-2407 v4 adds memory_propose (an owner-approved write on a shared
* page) with its proposal receipt, the E1 scope_read marking on each personal tool, and each memory_recall fact's own_page.
+ * GST-2407 v5 marks context_pack scope_read: a call that names its source reads only that source as its audience.
*/
import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
@@ -24,14 +25,17 @@ import { IDEMPOTENCY_KEY_RE, MEMORY_RECALL_MAX_CHARS, MEMORY_RECALL_QUERY_CHARS,
import { WRITE_REQUEST_STATES } from '../src/core/persistence/types.ts';
import { TERMINAL_STATES } from '../src/core/persistence/model.ts';
-export type QmContractVersion = 1 | 2 | 3 | 4;
+export type QmContractVersion = 1 | 2 | 3 | 4 | 5;
export const QM_CONTRACT_PATHS: Record<QmContractVersion, string> = {
1: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v1.json'),
2: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v2.json'),
3: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v3.json'),
4: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v4.json'),
+ 5: join(import.meta.dir, '..', 'docs', 'contracts', 'qm-memory-provider', 'v5.json'),
};
export const QM_CONTRACT_PATH = QM_CONTRACT_PATHS[1];
+/** The personal tools v4 marks scope_read, frozen: context_pack is marked from v5 on. */
+const V4_SCOPE_READ_OPS: ReadonlySet<string> = new Set(['entity', 'find_experts', 'get_backlinks', 'get_page', 'get_timeline', 'query', 'volunteer_context', 'whois']);
/** The arguments v1 publishes per tool, frozen: later arguments appear from v2 on. */
const V1_PARAMS: Record<string, readonly string[]> = { memory_recall: ['query', 'max_chars', 'acting_user'], memory_write: ['facts', 'idempotency_key', 'acting_user'] };
/** The arguments v2 publishes per tool, frozen: #8694's query_keep appears from v3 on. */
@@ -174,6 +178,7 @@ export function buildQmMemoryContract(version: QmContractVersion): Record<string
const v2 = version > 1;
const v3 = version > 2;
const v4 = version > 3;
+ const v5 = version > 4;
const codes: readonly (keyof typeof CODES)[] = v4 ? [...ERROR_CODES, 'permission_denied', 'page_not_found', 'result_too_large', 'idempotency_conflict', 'proposals_pending_limit', 'source_changed'] : v3 ? [...ERROR_CODES, 'permission_denied', 'page_not_found', 'result_too_large'] : v2 ? [...ERROR_CODES, 'permission_denied'] : ERROR_CODES;
const base: Record<string, string | undefined> = v2 ? { ...ERROR_NOTES,
actor_not_attested: 'With no x-qm-actor header, acting_user is accepted only from a credential bound to a member and only naming that member (its member id or a canonical id linked to it); the call then runs exactly as the credential.',
@@ -208,11 +213,13 @@ export function buildQmMemoryContract(version: QmContractVersion): Record<string
...(v4 ? { scope_read: {
marked: 'scope_read: true: a call that names sources (source_id, source_ids or all_sources, where the tool\'s input_schema declares them) reads those sources as their audience, never as the person, as memory_recall\'s scope_read does: no member-page fact, no page restricted to named readers, and privacy is never relaxed',
every_source: "under a scope read, source_id '__all__', '__all__' in source_ids and all_sources: true are refused with invalid_params; nothing is read",
- unmarked: 'scope_read: false: the tool reads as the person whatever the call names; context_pack refuses a call that names sources or entity_refs with invalid_params (nothing is read) unless the credential reads named sources as the person',
+ unmarked: v5 ? 'scope_read: false: the tool reads as the person whatever the call names'
+ : 'scope_read: false: the tool reads as the person whatever the call names; context_pack refuses a call that names sources or entity_refs with invalid_params (nothing is read) unless the credential reads named sources as the person',
+ ...(v5 ? { context_pack: 'a context_pack scope read names one source in source_id and reads only it: entities, cards, core memory, the counterparty brief and hot facts; entity_refs also name sources, and each must carry that same source_id; a call with entity_refs and no source_id, an entity_refs entry in another source, or session_id is refused with invalid_params, and nothing is read' } : {}),
as_person: 'a credential the brain operator binds with --attest-read person reads named sources as the person instead, narrowed to those sources',
without_sources: 'the person read (read_as above)',
} } : {}),
- tools: [...QM_PERSONAL_OPS].sort().map(name => ({ ...toolEntry(name, version), personal_only: true, ...(v4 ? { scope_read: SCOPE_READ_OPS.has(name) } : {}), result: PERSONAL_RESULTS[name],
+ tools: [...QM_PERSONAL_OPS].sort().map(name => ({ ...toolEntry(name, version), personal_only: true, ...(v4 ? { scope_read: (v5 ? SCOPE_READ_OPS : V4_SCOPE_READ_OPS).has(name) } : {}), result: PERSONAL_RESULTS[name],
...(v4 && name === 'get_write_request' ? { proposal_receipt: 'the fields and states in result are a write\'s receipt; a request_id from memory_propose that no write holds yet answers memory_propose.receipt instead, with its own fields and states (awaiting_owner, denied, expired, cancelled, failed, conflict)' } : {}) })),
} } : {}),
memory_recall: {
@@ -314,7 +321,7 @@ export function renderQmMemoryContract(version: QmContractVersion): string {
if (import.meta.main) {
let stale = false;
- for (const version of [1, 2, 3, 4] as const) {
+ for (const version of [1, 2, 3, 4, 5] as const) {
const path = QM_CONTRACT_PATHS[version];
const fresh = renderQmMemoryContract(version);
if (process.argv.includes('--check')) {
diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsv
index b1efc2ba87..d5cccf5878 100644
--- a/scripts/module-size-limits.tsv
+++ b/scripts/module-size-limits.tsv
@@ -49,6 +49,6 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: link
src/core/search/evidence-delivery.ts 1759 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move); +7 GBRA-205: EvidencePlan.titleHeader and DeliveryMeta.title_header (interface fields cannot move) and the titles option on the header loader (logic in search/evidence-date.ts; the query budget key lives in search/evidence-packing.ts); +11 #7600: assemble_evidence quotes conversation rows and capEvidenceToBudget counts the quote fence (logic in search/transcript-quote.ts); +2 GBRA-156 /ship review: the cut-path admission and title room count the quote fence; +2 GBRA-156 /ship review pass 2: capEvidenceToBudget counts the fence only for the paths that fence (quote flag; recall counts the text as returned); +4 GST-687: page evidence and the extractive fallback quote below-owner-tier text for untrusted readers (untrusted flag; logic in search/transcript-quote.ts)
src/commands/config.ts 1530 ratchet +1 GBRA-216: recall.* config set value refusal (facts/recall-config.ts); +1 GBRA-216: config set refuses a dream.claim_conflicts.mode other than propose|off (refusal in facts/claim-conflicts.ts); new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal); +4 GBRA-377 PR B: skills.resolver.* file-plane routing (doc line, the one-line router and its two dispatch lines; logic in core/setup/skill-resolver-config.ts)
src/commands/mcp-expose.ts 1519 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts); +7 GBRA-199: --surface help lines, surfaceChosen option field and the advertise pass-through (registrationAdvertise in core/mcp-registration.ts)
-src/core/behavior-change-notice.ts 1761 ratchet +4 train R: #7491/#7492 keyword_identifier_probe and keyword_slug_handles rows and their comment, #7175 keyword phrase row; the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +1 GBRA-156 #7593: private_pages_granted_sources row (re-summed at the 0.60.527.0 merge: 1574 + 1); +3 GBRA-200 comment, write-grant refusal and degraded-stamp rows (re-summed at the 0.60.562.0 merge: 1615 + 3); +2 GBRA-280 get_page selector-precedence row and comment (re-summed at the 0.60.569.0 merge: 1619 + 2); the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move); +1 GST-1251: skillopt_loop_deprecated_gst1251 row (rows are data and cannot move); +1 GST-1209 follow-up: untiled_hold_repair_gst1209 row (rows are data and cannot move); +1 GBRA-283 B3a: embedded_scope_required_gbra283 row (rows are data and cannot move); re-summed at the train R merge with v0.60.574.0: 1623 + 4; +2 GST-1387: refresh_fence_refusal_gst1387 row and its comment (rows are data and cannot move); re-summed at the memory train #8481 merge with v0.60.578.0 (1643 measured); +3 GBRA-253 #8109 rows (frontmatter_drift_write_8109, contacts_activity_advance_8109, contact_rows_dedupe_8109; rows are data and cannot move), re-summed at the master v0.60.581.0 merge: 1643 + 3 = 1646 measured; +3 #8123 part C rows: sync_write_through_off_writeback_7084, managed_sync_dry_run_counts_7087, frontmatter_missing_source_dir_7889 (since TBD until the merge slot; re-summed at the 0.60.583.0 merge: 1646 + 3); +4 PR B commit_ledger_prb, doctor_foreign_writers_prb and sources_guard_prb rows and their comment (rows are data and cannot move; since TBD until the merge slot); +1 PR B #8615: file_drift_held_needs_prefer_8615 row; +1 PR B #8617: refresh_source_changed_retry_8617 row; +1 PR B #8662: commit_push_checkout_not_a_source_8662 row (since TBD until the merge slot; rows are data and cannot move); +2 PR B refresh_barrier_prb and commit_push_base_prb rows (re-summed: 1658 measured); +3 convergence PR A: the wave comment and two rows (conversion_content_evidence_pr_a, git_gap_live_pages_pr_a; since TBD until the merge slot; rows are data and cannot move); re-summed at the gate-ahead on master v0.60.592.0 plus #8711: 1658 + 3 = 1661 measured; +4 GST-1094/GST-900 rows (memory_recall scope-read, member-bound acting_user, recall max_chars, unknown_param _meta-only) and +1 qm_scope_writes_gst1113 and +1 recall_question_terms_gst1304 rows (rows are data and cannot move), re-summed at the 0.60.595.0 slot merge: 1661 + 6; +1 GST-1582 refresh_barrier_import_gst1582 row (since TBD until the merge slot; rows are data and cannot move); +2 GST-1601 source_changed_origin_gst1601 and adopt_local_edits_gst1601 rows (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.596.0 merge: 1668 + 2; +1 GST-1623 refresh_barrier_capacity_gst1623 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.599.0 merge: 1670 + 1; +2 GBRA-224 W1 release_channel_stable_default row and its comment; +1 GST-1623 refresh_barrier_later_write_gst1623 row (#8765; rows are data and cannot move); +5 #8766 GST-1623 items 4/6-9 and #8755: the wave comment and four rows (doctor_foreign_writers_partial_gst1623, commit_push_enclosing_repo_gst1623, owner_guard_fail_closed_gst1623, adopt_local_edits_hardening_8755) and +1 managed_sync_kind_reserved_8765 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on master v0.60.608.0 plus #8798: 1674 + 6; +1 GST-1853 refresh_barrier_aborted_refresh_sync_gst1853 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.613.0 merge: 1680 + 1; +1 GST-1674 refresh_refused_merge_recovery_gst1674 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.614.0 merge: 1681 + 1; +1 #8824/#8826/#8767: adopt_local_edits_replay_markers_8824 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8837: 1682 + 1; +1 url_source_origin row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8834: 1683 + 1; +1 #8828: the refresh_replan_own_commits_8828 row (1684 + 1 at the 0.60.618.0 slot); +1 the managed commit-push unpublished-count row; +1 the refresh publish-diverged default row; +1 GST-2051 ungranted_member_writes_gst2051 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-731 think_window_trajectory_gst731 row and +1 GST-1602 purge_cancels_deferred_write_gst1602 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8915 v0.60.621.0: 1688 + 2; +1 GST-2059: owner_reads_private row; +1 #8888: the record-origin checkout lock-down row (re-summed at the Q6 stack on #8934 v0.60.625.0: 1691 + 1); +1 GST-1158 F9: the attest_direct_page_writes_deferred_gst1158 row (since TBD until the merge slot); +1 GST-1158 E1/F3/F4 rows (since TBD until the merge slot), re-summed at the master merge; +1 GBRA-284 personal_sources_gbra284 row (since TBD until the merge slot) (re-summed at the QM wave merge onto master v0.60.626.0: 1692 + 3); +1 GST-1158 F9: the attest_direct_page_writes_deferred_gst1158 row (since TBD until the merge slot); +1 GST-1158 v3: the qm_personal_structured_gst1158 row (since TBD until the merge slot); +1 #8477 GST-1158 F2 personal-tools row at the QM wave merge (1695 + 1); +1 GST-1158 F9: the attest_direct_page_writes_deferred_gst1158 row (since TBD until the merge slot); +1 #8483 memory_propose row at the QM wave merge (1696 + 1); +1 GST-1094 gap 4: the qm_admin_http_gst1094 row (since TBD until the merge slot); +1 GST-1158: the member_email_link_gst1158 row (since TBD until the merge slot); +2 #8479 member-email rows at the QM wave merge (1697 + 2); +1 GST-2112: ingest_keeps_readers_gst2112 row (re-summed at the Q7 v0.60.627.0 merge: 1692 + 1); +1 #8982 federated_member_writes_8982 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-2116 commit_push_skipped_paths_gst2116 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the Q10 slot on #9009 ee0f4a78: 1694 + 1; +1 GST-2118 pending_ledger_flagged_gst2118 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the Q12 slot on #9016 afb49de5: 1695 + 1; +1 GBRA-431: read_scope_params_gbra431 row (rows are data and cannot move), re-summed at the #9032 stack merge: 1697 measured; +2 GST-2201 sync_restored_file_gst2201 and purge_keeps_committed_file_gst2201 rows (since is the current VERSION until the merge slot; +1 GST-2243 remember_share_gst2243 row (re-summed at the #9098 stack merge: 1699 + 1); +1 GST-2312 #9024 sync_filter_owned_hold_9024 row (re-summed at the #9064 stack merge: 1700 + 1; rows are data and cannot move); +2 access-privacy wave (0.60.649.0): the owner_private_facts_gst2089 and private_labels_write_ahead_gst2092 rows; +1 GBRA-443 private_labels_batch_exit_gbra443 row (rows are data and cannot move), re-summed at the 0.60.650.0 slot on #9038: 1703 + 1; +1 postgres_tls_default row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.651.0 merge: 1704 + 1; +1 GST-2331 sync_reads_fetch_nothing_gst2331 row (rows are data and cannot move), re-summed at the 0.60.654.0 stack on #9045 6ff5540d: 1705 + 1; +7 QM wave (#9037) rows: attest_scope_read_ops_gst1158, attest_direct_page_writes_deferred_gst1158, personal_sources_gbra284, qm_personal_structured_gst1158, memory_propose_held_writes_gst1158, member_email_link_gst1158, qm_admin_http_gst1094 (re-summed at the 0.60.655.0 stack on #9110 f9b2072e: 1706 + 7); +1 GST-2228 recreated_takes_section_keeps_stored_takes_gst2228 row (since TBD; re-summed at the keep-takes-and-link-dates train merge: 1713 + 1); +1 GST-2228 links_rows_keep_own_dates_gst2228 row (since TBD; re-summed at the same train merge: 1714 + 1); +2 the W1 + memory proposals train (#9133): attest_every_page_write_deferred_gst2249 and memory_proposals_owner_http_gst2407 rows (rows are data and cannot move), re-summed at the #9138 v0.60.661.0 stack merge: 1715 + 2 = 1717 measured; +1 #8903 effect_git_secret_gate_gst1923 row (rows are data and cannot move), re-summed at the 0.60.664.0 stack on #9142 3931adb4: 1717 + 1; +1 GST-2407 PR 3: qm_recall_own_page_contract_v4 row (rows are data and cannot move), re-summed at the 0.60.666.0 stack on #9148 69c12917: 1718 + 1; +2 GST-363 PR 1 and PR 3 (#9135): the serves_several_labels_gst363 and stdio_member_per_harness_gst363 rows; +3 #9134 train rows member_forget_names_host_9101, refresh_fence_retry_id_gst2353 and recorded_read_view_args_gst2214 (rows are data and cannot move), re-summed at the #9134 slot merge onto #8829 dfc24954: 1721 + 3; +3 source-checkouts wave rows (autopilot_git_reconcile_gbra386, unknown_drift_history_rescreen, refresh_abandon_members_gst1465), re-summed at the #9137 stack merge: 1724 + 3; persistence train 13 at 0.60.676.0: its five rows on top of 0.60.675.0; +1 GST-2250 reconcile_publish_opt_out_gst2250 row (since TBD until the merge slot; rows are data and cannot move); +1 #8902 unmanaged_push_history_scan_8902 row (re-summed at the 0.60.678.0 stack on 501742d9: 1733 + 1); +1 GST-2246 maintain_safe_free_phases_gst2246 row (since TBD until the merge slot; rows are data and cannot move), re-summed on the doctor/dream/enrich train at the 0.60.679.0 slot merge onto #9170 82932eda: 1734 + 1; +2 GST-2462 privacy_label_ignored_gst2462 and access_page_rules_gst2462 rows (rows are data and cannot move), re-summed at the #9173 slot merge onto 49a922ef: 1735 + 2; +1 GST-2107 follow-up write_capacity_low_not_refusal_gst2107 row (rows are data and cannot move), re-summed at the 0.60.681.0 slot merge onto #9173 c08d0c8b: 1737 + 1; +1 GST-2490: owner_reads_derived_gst2490 row (rows are data and cannot move); +1 GST-2468: the label_only_operator_repairs_gst2468 row (a BEHAVIOR_CHANGES row cannot move); +1 GST-2446 remember_pageless_reply_gst2446, +1 GST-2492 strict_held_facts_gst2492 and +1 GST-2346 D1 owner_facts_shared_gst2346 rows (rows are data and cannot move), re-summed at the 0.60.685.0 train merge onto #9181 405ea4cf: 1740 + 3; +1 GST-2476: the readers_label_setter_gst2476 row (rows are data and cannot move), re-summed at the #9184 slot merge onto the #9179 train 361d57c6: 1743 + 1; +1 GST-2487: the fence_fact_private_in_place_gst2487 row (rows are data and cannot move), at the same slot merge of #9188 0075f09a: 1744 + 1; +1 GST-2515: the sync_status_commits_waiting_gst2515 row (rows are data and cannot move), at the 0.60.688.0 slot merge onto 599b1234: 1745 + 1; +3 GST-2519: commit_push_untrack_gst2519, db_only_labels_kept_gst2519 and git_ignored_label_repair_gst2519 rows (rows are data and cannot move), re-summed at the 0.60.691.0 slot merge onto #9167 ad4f0aef: 1746 + 3; +3 GST-2492 PR 2: the remember_pageless_ask, strict_fact_writers_held and sync_strict_requires_managed rows (rows are data and cannot move), re-summed at the master v0.60.691.0 merge: 1749 + 3; +3 GST-2346 rows owner_forget_private, owner_forget_readers_page and member_save_withdrawn_scope (rows are data and cannot move), re-summed at the 0.60.693.0 slot merge onto #9202 840858e9: 1752 + 3; +2 GST-2518 page_label_widening_held_gst2518 and GST-2521 owner_labels_guarded_gst2521 rows and +1 GST-2511 fence_fact_widening_held_gst2511 row (rows are data and cannot move), re-summed at the 0.60.694.0 slot merge onto master 2c8320d7: 1755 + 3; +3 the GST-2515/GST-2520 notifier_retry_unwatched_gst2515 and strict_skip_mode_refusal_gst2520 rows and the GST-2456 unmanaged_push_every_site_gst2456 row, re-summed at the 0.60.698.0 slot merge onto #9217 887398f0: 1758 + 3
+src/core/behavior-change-notice.ts 1763 ratchet +4 train R: #7491/#7492 keyword_identifier_probe and keyword_slug_handles rows and their comment, #7175 keyword phrase row; the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +1 GBRA-156 #7593: private_pages_granted_sources row (re-summed at the 0.60.527.0 merge: 1574 + 1); +3 GBRA-200 comment, write-grant refusal and degraded-stamp rows (re-summed at the 0.60.562.0 merge: 1615 + 3); +2 GBRA-280 get_page selector-precedence row and comment (re-summed at the 0.60.569.0 merge: 1619 + 2); the BEHAVIOR_CHANGES table grows by one row per disclosed change: +4 the #7891 provenance-drift and #7917/#7918 maintenance-lowering rows and their comments (re-summed at the 0.60.495.0 merge: 1547 + 4); +2 GBRA-205 saved_facts_stems row and its comment (re-summed at the #7901 0.60.492.0 merge: 1541 + 2); +2 GBRA-205 search.query_facts_block default-on row and its approval comment (re-summed at the #7610 0.60.490.0 merge: 1539 + 2); +2 the #7900 content checkpoint host-move row (since TBD until the merge slot), +2 the #7897 private-hold sweep row (since TBD until the merge slot), +2 the #7880 ingest_capture and company-brain private-hold row (since TBD until the merge slot), +5 the frozen-source wave comment and four rows (#7868, #7850, #7869/#7870, #7871), +2 the #7848 visibility_noncanonical hold row (since TBD until the merge slot), +2 the #7846 extract_atoms session-source row (re-summed at the 0.60.481.0 merge: master 1524 + 2), +2 the #7805 synthesize session-source and #7841 visibility_not_applied rows (re-summed at the 0.60.480.0 merge: master 1522 + 2), +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2), +2 the #7814 retired v0.13.1 grandfather row, +2 the #7618 conversion withhold/progress/push row (master 1520 + 2); the behavior-change table split (#7607) retires this row; +4 GBRA-188 #7489: the wave comment and three rows (brain-first instructions, starter surface default, per-turn rule); +1 GBRA-188 plugin_turn_hook_gbra188 row; +1 GBRA-242 provider_key_rules_7959 row (#7959), +2 the GBRA-199 registration_lists_verbs row (since TBD until the merge slot); +2 GBRA-133 #7652: the #7611 pass_abandoned reader row and the lean read-only serve socket row (re-summed at the 0.60.503.0 merge: master 1555 + 2); +1 GBRA-243: the per-turn hook disclosure row (rows are data and cannot move); +4 GBRA-156 #7598 harness wave comment and rows (remote page cap, sources_not_readable refusal, sources add next step); +4 GBRA-156 #7601 search_quotes_transcript_rows comment and row; +1 GBRA-175 #7475 autopilot_restarts_serve_7475 row (re-summed at the #8012 merge: 1566 + 1); +3 #7997/#8014/#8015 rows (redaction markers, company db_only keep, ignored supabase_only scope); +2 #7199 (re-port of #7228) classic_drift_rescreen_7199 comment and row; +2 #7931 file_drift_agrees_7931 comment and row; +1 #7950 file_drift_slug_release_7950 row; +1 #7974 file_drift_followups_7974 row; +1 #8059 quoted_fence_marker_8059 row; +2 GBRA-247 #8009 provenance_repair_held_8009 and #7982 pass_transient_streak_7982 rows; +4 GBRA-247 #7973 plain_directory_sync_7973, #7988 managed_marker_own_directory_7988, #7985 former_binding_parked_group_7985 and settle_effects_retire_7985 rows Train S merge: 1570 base + 5 (master since the #8077 base) + 13 (#8077) = 1588.; +2 GST-687 remote_quotes_unverified_text_gst687 row and its comment (re-summed at the gate-ahead on train S 0.60.534.0: 1588 + 2); +2 #8377: the quote fence follow-ups row and its comment; +2 #8384: the quote fence follow-ups 2 row and its comment; +2 #8384 wave 3: the quote fence follow-ups 3 row and its comment; +5 GBRA-218 train M rows (A1 member_read_access_gbra218 and member_access_hatch_scope_gbra218, B shared_agent_audience_gbra231, A2 folder_access_rules_gbra218, folder_access_scoped_role_gbra218), re-summed at the train M merge of master v0.60.541.0: 1596 + 5 = 1601 measured; +3 GST-359 train C rows (C1 qm_attested_actor_gst359, C2 member_facts_gst359, D qm_memory_provider_gst359), re-summed at the train C merge of master v0.60.543.0: 1601 + 3 = 1604 measured; +2 #8424: hook_launcher_8424 row and its comment (rows are data and cannot move), re-summed at the #8418 v0.60.546.0 merge: 1604 + 2 = 1606 measured; +2 #8426: mcp_lane_launcher_8426 row and its comment (rows are data and cannot move); +2 GST-927: empty_nonstring_args_gst927 row and its comment, re-summed at the gate-ahead on master v0.60.550.0 plus #8420: 1610 measured; +2 GBRA-283 Wave A (#8460): engine_keyed_caches_gbra283 row and its comment (rows are data and cannot move); +2 GBRA-287: segmented_freeze_hold_gbra287 and segmented_reexport_gbra287 rows (rows are data and cannot move); +1 GST-1209: segmented_tiling_gst1209 row (rows are data and cannot move); +1 GST-1251: skillopt_loop_deprecated_gst1251 row (rows are data and cannot move); +1 GST-1209 follow-up: untiled_hold_repair_gst1209 row (rows are data and cannot move); +1 GBRA-283 B3a: embedded_scope_required_gbra283 row (rows are data and cannot move); re-summed at the train R merge with v0.60.574.0: 1623 + 4; +2 GST-1387: refresh_fence_refusal_gst1387 row and its comment (rows are data and cannot move); re-summed at the memory train #8481 merge with v0.60.578.0 (1643 measured); +3 GBRA-253 #8109 rows (frontmatter_drift_write_8109, contacts_activity_advance_8109, contact_rows_dedupe_8109; rows are data and cannot move), re-summed at the master v0.60.581.0 merge: 1643 + 3 = 1646 measured; +3 #8123 part C rows: sync_write_through_off_writeback_7084, managed_sync_dry_run_counts_7087, frontmatter_missing_source_dir_7889 (since TBD until the merge slot; re-summed at the 0.60.583.0 merge: 1646 + 3); +4 PR B commit_ledger_prb, doctor_foreign_writers_prb and sources_guard_prb rows and their comment (rows are data and cannot move; since TBD until the merge slot); +1 PR B #8615: file_drift_held_needs_prefer_8615 row; +1 PR B #8617: refresh_source_changed_retry_8617 row; +1 PR B #8662: commit_push_checkout_not_a_source_8662 row (since TBD until the merge slot; rows are data and cannot move); +2 PR B refresh_barrier_prb and commit_push_base_prb rows (re-summed: 1658 measured); +3 convergence PR A: the wave comment and two rows (conversion_content_evidence_pr_a, git_gap_live_pages_pr_a; since TBD until the merge slot; rows are data and cannot move); re-summed at the gate-ahead on master v0.60.592.0 plus #8711: 1658 + 3 = 1661 measured; +4 GST-1094/GST-900 rows (memory_recall scope-read, member-bound acting_user, recall max_chars, unknown_param _meta-only) and +1 qm_scope_writes_gst1113 and +1 recall_question_terms_gst1304 rows (rows are data and cannot move), re-summed at the 0.60.595.0 slot merge: 1661 + 6; +1 GST-1582 refresh_barrier_import_gst1582 row (since TBD until the merge slot; rows are data and cannot move); +2 GST-1601 source_changed_origin_gst1601 and adopt_local_edits_gst1601 rows (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.596.0 merge: 1668 + 2; +1 GST-1623 refresh_barrier_capacity_gst1623 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.599.0 merge: 1670 + 1; +2 GBRA-224 W1 release_channel_stable_default row and its comment; +1 GST-1623 refresh_barrier_later_write_gst1623 row (#8765; rows are data and cannot move); +5 #8766 GST-1623 items 4/6-9 and #8755: the wave comment and four rows (doctor_foreign_writers_partial_gst1623, commit_push_enclosing_repo_gst1623, owner_guard_fail_closed_gst1623, adopt_local_edits_hardening_8755) and +1 managed_sync_kind_reserved_8765 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on master v0.60.608.0 plus #8798: 1674 + 6; +1 GST-1853 refresh_barrier_aborted_refresh_sync_gst1853 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.613.0 merge: 1680 + 1; +1 GST-1674 refresh_refused_merge_recovery_gst1674 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.614.0 merge: 1681 + 1; +1 #8824/#8826/#8767: adopt_local_edits_replay_markers_8824 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8837: 1682 + 1; +1 url_source_origin row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8834: 1683 + 1; +1 #8828: the refresh_replan_own_commits_8828 row (1684 + 1 at the 0.60.618.0 slot); +1 the managed commit-push unpublished-count row; +1 the refresh publish-diverged default row; +1 GST-2051 ungranted_member_writes_gst2051 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-731 think_window_trajectory_gst731 row and +1 GST-1602 purge_cancels_deferred_write_gst1602 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the gate-ahead on #8915 v0.60.621.0: 1688 + 2; +1 GST-2059: owner_reads_private row; +1 #8888: the record-origin checkout lock-down row (re-summed at the Q6 stack on #8934 v0.60.625.0: 1691 + 1); +1 GST-1158 F9: the attest_direct_page_writes_deferred_gst1158 row (since TBD until the merge slot); +1 GST-1158 E1/F3/F4 rows (since TBD until the merge slot), re-summed at the master merge; +1 GBRA-284 personal_sources_gbra284 row (since TBD until the merge slot) (re-summed at the QM wave merge onto master v0.60.626.0: 1692 + 3); +1 GST-1158 F9: the attest_direct_page_writes_deferred_gst1158 row (since TBD until the merge slot); +1 GST-1158 v3: the qm_personal_structured_gst1158 row (since TBD until the merge slot); +1 #8477 GST-1158 F2 personal-tools row at the QM wave merge (1695 + 1); +1 GST-1158 F9: the attest_direct_page_writes_deferred_gst1158 row (since TBD until the merge slot); +1 #8483 memory_propose row at the QM wave merge (1696 + 1); +1 GST-1094 gap 4: the qm_admin_http_gst1094 row (since TBD until the merge slot); +1 GST-1158: the member_email_link_gst1158 row (since TBD until the merge slot); +2 #8479 member-email rows at the QM wave merge (1697 + 2); +1 GST-2112: ingest_keeps_readers_gst2112 row (re-summed at the Q7 v0.60.627.0 merge: 1692 + 1); +1 #8982 federated_member_writes_8982 row (since TBD until the merge slot; rows are data and cannot move); +1 GST-2116 commit_push_skipped_paths_gst2116 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the Q10 slot on #9009 ee0f4a78: 1694 + 1; +1 GST-2118 pending_ledger_flagged_gst2118 row (since TBD until the merge slot; rows are data and cannot move), re-summed at the Q12 slot on #9016 afb49de5: 1695 + 1; +1 GBRA-431: read_scope_params_gbra431 row (rows are data and cannot move), re-summed at the #9032 stack merge: 1697 measured; +2 GST-2201 sync_restored_file_gst2201 and purge_keeps_committed_file_gst2201 rows (since is the current VERSION until the merge slot; +1 GST-2243 remember_share_gst2243 row (re-summed at the #9098 stack merge: 1699 + 1); +1 GST-2312 #9024 sync_filter_owned_hold_9024 row (re-summed at the #9064 stack merge: 1700 + 1; rows are data and cannot move); +2 access-privacy wave (0.60.649.0): the owner_private_facts_gst2089 and private_labels_write_ahead_gst2092 rows; +1 GBRA-443 private_labels_batch_exit_gbra443 row (rows are data and cannot move), re-summed at the 0.60.650.0 slot on #9038: 1703 + 1; +1 postgres_tls_default row (since TBD until the merge slot; rows are data and cannot move), re-summed at the master v0.60.651.0 merge: 1704 + 1; +1 GST-2331 sync_reads_fetch_nothing_gst2331 row (rows are data and cannot move), re-summed at the 0.60.654.0 stack on #9045 6ff5540d: 1705 + 1; +7 QM wave (#9037) rows: attest_scope_read_ops_gst1158, attest_direct_page_writes_deferred_gst1158, personal_sources_gbra284, qm_personal_structured_gst1158, memory_propose_held_writes_gst1158, member_email_link_gst1158, qm_admin_http_gst1094 (re-summed at the 0.60.655.0 stack on #9110 f9b2072e: 1706 + 7); +1 GST-2228 recreated_takes_section_keeps_stored_takes_gst2228 row (since TBD; re-summed at the keep-takes-and-link-dates train merge: 1713 + 1); +1 GST-2228 links_rows_keep_own_dates_gst2228 row (since TBD; re-summed at the same train merge: 1714 + 1); +2 the W1 + memory proposals train (#9133): attest_every_page_write_deferred_gst2249 and memory_proposals_owner_http_gst2407 rows (rows are data and cannot move), re-summed at the #9138 v0.60.661.0 stack merge: 1715 + 2 = 1717 measured; +1 #8903 effect_git_secret_gate_gst1923 row (rows are data and cannot move), re-summed at the 0.60.664.0 stack on #9142 3931adb4: 1717 + 1; +1 GST-2407 PR 3: qm_recall_own_page_contract_v4 row (rows are data and cannot move), re-summed at the 0.60.666.0 stack on #9148 69c12917: 1718 + 1; +2 GST-363 PR 1 and PR 3 (#9135): the serves_several_labels_gst363 and stdio_member_per_harness_gst363 rows; +3 #9134 train rows member_forget_names_host_9101, refresh_fence_retry_id_gst2353 and recorded_read_view_args_gst2214 (rows are data and cannot move), re-summed at the #9134 slot merge onto #8829 dfc24954: 1721 + 3; +3 source-checkouts wave rows (autopilot_git_reconcile_gbra386, unknown_drift_history_rescreen, refresh_abandon_members_gst1465), re-summed at the #9137 stack merge: 1724 + 3; persistence train 13 at 0.60.676.0: its five rows on top of 0.60.675.0; +1 GST-2250 reconcile_publish_opt_out_gst2250 row (since TBD until the merge slot; rows are data and cannot move); +1 #8902 unmanaged_push_history_scan_8902 row (re-summed at the 0.60.678.0 stack on 501742d9: 1733 + 1); +1 GST-2246 maintain_safe_free_phases_gst2246 row (since TBD until the merge slot; rows are data and cannot move), re-summed on the doctor/dream/enrich train at the 0.60.679.0 slot merge onto #9170 82932eda: 1734 + 1; +2 GST-2462 privacy_label_ignored_gst2462 and access_page_rules_gst2462 rows (rows are data and cannot move), re-summed at the #9173 slot merge onto 49a922ef: 1735 + 2; +1 GST-2107 follow-up write_capacity_low_not_refusal_gst2107 row (rows are data and cannot move), re-summed at the 0.60.681.0 slot merge onto #9173 c08d0c8b: 1737 + 1; +1 GST-2490: owner_reads_derived_gst2490 row (rows are data and cannot move); +1 GST-2468: the label_only_operator_repairs_gst2468 row (a BEHAVIOR_CHANGES row cannot move); +1 GST-2446 remember_pageless_reply_gst2446, +1 GST-2492 strict_held_facts_gst2492 and +1 GST-2346 D1 owner_facts_shared_gst2346 rows (rows are data and cannot move), re-summed at the 0.60.685.0 train merge onto #9181 405ea4cf: 1740 + 3; +1 GST-2476: the readers_label_setter_gst2476 row (rows are data and cannot move), re-summed at the #9184 slot merge onto the #9179 train 361d57c6: 1743 + 1; +1 GST-2487: the fence_fact_private_in_place_gst2487 row (rows are data and cannot move), at the same slot merge of #9188 0075f09a: 1744 + 1; +1 GST-2515: the sync_status_commits_waiting_gst2515 row (rows are data and cannot move), at the 0.60.688.0 slot merge onto 599b1234: 1745 + 1; +3 GST-2519: commit_push_untrack_gst2519, db_only_labels_kept_gst2519 and git_ignored_label_repair_gst2519 rows (rows are data and cannot move), re-summed at the 0.60.691.0 slot merge onto #9167 ad4f0aef: 1746 + 3; +3 GST-2492 PR 2: the remember_pageless_ask, strict_fact_writers_held and sync_strict_requires_managed rows (rows are data and cannot move), re-summed at the master v0.60.691.0 merge: 1749 + 3; +3 GST-2346 rows owner_forget_private, owner_forget_readers_page and member_save_withdrawn_scope (rows are data and cannot move), re-summed at the 0.60.693.0 slot merge onto #9202 840858e9: 1752 + 3; +2 GST-2518 page_label_widening_held_gst2518 and GST-2521 owner_labels_guarded_gst2521 rows and +1 GST-2511 fence_fact_widening_held_gst2511 row (rows are data and cannot move), re-summed at the 0.60.694.0 slot merge onto master 2c8320d7: 1755 + 3; +3 the GST-2515/GST-2520 notifier_retry_unwatched_gst2515 and strict_skip_mode_refusal_gst2520 rows and the GST-2456 unmanaged_push_every_site_gst2456 row, re-summed at the 0.60.698.0 slot merge onto #9217 887398f0: 1758 + 3; +2 GST-2407: context_pack scope read and attestRead over the owner route
src/core/git/commit-push.ts 1658 ratchet GST-2519: --untrack (#7753 port: untrackTargets, untrackPaths; untrackAdmitted, the managed-worktree storage.db_only admission; previewUntrack) and the staged-removal hint in skippedPathsError grow the commit door past the 1500 default (master 1487 + 140); GST-2456 (#9174): crossed the 1500 unlisted cap at the GST-2456 merge of master v0.60.678.0: pushBase (the scan base and lease read live from every push URL, #5138) and the scan budget and progress options; Ctx and publish internals keep it in this file (1487 + 31), re-summed at the master 0c577834 merge into #9198: 1627 + 31
src/commands/auth.ts 1503 ratchet new row: crossed the 1500 unlisted cap at the v0.60.595.0 merge: GST-1113 --attest-sources help lines plus GST-1158 F3 --attest-read help lines (3); CLI help lines cannot move
diff --git a/src/commands/mcp-admin.ts b/src/commands/mcp-admin.ts
index 8a89f14b20..1b53fdda12 100644
--- a/src/commands/mcp-admin.ts
+++ b/src/commands/mcp-admin.ts
@@ -17,7 +17,7 @@ gbrain mcp admin client ID
gbrain mcp admin register NAME --redirect-uri URI [--redirect-uri URI ...]
gbrain mcp admin setup ID --harness ID [--flow authorization-code|client-credentials]
gbrain mcp admin invalidate-tokens|revoke|delete ID [--yes --if-version N]
-gbrain mcp admin attest CLIENT_ID --attest-actor qm|none [--attest-ops LIST] [--dry-run]
+gbrain mcp admin attest CLIENT_ID --attest-actor qm|none [--attest-ops LIST] [--attest-read person|scope|none] [--dry-run]
gbrain mcp admin members [--all]
gbrain mcp admin member-add ID [--name NAME] [--email ADDR] [--groups G1,G2]
gbrain mcp admin member-set ID --email ADDR|none
@@ -47,6 +47,7 @@ gbrain mcp admin memory-proposals deny REQUEST_ID --reason TEXT [--dry-run]
--yes --if-version N Apply reviewed lifecycle action; otherwise preview only
--attest-actor qm|none Grant or clear the right to name the person a call serves (x-qm-actor)
--attest-ops LIST Operations an attested call may run (default get_write_request,memory_recall,memory_write)
+--attest-read person|scope|none How a call that names sources reads them: as the person, or as their audience (none: the default, scope)
--qm ID A canonical person id from the trusted system
--email ADDR A member's declared email (case-folded, unique); link finds the member by it
--timeout-ms N Request timeout, 100..300000 (default: 30000)
@@ -73,7 +74,7 @@ const commandValues: Record<string, string[]> = {
register: ['--redirect-uri', '--token-endpoint-auth-method', '--source', '--federated-read', '--scopes', '--profile', '--credentials-out', '--harness'],
setup: ['--harness', '--flow', '--credentials-out'],
'invalidate-tokens': ['--if-version'], revoke: ['--if-version'], delete: ['--if-version'],
- attest: ['--attest-actor', '--attest-ops'], members: [], 'member-add': ['--name', '--groups', '--email'], 'member-set': ['--email'], 'member-disable': [], 'member-enable': [],
+ attest: ['--attest-actor', '--attest-ops', '--attest-read'], members: [], 'member-add': ['--name', '--groups', '--email'], 'member-set': ['--email'], 'member-disable': [], 'member-enable': [],
links: ['--member'], link: ['--qm', '--email'], unlink: ['--qm'], 'memory-proposals': [],
};
/** GST-2407: memory-proposals takes a subcommand; show, approve and deny take exactly one request id. */
@@ -123,10 +124,11 @@ const ACCESS_COMMANDS: Record<string, (client: AdminClient, parsed: AdminArgs, v
attest: (client, parsed, value) => {
const actor = value('--attest-actor');
const ops = value('--attest-ops');
- if (actor === undefined && ops === undefined) throw new McpAdminError('invalid_arguments', 'attest needs --attest-actor qm|none and/or --attest-ops <list>.');
+ const read = value('--attest-read');
+ if (actor === undefined && ops === undefined && read === undefined) throw new McpAdminError('invalid_arguments', 'attest needs --attest-actor qm|none, --attest-ops <list> and/or --attest-read person|scope|none.');
const dryRun = parsed.flags.has('--dry-run');
return client.request('/admin/api/access/attest', { method: 'POST', mutation: !dryRun, nextAction: `gbrain mcp admin client ${parsed.target} --url ${client.base}`, body: {
- clientId: parsed.target, dryRun, ...(actor === undefined ? {} : { attestActor: actor === 'none' ? null : actor }), ...(ops === undefined ? {} : { attestOps: list(ops) }) } });
+ clientId: parsed.target, dryRun, ...(actor === undefined ? {} : { attestActor: actor === 'none' ? null : actor }), ...(ops === undefined ? {} : { attestOps: list(ops) }), ...(read === undefined ? {} : { attestRead: read === 'none' ? null : read }) } });
},
members: (client, parsed) => client.request(`/admin/api/access/members${parsed.flags.has('--all') ? '?all=1' : ''}`),
'member-add': (client, parsed, value) => client.request('/admin/api/access/members', { method: 'POST', mutation: true, nextAction: `gbrain mcp admin members --url ${client.base}`,
diff --git a/src/commands/serve-http-access.ts b/src/commands/serve-http-access.ts
index a2adfca4ae..ab776c7e5f 100644
--- a/src/commands/serve-http-access.ts
+++ b/src/commands/serve-http-access.ts
@@ -65,9 +65,10 @@ export function mountAdminAccess(app: Express, requireAdmin: RequestHandler, eng
});
app.post('/admin/api/access/attest', requireAdmin, express.json(), async (req, res) => {
- const { clientId, attestActor, attestOps, dryRun } = req.body ?? {};
+ const { clientId, attestActor, attestOps, attestRead, dryRun } = req.body ?? {};
if (typeof clientId !== 'string' || !clientId) return refuse(res, 'clientId required.');
- if (attestActor === undefined && attestOps === undefined) return refuse(res, 'Pass attestActor (qm or null) and/or attestOps.');
+ if (attestActor === undefined && attestOps === undefined && attestRead === undefined) return refuse(res, 'Pass attestActor (qm or null), attestOps and/or attestRead.');
+ if (attestRead !== undefined && attestRead !== null && attestRead !== 'person' && attestRead !== 'scope') return refuse(res, 'attestRead must be person or scope, or null for the default (scope).');
if (attestActor !== undefined && attestActor !== null && !ATTEST_SYSTEMS.includes(attestActor)) return refuse(res, `attestActor must be ${ATTEST_SYSTEMS.join(' or ')}, or null to clear the right.`);
if (attestOps !== undefined && attestOps !== null && !(Array.isArray(attestOps) && attestOps.every((op: unknown) => typeof op === 'string'))) return refuse(res, 'attestOps must be an array of operation names, or null for the default.');
if (dryRun !== undefined && typeof dryRun !== 'boolean') return refuse(res, 'dryRun must be a boolean.');
@@ -75,10 +76,11 @@ export function mountAdminAccess(app: Express, requireAdmin: RequestHandler, eng
const patch: BindingPatch = {
...(attestActor !== undefined ? { attestActor } : {}),
...(attestOps !== undefined ? { attestOps: attestOps === null ? null : parseAttestOps(attestOps.join(','), name => operationsByName[name]) } : {}),
+ ...(attestRead !== undefined ? { attestRead } : {}),
};
const result = await bindCredential(engine, { kind: 'client', id: clientId }, patch, { dryRun });
- if (result.changed && !dryRun) await audit(engine, 'client_attest', { client_id: clientId, attest_actor: result.attest_actor ?? null, attest_ops: result.attest_ops ?? null });
- return { applied: result.changed && dryRun !== true, client_id: clientId, attest_actor: result.attest_actor ?? null, attest_ops: result.attest_ops ?? null, changed: result.changed,
+ if (result.changed && !dryRun) await audit(engine, 'client_attest', { client_id: clientId, attest_actor: result.attest_actor ?? null, attest_ops: result.attest_ops ?? null, attest_read: result.attest_read ?? null });
+ return { applied: result.changed && dryRun !== true, client_id: clientId, attest_actor: result.attest_actor ?? null, attest_ops: result.attest_ops ?? null, attest_read: result.attest_read ?? null, changed: result.changed,
tokenImplications: 'Takes effect on the next request; a client that newly holds the right takes a new token with grant_type=client_credentials.' };
});
});
diff --git a/src/core/access/scope-read.ts b/src/core/access/scope-read.ts
index a339aad616..997a5b5624 100644
--- a/src/core/access/scope-read.ts
+++ b/src/core/access/scope-read.ts
@@ -17,9 +17,9 @@ export const SCOPE_READ_ACCESS: Partial<CallerAccess> = {
hidePrivate: true, applyRemoteReadPolicy: false, restricted: true, remotePolicy: { privacyRelaxed: false, restricted: true },
};
-/** GST-1158 E1: the reads an attested call that names sources runs as the scope. context_pack stays out until it is confined to the named sources, so it is refused when it names sources on a scope credential. */
+/** GST-1158 E1: the reads an attested call that names sources runs as the scope. GST-2407: context_pack reads only the source it names (assertPackConfined). */
export const SCOPE_READ_OPS: ReadonlySet<string> = new Set([
- 'memory_recall', 'get_page', 'entity', 'whois', 'get_backlinks', 'get_timeline', 'find_experts', 'volunteer_context', 'query',
+ 'memory_recall', 'get_page', 'entity', 'whois', 'get_backlinks', 'get_timeline', 'find_experts', 'volunteer_context', 'query', 'context_pack',
]);
export type ReadMode = 'scope' | 'person';
@@ -46,18 +46,29 @@ function namesSources(params: Record<string, unknown> | undefined): boolean {
* sources, else null. A scope read that asks for every source (`__all__`, `all_sources`) is refused with invalid_params.
*/
export function attestedReadMode(op: string, params: Record<string, unknown> | undefined, attestRead: ReadMode | null | undefined): ReadMode | null {
- if (op === 'context_pack' && attestRead !== 'person' && (namesSources(params) || (Array.isArray(params?.entity_refs) && params.entity_refs.length > 0))) throw contextPackScopeRefused();
- if (!SCOPE_READ_OPS.has(op) || !namesSources(params)) return null;
+ const refs = op === 'context_pack' && Array.isArray(params?.entity_refs) && params.entity_refs.length > 0;
+ if (!SCOPE_READ_OPS.has(op) || !(namesSources(params) || refs)) return null;
if (attestRead === 'person') return 'person';
const ids = params?.source_ids;
if (params?.source_id === ALL_SOURCES || params?.all_sources === true || (Array.isArray(ids) && ids.includes(ALL_SOURCES))) throw scopeAllSourcesRefused(op);
+ if (op === 'context_pack') assertPackConfined(params!);
return 'scope';
}
-function contextPackScopeRefused(): OperationError {
- return opError('invalid_params', 'context_pack: a call that names sources would read them as the person, and this credential reads named sources as their audience, so it is refused. Nothing was read.',
- 'Leave source_id, source_ids, all_sources and entity_refs out to read as the person, or call query, get_page or entity with source_id for the scope.',
- { why: 'context_pack is not yet confined to the named sources, so it cannot run as a scope read.' });
+/**
+ * GST-2407: a context_pack scope read reads one source, the source_id it names: its entities, every entity_refs entry,
+ * the core block, the pull brief and hot facts (ops/facts.ts reads the scope's source as home). session_id is refused,
+ * since a session's thread rows belong to the person. Each refusal comes before any read.
+ */
+function assertPackConfined(params: Record<string, unknown>): void {
+ const source = params.source_id;
+ const refused = (problem: string, fix: string) => opError('invalid_params', `context_pack: ${problem}, and this credential reads named sources as their audience, so it is refused. Nothing was read.`, fix,
+ { why: 'A scope read must name exactly the one source it reads, so the pack never reads past the scope the turn serves.' });
+ if (typeof source !== 'string' || !source) throw refused('a call with entity_refs names no source_id', 'Pass source_id with the source the entity_refs name, or leave entity_refs out to read as the person.');
+ if ((params.entity_refs as unknown[] | undefined)?.some(ref => (ref as { source_id?: unknown } | null)?.source_id !== source)) {
+ throw refused(`an entity_refs entry names a source other than source_id '${source}'`, 'Name only entities in the source_id the call reads, each with that source_id.');
+ }
+ if (params.session_id !== undefined && params.session_id !== null && params.session_id !== '') throw refused('a scope read cannot read a session\'s thread rows (session_id)', 'Leave session_id out of a call that names source_id.');
}
function scopeAllSourcesRefused(op: string): OperationError {
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 590ab065e6..21202f5a93 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1563,6 +1563,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.693.0', id: 'member_save_withdrawn_scope_gst2346', text: 'A remote `remember` onto a member\'s own page (`memory/members/<id>`) is refused `fact_withdrawn` only when that member could read what was withdrawn: a fact on its own page, its own copy withdrawn by the brain host, or for the brain owner a fact it reads. A claim withdrawn by the brain host or the owner that the member never read no longer refuses its save: the fact saves as the member\'s own active row with the same reply as a new claim. A schema migration makes the database insert guards mark a row on a member page only by that page\'s own withdrawals; a withdrawal still expires matching rows on member pages when it is made, and strikes them in the page\'s file, so an import of a member page\'s file no longer marks a row withdrawn by a withdrawal of another subject. The same holds for each item of a `remember` batch (`items`), a replay with the same `request_id`, a `replaces` and the write receipt (`get_write_request`). Trusted local saves keep the check they had.' },
{ since: '0.60.694.0', id: 'owner_labels_guarded_gst2521', text: 'Labels the owner sets with `gbrain repair visibility` (or its `--readers` setter, or `gbrain repair private-labels`) now raise the page\'s label guard to operator_curated, so a later local agent write at the page\'s own tier that drops or widens them is held like a write over an owner page, with a `lower_page` item. A local write below operator_curated whose `readable_by` would leave the brain owner out of a page the owner reads now publishes with the owner kept in the readers (the rest of the narrowing applies), and its item records the requested readers. Accepting such an item (`gbrain trust confirm tp<id>`) on a page whose own tier is an agent\'s writes only the labels and keeps the agent\'s tier; on an owner page it still endorses the edit at the owner\'s tier. The guard is stored in the database (`page_label_guards`) and set only by label repairs run after the upgrade, so labels set earlier, and a managed Git brain rebuilt from a clone, start unguarded; re-running `gbrain repair visibility --slug` or `--readers` on a page that already has those labels raises the guard without changing them. The owner\'s own label writes, synced owner edits, agent narrowing that keeps the owner, and brains with `access.owner_reads_restricted` on are unchanged.' },
{ since: '0.60.694.0', id: 'page_label_widening_held_gst2518', text: 'A local agent write (`put_page`, `capture`, `edit_page`, `append_page`, `revert_version`, `restore_page`) less trusted than a page that drops or widens its `visibility`, `access`, `confidentiality` or `readable_by` now publishes with the page\'s earlier labels kept, in the database and in the committed file, and its receipt lists them under `privacy_labels_kept`; so does a maintenance job\'s derived page publication, and a page whose tier is still `unknown` counts as the owner\'s. A soft delete no longer lowers the page\'s tier. Before, the page became readable to remote callers and other members at once, and only a `lower_page` item waited for the owner. That item now records the requested labels: `gbrain trust confirm tp<id>` applies them if the page has not changed since, `gbrain trust drop tp<id>` keeps the earlier ones, and undoing a confirm restores them while the page is unchanged since. Narrowing writes, label-neutral writes, writers at or above the page\'s tier, synced owner edits and `gbrain repair visibility` are unchanged.' },
+ { since: 'TBD', id: 'qm_context_pack_scope_read_gst2407', text: 'An attested `context_pack` that names `source_id` now reads that one source as its audience instead of being refused on a client that reads named sources as the scope: its entities and `entity_refs`, the core block, the counterparty brief and hot facts come from that source only, with no member-page fact, no page restricted to named readers and privacy never relaxed. A call that sends `entity_refs` without `source_id`, an `entity_refs` entry in another source, or `session_id` is refused with `invalid_params` before anything is read. A client set `--attest-read person` reads as the person, as before. Contract `docs/contracts/qm-memory-provider/v5.json` marks `context_pack` `scope_read: true`; v1 to v4 are unchanged.' },
+ { since: 'TBD', id: 'qm_admin_attest_read_gst2407', text: 'The owner can now set how a client reads named sources from another machine: `gbrain mcp admin attest <client> --attest-read person|scope|none`, backed by `attestRead` on `/admin/api/access/attest`. It refuses what `gbrain auth rescope --attest-read` refuses (no attest right, or a client with scope sources set to person), previews with `--dry-run` and logs `attest_read` in the `access_admin` row.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/cli-flag-registry.generated.ts b/src/core/cli-flag-registry.generated.ts
index cca0fb7231..eeabc0f88a 100644
--- a/src/core/cli-flag-registry.generated.ts
+++ b/src/core/cli-flag-registry.generated.ts
@@ -86,7 +86,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'loops': ['--all', '--as-of', '--brain', '--dry-run', '--fail-fast', '--help', '--json', '--note', '--source', '--stale-ok', '--status', '--tools-json', '--top', '--type'],
'lsd': ['--brain', '--force-resume', '--help', '--json', '--judge-model', '--limit', '--list-runs', '--max-cost', '--max-far-set', '--max-ideas-per-judge-call', '--max-usd', '--no-save', '--resume', '--save', '--source', '--strict-budget', '--yes'],
'maintain': ['--absolute-git-dir', '--account', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--after', '--all', '--allow-outside-source-root', '--apply', '--assign-corpus', '--attest-read', '--audit', '--background', '--brain', '--break-lock', '--budget-ms', '--by-mention', '--cached', '--catch-up', '--check-only', '--class', '--clear', '--client', '--concurrency', '--conflicts', '--contacts-dir', '--content-audit', '--continue', '--conversation', '--count', '--cwd', '--detach', '--detail', '--dim', '--dir', '--drain', '--dry-run', '--embedding-dimensions', '--embedding-model', '--enable', '--entity', '--expect', '--expected-revision', '--expected-state', '--explain', '--facts', '--fast', '--fix', '--follow', '--force', '--force-retry', '--force-schema', '--format', '--from-meetings', '--full', '--grammar', '--group-by', '--hard-deadline', '--harness', '--held', '--help', '--http', '--id', '--ignore-missing', '--images', '--include-ambiguous', '--include-flagged', '--include-frontmatter', '--include-gitignored', '--include-repairs', '--index-audit', '--infer-dates', '--input', '--install', '--instructions-only', '--json', '--keep-checkout', '--kind', '--lang', '--left-right', '--limit', '--link-source', '--link-type', '--list', '--local', '--locks', '--markdown', '--max-cost', '--max-cost-usd', '--max-jobs', '--max-rss', '--max-usd', '--may-act-for', '--migrate-legacy', '--migrate-only', '--multimodal', '--name', '--name-only', '--ner', '--no-autopilot-install', '--no-capture', '--no-delegate', '--no-embed', '--no-instructions', '--no-pull', '--no-renames', '--no-walk', '--once', '--only', '--operations', '--output', '--oversized', '--pack', '--page', '--parallel', '--params', '--path', '--pending', '--pglite', '--phase', '--pid-file', '--plan', '--porcelain', '--prefer', '--prefix', '--preview', '--probe', '--probe-pglite', '--project', '--providers', '--prune-orphans', '--pull', '--purge', '--push-only', '--query', '--question', '--queue', '--quiet', '--rate', '--raw-only', '--reader-mode', '--readers', '--reauth', '--rebase', '--rebuild', '--regenerate', '--remediate', '--remediation-plan', '--remote', '--remove', '--remove-core', '--request-id', '--reset', '--reset-default', '--restart-only', '--resume', '--retry-failed', '--retry-held', '--retry-parked', '--reverse', '--safe', '--scan-secrets', '--scope', '--scopes', '--serves', '--session', '--show-current', '--show-toplevel', '--since', '--skill-loading', '--skills-dir', '--skills-index-only', '--skip-failed', '--slot', '--slug', '--slugs', '--source', '--source-id', '--sources', '--staged', '--stale', '--stat', '--state', '--status', '--stdin', '--supabase', '--surface', '--symbol-kind', '--takes-holders', '--target', '--target-score', '--tier', '--to', '--token', '--top-k', '--type', '--unindexed', '--untracked-files', '--url-env', '--verbose', '--verify', '--version', '--where', '--window', '--workers', '--workspace', '--yes'],
- 'mcp': ['--admin-token-file', '--advertise', '--agent', '--all', '--arg', '--attest-actor', '--attest-ops', '--bearer-token-env-var', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--budget-usd-per-day', '--client', '--credentials-file', '--credentials-out', '--cursor', '--delegate', '--delegated-namespace', '--delegated-slug-prefixes', '--dry-run', '--email', '--enable-dcr', '--federated-read', '--flow', '--force', '--funnel', '--groups', '--harness', '--header', '--help', '--if-version', '--install', '--issuer-url', '--json', '--limit', '--mcp-only', '--mcp-url', '--member', '--name', '--no-install', '--no-service', '--no-tailscale', '--oauth-client-id', '--oauth-client-secret', '--oauth-request', '--port', '--profile', '--qm', '--queue', '--reason', '--redirect-uri', '--remove', '--resume', '--root', '--scope', '--scopes', '--skills', '--source', '--status', '--surface', '--timeout-ms', '--token', '--token-endpoint-auth-method', '--token-ttl', '--url', '--yes'],
+ 'mcp': ['--admin-token-file', '--advertise', '--agent', '--all', '--arg', '--attest-actor', '--attest-ops', '--attest-read', '--bearer-token-env-var', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--budget-usd-per-day', '--client', '--credentials-file', '--credentials-out', '--cursor', '--delegate', '--delegated-namespace', '--delegated-slug-prefixes', '--dry-run', '--email', '--enable-dcr', '--federated-read', '--flow', '--force', '--funnel', '--groups', '--harness', '--header', '--help', '--if-version', '--install', '--issuer-url', '--json', '--limit', '--mcp-only', '--mcp-url', '--member', '--name', '--no-install', '--no-service', '--no-tailscale', '--oauth-client-id', '--oauth-client-secret', '--oauth-request', '--port', '--profile', '--qm', '--queue', '--reason', '--redirect-uri', '--remove', '--resume', '--root', '--scope', '--scopes', '--skills', '--source', '--status', '--surface', '--timeout-ms', '--token', '--token-endpoint-auth-method', '--token-ttl', '--url', '--yes'],
'memory-proposals': ['--all', '--brain', '--dry-run', '--help', '--json', '--limit', '--reason', '--replace', '--source'],
'migrate': ['--accept-pending', '--admin-intent', '--all', '--apply', '--as', '--background', '--batch-size', '--brain', '--catch-up', '--dim', '--drain-timeout', '--dry-run', '--embedding-dimensions', '--embedding-model', '--expect', '--expected-epoch', '--expected-state', '--explain', '--facts', '--follow', '--force', '--force-retry', '--harness', '--held', '--help', '--ignore-env-override', '--images', '--include-null-signature', '--json', '--locks', '--manifest', '--max-cost', '--max-cost-usd', '--max-usd', '--no-accept-pending', '--no-embed', '--no-embedding', '--no-migrate', '--non-interactive', '--only', '--oversized', '--pace', '--pace-max-concurrency', '--path', '--pglite', '--plan', '--priority', '--probe', '--progress-interval', '--progress-json', '--quiet', '--replace', '--reranker', '--resume', '--retarget', '--rollback-to-source', '--scope', '--skip-verify', '--slugs', '--source', '--stale', '--statement-timeout', '--status', '--timeout', '--timings', '--to', '--trigger-bypass', '--trust', '--url', '--url-env', '--wait', '--yes'],
'models': ['--batch', '--brain', '--concurrent', '--cycles', '--dim', '--dimensions', '--embedding-dimensions', '--embedding-model', '--help', '--json', '--limit', '--max-tokens', '--max-usd', '--output', '--receipt-dir', '--skip', '--slot-a-model', '--slot-b-model', '--slot-c-model', '--slug', '--source', '--status', '--task', '--to', '--yes'],
diff --git a/src/core/ops/facts.ts b/src/core/ops/facts.ts
index 7bc7595584..da9cf0b60e 100644
--- a/src/core/ops/facts.ts
+++ b/src/core/ops/facts.ts
@@ -739,7 +739,6 @@ const context_pack: Operation = {
const { assembleContextPack, renderPack, isAfter, PACK_DEFAULT_MAX_ENTITIES, renderCardLine, renderThreadLine, renderFactLine, packHeaderCost,
renderNewerMentionLines, ENTITY_FACTS_HEADER } = await import('../context/turn-context.ts');
const { NEWER_MENTIONS_HEADER } = await import('../mentions/newer-mentions.ts');
- const sourceId = ctx.sourceId ?? 'default';
const rawSince = typeof p.since === 'string' && p.since.trim() ? p.since : undefined;
if (rawSince !== undefined && !Number.isFinite(Date.parse(rawSince))) {
throw verbError(
@@ -757,6 +756,8 @@ const context_pack: Operation = {
// #6723: names resolve across the readable sources (home first) unless source_id pins one; entity_refs name their source.
const { ambientMissNotice, entityRefs, entitySources } = await import('../verbs/entity-source.ts');
const walk = await entitySources(ctx, p, 'context_pack');
+ const scoped = (await import('../access/scope-read.ts')).currentReadMode() === 'scope';
+ const sourceId = scoped ? walk.home : ctx.sourceId ?? 'default';
const refs = (await entityRefs(ctx, p.entity_refs, PACK_DEFAULT_MAX_ENTITIES)).slice(0, PACK_DEFAULT_MAX_ENTITIES - names.length);
const entities = [...names, ...refs.map((r) => r.name)];
// Fail-closed: private only when EXPLICITLY requested AND the caller is
@@ -793,7 +794,7 @@ const context_pack: Operation = {
// Always-loaded core tier (core-memory.ts): owner-designated pages of
// `default` plus this source, inside the caller's grant; it packs first.
const { loadCoreBlock } = await import('../core-memory.ts');
- const allowed = ctx.auth?.allowedSources?.length ? ctx.auth.allowedSources : null;
+ const allowed = scoped ? [sourceId] : ctx.auth?.allowedSources?.length ? ctx.auth.allowedSources : null;
const core = await loadCoreBlock(ctx.engine, { sessionSourceId: sourceId, allowedSources: allowed, excludePrivate: !includePrivate, forCaller: true, eligibility })
.catch(() => null);
const coreText = core?.text ?? '';
diff --git a/test/mcp-admin-cli.serial.test.ts b/test/mcp-admin-cli.serial.test.ts
index 5fa803dd96..7ed90a361b 100644
--- a/test/mcp-admin-cli.serial.test.ts
+++ b/test/mcp-admin-cli.serial.test.ts
@@ -177,6 +177,8 @@ test('people administration commands send owner-session requests to the access r
const cases: Array<[string[], string, unknown]> = [
[['attest', clientId, '--attest-actor', 'qm', '--attest-ops', 'memory_recall,memory_write', '--dry-run'], '/admin/api/access/attest', { clientId, dryRun: true, attestActor: 'qm', attestOps: ['memory_recall', 'memory_write'] }],
[['attest', clientId, '--attest-actor', 'none'], '/admin/api/access/attest', { clientId, dryRun: false, attestActor: null }],
+ [['attest', clientId, '--attest-read', 'person', '--dry-run'], '/admin/api/access/attest', { clientId, dryRun: true, attestRead: 'person' }],
+ [['attest', clientId, '--attest-read', 'none'], '/admin/api/access/attest', { clientId, dryRun: false, attestRead: null }],
[['members', '--all'], '/admin/api/access/members?all=1', undefined],
[['member-add', 'alice-example', '--name', 'Alice Example', '--groups', 'team-a,team-b'], '/admin/api/access/members', { action: 'add', id: 'alice-example', name: 'Alice Example', groups: ['team-a', 'team-b'] }],
[['member-disable', 'alice-example'], '/admin/api/access/members', { action: 'disable', id: 'alice-example' }],
diff --git a/test/qm-memory-contract.test.ts b/test/qm-memory-contract.test.ts
index 8a9293c7e7..90e91b6242 100644
--- a/test/qm-memory-contract.test.ts
+++ b/test/qm-memory-contract.test.ts
@@ -28,6 +28,8 @@ const V1_SHA256 = 'c80a7a5f8133f875ef90a2b5052a53c4d2bb0ab95facfa3975ba626c00daa
/** The v2 and v3 bytes as they landed (v0.60.662.0): a published version never changes. */
const V2_SHA256 = '5458aa92d9495c391b7ec96978a16d4f7ea9841994e8e9163da1205223f1f6a6';
const V3_SHA256 = 'cf4e3f514c57bcd381c1bc0846a0de105dd2a0fbbf361aaa08175cd8bfe0760b';
+/** The v4 bytes as they landed (v0.60.666.0, #9152). */
+const V4_SHA256 = '51f2ee77f0925f6ac19ecc116eeb6d7527d00b8a2962ebbad939f61d0afa3b2f';
describe('QM memory-provider contract v1', () => {
const fixture = JSON.parse(readFileSync(QM_CONTRACT_PATH, 'utf8'));
@@ -295,11 +297,10 @@ describe('QM memory-provider contract v4 (GST-2407: memory_propose, E1 scope_rea
expect(v3.memory_propose).toBeUndefined();
});
- test('each personal tool is marked scope_read from SCOPE_READ_OPS, and every scope-read op QM sees is marked', () => {
+ test('each personal tool carries the scope_read marking v4 published, frozen at its sha (context_pack is marked from v5 on)', () => {
+ expect(sha(readFileSync(QM_CONTRACT_PATHS[4]))).toBe(V4_SHA256);
const marks = Object.fromEntries(fixture.personal_tools.tools.map((t: { name: string; scope_read: boolean }) => [t.name, t.scope_read]));
expect(marks).toEqual({ context_pack: false, entity: true, find_experts: true, forget_fact: false, get_backlinks: true, get_page: true, get_timeline: true, get_write_request: false, query: true, volunteer_context: true, whois: true });
- for (const name of Object.keys(marks)) expect(marks[name]).toBe(SCOPE_READ_OPS.has(name));
- for (const op of SCOPE_READ_OPS) expect(op === 'memory_recall' || marks[op] === true).toBe(true);
expect(fixture.memory_recall.scope_read).toEqual(v3.memory_recall.scope_read);
const rules = fixture.personal_tools.scope_read;
expect(rules.marked).toContain('never as the person');
@@ -346,3 +347,42 @@ describe('QM memory-provider contract v4 (GST-2407: memory_propose, E1 scope_rea
expect(fixture.errors.applies_to).toContain('memory_propose');
});
});
+
+describe('QM memory-provider contract v5 (GST-2407: context_pack reads its named source as the scope)', () => {
+ const fixture = JSON.parse(readFileSync(QM_CONTRACT_PATHS[5], 'utf8'));
+ const v4 = JSON.parse(readFileSync(QM_CONTRACT_PATHS[4], 'utf8'));
+ const sha = (bytes: string | Buffer) => createHash('sha256').update(bytes).digest('hex');
+
+ test('the committed fixture matches the live registry (regenerate with bun scripts/build-qm-memory-contract.ts)', () => {
+ expect(QM_CONTRACT_PATHS[5].endsWith(join('docs', 'contracts', 'qm-memory-provider', 'v5.json'))).toBe(true);
+ expect(readFileSync(QM_CONTRACT_PATHS[5], 'utf8')).toBe(renderQmMemoryContract(5));
+ });
+
+ test('v1 to v4 stay byte for byte as published, on disk and as the builder renders them', () => {
+ for (const [version, want] of [[1, V1_SHA256], [2, V2_SHA256], [3, V3_SHA256], [4, V4_SHA256]] as const) {
+ expect({ version, disk: sha(readFileSync(QM_CONTRACT_PATHS[version])), built: sha(renderQmMemoryContract(version)) }).toEqual({ version, disk: want, built: want });
+ }
+ });
+
+ test('it keeps everything v4 has; only the version, context_pack\'s marking and the scope_read rules change', () => {
+ expect(fixture.version).toBe(5);
+ for (const key of Object.keys(v4)) if (key !== 'version' && key !== 'personal_tools') expect(fixture[key]).toEqual(v4[key]);
+ const { scope_read: rules, tools: personalTools, ...rest } = fixture.personal_tools;
+ const { scope_read: v4Rules, tools: v4Tools, ...v4Rest } = v4.personal_tools;
+ expect(rest).toEqual(v4Rest);
+ expect(personalTools.map((t: { name: string; scope_read: boolean }) => (t.name === 'context_pack' ? { ...t, scope_read: false } : t))).toEqual(v4Tools);
+ const { context_pack: packRule, unmarked, ...ruleRest } = rules;
+ const { unmarked: v4Unmarked, ...v4RuleRest } = v4Rules;
+ expect(ruleRest).toEqual(v4RuleRest);
+ expect(v4Unmarked.startsWith(unmarked)).toBe(true);
+ expect(unmarked).not.toContain('context_pack');
+ for (const word of ['source_id', 'entity_refs', 'session_id', 'invalid_params', 'nothing is read']) expect(packRule).toContain(word);
+ });
+
+ test('each personal tool is marked scope_read from SCOPE_READ_OPS, and every scope-read op QM sees is marked', () => {
+ const marks = Object.fromEntries(fixture.personal_tools.tools.map((t: { name: string; scope_read: boolean }) => [t.name, t.scope_read]));
+ expect(marks).toEqual({ context_pack: true, entity: true, find_experts: true, forget_fact: false, get_backlinks: true, get_page: true, get_timeline: true, get_write_request: false, query: true, volunteer_context: true, whois: true });
+ for (const name of Object.keys(marks)) expect(marks[name]).toBe(SCOPE_READ_OPS.has(name));
+ for (const op of SCOPE_READ_OPS) expect(op === 'memory_recall' || marks[op] === true).toBe(true);
+ });
+});
diff --git a/test/qm-scope-read.test.ts b/test/qm-scope-read.test.ts
index e654813e9b..a217916133 100644
--- a/test/qm-scope-read.test.ts
+++ b/test/qm-scope-read.test.ts
@@ -219,16 +219,47 @@ for (const kind of testBackends()) {
expect((await call('person', 'get_backlinks', { slug: ACME, all_sources: true })).text).toContain('zephyr-restricted-example');
}, 120_000);
- test('context_pack that names sources is refused on a scope credential, never read as the person; unnamed and person credentials are unchanged', async () => {
- const c = await provider().registerClientManual('scope-ctx-' + randomUUID().slice(0, 8), ['client_credentials'], 'read write', [], SRC);
- await provider().rescopeClient(c.clientId, { federatedRead: [SRC, ROOM] });
- await bindCredential(engine, { kind: 'client', id: c.clientId }, { attestActor: 'qm', attestOps: [...SCOPE_OPS, 'context_pack'] });
- clients.ctx = { id: c.clientId, secret: c.clientSecret ?? '', token: (await provider().exchangeClientCredentials(c.clientId, c.clientSecret ?? '')).access_token };
- for (const params of [{ source_id: SRC }, { all_sources: true }, { entity_refs: [{ source_id: SRC, slug: RESTRICTED }] }]) {
- const out = await refused(call('ctx', 'context_pack', { counterparty: 'Zephyr Restricted Example', ...params }), 'invalid_params');
- expect(out.all).toContain('context_pack: a call that names sources');
+ test('GST-2407: context_pack that names sources reads only that source as its audience; a pack that would leave it is refused before any read', async () => {
+ for (const [name, read] of [['ctx', undefined], ['ctxp', 'person']] as const) {
+ const c = await provider().registerClientManual('scope-' + name + '-' + randomUUID().slice(0, 8), ['client_credentials'], 'read write', [], SRC);
+ await provider().rescopeClient(c.clientId, { federatedRead: [SRC, ROOM] });
+ await bindCredential(engine, { kind: 'client', id: c.clientId }, { attestActor: 'qm', attestOps: [...SCOPE_OPS, 'context_pack'], ...(read ? { attestRead: read } : {}) });
+ clients[name] = { id: c.clientId, secret: c.clientSecret ?? '', token: (await provider().exchangeClientCredentials(c.clientId, c.clientSecret ?? '')).access_token };
+ }
+ await engine.setConfig('memory.core.enabled', 'true');
+ await importFromContent(engine, 'notes/core-src-example', ['---', 'type: note', 'title: Core Src Example', 'always_load: true', '---', 'canarycoresrc harbor rules.'].join('\n'), { sourceId: SRC });
+ await importFromContent(engine, 'notes/core-room-example', ['---', 'type: note', 'title: Core Room Example', 'always_load: true', '---', 'canarycoreroom harbor rules.'].join('\n'), { sourceId: ROOM });
+ try {
+ const src = await call('ctx', 'context_pack', { entities: 'Acme Example,Zephyr Restricted Example,Ivo Galewright', counterparty: 'Acme Example', source_id: SRC });
+ expect(src.isError).toBe(false);
+ expect(src.structured?.cards?.map((card: { slug: string }) => card.slug)).toEqual([ACME]);
+ expect(src.all).toContain('canarycoresrc');
+ expect(src.all).not.toContain('canarycoreroom');
+ hidden(src);
+ const room = await call('ctx', 'context_pack', { entities: 'Room Example', counterparty: 'Acme Example', source_id: ROOM });
+ expect(room.isError).toBe(false);
+ expect(room.structured?.cards?.map((card: { slug: string }) => card.slug)).toEqual(['companies/room-example']);
+ expect(room.all).toContain('canarycoreroom');
+ for (const leak of ['canarycoresrc', 'acme-example', 'canaryworldacme', 'canaryworldtimeline']) expect(room.all).not.toContain(leak);
+ hidden(room);
+ const refs = await call('ctx', 'context_pack', { source_id: ROOM, entity_refs: [{ source_id: ROOM, slug: 'companies/room-example' }] });
+ expect(refs.structured?.cards?.map((card: { slug: string }) => card.slug)).toEqual(['companies/room-example']);
+ for (const params of [{ entity_refs: [{ source_id: SRC, slug: ACME }] }, { source_id: ROOM, entity_refs: [{ source_id: SRC, slug: RESTRICTED }] },
+ { source_id: ROOM, entity_refs: [{ slug: 'companies/room-example' }] }, { entities: 'Acme Example', source_id: SRC, session_id: 'session-a' }]) {
+ const out = await refused(call('ctx', 'context_pack', { counterparty: 'Zephyr Restricted Example', ...params }), 'invalid_params');
+ expect(out.all).toContain('context_pack: ');
+ expect(out.all).not.toContain('canarycore');
+ }
+ for (const params of [{ source_id: '__all__' }, { all_sources: true }]) await refused(call('ctx', 'context_pack', { entities: 'Acme Example', ...params }), 'invalid_params');
+ const other = await call('ctx', 'context_pack', { entities: 'Other Example', source_id: OTHER });
+ expect(other.isError).toBe(true);
+ expect(other.all).not.toContain('canaryotherpage');
+ expect((await call('ctx', 'context_pack', { counterparty: 'Zephyr Restricted Example' })).isError).toBe(false);
+ const person = await call('ctxp', 'context_pack', { entities: 'Acme Example', source_id: SRC, session_id: 'session-a' });
+ expect(person.isError).toBe(false);
+ } finally {
+ await engine.setConfig('memory.core.enabled', 'false');
}
- expect((await call('ctx', 'context_pack', { counterparty: 'Zephyr Restricted Example' })).all).not.toContain('context_pack: a call that names sources');
}, 120_000);
test('an agent job submitted for the person reads named sources as the scope too, exactly like the direct call', async () => {
diff --git a/test/serve-http-access.test.ts b/test/serve-http-access.test.ts
index 19ace7d131..2e741993e0 100644
--- a/test/serve-http-access.test.ts
+++ b/test/serve-http-access.test.ts
@@ -203,6 +203,29 @@ for (const kind of testBackends()) {
expect(await row()).toEqual({ attest_actor: null, attest_ops: null, attest_sources: null });
});
+ test('GST-2407: attestRead sets how named sources read over HTTP, as auth rescope --attest-read does; every CLI refusal holds', async () => {
+ const scope = 'scope-read-http-' + randomUUID().slice(0, 8);
+ await engine.executeRaw('INSERT INTO sources (id, name) VALUES ($1, $1)', [scope]);
+ const qm = await register('qm-read', ['client_credentials']);
+ const row = async () => (await engine.executeRaw<Record<string, unknown>>('SELECT attest_actor, attest_read FROM oauth_clients WHERE client_id = $1', [qm.clientId]))[0];
+ expect((await call('POST', '/admin/api/access/attest', { clientId: qm.clientId, attestRead: 'person' })).json).toMatchObject({ code: 'invalid_params' });
+ expect(await row()).toEqual({ attest_actor: null, attest_read: null });
+ expect((await call('POST', '/admin/api/access/attest', { clientId: qm.clientId, attestActor: 'qm', attestRead: 'person', dryRun: true })).json)
+ .toMatchObject({ applied: false, changed: true, attest_actor: 'qm', attest_read: 'person' });
+ expect(await row()).toEqual({ attest_actor: null, attest_read: null });
+ expect((await call('POST', '/admin/api/access/attest', { clientId: qm.clientId, attestActor: 'qm', attestRead: 'person' })).json).toMatchObject({ applied: true, attest_read: 'person' });
+ expect(await row()).toEqual({ attest_actor: 'qm', attest_read: 'person' });
+ const auth = await provider().verifyAccessToken((await provider().exchangeClientCredentials(qm.clientId, qm.clientSecret!)).access_token) as unknown as { attest?: { read?: string } };
+ expect(auth.attest?.read).toBe('person');
+ expect((await call('POST', '/admin/api/access/attest', { clientId: qm.clientId, attestRead: 'scope' })).json).toMatchObject({ applied: true, attest_read: 'scope' });
+ expect((await call('POST', '/admin/api/access/attest', { clientId: qm.clientId, attestRead: 'room' })).status).toBe(400);
+ await bindCredential(engine, { kind: 'client', id: qm.clientId }, { attestSources: [scope] });
+ expect((await call('POST', '/admin/api/access/attest', { clientId: qm.clientId, attestRead: 'person' })).json).toMatchObject({ code: 'invalid_params' });
+ expect((await call('POST', '/admin/api/access/attest', { clientId: qm.clientId, attestRead: null })).json).toMatchObject({ applied: true, attest_read: null });
+ expect(await row()).toEqual({ attest_actor: 'qm', attest_read: null });
+ expect((await audits()).filter(a => a.action === 'client_attest' && a.client_id === qm.clientId).map(a => a.attest_read)).toEqual(['person', 'scope', null]);
+ });
+
test('the audit rows an applied change writes are never read as client usage', async () => {
expect((await call('POST', '/admin/api/access/members', { action: 'add', id: 'usage-example' })).json).toMatchObject({ applied: true });
expect((await audits()).some(a => a.action === 'member_add' && a.member === 'usage-example')).toBe(true);