@openwop/openwop-conformance 1.0.0 → 1.1.1

package/src/scenarios/restart-during-run.test.ts

@@ -0,0 +1,177 @@
+/**
+ * Restart-during-run scenario per spec/v1/scale-profiles.md
+ * §"Replay semantics" + spec/v1/storage-adapters.md §"Claim acquisition."
+ *
+ * Distinct from `staleClaim.test.ts` (which exercises *cross-process*
+ * claim transfer where two host processes share a DB):
+ *
+ *   - **staleClaim:** process A starts a run → SIGKILL → process B
+ *     (different PID, different port, same DB) takes over after TTL.
+ *     Models multi-host scale-out.
+ *   - **restart-during-run** (this file): process A starts a run →
+ *     SIGKILL → process A' (same port, same DB, fresh PID) takes
+ *     over after TTL. Models the single-host crash + supervisor-
+ *     restart pattern that most production deployments rely on.
+ *
+ * Both reduce to the same primitive — resume-on-startup picks up an
+ * orphaned claim — but the contract this scenario asserts is that the
+ * SECOND boot at the SAME port works, which is the more common
+ * production failure mode (a node-level supervisor like systemd, k8s,
+ * pm2 restarts the host process on crash).
+ *
+ * **`@multi-process`** — spawns child host processes via
+ * `child_process.spawn`. Opt-in via `OPENWOP_RUN_RESTART_DURING_RUN=1`.
+ *
+ * **`@timing-sensitive`** — relies on a short claim TTL.
+ *
+ * @see lib/multiProcess.ts — spawnHost helper
+ * @see examples/hosts/sqlite/src/server.ts — resume-on-startup
+ * @see spec/v1/production-profile.md §Durability (RFC 0009 — this
+ *      scenario satisfies the supervisor-restart predicate when the
+ *      host advertises capabilities.production.supported: true)
+ */
+
+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';
+
+const HOST_PACKAGE_DIR =
+  process.env.OPENWOP_RESTART_DURING_RUN_HOST_DIR ?? 'examples/hosts/sqlite';
+const RUN_THIS_SCENARIO = process.env.OPENWOP_RUN_RESTART_DURING_RUN === '1';
+
+const APIKEY = 'openwop-restart-during-run';
+const PORT = 4803;
+const CLAIM_TTL_MS = 2000;
+const HEARTBEAT_INTERVAL_MS = 500;
+
+interface RunSnapshot {
+  status?: string;
+  runId?: string;
+  endedAt?: string | null;
+}
+
+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;
+}
+
+let workdir: string | null = null;
+const activeHosts: SpawnedHost[] = [];
+
+afterEach(async () => {
+  for (const h of activeHosts.splice(0)) {
+    await h.shutdown().catch(() => h.kill().catch(() => undefined));
+  }
+  if (workdir) {
+    rmSync(workdir, { recursive: true, force: true });
+    workdir = null;
+  }
+});
+
+describe.skipIf(!RUN_THIS_SCENARIO)(
+  'restart-during-run: SIGKILL + same-port restart resumes orphaned run',
+  () => {
+    it(
+      'mid-run SIGKILL on the host process; restart at the same port + DB resumes to terminal',
+      async () => {
+        workdir = mkdtempSync(join(tmpdir(), 'openwop-restart-during-run-'));
+        const dbPath = join(workdir, 'openwop-host.sqlite');
+
+        // ── Boot host A (the one we'll kill).
+        const hostA = await spawnHost({
+          packageDir: HOST_PACKAGE_DIR,
+          port: PORT,
+          apiKey: APIKEY,
+          dbPath,
+          claimTtlMs: CLAIM_TTL_MS,
+          heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
+        });
+        activeHosts.push(hostA);
+        await hostA.ready();
+
+        // Start a long-running run (uses conformance-cancellable so we
+        // have time between create and kill).
+        const create = await fetch(`${hostA.baseUrl}/v1/runs`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${APIKEY}`,
+          },
+          body: JSON.stringify({
+            workflowId: 'conformance-cancellable',
+            inputs: { delaySeconds: 8 },
+          }),
+        });
+        expect(create.status).toBe(201);
+        const runId = (await create.json() as { runId: string }).runId;
+        expect(runId).toMatch(/^run-/);
+
+        // Wait a beat so host A writes `run.started` and at least one
+        // node.started before we kill it.
+        await new Promise((r) => setTimeout(r, 300));
+
+        // SIGKILL host A. Claim remains held in the DB until TTL
+        // expires.
+        await hostA.kill();
+        activeHosts.length = 0; // hostA is dead; don't try to shut down again
+
+        // Wait for the claim to go stale.
+        await new Promise((r) => setTimeout(r, CLAIM_TTL_MS + 500));
+
+        // ── Boot the replacement at the SAME port + SAME DB. This is
+        // the supervisor-restart pattern.
+        const hostA2 = await spawnHost({
+          packageDir: HOST_PACKAGE_DIR,
+          port: PORT,
+          apiKey: APIKEY,
+          dbPath,
+          claimTtlMs: CLAIM_TTL_MS,
+          heartbeatIntervalMs: HEARTBEAT_INTERVAL_MS,
+        });
+        activeHosts.push(hostA2);
+        await hostA2.ready();
+
+        // Poll until terminal. A successful restart-recovery means
+        // resume-on-startup re-acquired the claim and the executor
+        // completed the run.
+        const deadline = Date.now() + 30_000;
+        let terminal: RunSnapshot | null = null;
+        while (Date.now() < deadline) {
+          const snap = await fetchSnapshot(hostA2.baseUrl, APIKEY, runId);
+          if (
+            snap.status === 'completed' ||
+            snap.status === 'failed' ||
+            snap.status === 'cancelled'
+          ) {
+            terminal = snap;
+            break;
+          }
+          await new Promise((r) => setTimeout(r, 200));
+        }
+
+        expect(
+          terminal,
+          'run MUST reach terminal status on the restarted host within 30s',
+        ).not.toBeNull();
+        expect(
+          terminal?.status,
+          'restart-recovery MUST drive the run to a non-pending terminal status',
+        ).toMatch(/^(completed|failed|cancelled)$/);
+        // For the cancellable fixture, completed is the expected
+        // outcome — the workflow just exits the delay node and finishes.
+        expect(terminal?.status).toBe('completed');
+        expect(typeof terminal?.endedAt).toBe('string');
+      },
+      45_000,
+    );
+  },
+);

package/src/scenarios/spec-corpus-validity.test.ts

@@ -45,6 +45,7 @@ import {
   FIXTURES_DIR,
   FIXTURES_DOC_PATH,
   GO_TYPES_PATH,
+  LAYOUT,
   PYTHON_TYPES_PATH,
   README_PATH,
   SCENARIOS_DIR,
@@ -786,10 +787,16 @@ describe.skipIf(
 )(
   'spec-corpus: SDK HTTP error helpers match canonical REST vocabulary',
   () => {
+    // describe.skipIf still evaluates the body for test registration; defaults guard against null
+    // dirname() when sources are missing under the published-tarball layout. it() blocks below are
+    // skipped at run time, so the path values are never actually read. The sentinel is
+    // intentionally an obviously-invalid path so a stack trace from any future code that DOES
+    // dereference it points the reader at this comment.
+    const UNUSED_IN_PUBLISHED_LAYOUT = '/__sdk_paths_unused_in_published_layout__';
     const sdkSources = {
-      typescript: TYPESCRIPT_RUN_HELPERS_PATH as string,
-      python: PYTHON_TYPES_PATH as string,
-      go: GO_TYPES_PATH as string,
+      typescript: TYPESCRIPT_RUN_HELPERS_PATH ?? UNUSED_IN_PUBLISHED_LAYOUT,
+      python: PYTHON_TYPES_PATH ?? UNUSED_IN_PUBLISHED_LAYOUT,
+      go: GO_TYPES_PATH ?? UNUSED_IN_PUBLISHED_LAYOUT,
     };
     const sdkReadmes = {
       typescript: pathResolve(dirname(sdkSources.typescript), '..', 'README.md'),
@@ -1072,12 +1079,18 @@ describe.skipIf(V1_DIR === null)('spec-corpus: prose docs carry a Status: legend
 });
 
 describe.skipIf(V1_DIR === null || README_PATH === null)('spec-corpus: README document index matches spec/v1', () => {
-  const v1Dir = V1_DIR as string;
-  const readmePath = README_PATH as string;
+  // describe.skipIf skips test execution but still evaluates the describe callback at registration
+  // time. Guard each side-effecting read against null so the body registers cleanly under the
+  // published-tarball layout where V1_DIR / README_PATH resolve to null.
+  const v1Dir = V1_DIR;
+  const readmePath = README_PATH ?? '';
 
-  const proseFiles = readdirSync(v1Dir)
-    .filter((f) => f.endsWith('.md'))
-    .sort();
+  const proseFiles =
+    v1Dir === null
+      ? []
+      : readdirSync(v1Dir)
+          .filter((f) => f.endsWith('.md'))
+          .sort();
 
   it('README Total count equals the number of spec/v1 prose docs', () => {
     const index = extractReadmeDocumentIndex(readFileSync(readmePath, 'utf8'));
@@ -1109,8 +1122,10 @@ describe.skipIf(V1_DIR === null || README_PATH === null)('spec-corpus: README do
 });
 
 describe.skipIf(README_PATH === null)('spec-corpus: local Markdown links resolve', () => {
-  const repoRoot = dirname(README_PATH as string);
-  const markdownFiles = listMarkdownFilesRecursive(repoRoot);
+  // describe.skipIf skips test execution but still evaluates the body for registration; default
+  // to '.' so dirname() never receives null in the published-tarball layout.
+  const repoRoot = README_PATH === null ? '.' : dirname(README_PATH);
+  const markdownFiles = README_PATH === null ? [] : listMarkdownFilesRecursive(repoRoot);
 
   it('finds Markdown files to check', () => {
     expect(markdownFiles.length, 'repo checkout should contain Markdown docs').toBeGreaterThan(0);
@@ -1132,6 +1147,11 @@ describe.skipIf(README_PATH === null)('spec-corpus: local Markdown links resolve
         }
 
         const target = pathResolve(dirname(file), decoded);
+        // Published-tarball layout: the conformance README references ../spec/v1/... and other paths
+        // that resolve OUTSIDE the package boundary. Repo layout has the full tree available. The
+        // `target === repoRoot || target.startsWith(repoRoot + sep)` form avoids a sibling-path
+        // false-negative when repoRoot=/foo/bar and target=/foo/barbaz.
+        if (LAYOUT === 'published' && target !== repoRoot && !target.startsWith(repoRoot + '/')) continue;
         expect(
           existsSync(target),
           `${relFile} links to missing local target: ${link}`,
@@ -1142,21 +1162,29 @@ describe.skipIf(README_PATH === null)('spec-corpus: local Markdown links resolve
 });
 
 describe.skipIf(README_PATH === null)('spec-corpus: public docs avoid private implementation breadcrumbs', () => {
-  const repoRoot = dirname(README_PATH as string);
-  const publicTextFiles = [
-    README_PATH as string,
-    join(repoRoot, 'QUICKSTART.md'),
-    join(repoRoot, 'QUICKSTART-10MIN.md'),
-    join(repoRoot, 'sdk', 'typescript', 'README.md'),
-    join(repoRoot, 'sdk', 'python', 'README.md'),
-    join(repoRoot, 'sdk', 'go', 'README.md'),
-    ...(CONFORMANCE_README_PATH ? [CONFORMANCE_README_PATH] : []),
-    ...(FIXTURES_DOC_PATH ? [FIXTURES_DOC_PATH] : []),
-    ...listTextFilesRecursive(join(repoRoot, 'examples'), new Set(['.md', 'package.json'])),
-    ...readdirSync(join(repoRoot, 'SECURITY')).filter((f) => f.endsWith('.md') || f.endsWith('.yaml')).map((f) => join(repoRoot, 'SECURITY', f)),
-    ...(V1_DIR !== null ? readdirSync(V1_DIR).filter((f) => f.endsWith('.md')).map((f) => join(V1_DIR as string, f)) : []),
-    ...readdirSync(SCHEMAS_DIR).filter((f) => f.endsWith('.json')).map((f) => join(SCHEMAS_DIR, f)),
-  ].filter((path) => existsSync(path));
+  // describe.skipIf skips test execution but still evaluates the body for registration; guard each
+  // path read against null/missing-dir so the body never throws under the published-tarball layout.
+  const repoRoot = README_PATH === null ? '.' : dirname(README_PATH);
+  const securityDir = join(repoRoot, 'SECURITY');
+  const publicTextFiles =
+    README_PATH === null
+      ? []
+      : [
+          README_PATH,
+          join(repoRoot, 'QUICKSTART.md'),
+          join(repoRoot, 'QUICKSTART-10MIN.md'),
+          join(repoRoot, 'sdk', 'typescript', 'README.md'),
+          join(repoRoot, 'sdk', 'python', 'README.md'),
+          join(repoRoot, 'sdk', 'go', 'README.md'),
+          ...(CONFORMANCE_README_PATH ? [CONFORMANCE_README_PATH] : []),
+          ...(FIXTURES_DOC_PATH ? [FIXTURES_DOC_PATH] : []),
+          ...listTextFilesRecursive(join(repoRoot, 'examples'), new Set(['.md', 'package.json'])),
+          ...(existsSync(securityDir)
+            ? readdirSync(securityDir).filter((f) => f.endsWith('.md') || f.endsWith('.yaml')).map((f) => join(securityDir, f))
+            : []),
+          ...(V1_DIR !== null ? ((v1Dir: string) => readdirSync(v1Dir).filter((f) => f.endsWith('.md')).map((f) => join(v1Dir, f)))(V1_DIR) : []),
+          ...readdirSync(SCHEMAS_DIR).filter((f) => f.endsWith('.json')).map((f) => join(SCHEMAS_DIR, f)),
+        ].filter((path) => existsSync(path));
 
   const banned = [
     { label: 'private workflow-runtime paths', pattern: /services\/workflow-runtime/ },
@@ -1231,7 +1259,12 @@ describe.skipIf(FIXTURES_DOC_PATH === null)('spec-corpus: fixtures.json catalog
       /^\|[^\n]*(PROPOSED|impl pending)[^\n]*\n/gm,
       '',
     );
-    const idRegex = /\bconformance-[a-z][a-z0-9-]*\b/g;
+    // Match `conformance-<id>` only at a real fixture-id boundary —
+    // require the preceding character to NOT be `[a-z0-9-]`, so that
+    // longer strings like `openwop-conformance-canary-secret` do NOT
+    // false-match `conformance-canary-secret` as a fixture id. The
+    // negative lookbehind keeps the regex JS-compatible.
+    const idRegex = /(?<![a-z0-9-])conformance-[a-z][a-z0-9-]*\b/g;
     const cited = new Set<string>();
     let m: RegExpExecArray | null;
     while ((m = idRegex.exec(docWithoutProposed)) !== null) {

package/src/scenarios/staleClaim.test.ts

@@ -25,6 +25,9 @@
  *
  * @see lib/multiProcess.ts — spawnHost helper
  * @see examples/hosts/sqlite/src/server.ts — heartbeat + resume
+ * @see spec/v1/production-profile.md §Durability (RFC 0009 — this
+ *      scenario satisfies the durable-restart predicate when the
+ *      host advertises capabilities.production.supported: true)
  */
 
 import { describe, it, expect, afterEach } from 'vitest';

package/src/scenarios/wasm-pack-abi-version-rejection.test.ts

@@ -1,23 +1,35 @@
 /**
  * RFC 0008 §Conformance — scenario 6/6: ABI version mismatch.
  *
- * Verifies that a host refuses to load a WASM pack whose declared ABI
- * version is not in the host's advertised `abiVersions[]`. The host's
- * loader MUST surface a recognizable `unsupported_abi_version` error
- * (or equivalent) and MUST NOT silently dispatch to the pack's
- * `openwop_node_invoke`.
+ * Two-part scenario per RFCS/0008-wasm-abi.md §H (ABI version handshake):
  *
- * Driving this end-to-end requires a pack with a deliberately wrong
- * ABI version. That pack is filed as v1.x follow-up (an
- * `examples/packs/abi-mismatch/`). The framework here asserts the
- * shape of the host's advertisement so future scenarios can rely on it.
+ *   1. **Discovery shape (observational, always-on)** — host advertises
+ *      `capabilities.nodePackRuntimes.wasm.abiVersions[]` as a non-empty
+ *      array of positive integers including v1.
+ *   2. **Positive path (loadedPacks-gated)** — when the host advertises
+ *      `capabilities.nodePackRuntimes.wasm.loadedPacks[]` AND lists the
+ *      well-behaved reference pack (proving the loader pipeline runs),
+ *      the misbehaving-abi pack at `examples/packs/rust-misbehaving-abi/`
+ *      — which declares `openwop_abi_version() == 999` — MUST NOT
+ *      appear in `loadedPacks[]`. ABI 999 is outside any host's
+ *      `abiVersions[]`, so a conformant host MUST reject the pack at
+ *      load time per RFC 0008 §H.
  *
- * @see RFCS/0008-wasm-abi.md §H (abiVersions array)
+ * The `loadedPacks[]` discovery field is the wire-observable signal:
+ * load-time rejection happens before any node-invoke surface, so the
+ * conformance suite needs a discovery-level affordance to verify the
+ * rejection took effect. Hosts that don't advertise `loadedPacks[]`
+ * soft-skip the positive path.
+ *
+ * @see RFCS/0008-wasm-abi.md §H (ABI version handshake)
  */
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 
+const MISBEHAVING_PACK_NAME = 'vendor.openwop.misbehaving-abi';
+const WELL_BEHAVED_PACK_NAME = 'vendor.openwop.rust-hello';
+
 describe('wasm-pack-abi-version-rejection: host advertises supported ABI versions', () => {
   it('abiVersions[] contains positive integers; loader rejects unsupported versions', async () => {
     const disco = await driver.get('/.well-known/openwop');
@@ -45,3 +57,48 @@ describe('wasm-pack-abi-version-rejection: host advertises supported ABI version
     }
   });
 });
+
+describe('wasm-pack-abi-version-rejection: positive path via misbehaving pack', () => {
+  it('misbehaving-abi pack (declares ABI 999) MUST NOT appear in loadedPacks[]', async () => {
+    const disco = await driver.get('/.well-known/openwop');
+    const wasm =
+      (disco.json as {
+        capabilities?: {
+          nodePackRuntimes?: {
+            wasm?: { supported?: boolean; loadedPacks?: unknown };
+          };
+        };
+      }).capabilities?.nodePackRuntimes?.wasm;
+
+    if (!wasm?.supported) return;
+
+    if (!Array.isArray(wasm.loadedPacks)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[wasm-pack-abi-version-rejection] host does not advertise capabilities.nodePackRuntimes.wasm.loadedPacks[]; skipping positive path. ' +
+          'Hosts MAY advertise loadedPacks[] to surface ABI rejection observably (RFC 0008 §H + Track 7).',
+      );
+      return;
+    }
+
+    // Soft-skip when the well-behaved reference pack isn't loaded. If
+    // loadedPacks[] doesn't include rust-hello, we can't distinguish
+    // "the loader pipeline runs but rejected misbehaving-abi" from
+    // "the loader doesn't run at all on this host."
+    if (!wasm.loadedPacks.includes(WELL_BEHAVED_PACK_NAME)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[wasm-pack-abi-version-rejection] reference pack ${WELL_BEHAVED_PACK_NAME} not in loadedPacks[]; ` +
+          'skipping positive path (build examples/packs/rust-hello first or run against a host that ships it).',
+      );
+      return;
+    }
+
+    // Core assertion: ABI 999 pack MUST NOT be in loadedPacks[]
+    // regardless of filesystem state. The host's loader rejected it.
+    expect(wasm.loadedPacks.includes(MISBEHAVING_PACK_NAME), driver.describe(
+      'RFCS/0008-wasm-abi.md §H',
+      `host MUST reject packs whose declared ABI is not in abiVersions[]; ${MISBEHAVING_PACK_NAME} declares 999 and MUST NOT appear in loadedPacks[]`,
+    )).toBe(false);
+  });
+});

