@openwop/openwop-conformance 1.0.0

package/src/scenarios/highConcurrency.test.ts

@@ -0,0 +1,263 @@
+/**
+ * High-concurrency scenarios — drives N parallel run creations against
+ * a host and asserts correct rate-limit, idempotency, and queue
+ * behavior per `spec/v1/scale-profiles.md`.
+ *
+ * **Tagged `@scale-profile-production`** — these scenarios are gated on
+ * the host claiming `production` or `high-throughput`. A host claiming
+ * `minimal` MAY skip via env var `OPENWOP_SKIP_SCALE_PRODUCTION=1`.
+ *
+ * Methodology:
+ *   - Spawn N concurrent `POST /v1/runs` requests with a mix of
+ *     idempotency-keyed and non-idempotency-keyed requests.
+ *   - Measure: success count, idempotency-replay count, 429/503 count,
+ *     wall-clock from first request to last response.
+ *   - Assert: zero double-execution; rate-limit responses carry
+ *     Retry-After; advertised ack-timeout (per RFC 0002) honored.
+ *
+ * Latency-percentile measurement is deliberately conservative: we run
+ * a small N (10) and verify shape, not microbenchmark numbers, because
+ * conformance must be reproducible across host environments. Real
+ * benchmark runs (against `production`/`high-throughput` claims) need
+ * larger N + warm-up, which is out of scope for the conformance suite.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-idempotent';
+const SKIP_SCALE = process.env.OPENWOP_SKIP_SCALE_PRODUCTION === '1';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+const SKIP = SKIP_SCALE || SKIP_NO_FIXTURE;
+
+function freshKey(suffix: string): string {
+  return `openwop-conformance-${Date.now()}-${Math.random().toString(36).slice(2, 8)}-${suffix}`;
+}
+
+interface RunCreateResult {
+  status: number;
+  runId: string | undefined;
+  replay: boolean;
+  retryAfter: number | undefined;
+  errorCode: string | undefined;
+}
+
+async function createRun(body: unknown, key?: string): Promise<RunCreateResult> {
+  const headers: Record<string, string> = {};
+  if (key !== undefined) headers['Idempotency-Key'] = key;
+  const res = await driver.post('/v1/runs', body, { headers });
+
+  const json = res.json as {
+    runId?: string;
+    error?: string;
+    details?: { retryAfter?: number };
+  } | undefined;
+  const retryAfterHeader = res.headers.get('retry-after');
+  return {
+    status: res.status,
+    runId: json?.runId,
+    replay: res.headers.get('openwop-idempotent-replay') === 'true',
+    retryAfter: json?.details?.retryAfter ?? (retryAfterHeader !== null ? Number(retryAfterHeader) : undefined),
+    errorCode: json?.error,
+  };
+}
+
+describe.skipIf(SKIP)(
+  'high-concurrency: parallel POST /v1/runs per scale-profiles.md §"Conformance scenarios"',
+  () => {
+    it(
+      '10 parallel requests with same key yield ONE runId and 9 replays',
+      async () => {
+        const key = freshKey('parallel-same-key');
+        const body = { workflowId: WORKFLOW_ID, inputs: { nonce: 'parallel-1' } };
+
+        const results = await Promise.all(
+          Array.from({ length: 10 }, () => createRun(body, key)),
+        );
+
+        const succeeded = results.filter((r) => r.status === 200 || r.status === 201);
+        const conflicted = results.filter((r) => r.status === 409);
+
+        expect(
+          succeeded.length + conflicted.length,
+          driver.describe(
+            'idempotency.md §Concurrent duplicates',
+            'every concurrent request MUST resolve to either the cached response or a deterministic 409',
+          ),
+        ).toBe(10);
+
+        const runIds = new Set(succeeded.map((r) => r.runId).filter((id): id is string => !!id));
+        expect(
+          runIds.size,
+          driver.describe(
+            'idempotency.md §Layer 1',
+            'same idempotency key MUST yield exactly ONE runId across all successful responses',
+          ),
+        ).toBe(1);
+
+        // Per idempotency.md, 409 carries idempotency_in_flight and
+        // retry-after metadata under the canonical details slot.
+        for (const c of conflicted) {
+          expect(
+            c.errorCode === 'idempotency_in_flight' || c.errorCode === undefined,
+            driver.describe(
+              'idempotency.md',
+              '409 on parallel idempotency-keyed retry MUST carry error="idempotency_in_flight"',
+            ),
+          ).toBe(true);
+          if (c.retryAfter !== undefined) {
+            expect(
+              c.retryAfter,
+              driver.describe(
+                'idempotency.md',
+                '409 idempotency_in_flight MUST include a numeric retryAfter',
+              ),
+            ).toBeGreaterThan(0);
+          }
+        }
+      },
+      30000,
+    );
+
+    it(
+      '10 parallel requests with distinct keys yield 10 distinct runIds',
+      async () => {
+        const body = { workflowId: WORKFLOW_ID, inputs: { nonce: 'parallel-2' } };
+
+        const results = await Promise.all(
+          Array.from({ length: 10 }, (_, i) => createRun(body, freshKey(`parallel-distinct-${i}`))),
+        );
+
+        const succeeded = results.filter((r) => r.status === 200 || r.status === 201);
+        const rateLimited = results.filter((r) => r.status === 429 || r.status === 503);
+
+        // A `production`-tier host MUST handle 10 parallel run creations.
+        // A `minimal`-tier host MAY rate-limit; documented in scale-profiles.md.
+        expect(
+          succeeded.length + rateLimited.length,
+          driver.describe(
+            'rest-endpoints.md',
+            'concurrent POST /v1/runs requests MUST resolve to either success or rate-limited',
+          ),
+        ).toBe(10);
+
+        // Among successful responses, every runId is distinct (no Layer-1 dedup
+        // because keys are distinct).
+        const succeededRunIds = succeeded.map((r) => r.runId);
+        const uniqueRunIds = new Set(succeededRunIds);
+        expect(
+          uniqueRunIds.size,
+          driver.describe(
+            'idempotency.md §Layer 1',
+            'distinct idempotency keys MUST yield distinct runIds (Layer 1 dedup is keyed)',
+          ),
+        ).toBe(succeededRunIds.length);
+
+        // Any rate-limited response MUST set Retry-After per scale-profiles.md
+        // §"Backpressure semantics."
+        for (const r of rateLimited) {
+          expect(
+            r.retryAfter,
+            driver.describe(
+              'scale-profiles.md §Backpressure',
+              '429/503 response MUST include numeric Retry-After',
+            ),
+          ).toBeGreaterThan(0);
+        }
+      },
+      30000,
+    );
+
+    it(
+      '5 sequential retries with same key 100ms apart all succeed (idempotency cache survives retry storm)',
+      async () => {
+        const key = freshKey('retry-storm');
+        const body = { workflowId: WORKFLOW_ID, inputs: { nonce: 'retry-storm' } };
+
+        const results: RunCreateResult[] = [];
+        for (let i = 0; i < 5; i++) {
+          results.push(await createRun(body, key));
+          await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+
+        const succeeded = results.filter((r) => r.status === 200 || r.status === 201);
+        expect(
+          succeeded.length,
+          driver.describe(
+            'scale-profiles.md §Retry semantics',
+            'host MUST handle ≥5 retries with same key 100ms apart without losing the cached response',
+          ),
+        ).toBe(5);
+
+        const runIds = new Set(succeeded.map((r) => r.runId));
+        expect(
+          runIds.size,
+          driver.describe(
+            'idempotency.md §Layer 1',
+            'all 5 retries with same key MUST resolve to the same runId',
+          ),
+        ).toBe(1);
+
+        // First request is fresh; subsequent are replays.
+        expect(
+          results[0]!.replay,
+          driver.describe(
+            'idempotency.md §Server responsibilities',
+            'first request with new key MUST NOT be marked as replay',
+          ),
+        ).toBe(false);
+        // RFC 0002 §1 promotes openwop-Idempotent-Replay from SHOULD to MUST.
+        // Until RFC 0002 is Accepted, the assertion is permissive: at
+        // least one of the subsequent requests SHOULD be marked as replay
+        // (the spec today says SHOULD, RFC 0002 promotes to MUST).
+        const someReplay = results.slice(1).some((r) => r.replay);
+        expect(
+          someReplay,
+          driver.describe(
+            'idempotency.md §Server responsibilities #2',
+            'replay responses SHOULD set openwop-Idempotent-Replay: true',
+          ),
+        ).toBe(true);
+      },
+      30000,
+    );
+
+    it(
+      'concurrent distinct-key requests respect advertised idempotency cache retention',
+      async () => {
+        // This is a structural assertion against /.well-known/openwop, NOT a
+        // wall-clock test. We can't realistically wait 24h for cache
+        // expiration in a conformance run. Instead we assert the host
+        // advertises a cache retention compatible with scale-profiles.md.
+        const discovery = await driver.get('/.well-known/openwop', { authenticated: false });
+        expect(discovery.status).toBe(200);
+
+        const limits = (discovery.json as { limits?: Record<string, unknown> })?.limits;
+        expect(
+          limits,
+          driver.describe(
+            'capabilities.md §3',
+            'limits MUST be advertised in discovery',
+          ),
+        ).toBeDefined();
+
+        // Per idempotency.md the optional `idempotencyAckTimeoutSec` field
+        // is a normative-additive field. If the host advertises it, the
+        // value MUST be ≥5. If absent, the spec default is 5.
+        const ackTimeout = (limits as { idempotencyAckTimeoutSec?: unknown })
+          ?.idempotencyAckTimeoutSec;
+        if (ackTimeout !== undefined) {
+          expect(
+            typeof ackTimeout === 'number' && Number.isInteger(ackTimeout) && ackTimeout >= 5,
+            driver.describe(
+              'idempotency.md',
+              'limits.idempotencyAckTimeoutSec MUST be integer ≥5 when advertised',
+            ),
+          ).toBe(true);
+        }
+      },
+      10000,
+    );
+  },
+);

package/src/scenarios/idempotency.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Idempotency scenarios — exercises the `Idempotency-Key` header
+ * contract on `POST /v1/runs` per `idempotency.md` and
+ * `rest-endpoints.md`.
+ *
+ * Uses the `conformance-idempotent` fixture. Server MUST have seeded
+ * it. The fixture's `nonce` input has no side effect — it exists so
+ * the conformance suite can vary the body without affecting behavior.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-idempotent';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+function freshKey(suffix: string): string {
+  return `openwop-conformance-${Date.now()}-${Math.random().toString(36).slice(2, 8)}-${suffix}`;
+}
+
+describe.skipIf(SKIP_NO_FIXTURE)('idempotency: same key + same body replays per idempotency.md §Layer 1', () => {
+  it('returns same runId twice and sets openwop-Idempotent-Replay on the replay', async () => {
+    const key = freshKey('replay');
+    const body = { workflowId: WORKFLOW_ID, inputs: { nonce: 'abc-123' } };
+
+    const first = await driver.post('/v1/runs', body, {
+      headers: { 'Idempotency-Key': key },
+    });
+    expect(first.status, driver.describe(
+      'rest-endpoints.md',
+      'first POST /v1/runs MUST return 201',
+    )).toBe(201);
+    const firstRunId = (first.json as { runId: string }).runId;
+
+    const replay = await driver.post('/v1/runs', body, {
+      headers: { 'Idempotency-Key': key },
+    });
+    expect(
+      [200, 201].includes(replay.status),
+      driver.describe(
+        'idempotency.md §Layer 1',
+        'replay request with same key + same body MUST return success status (200/201)',
+      ),
+    ).toBe(true);
+
+    const replayRunId = (replay.json as { runId: string }).runId;
+    expect(replayRunId, driver.describe(
+      'idempotency.md §Layer 1',
+      'replay MUST return the SAME runId (no new run created)',
+    )).toBe(firstRunId);
+
+    const replayHeader = replay.headers.get('openwop-idempotent-replay');
+    expect(replayHeader, driver.describe(
+      'rest-endpoints.md POST /v1/runs response headers',
+      'openwop-Idempotent-Replay header MUST be set on cache-served responses',
+    )).toBeTruthy();
+  });
+});
+
+describe.skipIf(SKIP_NO_FIXTURE)('idempotency: same key + different body conflicts per idempotency.md §Layer 1', () => {
+  it('returns 409 when the body changes under the same key', async () => {
+    const key = freshKey('conflict');
+
+    const first = await driver.post(
+      '/v1/runs',
+      { workflowId: WORKFLOW_ID, inputs: { nonce: 'first' } },
+      { headers: { 'Idempotency-Key': key } },
+    );
+    expect(first.status).toBe(201);
+
+    const conflict = await driver.post(
+      '/v1/runs',
+      { workflowId: WORKFLOW_ID, inputs: { nonce: 'DIFFERENT' } },
+      { headers: { 'Idempotency-Key': key } },
+    );
+
+    expect(conflict.status, driver.describe(
+      'idempotency.md §Layer 1',
+      'same Idempotency-Key with a different body MUST return 409',
+    )).toBe(409);
+  });
+});

package/src/scenarios/idempotencyRetry.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Idempotency-retry scenarios per spec/v1/idempotency.md.
+ *
+ * Builds on `idempotency.test.ts` (which covers basic Layer-1 cache and
+ * 409-on-body-conflict) by exercising the deterministic-dispatch
+ * additions documented in idempotency.md:
+ *
+ *   1. openwop-Idempotent-Replay header is present on every keyed response
+ *      (idempotency.md §Server responsibilities).
+ *   2. Retry-budget floor — hosts handle ≥5 retries 100ms apart with
+ *      the cached response (scale-profiles.md §"Retry semantics").
+ *   3. Same-key replay returns same runId across the budget.
+ *   4. (Optional) hosts that advertise `limits.idempotencyAckTimeoutSec`
+ *      MUST set it to integer ≥ 5 per idempotency.md.
+ *
+ * Profile gating: `openwop-core` (and `openwop-stream-poll` to read snapshots).
+ * Every conforming host runs these.
+ *
+ * @see spec/v1/idempotency.md
+ * @see spec/v1/scale-profiles.md §"Retry semantics"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-idempotent';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+function freshKey(suffix: string): string {
+  return `openwop-conformance-${Date.now()}-${Math.random().toString(36).slice(2, 8)}-${suffix}`;
+}
+
+describe.skipIf(SKIP_NO_FIXTURE)('idempotency-retry: openwop-Idempotent-Replay header per idempotency.md', () => {
+  it('first request with new key returns false (or absent SHOULD per current spec); replay returns true', async () => {
+    const key = freshKey('replay-header');
+    const body = { workflowId: WORKFLOW_ID, inputs: { nonce: 'replay-test' } };
+
+    const first = await driver.post('/v1/runs', body, { headers: { 'Idempotency-Key': key } });
+    expect(first.status, driver.describe(
+      'rest-endpoints.md',
+      'first POST /v1/runs returns 201',
+    )).toBe(201);
+
+    const firstReplay = first.headers.get('openwop-idempotent-replay');
+    // Per idempotency.md: header SHOULD be present even on the first call,
+    // set to "false". Pre-RFC spec only requires it on the replay.
+    // Permissive assertion: if present, MUST be "false" or "true".
+    if (firstReplay !== null) {
+      expect(['false', 'true'].includes(firstReplay), driver.describe(
+        'idempotency.md §Server responsibilities',
+        'openwop-Idempotent-Replay value MUST be "true" or "false"',
+      )).toBe(true);
+    }
+
+    const replay = await driver.post('/v1/runs', body, { headers: { 'Idempotency-Key': key } });
+    expect(
+      [200, 201].includes(replay.status),
+      driver.describe('idempotency.md §Layer 1', 'replay returns 200 or 201'),
+    ).toBe(true);
+
+    const replayHeader = replay.headers.get('openwop-idempotent-replay');
+    // Per idempotency.md §Server responsibilities #2: SHOULD be set.
+    // RFC 0002 §1 promotes to MUST. Today's strictness: present on replay.
+    expect(replayHeader, driver.describe(
+      'idempotency.md §Server responsibilities #2',
+      'openwop-Idempotent-Replay SHOULD be set on idempotent replay responses',
+    )).not.toBeNull();
+    if (replayHeader !== null) {
+      expect(replayHeader, driver.describe(
+        'idempotency.md §Server responsibilities #2',
+        'openwop-Idempotent-Replay on replay MUST be "true"',
+      )).toBe('true');
+    }
+  });
+});
+
+describe.skipIf(SKIP_NO_FIXTURE)('idempotency-retry: 5-retry budget per scale-profiles.md §"Retry semantics"', () => {
+  it('5 retries 100ms apart with same key all return the same runId', async () => {
+    const key = freshKey('retry-budget');
+    const body = { workflowId: WORKFLOW_ID, inputs: { nonce: 'retry-budget' } };
+
+    const responses = [];
+    for (let i = 0; i < 5; i++) {
+      const res = await driver.post('/v1/runs', body, { headers: { 'Idempotency-Key': key } });
+      responses.push(res);
+      if (i < 4) await new Promise((r) => setTimeout(r, 100));
+    }
+
+    for (const res of responses) {
+      expect(
+        [200, 201].includes(res.status),
+        driver.describe(
+          'scale-profiles.md §Retry semantics',
+          'host MUST handle ≥5 retries 100ms apart without losing the cached response',
+        ),
+      ).toBe(true);
+    }
+
+    const runIds = new Set(responses.map((r) => (r.json as { runId?: string })?.runId));
+    expect(runIds.size, driver.describe(
+      'idempotency.md §Layer 1',
+      '5 retries with same key MUST collapse to exactly one runId',
+    )).toBe(1);
+  });
+});
+
+describe('idempotency-retry: limits.idempotencyAckTimeoutSec contract per idempotency.md', () => {
+  it('host advertising idempotencyAckTimeoutSec sets integer ≥ 5', async () => {
+    const res = await driver.get('/.well-known/openwop', { authenticated: false });
+    expect(res.status).toBe(200);
+
+    const limits = (res.json as { limits?: Record<string, unknown> })?.limits;
+    if (!limits) return; // limits required per capabilities.md §3 — covered elsewhere
+    const ack = limits.idempotencyAckTimeoutSec;
+    if (ack === undefined) {
+      // Per idempotency.md, the field is optional; absence implies the
+      // 5-second floor. Nothing to assert.
+      return;
+    }
+    expect(typeof ack === 'number' && Number.isInteger(ack), driver.describe(
+      'idempotency.md',
+      'limits.idempotencyAckTimeoutSec MUST be an integer when advertised',
+    )).toBe(true);
+    expect(ack as number, driver.describe(
+      'idempotency.md',
+      'limits.idempotencyAckTimeoutSec MUST be ≥ 5',
+    )).toBeGreaterThanOrEqual(5);
+  });
+});

package/src/scenarios/identity-passthrough.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Identity-passthrough scenario — exercises the `conformance-identity`
+ * fixture. The fixture echoes its `payload` input back to the
+ * `payload` variable on output. This verifies:
+ *
+ *   1. inputs.{var} on POST /v1/runs is observable in subsequent
+ *      RunSnapshot.variables.{var} (per fixtures.md §conformance-identity).
+ *   2. Object equality is preserved end-to-end (no JSON serialization
+ *      drift on the server).
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-identity';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+describe.skipIf(SKIP_NO_FIXTURE)('identity: conformance-identity fixture echoes payload input to variables', () => {
+  it('arbitrary nested JSON payload round-trips through inputs → variables', async () => {
+    const payload = {
+      stringField: 'hello',
+      intField: 42,
+      boolField: true,
+      arrayField: [1, 'two', { three: 3 }],
+      nested: {
+        deeper: { stillDeeper: { value: 'leaf' } },
+      },
+    };
+
+    const create = await driver.post('/v1/runs', {
+      workflowId: WORKFLOW_ID,
+      inputs: { payload },
+    });
+    expect(create.status, driver.describe(
+      'rest-endpoints.md',
+      'POST /v1/runs MUST return 201',
+    )).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+
+    expect(terminal.status, driver.describe(
+      'fixtures.md conformance-identity',
+      'identity fixture MUST reach terminal `completed`',
+    )).toBe('completed');
+
+    expect(terminal.variables?.payload, driver.describe(
+      'fixtures.md conformance-identity §Expected behavior',
+      'RunSnapshot.variables.payload MUST deep-equal the input payload',
+    )).toEqual(payload);
+  });
+});

package/src/scenarios/interrupt-approval.test.ts

@@ -0,0 +1,97 @@
+/**
+ * Approval-interrupt scenarios — exercises the run-scoped HITL
+ * resolve surface (`POST /v1/runs/{runId}/interrupts/{nodeId}`)
+ * using the `conformance-approval` fixture.
+ *
+ * Per fixtures.md, the fixture's approval node id is `gate` and the
+ * resume schema is `{action: 'accept' | 'reject'}`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilStatus, pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const WORKFLOW_ID = 'conformance-approval';
+const NODE_ID = 'gate';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
+
+describe.skipIf(SKIP_NO_FIXTURE)('interrupt: approval accept resumes to `completed`', () => {
+  it('run suspends at gate, accept resolution drives terminal completed', 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 suspended = await pollUntilStatus(runId, 'waiting-approval', { timeoutMs: 10_000 });
+    expect(suspended.currentNodeId, driver.describe(
+      'fixtures.md conformance-approval',
+      'suspended run MUST report currentNodeId === "gate"',
+    )).toBe(NODE_ID);
+
+    const resolve = await driver.post(
+      `/v1/runs/${encodeURIComponent(runId)}/interrupts/${encodeURIComponent(NODE_ID)}`,
+      { resumeValue: { action: 'accept' } },
+    );
+    expect(resolve.status, driver.describe(
+      'rest-endpoints.md POST /v1/runs/{runId}/interrupts/{nodeId}',
+      'valid approval resolve MUST return 200',
+    )).toBe(200);
+
+    const terminal = await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+    expect(terminal.status, driver.describe(
+      'fixtures.md conformance-approval §Terminal status',
+      'fixture after accept MUST reach terminal `completed`',
+    )).toBe('completed');
+  });
+});
+
+describe.skipIf(SKIP_NO_FIXTURE)('interrupt: invalid resolve payload rejected per resumeSchema', () => {
+  it('400 (or 422) when action is not in {accept, reject}', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: WORKFLOW_ID });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilStatus(runId, 'waiting-approval', { timeoutMs: 10_000 });
+
+    const resolve = await driver.post(
+      `/v1/runs/${encodeURIComponent(runId)}/interrupts/${encodeURIComponent(NODE_ID)}`,
+      { resumeValue: { action: 'maybe' } },
+    );
+    expect(
+      [400, 422].includes(resolve.status),
+      driver.describe(
+        'interrupt.md + resumeSchema validation',
+        'resolve payload that violates resumeSchema MUST return 400 or 422',
+      ),
+    ).toBe(true);
+
+    // Cleanup: cancel the still-suspended run so the test doesn't leave
+    // a dangling fixture run on the server.
+    await driver.post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, {
+      reason: 'conformance-cleanup',
+    });
+  });
+});
+
+describe.skipIf(SKIP_NO_FIXTURE)('interrupt: resolving an unknown interrupt returns 404', () => {
+  it('400/404 when nodeId does not match an active interrupt', async () => {
+    const create = await driver.post('/v1/runs', { workflowId: WORKFLOW_ID });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilStatus(runId, 'waiting-approval', { timeoutMs: 10_000 });
+
+    const resolve = await driver.post(
+      `/v1/runs/${encodeURIComponent(runId)}/interrupts/no-such-node`,
+      { resumeValue: { action: 'accept' } },
+    );
+    expect(resolve.status, driver.describe(
+      'rest-endpoints.md POST /v1/runs/{runId}/interrupts/{nodeId}',
+      'resolving an unknown nodeId MUST return 404',
+    )).toBe(404);
+
+    await driver.post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, {
+      reason: 'conformance-cleanup',
+    });
+  });
+});