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

package/src/scenarios/v2-v1-events-translated.test.ts

@@ -0,0 +1,105 @@
+/**
+ * RFC 0176 §A.3 / §A.4 — `v1-events-translated` (suite 2.0.0, target major 2;
+ * seam-gated on `openwop-conformance-seams-v2`).
+ *
+ * A v2 host reading a run in era `2` MUST translate every event through
+ * `spec/v2/event-codemap.json` at the storage boundary: `type` is mapped,
+ * `sequence` is preserved verbatim including `0`, `eventId` / `timestamp` /
+ * `causationId` pass through (`spec/v2/core/persistence.md` §The reader rule).
+ * The rule binds every reader — poll, SSE and fork are read here so a
+ * wrapper-only adapter (one that some call sites bypass, §The seat) is caught.
+ *
+ * The era-2 log is seeded in v1 vocabulary through the event-log seed seam
+ * (lib/era2-seed.ts names the contract) with two renamed codemap rows
+ * (`agent.toolCalled` → `agent.tool-called`, `agent.toolReturned` →
+ * `agent.tool-returned`). Without the seams profile, or without the seam,
+ * every leg records `blocked` naming it.
+ *
+ * @see spec/v2/core/persistence.md §The reader rule, §The seat
+ * @see spec/v2/core/events.md §Reading an era-2 log
+ */
+
+import { describe, it, expect } from 'vitest';
+import { v2Discovery, gateFamily } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { codemapV1toV2, era2Gate, eventsOf, forkRun, pollEvents, seedEra2Log, streamEvents, v1FixtureLog, type ReadEvent, type SeedEvent } from '../lib/era2-seed.js';
+
+const DOC = 'spec/v2/core/persistence.md §The reader rule';
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+/** The assertions every reader must satisfy against the seeded log — one requirement id per leg, passed in. */
+function assertTranslated(id: string, reader: string, seeded: readonly SeedEvent[], read: readonly ReadEvent[]): void {
+  const map = codemapV1toV2();
+  const expectedTypes = seeded.map((e) => map.get(e.type) ?? e.type);
+  const renamed = seeded.filter((e) => map.get(e.type) !== undefined && map.get(e.type) !== e.type).map((e) => e.type);
+  expect(read.length, req(id, DOC, `${reader} MUST return every seeded row (${seeded.length}) — got ${read.length}`)).toBeGreaterThanOrEqual(seeded.length);
+  const bySeq = new Map<number, ReadEvent>();
+  for (const e of read) if (typeof e.sequence === 'number') bySeq.set(e.sequence, e);
+  expect(bySeq.has(0), req(id, DOC, `${reader}: sequence 0 MUST be present — sequence is preserved verbatim including 0 (RFC 0165 G7)`)).toBe(true);
+  for (const s of seeded) {
+    const got = bySeq.get(s.sequence);
+    expect(got, req(id, DOC, `${reader}: the seeded sequence ${s.sequence} MUST be readable under its own sequence (the sequence space is preserved, never renumbered)`)).toBeDefined();
+    expect(got?.type, req(id, DOC, `${reader}: v1 type ${s.type} at sequence ${s.sequence} MUST read back as the codemap's v2 name ${map.get(s.type) ?? s.type}`)).toBe(map.get(s.type) ?? s.type);
+    if (s.timestamp !== undefined) {
+      expect(got?.timestamp, req(id, DOC, `${reader}: timestamp passes through untouched at sequence ${s.sequence}`)).toBe(s.timestamp);
+    }
+  }
+  const leaked = read.map((e) => String(e.type)).filter((t) => renamed.includes(t));
+  expect(leaked, req(id, DOC, `${reader}: no v1 name of a renamed row may survive the read (a host MUST NOT carry a private mapping or pass an unmapped name through) — leaked [${leaked.join(', ')}]; expected [${expectedTypes.join(', ')}]`)).toEqual([]);
+}
+
+describe('RFC 0176 §A.3 — v1-events-translated (seam-gated)', () => {
+  it('poll reads an era-2 log with v2 type names and sequence 0 present', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const gate = era2Gate(doc);
+    if (gate !== null && !gate.ok) return softSkip(gate.kind, gate.reason);
+    const log = v1FixtureLog();
+    const seeded = await seedEra2Log(log, 'completed');
+    if (!seeded.ok) return softSkip(seeded.kind, seeded.reason);
+    const res = await pollEvents(seeded.runId);
+    if (res === null) return softSkip('blocked', 'GET /runs/{runId}/events/poll unreachable (fetch failed)');
+    expect(res.status, req('openwop.requirement.0176.v1-events-translated.poll', DOC, `poll over an era-2 log the codemap fully names MUST answer 200 (got ${res.status}) — every row is mapped, so nothing refuses the read`)).toBe(200);
+    assertTranslated('openwop.requirement.0176.v1-events-translated.poll', 'poll', log, eventsOf(res.json));
+  });
+
+  it('SSE reads the same era-2 log with v2 type names', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const gate = era2Gate(doc);
+    if (gate !== null && !gate.ok) return softSkip(gate.kind, gate.reason);
+    const log = v1FixtureLog();
+    const seeded = await seedEra2Log(log, 'completed');
+    if (!seeded.ok) return softSkip(seeded.kind, seeded.reason);
+    const stream = await streamEvents(seeded.runId);
+    if (stream === null) return softSkip('blocked', 'GET /runs/{runId}/events (SSE) unreachable (fetch failed)');
+    expect(stream.status, req('openwop.requirement.0176.v1-events-translated.sse', DOC, `streamRunEvents over an era-2 log MUST answer 200 text/event-stream (got ${stream.status}) — the stream reader is bound by the same rule as poll`)).toBe(200);
+    assertTranslated('openwop.requirement.0176.v1-events-translated.sse', 'SSE (streamMode=debug)', log, stream.events);
+  });
+
+  it('a fork of the era-2 run reads its inherited prefix with v2 type names', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const gate = era2Gate(doc);
+    if (gate !== null && !gate.ok) return softSkip(gate.kind, gate.reason);
+    if (!(await gateFamily('replay'))) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay) — the fork reader has no surface');
+    const log = v1FixtureLog();
+    const seeded = await seedEra2Log(log, 'completed');
+    if (!seeded.ok) return softSkip(seeded.kind, seeded.reason);
+    const last = Math.max(...log.map((e) => e.sequence));
+    const fork = await forkRun(seeded.runId, { mode: 'replay', fromSeq: last });
+    if (fork === null) return softSkip('blocked', 'POST /runs/{runId}:fork unreachable (fetch failed)');
+    expect(fork.status, req('openwop.requirement.0176.v1-events-translated.fork', 'spec/v2/core/replay.md §Forking a v1 run', `a v2 host MUST fork a run created before the cut — POST /runs/{runId}:fork {mode: replay, fromSeq: ${last}} answered ${fork.status}`)).toBe(201);
+    const forkId = (fork.json as { runId?: unknown } | undefined)?.runId;
+    if (typeof forkId !== 'string') return softSkip('blocked', 'the fork answered 201 without a runId — the inherited prefix cannot be read');
+    const res = await pollEvents(forkId);
+    if (res === null || res.status !== 200) return softSkip('blocked', `GET /runs/{forkId}/events/poll answered ${res?.status ?? 'no response'}`);
+    // The fork inherits the translated prefix [0, fromSeq) — the rows below the fork point.
+    const prefix = log.filter((e) => e.sequence < last);
+    assertTranslated('openwop.requirement.0176.v1-events-translated.fork', 'the fork\'s inherited prefix', prefix, eventsOf(res.json).filter((e) => typeof e.sequence === 'number' && e.sequence < last));
+  });
+});

