@adhd/apigen-engine-runtime 0.1.0

package/lib/api-package.d.ts

@@ -0,0 +1,4 @@
+import { MiddlewareDef, ApiPackageOptions, ApiPackageResult } from './types';
+
+export declare function assertNoSelfSubscription(middlewares: readonly MiddlewareDef[]): void;
+export declare function createApiPackage<M extends readonly MiddlewareDef[]>(options: ApiPackageOptions<M>): ApiPackageResult;

package/lib/apigen-runtime.d.ts

@@ -0,0 +1 @@
+export declare function apigenRuntime(): string;

package/lib/build-context.d.ts

@@ -0,0 +1,4 @@
+import { EventBus } from './event-bus';
+import { MiddlewareDef } from './types';
+
+export declare function buildContext(middlewares: readonly MiddlewareDef[], envelope: Record<string, unknown>, bus: EventBus): Promise<object>;

package/lib/coerce-query.d.ts

@@ -0,0 +1,38 @@
+/**
+ * FEAT-APIGEN-022 / BACKLOG point 3 — query-string coercion for GET domain args.
+ *
+ * HTTP query strings carry every value as a string (or string[] for repeated
+ * keys). The composed input schema's validate-Layer (`makeValidateLayer`,
+ * `@adhd/apigen-engine-runtime/validate-layer`) uses a single Ajv instance
+ * with NO `coerceTypes`, shared by both GET (query) and POST (JSON body)
+ * validation — enabling Ajv-level `coerceTypes` globally would silently
+ * coerce POST body values too (e.g. a JSON string erroneously accepted where
+ * a number was required), which SPEC §6 forbids. Coercion therefore happens
+ * here, at the TRANSPORT layer, scoped to exactly the GET/query-string path,
+ * before the already-strict (non-coercing) validate-Layer ever sees the
+ * value — POST/body validation is completely untouched.
+ *
+ * Only `number`/`integer`/`boolean` are coerced (the non-`string` members of
+ * FEAT-APIGEN-022's "properly typed primitives" set — `string` values are
+ * already correctly typed as they arrive). A value that fails to parse (e.g.
+ * `?count=abc` against a `number` param) is left AS-IS so the validate-Layer
+ * still rejects it with a clear `invalid_argument` error, rather than being
+ * silently dropped or coerced to `NaN`/`0`.
+ */
+/**
+ * Coerces a request's query-string params to the JS types their domain
+ * schema declares (`number`/`integer`/`boolean`), based on the function's own
+ * composed schema. `string`-typed and unrecognised params pass through
+ * unchanged; array-valued query entries (repeated keys) pass through
+ * unchanged (arrays are outside FEAT-APIGEN-022's primitive-only hoist
+ * boundary, so no domain param reaching here should be array-typed — but this
+ * stays defensive rather than assuming that invariant).
+ *
+ * @param query  The raw `req.query` / `request.query` object.
+ * @param schema The function's composed schema entry (`pkg.schemas[fnName]`) —
+ *               loosely typed like `describeParams`'s `schema` param, since
+ *               callers pass the untyped `ComposedSchemas` entry.
+ */
+export declare function coerceQueryParams(query: Record<string, unknown>, schema: {
+    input?: unknown;
+} | undefined): Record<string, unknown>;

package/lib/define-middleware.d.ts

@@ -0,0 +1,5 @@
+import { MiddlewareDef } from './types';
+
+export declare function defineMiddleware<TId extends string, TEnvelope extends object, TContext extends object>(def: MiddlewareDef<TEnvelope, TContext> & {
+    id: TId;
+}): typeof def;

package/lib/describe-params.d.ts

@@ -0,0 +1,18 @@
+export interface ParamInfo {
+    name: string;
+    type: string;
+    required: boolean;
+}
+/**
+ * Extract a composed schema entry's domain parameters for logging.
+ *
+ * Params live under `input.properties.data.properties` — the `data` envelope
+ * wrapper is always present (see [def:ComposedSchemas]). Returns both a
+ * structured list (for JSON logs) and a `name?: type` summary string.
+ */
+export declare function describeParams(schema: {
+    input?: unknown;
+} | undefined): {
+    params: ParamInfo[];
+    text: string;
+};

package/lib/dispatch.d.ts

