@openwop/openwop-conformance 2.0.0-rc.0 → 2.0.0-rc.2

package/src/scenarios/v2-coherence-not-in-bundle.test.ts

@@ -0,0 +1,98 @@
+/**
+ * v2-coherence-not-in-bundle — RFC 0168 §D.1; `spec/v2/core/conformance.md`
+ * §"Two products, two ledgers".
+ *
+ * Suite 2.0.0. Corpus-coherence checks run in the spec repo's CI and MUST NOT
+ * appear in a host bundle; the bundle schema forbids their ids. Unaided and
+ * fixture-based — no host is consulted:
+ *
+ *   1. disjoint by construction: every id in `evidence/corpus-ledger.json`
+ *      belongs to a scenario in `src/coherence/` and to none in
+ *      `src/scenarios/` (a derived `openwop.it.<stem>.…` id resolves to its
+ *      file; an explicit `req()` id is located by its literal in the sources),
+ *      so a bundle produced from the scenarios directory cannot carry one.
+ *   2. the bundle schema rejects a v3 fixture whose `results.requirements[]`
+ *      carries an id under `openwop.it.spec-corpus-validity.` and accepts the
+ *      same fixture under an `openwop.requirement.` id.
+ *
+ * @see RFCS/0168-v2-evidence-and-conformance.md §D.1
+ * @see spec/v2/core/conformance.md §"Two products, two ledgers"
+ * @see schemas/v2/certification-bundle.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { generateKeyPairSync } from 'node:crypto';
+import { join } from 'node:path';
+import { SCHEMAS_DIR, SCENARIOS_DIR } from '../lib/paths.js';
+import { req } from '../lib/requirement-ids.js';
+import { scenarioFileOfId } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { v2Validator } from '../lib/v2.js';
+import { signBundleV3, witnessDigest, type BundleV3, type BundleV3Requirement } from '../lib/certification-bundle-v3.js';
+
+const SECTION = 'conformance.md §"Two products, two ledgers" (RFC 0168 §D.1)';
+const LEDGER = join(SCHEMAS_DIR, '..', 'evidence', 'corpus-ledger.json');
+const COHERENCE_DIR = SCENARIOS_DIR === null ? null : join(SCENARIOS_DIR, '..', 'coherence');
+
+function sources(dir: string): Map<string, string> {
+  return new Map(readdirSync(dir).filter((f) => f.endsWith('.test.ts')).map((f) => [f, readFileSync(join(dir, f), 'utf8')]));
+}
+
+function bundleWith(rows: BundleV3Requirement[]): BundleV3 {
+  const { privateKey } = generateKeyPairSync('ed25519');
+  const pem = privateKey.export({ type: 'pkcs8', format: 'pem' }) as string;
+  const unsigned: Omit<BundleV3, 'signature'> = {
+    bundleVersion: '3',
+    generatedAt: new Date().toISOString(),
+    suite: { name: '@openwop/openwop-conformance', version: '2.0.0', targetMajor: 2, specArtifactsVersion: '2.0.0' },
+    host: { name: 'fixture-host', version: '0.0.0', build: { kind: 'commit', id: 'fixture' } },
+    discovery: { url: 'https://host.invalid/.well-known/openwop', sha256: 'a'.repeat(64), protocolVersions: ['2.0'], preferredVersion: '2.0' },
+    claimedProfiles: [{ id: 'openwop-core-v2', evidenceTier: 'self', witnessCount: rows.length, certified: true }],
+    results: { totals: { executedPass: rows.length, executedFail: 0, skipped: 0, inapplicable: 0, blocked: 0 }, requirements: rows },
+    witnessSha256: witnessDigest(rows),
+    assertionCount: rows.reduce((n, r) => n + (r.assertions ?? 0), 0),
+  };
+  return { ...unsigned, signature: signBundleV3(unsigned, pem, 'fixture-host-key') };
+}
+
+describe('v2-coherence-not-in-bundle (RFC 0168 §D.1)', () => {
+  it('every corpus-ledger id has a scenario in src/coherence and none in src/scenarios — the two id sets are disjoint by construction', () => {
+    if (!existsSync(LEDGER)) return softSkip('blocked', 'evidence/corpus-ledger.json is absent from this layout — the corpus id set cannot be read');
+    if (SCENARIOS_DIR === null || COHERENCE_DIR === null || !existsSync(COHERENCE_DIR)) return softSkip('blocked', 'src/scenarios or src/coherence is absent from this layout');
+    const ledger = JSON.parse(readFileSync(LEDGER, 'utf8')) as { requirements: Record<string, unknown> };
+    const ids = Object.keys(ledger.requirements);
+    expect(ids.length, req('openwop.requirement.0168.coherence-not-in-bundle.disjoint-by-construction', SECTION, 'the corpus ledger MUST carry at least one requirement id')).toBeGreaterThan(0);
+    const coherence = sources(COHERENCE_DIR);
+    const scenarios = sources(SCENARIOS_DIR);
+    const coherenceText = [...coherence.values()].join('\n');
+    const scenariosText = [...scenarios.values()].join('\n');
+    for (const id of ids) {
+      // `openwop.profile.*` / `openwop.family.*` are capability-GATE rows minted
+      // at run time by gateFamily(), not by a `req()` literal and not derived
+      // from a file. The same gate id is recorded by a corpus run and a host run
+      // alike, so it is shared by construction and carries no corpus content —
+      // the disjointness rule does not reach it.
+      if (id.startsWith('openwop.profile.') || id.startsWith('openwop.family.')) continue;
+      const file = scenarioFileOfId(id);
+      if (file !== null) {
+        expect(coherence.has(file), req('openwop.requirement.0168.coherence-not-in-bundle.disjoint-by-construction', SECTION, `${id} MUST belong to a src/coherence scenario (${file})`)).toBe(true);
+        expect(scenarios.has(file), req('openwop.requirement.0168.coherence-not-in-bundle.disjoint-by-construction', SECTION, `${id} MUST NOT belong to a src/scenarios file (${file}) — it would enter a host bundle`)).toBe(false);
+      } else {
+        const literal = `'${id}'`;
+        expect(coherenceText.includes(literal), req('openwop.requirement.0168.coherence-not-in-bundle.disjoint-by-construction', SECTION, `${id} MUST be cited by req() in a src/coherence scenario`)).toBe(true);
+        expect(scenariosText.includes(literal), req('openwop.requirement.0168.coherence-not-in-bundle.disjoint-by-construction', SECTION, `${id} MUST NOT be cited by req() in a src/scenarios file — it would enter a host bundle`)).toBe(false);
+      }
+    }
+  });
+
+  it('the bundle schema rejects a v3 bundle carrying a corpus-coherence id and accepts one under openwop.requirement.', () => {
+    const validate = v2Validator('certification-bundle');
+    const corpusRow: BundleV3Requirement = { id: 'openwop.it.spec-corpus-validity.every-fixture-validates', scenario: 'spec-corpus-validity.test.ts', result: 'executed-pass', assertions: 1 };
+    const hostRow: BundleV3Requirement = { id: 'openwop.requirement.0168.coherence-not-in-bundle.fixture', scenario: 'v2-coherence-not-in-bundle.test.ts', result: 'executed-pass', assertions: 1 };
+    const control = validate(bundleWith([hostRow]));
+    expect(control.ok, req('openwop.requirement.0168.coherence-not-in-bundle.schema-forbids-coherence-ids', SECTION, `a v3 bundle whose rows are openwop.requirement. ids MUST validate (${control.errors})`)).toBe(true);
+    const tainted = validate(bundleWith([hostRow, corpusRow]));
+    expect(tainted.ok, req('openwop.requirement.0168.coherence-not-in-bundle.schema-forbids-coherence-ids', SECTION, 'a v3 bundle carrying an openwop.it.spec-corpus-validity. id MUST be rejected by the bundle schema')).toBe(false);
+  });
+});

package/src/scenarios/v2-compensation-read-projection.test.ts

@@ -0,0 +1,85 @@
+/**
+ * RFC 0173 §B — `compensation-read-projection` (suite 2.0.0, target major 2; gated on `compensation`).
+ *
+ * Compensation is a core obligation with a declared witness: a host that
+ * advertises `compensation` MUST serve `GET /runs/{runId}/compensation`
+ * (`api/v2/openapi.yaml` `getRunCompensation`,
+ * `schemas/v2/compensation-projection.schema.json`) — `{ runId, status, plan[],
+ * attempts[] }` — so the obligation is deployed-wire evidence rather than
+ * seam-only (RFC 0151 G9; RFC 0173 §B row C6.6; `spec/v2/core/security-defaults.md`
+ * §Compensation).
+ *
+ * A fresh run of the noop fixture has nothing to compensate: the projection
+ * validates with `status: "none"`, an empty plan and no attempts. An unknown
+ * run is `404 not_found` through the canonical envelope.
+ *
+ * @see spec/v2/core/security-defaults.md §Compensation
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { v2Discovery, gateFamily, v2Validator } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const FIXTURE = 'conformance-noop';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+async function waitTerminal(runId: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}`);
+    if (res.status === 200 && TERMINAL.has(String((res.json as { status?: unknown } | null)?.status))) return;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+describe('RFC 0173 §B — compensation-read-projection (gated on compensation)', () => {
+  it('GET /runs/{runId}/compensation on a fresh run validates with status none', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('compensation'))) return softSkip('inapplicable', 'compensation family not advertised — no obligation (gate recorded under openwop.family.compensation)');
+    const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+    if (!fixtures.includes(FIXTURE)) return softSkip('inapplicable', `${FIXTURE} fixture not advertised — no run to project`);
+
+    const create = await driver.post('/runs', { workflowId: FIXTURE });
+    expect(create.status, req('openwop.requirement.0173.compensation-read-projection', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await waitTerminal(runId, 10_000);
+
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}/compensation`);
+    expect(
+      res.status,
+      req('openwop.requirement.0173.compensation-read-projection', 'security-defaults.md §Compensation', 'a host advertising `compensation` MUST serve GET /runs/{runId}/compensation with 200 (RFC 0173 §B — the read projection is the obligation\'s witness)'),
+    ).toBe(200);
+    const check = v2Validator('compensation-projection')(res.json);
+    expect(
+      check.ok,
+      req('openwop.requirement.0173.compensation-read-projection', 'compensation-projection.schema.json', `the projection MUST validate: ${check.errors}`),
+    ).toBe(true);
+    const body = res.json as { runId?: unknown; status?: unknown; plan?: unknown[]; attempts?: unknown[] };
+    expect(body.runId, req('openwop.requirement.0173.compensation-read-projection', 'compensation-projection.schema.json runId', 'runId MUST echo the run read')).toBe(runId);
+    expect(
+      body.status,
+      req('openwop.requirement.0173.compensation-read-projection', 'compensation-projection.schema.json status', 'a run with nothing to compensate MUST project status "none"'),
+    ).toBe('none');
+    expect(body.attempts, req('openwop.requirement.0173.compensation-read-projection', 'compensation-projection.schema.json attempts', 'no attempt exists before an unwind')).toEqual([]);
+  });
+
+  it('an unknown run projects 404 not_found through the canonical envelope', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('compensation'))) return softSkip('inapplicable', 'compensation family not advertised — no obligation (gate recorded under openwop.family.compensation)');
+    const res = await driver.get('/runs/conformance-no-such-run-0173/compensation');
+    expect(res.status, req('openwop.requirement.0173.compensation-read-projection.not-found', 'openapi.yaml getRunCompensation 404', 'an unknown runId MUST answer 404')).toBe(404);
+    expect(
+      readErrorCode(res.json),
+      req('openwop.requirement.0173.compensation-read-projection.not-found', 'errors.md §Envelope', 'the 404 MUST carry the registered not_found code in the flat envelope'),
+    ).toBe('not_found');
+  });
+});

package/src/scenarios/v2-configurable-closed.test.ts

@@ -0,0 +1,67 @@
+/**
+ * v2 — `configurable-closed` (suite 2.0.0; RFC 0171 §D.1;
+ * `spec/v2/core/runs.md` §"RunOptions" / `configurable`;
+ * `schemas/v2/configurable.schema.json`).
+ *
+ * Witness class: witnessable — unaided. `configurable` is a closed, nested,
+ * versioned object. A dotted key (`ai.provider` as a string key inside a
+ * section) and an unknown root key MUST be rejected with
+ * `400 validation_error`. The schema leg is server-free (the closure is a
+ * property of the standalone artifact); the two wire legs post the bodies to
+ * `POST /runs` and record `blocked` when the host refuses the control body
+ * for a reason unrelated to `configurable`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/runs.md §configurable';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+const DOTTED = { version: 1, ai: { 'ai.provider': 'x' } };
+const UNKNOWN = { version: 1, unknownKey: 1 };
+const CONTROL = { version: 1 };
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+/** Post a body; when the CONTROL body is itself refused the wire leg is blocked. */
+async function probe(configurable: Record<string, unknown>): Promise<OpenWOPResponse | { reason: string }> {
+  if (!(await discovery())) return { reason: 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0' };
+  const control = await http(() => driver.post('/runs', { workflowId: NOOP_WORKFLOW_ID, configurable: CONTROL }));
+  if (control === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  if (control.status !== 201) return { reason: `POST /runs with the control body { version: 1 } answered ${control.status} ${readErrorCode(control.json) ?? ''} — the create itself is refused, so the closure of configurable cannot be observed (fixture not seeded?)`.trim() };
+  const res = await http(() => driver.post('/runs', { workflowId: NOOP_WORKFLOW_ID, configurable }));
+  return res ?? { reason: 'POST /runs unreachable (fetch failed)' };
+}
+
+describe('v2 configurable-closed (RFC 0171 §D.1)', () => {
+  it('the standalone schema rejects a dotted key and an unknown root key and accepts the versioned control', () => {
+    const validate = v2Validator('configurable');
+    expect(validate(CONTROL).ok, req('openwop.requirement.0171.configurable-closed.schema', DOC, '{ version: 1 } is the smallest valid configurable (version REQUIRED, const 1)')).toBe(true);
+    expect(validate(DOTTED).ok, req('openwop.requirement.0171.configurable-closed.schema', DOC, 'a dotted key (`ai.provider` as a string key) MUST fail the closed nested schema')).toBe(false);
+    expect(validate(UNKNOWN).ok, req('openwop.requirement.0171.configurable-closed.schema', DOC, 'an unknown root key MUST fail the closed schema (additionalProperties: false in the standalone artifact)')).toBe(false);
+    expect(validate({ ai: { provider: 'x' } }).ok, req('openwop.requirement.0171.configurable-closed.schema', DOC, 'a configurable without `version` MUST fail')).toBe(false);
+  });
+
+  it('POST /runs rejects a dotted key with 400 validation_error', async () => {
+    const res = await probe(DOTTED);
+    if ('reason' in res) return softSkip('blocked', res.reason);
+    expect(res.status, req('openwop.requirement.0171.configurable-closed.dotted-key', DOC, 'a dotted key inside a section MUST be rejected with 400')).toBe(400);
+    expect(readErrorCode(res.json), req('openwop.requirement.0171.configurable-closed.dotted-key', DOC, 'the refusal code MUST be validation_error')).toBe('validation_error');
+  });
+
+  it('POST /runs rejects an unknown root key with 400 validation_error', async () => {
+    const res = await probe(UNKNOWN);
+    if ('reason' in res) return softSkip('blocked', res.reason);
+    expect(res.status, req('openwop.requirement.0171.configurable-closed.unknown-key', DOC, 'an unknown root key MUST be rejected with 400')).toBe(400);
+    expect(readErrorCode(res.json), req('openwop.requirement.0171.configurable-closed.unknown-key', DOC, 'the refusal code MUST be validation_error')).toBe('validation_error');
+  });
+});

package/src/scenarios/v2-dual-stack-negotiation.test.ts

@@ -0,0 +1,118 @@
+/**
+ * v2 — `dual-stack-negotiation` (suite 2.0.0; RFC 0172 §A.3–§A.4;
+ * `spec/v2/core/versioning.md` §1.3 "The request header", §1.4 "The response
+ * header", §5 "The overlap").
+ *
+ * Witness class: witnessable — gated on two majors. Unless `protocolVersions[]`
+ * carries both a `1.x` and a `2.x` member the file records `inapplicable`. On a
+ * dual-advertising host: a run created through `/v1/runs` with NO
+ * `OpenWOP-Version` header is readable through `GET /runs/{runId}` under
+ * `OpenWOP-Version: 2.0`; an unlisted major (`9.0`) is `406
+ * protocol_version_unsupported` with `details.protocolVersions[]`;
+ * `OpenWOP-Version: 2.0` on a `/v1/…` path is `400 protocol_version_mismatch`;
+ * every response's `OpenWOP-Version` equals the contract that produced it. The
+ * header-less v1 call bypasses the driver (which stamps `OpenWOP-Version: 2.0`
+ * under target major 2) with a raw `fetch` against the same base URL.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { loadEnv } from '../lib/env.js';
+import { v2Discovery } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/versioning.md §1.3';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+/** Raw request with exactly the headers given — no OpenWOP-Version unless named. */
+async function raw(method: string, path: string, headers: Record<string, string>, body?: unknown): Promise<OpenWOPResponse | null> {
+  try {
+    const env = loadEnv();
+    const init: RequestInit = { method, headers: { Accept: 'application/json', Authorization: `Bearer ${env.apiKey}`, ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}), ...headers } };
+    if (body !== undefined) init.body = JSON.stringify(body);
+    const res = await fetch(`${env.baseUrl}${path}`, init);
+    const text = await res.text();
+    let json: unknown;
+    try { json = text.length > 0 ? JSON.parse(text) : undefined; } catch { json = undefined; }
+    return { status: res.status, headers: res.headers, text, json };
+  } catch {
+    return null;
+  }
+}
+
+function major(res: OpenWOPResponse | null): string | null {
+  const v = res?.headers.get('openwop-version')?.trim();
+  return v === undefined ? null : (v.split('.')[0] ?? null);
+}
+
+async function gate(): Promise<{ versions: string[] } | { kind: 'blocked' | 'inapplicable'; reason: string }> {
+  const doc = await discovery();
+  if (!doc) return { kind: 'blocked', reason: 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0' };
+  const versions = Array.isArray(doc['protocolVersions']) ? (doc['protocolVersions'] as unknown[]).filter((v): v is string => typeof v === 'string') : [];
+  const has1 = versions.some((v) => v.startsWith('1.'));
+  const has2 = versions.some((v) => v.startsWith('2.'));
+  if (!(has1 && has2)) return { kind: 'inapplicable', reason: `protocolVersions [${versions.join(', ')}] does not carry both a 1.x and a 2.x member — dual-stack negotiation is gated on two majors` };
+  return { versions };
+}
+
+describe('v2 dual-stack-negotiation (RFC 0172 §A.3–§A.4 — gated on two majors)', () => {
+  it('a run created through /v1/runs with no header is readable through /runs under OpenWOP-Version: 2.0', async () => {
+    const g = await gate();
+    if ('kind' in g) return softSkip(g.kind, g.reason);
+    const created = await raw('POST', '/v1/runs', {}, { workflowId: NOOP_WORKFLOW_ID });
+    if (created === null) return softSkip('blocked', 'POST /v1/runs unreachable (fetch failed)');
+    const runId = (created.json as { runId?: unknown } | undefined)?.runId;
+    if (created.status !== 201 || typeof runId !== 'string') return softSkip('blocked', `POST /v1/runs {workflowId: ${NOOP_WORKFLOW_ID}} with no header answered ${created.status} ${readErrorCode(created.json) ?? ''} — the v1 create was refused (fixture not seeded?)`);
+    expect(major(created), req('openwop.requirement.0172.dual-stack-negotiation.cross-major-read', 'spec/v2/core/versioning.md §1.4', 'a /v1/ response MUST report the 1.x contract that produced it')).toBe('1');
+    const read = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}`, { headers: { 'OpenWOP-Version': '2.0' } }));
+    if (read === null) return softSkip('blocked', 'GET /runs/{runId} unreachable (fetch failed)');
+    expect(read.status, req('openwop.requirement.0172.dual-stack-negotiation.cross-major-read', 'spec/v2/core/versioning.md §5', 'the overlap: a run created through /v1/runs MUST be readable through GET /runs/{runId} with OpenWOP-Version: 2.0')).toBe(200);
+    expect((read.json as { runId?: unknown } | undefined)?.runId, req('openwop.requirement.0172.dual-stack-negotiation.cross-major-read', 'spec/v2/core/versioning.md §5', 'the v2 read MUST name the same run')).toBe(runId);
+    expect(major(read), req('openwop.requirement.0172.dual-stack-negotiation.cross-major-read', 'spec/v2/core/versioning.md §1.4', 'the v2 read MUST report the 2.x contract that produced it')).toBe('2');
+  });
+
+  it('an unlisted major is 406 protocol_version_unsupported with details.protocolVersions[]', async () => {
+    const g = await gate();
+    if ('kind' in g) return softSkip(g.kind, g.reason);
+    const res = await http(() => driver.get('/.well-known/openwop', { authenticated: false, headers: { 'OpenWOP-Version': '9.0' } }));
+    if (res === null) return softSkip('blocked', 'GET /.well-known/openwop unreachable (fetch failed)');
+    expect(res.status, req('openwop.requirement.0172.dual-stack-negotiation.unlisted-major', DOC, 'a header naming a major not in protocolVersions[] MUST be answered 406')).toBe(406);
+    expect(readErrorCode(res.json), req('openwop.requirement.0172.dual-stack-negotiation.unlisted-major', DOC, 'the refusal code MUST be protocol_version_unsupported')).toBe('protocol_version_unsupported');
+    const echoed = (res.json as { details?: { protocolVersions?: unknown } } | undefined)?.details?.protocolVersions;
+    expect(Array.isArray(echoed) ? [...echoed].sort() : echoed, req('openwop.requirement.0172.dual-stack-negotiation.unlisted-major', DOC, 'details.protocolVersions[] MUST echo the advertised list')).toEqual([...g.versions].sort());
+  });
+
+  it('OpenWOP-Version: 2.0 on a /v1/ path is 400 protocol_version_mismatch', async () => {
+    const g = await gate();
+    if ('kind' in g) return softSkip(g.kind, g.reason);
+    const res = await http(() => driver.get('/v1/openapi.json', { authenticated: false, headers: { 'OpenWOP-Version': '2.0' } }));
+    if (res === null) return softSkip('blocked', 'GET /v1/openapi.json unreachable (fetch failed)');
+    expect(res.status, req('openwop.requirement.0172.dual-stack-negotiation.v1-path-mismatch', DOC, 'a /v1/… path with OpenWOP-Version other than 1 MUST be answered 400')).toBe(400);
+    expect(readErrorCode(res.json), req('openwop.requirement.0172.dual-stack-negotiation.v1-path-mismatch', DOC, 'the refusal code MUST be protocol_version_mismatch')).toBe('protocol_version_mismatch');
+  });
+
+  it('every response reports the contract that produced it', async () => {
+    const g = await gate();
+    if ('kind' in g) return softSkip(g.kind, g.reason);
+    const v1 = await raw('GET', '/v1/openapi.json', {});
+    const v1Named = await raw('GET', '/v1/openapi.json', { 'OpenWOP-Version': '1.0' });
+    const v2 = await http(() => driver.get('/.well-known/openwop', { authenticated: false, headers: { 'OpenWOP-Version': '2.0' } }));
+    if (v1 === null || v1Named === null || v2 === null) return softSkip('blocked', 'a probe was unreachable (fetch failed)');
+    expect(major(v1), req('openwop.requirement.0172.dual-stack-negotiation.response-header', 'spec/v2/core/versioning.md §1.4', 'a header-less /v1/ response MUST carry OpenWOP-Version: 1.<minor> — the contract used, never another (silent downgrade)')).toBe('1');
+    expect(major(v1Named), req('openwop.requirement.0172.dual-stack-negotiation.response-header', 'spec/v2/core/versioning.md §1.4', 'a /v1/ response under OpenWOP-Version: 1.0 MUST carry OpenWOP-Version: 1.<minor>')).toBe('1');
+    expect(major(v2), req('openwop.requirement.0172.dual-stack-negotiation.response-header', 'spec/v2/core/versioning.md §1.4', 'a response under OpenWOP-Version: 2.0 MUST carry OpenWOP-Version: 2.<minor>')).toBe('2');
+    for (const res of [v1, v1Named, v2]) {
+      const v = res.headers.get('openwop-version')?.trim() ?? '';
+      expect(g.versions.includes(v), req('openwop.requirement.0172.dual-stack-negotiation.response-header', 'spec/v2/core/versioning.md §1.4', `the reported contract (${v}) MUST be a member of the advertised protocolVersions[]`)).toBe(true);
+    }
+  });
+});

package/src/scenarios/v2-effect-identity-business-key.test.ts

@@ -0,0 +1,132 @@
+/**
+ * RFC 0173 §B — `effect-identity-business-key` (suite 2.0.0, target major 2; gated on `idempotency`).
+ *
+ * Layer-2 effect identity is a core obligation keyed on business identity: a
+ * host that advertises `idempotency` assigns a logical effect id once per
+ * effect, stable across transport retries, injects it as the provider's
+ * idempotency key, and serves `GET /runs/{runId}/effects`
+ * (`schemas/v2/effect-ledger-projection.schema.json`) — each row
+ * `{ effectId, nodeId, attempt, keying: business-identity | activity-recipe,
+ * state, at }`, content-free of provider payloads (RFC 0150 §B; RFC 0173 §B row
+ * C6.7; `spec/v2/core/security-defaults.md` §Layer-2 effect identity).
+ *
+ * Legs:
+ *   1. the ledger read validates on a run of the noop fixture and every row's
+ *      `keying` is one of the two documented modes;
+ *   2. the "same provider key across two transport retries" leg needs the
+ *      suite's fixture provider (RFC 0173 §D.2 G4 — a provider that rejects a
+ *      changed key) driven through the seams profile; no such seam is
+ *      catalogued, so that leg records `blocked` naming it.
+ *
+ * @see spec/v2/core/security-defaults.md §Layer-2 effect identity
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { v2Discovery, gateFamily, v2Validator } from '../lib/v2.js';
+import { seamsProfileAdvertised, SEAMS_PREFIX } from '../lib/seams.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const FIXTURE = 'conformance-noop';
+const KEYING = ['business-identity', 'activity-recipe'];
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+async function waitTerminal(runId: string, timeoutMs: number): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}`);
+    if (res.status === 200 && TERMINAL.has(String((res.json as { status?: unknown } | null)?.status))) return;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+describe('RFC 0173 §B — effect-identity-business-key (gated on idempotency)', () => {
+  it('GET /runs/{runId}/effects validates and every row is keyed on business identity or the activity recipe', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('idempotency'))) return softSkip('inapplicable', 'idempotency family not advertised — no Layer-2 obligation (gate recorded under openwop.family.idempotency)');
+    const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+    if (!fixtures.includes(FIXTURE)) return softSkip('inapplicable', `${FIXTURE} fixture not advertised — no run to read`);
+
+    const create = await driver.post('/runs', { workflowId: FIXTURE });
+    expect(create.status, req('openwop.requirement.0173.effect-identity-business-key', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await waitTerminal(runId, 10_000);
+
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}/effects`);
+    expect(
+      res.status,
+      req('openwop.requirement.0173.effect-identity-business-key', 'security-defaults.md §Layer-2 effect identity', 'a host advertising `idempotency` MUST serve GET /runs/{runId}/effects with 200 (RFC 0173 §B)'),
+    ).toBe(200);
+    const check = v2Validator('effect-ledger-projection')(res.json);
+    expect(
+      check.ok,
+      req('openwop.requirement.0173.effect-identity-business-key', 'effect-ledger-projection.schema.json', `the ledger projection MUST validate: ${check.errors}`),
+    ).toBe(true);
+    const body = res.json as { runId?: unknown; effects?: Array<{ effectId?: unknown; keying?: unknown; providerKey?: unknown }> };
+    expect(body.runId, req('openwop.requirement.0173.effect-identity-business-key', 'effect-ledger-projection.schema.json runId', 'runId MUST echo the run read')).toBe(runId);
+    const effects = body.effects ?? [];
+    const ids = new Set<string>();
+    for (const e of effects) {
+      expect(
+        KEYING,
+        req('openwop.requirement.0173.effect-identity-business-key', 'security-defaults.md §Layer-2 effect identity', `keying MUST be business-identity or activity-recipe (the documented fallback) — effect ${String(e.effectId)} declares ${String(e.keying)}`),
+      ).toContain(e.keying);
+      // One logical effect id per effect: a duplicate row is a re-assignment.
+      expect(
+        ids.has(String(e.effectId)),
+        req('openwop.requirement.0173.effect-identity-business-key', 'RFC 0150 §B', `effectId ${String(e.effectId)} MUST be assigned once per effect (duplicate ledger row)`),
+      ).toBe(false);
+      ids.add(String(e.effectId));
+      if (typeof e.providerKey === 'string') {
+        expect(
+          /(secret|bearer |sk-[a-z0-9]{8,})/i.test(e.providerKey),
+          req('openwop.requirement.0173.effect-identity-business-key', 'effect-ledger-projection.schema.json providerKey', 'providerKey is a redaction-safe identity, never credential material'),
+        ).toBe(false);
+      }
+    }
+    if (effects.length === 0) softSkip('inapplicable', 'the noop fixture issued no external effect — the per-row keying leg had no rows (an effect-issuing fixture would exercise it)');
+  });
+
+  it('the same provider key is presented across two transport retries', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('idempotency'))) return softSkip('inapplicable', 'idempotency family not advertised — no Layer-2 obligation (gate recorded under openwop.family.idempotency)');
+    if (!seamsProfileAdvertised(doc)) return softSkip('blocked', 'the retry leg is driven through the suite fixture provider (RFC 0173 §D.2 G4) under the seams profile — seams profile not advertised');
+    // The seam is catalogued (api/seams-v2.yaml `forceEffectTransportRetry`). An
+    // unreachable providerUrl forces the transport retry; the witness is the
+    // host's own Layer-2 ledger (RFC 0173 §C.2), where every attempt of one
+    // effect MUST carry the same business-identity key.
+    const fired = await driver.post(`${SEAMS_PREFIX}/sample/test/idempotency/effect-retry`, { providerUrl: 'http://127.0.0.1:1/' });
+    if (fired.status === 404 || fired.status === 403 || fired.status === 405) {
+      return softSkip('blocked', `the host advertises the seams profile but does not serve ${SEAMS_PREFIX}/sample/test/idempotency/effect-retry (answered ${fired.status}) — the cross-retry keying leg cannot be driven`);
+    }
+    const body = fired.json as { runId?: unknown; effectId?: unknown } | null;
+    if (fired.status !== 201 || typeof body?.runId !== 'string' || typeof body?.effectId !== 'string') {
+      return softSkip('blocked', `${SEAMS_PREFIX}/sample/test/idempotency/effect-retry answered ${fired.status} without { runId, effectId } — the seam contract in api/seams-v2.yaml is 201 { runId, effectId }`);
+    }
+    const ledger = await driver.get(`/runs/${body.runId}/effects`);
+    if (ledger.status !== 200) return softSkip('blocked', `GET /runs/{runId}/effects answered ${ledger.status} — the ledger is the witness for cross-retry keying`);
+    const all = ((ledger.json as { effects?: unknown } | null)?.effects ?? []) as Array<Record<string, unknown>>;
+    const attempts = all.filter((e) => e['effectId'] === body.effectId);
+    if (attempts.length < 2) {
+      return softSkip('blocked', `the seam produced ${attempts.length} ledger row(s) for effect ${String(body.effectId)} — a cross-retry assertion needs at least two attempts`);
+    }
+    const keys = new Set(attempts.map((e) => String(e['providerKey'] ?? '')));
+    expect(
+      keys.size,
+      req('openwop.requirement.0173.effect-identity-business-key.retry', 'spec/v2/core/replay.md §Effect identity', `every attempt of one effect MUST present the same provider key across a transport retry — ${attempts.length} attempt(s) presented ${keys.size} distinct key(s)`),
+    ).toBe(1);
+    for (const a of attempts) {
+      expect(
+        a['keying'],
+        req('openwop.requirement.0173.effect-identity-business-key.retry', 'spec/v2/core/replay.md §Effect identity', `a Layer-2 host keys a retried effect on business identity, not the activity recipe (attempt ${String(a['attempt'])})`),
+      ).toBe('business-identity');
+    }
+  });
+});