@ably/ai-transport 0.2.0 → 0.3.0

package/src/core/codec/field-bag.ts

@@ -0,0 +1,142 @@
+/**
+ * Shared header-field bag helpers.
+ *
+ * The wire dispatch discriminator (`kind`) plus the symmetric field↔headers
+ * write and read used by the descriptor drivers. Centralised so encode and
+ * decode operate on the same record shape and the dispatch key has one home —
+ * and so the input drivers can reuse the same primitives as the output drivers.
+ */
+
+import type { HeaderField } from './fields.js';
+import type { OutputDescriptor, OutputEventDescriptor } from './output-descriptors.js';
+
+/** The codec header carrying the SDK-controlled dispatch kind / stream family id. */
+export const KIND_HEADER = 'kind';
+
+/** The sentinel suffix marking a descriptor literal as a wildcard family. */
+const WILDCARD_SUFFIX = '-*';
+
+/**
+ * Derive a wildcard dispatch predicate from a descriptor literal: a literal
+ * ending in `-*` matches any value sharing its prefix, so the literal and its
+ * predicate can never disagree. Returns `undefined` for an exact literal.
+ * Shared by the output event builder and the input part builder so the `-*`
+ * sentinel rule lives in one place, next to the {@link partFor} that consumes it.
+ * @param literal - The declared descriptor literal (`type` / `partType`).
+ * @returns A prefix-match predicate for a wildcard literal, else `undefined`.
+ */
+export const wildcardMatcher = (literal: string): ((value: string) => boolean) | undefined =>
+  literal.endsWith(WILDCARD_SUFFIX) ? (value: string): boolean => value.startsWith(literal.slice(0, -1)) : undefined;
+
+/**
+ * The codec header carrying a batch part's sub-discriminator. A batch stamps it
+ * on every exploded part on encode; the decoder reads it back to resolve the
+ * matching part descriptor. Centralised so the key has one home across the
+ * input encode and decode drivers and cannot drift between them.
+ */
+export const PART_TYPE_HEADER = 'partType';
+
+/**
+ * Read the value at a declared field key off a source object.
+ * @param source - The object to index (a chunk, or a lensed sub-object such as a payload).
+ * @param key - The declared field key.
+ * @returns The value at `key`, typed `unknown`.
+ */
+// CAST: a descriptor indexes a source object's props by a declared key. The
+// source's indexed type isn't statically known here, but a descriptor only ever
+// runs against the member it matches, so the value has the field's type at runtime.
+export const prop = (source: object, key: string): unknown => (source as Record<string, unknown>)[key];
+
+/**
+ * Build a codec-headers record from a source object through declared fields,
+ * seeded with the dispatch `kind`. Each field writes the value at its key on
+ * `source`; an optional `keys` subset restricts which fields are written.
+ * @param fields - The declared header fields.
+ * @param kindValue - The dispatch kind / stream family id to seed under {@link KIND_HEADER}.
+ * @param source - The object to read field values from (a chunk, or a lensed payload).
+ * @param keys - Optional subset of field keys to write; omit to write all.
+ * @returns The codec-headers record.
+ */
+export const writeFields = (
+  fields: readonly HeaderField<unknown>[],
+  kindValue: string,
+  source: object,
+  keys?: readonly string[],
+): Record<string, string> => {
+  const rec: Record<string, string> = { [KIND_HEADER]: kindValue };
+  for (const field of fields) {
+    if (keys && !keys.includes(field.key)) continue;
+    field.write(rec, prop(source, field.key));
+  }
+  return rec;
+};
+
+/**
+ * Read declared fields out of a codec-headers record into a bag keyed by field key.
+ * A field that reads `undefined` (absent, with no default) contributes no key — the
+ * bag carries only the values that are actually present.
+ * @param fields - The declared header fields.
+ * @param headers - The inbound codec-tier headers.
+ * @returns A bag of the present field values, keyed by each field's key.
+ */
+/** The structural slice of a part descriptor {@link partFor} dispatches on. */
+interface PartDispatch {
+  /** The exact `partType` literal, or the `-*` wildcard literal for a family. */
+  partType: string;
+  /** Wildcard dispatch predicate; absent for an exact part. */
+  match?: (partType: string) => boolean;
+}
+
+/**
+ * Resolve the part descriptor for a `partType`: an exact non-wildcard match,
+ * else a wildcard whose derived predicate accepts it. Wildcards are excluded
+ * from the exact pass — only their predicate may route to them. Shared by the
+ * input encode and decode drivers.
+ * @param parts - The batch's part descriptor sub-table.
+ * @param partType - The `partType` to resolve (from `partTypeOf` on encode, the wire header on decode).
+ * @returns The matching part descriptor, or undefined when none matches.
+ */
+export const partFor = <P extends PartDispatch>(parts: readonly P[], partType: string): P | undefined =>
+  parts.find((part) => !part.match && part.partType === partType) ?? parts.find((part) => part.match?.(partType));
+
+/** An output descriptor set's event descriptors, split for dispatch. */
+export interface OutputEventDispatch<U> {
+  /** Exact (non-wildcard) event descriptors, keyed by `type`. */
+  discreteByType: Map<string, OutputEventDescriptor<U>>;
+  /** Wildcard event descriptors, dispatched by their `match` predicate. */
+  wildcards: OutputEventDescriptor<U>[];
+}
+
+/**
+ * Partition an output descriptor set's `event` descriptors into an exact-type
+ * map and a wildcard list. Stream descriptors are skipped — each driver indexes
+ * those by its own key (phase on encode, kind on decode). Shared by the output
+ * encode and decode drivers so the exact-vs-wildcard split has one home.
+ * @template U - The codec's event union.
+ * @param descriptors - The full descriptor set (events + streamed families).
+ * @returns The event descriptors split into {@link OutputEventDispatch}.
+ */
+export const partitionOutputEvents = <U extends { type: string }>(
+  descriptors: readonly OutputDescriptor<U>[],
+): OutputEventDispatch<U> => {
+  const discreteByType = new Map<string, OutputEventDescriptor<U>>();
+  const wildcards: OutputEventDescriptor<U>[] = [];
+  for (const descriptor of descriptors) {
+    if (descriptor.construct !== 'event') continue;
+    if (descriptor.match) wildcards.push(descriptor);
+    else discreteByType.set(descriptor.type, descriptor);
+  }
+  return { discreteByType, wildcards };
+};
+
+export const readFields = (
+  fields: readonly HeaderField<unknown>[],
+  headers: Record<string, string>,
+): Record<string, unknown> => {
+  const bag: Record<string, unknown> = {};
+  for (const field of fields) {
+    const value = field.read(headers);
+    if (value !== undefined) bag[field.key] = value;
+  }
+  return bag;
+};