@@ -0,0 +1,23 @@
+import { ComposedSchemas } from './types';
+
+/** Returns true when the composed schema has `field` in input.properties (i.e. an envelope field). */
+export declare function needsEnvelopeField(fnSchema: ComposedSchemas[string], field: string): boolean;
+/** Returns ordered domain parameter names (keys of the data: {} sub-object). */
+export declare function dataParamNames(fnSchema: ComposedSchemas[string]): string[];
+/**
+ * Single canonical dispatch path used by ALL plugins in both generate and run modes.
+ * No plugin may inline this logic. [inv:dispatch-single-path]
+ *
+ * Logical-type decode/encode seam (DESIGN.md §4.4 / §6):
+ *   - BEFORE calling the fn: each domain arg is decoded from wire → host using
+ *     the schema node at `input.properties.data.properties[k]`. A param whose
+ *     node carries `{type:string, format:date-time}` arrives as a real `Date`;
+ *     a plain `string` node passes through unchanged.
+ *   - AFTER the fn returns: the result is encoded from host → wire using the
+ *     output schema. A `Date` return becomes an RFC 3339 string; plain JSON
+ *     values pass through unchanged.
+ *
+ * All existing behaviors (session ctx injection, BUG-APIGEN-001 ctx-param path,
+ * envelope handling) are preserved unchanged.
+ */
+export declare function dispatch(fns: Record<string, (...args: unknown[]) => unknown>, createClient: ((e: Record<string, unknown>) => Promise<unknown>) | undefined, schema: ComposedSchemas[string], fnName: string, envelope: Record<string, unknown>, domainArgs: Record<string, unknown>): Promise<unknown>;

package/lib/event-bus.d.ts

@@ -0,0 +1,19 @@
+import { MiddlewareDef, MiddlewareEvent } from './types';
+
+type EventHandler = (event: MiddlewareEvent) => void | Promise<void>;
+export declare class EventBus {
+    private handlers;
+    /**
+     * Register a handler. Returns an unsubscribe function — handlers registered
+     * per-request/per-package MUST be removed (via the returned fn, {@link off},
+     * or {@link clear}) or they accumulate for the bus's lifetime.
+     */
+    on(selector: string, handler: EventHandler): () => void;
+    /** Remove a previously registered handler (no-op if absent). */
+    off(selector: string, handler: EventHandler): void;
+    /** Remove every handler — call on package/server teardown. */
+    clear(): void;
+    emit(event: MiddlewareEvent): Promise<void>;
+}
+export declare function wireObservers(middlewares: readonly MiddlewareDef[], bus: EventBus): void;
+export {};

package/lib/fn-table.d.ts

@@ -0,0 +1,16 @@
+export type AnyFn = (...args: unknown[]) => unknown;
+/**
+ * Build a `name → function` table from an imported module namespace, matching how
+ * schema extraction names functions so `dispatch` can always resolve them.
+ *
+ * Robust to every export + interop shape:
+ *  - **named exports** (`export function f` / `export const f = …`) → keyed by name.
+ *  - **single default-exported function** (`export default f`) → keyed by the
+ *    function's declaration name (ESM keys it `default`; CJS-compiled deps double-
+ *    wrap it as `default.default` / `module.exports.default`). We unwrap those
+ *    layers and key every function found by its `.name`.
+ *  - **default object** (`export default { a, b }`) → each function keyed by name.
+ *
+ * Earlier keys win; explicit named exports are never overwritten by unwrapped ones.
+ */
+export declare function buildFnTable(mod: Record<string, unknown>): Record<string, AnyFn>;

