Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Keep shared-agent and attested writes for a labelled-only member labelled-only when a lookup fails
garrytand8aba9dfc6c6
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex e3ae70b913..0083a19a49 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -12,18 +12,20 @@ identifiers and attribution are available in the pre-removal Git revision## [Unreleased]-**A labelled-only member no longer reads and writes as an unbound guest when the database hiccups.** When gbrain looks up which member a token, OAuth client or local server is bound to, a dropped connection, a timeout or a failed statement used to look the same as "bound to nobody". A credential bound to nobody reads and writes every page that names no readers, so during that hiccup a member kept to its labelled pages could read, overwrite or create unlabelled pages. Now the request fails with `access_identity_unavailable`, a retryable error that tells the agent to wait a few seconds and send the same request again; nothing is read or written. Credentials that really are unbound read exactly as before, and so does every caller on a brain whose database predates member access.+**A labelled-only member no longer reads and writes as an unbound guest when the database hiccups.** When gbrain looks up which member a token, OAuth client or local server is bound to, a dropped connection, a timeout or a failed statement used to look the same as "bound to nobody". A credential bound to nobody reads and writes every page that names no readers, so during that hiccup a member kept to its labelled pages could read, overwrite or create unlabelled pages. Now the request fails with `access_identity_unavailable`, a retryable error that tells the agent to wait a few seconds and send the same request again; nothing is read or written. A queued write that meets a lock or statement timeout there is still retried by itself, as before. A shared agent's write for a labelled-only member, or a trusted system's write for a person it vouches for, stays labelled-only when the lookup of who it writes for fails. Credentials that really are unbound read exactly as before, and so does every caller on a brain whose database predates member access.### Itemized changes#### Member lookups fail closed-- `src/core/access/caller.ts`: `liveIdentity` (behind `memberIdentityFor` and `stdioMemberIdentity`) throws `access_identity_unavailable` when its lookup fails, instead of returning the empty identity. An unbound credential, an unknown member and a disabled or removed member stay empty. A missing table or column (SQLSTATE 42P01 or 42703, the same code on PGLite and Postgres) still reads as unbound: every table and column the lookup reads arrived with the member-access migration, before the labelled-only column, so no member of any kind can exist there.-- New error code `access_identity_unavailable` (`src/core/error-registry.ts`, `src/core/error-catalogue.ts`): class `retryable`, `retry_after_ms=2000`, and a fix whose `next` is `wait` that calls `whoami` to confirm the binding reads again. Documented in `docs/guides/write-refusals.md` and `docs/guides/error-codes.md`.+- `src/core/access/caller.ts`: `liveIdentity` (behind `memberIdentityFor` and `stdioMemberIdentity`) no longer returns the empty identity when its lookup fails. A statement the database rejects throws `access_identity_unavailable`. A transient failure (`transientDatabaseFailure` or `transientInterruption`: a dropped connection, a lock or statement timeout, a stale plan, a publication past its ceiling) and any failure that is not a statement error (a preparation deadline, an abort) are rethrown unchanged, so the persistence consumer still releases and retries the write. An unbound credential, an unknown member and a disabled or removed member stay empty. A missing `access_members` or `access_group_members` table or `member_id` column (`isMissingSchemaObject`) still reads as unbound: all three arrived with the member-access migration, before the labelled-only column, so no member of any kind can exist there; any other missing table or column throws.+- `src/core/persistence/page-visibility.ts`: a stored write's labelled-only check also reads the grant of the members its stored audience names and of its attested actor's member, so a re-resolution that fails and reads as the guest identity never makes a labelled-only member's write unlabelled. A database failure while re-resolving the attested actor is rethrown (the write is retried) instead of reading as the guest; a coded refusal (an audience no longer permitted, an actor no longer linked) still reads as the guest.+- `src/core/persistence/transient-retry.ts`: `transientDatabaseFailure` and `connectionCapFailure` move here from `coordinator.ts`, which re-exports them, so the access lookup can use them without an import cycle that fails at module load.+- New error code `access_identity_unavailable` (`src/core/error-registry.ts`, `src/core/error-catalogue.ts`): class `retryable`, `retry_after_ms=2000`, and a fix whose `next` is `wait` that calls `whoami` to confirm the binding reads again (the error-code table's Verify column now says `gbrain whoami --json` too). Documented in `docs/guides/write-refusals.md` and `docs/guides/error-codes.md`.- `src/mcp/dispatch.ts`: a coded error raised while resolving the caller's access comes back as an MCP error result, as every other refusal does, instead of a thrown call.-- `src/mcp/server.ts`: `gbrain serve` with a stdio member still starts when that member's lookup fails at startup; its writeback instructions treat the server as bound to a member, which keeps its writes private.+- `src/mcp/server.ts`: `gbrain serve` with a stdio member still starts when that member's lookup fails at startup with `access_identity_unavailable` or a transient database failure; its writeback instructions treat the server as bound to a member, which keeps its writes private. Any other error is thrown.- `src/core/persistence/page-visibility.ts`: the labelled-only create check drops a shortcut that skipped the check when the request's own policy said the brain had no restrictions. The check runs inside the persistence consumer, where that policy is never set, so the shortcut never fired; the check now always asks the database whether any labelled-only member exists.-- Tests: `test/access-labelled-only-fail-closed.test.ts` on PGLite and Postgres. A labelled-only credential whose lookups fail gets `access_identity_unavailable` on `get_page`, `list_pages`, `search` and the stdio binding, and cannot update or create an unlabelled page; a missing table or column still reads as unbound. It also pins the create refusal when the grant reaches a brain that served unrestricted requests. It covers one long-lived engine, a member that already wrote, a second serve process (Postgres only, because PGLite locks its data directory to one process) and `access.restrictions_present` deleted by hand. A failed visibility probe never lets a write through inside a transaction, and outside one it counts as labelled-only.+- Tests: `test/access-labelled-only-fail-closed.test.ts` on PGLite and Postgres. A labelled-only credential whose lookups fail gets `access_identity_unavailable` on `get_page`, `list_pages`, `search` and the stdio binding, and cannot update or create an unlabelled page; a missing member table or `member_id` column still reads as unbound, and any other missing object throws. A transient lookup failure is rethrown unchanged, and an owner `put_page` whose stored-write lookup meets one lock timeout still commits. A stored write for a labelled-only member through an audience or an attested actor stays refused when that lookup fails. It also pins the create refusal when the grant reaches a brain that served unrestricted requests. It covers one long-lived engine, a member that already wrote, a second serve process (Postgres only, because PGLite locks its data directory to one process) and `access.restrictions_present` deleted by hand. A failed visibility probe never lets a write through inside a transaction, and outside one it counts as labelled-only.## [0.60.704.0] - 2026-11-12diff --git a/docs/architecture/key-files/access.md b/docs/architecture/key-files/access.mdindex 068348ffe3..be9799d7be 100644--- a/docs/architecture/key-files/access.md+++ b/docs/architecture/key-files/access.md@@ -3,7 +3,7 @@[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; a binding lookup that fails throws `access_identity_unavailable` (retryable, `fix.next: wait`) instead of reading as unbound, and only a schema older than the member tables (SQLSTATE 42P01 or 42703) reads as unbound). 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`). GBRA-108 design 1 (the labelled-only migration, `schema-migrations/v*-access-labelled-only.ts`): `access_members.labelled_only` (`labelled-only.ts` `setMemberLabelledOnly`, local only, refused on the owner with `access_labelled_only_owner` from `owner.ts`, which `setOwner` also raises) sets `CallerAccess.labelledOnly` (`caller.ts`, `actor.ts`, `as-preview.ts`; fails closed to true when the table cannot be read). `private-visibility.ts` `labelledOnlySql` ANDs `page_readers && identity OR folder_rule_ids && satisfied` into `callerAccessSql`, `callerReadersAllowedSql` (a snapshot needs its own readers or a rule on the live page) and the fact filters (`labelledOnlyFactSql`: a fact on the caller's own member page while it names the member, or under member lineage a provenance page that passes; else FALSE); under member lineage a derived row may pass through `gbrain_access_origin_labelled_for()` (every origin labelled, none missing). Remote read gates that are not caller-aware use `remoteReadFloorSql` / `remoteProvenanceFloorSql` (the plain fragment, plus the labelled-only conjunct only for a labelled-only caller); `test/remote-read-floor.test.ts` lists the sites that keep the plain fragment. `labelledOnlyFor` never reports the configured owner, and dispatch refuses a scope read for a labelled-only person (`scope-read.ts` `scopeReadLabelledOnlyRefused`). The entity page of a fact is judged by the ordinary policy. Writes: `persistence/page-visibility.ts` (`writerReadPolicySql`, `remoteLabelsChecked` → `assertLabelledOnlyCreate` → `access_labelled_only_unnamed`), `cli/enforced-member.ts` `memberPageView`. Cache keys `xlo=1`, `labelled_only`; doctor `access_labelled_only_members` (`checks/access-labelled-only.ts`). Test: `test/access-labelled-only.test.ts` (both engines, both storesA 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/` (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; a binding lookup that fails never reads as unbound: a statement error throws `access_identity_unavailable` (retryable, `fix.next: wait`), a transient failure (`transientDatabaseFailure`, `transientInterruption` in `persistence/transient-retry.ts`) or a non-statement failure is rethrown unchanged for the persistence consumer, and only a schema missing `access_members`, `access_group_members` or `member_id` reads as unbound). 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`). GBRA-108 design 1 (the labelled-only migration, `schema-migrations/v*-access-labelled-only.ts`): `access_members.labelled_only` (`labelled-only.ts` `setMemberLabelledOnly`, local only, refused on the owner with `access_labelled_only_owner` from `owner.ts`, which `setOwner` also raises) sets `CallerAccess.labelledOnly` (`caller.ts`, `actor.ts`, `as-preview.ts`; fails closed to true when the table cannot be read). `private-visibility.ts` `labelledOnlySql` ANDs `page_readers && identity OR folder_rule_ids && satisfied` into `callerAccessSql`, `callerReadersAllowedSql` (a snapshot needs its own readers or a rule on the live page) and the fact filters (`labelledOnlyFactSql`: a fact on the caller's own member page while it names the member, or under member lineage a provenance page that passes; else FALSE); under member lineage a derived row may pass through `gbrain_access_origin_labelled_for()` (every origin labelled, none missing). Remote read gates that are not caller-aware use `remoteReadFloorSql` / `remoteProvenanceFloorSql` (the plain fragment, plus the labelled-only conjunct only for a labelled-only caller); `test/remote-read-floor.test.ts` lists the sites that keep the plain fragment. `labelledOnlyFor` never reports the configured owner, and dispatch refuses a scope read for a labelled-only person (`scope-read.ts` `scopeReadLabelledOnlyRefused`). The entity page of a fact is judged by the ordinary policy. Writes: `persistence/page-visibility.ts` (`writerReadPolicySql`, `remoteLabelsChecked` → `assertLabelledOnlyCreate` → `access_labelled_only_unnamed`), `cli/enforced-member.ts` `memberPageView`. Cache keys `xlo=1`, `labelled_only`; doctor `access_labelled_only_members` (`checks/access-labelled-only.ts`). Test: `test/access-labelled-only.test.ts` (both engines, both storesA 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.diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.mdindex ce42f8b46e..0768c26da2 100644--- a/docs/guides/error-codes.md+++ b/docs/guides/error-codes.md@@ -78,7 +78,7 @@ More: [docs/guides/google-connect.md#troubleshooting](../../docs/guides/google-c| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable ||---|---|---|---|---|---|---|-| The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up, so the request was refused and nothing was read or written. | Reading the binding failed: a dropped connection, a timeout or a failed statement. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member, so the request stops, and the same request succeeds once the database answers. | Retry the same request in a few seconds (a write with the same request_id); if it keeps failing, ask the brain operator to run gbrain doctor --json on the brain host. | provider | `repeat the read that failed` | 1 | yes |+| The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up, so the request was refused and nothing was read or written. | Reading the binding failed with a database error. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member, so the request stops, and the same request succeeds once the database answers. | Retry the same request in a few seconds (a write with the same request_id); if it keeps failing, ask the brain operator to run gbrain doctor --json on the brain host. Run: gbrain whoami --json | provider | `gbrain whoami --json` | 1 | yes |More: [docs/guides/write-refusals.md#access_identity_unavailable](../../docs/guides/write-refusals.md#access_identity_unavailable)diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex 7937d532a1..3cd631bfd3 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -1047,7 +1047,7 @@ same on a repo-less brain and on a git-backed one.| <a id="access_member_invalid"></a>`access_member_invalid` | A member or group id given to `gbrain access`, to `--member` on `gbrain auth create`, `rescope` or `register-client`, or to a local `--as <member>` is ill-formed (`ill_formed`) or names no usable member (`unknown`, `disabled`, `removed`, `unknown_group`), or `member add` named an existing member (`exists`). A member's declared email (`--email` on `member add` or `member set`) is not an address (`invalid_email`), another member already declares it (`email_taken`), or `member link --email` found several members declaring it (`email_ambiguous`; the email is unique, so this means a damaged table). Nothing was read or changed: an unknown `--as` is refused before the command runs instead of reading as unbound. | Check the id with `gbrain access member list --all`; add the member with `gbrain access member add <id>` or enable it with `gbrain access member enable <id>`. Ids are 1-64 characters: lower-case letters, digits, `.`, `_` or `-`. An email has one `@`, no spaces and at most 254 characters; clear a taken one with `gbrain access member set <id> --email none`, and link by member id when an email is ambiguous. `member link --email` naming an email no member declares is `not_found`; it never creates a member. || <a id="access_member_id_retired"></a>`access_member_id_retired` | `gbrain access member add` or `enable` named an id that `gbrain access member rm --yes` removed. Member ids are never reused, because pages and audit history may still name the removed id. Nothing was created. | Choose a new member id. `gbrain access member disable` is the reversible way to pause a member. || <a id="access_member_disabled"></a>`access_member_disabled` | The access token or OAuth client is bound to a member who is disabled, removed or missing, so it was refused at verification (HTTP 401, `invalid_token` with this code in the description). A credential bound to a member reads as that member, so it is refused rather than silently treated as unbound. | Ask the brain operator to run `gbrain access member enable <id>`, or to rebind the credential with `gbrain auth rescope --token <name> --member <id>` (`--member none` unbinds it; an unbound credential sees no page that names readers). |-| <a id="access_identity_unavailable"></a>`access_identity_unavailable` | The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up: the database dropped the connection, timed out or failed the statement. The request was refused and nothing was read or written. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member. | Retry the same request in a few seconds; a write keeps the same `request_id`. `whoami` shows the member the connection reads as once the lookup works again. If it keeps failing, the brain operator runs `gbrain doctor --json` on the brain host. |+| <a id="access_identity_unavailable"></a>`access_identity_unavailable` | The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up: the database failed the statement. The request was refused and nothing was read or written. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member. | Retry the same request in a few seconds; a write keeps the same `request_id`. `whoami` shows the member the connection reads as once the lookup works again. If it keeps failing, the brain operator runs `gbrain doctor --json` on the brain host. || <a id="access_rule_invalid"></a>`access_rule_invalid` | `gbrain access rule add` was given a rule whose prefix is not a literal lower-case slug folder ending in `/` (or holds `..` or `*`), whose readers are not member ids or `group:<id>`, or whose prefix another rule already covers; nothing was written. Prefixes match slugs literally, so a pattern or typo would restrict the wrong pages. | Write the prefix as a folder such as `partners/alice-example/` and the readers as `alice-example,group:team-a`; to change who reads a folder that already has a rule, pass that rule's `--id`. || <a id="access_policy_invalid"></a>`access_policy_invalid` | A source's committed `.gbrain/access.yml` (or a file given to `gbrain access rule import`) does not validate. The last applied rules stay in force and every prefix the file names reads as nobody for remote callers (the whole source when the file does not parse), so a typo never opens a folder. In a partial clone (`git clone --filter`), a policy file or an earlier version of it that the clone never fetched makes the whole source read as nobody the same way, because sync fetches nothing. | `gbrain access rule list --source <id>` shows each problem with its line. Fix the file, commit it with `gbrain git commit-push`, and run `gbrain sync --source <id> --no-pull`. In a partial clone, run the `git cat-file -p` or `git log -p` the problem names in the checkout, which fetches what is missing, then sync the same way. || <a id="access_policy_pending"></a>`access_policy_pending` | A narrowing change to a source's folder rules is still being stamped onto its pages, so pages under the folders it touches read as nobody for remote callers until it finishes (other folders keep the last applied rules). Remote reads carry this as a notice: an empty answer there is not proof of no notes. | Wait and retry. If it stays pending the apply was interrupted: on the brain host run `gbrain access resume --source <id>` (database store) or `gbrain sync --source <id> --no-pull` (git store); `gbrain access rule status --source <id>` shows the pending folders. |diff --git a/src/core/access/caller.ts b/src/core/access/caller.tsindex 3fcf4e29e4..6b2a92ec23 100644--- a/src/core/access/caller.ts+++ b/src/core/access/caller.ts@@ -12,13 +12,19 @@* hand. A remote read or write on a brain with no member-access restriction* and no owner never looks a binding up. An empty identity means the* credential is unbound or its member is unknown, disabled or removed; it- * reads no restricted page. A lookup that fails (a dropped connection, a- * timeout, a failed statement) throws access_identity_unavailable, which is- * retryable: reading the credential as unbound instead would open every- * unlabelled page to a labelled-only member. The one failure that stays empty- * is a schema older than the member tables (v282), whose lookup misses a table- * or column (SQLSTATE 42P01 or 42703 on both engines); no member, labelled-only- * (v308) or not, can exist there, and every owner caller there is unbound.+ * reads no restricted page. A lookup that fails never reads as unbound, which+ * would open every unlabelled page to a labelled-only member. A statement the+ * database rejected (a SQLSTATE) throws access_identity_unavailable, which is+ * retryable, unless the persistence consumer's transientDatabaseFailure or+ * transientInterruption classifies it (a dropped connection, a lock or+ * statement timeout, a stale plan, a publication past its ceiling); that, and+ * every failure that is not a statement error (a preparation deadline, an+ * abort, a coded refusal), is rethrown unchanged, so a stored write keeps its+ * consumer's release, retry and deadline handling. The one failure that stays+ * empty is a schema older than the member tables (v282), whose lookup misses+ * access_members, access_group_members or the member_id column; no member,+ * labelled-only (v308) or not, can exist there, and every owner caller there+ * is unbound.*/import type { BrainEngine } from '../engine.ts';import type { AuthInfo } from '../ops/contract.ts';@@ -33,6 +39,8 @@ import { edgeTrimSql } from '../edge-whitespace.ts';import { GUEST, STDIO_MAY_ACT_FOR_KEY, mayActForCovers, singleMemberAudience, type AudiencePrincipal } from './audience.ts';import { audienceMemberIds, parseMayActFor } from './members.ts';import { labelledOnlyFor } from './labelled-only.ts';+import { isMissingSchemaObject } from '../utils.ts';+import { transientDatabaseFailure, transientInterruption } from '../persistence/transient-retry.ts';/** Config key binding a local stdio MCP server to one member. */export const STDIO_MEMBER_KEY = 'mcp.stdio_member';@@ -43,15 +51,17 @@ const MEMBERS_WHERE_SQL = (predicate: string) => `SELECT m.id, COALESCE(array_agGROUP BY m.id`;const MEMBER_SQL = (member: string) => MEMBERS_WHERE_SQL(`m.id = (${member})`);-/** Missing table and missing column: the lookup's schema predates the member tables (v282). */-const SCHEMA_PREDATES_MEMBERS = new Set(['42P01', '42703']);+/** The objects v282 added that the lookup reads: a schema without them predates the member tables. */+const MEMBER_TABLES = ['access_members', 'access_group_members'];+const MEMBER_COLUMN = 'member_id';+const SQLSTATE_RE = /^[0-9A-Z]{5}$/;const IDENTITY_RETRY_AFTER_MS = 2_000;const WHOAMI: NonNullable<Action['verify']> = { argv: ['gbrain', 'whoami', '--json'], mcp: { tool: 'whoami', arguments: {} } };function identityUnavailable(): OperationError {return opError('access_identity_unavailable', 'The member this connection is bound to could not be looked up, so nothing was read or written.','Retry the same request in a few seconds (a write with the same request_id); if it keeps failing, ask the brain operator to run gbrain doctor --json on the brain host.', {- why: 'Reading the credential\'s member binding failed (a dropped connection, a timeout or a failed statement). Reading the connection as unbound instead would open pages its member may not read, so the request stops here.',+ why: 'Reading the credential\'s member binding failed with a database error. Reading the connection as unbound instead would open pages its member may not read, so the request stops here.',detail: `retry_after_ms=${IDENTITY_RETRY_AFTER_MS}`,fix: { ...WHOAMI, consent: [], actor: 'provider', requires_exclusive: false, verify: WHOAMI,why: 'After a few seconds whoami reads the binding again and shows the member this connection reads as; then repeat the original request.' },@@ -63,8 +73,10 @@ async function liveIdentity(engine: Pick<BrainEngine, 'executeRaw'>, memberSql:try {[row] = await engine.executeRaw<{ id: string; groups: string[] }>(MEMBER_SQL(memberSql), [param]);} catch (error) {- if (SCHEMA_PREDATES_MEMBERS.has(String((error as { code?: unknown } | null)?.code))) return [];- throw error instanceof OperationError ? error : identityUnavailable();+ if (isMissingSchemaObject(error, 'table', MEMBER_TABLES) || isMissingSchemaObject(error, 'column', MEMBER_COLUMN)) return [];+ const code = (error as { code?: unknown } | null)?.code;+ if (typeof code !== 'string' || !SQLSTATE_RE.test(code) || transientDatabaseFailure(error) || transientInterruption(error)) throw error;+ throw identityUnavailable();}if (!row || normalizePrincipal(`member:${row.id}`) !== `member:${row.id}`) return [];const groups = (row.groups ?? []).filter(g => normalizePrincipal(`group:${g}`) === `group:${g}`);@@ -74,8 +86,8 @@ async function liveIdentity(engine: Pick<BrainEngine, 'executeRaw'>, memberSql:/*** The member identity bound to `auth`: the verifier's join when present, else a lookup from its principal (a local* stdio principal reads the member its serve was started with, stamped as `stdioMember` on a stored write, else- * config mcp.stdio_member, as stdio reads do); empty when unbound or the member is unknown or not enabled, and- * access_identity_unavailable when the lookup fails (liveIdentity). A write's publication passes only its stored+ * config mcp.stdio_member, as stdio reads do); empty when unbound or the member is unknown or not enabled; a lookup+ * that fails throws (liveIdentity: a transient database failure unchanged, else access_identity_unavailable). A write's publication passes only its stored* principal, so a member disabled or a binding removed after submission takes effect.*/export async function memberIdentityFor(engine: Pick<BrainEngine, 'executeRaw'>, auth: Pick<AuthInfo, 'member'> & { principal?: { kind: string; id: string }; stdioMember?: string } | undefined): Promise<string[]> {@@ -102,8 +114,8 @@ export async function stdioMemberId(engine: BrainEngine): Promise<string | null>/*** The identity of a local stdio server: the live member its serve was started with (--stdio-member), else the live* member config mcp.stdio_member names, else empty. A named member that is disabled or unknown reads as nobody and- * never falls back to the config key; a lookup that fails throws access_identity_unavailable. With no member named it- * runs no query.+ * never falls back to the config key; a lookup that fails throws (liveIdentity). With no member named it runs no+ * query.*/export async function stdioMemberIdentity(engine: BrainEngine, registered?: string): Promise<string[]> {const member = registered ?? await stdioMemberId(engine);diff --git a/src/core/error-registry.ts b/src/core/error-registry.tsindex 1346ce4d9b..73d0d8b1bb 100644--- a/src/core/error-registry.ts+++ b/src/core/error-registry.ts@@ -64,7 +64,7 @@ export interface CodeEntry {export const CODES = {absent_from_worktree: { class: 'caller', retryable: false, reasons: ['skip_worktree', 'deleted_locally'], summary: "Sync held one file that is committed at HEAD but missing from the working tree (a sparse checkout or a skip-worktree bit, or a local deletion that is not committed); the rest of the source synced.", why: "Sync imports from the working tree, so it cannot import a file that is not on disk, and treating it as deleted would drop a committed file silently. Whether the file comes back or its deletion is committed is the user's choice; classic sync re-screens the hold on every run.", docs: 'docs/guides/write-refusals.md#absent_from_worktree', suggestion: 'Restore the file (git restore -- <path>, or widen the sparse checkout) and the next sync imports it; or commit the deletion with gbrain git commit-push -m <msg> -- <path> and the next sync clears the hold.' },access_command_failed: { class: 'caller', summary: "Google connect credential error: access command failed.", docs: 'docs/guides/google-connect.md#troubleshooting' },- access_identity_unavailable: { class: 'retryable', actor: 'provider', summary: "The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up, so the request was refused and nothing was read or written.", why: "Reading the binding failed: a dropped connection, a timeout or a failed statement. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member, so the request stops, and the same request succeeds once the database answers.", docs: 'docs/guides/write-refusals.md#access_identity_unavailable', suggestion: 'Retry the same request in a few seconds (a write with the same request_id); if it keeps failing, ask the brain operator to run gbrain doctor --json on the brain host.' },+ access_identity_unavailable: { class: 'retryable', actor: 'provider', summary: "The member a credential (access token, OAuth client or stdio binding) is bound to could not be looked up, so the request was refused and nothing was read or written.", why: "Reading the binding failed with a database error. Reading the credential as unbound instead would open every unlabelled page to a labelled-only member, so the request stops, and the same request succeeds once the database answers.", docs: 'docs/guides/write-refusals.md#access_identity_unavailable', suggestion: 'Retry the same request in a few seconds (a write with the same request_id); if it keeps failing, ask the brain operator to run gbrain doctor --json on the brain host.', fix: { argv: ['gbrain', 'whoami', '--json'], consent: [], actor: 'provider', requires_exclusive: false, why: 'Read-only: after a few seconds whoami reads the binding again and shows the member this connection reads as; then repeat the original request.', verify: { argv: ['gbrain', 'whoami', '--json'] } } },access_member_disabled: { class: 'host_only', actor: 'user', reasons: ['disabled', 'removed', 'missing', 'malformed'], summary: "The credential (access token, OAuth client or stdio binding) is bound to a member who is disabled, removed or missing, so it was refused at verification and nothing was read.", why: 'A credential bound to a member reads as that member. While the member cannot read, the credential is refused rather than silently treated as unbound.', docs: 'docs/guides/write-refusals.md#access_member_disabled', suggestion: 'Ask the brain operator to enable the member (gbrain access member enable <id>) or rebind the credential (gbrain auth rescope --token <name>|--client <id> --member <id>|none).' },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.", why: 'The audience decides whose notes the agent may read, so an audience gbrain cannot read exactly is refused instead of guessed.', docs: 'docs/guides/write-refusals.md#on_behalf_of_invalid_audience', 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.' },on_behalf_of_unknown_member: { class: 'caller', summary: "A shared agent's audience names a member who is not enabled on this brain, or a group that does not exist, so nothing was read.", why: 'An unknown or disabled entry is refused rather than read as a guest, so a typo or a removed person never quietly changes what the agent reads.', docs: 'docs/guides/write-refusals.md#on_behalf_of_unknown_member', suggestion: 'Name enabled members and existing groups only (gbrain access member list --all, gbrain access group list on the brain host); a person who is not a member joins the audience as guest.' },diff --git a/src/core/persistence/coordinator.ts b/src/core/persistence/coordinator.tsindex cbb5db5221..0ad852baf2 100644--- a/src/core/persistence/coordinator.ts+++ b/src/core/persistence/coordinator.ts@@ -16,10 +16,10 @@ import { acquireWorktree, getWorktreeBinding, guardOwnership, type WorktreeBindiimport { chargePreparationAttempt, clearResolvedRecovery, completeWrite, getWriteRequestById, lockCounters, markRecovering, prepareRecovery, releaseUnpublishedClaim } from './journal.ts';import type { WaitingOn } from './claim-phase.ts';import { PREPARATION_BUDGET_KEYS, preparationKind } from './preparation-budget.ts';-import { chargeTransientInterruption, chargedInterruptionDetail, transientInterruption, type TransientInterruption } from './transient-retry.ts';+import { chargeTransientInterruption, chargedInterruptionDetail, connectionCapFailure, transientDatabaseFailure, transientInterruption, type TransientInterruption } from './transient-retry.ts';+export { connectionCapFailure, transientDatabaseFailure } from './transient-retry.ts';import { readWriteSwitchSnapshot } from './switches.ts';import { isSharedReadFailure } from './bounded-reads.ts';-import { isStalePlanError } from '../retry-matcher.ts';import { isBundleRecovery, isTerminal, PAGES_RECOVERY_MAX_FILES, principalKey, requestPrincipal, recoveryFiles, type FileRecoveryRecord, type RecoveryRecord, type WriteRequest } from './model.ts';import { isLockOpenFailure, noteLockOpenFailure, type NativeLockHandle } from './native-lock.ts';import { withCoordinatedWrite } from './context.ts';@@ -57,7 +57,6 @@ import { recordPublicationFenceTrend } from '../fence-repair/census-store.ts';import { segmentWriteScope } from '../page-body/ingest.ts';import { publicationBeliefOptions, withBeliefBatch } from '../belief/ledger.ts';import { markBeliefCommits } from '../belief/append.ts';-import { classifyPgAccessError } from '../pg-access-classify.ts';import { commitThroughDoor, doorCommitLanded, doorMarker, replayAfterDoorCommit, sourceCanonicalGit, strictChanged } from './git-door.ts';import { assertNoPrivateCommit, declareStrictPublication } from './git-declared.ts';@@ -254,17 +253,6 @@ function requestError(error: unknown): PublicationFailure {function conflictCode(code: string): boolean { return ['revision_required','revision_conflict','revision_backfill_pending','source_changed','page_identity_changed',SYNC_CURSOR_REPLACED,SYNC_PASS_SUPERSEDED].includes(code); }/** The terminal state of an unpublished failure: `admission_paused` (#6712 PR 4b, a destructive write `sync.admission` paused at publication) is `cancelled`. */function failureState(code: string): 'conflict' | 'failed' | 'cancelled' { return code === 'admission_paused' ? 'cancelled' : conflictCode(code) ? 'conflict' : 'failed'; }-export function transientDatabaseFailure(error: unknown): boolean {- return ['40001','40P01','55P03','57014','53300','57P01','57P02','57P03','08000','08003','08006','08001','08004',- 'ECONNRESET','ECONNREFUSED','ETIMEDOUT','CONNECTION_CLOSED','CONNECTION_ENDED'].includes(String((error as {code?:string})?.code)) || connectionCapFailure(error) || isStalePlanError(error);-}-/**- * GBRA-133: a pooler's client cap (Supavisor `EMAXCONNSESSION`, "too many clients already") is the same contention as- * SQLSTATE 53300 whatever code the pooler sends with it, so a write that meets it is released, never failed terminally.- */-export function connectionCapFailure(error: unknown): boolean {- return classifyPgAccessError(error).reason === 'pool_exhausted';-}/*** Flip lane C: the shared-read failures (`sharedReadFailure`) already charged. A group's memoized read the database cancelled* ran once, for the whole group, and every member waiting on it gets the same failure: it is charged once, to the firstdiff --git a/src/core/persistence/page-visibility.ts b/src/core/persistence/page-visibility.tsindex a16c6fc905..23e0405fcd 100644--- a/src/core/persistence/page-visibility.ts+++ b/src/core/persistence/page-visibility.ts@@ -1,4 +1,4 @@-import { opError } from '../ops/contract.ts';+import { OperationError, opError } from '../ops/contract.ts';import { callerAccessAllowedSql, callerIdentities, currentCallerAccess, labelledOnlyForSql, OWNER_MEMBER_KEY, privatePagesFilterForCaller, readPolicyFragment, readRemotePolicyNow, resolveExcludePrivatePages, withCallerAccess } from '../search/private-visibility.ts';import { anyLabelledOnlyMember, labelledOnlyFor } from '../access/labelled-only.ts';import { hostFix } from '../ops/op-fix.ts';@@ -89,13 +89,18 @@ export async function writerReadPolicySql(engine: SqlEngine, authority: WriteAut/*** GBRA-108 design 1: a stored write is labelled-only when its credential's member, or a member it writes for, carries- * the grant (labelledOnlyFor); never the owner.+ * the grant (labelledOnlyFor); never the owner. The members it writes for are taken from the stored authority (the+ * audience's member entries, the attested actor's member) as well as from their re-resolved identities, so a+ * re-resolution that reads as the guest identity never makes a labelled-only member's write unlabelled.*/async function writerLabelledOnly(engine: SqlEngine, authority: WriteAuthority, identities: readonly (readonly string[])[]): Promise<boolean> {- const bound = authority.actingFor && !Array.isArray(authority.actingFor) ? [] : await memberIdentityFor(engine, authority);+ const attested = authority.actingFor && !Array.isArray(authority.actingFor);+ const bound = attested ? [] : await memberIdentityFor(engine, authority);+ const actor = attested ? parseStoredActor(authority.actingFor) : null;+ const stored = actor ? [`member:${actor.member}`] : Array.isArray(authority.actingFor) ? authority.actingFor.filter(p => p.startsWith('member:')) : [];const [owner] = await engine.executeRaw<{ value: string }>('SELECT value FROM config WHERE key = $1', [OWNER_MEMBER_KEY]);const ownerId = owner?.value?.trim();- const members = [...identities, bound].filter(id => !(ownerId && id.includes(`member:${ownerId}`)));+ const members = [...identities, bound, ...stored.map(p => [p])].filter(id => !(ownerId && id.includes(`member:${ownerId}`)));return labelledOnlyFor(engine, members);}@@ -135,21 +140,24 @@ export async function remoteLabelsChecked<T extends { parsedPage: { frontmatter:/*** The identities a stored write is checked under, re-resolved live: the principal's member, or (GBRA-231) every entry- * of the audience it was accepted for, bounded by the principal's live may_act_for. An audience no longer permitted- * or naming a disabled member resolves to the guest identity, which reads no restricted page (fail closed).+ * of the audience it was accepted for, bounded by the principal's live may_act_for. An audience no longer permitted,+ * naming a disabled member or an actor no longer covered (a coded refusal) resolves to the guest identity, which reads+ * no restricted page (fail closed; writerLabelledOnly still reads the stored members). A database failure is rethrown,+ * so the write is retried or fails instead of being checked as the guest.*/async function writerIdentities(engine: SqlEngine, authority: WriteAuthority): Promise<string[][]> {+ const refusedAsGuest = (error: unknown): string[] => { if (error instanceof OperationError) return []; throw error; };if (authority.actingFor && !Array.isArray(authority.actingFor)) {// GST-359 C1: an attested write reads as its member only while actorCoverage still covers the same member.const actor = parseStoredActor(authority.actingFor);- return [actor ? await storedActorIdentity(engine, authority.principal, actor).catch(() => []) : []];+ return [actor ? await storedActorIdentity(engine, authority.principal, actor).catch(refusedAsGuest) : []];}if (!authority.actingFor?.length) return [await memberIdentityFor(engine, authority)];try {return await resolveAudienceIdentities(engine, { principal: authority.principal, transport: authority.principal.kind === 'local_stdio' ? 'stdio' : 'http' },authority.actingFor as AudiencePrincipal[]);- } catch {- return [[]];+ } catch (error) {+ return [refusedAsGuest(error)];}}diff --git a/src/core/persistence/transient-retry.ts b/src/core/persistence/transient-retry.tsindex 93e1263d8e..a2b4b31e08 100644--- a/src/core/persistence/transient-retry.ts+++ b/src/core/persistence/transient-retry.ts@@ -25,6 +25,7 @@*/import { OperationError } from '../ops/contract.ts';import { isStalePlanError } from '../retry-matcher.ts';+import { classifyPgAccessError } from '../pg-access-classify.ts';import type { SqlEngine, WriteRequest } from './model.ts';import { PERSISTENCE_PROTOCOL_PREDICATE } from './protocol.ts';import { publicationDeadlinePassed } from './publication-deadline.ts';@@ -57,6 +58,17 @@ export function transientInterruption(error: unknown): TransientInterruption | nreturn code === '57014' ? { cause: 'statement_cancel', sqlstate: '57014' } : null;}+export function transientDatabaseFailure(error: unknown): boolean {+ return ['40001','40P01','55P03','57014','53300','57P01','57P02','57P03','08000','08003','08006','08001','08004',+ 'ECONNRESET','ECONNREFUSED','ETIMEDOUT','CONNECTION_CLOSED','CONNECTION_ENDED'].includes(String((error as {code?:string})?.code)) || connectionCapFailure(error) || isStalePlanError(error);+}+/**+ * GBRA-133: a pooler's client cap (Supavisor `EMAXCONNSESSION`, "too many clients already") is the same contention as+ * SQLSTATE 53300 whatever code the pooler sends with it, so a write that meets it is released, never failed terminally.+ */+export function connectionCapFailure(error: unknown): boolean {+ return classifyPgAccessError(error).reason === 'pool_exhausted';+}/** The `*_interruption_charged` fault-point detail: the charge and the error it was charged for. */export function chargedInterruptionDetail(interruption: TransientInterruption | null, error: unknown) {const e = error as { name?: unknown; code?: unknown; message?: unknown } | null;diff --git a/src/mcp/server.ts b/src/mcp/server.tsindex e4b1ac07f2..5df052d2c5 100644--- a/src/mcp/server.ts+++ b/src/mcp/server.ts@@ -4,7 +4,8 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'import type { Readable, Writable } from 'node:stream';import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';import type { BrainEngine } from '../core/engine.ts';-import { opError, type OperationMeta } from '../core/ops/contract.ts';+import { OperationError, opError, type OperationMeta } from '../core/ops/contract.ts';+import { transientDatabaseFailure } from '../core/persistence/transient-retry.ts';import { OPERATION_MANIFEST } from '../core/operation-manifest.generated.ts';import { isCallable, publishGatesFromDisabled } from '../core/ops/callable.ts';import { VERSION } from '../version.ts';@@ -333,13 +334,17 @@ const READ_ONLY_SERVE_NOTE = '[gbrain-serve] read-only: no persistence consumer,/*** The ambient writeback section's options for a stdio serve: what the session can call, and whether the stdio member (`--stdio-member`, else mcp.stdio_member) binds* it to a member, whose writes stay private unless shared (GST-2243), so its rule never says "pass visibility: world". The lookup runs only when a- * member is named, so one that fails (access_identity_unavailable) still reads as bound and serve starts.+ * member is named; one that fails with access_identity_unavailable or a transient database failure still reads as bound and serve starts, and any+ * other error is thrown.*/export async function stdioAmbientOpts(engine: BrainEngine, writeback: WritebackConfig, allowedOps: ReadonlySet<string> | undefined, stdioMember?: string) {return ambientOptsFrom(writeback, {remember: allowedOps ? allowedOps.has('remember') : true,extractFacts: allowedOps ? allowedOps.has('extract_facts') : true,- member: await stdioMemberIdentity(engine, stdioMember).then(identity => identity.some(p => p.startsWith('member:')), () => true),+ member: await stdioMemberIdentity(engine, stdioMember).then(identity => identity.some(p => p.startsWith('member:')), (error: unknown) => {+ if ((error instanceof OperationError && error.code === 'access_identity_unavailable') || transientDatabaseFailure(error)) return true;+ throw error;+ }),});}diff --git a/test/access-binding.test.ts b/test/access-binding.test.tsindex 89423e6a3a..50f2caf2dd 100644--- a/test/access-binding.test.ts+++ b/test/access-binding.test.ts@@ -149,7 +149,7 @@ for (const kind of testBackends()) {expect(await memberIdentityFor(noQueries, { ...joined, member: { id: 'alice-example', groups: ['team-a'] } })).toEqual(['group:team-a', 'member:alice-example']);expect(await memberIdentityFor(noQueries, { ...joined, member: null })).toEqual([]);expect(await memberIdentityFor(engine, joined)).toEqual(['group:team-a', 'member:alice-example']);- await expect(memberIdentityFor(noQueries, joined)).rejects.toMatchObject({ code: 'access_identity_unavailable' });+ await expect(memberIdentityFor(noQueries, joined)).rejects.toThrow('dispatch must not query when the verifier joined the member');});test('a stored principal whose token was revoked resolves to the empty identity, like may_act_for', async () => {diff --git a/test/access-labelled-only-fail-closed.test.ts b/test/access-labelled-only-fail-closed.test.tsindex 7cc33449ac..f55ccf2447 100644--- a/test/access-labelled-only-fail-closed.test.ts+++ b/test/access-labelled-only-fail-closed.test.ts@@ -5,6 +5,7 @@ import type { WriteAuthority } from '../src/core/persistence/model.ts';import { PGLiteEngine } from '../src/core/pglite-engine.ts';import { PostgresEngine } from '../src/core/postgres-engine.ts';import { runAccess } from '../src/commands/access.ts';+import { linkMember } from '../src/core/access/actor.ts';import { memberIdentityFor, stdioMemberIdentity } from '../src/core/access/caller.ts';import { bindCredential } from '../src/core/access/members.ts';import { setOwner } from '../src/core/access/owner.ts';@@ -48,6 +49,18 @@ const MISSING = 'notes/missing-example';const OPEN_CANARY = 'canarylofcopenx';const LABELLED_CANARY = 'canarylofclabelledx';const MEMBER_LOOKUP = 'FROM access_members m LEFT JOIN access_group_members g';+const AUDIENCE_LOOKUP = 'm.id = ANY($1::text[])';+const ACTOR_LOOKUP = 'FROM access_member_links l';+const BOT_EXTERNAL_ID = 'u-acme-example-bot';+const OWNER_SLUG = 'notes/owner-lock-example';+const OWNER_CANARY = 'canarylofcownerx';+/** SQLSTATEs an injected failure raises: an internal error (not transient), a dropped connection and a lock timeout (both transient). */+const FAULT = 'XX000';+const DROPPED = '08006';+const LOCK_TIMEOUT = '55P03';+const ONE_FAILURE = 1;+/** Submission checks the writer's member twice (writerIdentities, writerLabelledOnly); the stored write's checks come after. */+const SUBMISSION_LOOKUPS = 2;const COMBINED_PROBE = 'AS any_labelled';const LOOKUP_FAILURES = 2;/** Every lookup of one request fails: a put_page checks visibility at preparation and again at publication, two lookups each. */@@ -61,22 +74,24 @@ const SLOW_MS = 600_000;const SETUP_MS = 300_000;const SECOND_POOL = 2;-type Fail = 'throw' | ((sql: string) => string);+type Fail = string | ((sql: string) => string);/*** Makes the next `times` statements on `engine` that contain `marker` fail, in every transaction it opens too (a- * transaction engine is Object.create(engine)): 'throw' raises a dropped-connection error without reaching the+ * transaction engine is Object.create(engine)): a SQLSTATE raises an error with that code without reaching the* database; a function sends its rewrite of the statement instead, which the database rejects with a real SQLSTATE- * (and which aborts an open transaction). Returns how many failed and a restore.+ * (and which aborts an open transaction). The first `skip` matching statements run untouched. Returns how many failed+ * and a restore.*/-function failStatements(engine: BrainEngine, marker: string, times: number, fail: Fail) {+function failStatements(engine: BrainEngine, marker: string, times: number, fail: Fail, skip = 0) {const original = engine.executeRaw as (...a: unknown[]) => Promise<unknown[]>;- const state = { left: times, failed: 0 };+ const state = { skip, left: times, failed: 0 };engine.executeRaw = async function (this: BrainEngine, sql: string, params?: unknown[], opts?: unknown) {- if (state.left > 0 && sql.includes(marker)) {+ if (sql.includes(marker) && state.skip > 0) state.skip--;+ else if (state.left > 0 && sql.includes(marker)) {state.left--;state.failed++;- if (fail === 'throw') throw Object.assign(new Error('Connection terminated unexpectedly'), { code: '08006' });+ if (typeof fail === 'string') throw Object.assign(new Error('injected failure ' + fail), { code: fail });return original.call(this, fail(sql), params, opts);}return original.call(this, sql, params, opts);@@ -84,8 +99,8 @@ function failStatements(engine: BrainEngine, marker: string, times: number, failreturn { state, restore: () => { delete (engine as { executeRaw?: unknown }).executeRaw; } };}-async function withFailures<T>(engine: BrainEngine, marker: string, times: number, fail: Fail, fn: () => Promise<T>): Promise<{ value: T; failed: number }> {- const injected = failStatements(engine, marker, times, fail);+async function withFailures<T>(engine: BrainEngine, marker: string, times: number, fail: Fail, fn: () => Promise<T>, skip = 0): Promise<{ value: T; failed: number }> {+ const injected = failStatements(engine, marker, times, fail, skip);try {return { value: await fn(), failed: injected.state.failed };} finally {@@ -220,12 +235,12 @@ for (const kind of testBackends()) {['stdio get_page', () => stdioCall(engine, BOT, 'get_page', { slug: OPEN })],];for (const [label, read] of reads) {- const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, 'throw', read);+ const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, FAULT, read);expect({ label, failed: failed > 0 }).toEqual({ label, failed: true });expect({ label, leaked: value.text.includes(OPEN_CANARY) || value.text.includes('"' + OPEN + '"') }).toEqual({ label, leaked: false });expect({ label, isError: value.isError, code: value.json.code }).toEqual({ label, isError: true, code: 'access_identity_unavailable' });}- const refused = (await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, 'throw', () => call(engine, auth, 'get_page', { slug: OPEN }, true))).value.json;+ const refused = (await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, FAULT, () => call(engine, auth, 'get_page', { slug: OPEN }, true))).value.json;expect(refused).toMatchObject({ retryable: true, class: 'retryable', fix: { next: 'wait' } });expect(refused.why).toBeString();}, SLOW_MS);@@ -237,7 +252,7 @@ for (const kind of testBackends()) {['create check', () => assertLabelledOnlyCreate(engine, authorityFor(bot.id), 'notes/fc-direct-new', null, {})],];for (const [label, check] of checks) {- const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, 'throw', () => outcome(check()));+ const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, FAULT, () => outcome(check()));expect({ label, failed: failed > 0, outcome: value }).toEqual({ label, failed: true, outcome: 'access_identity_unavailable' });}const auth = await verify(engine, bot.token);@@ -248,7 +263,7 @@ for (const kind of testBackends()) {['put_page create, every lookup fails', 'notes/fc-put-new', REQUEST_OUTAGE, {}],];for (const [label, slug, times, extra] of puts) {- const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, times, 'throw',+ const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, times, FAULT,() => call(engine, auth, 'put_page', { slug, content: note('Bot rewrite', []), ...extra }));expect({ label, failed: failed > 0, isError: value.isError }).toEqual({ label, failed: true, isError: true });expect({ label, code: value.json.code === 'revision_required' ? 'leaks the hidden page' : 'ok' }).toEqual({ label, code: 'ok' });@@ -257,23 +272,67 @@ for (const kind of testBackends()) {expect(await pageRows(engine, 'notes/fc-put-new')).toEqual([]);}, SLOW_MS);- test('fix 1: a lookup whose table or column is missing (a schema older than the member tables) still reads as unbound; any other failure throws', async () => {+ test('fix 1: a lookup missing access_members, access_group_members or member_id (a schema older than the member tables) still reads as unbound; a transient failure is rethrown unchanged; any other failure throws access_identity_unavailable', async () => {const principal = { principal: { kind: 'legacy_token', id: bot.id } };expect(await memberIdentityFor(engine, principal)).toContain('member:' + BOT);const missing: Array<[string, (sql: string) => string]> = [- ['42P01', sql => sql.replace('FROM access_members m', 'FROM access_members_absent m')],- ['42703', sql => sql.replace('m.disabled_at IS NULL', 'm.disabled_at_absent IS NULL')],+ ['42P01', sql => sql.replace('FROM access_members m', 'FROM pg_temp.access_members m')],+ ['42703', sql => sql.replace('SELECT member_id FROM access_tokens', 'SELECT t.member_id FROM (SELECT id, revoked_at FROM access_tokens) t')],];for (const [state, rewrite] of missing) {const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, rewrite, () => memberIdentityFor(engine, principal));expect({ state, failed, identity: value }).toEqual({ state, failed: 1, identity: [] });}- expect((await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, 'throw', () => outcome(memberIdentityFor(engine, principal)))).value).toBe('access_identity_unavailable');- expect((await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, 'throw', () => outcome(stdioMemberIdentity(engine, BOT)))).value).toBe('access_identity_unavailable');+ const otherObjects: Array<[string, (sql: string) => string]> = [+ ['42P01', sql => sql.replace('FROM access_members m', 'FROM access_members_absent m')],+ ['42703', sql => sql.replace('m.disabled_at IS NULL', 'm.disabled_at_absent IS NULL')],+ ];+ for (const [state, rewrite] of otherObjects) {+ const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, rewrite, () => outcome(memberIdentityFor(engine, principal)));+ expect({ state, failed, outcome: value }).toEqual({ state, failed: 1, outcome: 'access_identity_unavailable' });+ }+ for (const state of [DROPPED, LOCK_TIMEOUT]) {+ expect({ state, outcome: (await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, state, () => outcome(memberIdentityFor(engine, principal)))).value }).toEqual({ state, outcome: state });+ }+ expect((await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, FAULT, () => outcome(memberIdentityFor(engine, principal)))).value).toBe('access_identity_unavailable');+ expect((await withFailures(engine, MEMBER_LOOKUP, LOOKUP_FAILURES, FAULT, () => outcome(stdioMemberIdentity(engine, BOT)))).value).toBe('access_identity_unavailable');expect(await memberIdentityFor(engine, { principal: { kind: 'legacy_token', id: unbound.id } })).toEqual([]);expect(await stdioMemberIdentity(engine)).toEqual([]);}, SLOW_MS);+ test('fix 1 (transient): an owner put_page whose stored-write lookup meets one lock timeout is released and retried, and commits', async () => {+ const auth = await verify(engine, owner.token);+ const { value, failed } = await withFailures(engine, MEMBER_LOOKUP, ONE_FAILURE, LOCK_TIMEOUT,+ () => call(engine, auth, 'put_page', { slug: OWNER_SLUG, content: note('Owner lock example', [], 'Owner note ' + OWNER_CANARY + ' here.') }), SUBMISSION_LOOKUPS);+ expect({ failed, isError: value.isError, code: value.json.code ?? null }).toEqual({ failed: ONE_FAILURE, isError: false, code: null });+ expect((await pageRows(engine, OWNER_SLUG))[0]?.compiled_truth).toContain(OWNER_CANARY);+ }, SLOW_MS);++ test('fix 1 red-first (stored audience and attested actor): a write for a labelled-only member stays labelled-only when re-resolving who it writes for fails', async () => {+ const agent = await mint(engine, 'audience-agent');+ await bindCredential(engine, { kind: 'token', id: agent.id }, { mayActFor: ['member:' + BOT] });+ const attest = await mint(engine, 'attest-agent');+ await bindCredential(engine, { kind: 'token', id: attest.id }, { attestActor: 'qm' });+ await linkMember(engine, BOT, 'qm', BOT_EXTERNAL_ID);+ const healthy = { update: 'page_not_found', create: 'access_labelled_only_unnamed' };+ const writers: Array<[string, WriteAuthority, string, typeof healthy | Record<string, string>]> = [+ ['audience', { ...authorityFor(agent.id), actingFor: ['member:' + BOT] } as WriteAuthority, AUDIENCE_LOOKUP, healthy],+ ['attested', { ...authorityFor(attest.id), actingFor: { system: 'qm', external_id: BOT_EXTERNAL_ID, member: BOT } } as WriteAuthority, ACTOR_LOOKUP, { update: DROPPED, create: DROPPED }],+ ];+ const seen: Record<string, unknown> = {};+ const expected: Record<string, unknown> = {};+ for (const [who, authority, marker, failing] of writers) {+ const checks = async () => ({ update: await outcome(authorizePageVisibility(engine, authority, OPEN)),+ create: await outcome(assertLabelledOnlyCreate(engine, authority, 'notes/fc-stored-new', null, {})) });+ const healthyRun = await checks();+ const { value, failed } = await withFailures(engine, marker, REQUEST_OUTAGE, DROPPED, checks);+ seen[who] = { healthy: healthyRun, failed: failed > 0, failing: value };+ expected[who] = { healthy, failed: true, failing };+ }+ expect(seen).toEqual(expected);+ expect(await pageRows(engine, 'notes/fc-stored-new')).toEqual([]);+ }, SLOW_MS);+test('fix 1 (R94): with lookups working, the owner credential and an unbound credential read as before', async () => {expect((await call(engine, owner.token, 'get_page', { slug: OPEN }, true)).text).toContain(OPEN_CANARY);expect((await call(engine, unbound.token, 'get_page', { slug: OPEN }, true)).text).toContain(OPEN_CANARY);