@particle-academy/fancy-flow 0.15.1 → 0.16.0

package/dist/engine.d.cts

@@ -1,6 +1,6 @@
 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 { F as FlowGraph, R as RunEvent, N as NodeExecutor } from './types-sOmpCitB.cjs';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, E as ExecutorRegistry, a as FlowEdge, b as FlowNode, c as FlowNodeData, d as FlowNodeKind, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, 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';
@@ -9,17 +9,22 @@ import '@xyflow/react';
  * 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.
+ * schema, ports, renderer) plus an executor for EACH runtime the consumer runs.
+ * A package shipping only a TS executor is unusable to anyone executing on PHP,
+ * and without a manifest that is invisible until a run fails. 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.
+ *
+ * ## Why the engine range lives per runtime
+ *
+ * The first cut of this manifest carried ONE `fancyFlow` range, and it was
+ * wrong: the two engines version independently, so a single range cannot say
+ * "needs npm >=0.11 AND php >=0.5". A package supporting both runtimes would
+ * install cleanly against a host whose OTHER runtime was too old — the 0.9.0
+ * failure shape wearing a manifest. The range belongs inside each runtime.
  */
 
 /** The current manifest schema version. Bump only on a breaking shape change. */
@@ -32,6 +37,38 @@ declare const NODE_MANIFEST_SCHEMA_VERSION = 1;
  * declare itself without a release here.
  */
 type NodeRuntimeId = "ts" | "php" | (string & {});
+/**
+ * How one runtime provides this node, and which engine version it needs.
+ *
+ * `entry` and `package` are both here because the two ecosystems install
+ * differently — a module path within the package for TS, a Composer
+ * requirement for PHP — and pretending otherwise just moves the problem into
+ * the CLI. Exactly one is required.
+ */
+type NodeRuntimeSpec = {
+    /** Module path within the package (TS-style runtimes). */
+    entry?: string;
+    /** Dependency requirement resolved by that ecosystem (PHP/Composer-style). */
+    package?: string;
+    /** Semver range of THIS runtime's engine. Required — see the module note. */
+    engine: string;
+};
+/**
+ * Whether a capability must be wired for the node to work at all.
+ *
+ * `required` is checked at AUTHOR time, not run time. The failure that hurts is
+ * a node that installs fine, authors fine, and silently no-ops during a run —
+ * the same silence as a routing bug. An editor can grey the node and say which
+ * capability the host never registered.
+ */
+type CapabilityRequirement = "required" | "optional";
+/**
+ * Whether a node is safe to run again.
+ *
+ * Durable runs RETRY. A node that writes needs to say so, or a host has to pick
+ * one retry policy for every node and get it wrong somewhere.
+ */
+type SideEffects = "none" | "idempotent" | "unsafe-to-replay";
 type NodePackageManifest = {
     /** Must equal `NODE_MANIFEST_SCHEMA_VERSION`. */
     schemaVersion: number;
@@ -42,22 +79,33 @@ type NodePackageManifest = {
      * 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.
+     * Previous ids this kind still answers to.
+     *
+     * Core renamed `llm_branch` to `llm_router` and kept every old id working.
+     * Third-party packages will rename too, and their documents break the same
+     * way core's would have — so packages get the same escape hatch, otherwise
+     * only first-party nodes can rename safely.
+     */
+    aliases?: string[];
+    /**
+     * Version of this node's CONFIG shape, independent of the document schema.
+     *
+     * A node's config evolves on its own clock. Without a declared version, every
+     * executor accretes hand-written read-fallbacks forever (MOIC carries one for
+     * `routes[].key` → `routes[].port`), because nothing canonicalises old config
+     * the way import canonicalises kind ids.
      */
-    runtimes: Partial<Record<NodeRuntimeId, string>>;
+    configVersion?: number;
+    /** Per-runtime entrypoints and engine ranges. */
+    runtimes: Partial<Record<NodeRuntimeId, NodeRuntimeSpec>>;
     /**
-     * Host capabilities this node needs wired before it can run — `llm`,
-     * `workflow_resolver`, `document`, or a host-specific one.
+     * Host capabilities this node needs, and whether each is mandatory.
      *
-     * Declared so the CLI can tell an author what to wire BEFORE install, rather
-     * than the node silently no-opping or crashing mid-run.
+     * Declared so the CLI and the editor can say what to wire BEFORE a run,
+     * rather than the node silently no-opping or crashing mid-run.
      */
-    capabilities?: string[];
+    capabilities?: Record<string, CapabilityRequirement>;
     /**
      * Path to this node's golden fixtures, relative to the package root.
      *
@@ -66,8 +114,16 @@ type NodePackageManifest = {
      * asserted. See `./fixtures`.
      */
     fixtures: string;
-    /** Declares the node halts for a person. Mirrors `NodeKindDefinition`. */
+    /**
+     * Declares the node halts for a person. Mirrors `NodeKindDefinition`.
+     *
+     * A host-planning fact, not a node internal: a parent that embeds workflows
+     * needs to reject a child that can pause, because a paused child wedges the
+     * parent — and discovering that at run time means watching a run park.
+     */
     pausesForHuman?: PauseAwaiting;
+    /** Whether this node is safe to replay. See `SideEffects`. */
+    sideEffects?: SideEffects;
     /** One-line summary — what `search_nodes` matches against. */
     description?: string;
     /**
@@ -97,19 +153,36 @@ type ManifestValidation = {
  */
 declare function validateNodeManifest(input: unknown): ManifestValidation;
 /**
- * Check a node against the runtimes a host actually executes on.
+ * Check a node against the runtimes a host executes on, and their versions.
+ *
+ * Two failures live here, and both are errors because the node genuinely
+ * cannot run: a runtime the package does not implement at all, and a runtime
+ * it implements against an engine newer than the host's.
  *
- * 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.
+ * `engineVersions` is optional — pass what the host knows. An unchecked range
+ * is reported as a warning rather than passed over silently, because "we did
+ * not check" and "it is fine" must not look the same.
  */
-declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[]): ManifestProblem[];
+declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[], engineVersions?: Readonly<Record<string, string>>): ManifestProblem[];
 /**
- * Check that every capability a node needs is actually wired.
+ * Minimal semver range check — `^x.y.z`, `~x.y.z`, `>=x.y.z`, `x.y.z`, `*`.
  *
- * 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.
+ * Deliberately small: this runs in the CLI and in CI, and pulling a semver
+ * library into the engine for one comparison is not worth the dependency. It
+ * covers the forms a manifest actually uses; anything it cannot parse is
+ * treated as unsatisfied rather than silently passed, so an unparseable range
+ * fails loudly instead of waving a node through.
+ */
+declare function satisfiesRange(version: string, range: string): boolean;
+/**
+ * Check that every capability a node needs is wired.
+ *
+ * A `required` capability that is missing is an ERROR — that is the whole point
+ * of the requirement level. It is meant to be surfaced at author time, so an
+ * editor can grey the node and name what the host never registered, rather than
+ * the node installing cleanly and silently no-opping during a run.
+ *
+ * An `optional` one is a warning: the node still works, with less.
  */
 declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" | "capabilities">, available: Readonly<Record<string, boolean>>): ManifestProblem[];
 
