@fyeeme/pi-dynamic-workflows 0.1.1

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@fyeeme/pi-dynamic-workflows",
+  "version": "0.1.1",
+  "description": "Deterministic TypeScript workflow orchestration for pi. Fuses the pi-dynamic-workflows design (declarative graph, 10 step primitives, heuristic planner, outcome collectors) with Claude Code's workflow engine coordination mechanisms (deterministic sandbox, cache-key resume, per-agent abort map, dynamic budget, runaway caps).",
+  "type": "module",
+  "license": "MIT",
+  "author": "fyeeme",
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "dynamic-workflow",
+    "workflow",
+    "orchestration",
+    "fan-out",
+    "pipeline",
+    "multi-agent"
+  ],
+  "files": [
+    "*.ts",
+    "src/**/*.ts",
+    "sessions/**/*.ts",
+    "README.md",
+    "README.zh-CN.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "vitest --run",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@fyeeme/pi-subagent-core": "^0.3.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": ">=0.84.1",
+    "@earendil-works/pi-coding-agent": ">=0.84.1",
+    "@earendil-works/pi-tui": ">=0.84.1",
+    "jiti": ">=2.0.0",
+    "typebox": ">=1.0.0",
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
+    "@types/node": "22.19.19",
+    "jiti": "2.7.0",
+    "typebox": "1.1.38",
+    "typescript": "5.9.3"
+  }
+}

package/sessions/spawn.ts

@@ -0,0 +1,15 @@
+/**
+ * sessions/spawn.ts — public per-agent abort/skip API (README §7).
+ *
+ * Thin barrel over src/agent/dispatch.ts: the spawn registry + per-agent
+ * abort primitives. The core spawn implementation lives in
+ * `@fyeeme/pi-subagent-core`; skip/retry (workflows-specific) stay in
+ * dispatch.ts.
+ */
+export {
+	abortAgent,
+	createSpawnRegistry,
+	retryAgent,
+	skipAgent,
+	type AgentSpawnRegistry,
+} from "../src/agent/dispatch.ts";

package/src/agent/dispatch.ts

@@ -0,0 +1,76 @@
+/**
+ * src/agent/dispatch.ts — agent dispatch底层 (Task 2)
+ *
+ * The core spawn primitive (`spawnAgent`, `mapWithConcurrencyLimit`,
+ * `createSpawnRegistry`, `abortAgent`, `getPiInvocation` + the registry/
+ * options/result types) lives in the shared `@fyeeme/pi-subagent-core`
+ * package — extracted from the duplicate copies that used to live here and
+ * in pi-review. This module keeps the workflows-specific layer on top:
+ * `skipAgent`/`retryAgent` (with `AbortReason` semantics) and the lifecycle
+ * notifications.
+ *
+ * Core semantics: one `pi --mode json -p --no-session` subprocess per agent
+ * call, stdout parsed for {message_end, tool_result_end} events,
+ * AbortSignal → SIGTERM with a 5s SIGKILL escalation. Each call owns a
+ * per-call AbortController registered in an AgentAbortMap, paired with
+ * Map<callId, ChildProcess>. A single callId can be aborted (retry/skip)
+ * without disturbing its batch siblings, because abort is translated to a
+ * SIGTERM on exactly one process.
+ */
+import type { AgentLifecycleListeners } from "../lifecycle.ts";
+import { notifyRetry, notifySkip } from "../lifecycle.ts";
+import type { AgentSpawnRegistry } from "@fyeeme/pi-subagent-core";
+
+// Re-export the core dispatch surface so existing importers of this module
+// (`../agent/dispatch.ts`) keep working unchanged.
+export {
+	abortAgent,
+	createSpawnRegistry,
+	getPiInvocation,
+	mapWithConcurrencyLimit,
+	spawnAgent,
+} from "@fyeeme/pi-subagent-core";
+export type {
+	AgentAbortMap,
+	AgentCallId,
+	AgentSpawnOptions,
+	AgentSpawnRegistry,
+	AgentSpawnResult,
+	AgentUsage,
+} from "@fyeeme/pi-subagent-core";
+
+export type AbortReason = "user-skip" | "user-retry";
+
+/**
+ * Abort one call as skipped. The call settles skipped (runner will not
+ * re-dispatch it); batch siblings are untouched. Fires `onAgentSkip`.
+ */
+export function skipAgent(
+	registry: AgentSpawnRegistry,
+	callId: string,
+	listeners?: AgentLifecycleListeners,
+): boolean {
+	const controller = registry.controllers.get(callId);
+	if (!controller) return false;
+	controller.abort("user-skip");
+	notifySkip(listeners, callId);
+	return true;
+}
+
+/**
+ * Abort one call so the runner can re-dispatch it. Only this callId is
+ * aborted; batch siblings keep running. Fires `onAgentRetry`. The actual
+ * re-dispatch is the runner's job (it sees the call settle aborted and
+ * decides whether to spawn again).
+ */
+export function retryAgent(
+	registry: AgentSpawnRegistry,
+	callId: string,
+	listeners?: AgentLifecycleListeners,
+): boolean {
+	const controller = registry.controllers.get(callId);
+	if (!controller) return false;
+	controller.abort("user-retry");
+	notifyRetry(listeners, callId);
+	return true;
+}