package/lib/instance-registry.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Instance registry for class-export instance dispatch (SPEC §10).
+ *
+ * When a `kind:'constructor'` op fires, the runtime constructs the target class
+ * and stores the live instance here under a unique `instanceId`.  Subsequent
+ * `kind:'instance-method'` ops look up the instance by `instanceId` and
+ * dispatch the method against it.
+ *
+ * Lifecycle (TTL + dispose):
+ *   - Every entry carries an optional TTL (milliseconds).  A sweeper clears
+ *     expired entries automatically; the sweep interval is configurable.
+ *   - Calling `dispose(instanceId)` removes the entry immediately and runs the
+ *     instance's `dispose()` method if it exists.
+ *   - `disposeAll()` tears down every live instance and stops the sweeper.
+ *
+ * Stateful caveat: the registry lives in-process; horizontal scaling without
+ * sticky routing or an external store will route requests to the wrong instance.
+ * Document this to API consumers (SPEC §10 note).
+ *
+ * Usage:
+ * ```ts
+ * const registry = new InstanceRegistry({ defaultTtlMs: 30_000 })
+ *
+ * // constructor op handler
+ * const { instanceId } = registry.create(Counter, [0])
+ *
+ * // instance-method op handler
+ * const counter = registry.get<Counter>(instanceId)
+ * counter.increment()
+ *
+ * // explicit teardown
+ * await registry.dispose(instanceId)
+ * await registry.disposeAll()
+ * ```
+ */
+/** Any class constructor (unknown args → unknown instance). */
+export type AnyConstructor = new (...args: unknown[]) => unknown;
+/** Options for the registry. */
+export interface InstanceRegistryOptions {
+    /**
+     * Default TTL in milliseconds for each instance. When omitted, instances
+     * live until explicitly `dispose()`d or `disposeAll()` is called.
+     */
+    defaultTtlMs?: number;
+    /**
+     * How often (ms) the background sweeper checks for expired entries.
+     * Defaults to `Math.max(1_000, defaultTtlMs / 4)` when a TTL is set,
+     * or `5_000` otherwise.  Pass `0` to disable the automatic sweeper.
+     */
+    sweepIntervalMs?: number;
+}
+/** The result returned by `registry.create()` — the `instanceId` is what the
+ *  client passes back on every `kind:'instance-method'` call. */
+export interface CreateResult {
+    instanceId: string;
+}
+/**
+ * In-process instance store for SPEC §10 class-instance dispatch.
+ *
+ * Thread-safe within a single Node.js event-loop (single-threaded JS).
+ * Stateful: does NOT survive process restarts; scale with sticky routing.
+ */
+export declare class InstanceRegistry {
+    private readonly _store;
+    private readonly _defaultTtlMs;
+    private _sweeper;
+    constructor(opts?: InstanceRegistryOptions);
+    /**
+     * Construct an instance of `Ctor` with `args` and store it in the registry.
+     *
+     * @param Ctor  - The class to instantiate.
+     * @param args  - Constructor arguments (positional).
+     * @param ttlMs - Per-entry TTL override.  Falls back to `defaultTtlMs`.
+     * @returns `{ instanceId }` — pass this to `dispatch()` / `get()`.
+     */
+    create(Ctor: AnyConstructor, args?: unknown[], ttlMs?: number): CreateResult;
+    /**
+     * Retrieve the instance stored under `instanceId`.
+     *
+     * @throws When `instanceId` is unknown or the entry has expired.
+     */
+    get<T = unknown>(instanceId: string): T;
+    /**
+     * Look up `instanceId` and call `method` on it with `args`.
+     *
+     * @throws When `instanceId` is unknown/expired, or `method` is not a function
+     *   on the instance.
+     */
+    dispatch(instanceId: string, method: string, args?: unknown[]): Promise<unknown>;
+    /**
+     * Remove `instanceId` from the registry and call `instance.dispose()` if the
+     * instance exposes one (opt-in lifecycle hook).
+     */
+    dispose(instanceId: string): Promise<void>;
+    /**
+     * Dispose every live instance and stop the background sweeper.  Call this
+     * when the server is shutting down.
+     */
+    disposeAll(): Promise<void>;
+    /** Number of live (non-expired) entries currently in the registry. */
+    get size(): number;
+    private _sweep;
+    private _evict;
+}

package/lib/invoke.d.ts

