@adhd/apigen-engine-runtime 0.1.2 → 0.1.4

package/lib/dispatch-for-plan.d.ts

@@ -0,0 +1,9 @@
+import { OpPlan } from './op-plan';
+import { Call as RuntimeCall, InvokeFn, InvokeOptions, LayerResult } from './invoke';
+
+/**
+ * Resolve one dispatch for `plan`, given the package's composed `invoke`
+ * (`InvokeFn`, e.g. from `createPackageInvoker`) and a partial runtime `Call`
+ * (minus `operation`/`ctx`, per the `TransportAdapter` contract).
+ */
+export declare function dispatchForPlan(plan: OpPlan, invoke: InvokeFn, call: Omit<RuntimeCall, 'operation' | 'ctx'>, opts: InvokeOptions): Promise<LayerResult>;

package/lib/op-plan.d.ts

@@ -0,0 +1,100 @@
+import { LayerResult } from './invoke';
+import { ParamInfo } from './describe-params';
+import { HttpVerb, ProjectionConfig } from '@adhd/apigen-engine-naming';
+import { Call as CoreClientCall, ComposedSchemas, MountedOperation, Operation, Transport } from '@adhd/apigen-core-client';
+
+/** One §9.1 envelope side-channel field, projected to every transport binding. */
+export interface OpPlanEnvelopeField {
+    /** The bare field name as it appears in the composed schema. */
+    field: string;
+    /** pluginId resolved from `x-apigen-envelope` metadata (defaults to `'adhd'`). */
+    pluginId: string;
+    /** `x-<pluginId>-<field>` — used verbatim for HTTP headers and MCP `_meta` keys. */
+    httpHeader: string;
+    /** Same string as `httpHeader` — an explicit alias so call sites self-document. */
+    mcpMetaKey: string;
+    /** `--<pluginId>-<field>` CLI flag. */
+    cliFlag: string;
+    /** `APIGEN_<PLUGINID>_<FIELD>` env-var fallback. */
+    envVar: string;
+}
+/**
+ * One resolved `--flag` for a command, keyed by its argv name (without the
+ * leading `--`) — the same shape `apigen-plugin-cli-output`'s `FlagSpec`
+ * carries, computed once here instead of per-plugin (F2).
+ */
+export interface OpPlanCliFlag {
+    /** The domain param name or envelope field name in camelCase. */
+    camelKey: string;
+    kind: 'domain' | 'envelope';
+    valueKind: 'boolean' | 'json' | 'string';
+    /** (envelope only) `APIGEN_<PLUGINID>_<FIELD>` fallback when the flag is absent. */
+    envVar?: string;
+}
+/**
+ * A fully-resolved, transport-complete plan for one `Operation` (proposal §3a).
+ *
+ * Computed ONCE per op — never re-derived per request — from the `Operation`
+ * and its composed schema. `transport` is stamped by the caller (F3); it is
+ * never inferred or hardcoded inside this module.
+ */
+export interface OpPlan {
+    /** The canonical (or mounted) operation descriptor this plan was built from. */
+    op: Operation;
+    /** The transport this plan was resolved FOR — stamped by the caller (F3). */
+    transport: Transport;
+    http: {
+        verb: HttpVerb;
+        route: string;
+    };
+    mcp: {
+        name: string;
+    };
+    cli: {
+        path: string[];
+    };
+    grpc: {
+        package: string;
+        service: string;
+        method: string;
+    };
+    /** Domain-param summary; `undefined` for a mount op (no composed schema exists). */
+    params?: ParamInfo[];
+    /** §9.1 envelope fields, one entry per non-`data` top-level input property. */
+    envelope: OpPlanEnvelopeField[];
+    /** The precomputed `--flag` table, keyed by argv flag name (no leading `--`). */
+    cliFlags: Map<string, OpPlanCliFlag>;
+    /** True when the underlying export is async-iterable/streaming (`Operation.streaming`). */
+    streaming: boolean;
+    /** True when `op` is a `MountedOperation` (a `--use` mount capability, not an extracted source op). */
+    isMount: boolean;
+    /**
+     * Present only when `isMount` is true — the mount's `handler`, normalised
+     * to always return a `Promise<LayerResult>` (its raw return type is
+     * `unknown | Promise<unknown> | AsyncIterable<Chunk>` — see
+     * `MountedOperation.handler`). Takes the core-client `Call` shape;
+     * `dispatchForPlan` is responsible for adapting the runtime `Call` into
+     * this shape and stamping `transport` from `plan.transport` (F3).
+     */
+    mountHandler?: (call: CoreClientCall) => Promise<LayerResult>;
+}
+export interface BuildOpPlanInput {
+    /** The canonical operation descriptor, or a `MountedOperation` contributed by a `--use` mount plugin. */
+    op: Operation | MountedOperation;
+    /**
+     * The composed schema entry for `op`. Omitted for a mount op — mount ops
+     * are synthetic and never flow through `composeSchemas()`, so no entry
+     * exists for them in a package's `ComposedSchemas` map.
+     */
+    schema?: ComposedSchemas[string];
+    /** The transport this plan is being resolved for (F3 — stamped by the caller, never inferred). */
+    transport: Transport;
+    /** Optional per-op projection overrides (`--opt http.verb.<id>=GET`, SPEC §5). */
+    projection?: ProjectionConfig;
+}
+/**
+ * Resolve `input.op` (+ its composed schema, when present) into a
+ * transport-complete `OpPlan`. Call this ONCE per op, at package/transport
+ * wiring time — never per request.
+ */
+export declare function buildOpPlan(input: BuildOpPlanInput): OpPlan;

