@ably/ai-transport 0.1.0 → 0.3.0

package/dist/core/codec/fields.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Typed header-field bindings.
+ *
+ * A {@link HeaderField} binds a codec header key to its value type **once**,
+ * and exposes a symmetric {@link HeaderField.read | read} / {@link
+ * HeaderField.write | write} pair over a raw `Record<string, string>` headers
+ * record. Because a single binding drives both the encode and decode side, the
+ * header key and its value type stay in lockstep across directions — a key
+ * cannot be misspelled on one side and silently read as absent on the other.
+ *
+ * This is deliberately **not** a schema library: it is a thin bidirectional
+ * string (de)serializer over the headers record. The SDK ships no hard runtime
+ * dependencies, and a schema approach would force re-declaring peer-SDK-owned
+ * types. The four constructors cover every header value shape the codecs use:
+ *
+ * - {@link strField} — string values, optional default.
+ * - {@link boolField} — `"true"`/`"false"` booleans, optional default.
+ * - {@link jsonField} — JSON-serialized structured values.
+ * - {@link enumField} — string values validated against an allow-list with a
+ *   fallback (e.g. a finish reason).
+ *
+ * Passing a default to `strField`/`boolField` makes the field **total**: its
+ * `read` returns `V` rather than `V | undefined`, for required headers that
+ * should always decode to a concrete value.
+ */
+/**
+ * A header key bound to its value type, with symmetric read/write over a raw
+ * headers record. Created via {@link strField}, {@link boolField}, {@link
+ * jsonField}, or {@link enumField}.
+ *
+ * The `key` plays a dual role in descriptor `fields` tables: it is the wire
+ * header key AND the property name the drivers read off the source object on
+ * encode and write back into the rebuilt object on decode. {@link FieldFor}
+ * enforces this — a declared field's key must name a real property of the
+ * member it lenses onto.
+ * @template V - The decoded value type this field reads and writes.
+ * @template K - The header key literal (preserved so {@link FieldFor} can match it against the member's property names).
+ */
+export interface HeaderField<V, K extends string = string> {
+    /** The raw header key this field reads from and writes to — also the source/rebuilt property name in descriptor tables. */
+    readonly key: K;
+    /**
+     * Read and decode this field's value from a headers record.
+     * @param headers - The raw codec headers record to read from.
+     * @returns The decoded value. For defaulted/validated fields this is total
+     * (the default/fallback is returned when the header is absent or invalid);
+     * otherwise `undefined` when the header is absent.
+     */
+    read(headers: Record<string, string>): V;
+    /**
+     * Encode and write this field's value into a headers record, mutating it in
+     * place. `undefined` (and `null`, for JSON values), and values whose runtime
+     * type doesn't match the field, are skipped — the key is left unset rather
+     * than written. The parameter is `unknown` (not `V`) so a field keeps `V` in
+     * a single covariant position (`read`); this lets heterogeneous fields share a
+     * `HeaderField<unknown>[]` array, which the descriptor drivers rely on. At a
+     * typed call site the caller still passes a `V`.
+     * @param headers - The headers record to mutate.
+     * @param value - The value to encode and set.
+     */
+    write(headers: Record<string, string>, value: unknown): void;
+}
+/**
+ * Symmetric codec for a descriptor's wire `data`. Many wire payloads are object
+ * envelopes a decode reads several chunk props out of (e.g. `{ errorText, input }`),
+ * so a single field can't model them. `encode` produces the wire data from the
+ * chunk; `decode` returns the chunk props the envelope contributes, merged into
+ * the rebuilt chunk by the driver.
+ * @template C - The narrowed chunk member.
+ */
+export interface DataCodec<C> {
+    /** Produce the wire `data` from the chunk. */
+    encode: (chunk: C) => unknown;
+    /**
+     * Extract the chunk props this envelope contributes from the wire `data`.
+     * Undefined-valued props are stripped when the driver rebuilds the object —
+     * every rebuild seam (output chunk, input payload, batch part) applies the
+     * same rule, since absent and undefined are indistinguishable on the wire.
+     */
+    decode: (data: unknown) => Partial<C>;
+}
+/**
+ * The header fields a descriptor may declare against member `C`. For each
+ * string-keyed property of `C`, a field is acceptable when its key IS that
+ * property name and its value type can hold the property. A mistyped key or a
+ * wrong-typed field (e.g. a `boolField` on a string property) is a compile
+ * error instead of a silently absent header.
+ * @template C - The member (chunk, payload, or part) the fields lens onto.
+ */
+export type FieldFor<C> = {
+    [K in keyof C & string]-?: HeaderField<C[K] | undefined, K>;
+}[keyof C & string];
+/**
+ * Bind a string-valued header field.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `string | undefined` (absent → `undefined`).
+ */
+export declare function strField<K extends string>(key: K): HeaderField<string | undefined, K>;
+/**
+ * Bind a string-valued header field with a default, making it total.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param fallback - Value returned by `read` when the header is absent.
+ * @returns A field whose `read` yields `string` (absent → `fallback`).
+ */
+export declare function strField<K extends string>(key: K, fallback: string): HeaderField<string, K>;
+/**
+ * Bind a boolean-valued header field, serialized as `"true"`/`"false"`.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `boolean | undefined` (absent → `undefined`).
+ */
+export declare function boolField<K extends string>(key: K): HeaderField<boolean | undefined, K>;
+/**
+ * Bind a boolean-valued header field with a default, making it total.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param fallback - Value returned by `read` when the header is absent.
+ * @returns A field whose `read` yields `boolean` (absent → `fallback`).
+ */
+export declare function boolField<K extends string>(key: K, fallback: boolean): HeaderField<boolean, K>;
+/**
+ * Bind a JSON-serialized header field. The value is written with
+ * `JSON.stringify` and read back with `JSON.parse`; malformed JSON reads as
+ * `undefined`. The decoded shape is a trust boundary — the caller asserts it
+ * via the `V` type parameter.
+ * @template V - The expected decoded shape of the JSON value.
+ * @template K - The header key literal. Inferred when `V` is omitted; pass it explicitly alongside `V` when the field participates in a typed descriptor `fields` table.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `V | undefined` (absent or malformed → `undefined`).
+ */
+export declare const jsonField: <V, K extends string = string>(key: K) => HeaderField<V | undefined, K>;
+/**
+ * Bind a string-valued header field validated against a fixed allow-list,
+ * falling back to a given value when the header is absent or unrecognized. Use
+ * for headers with a small closed set of valid values (e.g. a finish reason).
+ * @template T - The union of allowed string literals, inferred from `allowed`.
+ * @template K - The header key literal, inferred from `key`.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param allowed - The exhaustive list of valid values.
+ * @param fallback - Value returned by `read` when the header is absent or not in `allowed`.
+ * @returns A total field whose `read` yields one of the allowed literals.
+ */
+export declare const enumField: <const T extends string, K extends string>(key: K, allowed: readonly T[], fallback: NoInfer<T>) => HeaderField<T, K>;

