@openwop/openwop-conformance 2.42.7 → 2.42.9

package/src/scenarios/v2-client-version-header.test.ts

@@ -0,0 +1,124 @@
+/**
+ * v2 — `OpenWOP-Client-Version` (suite 2.42.8; RFC 0219;
+ * `spec/v2/core/versioning.md` §1.5 "Client precedence and minClientVersion").
+ *
+ * A client announces the protocol version it implements in
+ * `OpenWOP-Client-Version: <major>.<minor>[.<patch>]`. A host that advertises
+ * `minClientVersion` MAY refuse a client below it with `426
+ * client_version_unsupported`, and MUST NOT refuse anything else on version
+ * grounds. Every leg probes `GET /.well-known/openwop` under
+ * `OpenWOP-Version: 2.0` (the discovery document is not exempt from refusal).
+ *
+ *   floor-comparison     (gated on minClientVersion) `<floor>`, `<floor>.0` and
+ *                        `<floor>.99` are served: equal on major.minor is not
+ *                        below, and the patch never decides.
+ *   malformed-not-refused (gated on a host that refuses `0.0.1` with 426) the
+ *                        malformed values `not-a-version`, `1`, `01.0` and
+ *                        `1.0-rc.1` are treated as absent and served — never
+ *                        426, never 400. A host that serves `0.0.1` does not
+ *                        exercise the refusal, so a served malformed value
+ *                        proves nothing there: `inapplicable`.
+ *   absent-not-refused   a header-less request is never 426 (every host); on a
+ *                        host that refuses `0.0.1` with 426, it is also served.
+ *   no-floor-no-refusal  (hosts advertising NO minClientVersion) `0.0.1` is
+ *                        served, not 426. None of today's certified hosts is in
+ *                        this state, so it records `inapplicable` on each.
+ *
+ * Unwitnessed and recorded in RFC 0219's falsifiability table: a host choosing
+ * a major or a representation from the header, and the header used as an
+ * authentication or authorization input.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/versioning.md §1.5';
+const PATH = '/.well-known/openwop';
+const FLOOR = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/;
+/** Below any floor a host can advertise except `0.0`, which nothing is below. */
+const BELOW = '0.0.1';
+const MALFORMED = ['not-a-version', '1', '01.0', '1.0-rc.1'] as const;
+
+async function discovery(): Promise<Record<string, unknown> | null> {
+  try { return await v2Discovery(); } catch { return null; }
+}
+async function probe(clientVersion: string | null): Promise<OpenWOPResponse | null> {
+  const headers: Record<string, string> = { 'OpenWOP-Version': '2.0' };
+  if (clientVersion !== null) headers['OpenWOP-Client-Version'] = clientVersion;
+  try { return await driver.get(PATH, { authenticated: false, headers }); } catch { return null; }
+}
+const served = (r: OpenWOPResponse): boolean => r.status >= 200 && r.status < 300;
+
+/** The advertised floor, or a skip reason. */
+async function advertisedFloor(): Promise<{ floor: string } | { skip: [kind: 'blocked' | 'inapplicable', reason: string] }> {
+  const doc = await discovery();
+  if (!doc) return { skip: ['blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0'] };
+  const floor = doc['minClientVersion'];
+  if (floor === undefined) return { skip: ['inapplicable', 'the host does not advertise minClientVersion — the floor legs are gated on a host that sets it'] };
+  // The floor's own grammar is v2-min-client-version's row; a floor this leg cannot read compares nothing.
+  if (typeof floor !== 'string' || !FLOOR.test(floor)) return { skip: ['inapplicable', `minClientVersion ${JSON.stringify(floor)} is not <major>.<minor> — judged by v2-min-client-version, nothing to compare here`] };
+  if (floor === '0.0') return { skip: ['inapplicable', 'minClientVersion is 0.0 — no well-formed client version is below it, so no refusal can be provoked'] };
+  return { floor };
+}
+
+/** Gate for the legs that need a host which actually refuses a below-floor client. */
+async function refusingHost(): Promise<{ floor: string } | { skip: [kind: 'blocked' | 'inapplicable', reason: string] }> {
+  const f = await advertisedFloor();
+  if ('skip' in f) return f;
+  const control = await probe(BELOW);
+  if (control === null) return { skip: ['blocked', `GET ${PATH} with OpenWOP-Client-Version: ${BELOW} unreachable (fetch failed)`] };
+  if (served(control)) return { skip: ['inapplicable', `the host advertises minClientVersion ${f.floor} but served a client announcing ${BELOW} (${control.status}) — refusal is a MAY; a served header-less or malformed request distinguishes nothing on a host that refuses nobody`] };
+  if (control.status !== 426) return { skip: ['blocked', `the control (${BELOW}, below minClientVersion ${f.floor}) answered ${control.status} — neither served nor 426; v2-min-client-version records that as a failure, and this leg has no refusal to compare against`] };
+  return f;
+}
+
+describe('v2 OpenWOP-Client-Version (RFC 0219 — versioning.md §1.5)', () => {
+  it('a client at the floor is not below it: equal on major.minor, the patch never decides', async () => {
+    const f = await advertisedFloor();
+    if ('skip' in f) return softSkip(...f.skip);
+    for (const v of [f.floor, `${f.floor}.0`, `${f.floor}.99`]) {
+      const res = await probe(v);
+      if (res === null) return softSkip('blocked', `GET ${PATH} with OpenWOP-Client-Version: ${v} unreachable (fetch failed)`);
+      expect(res.status, req('openwop.requirement.0219.floor-comparison', DOC, `a client announcing ${v} is not below minClientVersion ${f.floor} (major and minor compared as integers; the patch never decides) and MUST be served, not refused (got ${res.status})`)).not.toBe(426);
+      expect(served(res), req('openwop.requirement.0219.floor-comparison', DOC, `a well-formed OpenWOP-Client-Version at the floor MUST NOT make the request fail — ${v} got ${res.status}`)).toBe(true);
+    }
+  });
+
+  it('a malformed OpenWOP-Client-Version is treated as absent: never 426, never 400', async () => {
+    const f = await refusingHost();
+    if ('skip' in f) return softSkip(...f.skip);
+    for (const v of MALFORMED) {
+      const res = await probe(v);
+      if (res === null) return softSkip('blocked', `GET ${PATH} with OpenWOP-Client-Version: ${v} unreachable (fetch failed)`);
+      expect(res.status, req('openwop.requirement.0219.malformed-not-refused', DOC, `a value outside the grammar (${JSON.stringify(v)}) MUST be treated as absent, so it MUST NOT be refused 426 client_version_unsupported (floor ${f.floor})`)).not.toBe(426);
+      expect(res.status, req('openwop.requirement.0219.malformed-not-refused', DOC, `a value outside the grammar (${JSON.stringify(v)}) MUST NOT produce a 400`)).not.toBe(400);
+      expect(served(res), req('openwop.requirement.0219.malformed-not-refused', DOC, `a malformed value is treated as absent and a header-less request is served — ${JSON.stringify(v)} got ${res.status}`)).toBe(true);
+    }
+  });
+
+  it('a request without OpenWOP-Client-Version is served where a below-floor one is refused', async () => {
+    // A 426 to a header-less request is a violation on ANY host, floor or not — probe it before the gate,
+    // because a host that refuses it also refuses the header-less discovery read the gate depends on.
+    const res = await probe(null);
+    if (res === null) return softSkip('blocked', `GET ${PATH} without OpenWOP-Client-Version unreachable (fetch failed)`);
+    expect(res.status, req('openwop.requirement.0219.absent-not-refused', DOC, 'a host MUST NOT answer 426 client_version_unsupported to a request that carries no OpenWOP-Client-Version')).not.toBe(426);
+    const f = await refusingHost();
+    // partial-witness-ok: the header-less request was not refused 426 (asserted above, binding on every host);
+    // that it is SERVED distinguishes something only on a host that refuses a below-floor client.
+    if ('skip' in f) return softSkip(...f.skip);
+    expect(served(res), req('openwop.requirement.0219.absent-not-refused', DOC, `a host MUST NOT refuse a request because it omits OpenWOP-Client-Version (got ${res.status})`)).toBe(true);
+  });
+
+  it('a host that advertises no minClientVersion refuses no client on version grounds', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    if (doc['minClientVersion'] !== undefined) return softSkip('inapplicable', `the host advertises minClientVersion ${JSON.stringify(doc['minClientVersion'])} — this leg is for a host with no floor`);
+    const res = await probe(BELOW);
+    if (res === null) return softSkip('blocked', `GET ${PATH} with OpenWOP-Client-Version: ${BELOW} unreachable (fetch failed)`);
+    expect(res.status, req('openwop.requirement.0219.no-floor-no-refusal', DOC, `a host that advertises no minClientVersion MUST NOT answer 426 client_version_unsupported (a client announcing ${BELOW})`)).not.toBe(426);
+    expect(served(res), req('openwop.requirement.0219.no-floor-no-refusal', DOC, `a well-formed OpenWOP-Client-Version MUST NOT make the request fail on a host with no floor (got ${res.status})`)).toBe(true);
+  });
+});

