# @boocode/contracts — cross-app wire contract SSOT

**Status:** shipped (2026-06-02)

Eliminate BooCode's hand-synced, duplicated cross-app TypeScript wire contracts by
creating one workspace package, `@boocode/contracts`, that every consumer imports.
Each contract is defined exactly once; the two Zod-backed contracts (`ws-frames`,
`provider-config`) use `z.infer` so validator and type derive from the same definition
and cannot drift independently.

## Why

BooCode maintained hand-synced copies of cross-app contracts across up to four
locations (`apps/server`, `apps/web`, `apps/coder`, `apps/coder/web`), verified only
by byte-parity tests — `provider-types-parity.test.ts` and the ws-frames byte-parity
assertion in `ws-frames.test.ts`. A live drift had appeared: `AgentSessionConfig`
existed in two incompatible shapes — `apps/coder` held an all-optional dead copy
(zero live importers) while `apps/web` held the real required/nullable shape — making
the parity-test regime insufficient for type-only contracts.

`v2.5.12-provider-lifecycle-phase4` had explicitly deferred a shared types package as
"not worth the Docker/build-order risk at solo scale"; the observed drift made the
investment worth taking.

## What shipped

**Package:** `packages/contracts` (`@boocode/contracts`), `declaration:true`, zod
pinned `^3.23.8`, per-subpath exports map with `types`-then-`default` conditions.
`packages/*` added to `pnpm-workspace.yaml`; `pnpm-lock.yaml` regenerated.

**Six contracts single-sourced:**

- `./ws-frames` — `WsFrameSchema` (Zod runtime), `KNOWN_FRAME_TYPES`, `WsFrame`
  (`z.infer` from the schema).
- `./provider-snapshot` — `ProviderSnapshotEntry`, `ProviderModel`, `ProviderMode`,
  `ThinkingOption`, `AgentCommand`, `ProviderSnapshotStatus` (plain TS; the coder's
  `provider-types.ts` re-exports them so internal importers are unchanged).
- `./provider-config` — `ProviderOverrideSchema`, `CoderProvidersFileSchema`,
  `ProviderConfigPatchSchema` and their `z.infer` types.
- `./message-metadata` — `MessageMetadata`, `ErrorReason`, `AgentSessionConfig`.
- `./worktree-risk` — `WorktreeRiskReport` (unified from three copies that differed
  only in name; the coder called it `RiskReport`).

**Four consumers** import via `workspace:*` through the exports map: `apps/server`,
`apps/web`, `apps/coder`, and the fallback SPA `apps/coder/web`. No tsconfig project
references; built dist only.

**Deleted:**
- `apps/server/src/types/ws-frames.ts` (server `./ws-frames` exports subpath dropped)
- `apps/web/src/api/ws-frames.ts`
- Provider-snapshot mirror block in web (`apps/web/src/api/types.ts`)
- Provider-config 17-line hand-mirror in web
- `apps/coder/src/services/__tests__/provider-types-parity.test.ts` (6 parity tests)
- ws-frames byte-parity assertion (server test suite)
- All duplicate `MessageMetadata`, `ErrorReason`, `AgentSessionConfig` copies
- `WorktreeRiskReport` / `RiskReport` duplicates (3 copies)
- `apps/coder/web` dead `pending_change_added`/`pending_change_updated` reducer arms
  and associated WS plumbing (`DiffPane` prop, `Session.tsx` listener)

**Preserved:**
- KNOWN_FRAME_TYPES drift test — moved into the package (11/11)
- Broker fail-closed tests — kept in `apps/server`, importing from the package (4/4)
- Web strict `SessionFrame`/`UserFrame` discriminated union — web-local, untouched

## Key decisions

**F1 (ws-frames):** repoint all 8 server/coder importers + 2 web validators to the
package; drop the server `./ws-frames` re-export subpath — one path per contract, no
shim.

**F2 (web strict union):** the package exports the runtime schema only (`WsFrameSchema`,
`KNOWN_FRAME_TYPES`, loose `WsFrame`). The web's rich discriminated union stays
web-local — it references entity types (`Message`, `ToolCall`, etc.) that are
intentionally web-local and not cross-app duplicated. Zero entity-type scope expansion.

**AgentSessionConfig drift:** unified to the web required/nullable shape; the coder's
all-optional copy confirmed dead (zero live importers) and deleted.

**`apps/coder/web` (fallback SPA):** its hand-copied 9-arm `WsFrame` union replaced by
the canonical import; dead `pending_change_*` arms removed (no publisher exists for
these frames anywhere in the codebase — they were HTTP-delivered, not WS); field
conflicts reconciled per-field (`tool_result.error` boolean→string, `tokens_used`
number→number|null, `snapshot.messages` cast).

**Two `ErrorReason` concepts (intentional, not duplication):**
`message-metadata`'s `ErrorReason` is the DB-persisted 3-value set; the ws-frames
frame-level `reason` is the wire 5-value set. Different value sets, different
semantics, confirmed during audit.

## Build-order inversion

Contracts builds before all consumers in:
- Root `package.json` build script
- `Dockerfile` — new `COPY packages/*` block + contracts build step before web/server
- Coder deploy command — updated in all 7 doc sites (CLAUDE.md, apps/coder/CLAUDE.md,
  BOOCODER.md, docs/ARCHITECTURE.md, docs/project-discovery.md, README.md,
  docs/coder-backends.md)

## Test counts at ship

Server 543 / coder 293 / contracts 11. Clean `docker compose build --no-cache boocode`
green. Human smoke verified 2026-06-02.