@warlock.js/core 4.3.0 → 4.5.0

package/esm/ai/src/orchestrator/compaction.mjs

@@ -0,0 +1,206 @@
+import { DEFAULT_LOCK_MAX_WAIT } from "./lock.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/compaction.ts
+/**
+* Most-recent messages kept verbatim when `summarize.keep` is omitted.
+* Defaulting to 0 would compact the entire history into one memo (losing
+* the live tail every turn), so the object form keeps a small recent
+* window by default — matching the canonical doc examples (`keep: 8`).
+*/
+const DEFAULT_COMPACTION_KEEP = 8;
+/** Whether the configured `summarize` is the fully-pluggable callback form. */
+function isCallbackForm(summarize) {
+	return typeof summarize === "function";
+}
+/**
+* Decide whether Phase 7 compaction should fire this turn (orchestrator
+* .md §4 Phase 7 / §12.1). v1 trigger is count-based:
+* `summarize.afterTurns` fires once `turnIndex >= afterTurns`. The
+* callback form has no threshold and never auto-fires — it is driven
+* exclusively by `command("compact")` (the manual path). Returns false
+* when `summarize` is unset.
+*/
+function shouldCompact(ctx, turnIndex) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0 || isCallbackForm(summarize)) return false;
+	const afterTurns = summarize.afterTurns;
+	return afterTurns !== void 0 && turnIndex >= afterTurns;
+}
+/**
+* Run the configured summarizer against the session history and build
+* a {@link CompactionResult} (§12.2 step 2–3). Three resolution paths:
+*
+* - callback form — `summarize(history)` returns the result directly.
+* - config + `summarizer` model — summarize the slice (history minus
+*   the most-recent `keep`) into one synthetic memo turn.
+* - config without a `summarizer` — produce a trivial degenerate memo
+*   (no model available); the dev is expected to supply a summarizer
+*   for real compaction. The range still reflects the kept tail.
+*/
+async function produceCompaction(summarize, history) {
+	if (isCallbackForm(summarize)) return summarize(history);
+	const keep = summarize.keep ?? 8;
+	const replacesFromIndex = 0;
+	const replacesToIndex = Math.max(-1, history.length - keep - 1);
+	return {
+		summary: {
+			role: "system",
+			content: await summarizeSlice(summarize, history.slice(0, replacesToIndex + 1))
+		},
+		replacesFromIndex,
+		replacesToIndex
+	};
+}
+/**
+* Summarize a slice of history into text. Uses the configured
+* `summarizer` model when present (a single non-streaming completion);
+* otherwise returns a placeholder memo. The summarizer is intentionally
+* the cheap model — never the specialists (§12.4).
+*/
+async function summarizeSlice(summarize, slice) {
+	if (slice.length === 0) return "";
+	if (!summarize.summarizer) return `Summary of ${slice.length} prior message(s).`;
+	const transcript = slice.map((message) => `${message.role}: ${stringifyContent(message.content)}`).join("\n");
+	return (await summarize.summarizer.complete([{
+		role: "system",
+		content: "Summarize the following conversation slice into a concise memo that preserves the facts, decisions, and open threads a later turn would need. Reply with the memo only."
+	}, {
+		role: "user",
+		content: transcript
+	}])).content;
+}
+/** Coerce a message's content into a flat string for the summarizer prompt. */
+function stringifyContent(content) {
+	if (typeof content === "string") return content;
+	return JSON.stringify(content);
+}
+/**
+* Phase 7 — post-turn compaction (orchestrator.md §3 / §4 Phase 7 /
+* §12.2). Runs AFTER the turn settles; never blocks the caller's
+* resolution path beyond this phase.
+*
+* Acquires the cooperative session lock (writes `lock_acquired_at` /
+* `lock_expires_at` onto a fresh row), runs the summarizer, builds the
+* compaction, then either invokes `summarize.onCompact` (framework-
+* driven apply) or surfaces the compaction on the result for the dev to
+* apply. Releases the lock on settle. Emits
+* `orchestrator.compaction.suggested` always,
+* `orchestrator.compaction.applied` only when `onCompact` succeeded, and
+* `orchestrator.compaction.failed` (carrying the thrown `error` and the
+* `phase` that failed) when the summarizer or `onCompact` throws.
+*
+* Retry policy is skip-and-log (§4 Phase 7): a summarizer failure
+* leaves the session running with unchanged history — the engine
+* treats a thrown summarizer / `onCompact` as "no compaction this
+* turn", emits `orchestrator.compaction.failed`, and returns `undefined`
+* (summarizer) or surfaces the unapplied compaction (`onCompact`).
+*/
+async function runCompaction(ctx, sessionId, history) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0) return;
+	await acquireCompactionLock(ctx, sessionId);
+	try {
+		const compaction = await produceCompaction(summarize, history);
+		ctx.emitter.emit("orchestrator.compaction.suggested", {
+			sessionId,
+			compaction
+		});
+		const onCompact = isCallbackForm(summarize) ? void 0 : summarize.onCompact;
+		if (!onCompact) return {
+			compaction,
+			applied: false
+		};
+		try {
+			await onCompact(compaction, { sessionId });
+			ctx.emitter.emit("orchestrator.compaction.applied", {
+				sessionId,
+				compaction
+			});
+			return {
+				compaction,
+				applied: true
+			};
+		} catch (error) {
+			ctx.emitter.emit("orchestrator.compaction.failed", {
+				sessionId,
+				phase: "onCompact",
+				error
+			});
+			return {
+				compaction,
+				applied: false
+			};
+		}
+	} catch (error) {
+		ctx.emitter.emit("orchestrator.compaction.failed", {
+			sessionId,
+			phase: "summarize",
+			error
+		});
+		return;
+	} finally {
+		await releaseCompactionLock(ctx, sessionId);
+	}
+}
+/**
+* Run a manual compaction for `command("compact", ...)` (§11 / §12.1).
+* Same code path as the post-turn trigger but driven on demand against
+* the supplied history, returning the raw {@link CompactionResult}. The
+* callback form is honored; the config form without a `summarizer`
+* produces the degenerate memo. Does not apply `onCompact` — the
+* command surface returns the compaction for the caller to handle.
+*/
+async function runManualCompaction(ctx, history) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0) return {
+		summary: {
+			role: "system",
+			content: `Summary of ${history.length} message(s).`
+		},
+		replacesFromIndex: 0,
+		replacesToIndex: Math.max(-1, history.length - 1)
+	};
+	return produceCompaction(summarize, history);
+}
+/** Resolve the lock TTL from the summarize config (config form only). */
+function resolveLockMaxWait(ctx) {
+	const summarize = ctx.config.summarize;
+	if (summarize === void 0 || isCallbackForm(summarize)) return DEFAULT_LOCK_MAX_WAIT;
+	return summarize.lock?.maxWait ?? 3e4;
+}
+/**
+* Write the cooperative compaction lock onto a fresh checkpoint row
+* (§12.2 step 1). The lock lives on the latest persisted row; we load
+* it, stamp the lock columns, and re-save (append-only) so the next
+* turn's Phase 3 observes it.
+*/
+async function acquireCompactionLock(ctx, sessionId) {
+	const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);
+	if (!latest) return;
+	const now = Date.now();
+	const maxWait = resolveLockMaxWait(ctx);
+	await ctx.checkpointStore.save({
+		...latest,
+		lock_acquired_at: new Date(now).toISOString(),
+		lock_expires_at: new Date(now + maxWait).toISOString(),
+		saved_at: new Date(now).toISOString()
+	});
+}
+/**
+* Clear the compaction lock columns (§12.2 step 6) by re-saving the
+* latest row with the lock fields nulled.
+*/
+async function releaseCompactionLock(ctx, sessionId) {
+	const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);
+	if (!latest) return;
+	await ctx.checkpointStore.save({
+		...latest,
+		lock_acquired_at: null,
+		lock_expires_at: null,
+		saved_at: (/* @__PURE__ */ new Date()).toISOString()
+	});
+}
+
+//#endregion
+export { runCompaction, runManualCompaction, shouldCompact };
+//# sourceMappingURL=compaction.mjs.map

