@openwop/openwop-conformance 2.36.1 → 2.37.0

package/src/lib/oidc-issuer.ts

@@ -19,6 +19,7 @@
 import {
   createSign,
   generateKeyPairSync,
+  randomBytes,
   type KeyObject,
 } from 'node:crypto';
 
@@ -166,10 +167,22 @@ export function createSyntheticOIDCIssuer(
     throw new Error('[oidc-issuer] issuer and audience are required');
   }
 
+  // The kid is unique PER INSTANCE, not just per rotation (2.37.0). Every
+  // instance generates a fresh key, and two scenarios can publish at the same
+  // OPENWOP_TEST_OIDC_ISSUER_URL (v2-oidc-id-token-audience and
+  // v2-lane-exp-only-bound both do). With a per-instance counter alone every
+  // instance minted `openwop-conformance-key-1`, so a host that caches JWKS by
+  // kid — RFC 7517 §4.5 says a kid identifies ONE key — verified the second
+  // scenario's tokens against the first scenario's key and rejected its VALID
+  // control as `invalid_signature`. Measured on openwop-app (suite 2.36.1):
+  // 4/4 red in a full run, 4/4 green filtered. A new kid over a new key lets a
+  // conformant host see an unknown kid and re-fetch, as it must.
+  const instance = randomBytes(6).toString('hex');
+  const kidFor = (n: number): string => `openwop-conformance-key-${instance}-${n}`;
   let rotationCounter = 1;
   let material = generateKeyMaterial(
     algorithm,
-    opts.keyId ?? `openwop-conformance-key-${rotationCounter}`,
+    opts.keyId ?? kidFor(rotationCounter),
   );
 
   return {
@@ -232,10 +245,7 @@ export function createSyntheticOIDCIssuer(
 
     rotateKey(): void {
       rotationCounter += 1;
-      material = generateKeyMaterial(
-        algorithm,
-        `openwop-conformance-key-${rotationCounter}`,
-      );
+      material = generateKeyMaterial(algorithm, kidFor(rotationCounter));
     },
   };
 }

package/src/scenarios/a2a-1-0-agent-card.test.ts

@@ -15,7 +15,7 @@
  *   - a legacy-only peer serves the 0.3 card (so the shape follows the revision,
  *     not the calendar);
  *   - `A2A-Version` absent ⇒ 0.3 semantics; unsupported ⇒ `-32009`
- *     `VERSION_NOT_SUPPORTED` with `supportedVersions[]`; a 1.0-only peer
+ *     `VERSION_NOT_SUPPORTED` with the supported versions (in `error.data`, an array of `Any` per A2A 1.0.1 §9.5: `google.rpc.ErrorInfo` `metadata.supportedVersions`, comma-joined); a 1.0-only peer
  *     rejects header-less requests;
  *   - `SendMessage` returns `{ task }` (the `SendMessageResponse` oneof) with
  *     `TASK_STATE_*`, `ROLE_*`, `Part` as a `oneof` (no `kind`), `status.timestamp`;
@@ -42,10 +42,20 @@ async function rpc(endpoint: string, method: string, params: unknown, version?:
   const headers: Record<string, string> = { 'content-type': 'application/json' };
   if (version !== undefined) headers['A2A-Version'] = version;
   const res = await fetch(`${endpoint}/a2a/jsonrpc`, { method: 'POST', headers, body: JSON.stringify({ jsonrpc: '2.0', id, method, params }) });
-  const body = (await res.json()) as { result?: Record<string, unknown>; error?: { code: number; message: string; data?: Record<string, unknown> } };
+  const body = (await res.json()) as { result?: Record<string, unknown>; error?: { code: number; message: string; data?: unknown } };
   return { status: res.status, ...body };
 }
 
