@ably/ai-transport 0.2.0 → 0.3.0

package/dist/core/codec/input-descriptors.d.ts

@@ -0,0 +1,281 @@
+import { DataCodec, FieldFor, HeaderField } from './fields.js';
+import { MessagePayload, WriteOptions } from './types.js';
+/**
+ * Declarative input descriptors — the single source of truth for a codec's
+ * `ai-input` wire mapping, the input-side sibling of {@link import('./output-descriptors.js')}.
+ *
+ * Inputs come in two cardinalities: a single domain input ↔ one wire message
+ * (the `event` construct), and a single domain message ↔ many atomic wire events
+ * (the `batch` construct — the input sibling of the output `stream`). Both are
+ * declared once per codec and consumed by the generic input encode/decode
+ * drivers, so adding an input is one descriptor entry rather than a pair of
+ * hand-synchronised switch arms.
+ *
+ * Authoring is cast-free: the {@link inputBuilder} factory hands the codec a
+ * `{ event, batch }` pair curried on the codec's input union, so every `data` /
+ * `fields` / `parts` callback receives the exact narrowed member. The descriptors
+ * are then erased to a heterogeneous {@link InputDescriptor} via a single
+ * documented cast at each constructor boundary — never in author code.
+ */
+import type * as Ably from 'ably';
+/** Resolve the input union member a `kind` literal selects. */
+export type ResolveInput<U extends {
+    kind: string;
+}, K extends U['kind']> = Extract<U, {
+    kind: K;
+}>;
+/**
+ * The payload an input `event`'s `fields` / `data` operate on. Inputs nest their
+ * domain data under `payload` (the `{ kind, codecMessageId, payload }` envelope of
+ * the well-known input variants), so a single event's spec is authored against the
+ * payload, and the driver wraps/unwraps the envelope. A member with no `payload`
+ * (a `wireOnly` signal) resolves to `never` — such an event declares no `fields` /
+ * `data`, so the payload type is never used.
+ * @template C - The narrowed input member.
+ */
+export type PayloadOf<C> = C extends {
+    payload: infer P;
+} ? P : never;
+/**
+ * Resolve the part union member a `partType` literal selects, mirroring the
+ * output {@link import('./output-descriptors.js').ResolveType} curry one level down.
+ * An exact match wins; a wildcard literal (`data-*`) resolves to the template
+ * member (`data-${string}`).
+ * @template P - The part union.
+ * @template T - The selected `partType` literal (or a `*-*` wildcard).
+ */
+export type ResolvePart<P extends {
+    type: string;
+}, T extends string> = Extract<P, {
+    type: T;
+}> extends never ? T extends `${infer Pre}-*` ? Extract<P, {
+    type: `${Pre}-${string}`;
+}> : never : Extract<P, {
+    type: T;
+}>;
+/**
+ * The encoder-core view the input encode driver receives: discrete publishes
+ * only — inputs never stream. The concrete {@link EncoderCore} satisfies this
+ * structurally.
+ */
+export interface InputEncoderCore {
+    /** Publish a single discrete message. */
+    publishDiscrete(payload: MessagePayload, opts?: WriteOptions): Promise<Ably.PublishResult>;
+    /** Publish multiple discrete messages atomically (the batch fan-out). */
+    publishDiscreteBatch(payloads: MessagePayload[], opts?: WriteOptions): Promise<Ably.PublishResult>;
+}
+/** Per-write context passed to the input encode driver. */
+export interface InputEncodeContext {
+    /** Per-write overrides (the wire codec-message-id is stamped here by the client session). */
+    opts: WriteOptions | undefined;
+}
+/** Per-message context the input decode driver receives for one inbound `ai-input` message. */
+export interface InputDecodeContext {
+    /** The codec `kind` header value (the input descriptor's dispatch key). */
+    codecKind: string;
+    /** The inbound message data. */
+    data: unknown;
+    /** The inbound codec-tier headers. */
+    codecHeaders: Record<string, string>;
+    /** The inbound transport-tier headers (role, codec-message-id, discrete marker). */
+    transportHeaders: Record<string, string>;
+}
+/**
+ * The spec the input `event` construct accepts for member `C`. A member with
+ * no `payload` has nothing for `fields` / `data` to lens onto, so it may only
+ * be declared `wireOnly` or escape-hatched; the driver also rejects a
+ * payload-less encode at runtime.
+ * @template C - The narrowed input member.
+ */
+export type InputEventSpecFor<C> = [PayloadOf<C>] extends [never] ? Pick<InputEventSpec<C>, 'wireOnly'> : InputEventSpec<C>;
+/**
+ * A single-event input descriptor spec, narrowed to input member `C`. `fields`
+ * and `data` operate on the member's {@link PayloadOf payload}; the driver wraps
+ * the `{ kind, codecMessageId, payload }` envelope on decode and unwraps it on
+ * encode. A `wireOnly` event carries no payload (kind only).
+ * @template C - The narrowed input member.
+ */
+export interface InputEventSpec<C> {
+    /**
+     * Declared header fields over the member's payload, written on encode and
+     * read on decode. Each field's key names both the wire header and the
+     * payload property it carries (see {@link FieldFor}). Omit for none.
+     */
+    fields?: readonly FieldFor<PayloadOf<C>>[];
+    /** Wire `data` codec over the payload. Omit when the input carries no data (`data: ''`). */
+    data?: DataCodec<PayloadOf<C>>;
+    /** Wire-only signal: encode stamps only the `kind` header (empty data, no fields); decode yields `[]`. */
+    wireOnly?: boolean;
+}
+/**
+ * A per-part wire mapping inside a {@link BatchSpec}, narrowed to part member `Q`.
+ * `fields` and `data` operate on the selected part; the batch driver fans the
+ * domain message out into one wire event per part and reassembles them in the
+ * reducer (merge by codec-message-id).
+ * @template Q - The narrowed part member.
+ */
+export interface PartSpec<Q> {
+    /**
+     * Declared header fields for this part, written on encode and read on
+     * decode. Each field's key names both the wire header and the part property
+     * it carries (see {@link FieldFor}). Omit for none.
+     */
+    fields?: readonly FieldFor<Q>[];
+    /** Wire `data` codec over the part. Omit when the part carries no data. */
+    data?: DataCodec<Q>;
+}
+/**
+ * The curried part sub-builder a {@link BatchSpec.parts} function receives.
+ * Mirrors the {@link inputBuilder} `event` curry one level down — and the
+ * output builder's wildcard idiom: `p(partType, spec)` narrows `spec` to the
+ * part member the literal selects, and a `-*` literal (e.g. `data-*`) declares
+ * a wildcard family whose dispatch predicate is derived from the literal's
+ * prefix, narrowing `spec` to the template member. Both forms are cast-free in
+ * author code.
+ * @template P - The part union.
+ */
+export type PartBuilder<P extends {
+    type: string;
+}> = <T extends P['type'] | `${string}-*`>(partType: T, spec: PartSpec<ResolvePart<P, T>>) => PartDescriptor;
+/**
+ * Per-message wire headers a {@link BatchSpec.messageHeaders} stamps on every
+ * part of one batch. These carry metadata that belongs to the whole message
+ * rather than an individual part (e.g. the message id as a codec header, the
+ * sender role as a transport header), so the decode side can reconstruct the
+ * shared message envelope from any single part. Both tiers are optional.
+ */
+export interface BatchMessageHeaders {
+    /** Codec-tier headers stamped on every part (e.g. a per-message id). */
+    codecHeaders?: Record<string, string>;
+    /** Transport-tier headers stamped on every part (e.g. the sender role). */
+    transportHeaders?: Record<string, string>;
+}
+/**
+ * The context a {@link BatchSpec.assemble} receives alongside one decoded part:
+ * the inbound header tiers of the wire event the part was decoded from. A batch
+ * fans out into N independent wire events, so each part arrives carrying the
+ * shared per-message headers ({@link BatchMessageHeaders}); `assemble` reads them
+ * to rebuild the message envelope (id, role, …) around its one part.
+ */
+export interface BatchAssembleContext {
+    /** The inbound codec-tier headers (carries the per-message codec headers). */
+    codecHeaders: Record<string, string>;
+    /** The inbound transport-tier headers (carries the per-message transport headers). */
+    transportHeaders: Record<string, string>;
+}
+/**
+ * A multi-part input descriptor spec: one domain message decomposed into many
+ * atomic wire events sharing the input member's `kind` and codec-message-id, each
+ * carrying a `partType` sub-discriminator. The part union `P` is inferred from
+ * `explode`'s return type and threaded into `parts`'s curried `p` and `assemble`,
+ * so all three are cast-free in author code.
+ * @template C - The narrowed input member (the message-bearing input).
+ * @template P - The part union the message explodes into.
+ */
+export interface BatchSpec<C, P extends {
+    type: string;
+}> {
+    /** ENCODE: decompose the domain message into its parts. */
+    explode: (input: C) => readonly P[];
+    /** The `partType` sub-discriminator read off each part on encode. */
+    partTypeOf: (part: P) => string;
+    /** Declarative per-part wire mapping (a sub-table built via the curried `p`). */
+    parts: (p: PartBuilder<P>) => readonly PartDescriptor[];
+    /**
+     * ENCODE: per-message headers stamped on every part (the driver merges them
+     * onto each part's headers, including the ≥1-event fallback). Use for metadata
+     * shared by the whole message — e.g. a message-id codec header and a role
+     * transport header. Omit when parts carry no shared per-message metadata.
+     */
+    messageHeaders?: (input: C) => BatchMessageHeaders;
+    /**
+     * DECODE: shape one decoded wire part into a one-part input (the reducer merges
+     * parts by codec-message-id). `ctx` exposes the inbound header tiers so the
+     * shared per-message metadata stamped by `messageHeaders` can be read back.
+     * The driver stamps only `kind`; the per-message identity rides the
+     * transport header and is recovered through `ctx` when needed.
+     */
+    assemble: (part: P, ctx: BatchAssembleContext) => Omit<C, 'kind'>;
+}
+/** A single-event input descriptor erased to the codec's input union `U`. */
+export interface InputEventDescriptor {
+    /** Discriminator. */
+    construct: 'event';
+    /** The wire `kind` this input dispatches on. */
+    kind: string;
+    /** Declared header fields (read/written against the member's payload). */
+    fields: readonly HeaderField<unknown>[];
+    /** Wire `data` codec, if any. */
+    data?: DataCodec<unknown>;
+    /** Wire-only signal flag. */
+    wireOnly: boolean;
+}
+/** An erased per-part wire mapping within a {@link BatchDescriptor}. */
+export interface PartDescriptor {
+    /** The exact `partType` this part encodes as (the wildcard sentinel for a family). */
+    partType: string;
+    /** Decode-dispatch predicate for a wildcard part; absent for an exact part. */
+    match?: (partType: string) => boolean;
+    /** Declared header fields for this part. */
+    fields: readonly HeaderField<unknown>[];
+    /** Wire `data` codec over the part, if any. */
+    data?: DataCodec<unknown>;
+}
+/** A multi-part (batch) input descriptor erased to the codec's input union `U`. */
+export interface BatchDescriptor<U> {
+    /** Discriminator. */
+    construct: 'batch';
+    /** The wire `kind` every part of this batch shares. */
+    kind: string;
+    /** Decompose the domain input into its parts. */
+    explode: (input: U) => readonly unknown[];
+    /** Read the `partType` sub-discriminator off a part. */
+    partTypeOf: (part: unknown) => string;
+    /** The per-part wire mappings. */
+    parts: readonly PartDescriptor[];
+    /** Build the per-message headers stamped on every part, if any. */
+    messageHeaders?: (input: U) => BatchMessageHeaders;
+    /** Shape one decoded part into a one-part input (sans the driver-stamped `kind`). */
+    assemble: (part: unknown, ctx: BatchAssembleContext) => Omit<U, 'kind'>;
+}
+/** An erased input descriptor — a single event or a multi-part batch. */
+export type InputDescriptor<U> = InputEventDescriptor | BatchDescriptor<U>;
+/**
+ * The direction-scoped input builder `defineCodec` injects into the `input`
+ * config function — `event` and `batch`, both curried on the codec's input union
+ * so author entries narrow cast-free.
+ * @template U - The codec's input union.
+ */
+export interface InputBuilder<U extends {
+    kind: string;
+}> {
+    /**
+     * Declare a single-event input. Narrows `spec` to the member `kind` selects;
+     * `fields` / `data` operate on that member's payload.
+     * @param kind - The input member's `kind` literal (the wire dispatch key).
+     * @param spec - The narrowed input spec. Omit for a bare-`kind` input.
+     * @returns An erased {@link InputDescriptor}.
+     */
+    event: <K extends U['kind']>(kind: K, spec?: InputEventSpecFor<ResolveInput<U, K>>) => InputDescriptor<U>;
+    /**
+     * Declare a multi-part (batch) input. Narrows the spec to the message-bearing
+     * member `kind` selects; `explode`'s return type fixes the part union `P`, which
+     * threads into `parts`'s curried `p` and `assemble` cast-free.
+     * @param kind - The input member's `kind` literal (the shared wire dispatch key).
+     * @param spec - The narrowed batch spec.
+     * @returns An erased {@link InputDescriptor}.
+     */
+    batch: <K extends U['kind'], P extends {
+        type: string;
+    }>(kind: K, spec: BatchSpec<ResolveInput<U, K>, P>) => InputDescriptor<U>;
+}
+/**
+ * Build the curried `{ event, batch }` input builder for a codec's input union.
+ * `defineCodec` calls this once and hands the result to the `input` config
+ * function; mirrors the output side's {@link import('./output-descriptors.js').outputBuilder}.
+ * @template U - The codec's input union.
+ * @returns The direction-scoped {@link InputBuilder}.
+ */
+export declare const inputBuilder: <U extends {
+    kind: string;
+}>() => InputBuilder<U>;

