@warlock.js/ai 4.4.0 → 4.6.0

package/esm/observe/observer-registry.mjs

@@ -0,0 +1,51 @@
+//#region ../@warlock.js/ai/src/observe/observer-registry.ts
+/**
+* Module-level list of globally registered {@link Observer}s. A flow
+* that resolves to "observed" hands its finished report to every entry
+* here. An observability tool (panoptic, …) registers exactly one
+* collector when its config is applied.
+*/
+const observers = [];
+/**
+* Global "observe every flow by default" flag. When `true`, a flow that
+* did not set its own `observe` option is observed (routed to the
+* globally registered observers). Individual flows opt out with
+* `observe: false`. Default `false` — opt-in observability.
+*/
+let observeAll = false;
+/**
+* Register a global {@link Observer}. Every flow that resolves to
+* "observed" (via `observeAll` or `observe: true`) routes its completed
+* report to it. An observability tool registers its collector here once,
+* when its config is applied.
+*/
+function registerObserver(observer) {
+	observers.push(observer);
+}
+/**
+* The currently registered global observers. Returned as a read-only
+* snapshot reference — callers must not mutate it; use
+* {@link registerObserver} to add and {@link clearObservers} (test-only)
+* to reset.
+*/
+function getObservers() {
+	return observers;
+}
+/**
+* Set the global "observe every flow by default" flag. An observability
+* tool flips this on when configured with its own observe-all option.
+*/
+function setObserveAll(value) {
+	observeAll = value;
+}
+/**
+* Read the global "observe every flow by default" flag. Consulted by the
+* observe-resolution helper when a flow left `observe` undefined.
+*/
+function isObserveAll() {
+	return observeAll;
+}
+
+//#endregion
+export { getObservers, isObserveAll, registerObserver, setObserveAll };
+//# sourceMappingURL=observer-registry.mjs.map

package/esm/observe/observer-registry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-registry.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/observe/observer-registry.ts"],"sourcesContent":["import type { Observer } from \"./observer.contract\";\n\n/**\n * Module-level list of globally registered {@link Observer}s. A flow\n * that resolves to \"observed\" hands its finished report to every entry\n * here. An observability tool (panoptic, …) registers exactly one\n * collector when its config is applied.\n */\nconst observers: Observer[] = [];\n\n/**\n * Global \"observe every flow by default\" flag. When `true`, a flow that\n * did not set its own `observe` option is observed (routed to the\n * globally registered observers). Individual flows opt out with\n * `observe: false`. Default `false` — opt-in observability.\n */\nlet observeAll = false;\n\n/**\n * Register a global {@link Observer}. Every flow that resolves to\n * \"observed\" (via `observeAll` or `observe: true`) routes its completed\n * report to it. An observability tool registers its collector here once,\n * when its config is applied.\n */\nexport function registerObserver(observer: Observer): void {\n  observers.push(observer);\n}\n\n/**\n * The currently registered global observers. Returned as a read-only\n * snapshot reference — callers must not mutate it; use\n * {@link registerObserver} to add and {@link clearObservers} (test-only)\n * to reset.\n */\nexport function getObservers(): readonly Observer[] {\n  return observers;\n}\n\n/**\n * Set the global \"observe every flow by default\" flag. An observability\n * tool flips this on when configured with its own observe-all option.\n */\nexport function setObserveAll(value: boolean): void {\n  observeAll = value;\n}\n\n/**\n * Read the global \"observe every flow by default\" flag. Consulted by the\n * observe-resolution helper when a flow left `observe` undefined.\n */\nexport function isObserveAll(): boolean {\n  return observeAll;\n}\n\n/**\n * Reset the registry to its initial empty state — clears all registered\n * observers and turns off the observe-all flag. Internal: intended for\n * test isolation so one spec's registrations don't leak into the next.\n * Not part of the public surface.\n */\nexport function clearObservers(): void {\n  observers.length = 0;\n  observeAll = false;\n}\n"],"mappings":";;;;;;;AAQA,MAAM,YAAwB,CAAC;;;;;;;AAQ/B,IAAI,aAAa;;;;;;;AAQjB,SAAgB,iBAAiB,UAA0B;CACzD,UAAU,KAAK,QAAQ;AACzB;;;;;;;AAQA,SAAgB,eAAoC;CAClD,OAAO;AACT;;;;;AAMA,SAAgB,cAAc,OAAsB;CAClD,aAAa;AACf;;;;;AAMA,SAAgB,eAAwB;CACtC,OAAO;AACT"}

package/esm/observe/observer.contract.d.mts

@@ -0,0 +1,40 @@
+import { ExecutionReport } from "../contracts/result/execution-report.type.mjs";
+
+//#region ../@warlock.js/ai/src/observe/observer.contract.d.ts
+/**
+ * Generic, panoptic-agnostic observability seam. A flow that resolves
+ * to "observed" hands its completed {@link ExecutionReport} to every
+ * registered `Observer`. Core depends only on this structural shape and
+ * `ExecutionReport` — it never imports any observability package
+ * (panoptic, OTel, Langfuse, …). An observability tool implements
+ * `Observer` and registers itself via {@link registerObserver}, so
+ * `observe: true` / `observeAll` route reports without coupling core to
+ * the tool. This is the dependency inversion that keeps the two sides
+ * decoupled.
+ *
+ * The object form of a flow's `observe` option is typed as this same
+ * structural `Observer` (NOT a panoptic-specific options type), so a
+ * panoptic flow-local collector — which implements `Observer` — can be
+ * passed directly.
+ *
+ * @example
+ * const collector: Observer = {
+ *   collect(report) {
+ *     // forward the finished report to a store / exporter
+ *   },
+ * };
+ * registerObserver(collector);
+ */
+interface Observer {
+  /**
+   * Receive a completed flow's report. May be sync or async — the flow
+   * awaits it. A throw is **isolated** (never breaks the run) but no
+   * longer **silent**: it is surfaced via `notifyObservers`' `onError`
+   * hook, or warned once per observer, so a broken exporter can't vanish
+   * from production with no signal (C5).
+   */
+  collect(report: ExecutionReport): void | Promise<void>;
+}
+//#endregion
+export { Observer };
+//# sourceMappingURL=observer.contract.d.mts.map

package/esm/observe/observer.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.contract.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/observe/observer.contract.ts"],"mappings":";;;;;AA0BA;;;;;;;;;AAQkD;;;;;;;;;;;;;UARjC,QAAA;;;;;;;;EAQf,OAAA,CAAQ,MAAA,EAAQ,eAAA,UAAyB,OAAO;AAAA"}

package/esm/observe/resolve-observers.d.mts

@@ -0,0 +1,40 @@
+import { Observer } from "./observer.contract.mjs";
+
+//#region ../@warlock.js/ai/src/observe/resolve-observers.d.ts
+/**
+ * The value a flow's `observe` config option may take. Additive and
+ * gated — when `undefined` (the default), behavior follows the global
+ * observe-all flag, so a flow that never sets `observe` behaves exactly
+ * as before unless an observability tool turned observe-all on.
+ *
+ * - `true`  → route this flow to the globally registered observers,
+ *   even when observe-all is off.
+ * - `false` → opt this flow out entirely, even when observe-all is on.
+ * - an {@link Observer} object → a flow-local collector; only this flow's
+ *   report is routed, and only to it (the global observers are skipped).
+ *   A panoptic flow-local collector implements `Observer`, so it can be
+ *   passed here directly — core stays panoptic-agnostic.
+ * - `undefined` → follow the global observe-all flag.
+ */
+type FlowObserveOption = boolean | Observer;
+/**
+ * Resolve a flow's `observe` option into the concrete list of
+ * {@link Observer}s to notify with that flow's completed report:
+ *
+ * - `false` → `[]` (opted out).
+ * - `true` → the globally registered observers.
+ * - an `Observer` object → just that one (flow-local).
+ * - `undefined` → the globally registered observers when observe-all is
+ *   on AND this is a ROOT run, otherwise `[]`.
+ *
+ * Reads the ambient {@link currentRunFrame} for the observe-all path:
+ * flows call it at completion, so a present frame means the run is nested
+ * inside an orchestration callback and is already attached to its parent's
+ * report tree — self-routing it again would double-count it as a separate
+ * top-level trace (and double its tokens/cost in the aggregate). Explicit
+ * `observe: true` / an `Observer` still route regardless of nesting.
+ */
+declare function resolveObservers(observe: FlowObserveOption | undefined): readonly Observer[];
+//#endregion
+export { FlowObserveOption, resolveObservers };
+//# sourceMappingURL=resolve-observers.d.mts.map

package/esm/observe/resolve-observers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-observers.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/observe/resolve-observers.ts"],"mappings":";;;;;AAmBA;;;;AAAkD;AAmBlD;;;;;;;;KAnBY,iBAAA,aAA8B,QAAQ;;;;;;;;;;;;;;;;;;iBAmBlC,gBAAA,CAAiB,OAAA,EAAS,iBAAA,wBAAyC,QAAQ"}

package/esm/observe/resolve-observers.mjs

