@cleocode/core 2026.6.13 → 2026.6.14

package/dist/playbooks/guarded-deterministic-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-deterministic-runner.js","sourceRoot":"","sources":["../../src/playbooks/guarded-deterministic-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAIH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,qCAAqC,GAAsB,MAAM,CAAC,MAAM,CAAC;IACpF,IAAI;IACJ,OAAO;IACP,UAAU;IACV,QAAQ;IACR,MAAM;IACN,IAAI;IACJ,OAAO;IACP,OAAO;IACP,QAAQ;IACR,MAAM;IACN,SAAS;CACV,CAAC,CAAC;AAgEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,gCAAgC,CAC9C,IAAuC;IAEvC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC;IACvB,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,KAAgC;YACxC,IAAI,CAAC;gBACH,oEAAoE;gBACpE,yEAAyE;gBACzE,sEAAsE;gBACtE,8BAA8B;gBAC9B,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC;oBACtC,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC;oBACrB,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtD,GAAG,CAAC,KAAK,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACtD,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC3E,CAAC,CAAC;gBACH,qEAAqE;gBACrE,wDAAwD;gBACxD,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBACtB,OAAO;wBACL,MAAM,EAAE,SAAS;wBACjB,MAAM,EAAE;4BACN,CAAC,GAAG,KAAK,CAAC,MAAM,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM;4BACzC,CAAC,GAAG,KAAK,CAAC,MAAM,WAAW,CAAC,EAAE,MAAM,CAAC,IAAI;yBAC1C;qBACF,CAAC;gBACJ,CAAC;gBACD,OAAO;oBACL,MAAM,EAAE,SAAS;oBACjB,MAAM,EAAE;wBACN,CAAC,GAAG,KAAK,CAAC,MAAM,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM;wBACzC,CAAC,GAAG,KAAK,CAAC,MAAM,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM;wBACzC,CAAC,GAAG,KAAK,CAAC,MAAM,WAAW,CAAC,EAAE,MAAM,CAAC,IAAI;qBAC1C;oBACD,KAAK,EACH,uBAAuB,KAAK,CAAC,MAAM,cAAc,KAAK,CAAC,OAAO,WAAW;wBACzE,GAAG,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,IAAI,EAAE,EAAE;iBAC/E,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,0EAA0E;gBAC1E,gDAAgD;gBAChD,OAAO;oBACL,MAAM,EAAE,SAAS;oBACjB,MAAM,EAAE,EAAE;oBACV,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBACxD,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/playbooks/index.d.ts

@@ -11,7 +11,9 @@
  * @task T1239 — meta-agent infrastructure (epic T1232)
  */
 export { AGENT_TIER_META, type AgentDispatcher, CoreAgentDispatcher, type CoreAgentDispatcherOptions, createAgentDispatcher, type DispatchContext, type DispatchResult, resolveMetaAgent, } from './agent-dispatcher.js';
+export { type CantbookProfilePin, cantbookNodeSystemKey, hasCantbookProfilePin, type ResolveCantbookNodeProfileInput, resolveCantbookNodeProfile, } from './cantbook-profile.js';
 export type { playbookCoreOps } from './ops.js';
+export { type MaybePiRunnerDeps, maybeCreatePiRunner } from './pi-runner-wiring.js';
 export { listPlaybooks, PlaybookNotFoundError, type PlaybookTier, type ResolvedPlaybook, type ResolvePlaybookOptions, resolvePlaybook, } from './playbook-resolver.js';
 export { createSkillNodeExecutor, ISOLATION_CONTEXT_KEY, runSkillNodeOrSpawn, type SkillNodeDispatchInput, type SkillNodeExecutorOptions, type SubprocessSpawnExecutor, } from './skill-node-executor.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/playbooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/playbooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/playbooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,mBAAmB,EACnB,KAAK,0BAA0B,EAC/B,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAM/B,OAAO,EACL,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,+BAA+B,EACpC,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAKhD,OAAO,EAAE,KAAK,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAIhC,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,0BAA0B,CAAC"}

package/dist/playbooks/index.js

@@ -11,6 +11,16 @@
  * @task T1239 — meta-agent infrastructure (epic T1232)
  */
 export { AGENT_TIER_META, CoreAgentDispatcher, createAgentDispatcher, resolveMetaAgent, } from './agent-dispatcher.js';