package/esm/ai/src/orchestrator/compaction.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/compaction.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type {\n  SummarizeCallback,\n  SummarizeConfig,\n} from \"../contracts/orchestrator/orchestrator-config.type\";\nimport type { CompactionResult } from \"../contracts/result/orchestrator-result.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\nimport { DEFAULT_LOCK_MAX_WAIT } from \"./lock\";\n\n/**\n * Most-recent messages kept verbatim when `summarize.keep` is omitted.\n * Defaulting to 0 would compact the entire history into one memo (losing\n * the live tail every turn), so the object form keeps a small recent\n * window by default — matching the canonical doc examples (`keep: 8`).\n */\nexport const DEFAULT_COMPACTION_KEEP = 8;\n\n/** Whether the configured `summarize` is the fully-pluggable callback form. */\nfunction isCallbackForm(\n  summarize: SummarizeConfig | SummarizeCallback | undefined,\n): summarize is SummarizeCallback {\n  return typeof summarize === \"function\";\n}\n\n/**\n * Decide whether Phase 7 compaction should fire this turn (orchestrator\n * .md §4 Phase 7 / §12.1). v1 trigger is count-based:\n * `summarize.afterTurns` fires once `turnIndex >= afterTurns`. The\n * callback form has no threshold and never auto-fires — it is driven\n * exclusively by `command(\"compact\")` (the manual path). Returns false\n * when `summarize` is unset.\n */\nexport function shouldCompact(\n  ctx: OrchestratorEngineContext,\n  turnIndex: number,\n): boolean {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined || isCallbackForm(summarize)) {\n    return false;\n  }\n\n  const afterTurns = summarize.afterTurns;\n\n  return afterTurns !== undefined && turnIndex >= afterTurns;\n}\n\n/** Result of a Phase-7 run — what the engine folds into the turn. */\nexport type CompactionOutcome = {\n  /** The produced compaction, surfaced on `result.compaction`. */\n  compaction: CompactionResult;\n  /**\n   * Whether `summarize.onCompact` ran AND succeeded — when true the\n   * engine advances `summarized_through` to `replacesToIndex` (§12.2\n   * step 4); when false it leaves it unchanged (§12.2 step 5).\n   */\n  applied: boolean;\n};\n\n/**\n * Run the configured summarizer against the session history and build\n * a {@link CompactionResult} (§12.2 step 2–3). Three resolution paths:\n *\n * - callback form — `summarize(history)` returns the result directly.\n * - config + `summarizer` model — summarize the slice (history minus\n *   the most-recent `keep`) into one synthetic memo turn.\n * - config without a `summarizer` — produce a trivial degenerate memo\n *   (no model available); the dev is expected to supply a summarizer\n *   for real compaction. The range still reflects the kept tail.\n */\nasync function produceCompaction(\n  summarize: SummarizeConfig | SummarizeCallback,\n  history: Message[],\n): Promise<CompactionResult> {\n  if (isCallbackForm(summarize)) {\n    return summarize(history);\n  }\n\n  const keep = summarize.keep ?? DEFAULT_COMPACTION_KEEP;\n  const replacesFromIndex = 0;\n  const replacesToIndex = Math.max(-1, history.length - keep - 1);\n  const slice = history.slice(0, replacesToIndex + 1);\n\n  const summaryText = await summarizeSlice(summarize, slice);\n\n  return {\n    summary: { role: \"system\", content: summaryText },\n    replacesFromIndex,\n    replacesToIndex,\n  };\n}\n\n/**\n * Summarize a slice of history into text. Uses the configured\n * `summarizer` model when present (a single non-streaming completion);\n * otherwise returns a placeholder memo. The summarizer is intentionally\n * the cheap model — never the specialists (§12.4).\n */\nasync function summarizeSlice(\n  summarize: SummarizeConfig,\n  slice: Message[],\n): Promise<string> {\n  if (slice.length === 0) {\n    return \"\";\n  }\n\n  if (!summarize.summarizer) {\n    return `Summary of ${slice.length} prior message(s).`;\n  }\n\n  const transcript = slice\n    .map((message) => `${message.role}: ${stringifyContent(message.content)}`)\n    .join(\"\\n\");\n\n  const response = await summarize.summarizer.complete([\n    {\n      role: \"system\",\n      content:\n        \"Summarize the following conversation slice into a concise memo \" +\n        \"that preserves the facts, decisions, and open threads a later \" +\n        \"turn would need. Reply with the memo only.\",\n    },\n    { role: \"user\", content: transcript },\n  ]);\n\n  return response.content;\n}\n\n/** Coerce a message's content into a flat string for the summarizer prompt. */\nfunction stringifyContent(content: Message[\"content\"]): string {\n  if (typeof content === \"string\") {\n    return content;\n  }\n\n  return JSON.stringify(content);\n}\n\n/**\n * Phase 7 — post-turn compaction (orchestrator.md §3 / §4 Phase 7 /\n * §12.2). Runs AFTER the turn settles; never blocks the caller's\n * resolution path beyond this phase.\n *\n * Acquires the cooperative session lock (writes `lock_acquired_at` /\n * `lock_expires_at` onto a fresh row), runs the summarizer, builds the\n * compaction, then either invokes `summarize.onCompact` (framework-\n * driven apply) or surfaces the compaction on the result for the dev to\n * apply. Releases the lock on settle. Emits\n * `orchestrator.compaction.suggested` always,\n * `orchestrator.compaction.applied` only when `onCompact` succeeded, and\n * `orchestrator.compaction.failed` (carrying the thrown `error` and the\n * `phase` that failed) when the summarizer or `onCompact` throws.\n *\n * Retry policy is skip-and-log (§4 Phase 7): a summarizer failure\n * leaves the session running with unchanged history — the engine\n * treats a thrown summarizer / `onCompact` as \"no compaction this\n * turn\", emits `orchestrator.compaction.failed`, and returns `undefined`\n * (summarizer) or surfaces the unapplied compaction (`onCompact`).\n */\nexport async function runCompaction<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n  history: Message[],\n): Promise<CompactionOutcome | undefined> {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined) {\n    return undefined;\n  }\n\n  await acquireCompactionLock(ctx, sessionId);\n\n  try {\n    const compaction = await produceCompaction(summarize, history);\n\n    ctx.emitter.emit(\"orchestrator.compaction.suggested\", {\n      sessionId,\n      compaction,\n    });\n\n    const onCompact = isCallbackForm(summarize) ? undefined : summarize.onCompact;\n\n    if (!onCompact) {\n      return { compaction, applied: false };\n    }\n\n    try {\n      await onCompact(compaction, { sessionId });\n\n      ctx.emitter.emit(\"orchestrator.compaction.applied\", {\n        sessionId,\n        compaction,\n      });\n\n      return { compaction, applied: true };\n    } catch (error) {\n      // onCompact threw — surface the compaction for the dev to apply,\n      // leave summarized_through unchanged (§12.2 step 4 failure path).\n      ctx.emitter.emit(\"orchestrator.compaction.failed\", {\n        sessionId,\n        phase: \"onCompact\",\n        error,\n      });\n\n      return { compaction, applied: false };\n    }\n  } catch (error) {\n    // Summarizer failed — skip-and-log; session keeps running unchanged.\n    ctx.emitter.emit(\"orchestrator.compaction.failed\", {\n      sessionId,\n      phase: \"summarize\",\n      error,\n    });\n\n    return undefined;\n  } finally {\n    await releaseCompactionLock(ctx, sessionId);\n  }\n}\n\n/**\n * Run a manual compaction for `command(\"compact\", ...)` (§11 / §12.1).\n * Same code path as the post-turn trigger but driven on demand against\n * the supplied history, returning the raw {@link CompactionResult}. The\n * callback form is honored; the config form without a `summarizer`\n * produces the degenerate memo. Does not apply `onCompact` — the\n * command surface returns the compaction for the caller to handle.\n */\nexport async function runManualCompaction<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  history: Message[],\n): Promise<CompactionResult> {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined) {\n    // No summarize policy configured — produce a degenerate memo over\n    // the full supplied history so the command always resolves.\n    return {\n      summary: { role: \"system\", content: `Summary of ${history.length} message(s).` },\n      replacesFromIndex: 0,\n      replacesToIndex: Math.max(-1, history.length - 1),\n    };\n  }\n\n  return produceCompaction(summarize, history);\n}\n\n/** Resolve the lock TTL from the summarize config (config form only). */\nfunction resolveLockMaxWait(ctx: OrchestratorEngineContext): number {\n  const summarize = ctx.config.summarize;\n\n  if (summarize === undefined || isCallbackForm(summarize)) {\n    return DEFAULT_LOCK_MAX_WAIT;\n  }\n\n  return summarize.lock?.maxWait ?? DEFAULT_LOCK_MAX_WAIT;\n}\n\n/**\n * Write the cooperative compaction lock onto a fresh checkpoint row\n * (§12.2 step 1). The lock lives on the latest persisted row; we load\n * it, stamp the lock columns, and re-save (append-only) so the next\n * turn's Phase 3 observes it.\n */\nasync function acquireCompactionLock<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\n): Promise<void> {\n  const latest = await ctx.checkpointStore.load(ctx.config.name, sessionId);\n\n  if (!latest) {\n    return;\n  }\n\n  const now = Date.now();\n  const maxWait = resolveLockMaxWait(ctx as OrchestratorEngineContext);\n\n  await ctx.checkpointStore.save({\n    ...latest,\n    lock_acquired_at: new Date(now).toISOString(),\n    lock_expires_at: new Date(now + maxWait).toISOString(),\n    saved_at: new Date(now).toISOString(),\n  });\n}\n\n/**\n * Clear the compaction lock columns (§12.2 step 6) by re-saving the\n * latest row with the lock fields nulled.\n */\nasync function releaseCompactionLock<TState>(\n  ctx: OrchestratorEngineContext<unknown, TState>,\n  sessionId: string,\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    lock_acquired_at: null,\n    lock_expires_at: null,\n    saved_at: new Date().toISOString(),\n  });\n}\n"],"mappings":"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"}