package/lib/package-invoker.d.ts

@@ -0,0 +1,50 @@
+import { ComposedSchemas } from './types';
+import { Layer, InvokeFn } from './invoke';
+
+/**
+ * A loaded `--use` plugin object (SPEC §7.1). We only depend on the shape we
+ * actually consume here (layer / mount capabilities) so the runtime stays
+ * decoupled from the full `Plugin` type surface.
+ */
+export interface UsePlugin {
+    id: string;
+    capabilities?: {
+        layer?: {
+            layer: (call: unknown, next: () => Promise<unknown>) => Promise<unknown> | AsyncIterable<unknown>;
+        };
+        mount?: {
+            operations: (descriptor: {
+                host: string;
+                operations: unknown[];
+            }, opts?: Record<string, unknown>) => Array<{
+                id: string;
+                transports?: string[];
+                handler: (call: unknown) => unknown;
+            }>;
+        };
+    };
+}
+/** Per-`--use` plugin option bag, keyed by plugin id (carried on `options.useOptions`). */
+export type UseOptions = Record<string, Record<string, unknown>>;
+/**
+ * Read the loaded `--use` plugins off `input.options`. The CLI loads the
+ * specifiers into real plugin objects and threads them here (`RunInput`
+ * carries no dedicated field, so they ride on `options.usePlugins`).
+ */
+export declare function readUsePlugins(options: Record<string, unknown>): UsePlugin[];
+export declare function readUseOptions(options: Record<string, unknown>): UseOptions;
+/**
+ * Adapt a core `LayerCapability.layer` (which receives the SPEC §7.1 `Call`
+ * shape with `.data`) into a runtime {@link Layer} (which threads the §8.1
+ * `Call` with `.domainArgs`). The runtime Call already carries `operation.id`,
+ * `envelope`, `ctx`, and `signal`; we additionally surface `.data` (an alias of
+ * `domainArgs`) so layers written against either shape see their fields.
+ */
+export declare function adaptCoreLayer(cap: NonNullable<NonNullable<UsePlugin['capabilities']>['layer']>): Layer;
+/**
+ * Compose the request-path invoker for one package: the `--use` layer
+ * plugins (outermost-first, in declaration order) wrapping the central
+ * validate-Layer (innermost, immediately before dispatch — BUG-APIGEN-009).
+ * Built ONCE per package, not per request.
+ */
+export declare function createPackageInvoker(schemas: ComposedSchemas, usePlugins: UsePlugin[]): InvokeFn;

package/lib/transport-adapter.d.ts

