@openwop/openwop-conformance 2.0.0-rc.9 → 2.0.1

package/src/scenarios/v2-stream-mode-refusal.test.ts

@@ -0,0 +1,118 @@
+/**
+ * `spec/v2/core/events.md` §The events channel — `streamMode` is one pattern,
+ * refused with `400 unsupported_stream_mode`, validated before content
+ * negotiation; `bufferMs` batches (suite 2.0.0, target major 2; unaided; one
+ * run created).
+ *
+ * Legs:
+ *   1. `?streamMode=bogus` → 400 `unsupported_stream_mode`, `details.supported`
+ *      a non-empty array of individual modes; the same request with
+ *      `Accept: application/json` → still 400, never 406 (validation runs
+ *      before content negotiation; the only v2 406 is a version mismatch and
+ *      this request names a listed major); `?streamMode=updates,values` → 400
+ *      (`values` never combines); a mode absent from `supported`, if any → 400.
+ *   2. control: `?streamMode=updates` → 200 `text/event-stream` with ≥1 frame
+ *      (a host that answers 400 to every mode fails here; `updates` is a MUST).
+ *   3. `?bufferMs=200` → at least one `event: batch` frame whose `data:` is an
+ *      array of RunEventDoc, and the flattened frames equal the log in order;
+ *      without `bufferMs` no frame is `batch` (the control). "Every frame is
+ *      batch" is deliberately NOT asserted: a consumer MUST tolerate an
+ *      unbatched frame beside a one-element batch (§SSE frames).
+ *
+ * @see spec/v2/core/events.md §The events channel, §SSE frames
+ * @see spec/v2/errors.json unsupported_stream_mode
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { subscribe, type SseEvent } from '../lib/sse.js';
+import { v2Discovery } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0171.stream-mode-refusal';
+const DOC = 'spec/v2/core/events.md §The events channel';
+const NOOP = 'conformance-noop';
+const MODES = ['values', 'updates', 'messages', 'debug'];
+const V2 = { 'OpenWOP-Version': '2.0' };
+
+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; } }
+const enc = (id: string): string => encodeURIComponent(id);
+
+async function createSettled(): Promise<{ runId: string } | { reason: string }> {
+  const res = await http(() => driver.post('/runs', { workflowId: NOOP }));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | null)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs answered ${res.status} ${readErrorCode(res.json) ?? ''}`.trim() };
+  const t0 = Date.now();
+  while (Date.now() - t0 < 10_000) {
+    const s = await http(() => driver.get(`/runs/${enc(runId)}`));
+    if (s?.status === 200 && ['completed', 'failed', 'cancelled'].includes(String((s.json as { status?: unknown }).status))) return { runId };
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return { reason: 'the noop run did not settle within 10 s' };
+}
+
+/** The events a frame carries: a batch frame's array flattened, a plain frame's one document. */
+function docsOf(frame: SseEvent): Array<Record<string, unknown>> {
+  try { const p = JSON.parse(frame.data) as unknown; return (Array.isArray(p) ? p : [p]).filter((x): x is Record<string, unknown> => !!x && typeof x === 'object'); } catch { return []; }
+}
+
+describe('v2 stream-mode-refusal (events.md §The events channel)', () => {
+  it('a value outside the pattern, a forbidden combination, and an unimplemented mode are refused 400 unsupported_stream_mode with details.supported — before content negotiation', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const c = await createSettled(); if ('reason' in c) return softSkip('blocked', c.reason);
+    const path = `/runs/${enc(c.runId)}/events`;
+    const bogus = await http(() => driver.get(`${path}?streamMode=bogus`, { headers: { Accept: 'text/event-stream' } }));
+    if (bogus === null) return softSkip('blocked', 'GET /runs/{runId}/events unreachable (fetch failed)');
+    if (bogus.status === 404) return softSkip('blocked', 'GET /runs/{runId}/events answered 404 — streamRunEvents is a core operation (runs.md §Surface) and is not mounted');
+    expect(bogus.status, req(ID, DOC, `a streamMode outside the pattern MUST be refused 400 — got ${bogus.status}`)).toBe(400);
+    expect(readErrorCode(bogus.json), req(ID, DOC, 'the refusal MUST be unsupported_stream_mode')).toBe('unsupported_stream_mode');
+    const supported = (bogus.json as { details?: { supported?: unknown } } | null)?.details?.supported;
+    expect(Array.isArray(supported) && supported.length > 0 && supported.every((m) => MODES.includes(String(m))), req(ID, DOC, `details.supported MUST list each individual mode the host serves (got ${JSON.stringify(supported)})`)).toBe(true);
+    expect((supported as string[]).includes('updates'), req(ID, DOC, 'a host MUST implement updates, so supported MUST list it')).toBe(true);
+
+    const negotiated = await http(() => driver.get(`${path}?streamMode=bogus`, { headers: { Accept: 'application/json' } }));
+    expect(negotiated?.status ?? null, req(ID, DOC, `validation MUST run before any content negotiation: a bogus streamMode with Accept: application/json is still 400 unsupported_stream_mode, never 406 (the only v2 406 is a version mismatch and this request names a listed major) — got ${negotiated?.status ?? 'no response'}`)).toBe(400);
+
+    const combo = await http(() => driver.get(`${path}?streamMode=updates,values`, { headers: { Accept: 'text/event-stream' } }));
+    expect(combo?.status ?? null, req(ID, DOC, `values never combines: streamMode=updates,values is outside the pattern and MUST be refused 400 — got ${combo?.status ?? 'no response'}`)).toBe(400);
+    expect(readErrorCode(combo?.json), req(ID, DOC, 'the refusal MUST be unsupported_stream_mode')).toBe('unsupported_stream_mode');
+
+    // The unimplemented-mode leg has something to request only when a mode is
+    // absent from details.supported; a host serving all four has no such mode,
+    // and the three refusals above are its witness.
+    const missing = MODES.find((m) => !(supported as string[]).includes(m));
+    if (missing !== undefined) {
+      const unimpl = await http(() => driver.get(`${path}?streamMode=${missing}`, { headers: { Accept: 'text/event-stream' } }));
+      expect(unimpl?.status ?? null, req(ID, DOC, `a mode the host does not implement (${missing}, absent from details.supported) MUST be refused 400 — got ${unimpl?.status ?? 'no response'}`)).toBe(400);
+      expect(readErrorCode(unimpl?.json), req(ID, DOC, 'the refusal MUST be unsupported_stream_mode')).toBe('unsupported_stream_mode');
+    }
+  }, 30_000);
+
+  it('updates streams 200 text/event-stream with frames; bufferMs yields at least one batch frame whose data is an array and loses nothing; without bufferMs no frame is batch', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const c = await createSettled(); if ('reason' in c) return softSkip('blocked', c.reason);
+    const path = `/runs/${enc(c.runId)}/events`;
+    const plain = await subscribe(`${path}?streamMode=updates`, { timeoutMs: 8_000, extraHeaders: V2 });
+    if (plain.status === 404) return softSkip('blocked', 'GET /runs/{runId}/events answered 404 — not mounted');
+    expect(plain.status, req(ID, DOC, `updates is a MUST: streamMode=updates MUST answer 200 — got ${plain.status} (the control for the refusals: a host answering 400 to every mode fails here)`)).toBe(200);
+    expect(plain.events.length, req(ID, 'spec/v2/core/events.md §SSE frames', 'the completed run\'s log MUST stream as at least one frame before the server closes')).toBeGreaterThan(0);
+    expect(plain.closedBy, req(ID, 'spec/v2/core/events.md §SSE frames', `the host MUST close after the terminal event (closed by ${plain.closedBy})`)).toBe('server');
+    expect(plain.events.some((f) => f.event === 'batch'), req(ID, 'spec/v2/core/events.md §SSE frames', 'without bufferMs no frame is a batch (the control for the batch leg)')).toBe(false);
+    const plainDocs = plain.events.flatMap(docsOf).map((d) => d['sequence']);
+
+    const buffered = await subscribe(`${path}?streamMode=updates&bufferMs=200`, { timeoutMs: 8_000, extraHeaders: V2 });
+    expect(buffered.status, req(ID, 'spec/v2/core/events.md §SSE frames', `streamMode=updates&bufferMs=200 MUST answer 200 — got ${buffered.status}`)).toBe(200);
+    const batches = buffered.events.filter((f) => f.event === 'batch');
+    expect(batches.length, req(ID, 'spec/v2/core/events.md §SSE frames', `with bufferMs the host accumulates events into event: batch frames — none seen among ${buffered.events.length} frame(s) (${[...new Set(buffered.events.map((f) => f.event))].join(', ')})`)).toBeGreaterThan(0);
+    for (const b of batches) {
+      let parsed: unknown; try { parsed = JSON.parse(b.data); } catch { parsed = undefined; }
+      expect(Array.isArray(parsed), req(ID, 'spec/v2/core/events.md §SSE frames', 'a batch frame\'s data MUST be an array of RunEventDoc')).toBe(true);
+    }
+    const bufferedDocs = buffered.events.flatMap(docsOf).map((d) => d['sequence']);
+    expect(bufferedDocs, req(ID, 'spec/v2/core/events.md §SSE frames', 'batching MUST NOT lose or reorder events: the flattened buffered stream equals the unbuffered log (a one-element batch and an unbatched frame are both tolerated)')).toEqual(plainDocs);
+  }, 30_000);
+});