package/esm/ai/src/orchestrator/dispatch.mjs

@@ -0,0 +1,171 @@
+import { supervisor } from "../supervisor/supervisor.mjs";
+
+//#region ../@warlock.js/ai/src/orchestrator/dispatch.ts
+/**
+* Derive the deterministic supervisor `runId` for an `iterate: true`
+* turn (orchestrator.md §5 Phase 5 / §10.2 / §18.7):
+* `${sessionId}.${version ?? "unversioned"}.${turnIndex}`. No base64,
+* no hashing — the `sessionId` is the dev's responsibility to make
+* unique. Deploying a new `version` cleanly partitions in-flight runs
+* across deploys so old runIds never collide with new ones.
+*/
+function deriveRunId(sessionId, version, turnIndex) {
+	return `${sessionId}.${version ?? "unversioned"}.${turnIndex}`;
+}
+/**
+* Build the internal supervisor config by spreading the orchestrator's
+* supervisor-surface fields (orchestrator.md §1 / §5 Phase 5) and
+* seeding `state` from the session-state seed.
+*
+* `iterate: false` caps `maxIterations` at 1 — a single dispatch per
+* turn ("the supervisor's Phase A + Phase B once, no iteration loop" —
+* §5). `iterate: true` keeps the configured `maxIterations` (default
+* 10) and wires the `snapshotStore` for mid-turn resume.
+*
+* The orchestrator DELEGATES to the existing supervisor — it never
+* reimplements dispatch / route / evaluate / strip-merge logic.
+*/
+function buildSupervisorConfig(ctx, seedState, iterate, snapshotStore) {
+	const config = ctx.config;
+	return {
+		name: config.name,
+		version: config.version,
+		systemPrompt: config.systemPrompt,
+		intents: config.intents,
+		route: config.route,
+		router: config.router,
+		evaluate: config.evaluate,
+		state: seedState,
+		output: config.output,
+		initialAgent: config.initialAgent,
+		maxIterations: iterate ? config.maxIterations : 1,
+		historyWindow: config.historyWindow ? {
+			router: toNumber(config.historyWindow.router),
+			agents: toNumber(config.historyWindow.agents)
+		} : void 0,
+		snapshotStore: iterate ? snapshotStore : void 0
+	};
+}
+/**
+* The supervisor's `historyWindow` tiers accept only numbers; the
+* orchestrator's accept a number OR a slicer callback. The callback
+* form is already applied at the orchestrator level (Phase 4), so any
+* non-number here has already done its slicing — drop it for the
+* supervisor (which sees the pre-sliced history) by returning
+* `undefined`.
+*/
+function toNumber(value) {
+	return typeof value === "number" ? value : void 0;
+}
+/**
+* Build the forensic {@link TurnSnapshot} for the dispatched turn from
+* the supervisor's result. Mirrors the supervisor's `IterationSnapshot`
+* shape (§15.5) so a turn reads uniformly whether one agent ran
+* (`iterate: false`) or the internal supervisor iterated
+* (`iterate: true`). The terminal iteration's branch records and
+* decision are lifted onto the turn; the supervisor's full report tree
+* becomes the turn's `childReport`.
+*/
+function buildTurnSnapshot(input, turnIndex, result, state) {
+	const report = result.report;
+	const snapshots = report.snapshots;
+	const terminal = snapshots.length > 0 ? snapshots[snapshots.length - 1] : void 0;
+	const decisionSource = mapDecisionSource(terminal?.decision.source);
+	return Object.freeze({
+		turn: turnIndex,
+		input,
+		decision: {
+			source: decisionSource,
+			raw: terminal?.decision.next ?? null,
+			reasoning: terminal?.decision.reasoning
+		},
+		result: terminal?.result ?? {},
+		state,
+		evaluate: terminal?.evaluateVerdict,
+		startedAt: report.startedAt,
+		endedAt: report.endedAt,
+		duration: report.duration,
+		usage: report.usage,
+		childReport: report
+	});
+}
+/**
+* Map the supervisor's `DecisionSource` onto the narrower turn-snapshot
+* decision source (§15.5 — `"route" | "router" | "intent.next"`). The
+* supervisor's `initialAgent` / `classifier` first-turn sources collapse
+* to `"intent.next"` (a non-route/router origin) at the orchestrator
+* layer, which only distinguishes the three coarse decision origins.
+*/
+function mapDecisionSource(source) {
+	if (source === "route" || source === "router") return source;
+	return "intent.next";
+}
+/**
+* Phase 5 — dispatch turn (orchestrator.md §3 / §4 Phase 5).
+*
+* Constructs a fresh internal supervisor seeded from the session state,
+* then:
+*
+* - `iterate: false` — runs a single dispatch (`maxIterations: 1`).
+* - `iterate: true` — runs the full supervisor with a deterministic
+*   `runId`, resuming an in-flight run when the `SnapshotStore` already
+*   has one for that `runId` (§5 step 5).
+*
+* The supervisor's final state replaces the session state (§5 — replace
+* semantics). The supervisor is never kept alive across turns
+* (single-call lifecycle invariant — §18.8).
+*/
+async function dispatchTurn(params) {
+	const { ctx, sessionId, input, seedState, turnIndex, history, context, signal } = params;
+	const iterate = ctx.config.iterate === true;
+	const sup = supervisor(buildSupervisorConfig(ctx, seedState, iterate, ctx.snapshotStore));
+	let result;
+	if (iterate) {
+		const runId = deriveRunId(sessionId, ctx.config.version, turnIndex);
+		const inFlight = ctx.snapshotStore ? await ctx.snapshotStore.load(runId) : void 0;
+		if (inFlight && inFlight.status === "running") result = await sup.resume(runId, {
+			context,
+			signal,
+			history,
+			sessionId
+		});
+		else result = await sup.execute(input, {
+			runId,
+			context,
+			signal,
+			history,
+			sessionId
+		});
+	} else result = await sup.execute(input, {
+		context,
+		signal,
+		history,
+		sessionId
+	});
+	const state = deriveFinalState(result, seedState);
+	const turnSnapshot = buildTurnSnapshot(input, turnIndex, result, state);
+	return {
+		result,
+		state,
+		turnSnapshot
+	};
+}
+/**
+* Derive the post-turn session state from the supervisor result.
+* Prefers the terminal iteration's accumulated `state`; falls back to
+* the validated `data` (when an `output` schema reshaped it), then to
+* the seed when the run produced neither (e.g. it terminated before
+* dispatching anything). Replace semantics — the supervisor is the
+* authority on state evolution within its loop (§5).
+*/
+function deriveFinalState(result, seedState) {
+	const snapshots = result.report.snapshots;
+	const terminal = snapshots.length > 0 ? snapshots[snapshots.length - 1] : void 0;
+	if (terminal && terminal.state !== void 0) return terminal.state;
+	if (result.data !== void 0) return result.data;
+	return seedState;
+}
+
+//#endregion
+export { deriveRunId, dispatchTurn };
+//# sourceMappingURL=dispatch.mjs.map

