@warlock.js/ai 4.2.11 → 4.3.0

package/esm/orchestrator/execution.mjs

@@ -0,0 +1,406 @@
+import { OrchestratorConfigError } from "../errors/orchestrator-config-error.mjs";
+import { OrchestratorDriftError } from "../errors/orchestrator-drift-error.mjs";
+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 { injectMemories, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory } from "./memory.mjs";
+import { persistCheckpoint, summarizeRoute } from "./checkpoint.mjs";
+import { acquireLock } from "./lock.mjs";
+import { runCompaction, runManualCompaction, shouldCompact } from "./compaction.mjs";
+import { deriveRunId, dispatchTurn } from "./dispatch.mjs";
+import { loadSession } from "./load.mjs";
+import { resolveResume } from "./resume.mjs";
+import { windowHistory } from "./window.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/execution.ts
+/** Empty rolled-up usage for turns that never dispatched (drift/seed). */
+const ZERO_USAGE = {
+	input: 0,
+	output: 0,
+	total: 0
+};
+/**
+* Per-call lifecycle engine — the single object the C1 factory
+* constructs and drives. Owns the 7-phase lifecycle (orchestrator.md §3:
+* load → drift → lock → window → dispatch → persist → compaction),
+* resolving the durable stores (own config field → `ai.config` default)
+* and adapting C1's three-tier {@link OrchestratorEmitter} to the
+* {@link OrchestratorEmitterLike} port the phase modules call.
+*
+* The factory creates a fresh instance per `execute` / `stream` /
+* `resume` / `command` call (single-call lifecycle invariant — §18.8);
+* the heavy lifting lives in the standalone phase functions
+* ({@link runTurn} / {@link runResume}) which this class delegates to.
+*
+* @example
+* const execution = new OrchestratorExecution({
+*   config, entries, signature, emitter, input, options,
+* });
+* const result = await execution.run();
+*/
+var OrchestratorExecution = class {
+	constructor(params) {
+		this.params = params;
+		this.streamController = params.streamController;
+		this.ctx = {
+			config: params.config,
+			signature: params.signature,
+			checkpointStore: resolveCheckpointStore(params.config),
+			snapshotStore: resolveSnapshotStore(params.config),
+			emitter: adaptEmitter(params.emitter, generateRunId("orchestrator"), this.streamController),
+			memory: resolveOrchestratorMemory(params.config.memory)
+		};
+	}
+	/**
+	* `execute()` / `stream()` entry — run one turn through the 7-phase
+	* lifecycle. When a `streamController` was supplied, the adapter mirrors
+	* every emitted event into the stream and the controller is settled
+	* (`end` / `fail`) once the result resolves.
+	*/
+	async run() {
+		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);
+			this.streamController?.end(result);
+			return result;
+		} catch (error) {
+			this.streamController?.fail(error);
+			throw error;
+		}
+	}
+	/**
+	* `resume()` entry — drain an interrupted `iterate: true` turn (§9).
+	* Returns `null` when nothing is in flight.
+	*/
+	async resume() {
+		if (!this.params.resumeSessionId) throw new OrchestratorConfigError(`ai.orchestrator("${this.params.config.name}"): internal — resume() invoked without a sessionId`);
+		return runResume(this.ctx, this.params.resumeSessionId, this.params.resumeOptions);
+	}
+	/**
+	* `command("compact")` entry — run a manual compaction on demand (§11 /
+	* §12.1). Reuses the post-turn compaction code path against the
+	* caller-supplied history and returns the raw {@link CompactionResult}.
+	*/
+	async compact(args) {
+		return runManualCompaction(this.ctx, args.history);
+	}
+};
+/**
+* Resolve the durable checkpoint store: the config's own field, falling
+* back to `ai.config({ defaultCheckpointStore })`. Throws
+* {@link OrchestratorConfigError} when neither resolves — persistence is
+* always on (§8.1), so a turn can never run without a checkpoint store.
+*/
+function resolveCheckpointStore(config) {
+	const store = config.checkpointStore ?? resolveDefaultCheckpointStore();
+	if (!store) throw new OrchestratorConfigError(`ai.orchestrator("${config.name}"): a \`checkpointStore\` is required (set one on the config or via \`ai.config({ defaultCheckpointStore })\`)`);
+	return store;
+}
+/**
+* Resolve the internal-supervisor snapshot store for `iterate: true`
+* turns: the config's own field, falling back to
+* `ai.config({ defaultSnapshotStore })`. Returns `undefined` for
+* `iterate: false` orchestrators (no mid-turn resume — nothing to
+* snapshot). The factory already guarantees presence when
+* `iterate: true`, so the engine never asserts here.
+*/
+function resolveSnapshotStore(config) {
+	if (config.iterate !== true) return;
+	return config.snapshotStore ?? resolveDefaultSnapshotStore();
+}
+/**
+* Adapt C1's three-tier {@link OrchestratorEmitter} (whose `emit` takes
+* `event, payload, identity, perCallHandlers?`) to the
+* {@link OrchestratorEmitterLike} port the phase modules call (a 2-arg
+* `emit(event, payload)` plus `bindPerCall`).
+*
+* The adapter injects the run identity centrally and, when a stream
+* controller is present, mirrors every fully-stamped event into the
+* stream pipe (§14.1 — the orchestrator's own events surface on the
+* stream alongside the bubbled child events). `bindPerCall` registers
+* the per-call `options.on` bag for the turn's duration and returns a
+* disposer that clears it.
+*/
+function adaptEmitter(emitter, runId, streamController) {
+	const fullIdentity = {
+		runId,
+		rootRunId: runId
+	};
+	let perCall;
+	return {
+		emit(event, payload) {
+			const fullPayload = emitter.emit(event, payload, fullIdentity, perCall);
+			streamController?.push({
+				type: event,
+				...fullPayload
+			});
+		},
+		bindPerCall(handlers) {
+			perCall = handlers;
+			return () => {
+				perCall = void 0;
+			};
+		}
+	};
+}
+/**
+* Phase 2 — drift check (orchestrator.md §3 / §4 Phase 2). Compares the
+* loaded checkpoint's `signature` against the current definition's.
+* Mismatch throws `OrchestratorDriftError` synchronously unless
+* `force` is set. Emits `orchestrator.drift.checked` either way. A new
+* session (no loaded signature) never drifts.
+*/
+function assertNoDrift(ctx, sessionId, loadedSignature, force) {
+	const drifted = loadedSignature !== void 0 && loadedSignature !== ctx.signature;
+	ctx.emitter.emit("orchestrator.drift.checked", {
+		sessionId,
+		signature: ctx.signature,
+		drifted
+	});
+	if (drifted && !force) throw new OrchestratorDriftError(`orchestrator "${ctx.config.name}": signature drift on session "${sessionId}" — the definition changed since this session was last persisted. Pass { force: true } only after reviewing the change, or discard / migrate the session.`, {
+		savedSignature: loadedSignature,
+		currentSignature: ctx.signature,
+		sessionId
+	});
+}
+/**
+* Shallow-merge the per-call `state` patch (§5 — partial state
+* override) over the loaded session-state seed. The merged value
+* becomes the supervisor's seed for this turn.
+*/
+function applyStatePatch(seed, patch) {
+	if (!patch) return seed;
+	return {
+		...seed,
+		...patch
+	};
+}
+/**
+* Assemble the orchestrator-scope {@link OrchestratorReport} from the
+* dispatched turn's child report and the turn snapshot. Wraps the
+* child supervisor/agent report tree as `children[0]` (§15.6 —
+* `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) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const usage = turnSnapshot?.usage ?? childReport?.usage ?? ZERO_USAGE;
+	return {
+		runId: deriveRunId(sessionId, ctx.config.version, turnIndex),
+		rootRunId: deriveRunId(sessionId, ctx.config.version, turnIndex),
+		name: ctx.config.name,
+		version: ctx.config.version,
+		sessionId,
+		type: "orchestrator",
+		status,
+		startedAt: turnSnapshot?.startedAt ?? now,
+		endedAt: turnSnapshot?.endedAt ?? now,
+		duration: turnSnapshot?.duration ?? 0,
+		usage,
+		children: childReport ? [childReport] : [],
+		reportSchemaVersion: 1,
+		turnIndex,
+		signature: ctx.signature,
+		turns: turnSnapshot ? [turnSnapshot] : []
+	};
+}
+/**
+* Map the dispatched supervisor result's report status onto the
+* orchestrator's status surface (§15.6). A clean completion that is
+* still mid-conversation reports `"awaiting-input"` (the session
+* continues) rather than `"completed"`; failures and cancellations
+* pass through.
+*/
+function deriveStatus(childStatus) {
+	if (childStatus === "completed") return "awaiting-input";
+	return childStatus;
+}
+/**
+* Emit the terminal turn event matching the report status (§14.1).
+*/
+function emitTerminal(ctx, sessionId, turnIndex, status) {
+	if (status === "cancelled") {
+		ctx.emitter.emit("orchestrator.turn.cancelled", {
+			sessionId,
+			turnIndex
+		});
+		return;
+	}
+	if (status === "failed" || status === "max-iterations") {
+		ctx.emitter.emit("orchestrator.turn.failed", {
+			sessionId,
+			turnIndex
+		});
+		return;
+	}
+	if (status === "awaiting-input") {
+		ctx.emitter.emit("orchestrator.turn.awaiting-input", {
+			sessionId,
+			turnIndex
+		});
+		return;
+	}
+	ctx.emitter.emit("orchestrator.turn.completed", {
+		sessionId,
+		turnIndex
+	});
+}
+/**
+* Run one turn end-to-end through the 7-phase lifecycle (orchestrator
+* .md §3). The single entry the C1 factory's `execute()` delegates to.
+*
+* Phase order is the diagram's contract: load → drift → lock → window
+* → dispatch → persist → compaction. Drift / config misuse throw;
+* every other failure surfaces on `result.error` (the contract: the
+* orchestrator never throws on runtime failure). Cancellation and
+* failure do NOT persist a fresh checkpoint (§17 — state reverts to the
+* pre-turn checkpoint).
+*/
+async function runTurn(ctx, input, options) {
+	const sessionId = options.sessionId;
+	const disposePerCall = ctx.emitter.bindPerCall(options.on);
+	try {
+		const loaded = await loadSession(ctx, sessionId);
+		ctx.emitter.emit("orchestrator.turn.starting", {
+			sessionId,
+			turnIndex: loaded.turnIndex
+		});
+		ctx.emitter.emit("orchestrator.session.loaded", {
+			sessionId,
+			turnIndex: loaded.turnIndex,
+			found: loaded.found
+		});
+		assertNoDrift(ctx, sessionId, loaded.record?.signature, options.force);
+		await acquireLock(ctx, sessionId, loaded.record);
+		const windowed = windowHistory(ctx, sessionId, options.history);
+		const seedState = applyStatePatch(loaded.state, options.state);
+		let turnContext = options.context;
+		if (ctx.memory) {
+			const recalled = await recallForTurn(ctx.memory, input);
+			turnContext = injectMemories(turnContext, ctx.memory, recalled);
+		}
+		const { result, state, turnSnapshot } = await dispatchTurn({
+			ctx,
+			sessionId,
+			input,
+			seedState,
+			turnIndex: loaded.turnIndex,
+			history: windowed.agents,
+			context: turnContext,
+			signal: options.signal
+		});
+		ctx.emitter.emit("orchestrator.turn.routed", {
+			sessionId,
+			turnIndex: loaded.turnIndex,
+			source: turnSnapshot.decision.source,
+			raw: turnSnapshot.decision.raw
+		});
+		const status = result.error ? deriveStatus(result.report.status) : "awaiting-input";
+		if (result.error) {
+			const report = buildReport(ctx, sessionId, loaded.turnIndex, status, turnSnapshot, result.report);
+			emitTerminal(ctx, sessionId, loaded.turnIndex, status);
+			return {
+				data: result.data,
+				error: result.error,
+				usage: result.usage,
+				report,
+				sessionId,
+				turnIndex: loaded.turnIndex
+			};
+		}
+		await persistCheckpoint({
+			ctx,
+			sessionId,
+			turnIndex: loaded.turnIndex,
+			state,
+			lastRoute: summarizeRoute(turnSnapshot.decision.raw),
+			summarizedThrough: loaded.record?.summarized_through ?? null
+		});
+		if (ctx.memory) await rememberTurnOutcome(ctx.memory, input, outcomeTextFromTurn(result.data, turnSnapshot));
+		let compaction;
+		if (shouldCompact(ctx, loaded.turnIndex)) {
+			const outcome = await runCompaction(ctx, sessionId, options.history);
+			if (outcome) {
+				compaction = outcome.compaction;
+				if (outcome.applied) await advanceSummarizedThrough(ctx, sessionId, outcome.compaction.replacesToIndex);
+			}
+		}
+		const report = buildReport(ctx, sessionId, loaded.turnIndex, "awaiting-input", turnSnapshot, result.report);
+		emitTerminal(ctx, sessionId, loaded.turnIndex, "awaiting-input");
+		return {
+			data: result.data,
+			error: void 0,
+			usage: result.usage,
+			report,
+			sessionId,
+			turnIndex: loaded.turnIndex,
+			compaction
+		};
+	} finally {
+		disposePerCall();
+	}
+}
+/**
+* After a framework-applied compaction (`onCompact` succeeded), advance
+* the persisted `summarized_through` to the compaction's
+* `replacesToIndex` (§12.2 step 4). Re-saves the latest row with the
+* updated marker (append-only stores keep the prior row).
+*/
+async function advanceSummarizedThrough(ctx, sessionId, replacesToIndex) {
+	const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);
+	if (!latest) return;
+	await ctx.checkpointStore.save({
+		...latest,
+		summarized_through: replacesToIndex,
+		saved_at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+/**
+* §9 resume protocol entry the C1 factory's `resume()` delegates to.
+* Returns `null` when no in-flight `iterate: true` turn is detected;
+* otherwise drains the interrupted supervisor run, persists a fresh
+* checkpoint for the resumed turn, and returns the completed result.
+*
+* Runs the same Phase 2 drift check as `runTurn` (§9.4). The heavy
+* lifting lives in `resume.ts`; this wrapper threads the engine
+* context.
+*/
+async function runResume(ctx, sessionId, options) {
+	const disposePerCall = ctx.emitter.bindPerCall(options?.on);
+	try {
+		return await resolveResume(ctx, sessionId, options, {
+			assertNoDrift: (loadedSignature) => assertNoDrift(ctx, sessionId, loadedSignature, options?.force),
+			buildReport: (turnIndex, status, turnSnapshot, childReport) => buildReport(ctx, sessionId, turnIndex, status, turnSnapshot, childReport),
+			deriveStatus,
+			emitTerminal: (turnIndex, status) => emitTerminal(ctx, sessionId, turnIndex, status),
+			persist: (turnIndex, state, lastRoute, summarizedThrough) => persistCheckpoint({
+				ctx,
+				sessionId,
+				turnIndex,
+				state,
+				lastRoute,
+				summarizedThrough
+			})
+		});
+	} finally {
+		disposePerCall();
+	}
+}
+/**
+* The `stream()` entry. The orchestrator's streaming surface bubbles
+* child agent/supervisor events under their own namespace (§14.2); the
+* C1 stream controller owns the `StreamContract` wiring. This engine
+* entry runs the same lifecycle as `runTurn` — the C1 factory passes a
+* per-call `on` bag wired to the stream controller, so the engine needs
+* no streaming-specific branch. Exposed as a distinct name for the
+* factory to call, returning the same `OrchestratorResult` the stream's
+* `.result` resolves to.
+*/
+async function streamTurn(ctx, input, options) {
+	return runTurn(ctx, input, options);
+}
+
+//#endregion
+export { OrchestratorExecution, runResume, runTurn, streamTurn };
+//# sourceMappingURL=execution.mjs.map

package/esm/orchestrator/execution.mjs.map

@@ -0,0 +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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"}

package/esm/orchestrator/index.d.mts

@@ -0,0 +1,8 @@
+import { asTool } from "./as-tool.mjs";
+import { OrchestratorCommandHandlers, createCommandDispatcher } from "./commands.mjs";
+import { OrchestratorEmitter } from "./emitter.mjs";
+import { ResolvedOrchestratorMemory, injectMemories, memoryQueryFromInput, outcomeTextFromTurn, recallForTurn, rememberTurnOutcome, resolveOrchestratorMemory } from "./memory.mjs";
+import { OrchestratorStreamController, createOrchestratorStream } from "./orchestrator-stream.mjs";
+import { OrchestratorExecution, OrchestratorExecutionParams, runResume, runTurn, streamTurn } from "./execution.mjs";
+import { orchestrator } from "./orchestrator.mjs";
+import { computeOrchestratorSignature } from "./signature.mjs";

package/esm/orchestrator/index.mjs

@@ -0,0 +1,10 @@
+import { asTool } from "./as-tool.mjs";
+import { createCommandDispatcher } from "./commands.mjs";
+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 { computeOrchestratorSignature } from "./signature.mjs";
+import { orchestrator } from "./orchestrator.mjs";
+
+export {  };

package/esm/orchestrator/load.mjs

@@ -0,0 +1,49 @@
+//#region ../@warlock.js/ai/src/orchestrator/load.ts
+/**
+* Deep-clone a JSON-serializable value so a rehydrated checkpoint's
+* `state` can be mutated by the turn without aliasing the stored row
+* (the in-memory store hands back live references). Mirrors the
+* round-trip semantics the design mandates for state (§5 — "JSON-
+* serializable only", `JSON.parse(JSON.stringify(...))`-equivalent).
+*/
+function cloneState(state) {
+	if (state === void 0 || state === null) return {};
+	return JSON.parse(JSON.stringify(state));
+}
+/**
+* Phase 1 — load session. Reads the latest checkpoint for the session
+* and resolves the starting state accumulator + the turn index about
+* to run.
+*
+* First-call seeding (Q2): when no checkpoint exists this is the
+* session's birth — `state` defaults to `config.state ?? {}` and
+* `turnIndex` is 0. Subsequent calls rehydrate the persisted `state`
+* and advance the turn index. The dev-passed `options.history` is the
+* per-call seed (Path 2 — the framework never persists messages), so
+* load does not touch history.
+*
+* Does NOT apply the per-call `state` patch — that shallow-merges over
+* this result in the dispatch phase (§5), where the supervisor seed is
+* assembled.
+*/
+async function loadSession(ctx, sessionId) {
+	const record = await ctx.checkpointStore.load(ctx.config.name, sessionId);
+	if (!record) return {
+		record: void 0,
+		found: false,
+		state: cloneState(ctx.config.state),
+		turnIndex: 0,
+		previousTurnIndex: -1
+	};
+	return {
+		record,
+		found: true,
+		state: cloneState(record.state),
+		turnIndex: record.turn_index + 1,
+		previousTurnIndex: record.turn_index
+	};
+}
+
+//#endregion
+export { loadSession };
+//# sourceMappingURL=load.mjs.map

package/esm/orchestrator/load.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/load.ts"],"sourcesContent":["import type { CheckpointRecord } from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\n\n/**\n * Outcome of Phase 1 — load session (orchestrator.md §4 Phase 1).\n *\n * `record` is the latest persisted checkpoint, or `undefined` for a\n * brand-new session. `state` is the starting accumulator the turn\n * mutates: the rehydrated `state` on a subsequent call, or the\n * `config.state ?? {}` seed on first call (the framework never\n * re-seeds from `config.state` once a session exists — §4 Phase 1).\n * `turnIndex` is the index of the turn ABOUT to run (loaded + 1, or 0\n * on first call). `previousTurnIndex` is the loaded value (or -1 when\n * none) — needed by resume's `runId` derivation (§9.1).\n */\nexport type LoadedSession<TState> = {\n  /** Latest persisted checkpoint, or `undefined` for a new session. */\n  record: CheckpointRecord | undefined;\n  /** Whether a prior checkpoint existed (drives `session.loaded.found`). */\n  found: boolean;\n  /** Starting state accumulator for this turn. */\n  state: TState;\n  /** Index of the turn about to run. */\n  turnIndex: number;\n  /** Index of the last settled turn (-1 when the session is new). */\n  previousTurnIndex: number;\n};\n\n/**\n * Deep-clone a JSON-serializable value so a rehydrated checkpoint's\n * `state` can be mutated by the turn without aliasing the stored row\n * (the in-memory store hands back live references). Mirrors the\n * round-trip semantics the design mandates for state (§5 — \"JSON-\n * serializable only\", `JSON.parse(JSON.stringify(...))`-equivalent).\n */\nfunction cloneState<TState>(state: unknown): TState {\n  if (state === undefined || state === null) {\n    return {} as TState;\n  }\n\n  return JSON.parse(JSON.stringify(state)) as TState;\n}\n\n/**\n * Phase 1 — load session. Reads the latest checkpoint for the session\n * and resolves the starting state accumulator + the turn index about\n * to run.\n *\n * First-call seeding (Q2): when no checkpoint exists this is the\n * session's birth — `state` defaults to `config.state ?? {}` and\n * `turnIndex` is 0. Subsequent calls rehydrate the persisted `state`\n * and advance the turn index. The dev-passed `options.history` is the\n * per-call seed (Path 2 — the framework never persists messages), so\n * load does not touch history.\n *\n * Does NOT apply the per-call `state` patch — that shallow-merges over\n * this result in the dispatch phase (§5), where the supervisor seed is\n * assembled.\n */\nexport async function loadSession<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n): Promise<LoadedSession<TState>> {\n  const record = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n\n  if (!record) {\n    return {\n      record: undefined,\n      found: false,\n      state: cloneState<TState>(ctx.config.state),\n      turnIndex: 0,\n      previousTurnIndex: -1,\n    };\n  }\n\n  return {\n    record,\n    found: true,\n    state: cloneState<TState>(record.state),\n    turnIndex: record.turn_index + 1,\n    previousTurnIndex: record.turn_index,\n  };\n}\n"],"mappings":";;;;;;;;AAmCA,SAAS,WAAmB,OAAwB;CAClD,IAAI,UAAU,UAAa,UAAU,MACnC,OAAO,CAAC;CAGV,OAAO,KAAK,MAAM,KAAK,UAAU,KAAK,CAAC;AACzC;;;;;;;;;;;;;;;;;AAkBA,eAAsB,YACpB,KACA,WACgC;CAChC,MAAM,SAAS,MAAM,IAAI,gBAAgB,KAAK,IAAI,OAAO,MAAM,SAAS;CAExE,IAAI,CAAC,QACH,OAAO;EACL,QAAQ;EACR,OAAO;EACP,OAAO,WAAmB,IAAI,OAAO,KAAK;EAC1C,WAAW;EACX,mBAAmB;CACrB;CAGF,OAAO;EACL;EACA,OAAO;EACP,OAAO,WAAmB,OAAO,KAAK;EACtC,WAAW,OAAO,aAAa;EAC/B,mBAAmB,OAAO;CAC5B;AACF"}

package/esm/orchestrator/lock.mjs

@@ -0,0 +1,75 @@
+//#region ../@warlock.js/ai/src/orchestrator/lock.ts
+/** Framework default for the compaction-lock wait, in ms (§3 / §12.3). */
+const DEFAULT_LOCK_MAX_WAIT = 3e4;
+/** Poll interval while waiting on a held lock, in ms. */
+const LOCK_POLL_INTERVAL = 100;
+/**
+* Resolve the configured `summarize.lock.maxWait`, falling back to the
+* framework default. The callback form of `summarize` carries no lock
+* config, so it uses the default.
+*/
+function resolveMaxWait(ctx) {
+	const summarize = ctx.config.summarize;
+	if (typeof summarize === "function" || summarize === void 0) return DEFAULT_LOCK_MAX_WAIT;
+	return summarize.lock?.maxWait ?? 3e4;
+}
+/** Whether a checkpoint's lock is still held relative to `now`. */
+function isLocked(record, now) {
+	if (!record.lock_expires_at) return false;
+	const expiresAt = Date.parse(record.lock_expires_at);
+	return Number.isFinite(expiresAt) && expiresAt > now;
+}
+/**
+* Phase 3 — lock check (orchestrator.md §3 / §4 Phase 3). The loaded
+* checkpoint may carry a compaction lock written by a prior turn's
+* Phase 7 (or by `command("compact")`). When the lock is still live,
+* wait up to `summarize.lock.maxWait` (default 30s), re-loading the
+* latest checkpoint each poll, then **fail open** — proceed without
+* the lock.
+*
+* Emits `orchestrator.lock.waiting` once, only when a held lock is
+* observed (§14.1 — "only when locked"). The dispatch then runs
+* against whatever state was written before the lock was taken (§3).
+*
+* A new session (`loaded === undefined`) is never locked, so this
+* returns immediately.
+*/
+async function acquireLock(ctx, sessionId, loaded) {
+	if (!loaded || !isLocked(loaded, Date.now())) return {
+		waited: false,
+		waitedMs: 0,
+		failedOpen: false
+	};
+	const maxWait = resolveMaxWait(ctx);
+	const startedAt = Date.now();
+	ctx.emitter.emit("orchestrator.lock.waiting", {
+		sessionId,
+		waitedMs: 0
+	});
+	let latest = loaded;
+	while (latest && isLocked(latest, Date.now())) {
+		const waitedMs = Date.now() - startedAt;
+		if (waitedMs >= maxWait) return {
+			waited: true,
+			waitedMs,
+			failedOpen: true
+		};
+		await delay(Math.min(LOCK_POLL_INTERVAL, maxWait - waitedMs));
+		latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);
+	}
+	return {
+		waited: true,
+		waitedMs: Date.now() - startedAt,
+		failedOpen: false
+	};
+}
+/** Promise-based sleep used by the cooperative wait loop. */
+function delay(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+
+//#endregion
+export { DEFAULT_LOCK_MAX_WAIT, acquireLock };
+//# sourceMappingURL=lock.mjs.map

package/esm/orchestrator/lock.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/orchestrator/lock.ts"],"sourcesContent":["import type { CheckpointRecord } from \"../contracts/orchestrator/checkpoint-store.contract\";\nimport type { SummarizeConfig } from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\n\n/** Framework default for the compaction-lock wait, in ms (§3 / §12.3). */\nexport const DEFAULT_LOCK_MAX_WAIT = 30_000;\n\n/** Poll interval while waiting on a held lock, in ms. */\nconst LOCK_POLL_INTERVAL = 100;\n\n/**\n * Resolve the configured `summarize.lock.maxWait`, falling back to the\n * framework default. The callback form of `summarize` carries no lock\n * config, so it uses the default.\n */\nfunction resolveMaxWait(ctx: OrchestratorEngineContext): number {\n  const summarize = ctx.config.summarize;\n\n  if (typeof summarize === \"function\" || summarize === undefined) {\n    return DEFAULT_LOCK_MAX_WAIT;\n  }\n\n  return (summarize as SummarizeConfig).lock?.maxWait ?? DEFAULT_LOCK_MAX_WAIT;\n}\n\n/** Whether a checkpoint's lock is still held relative to `now`. */\nfunction isLocked(record: CheckpointRecord, now: number): boolean {\n  if (!record.lock_expires_at) {\n    return false;\n  }\n\n  const expiresAt = Date.parse(record.lock_expires_at);\n\n  return Number.isFinite(expiresAt) && expiresAt > now;\n}\n\n/**\n * Outcome of Phase 3. `waited` is true when the turn observed a held\n * lock and spent time waiting; `waitedMs` is how long. `failedOpen` is\n * true when the wait timed out and the turn proceeds without the lock\n * (orchestrator.md §3 / §12.3 — a stuck summarizer must never block a\n * session forever).\n */\nexport type LockOutcome = {\n  waited: boolean;\n  waitedMs: number;\n  failedOpen: boolean;\n};\n\n/**\n * Phase 3 — lock check (orchestrator.md §3 / §4 Phase 3). The loaded\n * checkpoint may carry a compaction lock written by a prior turn's\n * Phase 7 (or by `command(\"compact\")`). When the lock is still live,\n * wait up to `summarize.lock.maxWait` (default 30s), re-loading the\n * latest checkpoint each poll, then **fail open** — proceed without\n * the lock.\n *\n * Emits `orchestrator.lock.waiting` once, only when a held lock is\n * observed (§14.1 — \"only when locked\"). The dispatch then runs\n * against whatever state was written before the lock was taken (§3).\n *\n * A new session (`loaded === undefined`) is never locked, so this\n * returns immediately.\n */\nexport async function acquireLock<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  loaded: CheckpointRecord | undefined,\n): Promise<LockOutcome> {\n  if (!loaded || !isLocked(loaded, Date.now())) {\n    return { waited: false, waitedMs: 0, failedOpen: false };\n  }\n\n  const maxWait = resolveMaxWait(ctx as OrchestratorEngineContext);\n  const startedAt = Date.now();\n\n  ctx.emitter.emit(\"orchestrator.lock.waiting\", { sessionId, waitedMs: 0 });\n\n  let latest: CheckpointRecord | undefined = loaded;\n\n  while (latest && isLocked(latest, Date.now())) {\n    const waitedMs = Date.now() - startedAt;\n\n    if (waitedMs >= maxWait) {\n      return { waited: true, waitedMs, failedOpen: true };\n    }\n\n    await delay(Math.min(LOCK_POLL_INTERVAL, maxWait - waitedMs));\n\n    latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n  }\n\n  return { waited: true, waitedMs: Date.now() - startedAt, failedOpen: false };\n}\n\n/** Promise-based sleep used by the cooperative wait loop. */\nfunction delay(ms: number): Promise<void> {\n  return new Promise((resolve) => {\n    setTimeout(resolve, ms);\n  });\n}\n"],"mappings":";;AAKA,MAAa,wBAAwB;;AAGrC,MAAM,qBAAqB;;;;;;AAO3B,SAAS,eAAe,KAAwC;CAC9D,MAAM,YAAY,IAAI,OAAO;CAE7B,IAAI,OAAO,cAAc,cAAc,cAAc,QACnD,OAAO;CAGT,OAAQ,UAA8B,MAAM;AAC9C;;AAGA,SAAS,SAAS,QAA0B,KAAsB;CAChE,IAAI,CAAC,OAAO,iBACV,OAAO;CAGT,MAAM,YAAY,KAAK,MAAM,OAAO,eAAe;CAEnD,OAAO,OAAO,SAAS,SAAS,KAAK,YAAY;AACnD;;;;;;;;;;;;;;;;AA8BA,eAAsB,YACpB,KACA,WACA,QACsB;CACtB,IAAI,CAAC,UAAU,CAAC,SAAS,QAAQ,KAAK,IAAI,CAAC,GACzC,OAAO;EAAE,QAAQ;EAAO,UAAU;EAAG,YAAY;CAAM;CAGzD,MAAM,UAAU,eAAe,GAAgC;CAC/D,MAAM,YAAY,KAAK,IAAI;CAE3B,IAAI,QAAQ,KAAK,6BAA6B;EAAE;EAAW,UAAU;CAAE,CAAC;CAExE,IAAI,SAAuC;CAE3C,OAAO,UAAU,SAAS,QAAQ,KAAK,IAAI,CAAC,GAAG;EAC7C,MAAM,WAAW,KAAK,IAAI,IAAI;EAE9B,IAAI,YAAY,SACd,OAAO;GAAE,QAAQ;GAAM;GAAU,YAAY;EAAK;EAGpD,MAAM,MAAM,KAAK,IAAI,oBAAoB,UAAU,QAAQ,CAAC;EAE5D,SAAS,MAAM,IAAI,gBAAgB,KAAK,IAAI,OAAO,MAAM,SAAS;CACpE;CAEA,OAAO;EAAE,QAAQ;EAAM,UAAU,KAAK,IAAI,IAAI;EAAW,YAAY;CAAM;AAC7E;;AAGA,SAAS,MAAM,IAA2B;CACxC,OAAO,IAAI,SAAS,YAAY;EAC9B,WAAW,SAAS,EAAE;CACxB,CAAC;AACH"}