@adhd/apigen-engine-runtime 0.1.0

package/lib/stream.d.ts

@@ -0,0 +1,88 @@
+import { AfterFirstChunkError, BeforeFirstChunkError } from '@adhd/apigen-base-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/tool-description.d.ts

@@ -0,0 +1,18 @@
+/** The minimal shape this module reads off a composed schema entry. */
+export interface ToolDescriptionSchema {
+    input?: {
+        description?: unknown;
+    };
+}
+/**
+ * Builds the description shown for tool `name` in an MCP `tools/list`
+ * response.
+ *
+ * @param name - The MCP tool name (used as the final fallback).
+ * @param schema - The function's composed schema (as produced by
+ *   `composeSchemas`); `input.description` carries the auto-generated
+ *   envelope/data-wrapper documentation.
+ * @param override - An optional caller-supplied description (e.g. from the
+ *   `toolDescriptions` plugin option), prepended when present.
+ */
+export declare function buildToolDescription(name: string, schema: ToolDescriptionSchema | undefined, override?: string): string;

package/lib/types.d.ts

@@ -0,0 +1,35 @@
+import { GeneratedSchemas, ComposedSchemas } from '@adhd/apigen-core-client';
+
+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>;
+    /**
+     * Release the package's event bus (removes every observer handler). Call
+     * when the package is discarded — hosts that create packages repeatedly
+     * (tests, hot reload, multi-tenant servers) leak handlers otherwise.
+     */
+    dispose: () => void;
+}
+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,19 @@
+{
+  "name": "@adhd/apigen-engine-runtime",
+  "version": "0.1.0",
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "ajv-formats": "2.1.1",
+    "pino": "10.3.1",
+    "@adhd/apigen-core-client": "^0.1.0",
+    "@adhd/apigen-base-logical": "^0.0.1",
+    "@adhd/apigen-base-errors": "^0.1.1",
+    "better-sqlite3": "12.10.0"
+  },
+  "main": "./index.js",
+  "module": "./index.mjs",
+  "typings": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}