package/esm/ai/src/orchestrator/dispatch.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch.mjs","names":["createSupervisor"],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/dispatch.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type { SnapshotStore } from \"../contracts/orchestrator/snapshot-store.contract\";\nimport type { SupervisorResult } from \"../contracts/result/supervisor-result.type\";\nimport type { TurnSnapshot } from \"../contracts/result/orchestrator-result.type\";\nimport type { SupervisorConfig } from \"../contracts/supervisor/supervisor-config.type\";\nimport type { SupervisorInput } from \"../contracts/supervisor/supervisor-input.type\";\nimport type { SupervisorReport } from \"../contracts/result/supervisor-result.type\";\nimport type { OrchestratorEngineContext } from \"./engine-context.type\";\nimport { supervisor as createSupervisor } from \"../supervisor/supervisor\";\n\n/**\n * Derive the deterministic supervisor `runId` for an `iterate: true`\n * turn (orchestrator.md §5 Phase 5 / §10.2 / §18.7):\n * `${sessionId}.${version ?? \"unversioned\"}.${turnIndex}`. No base64,\n * no hashing — the `sessionId` is the dev's responsibility to make\n * unique. Deploying a new `version` cleanly partitions in-flight runs\n * across deploys so old runIds never collide with new ones.\n */\nexport function deriveRunId(\n  sessionId: string,\n  version: string | undefined,\n  turnIndex: number,\n): string {\n  return `${sessionId}.${version ?? \"unversioned\"}.${turnIndex}`;\n}\n\n/** Parameters for one Phase-5 dispatch. */\nexport type DispatchParams<TOutput, TState> = {\n  ctx: OrchestratorEngineContext<TOutput, TState>;\n  sessionId: string;\n  input: SupervisorInput;\n  /** The session-state seed assembled in Phase 1 + the per-call patch. */\n  seedState: TState;\n  turnIndex: number;\n  /** Agent-windowed history from Phase 4. */\n  history: Message[];\n  context?: Record<string, unknown>;\n  signal?: AbortSignal;\n};\n\n/** Outcome of Phase 5 — the supervisor result plus the turn's snapshot. */\nexport type DispatchOutcome<TOutput> = {\n  result: SupervisorResult<TOutput>;\n  /** Post-dispatch session state (replaces session state per §5). */\n  state: unknown;\n  turnSnapshot: TurnSnapshot;\n};\n\n/**\n * Build the internal supervisor config by spreading the orchestrator's\n * supervisor-surface fields (orchestrator.md §1 / §5 Phase 5) and\n * seeding `state` from the session-state seed.\n *\n * `iterate: false` caps `maxIterations` at 1 — a single dispatch per\n * turn (\"the supervisor's Phase A + Phase B once, no iteration loop\" —\n * §5). `iterate: true` keeps the configured `maxIterations` (default\n * 10) and wires the `snapshotStore` for mid-turn resume.\n *\n * The orchestrator DELEGATES to the existing supervisor — it never\n * reimplements dispatch / route / evaluate / strip-merge logic.\n */\nfunction buildSupervisorConfig<TOutput, TState>(\n  ctx: OrchestratorEngineContext<TOutput, TState>,\n  seedState: TState,\n  iterate: boolean,\n  snapshotStore: SnapshotStore | undefined,\n): SupervisorConfig<TOutput, TState> {\n  const config = ctx.config;\n\n  const supervisorConfig: SupervisorConfig<TOutput, TState> = {\n    name: config.name,\n    version: config.version,\n    systemPrompt: config.systemPrompt,\n    intents: config.intents,\n    route: config.route,\n    router: config.router,\n    evaluate: config.evaluate,\n    state: seedState,\n    output: config.output,\n    initialAgent: config.initialAgent,\n    maxIterations: iterate ? config.maxIterations : 1,\n    historyWindow: config.historyWindow\n      ? { router: toNumber(config.historyWindow.router), agents: toNumber(config.historyWindow.agents) }\n      : undefined,\n    snapshotStore: iterate ? snapshotStore : undefined,\n  };\n\n  return supervisorConfig;\n}\n\n/**\n * The supervisor's `historyWindow` tiers accept only numbers; the\n * orchestrator's accept a number OR a slicer callback. The callback\n * form is already applied at the orchestrator level (Phase 4), so any\n * non-number here has already done its slicing — drop it for the\n * supervisor (which sees the pre-sliced history) by returning\n * `undefined`.\n */\nfunction toNumber(\n  value: number | ((messages: Message[]) => Message[]) | undefined,\n): number | undefined {\n  return typeof value === \"number\" ? value : undefined;\n}\n\n/**\n * Build the forensic {@link TurnSnapshot} for the dispatched turn from\n * the supervisor's result. Mirrors the supervisor's `IterationSnapshot`\n * shape (§15.5) so a turn reads uniformly whether one agent ran\n * (`iterate: false`) or the internal supervisor iterated\n * (`iterate: true`). The terminal iteration's branch records and\n * decision are lifted onto the turn; the supervisor's full report tree\n * becomes the turn's `childReport`.\n */\nfunction buildTurnSnapshot(\n  input: SupervisorInput,\n  turnIndex: number,\n  result: SupervisorResult<unknown>,\n  state: unknown,\n): TurnSnapshot {\n  const report = result.report;\n  const snapshots = report.snapshots;\n  const terminal = snapshots.length > 0 ? snapshots[snapshots.length - 1] : undefined;\n\n  const decisionSource = mapDecisionSource(terminal?.decision.source);\n\n  return Object.freeze({\n    turn: turnIndex,\n    input,\n    decision: {\n      source: decisionSource,\n      raw: terminal?.decision.next ?? null,\n      reasoning: terminal?.decision.reasoning,\n    },\n    result: terminal?.result ?? {},\n    state,\n    evaluate: terminal?.evaluateVerdict,\n    startedAt: report.startedAt,\n    endedAt: report.endedAt,\n    duration: report.duration,\n    usage: report.usage,\n    childReport: report,\n  });\n}\n\n/**\n * Map the supervisor's `DecisionSource` onto the narrower turn-snapshot\n * decision source (§15.5 — `\"route\" | \"router\" | \"intent.next\"`). The\n * supervisor's `initialAgent` / `classifier` first-turn sources collapse\n * to `\"intent.next\"` (a non-route/router origin) at the orchestrator\n * layer, which only distinguishes the three coarse decision origins.\n */\nfunction mapDecisionSource(\n  source: \"route\" | \"router\" | \"initialAgent\" | \"classifier\" | undefined,\n): \"route\" | \"router\" | \"intent.next\" {\n  if (source === \"route\" || source === \"router\") {\n    return source;\n  }\n\n  return \"intent.next\";\n}\n\n/**\n * Phase 5 — dispatch turn (orchestrator.md §3 / §4 Phase 5).\n *\n * Constructs a fresh internal supervisor seeded from the session state,\n * then:\n *\n * - `iterate: false` — runs a single dispatch (`maxIterations: 1`).\n * - `iterate: true` — runs the full supervisor with a deterministic\n *   `runId`, resuming an in-flight run when the `SnapshotStore` already\n *   has one for that `runId` (§5 step 5).\n *\n * The supervisor's final state replaces the session state (§5 — replace\n * semantics). The supervisor is never kept alive across turns\n * (single-call lifecycle invariant — §18.8).\n */\nexport async function dispatchTurn<TOutput, TState>(\n  params: DispatchParams<TOutput, TState>,\n): Promise<DispatchOutcome<TOutput>> {\n  const { ctx, sessionId, input, seedState, turnIndex, history, context, signal } =\n    params;\n\n  const iterate = ctx.config.iterate === true;\n  const sup = createSupervisor<TOutput, TState>(\n    buildSupervisorConfig(ctx, seedState, iterate, ctx.snapshotStore),\n  );\n\n  let result: SupervisorResult<TOutput>;\n\n  if (iterate) {\n    const runId = deriveRunId(sessionId, ctx.config.version, turnIndex);\n    const inFlight = ctx.snapshotStore\n      ? await ctx.snapshotStore.load(runId)\n      : undefined;\n\n    if (inFlight && inFlight.status === \"running\") {\n      result = await sup.resume(runId, { context, signal, history, sessionId });\n    } else {\n      result = await sup.execute(input, { runId, context, signal, history, sessionId });\n    }\n  } else {\n    result = await sup.execute(input, { context, signal, history, sessionId });\n  }\n\n  const state = deriveFinalState(result, seedState);\n  const turnSnapshot = buildTurnSnapshot(input, turnIndex, result, state);\n\n  return { result, state, turnSnapshot };\n}\n\n/**\n * Derive the post-turn session state from the supervisor result.\n * Prefers the terminal iteration's accumulated `state`; falls back to\n * the validated `data` (when an `output` schema reshaped it), then to\n * the seed when the run produced neither (e.g. it terminated before\n * dispatching anything). Replace semantics — the supervisor is the\n * authority on state evolution within its loop (§5).\n */\nfunction deriveFinalState<TOutput, TState>(\n  result: SupervisorResult<TOutput>,\n  seedState: TState,\n): unknown {\n  const report: SupervisorReport = result.report;\n  const snapshots = report.snapshots;\n  const terminal = snapshots.length > 0 ? snapshots[snapshots.length - 1] : undefined;\n\n  if (terminal && terminal.state !== undefined) {\n    return terminal.state;\n  }\n\n  if (result.data !== undefined) {\n    return result.data;\n  }\n\n  return seedState;\n}\n"],"mappings":";;;;;;;;;;;AAkBA,SAAgB,YACd,WACA,SACA,WACQ;CACR,OAAO,GAAG,UAAU,GAAG,WAAW,cAAc,GAAG;AACrD;;;;;;;;;;;;;;AAqCA,SAAS,sBACP,KACA,WACA,SACA,eACmC;CACnC,MAAM,SAAS,IAAI;CAoBnB,OAAO;EAjBL,MAAM,OAAO;EACb,SAAS,OAAO;EAChB,cAAc,OAAO;EACrB,SAAS,OAAO;EAChB,OAAO,OAAO;EACd,QAAQ,OAAO;EACf,UAAU,OAAO;EACjB,OAAO;EACP,QAAQ,OAAO;EACf,cAAc,OAAO;EACrB,eAAe,UAAU,OAAO,gBAAgB;EAChD,eAAe,OAAO,gBAClB;GAAE,QAAQ,SAAS,OAAO,cAAc,MAAM;GAAG,QAAQ,SAAS,OAAO,cAAc,MAAM;EAAE,IAC/F;EACJ,eAAe,UAAU,gBAAgB;CAGrB;AACxB;;;;;;;;;AAUA,SAAS,SACP,OACoB;CACpB,OAAO,OAAO,UAAU,WAAW,QAAQ;AAC7C;;;;;;;;;;AAWA,SAAS,kBACP,OACA,WACA,QACA,OACc;CACd,MAAM,SAAS,OAAO;CACtB,MAAM,YAAY,OAAO;CACzB,MAAM,WAAW,UAAU,SAAS,IAAI,UAAU,UAAU,SAAS,KAAK;CAE1E,MAAM,iBAAiB,kBAAkB,UAAU,SAAS,MAAM;CAElE,OAAO,OAAO,OAAO;EACnB,MAAM;EACN;EACA,UAAU;GACR,QAAQ;GACR,KAAK,UAAU,SAAS,QAAQ;GAChC,WAAW,UAAU,SAAS;EAChC;EACA,QAAQ,UAAU,UAAU,CAAC;EAC7B;EACA,UAAU,UAAU;EACpB,WAAW,OAAO;EAClB,SAAS,OAAO;EAChB,UAAU,OAAO;EACjB,OAAO,OAAO;EACd,aAAa;CACf,CAAC;AACH;;;;;;;;AASA,SAAS,kBACP,QACoC;CACpC,IAAI,WAAW,WAAW,WAAW,UACnC,OAAO;CAGT,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,eAAsB,aACpB,QACmC;CACnC,MAAM,EAAE,KAAK,WAAW,OAAO,WAAW,WAAW,SAAS,SAAS,WACrE;CAEF,MAAM,UAAU,IAAI,OAAO,YAAY;CACvC,MAAM,MAAMA,WACV,sBAAsB,KAAK,WAAW,SAAS,IAAI,aAAa,CAClE;CAEA,IAAI;CAEJ,IAAI,SAAS;EACX,MAAM,QAAQ,YAAY,WAAW,IAAI,OAAO,SAAS,SAAS;EAClE,MAAM,WAAW,IAAI,gBACjB,MAAM,IAAI,cAAc,KAAK,KAAK,IAClC;EAEJ,IAAI,YAAY,SAAS,WAAW,WAClC,SAAS,MAAM,IAAI,OAAO,OAAO;GAAE;GAAS;GAAQ;GAAS;EAAU,CAAC;OAExE,SAAS,MAAM,IAAI,QAAQ,OAAO;GAAE;GAAO;GAAS;GAAQ;GAAS;EAAU,CAAC;CAEpF,OACE,SAAS,MAAM,IAAI,QAAQ,OAAO;EAAE;EAAS;EAAQ;EAAS;CAAU,CAAC;CAG3E,MAAM,QAAQ,iBAAiB,QAAQ,SAAS;CAChD,MAAM,eAAe,kBAAkB,OAAO,WAAW,QAAQ,KAAK;CAEtE,OAAO;EAAE;EAAQ;EAAO;CAAa;AACvC;;;;;;;;;AAUA,SAAS,iBACP,QACA,WACS;CAET,MAAM,YAD2B,OAAO,OACf;CACzB,MAAM,WAAW,UAAU,SAAS,IAAI,UAAU,UAAU,SAAS,KAAK;CAE1E,IAAI,YAAY,SAAS,UAAU,QACjC,OAAO,SAAS;CAGlB,IAAI,OAAO,SAAS,QAClB,OAAO,OAAO;CAGhB,OAAO;AACT"}

