@cohortapp/agent-sdk 2.3.0

package/lib/org/protocol.mjs

@@ -0,0 +1,967 @@
+/**
+ * lib/org/protocol.mjs — SHARED Cohort org-protocol contract (transport-agnostic).
+ *
+ * This is the single source of truth for the wire contract between maestro
+ * agents and the Cohort org server (SPEC-org-server §0.3 / §2.4): method names,
+ * the scope each method requires, which methods mutate state, the event families,
+ * the board status vocabulary, the error codes, and — critically — the
+ * `computeRowHash` function that defines the append-only `org_events` hash chain.
+ *
+ * Both sides import this module so they agree byte-for-byte:
+ *   - the server (services/cohort) writes events and signs snapshots using these
+ *     names/scopes and this hash function;
+ *   - the agent client (lib/org/client.mjs) and the detective layer
+ *     (lib/org/verify.mjs) re-derive the same hashes to detect tampering.
+ *
+ * The protocol is defined independently of HTTP vs WebSocket: phase 1 implements
+ * only the HTTP binding, but nothing here changes when the WS binding lands.
+ *
+ * Pure, Node-builtin only (node:crypto). ESM.
+ *
+ * @module lib/org/protocol
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+
+/** Wire protocol version. Sent as the `X-Org-Protocol` header. */
+export const PROTOCOL_VERSION = 1;
+
+/**
+ * Event families. Every mutation appends to org_events under one of these, and
+ * every method's `family` must be one of them (CI-lintable invariant).
+ * @type {readonly string[]}
+ */
+export const FAMILIES = Object.freeze([
+  "pairing", "registry", "presence", "board", "hierarchy", "admin",
+  "lease", "handoff", "governance",
+  "approval", "decision", "cost", "policy",
+  "knowledge", "contacts", "meetings",
+  "credential",
+  "messaging", "calling",
+  // agent UI-parity families
+  "charter", "member", "team", "channel", "persona", "profile", "sop", "escalation", "annotation", "contact", "file", "memory", "compact", "notification", "invitation", "user", "settings", "billing", "org", "integration",
+  // Brand Studio v2 write surface (branding-generation / brand-templates / brand-export)
+  "branding",
+  // agent workspace email (SPEC 2026-07-21 agent-email-server)
+  "email",
+  // generative-UI artifacts (GU program 2026-07): interactive cards in feeds
+  "artifact",
+  // agent desks (2026-07): Books desk, workspace calendar, CRM desk, and the
+  // workspace drive. NB "files" (Docs/Sheets/Decks drive) coexists with the
+  // UI-parity "file" family (pins/comments on chat attachments) — distinct.
+  "books", "calendar", "crm", "files",
+  // the Directory (2026-07): the canonical registry of external people and
+  // organisations every other desk resolves its counterparties through.
+  "directory",
+]);
+
+/**
+ * Reserved method namespaces that ALWAYS resolve to the `admin` scope,
+ * regardless of a method descriptor — privileged control surfaces that an
+ * ordinary agent token must never reach (SPEC §2.4).
+ * @type {readonly string[]}
+ */
+export const RESERVED_ADMIN_NAMESPACES = Object.freeze(["admin", "pairing", "policy", "governance"]);
+
+/**
+ * The board work-item status vocabulary (SPEC org-server board kernel) plus its
+ * mapping onto the A2A Task lifecycle, so the board can later serialize to the
+ * A2A interop endpoints without a second enum.
+ * @type {readonly string[]}
+ */
+export const BOARD_STATUS = Object.freeze([
+  "triage", "backlog", "todo", "scheduled", "ready", "running", "review", "blocked", "done", "archived",
+]);
+
+/** Statuses an item can be claimed from (work is dispatchable). */
+export const CLAIMABLE_STATUS = Object.freeze(["ready", "todo"]);
+
+/** Terminal statuses (no further work; excluded from the ready feed). */
+export const TERMINAL_STATUS = Object.freeze(["done", "archived"]);
+
+/** A2A Task-state mapping for the board statuses (interop, phase 4). */
+export const BOARD_STATUS_A2A = Object.freeze({
+  triage: "submitted", backlog: "submitted", todo: "submitted", scheduled: "submitted",
+  ready: "submitted", running: "working", review: "input-required", blocked: "input-required",
+  done: "completed", archived: "canceled",
+});
+
+/**
+ * Scopes (capabilities). Default-deny: a token carries a set of these; a method
+ * is permitted only if the actor holds its required scope (or `admin`).
+ * @type {readonly string[]}
+ */
+export const SCOPES = Object.freeze([
+  "org.read",        // read directory / hierarchy / snapshot / events
+  "registry.write",  // register self, heartbeat
+  "presence.write",  // presence beats
+  "board.read",      // read board feeds
+  "board.write",     // create / comment / decompose / link items
+  "board.work",      // claim / heartbeat / complete items
+  "lease.write",     // claim/heartbeat/release generic leases (thread ownership, singletons)
+  "handoff.send",    // offer/accept/decline/cancel delegations (gated by governance_ready)
+  "approval.request",// request approval for a classified action; read own approvals
+  "approval.decide", // resolve (approve/reject) an approval — granted to approvers/humans only
+  "decision.write",  // propose a decision into the registry
+  "cost.report",     // report per-session usage into the rollup
+  "knowledge.read",  // search ACL'd shared facts (RLS-floored; barrier cells deny-override)
+  "knowledge.write", // append episodes / replace facts / upsert contacts+meetings
+  "credential.use",  // lease an org-level third-party credential (deepseek/kimi/...) — the
+                     //   single SoT: agents never hold the org key, they lease it short-lived
+  "messaging.read",  // read channels + message history in the human messaging app
+  "messaging.write", // send / react / edit messages in the human messaging app
+  "calling.write",   // start / join / end / invite — call lifecycle in the human app
+  "charter.write", // EDITOR-equivalent: author/amend member charters, clauses, sections, and colleague-charter fields. Reads use org.read.
+  "org.write", // EDITOR-equivalent: write org-structural content (members, teams, personas, profiles, SOPs, escalations, annotations, contacts, files, compacts, notification prefs, reporting lines, chart layout). Reads use org.read.
+  "email.read",  // read own-mailbox inbox / messages / threads + the Inbox-app read surface (mailboxes/threads/messages/drafts/approvals/rules/signatures)
+  "email.write", // send workspace email, mark read + the Inbox-app write surface (triage/move/drafts/rules/folders/signatures; guardian verbs enforced in-domain)
+  // agent-desk scope pairs (2026-07): one read/write pair per desk family so a
+  // key can be minted for exactly one desk (e.g. a Books-only finance seat).
+  "files.read",    // workspace drive reads: list/get + doc/sheet/deck reads; exportRequest is an AUDITED side-effecting export under this read scope
+  "files.write",   // workspace drive writes: create/upload/rename/move/star/pin/delete/recover/shares + doc/sheet/deck revisions
+  "calendar.read", // workspace calendar reads: list/get + the deterministic findATime scan
+  "calendar.write",// workspace calendar writes: create/update/reschedule/rsvp/delete (queue real invite/update/cancel emails)
+  "crm.read",      // CRM desk reads: deals/escalations/accounts/contacts/interactions/playbooks/targets + pure compile previews
+  "crm.write",     // CRM desk writes: deal lifecycle, accounts/contacts, playbooks, targets — human-only verbs (signEscalation, targetCents) refuse agent actors in-domain
+  "books.read",    // Books desk reads: accounts/journals/feed/invoices/bills/tax/reports/assets + grounded books.ask (AI-gateway self-audited)
+  "books.write",   // Books desk writes: AR/AP/expenses/payroll/tax/assets — the signature law (PB-B1..B4) is enforced in-domain; scope alone cannot move money
+  "directory.read",  // Directory reads: people/organisations/channels/lists/review queues + grounded directory.ask. AWARENESS-SCOPED: a named-only record is ABSENT from every result for a seat without a grant, never redacted
+  "directory.write", // Directory writes: create/update parties, channels, captures, links, lists. Structural verbs (merge execution, awareness change, archive) refuse an agent actor in-domain and create a review item instead
+  "design.read",     // Design reads: the SAVED brand foundation snapshot (never a draft), voice, visible templates. Renders and voice rewrites are AUDITED side-effecting reads under this scope (files.exportRequest precedent)
+  "design.write",    // Design writes: generate imagery, propose a foundation change. Foundation mutation itself is admin-only and human-gated -- a proposal creates a reviewable diff, it does not write
+  "admin",           // pairing approval, deactivate (kill switch), governance, policy, credential put/revoke
+]);
+
+/** Default scope set granted to a normal paired agent (no admin, no approval.decide). */
+export const DEFAULT_AGENT_SCOPES = Object.freeze([
+  "org.read", "registry.write", "presence.write", "board.read", "board.write", "board.work",
+  "lease.write", "handoff.send", "approval.request", "decision.write", "cost.report",
+  "knowledge.read", "knowledge.write", "credential.use",
+  "messaging.read", "messaging.write", "calling.write",
+  "charter.write", "org.write", // agent UI-parity (EDITOR-equivalent)
+  "email.read", "email.write", // workspace email + Inbox app (messaging precedent)
+  // agent desks (2026-07): a normal paired agent works the product surfaces its
+  // seat's human role could — dangerous verbs stay held in the domain layer
+  // (guardian-only, human-only, signature law), never behind scope alone.
+  "files.read", "files.write", "calendar.read", "calendar.write",
+  "crm.read", "crm.write", "books.read", "books.write",
+  "directory.read", "directory.write", "design.read", "design.write",
+]);
+
+/** Knowledge group scopes: org-wide, per-unit, or an information-barrier cell (deny-override). */
+export const KNOWLEDGE_GROUP_KINDS = Object.freeze(["org", "unit", "barrier"]);
+
+/** Generic lease scopes (one primitive, several scopes of use). */
+export const LEASE_SCOPES = Object.freeze(["work-claim", "thread-ownership", "session-leadership", "singleton-cadence"]);
+
+/**
+ * The method registry contract (the server globs one file per method; this is
+ * the authoritative name→descriptor map both sides validate against).
+ * `auth:false` ⇒ pre-auth method (pairing handshake). `sideEffecting:true` ⇒
+ * runs in a transaction and MUST append to the event chain.
+ * @type {Readonly<Record<string,{family:string,scope:string,sideEffecting:boolean,auth?:boolean,idempotent?:boolean}>>}
+ */
+export const METHODS = Object.freeze({
+  // --- pairing (pre-auth handshake + admin approval) ---
+  "pairing.request": { family: "pairing", scope: "admin", sideEffecting: true, auth: false },
+  "pairing.approve": { family: "pairing", scope: "admin", sideEffecting: true },
+  // --- registry / presence ---
+  "registry.register": { family: "registry", scope: "registry.write", sideEffecting: true, idempotent: true },
+  "registry.heartbeat": { family: "registry", scope: "registry.write", sideEffecting: true },
+  "presence.beat": { family: "presence", scope: "presence.write", sideEffecting: true },
+  // --- board (kanban / backlog) ---
+  "board.create": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
+  "board.claim": { family: "board", scope: "board.work", sideEffecting: true },
+  "board.heartbeat": { family: "board", scope: "board.work", sideEffecting: true },
+  "board.complete": { family: "board", scope: "board.work", sideEffecting: true },
+  "board.block": { family: "board", scope: "board.work", sideEffecting: true },
+  "board.comment": { family: "board", scope: "board.write", sideEffecting: true },
+  // --- board DAG (phase 2) — decompose/assign are governance-gated ---
+  "board.decompose": { family: "board", scope: "board.write", sideEffecting: true, governanceGated: true },
+  "board.assign": { family: "board", scope: "board.write", sideEffecting: true, governanceGated: true },
+  "board.link": { family: "board", scope: "board.write", sideEffecting: true },
+  // --- lease (phase 2): one generic primitive (work-claim / thread-ownership / singleton-cadence / session-leadership) ---
+  "lease.claim": { family: "lease", scope: "lease.write", sideEffecting: true },
+  "lease.heartbeat": { family: "lease", scope: "lease.write", sideEffecting: true },
+  "lease.release": { family: "lease", scope: "lease.write", sideEffecting: true },
+  // --- handoff (phase 2): signed delegation lifecycle — ALL governance-gated (§0.4) ---
+  "handoff.offer": { family: "handoff", scope: "handoff.send", sideEffecting: true, governanceGated: true },
+  "handoff.accept": { family: "handoff", scope: "handoff.send", sideEffecting: true, governanceGated: true },
+  "handoff.decline": { family: "handoff", scope: "handoff.send", sideEffecting: true, governanceGated: true },
+  "handoff.cancel": { family: "handoff", scope: "handoff.send", sideEffecting: true, governanceGated: true },
+  // --- hierarchy (org SoT — reads in phase 1; writes via governance later) ---
+  "hierarchy.set": { family: "hierarchy", scope: "admin", sideEffecting: true },
+  // --- governance (decision-rights ingest gates handoffs/assignment per §0.4) ---
+  "governance.set_decision_rights": { family: "governance", scope: "admin", sideEffecting: true },
+  "governance.status": { family: "governance", scope: "org.read", sideEffecting: false },
+  // --- approvals (phase 3): requester != approver enforced as a DB CHECK (G5) ---
+  "approval.request": { family: "approval", scope: "approval.request", sideEffecting: true, idempotent: true },
+  "approval.resolve": { family: "approval", scope: "approval.decide", sideEffecting: true },
+  "approval.get": { family: "approval", scope: "approval.request", sideEffecting: false },
+  "approval.list": { family: "approval", scope: "approval.request", sideEffecting: false },
+  // --- decisions registry (phase 3): adopt/supersede are governance-gated ---
+  "decision.propose": { family: "decision", scope: "decision.write", sideEffecting: true, idempotent: true },
+  "decision.adopt": { family: "decision", scope: "decision.write", sideEffecting: true, governanceGated: true },
+  "decision.supersede": { family: "decision", scope: "decision.write", sideEffecting: true, governanceGated: true },
+  // --- cost rollups (phase 3): agents report usage; rollups read org-wide ---
+  "cost.report": { family: "cost", scope: "cost.report", sideEffecting: true, idempotent: true },
+  // --- policy distribution (phase 3): publish is admin (reserved); agents fetch via the read surface ---
+  "policy.publish": { family: "policy", scope: "admin", sideEffecting: true },
+  // --- knowledge plane (phase 4): RLS-floored shared facts; barrier cells deny-override.
+  //     Mutable-artifact semantics: append (commutes) / replace (CAS) / rewrite (owner-only).
+  //     search is side-effecting because every retrieval is logged to org_events (read-audit). ---
+  "knowledge.append": { family: "knowledge", scope: "knowledge.write", sideEffecting: true, idempotent: true },
+  "knowledge.replace": { family: "knowledge", scope: "knowledge.write", sideEffecting: true },
+  "knowledge.rewrite": { family: "knowledge", scope: "knowledge.write", sideEffecting: true },
+  "knowledge.invalidate": { family: "knowledge", scope: "knowledge.write", sideEffecting: true },
+  "knowledge.search": { family: "knowledge", scope: "knowledge.read", sideEffecting: true },
+  "contacts.upsert": { family: "contacts", scope: "knowledge.write", sideEffecting: true, idempotent: true },
+  "meetings.record": { family: "meetings", scope: "knowledge.write", sideEffecting: true, idempotent: true },
+  // meetings.recapFile — file a held meeting's recap + transcript into the
+  //     workspace drive (two DOCs + a MeetingRecord, links back); the
+  //     notetaker's landing verb. Knowledge-capture like meetings.record, so it
+  //     rides knowledge.write (the integration manifest's declared contract). ---
+  "meetings.recapFile": { family: "meetings", scope: "knowledge.write", sideEffecting: true, idempotent: true },
+  // --- org credential broker: the single source of truth for org-level third-party
+  //     creds (DeepSeek/Kimi/OpenAI/...). Admin sets once; agents LEASE short-lived,
+  //     role-scoped, audited — the org key never lives on the 50-100 agent machines. ---
+  "credential.put": { family: "credential", scope: "admin", sideEffecting: true },
+  "credential.lease": { family: "credential", scope: "credential.use", sideEffecting: true },
+  "credential.list": { family: "credential", scope: "admin", sideEffecting: false },
+  "credential.revoke": { family: "credential", scope: "admin", sideEffecting: true },
+  // --- messaging (SP3): agents participate in the human messaging app. send is
+  //     idempotent via the client-supplied message id; audit rows are REDACTED
+  //     (no message body lands in org_events). NOT a reserved-admin namespace. ---
+  "messaging.send": { family: "messaging", scope: "messaging.write", sideEffecting: true, idempotent: true },
+  "messaging.createPoll": { family: "messaging", scope: "messaging.write", sideEffecting: true, idempotent: true },
+  "messaging.votePoll": { family: "messaging", scope: "messaging.write", sideEffecting: true, idempotent: true },
+  "messaging.react": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  "messaging.edit": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  "messaging.history": { family: "messaging", scope: "messaging.read", sideEffecting: false },
+  "messaging.channels": { family: "messaging", scope: "messaging.read", sideEffecting: false },
+  // --- calling (SP3): call lifecycle in the human app. NOT reserved-admin. ---
+  "calling.start": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.join": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.end": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.invite": { family: "calling", scope: "calling.write", sideEffecting: true },
+  // --- calling agent-operability: in-call actions + reads for authorised agents.
+  //     react/raiseHand/lowerHand are pure-event (the chain event IS the record,
+  //     no projection row); getDetails/getTranscript are participation-gated reads. ---
+  "calling.react": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.raiseHand": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.lowerHand": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.getDetails": { family: "calling", scope: "org.read", sideEffecting: false },
+  "calling.getTranscript": { family: "calling", scope: "org.read", sideEffecting: false },
+  "calling.recordingStart": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.recordingStop": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.setMute": { family: "calling", scope: "calling.write", sideEffecting: true },
+  // --- calling agent transcript + in-call chat: authorised agents write finalized
+  //     transcript lines and post to the in-call chat panel. Both persist a
+  //     projection row (CallTranscriptLine / CallChatMessage) and append exactly
+  //     one REDACTED calling event (no line/message body in the chain). ---
+  "calling.addTranscriptLine": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.chat": { family: "calling", scope: "calling.write", sideEffecting: true },
+  // --- calling host moderation (2026-08): remove a participant from the live
+  //     room + lock the room against NEW joins (existing participants and
+  //     reconnects are unaffected; start/end are unaffected). Host-gated in the
+  //     hq domain (the call starter), and an agent may act only on AI targets.
+  //     Governance refusals return as RESULTS with one audited *_refused event
+  //     — never a thrown error. ---
+  "calling.removeParticipant": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.setLock": { family: "calling", scope: "calling.write", sideEffecting: true },
+  // --- calling working sessions (2026-08): an AI participant "presents" a Cohort
+  //     surface (doc/sheet/channel/board/charter) on the call stage — an app
+  //     share rendered locally by every client and driven by step frames over
+  //     the room data lane. Lifecycle + coarse act batches persist a
+  //     CallShareSession projection and append REDACTED share.* events (never
+  //     step text/content). getAppShare hydrates late joiners; getVisualContext
+  //     reads the narrated visual stream (screen/camera stills interpreted into
+  //     text — frames are never persisted); getCallEvents reads recent
+  //     non-speech call events (reactions/hands/joins/share lifecycle). ---
+  "calling.appShareStart": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.appShareAct": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.appShareEnd": { family: "calling", scope: "calling.write", sideEffecting: true },
+  "calling.getAppShare": { family: "calling", scope: "org.read", sideEffecting: false },
+  "calling.getVisualContext": { family: "calling", scope: "org.read", sideEffecting: false },
+  "calling.getCallEvents": { family: "calling", scope: "org.read", sideEffecting: false },
+  // --- admin (kill switch) ---
+  "admin.deactivate": { family: "admin", scope: "admin", sideEffecting: true },
+  "admin.reactivate": { family: "admin", scope: "admin", sideEffecting: true },
+
+  // ============================================================
+  // Agent UI-parity methods (full human-action mirror)
+  // ============================================================
+  // --- charter ---
+  "charter.updateClauses": { family: "charter", scope: "charter.write", sideEffecting: true },
+  "charter.update": { family: "charter", scope: "charter.write", sideEffecting: true },
+  "charter.addSection": { family: "charter", scope: "charter.write", sideEffecting: true, idempotent: true },
+  "charter.updateSection": { family: "charter", scope: "charter.write", sideEffecting: true },
+  "charter.deleteSection": { family: "charter", scope: "charter.write", sideEffecting: true },
+  "charter.reorderSections": { family: "charter", scope: "charter.write", sideEffecting: true },
+  "charter.amend": { family: "charter", scope: "charter.write", sideEffecting: true },
+  "charter.editColleagueField": { family: "charter", scope: "charter.write", sideEffecting: true },
+  "charter.get": { family: "charter", scope: "org.read", sideEffecting: false },
+  // --- member ---
+  "member.create": { family: "member", scope: "org.write", sideEffecting: true, idempotent: true },
+  "member.update": { family: "member", scope: "org.write", sideEffecting: true },
+  "member.archive": { family: "member", scope: "org.write", sideEffecting: true },
+  "member.assignTeam": { family: "member", scope: "org.write", sideEffecting: true },
+  "member.reassignReporting": { family: "member", scope: "org.write", sideEffecting: true },
+  "member.savePosition": { family: "member", scope: "org.write", sideEffecting: true },
+  "member.resetPositions": { family: "member", scope: "org.write", sideEffecting: true },
+  "member.get": { family: "member", scope: "org.read", sideEffecting: false },
+  "member.list": { family: "member", scope: "org.read", sideEffecting: false },
+  "member.getEditorOptions": { family: "member", scope: "org.read", sideEffecting: false },
+  // --- team ---
+  "team.create": { family: "team", scope: "org.write", sideEffecting: true, idempotent: true },
+  "team.update": { family: "team", scope: "org.write", sideEffecting: true },
+  "team.delete": { family: "team", scope: "org.write", sideEffecting: true },
+  "team.list": { family: "team", scope: "org.read", sideEffecting: false },
+  // --- channel ---
+  "channel.create": { family: "channel", scope: "messaging.write", sideEffecting: true, idempotent: true },
+  "channel.update": { family: "channel", scope: "messaging.write", sideEffecting: true },
+  "channel.addMember": { family: "channel", scope: "messaging.write", sideEffecting: true, idempotent: true },
+  "channel.removeMember": { family: "channel", scope: "messaging.write", sideEffecting: true },
+  "channel.updateMemberRole": { family: "channel", scope: "messaging.write", sideEffecting: true },
+  "channel.markRead": { family: "channel", scope: "messaging.write", sideEffecting: true },
+  "channel.markUnreadFrom": { family: "channel", scope: "messaging.write", sideEffecting: true },
+  "channel.resolveOrCreateDm": { family: "channel", scope: "messaging.write", sideEffecting: true, idempotent: true },
+  "channel.createConversation": { family: "channel", scope: "messaging.write", sideEffecting: true, idempotent: true },
+  // --- persona ---
+  "persona.editField": { family: "persona", scope: "org.write", sideEffecting: true },
+  "persona.regenerate": { family: "persona", scope: "org.write", sideEffecting: true },
+  "persona.generateAgentId": { family: "persona", scope: "org.write", sideEffecting: true, idempotent: true },
+  // --- profile ---
+  "profile.update": { family: "profile", scope: "org.write", sideEffecting: true },
+  "profile.addSection": { family: "profile", scope: "org.write", sideEffecting: true, idempotent: true },
+  "profile.updateSection": { family: "profile", scope: "org.write", sideEffecting: true },
+  "profile.deleteSection": { family: "profile", scope: "org.write", sideEffecting: true },
+  "profile.updateAvatar": { family: "profile", scope: "org.write", sideEffecting: true },
+  "profile.get": { family: "profile", scope: "org.read", sideEffecting: false },
+  // --- sop ---
+  "sop.create": { family: "sop", scope: "org.write", sideEffecting: true, idempotent: true },
+  "sop.update": { family: "sop", scope: "org.write", sideEffecting: true },
+  "sop.delete": { family: "sop", scope: "org.write", sideEffecting: true },
+  "sop.list": { family: "sop", scope: "org.read", sideEffecting: false },
+  // --- escalation ---
+  "escalation.create": { family: "escalation", scope: "org.write", sideEffecting: true, idempotent: true },
+  "escalation.resolve": { family: "escalation", scope: "org.write", sideEffecting: true },
+  "escalation.list": { family: "escalation", scope: "org.read", sideEffecting: false },
+  // --- annotation ---
+  "annotation.create": { family: "annotation", scope: "org.write", sideEffecting: true, idempotent: true },
+  "annotation.comment": { family: "annotation", scope: "org.write", sideEffecting: true },
+  "annotation.resolve": { family: "annotation", scope: "org.write", sideEffecting: true },
+  "annotation.dismiss": { family: "annotation", scope: "org.write", sideEffecting: true },
+  "annotation.list": { family: "annotation", scope: "org.read", sideEffecting: false },
+  "annotation.getThread": { family: "annotation", scope: "org.read", sideEffecting: false },
+  // --- contact ---
+  "contact.add": { family: "contact", scope: "org.write", sideEffecting: true, idempotent: true },
+  "contact.update": { family: "contact", scope: "org.write", sideEffecting: true },
+  "contact.delete": { family: "contact", scope: "org.write", sideEffecting: true },
+  "contact.list": { family: "contact", scope: "org.read", sideEffecting: false },
+  // --- file ---
+  "file.pin": { family: "file", scope: "org.write", sideEffecting: true, idempotent: true },
+  "file.unpin": { family: "file", scope: "org.write", sideEffecting: true },
+  "file.addComment": { family: "file", scope: "org.write", sideEffecting: true },
+  "file.listComments": { family: "file", scope: "org.read", sideEffecting: false },
+  "file.listPinned": { family: "file", scope: "org.read", sideEffecting: false },
+  // --- memory ---
+  "memory.author": { family: "memory", scope: "knowledge.write", sideEffecting: true, idempotent: true },
+  "memory.proposeAmendment": { family: "memory", scope: "knowledge.write", sideEffecting: true },
+  "memory.mergeAmendment": { family: "memory", scope: "knowledge.write", sideEffecting: true },
+  "memory.list": { family: "memory", scope: "knowledge.read", sideEffecting: false },
+  // --- compact ---
+  "compact.upsert": { family: "compact", scope: "org.write", sideEffecting: true, idempotent: true },
+  // --- notification ---
+  "notification.updatePreferences": { family: "notification", scope: "org.write", sideEffecting: true },
+  "notification.getPreferences": { family: "notification", scope: "org.read", sideEffecting: false },
+  // --- decision ---
+  "decision.comment": { family: "decision", scope: "decision.write", sideEffecting: true },
+  "decision.sign": { family: "decision", scope: "decision.write", sideEffecting: true },
+  "decision.reverse": { family: "decision", scope: "decision.write", sideEffecting: true },
+  "decision.requestAdjustment": { family: "decision", scope: "decision.write", sideEffecting: true },
+  "decision.listComments": { family: "decision", scope: "org.read", sideEffecting: false },
+  // --- messaging ---
+  "messaging.schedule": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  "messaging.delete": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  "messaging.pin": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  "messaging.unpin": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  "messaging.bookmark": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  "messaging.unbookmark": { family: "messaging", scope: "messaging.write", sideEffecting: true },
+  // --- board ---
+  "board.createWorkstream": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
+  "board.updateWorkstream": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.deleteWorkstream": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.moveWorkstream": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.createTask": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
+  "board.updateTask": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.moveTask": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.assignTask": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.addTaskComment": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.addTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true, idempotent: true },
+  "board.updateTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.removeTaskAttachment": { family: "board", scope: "board.write", sideEffecting: true },
+  "board.taskComments": { family: "board", scope: "board.read", sideEffecting: false },
+  "board.taskAttachments": { family: "board", scope: "board.read", sideEffecting: false },
+  // --- invitation ---
+  "invitation.create": { family: "invitation", scope: "admin", sideEffecting: true, idempotent: true },
+  "invitation.revoke": { family: "invitation", scope: "admin", sideEffecting: true },
+  "invitation.resend": { family: "invitation", scope: "admin", sideEffecting: true },
+  // --- user ---
+  "user.updateRole": { family: "user", scope: "admin", sideEffecting: true },
+  "user.deactivate": { family: "user", scope: "admin", sideEffecting: true },
+  // --- settings ---
+  "settings.mintApiKey": { family: "settings", scope: "admin", sideEffecting: true, idempotent: true },
+  "settings.renameApiKey": { family: "settings", scope: "admin", sideEffecting: true },
+  "settings.revokeApiKey": { family: "settings", scope: "admin", sideEffecting: true },
+  "settings.recordSecretRotation": { family: "settings", scope: "admin", sideEffecting: true },
+  "settings.upsertSecret": { family: "settings", scope: "admin", sideEffecting: true, idempotent: true },
+  "settings.deleteSecret": { family: "settings", scope: "admin", sideEffecting: true },
+  "settings.upsertOfficeLocation": { family: "settings", scope: "admin", sideEffecting: true, idempotent: true },
+  "settings.deleteOfficeLocation": { family: "settings", scope: "admin", sideEffecting: true },
+  "settings.saveCompanyProfile": { family: "settings", scope: "admin", sideEffecting: true, idempotent: true },
+  "settings.saveDesignTokens": { family: "settings", scope: "admin", sideEffecting: true, idempotent: true },
+  "settings.getDesignTokens": { family: "settings", scope: "org.read", sideEffecting: false },
+  "settings.listApiKeys": { family: "settings", scope: "admin", sideEffecting: false },
+  // --- billing ---
+  "billing.update": { family: "billing", scope: "admin", sideEffecting: true },
+  // --- org ---
+  "org.create": { family: "org", scope: "admin", sideEffecting: true, idempotent: true },
+  "org.delete": { family: "org", scope: "admin", sideEffecting: true },
+  "org.mintApiKey": { family: "org", scope: "admin", sideEffecting: true, idempotent: true },
+  "org.revokeApiKey": { family: "org", scope: "admin", sideEffecting: true },
+  "org.list": { family: "org", scope: "org.read", sideEffecting: false },
+  // --- integration ---
+  "integration.connect": { family: "integration", scope: "admin", sideEffecting: true, idempotent: true },
+  "integration.disconnect": { family: "integration", scope: "admin", sideEffecting: true },
+  "integration.list": { family: "integration", scope: "org.read", sideEffecting: false },
+  // Live Integrations SP1 — tool-set versioning + propagation. Read-only pulls a
+  // runtime consumer (hq responder, MCP server, maestro daemon) uses to hot-refresh
+  // its in-memory tool cache without a restart: toolsetVersion is the cheap ETag
+  // poll; listAgentTools is the authoritative granted-tool manifest (schemas only —
+  // never plugin code or secrets). Org-scoped by the credential.
+  "integration.toolsetVersion": { family: "integration", scope: "org.read", sideEffecting: false },
+  "integration.listAgentTools": { family: "integration", scope: "org.read", sideEffecting: false },
+  // Live Integrations SP5 — execute one GRANTED plugin tool as the authenticated
+  // seat, returning the tool's raw output. The org + seat are resolved from the
+  // credential server-side (never a param), and the per-seat grant check is the
+  // real authorization gate. scope org.write (EDITOR-tier — in DEFAULT_AGENT_SCOPES,
+  // so a normal paired agent can invoke; a read-only VIEWER agent cannot). NOT a
+  // reserved-admin namespace. sideEffecting:false at the DISPATCHER layer: the hq
+  // handler proxies to runIntegrationTool, which owns its own execution + self-heal
+  // + audit and may run a long sandbox/external call — so, like the branding write
+  // surface, it must NOT run inside the dispatcher's single-append transaction.
+  "integration.invokeTool": { family: "integration", scope: "org.write", sideEffecting: false },
+  // --- branding (Brand Studio v2 write surface) — the agent mirror of the human
+  //     branding-generation / brand-templates / brand-export server actions.
+  //     sideEffecting:false at the dispatcher layer: the branding surface owns its
+  //     OWN versioned mutation + audit (the BrandVersion spine + self-appended
+  //     CohortEvents) and may run long AI/render passes, so it must NOT execute
+  //     inside the dispatcher's single-append transaction. Writes require ADMIN
+  //     (mirroring requireWorkspaceRole("ADMIN")); the two reads use org.read. ---
+  // --- directory (2026-07): the canonical party registry. Reads are AWARENESS
+  //     SCOPED at the query layer -- a named-only record is ABSENT from results
+  //     for a seat without a grant (never redacted, never inferable). Structural
+  //     verbs (executeMerge, revertMerge, setAwareness, archive*) are declared
+  //     here so a human bearer can call them; an AGENT actor is refused in-domain
+  //     and the call creates a review item instead. ---
+  "directory.search": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.listPeople": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.listOrgs": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.getPerson": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.getOrg": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.ask": { family: "directory", scope: "directory.read", sideEffecting: true },
+  "directory.exportVcard": { family: "directory", scope: "directory.read", sideEffecting: true },
+  "directory.listCaptures": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.listMerges": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.listAwarenessRequests": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.listLists": { family: "directory", scope: "directory.read", sideEffecting: false },
+  "directory.createPerson": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.updatePerson": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.archivePerson": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.createOrg": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.updateOrg": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.archiveOrg": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.addChannel": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.removeChannel": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.setPrimaryChannel": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.proposeCapture": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.resolveCapture": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.proposeMerge": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.executeMerge": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.revertMerge": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.requestAwareness": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.setAwareness": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.resolveAwarenessRequest": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.linkParty": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.unlinkParty": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.createList": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.addToList": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "directory.removeFromList": { family: "directory", scope: "directory.write", sideEffecting: true },
+  "directory.shareList": { family: "directory", scope: "directory.write", sideEffecting: true, idempotent: true },
+  "branding.regenerate": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.regenerateTemplates": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.regenerateTemplate": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.regenerateImages": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.uploadImage": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.amendArtifact": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.amendTemplate": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.cloneTemplate": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.deleteTemplate": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.restoreVersion": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.undo": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.redo": { family: "branding", scope: "admin", sideEffecting: false },
+  "branding.listVersions": { family: "branding", scope: "org.read", sideEffecting: false },
+  "branding.exportTemplate": { family: "branding", scope: "org.read", sideEffecting: false },
+  // --- Design section (2026-07): the versioned brand foundation. The UI section is
+  //     called "Design"; the wire family stays `branding` so enrolled agents keep
+  //     working. Agents read the SAVED snapshot only -- never a draft -- and can
+  //     render/generate within charter budgets. Foundation MUTATION is admin +
+  //     human-gated: `proposeChange` creates a reviewable diff, it never writes. ---
+  "branding.getFoundation": { family: "branding", scope: "design.read", sideEffecting: false },
+  "branding.getVoice": { family: "branding", scope: "design.read", sideEffecting: false },
+  "branding.listTemplates": { family: "branding", scope: "design.read", sideEffecting: false },
+  "branding.renderTemplate": { family: "branding", scope: "design.read", sideEffecting: true, idempotent: true },
+  "branding.rewriteInVoice": { family: "branding", scope: "design.read", sideEffecting: true },
+  "branding.exportKit": { family: "branding", scope: "design.read", sideEffecting: true },
+  "branding.generateImage": { family: "branding", scope: "design.write", sideEffecting: true, idempotent: true },
+  "branding.proposeChange": { family: "branding", scope: "design.write", sideEffecting: true },
+  "branding.saveFoundation": { family: "branding", scope: "admin", sideEffecting: true, idempotent: true },
+  "branding.restoreFoundation": { family: "branding", scope: "admin", sideEffecting: true },
+  // --- email (agent workspace email; SPEC 2026-07-21) — send is outbox-queued;
+  //     bodies NEVER enter org_events (redacted like messaging). Reads mirror
+  //     messaging.history (sideEffecting:false METHODS, not READS). ---
+  "email.send": { family: "email", scope: "email.write", sideEffecting: true, idempotent: true },
+  "email.markRead": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.inbox": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.message": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.thread": { family: "email", scope: "email.read", sideEffecting: false },
+  // --- email Inbox app (agent-lane mirror of the human Inbox; program
+  //     upgrade A) — THIN wrappers over the email domain services, the SAME
+  //     code the human server actions call, so mailbox entitlements, rules,
+  //     per-thread holds and the guardian-only verbs (approve/amend/return,
+  //     redirect) are enforced in the domain layer identically on both lanes.
+  //     Bodies stay REDACTED on-chain (the email.send precedent); reads
+  //     mirror email.inbox (sideEffecting:false METHODS, not READS). ---
+  "email.mailboxes": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.threads": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.messages": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.drafts": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.approvals": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.rules": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.signatures": { family: "email", scope: "email.read", sideEffecting: false },
+  "email.triage": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.triageNow": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.move": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.markAllRead": { family: "email", scope: "email.write", sideEffecting: true, idempotent: true },
+  "email.delegate": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.holdReplies": { family: "email", scope: "email.write", sideEffecting: true, idempotent: true },
+  "email.redirect": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.draftSave": { family: "email", scope: "email.write", sideEffecting: true, idempotent: true },
+  "email.draftDiscard": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.draftSend": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.undoSend": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.approve": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.approveAll": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.amend": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.return": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.ruleSave": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.ruleSetEnabled": { family: "email", scope: "email.write", sideEffecting: true, idempotent: true },
+  "email.folderRename": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.folderDelete": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.signatureSave": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.signatureDelete": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.logDecision": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.extractAction": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.fileAttachment": { family: "email", scope: "email.write", sideEffecting: true },
+  // --- email mobile-program delta (2026-08): spam disposition (blocklist
+  //     maintained in-domain), message reactions, cross-desk thread move, the
+  //     stored thread brief (closes inbox-report gap #3), and the grounded
+  //     mail ask (books.ask posture: read scope, gateway self-metered). ---
+  "email.reportSpam": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.react": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.moveMailbox": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.summarise": { family: "email", scope: "email.write", sideEffecting: true },
+  "email.ask": { family: "email", scope: "email.read", sideEffecting: false },
+  // --- artifact (generative-UI artifact system; GU program 2026-07) — rich
+  //     interactive cards agents post into conversational feeds, every rendered
+  //     action equally invocable programmatically (the two-sided law). Writes are
+  //     sideEffecting:false at the DISPATCHER: the hq artifact service owns its
+  //     own multi-write (Message + Artifact rows + self-appended chain events +
+  //     realtime fan-out + approval gating) exactly like branding.* /
+  //     integration.invokeTool, so it must NOT run inside the dispatcher's
+  //     single-append transaction. act idempotency is self-managed via an
+  //     (artifact, actor, action, idempotencyKey) dedupe in the service. Scopes
+  //     ride the messaging pair — artifacts live in conversation, and default
+  //     agent tokens already hold them, so deployed SDKs pick the family up on
+  //     protocol sync with no scope migration. ---
+  "artifact.create": { family: "artifact", scope: "messaging.write", sideEffecting: false },
+  "artifact.act": { family: "artifact", scope: "messaging.write", sideEffecting: false },
+  "artifact.patch": { family: "artifact", scope: "messaging.write", sideEffecting: false },
+  "artifact.get": { family: "artifact", scope: "messaging.read", sideEffecting: false },
+  "artifact.list": { family: "artifact", scope: "messaging.read", sideEffecting: false },
+  "artifact.catalog": { family: "artifact", scope: "messaging.read", sideEffecting: false },
+  // --- books (agent Books desk; PB-B1..B4) — THIN wrappers over the Books
+  //     domain services, the SAME code the human UI calls, so floors, holds
+  //     and the signature law behave identically on the agent lane. Writes run
+  //     in the dispatcher transaction and append exactly one chain event via
+  //     the domain op. The money/signature verbs (payrollSign, billScheduleRun,
+  //     taxSignLodge; floor/new-payee billApprove releases) additionally
+  //     require a verified HUMAN signature token inside the domain layer
+  //     (SIGNATURE_REQUIRED otherwise) — books.write alone cannot move money.
+  //     books.ask is a grounded ask-the-books via the shared AI gateway, which
+  //     self-audits its own model call (sideEffecting:false, the branding
+  //     precedent). Reads mirror email.inbox (sideEffecting:false METHODS).
+  //     Writes are idempotent-by-state (a replayed transition no-ops) except
+  //     the explicitly non-idempotent verbs (lineRecode, invoicePromise,
+  //     statementRun, taxReturn, stpResubmit — each run is a new act). ---
+  "books.journalPost": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.matchAccept": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.matchHoldResolve": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.receiptsRegister": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.lineRecode": { family: "books", scope: "books.write", sideEffecting: true },
+  "books.invoiceDraft": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.invoiceSend": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.invoiceChaseStep": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.invoiceRecordPayment": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.invoiceCreditNote": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.invoiceVoid": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.invoicePromise": { family: "books", scope: "books.write", sideEffecting: true },
+  "books.statementRun": { family: "books", scope: "books.write", sideEffecting: true },
+  "books.billCapture": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.billApprove": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.billHold": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.billReturn": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.billScheduleRun": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.expenseClaim": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.expenseApprove": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.payrollDraft": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.payrollSign": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.payrollRecall": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.onboardingStart": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.onboardingAdvance": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.leaveRequest": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.leaveApprove": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.taxPrepare": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.taxHold": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.taxReturn": { family: "books", scope: "books.write", sideEffecting: true },
+  "books.taxSignLodge": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.assetDepreciationRun": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.assetDispose": { family: "books", scope: "books.write", sideEffecting: true, idempotent: true },
+  "books.stpResubmit": { family: "books", scope: "books.write", sideEffecting: true },
+  "books.accounts": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.journals": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.feedLines": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.invoices": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.bills": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.taxObligations": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.reports": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.assets": { family: "books", scope: "books.read", sideEffecting: false },
+  "books.ask": { family: "books", scope: "books.read", sideEffecting: false },
+  // --- calendar (agent workspace calendar) — binds the same governance
+  //     DomainCtx as files.* (one governance layer, two families); writes
+  //     append exactly one chain event via the domain op. findATime is a
+  //     deterministic free-slot scan — proposing times changes nothing. ---
+  "calendar.create": { family: "calendar", scope: "calendar.write", sideEffecting: true, idempotent: true },
+  "calendar.update": { family: "calendar", scope: "calendar.write", sideEffecting: true, idempotent: true },
+  "calendar.reschedule": { family: "calendar", scope: "calendar.write", sideEffecting: true, idempotent: true },
+  "calendar.rsvp": { family: "calendar", scope: "calendar.write", sideEffecting: true, idempotent: true },
+  "calendar.delete": { family: "calendar", scope: "calendar.write", sideEffecting: true, idempotent: true },
+  "calendar.get": { family: "calendar", scope: "calendar.read", sideEffecting: false },
+  "calendar.list": { family: "calendar", scope: "calendar.read", sideEffecting: false },
+  "calendar.findATime": { family: "calendar", scope: "calendar.read", sideEffecting: false },
+  // Grounded calendar ask (books.ask posture; visibility-floored in-domain).
+  "calendar.ask": { family: "calendar", scope: "calendar.read", sideEffecting: false },
+  // --- crm (agent CRM desk) — THIN wrappers over the CRM domain services
+  //     (playbook holds, human-only signatures and ledger appends shared with
+  //     the UI). signEscalation / returnEscalation REFUSE non-human actors in
+  //     the domain layer — an agent-plane call fails exactly like the UI would
+  //     never allow it; setTarget's targetCents is likewise human-only.
+  //     compilePlaybook is a PURE compile preview (nothing persisted). ---
+  "crm.createDeal": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.updateDeal": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.deleteDeal": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.moveStage": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.closeDeal": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.signEscalation": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.returnEscalation": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.updateHeldTerms": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.delegate": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.holdNextStep": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.runNextBestAction": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.shareDeal": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.proposeTerms": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.revokeDealShare": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.linkFiles": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.linkContact": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.taskFollowThrough": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.logDealDecision": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.createAccount": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.updateAccount": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.archiveAccount": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.createContact": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.updateContact": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.deleteContact": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.logInteraction": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.addCallGuest": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.mintGuestToken": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.linkEmail": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.pinNote": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.redactInteraction": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.savePlaybook": { family: "crm", scope: "crm.write", sideEffecting: true },
+  "crm.togglePlaybook": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.deletePlaybook": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.setTarget": { family: "crm", scope: "crm.write", sideEffecting: true, idempotent: true },
+  "crm.listDeals": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.getDeal": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.listEscalations": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.listAccounts": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.listContacts": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.listInteractions": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.listPlaybooks": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.getTargets": { family: "crm", scope: "crm.read", sideEffecting: false },
+  "crm.compilePlaybook": { family: "crm", scope: "crm.read", sideEffecting: false },
+  // Grounded pipeline ask (books.ask posture; gateway self-metered).
+  "crm.ask": { family: "crm", scope: "crm.read", sideEffecting: false },
+  // --- files (agent workspace drive: Docs/Sheets/Decks/folders + binary
+  //     uploads) — binds the same Workspace DomainCtx the server actions use,
+  //     so shares/ACLs (VIEW/COMMENT/EDIT) govern agents exactly as humans
+  //     ("agents obey what you grant"). NB distinct from the UI-parity "file"
+  //     family (pins/comments on chat attachments) — both coexist. Reads
+  //     mirror email.inbox (sideEffecting:false METHODS, not READS). ---
+  "files.create": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.uploadRegister": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.rename": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.move": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.duplicate": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.star": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.pin": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.delete": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.recover": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.shareGrant": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.shareRevoke": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.docWriteRevision": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.sheetWriteCells": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.deckWriteSlides": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.list": { family: "files", scope: "files.read", sideEffecting: false },
+  "files.get": { family: "files", scope: "files.read", sideEffecting: false },
+  "files.docRead": { family: "files", scope: "files.read", sideEffecting: false },
+  "files.sheetRead": { family: "files", scope: "files.read", sideEffecting: false },
+  "files.deckRead": { family: "files", scope: "files.read", sideEffecting: false },
+  // files.exportRequest is an AUDITED export: it rides the READ scope (export
+  // is reading content out) but is sideEffecting — every export lands on the
+  // chain (path DIRECT_CONTENT | PRINT_VIEW | SANDBOX_CONVERTER).
+  "files.exportRequest": { family: "files", scope: "files.read", sideEffecting: true, idempotent: true },
+  // --- files mobile-editors delta (2026-08): multi-tab structure ops (one
+  //     method per surface, op-discriminated — the email.move precedent),
+  //     held doc suggestions, the kind-agnostic comment lane, agent-fed
+  //     sheet ranges, and the grounded drive ask (books.ask posture). ---
+  "files.sheetTabOp": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.docTabOp": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.docSuggestResolve": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.docSuggestions": { family: "files", scope: "files.read", sideEffecting: false },
+  "files.commentAdd": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.commentResolve": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.comments": { family: "files", scope: "files.read", sideEffecting: false },
+  "files.sheetFedRange": { family: "files", scope: "files.write", sideEffecting: true, idempotent: true },
+  "files.ask": { family: "files", scope: "files.read", sideEffecting: false },
+});
+
+/**
+ * Is a method refused until the org server is `governance_ready` (decision_rights
+ * populated AND signing live)? A partially deployed control plane is worse than
+ * none (SPEC §0.4): handoffs and assignment/decomposition must not flow before
+ * the decision-rights matrix exists. Pure.
+ * @param {string} name @returns {boolean}
+ */
+export function isGovernanceGated(name) {
+  const def = methodDef(name);
+  return !!(def && def.governanceGated);
+}
+
+/** Read endpoints (GET) and their required scope. */
+export const READS = Object.freeze({
+  "snapshot": "org.read",
+  "directory": "org.read",
+  "events": "org.read",
+  "hierarchy": "org.read",
+  "board.ready": "board.read",
+  "board.context": "board.read",
+  "ops": "org.read",
+  // phase 3 reads
+  "approval.wait": "approval.request", // bounded long-poll for an approval outcome
+  "cost.rollup": "org.read",           // org-wide cost rollup (per agent/model/cadence)
+  "decision.list": "org.read",         // adopted decisions registry
+  "policy": "org.read",                // agents fetch the current signed policy bundle
+  // phase 4 reads
+  "contacts.list": "knowledge.read",   // org contacts registry (ACL-filtered)
+  "meetings.list": "knowledge.read",   // org meetings registry (ACL-filtered)
+});
+
+/** Error codes (the error contract; HTTP status hints are advisory). */
+export const ERROR_CODES = Object.freeze({
+  BAD_REQUEST: { http: 400 },
+  UNAUTHORIZED: { http: 401 },
+  FORBIDDEN_SCOPE: { http: 403 },
+  NOT_FOUND: { http: 404 },
+  CONFLICT: { http: 409 },                 // e.g. claim race loser
+  IDEMPOTENT_REPLAY: { http: 200 },        // returned cached result, not an error per se
+  GOVERNANCE_NOT_READY: { http: 423 },     // §0.4 ordering gate
+  RATE_LIMITED: { http: 429 },
+  WEAK_SECRET: { http: 401 },
+  INTERNAL: { http: 500 },
+});
+
+/** Directive kinds the presence.beat response may carry (kill-switch + nudges). */
+export const DIRECTIVES = Object.freeze(["halt", "rotate_token", "policy_stale", "resync"]);
+
+// ---------------------------------------------------------------------------
+// Helpers (shared, pure)
+// ---------------------------------------------------------------------------
+
+/** @param {string} name @returns {object|null} the method descriptor or null. */
+export function methodDef(name) {
+  return Object.prototype.hasOwnProperty.call(METHODS, name) ? METHODS[name] : null;
+}
+
+/**
+ * Resolve the scope a method requires. A method in a reserved namespace ALWAYS
+ * requires `admin` (defence-in-depth: a missing/typo'd descriptor cannot
+ * accidentally widen access). Unknown methods resolve to `admin` (deny).
+ * @param {string} name
+ * @returns {string}
+ */
+export function scopeForMethod(name) {
+  const ns = String(name || "").split(".")[0];
+  if (RESERVED_ADMIN_NAMESPACES.includes(ns)) return "admin";
+  const def = methodDef(name);
+  return def ? def.scope : "admin";
+}
+
+/** @param {string} name @returns {boolean} */
+export function isReservedAdminNamespace(name) {
+  return RESERVED_ADMIN_NAMESPACES.includes(String(name || "").split(".")[0]);
+}
+
+/**
+ * Does an actor holding `scopes` satisfy the requirement for `methodName`?
+ * `admin` satisfies everything. Pure.
+ * @param {string[]} scopes
+ * @param {string} methodName
+ * @returns {boolean}
+ */
+export function actorCan(scopes, methodName) {
+  const need = scopeForMethod(methodName);
+  if (!Array.isArray(scopes)) return false;
+  if (scopes.includes("admin")) return true;
+  return scopes.includes(need);
+}
+
+/**
+ * Canonical JSON for hashing/signing: keys sorted recursively so the same
+ * logical value always serializes to the same bytes on both sides.
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalize(value) {
+  return JSON.stringify(sortDeep(value));
+}
+
+function sortDeep(v) {
+  if (Array.isArray(v)) return v.map(sortDeep);
+  if (v && typeof v === "object") {
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sortDeep(v[k]);
+    return out;
+  }
+  return v;
+}
+
+/**
+ * Compute the hash-chain row hash for an event. THE load-bearing function: the
+ * server writes `row_hash = computeRowHash(prevHash, row)` per event, and the
+ * detective layer recomputes it to prove the log was not rewritten. Any change
+ * to this function is a protocol break (bump PROTOCOL_VERSION).
+ *
+ * @param {string} prevHash hex hash of the previous event ("" for the genesis row)
+ * @param {{seq:number, family:string, kind:string, entity_id:string, payload:unknown, at:string, actor:string}} row
+ * @returns {string} lowercase hex sha-256
+ */
+export function computeRowHash(prevHash, row) {
+  const material = canonicalize({
+    prev: prevHash || "",
+    seq: row.seq,
+    family: row.family,
+    kind: row.kind,
+    entity_id: row.entity_id,
+    actor: row.actor || "",
+    at: row.at,
+    payload: row.payload ?? null,
+  });
+  return createHash("sha256").update(material).digest("hex");
+}
+
+/**
+ * Verify a contiguous slice of the event chain links correctly. Returns the
+ * first break (index + reason) or null when the slice is internally consistent.
+ * `startPrev` is the row_hash of the event BEFORE events[0] ("" if from genesis).
+ * @param {Array<object>} events ordered by seq ascending
+ * @param {string} [startPrev=""]
+ * @returns {{ index:number, reason:string }|null}
+ */
+export function verifyChain(events, startPrev = "") {
+  let prev = startPrev;
+  for (let i = 0; i < events.length; i++) {
+    const e = events[i];
+    if ((e.prev_hash || "") !== prev) return { index: i, reason: "prev_hash mismatch" };
+    const expect = computeRowHash(prev, e);
+    if (e.row_hash !== expect) return { index: i, reason: "row_hash mismatch" };
+    prev = e.row_hash;
+  }
+  return null;
+}
+
+/**
+ * Build a request frame for the RPC binding. Side-effecting methods require an
+ * idempotency key (the caller supplies a stable one for safe retries).
+ * @param {string} method @param {object} params @param {object} [opts] @param {string} [opts.idempotencyKey]
+ * @returns {{method:string, params:object, idempotencyKey?:string}}
+ */
+export function buildReqFrame(method, params = {}, opts = {}) {
+  const frame = { method, params: params || {} };
+  if (opts.idempotencyKey) frame.idempotencyKey = String(opts.idempotencyKey);
+  return frame;
+}
+
+/**
+ * Validate an inbound request frame against the registry. Returns
+ * {ok:true, def} or {ok:false, code, message}. Pure — no auth check here
+ * (that needs the actor's scopes; see actorCan).
+ * @param {any} frame
+ * @returns {{ok:true, def:object}|{ok:false, code:string, message:string}}
+ */
+export function validateReqFrame(frame) {
+  if (!frame || typeof frame !== "object") return { ok: false, code: "BAD_REQUEST", message: "frame not an object" };
+  if (typeof frame.method !== "string") return { ok: false, code: "BAD_REQUEST", message: "method missing" };
+  const def = methodDef(frame.method);
+  if (!def) return { ok: false, code: "NOT_FOUND", message: `unknown method ${frame.method}` };
+  if (frame.params != null && typeof frame.params !== "object") return { ok: false, code: "BAD_REQUEST", message: "params must be an object" };
+  if (def.sideEffecting && def.auth !== false && def.idempotent && !frame.idempotencyKey) {
+    // idempotent side-effecting methods want a key for safe retries; warn-not-fatal
+    // (the server may synthesize one), so this is advisory, not a hard reject.
+  }
+  return { ok: true, def };
+}
+
+/** Build a success response frame. */
+export function okFrame(result) {
+  return { ok: true, result: result ?? null };
+}
+
+/** Build an error response frame. */
+export function errFrame(code, message) {
+  const known = ERROR_CODES[code] ? code : "INTERNAL";
+  return { ok: false, error: { code: known, message: String(message || known) } };
+}