@openwop/openwop-conformance 2.0.0-rc.6 → 2.0.0-rc.61

package/src/scenarios/v2-run-bulk-cancel.test.ts

@@ -0,0 +1,91 @@
+/**
+ * `spec/v2/core/runs.md` §Cancel — `bulkCancelRuns` (suite 2.0.0, target major 2;
+ * unaided).
+ *
+ * Legs:
+ *   1. over the cap: 101 syntactically valid tenant-bound ids MUST be refused
+ *      `400 validation_error` with `details.maxRunIds` (creates nothing);
+ *   2. `[own, foreign-tenant, own]` MUST answer `200 { results[] }` in request
+ *      order even when every entry failed; the foreign entry is `ok: false` with
+ *      an error envelope in the entry — never a top-level 403. The prose names
+ *      `run_forbidden` for a run the caller cannot see while identity.md §5 names
+ *      `id_tenant_mismatch` / `not_found` for a foreign tenant segment; the leg
+ *      accepts any of the three and the disagreement is filed (finding 3). An
+ *      own entry on an already-terminal noop is `ok: true` with
+ *      `cancelling | cancelled` or `ok: false` with `run_terminal` (finding 1).
+ *
+ * The foreign id matches the runId grammar, so a 400 on leg 2 is a host defect,
+ * not body validation.
+ *
+ * @see spec/v2/core/runs.md §Cancel
+ * @see spec/v2/core/identity.md §5
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0170.run-bulk-cancel';
+const DOC = 'spec/v2/core/runs.md §Cancel';
+const NOOP = 'conformance-noop';
+const FOREIGN = 'openwop-conformance-foreign-tenant/foreignopaque0123456789abcdef';
+
+async function discovery(): Promise<Record<string, unknown> | null> { try { return await v2Discovery(); } catch { return null; } }
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+async function create(): Promise<{ runId: string } | { reason: string }> {
+  const res = await http(() => driver.post('/runs', { workflowId: NOOP }));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | null)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs answered ${res.status} ${readErrorCode(res.json) ?? ''} — create refused`.trim() };
+  return { runId };
+}
+interface Entry { runId?: unknown; ok?: unknown; status?: unknown; error?: unknown }
+
+describe('v2 run-bulk-cancel (runs.md §Cancel)', () => {
+  it('101 ids are refused 400 validation_error with details.maxRunIds', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const runIds = Array.from({ length: 101 }, (_, i) => `openwop-conformance-bulk-cap/opaque${String(i).padStart(3, '0')}0123456789abcdef`);
+    const res = await http(() => driver.post('/runs:bulk-cancel', { runIds }));
+    if (res === null) return softSkip('blocked', 'POST /runs:bulk-cancel unreachable (fetch failed)');
+    if (res.status === 404) return softSkip('blocked', 'POST /runs:bulk-cancel answered 404 — bulkCancelRuns is a core operation (runs.md §Surface) and is not mounted');
+    expect(res.status, req(ID, DOC, `over the cap (RECOMMENDED 100) the host MUST answer 400 — got ${res.status}`)).toBe(400);
+    expect(readErrorCode(res.json), req(ID, DOC, 'the refusal MUST be validation_error')).toBe('validation_error');
+    // The v2 envelope is { error: <code>, message, details? } — `details` at the ROOT
+    // (schemas/v2/error-envelope.schema.json). rc.48/rc.49 read `error.details`
+    // and reported a host defect that was this reader's; retracted in rc.50.
+    const max = (res.json as { details?: { maxRunIds?: unknown } } | null)?.details?.maxRunIds;
+    expect(typeof max === 'number' && max >= 1 && max <= 100, req(ID, DOC, `details.maxRunIds MUST state the cap (got ${String(max)})`)).toBe(true);
+  });
+
+  it('results[] come back in request order, each id processed independently, a foreign id refused in its entry and never as a top-level 403', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const a = await create(); if ('reason' in a) return softSkip('blocked', a.reason);
+    const b = await create(); if ('reason' in b) return softSkip('blocked', b.reason);
+    const runIds = [a.runId, FOREIGN, b.runId];
+    const res = await http(() => driver.post('/runs:bulk-cancel', { runIds, reason: 'conformance' }));
+    if (res === null) return softSkip('blocked', 'POST /runs:bulk-cancel unreachable (fetch failed)');
+    if (res.status === 404) return softSkip('blocked', 'POST /runs:bulk-cancel answered 404 — not mounted');
+    expect(res.status, req(ID, DOC, `bulkCancelRuns MUST answer 200 even when entries fail — a foreign id MUST NOT surface as a top-level ${res.status} ${readErrorCode(res.json) ?? ''}`.trim())).toBe(200);
+    const results = (res.json as { results?: unknown } | null)?.results;
+    expect(Array.isArray(results) && results.length === 3, req(ID, DOC, `results[] MUST carry one entry per requested id (got ${Array.isArray(results) ? results.length : typeof results})`)).toBe(true);
+    const entries = results as Entry[];
+    expect(entries.map((e) => e.runId), req(ID, DOC, 'results[] MUST be in request order')).toEqual(runIds);
+    const foreign = entries[1]!;
+    expect(foreign.ok, req(ID, DOC, 'the foreign-tenant entry MUST be ok: false')).toBe(false);
+    // An entry's `error` IS the error envelope (api/v2/openapi.yaml: `$ref error-envelope`):
+    // { error: <code>, message, details? } nested under the entry — so the code is
+    // `entry.error.error`, read the same way as a top-level envelope.
+    const env = v2Validator('error-envelope')(foreign.error);
+    expect(env.ok, req(ID, 'api/v2/openapi.yaml bulkCancelRuns results[].error', `an ok: false entry's error MUST be the error envelope { error: <code>, message, details? } (schemas/v2/error-envelope.schema.json; the OpenAPI $refs it for results[].error) — got ${JSON.stringify(foreign.error)}: ${env.errors}`)).toBe(true);
+    const fcode = String(readErrorCode(foreign.error));
+    expect(['id_tenant_mismatch', 'not_found'].includes(fcode), req(ID, 'spec/v2/core/identity.md §5', `an id whose tenant segment is not the caller's MUST be refused inside the entry with id_tenant_mismatch (or not_found where existence is not leaked) — identity.md §5 applies inside a bulk entry exactly as on a path; run_forbidden is for a same-tenant run the caller may not cancel — got ${fcode}`)).toBe(true);
+    for (const own of [entries[0]!, entries[2]!]) {
+      const okShape = own.ok === true && ['cancelling', 'cancelled'].includes(String(own.status));
+      const terminalShape = own.ok === false && readErrorCode(own.error) === 'run_terminal';
+      expect(okShape || terminalShape, req(ID, DOC, `an own entry MUST be ok: true with cancelling|cancelled, or ok: false run_terminal when the noop already completed — got ${JSON.stringify(own)}`)).toBe(true);
+    }
+  });
+});

package/src/scenarios/v2-run-cancel.test.ts

@@ -0,0 +1,97 @@
+/**
+ * `spec/v2/core/runs.md` §Cancel — `cancelRun` (suite 2.0.0, target major 2).
+ *
+ * Witness class: witnessable — the positive leg is gated on the
+ * `conformance-cancellable` fixture (a run that stays `running` for `delayMs`);
+ * the terminal-run leg is unaided.
+ *
+ * Legs:
+ *   1. cancelling a run that is already terminal — `runs.md` §Cancel is SILENT
+ *      on this case; the registry has `run_terminal` (409) and 200-idempotent is
+ *      the other defensible answer. The leg accepts either, records which, and
+ *      the ambiguity is filed for the prose (rc.48 CHANGELOG, finding 1).
+ *   2. on `conformance-cancellable`: `POST /runs/{runId}/cancel` on a running
+ *      run answers `200 { runId, status: cancelling | cancelled }`; `run.cancelled`
+ *      is in the log within 5 s; the snapshot reads `cancelled`.
+ *
+ * Until rc.48 nothing at major 2 witnessed §Cancel at all — runs.md carried 61
+ * MUSTs and 12 witness sites, every one under §Create.
+ *
+ * @see spec/v2/core/runs.md §Cancel
+ * @see conformance/fixtures.md §conformance-cancellable
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0170.run-cancel';
+const DOC = 'spec/v2/core/runs.md §Cancel';
+const NOOP = 'conformance-noop';
+const CANCELLABLE = 'conformance-cancellable';
+
+async function discovery(): Promise<Record<string, unknown> | null> { try { return await v2Discovery(); } catch { return null; } }
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+
+async function create(body: Record<string, unknown>): Promise<{ runId: string } | { reason: string }> {
+  const res = await http(() => driver.post('/runs', body));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | null)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs answered ${res.status} ${readErrorCode(res.json) ?? ''} — create refused`.trim() };
+  return { runId };
+}
+async function statusOf(runId: string): Promise<string | null> {
+  const res = await http(() => driver.get(`/runs/${enc(runId)}`));
+  return res?.status === 200 ? String((res.json as { status?: unknown } | null)?.status ?? '') : null;
+}
+async function waitFor(runId: string, pred: (s: string) => boolean, ms: number): Promise<string | null> {
+  const t0 = Date.now(); let last: string | null = null;
+  while (Date.now() - t0 < ms) { last = await statusOf(runId); if (last !== null && pred(last)) return last; await new Promise((r) => setTimeout(r, 250)); }
+  return last;
+}
+async function eventTypes(runId: string): Promise<string[] | null> {
+  const res = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1`));
+  const events = (res?.json as { events?: unknown } | null)?.events;
+  return res?.status === 200 && Array.isArray(events) ? events.map((e) => String((e as { type?: unknown }).type)) : null;
+}
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+describe('v2 run-cancel (runs.md §Cancel)', () => {
+  it('cancelling a terminal run is refused 409 run_terminal', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const c = await create({ workflowId: NOOP });
+    if ('reason' in c) return softSkip('blocked', c.reason);
+    const s = await waitFor(c.runId, (x) => TERMINAL.has(x), 10_000);
+    if (s === null || !TERMINAL.has(s)) return softSkip('blocked', `the noop run did not reach a terminal status within 10 s (last: ${s ?? 'unreadable'})`);
+    const res = await http(() => driver.post(`/runs/${enc(c.runId)}/cancel`, {}));
+    if (res === null) return softSkip('blocked', 'POST /runs/{runId}/cancel unreachable (fetch failed)');
+    const code = readErrorCode(res.json);
+    const status = (res.json as { status?: unknown } | null)?.status;
+    expect(res.status, req(ID, DOC, `a cancel on a run that is already terminal (${s}) MUST be refused 409 run_terminal — got ${res.status} ${code ?? String(status)}; a 200 echoing the terminal state is outside §Cancel's 200 grammar { runId, status: cancelling | cancelled }`)).toBe(409);
+    expect(code, req(ID, DOC, 'the refusal MUST be run_terminal')).toBe('run_terminal');
+  });
+
+  it('cancelling a running run answers 200 with cancelling|cancelled, emits run.cancelled within 5 s, and the snapshot reads cancelled', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    if (!isFixtureAdvertised(CANCELLABLE)) return softSkip('inapplicable', `${CANCELLABLE} fixture not advertised — no run stays running long enough to cancel`);
+    const c = await create({ workflowId: CANCELLABLE, inputs: { delayMs: 15_000 } });
+    if ('reason' in c) return softSkip('blocked', c.reason);
+    const running = await waitFor(c.runId, (x) => x === 'running' || TERMINAL.has(x), 5_000);
+    if (running !== 'running') return softSkip('blocked', `${CANCELLABLE} did not reach running within 5 s (last: ${running ?? 'unreadable'})`);
+    const res = await http(() => driver.post(`/runs/${enc(c.runId)}/cancel`, { reason: 'conformance' }));
+    if (res === null) return softSkip('blocked', 'POST /runs/{runId}/cancel unreachable (fetch failed)');
+    expect(res.status, req(ID, DOC, `cancelRun on a running run MUST answer 200 — got ${res.status} ${readErrorCode(res.json) ?? ''}`.trim())).toBe(200);
+    const body = res.json as { runId?: unknown; status?: unknown } | null;
+    expect(body?.runId, req(ID, DOC, 'the 200 body MUST carry the run\'s runId')).toBe(c.runId);
+    expect(['cancelling', 'cancelled'].includes(String(body?.status)), req(ID, DOC, `status MUST be cancelling or cancelled (got ${String(body?.status)})`)).toBe(true);
+    const final = await waitFor(c.runId, (x) => x === 'cancelled', 5_000);
+    expect(final, req(ID, DOC, `the snapshot MUST read cancelled within 5 s of an accepted cancel (last: ${final ?? 'unreadable'})`)).toBe('cancelled');
+    const types = await eventTypes(c.runId);
+    expect(types?.includes('run.cancelled') ?? false, req(ID, 'spec/v2/core/events.md §run.cancelled', `the log MUST carry run.cancelled once the cascade completes (types: ${(types ?? []).join(', ')})`)).toBe(true);
+  }, 30_000);
+});

package/src/scenarios/v2-run-completed-outputs.test.ts

@@ -0,0 +1,93 @@
+/**
+ * `spec/v2/core/events.md` §Payloads — `run.completed` MUST carry `outputs`
+ * (suite 2.0.0, target major 2; unaided).
+ *
+ * This requirement is one day old, and the reason it needed writing is the
+ * reason this file exists. Both majors' payload schemas NAMED `outputs` on
+ * `runCompleted` and REQUIRED nothing. v1 also left the object open. So a
+ * tier-1 host emitted the singular `output` for its entire life and validated
+ * every time; v2 closing the object caught the EXTRA key — and that is the
+ * only reason anyone looked. Nothing in either major has ever caught an ABSENT
+ * one: a host emitting `run.completed {}` validates in v1 and, until rc.35, in
+ * v2. Seventeen scenario files mention `run.completed`; none read its payload.
+ *
+ * A key that no schema requires and no scenario reads is a requirement that
+ * exists only as a property name — the same shape as `eventLogSchemaVersion`,
+ * which lived in a schema `description` for the life of v1 while two hosts
+ * shipped without it. Asserting the EFFECT (the terminal event of a run that
+ * completed carries an outputs object) is the only form of this check a
+ * permissive emitter cannot satisfy by accident.
+ *
+ * @see spec/v2/core/events.md §Payloads
+ * @see schemas/v2/run-event-payloads.schema.json $defs/runCompleted
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0171.run-completed-outputs';
+const DOC = 'spec/v2/core/events.md §Payloads';
+const NOOP_WORKFLOW_ID = 'conformance-noop';
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+async function createRun(): Promise<{ runId: string } | { reason: string }> {
+  try { if (!(await v2Discovery())) return { reason: 'v2 discovery unreachable' }; } catch { return { reason: 'v2 discovery unreachable' }; }
+  const res = await http(() => driver.post('/runs', { workflowId: NOOP_WORKFLOW_ID }));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | undefined)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {workflowId: ${NOOP_WORKFLOW_ID}} answered ${res.status} ${readErrorCode(res.json) ?? ''} — the smallest valid create was refused (fixture not seeded?)`.trim() };
+  return { runId };
+}
+
+interface Ev { readonly type?: unknown; readonly payload?: unknown }
+
+/** Poll until the terminal event lands. The noop workflow completes in well under a second; the bound is for a slow host, not a slow workflow. */
+async function terminalEvent(runId: string): Promise<{ ev: Ev } | { reason: string }> {
+  let last: string | null = null;
+  for (let i = 0; i < 20; i += 1) {
+    const res = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}/events/poll?timeout=1`));
+    if (res === null) return { reason: 'GET /runs/{runId}/events/poll unreachable (fetch failed)' };
+    if (res.status !== 200) return { reason: `GET /runs/{runId}/events/poll answered ${res.status}` };
+    const events = (res.json as { events?: unknown } | undefined)?.events;
+    if (Array.isArray(events)) {
+      const hit = events.find((e): e is Ev => typeof (e as Ev)?.type === 'string' && (e as Ev).type === 'run.completed');
+      if (hit) return { ev: hit };
+      const failed = events.find((e): e is Ev => typeof (e as Ev)?.type === 'string' && /^run\.(failed|cancelled)$/.test(String((e as Ev).type)));
+      if (failed) return { reason: `the noop run reached ${String(failed.type)} rather than run.completed — nothing to assert outputs on` };
+      last = `${events.length} event(s), none terminal`;
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return { reason: `run.completed never appeared (${last ?? 'no events'}) — the host may not run the noop workflow to completion` };
+}
+
+describe('v2 run-completed-outputs (events.md §Payloads)', () => {
+  it('the run.completed event of a run that completed carries an outputs object', async () => {
+    const c = await createRun();
+    if ('reason' in c) return softSkip('blocked', c.reason);
+    const t = await terminalEvent(c.runId);
+    if ('reason' in t) return softSkip('blocked', t.reason);
+
+    const payload = (t.ev.payload ?? null) as { outputs?: unknown; output?: unknown } | null;
+    expect(
+      payload !== null && typeof payload === 'object',
+      req(ID, DOC, 'run.completed MUST carry a payload object'),
+    ).toBe(true);
+    expect(
+      payload !== null && typeof payload.outputs === 'object' && payload.outputs !== null && !Array.isArray(payload.outputs),
+      req(ID, DOC, `run.completed MUST carry \`outputs\` as an object (an empty object is valid) — a client cannot tell "no outputs" from "outputs not rendered" when the key is absent, and no schema in either major required it until rc.35, which is how a host emitted the singular \`output\` for its whole life. Got keys ${JSON.stringify(payload ? Object.keys(payload) : null)}`),
+    ).toBe(true);
+
+    // The schema now requires it too; assert through the validator so the two
+    // cannot drift apart again without this leg saying which one moved.
+    const r = v2Validator('run-event')(t.ev);
+    expect(r.ok, req(ID, DOC, `the terminal event MUST validate against run-event.schema.json, whose runCompleted payload now requires outputs (${r.errors})`)).toBe(true);
+  });
+});