package/esm/ai/src/orchestrator/emitter.mjs

@@ -0,0 +1,85 @@
+//#region ../@warlock.js/ai/src/orchestrator/emitter.ts
+/**
+* Three-tier orchestrator event emitter — definition (factory) →
+* instance → per-call — for the `orchestrator.*` namespace (design
+* §14.3). Mirrors {@link import("../supervisor/emitter").SupervisorEmitter}
+* structurally; the differences are the event map and a central
+* identity-injection chokepoint (`emit` accepts an identity-less
+* payload and stamps {@link EventIdentity} once so all three tiers, and
+* any mirror like the stream, see the same value).
+*
+* Owns: the instance-handler registry and the fan-out order. Does NOT
+* own: child `supervisor.*` / `agent.*` events — those bubble up
+* unmodified under their own identity (§14.2) and never pass through
+* this emitter. All matching handlers fire in tier order; a handler
+* throwing never derails the turn.
+*
+* @example
+* const emitter = new OrchestratorEmitter(config.on);
+* const off = emitter.on("orchestrator.turn.completed", (event) => log(event));
+* emitter.emit(
+*   "orchestrator.turn.starting",
+*   { sessionId, turnIndex },
+*   { runId, rootRunId },
+*   perCallHandlers,
+* );
+*/
+var OrchestratorEmitter = class {
+	constructor(factoryHandlers) {
+		this.instanceHandlers = /* @__PURE__ */ new Map();
+		this.factoryHandlers = factoryHandlers;
+	}
+	/**
+	* Subscribe an instance-level handler (tier 2). Returns an
+	* unsubscribe function equivalent to `off(event, handler)`.
+	*/
+	on(event, handler) {
+		let bucket = this.instanceHandlers.get(event);
+		if (!bucket) {
+			bucket = /* @__PURE__ */ new Set();
+			this.instanceHandlers.set(event, bucket);
+		}
+		bucket.add(handler);
+		return () => this.off(event, handler);
+	}
+	/**
+	* Remove a previously-subscribed instance handler. No-op when the
+	* handler was never registered or already removed.
+	*/
+	off(event, handler) {
+		this.instanceHandlers.get(event)?.delete(handler);
+	}
+	/**
+	* Stamp run identity onto the payload, then fan out through all three
+	* tiers in order: definition → instance → per-call. Returns the full
+	* identity-stamped payload so the caller can mirror the same value
+	* into the stream controller (keeping `.on()` and iteration in lockstep).
+	*/
+	emit(event, payload, identity, perCallHandlers) {
+		const fullPayload = {
+			...payload,
+			...identity
+		};
+		invoke(this.factoryHandlers?.[event], fullPayload);
+		const bucket = this.instanceHandlers.get(event);
+		if (bucket) for (const handler of bucket) invoke(handler, fullPayload);
+		invoke(perCallHandlers?.[event], fullPayload);
+		return fullPayload;
+	}
+};
+/**
+* Invoke a single handler, swallowing any throw. A listener bug must
+* never derail the orchestrator turn. Typed structurally (a plain
+* `(payload) => void`) so the identity-stamped payload flows in without
+* fighting the contravariant `OrchestratorEventHandler<K>` union.
+*/
+function invoke(handler, payload) {
+	if (typeof handler !== "function") return;
+	try {
+		handler(payload);
+	} catch {}
+}
+
+//#endregion
+export { OrchestratorEmitter };
+//# sourceMappingURL=emitter.mjs.map

