@particle-academy/fancy-flow 0.14.0 → 0.15.1

package/dist/engine.d.cts

@@ -1,37 +1,215 @@
-import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-fc0fFKkf.cjs';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, a as FlowNode, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, b as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, S as SubgraphNodeData, T as TriggerNodeData } from './types-fc0fFKkf.cjs';
+export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-VKm57Hcj.cjs';
+import { N as NodeExecutor } from './types-sOmpCitB.cjs';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, E as ExecutorRegistry, a as FlowEdge, F as FlowGraph, b as FlowNode, c as FlowNodeData, d as FlowNodeKind, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-sOmpCitB.cjs';
+import { P as PauseAwaiting } from './pause-9iT4tCEV.cjs';
+export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from './pause-9iT4tCEV.cjs';
 import '@xyflow/react';
 
-type RunOptions = {
-    /** Stop the run after this many ms. Default: no timeout. */
-    timeoutMs?: number;
-    /** Abort signal — host can cancel the run. */
-    signal?: AbortSignal;
-    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
-    initialInputs?: Record<string, Record<string, unknown>>;
-    /** Nesting depth — set by `subflow` when it runs a child graph. */
-    depth?: number;
-};
-type RunResult = {
+/**
+ * The node package manifest — what a marketplace node declares about itself.
+ *
+ * A node is not one artifact. It is a kind definition (palette entry, config
+ * schema, ports, canvas renderer) plus an executor for EACH runtime the
+ * consumer actually runs. A package shipping only a TS executor is unusable to
+ * anyone executing on PHP, and today that is invisible until a run fails.
+ *
+ * So the manifest states which runtimes it implements, and the CLI checks that
+ * against the host before installing rather than after. Requested by the MOIC
+ * Suite consumer (fancy-flow#2 §2), who runs the editor in TS and executes in
+ * PHP and hit exactly this.
+ *
+ * The manifest is data, not code: the registry, the CLI, and the MCP all read
+ * it without executing anything a package author wrote.
+ */
+
+/** The current manifest schema version. Bump only on a breaking shape change. */
+declare const NODE_MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * A runtime a node can implement.
+ *
+ * Open rather than a closed union — the PHP and Node twins are what exist
+ * today, but the point of a manifest is that a runtime we haven't written can
+ * declare itself without a release here.
+ */
+type NodeRuntimeId = "ts" | "php" | (string & {});
+type NodePackageManifest = {
+    /** Must equal `NODE_MANIFEST_SCHEMA_VERSION`. */
+    schemaVersion: number;
+    /** Package name, as installed (`@acme/fancy-flow-salesforce`). */
+    name: string;
+    /**
+     * The canonical kind id this package provides — namespaced, and the string
+     * that gets persisted into every document using it.
+     */
+    kind: string;
+    /** Semver range of fancy-flow this node's contract targets. */
+    fancyFlow: string;
+    /**
+     * Per-runtime entrypoints. TS is a module path within the package; PHP is a
+     * Composer requirement, because the two ecosystems install differently and
+     * pretending otherwise just moves the problem into the CLI.
+     */
+    runtimes: Partial<Record<NodeRuntimeId, string>>;
+    /**
+     * Host capabilities this node needs wired before it can run — `llm`,
+     * `workflow_resolver`, `document`, or a host-specific one.
+     *
+     * Declared so the CLI can tell an author what to wire BEFORE install, rather
+     * than the node silently no-opping or crashing mid-run.
+     */
+    capabilities?: string[];
+    /**
+     * Path to this node's golden fixtures, relative to the package root.
+     *
+     * REQUIRED. Every runtime the package claims runs these same cases, which is
+     * what makes "behaves identically on both runtimes" verified rather than
+     * asserted. See `./fixtures`.
+     */
+    fixtures: string;
+    /** Declares the node halts for a person. Mirrors `NodeKindDefinition`. */
+    pausesForHuman?: PauseAwaiting;
+    /** One-line summary — what `search_nodes` matches against. */
+    description?: string;
+    /**
+     * Assigned by the registry, never by the author. Present in a manifest being
+     * submitted for publication, it is a claim to a trust signal the author does
+     * not get to make.
+     */
+    verified?: boolean;
+};
+type ManifestProblem = {
+    level: "error" | "warning";
+    field: string;
+    message: string;
+};
+type ManifestValidation = {
+    /** True when there are no `error`-level problems. Warnings do not block. */
     ok: boolean;
-    /** Outputs collected per node, keyed by node id. */
-    outputs: Record<string, unknown>;
-    /** Error captured if any node threw. */
-    error?: string;
+    manifest?: NodePackageManifest;
+    problems: ManifestProblem[];
 };
 /**
- * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
+ * Validate a manifest read from disk or a registry.
+ *
+ * Returns every problem rather than throwing on the first, because an author
+ * fixing a package wants the whole list — a validator that reveals one error
+ * per run turns a five-minute fix into five round trips.
+ */
+declare function validateNodeManifest(input: unknown): ManifestValidation;
+/**
+ * Check a node against the runtimes a host actually executes on.
+ *
+ * This is what makes a TS-only package visible to someone running PHP BEFORE
+ * they install it rather than at the first run. A missing runtime is an error,
+ * not a warning: the node genuinely cannot execute there.
+ */
+declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[]): ManifestProblem[];
+/**
+ * Check that every capability a node needs is actually wired.
+ *
+ * Pass `capabilityStatus()` from the host. Unwired capabilities are a warning
+ * rather than an error — install is the right time to learn what to wire, not
+ * a reason to refuse, since wiring usually happens after install.
+ */
+declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" | "capabilities">, available: Readonly<Record<string, boolean>>): ManifestProblem[];
+
+/**
+ * Golden fixtures — the parity guarantee, and a publishing requirement.
+ *
+ * Every runtime a node package claims runs these same JSON cases. That is what
+ * makes "this node behaves identically on TS and PHP" verified rather than
+ * asserted, and it is the one thing a loose collection of repos can never
+ * offer.
+ *
+ * WHY IT IS REQUIRED RATHER THAN ENCOURAGED: cross-runtime drift does not fail
+ * loudly. The 0.9.0 port-resolution divergence produced flows that routed
+ * correctly in the editor and silently down one path on the server — status
+ * `completed`, no error, no exception, nothing to alert on. A guarantee that
+ * only holds when an author opts in is not a guarantee.
  *
- * Each node runs once, when all upstream nodes have produced outputs on the
- * connected ports. Decision nodes (or any executor that returns `{ branch:
- * 'true' }`) can short-circuit specific output ports — only edges leaving
- * an "active" port propagate to downstream nodes.
+ * WHAT A CASE ASSERTS, and why it matters more than it looks:
  *
- * Cycles are detected and abort the run with an error.
+ *   A fixture asserts THE DOWNSTREAM NODE EXECUTED — not the port the node
+ *   recorded. The distinction is the whole lesson of that incident. A test
+ *   reading back `outputs.router.__port` stays green while no edge fires and
+ *   the run halts at the branch: the node faithfully recorded its choice, and
+ *   nothing downstream ever ran. So the runner wires a real probe to every
+ *   declared port and reports which probes actually executed.
+ *
+ * The format is plain JSON with no expressions or callbacks, so the PHP runner
+ * executes byte-identical cases without an embedded JS engine.
+ */
+
+/** What a case expects to have happened. */
+type FixtureExpectation = {
+    /**
+     * Output ports whose downstream node must have executed — the assertion that
+     * catches routing drift. Order-insensitive; the set must match exactly, so a
+     * node that fires an extra port fails just as loudly as one that fires none.
+     */
+    ports?: string[];
+    /** The value carried downstream, deep-compared when present. */
+    value?: unknown;
+    /** The run halted for a person. */
+    pause?: {
+        awaiting: PauseAwaiting;
+        detail?: unknown;
+    };
+    /** The run failed, and the message contains this substring. */
+    error?: string;
+};
+type FixtureCase = {
+    /** Human-readable, and what a failure report names. */
+    name: string;
+    /** Config for the node under test — drives config-derived ports. */
+    config?: Record<string, unknown>;
+    /**
+     * The node's resolved output ports, stated rather than derived.
+     *
+     * NOT a convenience. TS derives config-driven ports by running a JavaScript
+     * function (`switch_case`'s cases, `llm_router`'s routes); PHP cannot, and
+     * falls back to the kind's static declaration. Left there, the identical
+     * fixture would build a DIFFERENT graph on each runtime — the fixtures would
+     * silently stop comparing like with like, which is the exact failure they
+     * exist to catch.
+     *
+     * So a case states its ports the same way an exported document does (see
+     * 0.10.1, "serialize resolved ports"), and both runners honour it. Omit it
+     * only for a node whose ports are static.
+     */
+    ports?: string[];
+    /** Inputs delivered on the node's input ports. */
+    inputs?: Record<string, unknown>;
+    expect: FixtureExpectation;
+};
+type FixtureFile = {
+    /** The kind under test. Must match the manifest's `kind`. */
+    kind: string;
+    cases: FixtureCase[];
+};
+type FixtureFailure = {
+    case: string;
+    message: string;
+};
+type FixtureRunResult = {
+    ok: boolean;
+    passed: number;
+    failures: FixtureFailure[];
+};
+/**
+ * Run one fixture file against a kind's executor.
+ *
+ * `executor` is the node's own; everything else in the graph is supplied here,
+ * so a case exercises the node and nothing but the node.
+ */
+declare function runFixtures(file: FixtureFile, executor: NodeExecutor): Promise<FixtureRunResult>;
+/**
+ * Validate a fixture file's shape before running it.
  *
- * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
- * status feed, log panel, or store.
+ * A package that publishes an empty or malformed fixture file has satisfied the
+ * letter of the requirement and none of its purpose, so this is checked at
+ * publish rather than trusted.
  */
-declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+declare function validateFixtureFile(input: unknown, expectedKind?: string): string[];
 
-export { ExecutorRegistry, FlowGraph, RunEvent, type RunOptions, type RunResult, runFlow };
+export { type FixtureCase, type FixtureExpectation, type FixtureFailure, type FixtureFile, type FixtureRunResult, type ManifestProblem, type ManifestValidation, NODE_MANIFEST_SCHEMA_VERSION, NodeExecutor, type NodePackageManifest, type NodeRuntimeId, PauseAwaiting, checkCapabilities, checkRuntimeSupport, runFixtures, validateFixtureFile, validateNodeManifest };

package/dist/engine.d.ts

@@ -1,37 +1,215 @@
-import { F as FlowGraph, E as ExecutorRegistry, R as RunEvent } from './types-fc0fFKkf.js';
-export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, c as FlowEdge, a as FlowNode, d as FlowNodeData, e as FlowNodeKind, N as NodeExecutor, b as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, S as SubgraphNodeData, T as TriggerNodeData } from './types-fc0fFKkf.js';
+export { R as RunOptions, a as RunResult, r as runFlow } from './run-flow-ChBi6q-W.js';
+import { N as NodeExecutor } from './types-sOmpCitB.js';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, E as ExecutorRegistry, a as FlowEdge, F as FlowGraph, b as FlowNode, c as FlowNodeData, d as FlowNodeKind, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, R as RunEvent, S as SubgraphNodeData, T as TriggerNodeData } from './types-sOmpCitB.js';
+import { P as PauseAwaiting } from './pause-9iT4tCEV.js';
+export { L as LEGACY_PAUSE_PREFIXES, a as PAUSE_PREFIX, b as PauseSignal, d as decodePause, e as encodePause, i as isPause, p as pauseForHuman } from './pause-9iT4tCEV.js';
 import '@xyflow/react';
 