package/src/scenarios/v2-v1-signed-webhook-accepted.test.ts

@@ -0,0 +1,109 @@
+/**
+ * RFC 0176 §D.2 — `v1-signed-webhook-accepted` (suite 2.0.0, target major 2;
+ * gated on `webhooks`, driven through the seams profile).
+ *
+ * A v2 receiver MUST accept a delivery carrying only the `X-openwop-*` header
+ * family under scheme `v1`, verifying the same bytes (`{timestamp}.{rawBody}`
+ * HMAC-SHA256 with the subscription secret); this adds no signature scheme and
+ * per-subscription secrets are unchanged across the cut (`spec/v2/core/webhooks.md`
+ * §Dual emission through the overlap; persistence.md §Everything else a v1 host
+ * persisted; migration row C9.9). The facet's `signatureAlgorithms[]` MUST list
+ * `"v1"` (webhooks.md §Surfaces).
+ *
+ * The receiver under test is the HOST's inbound receiver path — the v2 host as
+ * a subscriber (its trigger bridge, its A2A/MCP peer callbacks) — which the
+ * canonical API does not expose. The seam this scenario drives:
+ *
+ *   POST /conformance/seams/sample/webhooks/receive
+ *     { secret, headers: { "X-openwop-Webhook-Id", "X-openwop-Event-Type", "X-openwop-Timestamp",
+ *                          "X-openwop-Signature", "X-openwop-Signature-Algorithm" }, body }
+ *     → 200 { accepted: boolean, reason? }
+ *
+ * The host runs the delivery through its production verifier with `secret` as
+ * the subscription secret and reports the verdict. Catalogued in
+ * `api/seams-v2.yaml` (`receiveWebhookDelivery`); a host answering 404 / 403 / 405 records `blocked`
+ * naming it. A control delivery with a wrong signature MUST be refused, so a
+ * receiver that accepts everything does not pass.
+ *
+ * @see spec/v2/core/webhooks.md §Dual emission through the overlap
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createHmac } from 'node:crypto';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, gateFamily } from '../lib/v2.js';
+import { seamPath, seamsProfileAdvertised } from '../lib/seams.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/webhooks.md §Dual emission through the overlap';
+const RECEIVE_V1 = '/v1/host/sample/webhooks/receive';
+const RECEIVE = seamPath(RECEIVE_V1);
+
+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; }
+}
+
+/** An `X-openwop-*`-only scheme-v1 delivery over the given bytes. */
+function v1Delivery(secret: string, body: string, tamper = false): { headers: Record<string, string>; body: string } {
+  const timestamp = String(Math.floor(Date.now() / 1000));
+  const sig = createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
+  const signature = tamper ? sig.replace(/^./, (c) => (c === '0' ? '1' : '0')) : sig;
+  return {
+    headers: {
+      'X-openwop-Webhook-Id': 'wh-conformance-v1-signed',
+      'X-openwop-Event-Type': 'run.completed',
+      'X-openwop-Timestamp': timestamp,
+      'X-openwop-Signature': `sha256=${signature}`,
+      'X-openwop-Signature-Algorithm': 'v1',
+    },
+    body,
+  };
+}
+
+type Verdict = { readonly ok: true; readonly accepted: unknown; readonly reason: unknown } | { readonly ok: false; readonly kind: 'blocked'; readonly reason: string };
+
+async function deliver(secret: string, delivery: { headers: Record<string, string>; body: string }): Promise<Verdict> {
+  const res = await http(() => driver.post(RECEIVE_V1, { secret, headers: delivery.headers, body: delivery.body }));
+  if (res === null) return { ok: false, kind: 'blocked', reason: `${RECEIVE} unreachable (fetch failed)` };
+  if (res.status === 404 || res.status === 403 || res.status === 405) return { ok: false, kind: 'blocked', reason: `no inbound receiver seam — ${RECEIVE} answered ${res.status}; the host's v2 receiver path cannot be driven (RFC 0176 falsifiability §D.2)` };
+  if (res.status !== 200 || !res.json || typeof res.json !== 'object') return { ok: false, kind: 'blocked', reason: `${RECEIVE} answered ${res.status} without a 200 { accepted } verdict — the receiver seam contract is not honoured` };
+  const j = res.json as { accepted?: unknown; reason?: unknown };
+  return { ok: true, accepted: j.accepted, reason: j.reason };
+}
+
+describe('RFC 0176 §D.2 — v1-signed-webhook-accepted (gated on webhooks + seams)', () => {
+  it('the webhooks facet lists scheme "v1" — the scheme a v1-signed delivery is verified under', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const webhooks = await gateFamily('webhooks');
+    if (!webhooks) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.webhooks)');
+    const algorithms = webhooks['signatureAlgorithms'];
+    expect(Array.isArray(algorithms), req('openwop.requirement.0176.v1-signed-webhook-accepted.facet', 'spec/v2/core/webhooks.md §Surfaces', 'the webhooks facet is { signatureAlgorithms[] }')).toBe(true);
+    expect(algorithms, req('openwop.requirement.0176.v1-signed-webhook-accepted.facet', 'spec/v2/core/webhooks.md §Surfaces', 'signatureAlgorithms MUST list "v1" — the cut adds no signature scheme (RFC 0176 §D.2)')).toContain('v1');
+  });
+
+  it('the host\'s v2 receiver path accepts an X-openwop-*-only scheme-v1 delivery and refuses a tampered one', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.webhooks)');
+    if (!seamsProfileAdvertised(doc)) return softSkip('blocked', `seams profile not advertised (conformance.seamsProfile !== openwop-conformance-seams-v2) — the host's inbound receiver is reachable only through ${RECEIVE}`);
+    const secret = `conformance-secret-${Date.now().toString(36)}`;
+    const body = JSON.stringify({ runId: 'run-conformance-v1-signed', workspaceId: 'ws-conformance', event: { type: 'run.completed', sequence: 3, payload: { durationMs: 1 } } });
+    const good = await deliver(secret, v1Delivery(secret, body));
+    if (!good.ok) return softSkip(good.kind, good.reason);
+    expect(
+      good.accepted,
+      req('openwop.requirement.0176.v1-signed-webhook-accepted', DOC, `a v2 receiver MUST accept a delivery carrying only the X-openwop-* family under scheme v1, verifying the same bytes — refused${good.reason !== undefined ? ` (${String(good.reason)})` : ''}`),
+    ).toBe(true);
+    const bad = await deliver(secret, v1Delivery(secret, body, true));
+    if (!bad.ok) return softSkip(bad.kind, `${bad.reason} — the acceptance was witnessed, the tamper control was not`);
+    expect(
+      bad.accepted,
+      req('openwop.requirement.0176.v1-signed-webhook-accepted', 'spec/v2/core/webhooks.md §Verification', 'a receiver MUST verify before acting: the same delivery with a wrong X-openwop-Signature MUST be refused (a receiver that accepts everything is not verifying the v1 bytes)'),
+    ).toBe(false);
+  });
+});

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

