@tangle-network/agent-runtime 0.116.0 → 0.119.0

package/dist/spawn-journal-IeXpidO2.js

@@ -0,0 +1,857 @@
+import { u as ValidationError } from "./errors-DEAvWQPy.js";
+import { f as zeroTokenUsage } from "./util-MVgdwuIS.js";
+import { isToolSpan, toolSpansToTraceAnalysisStore } from "@tangle-network/agent-eval";
+import { createHash } from "node:crypto";
+//#region src/runtime/supervise/snapshot.ts
+/** Deeply detach and freeze untrusted data at a runtime decision boundary. The clone prevents the
+* caller from mutating it later; the freeze prevents downstream code from mutating the snapshot. */
+function detachedSnapshot(value, context) {
+	try {
+		return deepFreeze(structuredClone(value));
+	} catch (error) {
+		throw new ValidationError(`${context}: input must be structured-cloneable`, { cause: error });
+	}
+}
+function deepFreeze(value, seen = /* @__PURE__ */ new Set()) {
+	if (value === null || typeof value !== "object" || seen.has(value)) return value;
+	seen.add(value);
+	for (const child of Object.values(value)) deepFreeze(child, seen);
+	return Object.freeze(value);
+}
+//#endregion
+//#region src/durable/content-address.ts
+/** Stable content address shared by result and trace artifacts. */
+function contentAddress(artifact) {
+	return `sha256:${createHash("sha256").update(stableStringify(artifact), "utf-8").digest("hex")}`;
+}
+function stableStringify(value) {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	return `{${Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+}
+//#endregion
+//#region src/runtime/supervise/trace-evidence.ts
+/**
+* Durable structured tool evidence for supervised workers.
+*
+* The executor-owned `TraceSource` is collected before teardown, snapshotted into the shared
+* content-addressed blob store, and only then referenced by a settlement. Analysis reconstructs
+* agent-eval's bounded `TraceAnalysisStore` from those exact bytes. Worker output is never accepted
+* as a substitute for tool evidence.
+*
+* @experimental
+*/
+/** Schema version for content-addressed worker tool-trace artifacts. */
+const WORKER_TOOL_TRACE_SCHEMA_VERSION = 1;
+/** Structural guard for the official bounded trace-analysis read contract. */
+function isTraceAnalysisStore(value) {
+	if (value === null || typeof value !== "object") return false;
+	const store = value;
+	return typeof store.getOverview === "function" && typeof store.queryTraces === "function" && typeof store.countTraces === "function" && typeof store.viewTrace === "function" && typeof store.viewSpans === "function" && typeof store.searchTrace === "function" && typeof store.searchSpan === "function";
+}
+/** Collect and persist one executor's structured tool trace without changing its task outcome. */
+async function captureWorkerTraceEvidence(readSource, blobs, executed) {
+	if (!executed) return unavailable("execution-did-not-start");
+	if (readSource === void 0) return unavailable("executor-did-not-expose-trace-source");
+	let source;
+	try {
+		source = readSource();
+	} catch {
+		return unavailable("trace-source-unavailable");
+	}
+	if (source === void 0) return unavailable("trace-source-unavailable");
+	let collected;
+	try {
+		collected = await source.collect();
+	} catch {
+		return unavailable("trace-collection-failed");
+	}
+	if (!Array.isArray(collected) || collected.some((span) => !isToolSpanValue(span))) return unavailable("invalid-tool-spans");
+	if (collected.length === 0) return unavailable("no-tool-spans-captured");
+	let artifact;
+	let traceRef;
+	try {
+		const snapshot = structuredClone(collected);
+		toolSpansToTraceAnalysisStore(snapshot);
+		artifact = {
+			schemaVersion: 1,
+			spans: snapshot
+		};
+		traceRef = contentAddress(artifact);
+	} catch {
+		return unavailable("invalid-tool-spans");
+	}
+	try {
+		await blobs.put(traceRef, artifact);
+	} catch {
+		return unavailable("trace-persistence-failed");
+	}
+	return Object.freeze({
+		status: "available",
+		traceRef,
+		spanCount: artifact.spans.length
+	});
+}
+/** Rehydrate exact persisted spans through agent-eval's one bounded trace-analysis adapter. */
+async function workerTraceAnalysisStore(evidence, blobs) {
+	if (evidence.status === "unavailable") return toolSpansToTraceAnalysisStore(void 0);
+	const raw = await blobs.get(evidence.traceRef);
+	if (raw === void 0) throw new ValidationError(`worker trace blob '${evidence.traceRef}' is missing; the settlement evidence is incomplete`);
+	const artifact = parseWorkerToolTraceArtifact(raw, evidence.traceRef);
+	if (artifact.spans.length !== evidence.spanCount) throw new ValidationError(`worker trace blob '${evidence.traceRef}' has ${artifact.spans.length} spans but its settlement records ${evidence.spanCount}`);
+	return toolSpansToTraceAnalysisStore(artifact.spans);
+}
+/** Validate a stored trace artifact before an analyst or replay trusts it. */
+function parseWorkerToolTraceArtifact(value, traceRef = "<unknown>") {
+	if (value === null || typeof value !== "object" || value.schemaVersion !== 1 || !Array.isArray(value.spans)) throw new ValidationError(`worker trace blob '${traceRef}' is not a version-1 tool trace artifact`);
+	const spans = value.spans;
+	if (spans.length === 0) return {
+		schemaVersion: 1,
+		spans
+	};
+	if (spans.some((span) => !isToolSpanValue(span))) throw new ValidationError(`worker trace blob '${traceRef}' contains a non-tool span`);
+	return {
+		schemaVersion: 1,
+		spans
+	};
+}
+function unavailable(reason) {
+	return Object.freeze({
+		status: "unavailable",
+		reason
+	});
+}
+function isToolSpanValue(value) {
+	try {
+		return isToolSpan(value);
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/runtime/supervise/tree-key.ts
+/** Runtime tag used only for a child that owns another supervised scope. */
+const driverRuntime = "driver";
+const nestedDriverTreeOwners = /* @__PURE__ */ new WeakSet();
+/** Canonical journal key for the scope owned by one nested driver node. */
+function nestedDriverTreeRoot(parentTreeRoot, driverNodeId) {
+	return `${parentTreeRoot}/${driverNodeId}`;
+}
+/** Privately mark the exact recursive executor that will create a nested journal tree. */
+function attestNestedDriverTreeOwner(owner) {
+	nestedDriverTreeOwners.add(owner);
+	return owner;
+}
+/** Return the canonical owned tree only for an exact privately marked recursive executor. */
+function runtimeOwnedNestedDriverTreeRoot(owner, parentTreeRoot, driverNodeId) {
+	return nestedDriverTreeOwners.has(owner) ? nestedDriverTreeRoot(parentTreeRoot, driverNodeId) : void 0;
+}
+//#endregion
+//#region src/durable/jsonl-file.ts
+/** Parse an append-only JSONL file without treating a torn final write as committed data.
+* A malformed newline-terminated or non-final record is corruption and fails loud. */
+function parseCommittedJsonLines(text, source) {
+	const lines = text.split("\n");
+	const finalIndex = lines.length - 1;
+	const records = [];
+	for (const [index, line] of lines.entries()) {
+		if (line.length === 0) continue;
+		try {
+			records.push(JSON.parse(line));
+		} catch (cause) {
+			if (index === finalIndex && !text.endsWith("\n")) break;
+			throw new Error(`${source}: malformed JSONL record at line ${index + 1}`, { cause });
+		}
+	}
+	return records;
+}
+/** FileHandle.write may legally make a short write. Loop until every byte is appended. */
+async function writeAllBytes(handle, value) {
+	const bytes = typeof value === "string" ? Buffer.from(value) : Buffer.from(value);
+	let offset = 0;
+	while (offset < bytes.byteLength) {
+		const { bytesWritten } = await handle.write(bytes, offset, bytes.byteLength - offset, null);
+		if (bytesWritten <= 0) throw new Error(`append-only file write made no progress at byte ${offset}`);
+		offset += bytesWritten;
+	}
+}
+/** Prepare a recovered JSONL file for its next append. A valid unterminated final value is retained
+* and needs a separator; an invalid unterminated tail was never committed and is truncated. */
+async function prepareJsonlAppend(path) {
+	const fs = await import("node:fs/promises");
+	let bytes;
+	try {
+		bytes = await fs.readFile(path);
+	} catch (error) {
+		if (isNoEntError$1(error)) return false;
+		throw error;
+	}
+	if (bytes.byteLength === 0 || bytes[bytes.byteLength - 1] === 10) return false;
+	const lastNewline = bytes.lastIndexOf(10);
+	const tail = bytes.subarray(lastNewline + 1).toString("utf8");
+	try {
+		JSON.parse(tail);
+		return true;
+	} catch {
+		await fs.truncate(path, lastNewline + 1);
+		return false;
+	}
+}
+function isNoEntError$1(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+//#region src/durable/spawn-journal.ts
+/**
+*
+* Event-sourced spawn journal for the recursive execution atom (build steps 3 + 7).
+*
+* The supervision tree is journaled as an append-only event log: every `spawned`,
+* `settled`, and `cancelled` is recorded AFTER it is observed-committed (never
+* speculative), mirroring `ConversationJournal`'s begin/append/load shape. The log
+* holds only the THIN decision record — ids, parentage, budget, the spend a decision
+* consumed, and a content-addressed `outRef`. The payloads the driver branched on
+* (the `out` artifacts) live in a separate `ResultBlobStore`, keyed by `outRef`, so
+* the journal stays small (decisions) and replay rehydrates the exact `Settled` from
+* the blob store (evidence). This is the decision/payload split the replay argument
+* rests on (B1/B2).
+*
+* Replay determinism (B2): `seq` is the monotonic cursor order `scope.next()` yielded
+* each settlement — NOT wall-clock. `replaySpawnTree` sorts strictly by `seq` before
+* touching the blob store, so the order in which rehydration `get`s resolve can never
+* reorder the replayed `Settled[]`; the result is identical regardless of blob latency.
+*
+* @experimental
+*/
+/**
+* Mint the content-addressed `outRef` for a result artifact: `sha256:<hex>` over a
+* stable JSON encoding. Producers call this to derive the `outRef` they journal and
+* `put`; the FS/in-mem stores re-derive it on `put` to verify the supplied ref
+* matches (fail loud on a mismatch — a forged ref breaks the replay invariant).
+*
+* Stable encoding: object keys are sorted recursively so two structurally-equal
+* artifacts hash identically regardless of key insertion order.
+*/
+/**
+* In-memory `ResultBlobStore`. Content-addressed: `put` verifies the supplied
+* `outRef` matches the artifact's hash so a stale/forged ref fails loud rather than
+* silently rehydrating the wrong payload. Idempotent on an identical re-put.
+*/
+var InMemoryResultBlobStore = class {
+	blobs = /* @__PURE__ */ new Map();
+	async put(outRef, artifact) {
+		assertContentAddress(outRef, artifact);
+		this.blobs.set(outRef, artifact);
+	}
+	async get(outRef) {
+		return this.blobs.has(outRef) ? this.blobs.get(outRef) : void 0;
+	}
+};
+/**
+* FS `ResultBlobStore`. One JSON file per artifact under `dir`, named by a
+* filesystem-safe encoding of the `outRef` (`sha256:<hex>` → `sha256-<hex>.json`).
+* `put` fsyncs so a crash between writes never loses an acknowledged blob.
+*/
+var FileResultBlobStore = class {
+	dir;
+	constructor(dir) {
+		this.dir = dir;
+	}
+	async put(outRef, artifact) {
+		assertContentAddress(outRef, artifact);
+		const fs = await import("node:fs/promises");
+		await fs.mkdir(this.dir, { recursive: true });
+		const fh = await fs.open(this.blobPath(outRef), "w");
+		try {
+			await fh.write(JSON.stringify(artifact));
+			await fh.sync();
+		} finally {
+			await fh.close();
+		}
+	}
+	async get(outRef) {
+		const fs = await import("node:fs/promises");
+		let text;
+		try {
+			text = await fs.readFile(this.blobPath(outRef), "utf8");
+		} catch (err) {
+			if (isNoEntError(err)) return void 0;
+			throw err;
+		}
+		return JSON.parse(text);
+	}
+	blobPath(outRef) {
+		return `${this.dir}/${outRef.replace(/:/g, "-")}.json`;
+	}
+};
+function assertContentAddress(outRef, artifact) {
+	const expected = contentAddress(artifact);
+	if (outRef !== expected) throw new Error(`blob outRef '${outRef}' does not match the artifact content hash '${expected}'; a content-addressed store refuses a mismatched ref (breaks the replay invariant)`);
+}
+/**
+* In-memory `SpawnJournal`. Appends are observed-committed only; the impl enforces
+* the corruption guards a durable replay rests on:
+*  - an event before `beginTree` is a corrupted tree (fail loud),
+*  - a duplicate `seq` within a tree is a corrupted cursor (fail loud) — two
+*    settlements cannot share the cursor position replay orders by.
+*/
+var InMemorySpawnJournal = class {
+	trees = /* @__PURE__ */ new Map();
+	async loadTree(root) {
+		const tree = this.trees.get(root);
+		if (!tree) return void 0;
+		return tree.events.map((ev) => ({ ...ev }));
+	}
+	async beginTree(root, at) {
+		const existing = this.trees.get(root);
+		if (existing) {
+			if (existing.begunAt !== at) throw new Error(`spawn tree '${root}' already begun at ${existing.begunAt}; refusing to overwrite with ${at}`);
+			return;
+		}
+		this.trees.set(root, {
+			begunAt: at,
+			events: []
+		});
+	}
+	async appendEvent(root, ev) {
+		const tree = this.trees.get(root);
+		if (!tree) throw new Error(`appendEvent called for unknown spawn tree '${root}'; call beginTree first`);
+		assertSeqUnique(root, tree.events, ev);
+		tree.events.push({ ...ev });
+	}
+};
+/**
+* JSONL on disk. One line per record: the first record is `begin`, subsequent records
+* are `event` envelopes wrapping a `SpawnEvent`. `loadTree` replays the whole file,
+* filtering by `root`, and applies the same begin-precedes-events + unique-seq
+* corruption guards as the in-memory impl. Each append fsyncs so a crash between
+* writes never loses an acknowledged event.
+*/
+var FileSpawnJournal = class {
+	path;
+	appendTail = Promise.resolve();
+	constructor(path) {
+		this.path = path;
+	}
+	async loadTree(root) {
+		const fs = await import("node:fs/promises");
+		let text;
+		try {
+			text = await fs.readFile(this.path, "utf8");
+		} catch (err) {
+			if (isNoEntError(err)) return void 0;
+			throw err;
+		}
+		let begun = false;
+		const events = [];
+		for (const record of parseCommittedJsonLines(text, this.path)) {
+			if (record.root !== root) continue;
+			if (record.kind === "begin") begun = true;
+			else {
+				if (!begun) throw new Error(`spawn journal corrupted: event for tree '${root}' precedes its begin record`);
+				assertSeqUnique(root, events, record.event);
+				events.push(record.event);
+			}
+		}
+		return begun ? events : void 0;
+	}
+	async beginTree(root, at) {
+		const existing = await this.loadTreeBegin(root);
+		if (existing) {
+			if (existing !== at) throw new Error(`spawn tree '${root}' already begun in ${this.path} at ${existing}; refusing to overwrite with ${at}`);
+			return;
+		}
+		await this.appendRecord({
+			kind: "begin",
+			root,
+			at
+		});
+	}
+	async appendEvent(root, ev) {
+		const events = await this.loadTree(root);
+		if (events === void 0) throw new Error(`appendEvent called for unknown spawn tree '${root}'; call beginTree first`);
+		assertSeqUnique(root, events, ev);
+		await this.appendRecord({
+			kind: "event",
+			root,
+			event: ev
+		});
+	}
+	async loadTreeBegin(root) {
+		const fs = await import("node:fs/promises");
+		let text;
+		try {
+			text = await fs.readFile(this.path, "utf8");
+		} catch (err) {
+			if (isNoEntError(err)) return void 0;
+			throw err;
+		}
+		for (const record of parseCommittedJsonLines(text, this.path)) if (record.root === root && record.kind === "begin") return record.at;
+	}
+	async appendRecord(record) {
+		const append = this.appendTail.then(() => this.writeRecord(record));
+		this.appendTail = append.catch(() => void 0);
+		return append;
+	}
+	async writeRecord(record) {
+		const fs = await import("node:fs/promises");
+		const path = await import("node:path");
+		await fs.mkdir(path.dirname(this.path), { recursive: true });
+		const needsSeparator = await prepareJsonlAppend(this.path);
+		const fh = await fs.open(this.path, "a");
+		try {
+			await writeAllBytes(fh, `${needsSeparator ? "\n" : ""}${JSON.stringify(record)}\n`);
+			await fh.sync();
+		} finally {
+			await fh.close();
+		}
+	}
+};
+/**
+* Load every journal tree owned by one recursive supervision run and flatten its nodes/events.
+*
+* Nested driver tree keys are a Runtime implementation detail; callers should use this reader
+* instead of deriving or scanning keys themselves. The reader follows only the explicit
+* `ownedTreeRoot` written after Runtime privately attested a recursive executor; the open runtime
+* string `driver` is never treated as ownership. Legacy records without `ownedTreeRoot` are
+* intentionally treated as leaves rather than guessing or scanning convention-derived keys.
+* This preserves each tree's independent cursor namespace on flattened events.
+* A driver whose subtree was never begun is reported in `missingTrees`; any spawned non-root node
+* without a terminal record is reported in `inDoubt`, matching resume's conservative lost-work
+* interpretation.
+*
+* This is a cold/quiescent reader, not a transaction across an actively mutating file. Every value
+* returned is a detached immutable snapshot, so later journal writes or caller mutation cannot
+* change the result already observed.
+*/
+async function loadSpawnForest(journal, root) {
+	const rootEvents = await journal.loadTree(root);
+	if (rootEvents === void 0) throw new Error(`loadSpawnForest: no journaled tree for root '${root}'`);
+	const trees = [];
+	const nodes = [];
+	const events = [];
+	const inDoubt = [];
+	const missingTrees = [];
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [{
+		root,
+		events: rootEvents
+	}];
+	for (let cursor = 0; cursor < queue.length; cursor += 1) {
+		const current = queue[cursor];
+		if (visited.has(current.root)) throw new Error(`loadSpawnForest: recursive journal tree '${current.root}' was reached twice`);
+		visited.add(current.root);
+		const stableEvents = detachedSnapshot(current.events, `loadSpawnForest tree ${JSON.stringify(current.root)}`);
+		const view = detachedSnapshot(materializeTreeView([...stableEvents]), `loadSpawnForest view ${JSON.stringify(current.root)}`);
+		trees.push({
+			root: current.root,
+			...current.ownerNodeId === void 0 ? {} : { ownerNodeId: current.ownerNodeId },
+			...current.parentTreeRoot === void 0 ? {} : { parentTreeRoot: current.parentTreeRoot },
+			events: stableEvents,
+			view
+		});
+		nodes.push(...view.nodes.map((node) => ({
+			treeRoot: current.root,
+			...node
+		})));
+		events.push(...stableEvents.map((event) => ({
+			treeRoot: current.root,
+			event
+		})));
+		const terminal = /* @__PURE__ */ new Set();
+		for (const event of stableEvents) if (event.kind === "settled" || event.kind === "cancelled") terminal.add(event.id);
+		const spawns = stableEvents.filter((event) => event.kind === "spawned").sort((a, b) => a.seq - b.seq || a.id.localeCompare(b.id));
+		for (const spawn of spawns) {
+			if (spawn.parent !== void 0 && !terminal.has(spawn.id)) inDoubt.push({
+				treeRoot: current.root,
+				nodeId: spawn.id,
+				label: spawn.label,
+				runtime: spawn.runtime
+			});
+			if (spawn.ownedTreeRoot === void 0) continue;
+			const expectedRoot = nestedDriverTreeRoot(current.root, spawn.id);
+			if (spawn.ownedTreeRoot !== expectedRoot) throw new Error(`loadSpawnForest: node '${spawn.id}' owns non-canonical tree '${spawn.ownedTreeRoot}'; expected '${expectedRoot}'`);
+			const nestedRoot = spawn.ownedTreeRoot;
+			const nestedEvents = await journal.loadTree(nestedRoot);
+			if (nestedEvents === void 0) {
+				missingTrees.push({
+					parentTreeRoot: current.root,
+					ownerNodeId: spawn.id,
+					root: nestedRoot
+				});
+				continue;
+			}
+			queue.push({
+				root: nestedRoot,
+				events: nestedEvents,
+				ownerNodeId: spawn.id,
+				parentTreeRoot: current.root
+			});
+		}
+	}
+	return detachedSnapshot({
+		root,
+		trees,
+		nodes,
+		events,
+		inDoubt,
+		missingTrees
+	}, "loadSpawnForest result");
+}
+/**
+* Two `seq` namespaces share the journal: a `spawned` event's `seq` is the spawn ordinal
+* (the order children were created), and a `settled`/`cancelled` event's `seq` is the
+* monotonic CURSOR order `scope.next()` yielded that settlement (B2). The uniqueness
+* replay rests on is the cursor namespace — two settlements cannot share the position
+* replay orders by — so the guard checks only settled/cancelled events. A `spawned`
+* ordinal legitimately equals a later `settled` cursor seq and is not a collision.
+*/
+function assertSeqUnique(root, events, ev) {
+	if (ev.kind === "materialized") {
+		if (events.some((event) => event.kind === "materialized" && event.id === ev.id)) throw new Error(`spawn journal corrupted: duplicate materialization receipt for node '${ev.id}' in tree '${root}'`);
+		if (!events.some((event) => event.kind === "spawned" && event.id === ev.id)) throw new Error(`spawn journal corrupted: materialization for node '${ev.id}' precedes its spawn in tree '${root}'`);
+	}
+	if (ev.kind === "execution-bound") {
+		if (events.some((event) => event.kind === "execution-bound" && event.id === ev.id && event.binding.attemptId === ev.binding.attemptId)) throw new Error(`spawn journal corrupted: duplicate execution binding for node '${ev.id}' attempt '${ev.binding.attemptId}' in tree '${root}'`);
+		if (!events.some((event) => event.kind === "materialized" && event.id === ev.id)) throw new Error(`spawn journal corrupted: execution binding for node '${ev.id}' precedes materialization in tree '${root}'`);
+	}
+	if (outsideCursorNamespace(ev)) return;
+	if (events.some((e) => !outsideCursorNamespace(e) && e.seq === ev.seq)) throw new Error(`spawn journal corrupted: duplicate cursor seq ${ev.seq} in tree '${root}'; the cursor order replay relies on is not unique`);
+}
+/** Node-CREATION and informational records — outside the cursor namespace whose uniqueness replay
+*  ordering rests on. The single predicate both the guard's sides read, so a new event kind is
+*  classified once. */
+function outsideCursorNamespace(ev) {
+	return ev.kind === "spawned" || ev.kind === "waiting" || ev.kind === "metered" || ev.kind === "materialized" || ev.kind === "execution-bound";
+}
+/**
+* Re-feed a journaled spawn tree in strict `seq` order, rehydrating each settled
+* child's `out` from the blob store by `outRef`, and return the `Settled[]` exactly
+* as `scope.next()` originally delivered them.
+*
+* Determinism (B2): the events are sorted by `seq` BEFORE any blob `get`, so the
+* replay order is the recorded cursor order regardless of how fast each rehydration
+* resolves. `at` (wall-clock) is never a replay input. Fail loud on a tree that was
+* never begun, a settled-done event missing its `outRef`, or a blob the store can't
+* rehydrate — a silent gap would let `act` branch on the wrong evidence.
+*/
+async function replaySpawnTree(journal, blobs, root) {
+	const events = await journal.loadTree(root);
+	if (events === void 0) throw new Error(`replaySpawnTree: no journaled tree for root '${root}'`);
+	const ordered = [...events].sort((a, b) => a.seq - b.seq);
+	const labels = /* @__PURE__ */ new Map();
+	const assignmentIds = /* @__PURE__ */ new Map();
+	const identities = /* @__PURE__ */ new Map();
+	const materializations = /* @__PURE__ */ new Map();
+	const executionBindings = /* @__PURE__ */ new Map();
+	for (const ev of ordered) {
+		if (ev.kind === "spawned" || ev.kind === "waiting") labels.set(ev.id, ev.label);
+		if (ev.kind === "spawned" && ev.assignmentId !== void 0) assignmentIds.set(ev.id, ev.assignmentId);
+		if (ev.kind === "spawned" && ev.identity !== void 0) identities.set(ev.id, copyFrozenIdentity(ev.identity));
+		if (ev.kind === "materialized") materializations.set(ev.id, ev.receipt);
+		if (ev.kind === "execution-bound") {
+			const bindings = executionBindings.get(ev.id) ?? [];
+			bindings.push(ev.binding);
+			executionBindings.set(ev.id, bindings);
+		}
+	}
+	const handleFor = (id, status) => replayHandle(id, labels.get(id) ?? id, status, {
+		assignmentId: assignmentIds.get(id),
+		identity: identities.get(id),
+		materialization: materializations.get(id),
+		executionBindings: executionBindings.get(id)
+	});
+	const settlementTime = (at) => {
+		const settledAt = Date.parse(at);
+		return Number.isFinite(settledAt) ? { settledAt } : {};
+	};
+	const settled = [];
+	for (const ev of ordered) {
+		if (ev.kind === "spawned") continue;
+		if (ev.kind === "waiting") continue;
+		if (ev.kind === "metered") continue;
+		if (ev.kind === "materialized") continue;
+		if (ev.kind === "execution-bound") continue;
+		if (ev.kind === "woken") {
+			if (ev.by === "cancelled" || ev.outRef === void 0) {
+				settled.push({
+					kind: "down",
+					handle: handleFor(ev.id, "cancelled"),
+					reason: "wait cancelled",
+					infra: false,
+					restartCount: 0,
+					trace: {
+						status: "unavailable",
+						reason: "not-an-executor"
+					},
+					...settlementTime(ev.at),
+					seq: ev.seq
+				});
+				continue;
+			}
+			const outcome = await blobs.get(ev.outRef);
+			if (outcome === void 0) throw new Error(`replaySpawnTree: blob store has no wait outcome for outRef '${ev.outRef}' (node '${ev.id}', seq ${ev.seq})`);
+			settled.push({
+				kind: "done",
+				handle: handleFor(ev.id, "done"),
+				out: outcome,
+				outRef: ev.outRef,
+				spent: zeroSpend(),
+				trace: {
+					status: "unavailable",
+					reason: "not-an-executor"
+				},
+				...settlementTime(ev.at),
+				seq: ev.seq
+			});
+			continue;
+		}
+		if (ev.kind === "cancelled") {
+			settled.push({
+				kind: "down",
+				handle: handleFor(ev.id, "cancelled"),
+				reason: ev.reason,
+				infra: false,
+				restartCount: 0,
+				trace: {
+					status: "unavailable",
+					reason: "execution-did-not-start"
+				},
+				...settlementTime(ev.at),
+				seq: ev.seq
+			});
+			continue;
+		}
+		if (ev.status === "down") {
+			const trace = traceEvidenceFor(ev);
+			if (trace.status === "available") await workerTraceAnalysisStore(trace, blobs);
+			settled.push({
+				kind: "down",
+				handle: handleFor(ev.id, "failed"),
+				reason: ev.reason ?? ev.verdict?.notes ?? "child down",
+				infra: ev.infra === true,
+				restartCount: 0,
+				trace,
+				...settlementTime(ev.at),
+				seq: ev.seq
+			});
+			continue;
+		}
+		if (ev.outRef === void 0) throw new Error(`replaySpawnTree: settled-done event for '${ev.id}' (seq ${ev.seq}) has no outRef; cannot rehydrate the result the driver branched on`);
+		const out = await blobs.get(ev.outRef);
+		if (out === void 0) throw new Error(`replaySpawnTree: blob store has no artifact for outRef '${ev.outRef}' (node '${ev.id}', seq ${ev.seq})`);
+		const trace = traceEvidenceFor(ev);
+		if (trace.status === "available") await workerTraceAnalysisStore(trace, blobs);
+		settled.push({
+			kind: "done",
+			handle: handleFor(ev.id, "done"),
+			out,
+			outRef: ev.outRef,
+			verdict: ev.verdict,
+			spent: ev.spent,
+			trace,
+			...settlementTime(ev.at),
+			seq: ev.seq
+		});
+	}
+	return settled;
+}
+function replayHandle(id, label, status, evidence = {}) {
+	return Object.freeze({
+		id,
+		label,
+		status,
+		...evidence.assignmentId === void 0 ? {} : { assignmentId: evidence.assignmentId },
+		...evidence.identity === void 0 ? {} : { identity: evidence.identity },
+		...evidence.materialization === void 0 ? {} : { materialization: evidence.materialization },
+		...evidence.executionBindings === void 0 ? {} : { executionBindings: Object.freeze([...evidence.executionBindings]) },
+		abort() {
+			throw new Error(`cannot abort node '${id}': replayed handles are terminal, not live`);
+		}
+	});
+}
+/** A replayed handle must not retain mutable references into the loaded journal event. */
+function copyFrozenIdentity(identity) {
+	const correlation = identity.correlation === void 0 ? void 0 : Object.freeze({ ...identity.correlation });
+	return Object.freeze({
+		...identity.profileDigest === void 0 ? {} : { profileDigest: identity.profileDigest },
+		...identity.taskDigest === void 0 ? {} : { taskDigest: identity.taskDigest },
+		...identity.candidateDigest === void 0 ? {} : { candidateDigest: identity.candidateDigest },
+		...correlation === void 0 ? {} : { correlation }
+	});
+}
+/**
+* Materialize a recorded `TreeView` from a journaled event list for inspection. Folds
+* `spawned`/`settled`/`cancelled` into a per-node snapshot in `seq` order, then adds each
+* `metered` event's driver-inference spend onto its node in a separate additive pass so the view
+* matches the recorded cursor. It does not recover live executors or driver state after restart.
+*/
+function materializeTreeView(events) {
+	const nodes = /* @__PURE__ */ new Map();
+	let root;
+	const spawns = events.filter((ev) => ev.kind === "spawned" || ev.kind === "waiting").sort((a, b) => a.seq - b.seq);
+	const settlements = events.filter((ev) => ev.kind !== "spawned" && ev.kind !== "waiting" && ev.kind !== "metered" && ev.kind !== "materialized" && ev.kind !== "execution-bound").sort((a, b) => a.seq - b.seq);
+	for (const ev of spawns) {
+		if (ev.kind === "waiting") {
+			nodes.set(ev.id, {
+				id: ev.id,
+				parent: ev.parent,
+				label: ev.label,
+				status: "waiting",
+				runtime: "wait",
+				budget: {
+					maxIterations: 0,
+					maxTokens: 0
+				},
+				spent: zeroSpend()
+			});
+			continue;
+		}
+		if (ev.parent === void 0 && root === void 0) root = ev.id;
+		nodes.set(ev.id, {
+			id: ev.id,
+			parent: ev.parent,
+			label: ev.label,
+			status: "pending",
+			runtime: ev.runtime,
+			budget: ev.budget,
+			...ev.ownedTreeRoot === void 0 ? {} : { ownedTreeRoot: ev.ownedTreeRoot },
+			...ev.assignmentId === void 0 ? {} : { assignmentId: ev.assignmentId },
+			...ev.identity ? { identity: ev.identity } : {},
+			spent: zeroSpend()
+		});
+	}
+	for (const ev of settlements) if (ev.kind === "settled") {
+		const node = requireNode(nodes, ev.id);
+		node.status = ev.status === "done" ? "done" : "failed";
+		node.spent = ev.spent;
+		node.outRef = ev.outRef;
+		node.trace = traceEvidenceFor(ev);
+		const settledAt = Date.parse(ev.at);
+		if (Number.isFinite(settledAt)) node.settledAt = settledAt;
+	} else if (ev.kind === "woken") {
+		const node = requireNode(nodes, ev.id);
+		node.status = ev.by === "cancelled" ? "cancelled" : "done";
+		node.outRef = ev.outRef;
+		node.trace = {
+			status: "unavailable",
+			reason: "not-an-executor"
+		};
+		const settledAt = Date.parse(ev.at);
+		if (Number.isFinite(settledAt)) node.settledAt = settledAt;
+	} else {
+		const node = requireNode(nodes, ev.id);
+		node.status = "cancelled";
+		node.trace = {
+			status: "unavailable",
+			reason: "execution-did-not-start"
+		};
+		const settledAt = Date.parse(ev.at);
+		if (Number.isFinite(settledAt)) node.settledAt = settledAt;
+	}
+	for (const ev of events) {
+		if (ev.kind !== "materialized") continue;
+		const node = requireNode(nodes, ev.id);
+		node.materialization = ev.receipt;
+		node.runtime = ev.receipt.runtime;
+	}
+	for (const ev of events) {
+		if (ev.kind !== "execution-bound") continue;
+		const node = requireNode(nodes, ev.id);
+		node.executionBindings ??= [];
+		node.executionBindings.push(ev.binding);
+	}
+	for (const ev of events) {
+		if (ev.kind !== "metered") continue;
+		const node = requireNode(nodes, ev.id);
+		node.spent = addJournalSpend(node.spent, ev.spend);
+	}
+	const snapshots = [...nodes.values()].map(freezeSnapshot);
+	return {
+		root: root ?? snapshots[0]?.id ?? "",
+		nodes: snapshots,
+		inFlight: snapshots.filter((n) => n.status === "running" || n.status === "acquiring").length,
+		waiting: snapshots.filter((n) => n.status === "waiting").length
+	};
+}
+/**
+* The waits a journaled tree shows as ARMED but never woken — what a resumed run re-arms with the
+* ORIGINAL absolute deadline. Reading it from the journal (rather than from any live state) is
+* what makes "SIGKILL a waiting tree, a new process keeps waiting to the same instant" true.
+*/
+function pendingWaits(events) {
+	const woken = /* @__PURE__ */ new Set();
+	for (const ev of events) if (ev.kind === "woken") woken.add(ev.id);
+	const pending = [];
+	for (const ev of events) {
+		if (ev.kind !== "waiting" || woken.has(ev.id)) continue;
+		pending.push({
+			id: ev.id,
+			label: ev.label,
+			spec: ev.spec,
+			armedAt: ev.armedAt,
+			ordinal: ev.seq
+		});
+	}
+	return pending.sort((a, b) => a.ordinal - b.ordinal);
+}
+function zeroSpend() {
+	return {
+		iterations: 0,
+		tokens: zeroTokenUsage(),
+		usd: 0,
+		ms: 0
+	};
+}
+/** Add a `metered` spend record onto a node's accumulated spend (per channel). */
+function addJournalSpend(a, b) {
+	return {
+		iterations: a.iterations + b.iterations,
+		tokens: {
+			input: a.tokens.input + b.tokens.input,
+			output: a.tokens.output + b.tokens.output
+		},
+		...a.tokensKnown === false || b.tokensKnown === false ? { tokensKnown: false } : {},
+		usd: a.usd + b.usd,
+		...a.tokensKnown === false || b.tokensKnown === false ? { tokensKnown: false } : {},
+		...a.usdKnown === false || b.usdKnown === false ? { usdKnown: false } : {},
+		ms: a.ms + b.ms
+	};
+}
+function requireNode(nodes, id) {
+	const node = nodes.get(id);
+	if (!node) throw new Error(`spawn journal corrupted: settle/cancel for node '${id}' with no prior spawn`);
+	return node;
+}
+function freezeSnapshot(node) {
+	return {
+		id: node.id,
+		parent: node.parent,
+		label: node.label,
+		status: node.status,
+		runtime: node.runtime,
+		budget: node.budget,
+		ownedTreeRoot: node.ownedTreeRoot,
+		assignmentId: node.assignmentId,
+		identity: node.identity,
+		materialization: node.materialization,
+		executionBindings: node.executionBindings === void 0 ? void 0 : Object.freeze([...node.executionBindings]),
+		spent: node.spent,
+		outRef: node.outRef,
+		trace: node.trace,
+		settledAt: node.settledAt
+	};
+}
+function traceEvidenceFor(event) {
+	return event.trace ?? {
+		status: "unavailable",
+		reason: "legacy-settlement-without-trace-evidence"
+	};
+}
+function isNoEntError(err) {
+	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+//#endregion
+export { detachedSnapshot as S, captureWorkerTraceEvidence as _, loadSpawnForest as a, workerTraceAnalysisStore as b, replaySpawnTree as c, writeAllBytes as d, attestNestedDriverTreeOwner as f, WORKER_TOOL_TRACE_SCHEMA_VERSION as g, runtimeOwnedNestedDriverTreeRoot as h, InMemorySpawnJournal as i, parseCommittedJsonLines as l, nestedDriverTreeRoot as m, FileSpawnJournal as n, materializeTreeView as o, driverRuntime as p, InMemoryResultBlobStore as r, pendingWaits as s, FileResultBlobStore as t, prepareJsonlAppend as u, isTraceAnalysisStore as v, contentAddress as x, parseWorkerToolTraceArtifact as y };
+
+//# sourceMappingURL=spawn-journal-IeXpidO2.js.map