@openwop/openwop-conformance 1.48.0 → 1.51.0

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);
+  });
+});