@openwop/openwop-conformance 1.48.0 → 1.52.0

package/schemas/capabilities.schema.json

@@ -1869,6 +1869,22 @@
         "supported": {
           "type": "boolean",
           "description": "Whether the host's workflow editor implements chain expansion at author time. `false` (or omission) signals the host does NOT consume workflow-chain packs."
+        },
+        "deferredParameters": {
+          "type": "object",
+          "description": "RFC 0124 (WCP4, `Active`). OPTIONAL. When `supported: true`, the host offers a capability-gated deferred-parameter expansion mode in ADDITION to expansion-time substitution (which remains the default and floor): at drop time it materializes the chain's `parameters` into top-level workflow `variables[]` (author value as `defaultValue`) and rewrites `{{params.<name>}}` into a spec'd runtime binding (PromptTemplate `{{varName}}` with `source:\"variable\"`, or a variable-sourced PortValue), so chain parameters stay overridable per run via `configurable` while the persisted definition keeps ZERO `{{params.*}}` tokens. A parameter marked `x-openwop-sensitive` MUST be deferred or the expansion fail-closed (`sensitive_param_not_deferrable`, 422) — never frozen into persisted `config`. Omission (or `supported:false`) signals the host does NOT offer deferred mode. No host may advertise `supported:true` until RFC 0124 is `Accepted`. See `workflow-chain-packs.md` §\"Deferred-parameter expansion\".",
+          "properties": {
+            "supported": {
+              "type": "boolean",
+              "description": "Whether the host offers the deferred-parameter expansion mode. Requires `capabilities.prompts.supported: true` with `variable` in `prompts.variableSources` for the prompt-bearing rewrite path."
+            }
+          },
+          "required": ["supported"],
+          "additionalProperties": false
+        },
+        "hostExpansionSeam": {
+          "type": "boolean",
+          "description": "RFC 0013 erratum (2026-07-05). OPTIONAL. A **conformance-only test seam** advertisement (category: test harness, cf. `observability.testSeams` — NOT a product capability): when `true`, the host serves `POST /v1/host/sample/workflow-chain:expand` returning the `vendor.openwop.workflow-chain-sample` v1.0.0 expansion that `conformance/src/scenarios/workflow-chain-host-expansion.test.ts` asserts against. Absent/`false` ⇒ that live-host expansion scenario soft-skips; the semantic `workflowChainPacks.supported` claim is witnessed by the server-free `workflow-chain-expansion.test.ts` legs. This flag is DISTINCT from `deferredParameters` (RFC 0124), which is witnessed through its own `POST /v1/host/sample/chain/deferred-expand` seam — so a host MAY advertise `supported` / `deferredParameters.supported` without standing up the RFC 0013 sample-pack seam it was never handed a published fixture for. Advertising `supported:true` no longer conscripts a host into the RFC 0013 host-expansion scenario."
         }
       },
       "required": ["supported"],

package/schemas/orchestrator-decision.schema.json

@@ -23,6 +23,11 @@
           },
           "description": "Ordered list of worker node-ids OR agent-ids to dispatch. Hosts that interpret entries as node-ids dispatch in DAG order; hosts that interpret as agent-ids resolve to nodes via the run's static DAG."
         },
