@tangle-network/agent-runtime 0.162.0 → 0.164.0

package/dist/graph.d.ts

@@ -1,7 +1,29 @@
-import { $l as MakeWorkerAgent, If as DeliverableSpec, bo as SupervisorAgentDeps, mu as WorkerSpawnContext } from "./index-8b0o4dMF.js";
-import { K as Spend, t as Agent } from "./types-DXKDG6DQ.js";
-import { o as ExecutorConfig } from "./runtime-B0FIFwpH.js";
+import { $l as MakeWorkerAgent, If as DeliverableSpec, an as PromptRegistry, bo as SupervisorAgentDeps, in as PromptHandle, mu as WorkerSpawnContext, os as SupervisorFinalizer } from "./index-BP11HXYi.js";
+import { H as SpawnJournal, K as Spend, i as Budget, j as ResultBlobStore, t as Agent } from "./types-C2l1jaos.js";
+import { o as ExecutorConfig } from "./runtime-D44YrQ4t.js";
 import { AgentProfile } from "@tangle-network/agent-interface";
+//#region src/runtime/graph/condition.d.ts
+/** The leaf comparison operators; `exists`/`truthy` are unary, the rest compare against `value`. */
+declare const CONDITION_OPS: readonly ["eq", "neq", "gt", "gte", "lt", "lte", "in", "contains", "exists", "truthy"];
+type ConditionOp = (typeof CONDITION_OPS)[number];
+interface ConditionLeaf {
+  /** Dotted path with `[N]` indexing into the guard context, e.g. `out.findings[0].severity`. */
+  readonly path: string;
+  readonly op: ConditionOp;
+  readonly value?: unknown;
+}
+type Condition = ConditionLeaf | {
+  readonly all: ReadonlyArray<Condition>;
+} | {
+  readonly any: ReadonlyArray<Condition>;
+} | {
+  readonly not: Condition;
+};
+/** Validate shape, bounds, and per-leaf path/operator rules; returns the input for chaining. */
+declare function validateCondition(raw: unknown, context: string): Condition;
+/** Walk a validated condition over a context to a boolean. Never throws on data shape. */
+declare function evaluateCondition(condition: Condition, context: unknown): boolean;
+//#endregion
 //#region src/runtime/graph/registry.d.ts
 /**
  * `Registry<T>` — the ONE name→thing shape for the graph engine.
@@ -148,6 +170,97 @@ declare function kindHandle(kind: Pick<NodeKind, 'id' | 'version'>): RegistryHan
  */
 declare function narrowEffects<Effects extends ReadonlyArray<EffectName>>(declared: Effects, provided: Readonly<Record<string, unknown>>, context: string): EffectContext<Effects>;
 //#endregion