-type RunOptions = {
-    /** Stop the run after this many ms. Default: no timeout. */
-    timeoutMs?: number;
-    /** Abort signal — host can cancel the run. */
-    signal?: AbortSignal;
-    /** Initial inputs supplied to entry-point nodes (no incoming edges). */
-    initialInputs?: Record<string, Record<string, unknown>>;
-    /** Nesting depth — set by `subflow` when it runs a child graph. */
-    depth?: number;
-};
-type RunResult = {
+/**
+ * The node package manifest — what a marketplace node declares about itself.
+ *
+ * A node is not one artifact. It is a kind definition (palette entry, config
+ * schema, ports, canvas renderer) plus an executor for EACH runtime the
+ * consumer actually runs. A package shipping only a TS executor is unusable to
+ * anyone executing on PHP, and today that is invisible until a run fails.
+ *
+ * So the manifest states which runtimes it implements, and the CLI checks that
+ * against the host before installing rather than after. Requested by the MOIC
+ * Suite consumer (fancy-flow#2 §2), who runs the editor in TS and executes in
+ * PHP and hit exactly this.
+ *
+ * The manifest is data, not code: the registry, the CLI, and the MCP all read
+ * it without executing anything a package author wrote.
+ */
+
+/** The current manifest schema version. Bump only on a breaking shape change. */
+declare const NODE_MANIFEST_SCHEMA_VERSION = 1;
+/**
+ * A runtime a node can implement.
+ *
+ * Open rather than a closed union — the PHP and Node twins are what exist
+ * today, but the point of a manifest is that a runtime we haven't written can
+ * declare itself without a release here.
+ */
+type NodeRuntimeId = "ts" | "php" | (string & {});
+type NodePackageManifest = {
+    /** Must equal `NODE_MANIFEST_SCHEMA_VERSION`. */
+    schemaVersion: number;
+    /** Package name, as installed (`@acme/fancy-flow-salesforce`). */
+    name: string;
+    /**
+     * The canonical kind id this package provides — namespaced, and the string
+     * that gets persisted into every document using it.
+     */
+    kind: string;
+    /** Semver range of fancy-flow this node's contract targets. */
+    fancyFlow: string;
+    /**
+     * Per-runtime entrypoints. TS is a module path within the package; PHP is a
+     * Composer requirement, because the two ecosystems install differently and
+     * pretending otherwise just moves the problem into the CLI.
+     */
+    runtimes: Partial<Record<NodeRuntimeId, string>>;
+    /**
+     * Host capabilities this node needs wired before it can run — `llm`,
+     * `workflow_resolver`, `document`, or a host-specific one.
+     *
+     * Declared so the CLI can tell an author what to wire BEFORE install, rather
+     * than the node silently no-opping or crashing mid-run.
+     */
+    capabilities?: string[];
+    /**
+     * Path to this node's golden fixtures, relative to the package root.
+     *
+     * REQUIRED. Every runtime the package claims runs these same cases, which is
+     * what makes "behaves identically on both runtimes" verified rather than
+     * asserted. See `./fixtures`.
+     */
+    fixtures: string;
+    /** Declares the node halts for a person. Mirrors `NodeKindDefinition`. */
+    pausesForHuman?: PauseAwaiting;
+    /** One-line summary — what `search_nodes` matches against. */
+    description?: string;
+    /**
+     * Assigned by the registry, never by the author. Present in a manifest being
+     * submitted for publication, it is a claim to a trust signal the author does
+     * not get to make.
+     */
+    verified?: boolean;
+};
+type ManifestProblem = {
+    level: "error" | "warning";
+    field: string;
+    message: string;
+};
+type ManifestValidation = {
+    /** True when there are no `error`-level problems. Warnings do not block. */
     ok: boolean;
-    /** Outputs collected per node, keyed by node id. */
-    outputs: Record<string, unknown>;
-    /** Error captured if any node threw. */
-    error?: string;
+    manifest?: NodePackageManifest;
+    problems: ManifestProblem[];
 };
 /**
- * runFlow — topological execution of a FlowGraph against an ExecutorRegistry.
+ * Validate a manifest read from disk or a registry.
+ *
+ * Returns every problem rather than throwing on the first, because an author
+ * fixing a package wants the whole list — a validator that reveals one error
+ * per run turns a five-minute fix into five round trips.
+ */
+declare function validateNodeManifest(input: unknown): ManifestValidation;
+/**
+ * Check a node against the runtimes a host actually executes on.
+ *
+ * This is what makes a TS-only package visible to someone running PHP BEFORE
+ * they install it rather than at the first run. A missing runtime is an error,
+ * not a warning: the node genuinely cannot execute there.
+ */
+declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[]): ManifestProblem[];
+/**
+ * Check that every capability a node needs is actually wired.
+ *
+ * Pass `capabilityStatus()` from the host. Unwired capabilities are a warning
+ * rather than an error — install is the right time to learn what to wire, not
+ * a reason to refuse, since wiring usually happens after install.
+ */
+declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" | "capabilities">, available: Readonly<Record<string, boolean>>): ManifestProblem[];
+
+/**
+ * Golden fixtures — the parity guarantee, and a publishing requirement.
+ *
+ * Every runtime a node package claims runs these same JSON cases. That is what
+ * makes "this node behaves identically on TS and PHP" verified rather than
+ * asserted, and it is the one thing a loose collection of repos can never
+ * offer.
+ *
+ * WHY IT IS REQUIRED RATHER THAN ENCOURAGED: cross-runtime drift does not fail
+ * loudly. The 0.9.0 port-resolution divergence produced flows that routed
+ * correctly in the editor and silently down one path on the server — status
+ * `completed`, no error, no exception, nothing to alert on. A guarantee that
+ * only holds when an author opts in is not a guarantee.
  *
- * Each node runs once, when all upstream nodes have produced outputs on the
- * connected ports. Decision nodes (or any executor that returns `{ branch:
- * 'true' }`) can short-circuit specific output ports — only edges leaving
- * an "active" port propagate to downstream nodes.
+ * WHAT A CASE ASSERTS, and why it matters more than it looks:
  *
- * Cycles are detected and abort the run with an error.
+ *   A fixture asserts THE DOWNSTREAM NODE EXECUTED — not the port the node
+ *   recorded. The distinction is the whole lesson of that incident. A test
+ *   reading back `outputs.router.__port` stays green while no edge fires and
+ *   the run halts at the branch: the node faithfully recorded its choice, and
+ *   nothing downstream ever ran. So the runner wires a real probe to every
+ *   declared port and reports which probes actually executed.
+ *
+ * The format is plain JSON with no expressions or callbacks, so the PHP runner
+ * executes byte-identical cases without an embedded JS engine.
+ */
+
+/** What a case expects to have happened. */
+type FixtureExpectation = {
+    /**
+     * Output ports whose downstream node must have executed — the assertion that
+     * catches routing drift. Order-insensitive; the set must match exactly, so a
+     * node that fires an extra port fails just as loudly as one that fires none.
+     */
+    ports?: string[];
+    /** The value carried downstream, deep-compared when present. */
+    value?: unknown;
+    /** The run halted for a person. */
+    pause?: {
+        awaiting: PauseAwaiting;
+        detail?: unknown;
+    };
+    /** The run failed, and the message contains this substring. */
+    error?: string;
+};
+type FixtureCase = {
+    /** Human-readable, and what a failure report names. */
+    name: string;
+    /** Config for the node under test — drives config-derived ports. */
+    config?: Record<string, unknown>;
+    /**
+     * The node's resolved output ports, stated rather than derived.
+     *
+     * NOT a convenience. TS derives config-driven ports by running a JavaScript
+     * function (`switch_case`'s cases, `llm_router`'s routes); PHP cannot, and
+     * falls back to the kind's static declaration. Left there, the identical
+     * fixture would build a DIFFERENT graph on each runtime — the fixtures would
+     * silently stop comparing like with like, which is the exact failure they
+     * exist to catch.
+     *
+     * So a case states its ports the same way an exported document does (see
+     * 0.10.1, "serialize resolved ports"), and both runners honour it. Omit it
+     * only for a node whose ports are static.
+     */
+    ports?: string[];
+    /** Inputs delivered on the node's input ports. */
+    inputs?: Record<string, unknown>;
+    expect: FixtureExpectation;
+};
+type FixtureFile = {
+    /** The kind under test. Must match the manifest's `kind`. */
+    kind: string;
+    cases: FixtureCase[];
+};
+type FixtureFailure = {
+    case: string;
+    message: string;
+};
+type FixtureRunResult = {
+    ok: boolean;
+    passed: number;
+    failures: FixtureFailure[];
+};
+/**
+ * Run one fixture file against a kind's executor.
+ *
+ * `executor` is the node's own; everything else in the graph is supplied here,
+ * so a case exercises the node and nothing but the node.
+ */
+declare function runFixtures(file: FixtureFile, executor: NodeExecutor): Promise<FixtureRunResult>;
+/**
+ * Validate a fixture file's shape before running it.
  *
- * The `onEvent` callback receives a stream of `RunEvent`s — wire it to a
- * status feed, log panel, or store.
+ * A package that publishes an empty or malformed fixture file has satisfied the
+ * letter of the requirement and none of its purpose, so this is checked at
+ * publish rather than trusted.
  */
-declare function runFlow(graph: FlowGraph, executors: ExecutorRegistry, onEvent?: (event: RunEvent) => void, options?: RunOptions): Promise<RunResult>;
+declare function validateFixtureFile(input: unknown, expectedKind?: string): string[];
 
-export { ExecutorRegistry, FlowGraph, RunEvent, type RunOptions, type RunResult, runFlow };
+export { type FixtureCase, type FixtureExpectation, type FixtureFailure, type FixtureFile, type FixtureRunResult, type ManifestProblem, type ManifestValidation, NODE_MANIFEST_SCHEMA_VERSION, NodeExecutor, type NodePackageManifest, type NodeRuntimeId, PauseAwaiting, checkCapabilities, checkRuntimeSupport, runFixtures, validateFixtureFile, validateNodeManifest };