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

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

@@ -0,0 +1,160 @@
+/**
+ * `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.
+ *
+ * Floor membership: RULED OUT (rc.65), and the reasoning generalises. Rule 10
+ * admits this file mechanically — it gates only on `replay`, which IS in the
+ * core-standard predicate, and carries no seam token. But rule 10's stated
+ * intent is that a floor file be "witnessable by an honest holder of the
+ * predicate", and this file is not: it is a SINGLE `it` gated entirely on
+ * `isFixtureAdvertised(conformance-multi-node)`, and no spec text makes that
+ * fixture mandatory. An honest `replay` holder without it records the whole
+ * file `inapplicable` and contributes zero witness. Contrast the eleven of
+ * thirteen current core-standard members with no fixture gate at all, and the
+ * two that have one (`v2-run-cancel`, `v2-run-pause-resume`) gating only SOME
+ * legs of a multi-`it` file, so the file still witnesses — the rc.59
+ * `partial-witness:` pattern.
+ *
+ * The test for any future floor candidate, then: CAN THE FILE STILL WITNESS
+ * FOR A PREDICATE HOLDER THAT ADVERTISES NO OPTIONAL FIXTURE? If the answer is
+ * no because it is single-leg and fixture-gated, it is a valid scenario and not
+ * a floor member. That is a statement about the floor's promise, not about this
+ * file's worth: the boundary it checks is real and a tier-1 host shipped the
+ * bug it catches.
+ *
+ * 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);
+});

package/src/scenarios/v2-run-options-limits.test.ts

@@ -0,0 +1,69 @@
+/**
+ * `spec/v2/core/runs.md` §Run options — `tags`, `metadata`, and the closed
+ * create body (suite 2.0.0, target major 2; unaided; one run created).
+ *
+ * `tags` is opaque: a host MUST NOT reject a tag on format and MUST answer
+ * `400 validation_error` over the limits (100 entries, 256 characters).
+ * `metadata` MUST be persisted and surface unchanged on the snapshot, as MUST
+ * `tags`. The create body is closed at the composition, so an unknown ROOT key
+ * MUST be refused `400 validation_error` (`v2-configurable-closed` covers keys
+ * inside `configurable` only).
+ *
+ * The refusals are the control for the acceptance and vice versa: a host that
+ * accepts everything fails the 400 legs; a host that refuses odd tags fails the
+ * 201 leg. `""` is deliberately not among the odd tags — the schema's
+ * `minLength: 1` is a length rule, not a format rule (finding 4).
+ *
+ * @see spec/v2/core/runs.md §Run options
+ * @see schemas/v2/run-options.schema.json
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0171.run-options-limits';
+const DOC = 'spec/v2/core/runs.md §Run options';
+const NOOP = 'conformance-noop';
+const ODD_TAGS = ['has space', 'emoji 🚀', 'slash/colon:pipe|', 'UPPER-and_under', 'x'.repeat(256)];
+const METADATA = { nested: { a: 1, b: [1, '2', null, true] }, s: 'unicode ∞ ok', n: 0 };
+
+async function discovery(): Promise<Record<string, unknown> | null> { try { return await v2Discovery(); } catch { return null; } }
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+
+async function refused(body: Record<string, unknown>, what: string): Promise<string | null> {
+  const res = await http(() => driver.post('/runs', body));
+  if (res === null) return `POST /runs unreachable (fetch failed) for ${what}`;
+  expect(res.status, req(ID, DOC, `${what} MUST be refused 400 — got ${res.status} ${readErrorCode(res.json) ?? ''}`.trim())).toBe(400);
+  expect(readErrorCode(res.json), req(ID, DOC, `the refusal for ${what} MUST be validation_error`)).toBe('validation_error');
+  return null;
+}
+
+describe('v2 run-options-limits (runs.md §Run options)', () => {
+  it('more than 100 tags, a tag over 256 characters, and an unknown root key are each refused 400 validation_error', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const probes: Array<[Record<string, unknown>, string]> = [
+      [{ workflowId: NOOP, tags: Array.from({ length: 101 }, (_, i) => `t${i}`) }, '101 tags'],
+      [{ workflowId: NOOP, tags: ['y'.repeat(257)] }, 'a 257-character tag'],
+      [{ workflowId: NOOP, conformanceUnknownRootKey: 1 }, 'an unknown root key on the create body (closed at the composition)'],
+    ];
+    for (const [body, what] of probes) { const r = await refused(body, what); if (r) return softSkip('blocked', r); }
+  });
+
+  it('odd-format tags and free-form metadata are accepted and surface unchanged on the snapshot', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const res = await http(() => driver.post('/runs', { workflowId: NOOP, tags: ODD_TAGS, metadata: METADATA }));
+    if (res === null) return softSkip('blocked', 'POST /runs unreachable (fetch failed)');
+    expect(res.status, req(ID, DOC, `a host MUST NOT reject a tag on format and MUST accept free-form metadata — got ${res.status} ${readErrorCode(res.json) ?? ''}`.trim())).toBe(201);
+    const runId = (res.json as { runId?: unknown } | null)?.runId;
+    if (typeof runId !== 'string') return softSkip('blocked', 'the 201 carried no runId');
+    const snap = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}`));
+    if (snap === null || snap.status !== 200) return softSkip('blocked', `GET /runs/{runId} answered ${snap?.status ?? 'no response'} for the run just created`);
+    const body = snap.json as { tags?: unknown; metadata?: unknown } | null;
+    expect(body?.tags, req(ID, DOC, 'tags MUST surface unchanged on RunSnapshot')).toEqual(ODD_TAGS);
+    expect(body?.metadata, req(ID, DOC, 'metadata MUST be persisted and surface unchanged on RunSnapshot')).toEqual(METADATA);
+  });
+});

package/src/scenarios/v2-run-pause-resume.test.ts

@@ -0,0 +1,117 @@
+/**
+ * `spec/v2/core/runs.md` §Pause and resume (suite 2.0.0, target major 2).
+ *
+ * Legs:
+ *   1. unaided: `:pause` and `:resume` on a terminal run MUST answer 409 with an
+ *      error envelope. The prose names no code; only `run_terminal` is
+ *      registered (finding 2). The leg asserts 409 + a code and names none. On
+ *      its own this leg is one-sided — a host that answers 409 to everything
+ *      passes it — so its recorded reason says so when leg 2 cannot run.
+ *   2. on `conformance-delay`: pause → `202 { runId, status: paused }`; pause
+ *      again → 409; resume → `202 { runId, status: running }`; the log carries
+ *      `run.paused` then `run.resumed`. The run is cancelled at the end so
+ *      nothing is left running.
+ *
+ * @see spec/v2/core/runs.md §Pause and resume
+ * @see conformance/fixtures.md §conformance-delay
+ */
+
+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-pause-resume';
+const DOC = 'spec/v2/core/runs.md §Pause and resume';
+const NOOP = 'conformance-noop';
+const DELAY = 'conformance-delay';
+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 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;
+}
+
+describe('v2 run-pause-resume (runs.md §Pause and resume)', () => {
+  it('pause and resume on a terminal run answer 409 with an error envelope', 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 pause = await http(() => driver.post(`/runs/${enc(c.runId)}:pause`, {}));
+    if (pause === null) return softSkip('blocked', 'POST /runs/{runId}:pause unreachable (fetch failed)');
+    if (pause.status === 404) return softSkip('blocked', 'POST /runs/{runId}:pause answered 404 — pauseRun is a core operation (runs.md §Surface) and is not mounted');
+    expect(pause.status, req(ID, DOC, `pause on a terminal (${s}) run MUST answer 409 — got ${pause.status} ${readErrorCode(pause.json) ?? ''}`.trim())).toBe(409);
+    expect(readErrorCode(pause.json), req(ID, DOC, `a pause refused because the run is terminal MUST carry run_terminal (got ${String(readErrorCode(pause.json))})`)).toBe('run_terminal');
+    const resume = await http(() => driver.post(`/runs/${enc(c.runId)}:resume`, {}));
+    if (resume === null) return softSkip('blocked', 'POST /runs/{runId}:resume unreachable (fetch failed)');
+    expect(resume.status, req(ID, DOC, `resume on a run that is not paused MUST answer 409 — got ${resume.status} ${readErrorCode(resume.json) ?? ''}`.trim())).toBe(409);
+    expect(readErrorCode(resume.json), req(ID, DOC, `a resume refused because the run is terminal MUST carry run_terminal (got ${String(readErrorCode(resume.json))})`)).toBe('run_terminal');
+    if (!isFixtureAdvertised(DELAY)) return softSkip('inapplicable', `${DELAY} fixture not advertised — the positive pause/resume leg cannot run, so the two 409s above are witnessed without their control (a host answering 409 to everything would pass them)`);
+  });
+
+  it('a running run pauses (202 paused), refuses a second pause (409), resumes (202 running), and the log carries run.paused then run.resumed', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    if (!isFixtureAdvertised(DELAY)) return softSkip('inapplicable', `${DELAY} fixture not advertised — no run stays running long enough to pause`);
+    const c = await create({ workflowId: DELAY, 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', `${DELAY} did not reach running within 5 s (last: ${running ?? 'unreadable'})`);
+    try {
+      const pause = await http(() => driver.post(`/runs/${enc(c.runId)}:pause`, { reason: 'conformance', drainPolicy: 'immediate' }));
+      if (pause === null) return softSkip('blocked', 'POST /runs/{runId}:pause unreachable (fetch failed)');
+      if (pause.status === 404) return softSkip('blocked', 'POST /runs/{runId}:pause answered 404 — not mounted');
+      expect(pause.status, req(ID, DOC, `pauseRun on a running run MUST answer 202 — got ${pause.status} ${readErrorCode(pause.json) ?? ''}`.trim())).toBe(202);
+      const pb = pause.json as { runId?: unknown; status?: unknown } | null;
+      expect(pb?.runId, req(ID, DOC, 'the 202 MUST carry the runId')).toBe(c.runId);
+      expect(pb?.status, req(ID, DOC, `the 202 MUST carry status paused (got ${String(pb?.status)})`)).toBe('paused');
+      const again = await http(() => driver.post(`/runs/${enc(c.runId)}:pause`, {}));
+      expect(again?.status ?? null, req(ID, DOC, `a second pause on a paused run MUST answer 409 — got ${again?.status ?? 'no response'}`)).toBe(409);
+      expect(readErrorCode(again?.json), req(ID, DOC, `a pause refused on a non-terminal run MUST carry run_state_conflict (got ${String(readErrorCode(again?.json))})`)).toBe('run_state_conflict');
+      // `details` sits at the envelope ROOT (schemas/v2/error-envelope.schema.json), not under `error`.
+      const runStatus = (again?.json as { details?: { runStatus?: unknown } } | null)?.details?.runStatus;
+      expect(runStatus, req(ID, DOC, `run_state_conflict MUST carry details.runStatus naming the status that refused it (got ${String(runStatus)})`)).toBe('paused');
+      const resume = await http(() => driver.post(`/runs/${enc(c.runId)}:resume`, { reason: 'conformance' }));
+      expect(resume?.status ?? null, req(ID, DOC, `resumeRun on a paused run MUST answer 202 — got ${resume?.status ?? 'no response'} ${readErrorCode(resume?.json) ?? ''}`.trim())).toBe(202);
+      const rb = resume?.json as { runId?: unknown; status?: unknown } | null;
+      expect(rb?.status, req(ID, DOC, `the 202 MUST carry status running (got ${String(rb?.status)})`)).toBe('running');
+      const types = await eventTypes(c.runId);
+      const p = types?.indexOf('run.paused') ?? -1; const r = types?.indexOf('run.resumed') ?? -1;
+      expect(p >= 0 && r > p, req(ID, 'spec/v2/core/events.md §run.paused', `the log MUST carry run.paused then run.resumed (types: ${(types ?? []).join(', ')})`)).toBe(true);
+      // An immediate pause cuts the executing attempt BETWEEN events: no terminal
+      // node event for it, ever — a node.failed here makes a replay fold a
+      // failure the source never had (runs.md §Pause and resume; replay.md).
+      const between = (types ?? []).slice(p + 1, r);
+      expect(between.some((t) => t === 'node.failed' || t === 'node.completed' || t === 'node.cancelled'), req(ID, DOC, `with drainPolicy immediate the interrupted attempt MUST NOT record a terminal node event (between run.paused and run.resumed: ${between.join(', ') || 'nothing'})`)).toBe(false);
+      const poll = await http(() => driver.get(`/runs/${enc(c.runId)}/events/poll?timeout=1`));
+      const paused = ((poll?.json as { events?: Array<{ type?: unknown; payload?: { drainPolicy?: unknown } }> } | null)?.events ?? []).find((e) => e.type === 'run.paused');
+      expect(paused?.payload?.drainPolicy, req(ID, DOC, `run.paused's payload MUST echo the request's drainPolicy word (got ${String(paused?.payload?.drainPolicy)})`)).toBe('immediate');
+    } finally {
+      await http(() => driver.post(`/runs/${enc(c.runId)}/cancel`, { reason: 'conformance cleanup' }));
+    }
+  }, 30_000);
+});

