# ADR 0014: A stream declares its subscription reply schema separately from its push payload

- Status: accepted
- Date: 2026-09-08
- Carried over: 2026-09-14, from the system Truewire was extracted from (its ADR 0022)

## Context

A `kind: 'stream'` endpoint in the request/response shape (design §8) carried two schemas:
`parameters` for the subscribe call and `payload` for each pushed message. The legacy
`openapi` shape had a third slot, `responses.reply`, and the migration dropped it: no
mechanized client's `subscribe()` did anything with the acknowledgement beyond handing it
back, so nothing seemed lost. `truewire_core.util.Stream` kept an `Any`-defaulted
`SubscriptionReply` type argument that no generated method ever filled.

dydx showed what was lost. Its Indexer acks every channel with a real value — `v4_orderbook`
with the full book as `{price, size}` objects, `v4_markets` with every market, the two
subaccount channels with the whole subaccount — and pushes a different shape afterwards
(`[price, size]` tuples, deltas). Its hand-written `StreamsMixin.subscribe` had one
`response_type` and applied it to both frames, so entering an order-book stream raised
`ValidationError` before the first push (SDK PoC report, 2026-09-06, live on testnet), and
three channels validated their ack silently to `{}`. The interim fix stopped validating the
ack at all, returning it raw into the `Any` slot. The seven `*ReplyContents` types sat
generated in `indexer/schemas.py`, unreferenced, because the spec had nowhere to name them.

The alternatives were a per-client `meta` convention (a core-private fact codegen would
have to be taught per venue) or a union `payload` covering both frames (which types every
push as possibly-a-snapshot and every ack as possibly-a-delta — wrong on both sides).

## Decision

`StreamEndpointSpec` gains an optional fourth new-shape field, `reply`: a JSON Schema for the
value the core hands back as `Stream.reply`, after `envelope.reply_payload` (or `payload`)
extraction, exactly as `payload` describes a pushed message after `envelope.payload`
extraction. It is the new-shape counterpart of the legacy `openapi.responses.reply`.

- `truewire check` validates every recorded `<id>.reply.json` against it, extracting
  through the envelope first. The authoring audit sees it as the `reply` response.
- The Python generator renders it as the second type argument of the generated method's
  `StreamManager[Payload, Reply, Any]` and passes it to the resolved core as `reply_type=`,
  beside `response_type=`. A bare `$ref` imports the shared type, as `payload` does.
- A stream that declares no `reply` generates byte-for-byte what it did before: no
  `reply_type=`, `Any` in the reply slot. Verified by regenerating every stream-carrying
  client and diffing nothing.
- A core is expected to validate the ack through `reply_type` and never through
  `response_type`, and vice versa. dydx's `StreamsMixin.subscribe` does; its seven channels
  declare `reply` pointing at their `*ReplyContents` schemas.

## Consequences

- `Stream.reply` is a real type on any channel that declares one, so an SDK consumer can
  seed a local book from the ack without a cast. The generated `validate` flag now governs
  the ack as well as the pushes on such a channel.
- Declaring `reply` on a stream whose core's `subscribe()` has no `reply_type` parameter
  fails pyright at generation time. That is deliberate: the core is the one place that
  knows how the ack is unwrapped, so adopting the field is a per-core step, not something
  codegen can do for a venue on its own.
- Left open: every other mechanized client's cores still take no `reply_type`, and their
  streams declare no `reply`. Where a venue's ack carries a value worth typing (deribit's
  `result` list of subscribed channels, say), adopting it is one spec field plus one
  parameter on that core's `subscribe()`; the audit does not require it.