+        "nextWorkerInputs": {
+          "type": "array",
+          "items": { "type": "object" },
+          "description": "RFC 0126 (data-parallel fan-out). OPTIONAL, index-aligned with `nextWorkerIds`: `nextWorkerInputs[i]` is a per-child input object (child input variable names → values) projected into the child dispatched for `nextWorkerIds[i]`, over the RFC 0022 `inputMapping`/`perWorkerInputMappings` projection (per-item value WINS on key collision). Enables fanning ONE `childWorkflowId` over N runtime items with distinct inputs (the map-over-collection pattern). When present, `nextWorkerInputs.length` MUST equal `nextWorkerIds.length` (a host MUST fail the dispatch node with `validation_error` and dispatch NO child otherwise — length is not JSON-Schema-enforceable, so this is a runtime MUST). Gated on `capabilities.dispatch.perItemInput`: a host NOT advertising it, upon receiving a non-empty `nextWorkerInputs`, MUST fail closed with `validation_error` and MUST NOT silently drop-and-dispatch N identical children (the correctness/spend hazard this closes). Replay-safe: rides the recorded `runOrchestrator.decided` event, re-read verbatim on `:fork`, never recomputed (frozen at decision time). A `sensitive`/secret per-item value MUST NOT appear here in plaintext (use the secret channel). See `node-packs.md` §core.dispatch."
+        },
         "confidence": {
           "type": "number",
           "minimum": 0,

package/schemas/workflow-chain-pack-manifest.schema.json

@@ -88,7 +88,7 @@
         },
         "parameters": {
           "type": "object",
-          "description": "JSON Schema 2020-12 fragment describing the parameter values the host editor MUST collect from the author at drop time. Authors-supplied values are validated against this schema before expansion proceeds; invalid input MUST be rejected with `chain_parameter_invalid`.",
+          "description": "JSON Schema 2020-12 fragment describing the parameter values the host editor MUST collect from the author at drop time. Authors-supplied values are validated against this schema before expansion proceeds; invalid input MUST be rejected with `chain_parameter_invalid`. RECOGNIZED EXTENSION KEY (RFC 0124 / WCP4): a property MAY carry `x-openwop-sensitive: true` to declare the parameter secret-class. A host that recognizes it MUST NOT expansion-time-freeze that parameter (plaintext secret-at-rest leak, SR-1) and MUST NOT materialize it as a plaintext `source:\"variable\"` binding (the value would land in the run-scoped bag / `RunSnapshot.variables` — the same SR-1 leak one layer down). Instead, per the 2026-07-04 §Security amendment: it is deferrable ONLY in a prompt-body position, where it MUST be materialized as a `source:\"secret\"` `PromptVariable` (BYOK-resolved via `capabilities.secrets`, redacted to `[REDACTED:<secretId>]` in `prompt.composed`, never bagged); in ANY other position (whole-value `node.inputs`, embedded non-prompt `config`, or a host lacking deferred / `secrets` support) it MUST fail closed with `sensitive_param_not_deferrable` (422). Per-run supply is a `credentialRef` secret reference, never plaintext. See `workflow-chain-packs.md` §\"Deferred-parameter expansion\" / RFC 0124 §Security.",
           "additionalProperties": true,
           "$comment": "Open by design — this field IS a JSON Schema document, so it must accept any of the 30+ JSON Schema 2020-12 keywords (`type`, `properties`, `required`, `oneOf`, `allOf`, etc.). Strict closure would require importing the JSON Schema meta-schema."
         },
@@ -197,12 +197,32 @@
           "description": "Target node id (must reference a node in `nodes[]`). MAY use `nodeId.inputPort` syntax."
         },
         "condition": {
+          "$ref": "#/$defs/EdgeCondition",
+          "description": "Optional edge condition — the SAME shape as a top-level workflow edge's condition (workflow-definition.schema.json §EdgeCondition). When present, the edge contributes to the target only if the condition holds against the source node's output, letting a chain express content routing (router/switch/conditional branches). Safety-fix (RFC 0013 amendment 2026-07-03): the field was previously typed `string`, contradicting this description; no chain used the string form (hosts dropped the field at expansion), so correcting it to the object shape breaks no conformant behavior."
+        },
+        "triggerRule": {
           "type": "string",
-          "description": "Optional edge condition expression — same shape as a top-level workflow edge's condition."
+          "enum": ["all_success", "any_success", "all_complete", "none_failed", "any_failed"],
+          "default": "all_success",
+          "description": "Optional fan-in / error-routing rule — the SAME shape and enum as a top-level workflow edge's `triggerRule` (workflow-definition.schema.json §WorkflowEdge). Governs how the target node fires given its incoming edges: `all_success` (default — every incoming edge's source succeeded), `any_success`, `all_complete` (fire when all sources have finished regardless of success — best-effort completion), `none_failed`, `any_failed`. Additive (RFC 0125): omitting it is identical to `all_success`, the implicit prior behavior. Mirrors the RFC 0013 2026-07-03 `condition` amendment's WorkflowEdge→FragmentEdge move. Expansion MUST carry this value onto the resulting `WorkflowEdge` so the scheduler honors it (see `workflow-chain-packs.md` §\"Expansion semantics\")."
         }
       },
       "additionalProperties": false
     },
