@openwop/openwop-conformance 1.136.11 → 1.139.0

package/src/scenarios/durability-poison-exhaustion.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Poison work reaches a bounded, operator-visible terminal state
+ * (RFC 0158 §C.8, conformance row `durability/poison-exhaustion`).
+ *
+ * THE REQUIREMENT: work that fails deterministically **MUST** reach a terminal,
+ * operator-visible state within a bounded number of attempts, and **MUST NOT**
+ * be redelivered indefinitely.
+ *
+ * ── Why the obvious assertion proves only half of it ─────────────────────────
+ * "The run reached `failed`" is the half everyone writes, and `failure-path.
+ * test.ts` already covers it. It says nothing about the second clause: a host
+ * that redelivers forever ALSO reports a terminal status at some point, or
+ * reports one while the work keeps being re-dispatched behind it. An assertion
+ * that stops at the terminal status cannot distinguish "terminated after N
+ * attempts" from "still going".
+ *
+ * So the load-bearing leg here is STABILITY AFTER TERMINAL: count the attempts
+ * on the run's own log, wait a scaled quiet window, count again, and assert the
+ * number did not move. A host still redelivering shows new attempts; a host that
+ * stopped shows the same count. That is the falsifiable form of "MUST NOT be
+ * redelivered indefinitely" — and, unlike a ceiling, it needs no number the wire
+ * does not carry (see below).
+ *
+ * ── What this scenario deliberately does NOT assert ──────────────────────────
+ * Conformance to a SPECIFIC declared attempt bound. RFC 0158 §E mints no
+ * advertised capability field, so a host's declared bound is not on the wire and
+ * the suite cannot read it. Asserting against a number the suite invented would
+ * be a bound of the suite's own making, which is the inverse of the §B.5
+ * discipline ("derived from the mechanism that enforces it"). When
+ * `OPENWOP_DECLARED_ATTEMPT_BOUND` is supplied by the operator — the same
+ * operator-supplied-input shape as `OPENWOP_OPTED_OUT_PROFILES` — the ceiling leg
+ * runs too. Without it, boundedness is still asserted; only the specific bound is
+ * not.
+ *
+ * ── Honest about its gating ──────────────────────────────────────────────────
+ * This is NOT a pure black-box scenario. Attempt counts live on the run's event
+ * log, which is read through the EXISTING `/v1/host/sample/test/runs/{runId}/
+ * events` seam — no new seam, but a seam. A host that has not wired it records
+ * `blocked`: unobservable, not unmet. Outside every profile floor, for the same
+ * reason.
+ *
+ * @see RFCS/0158-durable-execution-and-disaster-recovery-qualification.md §C.8
+ * @see spec/v1/host-sample-test-seams.md
+ */
+
+import { describe, expect, it } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal, scaledTimeoutMs } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { queryTestEvents, requireEvents } from '../lib/event-log-query.js';
+import { recordRequirement } from '../lib/requirement-ledger.js';
+import { requirementIdForFile } from '../lib/scenario-disposition.js';
+
+const WORKFLOW_ID = 'conformance-failure';
+const FILE = 'durability-poison-exhaustion.test.ts';
+const REQ = requirementIdForFile(FILE);
+
+/** Attempt-bearing event types. A `node.started` is attempt 1; each
+ *  `node.retried` is one more. Counting BOTH means a host that re-dispatches
+ *  without emitting `node.retried` is still caught. */
+const ATTEMPT_TYPES = new Set(['node.started', 'node.retried']);
+
+/** How long to watch for further attempts after the run reports terminal.
+ *  Scaled: a longer wait is a STRONGER claim here, because it is a wait for
+ *  something that must not happen. */
+const QUIET_WINDOW_MS = 4_000;
+
+function declaredAttemptBound(): number | null {
+  const raw = process.env['OPENWOP_DECLARED_ATTEMPT_BOUND'];
+  if (raw === undefined || raw.trim() === '') return null;
+  const n = Number(raw);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+// Recorded at MODULE scope, not inside the `it`. `describe.skipIf` never runs the
+// callback, so a `recordRequirement` in the test body is dead code on exactly the
+// path it exists to classify — the same shape as the note written after
+// `ctx.skip()` threw, which left seven files carrying notes the ledger never saw.
+// Caught by reading a CI log: this file and `failure-path.test.ts` both skipped
+// against the postgres host, which does not advertise the fixture, and the row
+// would have been recorded `blocked` with the unclassified-return marker instead
+// of `inapplicable` with a reason.
+if (SKIP_NO_FIXTURE) {
+  recordRequirement(REQ, 'inapplicable', `fixture ${WORKFLOW_ID} not advertised`);
+}
+
+describe.skipIf(SKIP_NO_FIXTURE)('RFC 0158 §C.8 — poison work terminates within a bounded number of attempts', () => {
+  it('reaches terminal AND stops being retried, asserted on the log rather than on the status alone', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: WORKFLOW_ID });
+    expect(create.status, driver.describe(
+      'rest-endpoints.md',
+      'POST /v1/runs MUST return 201 even for work that fails at runtime',
+    )).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    // ── First clause: a terminal, OPERATOR-VISIBLE state ─────────────────────
+    const terminal = await pollUntilTerminal(runId);
+    expect(terminal.status, driver.describe(
+      'RFC 0158 §C.8',
+      'deterministically failing work MUST reach a terminal, operator-visible state',
+    )).toBe('failed');
+
+    // ── The seam gate comes AFTER the control above, so a host that wired the
+    //    fixture but not the log still proves the fixture ran. ───────────────
+    const first = await queryTestEvents(runId);
+    if (!first.ok) {
+      const why = first.reason === 'seam_unavailable'
+        ? 'event-log seam /v1/host/sample/test/runs/{runId}/events not wired — attempts are unobservable'
+        : `event-log seam returned HTTP ${first.status}`;
+      recordRequirement(REQ, 'blocked', why);
+      return softSkip('blocked', why);
+    }
+
+    const events = requireEvents(first, 'RFC 0158 §C.8 attempt counting');
+    // Non-vacuity: the failure must actually be ON the log. Without this, a host
+    // returning an empty array would sail through every count comparison below,
+    // since 0 === 0 after any wait.
+    expect(events.some((e) => e.type === 'node.failed'), driver.describe(
+      'RFC 0158 §C.8',
+      'the run log MUST record the deterministic failure — an empty log makes every attempt count vacuous',
+    )).toBe(true);
+
+    const attemptsBefore = events.filter((e) => ATTEMPT_TYPES.has(e.type)).length;
+    expect(attemptsBefore, driver.describe(
+      'RFC 0158 §C.8',
+      'at least one attempt MUST be recorded — zero attempts means nothing was delivered',
+    )).toBeGreaterThan(0);
+
+    // ── Second clause, the load-bearing one: NOT redelivered indefinitely ────
+    await new Promise((r) => setTimeout(r, scaledTimeoutMs(QUIET_WINDOW_MS)));
+    const second = await queryTestEvents(runId);
+    const after = requireEvents(second, 'RFC 0158 §C.8 attempt counting (post-terminal)');
+    const attemptsAfter = after.filter((e) => ATTEMPT_TYPES.has(e.type)).length;
+
+    expect(attemptsAfter, driver.describe(
+      'RFC 0158 §C.8',
+      'attempts MUST NOT continue after the run reports terminal — a host still redelivering records more',
+    )).toBe(attemptsBefore);
+
+    // ── Optional ceiling, only when the operator supplies the declared bound ─
+    const bound = declaredAttemptBound();
+    if (bound !== null) {
+      expect(attemptsAfter, driver.describe(
+        'RFC 0158 §C.8 + §B.5',
+        'total attempts MUST NOT exceed the operator-declared attempt bound',
+      )).toBeLessThanOrEqual(bound);
+    }
+
+    recordRequirement(REQ, 'executed-pass', undefined, { assertionCount: bound === null ? 5 : 6 });
+  });
+});

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

