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

package/src/scenarios/trigger-ingestion.test.ts

@@ -47,6 +47,8 @@ import { SCHEMAS_DIR, FIXTURES_DIR } from '../lib/paths.js';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -74,7 +76,7 @@ describe('trigger-ingestion: TriggerEvent schema (always-on, server-free)', () =
     const ev = JSON.parse(readFileSync(EVENT_FIXTURE, 'utf8'));
     expect(
       validate(ev),
-      `trigger-event.schema.json MUST accept a conforming email TriggerEvent. Errors: ${JSON.stringify(validate.errors)}`,
+      req('openwop.it.trigger-ingestion.the-canonical-email-triggerevent-fixture-validates', 'RFC 0099', `trigger-event.schema.json MUST accept a conforming email TriggerEvent. Errors: ${JSON.stringify(validate.errors)}`),
     ).toBe(true);
   });
 
@@ -83,7 +85,7 @@ describe('trigger-ingestion: TriggerEvent schema (always-on, server-free)', () =
     ev.webhook = { method: 'POST', body: { x: 1 } };
     expect(
       validate(ev),
-      'trigger-bridge.md §F.1 — a TriggerEvent MUST carry exactly the per-source sub-object matching its `source` and MUST NOT carry the others',
+      req('openwop.it.trigger-ingestion.the-f-1-one-of-rule-holds-a-source-email-event-carrying-a-webhook-sub-object-fai', 'RFC 0099', 'trigger-bridge.md §F.1 — a TriggerEvent MUST carry exactly the per-source sub-object matching its `source` and MUST NOT carry the others'),
     ).toBe(false);
   });
 
@@ -92,7 +94,7 @@ describe('trigger-ingestion: TriggerEvent schema (always-on, server-free)', () =
     ev.contentTrust = 'trusted';
     expect(
       validate(ev),
-      'trigger-bridge.md §F.1 — `contentTrust` MUST be `"untrusted"`',
+      req('openwop.it.trigger-ingestion.contenttrust-must-be-the-const-untrusted', 'RFC 0099', 'trigger-bridge.md §F.1 — `contentTrust` MUST be `"untrusted"`'),
     ).toBe(false);
   });
 
@@ -102,7 +104,7 @@ describe('trigger-ingestion: TriggerEvent schema (always-on, server-free)', () =
     noRef.email.attachments = [{ filename: 'x.png' }];
     expect(
       validate(noRef),
-      'SECURITY invariant trigger-ingestion-ssrf — an AttachmentRef MUST carry a host-internal `ref`',
+      req('openwop.it.trigger-ingestion.attachmentref-requires-a-host-internal-ref-and-rejects-a-raw-external-url-trigge', 'RFC 0099', 'SECURITY invariant trigger-ingestion-ssrf — an AttachmentRef MUST carry a host-internal `ref`'),
     ).toBe(false);
 
     // A raw external `url` the run would fetch itself → invalid
@@ -111,7 +113,7 @@ describe('trigger-ingestion: TriggerEvent schema (always-on, server-free)', () =
     rawUrl.email.attachments = [{ ref: 'blob_a1', url: 'http://169.254.169.254/latest/meta-data/' }];
     expect(
       validate(rawUrl),
-      'SECURITY invariant trigger-ingestion-ssrf — the host MUST NOT hand the run an external URL to fetch itself; AttachmentRef is a host-internal handle only',
+      req('openwop.it.trigger-ingestion.attachmentref-requires-a-host-internal-ref-and-rejects-a-raw-external-url-trigge', 'RFC 0099', 'SECURITY invariant trigger-ingestion-ssrf — the host MUST NOT hand the run an external URL to fetch itself; AttachmentRef is a host-internal handle only'),
     ).toBe(false);
   });
 
