# Tool↔Gateway Mapping Contract (D8)

Status: DRAFT — awaiting ratification (webui-audit S2, contract 5 of 9).
Authority: PRD D8/D12 (Part I §8) — the webUI sits OVER official tooling:
every webUI operation goes through the Gateway API backed by the same
official framework tooling the CLI uses, and a webUI operation with no
backing tool is scored **blocked on tooling** and the tool is built
first. Measured input: the webui-audit A5 tooling baseline
(operation-by-operation inventory of the current Gateway surface and the
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
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 and Amendment A1), roll-up (contract 8), API artifact format
(contract 9).

## 1. Definitions

1. **Official tool**: a command implemented in the framework packages and
   exposed through the Gateway API; the CLI remains the primary execution
   method for the same command (D8). The webUI is a Gateway client only.
2. **Mapped operation**: a webUI operation with a named official path in
   §2 or §3. Anything else the webUI wants to do is unmapped and follows
   §5.
3. **Legacy non-substitute**: an existing endpoint that resembles a P1
   need but is contractually barred from backing it (§3.2).

## 2. P0 mapping (current operations, ratified as-is)

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` — 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.

## 3. P1 mapping (bound to the build-first tools)

1. Every P1 operation maps to exactly one build-first command family, in
   the T10-ruled rank order:

| Rank | Command family (owning contract)                                       | P1 webUI operations it backs                                                                                                                      |
| ---- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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, 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 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
   `/api/tasks` CRUD (planning-data records, not hierarchy nodes and not
   the typed kanban boundary); `POST /api/workspaces` (filesystem
   bootstrap, not audited hierarchy parentage); `/api/teams` reads (no
   grants, no inheritance); `POST /api/bootstrap/setup` (one-shot
   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
   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).

## 4. Command envelope (request / result / error / audit)

Binding on every mapped operation the build-first families expose:

1. **Typed request and result.** Each command and query has an explicit
   request DTO and result DTO in the shared types package, validated at
   the Gateway boundary; unvalidated pass-through and `any`-typed
   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 §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,
   authentication failure, authorization refusal, not-found, conflict
   (version/uniqueness), precondition/state refusal (e.g. bootstrap
   epoch, suspended team subjects), and internal fault. Where contract
   2's no-existence-oracle rule applies, authorization refusal and
   not-found are indistinguishable on the wire for unauthorized readers
   — same code, same status, same shape.
3. **Audit linkage.** A mutating mapped operation emits exactly the
   audit events its owning contract defines (contract 1 §5.2, contract 2
   §4.4, identity §§2–4, SOT audit rules); the envelope contributes the
   correlation: every request accepts/generates a correlation id,
   carried into the audit events and returned in the result, so a UI
   action is traceable end to end. The mapping layer itself adds no
   second audit stream.
4. **Fail-closed.** A mapped operation that cannot evaluate its
   authorization or reach its owning tool refuses (contract 2 §3.5); the
   envelope never degrades to an unauthorized fallback read or a direct
   data access.
5. **CLI parity.** Each build-first family is invocable through the
   official CLI against the same Gateway commands with the same
   request/result/error contracts. No webUI-only command exists; a
   Gateway command without CLI exposure is a conformance gap tracked at
   the family's implementing issue.

## 5. Closure rule (blocked on tooling)

1. A webUI change that needs an operation with no mapping row is
   **blocked on tooling**: the backing tool is built and mapped first
   (D8). Scoring a gap "blocked on tooling" is mandatory, not
   discretionary; working around it in the UI (direct DB or filesystem
   access, calling a legacy non-substitute, embedding domain logic in
   the web app) is non-conformant.
2. The mapping is enforced closed by §6.1's inventory witness: the web
   app's network surface must be a subset of the mapped paths.

## 6. Verification requirements

Binding on the implementing PRs:

1. **Network-surface inventory witness:** a CI assertion extracting the
   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.
3. **Envelope witnesses per family:** for each build-first family — a
   request with an invalid DTO is refused with the validation code; a
   version-mismatch mutation returns the conflict code; an unauthorized
   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. 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.
5. **Fail-closed witness:** with the owning tool or grant state
   unreachable (fault injection), the mapped operation returns the
   internal-fault or authorization-refusal class and performs no
   fallback read/write (extends contract 2 §7.6 to the mapping layer).

## Ruling request

Ratify sections 1–6 as written, with one decision embedded:

- Decision (§3.2): the legacy endpoints named there are **frozen for new
  consumers** as of ratification — existing P0/host consumers keep
  working, new UI or tool code may not call them, and each is retired by
  the migration its owning contract schedules. Alternative if rejected:
  allow P1 surfaces to reuse legacy endpoints as interim backends —
  rejected by the audit's finding that they cannot satisfy the
  hierarchy/kanban/RBAC contracts, so the interim would ship
  non-conformant semantics.