package/esm/ai/src/orchestrator/emitter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"emitter.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/orchestrator/emitter.ts"],"sourcesContent":["import type {\n  EventIdentity,\n  WithoutIdentity,\n} from \"../contracts/events/event-identity.type\";\nimport type {\n  OrchestratorEventHandler,\n  OrchestratorEventHandlers,\n  OrchestratorEventMap,\n  OrchestratorEventName,\n} from \"../contracts/orchestrator/orchestrator-event.type\";\n\n/** Full identity-stamped payload an orchestrator handler receives. */\ntype EventPayload<K extends OrchestratorEventName> = OrchestratorEventMap[K] &\n  EventIdentity;\n\n/**\n * Erased handler shape for the instance registry. Per-event handlers\n * are contravariant in their payload, so the registry stores them under\n * a single structural `(payload) => void` and re-narrows at the call\n * site — the `on` / `off` public surface keeps the precise per-event\n * typing.\n */\ntype AnyHandler = (payload: EventPayload<OrchestratorEventName>) => void;\n\n/**\n * Three-tier orchestrator event emitter — definition (factory) →\n * instance → per-call — for the `orchestrator.*` namespace (design\n * §14.3). Mirrors {@link import(\"../supervisor/emitter\").SupervisorEmitter}\n * structurally; the differences are the event map and a central\n * identity-injection chokepoint (`emit` accepts an identity-less\n * payload and stamps {@link EventIdentity} once so all three tiers, and\n * any mirror like the stream, see the same value).\n *\n * Owns: the instance-handler registry and the fan-out order. Does NOT\n * own: child `supervisor.*` / `agent.*` events — those bubble up\n * unmodified under their own identity (§14.2) and never pass through\n * this emitter. All matching handlers fire in tier order; a handler\n * throwing never derails the turn.\n *\n * @example\n * const emitter = new OrchestratorEmitter(config.on);\n * const off = emitter.on(\"orchestrator.turn.completed\", (event) => log(event));\n * emitter.emit(\n *   \"orchestrator.turn.starting\",\n *   { sessionId, turnIndex },\n *   { runId, rootRunId },\n *   perCallHandlers,\n * );\n */\nexport class OrchestratorEmitter {\n  private readonly factoryHandlers?: OrchestratorEventHandlers;\n  private readonly instanceHandlers = new Map<\n    OrchestratorEventName,\n    Set<AnyHandler>\n  >();\n\n  public constructor(factoryHandlers?: OrchestratorEventHandlers) {\n    this.factoryHandlers = factoryHandlers;\n  }\n\n  /**\n   * Subscribe an instance-level handler (tier 2). Returns an\n   * unsubscribe function equivalent to `off(event, handler)`.\n   */\n  public on<K extends OrchestratorEventName>(\n    event: K,\n    handler: OrchestratorEventHandler<K>,\n  ): () => void {\n    let bucket = this.instanceHandlers.get(event);\n\n    if (!bucket) {\n      bucket = new Set();\n      this.instanceHandlers.set(event, bucket);\n    }\n\n    bucket.add(handler as unknown as AnyHandler);\n\n    return () => this.off(event, handler);\n  }\n\n  /**\n   * Remove a previously-subscribed instance handler. No-op when the\n   * handler was never registered or already removed.\n   */\n  public off<K extends OrchestratorEventName>(\n    event: K,\n    handler: OrchestratorEventHandler<K>,\n  ): void {\n    this.instanceHandlers.get(event)?.delete(handler as unknown as AnyHandler);\n  }\n\n  /**\n   * Stamp run identity onto the payload, then fan out through all three\n   * tiers in order: definition → instance → per-call. Returns the full\n   * identity-stamped payload so the caller can mirror the same value\n   * into the stream controller (keeping `.on()` and iteration in lockstep).\n   */\n  public emit<K extends OrchestratorEventName>(\n    event: K,\n    payload: WithoutIdentity<OrchestratorEventMap[K]>,\n    identity: EventIdentity,\n    perCallHandlers?: OrchestratorEventHandlers,\n  ): EventPayload<K> {\n    const fullPayload = { ...payload, ...identity } as EventPayload<K>;\n\n    invoke(this.factoryHandlers?.[event], fullPayload);\n\n    const bucket = this.instanceHandlers.get(event);\n\n    if (bucket) {\n      for (const handler of bucket) {\n        invoke(handler as unknown as (payload: EventPayload<K>) => void, fullPayload);\n      }\n    }\n\n    invoke(perCallHandlers?.[event], fullPayload);\n\n    return fullPayload;\n  }\n}\n\n/**\n * Invoke a single handler, swallowing any throw. A listener bug must\n * never derail the orchestrator turn. Typed structurally (a plain\n * `(payload) => void`) so the identity-stamped payload flows in without\n * fighting the contravariant `OrchestratorEventHandler<K>` union.\n */\nfunction invoke<K extends OrchestratorEventName>(\n  handler: ((payload: EventPayload<K>) => void) | undefined,\n  payload: EventPayload<K>,\n): void {\n  if (typeof handler !== \"function\") {\n    return;\n  }\n\n  try {\n    handler(payload);\n  } catch {\n    // Listener bugs must not derail the orchestrator.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAiDA,IAAa,sBAAb,MAAiC;CAO/B,AAAO,YAAY,iBAA6C;0CAL5B,IAAI,IAGtC;EAGA,KAAK,kBAAkB;CACzB;;;;;CAMA,AAAO,GACL,OACA,SACY;EACZ,IAAI,SAAS,KAAK,iBAAiB,IAAI,KAAK;EAE5C,IAAI,CAAC,QAAQ;GACX,yBAAS,IAAI,IAAI;GACjB,KAAK,iBAAiB,IAAI,OAAO,MAAM;EACzC;EAEA,OAAO,IAAI,OAAgC;EAE3C,aAAa,KAAK,IAAI,OAAO,OAAO;CACtC;;;;;CAMA,AAAO,IACL,OACA,SACM;EACN,KAAK,iBAAiB,IAAI,KAAK,CAAC,EAAE,OAAO,OAAgC;CAC3E;;;;;;;CAQA,AAAO,KACL,OACA,SACA,UACA,iBACiB;EACjB,MAAM,cAAc;GAAE,GAAG;GAAS,GAAG;EAAS;EAE9C,OAAO,KAAK,kBAAkB,QAAQ,WAAW;EAEjD,MAAM,SAAS,KAAK,iBAAiB,IAAI,KAAK;EAE9C,IAAI,QACF,KAAK,MAAM,WAAW,QACpB,OAAO,SAA0D,WAAW;EAIhF,OAAO,kBAAkB,QAAQ,WAAW;EAE5C,OAAO;CACT;AACF;;;;;;;AAQA,SAAS,OACP,SACA,SACM;CACN,IAAI,OAAO,YAAY,YACrB;CAGF,IAAI;EACF,QAAQ,OAAO;CACjB,QAAQ,CAER;AACF"}