Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
Document the refusal of a guest writer deleting another writer's note (GBRA-504)
garrytan883dfe1039e8
diff --git a/docs/architecture/key-files/core-services-2.md b/docs/architecture/key-files/core-services-2.mdindex 332ffa7f1b..e2b579825c 100644--- a/docs/architecture/key-files/core-services-2.md+++ b/docs/architecture/key-files/core-services-2.md@@ -32,7 +32,7 @@ Fact and page purge modules (`src/core/facts/purge*.ts`, `deletion-inventory.ts`- `src/core/ops/attribution.ts` — write attribution reads (Foundations 1, F1b). `resolveWriteAttributions` turns stored (request id, principal kind, principal id) snapshots into `WriteAttributionView`s (`types.ts`), joining `persistence_requests` (operation, `completed_at`, `agent_label`), `oauth_clients.client_name`, `access_tokens.name` and the `persistence_local_writers` lane at read time, one query each; `origin` is `request`, `maintenance` (principal without request) or `unrecorded` (all NULL). `get_write_attribution` (scope `admin`, `localOnly: false`, CLI `gbrain attribution <slug> [--fact <id>] [--take <row>] [--timeline <id>] [--versions]`) returns `{ target, created, last, live_revision, versions? }`; a page's `created` is the origin of its oldest version snapshot. The page lookup uses `readPolicyOpts`, so remote admins stay inside their source grant; remote fact targets are `world` only and take targets follow `readHolders`. Tests: `test/write-attribution-read.test.ts` (PGLite) and `test/e2e/write-attribution-read-parity.test.ts` (Postgres and PgBouncer).- `src/core/ops/trust.ts` — `confirm_memory` (#5575 A4, CEO-9, DX-20): the one MCP-visible owner action. Raises a fact, take or page to `user_confirmed` through `trust/owner-actions.ts` after `requireOwnerConfirmation` (a `memory_confirm` connection, or the local CLI's typed-token TTY prompt); agent tokens get `insufficient_scope` with a `tell_user_to_run` fix naming `gbrain trust confirm <ref>`. Trust proposals and holds are not reachable here; the other owner actions are CLI or resident-owner administration only (`trust/owner-ipc.ts`). It also holds `promote_guest_note` (GBRA-504), whose logic is `guests/promote.ts`.-- `src/core/guests/{promote,owner-credentials}.ts`, `src/commands/doctor/checks/guest-source.ts` — GBRA-504 slice 4. `promote.ts` is `promote_guest_note` (CLI `gbrain guests promote`): `isGuestPromotionOwner` admits the trusted local CLI (not under `GBRAIN_ENFORCED_MEMBER`, not `--as`) and a remote or stdio caller whose `CallerAccess.owner` is set with no attested actor, anyone else is `guest_promotion_owner_only`; it writes the owner page with `submitPageMutation` put_page (git first where the target has a repo), carrying the note's type, title, body and `readable_by` plus `promoted_from: <guest source>:<slug>`, then inserts `guest_promotions`, which `marker.ts` `loadGuestMarks` reads as `guest.promoted` and `admission.ts` `refuseRemoteDeleteOfPromoted` reads to refuse a remote delete `guest_page_promoted` (at submission in `page-mutations.ts`, again in the delete's publication in `page-prepare.ts`). `owner-credentials.ts` lists tokens and OAuth clients bound to `access.owner_member` with their read lists, the exact `gbrain auth rescope ... --if-version` command and whether `min_trust` hides guest notes; `grantOwnerCredentials` (`gbrain guests grant-owner-clients --yes`) adds the guest source as a compare-and-set on the grant revision. The doctor check `guest_source` reads both and changes nothing. Tests: `test/guest-notes-promotion.test.ts`, `test/doctor-guest-source.test.ts`, `test/guests-grant-owner-clients.test.ts`.+- `src/core/guests/{promote,owner-credentials}.ts`, `src/commands/doctor/checks/guest-source.ts` — GBRA-504 slice 4. `promote.ts` is `promote_guest_note` (CLI `gbrain guests promote`): `isGuestPromotionOwner` admits the trusted local CLI (not under `GBRAIN_ENFORCED_MEMBER`, not `--as`) and a remote or stdio caller whose `CallerAccess.owner` is set with no attested actor, anyone else is `guest_promotion_owner_only`; it writes the owner page with `submitPageMutation` put_page (git first where the target has a repo), carrying the note's type, title, body and `readable_by` plus `promoted_from: <guest source>:<slug>`, then inserts `guest_promotions`, which `marker.ts` `loadGuestMarks` reads as `guest.promoted` and `admission.ts` `refuseRemoteGuestDelete` reads to refuse a remote delete `guest_page_promoted`; it also refuses `permission_denied` when the note's guest mark names a writer other than the caller (both at submission in `page-mutations.ts`, again in the delete's publication in `page-prepare.ts`). `owner-credentials.ts` lists tokens and OAuth clients bound to `access.owner_member` with their read lists, the exact `gbrain auth rescope ... --if-version` command and whether `min_trust` hides guest notes; `grantOwnerCredentials` (`gbrain guests grant-owner-clients --yes`) adds the guest source as a compare-and-set on the grant revision. The doctor check `guest_source` reads both and changes nothing. Tests: `test/guest-notes-promotion.test.ts`, `test/doctor-guest-source.test.ts`, `test/guests-grant-owner-clients.test.ts`.- `src/core/guests/{schema,sources}.ts` — GBRA-504 guest sources. `schema.ts` is the guest-notes migration's DDL (number: `guests/migration.ts`): `guest_sources` (the authority for which sources are guest sources, their writer list of `<kind>:<id>` attribution principals and their tier ceiling), `guest_marks` (immutable: `gbrain_guard_guest_records` refuses UPDATE; rows leave only with their page) and `guest_promotions`, RLS on, and the guard that keeps a guest source database-only (no `local_path`). The trust trigger (`trust/schema.ts` `GUEST_AWARE_STAMP_TIER_FUNCTION`, installed by that migration; v226 keeps its own body) clamps a guest page to the ceiling on every exit, refuses a page INSERT or content change (any content column but `deleted_at`) unless `gbrain.write_principal_kind`:`gbrain.write_principal_id` is on the writer list, and refuses facts, takes and timeline rows there. `sources.ts` holds the reads and writes behind `gbrain guests init` and `gbrain sources writers`.- `src/core/guests/{marker,stamp}.ts`, `src/core/access/page-items.ts`, `src/cli/guest-lines.ts` — GBRA-504 slice 3: the guest warning on every read. `marker.ts` holds the `GuestStamp` object (`sender`, from `guest_marks.sender_label`; `group`, `audience_member`, `saved_at` day, `promoted`, `writer` for owner callers only, `unattributed`), the warning line, the quote-fence label, think's fixed `Uses outside-guest notes:` line, `loadGuestMarks` (one batched `guest_marks` read; a failed read leaves rows unattributed, never bare) and `withGuestMarks`, which `operation-load.ts` `finalizeOperation` wraps around every op whose `outputRedaction` is not `no_stored_text`. `stamp.ts` `stampGuestNotes` finds page items with `page-items.ts` `collectPageItems` (the walker shared with `access/room.ts`; it also reads `fetch` rows by their `gbrain://page/` url), skips the trust load only when `marker.ts` `brainHasGuestSource` (one read of `sources` and `guest_sources`, yes when it fails) finds no guest source, reads guest rows through `eligibility/stamp.ts` `loadPageTrust` (a source is a guest source when its config says so or `guest_sources` lists it, `guestSourceSql`), and stamps a copy with `origin: guest`, `external_untrusted` and the `guest` object; a failed load fails the read. `eligibility/labels.ts` prints the warning line before the `origin="guest"` envelope, `eligibility/activation.ts` and `context/turn-context.ts` carry the stamp on `delta`, and the CLI prints it through `search-row-format.ts`, `page-render.ts` and `guest-lines.ts`. Publication refuses a plain write that lands after its source became a guest source (`guests/admission.ts` `assertNoGuestSourceAtPublication`). Servers list capability `guest_marker_v1`. Tests: `test/guest-notes-warning.test.ts`, `test/guest-notes-contract.test.ts` (every op that returns stored text, as owner over HTTP and stdio and as the audience member), `test/guest-notes-shortcut.test.ts` (a source marked guest without `gbrain guests init` is still marked).diff --git a/docs/guides/write-refusals.md b/docs/guides/write-refusals.mdindex a761051921..f031b0e502 100644--- a/docs/guides/write-refusals.md+++ b/docs/guides/write-refusals.md@@ -1085,6 +1085,7 @@ before anything is written. The rules live in the database, so they are the same| <a id="source_writer_restricted"></a>`source_writer_restricted` | A write to a guest source came from a credential that is not on the source's writer list: a remote token or client that was never listed, the local CLI (`gbrain put`, `gbrain import`, `remember`, `add_link`), an enforced member, or a listed writer that was removed between admission and publication (the receipt ends `failed` with this code). Only the brain owner on the brain host may delete or restore a guest page. Nothing was written. | Do not retry. Write the content to another source. Who may write a guest source is the brain owner's decision; an agent never changes the writer list. || <a id="guest_page_immutable"></a>`guest_page_immutable` | A listed writer tried something other than saving a new page: a write with `force` or `expected_revision`, `edit_page`, `append_page`, `add_timeline_entry`, `add_link`, `remember`, `put_pages`, an upload, or a `put_page` over a deleted guest page. The database refuses facts, takes and timeline rows in a guest source with the same code. A plain `put_page` to a slug that already exists is refused `revision_required`. Nothing was written. | Save the note again under a new slug. To change a guest note, the brain owner promotes it to an owner page and edits that. || <a id="guest_page_promoted"></a>`guest_page_promoted` | A remote `delete_page` of a guest note the brain owner kept as an owner page (`gbrain guests promote`); checked when the delete is submitted and again when it publishes. The owner's own delete from the local CLI still works. Nothing was deleted. | Do not retry. Treat the note as kept: it reads `guest.promoted: true`. Only the brain owner removes it, on the brain host. |+| <a id="guest_note_not_yours"></a>`permission_denied` (another writer's guest note) | A listed writer's remote `delete_page` of a guest note whose guest mark names a different writer: a writer deletes only the notes it saved. Checked when the delete is submitted and again when it publishes. The owner's own delete from the local CLI still works. Nothing was deleted. | Do not retry. Delete only the notes this credential saved; the brain owner deletes any guest note on the brain host (`gbrain delete`). || <a id="guest_attribution_missing"></a>`guest_attribution_missing` | A listed writer's `put_page` carried no guest attribution, or a malformed one. Attribution is the `X-Gbrain-Guest` header (`sender_label=<URL-encoded label>&group=<group-slug>`) or request-level `_meta.guest` (`{"sender_label": "...", "group": "..."}`). A label is 1 to 64 characters with no control, format or line-separator characters and none of `·`, `[`, `]`, `<`, `>` or `"`; a group slug is 1 to 64 of `a-z`, `0-9` and `-`. Sending both with different values is refused too. Nothing was written. | Fix the harness code that sets it, then save the note with a new `request_id`. Attribution sent with a write to any other source is ignored. || <a id="guest_frontmatter_refused"></a>`guest_frontmatter_refused` | A guest page's frontmatter held a key outside `type`, `title`, `readable_by`, `guest_group`, `guest_sender` and `saved_at` (for example `visibility`, `trust_tier`, `tags` or `always_load`), or its `guest_sender` or `guest_group` differs from the attribution. Nothing was written. | Send only the allowed keys, with `guest_sender` and `guest_group` equal to the attribution's `sender_label` and `group`. || <a id="guest_readers_invalid"></a>`guest_readers_invalid` | A guest page's `readable_by` is not exactly the brain owner plus the one member or group the call speaks for (`X-Gbrain-On-Behalf-Of`), the call speaks for several principals or for `guest`, or the brain has no owner set. A missing `readable_by` under an audience is refused `readable_by_invalid` first. Nothing was written. | Speak for one member or group and set `readable_by` to the owner and that principal, for example `[alice-example, group:team-a]`. The owner is set on the brain host with `gbrain access owner set`. |