@@ -0,0 +1,328 @@
+/**
+ * Host-initiated fan-out is an external effect (`replay.md` §"Host-initiated
+ * fan-out is an external effect").
+ *
+ * THE MUST NOT: a host that projects its event log outward — webhook delivery,
+ * outbound streams, analytics or audit sinks — MUST NOT emit those outbound
+ * deliveries for events a `mode: "replay"` fork re-emits as fixed history.
+ *
+ * WHY THIS SCENARIO EXISTS. Until now this was the largest normative MUST NOT on
+ * the replay surface with **no conformance scenario and no SECURITY invariant**.
+ * Two hosts had it deployed and the interop matrix still had to record it as
+ * *not suite-witnessed*, because both rows rested on the hosts' own tests. A
+ * host's own test is evidence about that host; it is not a witness of the wire.
+ *
+ * WHY IT IS OBSERVABLE AT ALL, unlike some other unmeasured invariants: the
+ * outbound side has a real probe surface. The suite can BE the subscriber — boot
+ * a local receiver, register it via `POST /v1/webhooks`, and read what actually
+ * arrives. The property is stated over exactly what a subscriber sees, so this
+ * asserts the thing itself rather than an adjacent proxy.
+ *
+ * ── The positive control is not decoration here; it is the whole test ────────
+ * "No delivery arrived" passes identically when delivery never worked at all: a
+ * mistyped URL, a subscription that was never created, a host that rejected the
+ * receiver, a fixture that emitted nothing. That is a vacuous witness in its
+ * purest form. So all three legs run in ONE test against ONE receiver and ONE
+ * subscription, and the absence is only ever asserted AFTER presence has been
+ * proven on that exact wiring. Do not split this into separate `it` blocks —
+ * separate blocks re-register, and a re-registration that silently fails turns
+ * the negative leg back into a vacuous pass.
+ *
+ * ── Why the timeout knob makes this leg STRICTER, not looser ─────────────────
+ * Absence has nothing to poll for, so the negative is "nothing arrived within
+ * N". `OPENWOP_POLL_TIMEOUT_SCALE` multiplies N. The reflex on seeing a timeout
+ * multiplier is that it weakens assertions — here it is the reverse: waiting
+ * longer for a delivery that must never come is a STRONGER claim, and an
+ * operator raising the scale on a slow host makes this scenario harder to pass,
+ * not easier.
+ *
+ * ── Deliberately NOT in the `openwop-replay-fork` floor ──────────────────────
+ * This scenario needs the host to accept a loopback receiver. A host with an
+ * SSRF guard on `POST /v1/webhooks` correctly refuses one, and the suite's
+ * standing operator contract asks such hosts for an opt-in
+ * (`OPENWOP_WEBHOOK_ALLOW_PRIVATE=true` on the SQLite reference). At least one
+ * certifying host rejects it today. Putting a receiver-gated row in that
+ * profile's floor would make the profile un-certifiable for a host whose
+ * SECURITY CONTROL IS CORRECT, and would read in the matrix as a regression that
+ * is not one. Capability-gated, outside the floor. Moving it into a floor is a
+ * separate decision needing an RFC 0148 §C argument.
+ *
+ * ── One interpretive call, stated rather than buried ─────────────────────────
+ * The subscription below is for `run.completed`. That is a LIFECYCLE event, and
+ * `replay.md` notes lifecycle events are "ambiguous noise" next to a
+ * recorded-fact event like `memory.written`, which is "a false statement". The
+ * reading applied here is that a replay fork reproduces the source's log, so the
+ * `run.completed` in the fork's log is RE-EMITTED HISTORY and therefore squarely
+ * inside "any event re-emitted as fixed history is in scope". A host that
+ * suppressed only recorded-fact events while delivering re-emitted lifecycle
+ * events would fail this scenario.
+ *
+ * That reading is no longer an inference: `replay.md` was clarified on
+ * 2026-08-19 to say the contrast RANKS THE HARM and does not narrow the scope,
+ * because the requirement above it already decides the question — replay-ness is
+ * read from the run, never from the event type, so suppressing by event type is
+ * selecting by event type. The paragraph stays here because a host that reads
+ * the older text should meet a visible claim rather than a surprise red.
+ *
+ * @see spec/v1/replay.md §"Host-initiated fan-out is an external effect"
+ * @see spec/v1/webhooks.md §"Register"
+ */
+
+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 { 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';
+import { recordRequirement } from '../lib/requirement-ledger.js';
+import { requirementIdForFile } from '../lib/scenario-disposition.js';
+
+/**
+ * RFC 0148 §A — the MUST NOT gets its OWN disposition, separate from the file's.
+ *
+ * Without this the file would be recorded `executed-pass` off leg 1's assertions
+ * even on a run where the fork returned 501 and the MUST NOT was never
+ * exercised. That is a partial witness reading as a full one: the positive
+ * control genuinely passed, so the file is not lying, but the matrix cell for
+ * this requirement would claim coverage the run did not produce. Recording the
+ * requirement explicitly at every exit keeps the cell honest whichever path is
+ * taken. `setup.ts` records the file's aggregate under the SAME id and catches
+ * the resulting conflict — "a scenario that recorded its own file id first
+ * wins" — so this is the sanctioned override, not a second row.
+ *
+ * It MUST be `requirementIdForFile`, not `requirementIdForScenario`. Those two
+ * agree only for files in a certification FLOOR; for a non-floor scenario like
+ * this one they differ (`openwop.scenario.<name>` vs the registry id). Recording
+ * the registry id here would mint an ORPHAN requirement nothing reads, while the
+ * row the bundle actually carries kept the file-level `executed-pass` — a fix
+ * that changes nothing and looks like it did.
+ */
+const REQUIREMENT_ID = requirementIdForFile('replay-fanout-suppression.test.ts');
+
+interface Delivered {
+  readonly body: string;
+}
+
+async function startReceiver(): Promise<{ server: Server; url: string; received: Delivered[] }> {
+  const received: Delivered[] = [];
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c: Buffer) => chunks.push(c));
+    req.on('end', () => {
+      received.push({ body: Buffer.concat(chunks).toString('utf8') });
+      res.writeHead(204);
+      res.end();
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+  const addr = server.address();
+  if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
+  return { server, url: `http://127.0.0.1:${addr.port}/`, received };
+}
+
+let activeServer: Server | null = null;
+afterEach(async () => {
+  if (activeServer) {
+    await new Promise<void>((resolve) => activeServer!.close(() => resolve()));
+    activeServer = null;
+  }
+});
+
+/** Deliveries whose body mentions this run id — the fan-out attributable to it. */
+function forRun(received: readonly Delivered[], runId: string): Delivered[] {
+  return received.filter((d) => d.body.includes(runId));
+}
+
+/**
+ * Wait `ms`, then report what arrived. Used for the NEGATIVE leg, where there is
+ * no event to poll for. Scaled, per the note in the file header.
+ */
+async function quietWindow(ms: number): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, scaledTimeoutMs(ms)));
+}
+
+/** Grace for fire-and-forget delivery on the POSITIVE legs. */
+const DELIVERY_GRACE_MS = 1_500;
+/**
+ * How long the replay fork is watched for a delivery that must never arrive.
+ * Deliberately several times the positive grace: a host that merely DELAYS
+ * fan-out rather than suppressing it must not pass by being slow.
+ */
+const SUPPRESSION_WINDOW_MS = 6_000;
+
+describe('replay-fanout-suppression: a replay fork MUST NOT fan out re-emitted events', () => {
+  it('delivers for a live run, suppresses for a replay fork, and delivers again for a branch fork', async (ctx) => {
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = discoveryFamilies(disco.json) as {
+      webhooks?: { supported?: boolean };
+      replay?: { fork?: boolean; supported?: boolean };
+    };
+    if (caps.webhooks?.supported !== true) {
+      recordRequirement(REQUIREMENT_ID, 'inapplicable', 'host does not advertise webhooks.supported — outbound fan-out has no probe surface on this host');
+      return softSkip('inapplicable', '[replay-fanout-suppression] host does not advertise webhook support');
+    }
+    if (!isFixtureAdvertised('conformance-noop')) {
+      recordRequirement(REQUIREMENT_ID, 'inapplicable', 'conformance-noop fixture not advertised — no run to fan out');
+      return softSkip('inapplicable', '[replay-fanout-suppression] conformance-noop not advertised');
+    }
+
+    const receiver = await startReceiver();
+    activeServer = receiver.server;
+
+    const ownedTenant = await discoverOwnedTenant(driver);
+    const reg = await driver.post('/v1/webhooks', {
+      url: receiver.url,
+      events: ['run.completed'],
+      ...(ownedTenant ? { tenantId: ownedTenant } : {}),
+    });
+    if (reg.status === 400 && (reg.json as { error?: string }).error === 'webhook_url_rejected') {
+      // The host's SSRF guard refused a loopback destination. That is CORRECT
+      // host behaviour, not a failure — see the floor note in the file header.
+      recordRequirement(
+        REQUIREMENT_ID,
+        'blocked',
+        "precondition not met — body.error === 'webhook_url_rejected'; the host's SSRF guard refused the loopback "
+          + 'receiver, which is correct host behaviour, so this requirement is unobservable rather than unmet',
+      );
+      return softSkip(
+        'blocked',
+        '[replay-fanout-suppression] host SSRF guard rejected the loopback receiver; '
+          + 'set OPENWOP_WEBHOOK_ALLOW_PRIVATE=true on the host (or equivalent) to run',
+      );
+    }
+    expect(reg.status, driver.describe(
+      'webhooks.md §"Register"',
+      'POST /v1/webhooks MUST return 201 on success',
+    )).toBe(201);
+
+    // ── LEG 1 — POSITIVE CONTROL. Prove this wiring delivers at all. ─────────
+    const create = await driver.post('/v1/runs', { workflowId: 'conformance-noop' });
+    expect(create.status, 'failed to start conformance-noop').toBe(201);
+    const sourceRunId = (create.json as { runId: string }).runId;
+    await pollUntilTerminal(sourceRunId, { timeoutMs: 10_000 });
+    await quietWindow(DELIVERY_GRACE_MS);
+
+    expect(
+      forRun(receiver.received, sourceRunId).length,
+      driver.describe(
+        'webhooks.md §"Register"',
+        'POSITIVE CONTROL: the host must deliver the source run\'s events to this receiver — '
+          + 'without this, every "no delivery" assertion below is vacuous',
+      ),
+    ).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 (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 ${replay.status} — the re-emission this requirement is stated over never happened, `
+          + 'so the absence of deliveries below would prove nothing',
+      );
+      ctx.skip();
+      return;
+    }
+    expect(replay.status, 'replay fork should be accepted').toBe(201);
+    const replayRunId = (replay.json as { runId: string }).runId;
+    await pollUntilTerminal(replayRunId, { timeoutMs: 30_000 });
+    await quietWindow(SUPPRESSION_WINDOW_MS);
+
+    expect(
+      forRun(receiver.received, replayRunId).map((d) => d.body.slice(0, 200)),
+      driver.describe(
+        'replay.md §"Host-initiated fan-out is an external effect"',
+        'a mode:"replay" fork MUST NOT emit outbound deliveries for the events it re-emits as fixed history — '
+          + 'delivering one asserts to a subscriber that something happened in this run which did not',
+      ),
+    ).toEqual([]);
+
+    // Guard against the OTHER vacuity: a fork that emitted nothing at all would
+    // also deliver nothing. The fork's own log MUST still carry the re-emitted
+    // events (`replay.md`: suppression is outbound-only, the fork's event log
+    // still carries them). Without this, a host that simply failed the fork
+    // would pass leg 2.
+    const forkEvents = await driver.get(`/v1/runs/${encodeURIComponent(replayRunId)}/events`);
+    expect(forkEvents.status, 'fork events must be readable').toBe(200);
+    const forkEventList = (forkEvents.json as { events?: { type?: string }[] }).events ?? [];
+    expect(
+      forkEventList.length,
+      driver.describe(
+        'replay.md §"Host-initiated fan-out is an external effect"',
+        'suppression is OUTBOUND ONLY — the fork\'s own event log MUST still carry the re-emitted events, '
+          + 'so an empty fork log means leg 2 proved nothing',
+      ),
+    ).toBeGreaterThan(0);
+
+    // The MUST NOT has now been exercised against wiring proven to deliver, on a
+    // fork proven to have re-emitted. Recorded here rather than after leg 3,
+    // because leg 3 pins the boundary and may legitimately not run.
+    recordRequirement(REQUIREMENT_ID, 'executed-pass', undefined, { assertionCount: 4 });
+
+    // ── LEG 3 — the boundary. `branch` is explicitly OUT of scope. ───────────
+    // This is what distinguishes "reads replay-ness from the RUN" from "silences
+    // anything that is a fork". A host that suppressed both would pass legs 1-2
+    // and be wrong: a branch fork's events are new facts and its effects are the
+    // ones the operator asked for.
+    const branch = await driver.post(`/v1/runs/${encodeURIComponent(sourceRunId)}:fork`, {
+      mode: 'branch',
+    });
+    if (branch.status === 501 || branch.status === 400) {
+      // branch not offered on this range — leg 2 still stands on its own.
+      return;
+    }
+    expect(branch.status, 'branch fork should be accepted').toBe(201);
+    const branchRunId = (branch.json as { runId: string }).runId;
+    await pollUntilTerminal(branchRunId, { timeoutMs: 30_000 });
+    await quietWindow(DELIVERY_GRACE_MS);
+
+    expect(
+      forRun(receiver.received, branchRunId).length,
+      driver.describe(
+        'replay.md §"Host-initiated fan-out is an external effect"',
+        'a branch fork is deliberately OUT of scope — its events are new facts, so suppressing them '
+          + 'means the host keyed on "is a fork" rather than on replay-ness read from the run',
+      ),
+    ).toBeGreaterThan(0);
+  });
+});

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);