@tangle-network/agent-runtime 0.349.0 → 0.352.1

package/dist/supervision-discovery-CewADdEs.js

@@ -0,0 +1,772 @@
+import { O as runtimeFailureCauseSchema, b as captureRunWriteContext, c as readCommittedJsonLines, i as appendCommittedJsonLine, r as spawnJournalRecordEvents, tt as detachedSnapshot } from "./journal-store-BJPMUydp.js";
+import { a as cloneSpend, n as addSpend, w as zeroSpend } from "./util-ebWMWzY0.js";
+import { a as withPursuitContext } from "./runtime-hooks-CsW2pfFk.js";
+import { isRecord } from "@tangle-network/agent-core";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+// src/durable/observer-journal.ts
+/**
+* Durable, append-only third-person history for one concrete Runtime execution.
+* It consumes Runtime's existing hook stream and does not participate in execution
+* decisions. A broken observer therefore cannot change what an agent is allowed to do.
+*
+* The write discipline deliberately matches `FileSpawnJournal`: serialized appends,
+* torn-tail recovery, short-write handling, and fsync before acknowledgement. One
+* execution owns one journal file; higher-level pursuit aggregation joins isolated
+* journals by `pursuitId` instead of making independent processes share a write head.
+*/
+var FileObserverJournal = class FileObserverJournal {
+	path;
+	pursuitId;
+	writeContext = captureRunWriteContext();
+	tail = Promise.resolve();
+	initialized = false;
+	sequence = 0;
+	previousDigest;
+	appendFailure;
+	constructor(path, pursuitId) {
+		const stableId = pursuitId.trim();
+		if (stableId.length === 0) throw new TypeError("FileObserverJournal: pursuitId must be non-empty");
+		this.path = resolve(path);
+		this.pursuitId = stableId;
+	}
+	/** Open existing committed history by its recorded identity; never creates a file. */
+	static async open(path) {
+		for await (const record of readCommittedJsonLines(path, { allowMissing: true })) {
+			if (typeof record?.pursuitId !== "string") throw new TypeError("observer journal: missing pursuit identity");
+			const journal = new FileObserverJournal(path, record.pursuitId);
+			verifyObserverRecords([record], journal.pursuitId);
+			return journal;
+		}
+	}
+	hooks() {
+		return withPursuitContext(this.pursuitId, {
+			onEvent: (event) => this.appendEvent(event).then(() => void 0),
+			onDecisionPoint: (point) => this.appendDecision(point).then(() => void 0)
+		});
+	}
+	appendEvent(event) {
+		return this.enqueue("event", event);
+	}
+	appendDecision(point) {
+		return this.enqueue("decision", point);
+	}
+	async read() {
+		await this.tail;
+		this.assertComplete();
+		const records = [];
+		const verify = observerVerifier(this.pursuitId);
+		for await (const record of this.readExistingUnsafe()) {
+			verify(record);
+			records.push(record);
+		}
+		return Object.freeze(records);
+	}
+	async enqueue(kind, value) {
+		if (value.pursuitId !== this.pursuitId) throw new Error(`FileObserverJournal: ${kind} pursuitId ${String(value.pursuitId)} does not match ${this.pursuitId}`);
+		const snapshot = detachedSnapshot(value, "observer record");
+		const operation = this.tail.then(() => this.writeContext(async () => {
+			this.assertComplete();
+			await this.initialize();
+			const unsigned = {
+				schemaVersion: 1,
+				pursuitId: this.pursuitId,
+				sequence: this.sequence + 1,
+				kind,
+				observedAt: Date.now(),
+				...this.previousDigest ? { previousDigest: this.previousDigest } : {},
+				...kind === "event" ? { event: snapshot } : { decision: snapshot }
+			};
+			const record = Object.freeze({
+				...unsigned,
+				digest: observerRecordDigest(unsigned)
+			});
+			const fs = await import("node:fs/promises");
+			const { dirname } = await import("node:path");
+			await fs.mkdir(dirname(this.path), { recursive: true });
+			await appendCommittedJsonLine(this.path, record);
+			this.sequence = record.sequence;
+			this.previousDigest = record.digest;
+			return record;
+		})).catch((error) => {
+			this.appendFailure ??= toError(error);
+			throw error;
+		});
+		this.tail = operation.then(() => void 0, () => void 0);
+		return operation;
+	}
+	async initialize() {
+		if (this.initialized) return;
+		const verify = observerVerifier(this.pursuitId);
+		let tail;
+		for await (const record of this.readExistingUnsafe()) {
+			verify(record);
+			tail = record;
+		}
+		this.sequence = tail?.sequence ?? 0;
+		this.previousDigest = tail?.digest;
+		this.initialized = true;
+	}
+	readExistingUnsafe() {
+		return readCommittedJsonLines(this.path, { allowMissing: true });
+	}
+	assertComplete() {
+		if (!this.appendFailure) return;
+		throw new Error("FileObserverJournal: a prior durable append failed; observer completeness is unknown", { cause: this.appendFailure });
+	}
+};
+/** Verify identity, monotonic sequence, payload shape, and the complete digest chain. */
+function verifyObserverRecords(records, pursuitId) {
+	const verify = observerVerifier(pursuitId);
+	for (const record of records) verify(record);
+	return Object.freeze([...records]);
+}
+/** The same full chain validation is used for replay, startup and in-memory evidence. */
+function observerVerifier(pursuitId) {
+	let previousDigest;
+	let expectedSequence = 1;
+	return (record) => {
+		if (record.schemaVersion !== 1) throw new Error("observer journal: unsupported schemaVersion");
+		if (pursuitId !== void 0 && record.pursuitId !== pursuitId) throw new Error(`observer journal: pursuit identity mismatch at sequence ${record.sequence}`);
+		if (record.sequence !== expectedSequence) throw new Error(`observer journal: non-contiguous sequence ${record.sequence}; expected ${expectedSequence}`);
+		if (record.previousDigest !== previousDigest) throw new Error(`observer journal: digest-chain break at sequence ${record.sequence}`);
+		for (const kind of ["event", "decision"]) {
+			const payload = record[kind];
+			if (record.kind === kind === (payload === void 0)) throw new Error(`observer journal: invalid ${kind} payload at sequence ${record.sequence}`);
+			if (payload !== void 0 && payload.pursuitId !== record.pursuitId) throw new Error(`observer journal: nested ${kind} pursuit mismatch at sequence ${record.sequence}`);
+		}
+		const { digest, ...unsigned } = record;
+		if (digest !== observerRecordDigest(unsigned)) throw new Error(`observer journal: digest mismatch at sequence ${record.sequence}`);
+		previousDigest = digest;
+		expectedSequence += 1;
+	};
+}
+/** Compute the canonical SHA-256 digest for an unsigned observer record. */
+function observerRecordDigest(record) {
+	return createHash("sha256").update(JSON.stringify(record)).digest("hex");
+}
+/** Build the canonical durable observer hook in one call. */
+function createFileObserverHooks(path, pursuitId) {
+	const journal = new FileObserverJournal(path, pursuitId);
+	return {
+		journal,
+		hooks: journal.hooks()
+	};
+}
+function toError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+// src/durable/observer-projection.ts
+/**
+* Fold one append-only execution journal into a deterministic operator projection.
+*
+* This is intentionally a READ model, not another state machine: it does not own
+* execution, cannot steer agents, and can be rebuilt from the journal at any time.
+* Projection verifies the complete hash chain first, so an operator view can never
+* silently render a mutated or reordered observer history as trustworthy state.
+*
+* Topology comes only from Runtime's canonical `agent.spawn` facts. Terminal node
+* state comes only from `agent.child`; concrete run state comes only from the root
+* `agent.run` lifecycle emitted by `supervisePursuit`, one row per attempt. Node identity is
+* scoped to the concrete Runtime run so independent trees may both contain `root:s0` without
+* aliasing, and a node belongs to the attempt that spawned it.
+*
+* Usage, cost and timing are reported at the class the runtime measured them at. A missing
+* class stays ABSENT and the run names the node in `spendGaps`; nothing here converts an
+* unmeasured channel into a zero, because a fabricated zero is indistinguishable from free work.
+*/
+function projectPursuit(records) {
+	if (records.length === 0) throw new TypeError("projectPursuit: at least one observer record is required");
+	const pursuitId = records[0].pursuitId;
+	const verified = verifyObserverRecords(records, pursuitId);
+	const attempts = /* @__PURE__ */ new Map();
+	const nodes = /* @__PURE__ */ new Map();
+	let eventCount = 0;
+	let decisionCount = 0;
+	for (const record of verified) {
+		const observed = record.event ?? record.decision;
+		if (!observed) throw new Error(`projectPursuit: record ${record.sequence} has no observation`);
+		const run = currentAttempt(attempts, observed.runId, record);
+		run.lastSequence = record.sequence;
+		run.lastObservedAt = record.observedAt;
+		if (record.event) {
+			eventCount += 1;
+			run.eventCount += 1;
+			increment(run.targets, record.event.target);
+			projectRunActivity(run, record);
+			projectSpawnNode(nodes, record, run.attemptIndex);
+			projectNodeActivity(nodes, record);
+			projectSeat(run, nodes, record);
+			projectTurn(run, nodes, record);
+		} else if (record.decision) {
+			decisionCount += 1;
+			run.decisionCount += 1;
+			increment(run.decisions, record.decision.kind);
+		}
+	}
+	const byAttempt = /* @__PURE__ */ new Map();
+	for (const node of nodes.values()) {
+		const key = attemptKey(node.runId, node.attemptIndex);
+		const list = byAttempt.get(key);
+		if (list) list.push(node);
+		else byAttempt.set(key, [node]);
+	}
+	const first = verified[0];
+	const last = verified.at(-1);
+	return Object.freeze({
+		pursuitId,
+		sequence: last.sequence,
+		chainTip: last.digest,
+		firstObservedAt: first.observedAt,
+		lastObservedAt: last.observedAt,
+		runs: Object.freeze([...attempts.values()].flat().sort((a, b) => a.firstSequence - b.firstSequence || a.runId.localeCompare(b.runId)).map((run) => freezeRun(run, byAttempt.get(attemptKey(run.runId, run.attemptIndex)) ?? []))),
+		nodes: Object.freeze([...nodes.values()].sort((a, b) => a.firstSequence - b.firstSequence || a.runId.localeCompare(b.runId) || a.id.localeCompare(b.id)).map(freezeNode)),
+		eventCount,
+		decisionCount
+	});
+}
+function projectSeat(run, nodes, record) {
+	const event = record.event;
+	if (event?.target !== "agent.seat") return;
+	const payload = objectRecord(event.payload);
+	const phase = stringField(payload, "phase");
+	const owner = nodes.get(nodeKey(event.runId, stringField(payload, "nodeId") ?? "")) ?? run;
+	if (phase === "paused") {
+		const resumeAt = stringField(payload, "resumeAt");
+		if (resumeAt) owner.resumeAt = resumeAt;
+		return;
+	}
+	if (phase === "resumed") {
+		delete owner.resumeAt;
+		return;
+	}
+	const raw = objectRecord(payload?.segment);
+	const seat = stringField(raw, "seat");
+	const harness = stringField(raw, "harness");
+	const provider = stringField(raw, "provider");
+	const model = stringField(raw, "model");
+	const startedAt = stringField(raw, "startedAt");
+	if (!seat || !harness || !provider || !model || !startedAt) return;
+	if (owner.segments === void 0) owner.segments = [];
+	const segments = owner.segments;
+	if (phase === "started") {
+		if (!segments.some((segment) => segment.startedAt === startedAt && segment.seat === seat)) segments.push({
+			seat,
+			harness,
+			provider,
+			model,
+			startedAt
+		});
+	} else if (phase === "ended") {
+		const endedAt = stringField(raw, "endedAt");
+		const reason = stringField(raw, "reason");
+		if (!endedAt || !reason) return;
+		const index = segments.findIndex((segment) => segment.startedAt === startedAt && segment.seat === seat);
+		if (index >= 0) segments[index] = {
+			seat,
+			harness,
+			provider,
+			model,
+			startedAt,
+			endedAt,
+			reason
+		};
+	}
+}
+function attemptKey(runId, attemptIndex) {
+	return `${runId}\u0000${attemptIndex}`;
+}
+/**
+* The attempt a record belongs to. An `agent.run` `before` opens a new attempt when the run has
+* none or its latest attempt already settled; on an open attempt it is a resume. Every other
+* record joins the latest attempt, and a journal that never emitted `before` gets attempt 0.
+*/
+function currentAttempt(attempts, runId, record) {
+	const list = attempts.get(runId) ?? [];
+	if (list.length === 0) attempts.set(runId, list);
+	const latest = list.at(-1);
+	const isStart = record.event?.target === "agent.run" && record.event.phase === "before";
+	if (latest !== void 0 && (!isStart || latest.status === "running")) {
+		if (isStart) {
+			if (latest.started) latest.resumeCount += 1;
+			latest.started = true;
+		}
+		return latest;
+	}
+	const created = {
+		runId,
+		attemptIndex: list.length,
+		resumeCount: 0,
+		started: isStart,
+		status: "running",
+		firstSequence: record.sequence,
+		lastSequence: record.sequence,
+		firstObservedAt: record.observedAt,
+		lastObservedAt: record.observedAt,
+		eventCount: 0,
+		decisionCount: 0,
+		targets: {},
+		decisions: {}
+	};
+	list.push(created);
+	return created;
+}
+function projectRunActivity(run, record) {
+	const event = record.event;
+	if (event?.target !== "agent.run") return;
+	const payload = objectRecord(event.payload);
+	const status = stringField(payload, "status");
+	const done = event.phase === "after" || status === "done";
+	if (!done && event.phase !== "error" && status !== "failed") return;
+	run.status = done ? "done" : "down";
+	run.settledAt = record.observedAt;
+	if (payload && Object.hasOwn(payload, "failure")) run.failure = runtimeFailureCauseSchema.parse(payload.failure);
+	const error = stringField(payload, "error");
+	if (error && (!done || run.failure !== void 0)) run.error = error;
+}
+function nodeKey(runId, nodeId) {
+	return `${runId}\u0000${nodeId}`;
+}
+function projectSpawnNode(nodes, record, attemptIndex) {
+	const event = record.event;
+	if (event?.target !== "agent.spawn") return;
+	const payload = objectRecord(event.payload);
+	const childId = stringField(payload, "childId");
+	if (!childId) return;
+	const key = nodeKey(event.runId, childId);
+	const existing = nodes.get(key);
+	if (existing) {
+		existing.lastSequence = record.sequence;
+		existing.lastObservedAt = record.observedAt;
+		existing.eventCount += 1;
+		return;
+	}
+	const label = stringField(payload, "label");
+	const runtime = stringField(payload, "runtime");
+	const depth = numberField(payload, "depth");
+	const assignmentId = stringField(payload, "assignmentId");
+	const successorOf = stringField(payload, "successorOf");
+	const attemptId = stringField(payload, "attemptId");
+	const startedAt = numberField(payload, "startedAt");
+	nodes.set(key, {
+		id: childId,
+		...event.parentId ? { parentId: event.parentId } : {},
+		runId: event.runId,
+		attemptIndex,
+		...label ? { label } : {},
+		...runtime ? { runtime } : {},
+		...depth !== void 0 ? { depth } : {},
+		...assignmentId ? { assignmentId } : {},
+		...successorOf ? { successorOf } : {},
+		...attemptId ? { attemptId } : {},
+		startedAt: startedAt ?? record.observedAt,
+		...payload && Object.hasOwn(payload, "identity") ? { identity: payload.identity } : {},
+		...payload && Object.hasOwn(payload, "budget") ? { budget: payload.budget } : {},
+		status: "running",
+		modelCalls: [],
+		firstSequence: record.sequence,
+		lastSequence: record.sequence,
+		firstObservedAt: record.observedAt,
+		lastObservedAt: record.observedAt,
+		eventCount: 1,
+		turnCount: 0
+	});
+}
+function projectNodeActivity(nodes, record) {
+	const event = record.event;
+	if (event === void 0) return;
+	if (event.target === "agent.spawn") return;
+	const payload = objectRecord(event.payload);
+	const nodeId = stringField(payload, "childId") ?? stringField(payload, "nodeId") ?? stringField(payload, "workerId");
+	if (!nodeId) return;
+	const node = nodes.get(nodeKey(event.runId, nodeId));
+	if (!node) return;
+	node.lastSequence = record.sequence;
+	node.lastObservedAt = record.observedAt;
+	node.eventCount += 1;
+	if (event.target !== "agent.child") return;
+	const status = stringField(payload, "status");
+	if (status !== "done" && status !== "down") return;
+	node.status = status;
+	node.settledAt = numberField(payload, "settledAt") ?? record.observedAt;
+	const startedAt = numberField(payload, "startedAt");
+	if (startedAt !== void 0) node.startedAt = startedAt;
+	if (payload && Object.hasOwn(payload, "spent")) node.spent = spendField(payload, "spent");
+	const metered = spendField(payload, "metered");
+	if (metered) node.ownInference = node.ownInference ? addSpend(node.ownInference, metered) : metered;
+	const runtime = stringField(payload, "runtime");
+	if (runtime) node.runtime = runtime;
+	const outRef = stringField(payload, "outRef");
+	if (outRef) node.outRef = outRef;
+	const score = numberField(payload, "score");
+	if (score !== void 0) node.score = score;
+	const valid = booleanField(payload, "valid");
+	if (valid !== void 0) node.valid = valid;
+	const reason = stringField(payload, "reason");
+	if (reason) node.reason = reason;
+	if (status === "done") node.failure = void 0;
+	else if (payload && Object.hasOwn(payload, "failure")) node.failure = runtimeFailureCauseSchema.parse(payload.failure);
+	const infra = booleanField(payload, "infra");
+	if (infra !== void 0) node.infra = infra;
+	const retained = stringField(payload, "retainedExecution");
+	if (retained === "pending" || retained === "released" || retained === "release-unconfirmed") node.retainedExecution = retained;
+	const cause = stringField(payload, "retainedPendingCause");
+	if (cause === "unobservable" || cause === "provider-contract" || cause === "request-rejected" || cause === "transport" || cause === "nested-recovery") node.retainedPendingCause = cause;
+	const releasedAt = numberField(payload, "releasedAt");
+	if (releasedAt !== void 0) node.releasedAt = releasedAt;
+	const budgetViolation = budgetViolationField(payload);
+	if (budgetViolation) node.budgetViolation = budgetViolation;
+	attachSettlementEvidence(node, payload);
+}
+/**
+* Read the receipts a settlement carries. Each is taken as reported: an `unknown` receipt keeps
+* its `status` and `reason` so a client can show WHY a model or backend is missing instead of
+* showing nothing, and a receipt that never landed leaves every derived field absent.
+*/
+function attachSettlementEvidence(node, payload) {
+	const providerModel = payload?.providerModel;
+	if (providerModel && typeof providerModel === "object") node.providerModel = providerModel;
+	const trace = payload?.trace;
+	if (trace && typeof trace === "object") node.trace = trace;
+	const bindings = payload?.executionBindings;
+	if (Array.isArray(bindings) && bindings.length > 0) {
+		node.executionBindings = bindings;
+		const known = bindings.find((binding) => objectRecord(binding)?.status === "known");
+		if (known) {
+			node.placement = known.descriptor;
+			node.attemptId ??= known.attemptId;
+		}
+	}
+	const receipt = payload?.materialization;
+	if (!receipt || typeof receipt !== "object") return;
+	node.materialization = receipt;
+	if (receipt.status !== "known") return;
+	node.backend = receipt.backend;
+	if (receipt.model.status === "known") node.model = receipt.model.id;
+	node.execution = {
+		kind: receipt.execution.kind,
+		id: receipt.execution.id
+	};
+}
+/**
+* Fold one metered turn onto whoever drove it. `agent.turn` names its subject in `parentId` — the
+* node making the call — not in the payload, because the caller IS the subject. A turn the run
+* root drove belongs to no spawned node and lands on the run instead, so the run's totals stay
+* complete without inventing a node for the root.
+*/
+function projectTurn(run, nodes, record) {
+	const event = record.event;
+	if (event?.target !== "agent.turn") return;
+	const payload = objectRecord(event.payload);
+	const spend = spendField(payload, "spend");
+	const subject = event.parentId;
+	if (subject === void 0) return;
+	const node = nodes.get(nodeKey(event.runId, subject));
+	if (!node) {
+		if (!spend) return;
+		run.rootInference = run.rootInference ? addSpend(run.rootInference, spend) : spend;
+		return;
+	}
+	node.turnCount += 1;
+	node.lastSequence = record.sequence;
+	node.lastObservedAt = record.observedAt;
+	if (spend) {
+		node.ownInference = node.ownInference ? addSpend(node.ownInference, spend) : spend;
+		node.firstOutputAt ??= record.observedAt;
+	}
+	const reasoning = numberField(payload, "reasoningTokens");
+	if (reasoning !== void 0) node.reasoningTokens = (node.reasoningTokens ?? 0) + reasoning;
+	const firstTokenAt = numberField(payload, "firstTokenAt");
+	if (firstTokenAt !== void 0) node.firstTokenAt ??= firstTokenAt;
+	const model = stringField(payload, "model");
+	if (model) node.model ??= model;
+	const callId = stringField(payload, "callId");
+	if (callId && !node.modelCalls.includes(callId)) node.modelCalls.push(callId);
+}
+/**
+* A node's whole reported cost: the child work its settlement reported plus the inference it drove
+* itself. `undefined` when neither landed — the run's `spendGaps` then names the node, so an
+* unaccounted node is visible instead of reading as free.
+*/
+function nodeTotal(node) {
+	if (node.spent && node.ownInference) return addSpend(node.spent, node.ownInference);
+	if (node.spent) return cloneSpend(node.spent);
+	if (node.ownInference) return cloneSpend(node.ownInference);
+}
+/**
+* The run counted once, and each node's own share of it.
+*
+* A settled node's `spent` already contains the child work its nested tree reported, so summing
+* every node would count a driver's descendants twice. Inclusive therefore sums only the run's
+* TOP-LEVEL nodes — those whose parent is not another node of this run — plus the root's own
+* turns. Exclusive subtracts each node's direct children from its own total, which telescopes:
+* the exclusive entries sum back to `inclusive` exactly.
+*/
+function runTotals(run, nodes) {
+	const present = new Set(nodes.map((node) => node.id));
+	const children = /* @__PURE__ */ new Map();
+	for (const node of nodes) {
+		if (node.parentId === void 0 || !present.has(node.parentId)) continue;
+		const list = children.get(node.parentId);
+		if (list) list.push(node);
+		else children.set(node.parentId, [node]);
+	}
+	const exclusiveByNode = {};
+	let inclusive = run.rootInference ? cloneSpend(run.rootInference) : zeroSpend();
+	if (run.rootInference) exclusiveByNode[run.runId] = cloneSpend(run.rootInference);
+	for (const node of nodes) {
+		const total = nodeTotal(node);
+		if (total === void 0) continue;
+		if (node.parentId === void 0 || !present.has(node.parentId)) inclusive = addSpend(inclusive, total);
+		let exclusive = total;
+		for (const child of children.get(node.id) ?? []) {
+			const childTotal = nodeTotal(child);
+			if (childTotal !== void 0) exclusive = subtractSpend(exclusive, childTotal);
+		}
+		exclusiveByNode[node.id] = exclusive;
+	}
+	return Object.freeze({
+		inclusive: Object.freeze(inclusive),
+		exclusiveByNode: Object.freeze(exclusiveByNode)
+	});
+}
+/**
+* Remove a child's reported total from its parent's. Per channel, never below zero: a parent whose
+* executor reported less than its children did is a reporting gap, and a negative exclusive share
+* would be a fabricated number rather than a measurement.
+*/
+function subtractSpend(a, b) {
+	const tokens = { ...a.tokens };
+	tokens.input = Math.max(0, tokens.input - b.tokens.input);
+	tokens.output = Math.max(0, tokens.output - b.tokens.output);
+	if (a.tokens.cacheRead !== void 0) tokens.cacheRead = Math.max(0, a.tokens.cacheRead - (b.tokens.cacheRead ?? 0));
+	if (a.tokens.cacheWrite !== void 0) tokens.cacheWrite = Math.max(0, a.tokens.cacheWrite - (b.tokens.cacheWrite ?? 0));
+	if (a.tokens.freshInput !== void 0) tokens.freshInput = Math.max(0, a.tokens.freshInput - (b.tokens.freshInput ?? 0));
+	return {
+		iterations: Math.max(0, a.iterations - b.iterations),
+		tokens,
+		...a.tokensKnown === false || b.tokensKnown === false ? { tokensKnown: false } : {},
+		usd: Math.max(0, a.usd - b.usd),
+		...a.usdKnown === false || b.usdKnown === false ? { usdKnown: false } : {},
+		...a.usdEstimated !== void 0 ? { usdEstimated: Math.max(0, a.usdEstimated - (b.usdEstimated ?? 0)) } : {},
+		ms: Math.max(0, a.ms - b.ms)
+	};
+}
+/** The nodes of one run whose accounting is incomplete, in the vocabulary the supervisor already
+*  uses: `never-settled` = no terminal record, so every channel is unaccounted; `unreported` = a
+*  record landed with a channel the provider did not report, so that channel is a floor. */
+function runSpendGaps(nodes) {
+	const gaps = [];
+	for (const node of nodes) {
+		const label = node.label;
+		if (node.status === "running") {
+			gaps.push({
+				id: node.id,
+				...label !== void 0 ? { label } : {},
+				kind: "never-settled",
+				channels: ["tokens", "usd"]
+			});
+			continue;
+		}
+		const total = nodeTotal(node);
+		const channels = [];
+		if (total === void 0 || total.tokensKnown === false) channels.push("tokens");
+		if (total === void 0 || total.usdKnown === false) channels.push("usd");
+		if (channels.length === 0) continue;
+		gaps.push({
+			id: node.id,
+			...label !== void 0 ? { label } : {},
+			kind: "unreported",
+			channels
+		});
+	}
+	return gaps;
+}
+function usageOf(total, reasoning) {
+	return {
+		input: total.tokens.input,
+		output: total.tokens.output,
+		...total.tokens.cacheRead !== void 0 ? { cacheRead: total.tokens.cacheRead } : {},
+		...total.tokens.cacheWrite !== void 0 ? { cacheWrite: total.tokens.cacheWrite } : {},
+		...reasoning !== void 0 ? { reasoning } : {},
+		tokensKnown: total.tokensKnown !== false && total.tokens.tokensKnown !== false
+	};
+}
+function costOf(total) {
+	const usdKnown = total.usdKnown !== false;
+	const estimated = total.usdEstimated;
+	const provenance = usdKnown ? estimated === void 0 || estimated === 0 ? "reported" : "partial" : estimated === void 0 ? "unknown" : estimated >= total.usd ? "estimated" : "partial";
+	return {
+		usd: total.usd,
+		usdKnown,
+		...estimated !== void 0 ? { usdEstimated: estimated } : {},
+		provenance
+	};
+}
+/** The platform block, or nothing at all when the node's spend names no box channel. */
+function platformOf(total) {
+	if (total.boxMinutesProvenance === void 0) return void 0;
+	return {
+		...total.boxMinutes !== void 0 ? { boxMinutes: total.boxMinutes } : {},
+		boxMinutesKnown: total.boxMinutesKnown === true,
+		provenance: total.boxMinutesProvenance
+	};
+}
+function timingOf(node) {
+	if (node.startedAt === void 0) return void 0;
+	return {
+		startedAt: node.startedAt,
+		...node.firstOutputAt !== void 0 ? { firstOutputAt: node.firstOutputAt } : {},
+		...node.firstTokenAt !== void 0 ? { firstTokenAt: node.firstTokenAt } : {},
+		...node.settledAt !== void 0 ? { settledAt: node.settledAt } : {},
+		...node.settledAt !== void 0 ? { wallMs: Math.max(0, node.settledAt - node.startedAt) } : {}
+	};
+}
+function freezeRun(run, nodes) {
+	const gaps = runSpendGaps(nodes);
+	const { rootInference: _rootInference, started: _started, segments, ...rest } = run;
+	return Object.freeze({
+		...rest,
+		...segments?.length ? { segments: Object.freeze(segments.map((segment) => Object.freeze(segment))) } : {},
+		targets: Object.freeze({ ...run.targets }),
+		decisions: Object.freeze({ ...run.decisions }),
+		totals: runTotals(run, nodes),
+		...gaps.length > 0 ? { spendGaps: Object.freeze(gaps) } : {}
+	});
+}
+function freezeNode(node) {
+	const { modelCalls, segments, reasoningTokens, startedAt: _startedAt, attemptIndex: _attemptIndex, ...rest } = node;
+	const total = nodeTotal(node);
+	const timing = timingOf(node);
+	return Object.freeze({
+		...rest,
+		...segments?.length ? { segments: Object.freeze(segments.map((segment) => Object.freeze(segment))) } : {},
+		...modelCalls.length > 0 ? { modelCalls: Object.freeze([...modelCalls]) } : {},
+		...total !== void 0 ? {
+			usage: usageOf(total, reasoningTokens),
+			cost: costOf(total)
+		} : {},
+		...total !== void 0 && platformOf(total) !== void 0 ? { platform: platformOf(total) } : {},
+		...timing !== void 0 ? { timing } : {}
+	});
+}
+function increment(target, key) {
+	target[key] = (target[key] ?? 0) + 1;
+}
+function objectRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+/** Read a journaled `Spend` without trusting the wire: a record missing the conserved channels is
+*  not a zero-cost turn, it is an unparseable one, and it must not enter a total. */
+function spendField(value, key) {
+	const field = objectRecord(value?.[key]);
+	if (!field) return void 0;
+	const tokens = objectRecord(field.tokens);
+	if (typeof field.usd !== "number" || !Number.isFinite(field.usd)) return void 0;
+	if (!tokens || typeof tokens.input !== "number" || typeof tokens.output !== "number") return;
+	return cloneSpend(field);
+}
+/** Read a journaled overspend without trusting the wire: one malformed channel drops the record,
+*  so an unparseable entry is never reported as an overspend of some size. */
+function budgetViolationField(value) {
+	const overspent = objectRecord(value?.budgetViolation)?.overspent;
+	if (!Array.isArray(overspent) || overspent.length === 0) return void 0;
+	const entries = [];
+	for (const raw of overspent) {
+		const entry = objectRecord(raw);
+		const channel = stringField(entry, "channel");
+		const reserved = numberField(entry, "reserved");
+		const spent = numberField(entry, "spent");
+		if (channel === void 0 || reserved === void 0 || spent === void 0) return void 0;
+		entries.push({
+			channel,
+			reserved,
+			spent
+		});
+	}
+	return { overspent: entries };
+}
+function stringField(value, key) {
+	const field = value?.[key];
+	return typeof field === "string" && field.length > 0 ? field : void 0;
+}
+function numberField(value, key) {
+	const field = value?.[key];
+	return typeof field === "number" && Number.isFinite(field) ? field : void 0;
+}
+function booleanField(value, key) {
+	const field = value?.[key];
+	return typeof field === "boolean" ? field : void 0;
+}
+// src/durable/supervision-discovery.ts
+/**
+* Discover the stable identities recorded by Runtime's durable supervision
+* files. This is the developer-facing first step before calling
+* `FileSpawnJournal.loadTree(root)`, `loadSpawnForest(journal, root)`, or
+* `FileCoordinationLog.load(runId, ownerId)`.
+*
+* Missing files produce empty collections. A malformed committed JSONL record
+* still fails loud through the same parser used by the runtime; a torn final
+* append is ignored because it was never acknowledged as committed.
+*/
+async function discoverDurableSupervisionRun(runDir) {
+	if (typeof runDir !== "string" || runDir.trim().length === 0) throw new TypeError("discoverDurableSupervisionRun: runDir must be a non-empty string");
+	const canonicalRunDir = resolve(runDir);
+	const spawnJournalPath = `${canonicalRunDir}/spawn-journal.jsonl`;
+	const coordinationLogPath = `${canonicalRunDir}/coordination-log.jsonl`;
+	const nestedRoots = /* @__PURE__ */ new Set();
+	const rootsBegunAt = /* @__PURE__ */ new Map();
+	for await (const record of readCommittedJsonLines(spawnJournalPath, { allowMissing: true })) {
+		if (record.kind === "begin") {
+			if (typeof record.root !== "string" || record.root.length === 0) throw new Error(`${spawnJournalPath}: begin record has no non-empty string root identity`);
+			rootsBegunAt.set(record.root, typeof record.at === "string" ? record.at : null);
+			continue;
+		}
+		for (const event of spawnJournalRecordEvents(record)) {
+			if (!isRecord(event) || event.kind !== "spawned") continue;
+			if (!Object.hasOwn(event, "ownedTreeRoot")) continue;
+			if (typeof event.ownedTreeRoot !== "string" || event.ownedTreeRoot.length === 0) throw new Error(`${spawnJournalPath}: spawned event ownedTreeRoot must be a non-empty string when present`);
+			nestedRoots.add(event.ownedTreeRoot);
+		}
+	}
+	const streams = /* @__PURE__ */ new Map();
+	for await (const record of readCommittedJsonLines(coordinationLogPath, { allowMissing: true })) {
+		if (typeof record.runId !== "string" || record.runId.length === 0) throw new Error(`${coordinationLogPath}: record has no non-empty string runId identity`);
+		const stream = streams.get(record.runId) ?? {
+			owners: /* @__PURE__ */ new Set(),
+			unscopedRecords: 0,
+			recordCount: 0
+		};
+		stream.recordCount += 1;
+		if (record.ownerId === void 0) stream.unscopedRecords += 1;
+		else if (typeof record.ownerId === "string" && record.ownerId.length > 0) stream.owners.add(record.ownerId);
+		else throw new Error(`${coordinationLogPath}: ownerId must be a non-empty string when present`);
+		streams.set(record.runId, stream);
+	}
+	const coordinationStreams = [...streams.entries()].sort(([left], [right]) => compareText(left, right)).map(([runId, stream]) => Object.freeze({
+		runId,
+		ownerIds: Object.freeze([...stream.owners].sort(compareText)),
+		unscopedRecords: stream.unscopedRecords,
+		recordCount: stream.recordCount
+	}));
+	const observer = await FileObserverJournal.open(`${canonicalRunDir}/observer.jsonl`);
+	const roots = [...rootsBegunAt.keys()].filter((root) => !nestedRoots.has(root)).sort(compareText);
+	return Object.freeze({
+		runDir: canonicalRunDir,
+		...observer ? { observer: {
+			path: observer.path,
+			pursuitId: observer.pursuitId
+		} } : {},
+		spawnJournalPath,
+		coordinationLogPath,
+		roots: Object.freeze(roots),
+		rootsBegunAt: Object.freeze(roots.map((root) => rootsBegunAt.get(root) ?? null)),
+		coordinationStreams: Object.freeze(coordinationStreams)
+	});
+}
+function compareText(left, right) {
+	return left < right ? -1 : left > right ? 1 : 0;
+}
+export { observerRecordDigest as a, createFileObserverHooks as i, projectPursuit as n, FileObserverJournal as r, discoverDurableSupervisionRun as t };
+
+//# sourceMappingURL=supervision-discovery-CewADdEs.js.map