package/src/scenarios/v2-run-diff-identical.test.ts

@@ -0,0 +1,75 @@
+/**
+ * `spec/v2/core/runs.md` §Diff and ancestry — `diffRun` is a pure function of
+ * the two logs (suite 2.0.0, target major 2; unaided; two runs created, a third
+ * when `conformance-failure` is advertised).
+ *
+ * Identical logs MUST yield `divergedAtSeq: null` and empty `eventDiffs`;
+ * `eventId`, `runId`, `timestamp` and other run-scoped fields MUST be excluded
+ * from the comparison — so two `conformance-noop` runs ARE identical logs.
+ * `diffRun` is OPTIONAL (`404` when absent → inapplicable).
+ *
+ * Controls: the response MUST validate against
+ * `schemas/v2/run-diff-response.schema.json` and echo both ids in `a` / `b`
+ * (a host answering `{}` to any pair fails there); and, when
+ * `conformance-failure` is advertised, a noop-vs-failure diff MUST diverge.
+ * Without that fixture the divergence control records `inapplicable`.
+ *
+ * @see spec/v2/core/runs.md §Diff and ancestry
+ * @see schemas/v2/run-diff-response.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, v2Validator } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0170.run-diff-identical';
+const DOC = 'spec/v2/core/runs.md §Diff and ancestry';
+const NOOP = 'conformance-noop';
+const FAILURE = 'conformance-failure';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+async function discovery(): Promise<Record<string, unknown> | null> { try { return await v2Discovery(); } catch { return null; } }
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+async function createSettled(workflowId: string): Promise<{ runId: string } | { reason: string }> {
+  const res = await http(() => driver.post('/runs', { workflowId }));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | null)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {workflowId: ${workflowId}} answered ${res.status} ${readErrorCode(res.json) ?? ''}`.trim() };
+  const t0 = Date.now();
+  while (Date.now() - t0 < 10_000) {
+    const s = await http(() => driver.get(`/runs/${enc(runId)}`));
+    if (s?.status === 200 && TERMINAL.has(String((s.json as { status?: unknown }).status))) return { runId };
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return { reason: `${workflowId} run ${runId} did not settle within 10 s` };
+}
+interface Diff { a?: unknown; b?: unknown; divergedAtSeq?: unknown; eventDiffs?: unknown }
+
+describe('v2 run-diff-identical (runs.md §Diff and ancestry)', () => {
+  it('two identical logs diff to divergedAtSeq null and empty eventDiffs, in a response that validates and echoes both ids', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const a = await createSettled(NOOP); if ('reason' in a) return softSkip('blocked', a.reason);
+    const b = await createSettled(NOOP); if ('reason' in b) return softSkip('blocked', b.reason);
+    const res = await http(() => driver.get(`/runs/${enc(a.runId)}:diff?against=${enc(b.runId)}`));
+    if (res === null) return softSkip('blocked', 'GET /runs/{runId}:diff unreachable (fetch failed)');
+    if (res.status === 404) return softSkip('inapplicable', 'diffRun is OPTIONAL and answered 404 (runs.md §Surface)');
+    expect(res.status, req(ID, DOC, `diffRun MUST answer 200 — got ${res.status} ${readErrorCode(res.json) ?? ''}`.trim())).toBe(200);
+    const check = v2Validator('run-diff-response')(res.json);
+    expect(check.ok, req(ID, 'schemas/v2/run-diff-response.schema.json', `the response MUST validate: ${check.errors}`)).toBe(true);
+    const d = res.json as Diff;
+    expect([d.a, d.b], req(ID, DOC, 'the response MUST name the two runs it compared')).toEqual([a.runId, b.runId]);
+    expect(d.divergedAtSeq, req(ID, DOC, `identical logs MUST yield divergedAtSeq: null (got ${String(d.divergedAtSeq)}) — eventId, runId, timestamp and other run-scoped fields MUST be excluded from the comparison`)).toBeNull();
+    expect(d.eventDiffs, req(ID, DOC, 'identical logs MUST yield empty eventDiffs')).toEqual([]);
+    if (!isFixtureAdvertised(FAILURE)) return softSkip('inapplicable', `${FAILURE} fixture not advertised — the divergence control (a noop-vs-failure diff MUST diverge) cannot run`);
+    const f = await createSettled(FAILURE); if ('reason' in f) return softSkip('blocked', f.reason);
+    const dv = await http(() => driver.get(`/runs/${enc(a.runId)}:diff?against=${enc(f.runId)}`));
+    if (dv === null || dv.status !== 200) return softSkip('blocked', `the divergence control diff answered ${dv?.status ?? 'no response'}`);
+    const x = dv.json as Diff;
+    expect(typeof x.divergedAtSeq === 'number' && Array.isArray(x.eventDiffs) && x.eventDiffs.length > 0, req(ID, DOC, `a noop log and a failure log MUST diverge (divergedAtSeq ${String(x.divergedAtSeq)}, ${Array.isArray(x.eventDiffs) ? x.eventDiffs.length : 0} diff(s)) — the identical-logs pass above is only evidence if a different pair does not also read identical`)).toBe(true);
+  }, 45_000);
+});

package/src/scenarios/v2-run-fork-prefix.test.ts

@@ -0,0 +1,140 @@
+/**
+ * `spec/v2/core/replay.md` §Endpoint — the fork prefix boundary is EXCLUSIVE
+ * (suite 2.0.0, target major 2; unaided; gated on `replay`; two runs created).
+ *
+ * "Events with `sequence < fromSeq` are fixed history; events `>= fromSeq` are
+ * re-executed." A host that copies `sequence <= fromSeq` inherits one event too
+ * many and re-executes from one event too late.
+ *
+ * Why this file exists. Until rc.60 the only major-2 witness of that boundary
+ * was `v2-fork-a-v1-run`, which is driven through the conformance seam and sits
+ * on the seams floor — so a host that does not advertise the seams profile was
+ * never measured on it, and `v2-run-fork-refusals` (the unaided fork scenario)
+ * asserts only the refusals and never reads the forked log. A tier-1 host
+ * shipped `<= fromSeq` and passed every unaided major-2 scenario; it found the
+ * defect only when fixing 1-based sequence numbering made the off-by-one
+ * visible — two errors cancelling. The v1 scenarios that do check the prefix
+ * (`replay-fork`, `replay-fork-arbitrary`, `feedback-fork-not-copied`) are
+ * `majors: [1]` and never run here.
+ *
+ * The falsifiable shape, chosen to be race-free and implementation-agnostic.
+ * `fromSeq` is placed on a `node.completed` that is not the run's last, so the
+ * source's event AT `fromSeq` is one re-execution cannot honestly reproduce at
+ * that same sequence: an exclusive host restarts that node, and its event at
+ * `fromSeq` is the fresh `node.started`; an inclusive host inherited the
+ * `node.completed` and re-executes from `fromSeq + 1`, so its event at
+ * `fromSeq` is the source's, verbatim. Both logs are read after they settle.
+ *
+ * Measured on the reference host (exclusive) at `fromSeq: 4` of an 8-event
+ * `conformance-multi-node` log: source `4 node.completed b`, fork
+ * `4 node.started b`, fork 9 events to the source's 8 — the fork is LONGER,
+ * because node `b` had started inside the prefix and its completion is
+ * re-executed. Length is therefore not the discriminator and this file does not
+ * assert on it; the event at the boundary is.
+ *
+ * What this file deliberately does NOT assert: the CONTENT of the re-executed
+ * tail, determinism across two forks, timing, and effect re-fire suppression.
+ * Those are `replay.md` §Replay determinism and the seams floor's, witnessed in
+ * `replay-fork-arbitrary` (major 1) and `v2-effect-seam-no-refire` (seams).
+ *
+ * @see spec/v2/core/replay.md §Endpoint
+ * @see spec/v2/core/runs.md §Fork
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, gateFamily } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0170.fork-prefix-boundary';
+const DOC = 'spec/v2/core/replay.md §Endpoint';
+const MULTI = 'conformance-multi-node';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+interface Ev { readonly sequence?: unknown; readonly type?: unknown }
+
+async function discovery(): Promise<Record<string, unknown> | null> { try { return await v2Discovery(); } catch { return null; } }
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+
+/** Every event of a run, in sequence order, read through the poll surface. */
+async function logOf(runId: string): Promise<Ev[] | null> {
+  const res = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1&streamMode=debug`));
+  if (res === null || res.status !== 200) return null;
+  const events = (res.json as { events?: unknown } | undefined)?.events;
+  if (!Array.isArray(events)) return null;
+  return (events as Ev[]).filter((e) => typeof e.sequence === 'number').sort((a, b) => (a.sequence as number) - (b.sequence as number));
+}
+
+/** Poll until the run is terminal or the bound elapses; returns the last status seen. */
+async function settle(runId: string, ms = 20_000): Promise<string | null> {
+  const deadline = Date.now() + ms;
+  let status: string | null = null;
+  while (Date.now() < deadline) {
+    const res = await http(() => driver.get(`/runs/${enc(runId)}`));
+    status = res?.status === 200 ? String((res.json as { status?: unknown } | undefined)?.status ?? '') : status;
+    if (status !== null && TERMINAL.has(status)) return status;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  return status;
+}
+
+describe('v2 run-fork-prefix (replay.md §Endpoint — the boundary is exclusive)', () => {
+  it('a replay fork inherits exactly [0, fromSeq): the event at fromSeq is re-executed, never carried over', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    if (!(await gateFamily('replay'))) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay) — forkRun is gated on replay (runs.md §Surface)');
+    if (!isFixtureAdvertised(MULTI)) return softSkip('inapplicable', `${MULTI} fixture not advertised — no multi-event deterministic run to fork at a mid-log point`);
+
+    const created = await http(() => driver.post('/runs', { workflowId: MULTI }));
+    if (created === null || created.status !== 201) return softSkip('blocked', `POST /runs {workflowId: ${MULTI}} answered ${created?.status ?? 'no response'} ${readErrorCode(created?.json) ?? ''}`.trim());
+    const runId = (created.json as { runId?: unknown }).runId;
+    if (typeof runId !== 'string') return softSkip('blocked', 'the 201 carried no runId');
+
+    const sourceStatus = await settle(runId);
+    if (sourceStatus === null || !TERMINAL.has(sourceStatus)) return softSkip('blocked', `the source run did not settle within 20 s (last status: ${sourceStatus ?? 'unreadable'}) — a mid-log fork point cannot be chosen from an unfinished log`);
+    const source = await logOf(runId);
+    if (source === null) return softSkip('blocked', `GET /runs/{runId}/events/poll did not answer 200 with events[] for the source run`);
+
+    // The fork point: a `node.completed` that is not the run's last event, so
+    // the source's event AT fromSeq is one an honest re-execution cannot
+    // reproduce at that sequence (it restarts the node instead).
+    const seqs = source.map((e) => e.sequence as number);
+    const last = Math.max(...seqs);
+    const point = source.find((e) => e.type === 'node.completed' && (e.sequence as number) > 0 && (e.sequence as number) < last);
+    if (point === undefined) return softSkip('inapplicable', `no node.completed sits strictly inside the ${source.length}-event source log (types: ${[...new Set(source.map((e) => String(e.type)))].join(', ')}) — this host's log shape offers no fork point where an inherited row and a re-executed row are distinguishable`);
+    const fromSeq = point.sequence as number;
+
+    const fork = await http(() => driver.post(`/runs/${enc(runId)}:fork`, { mode: 'replay', fromSeq }));
+    if (fork === null) return softSkip('blocked', 'POST /runs/{runId}:fork unreachable (fetch failed)');
+    if (fork.status === 404) return softSkip('blocked', 'POST /runs/{runId}:fork answered 404 — forkRun is served by a host advertising replay (runs.md §Surface)');
+    expect(fork.status, req(ID, 'spec/v2/core/runs.md §Fork', `a replay fork at a sequence in the source log MUST answer 201 — got ${fork.status} ${readErrorCode(fork.json) ?? ''}`.trim())).toBe(201);
+    const forkId = (fork.json as { runId?: unknown }).runId;
+    if (typeof forkId !== 'string') return softSkip('blocked', 'the fork 201 carried no runId');
+
+    const forkStatus = await settle(forkId);
+    if (forkStatus === null || !TERMINAL.has(forkStatus)) return softSkip('blocked', `the fork did not settle within 20 s (last status: ${forkStatus ?? 'unreadable'}) — the inherited-prefix length is only comparable on a finished log`);
+    const forked = await logOf(forkId);
+    if (forked === null) return softSkip('blocked', 'GET /runs/{runId}/events/poll did not answer 200 with events[] for the fork');
+
+    // The prefix itself: every inherited row matches the source by sequence and
+    // type. This is the fixed-history claim, stated positively.
+    const inherited = forked.filter((e) => (e.sequence as number) < fromSeq);
+    expect(
+      inherited.map((e) => `${String(e.sequence)}:${String(e.type)}`),
+      req(ID, DOC, `the fork MUST inherit [0, ${fromSeq}) from the source verbatim by sequence and type`),
+    ).toEqual(source.filter((e) => (e.sequence as number) < fromSeq).map((e) => `${String(e.sequence)}:${String(e.type)}`));
+
+    // The boundary. The source's event at `fromSeq` is re-executed, not fixed
+    // history, so it MUST NOT appear at its own sequence in the fork. An
+    // inclusive host copies [0, fromSeq] and that is exactly what it shows.
+    const at = forked.find((e) => (e.sequence as number) === fromSeq);
+    if (at === undefined) return softSkip('blocked', `the fork's log has no event at sequence ${fromSeq} (last ${Math.max(...forked.map((e) => e.sequence as number))}) — the boundary is unobservable on this log`);
+    expect(
+      String(at.type),
+      req(ID, DOC, `the event at sequence ${fromSeq} is re-executed, not fixed history: the fork MUST NOT carry the source's ${String(point.type)} at that sequence — seeing it means the prefix was copied inclusively ([0, ${fromSeq}] instead of [0, ${fromSeq}))`),
+    ).not.toBe(String(point.type));
+  }, 60_000);
+});

