@adhd/apigen-core-client 0.2.0 → 0.2.2

package/lib/batch.d.ts

@@ -0,0 +1,89 @@
+import { InlineDiscriminator } from './schema-builders/morph-walk';
+import { Operation, OperationKind, JSONSchema } from './descriptor';
+import { Descriptor, MountedOperation } from './plugin';
+
+/**
+ * Options accepted when deriving `_batch/<kind>` mounts (§2.1).
+ *
+ * `exclude` is the plugin's own opt-out switch — `--opt batch.exclude=...`
+ * (CLI `--use` path) or a literal argument at a hand-wired direct-invocation
+ * call site (§2.1). There is deliberately no other configuration surface
+ * (no runtime flag, no `apigen.config` file — Tenet 1).
+ */
+export interface BatchMountOptions {
+    /** Operation ids to exclude from every `_batch/<kind>` branch set. */
+    exclude?: string[];
+}
+/** One discriminator branch derived from a single batchable `Operation` (§1.2). */
+export interface BatchOperationBranch {
+    /** The literal `operation` value selecting this branch. */
+    operationConst: string;
+    /** The per-item input schema — `op.input` verbatim. */
+    itemsSchema: JSONSchema;
+    /** `BatchItemResult<op.output>` as a JSON Schema fragment (§3/§F3). */
+    resultSchema: JSONSchema;
+}
+/**
+ * Pure `Operation → schema fragment` transform (§1.2). Host-agnostic: takes
+ * only the already-host-neutral `Operation` IR, produces plain JSON Schema.
+ */
+export declare function deriveBatchOperationBranch(op: Operation): BatchOperationBranch;
+/**
+ * Group batchable operations (excluding `opts.exclude`) by `Operation.kind`
+ * (F1). Each distinct kind present gets its own `_batch/<kind>` mount —
+ * `_batch/query`, `_batch/action`, etc. — because `Operation.kind`/`.safe`
+ * are static per-op classifications transports read for wire decisions
+ * (HTTP verb/cacheability, gRPC idempotency), and a single `_batch` mount
+ * whose *actual* kind varies per selected `operation` branch cannot carry
+ * that truthfully (architect review F1).
+ */
+export declare function groupBatchableOperationsByKind(operations: readonly Operation[], opts?: BatchMountOptions): Map<OperationKind, Operation[]>;
+/** The input/output schema pair (+ discriminator, when applicable) for one `_batch/<kind>` mount. */
+export interface BatchKindSchema {
+    input: JSONSchema;
+    output: JSONSchema;
+    /** Present only when ≥2 operations share this kind (a 1-branch `oneOf` is not a union). */
+    discriminator?: InlineDiscriminator;
+}
+/**
+ * Build the input/output schema pair for one `_batch/<kind>` mount (F1).
+ *
+ * - **≥2 ops of that kind:** a real `oneOf` + `InlineDiscriminator` union,
+ *   using the same-document JSON-Pointer mechanism (`morph-walk.ts`), never
+ *   `union.ts`'s $ref/nominal mechanism (§1.1).
+ * - **Exactly 1 op of that kind:** the single branch's shape directly, no
+ *   `oneOf` wrapper — `detectDiscriminator` itself refuses below 2 variants
+ *   (§1.1's "edge case the 0.0.1 draft missed"), and a one-variant `oneOf`
+ *   is not a union.
+ *
+ * Throws if `ops` is empty — callers (mount-building) must never invoke this
+ * for a kind with zero operations; `groupBatchableOperationsByKind` never
+ * produces an empty group.
+ */
+export declare function buildBatchKindSchema(ops: readonly Operation[]): BatchKindSchema;
+/**
+ * One synthetic `_batch/<kind>` operation shape, minus `handler` — mounting
+ * a real, request-servable handler requires wiring `invokeBatch`
+ * (`@adhd/apigen-engine-runtime`), which is TS-runtime plumbing this
+ * (host-agnostic) module deliberately does not depend on. A `MountCapability`
+ * implementation composes `{ ...op, handler: ... }` using this fragment plus
+ * its own `invokeBatch` wiring (see BATCH_0.0.1.md §3/§5).
+ */
+export type BatchKindOperation = Omit<MountedOperation, 'handler'> & {
+    kind: OperationKind;
+    /** Ids of the operations this `_batch/<kind>` mount can fan out over. */
+    operationIds: string[];
+};
+/**
+ * Derive one `_batch/<kind>` synthetic mount per distinct kind present in the
+ * batchable operation set (F1). Refuses to mount anything for a descriptor
+ * with zero batchable operations (empty array — §1.1's "edge case the 0.0.1
+ * draft missed" restated per-kind rather than for a single global mount).
+ *
+ * `kind`/`safe` are truthful per mount (query kinds are `safe: true`;
+ * everything else defaults `safe: false` per the existing `Operation.safe`
+ * default-from-kind rule) — never the single hardcoded
+ * `kind:'action', safe:false` the 0.0.1 draft proposed for one omnibus
+ * `_batch` mount (architect review F1).
+ */
+export declare function buildBatchMountedOperations(descriptor: Descriptor, opts?: BatchMountOptions): BatchKindOperation[];

