@openwop/openwop-conformance 1.0.0

package/src/scenarios/staleClaim.test.ts

@@ -0,0 +1,223 @@
+/**
+ * Stale-claim recovery scenario per spec/v1/scale-profiles.md
+ * §"Replay semantics" + spec/v1/storage-adapters.md §"Claim acquisition."
+ *
+ * When a process holding a run claim dies without releasing the claim,
+ * another process that boots later (after the claim TTL has expired)
+ * MUST pick up the run and resume execution. The conformance contract:
+ *
+ *   - Process A starts a long-running run, writes some events,
+ *     SIGKILLs (claim left as held + expires_at populated).
+ *   - After CLAIM_TTL_MS elapses, claim is "stale" by definition.
+ *   - Process B boots pointing at the same DB; resume-on-startup
+ *     re-acquires the claim and finishes the run.
+ *   - The run's terminal status is observable through process B's
+ *     HTTP surface.
+ *
+ * **`@multi-process`** — needs `child_process.spawn` to drive two host
+ * processes against a shared SQLite file. Skipped against hosts that
+ * aren't the SQLite reference (no shared-storage contract).
+ *
+ * **`@timing-sensitive`** — relies on a configurable claim TTL.
+ * Skipped automatically against hosts that don't expose the TTL via
+ * env (the test reads `OPENWOP_STALE_CLAIM_HOST_DIR`; if unset, the
+ * scenario skip-equivalents).
+ *
+ * @see lib/multiProcess.ts — spawnHost helper
+ * @see examples/hosts/sqlite/src/server.ts — heartbeat + resume
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawnHost, type SpawnedHost } from '../lib/multiProcess.js';
+
+// Default off: scenario must be opted in via env. The opt-in lists
+// the host package dir relative to repo root that exposes the
+// OPENWOP_CLAIM_TTL_MS / OPENWOP_HEARTBEAT_INTERVAL_MS / OPENWOP_SQLITE_PATH env
+// vars. The reference SQLite host satisfies this contract.
+const HOST_PACKAGE_DIR = process.env.OPENWOP_STALE_CLAIM_HOST_DIR ?? 'examples/hosts/sqlite';
+const RUN_THIS_SCENARIO = process.env.OPENWOP_RUN_STALE_CLAIM === '1';
+
+const APIKEY_A = 'openwop-stale-claim-A';
+const APIKEY_B = 'openwop-stale-claim-B';
+const PORT_A = 4801;
+const PORT_B = 4802;
+const CLAIM_TTL_MS = 2000;
+const HEARTBEAT_INTERVAL_MS = 500;
+
+interface RunSnapshot {
+  status?: string;
+  runId?: string;
+}
+
+interface PollResponse {
+  events?: Array<{ type?: string; nodeId?: string | null; data?: unknown }>;
+  isComplete?: boolean;
+}
+
+async function fetchSnapshot(baseUrl: string, apiKey: string, runId: string): Promise<RunSnapshot> {
+  const res = await fetch(`${baseUrl}/v1/runs/${encodeURIComponent(runId)}`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+  if (!res.ok) throw new Error(`GET /v1/runs/${runId} failed: ${res.status}`);
+  return (await res.json()) as RunSnapshot;
+}
+
+async function fetchEvents(
+  baseUrl: string,
+  apiKey: string,
+  runId: string,
+): Promise<PollResponse> {
+  const res = await fetch(
+    `${baseUrl}/v1/runs/${encodeURIComponent(runId)}/events/poll`,
+    { headers: { Authorization: `Bearer ${apiKey}` } },
+  );
+  if (!res.ok) throw new Error(`poll failed: ${res.status}`);
+  return (await res.json()) as PollResponse;
+}
+
+async function pollUntilStatus(
+  baseUrl: string,
+  apiKey: string,
+  runId: string,
+  predicate: (s: string) => boolean,
+  timeoutMs: number,
+): Promise<RunSnapshot> {
+  const deadline = Date.now() + timeoutMs;
+  let last: RunSnapshot = {};
+  while (Date.now() < deadline) {
+    last = await fetchSnapshot(baseUrl, apiKey, runId);
+    if (typeof last.status === 'string' && predicate(last.status)) return last;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  throw new Error(
+    `pollUntilStatus did not match predicate within ${timeoutMs}ms; last status: ${last.status}`,
+  );
+}
+
+describe.skipIf(!RUN_THIS_SCENARIO)(
+  'staleClaim: orphaned run resumes on a second host process per spec/v1/storage-adapters.md',
+  () => {
+    let dbDir: string | null = null;
+    let hostA: SpawnedHost | null = null;
+    let hostB: SpawnedHost | null = null;
+
+    afterEach(async () => {
+      if (hostA) {
+        await hostA.kill().catch(() => {});
+        hostA = null;
+      }
+      if (hostB) {
+        await hostB.shutdown().catch(() => {});
+        hostB = null;
+      }
+      if (dbDir !== null) {
+        try {
+          rmSync(dbDir, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
+        dbDir = null;
+      }
+    });
+
+    it(
+      'process B picks up the orphaned run after process A dies + claim expires',
+      async () => {
+        // Phase 1: shared DB file in a temp dir.
+        dbDir = mkdtempSync(join(tmpdir(), 'openwop-stale-claim-'));
+        const dbPath = join(dbDir, 'host.sqlite');
+
+        // Phase 2: spawn host A and start a long-running cancellable run.
+        hostA = await spawnHost({
+          packageDir: HOST_PACKAGE_DIR,
+          port: PORT_A,
+          apiKey: APIKEY_A,
+          dbPath,
+          claimTtlMs: CLAIM_TTL_MS,
+          heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
+        });
+        await hostA.ready();
+
+        const createRes = await fetch(`${hostA.baseUrl}/v1/runs`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${APIKEY_A}`,
+          },
+          body: JSON.stringify({
+            workflowId: 'conformance-cancellable',
+            inputs: { delayMs: 5000 },
+          }),
+        });
+        expect(createRes.status).toBe(201);
+        const { runId } = (await createRes.json()) as { runId: string };
+
+        // Phase 3: wait until A reports the run as `running`.
+        await pollUntilStatus(hostA.baseUrl, APIKEY_A, runId, (s) => s === 'running', 5000);
+
+        // Phase 4: SIGKILL A. The kill MUST NOT release the claim —
+        // graceful shutdown is the OPPOSITE behavior.
+        await hostA.kill();
+        hostA = null;
+
+        // Phase 5: wait for the claim TTL to lapse. With CLAIM_TTL_MS=2000
+        // we wait ~3s to be safely past expiry.
+        await new Promise((r) => setTimeout(r, CLAIM_TTL_MS + 1000));
+
+        // Phase 6: spawn host B at the SAME DB. Its resume-on-startup
+        // MUST find the orphaned run, claim it, and dispatch.
+        hostB = await spawnHost({
+          packageDir: HOST_PACKAGE_DIR,
+          port: PORT_B,
+          apiKey: APIKEY_B,
+          dbPath,
+          claimTtlMs: CLAIM_TTL_MS,
+          heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
+        });
+        await hostB.ready();
+
+        // Phase 7: poll until B reports the run as terminal. The run
+        // restarts from the beginning of the delay node (5s) on B,
+        // plus a small slack window — generous timeout is fine.
+        const terminal = await pollUntilStatus(
+          hostB.baseUrl,
+          APIKEY_B,
+          runId,
+          (s) => s === 'completed' || s === 'failed' || s === 'cancelled',
+          15_000,
+        );
+
+        expect(terminal.status, 'orphaned run MUST resume to a terminal status under host B').toBe(
+          'completed',
+        );
+
+        // Phase 8: verify the event log records the resume. A
+        // `run.resumed` event MUST be present (per the SQLite host's
+        // implementation; other hosts MAY use a different marker but
+        // SOMETHING that distinguishes resume from fresh start MUST
+        // exist in the event log).
+        const events = await fetchEvents(hostB.baseUrl, APIKEY_B, runId);
+        expect(Array.isArray(events.events), 'events poll MUST return an events array').toBe(true);
+        if (events.events && events.events.length > 0) {
+          const types = events.events.map((e) => e.type);
+          expect(
+            types.includes('run.resumed') || types.includes('run.started'),
+            'event log MUST contain at least run.started; resume hosts SHOULD also emit run.resumed',
+          ).toBe(true);
+        }
+      },
+      60_000,
+    );
+  },
+);
+
+// Always-on smoke test for the multiProcess library shape — runs even
+// when the scenario is gated off.
+describe('staleClaim lib: spawnHost surface contract', () => {
+  it('spawnHost is exported and has the expected shape', async () => {
+    expect(typeof spawnHost).toBe('function');
+  });
+});

package/src/scenarios/stream-modes-buffer.test.ts

@@ -0,0 +1,148 @@
+/**
+ * SSE buffering scenarios (G1 / S3) — exercises `?bufferMs=` aggregation
+ * hint against the existing `conformance-delay` fixture.
+ *
+ * Verifies:
+ *   1. Server accepts `bufferMs` in [0..5000] without error.
+ *   2. Out-of-range `bufferMs` returns 400 with `validation_error`.
+ *   3. Buffered mode emits at least one `event: batch` SSE frame whose
+ *      data is a JSON array of `RunEventDoc`.
+ *   4. Force-flush on terminal: the run.completed event arrives bundled
+ *      in a batch, not held back to the next interval.
+ *   5. Total event count in buffered mode equals the unbuffered mode
+ *      count (no events dropped).
+ *
+ * Spec references:
+ *   - stream-modes.md §Aggregation hint
+ *   - spec gap G1
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { subscribe } from '../lib/sse.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-delay';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+interface RunEventDoc {
+  readonly type: string;
+  readonly sequence: number;
+}
+
+describe.skipIf(SKIP_NO_FIXTURE)('stream-modes-buffer: ?bufferMs= aggregation hint', () => {
+  it('accepts bufferMs in range and emits at least one event: batch frame', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: WORKFLOW_ID });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const result = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=updates&bufferMs=200`,
+      { timeoutMs: 30_000 },
+    );
+
+    expect(result.status, driver.describe(
+      'stream-modes.md §Aggregation hint',
+      'GET /v1/runs/{runId}/events with valid bufferMs MUST return 200 SSE',
+    )).toBe(200);
+
+    const batchEvents = result.events.filter((e) => e.event === 'batch');
+    expect(batchEvents.length, driver.describe(
+      'stream-modes.md §Aggregation hint',
+      'buffered mode MUST emit at least one `event: batch` SSE frame',
+    )).toBeGreaterThan(0);
+
+    // Each batch's data is a JSON array of RunEventDoc.
+    for (const batch of batchEvents) {
+      const parsed = JSON.parse(batch.data);
+      expect(Array.isArray(parsed), driver.describe(
+        'stream-modes.md §batch data shape',
+        'event: batch data MUST parse to a JSON array',
+      )).toBe(true);
+      expect(parsed.length).toBeGreaterThan(0);
+      for (const event of parsed) {
+        expect(typeof event.sequence).toBe('number');
+        expect(typeof event.type).toBe('string');
+      }
+    }
+  });
+
+  it('rejects out-of-range bufferMs with 400 validation_error', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: WORKFLOW_ID });
+    const runId = (create.json as { runId: string }).runId;
+
+    const result = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId)}/events?bufferMs=99999`,
+      { timeoutMs: 5_000 },
+    );
+
+    expect(result.status, driver.describe(
+      'stream-modes.md §Aggregation hint range',
+      'bufferMs > 5000 MUST return 400',
+    )).toBe(400);
+
+    // Drain the run so it doesn't stall the test runner.
+    await pollUntilTerminal(runId);
+  });
+
+  it('forces flush on terminal — run.completed arrives bundled in a batch BEFORE the timer fires', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: WORKFLOW_ID });
+    const runId = (create.json as { runId: string }).runId;
+
+    // Use a long bufferMs (4000ms) so the only flush before terminal
+    // would come from the force-flush rule. We measure elapsed time
+    // from subscribe-start to terminal-arrival; if force-flush works,
+    // it arrives in well under bufferMs/2 (i.e., the run completes +
+    // force-flush fires + we observe it before any timer-based flush
+    // could have happened). Without force-flush, terminal would either
+    // arrive AFTER bufferMs (timer-based delivery) OR not at all
+    // (stream closed before the timer fired).
+    const BUFFER_MS = 4000;
+    const startedAt = Date.now();
+    const result = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=updates&bufferMs=${BUFFER_MS}`,
+      { timeoutMs: 30_000 },
+    );
+    const elapsedMs = Date.now() - startedAt;
+
+    const batchEvents = result.events.filter((e) => e.event === 'batch');
+    const allFlattened: RunEventDoc[] = batchEvents.flatMap(
+      (b) => JSON.parse(b.data) as RunEventDoc[],
+    );
+    const hasTerminal = allFlattened.some(
+      (e) => e.type === 'run.completed' || e.type === 'run.failed' || e.type === 'run.cancelled',
+    );
+
+    expect(hasTerminal, driver.describe(
+      'stream-modes.md §Aggregation hint — force-flush triggers',
+      'terminal events MUST be force-flushed; the stream MUST NOT close before delivering run.completed',
+    )).toBe(true);
+
+    // Force-flush fires immediately on terminal; without it, terminal
+    // would arrive ~bufferMs after the run actually completed. We allow
+    // bufferMs/2 as headroom for cold-start latency on the conformance
+    // server, but failing here proves the timer fired before terminal
+    // arrived (i.e., force-flush is broken).
+    expect(elapsedMs, driver.describe(
+      'stream-modes.md §Aggregation hint — force-flush is immediate',
+      `terminal SHOULD arrive in well under bufferMs (${BUFFER_MS}ms); observed ${elapsedMs}ms — if elapsed is close to bufferMs, force-flush is not firing`,
+    )).toBeLessThan(BUFFER_MS / 2);
+  });
+
+  it('bufferMs=0 behaves identically to omitting (per-event mode)', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: WORKFLOW_ID });
+    const runId = (create.json as { runId: string }).runId;
+
+    const result = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=updates&bufferMs=0`,
+      { timeoutMs: 30_000 },
+    );
+
+    const batchEvents = result.events.filter((e) => e.event === 'batch');
+    expect(batchEvents.length, driver.describe(
+      'stream-modes.md §Aggregation hint — bufferMs=0 sentinel',
+      'bufferMs=0 MUST behave identically to omitting (no batch frames)',
+    )).toBe(0);
+  });
+});

package/src/scenarios/stream-modes-mixed.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Mixed-mode SSE scenarios (G2 / S4) — exercises comma-separated
+ * `?streamMode=` against the existing `conformance-delay` fixture.
+ *
+ * Verifies:
+ *   1. Server accepts `streamMode=updates,messages` (mixed subset).
+ *   2. Server rejects `streamMode=values,updates` with 400 +
+ *      `unsupported_stream_mode` error envelope (values is exclusive).
+ *   3. Server rejects `streamMode=updates,bogus` (one bad mode → whole
+ *      list fails).
+ *   4. Mixed mode sees AT LEAST every event the corresponding single
+ *      mode would see (union semantics).
+ *
+ * Spec references:
+ *   - stream-modes.md §Mixed mode (closes S4)
+ *   - spec gap G2
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { subscribe, type SseEvent } from '../lib/sse.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-delay';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+function eventTypes(events: readonly SseEvent[]): string[] {
+  return events.map((e) => e.event);
+}
+
+describe.skipIf(SKIP_NO_FIXTURE)('stream-modes-mixed: comma-separated subsets', () => {
+  it('accepts streamMode=updates,messages and emits a server-closed stream', async () => {
+    const create = await driver.post('/v1/runs', {
+      workflowId: WORKFLOW_ID,
+      inputs: { delayMs: 500 },
+    });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const result = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=updates,messages`,
+      { timeoutMs: 15_000 },
+    );
+
+    expect(result.status, driver.describe(
+      'stream-modes.md §Mixed mode',
+      'streamMode=updates,messages MUST return 200',
+    )).toBe(200);
+
+    expect(result.closedBy, driver.describe(
+      'stream-modes.md §Mixed mode + §updates',
+      'server MUST close the stream on terminal run event',
+    )).toBe('server');
+
+    const types = eventTypes(result.events);
+    expect(types, driver.describe(
+      'stream-modes.md §Mixed mode (union semantics)',
+      'mixed updates,messages MUST include run.completed (admitted by updates)',
+    )).toContain('run.completed');
+  });
+
+  it('rejects streamMode=values,updates with 400 + unsupported_stream_mode', async () => {
+    const create = await driver.post('/v1/runs', {
+      workflowId: WORKFLOW_ID,
+      inputs: { delayMs: 100 },
+    });
+    const runId = (create.json as { runId: string }).runId;
+
+    const res = await driver.get(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=values,updates`,
+    );
+    expect(res.status, driver.describe(
+      'stream-modes.md §Mixed mode',
+      'values combined with another mode MUST return 400',
+    )).toBe(400);
+
+    const body = res.json as
+      | { error?: string; message?: string; details?: { supported?: string[] } }
+      | undefined;
+    expect(body?.error, driver.describe(
+      'stream-modes.md §Mode selection error envelope + error-envelope.schema.json',
+      'unsupported_stream_mode error envelope MUST carry an `error` string discriminator',
+    )).toBe('unsupported_stream_mode');
+    expect(typeof body?.message, driver.describe(
+      'error-envelope.schema.json',
+      'error envelope MUST carry a human-readable `message` string',
+    )).toBe('string');
+    expect(Array.isArray(body?.details?.supported), driver.describe(
+      'stream-modes.md §Mode selection error envelope',
+      'error body MUST carry `details.supported` array (NOT top-level — `details` is the canonical contextual-data slot per error-envelope.schema.json)',
+    )).toBe(true);
+
+    await pollUntilTerminal(runId);
+  });
+
+  it('rejects streamMode=updates,bogus (one bad mode fails the whole list)', async () => {
+    const create = await driver.post('/v1/runs', {
+      workflowId: WORKFLOW_ID,
+      inputs: { delayMs: 100 },
+    });
+    const runId = (create.json as { runId: string }).runId;
+
+    const res = await driver.get(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=updates,bogus`,
+    );
+    expect(res.status, driver.describe(
+      'stream-modes.md §Mixed mode + §Mode selection',
+      'partial-unknown lists MUST return 400',
+    )).toBe(400);
+
+    await pollUntilTerminal(runId);
+  });
+
+  it('mixed mode union: updates,debug sees every event updates sees', async () => {
+    // Run twice — once with updates only, once with updates,debug.
+    // The mixed-mode response MUST be a superset of the updates-only
+    // response (union semantics).
+    const r1 = await driver.post('/v1/runs', {
+      workflowId: WORKFLOW_ID,
+      inputs: { delayMs: 500 },
+    });
+    const runId1 = (r1.json as { runId: string }).runId;
+    const updatesOnly = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId1)}/events?streamMode=updates`,
+      { timeoutMs: 15_000 },
+    );
+
+    const r2 = await driver.post('/v1/runs', {
+      workflowId: WORKFLOW_ID,
+      inputs: { delayMs: 500 },
+    });
+    const runId2 = (r2.json as { runId: string }).runId;
+    const mixed = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId2)}/events?streamMode=updates,debug`,
+      { timeoutMs: 15_000 },
+    );
+
+    const updatesTypes = new Set(eventTypes(updatesOnly.events));
+    const mixedTypes = new Set(eventTypes(mixed.events));
+
+    for (const t of updatesTypes) {
+      expect(mixedTypes.has(t), driver.describe(
+        'stream-modes.md §Mixed mode (union)',
+        `updates,debug MUST include every event type updates produces (missing: ${t})`,
+      )).toBe(true);
+    }
+  });
+});

package/src/scenarios/stream-modes.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Stream-mode scenarios — exercises `GET /v1/runs/{runId}/events` SSE
+ * with different `streamMode` query parameters per stream-modes.md.
+ *
+ * Uses the `conformance-delay` fixture with a short delay (1s) so the
+ * stream has well-defined start + completion bounds without making
+ * tests slow.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { subscribe, type SseEvent } from '../lib/sse.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-delay';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+async function startDelayRun(delayMs: number): Promise<string> {
+  const create = await driver.post('/v1/runs', {
+    workflowId: WORKFLOW_ID,
+    inputs: { delayMs },
+  });
+  if (create.status !== 201) {
+    throw new Error(`Failed to start ${WORKFLOW_ID} run: ${create.status} ${create.text}`);
+  }
+  return (create.json as { runId: string }).runId;
+}
+
+function eventTypes(events: readonly SseEvent[]): string[] {
+  return events.map((e) => e.event);
+}
+
+describe.skipIf(SKIP_NO_FIXTURE)('stream-modes: updates (default) closes on terminal event', () => {
+  it('emits at least run.started + run.completed and server closes the stream', async () => {
+    const runId = await startDelayRun(1_000);
+    const { events, closedBy } = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=updates`,
+      { timeoutMs: 15_000 },
+    );
+
+    expect(closedBy, driver.describe(
+      'stream-modes.md §updates',
+      'server MUST close the connection on terminal run event',
+    )).toBe('server');
+
+    const types = eventTypes(events);
+    expect(types, driver.describe(
+      'stream-modes.md §updates',
+      'updates stream MUST include run.started',
+    )).toContain('run.started');
+    expect(types, driver.describe(
+      'stream-modes.md §updates',
+      'updates stream MUST include run.completed for a successful run',
+    )).toContain('run.completed');
+  });
+});
+
+describe.skipIf(SKIP_NO_FIXTURE)('stream-modes: invalid streamMode is rejected', () => {
+  it('returns 400 and a structured error body', async () => {
+    const runId = await startDelayRun(1_000);
+    const res = await driver.get(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=does-not-exist`,
+    );
+
+    expect(res.status, driver.describe(
+      'stream-modes.md §Mode selection',
+      'unsupported streamMode MUST return 400',
+    )).toBe(400);
+
+    const body = res.json as
+      | { error?: unknown; message?: unknown; details?: { supported?: unknown } }
+      | undefined;
+    expect(typeof body?.error, driver.describe(
+      'stream-modes.md §Mode selection + error-envelope.schema.json',
+      'unsupported_stream_mode error body MUST include `error` string discriminator',
+    )).toBe('string');
+    expect(typeof body?.message, driver.describe(
+      'error-envelope.schema.json',
+      'error envelope MUST include a human-readable `message` string',
+    )).toBe('string');
+    expect(Array.isArray(body?.details?.supported), driver.describe(
+      'stream-modes.md §Mode selection',
+      'error body MUST include `details.supported` array of mode names (under `details` per error-envelope.schema.json)',
+    )).toBe(true);
+  });
+});
+
+describe.skipIf(SKIP_NO_FIXTURE)('stream-modes: values mode is reachable + closes on terminal', () => {
+  it('returns 200 + emits at least one event + server-closes per stream-modes.md §values', async () => {
+    const runId = await startDelayRun(1_000);
+    const result = await subscribe(
+      `/v1/runs/${encodeURIComponent(runId)}/events?streamMode=values`,
+      { timeoutMs: 15_000 },
+    );
+
+    // The state.snapshot payload schema is implementation-shaped per
+    // spec gap S1, so we don't assert payload shape here. What's
+    // canonical: the connection MUST be reachable, MUST emit at least
+    // one event before terminal, AND the server MUST close on terminal.
+    expect(result.closedBy, driver.describe(
+      'stream-modes.md §values',
+      'server MUST close the connection on terminal run event',
+    )).toBe('server');
+
+    expect(result.events.length, driver.describe(
+      'stream-modes.md §values',
+      'values mode MUST emit at least one event before terminal',
+    )).toBeGreaterThan(0);
+  });
+});
+
+describe.skipIf(SKIP_NO_FIXTURE)('stream-modes: debug emits at least as many events as updates', () => {
+  it('debug stream is a superset of updates per stream-modes.md mode-mapping', async () => {
+    const runIdUpdates = await startDelayRun(1_000);
+    const updatesResult = await subscribe(
+      `/v1/runs/${encodeURIComponent(runIdUpdates)}/events?streamMode=updates`,
+      { timeoutMs: 15_000 },
+    );
+
+    const runIdDebug = await startDelayRun(1_000);
+    const debugResult = await subscribe(
+      `/v1/runs/${encodeURIComponent(runIdDebug)}/events?streamMode=debug`,
+      { timeoutMs: 15_000 },
+    );
+
+    // Both runs are conformance-delay with the same input, so updates
+    // events (run.started, node.started not in updates per spec, node.completed,
+    // run.completed) should be a subset of debug events.
+    expect(debugResult.events.length, driver.describe(
+      'stream-modes.md mode-to-event mapping',
+      'debug stream event count MUST be >= updates stream event count',
+    )).toBeGreaterThanOrEqual(updatesResult.events.length);
+
+    expect(debugResult.closedBy, driver.describe(
+      'stream-modes.md §debug',
+      'debug stream MUST close on terminal event',
+    )).toBe('server');
+  });
+});