package/src/scenarios/v2-run-fork-refusals.test.ts

@@ -0,0 +1,70 @@
+/**
+ * `spec/v2/core/runs.md` §Fork — the refusals and the copied owner (suite
+ * 2.0.0, target major 2; gated on `replay`; one run created plus one fork).
+ *
+ * A `replay` fork with a non-empty `runOptionsOverlay` MUST be rejected 400
+ * (the overlay is `branch`-only); a `fromSeq` not in the source log MUST be
+ * rejected `422 fork_point_invalid`; a valid `replay` fork answers `201 {
+ * runId, sourceRunId, mode, status, eventsUrl }` and the child's `owner` is
+ * copied verbatim from the parent (RFC 0170 §A.4). The 201 is the control for
+ * the two refusals. Determinism and side-effect suppression are replay.md's
+ * and witnessed there.
+ *
+ * @see spec/v2/core/runs.md §Fork
+ * @see RFCS/0170 §A.4
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, gateFamily } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0170.run-fork-refusals';
+const DOC = 'spec/v2/core/runs.md §Fork';
+const NOOP = 'conformance-noop';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+async function discovery(): Promise<Record<string, unknown> | null> { try { return await v2Discovery(); } catch { return null; } }
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+async function snapshot(runId: string): Promise<Record<string, unknown> | null> {
+  const res = await http(() => driver.get(`/runs/${enc(runId)}`));
+  return res?.status === 200 && res.json && typeof res.json === 'object' ? (res.json as Record<string, unknown>) : null;
+}
+
+describe('v2 run-fork-refusals (runs.md §Fork)', () => {
+  it('replay+overlay → 400; a fromSeq outside the log → 422 fork_point_invalid; a valid replay fork → 201 with the parent\'s owner verbatim', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    if (!(await gateFamily('replay'))) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay) — forkRun is gated on replay (runs.md §Surface)');
+    const created = await http(() => driver.post('/runs', { workflowId: NOOP }));
+    if (created === null) return softSkip('blocked', 'POST /runs unreachable (fetch failed)');
+    const runId = (created.json as { runId?: unknown } | null)?.runId;
+    if (created.status !== 201 || typeof runId !== 'string') return softSkip('blocked', `POST /runs answered ${created.status} ${readErrorCode(created.json) ?? ''}`.trim());
+    const t0 = Date.now(); let parent: Record<string, unknown> | null = null;
+    while (Date.now() - t0 < 10_000) { parent = await snapshot(runId); if (parent && TERMINAL.has(String(parent['status']))) break; await new Promise((r) => setTimeout(r, 250)); }
+    if (!parent || !TERMINAL.has(String(parent['status']))) return softSkip('blocked', 'the noop run did not settle within 10 s');
+
+    const overlay = await http(() => driver.post(`/runs/${enc(runId)}:fork`, { mode: 'replay', runOptionsOverlay: { tags: ['conformance'] } }));
+    if (overlay === null) return softSkip('blocked', 'POST /runs/{runId}:fork unreachable (fetch failed)');
+    if (overlay.status === 404) return softSkip('blocked', 'POST /runs/{runId}:fork answered 404 with replay advertised — forkRun is not mounted');
+    expect(overlay.status, req(ID, DOC, `a replay fork with a non-empty runOptionsOverlay MUST be rejected 400 (the overlay is branch-only) — got ${overlay.status} ${readErrorCode(overlay.json) ?? ''}`.trim())).toBe(400);
+
+    const bad = await http(() => driver.post(`/runs/${enc(runId)}:fork`, { mode: 'branch', fromSeq: 999_999 }));
+    if (bad === null) return softSkip('blocked', 'POST /runs/{runId}:fork unreachable (fetch failed)');
+    expect(bad.status, req(ID, DOC, `a fromSeq not in the source log MUST be rejected 422 — got ${bad.status} ${readErrorCode(bad.json) ?? ''}`.trim())).toBe(422);
+    expect(readErrorCode(bad.json), req(ID, DOC, 'the refusal MUST be fork_point_invalid')).toBe('fork_point_invalid');
+
+    const ok = await http(() => driver.post(`/runs/${enc(runId)}:fork`, { mode: 'replay' }));
+    if (ok === null) return softSkip('blocked', 'POST /runs/{runId}:fork unreachable (fetch failed)');
+    expect(ok.status, req(ID, DOC, `a valid replay fork MUST answer 201 — got ${ok.status} ${readErrorCode(ok.json) ?? ''} (the control for the two refusals above)`.trim())).toBe(201);
+    const body = ok.json as { runId?: unknown; sourceRunId?: unknown; mode?: unknown; eventsUrl?: unknown } | null;
+    expect(body?.sourceRunId, req(ID, DOC, 'the 201 MUST name the parent as sourceRunId')).toBe(runId);
+    expect(body?.mode, req(ID, DOC, 'the 201 MUST echo the mode')).toBe('replay');
+    expect(typeof body?.runId === 'string' && typeof body?.eventsUrl === 'string', req(ID, DOC, 'the 201 MUST carry runId and eventsUrl')).toBe(true);
+    const child = await snapshot(String(body?.runId));
+    if (!child) return softSkip('blocked', 'the child snapshot could not be read');
+    expect(child['owner'], req(ID, 'RFCS/0170 §A.4', 'the child\'s owner MUST be copied verbatim from the parent')).toEqual(parent['owner']);
+  }, 30_000);
+});