package/lib/plugin.d.ts

@@ -1,5 +1,5 @@
 import { PluginLanguage } from './types';
-import { Operation, JSONSchema } from './descriptor';
+import { Operation, OperationKind, JSONSchema, TypeText } from './descriptor';
 
 /**
  * The four canonical transport carriers apigen knows about (SPEC §5/§7/§9.1).
@@ -248,6 +248,49 @@ export interface LayerCapability {
      */
     layer(call: Call, next: Next): Promise<Result> | AsyncIterable<Chunk>;
 }
+/**
+ * Runtime dispatch options a {@link MountHostBridge} hands back to a mount
+ * plugin's handler — structurally equivalent to `apigen-engine-runtime`'s
+ * real `InvokeOptions` (duck-typed here, never imported: `apigen-core-client`
+ * is a lower tier than `apigen-engine-runtime` and must never depend upward
+ * on it — batch-rollout architect review, Finding 3).
+ */
+export interface MountHostBridgeInvokeOptions {
+    /** The live function table (op-id → implementation), spanning EVERY package the host serves. */
+    fns: Record<string, (...args: unknown[]) => unknown>;
+    /** Composed schemas (op-id → schema), spanning every package the host serves. */
+    schemas: Record<string, unknown>;
+    /** Optional client factory (session-ctx middleware), when the host has one. */
+    createClient?: (envelope: Record<string, unknown>) => Promise<unknown>;
+}
+/**
+ * A host-supplied bridge letting a `MountCapability`'s handler invoke OTHER
+ * operations already registered on that host — the missing piece a fan-out
+ * mount (e.g. `_batch/<kind>`) needs that a pure mount like `/meta/health` or
+ * `/meta/openapi` never did (batch-rollout design note + architect review).
+ *
+ * `invoke`/`invokeOptions` are structurally equivalent to
+ * `apigen-engine-runtime`'s real `InvokeFn`/`InvokeOptions` pair so a plugin
+ * can hand them straight to `invokeBatch(hostBridge.invoke, fnName, calls,
+ * hostBridge.invokeOptions, batchOptions)` with zero adapter shim (Finding 1
+ * of the review) — the tier boundary is preserved by keeping this an inline
+ * structural type, never an import from `apigen-engine-runtime` (Finding 3).
+ */
+export interface MountHostBridge {
+    /**
+     * Invoke `fnName` (any operation id already registered on this host, from
+     * any package) with the given domain call, through the SAME composed
+     * `--use` Layer stack (auth/logging/validate) every other request goes
+     * through — never a bypass of it.
+     */
+    invoke(fnName: string, call: {
+        domainArgs: Record<string, unknown>;
+        envelope: Record<string, unknown>;
+        signal?: AbortSignal;
+    }, opts: MountHostBridgeInvokeOptions): Promise<unknown>;
+    /** The host's merged, package-spanning `InvokeOptions`-equivalent — pass straight to `invokeBatch`. */
+    invokeOptions: MountHostBridgeInvokeOptions;
+}
 /**
  * **`mount`** capability — add synthetic operations to the descriptor
  * (SPEC §7.1 / §7.2b / §7.2c).
@@ -255,7 +298,7 @@ export interface LayerCapability {
  * A `MountCapability` is loaded via `--use <plugin>` and contributes extra
  * `Operation`-like entries (with an in-process `handler`) that flow through the
  * harness and Layer stack exactly like extracted operations.  Typical uses:
- * `/meta/openapi`, `/meta/health`, version endpoints.
+ * `/meta/openapi`, `/meta/health`, version endpoints, `_batch/<kind>` fan-out.
  */
 export interface MountCapability {
     /**
@@ -264,11 +307,18 @@ export interface MountCapability {
      * `MountedOperation` extends `Operation` with an in-process `handler` and
      * an optional `transports` filter (default: all transports).
      *
-     * @param descriptor - The current merged descriptor (read-only).
-     * @param opts       - Plugin-specific options.
+     * @param descriptor  - The current merged descriptor (read-only).
+     * @param opts        - Plugin-specific options.
+     * @param hostBridge  - (BATCH_0.0.1.md §2/§F1 rollout) Optional, additive —
+     *   a host-supplied bridge letting the returned operations' handlers invoke
+     *   OTHER operations on this host (e.g. a `_batch/<kind>` fan-out target).
+     *   Omitted by plugins (like `health`/`openapi`) that never need it; a
+     *   plugin whose handler DOES need cross-op invocation (batch) must throw a
+     *   clear error if it's undefined rather than silently no-op, since that
+     *   means the host hasn't wired hostBridge support yet.
      * @returns           Array of `MountedOperation`s; may be empty.
      */
-    operations(descriptor: Descriptor, opts?: Record<string, unknown>): MountedOperation[];
+    operations(descriptor: Descriptor, opts?: Record<string, unknown>, hostBridge?: MountHostBridge): MountedOperation[];
 }
 /**
  * A synthetic operation contributed by a {@link MountCapability}.
@@ -296,6 +346,50 @@ export type MountedOperation = Operation & {
      */
     handler(call: Call): unknown | Promise<unknown> | AsyncIterable<Chunk>;
 };