package/src/scenarios/v2-id-grammar.test.ts

@@ -28,9 +28,11 @@ import { readErrorCode } from '../lib/error-envelope.js';
 import { softSkip } from '../lib/soft-skip.js';
 import { req } from '../lib/requirement-ids.js';
 import { BOUND_ID as RUN_ID } from '../lib/bound-id.js';
+import { scaledTimeoutMs } from '../lib/polling.js';
 
 const DOC = 'spec/v2/core/identity.md §5';
 const NOOP_WORKFLOW_ID = 'conformance-noop';
+const EVENTS_DEADLINE_MS = 20_000;
 const FOREIGN_RUN_ID = 'openwop-conformance-foreign-tenant/foreignopaque0123456789abcdef';
 
 async function discovery(): Promise<Record<string, unknown> | null> {
@@ -63,17 +65,27 @@ describe('v2 id-grammar (RFC 0170 §D.1)', () => {
   it('every id on the run events matches its ids.schema.json kind', async () => {
     const c = await createRun();
     if ('reason' in c) return softSkip('blocked', c.reason);
-    const res = await http(() => driver.get(`/runs/${encodeURIComponent(c.runId)}/events/poll?timeout=1`));
-    if (res === null || res.status !== 200) return softSkip('blocked', `GET /runs/{runId}/events/poll answered ${res?.status ?? 'no response'}`);
-    const events = (res.json as { events?: unknown } | undefined)?.events;
-    if (!Array.isArray(events) || events.length === 0) return softSkip('blocked', 'the poll returned no events for the run just created — nothing to check the eventId / runId / nodeId grammars against');
+    // Poll until the run has recorded an event. A single 1 s poll straight after
+    // the create raced the host's dispatch: a host that queues the run (Cloud
+    // Tasks on MyndHyve) can legitimately have no event yet, and `blocked` is
+    // bundle-fatal (2.42.8; MyndHyve cut 3 on 2.42.7). A host that records
+    // nothing for a noop run inside the scaled deadline is still `blocked`.
+    const deadline = Date.now() + scaledTimeoutMs(EVENTS_DEADLINE_MS);
+    let res: OpenWOPResponse | null = null;
+    let events: unknown;
+    do {
+      res = await http(() => driver.get(`/runs/${encodeURIComponent(c.runId)}/events/poll?timeout=5`));
+      if (res === null || res.status !== 200) return softSkip('blocked', `GET /runs/{runId}/events/poll answered ${res?.status ?? 'no response'}`);
+      events = (res.json as { events?: unknown } | undefined)?.events;
+    } while ((!Array.isArray(events) || events.length === 0) && Date.now() < deadline);
+    if (!Array.isArray(events) || events.length === 0) return softSkip('blocked', `the poll returned no events for the run just created within ${scaledTimeoutMs(EVENTS_DEADLINE_MS)} ms — nothing to check the eventId / runId / nodeId grammars against`);
     const validate = v2Validator('run-event');
     for (const ev of events) {
       const r = validate(ev);
       expect(r.ok, req('openwop.requirement.0170.id-grammar.events', DOC, `every RunEventDoc id (eventId, runId, nodeId, causationId) MUST match its kind — event ${String((ev as { eventId?: unknown }).eventId)} (${r.errors})`)).toBe(true);
       expect((ev as { runId?: unknown }).runId, req('openwop.requirement.0170.id-grammar.events', DOC, 'every event MUST carry the run\'s own runId')).toBe(c.runId);
     }
-  });
+  }, scaledTimeoutMs(EVENTS_DEADLINE_MS) + 15_000);
 
   it('a run id whose tenant segment is not the caller\'s is refused', async () => {
     if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');

package/src/scenarios/v2-min-client-version.test.ts

@@ -9,16 +9,19 @@
  * any advertised floor) is sent; when the host refuses, the refusal MUST be the
  * registered code at its registered status in the closed envelope; a host that
  * exercises the MAY by serving the request records `inapplicable` with that
- * reason. `OpenWOP-Client-Version` is the `OpenWOP-<Name>` header this
- * scenario uses to announce the client; it is not yet declared in
- * `api/v2/openapi.yaml` / `headers.md`.
+ * reason. `OpenWOP-Client-Version` is declared in `api/v2/openapi.yaml` /
+ * `headers.md` and specified in versioning.md §1.5 (RFC 0219), so a non-`2xx`,
+ * non-`426` answer to a well-formed below-floor value is a refusal in an
+ * unregistered form: a failure, not `blocked` (RFC 0219, Unresolved question 4,
+ * decided 2026-09-27). The header's other legs (at-floor, absent, malformed, no
+ * floor) are `v2-client-version-header`.
  */
 
 import { describe, it, expect } from 'vitest';
 import { driver, type OpenWOPResponse } from '../lib/driver.js';
 import { v2Discovery, v2Validator } from '../lib/v2.js';
 import { readErrorCode } from '../lib/error-envelope.js';
-import { blockedDespiteAssertions, softSkip } from '../lib/soft-skip.js';
+import { softSkip } from '../lib/soft-skip.js';
 import { req } from '../lib/requirement-ids.js';
 
 const DOC = 'spec/v2/core/versioning.md §1.5';
@@ -40,21 +43,22 @@ describe('v2 min-client-version (RFC 0172 §A.5 — gated on minClientVersion)',
     expect(typeof floor === 'string' && VERSION.test(floor), req('openwop.requirement.0172.min-client-version', DOC, 'minClientVersion MUST use the <major>.<minor> grammar (axis 15, as axis 1)')).toBe(true);
     const res = await http(() => driver.get('/.well-known/openwop', { authenticated: false, headers: { 'OpenWOP-Client-Version': '0.0.1' } }));
     if (res === null) return softSkip('blocked', 'GET /.well-known/openwop with OpenWOP-Client-Version unreachable (fetch failed)');
-    // unfailable-leg audit wave 2, 2026-09-27: every non-426 answer — including
-    // a 4xx/5xx that refused the client in an unregistered form — recorded
-    // `inapplicable` AFTER the grammar assert, i.e. a partial-witness PASS of
-    // the 426 refusal row. Only a SERVED request (2xx) is the MAY exercised; any
-    // other non-426 answer is `blocked`. Not asserted as a failure:
-    // `OpenWOP-Client-Version` is not yet declared in api/v2/openapi.yaml /
-    // headers.md, so a non-2xx here is not provably a version refusal.
-    if (res.status !== 426 && (res.status < 200 || res.status >= 300)) {
-      return blockedDespiteAssertions(`the host advertises minClientVersion ${String(floor)} and answered ${res.status} to a client announcing 0.0.1 — neither served (the MAY) nor refused with the registered 426 client_version_unsupported; the refusal form was not observed`);
-    }
+    // RFC 0219 Q4 (2026-09-27): the header is declared, so a host that answers a
+    // well-formed below-floor value with anything but 2xx (the MAY: served) or
+    // 426 client_version_unsupported refuses a declared header in an
+    // unregistered form. That is a failure. Before RFC 0219 it recorded `blocked`.
+    expect(res.status === 426 || (res.status >= 200 && res.status < 300), req('openwop.requirement.0172.min-client-version', DOC, `a client announcing 0.0.1 below minClientVersion ${String(floor)} MUST be served or refused with 426 client_version_unsupported — the host answered ${res.status}`)).toBe(true);
     // partial-witness-ok: the minClientVersion grammar MUST was asserted above; refusing a
     // below-floor client is a MAY and this host served it, so the 426 shape binds nothing.
     if (res.status !== 426) return softSkip('inapplicable', `the host advertises minClientVersion ${String(floor)} but served a client announcing 0.0.1 (${res.status}) — refusal is a MAY; nothing further is observable`);
     expect(readErrorCode(res.json), req('openwop.requirement.0172.min-client-version', DOC, 'a 426 refusal MUST carry client_version_unsupported')).toBe('client_version_unsupported');
     const r = v2Validator('error-envelope')(res.json);
     expect(r.ok, req('openwop.requirement.0172.min-client-version', 'spec/v2/core/errors.md §The envelope', `the refusal MUST be the closed error envelope (${r.errors})`)).toBe(true);
+    // RFC 0219 Q5: details.minClientVersion is OPTIONAL; when a host sends it, it names the floor
+    // (errors.json registers its grammar, which the envelope validator above already checked).
+    const details = (res.json as { details?: { minClientVersion?: unknown } } | null)?.details;
+    if (details && details.minClientVersion !== undefined) {
+      expect(details.minClientVersion, req('openwop.requirement.0172.min-client-version', DOC, `a refusal's details.minClientVersion MUST name the advertised floor ${String(floor)}`)).toBe(floor);
+    }
   });
 });