@@ -0,0 +1,73 @@
+import { isNestedRun } from "../utils/run-context.mjs";
+import { getObservers, isObserveAll } from "./observer-registry.mjs";
+
+//#region ../@warlock.js/ai/src/observe/resolve-observers.ts
+/**
+* Resolve a flow's `observe` option into the concrete list of
+* {@link Observer}s to notify with that flow's completed report:
+*
+* - `false` → `[]` (opted out).
+* - `true` → the globally registered observers.
+* - an `Observer` object → just that one (flow-local).
+* - `undefined` → the globally registered observers when observe-all is
+*   on AND this is a ROOT run, otherwise `[]`.
+*
+* Reads the ambient {@link currentRunFrame} for the observe-all path:
+* flows call it at completion, so a present frame means the run is nested
+* inside an orchestration callback and is already attached to its parent's
+* report tree — self-routing it again would double-count it as a separate
+* top-level trace (and double its tokens/cost in the aggregate). Explicit
+* `observe: true` / an `Observer` still route regardless of nesting.
+*/
+function resolveObservers(observe) {
+	if (observe === false) return [];
+	if (observe === true) return getObservers();
+	if (observe !== void 0) return [observe];
+	return isObserveAll() && !isNestedRun() ? getObservers() : [];
+}
+/**
+* Observers whose `collect()` already threw once — so the isolate-but-
+* surface warning fires at most once per observer object, never spamming
+* the log when every flow report hits the same broken exporter. Keyed by
+* object identity via a {@link WeakSet} so a discarded observer is GC'd
+* without leaking. Mirrors panoptic's per-exporter `warnedExporters`.
+*/
+const warnedObservers = /* @__PURE__ */ new WeakSet();
+/**
+* Route a completed flow report to every observer the flow's `observe`
+* option resolves to. Each `collect` is awaited so async exporters
+* finish before the flow returns; a throw is **isolated** (never breaks
+* the run) but no longer **silent** — it is surfaced via `onError` when
+* supplied, otherwise a `console.warn` once per observer. A broken
+* observer/exporter must not disappear from production with no signal
+* (C5). Adopts the isolate-but-surface pattern panoptic's collector
+* already uses for exporters.
+*/
+async function notifyObservers(observe, report, onError) {
+	for (const observer of resolveObservers(observe)) try {
+		await observer.collect(report);
+	} catch (error) {
+		surfaceObserverError(observer, error, onError);
+	}
+}
+/**
+* Surface an isolated observer failure without ever rethrowing into the
+* flow. Prefers the caller-supplied `onError` (itself guarded so a
+* throwing handler can't escape); otherwise warns once per observer.
+*/
+function surfaceObserverError(observer, error, onError) {
+	if (onError) {
+		try {
+			onError(error, observer);
+		} catch {}
+		return;
+	}
+	if (warnedObservers.has(observer)) return;
+	warnedObservers.add(observer);
+	const message = error instanceof Error ? error.message : String(error);
+	console.warn(`[warlock-ai] an observer's collect() threw and was isolated: ${message}`);
+}
+
+//#endregion
+export { notifyObservers, resolveObservers };
+//# sourceMappingURL=resolve-observers.mjs.map

package/esm/observe/resolve-observers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-observers.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/observe/resolve-observers.ts"],"sourcesContent":["import { isNestedRun } from \"../utils/run-context\";\nimport { getObservers, isObserveAll } from \"./observer-registry\";\nimport type { Observer } from \"./observer.contract\";\n\n/**\n * The value a flow's `observe` config option may take. Additive and\n * gated — when `undefined` (the default), behavior follows the global\n * observe-all flag, so a flow that never sets `observe` behaves exactly\n * as before unless an observability tool turned observe-all on.\n *\n * - `true`  → route this flow to the globally registered observers,\n *   even when observe-all is off.\n * - `false` → opt this flow out entirely, even when observe-all is on.\n * - an {@link Observer} object → a flow-local collector; only this flow's\n *   report is routed, and only to it (the global observers are skipped).\n *   A panoptic flow-local collector implements `Observer`, so it can be\n *   passed here directly — core stays panoptic-agnostic.\n * - `undefined` → follow the global observe-all flag.\n */\nexport type FlowObserveOption = boolean | Observer;\n\n/**\n * Resolve a flow's `observe` option into the concrete list of\n * {@link Observer}s to notify with that flow's completed report:\n *\n * - `false` → `[]` (opted out).\n * - `true` → the globally registered observers.\n * - an `Observer` object → just that one (flow-local).\n * - `undefined` → the globally registered observers when observe-all is\n *   on AND this is a ROOT run, otherwise `[]`.\n *\n * Reads the ambient {@link currentRunFrame} for the observe-all path:\n * flows call it at completion, so a present frame means the run is nested\n * inside an orchestration callback and is already attached to its parent's\n * report tree — self-routing it again would double-count it as a separate\n * top-level trace (and double its tokens/cost in the aggregate). Explicit\n * `observe: true` / an `Observer` still route regardless of nesting.\n */\nexport function resolveObservers(observe: FlowObserveOption | undefined): readonly Observer[] {\n  if (observe === false) {\n    return [];\n  }\n\n  if (observe === true) {\n    return getObservers();\n  }\n\n  if (observe !== undefined) {\n    return [observe];\n  }\n\n  // Observe-all captures ROOT runs only. A run nested inside any parent\n  // capture (orchestration callback, supervisor member dispatch, workflow\n  // step) already nests in its parent's report, so routing it here too would\n  // duplicate it as a standalone top-level trace.\n  return isObserveAll() && !isNestedRun() ? getObservers() : [];\n}\n\n/**\n * Observers whose `collect()` already threw once — so the isolate-but-\n * surface warning fires at most once per observer object, never spamming\n * the log when every flow report hits the same broken exporter. Keyed by\n * object identity via a {@link WeakSet} so a discarded observer is GC'd\n * without leaking. Mirrors panoptic's per-exporter `warnedExporters`.\n */\nconst warnedObservers = new WeakSet<Observer>();\n\n/**\n * Route a completed flow report to every observer the flow's `observe`\n * option resolves to. Each `collect` is awaited so async exporters\n * finish before the flow returns; a throw is **isolated** (never breaks\n * the run) but no longer **silent** — it is surfaced via `onError` when\n * supplied, otherwise a `console.warn` once per observer. A broken\n * observer/exporter must not disappear from production with no signal\n * (C5). Adopts the isolate-but-surface pattern panoptic's collector\n * already uses for exporters.\n */\nexport async function notifyObservers(\n  observe: FlowObserveOption | undefined,\n  report: Parameters<Observer[\"collect\"]>[0],\n  onError?: (error: unknown, observer: Observer) => void,\n): Promise<void> {\n  for (const observer of resolveObservers(observe)) {\n    try {\n      await observer.collect(report);\n    } catch (error) {\n      surfaceObserverError(observer, error, onError);\n    }\n  }\n}\n\n/**\n * Surface an isolated observer failure without ever rethrowing into the\n * flow. Prefers the caller-supplied `onError` (itself guarded so a\n * throwing handler can't escape); otherwise warns once per observer.\n */\nfunction surfaceObserverError(\n  observer: Observer,\n  error: unknown,\n  onError?: (error: unknown, observer: Observer) => void,\n): void {\n  if (onError) {\n    try {\n      onError(error, observer);\n    } catch {\n      // Never let the error handler itself escape into the flow.\n    }\n    return;\n  }\n\n  if (warnedObservers.has(observer)) return;\n  warnedObservers.add(observer);\n\n  const message = error instanceof Error ? error.message : String(error);\n  console.warn(`[warlock-ai] an observer's collect() threw and was isolated: ${message}`);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,iBAAiB,SAA6D;CAC5F,IAAI,YAAY,OACd,OAAO,CAAC;CAGV,IAAI,YAAY,MACd,OAAO,aAAa;CAGtB,IAAI,YAAY,QACd,OAAO,CAAC,OAAO;CAOjB,OAAO,aAAa,KAAK,CAAC,YAAY,IAAI,aAAa,IAAI,CAAC;AAC9D;;;;;;;;AASA,MAAM,kCAAkB,IAAI,QAAkB;;;;;;;;;;;AAY9C,eAAsB,gBACpB,SACA,QACA,SACe;CACf,KAAK,MAAM,YAAY,iBAAiB,OAAO,GAC7C,IAAI;EACF,MAAM,SAAS,QAAQ,MAAM;CAC/B,SAAS,OAAO;EACd,qBAAqB,UAAU,OAAO,OAAO;CAC/C;AAEJ;;;;;;AAOA,SAAS,qBACP,UACA,OACA,SACM;CACN,IAAI,SAAS;EACX,IAAI;GACF,QAAQ,OAAO,QAAQ;EACzB,QAAQ,CAER;EACA;CACF;CAEA,IAAI,gBAAgB,IAAI,QAAQ,GAAG;CACnC,gBAAgB,IAAI,QAAQ;CAE5B,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CACrE,QAAQ,KAAK,gEAAgE,SAAS;AACxF"}