+/**
+ * A2A 1.0.1 §9.5: `error.data` is an array of ProtoJSON `Any`; the error type is the
+ * `google.rpc.ErrorInfo` element's `reason` (§10.6/§11.6). Returns that element, or
+ * undefined when `data` is not such an array (so a bare-object `data` fails the leg).
+ */
+const errorInfo = (e: { data?: unknown } | undefined): { reason?: string; domain?: string; metadata?: Record<string, string> } | undefined => {
+  if (!Array.isArray(e?.data)) return undefined;
+  return (e!.data as Array<Record<string, unknown>>).find((d) => d['@type'] === 'type.googleapis.com/google.rpc.ErrorInfo') as { reason?: string; domain?: string; metadata?: Record<string, string> } | undefined;
+};
+
 describe('RFC 0152 — the suite peer speaks A2A 1.0 (dual-era A2AFakePeer)', () => {
   // Explicit 1.0-first so a header-less GET returns the 1.0 card (the default
   // is 0.3-first for today's 0.3 clients; both eras are spoken either way).
@@ -115,8 +125,10 @@ describe('RFC 0152 — the suite peer speaks A2A 1.0 (dual-era A2AFakePeer)', ()
     const r = await rpc(peer.endpoint(), 'SendMessage', { message: { messageId: 'm2', role: 'ROLE_USER', parts: [{ text: 'hi' }] } }, '99.0');
     expect(r.status, req('openwop.it.a2a-1-0-agent-card.an-unsupported-version-fails-32009-version-not-supported-with-supportedversions', 'RFC 0152 §A/§B/§C/§D', 'an unsupported version fails -32009 VERSION_NOT_SUPPORTED with supportedVersions[] (HTTP 400)')).toBe(400);
     expect(r.error?.code).toBe(-32009);
-    expect(r.error?.data?.['reason']).toBe('VERSION_NOT_SUPPORTED');
-    expect(r.error?.data?.['supportedVersions']).toEqual(['1.0', '0.3']); // constructor order
+    expect(Array.isArray(r.error?.data), req('openwop.it.a2a-1-0-agent-card.an-unsupported-version-fails-32009-version-not-supported-with-supportedversions', 'RFC 0152 §A/§B/§C/§D; A2A 1.0.1 §9.5', 'error.data is an array of Any carrying google.rpc.ErrorInfo')).toBe(true);
+    expect(errorInfo(r.error)?.reason).toBe('VERSION_NOT_SUPPORTED');
+    expect(errorInfo(r.error)?.domain).toBe('a2a-protocol.org');
+    expect(errorInfo(r.error)?.metadata?.['supportedVersions']).toBe('1.0,0.3'); // constructor order; ErrorInfo.metadata is map<string,string>
   });
 
   it('a 1.0-only peer rejects a header-less request (which is 0.3 by rule)', async () => {
@@ -125,7 +137,7 @@ describe('RFC 0152 — the suite peer speaks A2A 1.0 (dual-era A2AFakePeer)', ()
     try {
       const r = await rpc(only10.endpoint(), 'message/send', { message: { parts: [] } });
       expect(r.error?.code, req('openwop.it.a2a-1-0-agent-card.a-1-0-only-peer-rejects-a-header-less-request-which-is-0-3-by-rule', 'RFC 0152 §A/§B/§C/§D', 'a 1.0-only peer rejects a header-less request (which is 0.3 by rule)')).toBe(-32009);
-      expect(r.error?.data?.['requested']).toBe('0.3');
+      expect(errorInfo(r.error)?.metadata?.['requested']).toBe('0.3');
     } finally {
       await only10.stop();
     }
@@ -161,10 +173,10 @@ describe('RFC 0152 — the suite peer speaks A2A 1.0 (dual-era A2AFakePeer)', ()
     expect((cancelled.result as { status: { state: string } }).status.state).toBe('TASK_STATE_CANCELED');
     const again = await rpc(peer.endpoint(), 'CancelTask', { id }, '1.0');
     expect(again.error?.code).toBe(-32002);
-    expect(again.error?.data?.['reason']).toBe('TASK_NOT_CANCELABLE');
+    expect(errorInfo(again.error)?.reason).toBe('TASK_NOT_CANCELABLE');
     const missing = await rpc(peer.endpoint(), 'GetTask', { id: 'nope' }, '1.0');
     expect(missing.error?.code).toBe(-32001);
-    expect(missing.error?.data?.['reason']).toBe('TASK_NOT_FOUND');
+    expect(errorInfo(missing.error)?.reason).toBe('TASK_NOT_FOUND');
   });
 
   it('a 0.3 method name under a 1.0 header is method-not-found — loudly', async () => {

package/src/scenarios/v2-a2a-client-error-details.test.ts

@@ -0,0 +1,70 @@
+/**
+ * RFC 0211 §F — the host as an A2A 1.0 client reads a peer's error in either shape.
+ * Target major 2; gated on the v2 `a2a` record and the seams profile.
+ *
+ * A2A v1.0.1 §9.5 puts a JSON-RPC error's details in `error.data` as an ARRAY of
+ * `Any` objects; the suite's fake peer and the reference host shipped a bare
+ * `{ reason, domain }` object through 2.36.x. A host's A2A client MUST accept the
+ * array and SHOULD accept the object for the rest of 2.x
+ * (`spec/v2/core/interop.md` §"The operation mappings", A2A error details).
+ *
+ * The suite drives the host's client at its own 1.0-only fake peer through the
+ * §22 invoke seam with `requestVersion: '99.0'`, so the peer answers
+ * `VersionNotSupportedError` (-32009) — once with `data` as `Any[]`, once as the
+ * legacy object — and the host MUST project both to `interop_version_unsupported`.
+ *
+ * Weak by construction, and said so: a host that reads only one shape still
+ * identifies the error by its JSON-RPC code, so this leg witnesses that the client
+ * tolerates both shapes (does not throw, does not mis-project to `internal_error`),
+ * not that it reads `reason` out of the array. `interop_version_unsupported` has
+ * `details: null` in `spec/v2/errors.json`, so no projected `supportedVersions` is
+ * asserted.
+ *
+ * Callback-shaped (the host calls the suite's peer): unwitnessable when the host is
+ * in a separate network namespace — `../lib/host-callback.ts`.
+ *
+ * @see RFCS/0211-a2a-error-details-are-errorinfo.md §F
+ * @see spec/v2/interop-map.json a2a.errors VersionNotSupportedError (clientProjection)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { seamsProfileAdvertised, SEAMS_PREFIX } from '../lib/seams.js';
+import { A2AFakePeer } from '../lib/a2a-fake-peer.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip, seamAbsent } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+export const REQUIRES_HOST_CALLBACK = "the host's A2A client calls a suite-owned 1.0 peer that refuses the requested version with -32009";
+
+const ID = 'openwop.requirement.0211.a2a-client-reads-either-shape';
+const DOC = 'spec/v2/core/interop.md §"The operation mappings", A2A error details (RFC 0211 §F)';
+
+describe('RFC 0211 §F — v2-a2a-client-error-details (host as A2A 1.0 client; gated on a2a + seams)', () => {
+  it('a peer\'s version error projects to interop_version_unsupported whether error.data is an array or a legacy object', async () => {
+    const doc = await v2Discovery().catch(() => null);
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable');
+    const facet = await familyAdvertised('a2a');
+    if (!facet) return softSkip('inapplicable', 'a2a is not advertised at major 2 — the host has no A2A client to hold');
+    if (!seamsProfileAdvertised(doc)) return softSkip('inapplicable', 'the client exchange is driven through the seams profile — conformance.seamsProfile is not openwop-conformance-seams-v2');
+    const peer = new A2AFakePeer({ protocolVersions: ['1.0'] });
+    await peer.start();
+    const seen: string[] = [];
+    try {
+      for (const legacy of [false, true]) {
+        peer.reset();
+        peer.setLegacyErrorData(legacy);
+        const res = await driver.post(`${SEAMS_PREFIX}/sample/a2a/invoke`, { peerUrl: peer.hostFacingEndpoint(), authenticated: true, requestVersion: '99.0' });
+        if (res.status === 404 || res.status === 403 || res.status === 405) return seamAbsent(`host advertises a2a but ${SEAMS_PREFIX}/sample/a2a/invoke answered ${res.status} (host-sample-test-seams.md §22)`);
+        const reached = peer.invocations().some((i) => i.method !== 'GET');
+        if (!reached) return softSkip('blocked', `the host never called the suite peer (${legacy ? 'legacy' : 'Any[]'} pass) — the host cannot reach it, so no error was projected`);
+        const code = readErrorCode(res.json);
+        seen.push(`${legacy ? 'legacy object' : 'Any[]'}: HTTP ${res.status} ${String(code)}`);
+        expect(code, req(ID, DOC, `a peer's -32009 MUST project to interop_version_unsupported whichever shape error.data takes (${seen.join('; ')})`)).toBe('interop_version_unsupported');
+      }
+    } finally {
+      await peer.stop();
+    }
+  });
+});

package/src/scenarios/v2-a2a-operation-map.test.ts

@@ -25,6 +25,7 @@
  * @see spec/v2/interop-map.json a2a.operations / a2a.taskState / a2a.errors
  * @see RFCS/0208-v2-a2a-mcp-operation-mappings.md §C, §D, §E
  * @see RFCS/0199-outbound-oauth-client-and-credential-interrupt.md §D.1 (the credential leg; interop-map.json a2a.taskState override row)
+ * @see RFCS/0211-a2a-error-details-are-errorinfo.md §A–§E (the error-details legs; the isolation comparator)
  */
 import { describe, it, expect } from 'vitest';
 import { readFileSync } from 'node:fs';
@@ -37,6 +38,7 @@ import { softSkip } from '../lib/soft-skip.js';
 import { SCHEMAS_DIR } from '../lib/paths.js';
 import { req } from '../lib/requirement-ids.js';
 import { SEAMS_PREFIX } from '../lib/seams.js';
+import { errorInfos, normaliseErrorData, isOpenwopEnvelope, A2A_ERROR_DOMAIN } from '../lib/a2a-error-info.js';
 
 export const HOST_CALLBACK_NOT_REQUIRED = 'the suite is the A2A client: every leg POSTs JSON-RPC to the interface the host\'s own card lists; nothing harness-hosted is handed to the host';
 
@@ -44,6 +46,8 @@ const DOC = 'spec/v2/core/interop.md §"The operation mappings" (RFC 0208)';
 const PROFILE = 'a2a-1.0';
 const SKILL = 'conformance-approval';
 const R = (slug: string): string => `openwop.requirement.0208.${slug}`;
+const R11 = (slug: string): string => `openwop.requirement.0211.${slug}`;
+const DOC11 = 'spec/v2/core/interop.md §"The operation mappings", A2A error details (RFC 0211)';
 const ACCEPT = { action: 'accept' };
 
 interface MapStateRow { runStatus: string; wire: string; interruptKind?: string }
@@ -184,8 +188,12 @@ describe('RFC 0208 — v2-a2a-operation-map (host as A2A 1.0 server, gated on a2
     const b = await rpc(t.url, 'GetTask', { id: foreign });
     expect(a.error?.code, req(R('a2a-unreadable-not-found'), 'a2a.errors TaskNotFoundError', `an unknown task MUST be TaskNotFoundError -32001 (got ${JSON.stringify(a.error ?? a.result)})`)).toBe(-32001);
     expect(b.error?.code, req(R('a2a-unreadable-not-found'), 'interop.md §"The operation mappings" Isolation', `a task the caller cannot read — here a foreign tenant segment REST refuses 403 — MUST be answered exactly as a nonexistent one, -32001 (got ${JSON.stringify(b.error ?? b.result)}, HTTP ${b.status})`)).toBe(-32001);
-    const shape = (e: RpcError | undefined): string => JSON.stringify({ http: e === undefined ? null : 'rpc', dataKeys: e?.data && typeof e.data === 'object' ? Object.keys(e.data as object).sort() : typeof e?.data });
-    expect(shape(b.error) + String(b.status), req(R('a2a-unreadable-not-found'), 'interop.md §"The operation mappings" Isolation (A2A 1.0.1 §3.3.2)', 'the foreign-tenant answer MUST be indistinguishable from the unknown-id answer: same HTTP status and the same error.data shape')).toBe(shape(a.error) + String(a.status));
+    // RFC 0211 §D: compare the details per element. `Object.keys(data)` of a one-element
+    // array is ["0"] whatever the element discloses, so a key comparison is vacuous.
+    const na = normaliseErrorData(a.error?.data, fabricated);
+    const nb = normaliseErrorData(b.error?.data, foreign);
+    expect(errorInfos(a.error?.data).length, req(R11('a2a-unreadable-not-found-details'), DOC11, `positive control: the unknown-id answer MUST carry error.data as an array with a google.rpc.ErrorInfo — without one the comparison below proves nothing (got ${JSON.stringify(a.error?.data)})`)).toBeGreaterThanOrEqual(1);
+    expect(JSON.stringify(nb) + String(b.status), req(R11('a2a-unreadable-not-found-details'), 'interop.md §"The operation mappings" Isolation; RFC 0211 §D (A2A 1.0.1 §3.3.2)', 'the foreign-tenant answer MUST be indistinguishable from the unknown-id answer: same HTTP status and the same normalised error details (@type, reason, domain, sorted metadata keys, minus an echo of the requested id)')).toBe(JSON.stringify(na) + String(a.status));
     await rpc(t.url, 'CancelTask', { id });
   });
 
@@ -274,6 +282,80 @@ describe('RFC 0208 — v2-a2a-operation-map (host as A2A 1.0 server, gated on a2
     await rpc(t.url, 'CancelTask', { id: theirId }, { bearer: other });
   });
 
+  it('an A2A error\'s data is an array carrying one ErrorInfo with the map row\'s reason and the A2A domain', async () => {
+    const t = await target(true);
+    if (!t.ok) return skip(t, R11('a2a-error-data-shape'));
+    const first = await startApprovalTask(t.url);
+    const id = first.task?.id;
+    expect(typeof id === 'string' && id.includes('/'), req(R11('a2a-error-data-shape'), DOC, `SendMessage MUST start a task with a tenant-bound id: ${JSON.stringify(first.rpc.error)}`)).toBe(true);
+    const tenant = id!.slice(0, id!.indexOf('/'));
+    const unknown = await rpc(t.url, 'GetTask', { id: `${tenant}/${randomBytes(16).toString('hex').slice(0, 22)}` });
+    await rpc(t.url, 'SendMessage', { message: acceptMessage(id!) });
+    await settle(id!, (s) => s !== undefined && TERMINAL.has(s));
+    const terminal = await rpc(t.url, 'CancelTask', { id });
+    for (const [label, r, reason] of [['GetTask on an unknown id', unknown, 'TASK_NOT_FOUND'], ['CancelTask on a terminal task', terminal, 'TASK_NOT_CANCELABLE']] as const) {
+      expect(Array.isArray(r.error?.data), req(R11('a2a-error-data-shape'), `${DOC11} (A2A §9.5)`, `${label}: error.data MUST be an array of objects each carrying @type (got ${JSON.stringify(r.error ?? r.result)})`)).toBe(true);
+      const all = (Array.isArray(r.error?.data) ? r.error!.data : []) as unknown[];
+      expect(all.every((x) => typeof x === 'object' && x !== null && typeof (x as Record<string, unknown>)['@type'] === 'string'), req(R11('a2a-error-data-shape'), `${DOC11} (A2A §9.5)`, `${label}: every element of error.data MUST carry @type (got ${JSON.stringify(all)})`)).toBe(true);
+      const infos = errorInfos(r.error?.data);
+      expect(infos.length, req(R11('a2a-error-data-shape'), DOC11, `${label}: error.data MUST include exactly one google.rpc.ErrorInfo (got ${JSON.stringify(all)})`)).toBe(1);
+      expect([infos[0]?.reason, infos[0]?.domain], req(R11('a2a-error-data-shape'), `${DOC11}; interop-map.json a2a.errors reason`, `${label}: the ErrorInfo reason MUST be the map row's reason and the domain ${A2A_ERROR_DOMAIN}`)).toEqual([reason, A2A_ERROR_DOMAIN]);
+    }
+  });
+
+  it('no response on the card\'s JSON-RPC interface URL is the OpenWOP error envelope', async () => {
+    const t = await target(false);
+    if (!t.ok) return skip(t, R11('a2a-no-openwop-envelope'));
+    const probes: Array<[string, RequestInit]> = [
+      ['a body that is not JSON', { method: 'POST', headers: { 'content-type': 'application/json', 'A2A-Version': '1.0', ...(process.env.OPENWOP_API_KEY ? { authorization: `Bearer ${process.env.OPENWOP_API_KEY}` } : {}) }, body: '{"jsonrpc":"2.0","id":1,' }],
+      ['a request with no credential', { method: 'POST', headers: { 'content-type': 'application/json', 'A2A-Version': '1.0' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'GetTask', params: { id: 'x/y' } }) }],
+      ['an unknown method', { method: 'POST', headers: { 'content-type': 'application/json', 'A2A-Version': '1.0', ...(process.env.OPENWOP_API_KEY ? { authorization: `Bearer ${process.env.OPENWOP_API_KEY}` } : {}) }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'openwop.conformance.NoSuchMethod', params: {} }) }],
+    ];
+    const seen: string[] = [];
+    for (const [label, init] of probes) {
+      const res = await fetch(t.url, init);
+      const text = await res.text();
+      let body: unknown = null;
+      try { body = text.length > 0 ? JSON.parse(text) : null; } catch { body = null; }
+      seen.push(`${label}: HTTP ${res.status}`);
+      expect(isOpenwopEnvelope(body), req(R11('a2a-no-openwop-envelope'), `${DOC11}; RFC 0211 §C`, `${label}: a response on an interface URL the card lists — including a refusal before dispatch — MUST be in the binding's shape, never the OpenWOP { error, message } envelope (HTTP ${res.status}, body ${text.slice(0, 200)})`)).toBe(false);
+    }
+    expect(seen.length, req(R11('a2a-no-openwop-envelope'), DOC11, 'every probe reached the interface')).toBe(probes.length);
+  });
+
+  it('VersionNotSupportedError carries ErrorInfo VERSION_NOT_SUPPORTED, and supportedVersions is a comma-joined subset of the card', async () => {
+    const t = await target(false);
+    if (!t.ok) return skip(t, R11('a2a-version-not-supported-shape'));
+    const a2a = (await familyAdvertised('a2a'))!;
+    const card = (await (await fetch(String(a2a['agentCardUrl']), { headers: { accept: 'application/json', 'A2A-Version': '1.0' } })).json().catch(() => ({}))) as { supportedInterfaces?: Array<{ url?: string; protocolVersion?: string }> };
+    const offered = new Set((card.supportedInterfaces ?? []).filter((i) => i.url === t.url).map((i) => String(i.protocolVersion)));
+    const r = await rpc(t.url, 'GetTask', { id: 'zz-conformance/unknown' }, { version: '99.0' });
+    expect(r.error?.code, req(R11('a2a-version-not-supported-shape'), 'a2a.errors VersionNotSupportedError', `an A2A-Version the interface does not serve MUST be -32009, not -32600 (got ${JSON.stringify(r.error ?? r.result)})`)).toBe(-32009);
+    const info = errorInfos(r.error?.data)[0];
+    expect(info?.reason, req(R11('a2a-version-not-supported-shape'), DOC11, `the -32009 error MUST carry ErrorInfo reason VERSION_NOT_SUPPORTED (got ${JSON.stringify(r.error?.data)})`)).toBe('VERSION_NOT_SUPPORTED');
+    const sv = (info?.metadata as Record<string, unknown> | undefined)?.['supportedVersions'];
+    // metadata.supportedVersions is a SHOULD (RFC 0211 §E): absent is not a failure — a client
+    // falls back to the card. When present it MUST be a comma-joined subset of the card's versions.
+    if (sv !== undefined) {
+      expect(typeof sv === 'string' && sv.split(',').every((v) => offered.has(v.trim())), req(R11('a2a-version-not-supported-shape'), `${DOC11}; RFC 0211 §E`, `when present, metadata.supportedVersions MUST be a comma-joined string of versions the card lists for this interface (got ${JSON.stringify(sv)}; card ${JSON.stringify([...offered])})`)).toBe(true);
+    }
+  });
+
+  it('an HTTP+JSON interface answers an A2A error with google.rpc.Status carrying the ErrorInfo', async () => {
+    if (!(await v2Discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const a2a = await familyAdvertised('a2a');
+    if (!a2a || !(Array.isArray(a2a['profiles']) && (a2a['profiles'] as unknown[]).includes(PROFILE))) return softSkip('inapplicable', 'a2a-1.0 is not claimed — no A2A interface to hold');
+    const card = (await (await fetch(String(a2a['agentCardUrl']), { headers: { accept: 'application/json', 'A2A-Version': '1.0' } })).json().catch(() => ({}))) as { supportedInterfaces?: Array<{ url?: string; protocolBinding?: string; protocolVersion?: string }> };
+    const rest = (card.supportedInterfaces ?? []).find((i) => i.protocolBinding === 'HTTP+JSON' && i.protocolVersion === '1.0');
+    if (typeof rest?.url !== 'string') return softSkip('inapplicable', 'the card lists no HTTP+JSON interface at 1.0 — RFC 0211 §B binds only a host that lists one');
+    const headers: Record<string, string> = { accept: 'application/a2a+json, application/json', 'A2A-Version': '1.0' };
+    if (process.env.OPENWOP_API_KEY) headers['authorization'] = `Bearer ${process.env.OPENWOP_API_KEY}`;
+    const res = await fetch(`${rest.url.replace(/\/$/, '')}/tasks/${encodeURIComponent(`zz-conformance/${randomBytes(8).toString('hex')}`)}`, { headers });
+    const body = (await res.json().catch(() => ({}))) as { error?: { code?: unknown; status?: unknown; message?: unknown; details?: unknown } };
+    expect([typeof body.error?.code, typeof body.error?.status, typeof body.error?.message], req(R11('a2a-httpjson-status'), `${DOC11} (A2A §11.6)`, `an HTTP+JSON A2A error MUST be google.rpc.Status { error: { code, status, message, details } } (HTTP ${res.status}, got ${JSON.stringify(body)})`)).toEqual(['number', 'string', 'string']);
+    expect(errorInfos(body.error?.details)[0]?.reason, req(R11('a2a-httpjson-status'), `${DOC11} (A2A §11.6)`, 'the Status details MUST carry the ErrorInfo TASK_NOT_FOUND')).toBe('TASK_NOT_FOUND');
+  });
+
   it('a run suspended on a credential interrupt projects to TASK_STATE_AUTH_REQUIRED, naming the provider and carrying connectUrl', async () => {
     const id = 'openwop.requirement.0199.a2a-auth-required';
     const t = await target(false);

package/src/scenarios/v2-durability-recovery.test.ts

@@ -64,7 +64,6 @@
  * @see RFCS/0158-durable-execution-and-disaster-recovery-qualification.md §B.4 §D.9 §E
  */
 
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { describe, expect, it } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { v2Discovery } from '../lib/v2.js';
@@ -72,7 +71,7 @@ import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { softSkip } from '../lib/soft-skip.js';
 import { pollUntilTerminal, scaledTimeoutMs } from '../lib/polling.js';
 import { req } from '../lib/requirement-ids.js';
-import { receiverBinding, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
+import { startEffectReceiver, waitForFirstArrival } from '../lib/effect-receiver.js';
 import { watchForResumption, type Observation, type Watch } from '../lib/durability-watch.js';
 import { noteEvidence, parseRecoveryBounds, EVIDENCE_NAME_PATTERN } from '../lib/durability-evidence.js';
 
@@ -267,26 +266,15 @@ function watch(runId: string, budgetMs: number, resumed: (o: Observation) => boo
 }
 
 /**
- * The suite's own destination for the one staged effect. Every request that
- * reaches it is an INVOCATION — the thing §C says to count. Honours
- * OPENWOP_WEBHOOK_RECEIVER_PORT so a tunnelled cut forwards here (the
- * certification setting is already `--max-workers 1`, so the pinned port is
- * not contended by the webhook files).
+ * How long to wait for the ONE legitimate arrival before concluding none came.
+ *
+ * Separate from `QUIET_WINDOW_MS`, and for the opposite reason: this is a wait
+ * FOR something that must happen, so a generous bound weakens nothing, while
+ * the quiet window that follows is a wait for something that must NOT happen.
+ * Collapsing the two into one blind sleep made the row measure the host's
+ * effect latency under load — see `lib/effect-receiver.ts`.
  */
-async function startEffectReceiver(): Promise<{ server: Server; url: string; arrivals: Array<{ method: string; at: number }> }> {
-  const arrivals: Array<{ method: string; at: number }> = [];
-  const server = createServer((request: IncomingMessage, res: ServerResponse) => {
-    request.on('data', () => { /* drain */ });
-    request.on('end', () => { arrivals.push({ method: request.method ?? '', at: Date.now() }); res.writeHead(204); res.end(); });
-  });
-  const pinned = Number(process.env['OPENWOP_WEBHOOK_RECEIVER_PORT'] ?? '');
-  const bindPort = Number.isInteger(pinned) && pinned > 0 && pinned < 65536 ? pinned : 0;
-  const binding = receiverBinding();
-  await new Promise<void>((resolve) => server.listen(bindPort, binding.bind, () => resolve()));
-  const addr = server.address();
-  const port = typeof addr === 'object' && addr ? addr.port : 0;
-  return { server, url: `http://${binding.advertise}:${port}/effect`, arrivals };
-}
+const FIRST_ARRIVAL_BUDGET_MS = 20_000;
 
 describe('v2-durability-recovery (RFC 0158 §B.4, §D.9, §E — the durable-single-instance rows)', () => {
   it('accepted work survives a kill before dispatch and dispatches on resume', async () => {
@@ -421,12 +409,29 @@ describe('v2-durability-recovery (RFC 0158 §B.4, §D.9, §E — the durable-sin
     // (`conformance-noop` records none). The seam is host test infrastructure
     // (§E) and chooses the work; it MUST stage work that performs EXACTLY ONE
     // outbound effect, addressed to `effectUrl`, and deliver it twice.
+    //
+    // 2.37.0 — THE DESTINATION CARRIES A PER-EXERCISE NONCE, and that is what
+    // makes this row deterministic. An effect's Layer-2 identity is its
+    // BUSINESS identity (idempotency.md §"Layer 2 Keying"): tenant, workflow,
+    // node, request digest — and the destination URL is part of that digest,
+    // while the runId deliberately is not. Until 2.37.0 this leg and
+    // `0194.terminal-once.duplicate-delivery` both handed the seam
+    // `resolveRegistrationUrl(...)`, which on a tunnelled cut is
+    // OPENWOP_WEBHOOK_RECEIVER_URL verbatim — the same string for both. Same
+    // fixture, same node, same URL ⇒ SAME effect identity, so a CONFORMANT
+    // host resolved the second exercise to the first's recorded outcome and
+    // called out zero times. Whichever leg vitest ran second read zero
+    // arrivals: `blocked` on loopback, a hard `executed-fail` on a tunnelled
+    // cut. Measured on the v2 reference host — exercise 2's ledger row read
+    // `invocationId: "deduplicated-of:<run 1>"`. Nothing but the file order
+    // differed between a pass and a fail, and the row was measuring
+    // cross-exercise deduplication rather than §C's within-exercise
+    // exactly-once. The nonce gives every exercise its own identity.
     const rx = await startEffectReceiver();
     try {
-      const target = resolveRegistrationUrl(rx.url);
-      const fired = await driver.post(KILL_SEAM, { mode: 'duplicate-delivery', effectUrl: target.url });
+      const fired = await driver.post(KILL_SEAM, { mode: 'duplicate-delivery', effectUrl: rx.url });
       if (fired.status >= 400) {
-        return softSkip('blocked', `the durability seam answered ${fired.status} for mode=duplicate-delivery with effectUrl ${target.tunnelled ? '(tunnelled)' : rx.url} — the host exposes the route but could not stage a double delivery; if its egress guard refused the receiver, the operator precondition is the webhook rows' own: a publicly-resolvable https front (OPENWOP_WEBHOOK_RECEIVER_URL) or a host run with its private-egress relaxation recorded`);
+        return softSkip('blocked', `the durability seam answered ${fired.status} for mode=duplicate-delivery with effectUrl ${rx.tunnelled ? '(tunnelled front)' : rx.url} — the host exposes the route but could not stage a double delivery; if its egress guard refused the receiver, the operator precondition is the webhook rows' own: a publicly-resolvable https front (OPENWOP_WEBHOOK_RECEIVER_URL) or a host run with its private-egress relaxation recorded`);
       }
       const runId = (fired.json as { runId?: unknown } | null)?.runId;
       if (typeof runId !== 'string') {
@@ -434,28 +439,71 @@ describe('v2-durability-recovery (RFC 0158 §B.4, §D.9, §E — the durable-sin
       }
 
       await pollUntilTerminal(runId, { timeoutMs: scaledTimeoutMs(60_000) });
-      // A LONGER wait is a STRONGER claim: this is a wait for a second arrival
-      // that must not happen, and the second delivery may trail the first.
+      // Wait FOR the one legitimate arrival, then wait OUT the quiet window for
+      // a second that must not come. A single blind sleep conflated the two and
+      // made a slow-but-correct host read as zero.
+      await waitForFirstArrival(rx, scaledTimeoutMs(FIRST_ARRIVAL_BUDGET_MS));
       await new Promise((r) => setTimeout(r, scaledTimeoutMs(QUIET_WINDOW_MS)));
 
-      const arrivals = rx.arrivals.length;
-      if (arrivals === 0 && !target.tunnelled) {
-        return softSkip('blocked', `the staged work's effect never reached the suite's receiver at ${rx.url} — for mode=duplicate-delivery the seam MUST aim exactly one outbound effect at the given effectUrl; with nothing landed there is no invocation to count, and the ledger alone cannot witness a double-fire`);
+      // Read the host's OWN account first, so a zero can SAY WHY. The two
+      // zeroes are different facts and must not share one disposition: nothing
+      // was ever sent, or the host resolved this work to an outcome it had
+      // already recorded (a `deduplicated-of:` / `replay-of:` invocation) —
+      // correct Layer-2 behaviour that leaves §C unmeasured, not refuted.
+      const eff = await driver.get(`/runs/${encodeURIComponent(runId)}/effects`);
+      const effects = eff.status === 200 ? ((eff.json as { effects?: Array<Record<string, unknown>> } | null)?.effects ?? []) : [];
+      const resolvedElsewhere = effects.filter((e) => /^(deduplicated-of|replay-of):/.test(String(e['invocationId'] ?? '')));
+      // An effect the host ATTEMPTED and whose transport failed. `released` is
+      // the state persistence.md gives a claim that was taken and given back;
+      // a host that names it is telling us the invocation was tried and never
+      // reached the destination. That is a THIRD kind of zero and it must not
+      // be reported as either of the others.
+      const attemptedAndFailed = effects.filter((e) => String(e['state'] ?? '') === 'released');
+      const arrivals = rx.arrivals();
+      if (arrivals === 0) {
+        // A BARE FAIL ON ZERO IS UNINFORMATIVE, so the zero is classified from
+        // the host's own ledger before any disposition is chosen. Three states
+        // wear the same symptom and only one of them is about §C:
+        //   (a) resolved to an outcome the host had ALREADY recorded — correct
+        //       Layer-2 keying, and this exercise simply performed no
+        //       invocation to count;
+        //   (b) attempted and the transport failed — a missed fire, which is
+        //       the opposite of a double fire and cannot refute exactly-once;
+        //   (c) nothing in the ledger at all — the seam never staged the one
+        //       effect the mode requires, so the exercise did not happen.
+        // None of the three is evidence AGAINST §C, so none of them is an
+        // `executed-fail`; each is `blocked` with its own cause named. The only
+        // thing this row ever fails on is a count that is not 1 with at least
+        // one real invocation observed.
+        const why = resolvedElsewhere.length > 0
+          ? `the host resolved the staged effect to an outcome it had ALREADY RECORDED (${resolvedElsewhere.map((e) => String(e['invocationId'])).join(', ')}) — correct Layer-2 keying (idempotency.md §"Layer 2 Keying"), but it means no invocation happened in THIS exercise, so §C's exactly-once is unmeasured here rather than violated. The destination this suite minted carries a per-exercise nonce precisely so this cannot happen; a host that keys on something coarser than the request MUST stage a fresh business identity per exercise`
+          : attemptedAndFailed.length > 0
+            ? `the host ATTEMPTED the staged effect and its transport failed — ${attemptedAndFailed.length} ledger row(s) in state \`released\`${attemptedAndFailed.map((e) => ` (${String(e['effectId'] ?? '?')} attempt ${String(e['attempt'] ?? '?')})`).join('')}. A MISSED fire is not an exactly-once violation, so this is not a refutation of §C and is not recorded as one; the operator precondition is a destination the host can actually reach inside its own effect timeout, and a host whose staged work takes no transport retry will show this whenever the round trip exceeds that timeout`
+            : `the staged work's effect never reached the suite's receiver at ${rx.localUrl}${rx.tunnelled ? ` (fronted as ${rx.url})` : ''} within ${FIRST_ARRIVAL_BUDGET_MS}ms of terminal, and the host's own effect ledger records no attempt — for mode=duplicate-delivery the seam MUST aim exactly one outbound effect at the given effectUrl; with nothing landed there is no invocation to count, and the ledger alone cannot witness a double-fire${rx.foreign() > 0 ? `. ${rx.foreign()} request(s) DID reach this listener without this exercise's nonce, so the front is wired but the host addressed something else` : ''}`;
+        // Zero is never a pass, and — since 2.37.0 — never a bare fail either.
+        // Until now a tunnelled cut turned every zero into `executed-fail`
+        // ("a mis-wired tunnel must not read as a pass"), which is right about
+        // the pass and wrong about the fail: it convicted a host of violating
+        // exactly-once on the evidence that it fired too FEW times. The
+        // mis-wired tunnel it was defending against is now the `foreign()`
+        // count — a front that reaches this listener but carries someone
+        // else's nonce — which the reason above names. `blocked` is not a
+        // softening: a blocked row DENIES certification (RFC 0168 §E.1)
+        // exactly as a failed one does, so the rung is still refused; what
+        // changes is that the bundle says which of the three zeroes happened
+        // instead of asserting a violation that was never observed.
+        return softSkip('blocked', why);
       }
-      // With a tunnel declared, zero arrivals is a hard failure, never a skip
-      // (webhook-receiver.ts): a mis-wired tunnel must not read as a pass.
       expect(
         arrivals,
-        req('openwop.requirement.0158.duplicate-delivery', 'RFC 0158 §C', `the same accepted work delivered twice MUST fire each effect exactly once, counted at the effect's destination — the suite's receiver observed ${arrivals} arrival(s) of the one staged effect for run ${runId}`),
+        req('openwop.requirement.0158.duplicate-delivery', 'RFC 0158 §C', `the same accepted work delivered twice MUST fire each effect exactly once, counted at the effect's destination — the suite's receiver observed ${arrivals} arrival(s) bearing this exercise's nonce ${rx.nonce} for run ${runId}${rx.foreign() > 0 ? ` (and ${rx.foreign()} unrelated request(s), not counted)` : ''}`),
       ).toBe(1);
 
       // Secondary, and labelled for what it is: the host's own account agrees
       // with what landed. On an identity-keyed ledger this can never exceed one
       // row per identity, so it witnesses that the PROJECTION IS CONSISTENT, not
       // that no double-fire happened — the arrival count above owns that.
-      const eff = await driver.get(`/runs/${encodeURIComponent(runId)}/effects`);
       if (eff.status === 200) {
-        const effects = (eff.json as { effects?: Array<Record<string, unknown>> } | null)?.effects ?? [];
         const byIdentity = new Map<string, number>();
         for (const e of effects) {
           const id = String(e['effectId'] ?? e['keying'] ?? '');
@@ -469,7 +517,7 @@ describe('v2-durability-recovery (RFC 0158 §B.4, §D.9, §E — the durable-sin
         ).toBe(true);
       }
     } finally {
-      await new Promise<void>((r) => rx.server.close(() => r()));
+      await rx.close();
     }
   }, 180_000);
 

package/src/scenarios/v2-idempotency-in-flight.test.ts

@@ -0,0 +1,77 @@
+/**
+ * `spec/v2/core/idempotency.md` Concurrency row — the loser of a same-key race
+ * (RFC 0213 §B; suite 2.37.0, target major 2; unaided; one run created).
+ *
+ * Of concurrent same-key requests a host MUST process exactly one. The others
+ * MAY wait and receive the winner's response only if it is a final outcome,
+ * marked `OpenWOP-Idempotent-Replay: true`; otherwise the host MUST answer
+ * `409 idempotency_in_flight` with no retry timing in `details`, and SHOULD set
+ * `Retry-After`. The v2 counterpart of the major-1 `highConcurrency.test.ts`.
+ *
+ * N = 5 parallel `POST /runs` with one key. The record is in flight only
+ * while the winning create request is being handled — not while its run
+ * executes — so a host that answers create in milliseconds rarely refuses a
+ * loser; the fixture choice does not widen that window:
+ *   - exactly one distinct runId across the successes (two runs = the claim
+ *     was not honored);
+ *   - every success but one carries `OpenWOP-Idempotent-Replay: true`;
+ *   - every refusal is `409 idempotency_in_flight`, carries no
+ *     `details.retryAfter*`, and a `Retry-After`, when present, parses.
+ *
+ * Non-vacuity: overlap is not guaranteed. When no request was refused in flight
+ * the file records `partial-witness` — the 409 branch never ran, so a pass is
+ * not claimed for it.
+ *
+ * @see spec/v2/core/idempotency.md
+ * @see RFCS/0213-three-unstated-v2-outcomes.md §B
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.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/idempotency.md Concurrency';
+const ID_ONE = 'openwop.requirement.0213.in-flight-one-winner';
+const ID_LOSER = 'openwop.requirement.0213.in-flight-loser-outcome';
+const FIXTURE = 'conformance-delay';
+const N = 5;
+
+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; } }
+function parsesRetryAfter(v: string): boolean { return /^\d+$/.test(v.trim()) || !Number.isNaN(Date.parse(v)); }
+
+describe('v2 idempotency-in-flight (idempotency.md Concurrency, RFC 0213 §B)', () => {
+  it('concurrent same-key creates yield one run; each loser is a marked replay of a final outcome or 409 idempotency_in_flight with no retry timing in details', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const key = `openwopconf-inflight-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+    const body = { workflowId: FIXTURE, inputs: { delayMs: 1500 } };
+    const results = await Promise.all(Array.from({ length: N }, () => http(() => driver.post('/runs', body, { headers: { 'Idempotency-Key': key } }))));
+    if (results.some((r) => r === null)) return softSkip('blocked', 'POST /runs unreachable (fetch failed)');
+    const rs = results as OpenWOPResponse[];
+    const first = rs.find((r) => r.status >= 200 && r.status < 300);
+    if (first === undefined) {
+      const codes = rs.map((r) => `${r.status} ${readErrorCode(r.json) ?? ''}`.trim()).join(', ');
+      if (rs.every((r) => r.status === 404 || r.status === 422)) return softSkip('blocked', `the ${FIXTURE} fixture is not runnable (${codes})`);
+    }
+    const successes = rs.filter((r) => r.status >= 200 && r.status < 300);
+    const refusals = rs.filter((r) => !(r.status >= 200 && r.status < 300));
+    expect(successes.length, req(ID_ONE, DOC, `at least one of ${N} same-key creates MUST complete (statuses: ${rs.map((r) => r.status).join(',')})`)).toBeGreaterThan(0);
+    const runIds = new Set(successes.map((r) => (r.json as { runId?: unknown } | null)?.runId).filter((x): x is string => typeof x === 'string'));
+    expect(runIds.size, req(ID_ONE, DOC, `a host MUST NOT process two same-key requests: distinct runIds ${[...runIds].join(', ')}`)).toBe(1);
+    const unmarked = successes.filter((r) => r.headers.get('openwop-idempotent-replay') !== 'true');
+    expect(unmarked.length, req(ID_LOSER, DOC, `exactly one success is the winner; every other MUST carry OpenWOP-Idempotent-Replay: true (${unmarked.length} of ${successes.length} unmarked)`)).toBe(1);
+    for (const r of refusals) {
+      const code = readErrorCode(r.json);
+      expect({ status: r.status, code }, req(ID_LOSER, DOC, `a loser that is not a replay MUST be 409 idempotency_in_flight (got ${r.status} ${String(code)})`)).toEqual({ status: 409, code: 'idempotency_in_flight' });
+      const details = (r.json as { details?: Record<string, unknown> } | null)?.details ?? {};
+      const timing = Object.keys(details).filter((k) => /^retryAfter/i.test(k));
+      expect(timing, req(ID_LOSER, 'spec/v2/core/errors.md §Retry timing', `retry timing MUST NOT travel in details (found ${timing.join(', ')})`)).toEqual([]);
+      const ra = r.headers.get('retry-after');
+      if (ra !== null) expect(parsesRetryAfter(ra), req(ID_LOSER, DOC, `a Retry-After that is present MUST parse (got ${ra})`)).toBe(true);
+    }
+    if (refusals.length === 0) return softSkip('blocked', `no loser was refused in flight — all ${N} answers were successes, so the 409 branch did not run on this host`);
+  }, 60_000);
+});