@openwop/openwop-conformance 1.138.1 → 1.140.0

package/src/lib/spec-coherence-registry.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Keeps `SPEC_COHERENCE_SCENARIOS` honest by re-deriving it from source.
+ *
+ * A hand-maintained list of filenames is a claim that decays silently: a new
+ * spec-coherence scenario lands and reports `blocked` in every host's bundle
+ * forever, or one grows a `driver` call and starts telling hosts a requirement
+ * about their own behaviour does not apply to them. Neither shows up as a
+ * failure anywhere — which is the whole reason the original defect survived.
+ *
+ * The membership rule is mechanical, so the check can be too:
+ *   gates on `V1_DIR === null`  AND  never calls `driver.get/post/delete`.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { SPEC_COHERENCE_SCENARIOS, SPEC_COHERENCE_DETAIL } from './spec-coherence.js';
+import { resolveFileRecord } from './scenario-disposition.js';
+
+const SCENARIOS = new URL('../scenarios/', import.meta.url).pathname;
+
+function derive(): { pure: string[]; hostTouching: string[] } {
+  const pure: string[] = [];
+  const hostTouching: string[] = [];
+  for (const f of readdirSync(SCENARIOS)) {
+    if (!f.endsWith('.test.ts')) continue;
+    const src = readFileSync(join(SCENARIOS, f), 'utf8');
+    if (!/V1_DIR\s*===?\s*null/.test(src)) continue;
+    (/\bdriver\.(get|post|delete)\b/.test(src) ? hostTouching : pure).push(f);
+  }
+  return { pure: pure.sort(), hostTouching: hostTouching.sort() };
+}
+
+describe('SPEC_COHERENCE_SCENARIOS is derivable, not asserted', () => {
+  it('matches every scenario that reads spec/v1 and never drives a host', () => {
+    const { pure } = derive();
+    const listed = [...SPEC_COHERENCE_SCENARIOS].sort();
+    // Named diffs rather than a bare inequality: a failure here should say
+    // which file to add or drop, not that two sets differ.
+    expect(pure.filter((f) => !SPEC_COHERENCE_SCENARIOS.has(f)), 'reads spec/v1, drives no host, NOT in the registry — it will report `blocked` in every host bundle').toEqual([]);
+    expect(listed.filter((f) => !pure.includes(f)), 'in the registry but no longer qualifies — it now drives a host, or stopped reading spec/v1').toEqual([]);
+  });
+
+  it('excludes the host-touching ones, which are honestly `blocked`', () => {
+    // These assert ADVERTISED behaviour that a missing dependency prevented
+    // exercising — RFC 0148 §A's definition of `blocked`, verbatim. Calling
+    // them `inapplicable` would tell a host a requirement about its own
+    // behaviour does not apply to it.
+    const { hostTouching } = derive();
+    expect(hostTouching.length, 'expected some V1_DIR-gated scenarios to also drive the host').toBeGreaterThan(0);
+    for (const f of hostTouching) {
+      expect(SPEC_COHERENCE_SCENARIOS.has(f), `${f} drives a host and must NOT be classified inapplicable`).toBe(false);
+    }
+  });
+
+  it('the registry is non-empty — an empty set would silently disable the fix', () => {
+    expect(SPEC_COHERENCE_SCENARIOS.size).toBeGreaterThan(20);
+  });
+});
+
+describe('resolveFileRecord classifies a corpus scenario as inapplicable, not blocked', () => {
+  // A published-layout run: describe.skipIf fires at COLLECTION, so vitest
+  // reports the file's tests as skipped, nothing notes a reason, and before
+  // this change resolveFileRecord returned `blocked` with the unclassified
+  // marker — the row a host operator could not tell from a real gap.
+  const CORPUS = 'protocol-version-grammar.test.ts';
+
+  it('a corpus scenario that never ran is inapplicable, with a reason aimed at the host operator', () => {
+    const r = resolveFileRecord(['skip', 'skip'], undefined, 0, null, CORPUS);
+    expect(r.disposition).toBe('inapplicable');
+    expect(r.detail).toBe(SPEC_COHERENCE_DETAIL);
+    expect(r.detail).toContain('asserts nothing about a host');
+    expect(r.detail).toContain('OPENWOP_CONFORMANCE_ROOT');
+  });
+
+  it('WITHOUT the registry it would still be blocked — the branch is what changes it', () => {
+    // Same inputs, filename withheld: the pre-change behaviour. This is the
+    // negative control; if it ever returns `inapplicable`, the branch is not
+    // what is doing the work and the test above proves nothing.
+    const r = resolveFileRecord(['skip', 'skip'], undefined, 0, null);
+    expect(r.disposition).toBe('blocked');
+  });
+
+  it('a non-corpus scenario is untouched', () => {
+    const r = resolveFileRecord(['skip', 'skip'], undefined, 0, null, 'webhook-signed-delivery.test.ts');
+    expect(r.disposition).toBe('blocked');
+  });
+
+  it('a corpus scenario that FAILED is never laundered into inapplicable', () => {
+    // The guard that matters: if the corpus IS present and an assertion fails,
+    // that is a real spec-coherence defect and must stay executed-fail.
+    const r = resolveFileRecord(['pass', 'fail'], undefined, 12, null, CORPUS);
+    expect(r.disposition).toBe('executed-fail');
+  });
+
+  it('a corpus scenario that RAN and passed stays executed-pass', () => {
+    const r = resolveFileRecord(['pass'], undefined, 40, null, CORPUS);
+    expect(r.disposition).toBe('executed-pass');
+  });
+});