package/dist/core/codec/output-descriptor-decoder.d.ts

@@ -0,0 +1,29 @@
+import { OutputDescriptor } from './output-descriptors.js';
+import { StreamTrackerState } from './types.js';
+/** Decodes wire messages of union `U` from a descriptor set. */
+export interface OutputDescriptorDecoder<U> {
+    /** Rebuild the chunk(s) emitted when a stream starts. */
+    buildStart(tracker: StreamTrackerState): U[];
+    /** Rebuild the chunk(s) for a stream delta. */
+    buildDelta(tracker: StreamTrackerState, delta: string): U[];
+    /** Rebuild the chunk(s) emitted when a stream completes. */
+    buildEnd(tracker: StreamTrackerState, closingCodecHeaders: Record<string, string>): U[];
+    /**
+     * Decode a discrete message by its codec `kind`.
+     * @param codecKind - The codec `kind` header value (the dispatch key).
+     * @param codecHeaders - The inbound codec-tier headers.
+     * @param transportHeaders - The inbound transport-tier headers.
+     * @param data - The inbound message data.
+     * @returns The decoded events (empty if no descriptor matches).
+     */
+    decodeDiscrete(codecKind: string, codecHeaders: Record<string, string>, transportHeaders: Record<string, string>, data: unknown): U[];
+}
+/**
+ * Build an output decode driver for a descriptor set.
+ * @template U - The codec's event union.
+ * @param descriptors - The descriptor set (events + streamed families).
+ * @returns An {@link OutputDescriptorDecoder} that reconstructs events from the wire.
+ */
+export declare const createOutputDescriptorDecoder: <U extends {
+    type: string;
+}>(descriptors: readonly OutputDescriptor<U>[]) => OutputDescriptorDecoder<U>;

