diff --git a/docs/requirements/tool-gateway-mapping.md b/docs/requirements/tool-gateway-mapping.md index e413ebe8..663ba8a8 100644 --- a/docs/requirements/tool-gateway-mapping.md +++ b/docs/requirements/tool-gateway-mapping.md @@ -11,6 +11,15 @@ P1 gaps, cross-reviewed; `fleet/lanes/webui-audit/findings/ A5-tooling-baseline.md` in the estate brain). The T10 ruling adopted the targeted-update plan including building the D8 tools in A5's rank order. +Revision 2 (GLM review F1–F5): the §2 table completed against an +independent re-measurement of the live `apps/web` surface (mission +reads, coordination status, capability-gated `turn:send` added); rank-6 +composition corrected to ranks 1 and 4; SOT citations corrected to §3 +invariant 11 / REQ-TASK-001 / §5+A1; the §3.2 retirement clause +softened to match what the owning contracts actually schedule; §6.1 +scoped to outbound calls with an extractability lint, and §6.3 given +static companions for §4.1 and §4.3. + This contract binds three things: the operation→tool mapping itself (§2–§3), the command envelope every mapped operation satisfies (§4), and the process rule that keeps the mapping closed (§5). Domain @@ -18,7 +27,8 @@ semantics stay with their owning contracts — hierarchy (contract 1, `hierarchy-schema.md`), grants (contract 2, `rbac-grant-model.md`), wizard (contract 3, `onboarding-wizard.md`), identity (`identity-lifecycle.md`), kanban lifecycle (`native-kanban-sot.md` -§§5–6), roll-up (contract 8), API artifact format (contract 9). +§5 and Amendment A1), roll-up (contract 8), API artifact format +(contract 9). ## 1. Definitions @@ -33,19 +43,25 @@ wizard (contract 3, `onboarding-wizard.md`), identity ## 2. P0 mapping (current operations, ratified as-is) -The measured P0 surface is conformant today and stays bound to these -paths: +This table is the complete measured P0 surface: every Gateway call the +web app's production sources make at this revision's head appears as a +row (independently re-measured at review; the three calls the first +measurement missed — mission reads, coordination status, and the +capability-gated `turn:send` emit — are rows below). The surface stays +bound to these paths: -| WebUI operation | Official path | -| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | -| Register / log in / log out / OIDC callback | better-auth mount `/api/auth/*`; `GET /api/sso/providers` | -| List/show projects (legacy read) | `GET /api/projects`, `GET /api/projects/:id` | -| List tasks / task detail (legacy read) | `GET /api/tasks`, `GET /api/tasks/:id` | -| Conversation CRUD/search/messages | `/api/conversations*` | -| Chat turn / stop / thinking / command execute+approve / streaming | `/chat` socket events `message`, `abort`, `set:thinking`, `command:execute`, `command:approve` | -| Harness/model selection | `GET /api/harnesses*`, `GET/PUT /api/chat/preferences/selection` | -| Preferences; provider inspect/test | `/api/memory/preferences`, `GET /api/providers`, `POST /api/providers/test` | -| Admin users / roles / ban / health | `/api/admin/users*`, `/api/admin/health` | +| WebUI operation | Official path | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Register / log in / log out / OIDC callback | better-auth mount `/api/auth/*`; `GET /api/sso/providers` | +| List/show projects (legacy read) | `GET /api/projects`, `GET /api/projects/:id` | +| List tasks / task detail (legacy read) | `GET /api/tasks`, `GET /api/tasks/:id` — with the filtered legacy project/mission reads the same surfaces use | +| Mission list (legacy read) | `GET /api/missions` | +| Coordination status (legacy read) | `GET /api/coord/status` | +| Conversation CRUD/search/messages | `/api/conversations*` | +| Chat turn / stop / thinking / command execute+approve / streaming | `/chat` socket events `message`, `abort`, `set:thinking`, `command:execute`, `command:approve`; `turn:send` (capability-gated — emitted only when the server advertises the pi turn-runtime capability, which the current Gateway does not) | +| Harness/model selection | `GET /api/harnesses*`, `GET/PUT /api/chat/preferences/selection` | +| Preferences; provider inspect/test | `/api/memory/preferences`, `GET /api/providers`, `POST /api/providers/test` | +| Admin users / roles / ban / health | `/api/admin/users*`, `/api/admin/health` | P0 rows inherit §4 obligations as their backing controllers are next touched; they are not required to be retrofitted in one sweep. @@ -59,10 +75,10 @@ touched; they are not required to be retrofitted in one sweep. | ---- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Hierarchy command family (contract 1 §5; grants attach per contract 2) | Company/estate/platform-project/workspace CRUD, parentage and reparenting, hierarchy reads; the wizard's initial-hierarchy step (contract 3 §3.4) | | 2 | Hierarchy RBAC command/evaluator (contract 2) | Grant create/change/revoke at company/estate/platform-project; inherited evaluation down to workspace; authorization-safe hierarchy queries | -| 3 | Typed kanban command/query surface (SOT §§5–6, A1) | Workspace task lifecycle (create/edit/cancel/archive/move), board rank, typed queries | +| 3 | Typed kanban command/query surface (SOT §5, Amendment A1) | Workspace task lifecycle (create/edit/cancel/archive/move), board rank, typed queries | | 4 | Agent enrollment command | Enroll one agent: harness, credential reference/API-key intake (values never echoed), name/persona, assignment scope (contract 3 §3.5) | | 5 | Authorized roll-up query (contract 8) | Read-only aggregated task counts/statuses at every hierarchy level over readable workspaces only | -| 6 | Onboarding orchestration (contract 3) | The re-runnable wizard flow, composing ranks 1, 2, and 4 | +| 6 | Onboarding orchestration (contract 3) | The re-runnable wizard flow, composing ranks 1 and 4 (its only grant write rides inside the rank-1 company-create command, contract 2 §4.3) | 2. **Legacy non-substitutes.** The following MUST NOT back any P1 operation, matching the audit findings: legacy `/api/projects` and @@ -73,7 +89,9 @@ touched; they are not required to be retrofitted in one sweep. epoch transition, identity §3 — not the re-runnable wizard); the MCP `brain_*` task mutations (legacy Brain writes, not the typed kanban commands). These stay serving their existing P0/host consumers until - each is retired by the migration its owning contract schedules. + the owning contract (or a successor amendment) schedules each + retirement — no such migration is scheduled at this revision; the + freeze stands on its own. 3. New P1 mapping rows (operations this table does not list) are added by amending this contract, not ad hoc (§5). @@ -87,7 +105,8 @@ Binding on every mapped operation the build-first families expose: payloads are non-conformant. Mutations on records with an expected-version rule in their owning contract carry the expected version in the request and fail on mismatch with the conflict error - class (SOT §6 optimistic concurrency; hierarchy per contract 1). + class (SOT §3 invariant 11 and REQ-TASK-001's concurrent-update + conflict acceptance; hierarchy per contract 1). 2. **Error taxonomy.** Every error result carries a stable machine-readable code from a closed per-family enum plus an HTTP status mapping, distinguishing at minimum: validation failure, @@ -130,13 +149,17 @@ Binding on every mapped operation the build-first families expose: Binding on the implementing PRs: 1. **Network-surface inventory witness:** a CI assertion extracting the - web app's Gateway calls (route literals and socket event names in - `apps/web` sources) and failing on any call outside the §2/§3 mapped - paths. The inventory is closed like contract 1 §6.3's allowlist: a - new call fails until a mapping row exists in the same PR. Dynamic - route construction that evades extraction is resolved toward the - witness (routes are declared extractably), not by exempting the - caller. + web app's outbound Gateway calls — route literals at request call + sites and outbound socket emits in `apps/web` sources (inbound + handler registrations are not calls and are out of scope) — and + failing on any call outside the §2/§3 mapped paths. The inventory is + closed like contract 1 §6.3's allowlist: a new call fails until a + mapping row exists in the same PR. Dynamic route construction that + evades extraction is resolved toward the witness, enforced by an + extractability lint: every request call site takes a literal or + template-literal path, and a call site that does not fails the + assertion itself (the web-side analogue of contract 1's + raw-execution prong), never an exemption for the caller. 2. **Non-substitute witness:** the P1 surfaces (hierarchy, RBAC, kanban, enrollment, roll-up, wizard UI) make zero calls to the §3.2 legacy endpoints — asserted by the same inventory, scoped per surface. @@ -146,7 +169,12 @@ Binding on the implementing PRs: read of an existing node and a read of a nonexistent node return indistinguishable results where the no-existence-oracle rule applies; a correlation id submitted on a mutation appears in its audit - event(s) and result. + event(s) and result. Two static companions: a type-level assertion + that the family's boundary accepts no `any`-typed or unvalidated + pass-through payload (§4.1), and a single-emitter assertion that the + mapped operation's audit events originate only from the owning + contract's audit emitter (§4.3's no-second-audit-stream, made + checkable). 4. **CLI-parity witness:** for each family, a CLI smoke invocation of at least one command and one query against the Gateway succeeds with the same typed result the web client receives.