+// Cantbook stage LLM-profile resolution — the seam the production cantbook
+// dispatchers call to resolve a node's `profile:` / `model:` / `provider:` pin
+// through the E9 chokepoint (`resolveLLMForSystem`). Gate-13: resolves metadata
+// only, never constructs a transport (T11759 · M4).
+export { cantbookNodeSystemKey, hasCantbookProfilePin, resolveCantbookNodeProfile, } from './cantbook-profile.js';
+// Pi in-process runner wiring — default-OFF, lazy-imported Pi `SkillRunner` the
+// production cantbook dispatchers pass into `runSkillNodeOrSpawn`'s `runner`
+// slot (T11945 · M4). Exported here (the eager core graph) so its live binding
+// is initialised before `internal.ts` re-exports it.
+export { maybeCreatePiRunner } from './pi-runner-wiring.js';
 export { listPlaybooks, PlaybookNotFoundError, resolvePlaybook, } from './playbook-resolver.js';
 // Skill-node executor — injects the in-process SkillExecutorAdapter as the
 // dispatcher's executor while retaining subprocess-spawn for isolation nodes

package/dist/playbooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/playbooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,eAAe,EAEf,mBAAmB,EAEnB,qBAAqB,EAGrB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EACL,aAAa,EACb,qBAAqB,EAIrB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAEhC,2EAA2E;AAC3E,6EAA6E;AAC7E,0BAA0B;AAC1B,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,GAIpB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/playbooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EACL,eAAe,EAEf,mBAAmB,EAEnB,qBAAqB,EAGrB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,2EAA2E;AAC3E,+EAA+E;AAC/E,gFAAgF;AAChF,oDAAoD;AACpD,OAAO,EAEL,qBAAqB,EACrB,qBAAqB,EAErB,0BAA0B,GAC3B,MAAM,uBAAuB,CAAC;AAE/B,gFAAgF;AAChF,6EAA6E;AAC7E,+EAA+E;AAC/E,qDAAqD;AACrD,OAAO,EAA0B,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EACL,aAAa,EACb,qBAAqB,EAIrB,eAAe,GAChB,MAAM,wBAAwB,CAAC;AAChC,2EAA2E;AAC3E,6EAA6E;AAC7E,0BAA0B;AAC1B,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,mBAAmB,GAIpB,MAAM,0BAA0B,CAAC"}