package/dist/core/codec/output-descriptor-encoder.d.ts

@@ -0,0 +1,31 @@
+import { EncoderCore } from './encoder.js';
+import { OutputDescriptor } from './output-descriptors.js';
+import { WriteOptions } from './types.js';
+/** Per-write output encode context threaded from the encoder. */
+export interface OutputEncodeContext {
+    /** The encoder's configured fallback message id, if any. */
+    messageId: string | undefined;
+    /** Per-write overrides. */
+    opts: WriteOptions | undefined;
+}
+/** Encodes events of union `U` to channel operations via a descriptor set. */
+export interface OutputDescriptorEncoder<U> {
+    /**
+     * Encode one event through its descriptor.
+     * @param chunk - The event to encode.
+     * @param core - The encoder core to publish/stream through.
+     * @param ctx - Per-write context (fallback message id, write options).
+     * @returns A promise resolving when the publish/stream operation completes.
+     */
+    encode(chunk: U, core: EncoderCore, ctx: OutputEncodeContext): Promise<void>;
+}
+/**
+ * Build an output encode driver for a descriptor set bound to a wire message name.
+ * @template U - The codec's event union.
+ * @param descriptors - The descriptor set (events + streamed families).
+ * @param wireName - The Ably message name for this direction (`ai-output` / `ai-input`).
+ * @returns An {@link OutputDescriptorEncoder} routing each event through its descriptor.
+ */
+export declare const createOutputDescriptorEncoder: <U extends {
+    type: string;
+}>(descriptors: readonly OutputDescriptor<U>[], wireName: string) => OutputDescriptorEncoder<U>;