package/src/core/codec/fields.ts

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ */
+
+import { parseBool, parseJson } from '../../utils.js';
+
+/**
+ * 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 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 function strField<K extends string>(key: K, fallback: string): HeaderField<string, K>;
+export function strField<K extends string>(key: K, fallback?: string): HeaderField<string | undefined, K> {
+  return {
+    key,
+    read: (headers) => headers[key] ?? fallback,
+    write: (headers, value) => {
+      if (typeof value === 'string') headers[key] = value;
+    },
+  };
+}
+
+/**
+ * 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 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 function boolField<K extends string>(key: K, fallback: boolean): HeaderField<boolean, K>;
+export function boolField<K extends string>(key: K, fallback?: boolean): HeaderField<boolean | undefined, K> {
+  return {
+    key,
+    read: (headers) => parseBool(headers[key]) ?? fallback,
+    write: (headers, value) => {
+      if (typeof value === 'boolean') headers[key] = String(value);
+    },
+  };
+}
+
+/**
+ * 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 const jsonField = <V, K extends string = string>(key: K): HeaderField<V | undefined, K> => ({
+  key,
+  // CAST: header values are wire data parsed via JSON.parse — a trust
+  // boundary. The caller declares the expected shape through `V`; malformed
+  // JSON reads back as `undefined` (parseJson swallows the parse error).
+  read: (headers) => parseJson(headers[key]) as V | undefined,
+  write: (headers, value) => {
+    // Skip undefined and null so an absent value leaves the key unset rather
+    // than serializing to "null".
+    if (value !== undefined && value !== null) headers[key] = JSON.stringify(value);
+  },
+});
+
+/**
+ * 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 const enumField = <const T extends string, K extends string>(
+  key: K,
+  allowed: readonly T[],
+  fallback: NoInfer<T>,
+): HeaderField<T, K> => ({
+  key,
+  read: (headers) => {
+    const raw = headers[key];
+    // find returns the matched literal (typed T) or undefined — no cast needed.
+    return allowed.find((candidate) => candidate === raw) ?? fallback;
+  },
+  write: (headers, value) => {
+    if (typeof value === 'string') headers[key] = value;
+  },
+});

package/src/core/codec/index.ts

@@ -1,6 +1,7 @@
 export type {
   ChannelWriter,
   Codec,
+  CodecEvent,
   CodecInputEvent,
   CodecMessage,
   CodecOutputEvent,
@@ -33,3 +34,45 @@ export { createDecoderCore } from './decoder.js';
 // Lifecycle tracker
 export type { LifecycleTracker, PhaseConfig } from './lifecycle-tracker.js';
 export { createLifecycleTracker } from './lifecycle-tracker.js';
+
+// Typed header-field bindings
+export type { DataCodec, FieldFor, HeaderField } from './fields.js';
+export { boolField, enumField, jsonField, strField } from './fields.js';
+
+// Well-known input factories (merged into every codec by defineCodec)
+export type { WellKnownInputFactories } from './well-known-inputs.js';
+
+// Output descriptor authoring surface
+export type {
+  EscapeHatchCore,
+  HeaderBuilder,
+  OutputDecodeContext,
+  OutputDescriptor,
+  OutputEncodeHatchContext,
+  OutputEventSpec,
+  OutputStreamEndContext,
+  OutputStreamSpec,
+} from './output-descriptors.js';
+
+// Input descriptor authoring surface
+export type {
+  BatchAssembleContext,
+  BatchMessageHeaders,
+  BatchSpec,
+  InputDescriptor,
+  InputEventSpec,
+  PartBuilder,
+  PartSpec,
+} from './input-descriptors.js';
+
+// Codec composition factory
+export type {
+  CodecReducer,
+  DefineCodecConfig,
+  DefinedCodec,
+  InputBuilder,
+  LifecycleDiscreteContext,
+  LifecyclePolicy,
+  OutputBuilder,
+} from './define-codec.js';
+export { defineCodec } from './define-codec.js';

package/src/core/codec/input-descriptor-decoder.ts

@@ -0,0 +1,97 @@
+/**
+ * Generic input decode driver over an input descriptor set — the input-side
+ * sibling of {@link import('./output-descriptor-decoder.js')}.
+ *
+ * Rebuilds inputs from one inbound `ai-input` message, dispatching on the codec
+ * `kind` header. A single `event` rebuilds its field bag (and `data`) and wraps
+ * it into the `{ kind, codecMessageId, payload }` envelope; `wireOnly` events
+ * decode to `[]`. A
+ * `batch` reads the `partType` sub-discriminator, rebuilds the part via its
+ * sub-table, `assemble`s it into a one-part input, and the driver stamps the
+ * `kind` plus the codec-message-id reconstructed from the transport header.
+ *
+ * Returns bare `TInput[]`, never `CodecEvent[]` — direction tagging is
+ * core-owned, downstream at the decode→fold seam.
+ */
+
+import { HEADER_CODEC_MESSAGE_ID } from '../../constants.js';
+import { stripUndefined } from '../../utils.js';
+import { PART_TYPE_HEADER, partFor, readFields } from './field-bag.js';
+import type {
+  BatchDescriptor,
+  InputDecodeContext,
+  InputDescriptor,
+  InputEventDescriptor,
+} 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 const createInputDescriptorDecoder = <U extends { kind: string }>(
+  descriptors: readonly InputDescriptor<U>[],
+): InputDescriptorDecoder<U> => {
+  const byKind = new Map<string, InputDescriptor<U>>();
+  for (const descriptor of descriptors) byKind.set(descriptor.kind, descriptor);
+
+  const decodeEvent = (descriptor: InputEventDescriptor, ctx: InputDecodeContext): U[] => {
+    if (descriptor.wireOnly) return [];
+
+    const bag = readFields(descriptor.fields, ctx.codecHeaders);
+    if (descriptor.data) Object.assign(bag, descriptor.data.decode(ctx.data));
+
+    const codecMessageId = ctx.transportHeaders[HEADER_CODEC_MESSAGE_ID] ?? '';
+    // The payload bag is stripped of undefined-valued props — the same rule
+    // every rebuild seam applies to its innermost bag (absent and undefined
+    // are indistinguishable on the wire). The envelope keys are always defined.
+    // CAST: the rebuild seam — `bag` is assembled from the descriptor's declared
+    // fields and data codec onto the payload, so the `{ kind, codecMessageId, payload }`
+    // envelope conforms to the matched member by construction.
+    return [{ kind: descriptor.kind, codecMessageId, payload: stripUndefined(bag) } as unknown as U];
+  };
+
+  const decodeBatch = (descriptor: BatchDescriptor<U>, ctx: InputDecodeContext): U[] => {
+    const partType = ctx.codecHeaders[PART_TYPE_HEADER] ?? '';
+    const partDesc = partFor(descriptor.parts, partType);
+    if (!partDesc) return [];
+
+    const bag = readFields(partDesc.fields, ctx.codecHeaders);
+    if (partDesc.data) Object.assign(bag, partDesc.data.decode(ctx.data));
+    bag.type = partType;
+
+    // `assemble` takes the erased part (`unknown`); `bag` is the part rebuilt from
+    // its declared fields/data plus the `partType` written to the domain `type`
+    // field. The header tiers carry the per-message metadata (id, role, …) the
+    // batch stamped on every part, so `assemble` can rebuild the message envelope.
+    const partial = descriptor.assemble(stripUndefined(bag), {
+      codecHeaders: ctx.codecHeaders,
+      transportHeaders: ctx.transportHeaders,
+    });
+    // CAST: the driver stamps the shared `kind` onto the assembled one-part input; together
+    // they complete the matched member. A batch creates a new message (not addressed by a
+    // codec-message-id, unlike single `event`s), so none is stamped — the per-message
+    // identity rides the transport header and is recovered by `assemble` when needed.
+    return [{ kind: descriptor.kind, ...partial } as unknown as U];
+  };
+
+  return {
+    decode: (ctx) => {
+      const descriptor = byKind.get(ctx.codecKind);
+      if (!descriptor) return [];
+      if (descriptor.construct === 'event') return decodeEvent(descriptor, ctx);
+      return decodeBatch(descriptor, ctx);
+    },
+  };
+};