package/src/scenarios/v2-run-snapshot-etag.test.ts

@@ -0,0 +1,57 @@
+/**
+ * `spec/v2/core/runs.md` §Snapshot — the conditional GET (suite 2.0.0, target
+ * major 2; unaided; one run created).
+ *
+ * The 200 SHOULD carry a strong `ETag`; WHEN PRESENT, a matching
+ * `If-None-Match` MUST receive `304` with no body. The SHOULD gates the MUST:
+ * a host that sends no ETag records `inapplicable`. Every response carries
+ * `OpenWOP-Version` (versioning.md §1.4), the 304 included.
+ *
+ * Control: a non-matching `If-None-Match` MUST receive 200 with the body — a
+ * host that answers 304 to any conditional request fails here. `headers.md`
+ * scopes `If-None-Match` to the discovery document; runs.md applies it to the
+ * snapshot with a MUST (finding 5, filed).
+ *
+ * @see spec/v2/core/runs.md §Snapshot
+ * @see spec/v2/core/versioning.md §1.4
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0170.run-snapshot-etag';
+const DOC = 'spec/v2/core/runs.md §Snapshot';
+const NOOP = 'conformance-noop';
+
+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; } }
+
+describe('v2 run-snapshot-etag (runs.md §Snapshot)', () => {
+  it('a matching If-None-Match receives 304 with no body and the version header; a non-matching one receives 200', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    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) ?? ''} — create refused`.trim());
+    const path = `/runs/${encodeURIComponent(runId)}`;
+    // Let the noop settle so the tag is stable across the two conditional reads.
+    await new Promise((r) => setTimeout(r, 1_000));
+    const first = await http(() => driver.get(path));
+    if (first === null || first.status !== 200) return softSkip('blocked', `GET /runs/{runId} answered ${first?.status ?? 'no response'}`);
+    const etag = first.headers.get('etag');
+    if (!etag) return softSkip('inapplicable', 'the snapshot carries no ETag — runs.md §Snapshot makes the ETag a SHOULD; the 304 rule applies only when it is present');
+    const hit = await http(() => driver.get(path, { headers: { 'If-None-Match': etag } }));
+    if (hit === null) return softSkip('blocked', 'conditional GET unreachable (fetch failed)');
+    expect(hit.status, req(ID, DOC, `a request whose If-None-Match matches the ETag MUST receive 304 — got ${hit.status}`)).toBe(304);
+    expect(hit.text.length, req(ID, DOC, `the 304 MUST carry no body (got ${hit.text.length} byte(s))`)).toBe(0);
+    expect(hit.headers.get('openwop-version'), req(ID, 'spec/v2/core/versioning.md §1.4', 'every response carries OpenWOP-Version, the 304 included')).not.toBeNull();
+    const miss = await http(() => driver.get(path, { headers: { 'If-None-Match': '"openwop-conformance-no-such-tag"' } }));
+    if (miss === null) return softSkip('blocked', 'conditional GET unreachable (fetch failed)');
+    expect(miss.status, req(ID, DOC, `a non-matching If-None-Match MUST receive 200 with the body — got ${miss.status} (a host answering 304 to any conditional request is not honouring the tag)`)).toBe(200);
+    expect((miss.json as { runId?: unknown } | null)?.runId, req(ID, DOC, 'the 200 body is the snapshot')).toBe(runId);
+  });
+});

package/src/scenarios/v2-sse-last-event-id.test.ts

@@ -0,0 +1,93 @@
+/**
+ * `spec/v2/core/events.md` §SSE frames — `Last-Event-ID` resumes every mode
+ * (suite 2.0.0, target major 2; unaided; one run created).
+ *
+ * The host MUST look up the event with that sequence, MUST begin at the next
+ * sequence, and MUST NOT re-emit the resumption point; in `values` mode the
+ * resumption MUST emit a `state.snapshot` first. Frames carry `id:` = the
+ * sequence (0-based: the first frame's id is `0`, so ids are tested for
+ * presence and parsed, never for truthiness).
+ *
+ * Legs and controls, all on one completed noop run:
+ *   1. the full stream: ≥1 frame, numeric ids, closed by the server;
+ *   2. resume at the first id: the first resumed id is greater, the resumption
+ *      id is absent, and the resumed set equals the full set minus every id at
+ *      or below it — one assertion catches loss and duplication;
+ *   3. resume at the last id: zero frames, closed by server (a host that ignores
+ *      the header re-sends all N against an expected 0; a host that closes
+ *      every stream empty fails leg 1);
+ *   4. if `values` is served: a `values` resume's first frame is
+ *      `event: state.snapshot` (a frame name, not a type — §SSE frames).
+ *
+ * @see spec/v2/core/events.md §SSE frames
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { subscribe, type SseEvent } from '../lib/sse.js';
+import { v2Discovery } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0171.sse-last-event-id';
+const DOC = 'spec/v2/core/events.md §SSE frames';
+const NOOP = 'conformance-noop';
+const V2 = { 'OpenWOP-Version': '2.0' };
+
+async function discovery(): Promise<Record<string, unknown> | null> { try { return await v2Discovery(); } catch { return null; } }
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+/** The frame's sequence, or null when the frame carries no id — `0` is a valid id. */
+function seqOf(f: SseEvent): number | null { if (f.id === null || f.id === '') return null; const n = Number.parseInt(f.id, 10); return Number.isFinite(n) ? n : null; }
+
+async function createSettled(): Promise<{ runId: string } | { reason: string }> {
+  const res = await http(() => driver.post('/runs', { workflowId: NOOP }));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | null)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs answered ${res.status} ${readErrorCode(res.json) ?? ''}`.trim() };
+  const t0 = Date.now();
+  while (Date.now() - t0 < 10_000) {
+    const s = await http(() => driver.get(`/runs/${enc(runId)}`));
+    if (s?.status === 200 && ['completed', 'failed', 'cancelled'].includes(String((s.json as { status?: unknown }).status))) return { runId };
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  return { reason: 'the noop run did not settle within 10 s' };
+}
+
+describe('v2 sse-last-event-id (events.md §SSE frames)', () => {
+  it('Last-Event-ID resumes at the next sequence, never re-emits the resumption point, loses nothing, and at the last id yields nothing', async () => {
+    if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
+    const c = await createSettled(); if ('reason' in c) return softSkip('blocked', c.reason);
+    const path = `/runs/${enc(c.runId)}/events?streamMode=debug`;
+    const full = await subscribe(path, { timeoutMs: 8_000, extraHeaders: V2 });
+    if (full.status === 404) return softSkip('blocked', 'GET /runs/{runId}/events answered 404 — streamRunEvents is a core operation and is not mounted');
+    expect(full.status, req(ID, DOC, `the stream MUST answer 200 — got ${full.status}`)).toBe(200);
+    expect(full.events.length, req(ID, DOC, 'the completed log MUST stream as at least one frame')).toBeGreaterThan(0);
+    expect(full.closedBy, req(ID, DOC, `the host MUST close after the terminal event (closed by ${full.closedBy})`)).toBe('server');
+    const ids = full.events.map(seqOf);
+    expect(ids.every((n) => n !== null), req(ID, DOC, `every frame MUST carry id: = its sequence (frames without a parseable id: ${ids.filter((n) => n === null).length} of ${ids.length})`)).toBe(true);
+    const seqs = ids as number[];
+    expect([...seqs].sort((a, b) => a - b), req(ID, DOC, 'frames MUST arrive in log order')).toEqual(seqs);
+    const first = seqs[0]!; const last = seqs[seqs.length - 1]!;
+
+    const resumed = await subscribe(path, { timeoutMs: 8_000, extraHeaders: V2, lastEventId: String(first) });
+    expect(resumed.status, req(ID, DOC, `a resume with Last-Event-ID MUST answer 200 — got ${resumed.status}`)).toBe(200);
+    const rseqs = resumed.events.map(seqOf).filter((n): n is number => n !== null);
+    expect(rseqs.includes(first), req(ID, DOC, `the host MUST NOT re-emit the resumption point (Last-Event-ID ${first} re-emitted)`)).toBe(false);
+    expect(rseqs, req(ID, DOC, `the host MUST begin at the next sequence and lose nothing: resumed ids (${rseqs.join(',')}) MUST equal the full set minus every id ≤ ${first} (${seqs.filter((n) => n > first).join(',')})`)).toEqual(seqs.filter((n) => n > first));
+
+    const atEnd = await subscribe(path, { timeoutMs: 8_000, extraHeaders: V2, lastEventId: String(last) });
+    expect(atEnd.status, req(ID, DOC, `a resume at the terminal sequence MUST answer 200 — got ${atEnd.status}`)).toBe(200);
+    expect(atEnd.events.length, req(ID, DOC, `a resume at the last sequence (${last}) MUST emit nothing and close — a host ignoring the header re-sends all ${seqs.length} (got ${atEnd.events.length})`)).toBe(0);
+    expect(atEnd.closedBy, req(ID, DOC, 'the host MUST close the empty resume itself')).toBe('server');
+
+    // values: resumption MUST emit a state.snapshot first — only where the host serves values.
+    const probe = await http(() => driver.get(`/runs/${enc(c.runId)}/events?streamMode=bogus`, { headers: { Accept: 'text/event-stream' } }));
+    const supported = (probe?.json as { details?: { supported?: unknown } } | null)?.details?.supported;
+    if (!Array.isArray(supported) || !supported.includes('values')) return softSkip('inapplicable', `values mode not served (details.supported: ${JSON.stringify(supported)}) — the state.snapshot-first resumption leg does not apply`);
+    const values = await subscribe(`/runs/${enc(c.runId)}/events?streamMode=values`, { timeoutMs: 8_000, extraHeaders: V2, lastEventId: String(first) });
+    expect(values.status, req(ID, DOC, `a values resume MUST answer 200 — got ${values.status}`)).toBe(200);
+    expect(values.events[0]?.event ?? null, req(ID, DOC, `in values mode a resumption MUST emit a state.snapshot first (first frame: ${values.events[0]?.event ?? 'none'})`)).toBe('state.snapshot');
+  }, 45_000);
+});