@tangle-network/agent-runtime 1.0.0 → 2.0.2

package/dist/graph-registry-72DlMnUl.js

@@ -0,0 +1,585 @@
+import { m as ValidationError } from "./errors-AzSuGI23.js";
+import { a as readCommittedJsonFile, c as withJsonlFileLock, l as sha256, n as isNoEntError, s as upsertCommittedJsonLine } from "./jsonl-file-BBP9Dz9w.js";
+import { a as writeAtomicDurableFile } from "./durable-file-DstVeHcj.js";
+import { n as resolveJsonPointer } from "./coordination-map-routing-CUvwHAtv.js";
+import { z } from "zod";
+import { join } from "node:path";
+import { mkdir, readFile, readdir } from "node:fs/promises";
+// src/runtime/supervise/graph-file-schema.ts
+const scalar = z.union([
+	z.string(),
+	z.number().finite(),
+	z.boolean(),
+	z.null()
+]);
+const pointer = z.string().regex(/^(?:\/(?:[^~]|~[01])*)*$/);
+const matchBase = {
+	node: z.string().min(1).optional(),
+	pointer
+};
+const equals = z.strictObject({
+	...matchBase,
+	equals: scalar
+});
+const oneOf = z.strictObject({
+	...matchBase,
+	in: z.array(scalar)
+});
+const exists = z.strictObject({
+	...matchBase,
+	exists: z.boolean()
+});
+const match = z.union([
+	equals,
+	oneOf,
+	exists
+]);
+/** The same data grammar as routes; no executable expressions or additional operators. */
+const graphRouteWhenSchema = z.union([match, z.strictObject({ all: z.array(match).min(1) })]);
+const parameter = z.strictObject({
+	default: z.unknown().optional(),
+	type: z.enum([
+		"string",
+		"number",
+		"integer",
+		"boolean",
+		"object",
+		"array",
+		"null"
+	]).optional()
+});
+const command = z.strictObject({
+	command: z.string().min(1),
+	timeoutMs: z.number().int().positive().optional()
+});
+const nonnegativeInteger = z.number().int().nonnegative();
+/** Authoring envelope. Canonical profiles and topology are validated by their existing owners. */
+const graphFileSchema = z.strictObject({
+	digest: z.string().min(1).optional(),
+	graph: z.string().min(1).optional(),
+	describe: z.string().optional(),
+	params: z.record(z.string().min(1), parameter).optional(),
+	nodes: z.array(z.strictObject({
+		id: z.string().min(1),
+		profile: z.record(z.string(), z.unknown()).optional(),
+		seat: z.union([z.string().min(1), z.array(z.string().min(1)).min(1)]).optional(),
+		needs: z.array(z.string().min(1)).optional()
+	})).min(1),
+	entry: z.array(z.union([z.string().min(1), z.strictObject({
+		node: z.string().min(1),
+		task: z.unknown()
+	})])).min(1).optional(),
+	edges: z.array(z.record(z.string(), z.unknown())),
+	gates: z.array(z.unknown()).optional(),
+	budget: z.strictObject({
+		maxIterations: nonnegativeInteger,
+		maxTokens: nonnegativeInteger,
+		maxUsd: z.number().finite().nonnegative().optional(),
+		deadlineMs: nonnegativeInteger.optional(),
+		resources: z.record(z.string(), z.strictObject({
+			unit: z.string().min(1),
+			limit: nonnegativeInteger
+		})).optional()
+	}),
+	check: z.union([
+		equals.extend({ describe: z.string().optional() }),
+		oneOf.extend({ describe: z.string().optional() }),
+		exists.extend({ describe: z.string().optional() }),
+		z.strictObject({
+			describe: z.string().optional(),
+			all: z.array(match).min(1)
+		}),
+		z.strictObject({
+			describe: z.string().optional(),
+			command
+		})
+	]).optional(),
+	deliverable: z.strictObject({
+		describe: z.string().optional(),
+		checkRef: z.string().min(1),
+		command: command.optional(),
+		when: graphRouteWhenSchema.optional()
+	}).optional(),
+	on: z.unknown().optional()
+});
+/** Judge the flow's terminal-output map with RouteWhen's own JSON-pointer semantics. */
+function checkGraphRoute(when, output) {
+	return ("all" in when ? when.all : [when]).every((condition) => {
+		let document = output;
+		if (condition.node !== void 0) {
+			if (!output || typeof output !== "object" || !Object.hasOwn(output, condition.node)) return false;
+			document = output[condition.node];
+		}
+		const selected = resolveJsonPointer(document, condition.pointer);
+		if ("exists" in condition) return selected.found === condition.exists;
+		if (!selected.found) return false;
+		return "equals" in condition ? selected.value === condition.equals : condition.in.some((value) => value === selected.value);
+	});
+}
+// src/runtime/supervise/graph-parameters.ts
+const triggerPart = z.strictObject({ trigger: z.array(z.string()).min(1) });
+const literalPart = z.strictObject({ literal: z.string() });
+/** Explicit authored trigger slots in compiled graph data. An empty list marks fully bound data. */
+const graphTriggerBindingsSchema = z.array(z.strictObject({
+	path: z.array(z.union([z.string(), z.number().int().nonnegative()])).min(1),
+	mode: z.enum(["value", "text"]),
+	parts: z.array(z.union([literalPart, triggerPart])).min(1)
+}).superRefine((slot, context) => {
+	if (!slot.parts.some((part) => "trigger" in part) || slot.mode === "value" && (slot.parts.length !== 1 || !("trigger" in slot.parts[0]))) context.addIssue({
+		code: "custom",
+		message: "binding requires authored trigger parts; value slots require one trigger"
+	});
+}));
+function readBinding(namespace, keys, bindings) {
+	let found = bindings[namespace];
+	for (const key of keys) {
+		if (!found || typeof found !== "object" || !Object.hasOwn(found, key)) throw new ValidationError(`graph parameters: missing ${[namespace, ...keys].join(".")}`);
+		found = found[key];
+	}
+	if (found === void 0) throw new ValidationError(`graph parameters: missing ${[namespace, ...keys].join(".")}`);
+	return structuredClone(found);
+}
+function textValue(value, expression) {
+	if (value !== null && typeof value === "object") throw new ValidationError(`graph parameters: ${expression} needs a whole JSON slot`);
+	return String(value);
+}
+function pendingText(parts) {
+	return parts.map((part) => "literal" in part ? part.literal : `\${trigger.${part.trigger.join(".")}}`).join("");
+}
+/** Compile authored slots once. Inserted values are data, never recursively parsed templates. */
+function compileGraphParameters(value, bindings, options = {}) {
+	const visiting = /* @__PURE__ */ new Set();
+	const triggerBindings = [];
+	const bind = (item, path) => {
+		if (typeof item === "string") {
+			if (item.replace(/\$\{[^{}]+\}/g, "").includes("${")) throw new ValidationError("graph parameters: malformed reference");
+			const whole = /^\$\{([^{}]+)\}$/.exec(item);
+			const parts = [];
+			let cursor = 0;
+			let wholeValue;
+			let boundWhole = false;
+			for (const match of item.matchAll(/\$\{([^{}]+)\}/g)) {
+				if (match.index > cursor) parts.push({ literal: item.slice(cursor, match.index) });
+				const [namespace, ...keys] = match[1].split(".");
+				if (namespace !== "params" && namespace !== "trigger" || keys.length === 0) throw new ValidationError(`graph parameters: unsupported reference \${${match[1]}}`);
+				if (options.defer?.includes(namespace)) {
+					if (namespace === "trigger") parts.push({ trigger: keys });
+					else parts.push({ literal: match[0] });
+				} else {
+					const found = readBinding(namespace, keys, bindings);
+					if (whole) {
+						wholeValue = found;
+						boundWhole = true;
+					} else parts.push({ literal: textValue(found, match[1]) });
+				}
+				cursor = match.index + match[0].length;
+			}
+			if (boundWhole) return wholeValue;
+			if (cursor === 0) return item;
+			if (cursor < item.length) parts.push({ literal: item.slice(cursor) });
+			if (parts.some((part) => "trigger" in part)) triggerBindings.push({
+				path,
+				mode: whole ? "value" : "text",
+				parts
+			});
+			return pendingText(parts);
+		}
+		if (!item || typeof item !== "object") return item;
+		if (visiting.has(item)) throw new ValidationError("graph parameters: cyclic data is not JSON");
+		visiting.add(item);
+		const bound = Array.isArray(item) ? item.map((child, index) => bind(child, [...path, index])) : Object.fromEntries(Object.entries(item).map(([key, child]) => [key, bind(child, [...path, key])]));
+		visiting.delete(item);
+		return bound;
+	};
+	return {
+		value: bind(value, []),
+		triggerBindings
+	};
+}
+/** Legacy authored-data binding. Compiled graphs use bindCompiledGraphTriggers instead. */
+function bindGraphParameters(value, bindings, options = {}) {
+	return compileGraphParameters(value, bindings, options).value;
+}
+/** Check provenance against the exact provisional values without reading trigger data. */
+function assertGraphTriggerBindings(value, slots) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const slot of graphTriggerBindingsSchema.parse(slots)) {
+		const key = JSON.stringify(slot.path.map(String));
+		if (seen.has(key)) throw new ValidationError("graph parameters: duplicate trigger binding path");
+		seen.add(key);
+		let found = value;
+		for (const key of slot.path) {
+			if (!found || typeof found !== "object" || !Object.hasOwn(found, key)) throw new ValidationError("graph parameters: trigger binding path does not exist");
+			found = found[key];
+		}
+		if (found !== pendingText(slot.parts)) throw new ValidationError("graph parameters: trigger binding does not match its provisional value");
+	}
+}
+/** Only explicitly recorded authored slots bind. Literal parameter/trigger values are untouched. */
+function bindCompiledGraphTriggers(value, slots, trigger) {
+	assertGraphTriggerBindings(value, slots);
+	const bound = structuredClone(value);
+	for (const slot of slots) {
+		let parent = bound;
+		for (const key of slot.path.slice(0, -1)) parent = parent[key];
+		parent[slot.path.at(-1)] = slot.mode === "value" ? readBinding("trigger", slot.parts[0].trigger, { trigger }) : slot.parts.map((part) => "literal" in part ? part.literal : textValue(readBinding("trigger", part.trigger, { trigger }), `trigger.${part.trigger.join(".")}`)).join("");
+	}
+	return bound;
+}
+// src/runtime/supervise/graph-registry.ts
+/**
+* `graph-registry` — the designer's memory: graphs and their outcomes as files.
+*
+* The AgentGraph algebra makes a graph PLAIN DATA (nodes with pinned profiles,
+* edges with registry-versioned directives, a budget, a deliverable
+* description), which is the property that lets a graph be stored, replayed
+* byte-identical, and mutated like code. This module is the thin durable layer
+* on top: one JSONL record per run, the exact graph content-addressed beside
+* it. The natural home is a SANDBOX WORKSPACE — the platform's snapshot story
+* (Firecracker restore, warm leases, `continuity: 'resume'`) then makes the
+* registry the agent's compounding execution memory across runs: a rerun over
+* the same sandbox finds every graph the designer ever ran, what each cost,
+* and whether it delivered.
+*
+* ORACLES STAY ENVIRONMENT-OWNED. `DeliverableSpec.check` is a function and is
+* deliberately NOT stored: a stored graph keeps the deliverable's `describe`
+* and an optional `checkRef`, and replay re-binds the check from the caller's
+* environment. This is the graph contract's own doctrine — graders are
+* environment, never workers — applied to persistence.
+*
+* Scoring is a documented heuristic, not a learned model: delivered beats
+* failed, then cheaper (tokens, then iterations), then most recent. A designer
+* that needs better selection replaces `pickBest`, not the records.
+*/
+const RECORDS_FILE = "records.jsonl";
+const GRAPHS_DIR = "graphs";
+/** Canonical serialization for content-addressing: stable key order, sorted. */
+function canonicalJson(value) {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value && typeof value === "object") 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)}:${canonicalJson(v)}`).join(",")}}`;
+	return JSON.stringify(value);
+}
+/** Digest of the exact graph (nodes + edges + budget + deliverable describe, and a flow graph's
+*  entry and gates). An absent key is not serialized, so a graph without `entry` keeps the digest
+*  it had before flow graphs were stored. */
+function graphDigest(graph) {
+	return sha256(canonicalJson(graph));
+}
+/** Digest of the normalized task shape a designer looks records up by. */
+function taskShapeDigest(taskShape) {
+	return sha256(canonicalJson(taskShape));
+}
+/** Digest of a runnable graph exactly as the registry stores it — the value
+*  `recordGraphRun` demands. Callers recording real runs hash through this,
+*  never hand-rolled, so a record always matches its graph. */
+function digestOfGraph(graph) {
+	return storeGraph(graph).digest;
+}
+function storeGraph(graph) {
+	const { describe, checkRef, command, when } = graph.deliverable;
+	const content = {
+		nodes: graph.nodes,
+		edges: graph.edges,
+		budget: graph.budget,
+		...graph.triggerBindings === void 0 ? {} : { triggerBindings: graph.triggerBindings },
+		deliverable: {
+			...describe ? { describe } : {},
+			...checkRef ? { checkRef } : {},
+			...command ? { command } : {},
+			...when ? { when } : {}
+		},
+		...graph.entry === void 0 ? {} : { entry: graph.entry },
+		...graph.gates === void 0 ? {} : { gates: graph.gates }
+	};
+	return {
+		digest: graphDigest(content),
+		...content
+	};
+}
+function assertRecord(record) {
+	if (typeof record.graphDigest !== "string" || record.graphDigest.length === 0) throw new ValidationError("graph-registry: record.graphDigest is required");
+	if (typeof record.taskDigest !== "string" || record.taskDigest.length === 0) throw new ValidationError("graph-registry: record.taskDigest is required");
+	if (!Number.isFinite(Date.parse(record.startedAt))) throw new ValidationError("graph-registry: record.startedAt must be a timestamp");
+	if (![
+		"delivered",
+		"no-winner",
+		"unknown",
+		"running"
+	].includes(record.outcome.kind)) throw new ValidationError("graph-registry: invalid record.outcome.kind");
+	if ((record.outcome.kind === "delivered" || record.outcome.kind === "no-winner") && (!record.finishedAt || !Number.isFinite(Date.parse(record.finishedAt)))) throw new ValidationError("graph-registry: terminal outcomes require record.finishedAt");
+	if ((record.outcome.kind === "unknown" || record.outcome.kind === "running") && !record.outcome.reason) throw new ValidationError("graph-registry: incomplete outcomes require a reason");
+	if (record.source && (!record.source.kind || !record.source.id)) throw new ValidationError("graph-registry: source.kind and source.id are required");
+	if (record.finishedAt && (!Number.isFinite(Date.parse(record.finishedAt)) || Date.parse(record.finishedAt) < Date.parse(record.startedAt))) throw new ValidationError("graph-registry: finishedAt precedes startedAt or is invalid");
+	for (const [channel, value] of Object.entries(record.cost)) if (value !== void 0 && (typeof value !== "number" || !Number.isFinite(value) || value < 0)) throw new ValidationError(`graph-registry: invalid cost.${channel}`);
+}
+function recordKey(record) {
+	assertRecord(record);
+	if (record.source) return JSON.stringify([
+		"source",
+		record.source.kind,
+		record.source.id
+	]);
+	return JSON.stringify([
+		record.taskDigest,
+		record.graphDigest,
+		record.startedAt
+	]);
+}
+/** Open (or lazily create) a registry rooted at a workspace directory. The
+*  directory is the sandbox workspace; snapshots carry it across runs. */
+function graphRegistry(root) {
+	if (!root || root.trim().length === 0) throw new ValidationError("graphRegistry: root directory is required");
+	return { root };
+}
+/** Append one run record; the exact graph is content-addressed beside it.
+*  Idempotent per (taskDigest, graphDigest, startedAt): a replayed append with
+*  the same key replaces the prior row rather than duplicating it. */
+async function recordGraphRun(reg, graph, record) {
+	return recordStoredGraphRun(reg, storeGraph(graph), record);
+}
+/** Store an executable graph or an observed external topology in the same registry.
+* Imported observations retain their source identity and never authorize replay.
+* A reader refreshing facts can preserve independently joined labels; an explicit
+* correction leaves preserveLabels unset and replaces the record. */
+async function recordStoredGraphRun(reg, definition, record, options = {}) {
+	const { digest, ...content } = definition;
+	const stored = {
+		...content,
+		digest: digest ?? graphDigest(content)
+	};
+	if (stored.observed && !record) throw new ValidationError("graph-registry: observed graphs require a source run identity");
+	if (record) {
+		assertRecord(record);
+		if (stored.observed && !record.source) throw new ValidationError("graph-registry: observed graphs require a source run identity");
+		if (!stored.observed && !record.finishedAt) throw new ValidationError("graph-registry: native graph runs require a completion timestamp");
+		if ((!stored.observed || record.traversals !== void 0) && (!Number.isSafeInteger(record.traversals) || record.traversals < 0)) throw new ValidationError("graph-registry: native graphs require metered traversals; observed counts must be non-negative integers");
+		if (stored.digest !== record.graphDigest) throw new ValidationError(`graph-registry: record.graphDigest ${record.graphDigest} does not match the supplied graph (${stored.digest}) — record the graph that actually ran`);
+	}
+	if (graphDigest(content) !== stored.digest) throw new ValidationError("graph-registry: stored graph content does not match its digest");
+	await mkdir(join(reg.root, GRAPHS_DIR), { recursive: true });
+	const file = join(reg.root, RECORDS_FILE);
+	return withJsonlFileLock(file, async (canonicalPath) => {
+		if (!record) {
+			await persistGraph(reg, stored);
+			return stored;
+		}
+		let persisted = record;
+		if (options.preserveLabels && record.source) {
+			const prior = (await readCommittedJsonFile(canonicalPath)).find((row) => row.source?.kind === record.source.kind && row.source.id === record.source.id);
+			if (prior) {
+				const taskType = record.taskType ?? prior.taskType;
+				const priorTerminal = prior.outcome.kind === "delivered" || prior.outcome.kind === "no-winner";
+				const incomingUnassessed = record.outcome.kind === "unknown" || record.outcome.kind === "running";
+				if (priorTerminal && incomingUnassessed && prior.startedAt !== record.startedAt) throw new ValidationError("graph-registry: preserving labels requires the same task start and source identity");
+				const evidence = [...prior.evidence ?? [], ...record.evidence ?? []];
+				persisted = {
+					...record,
+					...taskType ? { taskType } : {},
+					...record.unknowns ? { unknowns: record.unknowns.filter((reason) => !(taskType && reason === "task type not explicitly labeled")) } : {},
+					...evidence.length ? { evidence: [...new Map(evidence.map((entry) => [canonicalJson(entry), entry])).values()] } : {},
+					...priorTerminal && incomingUnassessed ? {
+						outcome: prior.outcome,
+						finishedAt: prior.finishedAt,
+						cost: {
+							...record.cost,
+							...prior.cost.ms === void 0 ? {} : { ms: prior.cost.ms },
+							...prior.cost.mergeMs === void 0 ? {} : { mergeMs: prior.cost.mergeMs }
+						}
+					} : {}
+				};
+			}
+		}
+		assertRecord(persisted);
+		await persistGraph(reg, stored);
+		await upsertCommittedJsonLine(canonicalPath, persisted, recordKey);
+		return stored;
+	});
+}
+async function persistGraph(reg, stored) {
+	const revisionPath = join(reg.root, GRAPHS_DIR, `${stored.digest}.json`);
+	try {
+		const { digest: existingDigest, ...existing } = JSON.parse(await readFile(revisionPath, "utf8"));
+		if (existingDigest !== stored.digest || graphDigest(existing) !== stored.digest) throw new ValidationError("graph-registry: stored graph revision is immutable but its content differs");
+	} catch (error) {
+		if (!isNoEntError(error)) throw error;
+		writeAtomicDurableFile(revisionPath, JSON.stringify(stored), { preserveMode: true });
+	}
+}
+/** All records, newest last. */
+async function listGraphRuns(reg) {
+	return readCommittedJsonFile(join(reg.root, RECORDS_FILE));
+}
+function observedTopology(record) {
+	return record.topologyDigest ?? (record.source ? "unknown" : record.graphDigest);
+}
+/** Records for one task shape or deterministic label query, newest last. */
+async function graphRunsFor(reg, query = {}) {
+	const filters = typeof query === "string" ? { taskDigest: query } : query;
+	return (await listGraphRuns(reg)).filter((row) => (filters.taskDigest === void 0 || row.taskDigest === filters.taskDigest) && (filters.taskType === void 0 || (row.taskType ?? "unknown") === filters.taskType) && (filters.topologyDigest === void 0 || observedTopology(row) === filters.topologyDigest) && (filters.sourceKind === void 0 || (row.source?.kind ?? "native") === filters.sourceKind));
+}
+function medianKnown(values) {
+	const known = values.filter((value) => value !== void 0 && Number.isFinite(value) && value >= 0).sort((a, b) => a - b);
+	const middle = Math.floor(known.length / 2);
+	return {
+		count: known.length,
+		median: known.length === 0 ? null : known.length % 2 ? known[middle] : (known[middle - 1] + known[middle]) / 2
+	};
+}
+function observedGraphSummary(records) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		const key = JSON.stringify([record.taskType ?? "unknown", observedTopology(record)]);
+		const rows = groups.get(key);
+		if (rows) rows.push(record);
+		else groups.set(key, [record]);
+	}
+	const summaries = [...groups.values()].map((runs) => {
+		const assessed = runs.filter((run) => run.outcome.kind === "delivered" || run.outcome.kind === "no-winner");
+		const delivered = assessed.filter((run) => run.outcome.kind === "delivered");
+		const wall = medianKnown(assessed.map((run) => run.cost.ms));
+		const merge = medianKnown(delivered.filter((run) => run.evidence?.some((entry) => entry.kind === "pr-merged")).map((run) => run.cost.mergeMs));
+		const tokens = medianKnown(assessed.map((run) => run.cost.tokens));
+		const human = medianKnown(assessed.map((run) => run.cost.humanMessages));
+		return {
+			taskType: runs[0].taskType ?? "unknown",
+			topologyDigest: observedTopology(runs[0]),
+			delivered: delivered.length,
+			assessed: assessed.length,
+			unknown: runs.length - assessed.length,
+			deliveredRate: assessed.length ? delivered.length / assessed.length : null,
+			medianWallMs: wall.median,
+			wallMsCount: wall.count,
+			medianMergeMs: merge.median,
+			mergeMsCount: merge.count,
+			medianTokens: tokens.median,
+			tokenCount: tokens.count,
+			medianHumanMessages: human.median,
+			humanMessageCount: human.count,
+			runs
+		};
+	});
+	summaries.sort((a, b) => {
+		const delivered = (b.deliveredRate ?? -1) - (a.deliveredRate ?? -1);
+		if (delivered) return delivered;
+		for (const key of [
+			"medianWallMs",
+			"medianTokens",
+			"medianHumanMessages"
+		]) {
+			if (a[key] === b[key]) continue;
+			if (a[key] === null) return 1;
+			if (b[key] === null) return -1;
+			return a[key] - b[key];
+		}
+		return a.taskType.localeCompare(b.taskType) || a.topologyDigest.localeCompare(b.topologyDigest);
+	});
+	return {
+		recordCount: records.length,
+		groups: summaries
+	};
+}
+/** Query and rank the same registry records using the opt-in observational
+* policy: delivery rate, wall time, tokens, then human messages; unknowns last. */
+async function graphCorpusSummary(reg, query = {}) {
+	return observedGraphSummary(await graphRunsFor(reg, query));
+}
+/** The documented heuristic: delivered beats failed; among delivered, cheaper
+*  (tokens, then iterations) wins; ties go to the most recent. */
+function pickBestGraph(records, options = {}) {
+	if (options.policy === "observed") {
+		const group = observedGraphSummary(records).groups[0];
+		return group && pickBestGraph(group.runs);
+	}
+	const delivered = records.filter((row) => row.outcome.kind === "delivered");
+	if (delivered.length === 0) return void 0;
+	const better = (a, b) => {
+		const aTokens = a.cost.tokens ?? Number.POSITIVE_INFINITY;
+		const bTokens = b.cost.tokens ?? Number.POSITIVE_INFINITY;
+		if (aTokens !== bTokens) return aTokens < bTokens ? a : b;
+		const aIter = a.cost.iterations ?? Number.POSITIVE_INFINITY;
+		const bIter = b.cost.iterations ?? Number.POSITIVE_INFINITY;
+		if (aIter !== bIter) return aIter < bIter ? a : b;
+		return a.finishedAt >= b.finishedAt ? a : b;
+	};
+	return delivered.reduce((best, row) => better(best, row) === best ? best : row);
+}
+/** Load a stored graph by digest. */
+async function loadGraph(reg, digest) {
+	try {
+		return JSON.parse(await readFile(join(reg.root, GRAPHS_DIR, `${digest}.json`), "utf8"));
+	} catch {
+		return;
+	}
+}
+/** The designer's lookup: replay the known-good graph for this task shape, or
+*  author a new one — with the reason stated either way (the decision is data). */
+async function lookupGraph(reg, taskDigest) {
+	const records = await graphRunsFor(reg, taskDigest);
+	const candidates = [];
+	const loaded = /* @__PURE__ */ new Map();
+	for (const record of records) {
+		if (!loaded.has(record.graphDigest)) loaded.set(record.graphDigest, await loadGraph(reg, record.graphDigest));
+		if (!loaded.get(record.graphDigest)?.observed) candidates.push(record);
+	}
+	if (records.length && !candidates.length) return {
+		kind: "author",
+		reason: "only observed topologies are available; author an executable graph"
+	};
+	const best = pickBestGraph(candidates);
+	if (best) {
+		const graph = await loadGraph(reg, best.graphDigest);
+		if (graph) return {
+			kind: "replay",
+			graph,
+			record: best
+		};
+		return {
+			kind: "author",
+			reason: `best record's graph ${best.graphDigest.slice(0, 12)} is missing from the registry`
+		};
+	}
+	return {
+		kind: "author",
+		reason: records.length === 0 ? "first run for this task shape" : "no graph delivered for this task shape yet"
+	};
+}
+/** Rehydrate a stored graph, binding trigger data and an environment-owned named check. */
+function graphFromStored(stored, environment = {}) {
+	if (stored.observed) throw new ValidationError("graphFromStored: observed topology cannot be replayed");
+	const { digest: _digest, observed: _observed, triggerBindings: _triggerBindings, deliverable, ...topology } = stored.triggerBindings !== void 0 ? bindCompiledGraphTriggers(stored, stored.triggerBindings, typeof environment === "function" ? void 0 : environment.trigger ?? {}) : typeof environment === "function" ? stored : bindGraphParameters(stored, { trigger: environment.trigger ?? {} });
+	const selected = typeof environment === "function" ? environment : environment.checks && Object.hasOwn(environment.checks, deliverable.checkRef ?? "") ? environment.checks[deliverable.checkRef] : deliverable.checkRef === "command" ? deliverable.command : deliverable.checkRef === "route" && deliverable.when ? ((out, context) => context ? context.originalVerdict?.valid !== false : checkGraphRoute(deliverable.when, out)) : void 0;
+	if (!selected) throw new ValidationError(`graphFromStored: unknown checkRef ${deliverable.checkRef ?? "(missing)"}`);
+	const materialized = stored.triggerBindings === void 0 ? {} : { triggerBindings: [] };
+	if (typeof selected === "function") {
+		const { command: _command, ...description } = deliverable;
+		return {
+			...topology,
+			...materialized,
+			deliverable: {
+				...description,
+				check: selected
+			}
+		};
+	}
+	const command = selected === deliverable.command ? selected : bindGraphParameters(selected, { trigger: environment.trigger ?? {} });
+	return {
+		...topology,
+		...materialized,
+		deliverable: {
+			...deliverable,
+			command,
+			check: () => false
+		}
+	};
+}
+/** Digests present on disk (integrity probe for tests and audits). */
+async function storedGraphDigests(reg) {
+	try {
+		return (await readdir(join(reg.root, GRAPHS_DIR))).filter((name) => name.endsWith(".json")).map((name) => name.slice(0, -5)).sort();
+	} catch {
+		return [];
+	}
+}
+export { compileGraphParameters as _, graphRegistry as a, graphRouteWhenSchema as b, loadGraph as c, recordGraphRun as d, recordStoredGraphRun as f, bindGraphParameters as g, assertGraphTriggerBindings as h, graphFromStored as i, lookupGraph as l, taskShapeDigest as m, graphCorpusSummary as n, graphRunsFor as o, storedGraphDigests as p, graphDigest as r, listGraphRuns as s, digestOfGraph as t, pickBestGraph as u, graphTriggerBindingsSchema as v, graphFileSchema as y };
+
+//# sourceMappingURL=graph-registry-72DlMnUl.js.map