@adhd/apigen-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/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,11 @@
+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]
+ */
+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,8 @@
+import { MiddlewareDef, MiddlewareEvent } from './types';
+
+export declare class EventBus {
+    private handlers;
+    on(selector: string, handler: (event: MiddlewareEvent) => void | Promise<void>): void;
+    emit(event: MiddlewareEvent): Promise<void>;
+}
+export declare function wireObservers(middlewares: readonly MiddlewareDef[], bus: EventBus): void;

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';
+
+/**
+ * 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/stream.d.ts

@@ -0,0 +1,88 @@
+import { AfterFirstChunkError, BeforeFirstChunkError } from '@adhd/apigen-errors';
+
+/** A strongly-typed async iterable chunk stream (§11 consumer-pull). */
+export type ApiStream<T = unknown> = AsyncIterable<T>;
+/**
+ * Options for {@link createStream}.
+ *
+ * @template T - the chunk type yielded by the producer
+ */
+export interface CreateStreamOptions<T = unknown> {
+    /**
+     * The producer: an async generator that yields chunks.
+     * It receives the AbortSignal so it can honour cancellation directly;
+     * the harness also terminates iteration externally when the signal fires.
+     */
+    produce: (signal: AbortSignal) => AsyncGenerator<T>;
+    /**
+     * Optional cancellation signal (§11).
+     * When aborted, iteration terminates after the current `yield` without
+     * surfacing an error — each Layer's **end** path runs.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Wrap an async generator producer in a stream-lifecycle–aware `ApiStream`.
+ *
+ * The returned `AsyncIterable` is **consumer-pull**: the producer is driven
+ * one chunk at a time by the consumer's `for await`.  Backpressure is
+ * natural — the producer only runs when the consumer is ready for the next
+ * value.
+ *
+ * Cancellation: when `options.signal` fires, the next `next()` call returns
+ * `{ done: true }` cleanly.  Any pending `await` inside the producer is
+ * interrupted by the same signal (the producer must honour it).
+ *
+ * Error-after-first-chunk: if the producer throws after yielding at least
+ * one chunk, the `ApiStream` propagates the error as a normal iterator
+ * rejection (the consumer's `for await` body receives a thrown `ApiError`
+ * or plain error).  Transport adapters catch this and deliver it in-band
+ * per the §11 carrier table.
+ *
+ * @example
+ * ```ts
+ * const stream = createStream({
+ *   produce: async function* (signal) {
+ *     for (const item of items) {
+ *       if (signal.aborted) return
+ *       yield item
+ *     }
+ *   },
+ *   signal: call.signal,
+ * })
+ * for await (const chunk of stream) { ... }
+ * ```
+ */
+export declare function createStream<T = unknown>(options: CreateStreamOptions<T>): ApiStream<T>;
+/**
+ * Collect all chunks from an `ApiStream` into an array.
+ *
+ * Used by CLI adapters and test helpers.  Surfaces error-after-first-chunk
+ * as a thrown `ApiError` / plain error — callers wrap with try/catch.
+ */
+export declare function drainStream<T>(stream: ApiStream<T>): Promise<T[]>;
+/** Result returned by {@link collectWithPhase}. */
+export type CollectResult<T> = {
+    ok: true;
+    chunks: T[];
+} | {
+    ok: false;
+    carrier: BeforeFirstChunkError | AfterFirstChunkError;
+};
+/**
+ * Drain `stream`, tracking whether any chunks were emitted before an error.
+ *
+ * Returns a discriminated result:
+ * - `{ ok: true, chunks }` — stream completed cleanly.
+ * - `{ ok: false, carrier }` — stream threw; `carrier.phase` indicates
+ *   whether the error was before or after the first chunk was produced.
+ *
+ * Transport adapters use this to select the correct §11 in-band carrier.
+ */
+export declare function collectWithPhase<T>(stream: ApiStream<T>): Promise<CollectResult<T>>;
+/**
+ * Returns true when `value` is an `AsyncIterable` (i.e. an `ApiStream`).
+ *
+ * Used by Layer harness dispatch to distinguish streaming from scalar results.
+ */
+export declare function isApiStream(value: unknown): value is ApiStream<unknown>;

package/lib/types.d.ts

@@ -0,0 +1,29 @@
+import { GeneratedSchemas, ComposedSchemas } from '@adhd/apigen-core';
+
+export type { GeneratedSchemas, ComposedSchemas };
+export interface MiddlewareDef<TEnvelope extends object = object, TContext extends object = object> {
+    id: string;
+    envelope?: Record<string, unknown>;
+    createContext?: (ctx: object) => TContext | Promise<TContext>;
+    eventMapping?: Record<string, (event: MiddlewareEvent) => void | Promise<void>>;
+}
+export interface MiddlewareEvent {
+    module: string;
+    method: string;
+    lifecycle: 'start' | 'complete' | 'error';
+    ctx: object;
+    error?: unknown;
+}
+export interface ApiPackageOptions<M extends readonly MiddlewareDef[]> {
+    domainSchemas: GeneratedSchemas;
+    middlewares: readonly [...M];
+    overrides?: Partial<Record<string, Partial<Record<string, boolean>>>>;
+    strict?: boolean;
+}
+export interface ApiPackageResult {
+    schemas: ComposedSchemas;
+    createClient: (envelope: Record<string, unknown>) => Promise<object>;
+}
+export declare class ConfigurationError extends Error {
+    constructor(message: string);
+}

package/lib/validate-layer.d.ts

@@ -0,0 +1,54 @@
+import { ComposedSchemas } from './types';
+import { Layer } from './invoke';
+
+/**
+ * A compose-time Layer that validates `call.domainArgs` and `call.envelope`
+ * against the operation's composed input schema before forwarding to dispatch.
+ *
+ * Place this Layer **innermost** (last in the `layers` array passed to
+ * `createInvoker`) so it runs immediately before dispatch, after all
+ * authentication / authorization Layers have had their chance to inspect (and
+ * reject) the call.
+ *
+ * Short-circuits with `ApiError{ code: 'invalid_argument' }` on any schema
+ * violation.  Delegates to `next()` on success.
+ *
+ * @remarks
+ * This validates **shape**, not **domain correctness** (SPEC §6 necessary-but-
+ * not-sufficient boundary — see module JSDoc).
+ */
+export declare const validateLayer: Layer;
+/**
+ * Typed ctx extension token that carries the `ComposedSchemas` through the
+ * Layer stack to `validateLayer`.
+ *
+ * Usage (by the caller / transport adapter):
+ * ```ts
+ * call.ctx.set(ValidateSchemasToken, schemas)
+ * ```
+ *
+ * `validateLayer` reads it back with `call.ctx.get(ValidateSchemasToken)`.
+ */
+export declare const ValidateSchemasToken: unique symbol;
+declare module './invoke' {
+    interface LayerContext {
+        get(token: typeof ValidateSchemasToken): ComposedSchemas | undefined;
+        set(token: typeof ValidateSchemasToken, value: ComposedSchemas): void;
+    }
+}
+/**
+ * Factory that produces a validation Layer **pre-bound** to a `ComposedSchemas`
+ * map.  Prefer this over the raw `validateLayer` singleton when composing a
+ * static invoker at plugin instantiation time — it avoids the ctx-token
+ * ceremony and makes the Layer entirely self-contained.
+ *
+ * ```ts
+ * const invoke = createInvoker([makeValidateLayer(schemas), authLayer])
+ * ```
+ *
+ * Validation is still necessary-but-not-sufficient (SPEC §6) — it validates
+ * shape, not domain correctness.
+ *
+ * @param schemas - The composed schemas for the target namespace.
+ */
+export declare function makeValidateLayer(schemas: ComposedSchemas): Layer;

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@adhd/apigen-runtime",
+  "version": "0.1.0",
+  "dependencies": {
+    "@adhd/apigen-core": "^0.1.0",
+    "pino": "10.3.1"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}