package/src/budget/caps.ts

@@ -0,0 +1,42 @@
+/**
+ * Hard runaway caps — the pi port of CC's workflow backstops.
+ *
+ * CC caps: `min(16, cpu-2)` concurrent per workflow, 1000 agents per workflow
+ * lifetime (runaway backstop), 4096 items per `parallel()`/`pipeline()` call
+ * (explicit error on exceed — never silent truncation). Pi ports the lifetime
+ * and batch caps here; the concurrency cap is enforced by
+ * `mapWithConcurrencyLimit` in src/agent/dispatch.ts.
+ */
+
+import { WorkflowError } from "../errors.ts";
+
+export const MAX_LIFETIME_AGENTS = 1000;
+export const MAX_BATCH = 4096;
+
+/** Budget exhaustion (maxAgents / maxTokens / maxDuration) or a hard cap hit
+ *  (MAX_BATCH / MAX_LIFETIME_AGENTS). Extends WorkflowError so it carries the
+ *  `budget-exceeded` category for retry policy (terminal by default). */
+export class BudgetExceededError extends WorkflowError {
+	constructor(message: string) {
+		super(message, { category: "budget-exceeded" });
+		this.name = "BudgetExceededError";
+	}
+}
+
+/** Assert a fan-out batch fits the hard cap. Throws — no silent truncation. */
+export function assertBatchSize(n: number): void {
+	if (n > MAX_BATCH) {
+		throw new BudgetExceededError(
+			`fan-out batch ${n} exceeds MAX_BATCH (${MAX_BATCH}); pass fewer items or split the input`,
+		);
+	}
+}
+
+/** Assert cumulative agent count hasn't hit the runaway backstop. */
+export function assertLifetimeAgents(spawned: number): void {
+	if (spawned >= MAX_LIFETIME_AGENTS) {
+		throw new BudgetExceededError(
+			`workflow spawned ${spawned} agents — MAX_LIFETIME_AGENTS (${MAX_LIFETIME_AGENTS}) runaway backstop reached`,
+		);
+	}
+}

package/src/budget/index.ts

@@ -0,0 +1,8 @@
+export {
+	BudgetExceededError,
+	MAX_BATCH,
+	MAX_LIFETIME_AGENTS,
+	assertBatchSize,
+	assertLifetimeAgents,
+} from "./caps.ts";
+export { BudgetPool, type BudgetRemaining } from "./pool.ts";

package/src/budget/pool.ts