@@ -140,6 +213,35 @@ declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" |
  * executes byte-identical cases without an embedded JS engine.
  */
 
+/**
+ * Deterministic stand-ins for host capabilities, declared as DATA.
+ *
+ * `llm_router` cannot reach a provider in CI, so a fixture has to supply a fake
+ * `LlmClient`. If the stub format is not shared, each runtime stubs
+ * differently and the fixtures stop being comparable — parity theatre. So the
+ * fixture declares the stub's *behaviour* and both engines construct it
+ * identically from the same JSON.
+ */
+type FixtureStubs = {
+    /** Canned `chooseRoute` answer for the LLM capability. */
+    llm_client?: {
+        chooseRoute: {
+            port: string;
+            reason?: string;
+        };
+    };
+    /** Canned workflow resolution, keyed by ref, for `subflow`. */
+    workflow_resolver?: Record<string, FlowGraph | null>;
+};
+/** An event a case expects the run to have emitted. */
+type FixtureEventExpectation = {
+    type: RunEvent["type"];
+    /** Emitting node, when it matters. */
+    nodeId?: string;
+    level?: "info" | "warn" | "error";
+    /** Substring match against the message — full text is too brittle to pin. */
+    messageContains?: string;
+};
 /** What a case expects to have happened. */
 type FixtureExpectation = {
     /**
@@ -157,6 +259,29 @@ type FixtureExpectation = {
     };
     /** The run failed, and the message contains this substring. */
     error?: string;
+    /**
+     * Events the run must have emitted.
+     *
+     * Emitted events are BEHAVIOUR, not decoration. The hallucinated-port warning
+     * is a contract an operator relies on to know a run took the fallback — if
+     * one runtime stops emitting it, the guarantee degrades silently. Each entry
+     * must match at least one emitted event.
+     */
+    events?: FixtureEventExpectation[];
+    /**
+     * The run resumed after a pause and reached this state.
+     *
+     * Pause/resume is the ONLY path that crosses a persistence boundary, which
+     * makes it where two runtimes are most likely to drift — and it had no parity
+     * coverage at all while `PausesForHuman` became public API.
+     */
+    afterResume?: {
+        /** Delivered on the paused node's `values` input, as a host would on resume. */
+        submit: unknown;
+        ports?: string[];
+        value?: unknown;
+        error?: string;
+    };
 };
 type FixtureCase = {
     /** Human-readable, and what a failure report names. */
@@ -180,6 +305,16 @@ type FixtureCase = {
     ports?: string[];
     /** Inputs delivered on the node's input ports. */
     inputs?: Record<string, unknown>;
+    /**
+     * Run this case against an ALIAS or an older config shape.
+     *
+     * What proves `aliases` and `configVersion` actually work rather than being
+     * declared and rotting. A package that renames its kind should have a case
+     * pinning that the old id still resolves.
+     */
+    legacyKind?: string;
+    /** Deterministic capability stand-ins for this case. */
+    stubs?: FixtureStubs;
     expect: FixtureExpectation;
 };
 type FixtureFile = {
@@ -212,4 +347,4 @@ declare function runFixtures(file: FixtureFile, executor: NodeExecutor): Promise
  */
 declare function validateFixtureFile(input: unknown, expectedKind?: string): string[];
 
-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 };
+export { type CapabilityRequirement, type FixtureCase, type FixtureEventExpectation, type FixtureExpectation, type FixtureFailure, type FixtureFile, type FixtureRunResult, type FixtureStubs, FlowGraph, type ManifestProblem, type ManifestValidation, NODE_MANIFEST_SCHEMA_VERSION, NodeExecutor, type NodePackageManifest, type NodeRuntimeId, type NodeRuntimeSpec, PauseAwaiting, RunEvent, type SideEffects, checkCapabilities, checkRuntimeSupport, runFixtures, satisfiesRange, validateFixtureFile, validateNodeManifest };

package/dist/engine.d.ts

@@ -1,6 +1,6 @@
 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 { F as FlowGraph, R as RunEvent, N as NodeExecutor } from './types-sOmpCitB.js';
+export { A as ActionNodeData, B as BaseNodeData, D as DecisionNodeData, E as ExecutorRegistry, a as FlowEdge, b as FlowNode, c as FlowNodeData, d as FlowNodeKind, e as NodeRunStatus, f as NoteNodeData, O as OutputNodeData, P as PortDescriptor, 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';
@@ -9,17 +9,22 @@ import '@xyflow/react';
  * 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.
+ * schema, ports, renderer) plus an executor for EACH runtime the consumer runs.
+ * A package shipping only a TS executor is unusable to anyone executing on PHP,
+ * and without a manifest that is invisible until a run fails. 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.
+ *
+ * ## Why the engine range lives per runtime
+ *
+ * The first cut of this manifest carried ONE `fancyFlow` range, and it was
+ * wrong: the two engines version independently, so a single range cannot say
+ * "needs npm >=0.11 AND php >=0.5". A package supporting both runtimes would
+ * install cleanly against a host whose OTHER runtime was too old — the 0.9.0
+ * failure shape wearing a manifest. The range belongs inside each runtime.
  */
 
 /** The current manifest schema version. Bump only on a breaking shape change. */
@@ -32,6 +37,38 @@ declare const NODE_MANIFEST_SCHEMA_VERSION = 1;
  * declare itself without a release here.
  */
 type NodeRuntimeId = "ts" | "php" | (string & {});
+/**
+ * How one runtime provides this node, and which engine version it needs.
+ *
+ * `entry` and `package` are both here because the two ecosystems install
+ * differently — a module path within the package for TS, a Composer
+ * requirement for PHP — and pretending otherwise just moves the problem into
+ * the CLI. Exactly one is required.
+ */
+type NodeRuntimeSpec = {
+    /** Module path within the package (TS-style runtimes). */
+    entry?: string;
+    /** Dependency requirement resolved by that ecosystem (PHP/Composer-style). */
+    package?: string;
+    /** Semver range of THIS runtime's engine. Required — see the module note. */
+    engine: string;
+};
+/**
+ * Whether a capability must be wired for the node to work at all.
+ *
+ * `required` is checked at AUTHOR time, not run time. The failure that hurts is
+ * a node that installs fine, authors fine, and silently no-ops during a run —
+ * the same silence as a routing bug. An editor can grey the node and say which
+ * capability the host never registered.
+ */
+type CapabilityRequirement = "required" | "optional";
+/**
+ * Whether a node is safe to run again.
+ *
+ * Durable runs RETRY. A node that writes needs to say so, or a host has to pick
+ * one retry policy for every node and get it wrong somewhere.
+ */
+type SideEffects = "none" | "idempotent" | "unsafe-to-replay";
 type NodePackageManifest = {
     /** Must equal `NODE_MANIFEST_SCHEMA_VERSION`. */
     schemaVersion: number;
@@ -42,22 +79,33 @@ type NodePackageManifest = {
      * 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.
+     * Previous ids this kind still answers to.
+     *
+     * Core renamed `llm_branch` to `llm_router` and kept every old id working.
+     * Third-party packages will rename too, and their documents break the same
+     * way core's would have — so packages get the same escape hatch, otherwise
+     * only first-party nodes can rename safely.
+     */
+    aliases?: string[];
+    /**
+     * Version of this node's CONFIG shape, independent of the document schema.
+     *
+     * A node's config evolves on its own clock. Without a declared version, every
+     * executor accretes hand-written read-fallbacks forever (MOIC carries one for
+     * `routes[].key` → `routes[].port`), because nothing canonicalises old config
+     * the way import canonicalises kind ids.
      */
-    runtimes: Partial<Record<NodeRuntimeId, string>>;
+    configVersion?: number;
+    /** Per-runtime entrypoints and engine ranges. */
+    runtimes: Partial<Record<NodeRuntimeId, NodeRuntimeSpec>>;
     /**
-     * Host capabilities this node needs wired before it can run — `llm`,
-     * `workflow_resolver`, `document`, or a host-specific one.
+     * Host capabilities this node needs, and whether each is mandatory.
      *
-     * Declared so the CLI can tell an author what to wire BEFORE install, rather
-     * than the node silently no-opping or crashing mid-run.
+     * Declared so the CLI and the editor can say what to wire BEFORE a run,
+     * rather than the node silently no-opping or crashing mid-run.
      */
-    capabilities?: string[];
+    capabilities?: Record<string, CapabilityRequirement>;
     /**
      * Path to this node's golden fixtures, relative to the package root.
      *
@@ -66,8 +114,16 @@ type NodePackageManifest = {
      * asserted. See `./fixtures`.
      */
     fixtures: string;
-    /** Declares the node halts for a person. Mirrors `NodeKindDefinition`. */
+    /**
+     * Declares the node halts for a person. Mirrors `NodeKindDefinition`.
+     *
+     * A host-planning fact, not a node internal: a parent that embeds workflows
+     * needs to reject a child that can pause, because a paused child wedges the
+     * parent — and discovering that at run time means watching a run park.
+     */
     pausesForHuman?: PauseAwaiting;
+    /** Whether this node is safe to replay. See `SideEffects`. */
+    sideEffects?: SideEffects;
     /** One-line summary — what `search_nodes` matches against. */
     description?: string;
     /**
@@ -97,19 +153,36 @@ type ManifestValidation = {
  */
 declare function validateNodeManifest(input: unknown): ManifestValidation;
 /**
- * Check a node against the runtimes a host actually executes on.
+ * Check a node against the runtimes a host executes on, and their versions.
+ *
+ * Two failures live here, and both are errors because the node genuinely
+ * cannot run: a runtime the package does not implement at all, and a runtime
+ * it implements against an engine newer than the host's.
  *
- * 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.
+ * `engineVersions` is optional — pass what the host knows. An unchecked range
+ * is reported as a warning rather than passed over silently, because "we did
+ * not check" and "it is fine" must not look the same.
  */
-declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[]): ManifestProblem[];
+declare function checkRuntimeSupport(manifest: Pick<NodePackageManifest, "kind" | "runtimes">, hostRuntimes: readonly string[], engineVersions?: Readonly<Record<string, string>>): ManifestProblem[];
 /**
- * Check that every capability a node needs is actually wired.
+ * Minimal semver range check — `^x.y.z`, `~x.y.z`, `>=x.y.z`, `x.y.z`, `*`.
  *
- * 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.
+ * Deliberately small: this runs in the CLI and in CI, and pulling a semver
+ * library into the engine for one comparison is not worth the dependency. It
+ * covers the forms a manifest actually uses; anything it cannot parse is
+ * treated as unsatisfied rather than silently passed, so an unparseable range
+ * fails loudly instead of waving a node through.
+ */
+declare function satisfiesRange(version: string, range: string): boolean;
+/**
+ * Check that every capability a node needs is wired.
+ *
+ * A `required` capability that is missing is an ERROR — that is the whole point
+ * of the requirement level. It is meant to be surfaced at author time, so an
+ * editor can grey the node and name what the host never registered, rather than
+ * the node installing cleanly and silently no-opping during a run.
+ *
+ * An `optional` one is a warning: the node still works, with less.
  */
 declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" | "capabilities">, available: Readonly<Record<string, boolean>>): ManifestProblem[];
 
@@ -140,6 +213,35 @@ declare function checkCapabilities(manifest: Pick<NodePackageManifest, "kind" |
  * executes byte-identical cases without an embedded JS engine.
  */
 
+/**
+ * Deterministic stand-ins for host capabilities, declared as DATA.
+ *
+ * `llm_router` cannot reach a provider in CI, so a fixture has to supply a fake
+ * `LlmClient`. If the stub format is not shared, each runtime stubs
+ * differently and the fixtures stop being comparable — parity theatre. So the
+ * fixture declares the stub's *behaviour* and both engines construct it
+ * identically from the same JSON.
+ */
+type FixtureStubs = {
+    /** Canned `chooseRoute` answer for the LLM capability. */
+    llm_client?: {
+        chooseRoute: {
+            port: string;
+            reason?: string;
+        };
+    };
+    /** Canned workflow resolution, keyed by ref, for `subflow`. */
+    workflow_resolver?: Record<string, FlowGraph | null>;
+};
+/** An event a case expects the run to have emitted. */
+type FixtureEventExpectation = {
+    type: RunEvent["type"];
+    /** Emitting node, when it matters. */
+    nodeId?: string;
+    level?: "info" | "warn" | "error";
+    /** Substring match against the message — full text is too brittle to pin. */
+    messageContains?: string;
+};
 /** What a case expects to have happened. */
 type FixtureExpectation = {
     /**
@@ -157,6 +259,29 @@ type FixtureExpectation = {
     };
     /** The run failed, and the message contains this substring. */
     error?: string;
+    /**
+     * Events the run must have emitted.
+     *
+     * Emitted events are BEHAVIOUR, not decoration. The hallucinated-port warning
+     * is a contract an operator relies on to know a run took the fallback — if
+     * one runtime stops emitting it, the guarantee degrades silently. Each entry
+     * must match at least one emitted event.
+     */
+    events?: FixtureEventExpectation[];
+    /**
+     * The run resumed after a pause and reached this state.
+     *
+     * Pause/resume is the ONLY path that crosses a persistence boundary, which
+     * makes it where two runtimes are most likely to drift — and it had no parity
+     * coverage at all while `PausesForHuman` became public API.
+     */
+    afterResume?: {
+        /** Delivered on the paused node's `values` input, as a host would on resume. */
+        submit: unknown;
+        ports?: string[];
+        value?: unknown;
+        error?: string;
+    };
 };
 type FixtureCase = {
     /** Human-readable, and what a failure report names. */
@@ -180,6 +305,16 @@ type FixtureCase = {
     ports?: string[];
     /** Inputs delivered on the node's input ports. */
     inputs?: Record<string, unknown>;
+    /**
+     * Run this case against an ALIAS or an older config shape.
+     *
+     * What proves `aliases` and `configVersion` actually work rather than being
+     * declared and rotting. A package that renames its kind should have a case
+     * pinning that the old id still resolves.
+     */
+    legacyKind?: string;
+    /** Deterministic capability stand-ins for this case. */
+    stubs?: FixtureStubs;
     expect: FixtureExpectation;
 };
 type FixtureFile = {
@@ -212,4 +347,4 @@ declare function runFixtures(file: FixtureFile, executor: NodeExecutor): Promise
  */
 declare function validateFixtureFile(input: unknown, expectedKind?: string): string[];
 
-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 };
+export { type CapabilityRequirement, type FixtureCase, type FixtureEventExpectation, type FixtureExpectation, type FixtureFailure, type FixtureFile, type FixtureRunResult, type FixtureStubs, FlowGraph, type ManifestProblem, type ManifestValidation, NODE_MANIFEST_SCHEMA_VERSION, NodeExecutor, type NodePackageManifest, type NodeRuntimeId, type NodeRuntimeSpec, PauseAwaiting, RunEvent, type SideEffects, checkCapabilities, checkRuntimeSupport, runFixtures, satisfiesRange, validateFixtureFile, validateNodeManifest };