@tangle-network/agent-runtime 0.164.0 → 0.165.0

package/dist/graph.d.ts

@@ -1,6 +1,6 @@
-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 { $l as MakeWorkerAgent, If as DeliverableSpec, an as PromptRegistry, bo as SupervisorAgentDeps, in as PromptHandle, mu as WorkerSpawnContext, os as SupervisorFinalizer } from "./index-BGQtpQuJ.js";
+import { H as SpawnJournal, K as Spend, V as SpawnEvent, i as Budget, j as ResultBlobStore, t as Agent } from "./types-DjVO-p7R.js";
+import { o as ExecutorConfig } from "./runtime-B0HZbuEv.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`. */
@@ -330,6 +330,121 @@ declare function schemaAccepts(source: JsonSchema, target: JsonSchema, depth?: n
  */
 declare function compileGraph(engine: GraphEngine, spec: EngineGraphSpec, context?: string): CompiledGraph;
 //#endregion
+//#region src/runtime/graph/scheduler-types.d.ts
+/** Result vocabulary shared by the scheduler and the fold (agent-runtime#973, #974, #976). */
+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>;
+} | {
+  /** Every live branch parked on a host wake: a legitimate terminal state for an offline run.
+   *  Restart over the same journal and `resume(token, payload)` to continue (#976). */
+  readonly kind: 'suspended';
+  readonly tokens: ReadonlyArray<string>;
+  readonly terminals: ReadonlyArray<GraphNodeSettle>;
+  readonly settles: ReadonlyArray<GraphNodeSettle>;
+  readonly ledger: ReadonlyArray<GraphEdgeTraversal>;
+};
+//#endregion
+//#region src/runtime/graph/fold.d.ts
+type FoldEdgeState = 'pending' | 'satisfied' | 'dead' | 'failed';
+interface FoldEdge {
+  state: FoldEdgeState;
+  /** Set by a `join-state` whose wave this edge was pending inside; cleared when the in-flight
+   *  completion it refers to settles (absorbed, never re-released). */
+  consumedOnce: boolean;
+  /** Delivered consumptions — what the per-edge cap counts. */
+  traversals: number;
+  /** How many of the source's settles this edge has accounted for — by a journaled verdict or by
+   *  an absorption. The idempotence key: a kill between a settle and its verdicts re-judges ONLY
+   *  the unaccounted edges on restart, never a judged or absorbed one twice. */
+  judgedSourceSettles: number;
+  /** The admitted source payload this state reflects (the source settle's outRef). */
+  payloadRef?: string;
+  capped: boolean;
+}
+type FoldInstanceStatus = 'released' | 'live' | 'done' | 'down' | 'suspended';
+interface FoldInstance {
+  readonly node: string;
+  readonly instance: string;
+  readonly visit: number;
+  inputRef?: string;
+  status: FoldInstanceStatus;
+  settle?: GraphNodeSettle;
+}
+interface FoldSuspension {
+  readonly token: string;
+  readonly node: string;
+  readonly instance: string;
+  readonly onExpire: 'wait' | 'fail' | 'default';
+  readonly expiresAtMs?: number;
+  readonly defaultRef?: string;
+  status: 'pending' | 'woken' | 'expired';
+}
+interface FoldNode {
+  visits: number;
+  blocked: boolean;
+  settles: GraphNodeSettle[];
+}
+interface GraphFoldState {
+  readonly nodes: Map<string, FoldNode>;
+  readonly edges: Map<string, FoldEdge>;
+  /** Every node instance the journal knows, keyed by `<node>#<visit>`. */
+  readonly instances: Map<string, FoldInstance>;
+  /** Kernel node id → engine instance label, from `spawned`. */
+  readonly spawnedIds: Map<string, string>;
+  readonly suspensions: Map<string, FoldSuspension>;
+  readonly exhaustedEdges: Set<string>;
+}
+/** The reducer's zero: every node unvisited, every edge pending, nothing suspended. */
+declare function emptyFoldState(compiled: CompiledGraph): GraphFoldState;
+/**
+ * Apply ONE journal event. The live scheduler calls this right after each append; the restart path
+ * calls it over the loaded journal. Unknown kernel events are ignored — the engine folds only what
+ * it understands, exactly as the kernel's replay skips the engine's events.
+ */
+declare function applyGraphFoldEvent(state: GraphFoldState, ev: SpawnEvent, compiled: CompiledGraph): void;
+/** Fold a loaded journal (append order) into scheduler state. */
+declare function foldGraphJournal(events: ReadonlyArray<SpawnEvent>, compiled: CompiledGraph): GraphFoldState;
+//#endregion
 //#region src/runtime/graph/kinds.d.ts
 interface AgentKindConfig {
   /** Where this node's profile runs. Omit to inherit the engine's default backend. */
@@ -394,49 +509,26 @@ declare function subgraphKind(): NodeKind<{
 }>;
 //#endregion
 //#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;
+/** Engine-appended `woken` ordinals start here — far above any kernel cursor counter. */
+declare const ENGINE_WOKEN_SEQ_BASE = 10000000;
+declare const SUSPEND_MARK = "__graphSuspension";
+interface SuspensionRequest {
+  readonly [SUSPEND_MARK]: true;
+  readonly onExpire: 'wait' | 'fail' | 'default';
+  /** Milliseconds from the suspension's journaling instant; absent with `onExpire: 'wait'`. */
+  readonly expiresInMs?: number;
+  readonly default?: unknown;
 }
-/** 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>;
-};
+/** What a kind's executor returns to park its node on a host wake (agent-runtime#976). */
+declare function suspended(options?: {
+  readonly onExpire?: 'wait' | 'fail' | 'default';
+  readonly expiresInMs?: number;
+  readonly default?: unknown;
+}): SuspensionRequest;
+/** 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;
 interface GraphRunOptions {
   /** The run's conserved pool. */
   readonly budget: Budget;
@@ -452,16 +544,26 @@ interface GraphRunOptions {
   readonly signal?: AbortSignal;
   readonly now?: () => number;
   readonly runId?: string;
+  /** Continue an existing journaled run. An existing tree without this refuses, like the kernel. */
+  readonly resume?: boolean;
+  /** Hold a fully-suspended run open for live `resume()` calls instead of returning
+   *  `{ kind: 'suspended' }`. Offline callers leave this off and restart later (#976). */
+  readonly waitForWakes?: boolean;
 }
-/** 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;
+/** A live run: await `done`; deliver host wakes through `resume`/`expire` (#976). */
+interface GraphRunHandle {
+  readonly done: Promise<GraphRunResult>;
+  resume(token: string, payload: unknown): Promise<void>;
+  expire(token: string): Promise<void>;
+}
+/** Run a graph to its result: `createGraphRun` awaited — the one-call form for a run that needs
+ *  no live host wakes. */
+declare function runEngineGraph(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): Promise<GraphRunResult>;
 /**
- * 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.
+ * Start (or resume) a graph run and return its handle: await `done` for the result; deliver host
+ * wakes through `resume`/`expire` while it runs (#976).
  */
-declare function runEngineGraph(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): Promise<GraphRunResult>;
+declare function createGraphRun(engine: GraphEngine, spec: EngineGraphSpec | CompiledGraph, task: string, options: GraphRunOptions): GraphRunHandle;
 //#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 };
+export { type AgentKindConfig, type BudgetMode, CONDITION_OPS, type CompiledEdge, type CompiledGraph, type CompiledNode, type Condition, type ConditionLeaf, type ConditionOp, DEFAULT_MAX_NODE_VISITS, ENGINE_WOKEN_SEQ_BASE, type EffectContext, type EffectName, type EngineGraphEdge, type EngineGraphNode, type EngineGraphSpec, type FoldEdge, type FoldEdgeState, type FoldInstance, type FoldInstanceStatus, type FoldNode, type FoldSuspension, type GraphEdgeKind, type GraphEdgeTraversal, type GraphEngine, type GraphEngineOptions, type GraphFoldState, type GraphNodeSettle, type GraphRunHandle, 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, type SuspensionRequest, admitPayload, agentKind, applyGraphFoldEvent, applyProjection, compileGraph, createGraphEngine, createGraphRun, createRegistry, emptyFoldState, evaluateCondition, foldGraphJournal, formatRegistryHandle, kindHandle, narrowEffects, parseRegistryHandle, runEngineGraph, schemaAccepts, scriptKind, subgraphKind, supervisorKind, suspended, validateCondition, validateNodeKind, validateProjection };
 //# sourceMappingURL=graph.d.ts.map