package/dist/playbooks/pi-runner-wiring.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Production wiring helper for the Pi in-process `SkillRunner` (T11945 · M4).
+ *
+ * THE M4 keystone seam: this is the single place the two production cantbook
+ * dispatchers (`buildDefaultDispatcher` in `playbook.ts` and `buildGoDispatcher`
+ * in `go-ivtr-runner.ts`) reach to obtain the Pi-backed `SkillRunner` they pass
+ * into {@link runSkillNodeOrSpawn}'s `runner` slot. When the runner is supplied,
+ * an in-process `ct-*` skill node routes THROUGH the {@link
+ * import('../llm/pi/pi-agent-adapter.js').PiAgentAdapter} (the Pi agent loop);
+ * when it is `undefined`, the adapter falls back to `defaultSkillRunner` — the
+ * pre-T11945 behaviour.
+ *
+ * ## Default-OFF + lazy-import (Gate-13 + OOM safety)
+ *
+ * The Pi embed is gated behind the **default-OFF** `CLEO_PI_RUNNER_ENABLED`
+ * flag. When the flag is unset (the default) this helper returns `undefined`
+ * WITHOUT importing the Pi barrel — so `@earendil-works/pi-ai`'s `register-
+ * builtins` side effect is never paid on the hot dispatch path, and there is
+ * ZERO behaviour change. Only when the flag is explicitly `'1'` do we
+ * dynamically import the barrel and construct the runner. The import is dynamic
+ * (not a top-level `import`) precisely so the heavy `pi-ai` dependency stays out
+ * of `@cleocode/core/internal`'s eager module graph (every CLI dispatcher loads
+ * `internal`, but must not load `pi-ai` unless Pi is enabled).
+ *
+ * Keeping this helper in `core` keeps the CLI dispatchers thin (CLI package
+ * boundary, Gate-6): each call site is a single `await maybeCreatePiRunner(...)`.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11945
+ */
+import type { SystemOfUseLabel } from '@cleocode/contracts';
+import type { SkillRunner } from '../skills/skill-executor-adapter.js';
+/**
+ * Resolution + project-root deps forwarded to `createPiSkillRunner` when the Pi
+ * runner is constructed. Mirrors the subset of `PiAgentAdapterDeps` the
+ * dispatchers can supply at their call site.
+ */
+export interface MaybePiRunnerDeps {
+    /**
+     * The system-of-use label the Pi adapter resolves its LLM through (E9). When
+     * omitted, `createPiSkillRunner` defaults to `'task-executor'`.
+     */
+    readonly system?: SystemOfUseLabel;
+    /**
+     * Project root for config + credential resolution. When omitted, resolution
+     * defaults to `process.cwd()` inside `resolveLLMForSystem`.
+     */
+    readonly projectRoot?: string;
+}
+/**
+ * Return the Pi-backed {@link SkillRunner} when `CLEO_PI_RUNNER_ENABLED=1`, else
+ * `undefined`.
+ *
+ * The two production cantbook dispatchers call this and pass the result into
+ * {@link runSkillNodeOrSpawn}'s `runner` slot:
+ *
+ * @example
+ * ```ts
+ * const runner = await maybeCreatePiRunner({ system: 'task-executor', projectRoot });
+ * await runSkillNodeOrSpawn(input, { tools, cwd: projectRoot, subprocessSpawn, runner });
+ * ```
+ *
+ * Default-OFF: when the flag is unset (the common case) this short-circuits to
+ * `undefined` before importing the Pi barrel, so `pi-ai`'s `register-builtins`
+ * is never loaded and the dispatcher behaves exactly as it did pre-T11945
+ * (`defaultSkillRunner` runs the in-process skill node).
+ *
+ * @param deps - Optional resolution system + project root forwarded to the Pi
+ *   adapter when the runner is constructed.
+ * @returns The Pi `SkillRunner` when enabled, otherwise `undefined`.
+ * @task T11945
+ */
+export declare function maybeCreatePiRunner(deps?: MaybePiRunnerDeps): Promise<SkillRunner | undefined>;
+//# sourceMappingURL=pi-runner-wiring.d.ts.map

package/dist/playbooks/pi-runner-wiring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-runner-wiring.d.ts","sourceRoot":"","sources":["../../src/playbooks/pi-runner-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAUvE;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAoBlC"}

package/dist/playbooks/pi-runner-wiring.js

@@ -0,0 +1,82 @@
+/**
+ * Production wiring helper for the Pi in-process `SkillRunner` (T11945 · M4).
+ *
+ * THE M4 keystone seam: this is the single place the two production cantbook
+ * dispatchers (`buildDefaultDispatcher` in `playbook.ts` and `buildGoDispatcher`
+ * in `go-ivtr-runner.ts`) reach to obtain the Pi-backed `SkillRunner` they pass
+ * into {@link runSkillNodeOrSpawn}'s `runner` slot. When the runner is supplied,
+ * an in-process `ct-*` skill node routes THROUGH the {@link
+ * import('../llm/pi/pi-agent-adapter.js').PiAgentAdapter} (the Pi agent loop);
+ * when it is `undefined`, the adapter falls back to `defaultSkillRunner` — the
+ * pre-T11945 behaviour.
+ *
+ * ## Default-OFF + lazy-import (Gate-13 + OOM safety)
+ *
+ * The Pi embed is gated behind the **default-OFF** `CLEO_PI_RUNNER_ENABLED`
+ * flag. When the flag is unset (the default) this helper returns `undefined`
+ * WITHOUT importing the Pi barrel — so `@earendil-works/pi-ai`'s `register-
+ * builtins` side effect is never paid on the hot dispatch path, and there is
+ * ZERO behaviour change. Only when the flag is explicitly `'1'` do we
+ * dynamically import the barrel and construct the runner. The import is dynamic
+ * (not a top-level `import`) precisely so the heavy `pi-ai` dependency stays out
+ * of `@cleocode/core/internal`'s eager module graph (every CLI dispatcher loads
+ * `internal`, but must not load `pi-ai` unless Pi is enabled).
+ *
+ * Keeping this helper in `core` keeps the CLI dispatchers thin (CLI package
+ * boundary, Gate-6): each call site is a single `await maybeCreatePiRunner(...)`.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11945
+ */
+/**
+ * The default-OFF env flag controlling the Pi in-process runner. Mirrors
+ * `isPiRunnerEnabled()` in the Pi barrel exactly (strict `'1'`), read here as a
+ * cheap pre-check so the heavy Pi/`pi-ai` barrel is only dynamically imported
+ * when Pi is actually enabled.
+ */
+const PI_RUNNER_FLAG = 'CLEO_PI_RUNNER_ENABLED';
+/**
+ * Return the Pi-backed {@link SkillRunner} when `CLEO_PI_RUNNER_ENABLED=1`, else
+ * `undefined`.
+ *
+ * The two production cantbook dispatchers call this and pass the result into
+ * {@link runSkillNodeOrSpawn}'s `runner` slot:
+ *
+ * @example
+ * ```ts
+ * const runner = await maybeCreatePiRunner({ system: 'task-executor', projectRoot });
+ * await runSkillNodeOrSpawn(input, { tools, cwd: projectRoot, subprocessSpawn, runner });
+ * ```
+ *
+ * Default-OFF: when the flag is unset (the common case) this short-circuits to
+ * `undefined` before importing the Pi barrel, so `pi-ai`'s `register-builtins`
+ * is never loaded and the dispatcher behaves exactly as it did pre-T11945
+ * (`defaultSkillRunner` runs the in-process skill node).
+ *
+ * @param deps - Optional resolution system + project root forwarded to the Pi
+ *   adapter when the runner is constructed.
+ * @returns The Pi `SkillRunner` when enabled, otherwise `undefined`.
+ * @task T11945
+ */
+export async function maybeCreatePiRunner(deps = {}) {
+    // Cheap default-OFF gate — read the raw flag WITHOUT importing the Pi barrel
+    // (which transitively pulls the heavy `pi-ai` dependency). This is the hot
+    // path on every dispatch when Pi is disabled.
+    if (process.env[PI_RUNNER_FLAG] !== '1') {
+        return undefined;
+    }
+    // Flag is on — lazy-import the Pi barrel (subpath, NOT via `internal`) so
+    // `pi-ai` stays out of the eager module graph. `isPiRunnerEnabled()` is the
+    // authoritative predicate; re-confirm in case the env changed between the
+    // raw pre-check and the import.
+    const { createPiSkillRunner, isPiRunnerEnabled } = await import('../llm/pi/index.js');
+    if (!isPiRunnerEnabled()) {
+        return undefined;
+    }
+    return createPiSkillRunner({
+        ...(deps.system !== undefined ? { system: deps.system } : {}),
+        ...(deps.projectRoot !== undefined ? { projectRoot: deps.projectRoot } : {}),
+    });
+}
+//# sourceMappingURL=pi-runner-wiring.js.map

package/dist/playbooks/pi-runner-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-runner-wiring.js","sourceRoot":"","sources":["../../src/playbooks/pi-runner-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAKH;;;;;GAKG;AACH,MAAM,cAAc,GAAG,wBAAwB,CAAC;AAoBhD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,OAA0B,EAAE;IAE5B,6EAA6E;IAC7E,2EAA2E;IAC3E,8CAA8C;IAC9C,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,KAAK,GAAG,EAAE,CAAC;QACxC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,0EAA0E;IAC1E,4EAA4E;IAC5E,0EAA0E;IAC1E,gCAAgC;IAChC,MAAM,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACtF,IAAI,CAAC,iBAAiB,EAAE,EAAE,CAAC;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,mBAAmB,CAAC;QACzB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC7E,CAAC,CAAC;AACL,CAAC"}

package/dist/runtime/openapi/generate-openapi.d.ts

@@ -0,0 +1,211 @@
+/**
+ * generateOpenApi — projects the CLEO operations registry into an OpenAPI 3.1
+ * document (DHQ-033/057 SDK-projection · T11918 · AC2 · M5/E-API-STANDARD-FOUNDATION
+ * T11769).
+ *
+ * ## Why this exists
+ *
+ * The `/v1` REST gateway routes `POST /v1/<domain>/<operation>` for every entry
+ * in the 413-row {@link OPERATIONS} registry. Downstream task T11920 generates a
+ * typed SDK client; its projection source is an OpenAPI 3.1 spec. Hand-authoring
+ * 413 path objects (and keeping them in lock-step with the registry) is exactly
+ * the drift trap the schema-first SSoT (`inputSchema`/`outputSchema`) was built
+ * to close. This builder DERIVES the whole spec from the single source of truth:
+ *
+ *   - paths        ← {@link OPERATIONS} (`POST /v1/<domain>/<operation>`)
+ *   - requestBody  ← {@link getInputContract}(op).schema, else a JSON Schema
+ *                    synthesised from `def.params` (richest available input shape)
+ *   - 200 response ← {@link getOutputContract}(op).dataSchema (hand-authored
+ *                    {@link OUTPUT_CONTRACTS}, else {@link deriveOutputContract})
+ *
+ * Because `OperationInputContract.schema` and `OperationOutputContract.dataSchema`
+ * are ALREADY JSON Schema (draft-07) documents, and OpenAPI 3.1's Schema Object
+ * IS a superset of JSON Schema (it adopts the JSON Schema 2020-12 vocabulary),
+ * the schemas embed directly — no zod→OpenAPI conversion pass, no `zod-to-openapi`
+ * dependency. Zod (v4) is the authoring substrate for the contracts upstream; by
+ * the time a schema reaches this builder it is already plain JSON Schema, so this
+ * module stays a zero-runtime-dependency projection over the registry.
+ *
+ * ## Boundary
+ *
+ * Lives in `core/src/runtime` (NOT `contracts`): it reads {@link getOutputContract}
+ * / {@link getInputContract}, which are core-resident bodied resolvers, and it is
+ * itself a bodied runtime helper (the contracts-purity Gate 10 forbids net-new
+ * bodied functions in `contracts`). Import-time side-effect-free: it builds
+ * nothing at module load, only when {@link generateOpenApi} is called.
+ *
+ * @packageDocumentation
+ * @module @cleocode/core/runtime/openapi/generate-openapi
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0 | OpenAPI 3.1.0 Specification}
+ * @see OperationOutputContract — the OUTPUT-side JSON Schema SSoT this projects
+ * @see OperationInputContract — the INPUT-side JSON Schema SSoT this projects
+ *
+ * @epic T11769
+ * @task T11918 — AC2: zod→OpenAPI 3.1 bridge + `cleo gateway openapi`
+ */
+import { type JsonSchema } from '@cleocode/contracts';
+/**
+ * OpenAPI 3.1 `info` object — API identity surfaced to SDK generators and docs
+ * tooling.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#info-object}
+ */
+export interface OpenApiInfo {
+    /** Human-readable API title. */
+    title: string;
+    /**
+     * Semantic version of the API surface (NOT the package version). The `/v1`
+     * REST gateway is version `1.x`; defaults to `'1.0.0'`.
+     */
+    version: string;
+    /** Optional one-line summary (OpenAPI 3.1 adds `summary` to the info object). */
+    summary?: string;
+    /** Optional CommonMark description. */
+    description?: string;
+}
+/**
+ * OpenAPI 3.1 Media Type object — pairs a content type with its schema.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#media-type-object}
+ */
+export interface OpenApiMediaType {
+    /** The JSON Schema (2020-12 vocabulary) describing the payload. */
+    schema: JsonSchema;
+}
+/**
+ * OpenAPI 3.1 Request Body object.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#request-body-object}
+ */
+export interface OpenApiRequestBody {
+    /** Content keyed by media type (always `application/json` here). */
+    content: Record<string, OpenApiMediaType>;
+    /** Whether the request body is required (true iff the op has required params). */
+    required: boolean;
+    /** Optional human description. */
+    description?: string;
+}
+/**
+ * OpenAPI 3.1 Response object.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#response-object}
+ */
+export interface OpenApiResponse {
+    /** Required CommonMark description of the response. */
+    description: string;
+    /** Optional content keyed by media type. */
+    content?: Record<string, OpenApiMediaType>;
+}
+/**
+ * OpenAPI 3.1 Operation object — one HTTP operation on a path.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#operation-object}
+ */
+export interface OpenApiOperation {
+    /** Unique, machine-friendly id (`<gateway>.<domain>.<operation>`) for SDK method naming. */
+    operationId: string;
+    /** Short summary (the registry `description`). */
+    summary: string;
+    /** Grouping tags — the canonical domain. */
+    tags: string[];
+    /** Request body, omitted when the op declares no input params. */
+    requestBody?: OpenApiRequestBody;
+    /** Responses keyed by HTTP status code (always at least `'200'`). */
+    responses: Record<string, OpenApiResponse>;
+    /**
+     * Vendor extension carrying the CQRS gateway (`'query'` | `'mutate'`) this
+     * operation routes through. The clean `/v1/<domain>/<operation>` path omits the
+     * gateway for readability, so the SDK reads this extension to pick the right
+     * dispatch gateway. OpenAPI tooling ignores `x-`-prefixed members it does not
+     * recognise, so emitting it keeps the document valid.
+     */
+    'x-cleo-gateway': 'query' | 'mutate';
+}
+/**
+ * OpenAPI 3.1 Path Item object — the set of HTTP operations on one path. The
+ * CLEO `/v1` gateway only routes `POST`, so only `post` is ever populated.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#path-item-object}
+ */
+export interface OpenApiPathItem {
+    /** The single `POST` operation served at this path. */
+    post: OpenApiOperation;
+}
+/**
+ * A minimal, structurally-typed OpenAPI 3.1 document — exactly the members
+ * {@link generateOpenApi} emits. The `openapi` field is pinned to the `3.1.x`
+ * literal family so consumers can statically assert the version.
+ *
+ * @see {@link https://spec.openapis.org/oas/v3.1.0#openapi-object}
+ */
+export interface OpenApiDocument {
+    /** OpenAPI version string — always `'3.1.0'`. */
+    openapi: '3.1.0';
+    /** API identity. */
+    info: OpenApiInfo;
+    /**
+     * The JSON Schema dialect every embedded Schema Object uses, declared once at
+     * the document root per OpenAPI 3.1. The contracts ship draft-07 schemas,
+     * which validate under the 2020-12 dialect OpenAPI 3.1 mandates.
+     */
+    jsonSchemaDialect: string;
+    /**
+     * Path → path-item map, keyed by `<pathPrefix>/<domain>/<operation>` (with a
+     * trailing `/<gateway>` segment for the cross-gateway collision pairs).
+     */
+    paths: Record<string, OpenApiPathItem>;
+}
+/**
+ * Options for {@link generateOpenApi}.
+ */
+export interface GenerateOpenApiOptions {
+    /**
+     * Semantic version stamped into `info.version`. This is the API-surface
+     * version (the `/v1` gateway), NOT the npm package version.
+     *
+     * @default '1.0.0'
+     */
+    version?: string;
+    /**
+     * Path prefix prepended to every operation route. The SDK-facing REST surface
+     * is versioned under `/v1` (T11769); each op maps to
+     * `POST <pathPrefix>/<domain>/<operation>`.
+     *
+     * @default '/v1'
+     */
+    pathPrefix?: string;
+}
+/**
+ * Project the {@link OPERATIONS} registry into a complete OpenAPI 3.1 document.
+ *
+ * Walks every registry entry, mapping each to a `POST` path whose `requestBody`
+ * is the resolved input schema and whose `200` response is the resolved output
+ * schema (`deriveOutputContract` coverage), wrapped in the LAFS envelope.
+ *
+ * Routing: the clean form is `POST <pathPrefix>/<domain>/<operation>`. Because
+ * the registry has cross-gateway collisions on `<domain>/<operation>` (the same
+ * pair under both `query` and `mutate`), a colliding entry is disambiguated by
+ * appending its gateway segment (`<pathPrefix>/<domain>/<operation>/<gateway>`).
+ * Each operation also carries an `x-cleo-gateway` extension so the SDK knows
+ * which CQRS gateway to dispatch through regardless of the path form.
+ *
+ * The number of paths in the returned document equals `OPERATIONS.length` (AC5):
+ * every registry entry gets a unique route (and a unique operationId).
+ *
+ * @param options - {@link GenerateOpenApiOptions} (version, path prefix).
+ * @returns A structurally-valid OpenAPI 3.1 {@link OpenApiDocument}.
+ *
+ * @example
+ * ```ts
+ * const doc = generateOpenApi();
+ * doc.openapi;                                       // '3.1.0'
+ * Object.keys(doc.paths).length;                     // === OPERATIONS.length
+ * doc.paths['/v1/tasks/show'].post.operationId;      // 'query.tasks.show'
+ * doc.paths['/v1/tasks/show'].post['x-cleo-gateway'];// 'query'
+ * ```
+ *
+ * @task T11918 — AC1/AC2/AC5
+ */
+export declare function generateOpenApi(options?: GenerateOpenApiOptions): OpenApiDocument;
+//# sourceMappingURL=generate-openapi.d.ts.map

package/dist/runtime/openapi/generate-openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-openapi.d.ts","sourceRoot":"","sources":["../../../src/runtime/openapi/generate-openapi.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAgD,MAAM,qBAAqB,CAAC;AAQpG;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC1C,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAC;IAClB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kEAAkE;IAClE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,gBAAgB,EAAE,OAAO,GAAG,QAAQ,CAAC;CACtC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uDAAuD;IACvD,IAAI,EAAE,gBAAgB,CAAC;CACxB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,oBAAoB;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACxC;AAMD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA+LD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAkDrF"}