+    "EdgeCondition": {
+      "type": "object",
+      "description": "Edge condition — identical to workflow-definition.schema.json §EdgeCondition (RFC 0013 §edges: 'same shape as a top-level workflow definition'). Inlined here so the manifest schema is self-contained for pack-loader validators.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["expression", "equals", "notEquals", "contains", "regex"]
+        },
+        "left": { "type": "string", "description": "Left operand path (e.g., 'status', 'output.approved')." },
+        "right": { "description": "Right operand value (any JSON value)." },
+        "expression": { "type": "string", "description": "Used when type='expression'." }
+      },
+      "additionalProperties": false
+    },
     "Signing": {
       "type": "object",
       "description": "Optional signing metadata. Reuses node-packs.md §signing unchanged.",

package/src/lib/workflow-chain-expansion.ts

@@ -54,10 +54,25 @@ export interface FragmentNode {
   inputs?: Record<string, unknown>;
 }
 
+/** A fan-in / error-routing rule mirrored from `WorkflowEdge.triggerRule`
+ *  (workflow-definition.schema.json). RFC 0125. */
+export type TriggerRule =
+  | 'all_success'
+  | 'any_success'
+  | 'all_complete'
+  | 'none_failed'
+  | 'any_failed';
+
 export interface FragmentEdge {
   from: string;
   to: string;
-  condition?: string;
+  /** Edge condition — an `EdgeCondition` object (RFC 0013 amendment #818).
+   *  Carried through expansion opaquely; typed `unknown` since the lib does
+   *  not evaluate it. */
+  condition?: unknown;
+  /** Fan-in / error-routing rule (RFC 0125). Carried through expansion onto
+   *  the resulting WorkflowEdge so the scheduler honors it. */
+  triggerRule?: TriggerRule;
 }
 
 /** Per-expansion context the caller supplies. */
@@ -90,7 +105,7 @@ export interface ExpandedFragment {
     inputs?: Record<string, unknown>;
     capabilities?: ReadonlyArray<string>;
   }>;
-  edges: ReadonlyArray<{ from: string; to: string; condition?: string }>;
+  edges: ReadonlyArray<{ from: string; to: string; condition?: unknown; triggerRule?: TriggerRule }>;
   /** Map of original-fragment-id → rewritten-id, so the caller can
    *  wire the parent workflow's adjacent edges into the expansion. */
   idMap: ReadonlyMap<string, string>;
@@ -110,6 +125,12 @@ export class ChainUnresolvableTypeIdError extends Error {
 }
 
 const PARAM_PATTERN = /\{\{params\.([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+/** A value that is EXACTLY a single `{{params.<name>}}` token (whole-value),
+ *  distinct from a token embedded in a larger string. Whole-value tokens are
+ *  the only non-prompt position deferrable to a variable-sourced PortValue
+ *  (WCP2 raw-typed rule); an embedded non-prompt token has no runtime `{{}}`
+ *  construct and MUST resolve at expansion time. */
+const WHOLE_VALUE_PATTERN = /^\{\{params\.([a-zA-Z_][a-zA-Z0-9_]*)\}\}$/;
 
 /** Recursive literal substitution of `{{params.<name>}}` placeholders in
  *  any string field. Non-string values pass through unchanged; nested
@@ -206,8 +227,272 @@ export function expandChain(chain: WorkflowChain, ctx: ExpansionContext): Expand
       to: rewriteEdgeRef(e.to, fragmentNodeIds, prefix),
     };
     if (e.condition !== undefined) out.condition = e.condition;
+    // RFC 0125: carry the fan-in/error-routing rule onto the expanded
+    // WorkflowEdge so the scheduler honors it (mirrors the `condition`
+    // pass-through; without this the field is silently dropped at expansion).
+    if (e.triggerRule !== undefined) out.triggerRule = e.triggerRule;
     return out;
   });
 
   return { nodes: expandedNodes, edges: expandedEdges, idMap };
 }
+
+// ---------------------------------------------------------------------------
+// RFC 0124 (WCP4) — Portable per-run parameter deferral.
+//
+// The DEFERRED expansion mode: instead of freezing `{{params.*}}` values into
+// persisted `config`/`inputs` at drop time (the RFC 0013 default), the host
+// materializes the chain's `parameters` into top-level workflow `variables[]`
+// (author value → `defaultValue`) and rewrites each token into an already-spec'd
+// RUNTIME binding — so the persisted fragment carries ZERO `{{params.*}}` tokens
+// yet every parameter stays overridable per run via `configurable`. This is the
+// spec-authoritative reference for `spec/v1/workflow-chain-packs.md`
+// §"Deferred-parameter expansion (RFC 0124)".
+// ---------------------------------------------------------------------------
+
+/** The parameter JSON Schema fragment (`chain.parameters`), narrowed to the
+ *  fields deferred expansion reads: each property's `type`, `description`, and
+ *  the RFC 0124 `x-openwop-sensitive` extension key. */
+export interface ParameterSchema {
+  properties?: Record<
+    string,
+    { type?: string; description?: string; 'x-openwop-sensitive'?: boolean }
+  >;
+}
+
+/** Host capability context deferred expansion needs (RFC 0124 §Capability
+ *  gating). The prompt-bearing rewrite path requires `prompts.variableSources`
+ *  to include `variable`; a `source:"secret"` sensitive lift requires
+ *  `capabilities.secrets.supported`. */
+export interface DeferredHostContext {
+  /** `capabilities.prompts.variableSources` includes `"variable"`. */
+  promptVariableSource: boolean;
+  /** `capabilities.secrets.supported`. */
+  secretsSupported: boolean;
+}
+
+export interface DeferredExpansionContext {
+  expansionId: string;
+  /** Author-supplied parameter values (already validated) → `defaultValue` seeds. */
+  params: Record<string, unknown>;
+  /** The chain's `parameters` JSON Schema (type + `x-openwop-sensitive` per property). */
+  parameterSchema: ParameterSchema;
+  isTypeIdResolvable: (typeId: string) => boolean;
+  host: DeferredHostContext;
+}
+
+/** A materialized top-level `WorkflowVariable` (subset — the fields deferred
+ *  expansion sets). A NON-sensitive parameter materializes here with its author
+ *  value as `defaultValue`. A sensitive parameter does NOT (its value never
+ *  lands in the run-scoped bag); it is bound as a `source:"secret"` prompt
+ *  variable instead. */
+export interface MaterializedVariable {
+  name: string;
+  type: string;
+  description?: string;
+  defaultValue?: unknown;
+  sensitive?: boolean;
+}
+
+/** A rewritten prompt-template variable slot (RFC 0027). `source:"variable"`
+ *  resolves from the run bag; `source:"secret"` resolves a BYOK secret at
+ *  compose time, redacted in `prompt.composed` (RFC 0124 §Security). */
+export interface PromptVariableBinding {
+  name: string;
+  source: 'variable' | 'secret';
+}
+
+export interface DeferredExpandedFragment {
+  nodes: ExpandedFragment['nodes'];
+  edges: ExpandedFragment['edges'];
+  idMap: ReadonlyMap<string, string>;
+  /** Materialized top-level `variables[]` (non-sensitive params only). */
+  variables: ReadonlyArray<MaterializedVariable>;
+  /** Prompt-site variable bindings introduced by the rewrite. */
+  promptVariables: ReadonlyArray<PromptVariableBinding>;
+  /** Auto-generated `configurableSchema` mapping the BARE param name (the
+   *  normative override key) to its type, so a per-run `configurable` keyed on
+   *  the bare name resolves (R6 cross-host key stability). */
+  configurableSchema: { properties: Record<string, { type: string }> };
+}
+
+/** Thrown when a `x-openwop-sensitive` parameter cannot be securely deferred:
+ *  it resolves to a non-prompt position (whole-value `node.inputs`, embedded
+ *  non-prompt `config`), or the host lacks `secrets`/deferred support. Wire
+ *  code `sensitive_param_not_deferrable` (HTTP 422) per
+ *  `workflow-chain-packs.md` §"Error codes" (RFC 0124 §Security). */
+export class SensitiveParamNotDeferrableError extends Error {
+  readonly code = 'sensitive_param_not_deferrable';
+  readonly httpStatus = 422;
+  constructor(readonly param: string, readonly reason: string) {
+    super(`sensitive_param_not_deferrable: '${param}' — ${reason}`);
+    this.name = 'SensitiveParamNotDeferrableError';
+  }
+}
+
+/** The prompt-bearing `config` fields a token in which is a "prompt position"
+ *  (lifted to a PromptTemplate `{{varName}}` slot). Everything else in `config`
+ *  is a non-prompt position. */
+const PROMPT_CONFIG_FIELDS: ReadonlySet<string> = new Set(['systemPrompt', 'userPrompt']);
+
+/**
+ * Deferred-mode expansion (RFC 0124). Rewrites every `{{params.<name>}}` token
+ * into a spec'd runtime binding and materializes non-sensitive parameters into
+ * top-level `variables[]`, leaving ZERO `{{params.*}}` tokens in the persisted
+ * fragment. Sensitive parameters (`x-openwop-sensitive`) are handled per
+ * §Security: prompt-body → `source:"secret"`; anywhere else → fail closed.
+ *
+ * @throws SensitiveParamNotDeferrableError when a sensitive parameter is in a
+ *   non-prompt position, or the host lacks `secrets` support.
+ * @throws ChainUnresolvableTypeIdError when any node typeId fails resolution.
+ */
+export function expandChainDeferred(
+  chain: WorkflowChain,
+  ctx: DeferredExpansionContext,
+): DeferredExpandedFragment {
+  for (const node of chain.dag.nodes) {
+    if (!ctx.isTypeIdResolvable(node.typeId)) {
+      throw new ChainUnresolvableTypeIdError(node.typeId, chain.chainId);
+    }
+  }
+
+  const props = ctx.parameterSchema.properties ?? {};
+  const isSensitive = (name: string): boolean => props[name]?.['x-openwop-sensitive'] === true;
+  const typeOf = (name: string): string => props[name]?.type ?? 'string';
+
+  const prefix = computePrefix(chain.chainId, ctx.expansionId);
+  const fragmentNodeIds = new Set(chain.dag.nodes.map((n) => n.id));
+  const idMap = new Map<string, string>();
+  for (const id of fragmentNodeIds) idMap.set(id, `${prefix}${id}`);
+
+  const usedParams = new Set<string>();
+  const promptVariables = new Map<string, PromptVariableBinding>();
+
+  /** Rewrite a prompt-position string: each embedded `{{params.x}}` → a
+   *  PromptTemplate `{{x}}` slot. A sensitive param binds `source:"secret"`
+   *  (requires host secrets support), else `source:"variable"`. If the host
+   *  does not advertise the `variable` prompt source at all, the deferred
+   *  prompt path is unavailable — the caller falls back to expansion-time
+   *  substitution (G5); we surface that by returning `null`. */
+  function rewritePrompt(text: string): string | null {
+    if (!ctx.host.promptVariableSource) return null; // G5 fallback → expansion-time
+    return text.replace(PARAM_PATTERN, (_m, name: string) => {
+      usedParams.add(name);
+      if (isSensitive(name)) {
+        if (!ctx.host.secretsSupported) {
+          throw new SensitiveParamNotDeferrableError(name, 'host lacks capabilities.secrets support');
+        }
+        promptVariables.set(name, { name, source: 'secret' });
+      } else {
+        promptVariables.set(name, { name, source: 'variable' });
+      }
+      return `{{${name}}}`;
+    });
+  }
+
+  /** Rewrite a config object: prompt fields → PromptTemplate slots; a token in
+   *  any NON-prompt config field is embedded-non-prompt → sensitive fails
+   *  closed, non-sensitive resolves at expansion time (author-trusted). */
+  function rewriteConfig(config: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(config)) {
+      if (typeof v === 'string' && PROMPT_CONFIG_FIELDS.has(k) && PARAM_PATTERN.test(v)) {
+        PARAM_PATTERN.lastIndex = 0;
+        const rewritten = rewritePrompt(v);
+        out[k] = rewritten === null ? substitute(v, ctx.params) : rewritten;
+        continue;
+      }
+      PARAM_PATTERN.lastIndex = 0;
+      if (typeof v === 'string' && PARAM_PATTERN.test(v)) {
+        // embedded non-prompt token
+        PARAM_PATTERN.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = PARAM_PATTERN.exec(v)) !== null) {
+          if (isSensitive(m[1])) {
+            throw new SensitiveParamNotDeferrableError(m[1], `embedded non-prompt config field '${k}'`);
+          }
+        }
+        out[k] = substitute(v, ctx.params); // author-trusted expansion-time resolution
+      } else {
+        out[k] = substitute(v, ctx.params);
+      }
+    }
+    return out;
+  }
+
+  /** Rewrite an inputs object: a WHOLE-VALUE `{{params.x}}` → a variable-sourced
+   *  PortValue (WCP2 raw-typed); a sensitive whole-value fails closed (no
+   *  plaintext-bag path for a secret). Embedded input tokens follow the same
+   *  non-prompt rule as config. */
+  function rewriteInputs(inputs: Record<string, unknown>): Record<string, unknown> {
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(inputs)) {
+      const whole = typeof v === 'string' ? WHOLE_VALUE_PATTERN.exec(v) : null;
+      if (whole) {
+        const name = whole[1];
+        if (isSensitive(name)) {
+          throw new SensitiveParamNotDeferrableError(name, `whole-value node input '${k}'`);
+        }
+        usedParams.add(name);
+        out[k] = { source: 'variable', variable: name }; // variable-sourced PortValue
+        continue;
+      }
+      PARAM_PATTERN.lastIndex = 0;
+      if (typeof v === 'string' && PARAM_PATTERN.test(v)) {
+        PARAM_PATTERN.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = PARAM_PATTERN.exec(v)) !== null) {
+          if (isSensitive(m[1])) {
+            throw new SensitiveParamNotDeferrableError(m[1], `embedded non-prompt input '${k}'`);
+          }
+        }
+        out[k] = substitute(v, ctx.params);
+      } else {
+        out[k] = substitute(v, ctx.params);
+      }
+    }
+    return out;
+  }
+
+  const expandedNodes = chain.dag.nodes.map((n) => {
+    const out: ExpandedFragment['nodes'][number] = { id: `${prefix}${n.id}`, typeId: n.typeId };
+    if (n.name !== undefined) out.name = n.name;
+    if (n.position !== undefined) out.position = n.position;
+    if (n.config !== undefined) out.config = rewriteConfig(n.config);
+    if (n.inputs !== undefined) out.inputs = rewriteInputs(n.inputs);
+    if (chain.capabilities && chain.capabilities.length > 0) out.capabilities = [...chain.capabilities];
+    return out;
+  });
+
+  const expandedEdges = (chain.dag.edges ?? []).map((e) => {
+    const out: ExpandedFragment['edges'][number] = {
+      from: rewriteEdgeRef(e.from, fragmentNodeIds, prefix),
+      to: rewriteEdgeRef(e.to, fragmentNodeIds, prefix),
+    };
+    if (e.condition !== undefined) out.condition = e.condition;
+    if (e.triggerRule !== undefined) out.triggerRule = e.triggerRule;
+    return out;
+  });
+
+  // Materialize NON-sensitive used params into top-level variables[]; build the
+  // bare-param → type configurableSchema for the override key.
+  const variables: MaterializedVariable[] = [];
+  const configurableSchema: { properties: Record<string, { type: string }> } = { properties: {} };
+  for (const name of usedParams) {
+    configurableSchema.properties[name] = { type: typeOf(name) };
+    if (isSensitive(name)) continue; // sensitive value never lands in the bag
+    const v: MaterializedVariable = { name, type: typeOf(name) };
+    if (props[name]?.description !== undefined) v.description = props[name]!.description;
+    if (name in ctx.params) v.defaultValue = ctx.params[name];
+    variables.push(v);
+  }
+
+  return {
+    nodes: expandedNodes,
+    edges: expandedEdges,
+    idMap,
+    variables,
+    promptVariables: [...promptVariables.values()],
+    configurableSchema,
+  };
+}