package/src/scenarios/v2-stream-sse-projection.test.ts

@@ -0,0 +1,79 @@
+/**
+ * `spec/v2/core/events.md` §SSE frames + `identity.md` §5 — every `data:` frame
+ * on the major-2 run stream names the run by its tenant-bound id (suite 2.0.0,
+ * target major 2; unaided).
+ *
+ * This scenario exists because both production hosts shipped the same defect
+ * and the suite could not see it. Each built one projection seam for the
+ * tenant-bound `runId` and each found an emitter outside it on the stream
+ * path: one host's SSE route had three `res.write` sites and no per-frame
+ * projector at all; the other's per-frame path projected while its `batch`
+ * flush wrote the raw array. Sixteen green mount tests on one host all used
+ * `res.json` handlers. Of the 56 `v2-*` files, none read a stream frame —
+ * `grep -E '^v2-.*(sse|stream)'` was empty — so both defects were invisible to
+ * the suite by construction and were found by a live witness and by a peer's
+ * report. A tier-1 host asked for this file by name.
+ *
+ * The assertion is one line: every frame's `runId` is the bound id the create
+ * returned. It is asserted per frame rather than on the first, because the
+ * batch-flush variant projects the first frame and not the rest.
+ *
+ * @see spec/v2/core/events.md §SSE frames
+ * @see spec/v2/core/identity.md §5
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { streamEvents } from '../lib/era2-seed.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0171.stream-sse-projection';
+const DOC = 'spec/v2/core/events.md §SSE frames';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+const RUN_ID = /^[A-Za-z0-9._~-]{1,128}\/[A-Za-z0-9._~-]{16,128}$/;
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+async function createRun(): Promise<{ runId: string } | { reason: string }> {
+  try { if (!(await v2Discovery())) return { reason: 'v2 discovery unreachable' }; } catch { return { reason: 'v2 discovery unreachable' }; }
+  const res = await http(() => driver.post('/runs', { workflowId: NOOP_WORKFLOW_ID }));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | undefined)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {workflowId: ${NOOP_WORKFLOW_ID}} answered ${res.status} ${readErrorCode(res.json) ?? ''} — the smallest valid create was refused (fixture not seeded?)`.trim() };
+  return { runId };
+}
+
+describe('v2 stream-sse-projection (events.md §SSE frames)', () => {
+  it('every data: frame on the major-2 stream carries the tenant-bound runId of the run it belongs to', async () => {
+    const c = await createRun();
+    if ('reason' in c) return softSkip('blocked', c.reason);
+    expect(RUN_ID.test(c.runId), req(ID, 'spec/v2/core/identity.md §5', `the created runId MUST be tenant-bound before the stream can be held to it (got ${c.runId})`)).toBe(true);
+
+    const s = await streamEvents(c.runId);
+    if (s === null) return softSkip('blocked', 'GET /runs/{runId}/events (SSE, OpenWOP-Version: 2.0) unreachable (fetch failed)');
+    if (s.status !== 200) return softSkip('blocked', `GET /runs/{runId}/events (SSE) answered ${s.status} for the run just created`);
+    if (s.events.length === 0) return softSkip('blocked', 'the stream delivered no data: frames within the window — nothing to hold to the grammar');
+
+    const validate = v2Validator('run-event');
+    let i = 0;
+    for (const ev of s.events) {
+      i += 1;
+      const rid = (ev as { runId?: unknown }).runId;
+      expect(
+        typeof rid === 'string' && RUN_ID.test(rid),
+        req(ID, DOC, `frame ${i} (${String((ev as { type?: unknown }).type)}): data.runId MUST be tenant-bound <tenantId>/<opaque> (identity.md §5) — a stream frame is a rendering of the run event and every rendering of a v2 runId uses the same grammar; a bare storage id here is the projection seam missing the stream path (got ${JSON.stringify(rid)})`),
+      ).toBe(true);
+      expect(
+        rid,
+        req(ID, DOC, `frame ${i}: data.runId MUST be the run's own bound id — asserted on EVERY frame, not the first, because a batch flush that skips the per-frame projector projects frame 1 and not the rest`),
+      ).toBe(c.runId);
+      const r = validate(ev);
+      expect(r.ok, req(ID, DOC, `frame ${i}: data MUST be a valid RunEventDoc (run-event.schema.json) — ${r.errors}`)).toBe(true);
+    }
+  });
+});

package/src/scenarios/v2-subject-link-record.test.ts

@@ -56,7 +56,7 @@ async function readLink(externalId: string): Promise<Record<string, unknown> | n
 async function form(): Promise<Formed> {
   const doc = await discovery();
   if (!doc) return { kind: 'blocked', reason: 'v2 discovery unreachable — /.well-known/openwop did not answer 200 with a JSON body under OpenWOP-Version: 2.0' };
-  if (!seamsProfileAdvertised(doc)) return { kind: 'blocked', reason: 'seams profile not advertised (conformance.seamsProfile !== openwop-conformance-seams-v2) — the link record is seam-gated' };
+  if (!seamsProfileAdvertised(doc)) return { kind: 'inapplicable', reason: 'seams profile not advertised (conformance.seamsProfile !== openwop-conformance-seams-v2) — the link record is seam-gated' };
   const auth = await familyAdvertised('auth');
   const lanes = new Set((Array.isArray(auth?.['lanes']) ? (auth['lanes'] as Array<Record<string, unknown>>) : []).map((l) => String(l['lane'])));
   if (!(lanes.has('saml') && lanes.has('scim'))) return { kind: 'inapplicable', reason: 'the host does not advertise both the saml and scim lanes — advertising both is what implies the linking contract (row C2.5)' };

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

@@ -90,7 +90,7 @@ describe('RFC 0176 §D.2 — v1-signed-webhook-accepted (gated on webhooks + sea
     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}`);
+    if (!seamsProfileAdvertised(doc)) return softSkip('inapplicable', `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));

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

@@ -117,11 +117,62 @@ async function waitFor(pred: () => boolean, timeoutMs: number): Promise<boolean>
   return pred();
 }
 
-/** The retry policy the host advertises, where it does (`triggerBridge.retryPolicy` is the only v2 carrier; absent ⇒ null). */
+/**
+ * The retry policy the host advertises for WEBHOOK delivery.
+ *
+ * 2.0.1: this read the WRONG FIELD. Its docstring claimed
+ * `triggerBridge.retryPolicy` was "the only v2 carrier", but
+ * `spec/v2/facets/webhooks.schema.json` says the opposite in as many words:
+ * "retryPolicy is the v2 carrier of the delivery obligation (was
+ * triggerBridge.retryPolicy at v1)", and the field's own description adds
+ * "The webhooks family carries it at v2; `triggerBridge.retryPolicy` is the
+ * v1 carrier and stays through the overlap."
+ *
+ * So a host that correctly advertises the v2 carrier had its policy read as
+ * `null`, and a host still on the v1 carrier was measured against a policy
+ * belonging to a DIFFERENT SUBSYSTEM — the trigger-bridge state machine,
+ * whose delivery budget need not equal the webhook one. A tier-1 host
+ * reported exactly that: 8 on the trigger bridge, 5 on webhook delivery,
+ * and no way to be honest about both under a single borrowed field.
+ *
+ * `webhooks.retryPolicy` first, `triggerBridge.retryPolicy` second for the
+ * v1 overlap the schema explicitly preserves.
+ */
 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;