package/src/scenarios/wasm-pack-memory-cap.test.ts

@@ -1,23 +1,33 @@
 /**
  * RFC 0008 §Conformance — scenario 5/6: memory cap enforcement.
  *
- * Verifies that a host enforces `capabilities.nodePackRuntimes.wasm.maxMemoryBytes`
- * by trapping (or otherwise terminating) a module that exceeds the cap
- * and emitting `cap.breached` with `kind: 'wasm-memory'`.
+ * Two-part scenario per RFCS/0008-wasm-abi.md §K (resource limits):
  *
- * The reference rust-hello pack is well-behaved and does not allocate
- * excessively, so this scenario is OBSERVATIONAL: it asserts the cap
- * is *declared* (the protocol requires it) and that if the host
- * advertises a value, the value is plausible.
+ *   1. **Discovery shape (observational, always-on)** — host advertises
+ *      `capabilities.nodePackRuntimes.wasm.maxMemoryBytes` as a plausible
+ *      integer when WASM is supported.
+ *   2. **Positive path (fixture-gated)** — when the deliberately-
+ *      misbehaving Rust pack at `examples/packs/rust-misbehaving-memory/`
+ *      is built and the host advertises the
+ *      `conformance-wasm-pack-memory-cap-breach` fixture, invoking the
+ *      `vendor.openwop.misbehaving.memory-bomb` typeId MUST emit
+ *      `cap.breached` with `kind: 'wasm-memory'` and drive the run to
+ *      terminal `failed`.
  *
- * Driving a real OOM requires a deliberately misbehaving pack. Such a
- * pack is filed as v1.x follow-up; the framework lives here.
+ * Until the misbehaving pack ships in a host's fixture set, the positive
+ * path soft-skips so the scenario stays green on hosts that haven't
+ * wired up the cap-emit behavior yet.
  *
  * @see RFCS/0008-wasm-abi.md §K (resource limits)
+ * @see schemas/run-event-payloads.schema.json §"capBreached" (kind enum includes wasm-memory)
  */
 
 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 CAP_BREACH_FIXTURE = 'conformance-wasm-pack-memory-cap-breach';
 
 describe('wasm-pack-memory-cap: host advertises maxMemoryBytes', () => {
   it('capabilities.nodePackRuntimes.wasm.maxMemoryBytes is a plausible number', async () => {
@@ -41,3 +51,48 @@ describe('wasm-pack-memory-cap: host advertises maxMemoryBytes', () => {
     }
   });
 });
+
+describe('wasm-pack-memory-cap: positive path via misbehaving pack', () => {
+  it('misbehaving pack triggers cap.breached with kind=wasm-memory and terminal failed', async () => {
+    if (!isFixtureAdvertised(CAP_BREACH_FIXTURE)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[wasm-pack-memory-cap] fixture ${CAP_BREACH_FIXTURE} not advertised; skipping positive path. ` +
+          'Build the misbehaving pack at examples/packs/rust-misbehaving-memory/ and ensure the host serves the fixture.',
+      );
+      return;
+    }
+    const disco = await driver.get('/.well-known/openwop');
+    const wasm =
+      (disco.json as {
+        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } };
+      }).capabilities?.nodePackRuntimes?.wasm;
+    if (!wasm?.supported) return;
+
+    const create = await driver.post('/v1/runs', {
+      workflowId: CAP_BREACH_FIXTURE,
+      inputs: {},
+    });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+    expect(terminal.status, driver.describe(
+      'RFCS/0008-wasm-abi.md §K',
+      'WASM memory-cap breach MUST drive terminal `failed` (RFC 0008 §K: "kill the instance, emit cap.breached")',
+    )).toBe('failed');
+
+    const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+    const list = (events.json as { events?: Array<{ type: string; data?: unknown }> }).events ?? [];
+    const breachEvent = list.find((e) => e.type === 'cap.breached');
+    expect(breachEvent, driver.describe(
+      'RFCS/0008-wasm-abi.md §K',
+      'host MUST emit cap.breached when a WASM module exceeds its memory ceiling',
+    )).toBeDefined();
+    const breachKind = (breachEvent?.data as { kind?: string } | undefined)?.kind;
+    expect(breachKind, driver.describe(
+      'RFCS/0008-wasm-abi.md §K',
+      'cap.breached payload MUST carry kind: "wasm-memory" for memory-ceiling breaches',
+    )).toBe('wasm-memory');
+  });
+});

package/src/scenarios/webhook-negative.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Webhook negative-path contract (webhooks.md + review hardening).
+ *
+ * Exercises three failure surfaces that the positive `webhook-signed-
+ * delivery.test.ts` doesn't cover:
+ *   1. SSRF guard — `POST /v1/webhooks` with a private-IP destination
+ *      returns 400 `webhook_url_rejected` on hosts that enforce it.
+ *   2. URL validation — malformed `url` returns 400 `validation_error`.
+ *   3. Unregister of unknown subscription — `DELETE /v1/webhooks/{id}`
+ *      returns 404 `subscription_not_found`.
+ *
+ * Capability-gated: skips when the host does not advertise
+ * `capabilities.webhooks.supported = true`.
+ *
+ * SSRF gating: hosts that don't implement the guard (or bypass it via
+ * `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true`) will accept the loopback URL
+ * with 201 — that's acceptable spec behavior, so the SSRF subtest
+ * soft-skips with a warning rather than failing.
+ *
+ * @see spec/v1/webhooks.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+async function isWebhookSupported(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const caps = (disco.json as { capabilities?: { webhooks?: { supported?: boolean } } })
+    .capabilities;
+  return caps?.webhooks?.supported === true;
+}
+
+describe('webhook-negative: SSRF guard rejects private destinations', () => {
+  it('host with SSRF guard returns 400 webhook_url_rejected for loopback', async () => {
+    if (!(await isWebhookSupported())) {
+      // eslint-disable-next-line no-console
+      console.warn('[webhook-negative] host does not advertise webhook support; skipping');
+      return;
+    }
+    const reg = await driver.post('/v1/webhooks', { url: 'http://127.0.0.1:65535/' });
+    if (reg.status === 201) {
+      // Host accepted — SSRF guard not implemented or bypassed.
+      // Soft-skip; this is acceptable per spec.
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[webhook-negative] host accepts loopback destinations; SSRF guard not enforced',
+      );
+      // Cleanup the subscription so we don't leak state.
+      const body = reg.json as { subscriptionId?: string };
+      if (body.subscriptionId) {
+        await driver.delete(`/v1/webhooks/${encodeURIComponent(body.subscriptionId)}`);
+      }
+      return;
+    }
+    expect(reg.status, driver.describe(
+      'webhooks.md + review §"Webhook SSRF guard"',
+      'host with SSRF guard MUST return 400 for loopback / RFC1918 / link-local destinations',
+    )).toBe(400);
+    const body = reg.json as { error?: string };
+    expect(body.error).toBe('webhook_url_rejected');
+  });
+});
+
+describe('webhook-negative: validation errors', () => {
+  it('malformed url returns 400 validation_error', async () => {
+    if (!(await isWebhookSupported())) return;
+    const reg = await driver.post('/v1/webhooks', { url: 'not a url' });
+    expect([400, 422]).toContain(reg.status);
+    const body = reg.json as { error?: string };
+    expect(['validation_error', 'webhook_url_rejected']).toContain(body.error);
+  });
+
+  it('missing url returns 400 validation_error', async () => {
+    if (!(await isWebhookSupported())) return;
+    const reg = await driver.post('/v1/webhooks', { eventTypes: ['run.completed'] });
+    expect(reg.status).toBe(400);
+    const body = reg.json as { error?: string };
+    expect(body.error).toBe('validation_error');
+  });
+});
+
+describe('webhook-negative: unregister of unknown subscription', () => {
+  it('DELETE /v1/webhooks/{unknown} returns 404 subscription_not_found', async () => {
+    if (!(await isWebhookSupported())) return;
+    const del = await driver.delete('/v1/webhooks/wh-does-not-exist');
+    expect(del.status).toBe(404);
+    const body = del.json as { error?: string };
+    expect(body.error).toBe('subscription_not_found');
+  });
+});