@@ -0,0 +1,118 @@
+/**
+ * Budget pool — CC's `budget.{total, spent(), remaining()}` re-expressed for pi.
+ *
+ * A static `Budget` (types.ts) describes caps; a `BudgetPool` is the live,
+ * queryable tracker the runtime mutates as agents settle. Caps are enforced
+ * as SPAWN-GATE SOFT LIMITS: the runtime checks `isExhausted()` before
+ * committing each new spawn (guardSpawn/guardBatch) and stops spawning when
+ * exhausted — an in-flight agent is allowed to complete and may push spend
+ * past the cap. fan_out concurrency is the step's static `parallelism`; the
+ * budget does not dynamically resize it.
+ *
+ * Determinism: identity (runId, journal timestamps, cache keys) never reads
+ * Date.now() — `now` is the run inception timestamp. The DURATION dimension,
+ * however, is wall-clock and the engine reads Date.now() at the guard points
+ * (guardSpawn/guardBatch) to enforce maxDurationMs; engine code is not
+ * AST-guarded. Token/agent dimensions are passed `now` but don't depend on
+ * it (elapsed only matters for duration).
+ *
+ * Scope: per-run (one pool per workflow execution), not global.
+ *
+ * P1-1 fix — reservation model: the agents dimension is committed synchronously
+ * via `reserve(n)` (check + increment in one step, no `await` gap), closing the
+ * TOCTOU where N concurrent fan_out workers all read `remaining.agents >= 1`
+ * before any settles. `reserve` returns a release handle; a failed dispatch
+ * (spawn rejected) calls it to return the slot. Tokens can't be reserved
+ * (cost is unknown until the agent settles), so maxTokens stays an
+ * after-the-fact track + isExhausted check on the next guard.
+ */
+import type { Budget } from "../types.ts";
+import { BudgetExceededError } from "./caps.ts";
+
+export interface BudgetRemaining {
+	/** Tokens left before maxTokens is hit. Infinity if uncapped. */
+	readonly tokens: number;
+	/** Milliseconds left before maxDurationMs. Infinity if uncapped. */
+	readonly durationMs: number;
+	/** Agent slots left before maxAgents. Infinity if uncapped. */
+	readonly agents: number;
+}
+
+export class BudgetPool {
+	private spentTokens = 0;
+	/** Agents reserved via reserve() — synchronously committed, so concurrent
+	 * callers can't all pass the check before any settles (TOCTOU). */
+	private reservedAgents = 0;
+	private readonly originMs: number;
+	private readonly config: Budget;
+
+	// Note: no parameter properties (e.g. `private readonly config` in the param
+	// list) — erasableSyntaxOnly forbids them. Declare the field, assign in body.
+	constructor(config: Budget, originMs: number) {
+		this.config = config;
+		this.originMs = originMs;
+	}
+
+	/**
+	 * Atomically reserve `n` agent slots against maxAgents. Throws
+	 * BudgetExceededError if the reservation would exceed the cap. Returns a
+	 * release handle — call it ONLY if the dispatch fails (the slot was never
+	 * used); a settled agent keeps its slot (it consumed budget).
+	 */
+	reserve(n: number): () => void {
+		if (n <= 0) return () => {};
+		const cap = this.config.maxAgents;
+		if (cap !== undefined && this.reservedAgents + n > cap) {
+			throw new BudgetExceededError(
+				`budget exhausted: ${this.reservedAgents + n} agent(s) would exceed maxAgents ${cap}`,
+			);
+		}
+		this.reservedAgents += n;
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			this.reservedAgents -= n;
+		};
+	}
+
+	/** Record token spend by a settled agent. (Agents are counted via reserve.) */
+	track(input: { tokens?: number }): void {
+		if (input.tokens) this.spentTokens += input.tokens;
+	}
+
+	/** The configured cap set (CC's budget.total surface). */
+	get total(): Budget {
+		return this.config;
+	}
+
+	/** Remaining headroom per dimension at time `now`. */
+	remaining(now: number): BudgetRemaining {
+		return {
+			tokens:
+				this.config.maxTokens !== undefined
+					? Math.max(0, this.config.maxTokens - this.spentTokens)
+					: Number.POSITIVE_INFINITY,
+			durationMs:
+				this.config.maxDurationMs !== undefined
+					? Math.max(0, this.config.maxDurationMs - (now - this.originMs))
+					: Number.POSITIVE_INFINITY,
+			agents:
+				this.config.maxAgents !== undefined
+					? Math.max(0, this.config.maxAgents - this.reservedAgents)
+					: Number.POSITIVE_INFINITY,
+		};
+	}
+
+	/** True once any capped dimension hits zero. */
+	isExhausted(now: number): boolean {
+		const r = this.remaining(now);
+		return r.tokens === 0 || r.durationMs === 0 || r.agents === 0;
+	}
+
+	/** Can n more agents be spawned under the agents cap? (Pre-check; actual
+	 * commit is via reserve().) */
+	canSpawn(n: number, now: number): boolean {
+		return this.remaining(now).agents >= n;
+	}
+}

