@openwop/openwop-conformance 1.51.0 → 1.53.0

package/src/scenarios/purpose-propagation.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Purpose-propagation — permitted-use labels (RFC 0128) —
+ * `capabilities.md` §purposePropagation + `a2a-integration.md`
+ * §"Purpose-propagation labels".
+ *
+ * The conformance-testable core of RFC 0128 §3: a host advertising
+ * `capabilities.purposePropagation` MUST re-emit a received
+ * `permittedPurposes` label on onward OpenWOP-envelope hops (MAY narrow,
+ * MUST NOT widen), a derived output MUST NOT carry a purpose absent from any
+ * contributing labelled input, and `[]`-labelled data MUST NOT be forwarded
+ * onward at all. The internal-use restriction (§4) is deliberately NOT tested
+ * — it is not observable over the wire.
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free schema probes:
+ *      - a labelled TriggerEvent validates; a non-array label fails;
+ *      - absent vs `[]` are distinct wire states (both validate — the
+ *        semantic difference is behavioral, asserted in layer B);
+ *      - the `capabilities.purposePropagation` family shape: `supported`
+ *        REQUIRED, `additionalProperties:false`.
+ *
+ *   B. Capability-gated behavioral legs via the two-hop seam
+ *      `POST /v1/host/sample/purpose-propagation/forward` (the suite plays
+ *      hop A — the labelled sender — and hop C — the onward receiver — around
+ *      the host at B). Soft-skips when the seam is unwired (404/405);
+ *      REQUIRED once `purposePropagation.supported` is advertised
+ *      (advertise-only-what-you-honor):
+ *      1. survive/narrow — a forwarded label arrives ⊆ what B received;
+ *      2. never-widen — strictly no purpose beyond the input set;
+ *      3. derived output — a merge of two labelled inputs arrives ⊆ their
+ *         intersection (multi-input never-widen — transformation does not
+ *         launder a grant);
+ *      4. unlabelled inputs add no constraint to a merge;
+ *      5. `[]` fail-closed — a `[]`-labelled record is dropped from onward
+ *         emission, with an unlabelled twin as the positive control
+ *         (non-arrival is evidence, not a timeout artifact).
+ *
+ * @see RFCS/0128-purpose-propagation-permitted-use-labels.md §3
+ * @see spec/v1/capabilities.md §purposePropagation
+ * @see spec/v1/a2a-integration.md §"Purpose-propagation labels"
+ */
+
+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, FIXTURES_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 HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const SEAM = '/v1/host/sample/purpose-propagation/forward';
+
+interface OnwardEmission {
+  recordId?: string;
+  surface?: string;
+  permittedPurposes?: string[];
+}
+interface ForwardResponse {
+  onward?: OnwardEmission[];
+  dropped?: string[];
+}
+
+function subsetOf(actual: string[] | undefined, allowed: string[]): boolean {
+  return (actual ?? []).every((p) => allowed.includes(p));
+}
+
+describe('purpose-propagation: label schema (always-on, server-free)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(JSON.parse(readFileSync(join(SCHEMAS_DIR, 'trigger-event.schema.json'), 'utf8')));
+  const FIXTURE = join(FIXTURES_DIR, 'trigger-events', 'trigger-event-change.json');
+
+  it('a labelled TriggerEvent validates; a non-array label fails', () => {
+    const ev = JSON.parse(readFileSync(FIXTURE, 'utf8'));
+    expect(validate(ev), `a labelled TriggerEvent MUST validate (RFC 0128 §1). Errors: ${JSON.stringify(validate.errors)}`).toBe(true);
+
+    ev.permittedPurposes = 'analytics';
+    expect(validate(ev), 'RFC 0128 §1 — permittedPurposes MUST be string[]').toBe(false);
+  });
+
+  it('absent and [] are BOTH wire-valid — distinct states (unlabelled vs no-onward-use)', () => {
+    const ev = JSON.parse(readFileSync(FIXTURE, 'utf8'));
+    delete ev.permittedPurposes;
+    expect(validate(ev), 'RFC 0128 §1 — an unlabelled event (absent label) MUST validate').toBe(true);
+    ev.permittedPurposes = [];
+    expect(validate(ev), 'RFC 0128 §1 — a []-labelled event MUST validate (behavioral meaning: no onward use)').toBe(true);
+  });
+
+  it('the capabilities.purposePropagation family requires `supported` and closes its shape', () => {
+    const caps = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'capabilities.schema.json'), 'utf8'));
+    const fam = caps.properties?.purposePropagation;
+    expect(fam, 'capabilities.schema.json MUST define the purposePropagation family (RFC 0128 §2)').toBeDefined();
+    expect(fam.required, 'purposePropagation MUST require `supported`').toContain('supported');
+    expect(fam.additionalProperties, 'purposePropagation MUST close its shape').toBe(false);
+    const ajvFam = new Ajv2020({ allErrors: true, strict: false });
+    const vf = ajvFam.compile(fam);
+    expect(vf({ supported: true, propagatesOnward: true }), 'the canonical advert MUST validate').toBe(true);
+    expect(vf({ propagatesOnward: true }), 'an advert without `supported` MUST fail').toBe(false);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('purpose-propagation: two-hop onward behavior (capability-gated)', () => {
+  async function seamPost(body: Record<string, unknown>): Promise<ForwardResponse | null> {
+    const res = await driver.post(SEAM, body);
+    if (res.status === 404 || res.status === 405) return null; // seam unwired — soft-skip
+    return (res.json as ForwardResponse | undefined) ?? {};
+  }
+
+  async function gate(): Promise<boolean> {
+    const fam = await readCapabilityFamily<{ supported?: boolean }>('purposePropagation');
+    return behaviorGate('purposePropagation', fam?.supported === true);
+  }
+
+  it('a forwarded label survives ⊆ the received set (re-emit; MAY narrow, MUST NOT widen)', async () => {
+    if (!(await gate())) return;
+    const input = ['analytics', 'marketing-email'];
+    const res = await seamPost({ mode: 'forward', records: [{ id: 'r1', permittedPurposes: input, data: { k: 1 } }] });
+    if (res === null) return;
+
+    const onward = res.onward ?? [];
+    expect(
+      onward.length > 0,
+      driver.describe('RFC 0128 §3', 'an advertising host MUST re-emit a received label on the onward hop — silent loss fails (the promise is propagation)'),
+    ).toBe(true);
+    for (const o of onward) {
+      expect(
+        Array.isArray(o.permittedPurposes) && subsetOf(o.permittedPurposes, input),
+        driver.describe('RFC 0128 §3', `the onward label MUST be a subset of what the host received — got ${JSON.stringify(o.permittedPurposes)} vs input ${JSON.stringify(input)} (widening is the testable violation)`),
+      ).toBe(true);
+    }
+  });
+
+  it('a derived (merged) output arrives ⊆ the intersection of contributing labelled inputs', async () => {
+    if (!(await gate())) return;
+    const res = await seamPost({
+      mode: 'merge',
+      records: [
+        { id: 'a', permittedPurposes: ['analytics', 'marketing-email'], data: { k: 1 } },
+        { id: 'b', permittedPurposes: ['analytics'], data: { k: 2 } },
+      ],
+    });
+    if (res === null) return;
+    const onward = res.onward ?? [];
+    expect(onward.length > 0, driver.describe('RFC 0128 §3', 'a merge of forwardable labelled inputs MUST produce an onward emission')).toBe(true);
+    for (const o of onward) {
+      expect(
+        subsetOf(o.permittedPurposes, ['analytics']),
+        driver.describe('RFC 0128 §3', `a derived output MUST NOT carry a purpose absent from any contributing labelled input — transformation does not launder a grant; got ${JSON.stringify(o.permittedPurposes)}, allowed ⊆ ["analytics"]`),
+      ).toBe(true);
+    }
+  });
+
+  it('an unlabelled input adds no constraint to a merge', async () => {
+    if (!(await gate())) return;
+    const res = await seamPost({
+      mode: 'merge',
+      records: [
+        { id: 'a', permittedPurposes: ['analytics'], data: { k: 1 } },
+        { id: 'b', data: { k: 2 } },
+      ],
+    });
+    if (res === null) return;
+    for (const o of res.onward ?? []) {
+      expect(
+        subsetOf(o.permittedPurposes, ['analytics']),
+        driver.describe('RFC 0128 §3', 'an unlabelled input asserts no constraint — the derived label is still bounded by the labelled input(s)'),
+      ).toBe(true);
+    }
+  });
+
+  it('[]-labelled data is fail-closed dropped from onward emission (positive control: unlabelled twin forwards)', async () => {
+    if (!(await gate())) return;
+    const res = await seamPost({
+      mode: 'forward',
+      records: [
+        { id: 'blocked', permittedPurposes: [], data: { k: 1 } },
+        { id: 'control', data: { k: 1 } },
+      ],
+    });
+    if (res === null) return;
+
+    const onwardIds = (res.onward ?? []).map((o) => o.recordId);
+    expect(
+      !onwardIds.includes('blocked'),
+      driver.describe('RFC 0128 §3', 'permittedPurposes: [] means no onward use — a conformant host MUST NOT forward []-labelled data to a further sink at all'),
+    ).toBe(true);
+    expect(
+      (res.dropped ?? []).includes('blocked'),
+      driver.describe('RFC 0128 §3', 'the []-labelled record MUST be reported dropped (fail-closed, observable)'),
+    ).toBe(true);
+    expect(
+      onwardIds.includes('control'),
+      driver.describe('RFC 0128 §3', 'the unlabelled twin (positive control) MUST forward — proving the non-arrival of the []-labelled record is the rule firing, not a dead seam'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/trigger-stream-cdc-sources.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Streaming & CDC trigger sources (RFC 0127) — `trigger-bridge.md` §F.5.
+ *
+ * Verifies the two additive externally-originated sources — `stream` (a
+ * message consumed from a Kafka/Kinesis/Pub-Sub broker) and `change` (a
+ * warehouse/DB change-data-capture record) — layered on the RFC 0083/0099
+ * bridge with the envelope / SSRF posture / content-free `trigger.*` events /
+ * §C-1 dedup floor reused verbatim.
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free schema probes:
+ *      - the canonical `stream` + `change` TriggerEvent fixtures validate;
+ *      - a `change` event WITHOUT `op` fails (`ChangeEvent` requires it —
+ *        RFC 0127 §2, schema-enforced);
+ *      - an out-of-enum `op` fails;
+ *      - the §F.1 exactly-one rule extends to the new sources (a
+ *        `source:"stream"` event carrying a `change` sub-object fails);
+ *      - a registration accepts `source:"stream"` / `source:"change"`;
+ *      - the capabilities enums (`triggerBridge.sources[]` +
+ *        `ingestion.externalSources[]`) include both values (regression pin).
+ *
+ *   B. Capability-gated behavioral legs (soft-skip pre-implementation;
+ *      REQUIRED once `ingestion.externalSources[]` advertises the source —
+ *      advertise-only-what-you-honor, RFC 0127 §Negative example):
+ *      - `POST /v1/host/sample/trigger-bridge/ingest` with a `stream` /
+ *        `change` body → a run starts, the delivered `ctx.triggerData`
+ *        matches `trigger-event.schema.json`, and the durable
+ *        `trigger.delivery.attempted` is content-free (SR-1: no
+ *        message/row body);
+ *      - `POST /v1/host/sample/trigger-bridge/deliver` `{scenario:"dedup",
+ *        source:"stream"}` → the same broker-coordinate dedup key delivered
+ *        twice is effectively-once (§C-1 floor, `(topic,partition,offset)`
+ *        keying).
+ *
+ * @see spec/v1/trigger-bridge.md §F.5
+ * @see RFCS/0127-streaming-and-cdc-trigger-sources.md
+ * @see RFCS/0099-external-event-trigger-ingestion.md (§F envelope, reused)
+ */
+
+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, FIXTURES_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';
+import { driveDelivery } from '../lib/triggerBridge.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+const STREAM_FIXTURE = join(FIXTURES_DIR, 'trigger-events', 'trigger-event-stream.json');
+const CHANGE_FIXTURE = join(FIXTURES_DIR, 'trigger-events', 'trigger-event-change.json');
+
+function buildAjv(): Ajv2020 {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  for (const name of ['trigger-subscription.schema.json']) {
+    ajv.addSchema(JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')));
+  }
+  return ajv;
+}
+
+describe('trigger-stream-cdc: TriggerEvent schema for stream/change (always-on, server-free)', () => {
+  const ajv = buildAjv();
+  const validate = ajv.compile(JSON.parse(readFileSync(join(SCHEMAS_DIR, 'trigger-event.schema.json'), 'utf8')));
+
+  it('the canonical stream TriggerEvent fixture validates', () => {
+    const ev = JSON.parse(readFileSync(STREAM_FIXTURE, 'utf8'));
+    expect(
+      validate(ev),
+      `trigger-event.schema.json MUST accept a conforming stream TriggerEvent (RFC 0127 §2). Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('the canonical change TriggerEvent fixture validates (op + permittedPurposes present)', () => {
+    const ev = JSON.parse(readFileSync(CHANGE_FIXTURE, 'utf8'));
+    expect(
+      validate(ev),
+      `trigger-event.schema.json MUST accept a conforming change TriggerEvent (RFC 0127 §2 / RFC 0128 §1). Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('a change event WITHOUT op fails — ChangeEvent requires the operation discriminator', () => {
+    const ev = JSON.parse(readFileSync(CHANGE_FIXTURE, 'utf8'));
+    delete ev.change.op;
+    expect(
+      validate(ev),
+      'RFC 0127 §2 — `op` (insert|update|delete) is REQUIRED on a change event (schema-enforced in the ChangeEvent $def)',
+    ).toBe(false);
+  });
+
+  it('an out-of-enum op fails', () => {
+    const ev = JSON.parse(readFileSync(CHANGE_FIXTURE, 'utf8'));
+    ev.change.op = 'upsert';
+    expect(
+      validate(ev),
+      'RFC 0127 §2 — `op` MUST be one of insert|update|delete',
+    ).toBe(false);
+  });
+
+  it('the §F.1 exactly-one rule extends — a source:"stream" event carrying a change sub-object fails', () => {
+    const ev = JSON.parse(readFileSync(STREAM_FIXTURE, 'utf8'));
+    ev.change = { op: 'insert', table: 't' };
+    expect(
+      validate(ev),
+      'trigger-bridge.md §F.1 — a TriggerEvent MUST carry exactly the per-source sub-object matching its `source` and MUST NOT carry the others (extends to stream/change per RFC 0127)',
+    ).toBe(false);
+  });
+});
+
+describe('trigger-stream-cdc: registration + capabilities vocabulary (always-on, server-free)', () => {
+  const ajv = buildAjv();
+  const validateReg = ajv.compile(
+    JSON.parse(readFileSync(join(SCHEMAS_DIR, 'trigger-subscription-registration.schema.json'), 'utf8')),
+  );
+
+  it('a registration accepts source:"stream" and source:"change"', () => {
+    for (const source of ['stream', 'change']) {
+      expect(
+        validateReg({ source, workflowId: 'wf_1' }),
+        `trigger-subscription-registration.schema.json MUST accept source:"${source}" (RFC 0127 §1). Errors: ${JSON.stringify(validateReg.errors)}`,
+      ).toBe(true);
+    }
+  });
+
+  it('the capabilities source enums include stream + change (regression pin)', () => {
+    const caps = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'capabilities.schema.json'), 'utf8'));
+    const tb = caps.properties?.triggerBridge?.properties ?? {};
+    const sources: string[] = tb.sources?.items?.enum ?? [];
+    const external: string[] = tb.ingestion?.properties?.externalSources?.items?.enum ?? [];
+    for (const v of ['stream', 'change']) {
+      expect(sources.includes(v), `RFC 0127 §1 — triggerBridge.sources[] enum MUST include "${v}"`).toBe(true);
+      expect(external.includes(v), `RFC 0127 §3 — ingestion.externalSources[] enum MUST include "${v}"`).toBe(true);
+    }
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('trigger-stream-cdc: behavioral ingestion + dedup (capability-gated)', () => {
+  it('a stream and a change event each ingest to a run with a schema-valid envelope and a content-free delivery event', async () => {
+    const tb = await readCapabilityFamily<{ ingestion?: { externalSources?: string[] } }>('triggerBridge');
+    const external = tb?.ingestion?.externalSources ?? [];
+    const advertisesNew = external.includes('stream') || external.includes('change');
+    // Gate on the RFC 0099 ingestion surface existing at all; the new-source
+    // legs soft-skip on a pre-RFC-0127 host. Once the host ADVERTISES
+    // stream/change, a soft-skip is forbidden (advertise-only-what-you-honor).
+    if (!behaviorGate('triggerBridge.ingestion', (external.length ?? 0) > 0)) return;
+
+    const ajv = buildAjv();
+    const validate = ajv.compile(JSON.parse(readFileSync(join(SCHEMAS_DIR, 'trigger-event.schema.json'), 'utf8')));
+
+    const bodies: Record<string, unknown>[] = [
+      {
+        source: 'stream',
+        verification: { mode: 'none' },
+        stream: { topic: 'events', partition: 3, offset: '88412', key: 'user_77', message: { type: 'page_view', secretMarker: 'CANARY-STREAM-BODY' } },
+      },
+      {
+        source: 'change',
+        verification: { mode: 'none' },
+        change: { op: 'update', table: 'contacts', changelogId: '0/1C4F9D0', after: { id: 77, secretMarker: 'CANARY-CHANGE-BODY' } },
+      },
+    ];
+
+    for (const body of bodies) {
+      const res = await driver.post('/v1/host/sample/trigger-bridge/ingest', body);
+      if ((res.status === 404 || res.status === 405 || res.status === 400 || res.status === 422) && !advertisesNew) continue; // pre-0127 host — soft-skip this source
+      expect(
+        res.status < 400,
+        driver.describe(
+          'trigger-bridge.md §F.5',
+          `a host advertising ingestion of "${body.source as string}" MUST ingest it (advertise-only-what-you-honor, RFC 0127 §Negative example) — got HTTP ${res.status}`,
+        ),
+      ).toBe(true);
+
+      const out = res.json as { triggerEvent?: Record<string, unknown>; deliveryEvent?: Record<string, unknown> } | undefined;
+      expect(
+        validate(out?.triggerEvent),
+        driver.describe(
+          'trigger-bridge.md §F.5',
+          `the delivered ${body.source as string} envelope MUST validate against trigger-event.schema.json. Errors: ${JSON.stringify(validate.errors)}`,
+        ),
+      ).toBe(true);
+
+      // SR-1 — the durable delivery event MUST NOT carry the message/row body.
+      const durable = JSON.stringify(out?.deliveryEvent ?? {});
+      expect(
+        !durable.includes('CANARY-STREAM-BODY') && !durable.includes('CANARY-CHANGE-BODY'),
+        driver.describe(
+          'trigger-bridge.md §F.5 (SR-1)',
+          'the durable trigger.delivery.attempted MUST be content-free — the broker message / CDC row body has no slot on the event log',
+        ),
+      ).toBe(true);
+    }
+  });
+
+  it('stream dedup — the same broker coordinates delivered twice are effectively-once (§C-1 floor)', async () => {
+    const tb = await readCapabilityFamily<{ ingestion?: { externalSources?: string[] } }>('triggerBridge');
+    const external = tb?.ingestion?.externalSources ?? [];
+    if (!behaviorGate('triggerBridge.ingestion', (external.length ?? 0) > 0)) return;
+
+    const first = await driveDelivery({ scenario: 'dedup', dedupKey: 'events:3:99001', source: 'stream' });
+    if (first === null) return; // delivery seam unwired — soft-skip
+    if (first.outcome === undefined && !external.includes('stream')) return; // pre-0127 host — soft-skip
+    expect(
+      first.deliveredCount === 1 || first.outcome === 'delivered',
+      driver.describe(
+        'trigger-bridge.md §F.5 / §C-1',
+        'a stream event dedup-keyed on (topic,partition,offset) redelivered within the window MUST be effectively-once — reuses the RFC 0083 §C-1 ≥24h floor unchanged',
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/workflow-chain-expansion.test.ts

@@ -184,6 +184,118 @@ describe('category: workflow-chain expansion — placeholder substitution', () =
   });
 });
 
+describe('category: workflow-chain expansion — whole-value typed resolution', () => {
+  it('resolves a whole-value {{params.x}} token to the RAW typed value (object/array/number/boolean)', () => {
+    const chain: WorkflowChain = {
+      ...SAMPLE_CHAIN,
+      parameters: {
+        type: 'object',
+        properties: {
+          retryPolicy: { type: 'object' },
+          allowlist: { type: 'array' },
+          maxTokens: { type: 'number' },
+          streaming: { type: 'boolean' },
+        },
+      },
+      dag: {
+        nodes: [
+          {
+            id: 'n',
+            typeId: 'core.identity',
+            config: {
+              retryPolicy: '{{params.retryPolicy}}',
+              allowlist: '{{params.allowlist}}',
+              maxTokens: '{{params.maxTokens}}',
+              streaming: '{{params.streaming}}',
+            },
+          },
+        ],
+        edges: [],
+      },
+    };
+    const fragment = expandChain(chain, {
+      expansionId: 'wv1',
+      params: {
+        retryPolicy: { attempts: 3, backoff: 'exponential' },
+        allowlist: ['a', 'b'],
+        maxTokens: 4096,
+        streaming: true,
+      },
+      isTypeIdResolvable: RESOLVE_ALL,
+    });
+    const config = at(fragment.nodes, 0, 'fragment.nodes').config as {
+      retryPolicy: unknown;
+      allowlist: unknown;
+      maxTokens: unknown;
+      streaming: unknown;
+    };
+    expect(
+      config.retryPolicy,
+      'Per workflow-chain-packs.md §"Parameter substitution": a value that is EXACTLY one `{{params.x}}` token MUST resolve to the raw typed value — an object param MUST NOT be stringified to "[object Object]".',
+    ).toEqual({ attempts: 3, backoff: 'exponential' });
+    expect(config.allowlist).toEqual(['a', 'b']);
+    expect(config.maxTokens).toBe(4096);
+    expect(config.streaming).toBe(true);
+  });
+
+  it('does literal string coercion for an EMBEDDED token in surrounding text', () => {
+    const chain: WorkflowChain = {
+      ...SAMPLE_CHAIN,
+      parameters: { type: 'object', properties: { count: { type: 'number' } } },
+      dag: {
+        nodes: [{ id: 'n', typeId: 'core.identity', config: { label: 'items: {{params.count}}' } }],
+        edges: [],
+      },
+    };
+    const fragment = expandChain(chain, {
+      expansionId: 'wv2',
+      params: { count: 42 },
+      isTypeIdResolvable: RESOLVE_ALL,
+    });
+    const config = at(fragment.nodes, 0, 'fragment.nodes').config as { label: string };
+    expect(
+      config.label,
+      'A token embedded in surrounding text MUST do literal string substitution (the numeric param coerces to its string form).',
+    ).toBe('items: 42');
+  });
+});
+
+describe('category: workflow-chain expansion — inputs preservation', () => {
+  it('preserves a present node.inputs (PortValue references) through expansion', () => {
+    const chain: WorkflowChain = {
+      ...SAMPLE_CHAIN,
+      dag: {
+        nodes: [
+          {
+            id: 'n',
+            typeId: 'core.identity',
+            config: {},
+            inputs: {
+              prompt: { sourceNodeId: 'upstream', sourcePort: 'text' },
+              seed: '{{params.seed}}',
+            },
+          },
+        ],
+        edges: [],
+      },
+    };
+    const fragment = expandChain(chain, {
+      expansionId: 'ip1',
+      params: { seed: 'xyz' },
+      isTypeIdResolvable: RESOLVE_ALL,
+    });
+    const inputs = at(fragment.nodes, 0, 'fragment.nodes').inputs as {
+      prompt: unknown;
+      seed: unknown;
+    };
+    expect(
+      inputs.prompt,
+      'Per workflow-chain-packs.md §"Parameter substitution": expansion MUST preserve a present `node.inputs` (PortValue references) verbatim — only `{{params.*}}` tokens inside its string leaves are substituted.',
+    ).toEqual({ sourceNodeId: 'upstream', sourcePort: 'text' });
+    expect(inputs.seed).toBe('xyz');
+  });
+});
+
 describe('category: workflow-chain expansion — node id collision avoidance', () => {
   it('same chain expanded TWICE in one parent workflow produces non-colliding node ids', () => {
     const first = expandChain(SAMPLE_CHAIN, {