+/**
+ * Overridable fields accepted by {@link syntheticOp}. Every field has a safe
+ * default so a minimal mount (like health's `_meta/health`) needs to specify
+ * only what actually differs from a zero-input, zero-output `action`.
+ */
+export interface SyntheticOpFields {
+    /** @default 'action' */
+    kind?: OperationKind;
+    /** @default `kind === 'query'` (mirrors {@link Operation.safe}'s own default-from-kind rule) */
+    safe?: boolean;
+    /** @default false */
+    async?: boolean;
+    /** @default false */
+    streaming?: boolean;
+    /** @default {} */
+    input?: JSONSchema;
+    /** @default {} */
+    output?: JSONSchema;
+    /** @default {} */
+    envelope?: JSONSchema;
+    /** @default null */
+    typeText?: TypeText | null;
+    /** @default undefined (all transports) */
+    transports?: Transport[];
+    hasCtx?: boolean;
+}
+/**
+ * Build the common ~10-field {@link Operation} boilerplate for a synthetic
+ * mount-contributed operation (F2 — `apigen-core-client/src/lib/plugin.ts`
+ * JSDoc previously referenced this as though it already existed; it did not).
+ *
+ * `id` is `"<namespace>/<path...>"` (e.g. `'_meta/health'`, `'_batch/query'`).
+ * Per the existing `_meta/*` mount convention (health/openapi, pre-retrofit),
+ * a leading run of underscores on the first segment marks a synthetic
+ * namespace in the *id* but is stripped when tokenizing the namespace
+ * {@link Segment} itself — `'_meta/health'` → `namespace: {raw:'meta',…}`,
+ * `path: [{raw:'health',…}]`, matching what both plugins already produced
+ * by hand.
+ *
+ * Returns everything `MountedOperation` needs except `handler` — the caller
+ * supplies that (it's the one part that's genuinely plugin-specific) via
+ * `{ ...syntheticOp(id, descriptor, fields), handler: ... }`.
+ */
+export declare function syntheticOp(id: string, descriptor: Descriptor, fields?: SyntheticOpFields): Omit<MountedOperation, 'handler'>;
 /**
  * **`envelope`** capability — declare request/response side-channel fields
  * (SPEC §7.1 / §9 / §9.1).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/apigen-core-client",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "dependencies": {
     "ts-morph": "^23.0.0",
     "ts-json-schema-generator": "^2.3.0",