package/esm/orchestrator/execution.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/execution.ts"],"mappings":";;;;;;;;;;;;;;AAmEA;;;;;;;;;;;KAAY,2BAAA;EACV,MAAA,EAAQ,kBAAA,CAAmB,OAAA,EAAS,MAAA,GAOY;EALhD,OAAA,GAAU,GAAA,SAAY,mBAAA;EACtB,SAAA;EACA,OAAA,EAAS,mBAAA;EACT,KAAA,GAAQ,eAAA;EACR,OAAA,GAAU,0BAAA,CAA2B,MAAA;EACrC,gBAAA,GAAmB,4BAAA,CAA6B,kBAAA,CAAmB,OAAA;EACnE,eAAA;EACA,aAAA,GAAgB,yBAAA;AAAA;;;;;;;;;;;;;;;;;;;;cAsBL,qBAAA;EAAA,iBACM,MAAA;EAAA,iBACA,GAAA;EAAA,iBACA,gBAAA;cAIE,MAAA,EAAQ,2BAAA,CAA4B,OAAA,EAAS,MAAA;EAAT;;;;;;EAyB1C,GAAA,IAAO,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EA4BhB;;;;EAAlB,MAAA,IAAU,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EAiBxC;;;;;EAFG,OAAA,CACX,IAAA,EAAM,oBAAA,sBACL,OAAA,CAAQ,oBAAA;AAAA;;;;;;;;;;;;iBAkPS,OAAA,kBACpB,GAAA,EAAK,yBAAA,CAA0B,OAAA,EAAS,MAAA,GACxC,KAAA,EAAO,eAAA,EACP,OAAA,EAAS,0BAAA,CAA2B,MAAA,IACnC,OAAA,CAAQ,kBAAA,CAAmB,OAAA;;;;;;;;AAtPG;AAkPjC;;iBA2MsB,SAAA,kBACpB,GAAA,EAAK,yBAAA,CAA0B,OAAA,EAAS,MAAA,GACxC,SAAA,UACA,OAAA,GAAU,yBAAA,GACT,OAAA,CAAQ,kBAAA,CAAmB,OAAA;;;;;;;;;;;iBAiDR,UAAA,kBACpB,GAAA,EAAK,yBAAA,CAA0B,OAAA,EAAS,MAAA,GACxC,KAAA,EAAO,eAAA,EACP,OAAA,EAAS,0BAAA,CAA2B,MAAA,IACnC,OAAA,CAAQ,kBAAA,CAAmB,OAAA"}
+{"version":3,"file":"execution.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/execution.ts"],"mappings":";;;;;;;;;;;;;;AAqEA;;;;;;;;;;;KAAY,2BAAA;EACV,MAAA,EAAQ,kBAAA,CAAmB,OAAA,EAAS,MAAA,GAOY;EALhD,OAAA,GAAU,GAAA,SAAY,mBAAA;EACtB,SAAA;EACA,OAAA,EAAS,mBAAA;EACT,KAAA,GAAQ,eAAA;EACR,OAAA,GAAU,0BAAA,CAA2B,MAAA;EACrC,gBAAA,GAAmB,4BAAA,CAA6B,kBAAA,CAAmB,OAAA;EACnE,eAAA;EACA,aAAA,GAAgB,yBAAA;AAAA;;;;;;;;;;;;;;;;;;;;cAsBL,qBAAA;EAAA,iBACM,MAAA;EAAA,iBACA,GAAA;EAAA,iBACA,gBAAA;cAIE,MAAA,EAAQ,2BAAA,CAA4B,OAAA,EAAS,MAAA;EAAT;;;;;;EAyB1C,GAAA,IAAO,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EAiChB;;;;EAAlB,MAAA,IAAU,OAAA,CAAQ,kBAAA,CAAmB,OAAA;EAiBxC;;;;;EAFG,OAAA,CACX,IAAA,EAAM,oBAAA,sBACL,OAAA,CAAQ,oBAAA;AAAA;;;;;;;;;;;;iBAuPS,OAAA,kBACpB,GAAA,EAAK,yBAAA,CAA0B,OAAA,EAAS,MAAA,GACxC,KAAA,EAAO,eAAA,EACP,OAAA,EAAS,0BAAA,CAA2B,MAAA,IACnC,OAAA,CAAQ,kBAAA,CAAmB,OAAA;;;;;;;;AA3PG;AAuPjC;;iBA4MsB,SAAA,kBACpB,GAAA,EAAK,yBAAA,CAA0B,OAAA,EAAS,MAAA,GACxC,SAAA,UACA,OAAA,GAAU,yBAAA,GACT,OAAA,CAAQ,kBAAA,CAAmB,OAAA;;;;;;;;;;;iBAiDR,UAAA,kBACpB,GAAA,EAAK,yBAAA,CAA0B,OAAA,EAAS,MAAA,GACxC,KAAA,EAAO,eAAA,EACP,OAAA,EAAS,0BAAA,CAA2B,MAAA,IACnC,OAAA,CAAQ,kBAAA,CAAmB,OAAA"}

package/esm/orchestrator/execution.mjs

@@ -4,6 +4,7 @@ import "../errors/index.mjs";
 import { generateRunId } from "../utils/generate-run-id.mjs";
 import { REPORT_SCHEMA_VERSION } from "../contracts/result/base-report.type.mjs";
 import { resolveDefaultCheckpointStore, resolveDefaultSnapshotStore } from "../config.mjs";
+import { notifyObservers } from "../observe/resolve-observers.mjs";
 import { injectMemories, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory } from "./memory.mjs";
 import { persistCheckpoint, summarizeRoute } from "./checkpoint.mjs";
 import { acquireLock } from "./lock.mjs";