package/src/lib/spec-coherence.ts

@@ -0,0 +1,106 @@
+/**
+ * Scenarios that measure the SPEC, not the host (RFC 0148 §A).
+ *
+ * ## The defect
+ *
+ * 28 scenarios read `spec/v1/*.md` to check the corpus is internally coherent —
+ * that the `protocolVersion` grammar in the schema matches RFC 0149, that error
+ * envelopes are the shape `error-envelope.schema.json` declares, that every
+ * normative example extracts and validates. They assert nothing whatever about
+ * a host.
+ *
+ * `spec/v1/` is deliberately NOT bundled in the published tarball (`paths.ts`
+ * says so), so in a published-layout run `V1_DIR` is null and they
+ * `describe.skipIf` at COLLECTION time. No test body runs, so no `softSkip`
+ * note is recorded, and `resolveFileRecord` resolves an all-skipped file with no
+ * reason to **`blocked`** carrying "every test returned early … no recorded
+ * reason".
+ *
+ * That row then lands in a HOST's certification bundle. A host operator reads
+ * `blocked` and cannot tell it from a real gap in their implementation. A
+ * tier-2 host measured 13 such rows — **a third of their undiagnosed set** —
+ * and only discovered what they were by pointing `OPENWOP_CONFORMANCE_ROOT` at
+ * a spec checkout and watching 85 assertions pass in about a second, 59 of them
+ * against a dead `localhost:9`.
+ *
+ * ## Why `inapplicable`, and why not the other four
+ *
+ * RFC 0148 §A defines the two candidates precisely, and the definitions decide
+ * it:
+ *
+ *   - `blocked` — "**advertised behavior** could not be exercised because a
+ *     required seam, fixture, credential, or dependency was unavailable."
+ *     There is no advertised behaviour here. Nothing about the host was ever
+ *     going to be exercised, so nothing about the host failed to be.
+ *   - `inapplicable` — "the requirement does not apply to the captured
+ *     discovery/profile set." A requirement about the spec corpus does not
+ *     apply to any host's discovery set. This is the honest label.
+ *
+ * `executed-pass` is wrong for the obvious reason: in a run where the corpus is
+ * absent, nothing executed, and claiming a pass for an unrun scenario is the
+ * defect this whole disposition system exists to prevent. A NEW disposition
+ * value was considered and rejected — `certification-bundle-v2.schema.json`
+ * enumerates the five, and `verifyBundleV2` is a published consumer contract,
+ * so a sixth is a wire break for every existing verifier. Correct use of an
+ * existing value costs nothing and breaks no one.
+ *
+ * `inapplicable` is in `CERTIFIABLE`, which is the point: these rows stop
+ * counting against a host that has no way to affect them.
+ *
+ * ## Why a list and not a predicate
+ *
+ * The property is static — "gates on `V1_DIR` and never touches `driver`" — and
+ * cannot be evaluated from `setup.ts` at runtime. So it is a list, and a list
+ * drifts. `spec-coherence-registry.test.ts` re-derives it from source on every
+ * run and fails when the two disagree, which is the only thing that makes a
+ * hand-maintained set trustworthy.
+ *
+ * ## What is deliberately NOT here
+ *
+ * Seven scenarios gate on `V1_DIR` **and** drive the host
+ * (`replay-side-effect-suppression`, `data-residency-admission`,
+ * `profile-discovery-core-alias`, `workflow-variable-format`,
+ * `workflow-chain-deferred-parameters`, `artifact-type-store-emission`,
+ * `artifact-type-registration-source`). Those assert advertised host behaviour
+ * that could not be exercised because a dependency was unavailable — which is
+ * `blocked`, exactly as §A defines it. Classifying them `inapplicable` would
+ * tell a host "this does not apply to you" about a requirement that does.
+ */
+
+/** Scenarios whose subject is the corpus. Kept honest by `spec-coherence-registry.test.ts`. */
+export const SPEC_COHERENCE_SCENARIOS: ReadonlySet<string> = new Set([
+  'artifact-schema-compile-bounded.test.ts',
+  'artifact-type-legacy-ids.test.ts',
+  'capability-example-root-layout.test.ts',
+  'certification-floor-enforcement.test.ts',
+  'chain-subchain-unsupported-refused.test.ts',
+  'compensation-profile.test.ts',
+  'core-manifest-and-extension-registry.test.ts',
+  'discovery-canonical-family-no-shadow.test.ts',
+  'edge-condition-truthy-falsy.test.ts',
+  'effect-identity-composition.test.ts',
+  'effect-identity-cross-scope.test.ts',
+  'error-envelope-canonical-shape.test.ts',
+  'form-content-packs.test.ts',
+  'multi-region-effect-vocabulary.test.ts',
+  'normative-example-extraction.test.ts',
+  'openapi-asyncapi-sdk-parity.test.ts',
+  'pack-manifest-extensions.test.ts',
+  'protocol-version-grammar.test.ts',
+  'registry-declarative-kinds.test.ts',
+  'rfc-0147-self-audit.test.ts',
+  'rfc-lifecycle-coherence.test.ts',
+  'semantic-digest-v2.test.ts',
+  'spec-corpus-validity.test.ts',
+  'spec-section-citations.test.ts',
+  'tool-result-trust-monotone.test.ts',
+  'versioned-composition-profiles.test.ts',
+  'workflow-chain-internal-flag.test.ts',
+  'workload-identity-profile.test.ts',
+]);
+
+/** The reason recorded on such a row, written for the host operator reading it. */
+export const SPEC_COHERENCE_DETAIL =
+  'inapplicable to any host: this scenario reads spec/v1/ to check the SPEC corpus is internally coherent and asserts nothing about a host. '
+  + 'The published tarball does not bundle spec/v1/ (see lib/paths.ts), so it does not run here. '
+  + 'Set OPENWOP_CONFORMANCE_ROOT to a spec checkout to run it; it needs no host.';

