@tangle-network/agent-runtime 0.162.0 → 0.164.0

package/dist/graph.js

@@ -1,62 +1,217 @@
 import { m as ValidationError } from "./errors-CDZ8XsVj.js";
-import { x as contentAddress } from "./spawn-journal-oewq1g2h.js";
-import { i as workerFromBackend, s as supervisorAgent } from "./supervise-Di6xvnOL.js";
-//#region src/runtime/graph/kind.ts
-/** Validate a kind declaration at registration — so a malformed kind is refused by name once,
-*  not at the first node that uses it. */
-function validateNodeKind(kind, context = "registerNodeKind") {
-	const who = `${context}: kind ${JSON.stringify(`${kind.id}/v${kind.version}`)}`;
-	if (typeof kind.id !== "string" || kind.id.length === 0) throw new ValidationError(`${context}: a kind must carry a non-empty id`);
-	if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(kind.id)) throw new ValidationError(`${who}: id may contain only letters, digits, ".", "_" and "-"`);
-	if (!Number.isSafeInteger(kind.version) || kind.version < 1) throw new ValidationError(`${who}: version must be a positive integer`);
-	if (typeof kind.description !== "string" || kind.description.trim().length === 0) throw new ValidationError(`${who}: description is required`);
-	if (typeof kind.validateConfig !== "function") throw new ValidationError(`${who}: validateConfig must be a function`);
-	if (!isRecord(kind.configSchema)) throw new ValidationError(`${who}: configSchema must be a JSON Schema object`);
-	for (const [field, ports] of [["inputs", kind.inputs], ["outputs", kind.outputs]]) {
-		if (!Array.isArray(ports)) throw new ValidationError(`${who}: ${field} must be an array`);
-		const seen = /* @__PURE__ */ new Set();
-		for (const port of ports) {
-			if (!port || typeof port.name !== "string" || port.name.length === 0) throw new ValidationError(`${who}: every ${field} port needs a non-empty name`);
-			if (field === "outputs" && (port.name === "out" || port.name === "trace")) throw new ValidationError(`${who}: output port ${JSON.stringify(port.name)} is implicit on every node and cannot be declared`);
-			if (seen.has(port.name)) throw new ValidationError(`${who}: duplicate ${field} port ${JSON.stringify(port.name)}`);
-			seen.add(port.name);
-			if (!isRecord(port.schema)) throw new ValidationError(`${who}: ${field} port ${JSON.stringify(port.name)} needs a JSON Schema`);
+import { i as InMemorySpawnJournal, r as InMemoryResultBlobStore, x as contentAddress } from "./spawn-journal-oewq1g2h.js";
+import { A as createBudgetPool, B as createExecutorRegistry, i as collectDelivered, o as runFinalizer, r as bestDelivered, u as createScope } from "./supervisor-D5K8ihKQ.js";
+import { i as workerFromBackend, s as supervisorAgent } from "./supervise-CzllE0vn.js";
+import { t as GraphEdgeCapError } from "./graph-DzE4SwfP.js";
+//#region src/runtime/graph/condition.ts
+/**
+* The ONE predicate tree: every guard in a graph — an edge `guard`, a filter projection's
+* predicate — is this shape, evaluated by this evaluator, so `contains`, ordering and equality can
+* never mean two different things on two surfaces (adopted from ADC's `workflow-conditions`,
+* agent-runtime#968). A declarative tree keeps an untrusted predicate incapable of code execution;
+* the size and depth bounds keep a predicate authored once from burning CPU on every settle.
+*
+* No zod: the kernel's grain is a hand-written validator that throws `ValidationError` by name.
+*/
+/** The leaf comparison operators; `exists`/`truthy` are unary, the rest compare against `value`. */
+const CONDITION_OPS = [
+	"eq",
+	"neq",
+	"gt",
+	"gte",
+	"lt",
+	"lte",
+	"in",
+	"contains",
+	"exists",
+	"truthy"
+];
+/** Operators that compare against `value`; `exists`/`truthy` are unary and must omit it. */
+const OPS_NEEDING_VALUE = new Set(CONDITION_OPS.filter((op) => op !== "exists" && op !== "truthy"));
+const MAX_PATH_LENGTH = 256;
+const MAX_PATH_SEGMENTS = 16;
+const PATH_SEGMENT = /^[A-Za-z_$][A-Za-z0-9_$-]*$/u;
+/** Parse `a.b[0].c` into steps; refuse anything outside the bounded grammar. */
+function parseConditionPath(path, context) {
+	if (typeof path !== "string" || path.length === 0 || path.length > MAX_PATH_LENGTH) throw new ValidationError(`${context}: path must be a non-empty string of at most ${MAX_PATH_LENGTH} chars`);
+	const steps = [];
+	for (const part of path.split(".")) {
+		const open = part.indexOf("[");
+		const head = open === -1 ? part : part.slice(0, open);
+		if (head.length > 0) {
+			if (!PATH_SEGMENT.test(head)) throw new ValidationError(`${context}: path segment ${JSON.stringify(head)} is not addressable`);
+			steps.push(head);
+		} else if (open !== 0 || steps.length === 0) throw new ValidationError(`${context}: path ${JSON.stringify(path)} has an empty segment`);
+		let rest = open === -1 ? "" : part.slice(open);
+		while (rest.length > 0) {
+			const match = /^\[(\d{1,6})\]/u.exec(rest);
+			if (!match) throw new ValidationError(`${context}: path index in ${JSON.stringify(part)} must be [N]`);
+			steps.push(Number(match[1]));
+			rest = rest.slice(match[0].length);
 		}
+		if (steps.length > MAX_PATH_SEGMENTS) throw new ValidationError(`${context}: path exceeds ${MAX_PATH_SEGMENTS} segments`);
 	}
-	if (!Array.isArray(kind.effects) || kind.effects.some((e) => typeof e !== "string" || e.length === 0)) throw new ValidationError(`${who}: effects must be an array of non-empty names`);
-	if (new Set(kind.effects).size !== kind.effects.length) throw new ValidationError(`${who}: effects must not repeat a name`);
-	if (kind.onCrash !== "restart" && kind.onCrash !== "resume") throw new ValidationError(`${who}: onCrash must be "restart" or "resume"`);
-	if (kind.budget !== "metered" && kind.budget !== "exempt") throw new ValidationError(`${who}: budget must be "metered" or "exempt"`);
-	if (typeof kind.run !== "function") throw new ValidationError(`${who}: run must be a function`);
-	return kind;
+	if (steps.length === 0) throw new ValidationError(`${context}: path resolves no segment`);
+	return steps;
 }
-/** The handle a graph writes to name this kind. */
-function kindHandle(kind) {
-	return {
-		id: kind.id,
-		version: kind.version
+/** Walk a parsed path; any miss resolves `undefined`, never a throw — absence is an answer. */
+function resolveConditionPath(context, steps) {
+	let current = context;
+	for (const step of steps) {
+		if (current === null || current === void 0) return void 0;
+		if (typeof step === "number") {
+			if (!Array.isArray(current)) return void 0;
+			current = current[step];
+		} else {
+			if (typeof current !== "object" || Array.isArray(current)) return void 0;
+			current = current[step];
+		}
+	}
+	return current;
+}
+function isLeaf(condition) {
+	return typeof condition.path === "string";
+}
+/** Validate shape, bounds, and per-leaf path/operator rules; returns the input for chaining. */
+function validateCondition(raw, context) {
+	let nodes = 0;
+	const walk = (value, depth) => {
+		nodes += 1;
+		if (nodes > 40) throw new ValidationError(`${context}: condition exceeds 40 nodes`);
+		if (depth > 6) throw new ValidationError(`${context}: condition exceeds depth 6`);
+		if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ValidationError(`${context}: a condition must be an object`);
+		const record = value;
+		const combinators = [
+			"all",
+			"any",
+			"not"
+		].filter((key) => record[key] !== void 0);
+		if (combinators.length > 1) throw new ValidationError(`${context}: a condition carries ONE of all/any/not, got ${combinators.join("+")}`);
+		if (record.all !== void 0 || record.any !== void 0) {
+			const key = record.all !== void 0 ? "all" : "any";
+			const branch = record[key];
+			if (!Array.isArray(branch) || branch.length === 0) throw new ValidationError(`${context}: ${key} must be a non-empty array`);
+			for (const child of branch) walk(child, depth + 1);
+			return value;
+		}
+		if (record.not !== void 0) {
+			walk(record.not, depth + 1);
+			return value;
+		}
+		const op = record.op;
+		if (typeof record.path !== "string" || typeof op !== "string") throw new ValidationError(`${context}: a leaf needs { path, op }`);
+		if (!CONDITION_OPS.includes(op)) throw new ValidationError(`${context}: unknown op ${JSON.stringify(op)}; known: ${CONDITION_OPS.join(", ")}`);
+		parseConditionPath(record.path, context);
+		const needsValue = OPS_NEEDING_VALUE.has(op);
+		if (needsValue && !("value" in record)) throw new ValidationError(`${context}: op ${JSON.stringify(op)} requires a value`);
+		if (!needsValue && "value" in record) throw new ValidationError(`${context}: op ${JSON.stringify(op)} is unary — remove value`);
+		if (op === "in" && !Array.isArray(record.value)) throw new ValidationError(`${context}: op "in" takes an array value`);
+		return value;
 	};
+	return walk(raw, 1);
+}
+function canonicalEquals(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	try {
+		return JSON.stringify(a) === JSON.stringify(b);
+	} catch {
+		return false;
+	}
+}
+function ordering(op, left, right) {
+	if (typeof left === "number" && typeof right === "number") {
+		if (Number.isNaN(left) || Number.isNaN(right)) return false;
+		if (op === "gt") return left > right;
+		if (op === "gte") return left >= right;
+		if (op === "lt") return left < right;
+		return left <= right;
+	}
+	if (typeof left === "string" && typeof right === "string") {
+		if (op === "gt") return left > right;
+		if (op === "gte") return left >= right;
+		if (op === "lt") return left < right;
+		return left <= right;
+	}
+	return false;
+}
+/** Walk a validated condition over a context to a boolean. Never throws on data shape. */
+function evaluateCondition(condition, context) {
+	if (isLeaf(condition)) {
+		const resolved = resolveConditionPath(context, parseConditionPath(condition.path, "evaluate"));
+		switch (condition.op) {
+			case "exists": return resolved !== void 0 && resolved !== null;
+			case "truthy": return Boolean(resolved);
+			case "eq": return canonicalEquals(resolved, condition.value);
+			case "neq": return !canonicalEquals(resolved, condition.value);
+			case "in": return Array.isArray(condition.value) ? condition.value.some((candidate) => canonicalEquals(resolved, candidate)) : false;
+			case "contains":
+				if (Array.isArray(resolved)) return resolved.some((element) => canonicalEquals(element, condition.value));
+				return typeof resolved === "string" && typeof condition.value === "string" ? resolved.includes(condition.value) : false;
+			default: return ordering(condition.op, resolved, condition.value);
+		}
+	}
+	if ("all" in condition) return condition.all.every((child) => evaluateCondition(child, context));
+	if ("any" in condition) return condition.any.some((child) => evaluateCondition(child, context));
+	return !evaluateCondition(condition.not, context);
 }
+//#endregion
+//#region src/runtime/graph/projection.ts
 /**
-* Narrow a host's effect table to exactly what one kind declared. Anything the kind did not
-* declare is absent — `undefined` on read — so a kind cannot reach past its declaration, and the
-* engine can list a graph's required effects before spending a token.
+* The ONE pure projection a `data` edge may carry (agent-runtime#971): the bounded,
+* schema-preserving subset of ADC's collection helpers. Anything richer is a `script` NODE, so it
+* is journaled (`inputRef` → `outRef`), typed, and visible. Exactly one operator per projection.
 */
-function narrowEffects(declared, provided, context) {
-	const out = {};
-	const missing = [];
-	for (const name of declared) {
-		if (!(name in provided)) {
-			missing.push(name);
-			continue;
-		}
-		out[name] = provided[name];
+const PROJECTION_KEYS = [
+	"path",
+	"pick",
+	"map",
+	"filter",
+	"first",
+	"last",
+	"count"
+];
+/** Validate a projection: exactly one known operator, its argument well-formed. */
+function validateProjection(raw, context) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new ValidationError(`${context}: a projection must be an object`);
+	const record = raw;
+	const keys = PROJECTION_KEYS.filter((key) => record[key] !== void 0);
+	const unknown = Object.keys(record).filter((key) => !PROJECTION_KEYS.includes(key));
+	if (unknown.length > 0) throw new ValidationError(`${context}: unknown projection key(s) ${unknown.join(", ")}; known: ${PROJECTION_KEYS.join(", ")}`);
+	if (keys.length !== 1) throw new ValidationError(`${context}: a projection carries exactly ONE of ${PROJECTION_KEYS.join("/")}`);
+	const key = keys[0];
+	if (key === "path" || key === "map") parseConditionPath(record[key], context);
+	if (key === "pick") {
+		const fields = record.pick;
+		if (!Array.isArray(fields) || fields.length === 0 || fields.some((f) => typeof f !== "string")) throw new ValidationError(`${context}: pick must be a non-empty array of field names`);
 	}
-	if (missing.length > 0) throw new ValidationError(`${context}: host provides no effect for ${missing.map((m) => JSON.stringify(m)).join(", ")}; provided: ${Object.keys(provided).sort().join(", ") || "none"}`);
-	return Object.freeze(out);
+	if (key === "filter") validateCondition(record.filter, context);
+	if ((key === "first" || key === "last" || key === "count") && record[key] !== true) throw new ValidationError(`${context}: ${key} must be literally true`);
+	return raw;
 }
-function isRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* Apply a validated projection to an admitted payload. Collection operators over a non-array
+* refuse by name — a shape the author did not expect is a graph defect, not an empty result.
+*/
+function applyProjection(value, projection, context) {
+	if ("path" in projection) return resolveConditionPath(value, parseConditionPath(projection.path, context));
+	if ("pick" in projection) {
+		if (typeof value !== "object" || value === null || Array.isArray(value)) throw new ValidationError(`${context}: pick needs an object payload`);
+		const record = value;
+		const out = {};
+		for (const field of projection.pick) if (field in record) out[field] = record[field];
+		return out;
+	}
+	const collection = value;
+	if (!Array.isArray(collection)) throw new ValidationError(`${context}: this projection needs an array payload`);
+	if ("map" in projection) {
+		const steps = parseConditionPath(projection.map, context);
+		return collection.map((element) => resolveConditionPath(element, steps));
+	}
+	if ("filter" in projection) return collection.filter((element) => evaluateCondition(projection.filter, element));
+	if ("first" in projection) return collection[0];
+	if ("last" in projection) return collection[collection.length - 1];
+	return collection.length;
 }
 //#endregion
 //#region src/runtime/graph/registry.ts
@@ -131,6 +286,273 @@ function createRegistry(label, seed = []) {
 	return registry;
 }
 //#endregion
+//#region src/runtime/graph/definition.ts
+/** Which gating-edge outcomes release a node (adopted from ADC, agent-runtime#968). */
+const JOIN_RULES = [
+	"all",
+	"any",
+	"any_failed",
+	"all_done"
+];
+/** ADC-compatible visit backstop: nothing may be ENTERED more than this many times. */
+const DEFAULT_MAX_NODE_VISITS = 25;
+/** The hard ceiling an author's `maxVisits`/`maxNodeVisits` override may reach. */
+const MAX_MAX_NODE_VISITS = 100;
+/** Structural validation only — everything a registry is not needed for. */
+function validateEngineGraphSpec(spec, context = "compileGraph") {
+	if (!Array.isArray(spec.nodes) || spec.nodes.length === 0) throw new ValidationError(`${context}: a graph needs at least one node`);
+	const ids = /* @__PURE__ */ new Set();
+	for (const node of spec.nodes) {
+		if (typeof node.id !== "string" || node.id.length === 0) throw new ValidationError(`${context}: every node needs a non-empty id`);
+		if (ids.has(node.id)) throw new ValidationError(`${context}: duplicate node id ${JSON.stringify(node.id)}`);
+		ids.add(node.id);
+		parseRegistryHandle(node.kind, `${context}: node ${node.id} kind`);
+		if (node.join !== void 0 && !JOIN_RULES.includes(node.join)) throw new ValidationError(`${context}: node ${node.id} join ${JSON.stringify(node.join)}; known: ${JOIN_RULES.join(", ")}`);
+		if (node.maxVisits !== void 0) {
+			if (!Number.isSafeInteger(node.maxVisits) || node.maxVisits < 1 || node.maxVisits > 100) throw new ValidationError(`${context}: node ${node.id} maxVisits must be an integer in [1, 100]`);
+		}
+	}
+	if (!Array.isArray(spec.edges)) throw new ValidationError(`${context}: edges must be an array`);
+	for (const [index, edge] of spec.edges.entries()) {
+		const who = `${context}: edge[${index}]`;
+		if (edge.kind !== "delegates" && edge.kind !== "analyzes" && edge.kind !== "data") throw new ValidationError(`${who}: kind must be delegates | analyzes | data`);
+		for (const end of ["from", "to"]) {
+			const ref = edge[end];
+			if (typeof ref !== "object" || ref === null || typeof ref.node !== "string" || !ids.has(ref.node)) throw new ValidationError(`${who}: ${end}.node must name a node in this graph`);
+		}
+		if (edge.guard !== void 0) validateCondition(edge.guard, `${who} guard`);
+		if (edge.projection !== void 0) {
+			if (edge.kind !== "data") throw new ValidationError(`${who}: only a data edge carries a projection`);
+			validateProjection(edge.projection, `${who} projection`);
+		}
+		if (edge.maxTraversals !== void 0) {
+			if (!Number.isSafeInteger(edge.maxTraversals) || edge.maxTraversals < 1) throw new ValidationError(`${who}: maxTraversals must be a positive integer`);
+		}
+		if (edge.kind === "data" && edge.directive !== void 0) throw new ValidationError(`${who}: a data edge carries a port binding, never a directive`);
+	}
+	if (spec.root !== void 0 && !ids.has(spec.root)) throw new ValidationError(`${context}: root ${JSON.stringify(spec.root)} names no node`);
+	if (spec.maxNodeVisits !== void 0) {
+		if (!Number.isSafeInteger(spec.maxNodeVisits) || spec.maxNodeVisits < 1 || spec.maxNodeVisits > 100) throw new ValidationError(`${context}: maxNodeVisits must be an integer in [1, 100]`);
+	}
+}
+//#endregion
+//#region src/runtime/graph/compile.ts
+/**
+* Compile an authored graph against an engine's kind registry into the schedulable form. Every
+* refusal here happens before any spend: an unknown kind, a port that does not exist, a `data`
+* binding whose schemas cannot fit, a `delegates`/`data` edge into an oracle, a terminal with no
+* completion check (agent-runtime#971, #973).
+*/
+/** A node's ports: its kind's declared outputs plus the two implicit ones every node has. */
+const IMPLICIT_OUTPUT_PORTS = ["out", "trace"];
+/** A node's ports: node-level declarations merged OVER its kind's (the node wins on a name). */
+function nodePorts(kind, node) {
+	const merge = (declared, own) => {
+		if (own === void 0 || own.length === 0) return declared;
+		const names = new Set(own.map((port) => port.name));
+		return [...own, ...declared.filter((port) => !names.has(port.name))];
+	};
+	return {
+		inputs: merge(kind.inputs, node.ports?.inputs),
+		outputs: merge(kind.outputs, node.ports?.outputs)
+	};
+}
+function outputPort(ports, port) {
+	if (IMPLICIT_OUTPUT_PORTS.includes(port)) return {
+		name: port,
+		schema: {}
+	};
+	return ports.outputs.find((candidate) => candidate.name === port);
+}
+function inputPort(ports, port) {
+	return ports.inputs.find((candidate) => candidate.name === port);
+}
+/**
+* Bounded structural acceptance: does a value of `source`'s shape fit `target`? Schemas with no
+* `type` accept anything; object targets require their `required` properties to be present and
+* accepted when the source declares properties. Depth-bounded — this is a compile-time tripwire,
+* not a full JSON Schema validator.
+*/
+function schemaAccepts(source, target, depth = 0) {
+	if (depth > 6) return true;
+	const sourceType = source.type;
+	const targetType = target.type;
+	if (targetType === void 0 || sourceType === void 0) return true;
+	const targets = Array.isArray(targetType) ? targetType : [targetType];
+	const sources = Array.isArray(sourceType) ? sourceType : [sourceType];
+	if (sources.filter((candidate) => targets.includes(candidate === "integer" ? "number" : candidate) || targets.includes(candidate)).length === 0) return false;
+	if (targets.includes("object") && sources.includes("object")) {
+		const required = Array.isArray(target.required) ? target.required : [];
+		const sourceProps = source.properties;
+		const targetProps = target.properties;
+		if (sourceProps !== void 0) for (const name of required) {
+			const sourceProp = sourceProps[name];
+			if (sourceProp === void 0) return false;
+			const targetProp = targetProps?.[name];
+			if (targetProp !== void 0 && !schemaAccepts(sourceProp, targetProp, depth + 1)) return false;
+		}
+	}
+	if (targets.includes("array") && sources.includes("array")) {
+		const sourceItems = source.items;
+		const targetItems = target.items;
+		if (sourceItems !== void 0 && targetItems !== void 0) return schemaAccepts(sourceItems, targetItems, depth + 1);
+	}
+	return true;
+}
+/**
+* Lower an authored graph against an engine's kind registry into the schedulable form, refusing
+* every structural defect before any spend.
+*/
+function compileGraph(engine, spec, context = "compileGraph") {
+	validateEngineGraphSpec(spec, context);
+	const kinds = /* @__PURE__ */ new Map();
+	const configs = /* @__PURE__ */ new Map();
+	for (const node of spec.nodes) {
+		const handle = parseRegistryHandle(node.kind, `${context}: node ${node.id}`);
+		const kind = engine.kinds.require(handle, `${context}: node ${node.id}`);
+		kinds.set(node.id, kind);
+		configs.set(node.id, kind.validateConfig(node.config ?? {}, `${context}: node ${node.id}`));
+		if (node.flags?.pure && kind.id !== "script") throw new ValidationError(`${context}: node ${node.id} sets pure, which only a script node may claim`);
+	}
+	const compiledEdges = [];
+	const inbound = /* @__PURE__ */ new Map();
+	const outbound = /* @__PURE__ */ new Map();
+	for (const [index, edge] of spec.edges.entries()) {
+		const who = `${context}: edge[${index}] ${edge.from.node}->${edge.to.node}`;
+		const fromKind = kinds.get(edge.from.node);
+		const toKind = kinds.get(edge.to.node);
+		if (!fromKind || !toKind) throw new ValidationError(`${who}: unresolved endpoint`);
+		const toNode = spec.nodes.find((node) => node.id === edge.to.node);
+		if (edge.kind !== "analyzes" && toNode?.flags?.oracle) throw new ValidationError(`${who}: a ${edge.kind} edge may not target oracle node ${edge.to.node}; use analyzes`);
+		const fromPort = edge.from.port ?? (edge.kind === "analyzes" ? "trace" : "out");
+		if (edge.kind === "analyzes" && fromPort !== "trace") throw new ValidationError(`${who}: an analyzes edge reads the trace port, got ${fromPort}`);
+		const fromPorts = nodePorts(fromKind, spec.nodes.find((node) => node.id === edge.from.node));
+		const toPorts = nodePorts(toKind, toNode);
+		const sourcePort = outputPort(fromPorts, fromPort);
+		if (!sourcePort) {
+			const known = [...IMPLICIT_OUTPUT_PORTS, ...fromPorts.outputs.map((port) => port.name)];
+			throw new ValidationError(`${who}: ${formatRegistryHandle(fromKind)} has no output port ${JSON.stringify(fromPort)}; known: ${known.join(", ")}`);
+		}
+		let toPort = edge.to.port ?? "";
+		if (edge.kind === "data") {
+			if (toPort === "") if (toPorts.inputs.length === 1) toPort = toPorts.inputs[0]?.name ?? "";
+			else throw new ValidationError(`${who}: a data edge needs to.port; ${formatRegistryHandle(toKind)} declares ${toPorts.inputs.length} inputs`);
+			const targetPort = inputPort(toPorts, toPort);
+			if (!targetPort) throw new ValidationError(`${who}: ${formatRegistryHandle(toKind)} has no input port ${JSON.stringify(toPort)}; known: ${toPorts.inputs.map((port) => port.name).join(", ") || "(none)"}`);
+			if (edge.projection === void 0 && !schemaAccepts(sourcePort.schema, targetPort.schema)) throw new ValidationError(`${who}: output ${fromPort} (${JSON.stringify(sourcePort.schema.type ?? "any")}) cannot fit input ${toPort} (${JSON.stringify(targetPort.schema.type ?? "any")})`);
+		}
+		const compiled = {
+			id: edge.id ?? `${edge.from.node}->${edge.to.node}#${index}`,
+			spec: edge,
+			fromPort,
+			toPort: toPort === "" ? "out" : toPort
+		};
+		compiledEdges.push(compiled);
+		outbound.set(edge.from.node, [...outbound.get(edge.from.node) ?? [], compiled]);
+		inbound.set(edge.to.node, [...inbound.get(edge.to.node) ?? [], compiled]);
+	}
+	const dupes = /* @__PURE__ */ new Set();
+	for (const edge of compiledEdges) {
+		if (dupes.has(edge.id)) throw new ValidationError(`${context}: duplicate edge id ${edge.id}`);
+		dupes.add(edge.id);
+	}
+	const entries = spec.nodes.filter((node) => (inbound.get(node.id) ?? []).length === 0);
+	if (entries.length === 0) throw new ValidationError(`${context}: no entry node — every node has an inbound edge`);
+	const root = spec.root ?? (entries.length === 1 ? entries[0]?.id ?? "" : (() => {
+		throw new ValidationError(`${context}: ${entries.length} entry nodes (${entries.map((node) => node.id).join(", ")}) — name spec.root`);
+	})());
+	const nodes = /* @__PURE__ */ new Map();
+	const terminals = [];
+	for (const node of spec.nodes) {
+		const kind = kinds.get(node.id);
+		if (!kind) throw new ValidationError(`${context}: unresolved node ${node.id}`);
+		const terminal = node.terminal ?? (outbound.get(node.id) ?? []).length === 0;
+		const deliverable = node.deliverable ?? (node.id === root ? spec.deliverable : void 0);
+		if (terminal) terminals.push(node.id);
+		nodes.set(node.id, {
+			id: node.id,
+			kind,
+			config: configs.get(node.id),
+			join: node.join ?? "all",
+			maxVisits: node.maxVisits ?? spec.maxNodeVisits ?? 25,
+			oracle: node.flags?.oracle ?? false,
+			pure: node.flags?.pure ?? false,
+			terminal,
+			...deliverable === void 0 ? {} : { deliverable },
+			inbound: inbound.get(node.id) ?? [],
+			outbound: outbound.get(node.id) ?? [],
+			spec: node
+		});
+	}
+	if (terminals.filter((id) => nodes.get(id)?.deliverable === void 0).length === terminals.length) throw new ValidationError(`${context}: no terminal declares a completion check (terminals: ${terminals.join(", ")}); give a node a deliverable or set spec.deliverable`);
+	return {
+		nodes,
+		edges: compiledEdges,
+		entries: entries.map((node) => node.id),
+		terminals,
+		root,
+		maxNodeVisits: spec.maxNodeVisits ?? 25
+	};
+}
+//#endregion
+//#region src/runtime/graph/kind.ts
+/** Validate a kind declaration at registration — so a malformed kind is refused by name once,
+*  not at the first node that uses it. */
+function validateNodeKind(kind, context = "registerNodeKind") {
+	const who = `${context}: kind ${JSON.stringify(`${kind.id}/v${kind.version}`)}`;
+	if (typeof kind.id !== "string" || kind.id.length === 0) throw new ValidationError(`${context}: a kind must carry a non-empty id`);
+	if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(kind.id)) throw new ValidationError(`${who}: id may contain only letters, digits, ".", "_" and "-"`);
+	if (!Number.isSafeInteger(kind.version) || kind.version < 1) throw new ValidationError(`${who}: version must be a positive integer`);
+	if (typeof kind.description !== "string" || kind.description.trim().length === 0) throw new ValidationError(`${who}: description is required`);
+	if (typeof kind.validateConfig !== "function") throw new ValidationError(`${who}: validateConfig must be a function`);
+	if (!isRecord(kind.configSchema)) throw new ValidationError(`${who}: configSchema must be a JSON Schema object`);
+	for (const [field, ports] of [["inputs", kind.inputs], ["outputs", kind.outputs]]) {
+		if (!Array.isArray(ports)) throw new ValidationError(`${who}: ${field} must be an array`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const port of ports) {
+			if (!port || typeof port.name !== "string" || port.name.length === 0) throw new ValidationError(`${who}: every ${field} port needs a non-empty name`);
+			if (field === "outputs" && (port.name === "out" || port.name === "trace")) throw new ValidationError(`${who}: output port ${JSON.stringify(port.name)} is implicit on every node and cannot be declared`);
+			if (seen.has(port.name)) throw new ValidationError(`${who}: duplicate ${field} port ${JSON.stringify(port.name)}`);
+			seen.add(port.name);
+			if (!isRecord(port.schema)) throw new ValidationError(`${who}: ${field} port ${JSON.stringify(port.name)} needs a JSON Schema`);
+		}
+	}
+	if (!Array.isArray(kind.effects) || kind.effects.some((e) => typeof e !== "string" || e.length === 0)) throw new ValidationError(`${who}: effects must be an array of non-empty names`);
+	if (new Set(kind.effects).size !== kind.effects.length) throw new ValidationError(`${who}: effects must not repeat a name`);
+	if (kind.onCrash !== "restart" && kind.onCrash !== "resume") throw new ValidationError(`${who}: onCrash must be "restart" or "resume"`);
+	if (kind.budget !== "metered" && kind.budget !== "exempt") throw new ValidationError(`${who}: budget must be "metered" or "exempt"`);
+	if (typeof kind.run !== "function") throw new ValidationError(`${who}: run must be a function`);
+	return kind;
+}
+/** The handle a graph writes to name this kind. */
+function kindHandle(kind) {
+	return {
+		id: kind.id,
+		version: kind.version
+	};
+}
+/**
+* Narrow a host's effect table to exactly what one kind declared. Anything the kind did not
+* declare is absent — `undefined` on read — so a kind cannot reach past its declaration, and the
+* engine can list a graph's required effects before spending a token.
+*/
+function narrowEffects(declared, provided, context) {
+	const out = {};
+	const missing = [];
+	for (const name of declared) {
+		if (!(name in provided)) {
+			missing.push(name);
+			continue;
+		}
+		out[name] = provided[name];
+	}
+	if (missing.length > 0) throw new ValidationError(`${context}: host provides no effect for ${missing.map((m) => JSON.stringify(m)).join(", ")}; provided: ${Object.keys(provided).sort().join(", ") || "none"}`);
+	return Object.freeze(out);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/runtime/graph/engine.ts
 /**
 * `createGraphEngine` — one engine instance: its kind registry (core kinds pre-registered, host
@@ -375,6 +797,407 @@ function asRecord(value, context) {
 	return value;
 }
 //#endregion
-export { agentKind, createGraphEngine, createRegistry, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, scriptKind, subgraphKind, supervisorKind, validateNodeKind };
+//#region src/runtime/graph/scheduler.ts
+/**
+* The engine scheduler (agent-runtime#980): run a compiled graph by hosting every node instance on
+* one kernel `Scope` — the pool, the journal, the blob store and cancellation are the kernel's,
+* never re-implemented. The scheduler owns only what a graph adds: joins over guarded edges,
+* traversal and visit caps, directive/payload delivery, terminals and the finalizer reduce.
+*
+* Edge semantics are adopted from ADC's workflow graph (agent-runtime#968): an edge settles
+* SATISFIED / DEAD / FAILED per its source's LATEST completion; join rules `all | any | any_failed
+* | all_done` decide release; a release CONSUMES the outcomes that produced it (settled edges
+* re-arm; a pending edge at release is consumed-once, so an OR-diamond's second completer never
+* double-fires). Per-edge `maxTraversals` refuses the consumption and ledgers `unpropagated`; a
+* node entered past `maxVisits` fails the run `cycle-budget-exceeded` (#973).
+*/
+/** Admission for every value crossing an edge (#971): JSON round-trip, `undefined` stripped, a
+*  non-representable value becomes a RECORD of that fact — a degraded record beats a vanished
+*  edge. */
+function admitPayload(value) {
+	if (value === void 0) return void 0;
+	try {
+		const text = JSON.stringify(value);
+		if (text === void 0) return { nonCanonical: `payload of type ${typeof value}` };
+		return JSON.parse(text);
+	} catch (error) {
+		return { nonCanonical: error instanceof Error ? error.message : String(error) };
+	}
+}
+/**
+* Run a graph: host every node instance on one kernel `Scope`, resolve joins over guarded edges,
+* enforce the traversal and visit caps, and reduce the terminal settlements through the finalizer.
+*/
+async function runEngineGraph(engine, spec, task, options) {
+	const compiled = "nodes" in spec && spec.nodes instanceof Map ? spec : compileGraph(engine, spec);
+	const context = "runEngineGraph";
+	for (const node of compiled.nodes.values()) {
+		const missing = node.kind.effects.filter((name) => !(name in engine.effects));
+		if (missing.length > 0) throw new ValidationError(`${context}: node ${node.id} needs effect(s) ${missing.join(", ")} the host did not provide`);
+		if (node.spec.budget === void 0 && options.perNode === void 0) throw new ValidationError(`${context}: node ${node.id} declares no budget and options.perNode is absent — the engine invents no split`);
+	}
+	for (const edge of compiled.edges) if (edge.spec.directive !== void 0 && options.prompts === void 0) throw new ValidationError(`${context}: edge ${edge.id} carries a directive but options.prompts is absent`);
+	const now = options.now ?? Date.now;
+	const started = now();
+	const runId = options.runId ?? `graph:${contentAddress({
+		task,
+		at: started
+	}).slice(0, 18)}`;
+	const pool = createBudgetPool(options.budget, () => now() - started);
+	const journal = options.journal ?? new InMemorySpawnJournal();
+	const blobs = options.blobs ?? new InMemoryResultBlobStore();
+	await journal.beginTree(runId, new Date(started).toISOString());
+	const abort = new AbortController();
+	const onOuterAbort = () => abort.abort(options.signal?.reason);
+	options.signal?.addEventListener("abort", onOuterAbort, { once: true });
+	if (options.signal?.aborted) abort.abort(options.signal.reason);
+	const scope = createScope({
+		parentId: runId,
+		root: runId,
+		pool,
+		journal,
+		blobs,
+		executors: createExecutorRegistry(),
+		seams: {},
+		depth: 0,
+		signal: abort.signal,
+		now
+	});
+	const nodes = /* @__PURE__ */ new Map();
+	for (const id of compiled.nodes.keys()) nodes.set(id, {
+		visits: 0,
+		live: 0,
+		settles: [],
+		inputs: /* @__PURE__ */ new Map(),
+		directives: [],
+		traces: [],
+		blocked: false
+	});
+	const edges = /* @__PURE__ */ new Map();
+	for (const edge of compiled.edges) edges.set(edge.id, {
+		edge,
+		state: "pending",
+		consumedOnce: false,
+		traversals: 0,
+		payload: void 0
+	});
+	const ledger = [];
+	const exhaustedEdges = /* @__PURE__ */ new Set();
+	const settles = [];
+	const liveHandles = /* @__PURE__ */ new Map();
+	const waitingForBudget = [];
+	let ledgerSeq = 0;
+	let liveCount = 0;
+	let failure;
+	const record = (runtime, outcome, reason) => {
+		runtime.traversals += 1;
+		const spec = runtime.edge.spec;
+		const entry = {
+			edge: runtime.edge.id,
+			kind: spec.kind,
+			from: spec.from.node,
+			to: spec.to.node,
+			traversal: runtime.traversals,
+			outcome,
+			...spec.directive !== void 0 ? { directive: `${spec.directive.surface}/v${spec.directive.version}` } : {},
+			...spec.kind === "data" ? { port: runtime.edge.toPort } : {},
+			...reason !== void 0 ? { reason } : {}
+		};
+		ledger.push(entry);
+		journal.appendEvent(runId, {
+			kind: "edge",
+			id: `graph:${spec.to.node}`,
+			edge: {
+				kind: spec.kind,
+				from: spec.from.node,
+				to: spec.to.node,
+				...entry.directive !== void 0 ? { directive: entry.directive } : {},
+				...entry.port !== void 0 ? { port: entry.port } : {}
+			},
+			traversal: entry.traversal,
+			outcome: outcome === "delivered" ? "delivered" : outcome,
+			bytes: 0,
+			...reason !== void 0 ? { reason } : {},
+			seq: ledgerSeq++,
+			at: new Date(now()).toISOString()
+		});
+	};
+	/** Enter a node: count the visit, build its Agent from consumed inputs, spawn on the Scope. */
+	const enter = (id) => {
+		if (failure) return;
+		const node = compiled.nodes.get(id);
+		const runtime = nodes.get(id);
+		if (!node || !runtime) throw new ValidationError(`${context}: unknown node ${id}`);
+		runtime.visits += 1;
+		if (runtime.visits > node.maxVisits) {
+			failure = {
+				reason: "cycle-budget-exceeded",
+				error: {
+					name: "GraphCycleBudget",
+					message: `node ${id} entered ${runtime.visits} times; maxVisits ${node.maxVisits}`
+				}
+			};
+			abort.abort(`cycle-budget-exceeded: ${id}`);
+			return;
+		}
+		const inputs = {};
+		for (const [port, value] of runtime.inputs) inputs[port] = value;
+		const directives = runtime.directives.splice(0);
+		const traces = runtime.traces.splice(0);
+		const nodeTask = [
+			id === compiled.root ? task : "",
+			...directives,
+			...traces.map((trace) => `trace of ${trace.node}: ${trace.traceRef ?? "(no traceRef)"}`)
+		].filter((part) => part.length > 0).join("\n\n");
+		const effects = narrowEffects(node.kind.effects, engine.effects, `${context}: node ${id}`);
+		const agent = node.kind.run({
+			config: node.config,
+			profile: {
+				name: id,
+				...node.spec.profile ?? {}
+			},
+			inputs,
+			effects
+		});
+		const budget = node.spec.budget ?? options.perNode;
+		const spawned = scope.spawn(agent, nodeTask.length > 0 ? nodeTask : task, {
+			label: id,
+			budget
+		});
+		if (spawned.ok) {
+			liveCount += 1;
+			runtime.live += 1;
+			liveHandles.set(spawned.handle.id, id);
+			return;
+		}
+		if (spawned.reason === "budget-exhausted" || spawned.reason === "max-live-workers") {
+			waitingForBudget.push(id);
+			runtime.visits -= 1;
+			runtime.directives.unshift(...directives);
+			runtime.traces.unshift(...traces);
+			return;
+		}
+		failure = {
+			reason: "driver-failed",
+			error: {
+				name: "SpawnRefused",
+				message: `node ${id}: ${spawned.reason}`
+			}
+		};
+		abort.abort(`spawn refused: ${id}`);
+	};
+	/** Join evaluation per ADC's rules; returns whether the node released. */
+	const tryRelease = (id) => {
+		const node = compiled.nodes.get(id);
+		const runtime = nodes.get(id);
+		if (!node || !runtime || runtime.blocked || failure) return false;
+		const gating = node.inbound.map((edge) => edges.get(edge.id));
+		if (gating.length === 0) return false;
+		const settled = gating.filter((edge) => edge.state !== "pending");
+		const satisfied = gating.filter((edge) => edge.state === "satisfied");
+		const failed = gating.filter((edge) => edge.state === "failed");
+		const allSettled = settled.length === gating.length;
+		let release = false;
+		switch (node.join) {
+			case "all":
+				if (gating.some((edge) => edge.state === "dead" || edge.state === "failed")) release = false;
+				else release = satisfied.length === gating.length;
+				break;
+			case "any":
+				release = satisfied.length > 0;
+				if (!release && allSettled) runtime.blocked = true;
+				break;
+			case "any_failed":
+				release = failed.length > 0;
+				if (!release && allSettled) runtime.blocked = true;
+				break;
+			case "all_done":
+				release = allSettled;
+				break;
+		}
+		if (!release) return false;
+		const consuming = node.join === "any" ? [satisfied[0]] : node.join === "any_failed" ? [failed[0]] : settled;
+		for (const runtimeEdge of consuming) {
+			const cap = runtimeEdge.edge.spec.maxTraversals;
+			if (cap !== void 0 && runtimeEdge.traversals >= cap) {
+				record(runtimeEdge, "unpropagated", `traversal-cap-exhausted (max ${cap})`);
+				runtimeEdge.traversals -= 1;
+				exhaustedEdges.add(runtimeEdge.edge.id);
+				runtime.blocked = node.join === "any" || node.join === "any_failed" ? runtime.blocked : true;
+				return false;
+			}
+		}
+		for (const runtimeEdge of consuming) {
+			const spec = runtimeEdge.edge.spec;
+			if (runtimeEdge.state === "satisfied" && spec.kind === "data") {
+				let payload = runtimeEdge.payload;
+				let outcome = "delivered";
+				let reason;
+				if (spec.projection !== void 0) try {
+					payload = admitPayload(applyProjection(payload, spec.projection, `edge ${runtimeEdge.edge.id}`));
+				} catch (error) {
+					outcome = "empty";
+					reason = error instanceof Error ? error.message : String(error);
+					payload = void 0;
+				}
+				if (payload === void 0 && outcome === "delivered") outcome = "empty";
+				record(runtimeEdge, outcome, reason);
+				if (payload !== void 0) runtime.inputs.set(runtimeEdge.edge.toPort, payload);
+			} else if (runtimeEdge.state === "satisfied" || node.join === "any_failed" || node.join === "all_done") {
+				if (spec.directive !== void 0 && options.prompts !== void 0) runtime.directives.push(options.prompts.resolve(spec.directive).text);
+				if (spec.kind === "analyzes" && runtimeEdge.state === "satisfied") {
+					const trace = runtimeEdge.payload;
+					runtime.traces.push({
+						node: spec.from.node,
+						...trace?.traceRef !== void 0 ? { traceRef: trace.traceRef } : {}
+					});
+				}
+				record(runtimeEdge, "delivered");
+			}
+		}
+		for (const runtimeEdge of gating) if (runtimeEdge.state !== "pending") {
+			runtimeEdge.state = "pending";
+			runtimeEdge.payload = void 0;
+		} else if ((nodes.get(runtimeEdge.edge.spec.from.node)?.live ?? 0) > 0) runtimeEdge.consumedOnce = true;
+		enter(id);
+		return true;
+	};
+	/** Settle every outbound edge of a completed source per its LATEST completion, then try joins. */
+	const propagate = (id, settle) => {
+		const node = compiled.nodes.get(id);
+		if (!node) return;
+		const succeeded = settle.status === "done" && settle.valid !== false;
+		for (const edge of node.outbound) {
+			const runtime = edges.get(edge.id);
+			if (!runtime) continue;
+			if (runtime.consumedOnce && runtime.state === "pending") {
+				runtime.consumedOnce = false;
+				continue;
+			}
+			if (!succeeded) {
+				runtime.state = "failed";
+				runtime.payload = void 0;
+			} else {
+				const guardContext = {
+					node: id,
+					out: settle.out,
+					visits: nodes.get(id)?.visits ?? 0,
+					valid: settle.valid ?? true
+				};
+				const pass = edge.spec.guard === void 0 || evaluateCondition(edge.spec.guard, guardContext);
+				runtime.state = pass ? "satisfied" : "dead";
+				runtime.payload = pass ? edge.spec.kind === "analyzes" ? { traceRef: settle.traceRef } : settle.out : void 0;
+			}
+		}
+		for (const edge of node.outbound) tryRelease(edge.spec.to.node);
+	};
+	const allTerminalsSettled = () => compiled.terminals.every((id) => (nodes.get(id)?.settles.length ?? 0) > 0);
+	for (const id of compiled.entries) enter(id);
+	while (!failure && liveCount > 0) {
+		const settled = await scope.next();
+		if (settled === null) break;
+		const nodeId = liveHandles.get(settled.handle.id);
+		if (nodeId === void 0) continue;
+		liveHandles.delete(settled.handle.id);
+		liveCount -= 1;
+		const node = compiled.nodes.get(nodeId);
+		const runtime = nodes.get(nodeId);
+		if (!node || !runtime) continue;
+		runtime.live -= 1;
+		let entry;
+		if (settled.kind === "done") {
+			const admitted = admitPayload(settled.out);
+			let valid;
+			if (node.deliverable !== void 0) try {
+				valid = await node.deliverable.check(admitted);
+			} catch (error) {
+				valid = false;
+			}
+			entry = {
+				node: nodeId,
+				visit: runtime.visits,
+				status: "done",
+				...valid !== void 0 ? { valid } : {},
+				out: admitted,
+				outRef: settled.outRef
+			};
+			if (settled.trace?.status === "available") entry.traceRef = settled.trace.traceRef;
+		} else if (settled.kind === "down") entry = {
+			node: nodeId,
+			visit: runtime.visits,
+			status: "down",
+			reason: settled.reason
+		};
+		else continue;
+		runtime.settles.push(entry);
+		settles.push(entry);
+		if (nodeId === compiled.root && entry.status === "done" && entry.valid === true) {
+			abort.abort("root delivered");
+			break;
+		}
+		propagate(nodeId, entry);
+		if (allTerminalsSettled()) break;
+		for (const parked of waitingForBudget.splice(0)) enter(parked);
+		if (liveCount === 0 && !failure) break;
+	}
+	options.signal?.removeEventListener("abort", onOuterAbort);
+	abort.abort("run complete");
+	while (await scope.next() !== null);
+	const finalize = async () => {
+		const rows = compiled.terminals.flatMap((id) => (nodes.get(id)?.settles ?? []).map((settle) => ({
+			id: settle.node,
+			status: settle.status,
+			valid: settle.status === "done" && settle.valid !== false,
+			...settle.outRef !== void 0 ? { outRef: settle.outRef } : {}
+		})));
+		return runFinalizer(options.finalizer === void 0 || options.finalizer === "bestDelivered" ? bestDelivered : options.finalizer === "collectDelivered" ? collectDelivered : options.finalizer, {
+			settled: rows,
+			blobs,
+			tree: scope.view,
+			budget: scope.budget
+		});
+	};
+	const terminals = compiled.terminals.flatMap((id) => nodes.get(id)?.settles ?? []);
+	const finish = (result) => {
+		if (result.kind === "no-winner" && exhaustedEdges.size > 0) throw new GraphEdgeCapError(Object.freeze([...exhaustedEdges]), Object.freeze([...ledger]), result);
+		return result;
+	};
+	if (failure) return finish({
+		kind: "no-winner",
+		reason: failure.reason,
+		...failure.error ? { error: failure.error } : {},
+		terminals,
+		settles,
+		ledger,
+		unreachable: []
+	});
+	if (options.signal?.aborted) return finish({
+		kind: "no-winner",
+		reason: "aborted",
+		terminals,
+		settles,
+		ledger,
+		unreachable: []
+	});
+	const out = compiled.terminals.some((id) => (nodes.get(id)?.settles ?? []).some((settle) => settle.status === "done" && settle.valid !== false)) ? await finalize() : void 0;
+	if (out !== void 0) return {
+		kind: "winner",
+		out,
+		terminals,
+		settles,
+		ledger
+	};
+	const unreachable = [...compiled.nodes.keys()].filter((id) => (nodes.get(id)?.settles.length ?? 0) === 0);
+	return finish({
+		kind: "no-winner",
+		reason: compiled.terminals.some((id) => unreachable.includes(id)) ? unreachable.length === compiled.nodes.size ? "budget-exhausted" : "unreachable-terminal" : "all-children-down",
+		terminals,
+		settles,
+		ledger,
+		unreachable
+	});
+}
+//#endregion
+export { CONDITION_OPS, DEFAULT_MAX_NODE_VISITS, JOIN_RULES, MAX_MAX_NODE_VISITS, admitPayload, agentKind, applyProjection, compileGraph, createGraphEngine, createRegistry, evaluateCondition, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, validateCondition, validateNodeKind, validateProjection };
 
 //# sourceMappingURL=graph.js.map