package/dist/core/codec/index.d.ts

@@ -1,8 +1,14 @@
-export { eventOutput } from './decoder.js';
-export type { ChannelWriter, Codec, DecoderOutput, DiscreteEncoder, EncoderOptions, Extras, MessageAccumulator, MessagePayload, StreamDecoder, StreamEncoder, StreamPayload, StreamTrackerState, WriteOptions, } from './types.js';
+export type { ChannelWriter, Codec, CodecEvent, CodecInputEvent, CodecMessage, CodecOutputEvent, DecodedMessage, Decoder, Encoder, EncoderOptions, Extras, MessagePayload, Reducer, ReducerMeta, Regenerate, StreamPayload, StreamTrackerState, ToolApprovalResponse, ToolResult, ToolResultError, UserMessage, WriteOptions, } from './types.js';
 export type { EncoderCore, EncoderCoreOptions } from './encoder.js';
 export { createEncoderCore } from './encoder.js';
 export type { DecoderCore, DecoderCoreHooks, DecoderCoreOptions } from './decoder.js';
 export { createDecoderCore } from './decoder.js';
 export type { LifecycleTracker, PhaseConfig } from './lifecycle-tracker.js';
 export { createLifecycleTracker } from './lifecycle-tracker.js';
+export type { DataCodec, FieldFor, HeaderField } from './fields.js';
+export { boolField, enumField, jsonField, strField } from './fields.js';
+export type { WellKnownInputFactories } from './well-known-inputs.js';
+export type { EscapeHatchCore, HeaderBuilder, OutputDecodeContext, OutputDescriptor, OutputEncodeHatchContext, OutputEventSpec, OutputStreamEndContext, OutputStreamSpec, } from './output-descriptors.js';
+export type { BatchAssembleContext, BatchMessageHeaders, BatchSpec, InputDescriptor, InputEventSpec, PartBuilder, PartSpec, } from './input-descriptors.js';
+export type { CodecReducer, DefineCodecConfig, DefinedCodec, InputBuilder, LifecycleDiscreteContext, LifecyclePolicy, OutputBuilder, } from './define-codec.js';
+export { defineCodec } from './define-codec.js';

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