+  const read = (holder: unknown): { maxAttempts?: number; backoff?: string } | null => {
+    const rp = holder && typeof holder === 'object' ? (holder as { retryPolicy?: unknown }).retryPolicy : undefined;
+    return rp && typeof rp === 'object' ? (rp as { maxAttempts?: number; backoff?: string }) : null;
+  };
+  return read(doc['webhooks']) ?? read(doc['triggerBridge']);
+}
+
+/**
+ * How long to wait for a retry, derived from what the host ADVERTISED.
+ *
+ * 2.0.1: this was a hard 20 s, and a host whose first backoff is deliberately
+ * slower than that was recorded `executed-fail` on a core-standard floor row
+ * for being durable. Measured on a tier-1 host: Cloud Tasks `minBackoff: 30s`,
+ * the retry lands at t+30 s, the window closed at t+20 s, and the assertion
+ * said "a 500 MUST be retried" about a host that retried. 30 s is not an
+ * unusual first backoff.
+ *
+ * That is rc.67's poll-cursor defect one file over and DETERMINISTIC rather
+ * than flaky: the instrument's own window, attributed to the host. A scenario
+ * must not blame a host for a deadline the scenario chose.
+ *
+ * The floor stays 20 s so a host that advertises nothing is measured exactly
+ * as before; an advertised `exponential`/`fixed` backoff widens it to 90 s,
+ * which covers a 30 s first attempt with room for the second. The cap is
+ * deliberate: unbounded waiting would let a host that never retries hold the
+ * suite open instead of failing.
+ */
+const RETRY_WAIT_FLOOR_MS = 20_000;
+const RETRY_WAIT_CAP_MS = 90_000;
+function retryWaitMs(doc: Record<string, unknown>): number {
+  const policy = advertisedRetryPolicy(doc);
+  if (policy === null) return RETRY_WAIT_FLOOR_MS;
+  const backoff = String(policy.backoff ?? '');
+  return backoff === 'exponential' || backoff === 'fixed' ? RETRY_WAIT_CAP_MS : RETRY_WAIT_FLOOR_MS;
 }
 
 /** Register the suite receiver; null (with a note) when the host's SSRF guard refuses a loopback URL. */