@@ -127,7 +129,7 @@ describe('trigger-ingestion: TriggerEvent schema (always-on, server-free)', () =
     };
     expect(
       validate(ev),
-      `a conforming webhook TriggerEvent MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+      req('openwop.it.trigger-ingestion.a-webhook-triggerevent-with-an-allowlisted-header-validates', 'RFC 0099', `a conforming webhook TriggerEvent MUST validate. Errors: ${JSON.stringify(validate.errors)}`),
     ).toBe(true);
   });
 });
@@ -143,7 +145,7 @@ describe('trigger-ingestion: content-freeness of the durable trigger.delivery.at
   const deliveryDef = payloads.$defs?.triggerDeliveryAttempted;
 
   it('trigger.delivery.attempted declares only the content-free RFC 0083 §C fields', () => {
-    expect(deliveryDef, 'run-event-payloads.schema.json MUST define triggerDeliveryAttempted').toBeDefined();
+    expect(deliveryDef, req('openwop.it.trigger-ingestion.trigger-delivery-attempted-declares-only-the-content-free-rfc-0083-c-fields', 'RFC 0083 §C', 'run-event-payloads.schema.json MUST define triggerDeliveryAttempted')).toBeDefined();
     const props = Object.keys(deliveryDef.properties ?? {});
     // The complete content-free field set — no `body`, `headers`, `email`,
     // `form`, `fields`, or any inbound-content carrier.
@@ -151,7 +153,7 @@ describe('trigger-ingestion: content-freeness of the durable trigger.delivery.at
     for (const banned of ['body', 'headers', 'email', 'form', 'fields', 'html', 'text', 'subject']) {
       expect(
         props.includes(banned),
-        `trigger-ingestion-content-redaction — the durable trigger.delivery.attempted payload MUST NOT carry an inbound-content field ("${banned}")`,
+        req('openwop.it.trigger-ingestion.trigger-delivery-attempted-declares-only-the-content-free-rfc-0083-c-fields', 'RFC 0083 §C', `trigger-ingestion-content-redaction — the durable trigger.delivery.attempted payload MUST NOT carry an inbound-content field ("${banned}")`),
       ).toBe(false);
     }
   });
@@ -165,16 +167,16 @@ describe('trigger-ingestion: TriggerSubscriptionRegistration schema (always-on,
     const reg = JSON.parse(readFileSync(REG_FIXTURE, 'utf8'));
     expect(
       validate(reg),
-      `trigger-subscription-registration.schema.json MUST accept a conforming registration. Errors: ${JSON.stringify(validate.errors)}`,
+      req('openwop.it.trigger-ingestion.the-canonical-registration-fixture-validates', 'RFC 0099', `trigger-subscription-registration.schema.json MUST accept a conforming registration. Errors: ${JSON.stringify(validate.errors)}`),
     ).toBe(true);
   });
 
   it('requires source + workflowId and rejects an out-of-enum source', () => {
-    expect(validate({ workflowId: 'w' }), 'registration MUST require `source`').toBe(false);
-    expect(validate({ source: 'email' }), 'registration MUST require `workflowId`').toBe(false);
+    expect(validate({ workflowId: 'w' }), req('openwop.it.trigger-ingestion.requires-source-workflowid-and-rejects-an-out-of-enum-source', 'RFC 0099', 'registration MUST require `source`')).toBe(false);
+    expect(validate({ source: 'email' }), req('openwop.it.trigger-ingestion.requires-source-workflowid-and-rejects-an-out-of-enum-source', 'RFC 0099', 'registration MUST require `workflowId`')).toBe(false);
     expect(
       validate({ source: 'schedule', workflowId: 'w' }),
-      'registration `source` MUST be one of webhook/email/form (schedule is not externally registerable)',
+      req('openwop.it.trigger-ingestion.requires-source-workflowid-and-rejects-an-out-of-enum-source', 'RFC 0099', 'registration `source` MUST be one of webhook/email/form (schedule is not externally registerable)'),
     ).toBe(false);
   });
 });
@@ -192,13 +194,13 @@ describe.skipIf(HTTP_SKIP)('trigger-ingestion: behavioral ingestion + SSRF (capa
       verification: { mode: 'none' },
       attachmentUrl: 'http://169.254.169.254/latest/meta-data/',
     });
-    if (ssrf.status === 404 || ssrf.status === 403) return; // seam unwired — soft-skip
+    if (ssrf.status === 404 || ssrf.status === 403) return softSkip('blocked', 'precondition not met — `ssrf.status === 404 || ssrf.status === 403` returned early (seam unwired — soft-skip) (seam, prior step, or fixture unavailable)'); // seam unwired — soft-skip
 
     const ssrfBody = ssrf.json as { triggerEvent?: { email?: { attachments?: unknown[] } }; ssrfRefused?: boolean } | undefined;
     expect(
       ssrfBody?.ssrfRefused === true ||
         (ssrfBody?.triggerEvent?.email?.attachments ?? []).length === 0,
-      driver.describe(
+      req('openwop.it.trigger-ingestion.an-ingestion-path-fetch-to-a-private-address-is-refused-a-delivered-event-is-con', 
         'trigger-bridge.md §F.4',
         'trigger-ingestion-ssrf — an ingestion-path fetch to a private address MUST be refused (attachment dropped), the run still starting on the rest of the event',
       ),
@@ -211,14 +213,14 @@ describe.skipIf(HTTP_SKIP)('trigger-ingestion: behavioral ingestion + SSRF (capa
       verification: { mode: 'none' },
       webhook: { method: 'POST', headers: { Authorization: 'Bearer canary' }, body: { x: 1 } },
     });
-    if (del.status === 404 || del.status === 403) return;
+    if (del.status === 404 || del.status === 403) return softSkip('blocked', 'precondition not met — `del.status === 404 || del.status === 403` returned early (seam, prior step, or fixture unavailable)');
     const delBody = del.json as
       | { deliveryEvent?: Record<string, unknown>; triggerEvent?: { webhook?: { headers?: Record<string, string> } } }
       | undefined;
     const evtJson = JSON.stringify(delBody?.deliveryEvent ?? {});
     expect(
       evtJson.includes('Bearer canary') === false && evtJson.includes('Authorization') === false,
-      driver.describe(
+      req('openwop.it.trigger-ingestion.an-ingestion-path-fetch-to-a-private-address-is-refused-a-delivered-event-is-con', 
         'trigger-bridge.md §F.4',
         'trigger-ingestion-content-redaction — the durable trigger.delivery.attempted MUST NOT carry inbound body/header content',
       ),
@@ -226,7 +228,7 @@ describe.skipIf(HTTP_SKIP)('trigger-ingestion: behavioral ingestion + SSRF (capa
     const passedHeaders = delBody?.triggerEvent?.webhook?.headers ?? {};
     expect(
       Object.keys(passedHeaders).every((k) => k.toLowerCase() !== 'authorization'),
-      driver.describe(
+      req('openwop.it.trigger-ingestion.an-ingestion-path-fetch-to-a-private-address-is-refused-a-delivered-event-is-con', 
         'trigger-bridge.md §F.1',
         'webhook.headers MUST be a host-curated allowlist — Authorization MUST NOT pass through',
       ),

package/src/scenarios/trigger-stream-cdc-sources.test.ts

@@ -48,6 +48,8 @@ import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
 import { driveDelivery } from '../lib/triggerBridge.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -71,7 +73,7 @@ describe('trigger-stream-cdc: TriggerEvent schema for stream/change (always-on,
     const ev = JSON.parse(readFileSync(STREAM_FIXTURE, 'utf8'));
     expect(
       validate(ev),
-      `trigger-event.schema.json MUST accept a conforming stream TriggerEvent (RFC 0127 §2). Errors: ${JSON.stringify(validate.errors)}`,
+      req('openwop.it.trigger-stream-cdc-sources.the-canonical-stream-triggerevent-fixture-validates', 'RFC 0127', `trigger-event.schema.json MUST accept a conforming stream TriggerEvent (RFC 0127 §2). Errors: ${JSON.stringify(validate.errors)}`),
     ).toBe(true);
   });
 
@@ -79,7 +81,7 @@ describe('trigger-stream-cdc: TriggerEvent schema for stream/change (always-on,
     const ev = JSON.parse(readFileSync(CHANGE_FIXTURE, 'utf8'));
     expect(
       validate(ev),
-      `trigger-event.schema.json MUST accept a conforming change TriggerEvent (RFC 0127 §2 / RFC 0128 §1). Errors: ${JSON.stringify(validate.errors)}`,
+      req('openwop.it.trigger-stream-cdc-sources.the-canonical-change-triggerevent-fixture-validates-op-permittedpurposes-present', 'RFC 0127', `trigger-event.schema.json MUST accept a conforming change TriggerEvent (RFC 0127 §2 / RFC 0128 §1). Errors: ${JSON.stringify(validate.errors)}`),
     ).toBe(true);
   });
 
@@ -88,7 +90,7 @@ describe('trigger-stream-cdc: TriggerEvent schema for stream/change (always-on,
     delete ev.change.op;
     expect(
       validate(ev),
-      'RFC 0127 §2 — `op` (insert|update|delete) is REQUIRED on a change event (schema-enforced in the ChangeEvent $def)',
+      req('openwop.it.trigger-stream-cdc-sources.a-change-event-without-op-fails-changeevent-requires-the-operation-discriminator', 'RFC 0127', 'RFC 0127 §2 — `op` (insert|update|delete) is REQUIRED on a change event (schema-enforced in the ChangeEvent $def)'),
     ).toBe(false);
   });
 
@@ -97,7 +99,7 @@ describe('trigger-stream-cdc: TriggerEvent schema for stream/change (always-on,
     ev.change.op = 'upsert';
     expect(
       validate(ev),
-      'RFC 0127 §2 — `op` MUST be one of insert|update|delete',
+      req('openwop.it.trigger-stream-cdc-sources.an-out-of-enum-op-fails', 'RFC 0127', 'RFC 0127 §2 — `op` MUST be one of insert|update|delete'),
     ).toBe(false);
   });
 
@@ -106,7 +108,7 @@ describe('trigger-stream-cdc: TriggerEvent schema for stream/change (always-on,
     ev.change = { op: 'insert', table: 't' };
     expect(
       validate(ev),
-      'trigger-bridge.md §F.1 — a TriggerEvent MUST carry exactly the per-source sub-object matching its `source` and MUST NOT carry the others (extends to stream/change per RFC 0127)',
+      req('openwop.it.trigger-stream-cdc-sources.the-f-1-exactly-one-rule-extends-a-source-stream-event-carrying-a-change-sub-obj', 'RFC 0127', 'trigger-bridge.md §F.1 — a TriggerEvent MUST carry exactly the per-source sub-object matching its `source` and MUST NOT carry the others (extends to stream/change per RFC 0127)'),
     ).toBe(false);
   });
 });
@@ -121,7 +123,7 @@ describe('trigger-stream-cdc: registration + capabilities vocabulary (always-on,
     for (const source of ['stream', 'change']) {
       expect(
         validateReg({ source, workflowId: 'wf_1' }),
-        `trigger-subscription-registration.schema.json MUST accept source:"${source}" (RFC 0127 §1). Errors: ${JSON.stringify(validateReg.errors)}`,
+        req('openwop.it.trigger-stream-cdc-sources.a-registration-accepts-source-stream-and-source-change', 'RFC 0127', `trigger-subscription-registration.schema.json MUST accept source:"${source}" (RFC 0127 §1). Errors: ${JSON.stringify(validateReg.errors)}`),
       ).toBe(true);
     }
   });
@@ -132,8 +134,8 @@ describe('trigger-stream-cdc: registration + capabilities vocabulary (always-on,
     const sources: string[] = tb.sources?.items?.enum ?? [];
     const external: string[] = tb.ingestion?.properties?.externalSources?.items?.enum ?? [];
     for (const v of ['stream', 'change']) {
-      expect(sources.includes(v), `RFC 0127 §1 — triggerBridge.sources[] enum MUST include "${v}"`).toBe(true);
-      expect(external.includes(v), `RFC 0127 §3 — ingestion.externalSources[] enum MUST include "${v}"`).toBe(true);
+      expect(sources.includes(v), req('openwop.it.trigger-stream-cdc-sources.the-capabilities-source-enums-include-stream-change-regression-pin', 'RFC 0127', `RFC 0127 §1 — triggerBridge.sources[] enum MUST include "${v}"`)).toBe(true);
+      expect(external.includes(v), req('openwop.it.trigger-stream-cdc-sources.the-capabilities-source-enums-include-stream-change-regression-pin', 'RFC 0127', `RFC 0127 §3 — ingestion.externalSources[] enum MUST include "${v}"`)).toBe(true);
     }
   });
 });
@@ -169,7 +171,7 @@ describe.skipIf(HTTP_SKIP)('trigger-stream-cdc: behavioral ingestion + dedup (ca
       if ((res.status === 404 || res.status === 405 || res.status === 400 || res.status === 422) && !advertisesNew) continue; // pre-0127 host — soft-skip this source
       expect(
         res.status < 400,
-        driver.describe(
+        req('openwop.it.trigger-stream-cdc-sources.a-stream-and-a-change-event-each-ingest-to-a-run-with-a-schema-valid-envelope-an', 
           'trigger-bridge.md §F.5',
           `a host advertising ingestion of "${body.source as string}" MUST ingest it (advertise-only-what-you-honor, RFC 0127 §Negative example) — got HTTP ${res.status}`,
         ),
@@ -178,7 +180,7 @@ describe.skipIf(HTTP_SKIP)('trigger-stream-cdc: behavioral ingestion + dedup (ca
       const out = res.json as { triggerEvent?: Record<string, unknown>; deliveryEvent?: Record<string, unknown> } | undefined;
       expect(
         validate(out?.triggerEvent),
-        driver.describe(
+        req('openwop.it.trigger-stream-cdc-sources.a-stream-and-a-change-event-each-ingest-to-a-run-with-a-schema-valid-envelope-an', 
           'trigger-bridge.md §F.5',
           `the delivered ${body.source as string} envelope MUST validate against trigger-event.schema.json. Errors: ${JSON.stringify(validate.errors)}`,
         ),
@@ -188,7 +190,7 @@ describe.skipIf(HTTP_SKIP)('trigger-stream-cdc: behavioral ingestion + dedup (ca
       const durable = JSON.stringify(out?.deliveryEvent ?? {});
       expect(
         !durable.includes('CANARY-STREAM-BODY') && !durable.includes('CANARY-CHANGE-BODY'),
-        driver.describe(
+        req('openwop.it.trigger-stream-cdc-sources.a-stream-and-a-change-event-each-ingest-to-a-run-with-a-schema-valid-envelope-an', 
           'trigger-bridge.md §F.5 (SR-1)',
           'the durable trigger.delivery.attempted MUST be content-free — the broker message / CDC row body has no slot on the event log',
         ),
@@ -202,11 +204,11 @@ describe.skipIf(HTTP_SKIP)('trigger-stream-cdc: behavioral ingestion + dedup (ca
     if (!behaviorGate('triggerBridge.ingestion', (external.length ?? 0) > 0)) return;
 
     const first = await driveDelivery({ scenario: 'dedup', dedupKey: 'events:3:99001', source: 'stream' });
-    if (first === null) return; // delivery seam unwired — soft-skip
-    if (first.outcome === undefined && !external.includes('stream')) return; // pre-0127 host — soft-skip
+    if (first === null) return softSkip('blocked', 'precondition not met — `first === null` returned early (delivery seam unwired — soft-skip) (seam, prior step, or fixture unavailable)'); // delivery seam unwired — soft-skip
+    if (first.outcome === undefined && !external.includes('stream')) return softSkip('blocked', 'precondition not met — `first.outcome === undefined && !external.includes(\'stream\')` returned early (pre-0127 host — soft-skip) (seam, prior step, or fixture unavailable)'); // pre-0127 host — soft-skip
     expect(
       first.deliveredCount === 1 || first.outcome === 'delivered',
-      driver.describe(
+      req('openwop.it.trigger-stream-cdc-sources.stream-dedup-the-same-broker-coordinates-delivered-twice-are-effectively-once-c', 
         'trigger-bridge.md §F.5 / §C-1',
         'a stream event dedup-keyed on (topic,partition,offset) redelivered within the window MUST be effectively-once — reuses the RFC 0083 §C-1 ≥24h floor unchanged',
       ),

package/src/scenarios/vector-knn-roundtrip.test.ts

@@ -16,6 +16,8 @@
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { discoveryFamilies } from '../lib/discovery-capabilities.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 interface DiscoveryDoc {
   capabilities?: Record<string, unknown>;
@@ -32,10 +34,10 @@ async function readCap(): Promise<Record<string, unknown> | null> {
 describe('vector-knn-roundtrip: advertisement shape (RFC 0018)', () => {
   it('capabilities.vectorStore is either absent or a well-formed object', async () => {
     const cap = await readCap();
-    if (cap === null) return; // host doesn't advertise — skip
+    if (cap === null) return softSkip('inapplicable', 'capability or profile not advertised by this host — gate `cap === null` returned early (host doesn\'t advertise — skip)'); // host doesn't advertise — skip
     expect(
       typeof cap.supported,
-      driver.describe(
+      req('openwop.it.vector-knn-roundtrip.capabilities-vectorstore-is-either-absent-or-a-well-formed-object', 
         'capabilities.schema.json §vectorStore',
         'capabilities.vectorStore.supported MUST be a boolean when present',
       ),
@@ -50,7 +52,7 @@ async function call(op: string, args: Record<string, unknown>) {
 describe('vector-knn-roundtrip: behavioral (RFC 0018 §A.vectorStore)', () => {
   it('upsert 10 vectors → query with one of them returns it as the top match', async () => {
     const probe = await call('query', { namespace: '__probe__', vector: [1, 0], topK: 1 });
-    if (probe.status === 404) return; // seam not exposed
+    if (probe.status === 404) return softSkip('blocked', 'precondition not met — `probe.status === 404` returned early (seam not exposed) (seam, prior step, or fixture unavailable)'); // seam not exposed
     const namespace = `knn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const items = Array.from({ length: 10 }, (_, i) => ({
       id: `vec-${i}`,
@@ -62,17 +64,17 @@ describe('vector-knn-roundtrip: behavioral (RFC 0018 §A.vectorStore)', () => {
     const queryRes = await call('query', { namespace, vector: items[3]!.vector, topK: 1 });
     expect(queryRes.status).toBe(200);
     const body = queryRes.json as { matches?: Array<{ id?: string; score?: number }> };
-    expect(Array.isArray(body.matches), 'matches MUST be an array').toBe(true);
+    expect(Array.isArray(body.matches), req('openwop.it.vector-knn-roundtrip.upsert-10-vectors-query-with-one-of-them-returns-it-as-the-top-match', 'RFC 0018 §A.vectorStore', 'matches MUST be an array')).toBe(true);
     expect(body.matches!.length).toBeGreaterThan(0);
     expect(
       body.matches![0]!.id,
-      driver.describe('RFC 0018 §A.vectorStore', 'query with an indexed vector MUST return it as the top match'),
+      req('openwop.it.vector-knn-roundtrip.upsert-10-vectors-query-with-one-of-them-returns-it-as-the-top-match', 'RFC 0018 §A.vectorStore', 'query with an indexed vector MUST return it as the top match'),
     ).toBe('vec-3');
   });
 
   it('topK respects the configured limit', async () => {
     const probe = await call('query', { namespace: '__probe__', vector: [1, 0], topK: 1 });
-    if (probe.status === 404) return;
+    if (probe.status === 404) return softSkip('blocked', 'precondition not met — `probe.status === 404` returned early (seam, prior step, or fixture unavailable)');
     const namespace = `topk-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const items = Array.from({ length: 8 }, (_, i) => ({
       id: `t-${i}`,
@@ -83,7 +85,7 @@ describe('vector-knn-roundtrip: behavioral (RFC 0018 §A.vectorStore)', () => {
     const body = r3.json as { matches?: unknown[] };
     expect(
       Array.isArray(body.matches) && body.matches.length <= 3,
-      driver.describe('RFC 0018 §A.vectorStore', 'query MUST return at most topK matches'),
+      req('openwop.it.vector-knn-roundtrip.topk-respects-the-configured-limit', 'RFC 0018 §A.vectorStore', 'query MUST return at most topK matches'),
     ).toBe(true);
   });
 });

package/src/scenarios/verifier-gating.test.ts

@@ -23,6 +23,8 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const SEAM = '/v1/host/sample/agents/verify-run';
 
@@ -48,26 +50,26 @@ describe('verifier-gating (RFC 0090 §B)', () => {
 
     // FAIL verdict → must NOT complete as success; agent.verified{fail} emitted.
     const failRes = await driver.post(SEAM, { simulateVerdict: 'fail' });
-    if (failRes.status === 404) return; // seam unwired — soft-skip
+    if (failRes.status === 404) return softSkip('blocked', 'precondition not met — `failRes.status === 404` returned early (seam unwired — soft-skip) (seam, prior step, or fixture unavailable)'); // seam unwired — soft-skip
     expect(
       verifiedVerdict(failRes.json) === 'fail',
-      driver.describe('RFC 0090 §A', 'a verify-run forcing a fail MUST emit agent.verified{verdict:"fail"}'),
+      req('openwop.it.verifier-gating.a-fail-verdict-blocks-commit-on-a-gating-host-a-pass-verdict-completes', 'RFC 0090 §A', 'a verify-run forcing a fail MUST emit agent.verified{verdict:"fail"}'),
     ).toBe(true);
     expect(
       !isSuccess(failRes.json),
-      driver.describe('RFC 0090 §B', 'on a gating host a fail verdict MUST block commit/terminate-as-success'),
+      req('openwop.it.verifier-gating.a-fail-verdict-blocks-commit-on-a-gating-host-a-pass-verdict-completes', 'RFC 0090 §B', 'on a gating host a fail verdict MUST block commit/terminate-as-success'),
     ).toBe(true);
 
     // PASS verdict → completes normally.
     const passRes = await driver.post(SEAM, { simulateVerdict: 'pass' });
-    if (passRes.status === 404) return;
+    if (passRes.status === 404) return softSkip('blocked', 'precondition not met — `passRes.status === 404` returned early (seam, prior step, or fixture unavailable)');
     expect(
       verifiedVerdict(passRes.json) === 'pass',
-      driver.describe('RFC 0090 §A', 'a verify-run forcing a pass MUST emit agent.verified{verdict:"pass"}'),
+      req('openwop.it.verifier-gating.a-fail-verdict-blocks-commit-on-a-gating-host-a-pass-verdict-completes', 'RFC 0090 §A', 'a verify-run forcing a pass MUST emit agent.verified{verdict:"pass"}'),
     ).toBe(true);
     expect(
       isSuccess(passRes.json),
-      driver.describe('RFC 0090 §B', 'a pass verdict MUST allow the turn to complete'),
+      req('openwop.it.verifier-gating.a-fail-verdict-blocks-commit-on-a-gating-host-a-pass-verdict-completes', 'RFC 0090 §B', 'a pass verdict MUST allow the turn to complete'),
     ).toBe(true);
   });
 });

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

@@ -39,6 +39,7 @@ import { driver, type OpenWOPResponse } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { capabilityFamily } from '../lib/discovery-capabilities.js';
+import { req } from '../lib/requirement-ids.js';
 
 const FIXTURE_ID = 'conformance-version-fold';
 const SKIP_NO_FIXTURE = !isFixtureAdvertised(FIXTURE_ID);
@@ -94,7 +95,7 @@ describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best
     );
     expect(
       versions.length,
-      driver.describe(
+      req('openwop.it.version-fold.each-version-in-min-current-max-completes-snapshot-and-event-log-stay-readable', 
         'version-negotiation.md §Conformance via X-Force-Engine-Version',
         'forceEngineVersionRange MUST describe a non-empty integer range (min <= max)',
       ),
@@ -109,7 +110,7 @@ describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best
       }
       expect(
         create.status,
-        driver.describe(
+        req('openwop.it.version-fold.each-version-in-min-current-max-completes-snapshot-and-event-log-stay-readable', 
           'version-negotiation.md §Conformance via X-Force-Engine-Version',
           `POST /v1/runs with X-Force-Engine-Version: ${v} (within the advertised range) MUST be accepted on a test key`,
         ),
@@ -120,7 +121,7 @@ describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best
       const terminal = await pollUntilTerminal(runId);
       expect(
         terminal.status,
-        driver.describe(
+        req('openwop.it.version-fold.each-version-in-min-current-max-completes-snapshot-and-event-log-stay-readable', 
           'version-negotiation.md §Cross-version interop matrix',
           `the conformance-version-fold noop run MUST complete under forced engine version ${v} (fold-best-effort)`,
         ),
@@ -130,7 +131,7 @@ describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best
       const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
       expect(
         snap.status,
-        driver.describe(
+        req('openwop.it.version-fold.each-version-in-min-current-max-completes-snapshot-and-event-log-stay-readable', 
           'version-negotiation.md §Cross-version interop matrix',
           `GET /v1/runs/{runId} MUST return a readable RunSnapshot under forced engine version ${v}`,
         ),
@@ -145,7 +146,7 @@ describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best
       );
       expect(
         events.status,
-        driver.describe(
+        req('openwop.it.version-fold.each-version-in-min-current-max-completes-snapshot-and-event-log-stay-readable', 
           'version-negotiation.md §Conformance via X-Force-Engine-Version',
           `the event log MUST be readable via events/poll under forced engine version ${v}`,
         ),
@@ -153,7 +154,7 @@ describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best
       const eventList = (events.json as { events?: unknown[] } | undefined)?.events ?? [];
       expect(
         eventList.length,
-        driver.describe(
+        req('openwop.it.version-fold.each-version-in-min-current-max-completes-snapshot-and-event-log-stay-readable', 
           'version-negotiation.md §Conformance via X-Force-Engine-Version',
           `events/poll MUST return a non-empty events[] for the forced-version run (v=${v})`,
         ),
@@ -178,14 +179,14 @@ describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best
     }
     expect(
       create.status,
-      driver.describe(
+      req('openwop.it.version-fold.a-forced-version-outside-the-advertised-range-is-rejected-with-400-unsupported-f', 
         'version-negotiation.md §Conformance via X-Force-Engine-Version',
         `X-Force-Engine-Version: ${outOfRange} (outside the advertised range) MUST return 400`,
       ),
     ).toBe(400);
     expect(
       errCode(create.json),
-      driver.describe(
+      req('openwop.it.version-fold.a-forced-version-outside-the-advertised-range-is-rejected-with-400-unsupported-f', 
         'version-negotiation.md §Conformance via X-Force-Engine-Version',
         'the out-of-range refusal MUST carry the canonical unsupported_force_engine_version code',
       ),

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

@@ -26,6 +26,7 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { req } from '../lib/requirement-ids.js';
 
 const NOOP_WORKFLOW_ID = 'conformance-noop';
 const SKIP_NO_NOOP = !isFixtureAdvertised(NOOP_WORKFLOW_ID);
@@ -47,7 +48,7 @@ describe('version-negotiation: Capabilities advertises a protocolVersion', () =>
     expect(res.status).toBe(200);
 
     const caps = res.json as { protocolVersion?: unknown };
-    expect(typeof caps.protocolVersion, driver.describe(
+    expect(typeof caps.protocolVersion, req('openwop.it.version-negotiation.get-well-known-openwop-returns-capabilities-with-protocolversion-string', 
       'capabilities.md §3 + version-negotiation.md',
       'Capabilities.protocolVersion MUST be a non-empty string',
     )).toBe('string');
@@ -69,34 +70,34 @@ describe.skipIf(SKIP_NO_NOOP)('version-negotiation: persisted events carry the c
     expect(eventsRes.status).toBe(200);
 
     const events = (eventsRes.json as { events?: RunEvent[] } | undefined)?.events ?? [];
-    expect(events.length, 'noop run MUST emit at least one event').toBeGreaterThan(0);
+    expect(events.length, req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 'run-event.schema.json §required', 'noop run MUST emit at least one event')).toBeGreaterThan(0);
 
     for (const e of events) {
-      expect(typeof e.eventId, driver.describe(
+      expect(typeof e.eventId, req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 
         'run-event.schema.json §required',
         'eventId MUST be a string',
       )).toBe('string');
-      expect(typeof e.runId, driver.describe(
+      expect(typeof e.runId, req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 
         'run-event.schema.json §required',
         'runId MUST be a string',
       )).toBe('string');
-      expect(typeof e.type, driver.describe(
+      expect(typeof e.type, req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 
         'run-event.schema.json §required',
         'type MUST be a string (RunEventType discriminator)',
       )).toBe('string');
-      expect(e.payload, driver.describe(
+      expect(e.payload, req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 
         'run-event.schema.json §required',
         'payload MUST be present (any JSON value, including null)',
       )).not.toBe(undefined);
-      expect(typeof e.timestamp, driver.describe(
+      expect(typeof e.timestamp, req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 
         'run-event.schema.json §required',
         'timestamp MUST be an ISO 8601 string',
       )).toBe('string');
-      expect(Number.isInteger(e.sequence), driver.describe(
+      expect(Number.isInteger(e.sequence), req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 
         'run-event.schema.json §required',
         'sequence MUST be a non-negative integer',
       )).toBe(true);
-      expect(e.sequence, 'sequence MUST be >= 0').toBeGreaterThanOrEqual(0);
+      expect(e.sequence, req('openwop.it.version-negotiation.every-event-has-the-6-required-runeventdoc-fields-per-run-event-schema-json', 'run-event.schema.json §required', 'sequence MUST be >= 0')).toBeGreaterThanOrEqual(0);
     }
   });
 
@@ -118,7 +119,7 @@ describe.skipIf(SKIP_NO_NOOP)('version-negotiation: persisted events carry the c
       const curr = sequences[i] ?? -1;
       expect(
         curr,
-        driver.describe(
+        req('openwop.it.version-negotiation.event-sequences-within-a-run-are-strictly-monotonic', 
           'run-event.schema.json §sequence + idempotency.md',
           `event[${i}].sequence (${curr}) MUST be > event[${i - 1}].sequence (${prev}) — strictly monotonic per run`,
         ),
@@ -144,7 +145,7 @@ describe.skipIf(SKIP_NO_NOOP)('version-negotiation: events/poll forward-compat t
 
     expect(
       eventsRes.status,
-      driver.describe(
+      req('openwop.it.version-negotiation.events-poll-with-lastsequence-past-current-end-returns-empty-events-iscomplete', 
         'rest-endpoints.md GET /v1/runs/{runId}/events/poll',
         'lastSequence beyond the current end MUST return 200 with empty events, not 4xx',
       ),

package/src/scenarios/voice-bargein-no-partial-leak.test.ts

@@ -21,6 +21,8 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { req } from '../lib/requirement-ids.js';
+import { softSkip } from '../lib/soft-skip.js';
 
 const SEAM = '/v1/host/sample/voice/barge-in';
 
@@ -40,22 +42,22 @@ describe('voice-bargein-no-partial-leak (RFC 0106 §F INV-3)', () => {
     if (!behaviorGate('openwop-voice-bargein', advertised)) return;
 
     const res = await driver.post(SEAM, {});
-    if (res.status === 404) return; // seam unwired — soft-skip
+    if (res.status === 404) return softSkip('blocked', 'precondition not met — `res.status === 404` returned early (seam unwired — soft-skip) (seam, prior step, or fixture unavailable)'); // seam unwired — soft-skip
 
-    expect(res.status === 200, driver.describe('RFC 0106 §F', 'the barge-in seam MUST return 200')).toBe(true);
+    expect(res.status === 200, req('openwop.it.voice-bargein-no-partial-leak.barge-in-cancels-with-no-synthesis-chunk-emitted-after-voice-cancelled', 'RFC 0106 §F', 'the barge-in seam MUST return 200')).toBe(true);
 
     const types = eventsOf(res.json).map((e) => e.type);
     const bargeIdx = types.indexOf('voice.barge_in');
     const cancelIdx = types.indexOf('voice.cancelled');
-    expect(bargeIdx >= 0, driver.describe('RFC 0106 §D', 'a barge-in MUST emit voice.barge_in')).toBe(true);
-    expect(cancelIdx >= 0, driver.describe('RFC 0106 §D', 'a barge-in that cancels work MUST emit voice.cancelled')).toBe(true);
-    expect(cancelIdx > bargeIdx, driver.describe('RFC 0106 §D', 'voice.cancelled MUST follow voice.barge_in')).toBe(true);
+    expect(bargeIdx >= 0, req('openwop.it.voice-bargein-no-partial-leak.barge-in-cancels-with-no-synthesis-chunk-emitted-after-voice-cancelled', 'RFC 0106 §D', 'a barge-in MUST emit voice.barge_in')).toBe(true);
+    expect(cancelIdx >= 0, req('openwop.it.voice-bargein-no-partial-leak.barge-in-cancels-with-no-synthesis-chunk-emitted-after-voice-cancelled', 'RFC 0106 §D', 'a barge-in that cancels work MUST emit voice.cancelled')).toBe(true);
+    expect(cancelIdx > bargeIdx, req('openwop.it.voice-bargein-no-partial-leak.barge-in-cancels-with-no-synthesis-chunk-emitted-after-voice-cancelled', 'RFC 0106 §D', 'voice.cancelled MUST follow voice.barge_in')).toBe(true);
 
     // The load-bearing INV-3 assertion: nothing partial after the cancel.
     const afterCancel = types.slice(cancelIdx + 1);
     expect(
       !afterCancel.includes('voice.synthesis_chunk'),
-      driver.describe('RFC 0106 §F INV-3', 'NO voice.synthesis_chunk (partial output) may be emitted AFTER voice.cancelled'),
+      req('openwop.it.voice-bargein-no-partial-leak.barge-in-cancels-with-no-synthesis-chunk-emitted-after-voice-cancelled', 'RFC 0106 §F INV-3', 'NO voice.synthesis_chunk (partial output) may be emitted AFTER voice.cancelled'),
     ).toBe(true);
   });
 });

package/src/scenarios/voice-event-payloads-shape.test.ts

@@ -32,8 +32,7 @@ import { join } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 import { SCHEMAS_DIR } from '../lib/paths.js';
-
-const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+import { req } from '../lib/requirement-ids.js';
 
 function loadSchema(name: string): Record<string, any> {
   return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, any>;
@@ -63,7 +62,7 @@ describe('voice-event-payloads-shape: the voice.* run-event taxonomy (RFC 0106
   it('all seven voice.* types are in the RunEventType enum', () => {
     const enumVals: string[] = loadSchema('run-event.schema.json').$defs.RunEventType.enum;
     for (const t of VOICE_TYPES) {
-      expect(enumVals.includes(t), why('run-event.schema.json §RunEventType', `${t} MUST be a RunEventType`)).toBe(true);
+      expect(enumVals.includes(t), req('openwop.it.voice-event-payloads-shape.all-seven-voice-types-are-in-the-runeventtype-enum', 'run-event.schema.json §RunEventType', `${t} MUST be a RunEventType`)).toBe(true);
     }
   });
 
@@ -71,8 +70,8 @@ describe('voice-event-payloads-shape: the voice.* run-event taxonomy (RFC 0106
     const payloads = loadSchema('run-event-payloads.schema.json');
     const typeIndex = payloads.$defs._typeIndex.properties as Record<string, { $ref: string }>;
     for (const t of VOICE_TYPES) {
-      expect(typeIndex[t], why('run-event-payloads.schema.json §typeIndex', `${t} MUST map to a $def`)).toBeDefined();
-      expect(payloads.$defs[DEF_KEY[t]], why('run-event-payloads.schema.json', `$defs.${DEF_KEY[t]} MUST exist`)).toBeDefined();
+      expect(typeIndex[t], req('openwop.it.voice-event-payloads-shape.each-voice-type-has-a-payload-def-reachable-via-typeindex', 'run-event-payloads.schema.json §typeIndex', `${t} MUST map to a $def`)).toBeDefined();
+      expect(payloads.$defs[DEF_KEY[t]], req('openwop.it.voice-event-payloads-shape.each-voice-type-has-a-payload-def-reachable-via-typeindex', 'run-event-payloads.schema.json', `$defs.${DEF_KEY[t]} MUST exist`)).toBeDefined();
     }
   });
 
@@ -84,15 +83,15 @@ describe('voice-event-payloads-shape: the voice.* run-event taxonomy (RFC 0106
 
     expect(
       validate({ text: 'book a table', isFinal: true, atMs: 1200, contentTrust: 'untrusted' }),
-      why('RFC 0106 §F INV-2', 'a transcript marked untrusted MUST validate'),
+      req('openwop.it.voice-event-payloads-shape.voice-transcript-requires-contenttrust-untrusted-security-voice-transcript-untru', 'RFC 0106 §F INV-2', 'a transcript marked untrusted MUST validate'),
     ).toBe(true);
     expect(
       validate({ text: 'book a table', isFinal: true, atMs: 1200 }),
-      why('RFC 0106 §F INV-2 (voice-transcript-untrusted)', 'a transcript WITHOUT contentTrust MUST be rejected'),
+      req('openwop.it.voice-event-payloads-shape.voice-transcript-requires-contenttrust-untrusted-security-voice-transcript-untru', 'RFC 0106 §F INV-2 (voice-transcript-untrusted)', 'a transcript WITHOUT contentTrust MUST be rejected'),
     ).toBe(false);
     expect(
       validate({ text: 'book a table', isFinal: true, atMs: 1200, contentTrust: 'trusted' }),
-      why('RFC 0106 §F INV-2 (voice-transcript-untrusted)', 'contentTrust MUST be the const "untrusted" — never promoted'),
+      req('openwop.it.voice-event-payloads-shape.voice-transcript-requires-contenttrust-untrusted-security-voice-transcript-untru', 'RFC 0106 §F INV-2 (voice-transcript-untrusted)', 'contentTrust MUST be the const "untrusted" — never promoted'),
     ).toBe(false);
   });
 
@@ -104,11 +103,11 @@ describe('voice-event-payloads-shape: the voice.* run-event taxonomy (RFC 0106
 
     expect(
       validate({ seq: 0, mimeType: 'audio/mpeg', durationMs: 240, url: 'https://host/seg/0', final: false }),
-      why('RFC 0106 §C', 'a metadata chunk referencing bytes by url MUST validate'),
+      req('openwop.it.voice-event-payloads-shape.voice-synthesis-chunk-is-metadata-shaped-seq-mimetype-required-bytes-by-referenc', 'RFC 0106 §C', 'a metadata chunk referencing bytes by url MUST validate'),
     ).toBe(true);
     expect(
       validate({ mimeType: 'audio/mpeg' }),
-      why('RFC 0106 §C', 'a chunk without seq MUST be rejected'),
+      req('openwop.it.voice-event-payloads-shape.voice-synthesis-chunk-is-metadata-shaped-seq-mimetype-required-bytes-by-referenc', 'RFC 0106 §C', 'a chunk without seq MUST be rejected'),
     ).toBe(false);
   });
 
@@ -120,7 +119,7 @@ describe('voice-event-payloads-shape: the voice.* run-event taxonomy (RFC 0106
       const validate = ajv.compile(payloads.$defs[key]);
       expect(
         validate({ atMs: 100, transcriptBody: 'should not be here' }),
-        why('RFC 0106 §D', `${key} MUST reject an unknown (content-bearing) property`),
+        req('openwop.it.voice-event-payloads-shape.content-free-voice-events-reject-unknown-properties-additionalproperties-false', 'RFC 0106 §D', `${key} MUST reject an unknown (content-bearing) property`),
       ).toBe(false);
     }
   });