+//#region src/runtime/graph/projection.d.ts
+type Projection = {
+  readonly path: string;
+} | {
+  readonly pick: ReadonlyArray<string>;
+} | {
+  readonly map: string;
+} | {
+  readonly filter: Condition;
+} | {
+  readonly first: true;
+} | {
+  readonly last: true;
+} | {
+  readonly count: true;
+};
+/** Validate a projection: exactly one known operator, its argument well-formed. */
+declare function validateProjection(raw: unknown, context: string): Projection;
+/**
+ * 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.
+ */
+declare function applyProjection(value: unknown, projection: Projection, context: string): unknown;
+//#endregion
+//#region src/runtime/graph/definition.d.ts
+/** Which gating-edge outcomes release a node (adopted from ADC, agent-runtime#968). */
+declare const JOIN_RULES: readonly ["all", "any", "any_failed", "all_done"];
+type JoinRule = (typeof JOIN_RULES)[number];
+/** ADC-compatible visit backstop: nothing may be ENTERED more than this many times. */
+declare const DEFAULT_MAX_NODE_VISITS = 25;
+/** The hard ceiling an author's `maxVisits`/`maxNodeVisits` override may reach. */
+declare const MAX_MAX_NODE_VISITS = 100;
+type GraphEdgeKind = 'delegates' | 'analyzes' | 'data';
+interface EngineGraphNode {
+  readonly id: string;
+  /** `<id>/v<n>` into the engine's kind registry. */
+  readonly kind: string;
+  /** This node's config, validated by its kind's `validateConfig` at compile. */
+  readonly config?: unknown;
+  /** Per-node flags — properties of the node, never of its kind (agent-runtime#970). */
+  readonly flags?: NodeFlags;
+  /** Node-level port declarations, merged OVER the kind's. A kind whose surface depends on its
+   *  config (a script) declares ports here; a typed kind's declared ports stay authoritative. */
+  readonly ports?: {
+    readonly inputs?: ReadonlyArray<PortSpec>;
+    readonly outputs?: ReadonlyArray<PortSpec>;
+  };
+  /** Which inbound gating-edge outcomes release this node. Default `all`. */
+  readonly join?: JoinRule;
+  /** Entered more than this many times fails the run `cycle-budget-exceeded`. */
+  readonly maxVisits?: number;
+  /** This node's completion check; a terminal without one (or a kind/graph default) refuses. */
+  readonly deliverable?: DeliverableSpec<unknown>;
+  /** Force-mark a terminal. Absent, a node with no outbound gating edge is terminal. */
+  readonly terminal?: boolean;
+  /** Profile fields merged over the engine-authored `{ name: id }` for this node's spawns. */
+  readonly profile?: Readonly<Partial<AgentProfile>>;
+  /** Per-instance reservation for this node's spawns; falls back to the run's `perNode`. */
+  readonly budget?: Budget;
+}
+interface EngineGraphEdge {
+  /** Stable id for the ledger; defaults to `<from>-><to>#<ordinal>`. */
+  readonly id?: string;
+  readonly kind: GraphEdgeKind;
+  readonly from: {
+    readonly node: string;
+    readonly port?: string;
+  };
+  readonly to: {
+    readonly node: string;
+    readonly port?: string;
+  };
+  /** Evaluated over the source's settle context; absent = satisfied by completion. */
+  readonly guard?: Condition;
+  /** `data` edges only: ONE pure reshape of the admitted payload. */
+  readonly projection?: Projection;
+  /** Refuses the traversal past this many firings (ledgered `unpropagated`). */
+  readonly maxTraversals?: number;
+  /** `delegates`/`analyzes`: the versioned directive appended to the target's task. */
+  readonly directive?: PromptHandle;
+}
+interface EngineGraphSpec {
+  readonly nodes: ReadonlyArray<EngineGraphNode>;
+  readonly edges: ReadonlyArray<EngineGraphEdge>;
+  /** Root node for the graph-level completion check. Defaults to the single entry node. */
+  readonly root?: string;
+  /** Becomes the ROOT node's completion check when the root declares none (#973). */
+  readonly deliverable?: DeliverableSpec<unknown>;
+  readonly maxNodeVisits?: number;
+}
+//#endregion
 //#region src/runtime/graph/engine.d.ts
 interface GraphEngineOptions {
   /** Kinds to register beside the core set. A host adds its own here; nothing is global. */
@@ -174,6 +287,49 @@ interface GraphEngine {
  */
 declare function createGraphEngine(options: GraphEngineOptions): GraphEngine;
 //#endregion
+//#region src/runtime/graph/compile.d.ts
+interface CompiledEdge {
+  readonly id: string;
+  readonly spec: EngineGraphEdge;
+  readonly fromPort: string;
+  readonly toPort: string;
+}
+interface CompiledNode {
+  readonly id: string;
+  readonly kind: NodeKind;
+  readonly config: unknown;
+  readonly join: JoinRule;
+  readonly maxVisits: number;
+  readonly oracle: boolean;
+  readonly pure: boolean;
+  readonly terminal: boolean;
+  /** The check this node must pass to count DELIVERED; resolved per #973. */
+  readonly deliverable?: DeliverableSpec<unknown>;
+  readonly inbound: ReadonlyArray<CompiledEdge>;
+  readonly outbound: ReadonlyArray<CompiledEdge>;
+  readonly spec: EngineGraphSpec['nodes'][number];
+}
+interface CompiledGraph {
+  readonly nodes: ReadonlyMap<string, CompiledNode>;
+  readonly edges: ReadonlyArray<CompiledEdge>;
+  readonly entries: ReadonlyArray<string>;
+  readonly terminals: ReadonlyArray<string>;
+  readonly root: string;
+  readonly maxNodeVisits: number;
+}
+/**
+ * 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.
+ */
+declare function schemaAccepts(source: JsonSchema, target: JsonSchema, depth?: number): boolean;
+/**
+ * Lower an authored graph against an engine's kind registry into the schedulable form, refusing
+ * every structural defect before any spend.
+ */
+declare function compileGraph(engine: GraphEngine, spec: EngineGraphSpec, context?: string): CompiledGraph;
+//#endregion
 //#region src/runtime/graph/kinds.d.ts
 interface AgentKindConfig {
   /** Where this node's profile runs. Omit to inherit the engine's default backend. */
@@ -237,5 +393,75 @@ declare function subgraphKind(): NodeKind<{
   readonly graph: unknown;
 }>;
 //#endregion
-export { type AgentKindConfig, type BudgetMode, type EffectContext, type EffectName, type GraphEngine, type GraphEngineOptions, type JsonSchema, type NodeFlags, type NodeKind, type OnCrash, type PortSpec, type Registered, type Registry, type RegistryHandle, type ScriptBody, type ScriptKindConfig, type SupervisorKindConfig, agentKind, createGraphEngine, createRegistry, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, scriptKind, subgraphKind, supervisorKind, validateNodeKind };
+//#region src/runtime/graph/scheduler.d.ts
+type GraphRunReason = 'all-children-down' | 'budget-exhausted' | 'aborted' | 'driver-failed' | 'cycle-budget-exceeded' | 'unreachable-terminal';
+/** One node settlement as the graph result reports it. */
+interface GraphNodeSettle {
+  readonly node: string;
+  readonly visit: number;
+  readonly status: 'done' | 'down';
+  /** The node's completion check verdict; `undefined` when the node declares no check. */
+  readonly valid?: boolean;
+  readonly out?: unknown;
+  readonly outRef?: string;
+  readonly reason?: string;
+}
+/** One ledgered edge firing (or refusal) — the run's observable data flow. */
+interface GraphEdgeTraversal {
+  readonly edge: string;
+  readonly kind: 'delegates' | 'analyzes' | 'data';
+  readonly from: string;
+  readonly to: string;
+  readonly traversal: number;
+  readonly outcome: 'delivered' | 'empty' | 'unpropagated';
+  readonly directive?: string;
+  readonly port?: string;
+  readonly reason?: string;
+}
+type GraphRunResult = {
+  readonly kind: 'winner';
+  readonly out: unknown;
+  readonly terminals: ReadonlyArray<GraphNodeSettle>;
+  readonly settles: ReadonlyArray<GraphNodeSettle>;
+  readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
+} | {
+  readonly kind: 'no-winner';
+  readonly reason: GraphRunReason;
+  readonly error?: {
+    readonly name: string;
+    readonly message: string;
+  };
+  readonly terminals: ReadonlyArray<GraphNodeSettle>;
+  readonly settles: ReadonlyArray<GraphNodeSettle>;
+  readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
+  /** Nodes provably stuck when the run ended: every upstream settled, no release possible. */
+  readonly unreachable: ReadonlyArray<string>;
+};
+interface GraphRunOptions {
+  /** The run's conserved pool. */
+  readonly budget: Budget;
+  /** Default per-instance reservation for nodes that declare no `budget` of their own.
+   *  Required when any such node exists — the engine invents no split. */
+  readonly perNode?: Budget;
+  readonly journal?: SpawnJournal;
+  readonly blobs?: ResultBlobStore;
+  /** Resolves `delegates`/`analyzes` directives; required when any edge carries one. */
+  readonly prompts?: PromptRegistry;
+  /** How terminal settles reduce to `out`. Default `bestDelivered`. */
+  readonly finalizer?: 'bestDelivered' | 'collectDelivered' | SupervisorFinalizer;
+  readonly signal?: AbortSignal;
+  readonly now?: () => number;
+  readonly runId?: string;
+}
+/** 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. */
+declare function admitPayload(value: unknown): unknown;
+/**
+ * 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.
+ */
+declare function runEngineGraph(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): Promise<GraphRunResult>;
+//#endregion
+export { type AgentKindConfig, type BudgetMode, CONDITION_OPS, type CompiledEdge, type CompiledGraph, type CompiledNode, type Condition, type ConditionLeaf, type ConditionOp, DEFAULT_MAX_NODE_VISITS, type EffectContext, type EffectName, type EngineGraphEdge, type EngineGraphNode, type EngineGraphSpec, type GraphEdgeKind, type GraphEdgeTraversal, type GraphEngine, type GraphEngineOptions, type GraphNodeSettle, type GraphRunOptions, type GraphRunReason, type GraphRunResult, JOIN_RULES, type JoinRule, type JsonSchema, MAX_MAX_NODE_VISITS, type NodeFlags, type NodeKind, type OnCrash, type PortSpec, type Projection, type Registered, type Registry, type RegistryHandle, type ScriptBody, type ScriptKindConfig, type SupervisorKindConfig, admitPayload, agentKind, applyProjection, compileGraph, createGraphEngine, createRegistry, evaluateCondition, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, validateCondition, validateNodeKind, validateProjection };
 //# sourceMappingURL=graph.d.ts.map