@openwop/openwop-conformance 1.0.0

package/src/scenarios/wasm-pack-load.test.ts

@@ -0,0 +1,75 @@
+/**
+ * RFC 0008 §Conformance — scenario 1/6: pack load + identity.
+ *
+ * Verifies that a host advertising `capabilities.nodePackRuntimes.wasm.supported: true`:
+ *   1. Loads a signed WASM pack at startup or on-demand.
+ *   2. Surfaces the pack's typeIds for dispatch.
+ *   3. Reports the loaded pack's name + ABI version via discovery.
+ *
+ * Hosts that don't advertise WASM support skip this scenario.
+ *
+ * @see RFCS/0008-wasm-abi.md §B (required exports)
+ * @see RFCS/0008-wasm-abi.md §H (capability advertisement)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const FIXTURE = 'conformance-wasm-pack-roundtrip';
+
+interface WasmCaps {
+  supported?: boolean;
+  abiVersions?: number[];
+  engine?: string;
+  engineVersion?: string;
+}
+
+async function getWasmCaps(): Promise<WasmCaps | null> {
+  const disco = await driver.get('/.well-known/openwop');
+  const caps =
+    (disco.json as { capabilities?: { nodePackRuntimes?: { wasm?: WasmCaps } } })
+      .capabilities?.nodePackRuntimes?.wasm ?? null;
+  return caps;
+}
+
+describe('wasm-pack-load: discovery surfaces WASM runtime support', () => {
+  it('a host claiming WASM support advertises abiVersions including 1', async () => {
+    const wasm = await getWasmCaps();
+    if (!wasm?.supported) {
+      // eslint-disable-next-line no-console
+      console.warn('[wasm-pack-load] host does not advertise WASM support; skipping');
+      return;
+    }
+    expect(Array.isArray(wasm.abiVersions), driver.describe(
+      'RFCS/0008-wasm-abi.md §H',
+      'capabilities.nodePackRuntimes.wasm.abiVersions MUST be an array',
+    )).toBe(true);
+    expect(wasm.abiVersions?.includes(1), driver.describe(
+      'RFCS/0008-wasm-abi.md §H',
+      'abiVersions MUST include 1 (this RFC) when supported',
+    )).toBe(true);
+  });
+});
+
+describe('wasm-pack-load: loaded pack typeIds are dispatchable', () => {
+  it('host accepts a workflow whose node typeId is provided by a loaded WASM pack', async () => {
+    const wasm = await getWasmCaps();
+    if (!wasm?.supported) return;
+    if (!isFixtureAdvertised(FIXTURE)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[wasm-pack-load] fixture ${FIXTURE} not advertised; skipping`);
+      return;
+    }
+    // Creating a run against the fixture proves the host knows about the
+    // WASM-provided typeId. A host that loaded the pack accepts the
+    // POST /v1/runs; one that didn't would return 400/404.
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE, inputs: { name: 'world' } });
+    expect(create.status, driver.describe(
+      'RFCS/0008-wasm-abi.md §B + node-packs.md §Reserved typeIds',
+      'host MUST accept runs whose nodes reference loaded-pack typeIds',
+    )).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await driver.post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, { reason: 'conformance-cleanup' });
+  });
+});

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

@@ -0,0 +1,43 @@
+/**
+ * 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'`.
+ *
+ * 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.
+ *
+ * Driving a real OOM requires a deliberately misbehaving pack. Such a
+ * pack is filed as v1.x follow-up; the framework lives here.
+ *
+ * @see RFCS/0008-wasm-abi.md §K (resource limits)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+describe('wasm-pack-memory-cap: host advertises maxMemoryBytes', () => {
+  it('capabilities.nodePackRuntimes.wasm.maxMemoryBytes is a plausible number', async () => {
+    const disco = await driver.get('/.well-known/openwop');
+    const wasm =
+      (disco.json as {
+        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean; maxMemoryBytes?: unknown } } };
+      }).capabilities?.nodePackRuntimes?.wasm;
+
+    if (!wasm?.supported) return;
+
+    // The cap is REQUIRED to enforce §K. Hosts MUST surface the configured
+    // ceiling so clients can size their packs accordingly.
+    expect(typeof wasm.maxMemoryBytes, driver.describe(
+      'RFCS/0008-wasm-abi.md §K',
+      'capabilities.nodePackRuntimes.wasm.maxMemoryBytes MUST be advertised as a number when WASM is supported',
+    )).toBe('number');
+    if (typeof wasm.maxMemoryBytes === 'number') {
+      expect(wasm.maxMemoryBytes).toBeGreaterThanOrEqual(1024 * 1024); // ≥ 1 MiB
+      expect(wasm.maxMemoryBytes).toBeLessThanOrEqual(8 * 1024 * 1024 * 1024); // ≤ 8 GiB
+    }
+  });
+});

package/src/scenarios/wasm-pack-replay-determinism.test.ts

@@ -0,0 +1,61 @@
+/**
+ * RFC 0008 §Conformance — scenario 4/6: replay determinism.
+ *
+ * Verifies that re-running the same WASM workflow with the same inputs
+ * yields the same output, AND that `:fork` against a completed run
+ * reproduces the same final state. RFC 0008 §G requires that
+ * `openwop_now_ms` and `openwop_random` be host-controlled and replay-
+ * stable; this scenario indirectly verifies the contract.
+ *
+ * @see RFCS/0008-wasm-abi.md §G (replay determinism)
+ */
+
+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 FIXTURE = 'conformance-wasm-pack-roundtrip';
+
+async function isWasmSupported(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  return Boolean(
+    (disco.json as { capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } } })
+      .capabilities?.nodePackRuntimes?.wasm?.supported,
+  );
+}
+
+function extractGreeting(events: Array<{ type: string; data?: unknown }>): string | null {
+  const haystack = JSON.stringify(events);
+  const m = haystack.match(/Hello, ([^!]+)!/);
+  return m ? m[1] : null;
+}
+
+describe('wasm-pack-replay-determinism: same inputs → same output', () => {
+  it('two independent runs with same inputs produce same WASM output', async () => {
+    if (!isFixtureAdvertised(FIXTURE)) return;
+    if (!(await isWasmSupported())) return;
+
+    const inputs = { name: 'determinism-probe' };
+
+    const run = async (): Promise<string | null> => {
+      const create = await driver.post('/v1/runs', { workflowId: FIXTURE, inputs });
+      expect(create.status).toBe(201);
+      const runId = (create.json as { runId: string }).runId;
+      await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+      const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
+      return extractGreeting(
+        (events.json as { events?: Array<{ type: string; data?: unknown }> }).events ?? [],
+      );
+    };
+
+    const a = await run();
+    const b = await run();
+
+    expect(a, driver.describe(
+      'RFCS/0008-wasm-abi.md §G',
+      'WASM-node output MUST be reproducible given the same inputs',
+    )).not.toBeNull();
+    expect(b).toBe(a);
+  });
+});

