@openwop/openwop-conformance 2.36.1 → 2.37.1

package/src/scenarios/v2-webhook-delivery-shape.test.ts

@@ -44,14 +44,13 @@
  * @see spec/v2/core/versioning.md §1.2
  */
 import { afterEach, describe, it, expect } from 'vitest';
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 import { driver } from '../lib/driver.js';
 import { v2Discovery, gateFamily } from '../lib/v2.js';
-import { receiverBinding, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
+import { noDeliveryCause, startScopedReceiver, type ScopedReceiver } from '../lib/scoped-receiver.js';
 import { readErrorCode } from '../lib/error-envelope.js';
 import { softSkip } from '../lib/soft-skip.js';
 import { req } from '../lib/requirement-ids.js';
@@ -67,32 +66,23 @@ const EVENT_TYPE = 'run.started';
 type Delivery = { body: string; headers: Record<string, string | string[] | undefined> };
 type Validator = (doc: unknown) => { ok: boolean; errors: string };
 
-async function startReceiver(): Promise<{ server: Server; url: string; deliveries: Delivery[] }> {
+async function startReceiver(): Promise<ScopedReceiver & { deliveries: Delivery[] }> {
   const deliveries: Delivery[] = [];
-  const server = createServer((request: IncomingMessage, res: ServerResponse) => {
-    const chunks: Buffer[] = [];
-    request.on('data', (c: Buffer) => chunks.push(c));
-    request.on('end', () => {
-      deliveries.push({ body: Buffer.concat(chunks).toString('utf8'), headers: request.headers });
-      res.writeHead(204); res.end();
-    });
-  });
-  // Honour OPENWOP_WEBHOOK_RECEIVER_PORT like `v2-webhook-durable-delivery`
-  // does. Without it, a tunnelled run registers the tunnel URL here and the
+  // `startScopedReceiver` (2.37.0) replaces this file's own `createServer` +
+  // pinned-port binding. The comment that stood here described the collision
+  // from the inside: "a tunnelled run registers the tunnel URL here and the
   // tunnel forwards to the PINNED port — held by the other receiver, which
   // answers 500 by design — so this file's `deliveries` stays empty, its legs
   // soft-skip, and (because `register()` already asserted) the rows resolve
-  // `executed-pass`. A wire-shape scenario that never opened a delivery body
-  // went green. Two major-2 files now want the same pinned port, so the
-  // webhook lane MUST run with `--max-workers 1`, which is already the
-  // certification setting.
-  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}/hook`, deliveries };
+  // `executed-pass`." Four files registered that one byte-identical URL. Each
+  // now registers its own nonce path, and `front-mux` routes a delivery to the
+  // exercise it was addressed to whichever listener holds the port.
+  const rx = await startScopedReceiver((hit, res) => {
+    deliveries.push({ body: hit.body, headers: hit.headers });
+    res.writeHead(204);
+    res.end();
+  });
+  return { ...rx, deliveries };
 }
 
 /**
@@ -103,8 +93,11 @@ async function startReceiver(): Promise<{ server: Server; url: string; deliverie
  * for leg 2, not a failure: there is no v1 wire to keep still.
  */
 async function register(url: string, major: 1 | 2): Promise<string | null> {
-  const registration = resolveRegistrationUrl(url);
-  const reg = await driver.post(major === 2 ? '/webhooks' : '/v1/webhooks', { url: registration.url, events: [EVENT_TYPE] }, { headers: { 'OpenWOP-Version': major === 2 ? '2.0' : '1.0' } });
+  // `url` is already the destination for THIS exercise — the public front (when
+  // one is wired) plus this receiver's nonce path. It is no longer run through
+  // `resolveRegistrationUrl`, which returned the front VERBATIM and so dropped
+  // the path that makes the subscription this exercise's.
+  const reg = await driver.post(major === 2 ? '/webhooks' : '/v1/webhooks', { url, events: [EVENT_TYPE] }, { headers: { 'OpenWOP-Version': major === 2 ? '2.0' : '1.0' } });
   if (major === 1 && reg.status === 404) {
     softSkip('inapplicable', 'host serves no 1.x webhook surface (POST /v1/webhooks not_found) — no v1 wire to keep still');
     return null;
@@ -214,18 +207,22 @@ const V2 = 'https://openwop.dev/spec/v2/';
 const V1 = 'https://openwop.dev/spec/v1/';
 
 describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versioning.md §1.2)', () => {
-  let active: Server | null = null;
-  afterEach(async () => { await unregisterAll(); const s = active; active = null; if (s) await new Promise<void>((r) => s.close(() => r())); });
+  // Closed through the receiver, not the raw server: `close()` also drops this
+  // exercise's nonce from the front-mux registry, so a retry that arrives after
+  // the leg has finished is answered 404 by whoever holds the port rather than
+  // being handed to the next exercise's recorder.
+  let active: ScopedReceiver | null = null;
+  afterEach(async () => { await unregisterAll(); const rx = active; active = null; if (rx) await rx.close(); });
 
   it('a major-2 subscriber receives the v2 rendering: the delivery validates, and run.started.owner carries subject, never principal', async () => {
     if (!(await v2Discovery())) return softSkip('blocked', 'v2 discovery unreachable');
     if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.webhooks)');
-    const receiver = await startReceiver(); active = receiver.server;
+    const receiver = await startReceiver(); active = receiver;
     const webhookId = await register(receiver.url, 2);
     if (webhookId === null) return softSkip('blocked', 'registration refused (reason recorded above)');
     const runId = await driveRun();
     const d = await waitFor(() => deliveryFor(receiver.deliveries, runId, webhookId), 15_000);
-    if (!d) return softSkip('blocked', `no ${EVENT_TYPE} delivery for this run arrived inside 15s — durability is v2-webhook-durable-delivery's claim, not this file's`);
+    if (!d) return softSkip('blocked', `no ${EVENT_TYPE} delivery for this run arrived inside 15s — durability is v2-webhook-durable-delivery's claim, not this file's. ${noDeliveryCause(receiver, `${EVENT_TYPE} delivery`)}`);
     const v2 = validators(2);
     const envelope = v2.ref(`${V2}webhook-delivery.schema.json`)(d.envelope);
     expect(envelope.ok, req(ID, DOC, `a major-2 delivery MUST validate against webhook-delivery.schema.json (v2) — { runId, workspaceId?, event } with event the verbatim v2 run event. ${envelope.errors}`)).toBe(true);
@@ -245,12 +242,12 @@ describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versio
     // `versions.supported` that no discovery document has, so this leg was inapplicable on every host.
     const versions = Array.isArray(disc?.['protocolVersions']) ? (disc?.['protocolVersions'] as unknown[]).map(String) : [];
     if (!versions.some((v) => v.startsWith('1.'))) return softSkip('inapplicable', `host advertises [${versions.join(', ') || 'no protocolVersions'}] — no 1.x member, so there is no v1 wire to keep still`);
-    const receiver = await startReceiver(); active = receiver.server;
+    const receiver = await startReceiver(); active = receiver;
     const webhookId = await register(receiver.url, 1);
     if (webhookId === null) return softSkip('blocked', 'registration refused or inapplicable (disposition recorded above)');
     const runId = await driveRun();
     const d = await waitFor(() => deliveryFor(receiver.deliveries, runId, webhookId), 15_000);
-    if (!d) return softSkip('blocked', `no ${EVENT_TYPE} delivery for this run arrived inside 15s`);
+    if (!d) return softSkip('blocked', `no ${EVENT_TYPE} delivery for this run arrived inside 15s. ${noDeliveryCause(receiver, `${EVENT_TYPE} delivery`)}`);
     // The v1 definition is the discriminator, not the owner's keys: v1's owner admits `subject` (RFC 0165
     // §B, echoed verbatim when present) alongside `principal`, so a v2 owner is ALSO a valid v1 owner.
     // What the v1 wire cannot carry is the v2 payload's integer `engineVersion` (string on v1) — a fan-out
@@ -269,7 +266,7 @@ describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versio
     // read null as absence, so this leg was inapplicable on exactly the hosts that could witness it.
     const gate = era2Gate(disc);
     if (gate !== null && !gate.ok) return softSkip(gate.kind, gate.reason);
-    const receiver = await startReceiver(); active = receiver.server;
+    const receiver = await startReceiver(); active = receiver;
     const webhookId = await register(receiver.url, 2);
     if (webhookId === null) return softSkip('blocked', 'registration refused (reason recorded above)');
     const log = await seedEra2Log(v1FixtureLog(FIXTURE), 'completed');
@@ -279,7 +276,7 @@ describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versio
     // The seam appends HISTORY — rows that already happened — and a host MAY not fan out history (the
     // reference host's seam appends with fan-out suppressed by design). No delivery inside 15s means the
     // era-2 fan-out branch is unobservable on this host, not that a measurement failed: inapplicable.
-    if (!d) return softSkip('inapplicable', `no ${EVENT_TYPE} delivery for the seeded era-2 run inside 15s — this host does not fan out seeded history, so the era-2 fan-out branch is unobservable here (recorded under openwop.family.conformance)`);
+    if (!d) return softSkip('inapplicable', `no ${EVENT_TYPE} delivery for the seeded era-2 run inside 15s — this host does not fan out seeded history, so the era-2 fan-out branch is unobservable here (recorded under openwop.family.conformance). ${noDeliveryCause(receiver, `${EVENT_TYPE} delivery`)}`);
     const payload = validators(2).ref(`${V2}run-event-payloads.schema.json#/$defs/runStarted`)(d.event['payload']);
     expect(payload.ok, req(ID, DOC, `an era-2 row delivered to a major-2 subscriber MUST be projected — the read projection applies at the fan-out as at poll/SSE (events.md §Era-2). ${payload.errors}`)).toBe(true);
     const owner = ownerOf(d.event);

package/src/scenarios/v2-webhook-durable-delivery.test.ts

@@ -28,11 +28,10 @@
  */
 
 import { afterEach, describe, it, expect } from 'vitest';
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { driver } from '../lib/driver.js';
 import { v2Discovery, gateFamily } from '../lib/v2.js';
 import { projectBoundId } from '../lib/bound-id.js';
-import { receiverBinding, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
+import { absenceIsUnmeasured, noDeliveryCause, startScopedReceiver, type ScopedReceiver } from '../lib/scoped-receiver.js';
 import { readErrorCode } from '../lib/error-envelope.js';
 import { blockedDespiteAssertions, softSkip } from '../lib/soft-skip.js';
 import { req } from '../lib/requirement-ids.js';
@@ -48,47 +47,48 @@ interface Attempt { readonly key: string; readonly runId: string | null; readonl
  * (`Infinity` ⇒ always fails). The key is `(webhookId, runId, sequence)` —
  * the dedup triple webhooks.md §Verification names.
  */
-async function startReceiver(failFirst: number): Promise<{ server: Server; url: string; attempts: Attempt[] }> {
+async function startReceiver(failFirst: number): Promise<ScopedReceiver & { attempts: Attempt[] }> {
   const attempts: Attempt[] = [];
   const seen = new Map<string, number>();
-  const server = createServer((request: IncomingMessage, res: ServerResponse) => {
-    const chunks: Buffer[] = [];
-    request.on('data', (c: Buffer) => chunks.push(c));
-    request.on('end', () => {
-      const body = Buffer.concat(chunks).toString('utf8');
-      let runId: string | null = null;
-      let sequence: unknown = null;
-      try {
-        const parsed = JSON.parse(body) as { runId?: unknown; event?: { sequence?: unknown } };
-        runId = typeof parsed.runId === 'string' ? parsed.runId : null;
-        sequence = parsed.event?.sequence ?? null;
-      } catch { /* not JSON — still an attempt */ }
-      const h = request.headers;
-      const webhookId = String(h['openwop-webhook-id'] ?? h['x-openwop-webhook-id'] ?? '');
-      const key = `${webhookId}|${runId ?? ''}|${String(sequence)}`;
-      const n = (seen.get(key) ?? 0) + 1;
-      seen.set(key, n);
-      const status = n <= failFirst ? 500 : 204;
-      attempts.push({ key, runId, webhookId, status, at: Date.now() });
-      res.writeHead(status);
-      res.end();
-    });
+  // `startScopedReceiver` (2.37.0). This receiver answers 500 BY DESIGN, and
+  // until now it advertised the same byte-identical destination as the other
+  // three webhook files on a tunnelled cut — so on a shared pinned port the
+  // exercise that happened to register alongside it saw failures it never
+  // caused. The `ours()` filter below was the workaround; the nonce removes the
+  // cause. The measured case is in that filter's own comment: a tier-2 host
+  // counted 6 attempts against a maxAttempts of 5 because another scenario's
+  // subscription delivered into this budget.
+  const rx = await startScopedReceiver((hit, res) => {
+    let runId: string | null = null;
+    let sequence: unknown = null;
+    try {
+      const parsed = JSON.parse(hit.body) as { runId?: unknown; event?: { sequence?: unknown } };
+      runId = typeof parsed.runId === 'string' ? parsed.runId : null;
+      sequence = parsed.event?.sequence ?? null;
+    } catch { /* not JSON — still an attempt */ }
+    const h = hit.headers;
+    const webhookId = String(h['openwop-webhook-id'] ?? h['x-openwop-webhook-id'] ?? '');
+    const key = `${webhookId}|${runId ?? ''}|${String(sequence)}`;
+    const n = (seen.get(key) ?? 0) + 1;
+    seen.set(key, n);
+    const status = n <= failFirst ? 500 : 204;
+    attempts.push({ key, runId, webhookId, status, at: Date.now() });
+    res.writeHead(status);
+    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();
-  if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
-  return { server, url: `http://${binding.advertise}:${addr.port}/`, attempts };
+  return { ...rx, attempts };
 }
 
-let active: Server | null = null;
+// Closed through the receiver: `close()` also drops this exercise's nonce from
+// the front-mux registry, so the retries this file deliberately provokes are
+// answered 404 by whoever next holds the port instead of being handed to the
+// next exercise's recorder.
+let active: ScopedReceiver | null = null;
 afterEach(async () => {
   if (active) {
-    const s = active;
+    const rx = active;
     active = null;
-    await new Promise<void>((resolve) => s.close(() => resolve()));
+    await rx.close();
   }
 });
 
@@ -215,15 +215,18 @@ const RETRY_TEST_TIMEOUT_MS = RETRY_WAIT_CAP_MS + WAIT_SLACK_MS;
 const DEAD_LETTER_TEST_TIMEOUT_MS = RETRY_WAIT_CAP_MS * 2 + WAIT_SLACK_MS;
 
 /** Register the suite receiver; null (with a note) when the host's SSRF guard refuses a loopback URL. */
-async function register(url: string): Promise<{ webhookId: string } | null> {
-  const registration = resolveRegistrationUrl(url);
-  const reg = await driver.post('/webhooks', { url: registration.url, events: ['run.completed'] });
+async function register(rx: ScopedReceiver): Promise<{ webhookId: string } | null> {
+  // `rx.url` is this exercise's own destination already — the front (when
+  // wired) plus this receiver's nonce path. It is no longer run through
+  // `resolveRegistrationUrl`, which returned the front VERBATIM and so dropped
+  // the path that makes the subscription ours.
+  const reg = await driver.post('/webhooks', { url: rx.url, events: ['run.completed'] });
   if (reg.status === 400 && readErrorCode(reg.json) === 'webhook_url_rejected') {
-    if (!registration.tunnelled) {
+    if (!rx.tunnelled) {
       softSkip('blocked', 'host SSRF guard rejected the loopback receiver (webhooks.md §Egress requires it); set OPENWOP_WEBHOOK_RECEIVER_URL to a public https tunnel in front of the suite receiver');
       return null;
     }
-    expect.fail(`host rejected the operator-supplied public https receiver (${registration.url}) with webhook_url_rejected — a public https destination is legitimate under webhooks.md §Egress`);
+    expect.fail(`host rejected the operator-supplied public https receiver (${rx.url}) with webhook_url_rejected — a public https destination is legitimate under webhooks.md §Egress`);
   }
   expect(reg.status, req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Surfaces', 'POST /webhooks MUST answer 201 { webhookId }')).toBe(201);
   const webhookId = (reg.json as { webhookId?: unknown } | null)?.webhookId;
@@ -239,8 +242,8 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     if (!fixtureAdvertised(doc, FIXTURE)) return softSkip('inapplicable', `${FIXTURE} fixture not advertised — no run to deliver`);
 
     const receiver = await startReceiver(FAIL_FIRST); // 500, 500, then 204
-    active = receiver.server;
-    const sub = await register(receiver.url);
+    active = receiver;
+    const sub = await register(receiver);
     if (sub === null) return softSkip('blocked', 'registration refused (reason recorded above)');
 
     const create = await driver.post('/runs', { workflowId: FIXTURE });
@@ -258,9 +261,22 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     const ours = () => receiver.attempts.filter((a) => a.runId === runId && a.webhookId === sub.webhookId);
     const retried = await waitFor(() => ours().some((a) => a.status === 204), retryWaitMs(doc));
     const attempts = ours();
+    // A zero that is PROVABLY not a verdict about the host records `blocked`
+    // with its cause, not `executed-fail` (2.37.0). `absenceIsUnmeasured` is
+    // true only when other traffic reached this listener — the path from the
+    // host to this process works, so what is absent is this exercise's
+    // IDENTITY, not delivery. That was the ordinary case on a tunnelled cut
+    // until this file stopped sharing one byte-identical destination with three
+    // others. `blocked` denies certification exactly as a failure does (RFC
+    // 0168 §E.1), so nothing is softened. When nothing reached the listener at
+    // all the reading is still ambiguous, and the hard assertion below stands —
+    // now carrying the address it was waiting on.
+    if (attempts.length === 0 && absenceIsUnmeasured(receiver)) {
+      return blockedDespiteAssertions(noDeliveryCause(receiver, 'run.completed attempt for this run'));
+    }
     expect(
       attempts.length,
-      req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Durability', 'the host MUST attempt delivery of run.completed for THIS run to the registered subscriber'),
+      req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Durability', `the host MUST attempt delivery of run.completed for THIS run to the registered subscriber — ${noDeliveryCause(receiver, 'run.completed attempt for this run')}`),
     ).toBeGreaterThan(0);
     const failedThenSucceeded = attempts.filter((a) => a.status === 500).length;
     expect(
@@ -327,8 +343,8 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     if (!fixtureAdvertised(doc, FIXTURE)) return softSkip('inapplicable', `${FIXTURE} fixture not advertised — no run to deliver`);
 
     const receiver = await startReceiver(Number.POSITIVE_INFINITY); // never succeeds
-    active = receiver.server;
-    const sub = await register(receiver.url);
+    active = receiver;
+    const sub = await register(receiver);
     if (sub === null) return softSkip('blocked', 'registration refused (reason recorded above)');
 
     // The row id is the FIRST thing this leg names: `register()` asserts under
@@ -459,8 +475,8 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     if (!fixtureAdvertised(doc, FIXTURE)) return softSkip('inapplicable', `${FIXTURE} fixture not advertised — no delivery to exhaust`);
 
     const receiver = await startReceiver(Number.POSITIVE_INFINITY); // never succeeds
-    active = receiver.server;
-    const sub = await register(receiver.url);
+    active = receiver;
+    const sub = await register(receiver);
     if (sub === null) return softSkip('blocked', 'registration refused (reason recorded above)');
     // Same two traps as the leg above (2.34.1): `register()` asserts under the base
     // id, so name this row first; and every `blocked` after it must STAND rather

package/src/scenarios/webhook-signed-delivery.test.ts

@@ -103,14 +103,14 @@
  */
 
 import { afterEach, describe, expect, it } from 'vitest';
-import { softSkip } from '../lib/soft-skip.js';
+import { blockedDespiteAssertions, softSkip } from '../lib/soft-skip.js';
 import { createHmac } from 'node:crypto';
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { driver } from '../lib/driver.js';
 import { discoveryFamilies } from '../lib/discovery-capabilities.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
-import { discoverOwnedTenant, receiverBinding, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
+import { discoverOwnedTenant } from '../lib/webhook-receiver.js';
+import { absenceIsUnmeasured, noDeliveryCause, startScopedReceiver, type ScopedReceiver } from '../lib/scoped-receiver.js';
 import { req } from '../lib/requirement-ids.js';
 
 interface DeliveredRequest {
@@ -118,44 +118,43 @@ interface DeliveredRequest {
   readonly body: string;
 }
 
-async function startReceiver(): Promise<{ server: Server; url: string; received: DeliveredRequest[] }> {
+async function startReceiver(): Promise<ScopedReceiver & { received: DeliveredRequest[] }> {
   const received: DeliveredRequest[] = [];
-  const server = createServer((reqBody: IncomingMessage, res: ServerResponse) => {
-    const chunks: Buffer[] = [];
-    reqBody.on('data', (c: Buffer) => chunks.push(c));
-    reqBody.on('end', () => {
-      const body = Buffer.concat(chunks).toString('utf8');
-      const headers: Record<string, string> = {};
-      for (const [k, v] of Object.entries(reqBody.headers)) {
-        if (typeof v === 'string') headers[k.toLowerCase()] = v;
-        else if (Array.isArray(v)) headers[k.toLowerCase()] = v.join(',');
-      }
-      received.push({ headers, body });
-      res.writeHead(204);
-      res.end();
-    });
-  });
-  // Port 0 (ephemeral) by default — nothing outside this process needs to find
-  // it. But OPENWOP_WEBHOOK_RECEIVER_URL fronts THIS receiver through a tunnel,
-  // and a tunnel has to be pointed at a port the operator knows in ADVANCE. An
+  // `startScopedReceiver` (2.37.0) supplies the listening, the pinned-port
+  // binding described below, the public front, AND a nonce path that makes this
+  // exercise's destination its own. Four webhook files registered the SAME
+  // byte-identical front URL before that, and a webhook subscription outlives
+  // the file that made it — so a sibling's retries (one of those files answers
+  // 500 by design) arrived here indistinguishable from this run's deliveries.
+  //
+  // The pinned port is still honoured, and still for the reason it was added:
+  // OPENWOP_WEBHOOK_RECEIVER_URL fronts THIS receiver through a tunnel, and a
+  // tunnel has to be pointed at a port the operator knows in ADVANCE. An
   // ephemeral port makes that variable unusable by anyone not reading the port
   // out of a running process — a gap found by standing up a real TLS front and
-  // trying to use the feature, not by reading the code. OPENWOP_WEBHOOK_RECEIVER_PORT
-  // pins it so `ngrok http <port>` (or a proxy) has a stable target.
-  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();
-  if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
-  return { server, url: `http://${binding.advertise}:${addr.port}/`, received };
+  // trying to use the feature, not by reading the code.
+  const rx = await startScopedReceiver((hit, res) => {
+    const headers: Record<string, string> = {};
+    for (const [k, v] of Object.entries(hit.headers)) {
+      if (typeof v === 'string') headers[k.toLowerCase()] = v;
+      else if (Array.isArray(v)) headers[k.toLowerCase()] = v.join(',');
+    }
+    received.push({ headers, body: hit.body });
+    res.writeHead(204);
+    res.end();
+  });
+  return { ...rx, received };
 }
 
-let activeServer: Server | null = null;
+// Closed through the receiver: `close()` also drops this exercise's nonce from
+// the front-mux registry, so a delivery that arrives after the leg has finished
+// is answered 404 rather than handed to the next exercise's recorder.
+let activeServer: ScopedReceiver | null = null;
 afterEach(async () => {
   if (activeServer) {
-    await new Promise<void>((resolve) => activeServer!.close(() => resolve()));
+    const rx = activeServer;
     activeServer = null;
+    await rx.close();
   }
 });
 
@@ -179,7 +178,7 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     }
 
     const receiver = await startReceiver();
-    activeServer = receiver.server;
+    activeServer = receiver;
 
     // Register the webhook.
     // webhooks.md §Register: `events` + `tenantId` are REQUIRED (empty events → 400).
@@ -190,9 +189,12 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     // tenantId is 403'd by a host that scopes subscriptions by membership
     // (RFC 0093). Single-tenant hosts return undefined ⇒ omit tenantId.
     const ownedTenant = await discoverOwnedTenant(driver);
-    const registration = resolveRegistrationUrl(receiver.url);
+    // `receiver.url` is this exercise's own destination — the public front (when
+    // wired) plus this receiver's nonce path. It is no longer run through
+    // `resolveRegistrationUrl`, which returned the front VERBATIM and so dropped
+    // the path that makes the subscription ours.
     const reg = await driver.post('/v1/webhooks', {
-      url: registration.url,
+      url: receiver.url,
       events: ['run.completed'],
       ...(ownedTenant ? { tenantId: ownedTenant } : {}),
     });
@@ -212,7 +214,7 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     if (reg.status === 400) {
       const body = reg.json as { error?: string };
       if (body.error === 'webhook_url_rejected') {
-        if (!registration.tunnelled) {
+        if (!receiver.tunnelled) {
           // eslint-disable-next-line no-console
           console.warn(
             '[webhook-signed-delivery] host SSRF guard rejected the loopback receiver; ' +
@@ -222,7 +224,7 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
           return softSkip('blocked', 'precondition not met — `body.error === \'webhook_url_rejected\'` returned early (seam, prior step, or fixture unavailable)');
         }
         expect.fail(
-          `host rejected the operator-supplied public https receiver (${registration.url}) with ` +
+          `host rejected the operator-supplied public https receiver (${receiver.url}) with ` +
             'webhook_url_rejected. A public https destination is legitimate under ' +
             'webhooks.md §"SSRF protection" and RFC 0093 §"Delivery-time egress validation"; ' +
             'rejecting it is a host defect, not an unmet precondition.',
@@ -307,15 +309,26 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     // has a subscriber; if nothing arrived HERE, the delivery went somewhere
     // this process cannot see and every assertion below it would be vacuous.
     // It fails — it must never soft-skip.
+    //
+    // The ONE exception, and it is not a softening (2.37.0): when other traffic
+    // DID reach this listener, the path from the host to this process demonstrably
+    // works, so a zero is the absence of this exercise's IDENTITY and not of
+    // delivery — unmeasured, not unmet. That is recorded `blocked`, which denies
+    // certification exactly as a failure does (RFC 0168 §E.1), so the mis-wired
+    // front this assertion guards against still cannot read as a pass; a
+    // mis-wired front produces no traffic here at all and still fails below.
+    if (ourDeliveries.length === 0 && absenceIsUnmeasured(receiver)) {
+      return blockedDespiteAssertions(noDeliveryCause(receiver, 'run event for this run'));
+    }
     expect(ourDeliveries.length, req('openwop.it.webhook-signed-delivery.host-posts-run-events-to-subscriber-with-valid-x-openwop-signature', 
       'webhooks.md §"Delivery"',
-      registration.tunnelled
+      receiver.tunnelled
         ? 'host MUST POST at least one event for THIS run to the registered subscriber. ' +
           'Registration was accepted, so zero deliveries observed on the local receiver means ' +
           'either the host did not deliver, or OPENWOP_WEBHOOK_RECEIVER_URL does not actually ' +
-          'front this process. Both are failures; neither is a skip.'
+          `front this process. Both are failures; neither is a skip. ${noDeliveryCause(receiver, 'run event for this run')}`
         : 'host MUST POST at least one event for THIS run to a registered subscriber within '
-          + `${DELIVERY_DEADLINE_MS}ms of run.completed`,
+          + `${DELIVERY_DEADLINE_MS}ms of run.completed. ${noDeliveryCause(receiver, 'run event for this run')}`,
     )).toBeGreaterThan(0);
 
     // Validate the FIRST delivery's signature contract. Other deliveries
@@ -418,7 +431,7 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     }
 
     const receiver = await startReceiver();
-    activeServer = receiver.server;
+    activeServer = receiver;
 
     const ownedTenant = await discoverOwnedTenant(driver);
     const reg = await driver.post('/v1/webhooks', {

package/src/setup.ts

@@ -36,7 +36,7 @@ import { basename, join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { PKG_ROOT_PATH } from './lib/paths.js';
 import { recordRequirement, hasRequirement, journalLength, journalSince } from './lib/requirement-ledger.js';
-import { requirementIdForFile, resolveFileRecord, resolveItRecord, type FileTestState } from './lib/scenario-disposition.js';
+import { requirementIdForFile, resolveFileRecord, resolveItRecord, type FileTestState, type TestFailure } from './lib/scenario-disposition.js';
 import { softSkipDisposition, softSkipDispositionSince, softSkipMark } from './lib/soft-skip.js';
 import { ItIdAllocator, takeExplicitRequirementId } from './lib/requirement-ids.js';
 import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './lib/spec-coherence.js';
@@ -248,6 +248,8 @@ await maybeStartA2AFakePeer();
 // Setup-file hooks apply to every file in the worker; state is keyed by file.
 const _fileStates = new Map<string, FileTestState[]>();
 const _fileAssertions = new Map<string, number>();
+/** Per file: the failing cases, so the file row can NAME them (2.37.0). */
+const _fileFailures = new Map<string, TestFailure[]>();
 const _ledgerMarks = new Map<string, number>();
 // Per-`it` recording (v2 charter Phase 1, suite 1.153.0 — the durable G8 fix
 // named in scenario-disposition.ts). Each test gets its own ledger row under
@@ -415,6 +417,17 @@ afterEach(({ task }) => {
   const arr = _fileStates.get(file) ?? [];
   arr.push(state === 'pass' ? 'pass' : state === 'fail' ? 'fail' : 'skip');
   _fileStates.set(file, arr);
+  // Which leg failed, and why (2.37.0). The file row used to say only "one or
+  // more assertions in the file failed" — a detail that names no case, quotes no
+  // message, and cannot be acted on. A tier-2 operator read exactly that row for
+  // `v2-run-bulk-cancel` and had to hand-probe every assertion in the file
+  // against production to find out what the host had done.
+  if (state === 'fail') {
+    const msg = ((task.result?.errors ?? [])[0] as { message?: string } | undefined)?.message;
+    const fails = _fileFailures.get(file) ?? [];
+    fails.push({ name: task.name, ...(msg === undefined ? {} : { message: msg }) });
+    _fileFailures.set(file, fails);
+  }
   // RFC 0148 §C assertionCount: how many `expect` calls this test actually made.
   // A leg that early-returns from a gate makes zero, and a file of such legs is
   // an `executed-pass` with assertionCount 0 — visible, and unclassified for a
@@ -470,13 +483,19 @@ afterEach(({ task }) => {
     // `inapplicable` came out `blocked` — which denies certification bundle-wide).
     const noted = softSkipDispositionSince(file, _itSoftSkipMarks.get(file) ?? 0);
     const err = (task.result?.errors ?? [])[0] as { message?: string } | undefined;
-    const rec = resolveItRecord(state === 'pass' ? 'pass' : state === 'fail' ? 'fail' : 'skip', calls, gate, noted, err?.message, targetMajor() === 2);
+    const rec = resolveItRecord(state === 'pass' ? 'pass' : state === 'fail' ? 'fail' : 'skip', calls, gate, noted, err?.message, targetMajor() === 2, task.name);
     disposition = rec.disposition;
     detail = rec.detail;
   }
   try {
     const evidence = takeNotedEvidence();
-    recordRequirement(itId, disposition, detail, { assertionCount: calls, scenarioFile: file, ...(evidence === null ? {} : { evidence }) });
+    // `fold: true` — several `it` legs of one file legitimately share ONE
+    // explicit id (27 files do, via a module-level `const ID` handed to
+    // `req()`). Without the fold the second leg's verdict hit
+    // `recordRequirement`'s one-disposition-per-run throw, was swallowed by the
+    // catch below, and never reached the JSONL sink: a file could record
+    // `executed-fail` while its own requirement row read `executed-pass`.
+    recordRequirement(itId, disposition, detail, { assertionCount: calls, scenarioFile: file, fold: true, ...(evidence === null ? {} : { evidence }) });
   } catch {
     /* never fail a test for bookkeeping */
   }
@@ -503,7 +522,7 @@ afterAll(({}, suite) => {
   // the marker detail — never to a pass. Floors still REJECT that row, so the
   // honest bundle row and the pressure to say why both survive. The rule is
   // `resolveFileRecord` (pinned by conformance-execution-witness.test.ts).
-  const { disposition, detail } = resolveFileRecord(states, gateReason, assertionCount, softSkipDisposition(file), file);
+  const { disposition, detail } = resolveFileRecord(states, gateReason, assertionCount, softSkipDisposition(file), file, _fileFailures.get(file) ?? []);
   const fileRequirementId = requirementIdForFile(file);
   // A scenario that classified ITSELF wins outright — including its `detail` and
   // its `assertionCount`.
@@ -530,6 +549,7 @@ afterAll(({}, suite) => {
   }
   _fileStates.delete(file);
   _fileAssertions.delete(file);
+  _fileFailures.delete(file);
   _ledgerMarks.delete(file);
   _itAllocators.delete(file);
   _itMarks.delete(file);