@particle-academy/fancy-flow 0.45.0 → 0.46.0

package/dist/durable/index.d.ts

@@ -0,0 +1,490 @@
+import { F as FlowGraph, R as RunEvent, b as RunIdentity, E as ExecutorRegistry, a as FlowNode, N as NodeExecutor, c as RunIdentityJson } from '../types-Jx1TwehV.js';
+import { a as RunResult } from '../run-flow-CQvTDBYk.js';
+import { b as PauseSignal } from '../pause-9iT4tCEV.js';
+import '@xyflow/react';
+
+/**
+ * What a durable run remembers, and the seam a real database plugs into.
+ *
+ * A durable run is bookkeeping plus one hard requirement: **the claim is a
+ * unique constraint, not a check.** Two workers racing for the same node must
+ * produce a no-op, not a double run, and only the storage layer can promise
+ * that. So {@link NodeClaimStore} is an interface with exactly the operations a
+ * driver needs, and an adapter implements it over `INSERT … ON CONFLICT DO
+ * NOTHING` (or its dialect's spelling).
+ *
+ * {@link InMemoryClaimStore} is the reference implementation and is genuinely
+ * useful: it makes the whole per-node driver testable, and it is correct for a
+ * single-process durable run.
+ *
+ * This is a port of `fancy_flow.durable.state`, which is itself the Python twin
+ * of `fancy-flow-php`'s `NodeClaims` + `workflow_run_nodes`. Three runtimes,
+ * one design — see `.ai/plans/fancy-flow-run-identity-and-steps.md`.
+ */
+/** Where one node of one run has got to. */
+declare const NodeRunStatus: {
+    readonly CLAIMED: "claimed";
+    readonly COMPLETED: "completed";
+    readonly SKIPPED: "skipped";
+    readonly FAILED: "failed";
+    readonly PAUSED: "paused";
+};
+type NodeRunStatusValue = (typeof NodeRunStatus)[keyof typeof NodeRunStatus];
+/**
+ * A node the frontier may treat as decided.
+ *
+ * A FAILED node is settled too — it will never publish, so its successors skip
+ * rather than wait forever.
+ */
+declare const SETTLED: readonly NodeRunStatusValue[];
+/**
+ * One node's row.
+ *
+ * `ports` are the ports the engine's own `node-output` events reported. They
+ * are STORED, never recomputed: a second copy of the routing table would agree
+ * for a year and then disagree on one branch.
+ */
+type NodeState = {
+    status: NodeRunStatusValue;
+    ports: readonly string[];
+    output?: unknown;
+    error?: string | null;
+    owner?: string | null;
+    /** 1-based, incremented when an owner re-enters its own claim. */
+    attempts: number;
+    /** ISO-8601 UTC of the FIRST claim. Never updated — it is the retry clock. */
+    firstAttemptAt: string;
+};
+/**
+ * The persistence a per-node driver needs.
+ *
+ * Six operations. An adapter over Postgres, SQLite or Redis implements these
+ * and nothing else; every rule about WHICH node may run lives in `frontier.ts`,
+ * which reads only {@link state}.
+ */
+interface NodeClaimStore {
+    /**
+     * Take exclusive ownership of one node of one run.
+     *
+     * MUST be atomic against concurrent callers, and MUST return `true` for a
+     * caller re-entering its OWN claim — that is what lets a job's retry resume
+     * instead of deadlocking against the row it wrote itself.
+     */
+    claim(runKey: string, nodeId: string, owner: string): boolean | Promise<boolean>;
+    state(runKey: string): Record<string, NodeState> | Promise<Record<string, NodeState>>;
+    complete(runKey: string, nodeId: string, output: unknown, ports: readonly string[]): void | Promise<void>;
+    skip(runKey: string, nodeId: string): void | Promise<void>;
+    fail(runKey: string, nodeId: string, error: string): void | Promise<void>;
+    pause(runKey: string, nodeId: string, reason: string): void | Promise<void>;
+}
+/**
+ * A correct, single-process {@link NodeClaimStore}.
+ *
+ * JavaScript's single-threaded event loop makes the claim atomic for free —
+ * there is no interleaving point inside a synchronous method. It is NOT durable
+ * across a restart, which is the honest limit: use it for tests, for a CLI run,
+ * and for a worker that genuinely owns the whole run.
+ */
+declare class InMemoryClaimStore implements NodeClaimStore {
+    private readonly runs;
+    claim(runKey: string, nodeId: string, owner: string): boolean;
+    state(runKey: string): Record<string, NodeState>;
+    complete(runKey: string, nodeId: string, output: unknown, ports: readonly string[]): void;
+    skip(runKey: string, nodeId: string): void;
+    fail(runKey: string, nodeId: string, error: string): void;
+    pause(runKey: string, nodeId: string, reason: string): void;
+    /**
+     * Drop a paused node's claim so a recorded answer can re-run it.
+     *
+     * Not part of the interface: resuming a human gate is the host's decision and
+     * its storage's business. Provided here because the in-memory store is also
+     * what the tests resume through.
+     */
+    release(runKey: string, nodeId: string): void;
+    private run;
+    /** The row for one node, created as CLAIMED if a driver never claimed it. */
+    private entry;
+}
+declare function isSettled(status: string | undefined): boolean;
+
+/**
+ * Which nodes can run RIGHT NOW, given what has already settled.
+ *
+ * ## Why this is not a second engine
+ *
+ * `runFlow` walks a Kahn topological order and, at each node, runs it when at
+ * least one incoming edge is active. That is a total order because one process
+ * executes every node. Split the graph across jobs and the same rule has to be
+ * asked the other way round — not "what is next" but "what is unblocked" —
+ * which is this module.
+ *
+ * The rule is the engine's, restated:
+ *
+ * - every direct predecessor has SETTLED (in topological order the engine has
+ *   already settled all of them by the time it reaches a node);
+ * - and either the node has no incoming edges, or at least one incoming edge is
+ *   ACTIVE — its source completed and published on that edge's source handle.
+ *
+ * A node whose predecessors have all settled with no active edge is what the
+ * engine reports as `idle/skipped`. Skipping SETTLES it, which can in turn
+ * unblock — or skip — its own successors, so the pass repeats until nothing
+ * changes. That cascade is how a dead branch collapses without leaving the run
+ * stuck.
+ *
+ * ## The one thing it does NOT decide
+ *
+ * Which ports a result activated. Those rules (`__port`, `branch`, declared
+ * outputs, the kind's ports, the `out` fallback) live in the engine and stay
+ * there: this reads the ports back off the `node-output` events the engine
+ * emitted when the node ran, stored on the claim row.
+ */
+
+type FrontierResult = {
+    ready: string[];
+    skipped: string[];
+};
+declare const Frontier: {
+    compute(graph: FlowGraph, state: Record<string, NodeState>): FrontierResult;
+    /** Has every node settled? The run is finished when it has. */
+    isComplete(graph: FlowGraph, state: Record<string, NodeState>): boolean;
+    /**
+     * Is any node still held by a worker, or parked for a person?
+     *
+     * An empty frontier means something different depending on this: with work in
+     * flight the run is simply waiting, and whichever job finishes will advance
+     * it. With nothing in flight and nodes still unsettled, the graph cannot
+     * progress at all — which is a stuck run, and must be reported rather than
+     * waited on.
+     */
+    hasWorkInFlight(state: Record<string, NodeState>): boolean;
+    /** Persist the skip cascade so the next pass does not recompute it. */
+    settleSkips(store: NodeClaimStore, runKey: string, skipped: readonly string[]): Promise<void>;
+};
+
+/**
+ * Run ONE node of a graph — through the real engine, not around it.
+ *
+ * ## The problem this solves
+ *
+ * A per-node driver has to hand a node exactly the inputs it would have
+ * received mid-run: the right values, on the right target handles, from the
+ * right *active* edges. Those rules are the engine's (`collectInputs`,
+ * `activatedPorts`, the merge-after-decision contract, the `out` fallbacks),
+ * and they are the reason the three runtimes agree. Re-implementing them here
+ * would be a second engine wearing a driver's clothes, and the two would drift.
+ *
+ * ## What it does instead
+ *
+ * It replays the graph with `runFlow` untouched:
+ *
+ * - every node already completed is fed back as `resumeOutputs`, so the engine
+ *   republishes it on the same ports and routes exactly as it did the first
+ *   time;
+ * - every node EXCEPT the target is bound, by node id, to a boundary executor
+ *   that aborts — and a node-id binding outranks every kind binding and the
+ *   `*` fallback, so the fence holds whatever a host registered;
+ * - so the engine walks its own topological order, skips its own dead branches,
+ *   collects the target's inputs its own way, runs the target — and stops at
+ *   the next thing it would have run.
+ *
+ * The target's output is `result.outputs[nodeId]`, and the ports it activated
+ * arrive as the engine's own `node-output` events. Nothing about routing is
+ * recomputed here.
+ *
+ * ## The cost, stated plainly
+ *
+ * Replaying the completed prefix is O(nodes) per node, so a run is O(nodes²) in
+ * bookkeeping. The republish executes nothing — it re-publishes stored values —
+ * so for the graph sizes workflows actually have this is noise next to a single
+ * queue round trip. It buys exact fidelity to the engine, which is not
+ * negotiable, and one implementation of the routing rules instead of two.
+ */
+
+/**
+ * The abort reason the boundary executor uses.
+ *
+ * Not a failure: it is the engine telling us it reached a node this job is not
+ * responsible for.
+ */
+declare const BOUNDARY = "fancy-flow:node-boundary";
+type ReplayResult = {
+    result: RunResult;
+    /** node id -> the ports its output activated, from the engine's own events. */
+    ports: Record<string, string[]>;
+    outputOf(nodeId: string): unknown;
+    portsOf(nodeId: string): string[];
+};
+type ReplayOptions = {
+    resumeOutputs?: Record<string, unknown>;
+    initialInputs?: Record<string, Record<string, unknown>>;
+    onEvent?: (event: RunEvent) => void;
+    depth?: number;
+    run?: RunIdentity;
+};
+/**
+ * Replay `graph` up to and through `nodeId`.
+ *
+ * Pass `nodeId = null` to PROBE: every node is a boundary, so nothing executes
+ * and the engine reports only what it can determine structurally — a cycle, and
+ * the ports each resumed output republishes on.
+ */
+declare function replayUpTo(graph: FlowGraph, nodeId: string | null, executors: ExecutorRegistry, options?: ReplayOptions): Promise<ReplayResult>;
+/** True when a replay ended because it reached a node it does not own. */
+declare function isBoundary(error: string | null | undefined): boolean;
+
+/**
+ * How many times a single node may be attempted.
+ *
+ * ## Why this cannot be one number
+ *
+ * A run-wide `tries` setting forces every workflow to pick between two bad
+ * answers. At 1, a single flaky LLM or HTTP call takes the whole run down.
+ * Above 1, the retry replays from the last checkpoint and everything already
+ * done runs again — including the nodes that must not: `git_pr_open` opens a
+ * second pull request.
+ *
+ * Per-node jobs make the question per node, which is where it always belonged.
+ * A node declaring `sideEffects: unsafe-to-replay` is pinned to ONE attempt and
+ * no backoff. Everything else takes the configured tries, or a per-kind
+ * override.
+ *
+ * Undeclared side effects are treated as the configured default rather than
+ * assumed safe: this decides retries, and inventing a safety claim on a node
+ * author's behalf is how a retry loop ends up posting the same webhook twice.
+ */
+
+/** A node that is not safe to run twice. Same vocabulary as the node manifest. */
+declare const UNSAFE_TO_REPLAY = "unsafe-to-replay";
+type RetryPolicyOptions = {
+    tries?: number;
+    backoffSeconds?: number;
+    /** kind id -> tries. Keyed by any spelling; every id is checked. */
+    perKind?: Record<string, number>;
+};
+declare class RetryPolicy {
+    readonly tries: number;
+    readonly backoffSeconds: number;
+    readonly perKind: Record<string, number>;
+    constructor(options?: RetryPolicyOptions);
+    triesFor(node: FlowNode): number;
+    backoffFor(node: FlowNode): number;
+    static isUnsafeToReplay(node: FlowNode): boolean;
+}
+
+/**
+ * Human gates that cannot be walked past — and that hold no worker.
+ *
+ * ## The directive these implement
+ *
+ * A node that waits on a person must not occupy a worker, a connection or a
+ * process while it waits. So the job for a human gate does its work by
+ * **emitting the request** and then **finishing**: the run is persisted as
+ * parked, the job returns, the worker takes the next thing off the queue. When
+ * the person answers, *that* enqueues the continuation.
+ *
+ * Mechanically the gate aborts with an encoded pause, which is a *return*, not
+ * a block. Nothing in this file sleeps, polls or awaits a person.
+ *
+ * ## Fail closed, and why
+ *
+ * A gate pauses because it **is** a human node, not because its input port
+ * happens to be empty. This is not a preference; it is a fix. Both peer
+ * runtimes once decided whether to pause by reading their own input, so a
+ * pre-filled `values` or `approved` value ran the flow straight past the person
+ * it was waiting for — silently, with the run reporting success.
+ *
+ * Restoring the old behaviour is possible, explicit, and per node:
+ * `autoAnswerFromInput`. Turn it on for a step that is a form when a human is
+ * present and a pass-through when an upstream node already produced the answer.
+ * On an approval node, weigh it harder: it means the graph, not a person, can
+ * approve.
+ *
+ * ## The other half of the fix
+ *
+ * Recording an answer for a node the run is not parked on THROWS rather than
+ * queueing a write nobody reads. See {@link Submissions.record}.
+ */
+
+/** An answer was recorded for a node the run is not waiting on. */
+declare class NotAwaitingHuman extends Error {
+    constructor(message: string);
+}
+/**
+ * Answers recorded for human gates, keyed by node id.
+ *
+ * Deliberately separate from the run's inputs. Keeping them in one bag is
+ * precisely what let a pre-filled input satisfy a gate.
+ */
+declare class Submissions {
+    private readonly answers;
+    /** The node the run is currently parked on, if any. */
+    awaiting: string | null;
+    /**
+     * Record an answer for the node the run is parked on.
+     *
+     * Throws when the run is not waiting on that node. A queued answer for a node
+     * that never paused is a write nobody reads — and it looks, from the outside,
+     * exactly like a submission that worked.
+     */
+    record(nodeId: string, value: unknown): void;
+    answered(nodeId: string): boolean;
+    answer(nodeId: string): unknown;
+    park(nodeId: string): void;
+}
+/** `user_input` — pauses until a submission for THIS node is recorded. */
+declare function durableUserInput(submissions: Submissions): NodeExecutor;
+/** `human_approval` — pauses until a decision for THIS node is recorded. */
+declare function durableApproval(submissions: Submissions): NodeExecutor;
+
+/**
+ * The per-node driver, with the queue left out.
+ *
+ * This is the whole of "how a queued run branches", minus the transport. It
+ * owns two operations and nothing else:
+ *
+ * `advance()`
+ *   Ask the frontier what is unblocked, settle the skip cascade, and report the
+ *   ready node ids. A queue adapter dispatches one job per id.
+ *
+ * `runNode()`
+ *   Claim one node, replay the graph through the real engine fenced to that
+ *   node, and checkpoint the output plus the ports the ENGINE said it
+ *   activated.
+ *
+ * Everything a queue library would add — enqueue, retry scheduling, worker
+ * lifecycle — sits outside. That separation is the point: it makes the subtle
+ * part (which node may run, and with what inputs) testable in-process, with no
+ * broker, and identical under every adapter. **A queue adapter therefore
+ * contains no workflow logic at all.** That is the test: if an adapter needs to
+ * know what a port is, the seam is in the wrong place.
+ *
+ * `runToCompletion` drives both in one process. It is a real durable runner,
+ * not a toy: with a persistent `NodeClaimStore` it survives a crash exactly as
+ * a queued run does, because the crash-resume behaviour lives in the
+ * checkpoints rather than in the loop.
+ *
+ * ## No worker waits on a person
+ *
+ * A human gate returns `paused`. `runToCompletion` returns immediately when it
+ * sees one — it does not spin, sleep or poll. The run is parked in the store,
+ * the process is free, and a recorded answer is what starts the next job.
+ */
+
+/** What happened to one node. */
+type NodeOutcome = {
+    nodeId: string;
+    status: "not-claimed" | "completed" | "skipped" | "failed" | "paused";
+    output?: unknown;
+    ports?: string[];
+    error?: string;
+    pause?: PauseSignal;
+    /** False when another worker got there first. A lost race is a NO-OP. */
+    claimed: boolean;
+    /** 1-based attempt this execution ran as. */
+    attempt: number;
+    /**
+     * `true` when this attempt failed and the policy still allows another.
+     *
+     * The claim row is left CLAIMED in that case, deliberately: a queue adapter
+     * re-dispatches the job with the SAME owner token and the retry re-enters the
+     * claim it already holds. Recording FAILED here instead would settle the
+     * node, which SKIPS everything downstream — a run reporting a tidy finish
+     * having done half its work.
+     */
+    retryable?: boolean;
+};
+type DurableRunResult = {
+    ok: boolean;
+    outputs: Record<string, unknown>;
+    error?: string;
+    pause?: PauseSignal;
+    paused: boolean;
+};
+type CoordinatorOptions = {
+    graph: FlowGraph;
+    executors: ExecutorRegistry;
+    /**
+     * The run's stable identity. A bare string is taken as the run key.
+     *
+     * Required — not defaulted. A durable run without a stable key cannot key an
+     * idempotent write, and minting one per construction would hand a retrying
+     * host a different key each time.
+     */
+    run: string | RunIdentity | RunIdentityJson;
+    store?: NodeClaimStore;
+    initialInputs?: Record<string, Record<string, unknown>>;
+    retry?: RetryPolicy;
+    onEvent?: (event: RunEvent) => void;
+};
+declare class Coordinator {
+    readonly graph: FlowGraph;
+    readonly executors: ExecutorRegistry;
+    readonly run: RunIdentity;
+    readonly store: NodeClaimStore;
+    readonly initialInputs: Record<string, Record<string, unknown>>;
+    readonly retry: RetryPolicy;
+    private readonly onEvent?;
+    constructor(options: CoordinatorOptions);
+    get runKey(): string;
+    /**
+     * Which nodes may be dispatched right now.
+     *
+     * Also settles the skip cascade, because a skip is a decision the frontier
+     * just made and a second caller must not make it again.
+     */
+    advance(): Promise<string[]>;
+    /**
+     * Claim, execute and checkpoint one node.
+     *
+     * The claim is taken FIRST. Two workers racing for the same node produce one
+     * execution and one no-op, and the loser learns that from the store rather
+     * than from a duplicate side effect.
+     *
+     * `owner` is the token that lets a job's own retry re-enter its claim instead
+     * of deadlocking against the row it wrote itself — pass the SAME token across
+     * a job's attempts.
+     */
+    runNode(nodeId: string, owner?: string): Promise<NodeOutcome>;
+    /**
+     * Drive the graph here, in this process, one node at a time.
+     *
+     * Every checkpoint is written exactly as a queued run writes it, so a crash
+     * mid-loop resumes from the same place a crashed worker would.
+     *
+     * Retries honour {@link RetryPolicy}: a node declaring `unsafe-to-replay`
+     * gets one attempt whatever the policy says, and the retry re-enters the same
+     * claim with the same owner token — so the step key it derives is unchanged,
+     * which is what makes the retry idempotent rather than duplicative.
+     */
+    runToCompletion(maxPasses?: number): Promise<DurableRunResult>;
+    /**
+     * Checkpointed outputs, in the graph's own node order.
+     *
+     * Ordered by the graph rather than by completion so two runs of the same
+     * workflow produce comparable output maps even when nodes finished in a
+     * different order.
+     */
+    outputs(): Promise<Record<string, unknown>>;
+    /** The checkpointed run, in the shape a single-process run returns. */
+    asRunResult(): Promise<RunResult>;
+    private runNodeWithRetries;
+    /**
+     * The identity handed to the node about to execute.
+     *
+     * `attempt` and `firstAttemptAt` come off the CLAIM ROW, so they describe
+     * this step rather than the run — which is what makes the retry window check
+     * exact instead of conservative.
+     */
+    private identityFor;
+    private completedOutputs;
+    /**
+     * Forward only the events the target node produced.
+     *
+     * A replay re-emits the whole completed prefix. Passing that through would
+     * show a consumer every node running again on every job — the run feed would
+     * report a 20-node workflow as 200 status changes.
+     */
+    private forward;
+}
+
+export { BOUNDARY, Coordinator, type CoordinatorOptions, type DurableRunResult, Frontier, type FrontierResult, InMemoryClaimStore, type NodeClaimStore, type NodeOutcome, NodeRunStatus, type NodeRunStatusValue, type NodeState, NotAwaitingHuman, type ReplayOptions, type ReplayResult, RetryPolicy, type RetryPolicyOptions, SETTLED, Submissions, UNSAFE_TO_REPLAY, durableApproval, durableUserInput, isBoundary, isSettled, replayUpTo };