@@ -159,7 +210,7 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     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 retried = await waitFor(() => ours().some((a) => a.status === 204), retryWaitMs(doc));
     const attempts = ours();
     expect(
       attempts.length,
@@ -212,7 +263,7 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     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);
+    await waitFor(() => ours().length > 1, retryWaitMs(doc));
     const attempts = ours();
     expect(
       attempts.length,
@@ -221,7 +272,7 @@ describe('RFC 0173 §B — webhook-durable-delivery (gated on webhooks)', () =>
     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 waitFor(() => ours().length >= policy.maxAttempts!, retryWaitMs(doc));
       await new Promise((r) => setTimeout(r, 1_000));
       expect(
         ours().length,

package/src/scenarios/version-negotiation.test.ts

@@ -7,9 +7,31 @@
  *
  * What we CAN test cheaply:
  *   1. Server advertises a `protocolVersion` in `Capabilities`.
- *   2. The four version axes (`engineVersion`,
- *      `eventLogSchemaVersion`, per-event `schemaVersion`,
- *      `pinnedVersions`) appear where the spec says they should.
+ *   2. `protocolVersion` is advertised, and every event carries the six
+ *      required `RunEventDoc` fields.
+ *
+ *   This file previously claimed to check "the four version axes
+ *   (`engineVersion`, `eventLogSchemaVersion`, per-event `schemaVersion`,
+ *   `pinnedVersions`)". IT DID NOT. `protocolVersion` was the only axis
+ *   asserted, and across all 444 v1 scenario files the sole occurrence of the
+ *   identifier `eventLogSchemaVersion` was that sentence — a docstring
+ *   describing a check that did not exist. A comment claiming coverage is
+ *   worse than no comment: it answers "is this tested?" for anyone who greps,
+ *   and answers it wrongly.
+ *
+ *   Current state of the four, stated so this comment can be checked rather
+ *   than trusted: `eventLogSchemaVersion` and `engineVersion` are witnessed by
+ *   `era-key-stamped-v1.test.ts` (both are run-document `MUST`s in
+ *   `version-negotiation.md` §Stamping, and both were unasserted until
+ *   2026-09-04). Per-event `schemaVersion` and `pinnedVersions` are **not
+ *   asserted here and carry no `MUST` in that document** — checked, rather
+ *   than assumed to be a gap.
+ *
+ *   This paragraph was itself wrong for one release candidate: it said
+ *   `engineVersion` "remains UNASSERTED" after the leg asserting it had
+ *   landed. A docstring that describes coverage goes stale the moment
+ *   coverage changes, which is the argument for stating what can be
+ *   re-derived rather than what was true once.
  *   3. Forward-compat read: events carrying an UNKNOWN
  *      `schemaVersion` SHOULD still be readable via the events/poll
  *      endpoint without 5xx (best-effort fold per

package/src/setup.ts

@@ -25,7 +25,7 @@
  * `it` here; vitest treats setupFiles differently from scenario files.
  */
 
-import { setAdvertisedFixtures } from './lib/fixtures.js';
+import { setAdvertisedFixtures, setDiscoveryUnreadable } from './lib/fixtures.js';
 import { setMultiAgentCapabilities } from './lib/multi-agent-capabilities.js';
 import { OtelCollector, setCollector } from './lib/otel-collector.js';
 import { McpFakeServer, setMcpFakeServer } from './lib/mcp-fake-server.js';
@@ -35,19 +35,23 @@ import { basename, join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { PKG_ROOT_PATH } from './lib/paths.js';
 import { recordRequirement, hasRequirement, journalLength, journalSince } from './lib/requirement-ledger.js';
-import { requirementIdForFile, resolveFileRecord, type FileTestState } from './lib/scenario-disposition.js';
-import { softSkipDisposition } from './lib/soft-skip.js';
+import { requirementIdForFile, resolveFileRecord, resolveItRecord, type FileTestState } from './lib/scenario-disposition.js';
+import { softSkipDisposition, softSkipDispositionSince, softSkipMark } from './lib/soft-skip.js';
 import { ItIdAllocator, takeExplicitRequirementId } from './lib/requirement-ids.js';
 import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './lib/spec-coherence.js';
 import type { DiscoveryPayload } from './lib/profiles.js';
+import { targetMajor } from './lib/seams.js';
+import { softSkip } from './lib/soft-skip.js';
 
-const SUITE_INIT_TIMEOUT_MS = 5_000;
+// 20 s, not 5: a Cloud Run cold start routinely exceeds 5 s, and a discovery
+// fetch that aborted at init used to turn every fixture-gated scenario into a
+// vacuous `inapplicable`. Measured 2026-09-05 on a host answering in 200 ms.
+const SUITE_INIT_TIMEOUT_MS = 20_000;
+const SUITE_INIT_ATTEMPTS = 2;
 
 async function loadHostFixtures(): Promise<void> {
   const baseUrl = process.env.OPENWOP_BASE_URL?.trim();
   if (!baseUrl) {
-    // Offline / fixture-stub-only run. No host to ask; treat as "host
-    // advertises no fixtures" so all fixture-dependent scenarios skip.
     setAdvertisedFixtures(null);
     setMultiAgentCapabilities(null);
     return;
@@ -55,39 +59,36 @@ async function loadHostFixtures(): Promise<void> {
 
   const normalizedBase = baseUrl.replace(/\/$/, '');
   const url = `${normalizedBase}/.well-known/openwop`;
+  // The representation the header selects is the one whose fixtures[] this
+  // lane is held to (versioning.md §5): read it under the lane's major.
+  const headers: Record<string, string> = { Accept: 'application/json' };
+  if (targetMajor() === 2) headers['OpenWOP-Version'] = '2.0';
 
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), SUITE_INIT_TIMEOUT_MS);
-  try {
-    const res = await fetch(url, {
-      method: 'GET',
-      headers: { Accept: 'application/json' },
-      signal: controller.signal,
-    });
-    if (!res.ok) {
-      // eslint-disable-next-line no-console
-      console.warn(
-        `[openwop-conformance setup] discovery fetch returned ${res.status}; ` +
-          `treating host as advertising no fixtures. Fixture-dependent scenarios will skip.`,
-      );
-      setAdvertisedFixtures(null);
-    setMultiAgentCapabilities(null);
+  let lastFailure = 'unknown';
+  for (let attempt = 1; attempt <= SUITE_INIT_ATTEMPTS; attempt += 1) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), SUITE_INIT_TIMEOUT_MS);
+    try {
+      const res = await fetch(url, { method: 'GET', headers, signal: controller.signal });
+      if (!res.ok) {
+        lastFailure = `HTTP ${res.status} on attempt ${attempt}`;
+        continue;
+      }
+      const body = (await res.json()) as DiscoveryPayload;
+      setAdvertisedFixtures(body);
+      setMultiAgentCapabilities(body);
       return;
+    } catch (err) {
+      lastFailure = `${(err as Error).message ?? 'unknown'} on attempt ${attempt}`;
+    } finally {
+      clearTimeout(timer);
     }
-    const body = (await res.json()) as DiscoveryPayload;
-    setAdvertisedFixtures(body);
-    setMultiAgentCapabilities(body);
-  } catch (err) {
-    // eslint-disable-next-line no-console
-    console.warn(
-      `[openwop-conformance setup] discovery fetch failed (${(err as Error).message ?? 'unknown'}); ` +
-        `treating host as advertising no fixtures. Fixture-dependent scenarios will skip.`,
-    );
-    setAdvertisedFixtures(null);
-    setMultiAgentCapabilities(null);
-  } finally {
-    clearTimeout(timer);
   }
+  // Not "the host advertises no fixtures". The document went UNREAD, and every
+  // fixture gate will say so as `blocked` rather than `inapplicable`.
+  console.warn(`[openwop-conformance setup] discovery unreadable after ${SUITE_INIT_ATTEMPTS} attempt(s) (${lastFailure}); fixture-gated scenarios will record blocked, not inapplicable.`);
+  setDiscoveryUnreadable(lastFailure);
+  setMultiAgentCapabilities(null);
 }
 
 /**
@@ -238,6 +239,7 @@ const _ledgerMarks = new Map<string, number>();
 const _itAllocators = new Map<string, ItIdAllocator>();
 const _itMarks = new Map<string, number>();
 const _itAssertionsBefore = new Map<string, number>();
+const _itSoftSkipMarks = new Map<string, number>();
 function _assertionCalls(): number {
   try {
     return (expect.getState() as { assertionCalls?: number }).assertionCalls ?? 0;
@@ -277,6 +279,62 @@ function _fileOf(task: { file?: { filepath?: string; name?: string } } | undefin
   const f = task?.file?.filepath ?? task?.file?.name;
   return typeof f === 'string' && f.length > 0 ? basename(f) : null;
 }
+// ---------------------------------------------------------------------------
+// The applicability check and the assertion MUST run under the same contract.
+//
+// A scenario's registration in scenario-majors.json says which target majors it
+// is written for. The driver reads OPENWOP_TARGET_MAJOR to decide which header
+// and path space every probe uses. Nothing connected the two: a lane that ran
+// vitest directly over all 501 files at the default (major 1) executed every
+// major-2 scenario with major-1 requests. The scenarios' own gates call
+// v2Discovery(), which sets the header EXPLICITLY, so the gate passed and the
+// probe went out as v1 — a check that proved the host speaks v2 with one
+// request, then tested a v2 requirement with a request that did not.
+//
+// Measured on a tier-1 host 2026-09-04: three "host defects" reported from that
+// lane, all of which evaporated at major 2; the host was one edit from "fixing"
+// correct behaviour. And in the other direction: 4 of 56 v2 files fail on every
+// host forever under a major-1 driver, so a gate that runs them that way is red
+// by construction and gets reasoned past. Both are the same defect: a scoped
+// signal read as unscoped, with the scope nowhere in the output.
+//
+// So: a file whose registered majors do not include the driver's target major
+// is INAPPLICABLE to this lane, recorded as such with the reason, and never
+// probes. Files not in the registry (coherence checks, lib tests) are untouched.
+// ---------------------------------------------------------------------------
+const SCENARIO_MAJORS: Record<string, number[]> = (() => {
+  try {
+    const p = join(PKG_ROOT_PATH, 'scenario-majors.json');
+    if (!existsSync(p)) return {};
+    return (JSON.parse(readFileSync(p, 'utf8')) as { majors?: Record<string, number[]> }).majors ?? {};
+  } catch {
+    return {};
+  }
+})();
+
+beforeEach((ctx) => {
+  const p = (expect.getState() as { testPath?: string }).testPath;
+  if (!p) return;
+  const file = basename(p);
+  const majors = SCENARIO_MAJORS[file];
+  if (!majors) return;
+  const lane = targetMajor();
+  if (majors.includes(lane)) return;
+  const detail = `registered for target major ${majors.join('/')} and this lane runs at major ${lane} (OPENWOP_TARGET_MAJOR) — the probe would go out under a contract the scenario's gate does not use; select files with --target-major or set the variable`;
+  // Two records, one per resolver. The per-TEST disposition is read from the
+  // requirement journal (the same entry behaviorGate writes), so the row lands
+  // as `inapplicable` with this reason rather than `skipped`, which under RFC
+  // 0148 would claim the operator opted out. The per-FILE note covers the
+  // all-skipped fallback in resolveFileRecord.
+  try {
+    recordRequirement('openwop.family.lane-target-major', 'inapplicable', detail, { scenarioFile: file });
+  } catch {
+    /* never fail a test for bookkeeping */
+  }
+  softSkip('inapplicable', detail);
+  ctx.skip();
+});
+
 beforeAll(({}, suite) => {
   // Mark the ledger journal BEFORE the file's tests run, so a behaviorGate
   // decision made by the very first test is inside the file's window.
@@ -290,6 +348,7 @@ beforeEach(({ task }) => {
   // Window for this test's own gate decisions and its own assertion count.
   _itMarks.set(file, journalLength());
   _itAssertionsBefore.set(file, _assertionCalls());
+  _itSoftSkipMarks.set(file, softSkipMark()); // rc.56: this test's own softSkip window
   takeExplicitRequirementId(); // clear any override left by a test that threw before afterEach
 });
 afterEach(({ task }) => {
@@ -338,7 +397,8 @@ afterEach(({ task }) => {
   _itAllocators.set(file, alloc);
   const itId = explicit ?? alloc.allocate(file, task.name);
   const since = journalSince(_itMarks.get(file) ?? 0);
-  const gate = since.find((e) => e.disposition === 'inapplicable') ?? since.find((e) => e.disposition === 'skipped');
+  const gateEntry = since.find((e) => e.disposition === 'inapplicable') ?? since.find((e) => e.disposition === 'skipped');
+  const gate = gateEntry === undefined ? undefined : { disposition: gateEntry.disposition as 'inapplicable' | 'skipped', ...(gateEntry.detail === undefined ? {} : { detail: gateEntry.detail }) };
   let disposition: 'executed-pass' | 'executed-fail' | 'skipped' | 'inapplicable' | 'blocked';
   let detail: string | undefined;
   // Suite 2.0.0: under the corpus gate (scripts/check-spec-coherence.mjs sets OPENWOP_CORPUS_GATE) a coherence scenario IS the subject; its rows are real dispositions for evidence/corpus-ledger.json.
@@ -348,21 +408,15 @@ afterEach(({ task }) => {
     // rule `resolveFileRecord` applies to the file in the published layout.
     disposition = 'inapplicable';
     detail = SPEC_COHERENCE_DETAIL;
-  } else if (state === 'fail') {
-    disposition = 'executed-fail';
-    const err = (task.result?.errors ?? [])[0] as { message?: string } | undefined;
-    detail = `the test executed and failed: ${(err?.message ?? 'no message').slice(0, 300)}`;
-  } else if (state === 'pass' && calls > 0) {
-    disposition = 'executed-pass';
-  } else if (gate !== undefined) {
-    disposition = gate.disposition as 'skipped' | 'inapplicable';
-    detail = gate.detail ?? `${gate.disposition} (gate recorded no reason)`;
-  } else if (state === 'pass') {
-    disposition = 'blocked';
-    detail = 'unclassified return: the test passed with zero assertions and recorded no reason — RFC 0148 §A resolves it to blocked, never to a pass';
   } else {
-    disposition = 'skipped';
-    detail = 'vitest skipped the test (ctx.skip / it.skip) without a recorded gate reason';
+    // rc.56: the softSkip notes THIS test wrote are its reason (the file row
+    // already read them; the per-`it` row did not, and a leg that said
+    // `inapplicable` came out `blocked` — which denies certification bundle-wide).
+    const noted = softSkipDispositionSince(file, _itSoftSkipMarks.get(file) ?? 0);
+    const err = (task.result?.errors ?? [])[0] as { message?: string } | undefined;
+    const rec = resolveItRecord(state === 'pass' ? 'pass' : state === 'fail' ? 'fail' : 'skip', calls, gate, noted, err?.message);
+    disposition = rec.disposition;
+    detail = rec.detail;
   }
   try {
     recordRequirement(itId, disposition, detail, { assertionCount: calls, scenarioFile: file });