package/src/scenarios/a2a-task-roundtrip.test.ts

@@ -47,6 +47,7 @@ import { pollUntilTerminal, pollUntilStatus } from '../lib/polling.js';
 import { SCHEMAS_DIR } from '../lib/paths.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { seamAbsent } from '../lib/soft-skip.js';
 
 /**
  * Callback-shaped: the host issues A2A JSON-RPC calls to the suite's fake peer.
@@ -403,21 +404,76 @@ describe.skipIf(HTTP_SKIP)('a2a-task-roundtrip: durable tasks/get after disconne
   });
 });
 
-describe.skipIf(HTTP_SKIP)('a2a-task-roundtrip: push-config SSRF (gated on a2a.pushNotifications; RFC 0100)', () => {
-  it('registering a pushConfig.url at a private address is refused (a2a-push-egress-ssrf)', async () => {
+/**
+ * Push-config SSRF, TWO-SIDED (RFC 0100 §4, a2a-integration.md §D.6).
+ *
+ * The RFC 0093 webhook-egress guard has two arms — `webhooks.md`
+ * §"SSRF protection" rejects non-`https://` protocols AND private/loopback/
+ * link-local/ULA/metadata addresses — and a host may implement either one
+ * alone.
+ *
+ * Until 2026-08-25 this file probed with a single `http://10.0.0.5/push`,
+ * which **violates both arms at once**. Either arm alone refuses it, so a
+ * `>= 400` witnessed *that something refused* and never *which guard ran*.
+ * A host with only the address arm passed; so did a host with only the
+ * scheme arm; so would a host that refused every push URL for an unrelated
+ * reason. The assertion was real and the conclusion drawn from it was not.
+ *
+ * The probes below isolate one arm each: `https` at a private address can
+ * only be refused by the address arm, and `http` at a public host can only
+ * be refused by the scheme arm. Two legs is the minimum that distinguishes
+ * them — the same reason a negative control is not optional.
+ *
+ * The scheme leg is new, and the obligation it checks was previously stated
+ * only by reference (every prior wording abbreviated the guard to its
+ * address arm). `COMPATIBILITY.md` §3 records the Class 3 classification: a
+ * host accepting a plaintext push target was never conforming. An
+ * implementer reddened by this leg is reading a clarification, not a new
+ * requirement — the failure message says so.
+ */
+describe.skipIf(HTTP_SKIP)('a2a-task-roundtrip: push-config SSRF, two-sided (gated on a2a.pushNotifications; RFC 0100)', () => {
+  async function registerPush(url: string): Promise<{ status: number } | null> {
     const a2a = await readCapabilityFamily<{ pushNotifications?: boolean }>('a2a');
-    if (!behaviorGate('a2a.pushNotifications', a2a?.pushNotifications === true)) return;
+    if (!behaviorGate('a2a.pushNotifications', a2a?.pushNotifications === true)) return null;
+    const res = await driver.post('/v1/host/sample/a2a/tasks/push-config', { taskId: 'run_x', url });
+    if (res.status === 404 || res.status === 403) {
+      // Previously a bare `return`, invisible to the RFC 0148 §A ledger because
+      // this file's other tests assert — so the file recorded `executed-pass`
+      // while this leg had witnessed nothing. Say why instead.
+      return seamAbsent(
+        'a2a-push-egress-ssrf — the `/v1/host/sample/a2a/tasks/push-config` seam is not mounted (404/403), so neither guard arm is observable',
+      ) ?? null;
+    }
+    return { status: res.status };
+  }
+
+  it('ADDRESS arm: an https pushConfig.url at a private address is refused', async () => {
+    // `https` on purpose: this probe is refusable ONLY by the address arm, so a
+    // host that implements the scheme arm alone cannot pass it by accident.
+    const res = await registerPush('https://10.0.0.5/push');
+    if (res === null) return;
+    expect(
+      res.status >= 400,
+      driver.describe(
+        'a2a-integration.md §D.6 (address arm)',
+        'a2a-push-egress-ssrf — a pushConfig.url at a private/loopback address MUST be refused before any push, even over https',
+      ),
+    ).toBe(true);
+  });
 
-    const res = await driver.post('/v1/host/sample/a2a/tasks/push-config', {
-      taskId: 'run_x',
-      url: 'http://10.0.0.5/push',
-    });
-    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+  it('SCHEME arm: an http pushConfig.url at a public host is refused', async () => {
+    // Public hostname on purpose: refusable ONLY by the scheme arm.
+    const res = await registerPush('http://push.example.com/push');
+    if (res === null) return;
     expect(
       res.status >= 400,
       driver.describe(
-        'a2a-integration.md §"Async / durable Tasks"',
-        'a2a-push-egress-ssrf — a caller-supplied pushConfig.url at a private/loopback address MUST be refused before any push',
+        'a2a-integration.md §D.6 (scheme arm)',
+        'a2a-push-egress-ssrf — a plaintext `http://` pushConfig.url MUST be refused before any push. '
+          + 'The RFC 0093 webhook-egress guard is the `webhooks.md` §"SSRF protection" list IN FULL, whose first entry is '
+          + '"Non-`https://` protocols". Every prior wording of this requirement abbreviated the guard to its address arm; '
+          + 'COMPATIBILITY.md §3 records this as a Class 3 clarification, so a host failing here was never conforming rather '
+          + 'than newly non-conforming.',
       ),
     ).toBe(true);
   });

package/src/scenarios/agent-channel-dispatch.test.ts

@@ -38,6 +38,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { forkDeclined } from '../lib/fork-availability.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
@@ -149,8 +150,7 @@ describe.skipIf(HTTP_SKIP)('agent-channel-dispatch (RFC 0082 §B): production ru
       `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
       { fromSeq: 0, mode: 'replay' },
     );
-    if (fork1.status === 501) {
-      // replay advertised but not implemented for this run — skip-equivalent.
+    if (forkDeclined(fork1.status, 'channel-dispatch replay fork 1')) {
       ctx.skip();
       return;
     }
@@ -213,7 +213,7 @@ describe.skipIf(HTTP_SKIP)('agent-channel-dispatch (RFC 0082 §B): production ru
       `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
       { fromSeq: 0, mode: 'replay' },
     );
-    if (fork2.status === 501) {
+    if (forkDeclined(fork2.status, 'channel-dispatch replay fork 2')) {
       ctx.skip();
       return;
     }

package/src/scenarios/replay-fanout-suppression.test.ts

@@ -72,7 +72,8 @@ import { afterEach, describe, expect, it } from 'vitest';
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 import { softSkip } from '../lib/soft-skip.js';
 import { driver } from '../lib/driver.js';
-import { discoveryFamilies } from '../lib/discovery-capabilities.js';
+import { forkDeclined } from '../lib/fork-availability.js';
+import { discoveryFamilies, readCapabilityFamily } from '../lib/discovery-capabilities.js';
 import { pollUntilTerminal, scaledTimeoutMs } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { discoverOwnedTenant } from '../lib/webhook-receiver.js';
@@ -213,18 +214,50 @@ describe('replay-fanout-suppression: a replay fork MUST NOT fan out re-emitted e
       ),
     ).toBeGreaterThan(0);
 
+    // ── CAPABILITY GATE (added 2026-08-25) ──────────────────────────────────
+    // This is the ONLY scenario in the replay family that never checked whether
+    // the host advertises replay before forking — every sibling reads
+    // `replay.supported` first. That omission is why it was the one scenario
+    // reaching the fork seam on a host that does not implement it, and why it
+    // hard-failed `expected 404 to be 201` on every CI run of `main` while the
+    // siblings quietly returned at their capability check.
+    //
+    // `inapplicable`, not `blocked`: a host that does not advertise replay is
+    // outside this MUST NOT's scope entirely, and `blocked` would claim the
+    // requirement applies but could not be witnessed — a stronger claim than
+    // the evidence supports. Recorded explicitly because LEG 1 above asserted,
+    // so the file-level disposition would otherwise be `executed-pass`.
+    const replayCap = await readCapabilityFamily<{ supported?: boolean; modes?: unknown }>('replay');
+    if (replayCap?.supported !== true) {
+      recordRequirement(
+        REQUIREMENT_ID,
+        'inapplicable',
+        'host does not advertise `replay.supported: true`, so a replay fork cannot occur and this MUST NOT '
+          + 'has nothing to constrain on this host',
+      );
+      ctx.skip();
+      return;
+    }
+
     // ── LEG 2 — THE MUST NOT. A replay fork re-emits; it must not deliver. ───
     const replay = await driver.post(`/v1/runs/${encodeURIComponent(sourceRunId)}:fork`, {
       mode: 'replay',
     });
-    if (replay.status === 501) {
-      // Advertised but not implemented for this range. Leg 1 already asserted,
-      // so the FILE is `executed-pass` — but the MUST NOT was never exercised,
-      // and that is what this row must say.
+    if (forkDeclined(replay.status, 'fanout-suppression replay fork')) {
+      // Leg 1 already asserted, so the FILE is `executed-pass` — but the MUST
+      // NOT was never exercised, and that is what this row must say. The
+      // explicit record wins over the file-level one (setup.ts).
+      //
+      // 404 and 403 were NOT handled here until 2026-08-25, only 501. The
+      // postgres reference host 404s this route, so this was the one scenario
+      // in the replay family that actually reached the seam — and it hard-
+      // failed `expected 404 to be 201` on every CI run of `main`, absorbed by
+      // the 85% pass-rate floor. The suite required a host to implement the
+      // route in order to say it had not implemented the route.
       recordRequirement(
         REQUIREMENT_ID,
         'blocked',
-        'replay fork returned 501 — the re-emission this requirement is stated over never happened, '
+        `replay fork returned ${replay.status} — the re-emission this requirement is stated over never happened, `
           + 'so the absence of deliveries below would prove nothing',
       );
       ctx.skip();

package/src/scenarios/replay-fork-arbitrary.test.ts

@@ -30,6 +30,8 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { forkDeclined } from '../lib/fork-availability.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 
@@ -122,6 +124,7 @@ describe.skipIf(SKIP_NO_MULTI)(
     it('mid-fromSeq replay fork produces a new run that reaches `completed`', async (ctx) => {
       const replay = await fetchReplayCapability();
       if (replay?.supported !== true) {
+        softSkip('inapplicable', "host does not advertise `replay.supported: true` — the replay contract does not apply to it");
         ctx.skip();
         return;
       }
@@ -129,6 +132,7 @@ describe.skipIf(SKIP_NO_MULTI)(
         ? replay.modes.filter((m): m is string => typeof m === 'string')
         : [];
       if (!modes.includes('replay')) {
+        softSkip('inapplicable', "host does not advertise the `replay` fork mode — this leg's rule has no path to apply");
         ctx.skip();
         return;
       }
@@ -140,6 +144,7 @@ describe.skipIf(SKIP_NO_MULTI)(
         // Fixture's wire shape doesn't expose node.completed(b) with a
         // numeric sequence — skip rather than fail. Conformant hosts
         // with the standard event shape will hit the assertions below.
+        softSkip('blocked', "the advertised fixture's wire shape exposes no numeric sequence for node.completed(b), so there is no mid-run point to fork from");
         ctx.skip();
         return;
       }
@@ -149,7 +154,7 @@ describe.skipIf(SKIP_NO_MULTI)(
         { fromSeq, mode: 'replay' },
       );
 
-      if (fork.status === 501) {
+      if (forkDeclined(fork.status, 'arbitrary-event fork')) {
         ctx.skip();
         return;
       }
@@ -226,7 +231,7 @@ describe.skipIf(SKIP_NO_MULTI)(
           `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
           { fromSeq, mode: 'replay' },
         );
-        if (fork1.status === 501) {
+        if (forkDeclined(fork1.status, 'arbitrary-event fork 1')) {
           ctx.skip();
           return;
         }
@@ -238,7 +243,7 @@ describe.skipIf(SKIP_NO_MULTI)(
           `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
           { fromSeq, mode: 'replay' },
         );
-        if (fork2.status === 501) {
+        if (forkDeclined(fork2.status, 'arbitrary-event fork 2')) {
           ctx.skip();
           return;
         }
@@ -294,6 +299,7 @@ describe.skipIf(SKIP_NO_MULTI)(
     it('mid-fromSeq branch fork with empty overlay produces a new run that reaches `completed`', async (ctx) => {
       const replay = await fetchReplayCapability();
       if (replay?.supported !== true) {
+        softSkip('inapplicable', "host does not advertise `replay.supported: true` — the replay contract does not apply to it");
         ctx.skip();
         return;
       }

package/src/scenarios/replay-fork.test.ts

@@ -25,6 +25,8 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { forkDeclined } from '../lib/fork-availability.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 
@@ -60,6 +62,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: fork from fromSeq=0 in replay mode', () =
       // Visible skip — earlier this was a silent `return` that
       // collapsed to a vacuous pass and made it impossible to tell
       // unexercised tests apart from honest passes.
+      softSkip('inapplicable', "host does not advertise the `replay` fork mode — this leg's rule has no path to apply");
       ctx.skip();
       return;
     }
@@ -70,7 +73,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: fork from fromSeq=0 in replay mode', () =
       { fromSeq: 0, mode: 'replay' },
     );
 
-    if (fork.status === 501) return; // mode advertised but not implemented; skip-equivalent
+    if (forkDeclined(fork.status, 'replay fork')) return;
     expect(fork.status, driver.describe(
       'rest-endpoints.md POST /v1/runs/{runId}:fork',
       'fork MUST return 201 on accepted replay',
@@ -101,6 +104,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: fork from fromSeq=0 in branch mode with e
   it('produces a new run that reaches terminal `completed`', async (ctx) => {
     const modes = await fetchReplayModes();
     if (!modes.includes('branch')) {
+      softSkip('inapplicable', "host does not advertise the `branch` fork mode — this leg's rule has no path to apply");
       ctx.skip();
       return;
     }
@@ -111,7 +115,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: fork from fromSeq=0 in branch mode with e
       { fromSeq: 0, mode: 'branch', runOptionsOverlay: {} },
     );
 
-    if (fork.status === 501) return; // mode advertised but not implemented; skip-equivalent
+    if (forkDeclined(fork.status, 'branch fork')) return;
     expect(fork.status, driver.describe(
       'rest-endpoints.md POST /v1/runs/{runId}:fork',
       'branch fork MUST return 201',
@@ -137,6 +141,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: validation errors', () => {
   it('rejects negative fromSeq with 400', async (ctx) => {
     const modes = await fetchReplayModes();
     if (modes.length === 0) {
+      softSkip('inapplicable', "host advertises no usable fork mode for this leg");
       ctx.skip();
       return;
     }
@@ -155,6 +160,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: validation errors', () => {
   it('rejects fromSeq beyond source event log length with 422', async (ctx) => {
     const modes = await fetchReplayModes();
     if (modes.length === 0) {
+      softSkip('inapplicable', "host advertises no usable fork mode for this leg");
       ctx.skip();
       return;
     }
@@ -179,6 +185,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: validation errors', () => {
       // → 400) only applies on hosts that advertise the `replay` mode.
       // A `branch`-only host has no path to even attempt the request.
       // Visible skip rather than silent vacuous pass.
+      softSkip('inapplicable', "host does not advertise the `replay` fork mode — the runOptionsOverlay rejection rule only applies to hosts that do");
       ctx.skip();
       return;
     }
@@ -200,6 +207,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay: validation errors', () => {
   it('rejects fork on a non-existent run with 404', async (ctx) => {
     const modes = await fetchReplayModes();
     if (modes.length === 0) {
+      softSkip('inapplicable', "host advertises no usable fork mode for this leg");
       ctx.skip();
       return;
     }

package/src/scenarios/replay-side-effect-suppression.test.ts

@@ -48,6 +48,7 @@ import { describe, it, expect } from 'vitest';
 import { recordRequirement } from '../lib/requirement-ledger.js';
 import { requirementIdForScenario } from '../lib/requirement-registry.js';
 import { driver } from '../lib/driver.js';
+import { forkDeclined } from '../lib/fork-availability.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { readFileSync } from 'node:fs';
@@ -173,8 +174,8 @@ describe.skipIf(SKIP_NO_FIXTURE)('replay-side-effect-suppression: a replay does
     const fork = await driver.post(`/v1/runs/${encodeURIComponent(sourceRunId)}:fork`, {
       mode: 'replay',
     });
-    if (fork.status === 501) {
-      ctx.skip(); // advertised but not implemented for this range — suite convention
+    if (forkDeclined(fork.status, 'side-effect-suppression replay fork')) {
+      ctx.skip();
       return;
     }
     expect(fork.status, 'fork should be accepted').toBe(201);

package/src/scenarios/replayDeterminism.test.ts

@@ -18,6 +18,8 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { forkDeclined } from '../lib/fork-availability.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 
@@ -69,7 +71,7 @@ function structuralShape(events: readonly RawEvent[]): Array<{ type: unknown; no
 describe('replay-determinism: openwop-replay-fork profile gate', () => {
   it('host advertising replay.supported MUST also advertise replay.modes', async () => {
     const replay = await fetchReplayCapability();
-    if (replay === null || replay.supported !== true) return; // skip-equivalent
+    if (replay === null || replay.supported !== true) return softSkip('inapplicable', 'host does not advertise `replay.supported: true` — the replay contract does not apply to it');
 
     expect(Array.isArray(replay.modes), driver.describe(
       'spec/v1/replay.md',
@@ -91,8 +93,8 @@ describe.skipIf(SKIP_NO_NOOP)('replay-determinism: same fromSeq + same workflow
     'two replay forks of the same point produce structurally-identical event lists',
     async () => {
       const replay = await fetchReplayCapability();
-      if (replay === null || replay.supported !== true) return; // host doesn't claim replay
-      if (!Array.isArray(replay.modes) || !replay.modes.includes('replay')) return; // mode not supported
+      if (replay === null || replay.supported !== true) return softSkip('inapplicable', 'host does not advertise `replay.supported: true` — the replay contract does not apply to it');
+      if (!Array.isArray(replay.modes) || !replay.modes.includes('replay')) return softSkip('inapplicable', 'host advertises replay but not the `replay` mode — this leg is out of scope for it');
 
       // Phase 1: complete an original run.
       const create = await driver.post('/v1/runs', { workflowId: NOOP_WORKFLOW_ID });
@@ -105,7 +107,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay-determinism: same fromSeq + same workflow
         mode: 'replay',
         fromSeq: 0,
       });
-      if (fork1.status === 501) return; // mode not implemented; skip-equivalent
+      if (forkDeclined(fork1.status, 'determinism fork 1')) return;
       expect(fork1.status, driver.describe(
         'spec/v1/replay.md',
         'POST /v1/runs/{runId}:fork with mode=replay MUST return 201',
@@ -118,7 +120,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay-determinism: same fromSeq + same workflow
         mode: 'replay',
         fromSeq: 0,
       });
-      if (fork2.status === 501) return;
+      if (forkDeclined(fork2.status, 'determinism fork 2')) return;
       expect(fork2.status).toBe(201);
       const fork2Id = (fork2.json as { runId: string }).runId;
       await pollUntilTerminal(fork2Id, { timeoutMs: 10_000 });
@@ -152,7 +154,7 @@ describe.skipIf(SKIP_NO_NOOP)('replay-determinism: same fromSeq + same workflow
 describe.skipIf(SKIP_NO_NOOP)('replay-determinism: branch-mode is permitted to diverge', () => {
   it('branch mode does NOT need to produce identical event sequences (negative-control)', async () => {
     const replay = await fetchReplayCapability();
-    if (replay === null || replay.supported !== true) return;
+    if (replay === null || replay.supported !== true) return softSkip('inapplicable', 'host does not advertise `replay.supported: true` — the replay contract does not apply to it');
     if (!Array.isArray(replay.modes) || !replay.modes.includes('branch')) return;
 
     // Self-test on the spec interpretation: branch and replay are