package/src/core/codec/input-descriptor-encoder.ts

@@ -0,0 +1,150 @@
+/**
+ * Generic input encode driver over an input descriptor set — the input-side
+ * sibling of {@link import('./output-descriptor-encoder.js')}.
+ *
+ * Builds a `kind`→descriptor registry once, then routes each input: a single
+ * `event` publishes one discrete message (fields/data lensed onto the member's
+ * `payload`, or kind-only when `wireOnly`); a `batch` explodes the domain
+ * message into one wire event per part and publishes them atomically, with a
+ * built-in ≥1-event guarantee so the codec-message-id and role survive an empty
+ * decomposition. Headers are always built through the descriptor's declared
+ * fields ({@link writeFields}), so the imperative paths can't drift.
+ */
+
+import * as Ably from 'ably';
+
+import { ErrorCode } from '../../errors.js';
+import { KIND_HEADER, PART_TYPE_HEADER, partFor, prop, writeFields } from './field-bag.js';
+import type {
+  BatchDescriptor,
+  BatchMessageHeaders,
+  InputDescriptor,
+  InputEncodeContext,
+  InputEncoderCore,
+  InputEventDescriptor,
+} from './input-descriptors.js';
+import type { MessagePayload } from './types.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>;
+}
+
+// Layer the batch's per-message transport headers onto a part payload, if any.
+const withMessageTransport = (payload: MessagePayload, message: BatchMessageHeaders | undefined): MessagePayload =>
+  message?.transportHeaders === undefined
+    ? payload
+    : { ...payload, transportHeaders: { ...payload.transportHeaders, ...message.transportHeaders } };
+
+/**
+ * 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 const createInputDescriptorEncoder = <U extends { kind: string }>(
+  descriptors: readonly InputDescriptor<U>[],
+  wireName: string,
+): InputDescriptorEncoder<U> => {
+  const byKind = new Map<string, InputDescriptor<U>>();
+  for (const descriptor of descriptors) byKind.set(descriptor.kind, descriptor);
+
+  const encodeEvent = async (
+    descriptor: InputEventDescriptor,
+    input: U,
+    core: InputEncoderCore,
+    ctx: InputEncodeContext,
+  ): Promise<void> => {
+    if (descriptor.wireOnly) {
+      // Kind only: no fields, no data — the parent/target ride transport headers.
+      await core.publishDiscrete(
+        { name: wireName, data: '', codecHeaders: { [KIND_HEADER]: descriptor.kind } },
+        ctx.opts,
+      );
+      return;
+    }
+    // A non-wireOnly input nests its domain data under `payload` — fields and
+    // data are authored against it. Fail fast on a payload-less member instead
+    // of silently publishing empty data the decoder can't rebuild from.
+    const source = prop(input, 'payload');
+    if (typeof source !== 'object' || source === null) {
+      throw new Ably.ErrorInfo(
+        `unable to encode input; event '${descriptor.kind}' carries no payload object — declare it wireOnly or use an encode escape hatch`,
+        ErrorCode.InvalidArgument,
+        400,
+      );
+    }
+    const codecHeaders = writeFields(descriptor.fields, descriptor.kind, source);
+    const data = descriptor.data ? descriptor.data.encode(source) : '';
+    await core.publishDiscrete({ name: wireName, data, codecHeaders }, ctx.opts);
+  };
+
+  const encodeBatch = async (
+    descriptor: BatchDescriptor<U>,
+    input: U,
+    core: InputEncoderCore,
+    ctx: InputEncodeContext,
+  ): Promise<void> => {
+    // Per-message headers (e.g. message id, role) are stamped on every part so
+    // the decode side can reconstruct the shared message envelope from any one.
+    const message = descriptor.messageHeaders?.(input);
+    const payloads: MessagePayload[] = [];
+    for (const part of descriptor.explode(input)) {
+      const partType = descriptor.partTypeOf(part);
+      const partDesc = partFor(descriptor.parts, partType);
+      if (!partDesc) continue;
+      // CAST: a part is indexed by its declared fields; the part descriptor only
+      // runs against the part its predicate/literal matched, so the source has the
+      // field's type at runtime. The wire `partType` is the resolved part type.
+      const source = part as object;
+      const codecHeaders = {
+        ...writeFields(partDesc.fields, descriptor.kind, source),
+        ...message?.codecHeaders,
+        [PART_TYPE_HEADER]: partType,
+      };
+      const data = partDesc.data ? partDesc.data.encode(part) : '';
+      payloads.push(withMessageTransport({ name: wireName, data, codecHeaders }, message));
+    }
+
+    if (payloads.length === 0) {
+      // ≥1-event guarantee: emit one bare part so the per-message headers (e.g.
+      // the message id and role) reach the wire even when no exploded part
+      // matched a descriptor. This fallback carries no partType, so the batch
+      // decode path yields no input for it — a codec that needs an empty
+      // message to round-trip must guarantee ≥1 encodable part in `explode`
+      // (e.g. by substituting a canonical empty part).
+      payloads.push(
+        withMessageTransport(
+          { name: wireName, data: '', codecHeaders: { [KIND_HEADER]: descriptor.kind, ...message?.codecHeaders } },
+          message,
+        ),
+      );
+    }
+
+    await core.publishDiscreteBatch(payloads, ctx.opts);
+  };
+
+  return {
+    encode: async (input, core, ctx) => {
+      const descriptor = byKind.get(input.kind);
+      if (!descriptor) {
+        throw new Ably.ErrorInfo(
+          `unable to publish; unsupported input kind '${input.kind}'`,
+          ErrorCode.InvalidArgument,
+          400,
+        );
+      }
+      await (descriptor.construct === 'event'
+        ? encodeEvent(descriptor, input, core, ctx)
+        : encodeBatch(descriptor, input, core, ctx));
+    },
+  };
+};