package/src/scenarios/webhook-sig-algorithm.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Track 13: webhook signature-algorithm versioning (webhooks.md v1.1).
+ *
+ * Verifies that hosts adopting v1.1+ set the `X-openwop-Signature-Algorithm`
+ * header to a recognized value (currently `v1`) on every webhook delivery,
+ * and that subscribers can rely on the absence-equals-v1 rule.
+ *
+ * This scenario observes the host's registered subscription receipts —
+ * it does not exercise the dispatch path end-to-end (which would require
+ * a public-internet test receiver). The full dispatch is exercised by
+ * the host-side webhook test harness.
+ *
+ * @see spec/v1/webhooks.md §"Signature algorithm versioning"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryWebhooks {
+  webhooks?: {
+    supported?: boolean;
+    signatureAlgorithms?: string[];
+  };
+}
+
+describe('webhook-sig-algorithm: host advertises supported algorithm set', () => {
+  it('discovery surfaces a webhooks.signatureAlgorithms array including "v1"', async () => {
+    const disco = await driver.get('/.well-known/openwop');
+    const caps = (disco.json as { capabilities?: DiscoveryWebhooks }).capabilities ?? {};
+    const webhooks = caps.webhooks;
+
+    if (!webhooks?.supported) {
+      // eslint-disable-next-line no-console
+      console.warn('[webhook-sig-algorithm] host does not advertise webhook support; skipping');
+      return;
+    }
+
+    const algos = webhooks.signatureAlgorithms;
+    if (!Array.isArray(algos)) {
+      // Pre-v1.1 hosts that support webhooks but don't yet advertise the
+      // algorithm list are still v1-conformant — the absence-equals-v1
+      // rule applies. Skip the v1.1 shape check.
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[webhook-sig-algorithm] host does not advertise webhooks.signatureAlgorithms (pre-v1.1); skipping shape check',
+      );
+      return;
+    }
+
+    expect(algos.includes('v1'), driver.describe(
+      'webhooks.md §"Signature algorithm versioning"',
+      'webhooks.signatureAlgorithms MUST include "v1" when surfaced (canonical baseline)',
+    )).toBe(true);
+
+    // All declared algorithms MUST be non-empty strings.
+    for (const a of algos) {
+      expect(typeof a).toBe('string');
+      expect((a as string).length).toBeGreaterThan(0);
+    }
+  });
+});