@@ -0,0 +1,112 @@
+import { ComposedSchemas } from './types';
+import { Operation } from '@adhd/apigen-core-client';
+
+/**
+ * A symbol-keyed or constructor-keyed typed extension map.  Each value is
+ * stored under a unique token so Layers can share typed data without a mutable
+ * property bag.  Modeled after Tower/`http::Extensions` — the only `ctx` shape
+ * expressible under Rust's borrow checker, so TS matches it for dual-host
+ * alignment.
+ */
+export declare class LayerContext {
+    private readonly _map;
+    /** Store `value` under `token` (a constructor or a unique symbol). */
+    set<T>(token: abstract new (...args: never[]) => T, value: T): void;
+    set<T>(token: symbol, value: T): void;
+    /**
+     * Retrieve the value stored under `token`.  Returns `undefined` when the
+     * token has not been inserted — callers are responsible for presence checks.
+     */
+    get<T>(token: abstract new (...args: never[]) => T): T | undefined;
+    get<T>(token: symbol): T | undefined;
+    /** Returns true when the token has a stored value. */
+    has(token: unknown): boolean;
+}
+/** The resolved domain call, threaded through the Layer stack. */
+export interface Call {
+    /**
+     * The canonical operation descriptor.  For v1 callers that do not have a
+     * full Operation, only `id` is guaranteed; the remaining fields are optional.
+     */
+    operation: Pick<Operation, 'id'> & Partial<Operation>;
+    /** Typed extension map — insert/read per §8.1 rule 3. */
+    ctx: LayerContext;
+    /** Middleware envelope (side-channel from transport metadata). */
+    envelope: Record<string, unknown>;
+    /** Domain arguments (the `data` sub-object from the composed input). */
+    domainArgs: Record<string, unknown>;
+    /** Cancellation signal (AbortSignal) — §11. */
+    signal?: AbortSignal;
+}
+/**
+ * The primitive result a Layer or dispatch can return.
+ *
+ * §11: a streaming operation returns `AsyncIterable<unknown>`; a normal
+ * operation returns `unknown`.  Both are covered by this union.
+ */
+export type LayerResult = unknown | AsyncIterable<unknown>;
+/**
+ * `next` continuation — the inner Layer or dispatch Service.
+ *
+ * Returns a promise of either a scalar result or an AsyncIterable stream
+ * (§11).  A Layer that short-circuits (§8.1 rule 1) never calls this.
+ */
+export type Next = () => Promise<LayerResult>;
+/**
+ * A Layer in the TS harness (§8.1 normative closure signature).
+ *
+ * ```ts
+ * const logger: Layer = async (call, next) => {
+ *   const t = Date.now()
+ *   try   { const r = await next(); return r }
+ *   catch (e) { throw e }  // error unwinds outward — §8.1 rule 2
+ * }
+ * ```
+ *
+ * Rule 1 (short-circuit): return a value WITHOUT calling `next`.
+ * Rule 2 (error propagation): `throw` propagates to the enclosing Layer.
+ * Rule 4 (poll_ready): not present — TS host omits it entirely (host-optional).
+ * Rule 5 (streaming): `next()` return type includes `AsyncIterable<unknown>`.
+ * Rule 6 (codegen-weave): composition is a pure function; same semantics.
+ */
+export type Layer = (call: Call, next: Next) => Promise<LayerResult>;
+/**
+ * Runtime context needed by `invoke` to reach the core dispatch Service.
+ *
+ * v1 callers supply `fns` + `createClient` + `schemas` directly; future
+ * callers may pre-build an invoker from an Operation descriptor.
+ */
+export interface InvokeOptions {
+    /** The live function table (fn-name → implementation). */
+    fns: Record<string, (...args: unknown[]) => unknown>;
+    /** Optional client factory (for session-ctx middleware). */
+    createClient?: (envelope: Record<string, unknown>) => Promise<unknown>;
+    /** Composed schemas for the target namespace. */
+    schemas: ComposedSchemas;
+}
+/**
+ * The composed invoke function returned by {@link createInvoker}.
+ *
+ * Accepts an operation name, a {@link Call}, and runtime dispatch options.
+ * Returns the Service result, streaming or scalar.
+ */
+export type InvokeFn = (fnName: string, call: Call, opts: InvokeOptions) => Promise<LayerResult>;
+/**
+ * Compose a Layer stack and return a typed `invoke` function.
+ *
+ * Layers are applied **outermost-first**: `layers[0]` wraps `layers[1]`
+ * which wraps … which wraps `dispatch`.  Equivalent to Tower's
+ * `ServiceBuilder::layer` / `layer_fn` composition order.
+ *
+ * ```ts
+ * const invoke = createInvoker([authLayer, loggerLayer])
+ * const result = await invoke('getUser', call, opts)
+ * ```
+ *
+ * When `layers` is empty, `invoke` calls `dispatch` directly.
+ *
+ * §8.1 rule 6 (codegen-weave): static hosts receive the composed list at
+ * codegen time; `createInvoker` is called once per plugin instantiation, not
+ * once per request.
+ */
+export declare function createInvoker(layers?: readonly Layer[]): InvokeFn;

package/lib/logger.d.ts