@@ -62,6 +63,7 @@ var OrchestratorExecution = class {
 		if (this.params.input === void 0 || !this.params.options) throw new OrchestratorConfigError(`ai.orchestrator("${this.params.config.name}"): internal — run() invoked without input/options`);
 		try {
 			const result = await runTurn(this.ctx, this.params.input, this.params.options);
+			await notifyObservers(this.ctx.config.observe, result.report);
 			this.streamController?.end(result);
 			return result;
 		} catch (error) {
@@ -183,7 +185,7 @@ function applyStatePatch(seed, patch) {
 * `children[]` carries only the CURRENT turn's dispatched primitive
 * reports) while the per-turn forensic record lives on `turns[]`.
 */
-function buildReport(ctx, sessionId, turnIndex, status, turnSnapshot, childReport) {
+function buildReport(ctx, sessionId, turnIndex, status, turnSnapshot, childReport, error) {
 	const now = (/* @__PURE__ */ new Date()).toISOString();
 	const usage = turnSnapshot?.usage ?? childReport?.usage ?? ZERO_USAGE;
 	return {
@@ -194,6 +196,7 @@ function buildReport(ctx, sessionId, turnIndex, status, turnSnapshot, childRepor
 		sessionId,
 		type: "orchestrator",
 		status,
+		...error ? { error } : {},
 		startedAt: turnSnapshot?.startedAt ?? now,
 		endedAt: turnSnapshot?.endedAt ?? now,
 		duration: turnSnapshot?.duration ?? 0,
@@ -298,7 +301,7 @@ async function runTurn(ctx, input, options) {
 		});
 		const status = result.error ? deriveStatus(result.report.status) : "awaiting-input";
 		if (result.error) {
-			const report = buildReport(ctx, sessionId, loaded.turnIndex, status, turnSnapshot, result.report);
+			const report = buildReport(ctx, sessionId, loaded.turnIndex, status, turnSnapshot, result.report, result.error);
 			emitTerminal(ctx, sessionId, loaded.turnIndex, status);
 			return {
 				data: result.data,

package/esm/orchestrator/execution.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"execution.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/execution.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type { OrchestratorCommands } from \"../contracts/orchestrator/orchestrator-commands.type\";\nimport type { OrchestratorConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type {\n  OrchestratorEvent,\n  OrchestratorEventHandlers,\n  OrchestratorEventMap,\n  OrchestratorEventName,\n} from \"../contracts/orchestrator/orchestrator-event.type\";\nimport type {\n  OrchestratorExecuteOptions,\n  OrchestratorResumeOptions,\n} from \"../contracts/orchestrator/orchestrator-execute-options.type\";\nimport type {\n  CompactionResult,\n  OrchestratorReport,\n  OrchestratorReportStatus,\n  OrchestratorResult,\n  TurnSnapshot,\n} from \"../contracts/result/orchestrator-result.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type { EventIdentity } from \"../contracts/events/event-identity.type\";\nimport {\n  resolveDefaultCheckpointStore,\n  resolveDefaultSnapshotStore,\n} from \"../config\";\nimport { OrchestratorConfigError, OrchestratorDriftError } from \"../errors\";\nimport type { ResolvedIntentEntry } from \"../supervisor/entries\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { persistCheckpoint, summarizeRoute } from \"./checkpoint\";\nimport { runCompaction, runManualCompaction, shouldCompact } from \"./compaction\";\nimport { deriveRunId, dispatchTurn } from \"./dispatch\";\nimport type { OrchestratorEmitter } from \"./emitter\";\nimport type { OrchestratorEmitterLike } from \"./emitter-port.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\nimport { acquireLock } from \"./lock\";\nimport { loadSession } from \"./load\";\nimport {\n  injectMemories,\n  outcomeTextFromTurn,\n  recallForTurn,\n  rememberTurnOutcome,\n  resolveOrchestratorMemory,\n} from \"./memory\";\nimport type { OrchestratorStreamController } from \"./orchestrator-stream\";\nimport { resolveResume } from \"./resume\";\nimport { windowHistory } from \"./window\";\n\n/** Empty rolled-up usage for turns that never dispatched (drift/seed). */\nconst ZERO_USAGE: Usage = { input: 0, output: 0, total: 0 };\n\n/**\n * Constructor params the C1 factory passes when building an\n * {@link OrchestratorExecution} per call. The factory owns author-time\n * validation, intent-entry resolution, and signature computation; it\n * hands the engine the validated `config`, the resolved `entries`, the\n * computed `signature`, and the shared three-tier `emitter`. The\n * per-call inputs vary by entry point:\n *\n * - `execute` / `stream` — `input` + `options` (and `streamController`\n *   for `stream`).\n * - `resume` — `resumeSessionId` + `resumeOptions`.\n * - `command(\"compact\")` — neither; `compact(args)` carries its own.\n */\nexport type OrchestratorExecutionParams<TOutput, TState> = {\n  config: OrchestratorConfig<TOutput, TState>;\n  /** Resolved intent entries (validated by C1; the engine delegates dispatch to the supervisor). */\n  entries?: Map<string, ResolvedIntentEntry>;\n  signature: string;\n  emitter: OrchestratorEmitter;\n  input?: SupervisorInput;\n  options?: OrchestratorExecuteOptions<TState>;\n  streamController?: OrchestratorStreamController<OrchestratorResult<TOutput>>;\n  resumeSessionId?: string;\n  resumeOptions?: OrchestratorResumeOptions;\n};\n\n/**\n * Per-call lifecycle engine — the single object the C1 factory\n * constructs and drives. Owns the 7-phase lifecycle (orchestrator.md §3:\n * load → drift → lock → window → dispatch → persist → compaction),\n * resolving the durable stores (own config field → `ai.config` default)\n * and adapting C1's three-tier {@link OrchestratorEmitter} to the\n * {@link OrchestratorEmitterLike} port the phase modules call.\n *\n * The factory creates a fresh instance per `execute` / `stream` /\n * `resume` / `command` call (single-call lifecycle invariant — §18.8);\n * the heavy lifting lives in the standalone phase functions\n * ({@link runTurn} / {@link runResume}) which this class delegates to.\n *\n * @example\n * const execution = new OrchestratorExecution({\n *   config, entries, signature, emitter, input, options,\n * });\n * const result = await execution.run();\n */\nexport class OrchestratorExecution<TOutput, TState> {\n  private readonly params: OrchestratorExecutionParams<TOutput, TState>;\n  private readonly ctx: OrchestratorEngineContext<TOutput, TState>;\n  private readonly streamController?: OrchestratorStreamController<\n    OrchestratorResult<TOutput>\n  >;\n\n  public constructor(params: OrchestratorExecutionParams<TOutput, TState>) {\n    this.params = params;\n    this.streamController = params.streamController;\n    this.ctx = {\n      config: params.config,\n      signature: params.signature,\n      checkpointStore: resolveCheckpointStore(params.config),\n      snapshotStore: resolveSnapshotStore(params.config),\n      emitter: adaptEmitter(\n        params.emitter,\n        generateRunId(\"orchestrator\"),\n        this.streamController as\n          | OrchestratorStreamController<unknown>\n          | undefined,\n      ),\n      memory: resolveOrchestratorMemory(params.config.memory),\n    };\n  }\n\n  /**\n   * `execute()` / `stream()` entry — run one turn through the 7-phase\n   * lifecycle. When a `streamController` was supplied, the adapter mirrors\n   * every emitted event into the stream and the controller is settled\n   * (`end` / `fail`) once the result resolves.\n   */\n  public async run(): Promise<OrchestratorResult<TOutput>> {\n    if (this.params.input === undefined || !this.params.options) {\n      throw new OrchestratorConfigError(\n        `ai.orchestrator(\"${this.params.config.name}\"): internal — run() invoked without input/options`,\n      );\n    }\n\n    try {\n      const result = await runTurn(\n        this.ctx,\n        this.params.input,\n        this.params.options,\n      );\n\n      this.streamController?.end(result);\n\n      return result;\n    } catch (error) {\n      this.streamController?.fail(error as Error);\n\n      throw error;\n    }\n  }\n\n  /**\n   * `resume()` entry — drain an interrupted `iterate: true` turn (§9).\n   * Returns `null` when nothing is in flight.\n   */\n  public async resume(): Promise<OrchestratorResult<TOutput> | null> {\n    if (!this.params.resumeSessionId) {\n      throw new OrchestratorConfigError(\n        `ai.orchestrator(\"${this.params.config.name}\"): internal — resume() invoked without a sessionId`,\n      );\n    }\n\n    return runResume(this.ctx, this.params.resumeSessionId, this.params.resumeOptions);\n  }\n\n  /**\n   * `command(\"compact\")` entry — run a manual compaction on demand (§11 /\n   * §12.1). Reuses the post-turn compaction code path against the\n   * caller-supplied history and returns the raw {@link CompactionResult}.\n   */\n  public async compact(\n    args: OrchestratorCommands[\"compact\"][\"args\"],\n  ): Promise<OrchestratorCommands[\"compact\"][\"result\"]> {\n    return runManualCompaction(\n      this.ctx as OrchestratorEngineContext<unknown, TState>,\n      args.history,\n    );\n  }\n}\n\n/**\n * Resolve the durable checkpoint store: the config's own field, falling\n * back to `ai.config({ defaultCheckpointStore })`. Throws\n * {@link OrchestratorConfigError} when neither resolves — persistence is\n * always on (§8.1), so a turn can never run without a checkpoint store.\n */\nfunction resolveCheckpointStore<TOutput, TState>(\n  config: OrchestratorConfig<TOutput, TState>,\n) {\n  const store = config.checkpointStore ?? resolveDefaultCheckpointStore();\n\n  if (!store) {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): a \\`checkpointStore\\` is required ` +\n        `(set one on the config or via \\`ai.config({ defaultCheckpointStore })\\`)`,\n    );\n  }\n\n  return store;\n}\n\n/**\n * Resolve the internal-supervisor snapshot store for `iterate: true`\n * turns: the config's own field, falling back to\n * `ai.config({ defaultSnapshotStore })`. Returns `undefined` for\n * `iterate: false` orchestrators (no mid-turn resume — nothing to\n * snapshot). The factory already guarantees presence when\n * `iterate: true`, so the engine never asserts here.\n */\nfunction resolveSnapshotStore<TOutput, TState>(\n  config: OrchestratorConfig<TOutput, TState>,\n) {\n  if (config.iterate !== true) {\n    return undefined;\n  }\n\n  return config.snapshotStore ?? resolveDefaultSnapshotStore();\n}\n\n/**\n * Adapt C1's three-tier {@link OrchestratorEmitter} (whose `emit` takes\n * `event, payload, identity, perCallHandlers?`) to the\n * {@link OrchestratorEmitterLike} port the phase modules call (a 2-arg\n * `emit(event, payload)` plus `bindPerCall`).\n *\n * The adapter injects the run identity centrally and, when a stream\n * controller is present, mirrors every fully-stamped event into the\n * stream pipe (§14.1 — the orchestrator's own events surface on the\n * stream alongside the bubbled child events). `bindPerCall` registers\n * the per-call `options.on` bag for the turn's duration and returns a\n * disposer that clears it.\n */\nfunction adaptEmitter(\n  emitter: OrchestratorEmitter,\n  runId: string,\n  streamController: OrchestratorStreamController<unknown> | undefined,\n): OrchestratorEmitterLike {\n  // `rootRunId === runId` for a standalone run; nested propagation lands\n  // in a follow-up (see `EventIdentity`).\n  const fullIdentity: EventIdentity = { runId, rootRunId: runId };\n\n  let perCall: OrchestratorEventHandlers | undefined;\n\n  return {\n    emit<K extends OrchestratorEventName>(\n      event: K,\n      payload: OrchestratorEventMap[K],\n    ): void {\n      const fullPayload = emitter.emit(event, payload, fullIdentity, perCall);\n\n      // The discriminated-union correlation between `type` and the\n      // matching payload variant can't be expressed structurally — the\n      // cast mirrors the supervisor stream's established pattern.\n      streamController?.push({ type: event, ...fullPayload } as OrchestratorEvent);\n    },\n    bindPerCall(handlers: OrchestratorEventHandlers | undefined): () => void {\n      perCall = handlers;\n\n      return () => {\n        perCall = undefined;\n      };\n    },\n  };\n}\n\n/**\n * Phase 2 — drift check (orchestrator.md §3 / §4 Phase 2). Compares the\n * loaded checkpoint's `signature` against the current definition's.\n * Mismatch throws `OrchestratorDriftError` synchronously unless\n * `force` is set. Emits `orchestrator.drift.checked` either way. A new\n * session (no loaded signature) never drifts.\n */\nfunction assertNoDrift(\n  ctx: OrchestratorEngineContext,\n  sessionId: string,\n  loadedSignature: string | undefined,\n  force: boolean | undefined,\n): void {\n  const drifted =\n    loadedSignature !== undefined && loadedSignature !== ctx.signature;\n\n  ctx.emitter.emit(\"orchestrator.drift.checked\", {\n    sessionId,\n    signature: ctx.signature,\n    drifted,\n  });\n\n  if (drifted && !force) {\n    throw new OrchestratorDriftError(\n      `orchestrator \"${ctx.config.name}\": signature drift on session \"${sessionId}\" — ` +\n        `the definition changed since this session was last persisted. ` +\n        `Pass { force: true } only after reviewing the change, or discard / migrate the session.`,\n      {\n        savedSignature: loadedSignature as string,\n        currentSignature: ctx.signature,\n        sessionId,\n      },\n    );\n  }\n}\n\n/**\n * Shallow-merge the per-call `state` patch (§5 — partial state\n * override) over the loaded session-state seed. The merged value\n * becomes the supervisor's seed for this turn.\n */\nfunction applyStatePatch<TState>(\n  seed: TState,\n  patch: Partial<TState> | undefined,\n): TState {\n  if (!patch) {\n    return seed;\n  }\n\n  return { ...seed, ...patch } as TState;\n}\n\n/**\n * Assemble the orchestrator-scope {@link OrchestratorReport} from the\n * dispatched turn's child report and the turn snapshot. Wraps the\n * child supervisor/agent report tree as `children[0]` (§15.6 —\n * `children[]` carries only the CURRENT turn's dispatched primitive\n * reports) while the per-turn forensic record lives on `turns[]`.\n */\nfunction buildReport(\n  ctx: OrchestratorEngineContext,\n  sessionId: string,\n  turnIndex: number,\n  status: OrchestratorReportStatus,\n  turnSnapshot: TurnSnapshot | undefined,\n  childReport: BaseReport | undefined,\n): OrchestratorReport {\n  const now = new Date().toISOString();\n  const usage = turnSnapshot?.usage ?? childReport?.usage ?? ZERO_USAGE;\n\n  return {\n    runId: deriveRunId(sessionId, ctx.config.version, turnIndex),\n    rootRunId: deriveRunId(sessionId, ctx.config.version, turnIndex),\n    name: ctx.config.name,\n    version: ctx.config.version,\n    sessionId,\n    type: \"orchestrator\",\n    status,\n    startedAt: turnSnapshot?.startedAt ?? now,\n    endedAt: turnSnapshot?.endedAt ?? now,\n    duration: turnSnapshot?.duration ?? 0,\n    usage,\n    children: childReport ? [childReport] : [],\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n    turnIndex,\n    signature: ctx.signature,\n    turns: turnSnapshot ? [turnSnapshot] : [],\n  };\n}\n\n/**\n * Map the dispatched supervisor result's report status onto the\n * orchestrator's status surface (§15.6). A clean completion that is\n * still mid-conversation reports `\"awaiting-input\"` (the session\n * continues) rather than `\"completed\"`; failures and cancellations\n * pass through.\n */\nfunction deriveStatus(childStatus: BaseReport[\"status\"]): OrchestratorReportStatus {\n  if (childStatus === \"completed\") {\n    return \"awaiting-input\";\n  }\n\n  return childStatus;\n}\n\n/**\n * Emit the terminal turn event matching the report status (§14.1).\n */\nfunction emitTerminal(\n  ctx: OrchestratorEngineContext,\n  sessionId: string,\n  turnIndex: number,\n  status: OrchestratorReportStatus,\n): void {\n  if (status === \"cancelled\") {\n    ctx.emitter.emit(\"orchestrator.turn.cancelled\", { sessionId, turnIndex });\n\n    return;\n  }\n\n  if (status === \"failed\" || status === \"max-iterations\") {\n    ctx.emitter.emit(\"orchestrator.turn.failed\", { sessionId, turnIndex });\n\n    return;\n  }\n\n  if (status === \"awaiting-input\") {\n    ctx.emitter.emit(\"orchestrator.turn.awaiting-input\", {\n      sessionId,\n      turnIndex,\n    });\n\n    return;\n  }\n\n  ctx.emitter.emit(\"orchestrator.turn.completed\", { sessionId, turnIndex });\n}\n\n/**\n * Run one turn end-to-end through the 7-phase lifecycle (orchestrator\n * .md §3). The single entry the C1 factory's `execute()` delegates to.\n *\n * Phase order is the diagram's contract: load → drift → lock → window\n * → dispatch → persist → compaction. Drift / config misuse throw;\n * every other failure surfaces on `result.error` (the contract: the\n * orchestrator never throws on runtime failure). Cancellation and\n * failure do NOT persist a fresh checkpoint (§17 — state reverts to the\n * pre-turn checkpoint).\n */\nexport async function runTurn<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  input: SupervisorInput,\n  options: OrchestratorExecuteOptions<TState>,\n): Promise<OrchestratorResult<TOutput>> {\n  const sessionId = options.sessionId;\n  const disposePerCall = ctx.emitter.bindPerCall(options.on);\n\n  try {\n    // Phase 1 — load session.\n    const loaded = await loadSession(ctx, sessionId);\n\n    ctx.emitter.emit(\"orchestrator.turn.starting\", {\n      sessionId,\n      turnIndex: loaded.turnIndex,\n    });\n\n    ctx.emitter.emit(\"orchestrator.session.loaded\", {\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      found: loaded.found,\n    });\n\n    // Phase 2 — drift check.\n    assertNoDrift(\n      ctx as OrchestratorEngineContext,\n      sessionId,\n      loaded.record?.signature,\n      options.force,\n    );\n\n    // Phase 3 — lock check (cooperative, fail-open).\n    await acquireLock(ctx, sessionId, loaded.record);\n\n    // Phase 4 — window history.\n    const windowed = windowHistory(\n      ctx as OrchestratorEngineContext,\n      sessionId,\n      options.history,\n    );\n\n    // Phase 5 — dispatch. When memory is configured, recall the\n    // turn-relevant memories and inject them into the request-scoped\n    // context bag so every route / router / evaluate / dispatch callback\n    // surfaces them at `ctx.context[injectKey]` before routing runs.\n    const seedState = applyStatePatch(loaded.state, options.state);\n\n    let turnContext = options.context;\n\n    if (ctx.memory) {\n      const recalled = await recallForTurn(ctx.memory, input);\n      turnContext = injectMemories(turnContext, ctx.memory, recalled);\n    }\n\n    const { result, state, turnSnapshot } = await dispatchTurn<TOutput, TState>({\n      ctx,\n      sessionId,\n      input,\n      seedState,\n      turnIndex: loaded.turnIndex,\n      history: windowed.agents,\n      context: turnContext,\n      signal: options.signal,\n    });\n\n    ctx.emitter.emit(\"orchestrator.turn.routed\", {\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      source: turnSnapshot.decision.source,\n      raw: turnSnapshot.decision.raw,\n    });\n\n    const status = result.error\n      ? deriveStatus(result.report.status)\n      : \"awaiting-input\";\n\n    // Cancelled / failed turns revert: no fresh checkpoint, no compaction.\n    if (result.error) {\n      const report = buildReport(\n        ctx as OrchestratorEngineContext,\n        sessionId,\n        loaded.turnIndex,\n        status,\n        turnSnapshot,\n        result.report,\n      );\n\n      emitTerminal(ctx as OrchestratorEngineContext, sessionId, loaded.turnIndex, status);\n\n      return {\n        data: result.data,\n        error: result.error,\n        usage: result.usage,\n        report,\n        sessionId,\n        turnIndex: loaded.turnIndex,\n      };\n    }\n\n    // Phase 6 — persist checkpoint.\n    await persistCheckpoint({\n      ctx,\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      state,\n      lastRoute: summarizeRoute(turnSnapshot.decision.raw as never),\n      summarizedThrough: loaded.record?.summarized_through ?? null,\n    });\n\n    // Memory write-back (memory core M2). The turn settled cleanly (the\n    // `result.error` branch above already returned for cancelled /\n    // failed turns, which revert and never remember — §17), so remember\n    // the input + its outcome for later recall.\n    if (ctx.memory) {\n      await rememberTurnOutcome(\n        ctx.memory,\n        input,\n        outcomeTextFromTurn(result.data, turnSnapshot),\n      );\n    }\n\n    // Phase 7 — post-turn compaction (only when triggered).\n    let compaction: CompactionResult | undefined;\n\n    if (shouldCompact(ctx as OrchestratorEngineContext, loaded.turnIndex)) {\n      const outcome = await runCompaction(\n        ctx as OrchestratorEngineContext<unknown, TState>,\n        sessionId,\n        options.history,\n      );\n\n      if (outcome) {\n        compaction = outcome.compaction;\n\n        if (outcome.applied) {\n          await advanceSummarizedThrough(\n            ctx as OrchestratorEngineContext<unknown, TState>,\n            sessionId,\n            outcome.compaction.replacesToIndex,\n          );\n        }\n      }\n    }\n\n    const report = buildReport(\n      ctx as OrchestratorEngineContext,\n      sessionId,\n      loaded.turnIndex,\n      \"awaiting-input\",\n      turnSnapshot,\n      result.report,\n    );\n\n    emitTerminal(ctx as OrchestratorEngineContext, sessionId, loaded.turnIndex, \"awaiting-input\");\n\n    return {\n      data: result.data,\n      error: undefined,\n      usage: result.usage,\n      report,\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      compaction,\n    };\n  } finally {\n    disposePerCall();\n  }\n}\n\n/**\n * After a framework-applied compaction (`onCompact` succeeded), advance\n * the persisted `summarized_through` to the compaction's\n * `replacesToIndex` (§12.2 step 4). Re-saves the latest row with the\n * updated marker (append-only stores keep the prior row).\n */\nasync function advanceSummarizedThrough<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  replacesToIndex: number,\n): Promise<void> {\n  const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n\n  if (!latest) {\n    return;\n  }\n\n  await ctx.checkpointStore.save({\n    ...latest,\n    summarized_through: replacesToIndex,\n    saved_at: new Date().toISOString(),\n  });\n}\n\n/**\n * §9 resume protocol entry the C1 factory's `resume()` delegates to.\n * Returns `null` when no in-flight `iterate: true` turn is detected;\n * otherwise drains the interrupted supervisor run, persists a fresh\n * checkpoint for the resumed turn, and returns the completed result.\n *\n * Runs the same Phase 2 drift check as `runTurn` (§9.4). The heavy\n * lifting lives in `resume.ts`; this wrapper threads the engine\n * context.\n */\nexport async function runResume<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  sessionId: string,\n  options?: OrchestratorResumeOptions,\n): Promise<OrchestratorResult<TOutput> | null> {\n  const disposePerCall = ctx.emitter.bindPerCall(options?.on);\n\n  try {\n    return await resolveResume(ctx, sessionId, options, {\n      assertNoDrift: (loadedSignature) =>\n        assertNoDrift(\n          ctx as OrchestratorEngineContext,\n          sessionId,\n          loadedSignature,\n          options?.force,\n        ),\n      buildReport: (turnIndex, status, turnSnapshot, childReport) =>\n        buildReport(\n          ctx as OrchestratorEngineContext,\n          sessionId,\n          turnIndex,\n          status,\n          turnSnapshot,\n          childReport,\n        ),\n      deriveStatus,\n      emitTerminal: (turnIndex, status) =>\n        emitTerminal(ctx as OrchestratorEngineContext, sessionId, turnIndex, status),\n      persist: (turnIndex, state, lastRoute, summarizedThrough) =>\n        persistCheckpoint({\n          ctx,\n          sessionId,\n          turnIndex,\n          state,\n          lastRoute,\n          summarizedThrough,\n        }),\n    });\n  } finally {\n    disposePerCall();\n  }\n}\n\n/**\n * The `stream()` entry. The orchestrator's streaming surface bubbles\n * child agent/supervisor events under their own namespace (§14.2); the\n * C1 stream controller owns the `StreamContract` wiring. This engine\n * entry runs the same lifecycle as `runTurn` — the C1 factory passes a\n * per-call `on` bag wired to the stream controller, so the engine needs\n * no streaming-specific branch. Exposed as a distinct name for the\n * factory to call, returning the same `OrchestratorResult` the stream's\n * `.result` resolves to.\n */\nexport async function streamTurn<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  input: SupervisorInput,\n  options: OrchestratorExecuteOptions<TState>,\n): Promise<OrchestratorResult<TOutput>> {\n  return runTurn(ctx, input, options);\n}\n\nexport type { OrchestratorEngineContext } from \"./engine-context.type\";\nexport type { Message };\n"],"mappings":"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"}
+{"version":3,"file":"execution.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/execution.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type { OrchestratorCommands } from \"../contracts/orchestrator/orchestrator-commands.type\";\nimport type { OrchestratorConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type {\n  OrchestratorEvent,\n  OrchestratorEventHandlers,\n  OrchestratorEventMap,\n  OrchestratorEventName,\n} from \"../contracts/orchestrator/orchestrator-event.type\";\nimport type {\n  OrchestratorExecuteOptions,\n  OrchestratorResumeOptions,\n} from \"../contracts/orchestrator/orchestrator-execute-options.type\";\nimport type {\n  CompactionResult,\n  OrchestratorReport,\n  OrchestratorReportStatus,\n  OrchestratorResult,\n  TurnSnapshot,\n} from \"../contracts/result/orchestrator-result.type\";\nimport { REPORT_SCHEMA_VERSION } from \"../contracts/result/base-report.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type { EventIdentity } from \"../contracts/events/event-identity.type\";\nimport {\n  resolveDefaultCheckpointStore,\n  resolveDefaultSnapshotStore,\n} from \"../config\";\nimport type { AIError } from \"../errors/ai-error\";\nimport { OrchestratorConfigError, OrchestratorDriftError } from \"../errors\";\nimport { notifyObservers } from \"../observe/resolve-observers\";\nimport type { ResolvedIntentEntry } from \"../supervisor/entries\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport { persistCheckpoint, summarizeRoute } from \"./checkpoint\";\nimport { runCompaction, runManualCompaction, shouldCompact } from \"./compaction\";\nimport { deriveRunId, dispatchTurn } from \"./dispatch\";\nimport type { OrchestratorEmitter } from \"./emitter\";\nimport type { OrchestratorEmitterLike } from \"./emitter-port.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\nimport { acquireLock } from \"./lock\";\nimport { loadSession } from \"./load\";\nimport {\n  injectMemories,\n  outcomeTextFromTurn,\n  recallForTurn,\n  rememberTurnOutcome,\n  resolveOrchestratorMemory,\n} from \"./memory\";\nimport type { OrchestratorStreamController } from \"./orchestrator-stream\";\nimport { resolveResume } from \"./resume\";\nimport { windowHistory } from \"./window\";\n\n/** Empty rolled-up usage for turns that never dispatched (drift/seed). */\nconst ZERO_USAGE: Usage = { input: 0, output: 0, total: 0 };\n\n/**\n * Constructor params the C1 factory passes when building an\n * {@link OrchestratorExecution} per call. The factory owns author-time\n * validation, intent-entry resolution, and signature computation; it\n * hands the engine the validated `config`, the resolved `entries`, the\n * computed `signature`, and the shared three-tier `emitter`. The\n * per-call inputs vary by entry point:\n *\n * - `execute` / `stream` — `input` + `options` (and `streamController`\n *   for `stream`).\n * - `resume` — `resumeSessionId` + `resumeOptions`.\n * - `command(\"compact\")` — neither; `compact(args)` carries its own.\n */\nexport type OrchestratorExecutionParams<TOutput, TState> = {\n  config: OrchestratorConfig<TOutput, TState>;\n  /** Resolved intent entries (validated by C1; the engine delegates dispatch to the supervisor). */\n  entries?: Map<string, ResolvedIntentEntry>;\n  signature: string;\n  emitter: OrchestratorEmitter;\n  input?: SupervisorInput;\n  options?: OrchestratorExecuteOptions<TState>;\n  streamController?: OrchestratorStreamController<OrchestratorResult<TOutput>>;\n  resumeSessionId?: string;\n  resumeOptions?: OrchestratorResumeOptions;\n};\n\n/**\n * Per-call lifecycle engine — the single object the C1 factory\n * constructs and drives. Owns the 7-phase lifecycle (orchestrator.md §3:\n * load → drift → lock → window → dispatch → persist → compaction),\n * resolving the durable stores (own config field → `ai.config` default)\n * and adapting C1's three-tier {@link OrchestratorEmitter} to the\n * {@link OrchestratorEmitterLike} port the phase modules call.\n *\n * The factory creates a fresh instance per `execute` / `stream` /\n * `resume` / `command` call (single-call lifecycle invariant — §18.8);\n * the heavy lifting lives in the standalone phase functions\n * ({@link runTurn} / {@link runResume}) which this class delegates to.\n *\n * @example\n * const execution = new OrchestratorExecution({\n *   config, entries, signature, emitter, input, options,\n * });\n * const result = await execution.run();\n */\nexport class OrchestratorExecution<TOutput, TState> {\n  private readonly params: OrchestratorExecutionParams<TOutput, TState>;\n  private readonly ctx: OrchestratorEngineContext<TOutput, TState>;\n  private readonly streamController?: OrchestratorStreamController<\n    OrchestratorResult<TOutput>\n  >;\n\n  public constructor(params: OrchestratorExecutionParams<TOutput, TState>) {\n    this.params = params;\n    this.streamController = params.streamController;\n    this.ctx = {\n      config: params.config,\n      signature: params.signature,\n      checkpointStore: resolveCheckpointStore(params.config),\n      snapshotStore: resolveSnapshotStore(params.config),\n      emitter: adaptEmitter(\n        params.emitter,\n        generateRunId(\"orchestrator\"),\n        this.streamController as\n          | OrchestratorStreamController<unknown>\n          | undefined,\n      ),\n      memory: resolveOrchestratorMemory(params.config.memory),\n    };\n  }\n\n  /**\n   * `execute()` / `stream()` entry — run one turn through the 7-phase\n   * lifecycle. When a `streamController` was supplied, the adapter mirrors\n   * every emitted event into the stream and the controller is settled\n   * (`end` / `fail`) once the result resolves.\n   */\n  public async run(): Promise<OrchestratorResult<TOutput>> {\n    if (this.params.input === undefined || !this.params.options) {\n      throw new OrchestratorConfigError(\n        `ai.orchestrator(\"${this.params.config.name}\"): internal — run() invoked without input/options`,\n      );\n    }\n\n    try {\n      const result = await runTurn(\n        this.ctx,\n        this.params.input,\n        this.params.options,\n      );\n\n      // Route the orchestrator's report to observers (per-flow `observe` +\n      // the global observe-all gate) — parity with agent/workflow/supervisor,\n      // so a durable session root no longer needs a manual observe.collect().\n      await notifyObservers(this.ctx.config.observe, result.report);\n\n      this.streamController?.end(result);\n\n      return result;\n    } catch (error) {\n      this.streamController?.fail(error as Error);\n\n      throw error;\n    }\n  }\n\n  /**\n   * `resume()` entry — drain an interrupted `iterate: true` turn (§9).\n   * Returns `null` when nothing is in flight.\n   */\n  public async resume(): Promise<OrchestratorResult<TOutput> | null> {\n    if (!this.params.resumeSessionId) {\n      throw new OrchestratorConfigError(\n        `ai.orchestrator(\"${this.params.config.name}\"): internal — resume() invoked without a sessionId`,\n      );\n    }\n\n    return runResume(this.ctx, this.params.resumeSessionId, this.params.resumeOptions);\n  }\n\n  /**\n   * `command(\"compact\")` entry — run a manual compaction on demand (§11 /\n   * §12.1). Reuses the post-turn compaction code path against the\n   * caller-supplied history and returns the raw {@link CompactionResult}.\n   */\n  public async compact(\n    args: OrchestratorCommands[\"compact\"][\"args\"],\n  ): Promise<OrchestratorCommands[\"compact\"][\"result\"]> {\n    return runManualCompaction(\n      this.ctx as OrchestratorEngineContext<unknown, TState>,\n      args.history,\n    );\n  }\n}\n\n/**\n * Resolve the durable checkpoint store: the config's own field, falling\n * back to `ai.config({ defaultCheckpointStore })`. Throws\n * {@link OrchestratorConfigError} when neither resolves — persistence is\n * always on (§8.1), so a turn can never run without a checkpoint store.\n */\nfunction resolveCheckpointStore<TOutput, TState>(\n  config: OrchestratorConfig<TOutput, TState>,\n) {\n  const store = config.checkpointStore ?? resolveDefaultCheckpointStore();\n\n  if (!store) {\n    throw new OrchestratorConfigError(\n      `ai.orchestrator(\"${config.name}\"): a \\`checkpointStore\\` is required ` +\n        `(set one on the config or via \\`ai.config({ defaultCheckpointStore })\\`)`,\n    );\n  }\n\n  return store;\n}\n\n/**\n * Resolve the internal-supervisor snapshot store for `iterate: true`\n * turns: the config's own field, falling back to\n * `ai.config({ defaultSnapshotStore })`. Returns `undefined` for\n * `iterate: false` orchestrators (no mid-turn resume — nothing to\n * snapshot). The factory already guarantees presence when\n * `iterate: true`, so the engine never asserts here.\n */\nfunction resolveSnapshotStore<TOutput, TState>(\n  config: OrchestratorConfig<TOutput, TState>,\n) {\n  if (config.iterate !== true) {\n    return undefined;\n  }\n\n  return config.snapshotStore ?? resolveDefaultSnapshotStore();\n}\n\n/**\n * Adapt C1's three-tier {@link OrchestratorEmitter} (whose `emit` takes\n * `event, payload, identity, perCallHandlers?`) to the\n * {@link OrchestratorEmitterLike} port the phase modules call (a 2-arg\n * `emit(event, payload)` plus `bindPerCall`).\n *\n * The adapter injects the run identity centrally and, when a stream\n * controller is present, mirrors every fully-stamped event into the\n * stream pipe (§14.1 — the orchestrator's own events surface on the\n * stream alongside the bubbled child events). `bindPerCall` registers\n * the per-call `options.on` bag for the turn's duration and returns a\n * disposer that clears it.\n */\nfunction adaptEmitter(\n  emitter: OrchestratorEmitter,\n  runId: string,\n  streamController: OrchestratorStreamController<unknown> | undefined,\n): OrchestratorEmitterLike {\n  // `rootRunId === runId` for a standalone run; nested propagation lands\n  // in a follow-up (see `EventIdentity`).\n  const fullIdentity: EventIdentity = { runId, rootRunId: runId };\n\n  let perCall: OrchestratorEventHandlers | undefined;\n\n  return {\n    emit<K extends OrchestratorEventName>(\n      event: K,\n      payload: OrchestratorEventMap[K],\n    ): void {\n      const fullPayload = emitter.emit(event, payload, fullIdentity, perCall);\n\n      // The discriminated-union correlation between `type` and the\n      // matching payload variant can't be expressed structurally — the\n      // cast mirrors the supervisor stream's established pattern.\n      streamController?.push({ type: event, ...fullPayload } as OrchestratorEvent);\n    },\n    bindPerCall(handlers: OrchestratorEventHandlers | undefined): () => void {\n      perCall = handlers;\n\n      return () => {\n        perCall = undefined;\n      };\n    },\n  };\n}\n\n/**\n * Phase 2 — drift check (orchestrator.md §3 / §4 Phase 2). Compares the\n * loaded checkpoint's `signature` against the current definition's.\n * Mismatch throws `OrchestratorDriftError` synchronously unless\n * `force` is set. Emits `orchestrator.drift.checked` either way. A new\n * session (no loaded signature) never drifts.\n */\nfunction assertNoDrift(\n  ctx: OrchestratorEngineContext,\n  sessionId: string,\n  loadedSignature: string | undefined,\n  force: boolean | undefined,\n): void {\n  const drifted =\n    loadedSignature !== undefined && loadedSignature !== ctx.signature;\n\n  ctx.emitter.emit(\"orchestrator.drift.checked\", {\n    sessionId,\n    signature: ctx.signature,\n    drifted,\n  });\n\n  if (drifted && !force) {\n    throw new OrchestratorDriftError(\n      `orchestrator \"${ctx.config.name}\": signature drift on session \"${sessionId}\" — ` +\n        `the definition changed since this session was last persisted. ` +\n        `Pass { force: true } only after reviewing the change, or discard / migrate the session.`,\n      {\n        savedSignature: loadedSignature as string,\n        currentSignature: ctx.signature,\n        sessionId,\n      },\n    );\n  }\n}\n\n/**\n * Shallow-merge the per-call `state` patch (§5 — partial state\n * override) over the loaded session-state seed. The merged value\n * becomes the supervisor's seed for this turn.\n */\nfunction applyStatePatch<TState>(\n  seed: TState,\n  patch: Partial<TState> | undefined,\n): TState {\n  if (!patch) {\n    return seed;\n  }\n\n  return { ...seed, ...patch } as TState;\n}\n\n/**\n * Assemble the orchestrator-scope {@link OrchestratorReport} from the\n * dispatched turn's child report and the turn snapshot. Wraps the\n * child supervisor/agent report tree as `children[0]` (§15.6 —\n * `children[]` carries only the CURRENT turn's dispatched primitive\n * reports) while the per-turn forensic record lives on `turns[]`.\n */\nfunction buildReport(\n  ctx: OrchestratorEngineContext,\n  sessionId: string,\n  turnIndex: number,\n  status: OrchestratorReportStatus,\n  turnSnapshot: TurnSnapshot | undefined,\n  childReport: BaseReport | undefined,\n  error?: AIError,\n): OrchestratorReport {\n  const now = new Date().toISOString();\n  const usage = turnSnapshot?.usage ?? childReport?.usage ?? ZERO_USAGE;\n\n  return {\n    runId: deriveRunId(sessionId, ctx.config.version, turnIndex),\n    rootRunId: deriveRunId(sessionId, ctx.config.version, turnIndex),\n    name: ctx.config.name,\n    version: ctx.config.version,\n    sessionId,\n    type: \"orchestrator\",\n    status,\n    // Stamp the terminal error so the observe path surfaces it on the\n    // orchestrator span (an observer never sees the result envelope).\n    // Absent on a clean turn.\n    ...(error ? { error } : {}),\n    startedAt: turnSnapshot?.startedAt ?? now,\n    endedAt: turnSnapshot?.endedAt ?? now,\n    duration: turnSnapshot?.duration ?? 0,\n    usage,\n    children: childReport ? [childReport] : [],\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n    turnIndex,\n    signature: ctx.signature,\n    turns: turnSnapshot ? [turnSnapshot] : [],\n  };\n}\n\n/**\n * Map the dispatched supervisor result's report status onto the\n * orchestrator's status surface (§15.6). A clean completion that is\n * still mid-conversation reports `\"awaiting-input\"` (the session\n * continues) rather than `\"completed\"`; failures and cancellations\n * pass through.\n */\nfunction deriveStatus(childStatus: BaseReport[\"status\"]): OrchestratorReportStatus {\n  if (childStatus === \"completed\") {\n    return \"awaiting-input\";\n  }\n\n  return childStatus;\n}\n\n/**\n * Emit the terminal turn event matching the report status (§14.1).\n */\nfunction emitTerminal(\n  ctx: OrchestratorEngineContext,\n  sessionId: string,\n  turnIndex: number,\n  status: OrchestratorReportStatus,\n): void {\n  if (status === \"cancelled\") {\n    ctx.emitter.emit(\"orchestrator.turn.cancelled\", { sessionId, turnIndex });\n\n    return;\n  }\n\n  if (status === \"failed\" || status === \"max-iterations\") {\n    ctx.emitter.emit(\"orchestrator.turn.failed\", { sessionId, turnIndex });\n\n    return;\n  }\n\n  if (status === \"awaiting-input\") {\n    ctx.emitter.emit(\"orchestrator.turn.awaiting-input\", {\n      sessionId,\n      turnIndex,\n    });\n\n    return;\n  }\n\n  ctx.emitter.emit(\"orchestrator.turn.completed\", { sessionId, turnIndex });\n}\n\n/**\n * Run one turn end-to-end through the 7-phase lifecycle (orchestrator\n * .md §3). The single entry the C1 factory's `execute()` delegates to.\n *\n * Phase order is the diagram's contract: load → drift → lock → window\n * → dispatch → persist → compaction. Drift / config misuse throw;\n * every other failure surfaces on `result.error` (the contract: the\n * orchestrator never throws on runtime failure). Cancellation and\n * failure do NOT persist a fresh checkpoint (§17 — state reverts to the\n * pre-turn checkpoint).\n */\nexport async function runTurn<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  input: SupervisorInput,\n  options: OrchestratorExecuteOptions<TState>,\n): Promise<OrchestratorResult<TOutput>> {\n  const sessionId = options.sessionId;\n  const disposePerCall = ctx.emitter.bindPerCall(options.on);\n\n  try {\n    // Phase 1 — load session.\n    const loaded = await loadSession(ctx, sessionId);\n\n    ctx.emitter.emit(\"orchestrator.turn.starting\", {\n      sessionId,\n      turnIndex: loaded.turnIndex,\n    });\n\n    ctx.emitter.emit(\"orchestrator.session.loaded\", {\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      found: loaded.found,\n    });\n\n    // Phase 2 — drift check.\n    assertNoDrift(\n      ctx as OrchestratorEngineContext,\n      sessionId,\n      loaded.record?.signature,\n      options.force,\n    );\n\n    // Phase 3 — lock check (cooperative, fail-open).\n    await acquireLock(ctx, sessionId, loaded.record);\n\n    // Phase 4 — window history.\n    const windowed = windowHistory(\n      ctx as OrchestratorEngineContext,\n      sessionId,\n      options.history,\n    );\n\n    // Phase 5 — dispatch. When memory is configured, recall the\n    // turn-relevant memories and inject them into the request-scoped\n    // context bag so every route / router / evaluate / dispatch callback\n    // surfaces them at `ctx.context[injectKey]` before routing runs.\n    const seedState = applyStatePatch(loaded.state, options.state);\n\n    let turnContext = options.context;\n\n    if (ctx.memory) {\n      const recalled = await recallForTurn(ctx.memory, input);\n      turnContext = injectMemories(turnContext, ctx.memory, recalled);\n    }\n\n    const { result, state, turnSnapshot } = await dispatchTurn<TOutput, TState>({\n      ctx,\n      sessionId,\n      input,\n      seedState,\n      turnIndex: loaded.turnIndex,\n      history: windowed.agents,\n      context: turnContext,\n      signal: options.signal,\n    });\n\n    ctx.emitter.emit(\"orchestrator.turn.routed\", {\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      source: turnSnapshot.decision.source,\n      raw: turnSnapshot.decision.raw,\n    });\n\n    const status = result.error\n      ? deriveStatus(result.report.status)\n      : \"awaiting-input\";\n\n    // Cancelled / failed turns revert: no fresh checkpoint, no compaction.\n    if (result.error) {\n      const report = buildReport(\n        ctx as OrchestratorEngineContext,\n        sessionId,\n        loaded.turnIndex,\n        status,\n        turnSnapshot,\n        result.report,\n        result.error,\n      );\n\n      emitTerminal(ctx as OrchestratorEngineContext, sessionId, loaded.turnIndex, status);\n\n      return {\n        data: result.data,\n        error: result.error,\n        usage: result.usage,\n        report,\n        sessionId,\n        turnIndex: loaded.turnIndex,\n      };\n    }\n\n    // Phase 6 — persist checkpoint.\n    await persistCheckpoint({\n      ctx,\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      state,\n      lastRoute: summarizeRoute(turnSnapshot.decision.raw as never),\n      summarizedThrough: loaded.record?.summarized_through ?? null,\n    });\n\n    // Memory write-back (memory core M2). The turn settled cleanly (the\n    // `result.error` branch above already returned for cancelled /\n    // failed turns, which revert and never remember — §17), so remember\n    // the input + its outcome for later recall.\n    if (ctx.memory) {\n      await rememberTurnOutcome(\n        ctx.memory,\n        input,\n        outcomeTextFromTurn(result.data, turnSnapshot),\n      );\n    }\n\n    // Phase 7 — post-turn compaction (only when triggered).\n    let compaction: CompactionResult | undefined;\n\n    if (shouldCompact(ctx as OrchestratorEngineContext, loaded.turnIndex)) {\n      const outcome = await runCompaction(\n        ctx as OrchestratorEngineContext<unknown, TState>,\n        sessionId,\n        options.history,\n      );\n\n      if (outcome) {\n        compaction = outcome.compaction;\n\n        if (outcome.applied) {\n          await advanceSummarizedThrough(\n            ctx as OrchestratorEngineContext<unknown, TState>,\n            sessionId,\n            outcome.compaction.replacesToIndex,\n          );\n        }\n      }\n    }\n\n    const report = buildReport(\n      ctx as OrchestratorEngineContext,\n      sessionId,\n      loaded.turnIndex,\n      \"awaiting-input\",\n      turnSnapshot,\n      result.report,\n    );\n\n    emitTerminal(ctx as OrchestratorEngineContext, sessionId, loaded.turnIndex, \"awaiting-input\");\n\n    return {\n      data: result.data,\n      error: undefined,\n      usage: result.usage,\n      report,\n      sessionId,\n      turnIndex: loaded.turnIndex,\n      compaction,\n    };\n  } finally {\n    disposePerCall();\n  }\n}\n\n/**\n * After a framework-applied compaction (`onCompact` succeeded), advance\n * the persisted `summarized_through` to the compaction's\n * `replacesToIndex` (§12.2 step 4). Re-saves the latest row with the\n * updated marker (append-only stores keep the prior row).\n */\nasync function advanceSummarizedThrough<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  replacesToIndex: number,\n): Promise<void> {\n  const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n\n  if (!latest) {\n    return;\n  }\n\n  await ctx.checkpointStore.save({\n    ...latest,\n    summarized_through: replacesToIndex,\n    saved_at: new Date().toISOString(),\n  });\n}\n\n/**\n * §9 resume protocol entry the C1 factory's `resume()` delegates to.\n * Returns `null` when no in-flight `iterate: true` turn is detected;\n * otherwise drains the interrupted supervisor run, persists a fresh\n * checkpoint for the resumed turn, and returns the completed result.\n *\n * Runs the same Phase 2 drift check as `runTurn` (§9.4). The heavy\n * lifting lives in `resume.ts`; this wrapper threads the engine\n * context.\n */\nexport async function runResume<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  sessionId: string,\n  options?: OrchestratorResumeOptions,\n): Promise<OrchestratorResult<TOutput> | null> {\n  const disposePerCall = ctx.emitter.bindPerCall(options?.on);\n\n  try {\n    return await resolveResume(ctx, sessionId, options, {\n      assertNoDrift: (loadedSignature) =>\n        assertNoDrift(\n          ctx as OrchestratorEngineContext,\n          sessionId,\n          loadedSignature,\n          options?.force,\n        ),\n      buildReport: (turnIndex, status, turnSnapshot, childReport) =>\n        buildReport(\n          ctx as OrchestratorEngineContext,\n          sessionId,\n          turnIndex,\n          status,\n          turnSnapshot,\n          childReport,\n        ),\n      deriveStatus,\n      emitTerminal: (turnIndex, status) =>\n        emitTerminal(ctx as OrchestratorEngineContext, sessionId, turnIndex, status),\n      persist: (turnIndex, state, lastRoute, summarizedThrough) =>\n        persistCheckpoint({\n          ctx,\n          sessionId,\n          turnIndex,\n          state,\n          lastRoute,\n          summarizedThrough,\n        }),\n    });\n  } finally {\n    disposePerCall();\n  }\n}\n\n/**\n * The `stream()` entry. The orchestrator's streaming surface bubbles\n * child agent/supervisor events under their own namespace (§14.2); the\n * C1 stream controller owns the `StreamContract` wiring. This engine\n * entry runs the same lifecycle as `runTurn` — the C1 factory passes a\n * per-call `on` bag wired to the stream controller, so the engine needs\n * no streaming-specific branch. Exposed as a distinct name for the\n * factory to call, returning the same `OrchestratorResult` the stream's\n * `.result` resolves to.\n */\nexport async function streamTurn<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  input: SupervisorInput,\n  options: OrchestratorExecuteOptions<TState>,\n): Promise<OrchestratorResult<TOutput>> {\n  return runTurn(ctx, input, options);\n}\n\nexport type { OrchestratorEngineContext } from \"./engine-context.type\";\nexport type { Message };\n"],"mappings":"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"}

package/esm/orchestrator/index.d.mts

@@ -5,4 +5,5 @@ import { ResolvedOrchestratorMemory, injectMemories, memoryQueryFromInput, outco
 import { OrchestratorStreamController, createOrchestratorStream } from "./orchestrator-stream.mjs";
 import { OrchestratorExecution, OrchestratorExecutionParams, runResume, runTurn, streamTurn } from "./execution.mjs";
 import { orchestrator } from "./orchestrator.mjs";
+import { inProcessSessionLock, noopSessionLock } from "./session-lock.mjs";
 import { computeOrchestratorSignature } from "./signature.mjs";

package/esm/orchestrator/index.mjs

@@ -4,6 +4,7 @@ import { OrchestratorEmitter } from "./emitter.mjs";
 import { injectMemories, memoryQueryFromInput, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory } from "./memory.mjs";
 import { OrchestratorExecution, runResume, runTurn, streamTurn } from "./execution.mjs";
 import { createOrchestratorStream } from "./orchestrator-stream.mjs";
+import { inProcessSessionLock, noopSessionLock } from "./session-lock.mjs";
 import { computeOrchestratorSignature } from "./signature.mjs";
 import { orchestrator } from "./orchestrator.mjs";
 

package/esm/orchestrator/orchestrator.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/orchestrator.ts"],"mappings":";;;;;;;AA4DA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,YAAA,6BAEL,OAAA,mBACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAEvD,qBAAA,GAGF,MAAA,EAAQ,kBAAA,CAAmB,OAAA,EAAS,MAAA,EAAQ,QAAA,IAC3C,oBAAA,CAAqB,OAAA,EAAS,MAAA"}
+{"version":3,"file":"orchestrator.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/orchestrator.ts"],"mappings":";;;;;;;AA8DA;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,YAAA,6BAEL,OAAA,mBACQ,MAAA,SAAe,qBAAA,IAAyB,MAAA,SAEvD,qBAAA,GAGF,MAAA,EAAQ,kBAAA,CAAmB,OAAA,EAAS,MAAA,EAAQ,QAAA,IAC3C,oBAAA,CAAqB,OAAA,EAAS,MAAA"}

package/esm/orchestrator/orchestrator.mjs

@@ -8,6 +8,7 @@ import { OrchestratorEmitter } from "./emitter.mjs";
 import { resolveIntentEntries } from "../supervisor/entries.mjs";
 import { OrchestratorExecution } from "./execution.mjs";
 import { createOrchestratorStream } from "./orchestrator-stream.mjs";
+import { inProcessSessionLock, noopSessionLock } from "./session-lock.mjs";
 import { computeOrchestratorSignature } from "./signature.mjs";
 
 //#region ../@warlock.js/ai/src/orchestrator/orchestrator.ts
@@ -46,19 +47,22 @@ function orchestrator(config) {
 	assertInitialAgent(config, entries);
 	const signature = computeOrchestratorSignature(config, entries);
 	const emitter = new OrchestratorEmitter(config.on);
+	const sessionLock = resolveSessionLock(config);
+	warnOnUnlockedDurableStore(config);
 	async function execute(input, options) {
-		return new OrchestratorExecution({
+		const execution = new OrchestratorExecution({
 			config,
 			entries,
 			signature,
 			emitter,
 			input,
 			options
-		}).run();
+		});
+		return sessionLock.withLock(options.sessionId, () => execution.run(), { signal: options.signal });
 	}
 	function stream(input, options) {
 		const { controller, stream: contract } = createOrchestratorStream();
-		new OrchestratorExecution({
+		const execution = new OrchestratorExecution({
 			config,
 			entries,
 			signature,
@@ -66,18 +70,20 @@ function orchestrator(config) {
 			input,
 			options,
 			streamController: controller
-		}).run();
+		});
+		sessionLock.withLock(options.sessionId, () => execution.run(), { signal: options.signal });
 		return contract;
 	}
 	async function resume(sessionId, options) {
-		return new OrchestratorExecution({
+		const execution = new OrchestratorExecution({
 			config,
 			entries,
 			signature,
 			emitter,
 			resumeSessionId: sessionId,
 			resumeOptions: options
-		}).resume();
+		});
+		return sessionLock.withLock(sessionId, () => execution.resume(), { signal: options?.signal });
 	}
 	const command = createCommandDispatcher({ compact: (args) => {
 		return new OrchestratorExecution({
@@ -167,6 +173,33 @@ function resolveEntries(config) {
 function assertInitialAgent(config, entries) {
 	if (config.initialAgent && !entries.has(config.initialAgent)) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): \`initialAgent\` "${config.initialAgent}" is not a key in \`intents\``, { context: { authoring: true } });
 }
+/**
+* Resolve the per-session lock (C4): an explicit {@link SessionLock} when
+* supplied, a no-op when `sessionLock: false`, otherwise the framework
+* default in-process mutex.
+*/
+function resolveSessionLock(config) {
+	if (config.sessionLock === false) return noopSessionLock();
+	if (config.sessionLock) return config.sessionLock;
+	return inProcessSessionLock();
+}
+/** Orchestrator names already warned about an unlocked durable store. */
+const warnedUnlockedStores = /* @__PURE__ */ new Set();
+/**
+* Warn once when a durable `checkpointStore` is configured but no explicit
+* `sessionLock` was supplied (C4). The in-process default serializes
+* same-session turns within one process only — a horizontally-scaled
+* deployment needs a distributed lock or sticky routing. Suppressed in
+* tests and when the dev explicitly chose a lock (or `sessionLock: false`).
+*/
+function warnOnUnlockedDurableStore(config) {
+	if (config.sessionLock !== void 0) return;
+	if (!config.checkpointStore) return;
+	if (process.env.NODE_ENV === "test" || process.env.VITEST) return;
+	if (warnedUnlockedStores.has(config.name)) return;
+	warnedUnlockedStores.add(config.name);
+	console.warn(`[warlock-ai] orchestrator "${config.name}" uses a durable checkpointStore with the default in-process sessionLock. That serializes same-session turns within ONE process only; in a horizontally-scaled deployment supply a distributed \`sessionLock\` (Redis/Postgres advisory locks) or use sticky routing. Pass \`sessionLock: false\` to silence this.`);
+}
 
 //#endregion
 export { orchestrator };