@openwop/openwop-conformance 1.2.0 → 1.4.0

package/src/scenarios/envelope-truncated.test.ts

@@ -0,0 +1,136 @@
+/**
+ * envelope-truncated — RFC 0032 §B.4 + RFC 0033 §B runtime behavior.
+ *
+ * Capability- + fixture-gated. Drives the conformance `mock` provider via
+ * `POST /v1/host/sample/test/mock-ai/program` with a program that returns
+ * `stopReason: 'max_tokens'` on attempt 1 then a valid envelope on attempt 2.
+ * The host's `dispatchStructured` retry loop MUST: (a) emit exactly one
+ * `envelope.truncated` event with `stopReason: 'max_tokens'`; (b) retry with
+ * a maxTokens value strictly greater than the original budget per RFC 0033
+ * §B `truncationBudgetMultiplier`; (c) NOT inject the corrective schema
+ * fragment on the truncation retry (truncation is an output-size problem,
+ * not a schema problem); (d) complete normally after attempt 2 succeeds.
+ *
+ * @see RFCS/0032-envelope-reliability-events.md §B.4
+ * @see RFCS/0033-envelope-completion-contract.md §B
+ * @see schemas/run-event-payloads.schema.json §envelopeTruncated
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const FIXTURE = 'conformance-envelope-truncated';
+const NODE_ID = 'structured-call';
+
+interface RunEvent {
+  type: string;
+  payload?: Record<string, unknown>;
+  nodeId?: string;
+  sequence: number;
+}
+
+async function programMock(program: Array<Record<string, unknown>>): Promise<{ status: number }> {
+  const res = await driver.post('/v1/host/sample/test/mock-ai/program', { nodeId: NODE_ID, program });
+  return { status: res.status };
+}
+
+async function startRunAndRead(): Promise<{ events: RunEvent[]; terminal: unknown } | null> {
+  const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+  if (create.status !== 201) return null;
+  const runId = (create.json as { runId: string }).runId;
+  const terminal = await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+  const eventsRes = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+  if (eventsRes.status !== 200) return null;
+  const events = ((eventsRes.json as { events?: RunEvent[] } | undefined)?.events ?? []) as RunEvent[];
+  return { events, terminal };
+}
+
+async function lastBudget(): Promise<number | null> {
+  const res = await driver.get(`/v1/host/sample/test/mock-ai/last-dispatch-budget?nodeId=${encodeURIComponent(NODE_ID)}`);
+  if (res.status !== 200) return null;
+  return (res.json as { maxTokens?: number | null }).maxTokens ?? null;
+}
+
+describe.skipIf(HTTP_SKIP)('envelope-truncated: runtime behavior (RFC 0032 §B.4 + RFC 0033 §B)', () => {
+  it('when mock returns stopReason: max_tokens on attempt 1, exactly one envelope.truncated event fires with stopReason: max_tokens', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock([
+      { stopReason: 'max_tokens', content: '{"valid":' },
+      { stopReason: 'end_turn', content: '{"valid":true}' },
+    ]);
+    if (seed.status === 404) return;
+    expect(seed.status).toBe(200);
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    const truncated = result.events.filter((e) => e.type === 'envelope.truncated');
+    expect(
+      truncated.length,
+      driver.describe(
+        'RFCS/0032-envelope-reliability-events.md §B.4',
+        'exactly one envelope.truncated event MUST fire when the provider returns finishReason corresponding to truncation',
+      ),
+    ).toBe(1);
+    expect(truncated[0]!.payload?.stopReason).toBe('max_tokens');
+  });
+
+  it('payload includes nodeId + provider + model + partialPayloadAvailable boolean', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock([
+      { stopReason: 'max_tokens', content: '{"partial' },
+      { stopReason: 'end_turn', content: '{"valid":true}' },
+    ]);
+    if (seed.status === 404) return;
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    const truncated = result.events.find((e) => e.type === 'envelope.truncated');
+    expect(truncated).toBeDefined();
+    const payload = truncated!.payload ?? {};
+    expect(payload.nodeId).toBe(NODE_ID);
+    expect(payload.provider).toBe('mock');
+    expect(typeof payload.model).toBe('string');
+    expect(typeof payload.partialPayloadAvailable).toBe('boolean');
+  });
+
+  it('retry attempt receives a maxTokens value strictly greater than the previous attempt (RFC 0033 §B truncationBudgetMultiplier)', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock([
+      { stopReason: 'max_tokens', content: '{"partial' },
+      { stopReason: 'end_turn', content: '{"valid":true}' },
+    ]);
+    if (seed.status === 404) return;
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    // After the run, the mock's most-recent budget is the SECOND (retry)
+    // attempt's maxTokens. Per RFC 0033 §B, this MUST exceed the fixture's
+    // initial maxTokens (50). The host's default multiplier is 2 — so the
+    // retry should see 100.
+    const budget = await lastBudget();
+    if (budget === null) return; // host doesn't expose the seam
+    expect(
+      budget,
+      driver.describe(
+        'RFCS/0033-envelope-completion-contract.md §B',
+        'truncation retry MUST issue with a strictly-increased maxTokens budget (host multiplies by capabilities.envelopes.reliability.completion.truncationBudgetMultiplier)',
+      ),
+    ).toBeGreaterThan(50);
+  });
+
+  it('run terminates `completed` after the second attempt succeeds', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock([
+      { stopReason: 'max_tokens', content: '{"partial' },
+      { stopReason: 'end_turn', content: '{"valid":true}' },
+    ]);
+    if (seed.status === 404) return;
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    expect((result.terminal as { status?: string }).status).toBe('completed');
+  });
+});

package/src/scenarios/envelope-truncation-cap-exhaustion.test.ts

@@ -0,0 +1,144 @@
+/**
+ * envelope-truncation-cap-exhaustion — RFC 0033 §B DoS-bound assertion.
+ *
+ * Capability- + fixture-gated. Drives the conformance `mock` provider via
+ * `POST /v1/host/sample/test/mock-ai/program` with a program that returns
+ * `stopReason: 'max_tokens'` on EVERY attempt. The host's `dispatchStructured`
+ * retry loop MUST: (a) emit `envelope.truncated` per attempt (or at least the
+ * first); (b) double the budget each retry per RFC 0033 §B; (c) exhaust
+ * retries after `maxRetryAttempts`; (d) emit exactly one
+ * `envelope.retry.exhausted` with `finalReason: 'truncation'`; (e) fail the
+ * node with `error.code: 'envelope_truncation_unrecoverable'` per RFC 0033 §F;
+ * (f) NOT exceed `maxRetryAttempts` total LLM calls — DoS-bound assertion.
+ *
+ * @see RFCS/0033-envelope-completion-contract.md §B + §F
+ * @see spec/v1/rest-endpoints.md §"Common error codes" — envelope_truncation_unrecoverable
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const FIXTURE = 'conformance-envelope-truncation-cap-exhaustion';
+const NODE_ID = 'structured-call';
+
+interface RunEvent {
+  type: string;
+  payload?: Record<string, unknown>;
+  nodeId?: string;
+  sequence: number;
+}
+
+async function programMock(program: Array<Record<string, unknown>>): Promise<{ status: number }> {
+  const res = await driver.post('/v1/host/sample/test/mock-ai/program', { nodeId: NODE_ID, program });
+  return { status: res.status };
+}
+
+async function startRunAndRead(): Promise<{ events: RunEvent[]; terminal: unknown } | null> {
+  const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+  if (create.status !== 201) return null;
+  const runId = (create.json as { runId: string }).runId;
+  const terminal = await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+  const eventsRes = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+  if (eventsRes.status !== 200) return null;
+  const events = ((eventsRes.json as { events?: RunEvent[] } | undefined)?.events ?? []) as RunEvent[];
+  return { events, terminal };
+}
+
+// Seeded program: 16 truncation entries. The retry loop will only consume
+// up to maxRetryAttempts; any unused entries are wasted — bound is
+// confirmed by the events[] count, not by program exhaustion behavior.
+const PERPETUAL_TRUNCATION = Array.from({ length: 16 }, () => ({
+  stopReason: 'max_tokens' as const,
+  content: '{"partial',
+}));
+
+describe.skipIf(HTTP_SKIP)('envelope-truncation-cap-exhaustion: DoS-bound retry budget (RFC 0033 §B + §F)', () => {
+  it('perpetual truncation → emits exactly one envelope.retry.exhausted with finalReason: "truncation"', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock(PERPETUAL_TRUNCATION);
+    if (seed.status === 404) return;
+    expect(seed.status).toBe(200);
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    const exhausted = result.events.filter((e) => e.type === 'envelope.retry.exhausted');
+    expect(
+      exhausted.length,
+      driver.describe(
+        'RFCS/0032-envelope-reliability-events.md §B.2',
+        'exactly one envelope.retry.exhausted event MUST fire when the truncation-retry budget is exhausted',
+      ),
+    ).toBe(1);
+    expect(
+      exhausted[0]!.payload?.finalReason,
+      driver.describe(
+        'RFCS/0033-envelope-completion-contract.md §B',
+        'finalReason MUST be "truncation" when the host exhausts truncation retries (distinguished from schema-violation per RFC 0033 §A)',
+      ),
+    ).toBe('truncation');
+  });
+
+  it('node fails with RunSnapshot.error.code: "envelope_truncation_unrecoverable" per RFC 0033 §F', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock(PERPETUAL_TRUNCATION);
+    if (seed.status === 404) return;
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    const code = (result.terminal as { error?: { code?: string } }).error?.code;
+    expect(
+      code,
+      driver.describe(
+        'RFCS/0033-envelope-completion-contract.md §F',
+        'truncation-retry-exhaustion MUST surface as RunSnapshot.error.code = envelope_truncation_unrecoverable (distinct from envelope_invalid which surfaces schema-violation-exhaustion)',
+      ),
+    ).toBe('envelope_truncation_unrecoverable');
+  });
+
+  it('total LLM calls bounded by maxRetryAttempts (DoS-bound — no infinite loop)', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock(PERPETUAL_TRUNCATION);
+    if (seed.status === 404) return;
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    // Count envelope.truncated events as a proxy for LLM-call count
+    // (each truncated attempt emits one).
+    const truncatedCount = result.events.filter((e) => e.type === 'envelope.truncated').length;
+    expect(
+      truncatedCount,
+      driver.describe(
+        'RFCS/0033-envelope-completion-contract.md §B',
+        'truncation-retry count MUST be bounded — host cannot loop indefinitely doubling budget; expected upper-bound matches advertised maxRetryAttempts',
+      ),
+    ).toBeLessThanOrEqual(16);
+    // The host advertises maxRetryAttempts (default 3) — at most 3 LLM calls
+    // = 3 envelope.truncated events. Allow a generous upper bound here to
+    // accommodate hosts with larger configured retry budgets, but assert
+    // strictly that it's finite.
+    expect(truncatedCount).toBeGreaterThan(0);
+  });
+
+  it('envelope.retry.exhausted is emitted BEFORE node.failed (cause precedes effect)', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    const seed = await programMock(PERPETUAL_TRUNCATION);
+    if (seed.status === 404) return;
+
+    const result = await startRunAndRead();
+    if (result === null) return;
+    const exhaustedIdx = result.events.findIndex((e) => e.type === 'envelope.retry.exhausted');
+    const failedIdx = result.events.findIndex((e) => e.type === 'node.failed');
+    expect(exhaustedIdx).toBeGreaterThanOrEqual(0);
+    expect(failedIdx).toBeGreaterThanOrEqual(0);
+    expect(
+      exhaustedIdx < failedIdx,
+      driver.describe(
+        'RFCS/0032-envelope-reliability-events.md §B.2',
+        'envelope.retry.exhausted MUST be emitted BEFORE node.failed',
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/envelope-variant-discriminator-static.test.ts

@@ -0,0 +1,152 @@
+/**
+ * envelope-variant-discriminator-static — RFC 0031 §A static schema-walker.
+ *
+ * Asserts (always-on):
+ *   1. For every envelope payload schema in `schemas/envelopes/*.schema.json`,
+ *      `oneOf` MUST NOT appear at any nesting depth (Gemini silently drops
+ *      `oneOf`, producing a looser-than-declared schema — silent correctness bug).
+ *   2. Where `anyOf` is present in a payload schema, every branch MUST declare
+ *      a single-string-`enum` discriminator property in `required` per RFC 0031 §A.
+ *
+ * Capability-gated extension (when `OPENWOP_BASE_URL` is set AND
+ * `capabilities.supportedEnvelopes` is non-empty): same checks applied
+ * to the host's full envelope catalog where schemas can be resolved locally.
+ *
+ * @see RFCS/0031-envelope-variants-and-model-capabilities.md §A
+ * @see spec/v1/ai-envelope.md §"Variant payload discrimination (normative)"
+ * @see spec/v1/structured-output-subset.md (Tier-1 portability rationale)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+interface DiscriminatorViolation {
+  path: string;
+  rule: string;
+  detail?: string;
+}
+
+function loadSchema(p: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(p, 'utf8')) as Record<string, unknown>;
+}
+
+function walkForOneOf(schema: unknown, path: string, out: DiscriminatorViolation[]): void {
+  if (!schema || typeof schema !== 'object') return;
+  if (Array.isArray(schema)) {
+    schema.forEach((item, i) => walkForOneOf(item, `${path}/${i}`, out));
+    return;
+  }
+  const obj = schema as Record<string, unknown>;
+  if ('oneOf' in obj) {
+    out.push({
+      path,
+      rule: 'oneOf-forbidden',
+      detail: 'use `anyOf` with single-string-enum discriminator per RFC 0031 §A',
+    });
+  }
+  for (const key of Object.keys(obj)) {
+    walkForOneOf(obj[key], `${path}/${key}`, out);
+  }
+}
+
+interface AnyOfBranchValidation {
+  ok: boolean;
+  rule?: string;
+  detail?: string;
+}
+
+function validateAnyOfBranch(branch: Record<string, unknown>): AnyOfBranchValidation {
+  // A branch passes the discriminator rule if at least one of its `required` properties
+  // declares `type: string` + `enum` containing exactly one value.
+  const required = (branch.required as string[] | undefined) ?? [];
+  const properties = (branch.properties as Record<string, Record<string, unknown>> | undefined) ?? {};
+  for (const propName of required) {
+    const prop = properties[propName];
+    if (!prop) continue;
+    if (prop.type === 'string' && Array.isArray(prop.enum) && prop.enum.length === 1) {
+      return { ok: true };
+    }
+  }
+  // The branch may also be a `$ref` to a defined shape; ref-resolution is
+  // out of scope for this static walker — flag with a note rather than a hard fail.
+  if ('$ref' in branch) {
+    return { ok: true, detail: 'branch is a $ref; discriminator presence assumed in referenced $def' };
+  }
+  return {
+    ok: false,
+    rule: 'anyOf-branch-missing-discriminator',
+    detail: 'branch MUST declare a single-string-enum discriminator property in `required` per RFC 0031 §A',
+  };
+}
+
+function walkForAnyOfDiscriminators(
+  schema: unknown,
+  path: string,
+  out: DiscriminatorViolation[],
+): void {
+  if (!schema || typeof schema !== 'object') return;
+  if (Array.isArray(schema)) {
+    schema.forEach((item, i) => walkForAnyOfDiscriminators(item, `${path}/${i}`, out));
+    return;
+  }
+  const obj = schema as Record<string, unknown>;
+  if (Array.isArray(obj.anyOf)) {
+    obj.anyOf.forEach((branch, i) => {
+      const result = validateAnyOfBranch(branch as Record<string, unknown>);
+      if (!result.ok) {
+        out.push({
+          path: `${path}/anyOf/${i}`,
+          rule: result.rule ?? 'unknown',
+          ...(result.detail !== undefined ? { detail: result.detail } : {}),
+        });
+      }
+    });
+  }
+  for (const key of Object.keys(obj)) {
+    if (key === 'anyOf') continue; // handled above
+    walkForAnyOfDiscriminators(obj[key], `${path}/${key}`, out);
+  }
+}
+
+function listLocalEnvelopeSchemas(): { kind: string; path: string }[] {
+  const dir = join(SCHEMAS_DIR, 'envelopes');
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.schema.json'))
+    .map((f) => ({ kind: f.replace(/\.schema\.json$/, ''), path: join(dir, f) }));
+}
+
+describe('envelope-variant-discriminator-static (RFC 0031 §A)', () => {
+  const schemas = listLocalEnvelopeSchemas();
+
+  it('local envelope-schema directory is discoverable', () => {
+    expect(
+      schemas.length,
+      'schemas/envelopes/*.schema.json MUST contain at least the four universal-kind schemas',
+    ).toBeGreaterThanOrEqual(4);
+  });
+
+  for (const { kind, path } of schemas) {
+    it(`${kind}.schema.json MUST NOT contain \`oneOf\` at any nesting depth (Gemini silently drops it)`, () => {
+      const schema = loadSchema(path);
+      const violations: DiscriminatorViolation[] = [];
+      walkForOneOf(schema, '#', violations);
+      expect(
+        violations,
+        `${kind}.schema.json contains \`oneOf\` — REFORMULATE as \`anyOf\` + single-string-enum discriminator per RFC 0031 §A. Violations: ${JSON.stringify(violations, null, 2)}`,
+      ).toEqual([]);
+    });
+
+    it(`${kind}.schema.json: every \`anyOf\` branch declares a single-string-enum discriminator in \`required\``, () => {
+      const schema = loadSchema(path);
+      const violations: DiscriminatorViolation[] = [];
+      walkForAnyOfDiscriminators(schema, '#', violations);
+      expect(
+        violations,
+        `${kind}.schema.json \`anyOf\` discriminator violations: ${JSON.stringify(violations, null, 2)}`,
+      ).toEqual([]);
+    });
+  }
+});

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

@@ -18,7 +18,7 @@
  * @see RFCS/0003-fixture-gating.md
  */
 
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import {
   isFixtureAdvertised,
   setAdvertisedFixtures,
@@ -26,6 +26,7 @@ import {
   isFixtureCacheReady,
   __resetForTests,
 } from '../lib/fixtures.js';
+import { isScenarioOptedOut } from '../lib/env.js';
 
 beforeEach(() => {
   __resetForTests();
@@ -135,3 +136,140 @@ describe('fixtures: __resetForTests', () => {
     expect(getAdvertisedFixtures()).toBe(null);
   });
 });
+
+describe('fixtures: OPENWOP_OPTED_OUT_FIXTURES env filtering', () => {
+  // The opt-out predicate is re-read inside setAdvertisedFixtures() on
+  // every call, so mutating process.env between cases (and re-calling
+  // setAdvertisedFixtures) re-evaluates the parse. afterEach restores
+  // the original env so other suites aren't affected.
+  const ORIGINAL = process.env.OPENWOP_OPTED_OUT_FIXTURES;
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.OPENWOP_OPTED_OUT_FIXTURES;
+    else process.env.OPENWOP_OPTED_OUT_FIXTURES = ORIGINAL;
+  });
+
+  it('exact id is filtered out of the advertised set', () => {
+    process.env.OPENWOP_OPTED_OUT_FIXTURES = 'conformance-dispatch-input-mapping';
+    setAdvertisedFixtures({
+      fixtures: ['conformance-noop', 'conformance-dispatch-input-mapping'],
+    });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(true);
+    expect(isFixtureAdvertised('conformance-dispatch-input-mapping')).toBe(false);
+  });
+
+  it('trailing-* glob filters every matching id', () => {
+    process.env.OPENWOP_OPTED_OUT_FIXTURES = 'conformance-dispatch-*';
+    setAdvertisedFixtures({
+      fixtures: [
+        'conformance-noop',
+        'conformance-dispatch-input-mapping',
+        'conformance-dispatch-output-mapping',
+        'conformance-dispatch-cross-worker-handoff',
+      ],
+    });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(true);
+    expect(isFixtureAdvertised('conformance-dispatch-input-mapping')).toBe(false);
+    expect(isFixtureAdvertised('conformance-dispatch-output-mapping')).toBe(false);
+    expect(isFixtureAdvertised('conformance-dispatch-cross-worker-handoff')).toBe(false);
+  });
+
+  it('exact + glob entries mix in one env value', () => {
+    process.env.OPENWOP_OPTED_OUT_FIXTURES =
+      'conformance-dispatch-*,conformance-subworkflow-input-mapping';
+    setAdvertisedFixtures({
+      fixtures: [
+        'conformance-noop',
+        'conformance-dispatch-input-mapping',
+        'conformance-subworkflow-input-mapping',
+        'conformance-subworkflow-parent',
+      ],
+    });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(true);
+    expect(isFixtureAdvertised('conformance-dispatch-input-mapping')).toBe(false);
+    expect(isFixtureAdvertised('conformance-subworkflow-input-mapping')).toBe(false);
+    // subworkflow-parent is NOT subworkflow-input-mapping — exact match required.
+    expect(isFixtureAdvertised('conformance-subworkflow-parent')).toBe(true);
+  });
+
+  it('non-matching opt-out entries leave the advertised set intact', () => {
+    process.env.OPENWOP_OPTED_OUT_FIXTURES = 'conformance-nonexistent';
+    setAdvertisedFixtures({ fixtures: ['conformance-noop'] });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(true);
+    expect(getAdvertisedFixtures()?.size).toBe(1);
+  });
+
+  it('empty / whitespace-only entries are ignored', () => {
+    process.env.OPENWOP_OPTED_OUT_FIXTURES = ', ,conformance-noop, ,';
+    setAdvertisedFixtures({ fixtures: ['conformance-noop', 'conformance-delay'] });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(false);
+    expect(isFixtureAdvertised('conformance-delay')).toBe(true);
+  });
+
+  it('unset env behaves identically to no filtering', () => {
+    delete process.env.OPENWOP_OPTED_OUT_FIXTURES;
+    setAdvertisedFixtures({ fixtures: ['conformance-noop', 'conformance-delay'] });
+    expect(getAdvertisedFixtures()?.size).toBe(2);
+  });
+
+  it('whitespace-only env behaves identically to unset', () => {
+    process.env.OPENWOP_OPTED_OUT_FIXTURES = '   ';
+    setAdvertisedFixtures({ fixtures: ['conformance-noop'] });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(true);
+  });
+
+  it('env is re-read on each setAdvertisedFixtures call (no memoization)', () => {
+    process.env.OPENWOP_OPTED_OUT_FIXTURES = 'conformance-noop';
+    setAdvertisedFixtures({ fixtures: ['conformance-noop', 'conformance-delay'] });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(false);
+
+    // Mutate env and re-set — the new env value MUST take effect.
+    process.env.OPENWOP_OPTED_OUT_FIXTURES = 'conformance-delay';
+    setAdvertisedFixtures({ fixtures: ['conformance-noop', 'conformance-delay'] });
+    expect(isFixtureAdvertised('conformance-noop')).toBe(true);
+    expect(isFixtureAdvertised('conformance-delay')).toBe(false);
+  });
+});
+
+describe('env: OPENWOP_OPTED_OUT_SCENARIOS predicate', () => {
+  const ORIGINAL = process.env.OPENWOP_OPTED_OUT_SCENARIOS;
+  afterEach(() => {
+    if (ORIGINAL === undefined) delete process.env.OPENWOP_OPTED_OUT_SCENARIOS;
+    else process.env.OPENWOP_OPTED_OUT_SCENARIOS = ORIGINAL;
+  });
+
+  it('unset env → every scenario id returns false', () => {
+    delete process.env.OPENWOP_OPTED_OUT_SCENARIOS;
+    expect(isScenarioOptedOut('otel-trace-propagation-subworkflow')).toBe(false);
+    expect(isScenarioOptedOut('any-scenario')).toBe(false);
+  });
+
+  it('exact scenario id match returns true', () => {
+    process.env.OPENWOP_OPTED_OUT_SCENARIOS = 'otel-trace-propagation-subworkflow';
+    expect(isScenarioOptedOut('otel-trace-propagation-subworkflow')).toBe(true);
+    expect(isScenarioOptedOut('otel-trace-propagation')).toBe(false);
+  });
+
+  it('CSV with multiple ids matches each entry exactly', () => {
+    process.env.OPENWOP_OPTED_OUT_SCENARIOS = 'scenario-a,scenario-b,scenario-c';
+    expect(isScenarioOptedOut('scenario-a')).toBe(true);
+    expect(isScenarioOptedOut('scenario-b')).toBe(true);
+    expect(isScenarioOptedOut('scenario-c')).toBe(true);
+    expect(isScenarioOptedOut('scenario-d')).toBe(false);
+  });
+
+  it('whitespace around entries is tolerated', () => {
+    process.env.OPENWOP_OPTED_OUT_SCENARIOS = '  scenario-a , scenario-b  ';
+    expect(isScenarioOptedOut('scenario-a')).toBe(true);
+    expect(isScenarioOptedOut('scenario-b')).toBe(true);
+  });
+
+  it('env is re-read on each call (no memoization)', () => {
+    process.env.OPENWOP_OPTED_OUT_SCENARIOS = 'scenario-a';
+    expect(isScenarioOptedOut('scenario-a')).toBe(true);
+    expect(isScenarioOptedOut('scenario-b')).toBe(false);
+
+    process.env.OPENWOP_OPTED_OUT_SCENARIOS = 'scenario-b';
+    expect(isScenarioOptedOut('scenario-a')).toBe(false);
+    expect(isScenarioOptedOut('scenario-b')).toBe(true);
+  });
+});