@@ -0,0 +1,29 @@
+import { Logger } from 'pino';
+
+export type { Logger };
+/** Log output format. `pretty` is colorized human-readable; `json` is raw jsonl. */
+export type LogFormat = 'json' | 'pretty';
+export interface CreateLoggerOptions {
+    /** pino log level. Default: `info`. */
+    level?: string;
+    /**
+     * Output format. Default: `pretty` when the destination is a TTY, else `json`.
+     * `pretty` routes through pino-pretty (colorized, timestamped); `json` emits jsonl.
+     */
+    format?: LogFormat;
+    /**
+     * Where logs are written. Default: stderr (fd 2) — NEVER stdout, which is the
+     * MCP stdio JSON-RPC channel. Pass a filesystem path to write logs to a file.
+     */
+    destination?: string;
+}
+/**
+ * Build the shared apigen pino logger.
+ *
+ * Logging always targets stderr or a file — never stdout — so the MCP stdio
+ * transport's JSON-RPC channel on stdout stays free of log noise.
+ *
+ * @param opts - level, format (`json` | `pretty`), and destination (stderr or a file path).
+ * @returns a configured pino {@link Logger}.
+ */
+export declare function createLogger(opts?: CreateLoggerOptions): Logger;

package/lib/logical/host-ts.d.ts

@@ -0,0 +1,41 @@
+import { LogicalTypeCodec, LogicalTypeId } from '@adhd/apigen-base-logical';
+
+/**
+ * @stable A host binding maps a LogicalTypeId to that host's native
+ * encode/decode primitives (DESIGN.md §4.6).
+ *
+ * - `host`               — identifies the language/runtime.
+ * - `logicalTypeVersion` — pinned to `LOGICAL_TYPE_VERSION` from
+ *                          `@adhd/apigen-base-logical`; bumped on any wire-table
+ *                          or pinned-lib-version change (DESIGN §8.6).
+ * - `codecs`             — frozen ReadonlyMap keyed by LogicalTypeId. Must
+ *                          cover every well-known id (DESIGN §4.6 "Must cover
+ *                          every well-known id.").
+ */
+export interface HostBinding {
+    readonly host: 'ts' | 'python' | 'rust' | 'go' | 'java';
+    readonly logicalTypeVersion: string;
+    /** The codecs this host provides, keyed by LogicalTypeId. */
+    readonly codecs: ReadonlyMap<LogicalTypeId, LogicalTypeCodec>;
+}
+/**
+ * @stable Ordered array of all well-known scalar codec instances for the TS
+ * host. Derived from the same import list used by `registerWellKnown` in
+ * `@adhd/apigen-base-logical`; kept in sync by importing the exact same named
+ * exports (a future addition to that barrel automatically lands here).
+ */
+export declare const WELL_KNOWN_TS_CODECS: ReadonlyArray<LogicalTypeCodec>;
+/**
+ * @stable The TypeScript HostBinding (DESIGN.md §4.6).
+ *
+ * A frozen object exposing all TS codec instances keyed by their
+ * `LogicalTypeId`. Consumers obtain a per-surface registry by calling
+ * `registerWellKnown(registry)` from `@adhd/apigen-base-logical`, then
+ * registering the generated nominal/union codecs on top.
+ *
+ * `logicalTypeVersion` is pinned to `LOGICAL_TYPE_VERSION` exported by
+ * `@adhd/apigen-base-logical` (`descriptor-ext.ts`) — `'0.1.0'` at authoring time.
+ * Any wire-table or pinned-lib-version change bumps that constant and this
+ * binding automatically reflects the new version.
+ */
+export declare const tsHostBinding: HostBinding;

package/lib/logical/nominal-codec.d.ts