package/src/cache/index.ts

@@ -0,0 +1,7 @@
+export {
+	computeCacheKey,
+	normalizeSignature,
+	type AgentCacheSignature,
+	type CacheKeyInput,
+} from "./key.ts";
+export { Journal, type JournalEntry, type JournalOptions, type RunManifest } from "./journal.ts";

package/src/cache/journal.ts

@@ -0,0 +1,184 @@
+/**
+ * Per-run journal of agent call results — the pi port of CC.s LocalFileJournal.
+ *
+ * One JSONL file per run (<dir>/journal.jsonl). Each line is either a
+ * `started` marker (an agent dispatched) or a `result` (an agent settled with
+ * a value). On resume, the journal is loaded into an in-memory map keyed by
+ * CacheKey; `result` entries supersede earlier `started` entries for the same
+ * key. The runner consults `lookup()` before dispatching: a hit means replay,
+ * skipping the subprocess entirely.
+ *
+ * Append-only within a run; resume reads the existing file, then the resumed
+ * run continues appending entries for cache-miss agents.
+ *
+ * Determinism note: `at` is an opaque counter/timestamp supplied by the caller
+ * (from the run's deterministic inception time, never Date.now() inside the
+ * workflow body — the Task 3 sandbox forbids that).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { CacheKey } from "../types.ts";
+
+export type JournalEntry<T = unknown> =
+	| { readonly type: "started"; readonly key: CacheKey; readonly at: number }
+	| { readonly type: "result"; readonly key: CacheKey; readonly at: number; readonly ok: boolean; readonly value: T };
+
+/** Staged-resume manifest: identifies the last completed run. Only `runId` is
+ *  consumed downstream (resume.previousRunId); cache-hit accounting is observed
+ *  live during the run, so no key list is persisted here. */
+export interface RunManifest {
+	/** Run ID that produced this manifest. */
+	readonly runId: string;
+	/** Inception timestamp. */
+	readonly at: number;
+}
+
+export interface JournalOptions {
+	/** Directory holding journal.jsonl (typically <cwd>/.pi/workflows/runs/<runId>). */
+	readonly dir: string;
+}
+
+/** Monotonic counter for unique manifest temp-file names (crash-safe atomic writes). */
+let manifestSeq = 0;
+
+export class Journal {
+	private readonly filePath: string;
+	/** key → latest entry. result entries supersede started entries. */
+	private readonly results = new Map<CacheKey, JournalEntry>();
+	private loaded = false;
+
+	constructor(opts: JournalOptions) {
+		this.filePath = path.join(opts.dir, "journal.jsonl");
+	}
+
+	/** Read the JSONL file into the in-memory map. A missing file (fresh run) is a no-op. */
+	async load(): Promise<void> {
+		let content: string;
+		try {
+			content = await fs.promises.readFile(this.filePath, "utf-8");
+		} catch (e) {
+			if (!isENOENT(e)) throw e;
+			this.loaded = true;
+			return;
+		}
+		for (const line of content.split("\n")) {
+			if (!line.trim()) continue;
+			let entry: JournalEntry;
+			try {
+				entry = JSON.parse(line) as JournalEntry;
+			} catch {
+				continue; // skip malformed line, keep the rest
+			}
+			if (entry.type === "result") this.results.set(entry.key, entry);
+		}
+		this.loaded = true;
+	}
+
+	/** Look up a settled result by cache key. Undefined = cache miss → must dispatch. */
+	lookup(key: CacheKey): JournalEntry | undefined {
+		return this.results.get(key);
+	}
+
+	/** Append an entry to disk and (for result entries) the in-memory map. */
+	private appendChain: Promise<void> = Promise.resolve();
+	private lastWriteError: unknown;
+	async append(entry: JournalEntry): Promise<void> {
+		if (entry.type === "result") this.results.set(entry.key, entry);
+		// Serialize appends: concurrent appendFile calls interleave bytes for
+		// entries larger than PIPE_BUF (4KB on Linux), corrupting JSONL lines that
+		// Journal.load then silently drops. Chain each write onto the previous.
+		//
+		// P0 fix: catch on the chain so a single disk failure (ENOSPC/EACCES/EIO)
+		// does NOT poison it forever — without the catch, every later `.then`
+		// never runs its callback, so all subsequent writes become permanent
+		// silent no-ops while `lookup()` keeps returning the in-memory entries.
+		// The failed write is recorded in `lastWriteError` for the caller.
+		const line = JSON.stringify(entry) + "\n";
+		this.appendChain = this.appendChain
+			.then(() => fs.promises.appendFile(this.filePath, line, "utf-8"))
+			.catch((e) => {
+				this.lastWriteError = e;
+			});
+		return this.appendChain;
+	}
+
+	/** Number of cached results currently in memory. */
+	get size(): number {
+		return this.results.size;
+	}
+
+	get file(): string {
+		return this.filePath;
+	}
+
+	get isLoaded(): boolean {
+		return this.loaded;
+	}
+
+	/** The most recent disk-write error, if any. A non-null value means at least
+	 * one entry may be in memory but not on disk → resume could lose it. */
+	get writeError(): unknown {
+		return this.lastWriteError;
+	}
+
+	/** Iterator over all entries in the in-memory cache. */
+	allEntries(): IterableIterator<JournalEntry> {
+		return this.results.values();
+	}
+
+	/** Write the staged-resume manifest for the next run to consume.
+	 *  Call after the run completes successfully. Written atomically
+	 *  (write-temp + rename) so a crash between truncate and write can never
+	 *  leave a 0-byte / truncated manifest that would crash future runs. */
+	async writeManifest(manifest: RunManifest): Promise<void> {
+		const dir = path.dirname(this.filePath);
+		const manifestPath = path.join(dir, "manifest.json");
+		const tmp = path.join(dir, `.manifest.${process.pid}.${manifestSeq++}.tmp`);
+		// Sweep stale tmp files from crashed prior writes BEFORE writing ours — a
+		// post-write sweep would match (and delete) the file we are about to
+		// rename from.
+		await this.sweepStaleTmp(dir);
+		await fs.promises.writeFile(tmp, JSON.stringify(manifest, null, 2), "utf-8");
+		await fs.promises.rename(tmp, manifestPath);
+	}
+
+	private async sweepStaleTmp(dir: string): Promise<void> {
+		try {
+			const entries = await fs.promises.readdir(dir);
+			await Promise.all(
+				entries
+					.filter((e) => e.startsWith(".manifest.") && e.endsWith(".tmp"))
+					.map((e) => fs.promises.unlink(path.join(dir, e)).catch(() => {})),
+			);
+		} catch {
+			/* best-effort */
+		}
+	}
+
+	/** Load the staged-resume manifest from the last completed run, if present.
+	 *  Best-effort and crash-resilient: a missing file is the normal
+	 *  pre-first-run state; a corrupt/truncated file (e.g. after a crash
+	 *  mid-write) is treated as "no manifest" with a warning — it MUST never
+	 *  crash the run. The next successful run overwrites it. */
+	async loadManifest(): Promise<RunManifest | undefined> {
+		const manifestPath = path.join(path.dirname(this.filePath), "manifest.json");
+		let raw: string;
+		try {
+			raw = await fs.promises.readFile(manifestPath, "utf-8");
+		} catch (e) {
+			if (isENOENT(e)) return undefined; // normal pre-first-run state
+			console.warn(`[pi-dynamic-workflows] manifest read failed, ignoring: ${(e as Error).message}`);
+			return undefined;
+		}
+		try {
+			return JSON.parse(raw) as RunManifest;
+		} catch (e) {
+			console.warn(`[pi-dynamic-workflows] manifest is corrupt, ignoring: ${(e as Error).message}`);
+			return undefined;
+		}
+	}
+}
+
+function isENOENT(e: unknown): boolean {
+	return e !== null && typeof e === "object" && (e as { code?: string }).code === "ENOENT";
+}