@@ -0,0 +1,24 @@
+import { OpPlan } from './op-plan';
+import { Call, LayerResult } from './invoke';
+
+export interface TransportAdapter<Raw = unknown> {
+    /**
+     * Register `plan`'s projected route/tool/command/method with this
+     * transport's underlying server/CLI/router, wiring inbound requests to
+     * `dispatch`. Called ONCE per `OpPlan`, at server/CLI wiring time.
+     */
+    registerRoute(plan: OpPlan, dispatch: (call: Omit<Call, 'operation' | 'ctx'>) => Promise<LayerResult>): void;
+    /**
+     * Marshal the transport-native inbound request `raw` into the runtime
+     * `Call` shape (minus `operation`/`ctx`, filled in by the dispatch path).
+     */
+    readCall(raw: Raw, plan: OpPlan): Omit<Call, 'operation' | 'ctx'> | Promise<Omit<Call, 'operation' | 'ctx'>>;
+    /**
+     * Marshal a resolved `LayerResult` (the value `dispatch`'s returned
+     * Promise resolved to — F1) back onto the transport-native outbound
+     * carrier `raw`.
+     */
+    writeResult(raw: Raw, result: LayerResult, plan: OpPlan): void | Promise<void>;
+    /** Marshal a thrown error back onto the transport-native outbound carrier `raw`. */
+    writeError(raw: Raw, err: unknown, plan: OpPlan): void | Promise<void>;
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@adhd/apigen-engine-runtime",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "2.1.1",
     "pino": "10.3.1",
-    "@adhd/apigen-core-client": "^0.1.2",
-    "@adhd/apigen-base-logical": "^0.0.3",
-    "@adhd/apigen-base-errors": "^0.1.3",
+    "@adhd/apigen-core-client": "^0.1.4",
+    "@adhd/apigen-base-logical": "^0.0.5",
+    "@adhd/apigen-base-errors": "^0.1.5",
+    "@adhd/apigen-engine-naming": "^0.1.4",
     "better-sqlite3": "12.10.0"
   },
   "main": "./index.js",

package/test-support/parity-harness.d.ts