@@ -0,0 +1,73 @@
+import { LogicalTypeCodec, LogicalTypeId, SchemaNode } from '@adhd/apigen-base-logical';
+
+/**
+ * Reserved descriptor keyword carrying the extractor's **opt-in-instances**
+ * decision (DESIGN.md §4.5 / §13 — risk 8.5, RESOLVED). A class the extractor
+ * could not prove reconstructable (sockets, closures, opaque handles) is emitted
+ * with `x-apigen-instances:false`; its codec is **encode-only** and `decode`
+ * throws a clear `E_NOMINAL_NONRECONSTRUCTABLE` diagnostic rather than minting a
+ * half-built instance.
+ */
+export declare const X_APIGEN_INSTANCES: "x-apigen-instances";
+/**
+ * Stable, transport-neutral error codes raised by the nominal codec. They are
+ * carried on a typed `Error` subclass so callers can branch on `err.code`
+ * without string-matching the message.
+ */
+export type NominalCodecErrorCode = 'E_NOMINAL_CYCLE' | 'E_NOMINAL_NONRECONSTRUCTABLE' | 'E_NOMINAL_INVALID_WIRE';
+/** @stable Error carrier for the custom-class (`kind:'nominal'`) codec. */
+export declare class NominalCodecError extends Error {
+    readonly code: NominalCodecErrorCode;
+    constructor(code: NominalCodecErrorCode, message: string);
+}
+/**
+ * A host class that knows how to rebuild itself from its field bag. The codec
+ * looks up the static reconstructor named by `x-apigen-ctor` (default
+ * `fromJSON`) on the registered host class; absent that, it falls back to a
+ * schema-projected plain construction.
+ */
+export type NominalCtor = {
+    new (...args: any[]): object;
+    fromJSON?(bag: Record<string, unknown>): object;
+    [staticCtor: string]: unknown;
+};
+/** Options threaded into {@link createNominalCodec} for one custom class. */
+export interface NominalCodecOptions {
+    /** Stable LogicalTypeId (namespace-qualified, e.g. `cli.User`). */
+    readonly id: LogicalTypeId;
+    /** Resolved `$def` object schema this codec owns (carries `properties`/`required`). */
+    readonly schema: SchemaNode;
+    /**
+     * Host class used to reconstruct instances on decode. OPTIONAL: when absent
+     * the codec decodes to a schema-projected plain object (still a faithful
+     * round-trip of the field bag — see `[inv:hints-advisory]`).
+     */
+    readonly ctor?: NominalCtor;
+}
+/**
+ * @stable Codec factory for a single custom class (`kind:'nominal'`).
+ *
+ * Encode (host → wire), DESIGN.md §4/§13:
+ *  1. **Cycle guard** — track each visited instance in `ctx.seen`; a back-edge
+ *     in `strict` mode throws `E_NOMINAL_CYCLE` (the approved strict policy,
+ *     decision 8.3). `lossy` mode breaks the cycle by emitting `null`.
+ *  2. **`toJSON` hint** — when the class exposes `toJSON` (named by
+ *     `x-apigen-tojson`, default `toJSON`), use its field bag.
+ *  3. **Field projection** — otherwise project the schema's declared
+ *     `properties`. Either way every field VALUE is recursed through the
+ *     registry so nested logical types (e.g. `Date`) encode correctly.
+ *
+ * Decode (wire → host), validate-then-construct:
+ *  1. **Validate** the wire against the node FIRST (object shape + required
+ *     fields present) → `E_NOMINAL_INVALID_WIRE` on a mismatch.
+ *  2. **Reconstructable gate** — `x-apigen-instances:false` ⇒ encode-only;
+ *     decode throws `E_NOMINAL_NONRECONSTRUCTABLE`.
+ *  3. **Construct** — via the static reconstructor named by `x-apigen-ctor`
+ *     (default `fromJSON`) when the host class is supplied, else a
+ *     schema-projected plain object. Field VALUES are recursed first.
+ *
+ * `[inv:hints-advisory]`: the `x-apigen-*` keys only *accelerate* the choice of
+ * hook. With every hint stripped the codec still round-trips via schema
+ * projection — proven by a negative-control vector.
+ */
+export declare function createNominalCodec(opts: NominalCodecOptions): LogicalTypeCodec<object>;

package/lib/logical/union-codec.d.ts

