@particle-academy/fancy-flow 0.65.2 → 0.66.0

package/dist/types-JFYjPJAG.d.ts

@@ -1,333 +0,0 @@
-import { Node, Edge } from '@xyflow/react';
-
-/**
- * Who is running, which step this is, and how many times it has been tried.
- *
- * ## Why an engine needs this at all
- *
- * A node that WRITES to somebody else's system — charge a card, send a message,
- * open a pull request — can only survive a retry if the retry carries the same
- * idempotency key the first attempt did. Otherwise the provider treats the
- * second call as a new request and the customer is charged twice.
- *
- * Until this existed the executor context was `{ node, inputs, emit, abort }`,
- * which is not enough to derive one. Both obvious fallbacks are worse than
- * sending no key at all:
- *
- * - **the node id alone** is stable across retries, and also across RUNS — two
- *   legitimate payments share a key and the provider silently collapses the
- *   second into the first. A payment that never happened, reported as success;
- * - **a fresh random value** is unique per run, and also per ATTEMPT — a retry
- *   creates a second charge, which is the thing being avoided.
- *
- * ## What actually identifies a step
- *
- * Not `(run, node)`. A node legitimately executes more than once inside one
- * run: once per subflow invocation, once per iteration of a loop an executor
- * drives itself. `(run, node)` would give every one of those the same key, and
- * a provider would honour exactly one of them.
- *
- * So a step is identified by the **path of invocations that led to it**, plus
- * an optional **occurrence** for repetition at the same level:
- *
- * ```text
- * runKey ":" segment ("/" segment)*        segment := escape(id) ["#" occurrence]
- * ```
- *
- * And the part that is easy to get backwards: **`attempt` is NOT in the key.**
- * It is carried here for logging and for {@link RunIdentity.isReplaySafe}, and
- * putting it in the key would restore the exact bug the key exists to prevent.
- *
- * Pinned cross-runtime by `shared/flow-run-identity` in
- * `@particle-academy/fancy-conformance`.
- */
-/** The wire shape — what a queue job payload carries. */
-type RunIdentityJson = {
-    runKey: string;
-    path?: string[];
-    attempt?: number;
-    firstAttemptAt?: string;
-};
-/**
- * Escape one segment so the composition is injective.
- *
- * `%` FIRST, or the escaping is not reversible: escaping `/` before `%` turns a
- * literal `a%2Fb` into the same text as the escaped form of `a/b`, which is the
- * collision this exists to prevent, reintroduced by its own fix.
- */
-declare function escapeSegment(value: string): string;
-/**
- * A run, a position inside it, and how many times this position has been tried.
- *
- * Immutable. {@link descend} returns a new identity rather than mutating, so an
- * executor cannot change what its siblings see.
- */
-declare class RunIdentity {
-    /** Stable for the whole run: same across retries, resumes, workers and hosts. */
-    readonly runKey: string;
-    /**
-     * Enclosing invocation segments, outermost first, ALREADY RENDERED.
-     *
-     * Empty at the top level. A subflow pushes the invoking node's id; an
-     * executor that loops pushes `id#i`.
-     */
-    readonly path: readonly string[];
-    /**
-     * 1-based attempt of THIS logical step. Never part of the key.
-     *
-     * The durable driver sets it from the node's claim row, which is exact. A
-     * plain in-process `runFlow` gets whatever the host passed, which is
-     * run-scoped and therefore conservative — see `isReplaySafe`.
-     */
-    readonly attempt: number;
-    /** ISO-8601 UTC instant of attempt 1 of this step. */
-    readonly firstAttemptAt: string;
-    constructor(runKey: string, path?: readonly string[], attempt?: number, firstAttemptAt?: string);
-    /**
-     * The identity of one execution of one node — stable across retries of that
-     * execution, distinct from every other execution of the same node.
-     *
-     * Pass `occurrence` when an executor runs the same node more than once at the
-     * same level (a loop body, one item of a fan-out it drives itself).
-     */
-    stepKey(nodeId: string, occurrence?: number | null): string;
-    /**
-     * A child identity for work nested inside this step.
-     *
-     * `subflow` pushes the invoking node's id, so a node inside the child graph
-     * cannot collide with a same-named node in the parent. Attempt and
-     * `firstAttemptAt` are carried down unchanged: the nested work happens inside
-     * this step's attempt, and shares its clock.
-     */
-    descend(segment: string, occurrence?: number | null): RunIdentity;
-    /** A copy on a different attempt, first-attempt clock preserved. */
-    withAttempt(attempt: number, firstAttemptAt?: string): RunIdentity;
-    /**
-     * May this attempt reuse the step key and still be deduplicated?
-     *
-     * Providers forget idempotency keys — Stripe after 24 hours. Past that
-     * window, resending the key creates a second charge and sending a fresh one
-     * creates a second charge, so **the caller must refuse rather than pick
-     * between them**: a loud stuck run beats a silent double write.
-     *
-     * `true` on attempt 1 whatever the elapsed time — nothing was sent on an
-     * earlier attempt, so there is nothing for the provider to have forgotten.
-     * That is what lets a run park on a human gate for a week and then write.
-     *
-     * `windowSeconds: null` means the provider does not expire keys. `0` means
-     * it does not dedupe at all, so no retry may reuse a key — it is a real
-     * window, not an absent one, and the two must not be conflated: reading `0`
-     * as `null` turns "this provider does not dedupe" into "this provider
-     * dedupes forever", which is the more dangerous of the two by a distance.
-     */
-    isReplaySafe(windowSeconds: number | null | undefined, now?: Date | string): boolean;
-    toJSON(): Required<RunIdentityJson>;
-    /** Rebuild from a queue payload. */
-    static from(value: RunIdentity | RunIdentityJson | string): RunIdentity;
-}
-
-/**
- * Public domain types for fancy-flow. Built-in nodes are layered on top of
- * @xyflow/react's `Node` so consumers can mix custom xyflow nodes alongside
- * the kit. Edges remain xyflow's standard `Edge`.
- */
-
-type FlowNodeKind = "trigger" | "action" | "decision" | "output" | "note" | "subgraph";
-/** Status surfaced on the node while a run is in progress. */
-type NodeRunStatus = "idle" | "queued" | "running" | "done" | "error";
-/** Port description on a node. Ports are visual handles xyflow can connect. */
-type PortDescriptor = {
-    id: string;
-    label?: string;
-    /** Optional logical type for hosts that want to validate connections. */
-    type?: string;
-};
-/** Common shape every kit node carries in its `data` slot. */
-type BaseNodeData = {
-    label: string;
-    description?: string;
-    /** Free-form configuration the host owns (form values, code, parameters). */
-    config?: Record<string, unknown>;
-    /** Set by the runner; hosts shouldn't edit this directly. */
-    status?: NodeRunStatus;
-    /** Optional human-readable status detail (e.g. error message, current step). */
-    statusText?: string;
-    /**
-     * Announced to a person just BEFORE this node runs — "Starting the deep
-     * analysis". Authored on the node, so a graph narrates itself without the
-     * host writing any per-node reporting code.
-     *
-     * Optional on purpose. Most nodes in a real graph are plumbing, and a run
-     * that narrates all of them buries the two or three steps anyone follows.
-     */
-    startingMsg?: string;
-    /**
-     * Announced AFTER this node finishes — "Analysis complete".
-     *
-     * Emitted only when the node SUCCEEDS. A completion message printed after a
-     * failure tells a human the opposite of what happened, in the part of the UI
-     * they trust most; failures report through `node-status` and `log`.
-     */
-    stoppingMsg?: string;
-    /** Per-node accent override, e.g. for theming a custom subclass. */
-    color?: string;
-    /** Input ports rendered on the node. Defaults vary by kind. */
-    inputs?: PortDescriptor[];
-    /** Output ports rendered on the node. Defaults vary by kind. */
-    outputs?: PortDescriptor[];
-};
-type TriggerNodeData = BaseNodeData & {
-    kind: "trigger";
-};
-type ActionNodeData = BaseNodeData & {
-    kind: "action";
-};
-type DecisionNodeData = BaseNodeData & {
-    kind: "decision";
-};
-type OutputNodeData = BaseNodeData & {
-    kind: "output";
-};
-type NoteNodeData = BaseNodeData & {
-    kind: "note";
-    body?: string;
-};
-type SubgraphNodeData = BaseNodeData & {
-    kind: "subgraph";
-    /** Ids of the nodes contained in this subgraph. */
-    childIds?: string[];
-    /** Whether the subgraph is shown collapsed (default true — children hidden). */
-    collapsed?: boolean;
-};
-type FlowNodeData = TriggerNodeData | ActionNodeData | DecisionNodeData | OutputNodeData | NoteNodeData | SubgraphNodeData;
-type FlowNode = Node<FlowNodeData>;
-type FlowEdge = Edge;
-/**
- * One value a workflow DECLARES that it accepts at run start.
- *
- * The declaration is the point. Before this existed, a caller passed
- * `initialInputs` keyed BY NODE ID — so they had to know the trigger happened
- * to be called `t`, and renaming that node broke every caller while the graph
- * itself stayed valid. Nothing reported it.
- *
- * And nothing said what a workflow accepted at all: no names, no types, no
- * defaults. An agent composing a call had nothing to read, and a misspelled key
- * did not fail — the value simply sat unused while the run reported success.
- */
-type WorkflowInput = {
-    /** What a caller passes it as. */
-    name: string;
-    /**
-     * Optional. Omitting it means "I am not asserting a shape", which must not
-     * degrade into "nothing is allowed" — an undeclared type accepts anything.
-     */
-    type?: "string" | "number" | "boolean" | "object" | "array";
-    /**
-     * The run needs a value. Satisfied by a `default`, so `required` means
-     * "this must resolve to something" rather than "the caller must type it".
-     */
-    required?: boolean;
-    /** Used when the caller omits the key. An explicit value always wins. */
-    default?: unknown;
-    description?: string;
-};
-/** A serializable graph — what hosts persist, what agents read/write. */
-type FlowGraph = {
-    nodes: FlowNode[];
-    edges: FlowEdge[];
-    /**
-     * What this workflow accepts. Callers pass a flat object BY NAME.
-     *
-     * Omitted entirely when a graph takes none, so existing saved graphs are
-     * unchanged byte for byte and every diff stays readable.
-     */
-    inputs?: WorkflowInput[];
-};
-/** Per-node executor signature. Inputs are keyed by input-port id. */
-type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
-    node: FlowNode;
-    inputs: TIn;
-    /** Stops the run if called. */
-    abort: (reason?: string) => never;
-    /** Lets the executor stream status updates and partial outputs. */
-    emit: (event: RunEvent) => void;
-    /**
-     * The registry THIS run is executing against.
-     *
-     * Handed down so an executor that starts a NESTED run gives the child the
-     * same executors as the parent. `subflow` previously ran its child against
-     * `config.executors ?? {}` — an empty registry unless the graph happened to
-     * carry one — so a host kind resolved at top level and vanished one level
-     * down, and a host that had REPLACED a builtin got the package's version in
-     * the child. Same graph, different behaviour by nesting depth, reported
-     * against the PHP twin as fancy-flow-php#7.
-     *
-     * Inheriting from the context rather than from a parameter is what makes it
-     * unforgettable: any future nesting executor gets it without opting in.
-     */
-    executors?: ExecutorRegistry;
-    /**
-     * How deep this run is nested. 0 for a top-level run; `subflow` passes
-     * depth + 1 to its child, so runaway recursion can be reported by name
-     * rather than as a stack overflow.
-     */
-    depth?: number;
-    /**
-     * Who is running, and which attempt of which step this is.
-     *
-     * `ctx.run.stepKey(ctx.node.id)` is the idempotency key for a node that
-     * writes to somebody else's system — stable across retries of this step,
-     * distinct for every other execution of the same node.
-     *
-     * `undefined` when the host supplied no identity, and that is a real
-     * answer: a write with no key must decline or accept one attempt, never
-     * invent a key. See `RunIdentity`.
-     */
-    run?: RunIdentity;
-}) => Promise<TOut> | TOut;
-type ExecutorRegistry = Partial<Record<FlowNodeKind | string, NodeExecutor>>;
-type RunEvent = {
-    type: "node-status";
-    nodeId: string;
-    status: NodeRunStatus;
-    text?: string;
-}
-/**
- * A human-facing announcement a node makes around its own execution, from
- * `data.startingMsg` / `data.stoppingMsg`. Opt-in per node: most nodes in a
- * real graph are plumbing, and narrating all of them buries the few steps a
- * person cares about.
- *
- * Deliberately NOT folded into `node-status.text`, which already carries
- * "skipped", "resumed", "lane", "annotation" and raw error strings. Those are
- * diagnostics; these are addressed to a person. A consumer rendering a
- * progress feed cannot be asked to guess which is which — that is how an
- * error string ends up shown to a user as a status update.
- */
- | {
-    type: "node-message";
-    nodeId: string;
-    phase: "start" | "end";
-    message: string;
-} | {
-    type: "node-output";
-    nodeId: string;
-    portId: string;
-    value: unknown;
-} | {
-    type: "log";
-    nodeId?: string;
-    level: "info" | "warn" | "error";
-    message: string;
-    detail?: unknown;
-} | {
-    type: "run-start";
-} | {
-    type: "run-end";
-    ok: boolean;
-} | {
-    type: "run-error";
-    error: string;
-};
-
-export { type ActionNodeData as A, type BaseNodeData as B, type DecisionNodeData as D, type ExecutorRegistry as E, type FlowGraph as F, type NodeExecutor as N, type OutputNodeData as O, type PortDescriptor as P, type RunEvent as R, type SubgraphNodeData as S, type TriggerNodeData as T, type WorkflowInput as W, type FlowNode as a, RunIdentity as b, type RunIdentityJson as c, type FlowEdge as d, type FlowNodeData as e, type FlowNodeKind as f, type NodeRunStatus as g, type NoteNodeData as h, escapeSegment as i };