@@ -0,0 +1,108 @@
+import { ChildProcess } from 'node:child_process';
+
+/**
+ * One golden-fixture case. `name` is the stable key under which its result
+ * lands in the snapshot — it must be unique within a fixture list so a
+ * snapshot round-trips through `JSON.stringify`/parse without collisions.
+ *
+ * The proposal's fixture classes (safe/scalar GET-hoist, unsafe/mutating
+ * scalar, session/envelope, `streaming:true`, `--use` mount, plus one
+ * validation-failure and one domain `ApiError` per class) are just
+ * `GoldenFixture` values a transport migration's own spec constructs; this
+ * harness has no opinion on fixture shape beyond "has a stable name".
+ */
+export interface GoldenFixture<TInput = unknown> {
+    /** Stable snapshot key. Must be unique within one fixture list. */
+    readonly name: string;
+    /** Whatever the driver needs to make the call (request shape is driver-defined). */
+    readonly input: TInput;
+}
+/**
+ * Drives one fixture through a REAL consumer protocol
+ * ([def:real-consumer-protocol]) and returns whatever that protocol yielded
+ * (parsed JSON body, tool-call result, stdout+exit-code, …). Implementations
+ * live in each transport's own spec — this harness only orchestrates calls
+ * through the interface, never reaches into transport/plugin internals.
+ */
+export interface ParityDriver<TInput = unknown, TOutput = unknown> {
+    invoke(fixture: GoldenFixture<TInput>): Promise<TOutput>;
+}
+/** A captured (or committed) golden snapshot: fixture name -> captured result. */
+export type GoldenSnapshot<TOutput = unknown> = Record<string, TOutput>;
+/**
+ * Drives `driver` over every fixture, in order, and records each result
+ * keyed by `fixture.name`. Used BOTH to capture the pre-migration golden
+ * snapshot (commit the result) and to re-capture post-migration (feed the
+ * result to {@link assertParity}).
+ *
+ * Fails loudly — never silently — on the two shapes that would make a
+ * "parity" claim meaningless: an empty fixture list (nothing was proven) and
+ * a duplicate fixture name (a later result would silently clobber an
+ * earlier one in the snapshot object).
+ */
+export declare function captureGolden<TInput = unknown, TOutput = unknown>(driver: ParityDriver<TInput, TOutput>, fixtures: readonly GoldenFixture<TInput>[]): Promise<GoldenSnapshot<TOutput>>;
+/** Thrown by {@link assertParity} when a recapture diverges from the committed snapshot. */
+export declare class ParityMismatchError extends Error {
+    /** Fixture names that diverged (missing, unexpectedly added, or value-mismatched). */
+    readonly fixtureNames: readonly string[];
+    constructor(message: string, fixtureNames: readonly string[]);
+}
+/**
+ * Asserts `recapture` deep-equals `committed`, fixture-by-fixture
+ * ([inv:byte-identical]). Uses `node:util`'s `isDeepStrictEqual` — strict
+ * structural equality (type-sensitive, own-enumerable-key-sensitive: e.g.
+ * `{a: undefined}` is NOT equal to `{}`) so a silent `undefined`⇄absent or
+ * `"1"`⇄`1` drift is caught, not coerced away.
+ *
+ * Reports every divergence in one error (missing fixtures, unexpectedly
+ * added fixtures, and per-fixture value mismatches) rather than failing on
+ * the first one, so a broken migration's full blast radius is visible from
+ * a single test failure.
+ */
+export declare function assertParity<TOutput = unknown>(committed: GoldenSnapshot<TOutput>, recapture: GoldenSnapshot<TOutput>): void;
+/** Options for {@link proveNegativeControl}. */
+export interface NegativeControlOptions {
+    /**
+     * Working directory `git apply` runs in — the repository root the
+     * committed `patchPath` is expressed relative to. Defaults to
+     * `process.cwd()`.
+     */
+    cwd?: string;
+}
+/**
+ * Proves a parity suite is an actual gate, not dead weight
+ * ([inv:negative-control], AGENTS.md §7 pt 2): applies `patchPath` (a
+ * one-line regression, `git apply`), asserts `runner()` now REJECTS (goes
+ * RED), reverts the patch (`git apply -R`) even if the RED assertion itself
+ * fails, then asserts `runner()` resolves again (goes GREEN).
+ *
+ * `runner` is whatever re-proves parity for the migration under test —
+ * typically "recapture via the driver, then `assertParity` against the
+ * committed snapshot". It must REJECT (throw / return a rejected promise) to
+ * signal RED and resolve to signal GREEN.
+ *
+ * Throws if the patch fails to turn the suite RED (the gate would not have
+ * caught the regression) — this is the one case `proveNegativeControl`
+ * itself must fail loudly on, independent of whatever `runner` does. Repo
+ * rule: never `git stash` / `git reset --hard` — patch apply/revert is the
+ * only mutation performed, and it is always undone in a `finally`.
+ */
+export declare function proveNegativeControl(runner: () => void | Promise<void>, patchPath: string, opts?: NegativeControlOptions): Promise<void>;
+/**
+ * Bulletproof teardown for a spawned test server (`flask_server.py`,
+ * `grpc_server.py`, …): sends `SIGTERM`, waits for the process's real `exit`
+ * event, and escalates to `SIGKILL` if it hasn't exited within
+ * `gracefulTimeoutMs` (BUG-APIGEN-TEST-SUBPROCESS-TEARDOWN-LEAK-001).
+ *
+ * The bug this fixes: a bare `proc.kill('SIGTERM')` racing a `setTimeout`
+ * that resolves regardless of whether the process actually died leaves an
+ * unresponsive Python process running — it binds a fixed test port and
+ * survives to answer (with stale/pre-migration behavior) a later, unrelated
+ * test suite that happens to reuse the same port. Resolving here ONLY on the
+ * real `exit` event (never on a bare timer) plus the `SIGKILL` escalation
+ * guarantees the process is gone, and gone within a bounded deadline, before
+ * the caller proceeds.
+ *
+ * No-op if the process has already exited.
+ */
+export declare function killChildProcess(proc: ChildProcess, gracefulTimeoutMs?: number): Promise<void>;