@@ -0,0 +1,238 @@
+/**
+ * RFC 0173 §B — `webhook-durable-delivery` (suite 2.0.0, target major 2; gated on `webhooks`).
+ *
+ * In v2 durable delivery binds with the `webhooks` surface: a host MUST retry a
+ * failed attempt per its advertised `retryPolicy`, MUST route an exhausted
+ * delivery to the dead-letter sink rather than drop it, and MUST deliver at
+ * least once; best-effort is not a conforming mode and a `3xx` is a failure
+ * (`spec/v2/core/webhooks.md` §Durability; security-defaults.md §Webhook
+ * durability; RFC 0173 §B row C6.3).
+ *
+ * How the receiver is driven: the suite boots its own HTTP receiver (the same
+ * shape `webhook-signed-delivery.test.ts` uses) in a FAILING mode — it answers
+ * `500` to the first N attempts for a delivery key and `204` afterwards — so
+ * the retry is observable as more than one attempt for one
+ * `(webhookId, runId, sequence)` key, and the eventual `204` is the at-least-once
+ * delivery. A second receiver never succeeds, so the retries exhaust; the
+ * dead-letter leg then needs a read surface for the sink, which
+ * `api/v2/openapi.yaml` does not carry — that leg records `blocked` naming it.
+ *
+ * Registration goes through the canonical `POST /webhooks` with the v2 body
+ * (`{ url, events[] }` — no `tenantId`, the v2 body is closed). The SSRF posture
+ * is the one `webhook-signed-delivery.test.ts` documents: a loopback receiver is
+ * rejected by a conforming host unless `OPENWOP_WEBHOOK_RECEIVER_URL` fronts it
+ * with a public https tunnel; a rejection of the loopback URL is `blocked`.
+ *
+ * @see spec/v2/core/webhooks.md §Durability
+ * @see spec/v2/core/security-defaults.md §Webhook durability
+ */
+
+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 { resolveRegistrationUrl } from '../lib/webhook-receiver.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const FIXTURE = 'conformance-noop';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+interface Attempt { readonly key: string; readonly runId: string | null; readonly status: number; readonly at: number }
+
+/**
+ * A receiver that fails the first `failFirst` attempts for each delivery key
+ * (`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[] }> {
+  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, 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;
+  await new Promise<void>((resolve) => server.listen(bindPort, '127.0.0.1', () => resolve()));
+  const addr = server.address();
+  if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
+  return { server, url: `http://127.0.0.1:${addr.port}/`, attempts };
+}
+
+let active: Server | null = null;
+afterEach(async () => {
+  if (active) {
+    const s = active;
+    active = null;
+    await new Promise<void>((resolve) => s.close(() => resolve()));
+  }
+});
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+function fixtureAdvertised(doc: Record<string, unknown>, id: string): boolean {
+  return Array.isArray(doc['fixtures']) && (doc['fixtures'] as unknown[]).includes(id);
+}
+
+async function waitTerminal(runId: string, timeoutMs: number): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const res = await driver.get(`/runs/${encodeURIComponent(runId)}`);
+    const status = res.status === 200 ? String((res.json as { status?: unknown } | null)?.status ?? '') : null;
+    if (status !== null && TERMINAL.has(status)) return status;
+    if (Date.now() > deadline) return status;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+}
+
+async function waitFor(pred: () => boolean, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (pred()) return true;
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return pred();
+}
+
+/** The retry policy the host advertises, where it does (`triggerBridge.retryPolicy` is the only v2 carrier; absent ⇒ null). */
+function advertisedRetryPolicy(doc: Record<string, unknown>): { maxAttempts?: number; backoff?: string } | null {
+  const tb = doc['triggerBridge'];
+  const rp = tb && typeof tb === 'object' ? (tb as { retryPolicy?: unknown }).retryPolicy : undefined;
+  return rp && typeof rp === 'object' ? (rp as { maxAttempts?: number; backoff?: string }) : null;
+}
+
+/** 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'] });
+  if (reg.status === 400 && readErrorCode(reg.json) === 'webhook_url_rejected') {
+    if (!registration.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(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;
+  expect(typeof webhookId, req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Surfaces', 'the 201 body MUST carry `webhookId`')).toBe('string');
+  return { webhookId: webhookId as string };
+}
+
+describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () => {
+  it('a failed attempt is retried and the event is delivered at least once', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.webhooks)');
+    if (!fixtureAdvertised(doc, FIXTURE)) return softSkip('inapplicable', `${FIXTURE} fixture not advertised — no run to deliver`);
+
+    const receiver = await startReceiver(2); // 500, 500, then 204
+    active = receiver.server;
+    const sub = await register(receiver.url);
+    if (sub === null) return softSkip('blocked', 'registration refused (reason recorded above)');
+
+    const create = await driver.post('/runs', { workflowId: FIXTURE });
+    expect(create.status, req('openwop.requirement.0173.webhook-durable-delivery', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await waitTerminal(runId, 10_000);
+
+    const ours = () => receiver.attempts.filter((a) => a.runId === runId);
+    const retried = await waitFor(() => ours().some((a) => a.status === 204), 20_000);
+    const attempts = ours();
+    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'),
+    ).toBeGreaterThan(0);
+    const failedThenSucceeded = attempts.filter((a) => a.status === 500).length;
+    expect(
+      attempts.length,
+      req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Durability', `a 500 from the subscriber MUST be retried — ${failedThenSucceeded} failed attempt(s) were answered and the host made ${attempts.length} attempt(s) in total; one attempt is best-effort delivery, which is not a conforming mode (RFC 0173 §B)`),
+    ).toBeGreaterThan(1);
+    expect(
+      retried,
+      req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Durability', 'at-least-once: after the failing attempts the retry MUST land (the receiver answered 204 to the third attempt for the key)'),
+    ).toBe(true);
+    // Backoff: the retry MUST NOT be a tight loop — consecutive attempts for one
+    // key are spaced. Only asserted when the host advertises a non-`none` backoff.
+    const policy = advertisedRetryPolicy(doc);
+    const byKey = new Map<string, number[]>();
+    for (const a of attempts) byKey.set(a.key, [...(byKey.get(a.key) ?? []), a.at]);
+    if (policy?.backoff !== undefined && policy.backoff !== 'none') {
+      for (const [key, times] of byKey) {
+        for (let i = 1; i < times.length; i++) {
+          expect(
+            times[i]! - times[i - 1]!,
+            req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Durability', `retry attempts for ${key} MUST be spaced by the advertised ${policy.backoff} backoff (attempt ${i + 1} followed attempt ${i} after ${times[i]! - times[i - 1]!}ms)`),
+          ).toBeGreaterThan(0);
+        }
+      }
+    } else {
+      softSkip('inapplicable', 'no advertised retryPolicy.backoff other than none — the spacing leg is not asserted');
+    }
+
+    const del = await driver.delete(`/webhooks/${encodeURIComponent(sub.webhookId)}`);
+    expect(del.status, req('openwop.requirement.0173.webhook-durable-delivery', 'webhooks.md §Surfaces', 'DELETE /webhooks/{webhookId} MUST answer 204')).toBe(204);
+  });
+
+  it('an exhausted delivery is dead-lettered, never dropped', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.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);
+    if (sub === null) return softSkip('blocked', 'registration refused (reason recorded above)');
+
+    const create = await driver.post('/runs', { workflowId: FIXTURE });
+    expect(create.status, req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await waitTerminal(runId, 10_000);
+    const ours = () => receiver.attempts.filter((a) => a.runId === runId);
+    await waitFor(() => ours().length > 1, 20_000);
+    const attempts = ours();
+    expect(
+      attempts.length,
+      req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', 'a delivery that keeps failing MUST be retried before it can be exhausted (one attempt is a drop)'),
+    ).toBeGreaterThan(1);
+    const policy = advertisedRetryPolicy(doc);
+    if (policy?.maxAttempts !== undefined) {
+      // Give the policy time to exhaust, then the host MUST stop.
+      await waitFor(() => ours().length >= policy.maxAttempts!, 20_000);
+      await new Promise((r) => setTimeout(r, 1_000));
+      expect(
+        ours().length,
+        req('openwop.requirement.0173.webhook-durable-delivery.dead-letter', 'webhooks.md §Durability', `retries MUST stop at the advertised retryPolicy.maxAttempts (${policy.maxAttempts}) — exhaustion routes to the dead-letter sink, not to an unbounded loop`),
+      ).toBeLessThanOrEqual(policy.maxAttempts);
+    }
+    await driver.delete(`/webhooks/${encodeURIComponent(sub.webhookId)}`);
+    // The sink itself: webhooks.md §Durability says "inspectable for retentionDays",
+    // but api/v2/openapi.yaml carries no dead-letter read for webhook deliveries
+    // (no GET /webhooks/{webhookId}/dead-letters). Without a normative read the
+    // routing to the sink is not observable from the suite.
+    return softSkip('blocked', 'no normative dead-letter read surface for webhook deliveries in api/v2/openapi.yaml (a GET /webhooks/{webhookId}/dead-letters projection is needed) — exhaustion was observed, routing to the sink was not');
+  });
+});

package/src/scenarios/v2-well-known-one-resource.test.ts

@@ -0,0 +1,129 @@
+/**
+ * RFC 0176 §C — `well-known-one-resource` (suite 2.0.0, target major 2; gated
+ * on a host advertising two majors).
+ *
+ * `/.well-known/openwop` is ONE resource whose representation the RFC 0172
+ * §A.3 header selects: no `OpenWOP-Version` ⇒ the v1 document (with
+ * `protocolVersions[]` additive, RFC 0165 §A) through the overlap;
+ * `OpenWOP-Version: 2.0` ⇒ the closed v2 root (RFC 0169 §A.4). A single fetch
+ * answers the major the client speaks and names the other, so
+ * `protocolVersions[]` is equal in both representations (§C.1). The wrapper
+ * (`capabilities-wrapper`), the dotted mirror (`host-dotted-mirror`),
+ * `Capabilities-Etag` (`capabilities-etag-header`) and the root `profiles[]`
+ * are absent from the v2 representation at the cut (§C.2; RFC 0169 §C.1).
+ *
+ * The two GETs are issued raw (lib/driver.ts always names a version under
+ * target major 2 and the header-less request is the point of leg 1);
+ * `getCapabilities` carries `security: []`, so neither is authenticated.
+ *
+ * @see spec/v2/core/versioning.md (RFC 0172 §A.3 — the header selects)
+ * @see spec/v2/core/capabilities.md §7 (no `profiles[]` at the root)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { loadEnv } from '../lib/env.js';
+import { v2Discovery } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const PATH = '/.well-known/openwop';
+const DOC = 'RFC 0176 §C.1 (one well-known resource)';
+
+interface Representation { readonly status: number; readonly headers: Headers; readonly body: Record<string, unknown> | null }
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+
+async function representation(version: string | null): Promise<Representation | null> {
+  const env = loadEnv();
+  try {
+    const res = await fetch(`${env.baseUrl}${PATH}`, { headers: { Accept: 'application/json', ...(version === null ? {} : { 'OpenWOP-Version': version }) } });
+    const text = await res.text();
+    let body: Record<string, unknown> | null = null;
+    try { const j = JSON.parse(text) as unknown; body = j && typeof j === 'object' && !Array.isArray(j) ? (j as Record<string, unknown>) : null; } catch { body = null; }
+    return { status: res.status, headers: res.headers, body };
+  } catch {
+    return null;
+  }
+}
+
+function versionsOf(doc: Record<string, unknown> | null): string[] | null {
+  const v = doc?.['protocolVersions'];
+  return Array.isArray(v) ? v.map(String) : null;
+}
+
+/** Both majors advertised by the v2 representation, else the reason the scenario does not apply. */
+function twoMajors(doc: Record<string, unknown>): string | null {
+  const versions = versionsOf(doc) ?? [];
+  const majors = new Set(versions.map((v) => v.split('.')[0]));
+  if (majors.has('1') && majors.has('2')) return null;
+  return `the host advertises protocolVersions [${versions.join(', ')}] — one major only; the one-resource rule is witnessable on a dual-advertising host (RFC 0176 falsifiability §C.1 "gated on two majors")`;
+}
+
+describe('RFC 0176 §C — well-known-one-resource (gated on two majors)', () => {
+  it('a header-less GET and an OpenWOP-Version: 2.0 GET are two representations of one path with equal protocolVersions[]', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const gate = twoMajors(doc);
+    if (gate !== null) return softSkip('inapplicable', gate);
+    const v1 = await representation(null);
+    const v2 = await representation('2.0');
+    if (v1 === null || v2 === null) return softSkip('blocked', `${PATH} unreachable (fetch failed) for one of the two representations`);
+    expect(
+      v1.status,
+      req('openwop.requirement.0176.well-known-one-resource', DOC, `the header-less GET selects the v1 representation through the overlap and MUST answer 200 (got ${v1.status}) — no header ⇒ v1 (RFC 0172 §A.3)`),
+    ).toBe(200);
+    expect(
+      v2.status,
+      req('openwop.requirement.0176.well-known-one-resource', DOC, `GET ${PATH} with OpenWOP-Version: 2.0 MUST answer 200 with the closed v2 root (got ${v2.status})`),
+    ).toBe(200);
+    expect(v1.body !== null && v2.body !== null, req('openwop.requirement.0176.well-known-one-resource', DOC, 'both representations MUST be JSON objects')).toBe(true);
+    const v1Versions = versionsOf(v1.body);
+    const v2Versions = versionsOf(v2.body);
+    expect(
+      v1Versions,
+      req('openwop.requirement.0176.well-known-one-resource', DOC, 'the v1 representation MUST carry protocolVersions[] (RFC 0165 §A, additive) — a single fetch names the other major'),
+    ).not.toBeNull();
+    expect(
+      v2Versions,
+      req('openwop.requirement.0176.well-known-one-resource', DOC, 'the v2 representation MUST carry protocolVersions[]'),
+    ).not.toBeNull();
+    expect(
+      [...(v1Versions ?? [])].sort(),
+      req('openwop.requirement.0176.well-known-one-resource', DOC, `protocolVersions[] MUST be equal in both representations — one resource, two renderings (v1: [${(v1Versions ?? []).join(', ')}], v2: [${(v2Versions ?? []).join(', ')}])`),
+    ).toEqual([...(v2Versions ?? [])].sort());
+    // The two are representations, not one document: the v1 rendering is the
+    // wrapped document and the v2 rendering is the closed root, so they differ.
+    expect(
+      JSON.stringify(v1.body) === JSON.stringify(v2.body),
+      req('openwop.requirement.0176.well-known-one-resource', DOC, 'the header MUST select a representation — a host that serves one document for both majors is the charter\'s "per-major sub-objects" the RFC does not adopt (adversarial review 3)'),
+    ).toBe(false);
+  });
+
+  it('the v2 representation carries no `capabilities` wrapper, no dotted `host.*` key, no `profiles[]`, no Capabilities-Etag', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'discovery unreachable');
+    const gate = twoMajors(doc);
+    if (gate !== null) return softSkip('inapplicable', gate);
+    const v2 = await representation('2.0');
+    if (v2 === null || v2.status !== 200 || v2.body === null) return softSkip('blocked', `GET ${PATH} with OpenWOP-Version: 2.0 answered ${v2?.status ?? 'no response'} without a JSON object`);
+    const keys = Object.keys(v2.body);
+    expect(
+      keys.includes('capabilities'),
+      req('openwop.requirement.0176.well-known-one-resource.v2-representation', 'RFC 0176 §C.2', 'the `capabilities` wrapper (deprecation capabilities-wrapper, removalTrigger v2.0-cut) MUST be absent from the v2 representation'),
+    ).toBe(false);
+    expect(
+      keys.filter((k) => k.startsWith('host.')),
+      req('openwop.requirement.0176.well-known-one-resource.v2-representation', 'RFC 0176 §C.2', 'the dotted `host.*` mirror (deprecation host-dotted-mirror) MUST be absent from the v2 representation'),
+    ).toEqual([]);
+    expect(
+      keys.includes('profiles'),
+      req('openwop.requirement.0176.well-known-one-resource.v2-representation', 'spec/v2/core/capabilities.md §7', 'no `profiles[]` exists at the v2 root (RFC 0169 §C.1, row C2.10)'),
+    ).toBe(false);
+    expect(
+      v2.headers.get('capabilities-etag'),
+      req('openwop.requirement.0176.well-known-one-resource.v2-representation', 'RFC 0176 §C.2', 'Capabilities-Etag (deprecation capabilities-etag-header) MUST be absent from the v2 representation — the standard ETag is the probe handle'),
+    ).toBeNull();
+  });
+});