package/src/scenarios/dispatch-per-item-input.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Data-parallel dispatch — per-item child inputs. `node-packs.md` §"`core.dispatch`
+ * per-item input — data-parallel fan-out" (RFC 0126). Validates the additive, OPTIONAL
+ * `nextWorkerInputs` array on `NextWorkerDecision` (`orchestrator-decision.schema.json`)
+ * and the `capabilities.dispatch.perItemInput` fail-closed gate.
+ *
+ * `nextWorkerInputs[i]` is a per-child input object, index-aligned with `nextWorkerIds`,
+ * projected into the child dispatched for `nextWorkerIds[i]` — fanning ONE childWorkflowId
+ * over N runtime items with distinct inputs (the map-over-collection pattern). It rides the
+ * recorded `runOrchestrator.decided` event, so `:fork`/replay reproduces byte-identical
+ * children.
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free schema probe — `NextWorkerDecision` accepts a well-formed
+ *      `nextWorkerInputs`, still accepts a decision that omits it (additive/back-compat),
+ *      rejects a non-object item, and — because `additionalProperties:false` — rejects the
+ *      field on a pre-RFC-0126 strict validator only when the property name differs (the
+ *      point of the fail-closed gate). Array-length equality with `nextWorkerIds` is NOT
+ *      JSON-Schema-expressible, so the schema ADMITS a length-mismatch; that MUST is a
+ *      HOST runtime check, driven in layer B.
+ *
+ *   B. Capability-gated behavioral legs — on a host advertising
+ *      `capabilities.dispatch.perItemInput: true` that exposes the dispatch test seam, a
+ *      length-mismatched decision fails with a validation_error and dispatches no child,
+ *      and each child receives its own `nextWorkerInputs[i]`. On a host NOT advertising the
+ *      capability, a non-empty `nextWorkerInputs` MUST fail closed (validation_error), never
+ *      silently drop-and-dispatch N identical children. No conformant host advertises
+ *      perItemInput yet — these legs soft-skip until a reference host wires it (the first
+ *      witness toward `Active → Accepted`).
+ *
+ * @see spec/v1/node-packs.md §"core.dispatch per-item input — data-parallel fan-out (RFC 0126)"
+ * @see spec/v1/capabilities.md §dispatch
+ * @see schemas/orchestrator-decision.schema.json
+ * @see RFCS/0126-data-parallel-dispatch-per-item-input.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const DECISION = join(SCHEMAS_DIR, 'orchestrator-decision.schema.json');
+
+describe('dispatch-per-item: NextWorkerDecision.nextWorkerInputs schema (always-on, server-free)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(JSON.parse(readFileSync(DECISION, 'utf8')));
+
+  it('accepts a next-worker decision carrying a well-formed, index-aligned nextWorkerInputs', () => {
+    const decision = {
+      kind: 'next-worker',
+      nextWorkerIds: ['pack.re-engage-contact', 'pack.re-engage-contact', 'pack.re-engage-contact'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }, { contactId: 'c-3' }],
+    };
+    expect(
+      validate(decision),
+      `orchestrator-decision.schema.json §NextWorkerDecision — a well-formed nextWorkerInputs MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('still accepts a next-worker decision that omits nextWorkerInputs (additive / back-compat)', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['pack.child'] }),
+      'a pre-RFC-0126 next-worker decision MUST stay valid — the field is OPTIONAL',
+    ).toBe(true);
+  });
+
+  it('rejects a non-object nextWorkerInputs item', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a'], nextWorkerInputs: ['not-an-object'] }),
+      'each nextWorkerInputs entry MUST be a per-child input object',
+    ).toBe(false);
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a'], nextWorkerInputs: 'nope' }),
+      'nextWorkerInputs MUST be an array',
+    ).toBe(false);
+  });
+
+  it('still rejects an unknown property (additionalProperties:false) — the fail-closed gate', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a'], perItemInputs: [{ x: 1 }] }),
+      'NextWorkerDecision is additionalProperties:false — a mis-named field MUST be rejected, so old strict validators fail closed on unknown per-item shapes',
+    ).toBe(false);
+  });
+
+  it('ADMITS a length-mismatch — array-length equality is a runtime MUST, not schema-expressible', () => {
+    expect(
+      validate({ kind: 'next-worker', nextWorkerIds: ['a', 'b'], nextWorkerInputs: [{ x: 1 }] }),
+      'the wire schema cannot express nextWorkerInputs.length == nextWorkerIds.length; the host enforces it at decision time (layer B)',
+    ).toBe(true);
+  });
+});
+
+describe('dispatch-per-item: per-item input behavior (capability-gated, RFC 0126)', () => {
+  it('a host advertising perItemInput projects nextWorkerInputs[i] into child i', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { children?: Array<{ inputs?: Record<string, unknown> }> } | undefined;
+    expect(
+      body?.children?.length,
+      driver.describe('node-packs.md §core.dispatch per-item input', 'one child dispatched per nextWorkerIds entry'),
+    ).toBe(2);
+    expect(
+      body?.children?.map((c) => c.inputs?.contactId),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'each child receives its own nextWorkerInputs[i] (per-item value wins over inputMapping)'),
+    ).toEqual(['c-1', 'c-2']);
+  });
+
+  it('a length-mismatched nextWorkerInputs fails with a validation_error and dispatches no child', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    expect(
+      res.status >= 400 && res.status < 500,
+      driver.describe('node-packs.md §core.dispatch per-item input', 'nextWorkerInputs.length != nextWorkerIds.length MUST fail the dispatch node (4xx validation_error), dispatching no child'),
+    ).toBe(true);
+  });
+
+  it('nextWorkerInputs[i] OVERRIDES the inputMapping projection on key collision (G1 precedence)', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    // The seam applies `inputMapping` first (parent-variable projection, RFC 0022), then overlays
+    // nextWorkerInputs[i]. A key present in BOTH MUST resolve to the per-item value (most-specific wins).
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      inputMapping: { contactId: 'from-mapping', region: 'us' },
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { children?: Array<{ inputs?: Record<string, unknown> }> } | undefined;
+    expect(
+      body?.children?.map((c) => c.inputs?.contactId),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'on key collision the per-item value wins over inputMapping (G1)'),
+    ).toEqual(['c-1', 'c-2']);
+    expect(
+      body?.children?.every((c) => c.inputs?.region === 'us'),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'non-colliding inputMapping keys still project (per-item merges OVER, does not replace)'),
+    ).toBe(true);
+  });
+
+  it('replay re-reads the recorded nextWorkerInputs verbatim — no recomputation (R5 replay-freeze)', async () => {
+    const dispatch = await readCapabilityFamily<{ perItemInput?: boolean }>('dispatch');
+    if (!behaviorGate('dispatch.perItemInput', dispatch?.perItemInput === true)) return;
+
+    // A :fork/replay MUST re-read the per-item inputs frozen in the recorded runOrchestrator.decided
+    // decision and reproduce byte-identical children (CP-2), never re-derive them at replay time.
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+      replay: true,
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { children?: Array<{ inputs?: Record<string, unknown> }>; replayed?: boolean } | undefined;
+    expect(
+      body?.children?.map((c) => c.inputs?.contactId),
+      driver.describe('node-packs.md §core.dispatch per-item input', 'replay/:fork reproduces the recorded per-item children verbatim (frozen at decision time)'),
+    ).toEqual(['c-1', 'c-2']);
+  });
+
+  it('a host NOT advertising perItemInput MUST fail closed on a non-empty nextWorkerInputs', async () => {
+    const dispatch = await readCapabilityFamily<{ supported?: boolean; perItemInput?: boolean }>('dispatch');
+    if (!dispatch?.supported) return; // no dispatch surface → out of scope
+    if (dispatch.perItemInput === true) return; // this leg targets non-supporting hosts
+
+    const res = await driver.post('/v1/host/sample/dispatch/per-item', {
+      nextWorkerIds: ['conformance.child', 'conformance.child'],
+      nextWorkerInputs: [{ contactId: 'c-1' }, { contactId: 'c-2' }],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    expect(
+      res.status >= 400 && res.status < 500,
+      driver.describe('node-packs.md §core.dispatch per-item input', 'a host not advertising perItemInput MUST fail closed (4xx) on a non-empty nextWorkerInputs — never silently drop it and dispatch N identical children'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/fixtures-valid.test.ts

@@ -110,6 +110,12 @@ describe('fixtures: node-pack-manifest schema validity', () => {
   ajv.addSchema(promptKindSchema, './prompt-kind.schema.json');
   const schema = JSON.parse(readFileSync(PACK_MANIFEST_SCHEMA_PATH, 'utf8'));
   const validate = ajv.compile(schema);
+  // A `pack-manifests/` fixture may be a node pack OR a `kind: "workflow-chain"`
+  // pack (RFC 0013) — pick the schema by `kind`, exactly as the registry does.
+  const chainSchema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'workflow-chain-pack-manifest.schema.json'), 'utf8'),
+  );
+  const validateChain = ajv.compile(chainSchema);
 
   const files = readdirSync(PACK_MANIFEST_FIXTURES_DIR)
     .filter((f) => f.endsWith('.json'))
@@ -120,17 +126,22 @@ describe('fixtures: node-pack-manifest schema validity', () => {
   });
 
   for (const file of files) {
-    it(`pack-manifests/${file} validates against node-pack-manifest.schema.json`, () => {
+    it(`pack-manifests/${file} validates against its kind's manifest schema`, () => {
       const data = JSON.parse(
         readFileSync(join(PACK_MANIFEST_FIXTURES_DIR, file), 'utf8'),
-      );
-      const ok = validate(data);
-      const errors = (validate.errors ?? [])
+      ) as { kind?: string };
+      const isChain = data.kind === 'workflow-chain';
+      const v = isChain ? validateChain : validate;
+      const schemaName = isChain
+        ? 'workflow-chain-pack-manifest.schema.json'
+        : 'node-pack-manifest.schema.json';
+      const ok = v(data);
+      const errors = (v.errors ?? [])
         .map((e: ErrorObject) => `${e.instancePath || '/'}: ${e.message}`)
         .join('\n');
       expect(
         ok,
-        `Fixture pack-manifests/${file} fails node-pack-manifest schema:\n${errors}`,
+        `Fixture pack-manifests/${file} fails ${schemaName}:\n${errors}`,
       ).toBe(true);
     });
   }