package/src/cache/key.ts

@@ -0,0 +1,97 @@
+/**
+ * Cache key for agent invocations — the pi port of Claude Code.s workflow cache-key
+ *
+ * A workflow run that is re-executed (resume after a script edit, or a second
+ * identical run) should NOT pay to re-dispatch agents whose (prompt,
+ * signature) is unchanged. The key captures everything that affects an
+ * agent's output: workflow name (scope), prompt (the task), and a normalized
+ * signature (model/tools/systemPrompt). runId is deliberately excluded —
+ * resume changes the runId but must still hit the cache.
+ *
+ * Normalization (CC.s signature normalizer): drop functions, sort object keys, so the same
+ * logical signature produces the same JSON regardless of field declaration
+ * order or attached closures. sha256 makes the key opaque and fixed-length.
+ */
+import { createHash } from "node:crypto";
+import type { CacheKey } from "../types.ts";
+
+/**
+ * The subset of agent options that affect output and therefore belong in the
+ * key. Caller constructs this explicitly so callId/signal/cwd (run-time
+ * control, not output semantics) never leak into the key by accident.
+ */
+export interface AgentCacheSignature {
+	readonly model?: string;
+	readonly tools?: readonly string[];
+	readonly systemPrompt?: string;
+}
+
+/**
+ * Serialize a signature to a stable canonical form: object keys sorted, no
+ * functions, arrays in order. Same signature → identical string.
+ *
+ * Picks only the known data fields (model/tools/systemPrompt) — CC.s signature normalizer
+ * pattern. A caller may pass a wider object (e.g. an AgentCallSpec that also
+ * carries a `prompt` function); picking avoids both hashing the prompt
+ * (which is a separate cache-key dimension) and tripping the function-guard
+ * on the prompt closure.
+ */
+const SIGNATURE_FIELDS = ["model", "tools", "systemPrompt"] as const;
+
+export function normalizeSignature(signature: AgentCacheSignature | undefined): string {
+	if (!signature) return "{}";
+	const src = signature as Record<string, unknown>;
+	const picked: Record<string, unknown> = {};
+	for (const f of SIGNATURE_FIELDS) {
+		const v = src[f];
+		if (v !== undefined) picked[f] = v;
+	}
+	return JSON.stringify(stabilize(picked));
+}
+
+function stabilize(value: unknown): unknown {
+	if (typeof value === "function") {
+		// Functions are not stable across runs (closures capture mutable scope),
+		// so silently dropping them would let two signatures that differ only in a
+		// function field hash identically → resume returns a result computed under
+		// function A to a caller that supplied function B. Throw instead — a
+		// determinism subsystem must not accept un-hashable inputs.
+		throw new Error(
+			"workflow signature contains a function — functions are not stable across runs; pass only data (string/number/array/plain object)",
+		);
+	}
+	if (Array.isArray(value)) return value.map(stabilize);
+	if (value !== null && typeof value === "object") {
+		const out: Record<string, unknown> = {};
+		const src = value as Record<string, unknown>;
+		for (const key of Object.keys(src).sort()) out[key] = stabilize(src[key]);
+		return out;
+	}
+	return value;
+}
+
+export interface CacheKeyInput {
+	readonly workflowName: string;
+	readonly prompt: string;
+	readonly signature?: AgentCacheSignature;
+}
+
+/** Cache-key namespace prefix. Bump it (wf3 → wf4 → …) whenever the key
+ *  derivation OR the engine's prompt-affecting behavior changes — old journal
+ *  entries then cleanly miss instead of being replayed as stale results (the
+ *  entries stay on disk but are never looked up). Derivation history:
+ *  `wf:` — initial; `wf2:` — B1+B2 base system prompt joined into the key;
+ *  `wf3:` — JSON-tuple encoding; `wf4:` — current revision. */
+export const CACHE_KEY_PREFIX = "wf4";
+
+/** Compute the deterministic cache key for one agent call.
+ *  The tuple is JSON-encoded so field boundaries are unambiguous: a `\x00`
+ *  (or any char) inside workflowName/prompt cannot shift the parse and collide
+ *  with another (name, prompt) pair. Production paths sanitize these inputs,
+ *  but this is a self-defending public function. */
+export function computeCacheKey(input: CacheKeyInput): CacheKey {
+	const hash = createHash("sha256");
+	const blob = JSON.stringify([input.workflowName, input.prompt, normalizeSignature(input.signature)]);
+	hash.update(blob);
+	return `${CACHE_KEY_PREFIX}:${hash.digest("hex")}`;
+}