package/src/scenarios/v2-preferred-version-default.test.ts

@@ -8,7 +8,8 @@
  * served `preferredVersion`'s major, so a header-less `GET /.well-known/openwop`
  * is the `preferredVersion` representation and its `OpenWOP-Version` response
  * header names that major. The header-less fetch bypasses the driver (which
- * stamps `OpenWOP-Version: 2.0` under target major 2).
+ * stamps `OpenWOP-Version: 2.0` under target major 2). Any OTHER unversioned path
+ * is the v2 surface (§1.2), so a header-less request there is served major 2.
  */
 
 import { describe, it, expect } from 'vitest';
@@ -67,6 +68,23 @@ describe('v2 preferred-version-default (RFC 0172 §A.1, §A.3)', () => {
       expect(Array.isArray(body?.['protocolVersions']) && typeof body?.['preferredVersion'] === 'string', req('openwop.requirement.0172.preferred-version-default.headerless', 'spec/v2/core/capabilities.md §1', 'the v1 representation MUST carry protocolVersions[] and preferredVersion additively so a single fetch names the other major')).toBe(true);
     }
   });
+  it('a header-less request on any other unversioned path is served major 2', async () => {
+    const doc = await discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');
+    // versioning.md §1.2/§1.3: an unversioned operation path is the v2 surface, so the
+    // header-less default (preferredVersion) applies to /.well-known/openwop only. Any
+    // answer carries OpenWOP-Version (§1.4), so an unknown run id is enough to read it.
+    const path = `/runs/openwop-conformance~2F${'h'.repeat(22)}`;
+    let version: string | null = null;
+    try {
+      const res = await fetch(`${loadEnv().baseUrl}${path}`, { headers: { Accept: 'application/json', Authorization: `Bearer ${loadEnv().apiKey}` } });
+      await res.text();
+      version = res.headers.get('openwop-version');
+    } catch {
+      return softSkip('blocked', `header-less GET ${path} unreachable (fetch failed)`);
+    }
+    expect(version?.trim().split('.')[0], req('openwop.requirement.0172.preferred-version-default.unversioned-is-v2', 'spec/v2/core/versioning.md §1.2, §1.3', `a header-less request on an unversioned operation path MUST be served major 2 and say so in OpenWOP-Version — the preferredVersion default is for /.well-known/openwop only (got ${JSON.stringify(version)})`)).toBe('2');
+  });
   it('through the overlap preferredVersion names a 1.x member', async () => {
     const doc = await discovery();
     if (!doc) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0');

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

@@ -234,6 +234,11 @@ describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versio
     expect(owner !== null, req(ID, DOC, 'a major-2 run.started payload MUST carry the owner echo { tenant, subject } (identity.md §1; run-event-payloads runStarted.owner requires both)')).toBe(true);
     expect(Object.keys(owner ?? {}).filter((k) => k === 'principal' || k === 'principalKind'), req(ID, DOC, 'a major-2 owner echo MUST NOT carry the v1 keys principal / principalKind — that is the fan-out forwarding the in-process dialect instead of projecting')).toEqual([]);
     expect(typeof owner?.['tenant'] === 'string' && owner?.['subject'] !== undefined, req(ID, DOC, 'a major-2 owner echo carries tenant and subject')).toBe(true);
+    // webhooks.md §Delivery: `workspaceId` is present exactly when RunSnapshot.owner.workspace is,
+    // equal to it, and a host MUST NOT substitute its tenant id (or any placeholder) for an absent one.
+    const ws = owner?.['workspace'];
+    const sent = (d.envelope as Record<string, unknown>)['workspaceId'];
+    expect(ws === undefined ? sent === undefined : sent === ws, req(ID, DOC, `workspaceId MUST be present exactly when owner.workspace is, and equal to it — nothing is substituted for an absent workspace (owner.workspace ${JSON.stringify(ws)}, delivered workspaceId ${JSON.stringify(sent)})`)).toBe(true);
   });
 
   it('a major-1 subscriber still receives the v1 rendering — the v1 wire does not move mid-overlap', async () => {

package/src/scenarios/v2-webhook-generated-secret.test.ts

@@ -0,0 +1,76 @@
+/**
+ * RFC 0221 — a secret the host generates is returned once (`spec/v2/core/webhooks.md`
+ * §Surfaces; suite 2.42.8, target major 2; gated on the `webhooks` family and the
+ * `conformance-noop` fixture).
+ *
+ * `registerWebhook` makes `secret` optional. When the request omits it, the host
+ * MUST generate one and return it in the `201` as `secret`, the only time it
+ * appears on the wire, and every delivery to that subscription MUST verify under
+ * it (`OpenWOP-Signature`, scheme `v1`). When the request supplies a secret, the
+ * `201` MUST NOT echo it (RFC 0201 §B.6, now for every subscription).
+ *
+ * How it FAILS: a `201` without `secret` for a secret-less registration (the
+ * subscriber can never verify a delivery); a returned secret the deliveries are
+ * not signed with; a `201` that echoes a supplied secret.
+ *
+ * @see spec/v2/core/webhooks.md §Surfaces
+ * @see RFCS/0221-generated-webhook-secret-returned-once.md
+ */
+
+import { afterEach, describe, it, expect } from 'vitest';
+import { createHmac } from 'node:crypto';
+import { req } from '../lib/requirement-ids.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { v2Discovery, gateFamily } from '../lib/v2.js';
+import { hitHeader, startModalReceiver, type ModalHit } from '../lib/webhook-receiver.js';
+import { SW_FIXTURE, deliveriesFor, driveRun, loopbackRefusal, registerSw, unregisterAllSw, waitFor } from '../lib/standard-webhooks.js';
+
+const ID = 'openwop.requirement.0221.generated-secret-returned';
+const SPEC = 'RFC 0221 · webhooks.md §Surfaces';
+
+let closeReceiver: (() => Promise<void>) | null = null;
+afterEach(async () => {
+  await unregisterAllSw();
+  if (closeReceiver) { const c = closeReceiver; closeReceiver = null; await c(); }
+});
+
+function v1SignedBy(secret: string, h: ModalHit): boolean {
+  const ts = hitHeader(h, 'openwop-timestamp');
+  return ts !== undefined && hitHeader(h, 'openwop-signature') === `sha256=${createHmac('sha256', secret).update(`${ts}.${h.body}`, 'utf8').digest('hex')}`;
+}
+
+describe('RFC 0221 — a host-generated webhook secret is returned once', () => {
+  it('a secret-less registration returns the generated secret, and deliveries verify under it; a supplied secret is never echoed', async () => {
+    let doc: Record<string, unknown> | null = null;
+    try { doc = await v2Discovery(); } catch { doc = null; }
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable');
+    if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.webhooks)');
+    const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+    if (!fixtures.includes(SW_FIXTURE)) return softSkip('inapplicable', `${SW_FIXTURE} fixture not advertised — no run to deliver`);
+
+    const rx = await startModalReceiver();
+    closeReceiver = rx.close;
+    const target = rx.urlFor('no-echo');
+    const reg = await registerSw({ url: target.url, events: ['run.completed'] });
+    const refused = loopbackRefusal(reg, target.tunnelled);
+    if (refused) return softSkip('blocked', refused);
+    if (reg.status !== 201) return softSkip('blocked', `registerWebhook answered ${reg.status} ${readErrorCode(reg.json) ?? ''} — webhooks.md §Surfaces owns that contract`);
+
+    const body = reg.json as { webhookId: string; secret?: unknown };
+    expect(typeof body.secret === 'string' && body.secret.length > 0, req(ID, SPEC, 'a registration that omits secret MUST get the host-generated secret back in the 201 as a non-empty string')).toBe(true);
+    const secret = body.secret as string;
+
+    const run = await driveRun();
+    expect(run.status, req(ID, 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    await waitFor(() => deliveriesFor(rx.hits, body.webhookId, run.runId).length > 0, 15_000);
+    const delivery = deliveriesFor(rx.hits, body.webhookId, run.runId)[0];
+    expect(delivery, req(ID, 'webhooks.md §Durability', 'the subscription MUST receive the run.completed delivery')).toBeDefined();
+    expect(v1SignedBy(secret, delivery!), req(ID, SPEC, 'the delivery MUST verify (OpenWOP-Signature, scheme v1) under the secret the 201 returned')).toBe(true);
+
+    const supplied = `conformance-${'s'.repeat(24)}`;
+    const own = await registerSw({ url: rx.urlFor('no-echo').url, events: ['run.completed'], secret: supplied });
+    expect(own.status, req(ID, SPEC, `a registration with a supplied secret MUST answer 201 (got ${own.status} ${readErrorCode(own.json) ?? ''})`)).toBe(201);
+    expect(own.text.includes(supplied) || (own.json as { secret?: unknown }).secret !== undefined, req(ID, 'RFC 0221 · RFC 0201 §B.6', 'the 201 MUST NOT echo a supplied secret')).toBe(false);
+  });
+});