@adhd/apigen-engine-runtime 0.2.0 → 0.2.1

package/lib/batch.d.ts

@@ -0,0 +1,96 @@
+import { Call, InvokeFn, InvokeOptions } from './invoke';
+
+/** Concurrency ceiling used when the caller doesn't request one. */
+export declare const BATCH_DEFAULT_CONCURRENCY = 4;
+/**
+ * Hard cap on requested concurrency, enforced regardless of what the caller
+ * asks for (§3 — "Concurrency ceiling is framework-enforced, not advisory",
+ * the direct lesson of `BUG-AGENTMCP-TRIAGE-CONCURRENCY-001`'s unbounded
+ * fan-out incident).
+ */
+export declare const BATCH_MAX_CONCURRENCY = 32;
+/**
+ * Options accepted by {@link invokeBatch} (§3).
+ *
+ * The JSON-Schema-describable wire-contract half of this shape (what a
+ * non-TS host implements against) is specified independently in
+ * BATCH_0.0.1.md §F3/§5 and `apigen-core-client`'s `buildBatchKindSchema`
+ * branch shape — this TS interface is the runtime-only mirror of it.
+ */
+export interface BatchOptions {
+    /**
+     * Caller-requested fan-out width. Clamped to `[1, BATCH_MAX_CONCURRENCY]`
+     * — never honored above the hard cap, and forced to `1` for
+     * `mode: 'serial' | 'chained'`.
+     * @default BATCH_DEFAULT_CONCURRENCY
+     */
+    concurrency?: number;
+    /**
+     * - `'parallel'` (default) — up to `concurrency` items in flight at once.
+     * - `'serial'` — one item at a time, in order; a failure does NOT stop
+     *   later items unless `onItemError: 'abort'` is also set.
+     * - `'chained'` — one item at a time, in order, and a failure ALWAYS stops
+     *   every remaining item (each result: `rejected`, reason: an "upstream
+     *   item failed" error) regardless of `onItemError` — the DAG
+     *   `depends_on`-style behavior §0's motivating incident hand-built
+     *   (`BUG-AGENTMCP-TRIAGE-CONCURRENCY-001`). `calls` carries no explicit
+     *   dependency edges in v1; `'chained'` is the single linear-chain case of
+     *   that pattern, not a general DAG — a richer per-item dependency graph is
+     *   out of scope for v1 (see BATCH_0.0.1.md §7 open-question 3's
+     *   `batchId`/interactive-cancel deferral, same rationale).
+     * @default 'parallel'
+     */
+    mode?: 'parallel' | 'serial' | 'chained';
+    /**
+     * `'continue'` (default) — `Promise.allSettled` semantics: every item
+     * runs regardless of earlier failures.
+     * `'abort'` — once ANY item rejects, every not-yet-started item resolves
+     * as `rejected` without ever being invoked (in-flight items under
+     * `'parallel'` are allowed to finish; they are not force-cancelled by this
+     * setting alone — see `itemTimeoutMs` / the batch's own `AbortSignal` for
+     * that).
+     * @default 'continue'
+     */
+    onItemError?: 'continue' | 'abort';
+    /**
+     * (F4) Per-item timeout in milliseconds. When set, each item gets its own
+     * `AbortSignal` — DERIVED/LINKED from that item's `Call.signal` (the
+     * whole-batch/whole-request signal): aborting the batch signal aborts the
+     * item immediately, and the item additionally self-aborts after
+     * `itemTimeoutMs` if it hasn't settled. This composes rather than bypasses
+     * whole-batch cancellation (§3's "two distinct, composable operations").
+     */
+    itemTimeoutMs?: number;
+}
+/** Per-item result shape (§3). Mirrors `apigen-core-client`'s `batchItemResultSchema` wire fragment. */
+export type BatchItemResult<T = unknown> = {
+    index: number;
+    status: 'fulfilled';
+    value: T;
+} | {
+    index: number;
+    status: 'fulfilled';
+    chunks: unknown[];
+} | {
+    index: number;
+    status: 'rejected';
+    reason: unknown;
+    chunksDelivered?: number;
+};
+/**
+ * Fan out `calls.length` invocations of `fnName` through the already-composed
+ * `invoke` function `createInvoker(layers)` returned — pure orchestration,
+ * never a bypass of the Layer stack (§3).
+ *
+ * @param invoke   - The composed invoke function from `createInvoker(layers)`.
+ * @param fnName   - The operation name to invoke for every item.
+ * @param calls    - One {@link Call} per item — each carries its own
+ *                   `domainArgs`; `signal`/`envelope`/`ctx` are typically the
+ *                   same shared batch-level values across all items (F4:
+ *                   per-item cancellation is derived from `call.signal`, not
+ *                   a second signal the caller must fabricate per item).
+ * @param opts     - `InvokeOptions` — same runtime dispatch options passed to
+ *                   `invoke` for every item.
+ * @param batch    - {@link BatchOptions} — concurrency/mode/onItemError/itemTimeoutMs.
+ */
+export declare function invokeBatch(invoke: InvokeFn, fnName: string, calls: readonly Call[], opts: InvokeOptions, batch?: BatchOptions): Promise<BatchItemResult[]>;

package/lib/package-invoker.d.ts

@@ -16,7 +16,22 @@ export interface UsePlugin {
             operations: (descriptor: {
                 host: string;
                 operations: unknown[];
-            }, opts?: Record<string, unknown>) => Array<{
+            }, opts?: Record<string, unknown>, hostBridge?: {
+                invoke(fnName: string, call: {
+                    domainArgs: Record<string, unknown>;
+                    envelope: Record<string, unknown>;
+                    signal?: AbortSignal;
+                }, opts: {
+                    fns: Record<string, unknown>;
+                    schemas: Record<string, unknown>;
+                    createClient?: (envelope: Record<string, unknown>) => Promise<unknown>;
+                }): Promise<unknown>;
+                invokeOptions: {
+                    fns: Record<string, unknown>;
+                    schemas: Record<string, unknown>;
+                    createClient?: (envelope: Record<string, unknown>) => Promise<unknown>;
+                };
+            }) => Array<{
                 id: string;
                 transports?: string[];
                 handler: (call: unknown) => unknown;

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@adhd/apigen-engine-runtime",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "dependencies": {
     "ajv": "^8.20.0",
     "ajv-formats": "2.1.1",
     "pino": "10.3.1",
-    "@adhd/apigen-core-client": "^0.2.0",
+    "@adhd/apigen-core-client": "^0.2.1",
     "@adhd/apigen-base-logical": "^0.1.0",
     "@adhd/apigen-base-errors": "^0.2.0",
-    "@adhd/apigen-engine-naming": "^0.2.0",
+    "@adhd/apigen-engine-naming": "^0.2.1",
     "better-sqlite3": "12.10.0"
   },
   "main": "./index.js",