kestrel.markets/docs/adr/0046-the-protocol-package-owns-the-wire-shapes-and-stays-dependency-free.md

A typed, token-efficient language + runtime for agentic trading: agents author bounded plans, the runtime fires them at the tick. CLI + typed library + MCP server.

# OSS-ADR-0046 — The protocol package owns the wire shapes and stays dependency-free

Status: accepted (2026-07-15, owner grill — arch-review B3)

## Context

The CLI's remote transport hand-writes a parallel copy of every hosted-service
wire shape (`src/cli/backend/wire.ts` — operations, offers, trial capabilities,
SSE event names) and its header promises byte-for-byte fidelity that nothing
verifies; the conformance suite exercises a local mock that has already been
caught speaking a wrong dialect. Meanwhile `src/protocol` already owns the
wire *vocabulary* piece by piece — the `Scope` union, `RECEIPT_KINDS`, the
wire-path/SSE constants, and (per OSS-ADR-0045) the refusal-code union —
and downstream consumers import it as the single source of truth.

## Decision

1. **`src/protocol` owns the wire shapes.** The request/response and SSE event
   shapes the CLI speaks live in the protocol package as pure TypeScript types
   and `const` tuples — the same form as the existing vocabulary. The remote
   transport (`cli/backend/wire.ts`) becomes imports from protocol; the
   hand-maintained copy is deleted.
2. **The protocol package ships zero runtime dependencies.** Types and tuples
   only — no schema-library runtime. Consumers that need runtime validation or
   JSON Schema generate them from the published types at their own build time.
3. **Conformance runs against externally generated fixtures**, not a
   hand-written mock dialect: the CLI conformance suite consumes the hosted
   service's published contract fixtures as the cross-check that the shapes
   match reality.

## Consequences

- One source for every wire shape inside this repo; a shape change is one edit.
- The published package stays lean for the `npx` funnel — no validator
  dependency rides along.
- Shape drift against the hosted service becomes a red conformance run instead
  of a runtime surprise.