package/dist/core/codec/output-descriptors.d.ts

@@ -0,0 +1,237 @@
+import { DataCodec, FieldFor, HeaderField } from './fields.js';
+import { MessagePayload, StreamPayload, WriteOptions } from './types.js';
+/**
+ * Declarative output descriptors — the single source of truth for a codec's
+ * `ai-output` wire mapping, the output-side sibling of {@link import('./input-descriptors.js')}.
+ *
+ * A codec declares each ordinary output event once, as a descriptor built on the
+ * typed header-field bindings ({@link HeaderField}). The generic encode/decode
+ * drivers consume the descriptor set, so adding an ordinary event is one
+ * descriptor entry instead of three hand-synchronised switch arms (encoder,
+ * decoder, stream reconstruction).
+ *
+ * Authoring is cast-free: the {@link outputBuilder} factory hands the codec an
+ * `{ event, stream }` pair curried on the codec's output union, so every `data` /
+ * `encode` / `decode` callback receives the exact narrowed member. The descriptors
+ * are then erased to a heterogeneous {@link OutputDescriptor} via a single
+ * documented cast at each constructor boundary — never in author code.
+ */
+import type * as Ably from 'ably';
+/** The string-valued keys of `C` — the only keys `idField`/`deltaField` may name. */
+export type StringKeyOf<C> = {
+    [K in keyof C]-?: C[K] extends string ? K : never;
+}[keyof C];
+/**
+ * Resolve the union member a descriptor `type` literal selects. An exact match
+ * wins; a wildcard literal (`'data-*'`) resolves to the template member
+ * (`data-${string}`), so wildcard descriptors still narrow to the real member.
+ */
+export type ResolveType<U extends {
+    type: string;
+}, T extends string> = Extract<U, {
+    type: T;
+}> extends never ? T extends `${infer P}-*` ? Extract<U, {
+    type: `${P}-${string}`;
+}> : never : Extract<U, {
+    type: T;
+}>;
+/**
+ * The narrowed view of the encoder core that escape-hatch `encode` functions
+ * receive — only the publish/stream operations a hatch legitimately needs. The
+ * full internal `EncoderCore` satisfies this structurally.
+ */
+export interface EscapeHatchCore {
+    /** Publish a single discrete message. */
+    publishDiscrete(payload: MessagePayload, opts?: WriteOptions): Promise<Ably.PublishResult>;
+    /** Start a streamed message. */
+    startStream(streamId: string, payload: StreamPayload, opts?: WriteOptions): Promise<void>;
+    /** Append a fragment to an in-flight stream (fire-and-forget). */
+    appendStream(streamId: string, data: string): void;
+    /** Close a streamed message. */
+    closeStream(streamId: string, payload: StreamPayload): Promise<void>;
+    /** Cancel all in-progress streams. */
+    cancelAllStreams(opts?: WriteOptions): Promise<void>;
+}
+/**
+ * Builds a codec headers record from a chunk through the descriptor's declared
+ * fields, stamping the dispatch `type` plus each field read off `chunk`. An
+ * optional `keys` subset restricts which declared fields are written; the keys
+ * are checked against the chunk so the imperative path can't drift.
+ * @template C - The narrowed chunk member.
+ */
+export type HeaderBuilder<C> = <K extends keyof C & string>(chunk: C, keys?: readonly K[]) => Record<string, string>;
+/**
+ * Context passed to an escape-hatch `encode` function.
+ * @template C - The narrowed chunk member.
+ */
+export interface OutputEncodeHatchContext<C> {
+    /** Header builder bound to the descriptor's declared fields. */
+    h: HeaderBuilder<C>;
+    /** The wire message name for this direction (`ai-output` / `ai-input`). */
+    name: string;
+    /** The encoder's configured fallback message id, if any. */
+    messageId: string | undefined;
+    /** Per-write overrides to thread into the hatch's publish/cancel calls. */
+    opts: WriteOptions | undefined;
+}
+/** Context passed to a discrete escape-hatch `decode` function. */
+export interface OutputDecodeContext {
+    /** The codec `kind` header value the message dispatched on (mirrors the input context's `codecKind`). */
+    codecKind: string;
+    /** The inbound codec-tier headers. */
+    codecHeaders: Record<string, string>;
+    /** The inbound transport-tier headers. */
+    transportHeaders: Record<string, string>;
+    /** The inbound message data. */
+    data: unknown;
+}
+/** Context passed to a stream descriptor's `decodeEnd` escape hatch. */
+export interface OutputStreamEndContext {
+    /** The stream identifier (e.g. chunk id, toolCallId). */
+    streamId: string;
+    /** The full accumulated stream text. */
+    accumulated: string;
+    /** The stream's persistent (start) codec headers. */
+    codecHeaders: Record<string, string>;
+    /** The codec headers carried on close (may differ from the start headers). */
+    closingCodecHeaders: Record<string, string>;
+}
+/**
+ * A discrete (non-streaming) output event descriptor spec, narrowed to chunk member `C`.
+ * @template C - The narrowed chunk member.
+ */
+export interface OutputEventSpec<C> {
+    /**
+     * Declared header fields, written on encode and read on decode. Each field's
+     * key names both the wire header and the chunk property it carries (see
+     * {@link FieldFor}). Omit for a header-less event.
+     */
+    fields?: readonly FieldFor<C>[];
+    /** Wire `data` codec. Omit when the event carries no data (`data: ''`). */
+    data?: DataCodec<C>;
+    /** Whether the publish is ephemeral (not persisted). Default false. */
+    ephemeral?: (chunk: C) => boolean;
+    /** Escape-hatch encode — overrides the default discrete publish. */
+    encode?: (chunk: C, core: EscapeHatchCore, ctx: OutputEncodeHatchContext<C>) => Promise<void>;
+}
+/**
+ * A streamed-family descriptor spec. `start`/`delta`/`end` are the domain chunk
+ * `type` literals; the family id (the {@link OutputBuilder.stream} first argument)
+ * is the wire `kind` header all three phases stamp.
+ * @template U - The codec's event union.
+ * @template S - The start chunk `type` literal.
+ * @template D - The delta chunk `type` literal.
+ * @template E - The end chunk `type` literal.
+ */
+export interface OutputStreamSpec<U extends {
+    type: string;
+}, S extends U['type'], D extends U['type'], E extends U['type']> {
+    /** The start chunk `type` literal. */
+    start: S;
+    /** The delta chunk `type` literal. */
+    delta: D;
+    /** The end chunk `type` literal. */
+    end: E;
+    /** The string-valued chunk key carrying the stream id (e.g. `id`, `toolCallId`). */
+    idField: StringKeyOf<ResolveType<U, S>> & StringKeyOf<ResolveType<U, D>> & StringKeyOf<ResolveType<U, E>>;
+    /** The string-valued delta chunk key carrying the appended fragment. */
+    deltaField: StringKeyOf<ResolveType<U, D>>;
+    /**
+     * Declared header fields written/read on the start and end chunks. Each
+     * field's key names both the wire header and the chunk property (see
+     * {@link FieldFor}); a field may bind a property carried by either phase.
+     */
+    fields: readonly (FieldFor<ResolveType<U, S>> | FieldFor<ResolveType<U, E>>)[];
+    /** Escape-hatch override for the stream-close step only (e.g. close-or-discrete fallback). */
+    onEnd?: (chunk: ResolveType<U, E>, core: EscapeHatchCore, ctx: OutputEncodeHatchContext<ResolveType<U, E>>) => Promise<void>;
+    /** Escape-hatch override for the end-chunk rebuild (e.g. input from accumulated text). */
+    decodeEnd?: (ctx: OutputStreamEndContext) => ResolveType<U, E>[];
+    /**
+     * Escape-hatch decode for when the family arrives as a discrete (non-streamed)
+     * message — the wire `kind` equals the family id but the wire wasn't streamed
+     * (e.g. history compaction). Reconstructs the start/end chunk pair.
+     */
+    decodeDiscrete?: (ctx: OutputDecodeContext) => ResolveType<U, S | E>[];
+}
+/** A discrete output event descriptor erased to the codec's union `U`. */
+export interface OutputEventDescriptor<U> {
+    /** Discriminator — the construct this descriptor was built with. */
+    construct: 'event';
+    /** The dispatch `type` literal (or wildcard sentinel), stamped as the wire `kind` header. */
+    type: string;
+    /** Declared header fields. */
+    fields: readonly HeaderField<unknown>[];
+    /** Wire `data` codec, if any. */
+    data?: DataCodec<U>;
+    /** Ephemeral predicate, if any. */
+    ephemeral?: (chunk: U) => boolean;
+    /** Wildcard dispatch predicate (both directions), derived by the builder from a `-*` type literal. */
+    match?: (type: string) => boolean;
+    /** Escape-hatch encode, if any. */
+    encode?: (chunk: U, core: EscapeHatchCore, ctx: OutputEncodeHatchContext<U>) => Promise<void>;
+}
+/** A streamed-family descriptor erased to the codec's union `U`. */
+export interface OutputStreamDescriptor<U> {
+    /** Discriminator — the construct this descriptor was built with. */
+    construct: 'stream';
+    /** The stream family id, stamped as the wire `kind` header on every phase. */
+    kind: string;
+    /** The start chunk `type`. */
+    start: string;
+    /** The delta chunk `type`. */
+    delta: string;
+    /** The end chunk `type`. */
+    end: string;
+    /** The chunk key carrying the stream id. */
+    idField: string;
+    /** The delta chunk key carrying the appended fragment. */
+    deltaField: string;
+    /** Declared header fields. */
+    fields: readonly HeaderField<unknown>[];
+    /** Escape-hatch close override, if any. */
+    onEnd?: (chunk: U, core: EscapeHatchCore, ctx: OutputEncodeHatchContext<U>) => Promise<void>;
+    /** Escape-hatch end-rebuild override, if any. */
+    decodeEnd?: (ctx: OutputStreamEndContext) => U[];
+    /** Escape-hatch non-streamed decode, if any. */
+    decodeDiscrete?: (ctx: OutputDecodeContext) => U[];
+}
+/** An erased output descriptor — a discrete event or a streamed family. */
+export type OutputDescriptor<U> = OutputEventDescriptor<U> | OutputStreamDescriptor<U>;
+/**
+ * The direction-scoped output builder `defineCodec` injects into the `output`
+ * config function — `event` (single discrete) and `stream` (streamed family),
+ * both curried on the codec's output union so author entries narrow cast-free.
+ * @template U - The codec's output union.
+ */
+export interface OutputBuilder<U extends {
+    type: string;
+}> {
+    /**
+     * Declare a single discrete output event. Curried on the output union; narrows
+     * `spec` to the member the `type` literal selects. The `type` literal is stamped
+     * as the wire `kind` dispatch header.
+     * @param type - The event's `type` literal (or a `*-*` wildcard); stamped as the wire `kind` header.
+     * @param spec - The narrowed output event spec. Omit for a header-less event with no data.
+     * @returns An erased {@link OutputDescriptor}.
+     */
+    event: <T extends U['type'] | `${string}-*`>(type: T, spec?: OutputEventSpec<ResolveType<U, T>>) => OutputDescriptor<U>;
+    /**
+     * Declare a streamed output family (start / delta / end). `start`/`delta`/`end`
+     * are domain chunk `type` literals; the first argument is the family id, stamped
+     * as the wire `kind` dispatch header on every phase.
+     * @param kind - The stream family id, stamped as the wire `kind` header on every phase.
+     * @param spec - The narrowed stream spec.
+     * @returns An erased {@link OutputDescriptor}.
+     */
+    stream: <S extends U['type'], D extends U['type'], E extends U['type']>(kind: string, spec: OutputStreamSpec<U, S, D, E>) => OutputDescriptor<U>;
+}
+/**
+ * Build the curried `{ event, stream }` output builder for a codec's output union.
+ * `defineCodec` calls this once and hands the result to the `output` config
+ * function; mirrors the input side's {@link import('./input-descriptors.js').inputBuilder}.
+ * @template U - The codec's output union.
+ * @returns The direction-scoped {@link OutputBuilder}.
+ */
+export declare const outputBuilder: <U extends {
+    type: string;
+}>() => OutputBuilder<U>;