@@ -0,0 +1,19 @@
+import { InputDecodeContext, InputDescriptor } from './input-descriptors.js';
+/** Decodes inbound `ai-input` messages of union `U` from an input descriptor set. */
+export interface InputDescriptorDecoder<U> {
+    /**
+     * Rebuild zero or more inputs from one inbound `ai-input` message.
+     * @param ctx - The inbound message context (codec kind, data, header tiers).
+     * @returns The decoded inputs (empty when no descriptor matches or the input is wire-only).
+     */
+    decode(ctx: InputDecodeContext): U[];
+}
+/**
+ * Build an input decode driver for an input descriptor set.
+ * @template U - The codec's input union.
+ * @param descriptors - The input descriptor set (events + batches).
+ * @returns An {@link InputDescriptorDecoder} that reconstructs inputs from the wire.
+ */
+export declare const createInputDescriptorDecoder: <U extends {
+    kind: string;
+}>(descriptors: readonly InputDescriptor<U>[]) => InputDescriptorDecoder<U>;

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

@@ -0,0 +1,22 @@
+import { InputDescriptor, InputEncodeContext, InputEncoderCore } from './input-descriptors.js';
+/** Encodes inputs of union `U` to channel operations via an input descriptor set. */
+export interface InputDescriptorEncoder<U> {
+    /**
+     * Encode one input through its descriptor.
+     * @param input - The input to encode.
+     * @param core - The input encoder core to publish through.
+     * @param ctx - Per-write context (write options, carrying the codec-message-id).
+     * @returns A promise resolving when the publish operation completes.
+     */
+    encode(input: U, core: InputEncoderCore, ctx: InputEncodeContext): Promise<void>;
+}
+/**
+ * Build an input encode driver for an input descriptor set bound to a wire name.
+ * @template U - The codec's input union.
+ * @param descriptors - The input descriptor set (events + batches).
+ * @param wireName - The Ably message name for the input direction (`ai-input`).
+ * @returns An {@link InputDescriptorEncoder} routing each input through its descriptor.
+ */
+export declare const createInputDescriptorEncoder: <U extends {
+    kind: string;
+}>(descriptors: readonly InputDescriptor<U>[], wireName: string) => InputDescriptorEncoder<U>;

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/lifecycle-tracker.d.ts

@@ -1,7 +1,7 @@
 /**
  * Generic lifecycle tracker for codec decoders.
  *
- * Manages per-scope (typically per-turn) tracking of lifecycle phases that
+ * Manages per-scope (typically per-run) tracking of lifecycle phases that
  * must be emitted before content events. When a phase has not been emitted
  * (e.g. mid-stream join), the tracker synthesizes the missing events using
  * codec-provided build functions.
@@ -30,15 +30,16 @@ export interface PhaseConfig<TEvent> {
  * Per-scope lifecycle tracker that ensures required phases are emitted
  * before content events, synthesizing missing ones for mid-stream joins.
  *
- * Scoped by an arbitrary string key (typically a turn ID). Each scope
+ * Scoped by an arbitrary string key (typically a run ID). Each scope
  * tracks independently which phases have been emitted.
  */
 export interface LifecycleTracker<TEvent> {
     /**
      * Ensure all configured phases have been emitted for the given scope.
-     * Returns synthetic events for any phases not yet marked as emitted,
-     * then marks them. Returns an empty array if all phases are current.
-     * @param scopeId - The scope to check (e.g. turn ID).
+     * Synthesizes and returns the events for any phases not yet marked as
+     * emitted, marking each as emitted so it is not synthesized again.
+     * Returns an empty array if all phases are already emitted.
+     * @param scopeId - The scope to check (e.g. run ID).
      * @param context - Key-value pairs passed through to phase build functions.
      * @returns Synthetic events for missing phases, in configuration order.
      */
@@ -46,7 +47,7 @@ export interface LifecycleTracker<TEvent> {
     /**
      * Mark a phase as emitted from the wire (not synthetic). Call this
      * when the real event arrives so the tracker does not re-synthesize it.
-     * @param scopeId - The scope (e.g. turn ID).
+     * @param scopeId - The scope (e.g. run ID).
      * @param phaseKey - The phase key to mark.
      */
     markEmitted(scopeId: string, phaseKey: string): void;
@@ -54,13 +55,13 @@ export interface LifecycleTracker<TEvent> {
      * Reset a phase so it will be re-synthesized on the next
      * {@link ensurePhases} call. Used for repeating phases (e.g. "start-step"
      * resets after "finish-step").
-     * @param scopeId - The scope (e.g. turn ID).
+     * @param scopeId - The scope (e.g. run ID).
      * @param phaseKey - The phase key to reset.
      */
     resetPhase(scopeId: string, phaseKey: string): void;
     /**
-     * Remove all tracking state for a scope. Call on turn completion
-     * (finish, abort) to free memory.
+     * Remove all tracking state for a scope. Call on run completion
+     * (finish, cancel) to free memory.
      * @param scopeId - The scope to clear.
      */
     clearScope(scopeId: string): void;

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>;