@openwop/openwop-conformance 2.37.0 → 2.37.1

package/src/scenarios/v2-bound-id-kinds.test.ts

@@ -27,12 +27,11 @@
  * @see RFCS/0187-host-found-bindings.md §A
  */
 import { describe, it, expect } from 'vitest';
-import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { driver, type OpenWOPResponse } from '../lib/driver.js';
 import { v2Discovery, gateFamily } from '../lib/v2.js';
 import { readErrorCode } from '../lib/error-envelope.js';
 import { softSkip } from '../lib/soft-skip.js';
-import { receiverBinding, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
+import { noDeliveryCause, startScopedReceiver, unservedDestination, type ScopedReceiver } from '../lib/scoped-receiver.js';
 import { scaledTimeoutMs } from '../lib/polling.js';
 import { req } from '../lib/requirement-ids.js';
 import { projectBoundId, BOUND_ID } from '../lib/bound-id.js';
@@ -50,20 +49,21 @@ const PER_KIND = 'openwop.requirement.0187.bound-id-kinds.per-kind';
 const WEBHOOK_EMITTED = 'openwop.requirement.0187.bound-id-kinds.webhook-emitted';
 
 type Delivery = { body: string; headers: Record<string, string | string[] | undefined> };
-/** The suite's receiver, bound the way every webhook scenario binds it (pinned port / public front honoured). */
-async function startReceiver(): Promise<{ server: Server; url: string; deliveries: Delivery[] }> {
+/**
+ * The suite's receiver for THIS exercise — pinned port and public front
+ * honoured, plus a per-exercise nonce path (2.37.0). Four webhook files used to
+ * register the same byte-identical front URL, and a webhook subscription
+ * outlives the file that made it, so a sibling's leftovers arrived here
+ * indistinguishable from this run's deliveries.
+ */
+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(); });
+  const rx = await startScopedReceiver((hit, res) => {
+    deliveries.push({ body: hit.body, headers: hit.headers });
+    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();
-  return { server, url: `http://${binding.advertise}:${typeof addr === 'object' && addr ? addr.port : 0}/hook`, deliveries };
+  return { ...rx, deliveries };
 }
 const header = (d: Delivery, name: string): string | undefined => { const v = d.headers[name]; return Array.isArray(v) ? v[0] : v; };
 
@@ -89,13 +89,21 @@ describe('v2 bound-id kinds (identity.md §5, RFC 0187 §A)', () => {
   it('subscriptionId: POST /webhooks mints a bound webhookId, the projected segment is accepted, and a foreign tenant segment is refused 403', async () => {
     if (!(await v2Discovery())) return softSkip('blocked', 'v2 discovery unreachable');
     if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised — no subscription to mint (gate recorded under openwop.family.webhooks)');
-    // Route the mint through `resolveRegistrationUrl` so an operator who sets
+    // Route the mint through the operator's front so an operator who sets
     // OPENWOP_WEBHOOK_RECEIVER_URL actually gets a reachable registration here.
-    // Before this, the blocked note TOLD them to set that variable and this file
+    // Before that, the blocked note TOLD them to set the variable and this file
     // never read it — inoperative advice in a suite where one blocked row denies
     // every claimed profile (RFC 0168 §E.1). The fallback stays a reserved
     // `.invalid` host: this leg only needs the mint, never a delivery.
-    const registration = resolveRegistrationUrl('https://subscriber.invalid/hook');
+    //
+    // `unservedDestination`, not `resolveRegistrationUrl` (2.37.0): the latter
+    // returns the front VERBATIM, so this subscription had the same identity as
+    // every other exercise's, and it is live from the 201 until the DELETE
+    // below. Anything the host fanned out in that window landed on whichever
+    // listener held the pinned port and was read as THAT exercise's traffic. The
+    // nonce is served by nobody on purpose — this leg wants no delivery, and a
+    // delivery to it is now answered 404 instead of absorbed.
+    const registration = unservedDestination('https://subscriber.invalid/hook');
     const reg = await http(() => driver.post('/webhooks', { url: registration.url, events: ['run.completed'] }));
     if (reg === null) return softSkip('blocked', 'POST /webhooks unreachable (fetch failed)');
     if (reg.status === 400 && readErrorCode(reg.json) === 'webhook_url_rejected') return softSkip('blocked', `host SSRF guard rejected the registration URL ${registration.url}${registration.tunnelled ? ' (from OPENWOP_WEBHOOK_RECEIVER_URL)' : ' — set OPENWOP_WEBHOOK_RECEIVER_URL to a public https receiver, which THIS leg now honours'}`);
@@ -136,11 +144,14 @@ describe('v2 bound-id kinds (identity.md §5, RFC 0187 §A)', () => {
     const rx = await startReceiver();
     let webhookId: string | null = null;
     try {
-      const registration = resolveRegistrationUrl(rx.url);
-      const reg = await http(() => driver.post('/webhooks', { url: registration.url, events: ['run.completed'] }));
+      // `rx.url` is already this exercise's destination — the front (when
+      // wired) plus its nonce path — so it is not run through
+      // `resolveRegistrationUrl`, which returns the front VERBATIM and would
+      // drop the path that makes the subscription ours.
+      const reg = await http(() => driver.post('/webhooks', { url: rx.url, events: ['run.completed'] }));
       if (reg === null) return softSkip('blocked', 'POST /webhooks unreachable (fetch failed)');
       if (reg.status === 400 && readErrorCode(reg.json) === 'webhook_url_rejected') {
-        return softSkip('blocked', `host SSRF guard rejected the suite receiver ${registration.url} (webhooks.md §Egress requires it) — set OPENWOP_WEBHOOK_RECEIVER_URL to a public https front for the receiver to witness what the host emits`);
+        return softSkip('blocked', `host SSRF guard rejected the suite receiver ${rx.url} (webhooks.md §Egress requires it) — set OPENWOP_WEBHOOK_RECEIVER_URL to a public https front for the receiver to witness what the host emits`);
       }
       const minted = (reg.json as { webhookId?: unknown } | null)?.webhookId;
       if (reg.status !== 201 || typeof minted !== 'string') return softSkip('blocked', `POST /webhooks answered ${reg.status} without a webhookId — the mint leg above owns that obligation; this leg needs an id to compare`);
@@ -155,7 +166,7 @@ describe('v2 bound-id kinds (identity.md §5, RFC 0187 §A)', () => {
       const deadline = Date.now() + scaledTimeoutMs(20_000);
       while (ours().length === 0 && Date.now() < deadline) await new Promise((r) => setTimeout(r, 250));
       const delivery = ours()[0];
-      if (delivery === undefined) return softSkip('blocked', `no delivery for run ${runId} reached the suite receiver within ${scaledTimeoutMs(20_000)}ms — what the host emits was not observed`);
+      if (delivery === undefined) return softSkip('blocked', `no delivery for run ${runId} reached the suite receiver within ${scaledTimeoutMs(20_000)}ms — what the host emits was not observed. ${noDeliveryCause(rx, `run.completed delivery for run ${runId}`)}`);
       expect(
         header(delivery, 'openwop-webhook-id'),
         req(WEBHOOK_EMITTED, 'webhooks.md §Headers (RFC 0187 §A.1)', `the delivery's OpenWOP-Webhook-Id MUST equal the tenant-bound webhookId the host minted (${minted}) — a subscriber identifies its deliveries by the header, not by the 201 it received once`),
@@ -172,7 +183,9 @@ describe('v2 bound-id kinds (identity.md §5, RFC 0187 §A)', () => {
       }
     } finally {
       if (webhookId !== null) await http(() => driver.delete(`/webhooks/${projectBoundId(webhookId as string)}`));
-      await new Promise<void>((ok) => rx.server.close(() => ok()));
+      // Closed through the receiver: `close()` also drops this exercise's
+      // nonce from the front-mux registry.
+      await rx.close();
     }
   });
 

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

@@ -19,8 +19,15 @@
  *     `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.
+ * the LOSER leg records `partial-witness` — the 409 branch never ran, so a pass
+ * is not claimed for it.
+ *
+ * Two `it`s over ONE race (2.37.x). §B names two requirement ids and both were
+ * cited from a single `it`, so only the last of them could ever get a ledger
+ * row; the winner id was recorded on no host. The race is driven once and
+ * memoised — driving it twice would measure two unrelated races and halve the
+ * chance that either overlaps — and each leg now carries its own id, so the
+ * winner clause keeps its verdict when the 409 branch does not run.
  *
  * @see spec/v2/core/idempotency.md
  * @see RFCS/0213-three-unstated-v2-outcomes.md §B
@@ -43,35 +50,83 @@ async function discovery(): Promise<Record<string, unknown> | null> { try { retu
 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)); }
 
+/** The race's outcome, or the reason it could not be driven. */
+type Race =
+  | { readonly kind: 'ran'; readonly all: readonly OpenWOPResponse[]; readonly successes: readonly OpenWOPResponse[]; readonly refusals: readonly OpenWOPResponse[] }
+  | { readonly kind: 'blocked'; readonly reason: string };
+
+/**
+ * ONE race, read by both legs.
+ *
+ * RFC 0213 §B names two requirement ids, and until 2.37.x both were cited from
+ * a SINGLE `it()`. The ledger keys on the id and `setup.ts` takes one
+ * `explicitId` per test, so only the LAST one cited got a row:
+ * `0213.in-flight-one-winner` was never recorded on any host, and nothing said
+ * so. (Found by `check-req-only.mjs` rule (d) the moment it learned to resolve a
+ * `const` handed to `req()` — it had compared only call-site literals, so the
+ * violation was invisible when this file was written.)
+ *
+ * Splitting the legs must not split the EXERCISE: the record is in flight only
+ * while the winning create is being handled, so driving the race twice would
+ * measure two unrelated races and halve the chance that either overlaps. The
+ * race is therefore memoised here and both legs await the same result — the
+ * house pattern from `v2-subject-link-record.test.ts`.
+ */
+let race: Promise<Race> | undefined;
+function theRace(): Promise<Race> {
+  return (race ??= drive());
+}
+
+async function drive(): Promise<Race> {
+  if (!(await discovery())) return { kind: 'blocked', reason: '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 { kind: 'blocked', reason: '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 { kind: 'blocked', reason: `the ${FIXTURE} fixture is not runnable (${codes})` };
+  }
+  return {
+    kind: 'ran',
+    all: rs,
+    successes: rs.filter((r) => r.status >= 200 && r.status < 300),
+    refusals: rs.filter((r) => !(r.status >= 200 && r.status < 300)),
+  };
+}
+
 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'));
+  it('concurrent same-key creates yield exactly one run', async () => {
+    const r = await theRace();
+    if (r.kind === 'blocked') return softSkip('blocked', r.reason);
+    expect(r.successes.length, req(ID_ONE, DOC, `at least one of ${N} same-key creates MUST complete (statuses: ${r.all.map((x) => x.status).join(',')})`)).toBeGreaterThan(0);
+    const runIds = new Set(r.successes.map((x) => (x.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 ?? {};
+  }, 60_000);
+
+  it('each loser is a marked replay of a final outcome, or 409 idempotency_in_flight with no retry timing in details', async () => {
+    const r = await theRace();
+    if (r.kind === 'blocked') return softSkip('blocked', r.reason);
+    const unmarked = r.successes.filter((x) => x.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 ${r.successes.length} unmarked)`)).toBe(1);
+    for (const x of r.refusals) {
+      const code = readErrorCode(x.json);
+      expect({ status: x.status, code }, req(ID_LOSER, DOC, `a loser that is not a replay MUST be 409 idempotency_in_flight (got ${x.status} ${String(code)})`)).toEqual({ status: 409, code: 'idempotency_in_flight' });
+      const details = (x.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');
+      const ra = x.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`);
+    // Every loser replayed the winner: RFC 0213 §B permits exactly this (a
+    // loser MAY wait and receive a final outcome, marked). The 409 branch did
+    // not run, so the row is a partial witness — never `blocked`, which would
+    // deny certification (RFC 0168 §E.1) to a host that did nothing wrong.
+    // (#1525's fix, kept verbatim; `r.refusals` is the split form's spelling of
+    // its `refusals`, and it now lands on the LOSER id it is about rather than
+    // on a row shared with the winner clause.)
+    if (r.refusals.length === 0) return softSkip('inapplicable', `no loser was refused in flight — all ${N} answers were successes (each loser a marked replay, which §B permits), so the 409 branch did not run on this host`);
   }, 60_000);
 });

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