package/src/setup.ts

@@ -0,0 +1,173 @@
+/**
+ * Suite-init setup (RFC 0003).
+ *
+ * Loaded by vitest via `test.setupFiles` BEFORE any scenario file is
+ * imported. Top-level `await` is supported in vitest's setup files so
+ * this can fetch the host's `/.well-known/openwop` once and populate the
+ * fixture-gating cache; `describe.skipIf(...)` predicates that read
+ * `isFixtureAdvertised(...)` then see the populated cache when they
+ * register their tests.
+ *
+ * Behavior matrix:
+ *
+ *   | OPENWOP_BASE_URL | discovery 200 | fixtures field | result |
+ *   |---|---|---|---|
+ *   | unset        | n/a            | n/a             | empty cache (offline mode) |
+ *   | set          | yes            | absent/empty    | empty cache (host advertises none) |
+ *   | set          | yes            | non-empty       | populated cache |
+ *   | set          | non-200 / err  | n/a             | empty cache + console warning |
+ *
+ * "Empty cache" means every fixture-dependent scenario skips. That is
+ * the correct outcome for a host that doesn't advertise the fixture
+ * surface — see RFC 0003 §"Implementation notes."
+ *
+ * This file is intentionally side-effect-only. Do NOT add `describe`/
+ * `it` here; vitest treats setupFiles differently from scenario files.
+ */
+
+import { setAdvertisedFixtures } from './lib/fixtures.js';
+import { setMultiAgentCapabilities } from './lib/multi-agent-capabilities.js';
+import { OtelCollector, setCollector } from './lib/otel-collector.js';
+import { McpFakeServer, setMcpFakeServer } from './lib/mcp-fake-server.js';
+import { A2AFakePeer, setA2AFakePeer } from './lib/a2a-fake-peer.js';
+import type { DiscoveryPayload } from './lib/profiles.js';
+
+const SUITE_INIT_TIMEOUT_MS = 5_000;
+
+async function loadHostFixtures(): Promise<void> {
+  const baseUrl = process.env.OPENWOP_BASE_URL?.trim();
+  if (!baseUrl) {
+    // Offline / fixture-stub-only run. No host to ask; treat as "host
+    // advertises no fixtures" so all fixture-dependent scenarios skip.
+    setAdvertisedFixtures(null);
+    setMultiAgentCapabilities(null);
+    return;
+  }
+
+  const normalizedBase = baseUrl.replace(/\/$/, '');
+  const url = `${normalizedBase}/.well-known/openwop`;
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SUITE_INIT_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[openwop-conformance setup] discovery fetch returned ${res.status}; ` +
+          `treating host as advertising no fixtures. Fixture-dependent scenarios will skip.`,
+      );
+      setAdvertisedFixtures(null);
+    setMultiAgentCapabilities(null);
+      return;
+    }
+    const body = (await res.json()) as DiscoveryPayload;
+    setAdvertisedFixtures(body);
+    setMultiAgentCapabilities(body);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[openwop-conformance setup] discovery fetch failed (${(err as Error).message ?? 'unknown'}); ` +
+        `treating host as advertising no fixtures. Fixture-dependent scenarios will skip.`,
+    );
+    setAdvertisedFixtures(null);
+    setMultiAgentCapabilities(null);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * OTel collector lifecycle (Track 11).
+ *
+ * Opt-in: only starts when `OPENWOP_OTEL_COLLECTOR=true` is set. Hosts
+ * that don't claim observability conformance skip the scenarios; hosts
+ * that do MUST be configured with
+ * `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:<port>` and
+ * `OTEL_EXPORTER_OTLP_PROTOCOL=http/json` before startup. The chosen
+ * port is exposed via `OPENWOP_OTEL_COLLECTOR_PORT` (read by scenarios
+ * for diagnostics) and printed to stderr at suite init.
+ */
+async function maybeStartOtelCollector(): Promise<void> {
+  if (process.env.OPENWOP_OTEL_COLLECTOR !== 'true') {
+    setCollector(null);
+    return;
+  }
+  const portEnv = process.env.OPENWOP_OTEL_COLLECTOR_PORT;
+  const requestedPort = portEnv ? Number(portEnv) : 4318;
+  const collector = new OtelCollector();
+  try {
+    await collector.start(requestedPort);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `[openwop-conformance setup] OTel collector failed to bind on port ${requestedPort} ` +
+        `(${(err as Error).message ?? 'unknown'}); falling back to ephemeral port.`,
+    );
+    await collector.start(0);
+  }
+  setCollector(collector);
+  // eslint-disable-next-line no-console
+  console.error(
+    `[openwop-conformance setup] OTel collector listening at ${collector.endpoint()}. ` +
+      `Configure the host with OTEL_EXPORTER_OTLP_ENDPOINT=${collector.endpoint()} ` +
+      `and OTEL_EXPORTER_OTLP_PROTOCOL=http/json.`,
+  );
+}
+
+/**
+ * MCP fake-server lifecycle (Track 6).
+ *
+ * Opt-in: only starts when `OPENWOP_MCP_FAKE_SERVER=true`. Operator
+ * configures the host to use the printed URL as one of its MCP servers
+ * (e.g., via host-specific config — the wire transport is normative
+ * but how the host registers servers is not).
+ */
+async function maybeStartMcpFakeServer(): Promise<void> {
+  if (process.env.OPENWOP_MCP_FAKE_SERVER !== 'true') {
+    setMcpFakeServer(null);
+    return;
+  }
+  const portEnv = process.env.OPENWOP_MCP_FAKE_SERVER_PORT;
+  const requestedPort = portEnv ? Number(portEnv) : 0;
+  const server = new McpFakeServer();
+  await server.start(requestedPort);
+  setMcpFakeServer(server);
+  // eslint-disable-next-line no-console
+  console.error(
+    `[openwop-conformance setup] MCP fake server listening at ${server.endpoint()}. ` +
+      `Configure the host's MCP integration to use this URL.`,
+  );
+}
+
+/**
+ * A2A fake peer lifecycle (Track 6).
+ *
+ * Opt-in via `OPENWOP_A2A_FAKE_PEER=true`. Operator configures the host
+ * to consume the printed AgentCard URL.
+ */
+async function maybeStartA2AFakePeer(): Promise<void> {
+  if (process.env.OPENWOP_A2A_FAKE_PEER !== 'true') {
+    setA2AFakePeer(null);
+    return;
+  }
+  const portEnv = process.env.OPENWOP_A2A_FAKE_PEER_PORT;
+  const requestedPort = portEnv ? Number(portEnv) : 0;
+  const peer = new A2AFakePeer();
+  await peer.start(requestedPort);
+  setA2AFakePeer(peer);
+  // eslint-disable-next-line no-console
+  console.error(
+    `[openwop-conformance setup] A2A fake peer listening at ${peer.endpoint()}. ` +
+      `AgentCard at ${peer.endpoint()}/agent.json.`,
+  );
+}
+
+await loadHostFixtures();
+await maybeStartOtelCollector();
+await maybeStartMcpFakeServer();
+await maybeStartA2AFakePeer();

package/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/scenarios/**/*.test.ts'],
+    testTimeout: 30_000,
+    hookTimeout: 30_000,
+    globals: true,
+    reporters: ['default'],
+    bail: 0,
+    // RFC 0003 — load the host's `/.well-known/openwop` `fixtures` array
+    // before any scenario file imports. Top-level await in setupFiles
+    // populates `lib/fixtures.ts` so `describe.skipIf(...)` predicates
+    // see the cached set when scenarios register their tests.
+    setupFiles: ['src/setup.ts'],
+  },
+});