@@ -0,0 +1,63 @@
+import { LogicalTypeCodec, LogicalTypeId, SchemaNode } from '@adhd/apigen-base-logical';
+
+/**
+ * Stable, transport-neutral error codes raised by the union codec. Carried on
+ * a typed `Error` subclass so callers can branch on `err.code` without
+ * string-matching the message.
+ */
+export type UnionCodecErrorCode = 'E_UNION_NO_DISCRIMINATOR' | 'E_UNION_UNKNOWN_TAG' | 'E_UNION_INVALID_WIRE';
+/** @stable Error carrier for the polymorphic-union (`kind:'union'`) codec. */
+export declare class UnionCodecError extends Error {
+    readonly code: UnionCodecErrorCode;
+    constructor(code: UnionCodecErrorCode, message: string);
+}
+/** Options threaded into {@link createUnionCodec} for one polymorphic union. */
+export interface UnionCodecOptions {
+    /** Stable LogicalTypeId (namespace-qualified, e.g. `cli.Pet`). */
+    readonly id: LogicalTypeId;
+    /**
+     * The union schema node: `{ oneOf:[...], discriminator:{propertyName, mapping} }`.
+     * This is the authoritative ownership schema stored on the codec; individual
+     * `encode`/`decode` calls may pass a node with `x-apigen-logical` stripped
+     * (or a structurally equivalent node) — the codec MUST behave identically.
+     */
+    readonly schema: SchemaNode;
+}
+/**
+ * @stable Codec factory for a discriminated union (`kind:'union'`).
+ *
+ * Wire shape (DESIGN §3 + §4.1): the value is a JSON object that carries a
+ * const discriminator property (e.g. `kind`). The schema node looks like:
+ * ```json
+ * { "oneOf": [{"$ref":"#/$defs/Dog"},{"$ref":"#/$defs/Cat"}],
+ *   "discriminator": {"propertyName":"kind","mapping":{"dog":"#/$defs/Dog","cat":"#/$defs/Cat"}},
+ *   "x-apigen-logical": "union" }
+ * ```
+ *
+ * Ownership test — `matches(node)`:
+ *   true when the node has BOTH `oneOf` (array) AND `discriminator` (object with
+ *   `propertyName`). The `x-apigen-logical:"union"` hint accelerates dispatch but
+ *   is NOT required — structure is authoritative (`[inv:hints-advisory]`).
+ *
+ * Encode (host → wire):
+ *  1. Read `discriminator.propertyName` off the **value** to get the tag.
+ *     Throws `E_UNION_NO_DISCRIMINATOR` if the tag prop is absent/undefined.
+ *  2. Map tag → branch `$ref` via `discriminator.mapping[tag]`.
+ *     Throws `E_UNION_UNKNOWN_TAG` if the tag isn't in the mapping.
+ *  3. Resolve the branch schema node via `ctx.resolve(ref)`.
+ *  4. Delegate encoding of value to the branch codec via `ctx.registry.resolve`,
+ *     falling back to structural identity pass-through for plain object schemas.
+ *
+ * Decode (wire → host) — mirror of encode:
+ *  1. Validate the wire is a non-null, non-array object.
+ *     Throws `E_UNION_INVALID_WIRE` on a non-object.
+ *  2. Read the discriminator tag off the wire object.
+ *     Throws `E_UNION_NO_DISCRIMINATOR` if absent.
+ *  3. Map tag → branch `$ref` + resolve, then delegate to the branch codec.
+ *     Throws `E_UNION_UNKNOWN_TAG` if the tag isn't in the mapping.
+ *
+ * `[inv:hints-advisory]`: stripping `x-apigen-logical:"union"` from the node
+ *  passed to `encode`/`decode` produces identical output. Proven by the
+ *  negative-control vector in the spec.
+ */
+export declare function createUnionCodec(opts: UnionCodecOptions): LogicalTypeCodec<object>;

package/lib/mcp-output-schema.d.ts

@@ -0,0 +1,21 @@
+/** Result of adapting a composed-schema `output` fragment for MCP's `outputSchema` field. */
+export interface McpOutputAdapter {
+    /** The MCP `Tool.outputSchema` value, or `undefined` when `output` carries no usable schema. */
+    outputSchema: Record<string, unknown> | undefined;
+    /** True when the output wasn't top-level `type:"object"` and had to be wrapped under `result`. */
+    wrapped: boolean;
+}
+/**
+ * Builds the MCP `outputSchema` for a composed schema's `output` fragment.
+ *
+ * @param output - `ComposedSchemas[fn].output`, whatever `buildSchema` produced
+ *   (may be `type:"object"`, `oneOf`+`discriminator` for a union, an array, a
+ *   bare scalar, or `undefined`/`{}` for an unresolved/void return).
+ */
+export declare function buildMcpOutputSchema(output: unknown): McpOutputAdapter;
+/**
+ * Wraps a tool's actual return value to match the `outputSchema` shape built by
+ * `buildMcpOutputSchema` for the SAME `output` fragment, for use as MCP's
+ * `structuredContent` (also constrained to a plain object by the SDK).
+ */
+export declare function wrapMcpStructuredContent(wrapped: boolean, value: unknown): Record<string, unknown> | undefined;