@openwop/openwop-conformance 1.1.1 → 1.2.0

package/src/scenarios/fs-path-traversal.test.ts

@@ -0,0 +1,124 @@
+/**
+ * fs-path-traversal — RFC 0014 §C invariant verification.
+ *
+ * Status: ACTIVE. RFC 0014 promoted to `Active` 2026-05-17. The
+ * `capabilities.fs` block has landed in `schemas/capabilities.schema.json`
+ * and the invariant row `fs-path-traversal` is in `SECURITY/invariants.yaml`.
+ *
+ * Capability-gated: skips when the host does not advertise
+ * `capabilities.fs.supported = true`.
+ *
+ * What this scenario asserts:
+ *   1. Advertisement shape — `capabilities.fs` is either absent or a
+ *      well-formed object; when `supported: true`, `sandboxRoot` is
+ *      non-empty (RFC 0014 §A).
+ *   2. Path-traversal MUST-NOT — when the host exposes the optional
+ *      `POST /v1/host/sample/fs/read` test seam, absolute paths outside
+ *      the sandbox AND relative `../` escapes MUST be rejected with a
+ *      4xx envelope whose `error.code` is in the canonical rejection set.
+ *
+ * Hosts without the test seam soft-skip the path-escape steps and still
+ * assert the advertisement shape. This lets the suite pass against the
+ * stricter hosts that don't expose any unauthenticated fs probe.
+ *
+ * @see RFCS/0014-host-fs-capability.md
+ * @see SECURITY/invariants.yaml id: fs-path-traversal
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryFs {
+  supported?: boolean;
+  sandboxRoot?: string;
+  maxFileSizeBytes?: number;
+}
+
+interface DiscoveryDoc {
+  capabilities?: {
+    fs?: DiscoveryFs;
+  };
+}
+
+async function readFs(): Promise<DiscoveryFs | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return body?.capabilities?.fs ?? null;
+}
+
+const PATH_REJECTION_CODES: ReadonlySet<string> = new Set([
+  'path_outside_sandbox',
+  'fs_path_traversal',
+  'invalid_path',
+]);
+
+describe('fs-path-traversal: advertisement shape (RFC 0014 §A)', () => {
+  it('capabilities.fs is either absent or well-formed', async () => {
+    const fs = await readFs();
+    if (fs === null) return; // host doesn't advertise fs at all
+    expect(
+      typeof fs.supported,
+      driver.describe(
+        'capabilities.schema.json §fs',
+        'capabilities.fs.supported MUST be a boolean when fs is advertised',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('fs.sandboxRoot is set + non-empty when fs.supported=true', async () => {
+    const fs = await readFs();
+    if (!fs?.supported) return;
+    expect(
+      typeof fs.sandboxRoot,
+      driver.describe(
+        'RFC 0014 §A',
+        'capabilities.fs.sandboxRoot MUST be present when fs.supported=true',
+      ),
+    ).toBe('string');
+    expect(
+      (fs.sandboxRoot ?? '').length,
+      driver.describe('RFC 0014 §A', 'capabilities.fs.sandboxRoot MUST NOT be empty'),
+    ).toBeGreaterThan(0);
+  });
+});
+
+describe('fs-path-traversal: MUST-NOT escape sandboxRoot (RFC 0014 §C)', () => {
+  it('absolute path outside sandbox is rejected', async () => {
+    const fs = await readFs();
+    if (!fs?.supported) return;
+    const res = await driver.post('/v1/host/sample/fs/read', { path: '/etc/passwd' });
+    // 404 from a host that hasn't wired the test seam is a soft-skip.
+    if (res.status === 404) return;
+    expect(
+      res.status,
+      driver.describe(
+        'SECURITY/invariants.yaml fs-path-traversal',
+        'absolute paths outside sandboxRoot MUST be rejected with a 4xx envelope',
+      ),
+    ).toBeGreaterThanOrEqual(400);
+    const code = (res.json as { error?: { code?: string } } | undefined)?.error?.code;
+    expect(
+      code !== undefined && PATH_REJECTION_CODES.has(code),
+      driver.describe(
+        'SECURITY/invariants.yaml fs-path-traversal',
+        `error.code MUST be one of {${[...PATH_REJECTION_CODES].join(', ')}}, got: ${code ?? '(absent)'}`,
+      ),
+    ).toBe(true);
+  });
+
+  it('relative ../ path escape is rejected', async () => {
+    const fs = await readFs();
+    if (!fs?.supported) return;
+    const res = await driver.post('/v1/host/sample/fs/read', { path: '../../etc/passwd' });
+    if (res.status === 404) return;
+    expect(res.status).toBeGreaterThanOrEqual(400);
+    const code = (res.json as { error?: { code?: string } } | undefined)?.error?.code;
+    expect(
+      code !== undefined && PATH_REJECTION_CODES.has(code),
+      driver.describe(
+        'SECURITY/invariants.yaml fs-path-traversal',
+        `error.code MUST be one of {${[...PATH_REJECTION_CODES].join(', ')}}, got: ${code ?? '(absent)'}`,
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/idempotency-key-determinism.test.ts

@@ -0,0 +1,230 @@
+/**
+ * core.openwop.http.idempotency-key — determinism contract
+ *
+ * Verifies the normative MUST from `idempotency.md §"Idempotency-Key"`
+ * and the pack's documented purpose (retry-safety): identical
+ * `(runId, nodeId, payload)` → identical key, so the remote endpoint
+ * can dedupe across retries.
+ *
+ * Hardens against the 1.1.0 / 1.1.1 defect where the default `uuid`
+ * mode returned a fresh `randomUUID()` per call, defeating retry-safety
+ * (each retry produced a different key → remote treated every attempt
+ * as a new request). Removed in 1.1.2 as a safety-fix per
+ * `COMPATIBILITY.md §3` — see CHANGELOG `[Unreleased]` §"core.openwop.http@1.1.2".
+ *
+ * Server-free. Loads the pack module via dynamic import and asserts:
+ *
+ *   1. Default mode (`composite`) produces a deterministic key for
+ *      identical inputs.
+ *   2. Payload sensitivity — same run+node, different payload → different key.
+ *   3. Run isolation — same node+payload, different run → different key.
+ *   4. Node isolation — same run+payload, different node → different key.
+ *   5. `hash` mode is deterministic in the payload alone (run+node ignored).
+ *   6. Output shape matches the canonical `^openwop-[0-9a-f]{16}$` pattern
+ *      (per `idempotency-key.output.json` 1.1.2).
+ *   7. Removed `uuid` mode rejects with `CONFIG_INVALID` — the safety-fix
+ *      surfaces loudly rather than silently producing weak keys.
+ *   8. Pack output matches the canonical SHA-256 formula computed
+ *      independently in this test — third-party pack reimplementations
+ *      can run the same scenario against their runtime to verify
+ *      cross-impl agreement.
+ *
+ * Skip-conditions: none. The scenario validates the spec corpus +
+ * reference pack source directly; runs in any environment with the
+ * repo checked out.
+ *
+ * @see spec/v1/idempotency.md §"Idempotency-Key"
+ * @see packs/core.openwop.http/schemas/idempotency-key.config.json
+ * @see packs/core.openwop.http/schemas/idempotency-key.output.json
+ * @see SECURITY/invariants.yaml#idempotency-key-deterministic
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACK_PATH = resolve(__dirname, '../../../packs/core.openwop.http/index.mjs');
+
+interface IdempotencyKeyCtx {
+  config?: { mode?: string };
+  inputs?: { payload?: unknown; runId?: string; nodeId?: string };
+  runId?: string;
+  nodeId?: string;
+}
+
+interface IdempotencyKeyResult {
+  status: 'success';
+  outputs: { key: string };
+}
+
+type IdempotencyKeyFn = (ctx: IdempotencyKeyCtx) => Promise<IdempotencyKeyResult>;
+
+const KEY_PATTERN = /^openwop-[0-9a-f]{16}$/;
+
+/**
+ * Canonical formula per `idempotency-key.{config,output}.json` (1.1.2):
+ *   sha256( runId || \0 || nodeId || \0 || JSON.stringify(payload) )
+ *   key = 'openwop-' + digest.hex().slice(0, 16)
+ *
+ * Mirrors `deriveIdempotencyKey` in `packs/core.openwop.http/index.mjs`
+ * (the same formula `core.openwop.http.fetch` uses internally). Inlined
+ * here so the test verifies the spec contract independent of the pack
+ * runtime — a third-party reimplementation that follows the spec MUST
+ * produce identical keys for these vectors.
+ */
+function canonicalCompositeKey(runId: string, nodeId: string, payload: unknown): string {
+  const h = createHash('sha256');
+  h.update(runId, 'utf8');
+  h.update('\0', 'utf8');
+  h.update(nodeId, 'utf8');
+  h.update('\0', 'utf8');
+  if (payload !== undefined && payload !== null) {
+    h.update(JSON.stringify(payload), 'utf8');
+  }
+  return 'openwop-' + h.digest('hex').slice(0, 16);
+}
+
+function canonicalHashKey(payload: unknown): string {
+  const h = createHash('sha256').update(JSON.stringify(payload ?? null), 'utf8').digest('hex');
+  return 'openwop-' + h.slice(0, 16);
+}
+
+describe('category: core.openwop.http.idempotency-key — determinism contract', () => {
+  let idempotencyKey: IdempotencyKeyFn;
+  let packAvailable: boolean;
+
+  beforeAll(async () => {
+    packAvailable = existsSync(PACK_PATH);
+    if (!packAvailable) return;
+    const mod = (await import(PACK_PATH)) as { idempotencyKey?: IdempotencyKeyFn };
+    if (typeof mod.idempotencyKey !== 'function') {
+      throw new Error(
+        `expected packs/core.openwop.http/index.mjs to export idempotencyKey; got ${typeof mod.idempotencyKey}`,
+      );
+    }
+    idempotencyKey = mod.idempotencyKey;
+  });
+
+  it('skips cleanly when packs/ is not bundled', () => {
+    // This scenario reads the in-tree pack source. When the conformance
+    // suite is consumed as a published npm package, packs/ isn't shipped
+    // — the scenario soft-skips rather than failing.
+    if (!packAvailable) {
+      console.warn(`[idempotency-key-determinism] packs/core.openwop.http/index.mjs not present; skipping`);
+      expect(packAvailable).toBe(false);
+      return;
+    }
+    expect(packAvailable).toBe(true);
+  });
+
+  it('default mode (composite) — identical (runId, nodeId, payload) produces identical keys', async () => {
+    if (!packAvailable) return;
+    const ctx: IdempotencyKeyCtx = {
+      runId: 'run-1',
+      nodeId: 'node-1',
+      inputs: { payload: { hello: 'world' } },
+    };
+    const a = await idempotencyKey(ctx);
+    const b = await idempotencyKey(ctx);
+    expect(a.outputs.key, 'idempotency.md §Idempotency-Key: same logical request MUST produce same key').toBe(b.outputs.key);
+    expect(a.outputs.key).toMatch(KEY_PATTERN);
+  });
+
+  it('payload sensitivity — different payload produces different key', async () => {
+    if (!packAvailable) return;
+    const baseCtx = { runId: 'run-1', nodeId: 'node-1' };
+    const a = await idempotencyKey({ ...baseCtx, inputs: { payload: { hello: 'world' } } });
+    const b = await idempotencyKey({ ...baseCtx, inputs: { payload: { hello: 'CHANGED' } } });
+    expect(a.outputs.key).not.toBe(b.outputs.key);
+  });
+
+  it('run isolation — different runId produces different key', async () => {
+    if (!packAvailable) return;
+    const payload = { hello: 'world' };
+    const a = await idempotencyKey({ runId: 'run-1', nodeId: 'node-1', inputs: { payload } });
+    const b = await idempotencyKey({ runId: 'run-2', nodeId: 'node-1', inputs: { payload } });
+    expect(a.outputs.key).not.toBe(b.outputs.key);
+  });
+
+  it('node isolation — different nodeId produces different key', async () => {
+    if (!packAvailable) return;
+    const payload = { hello: 'world' };
+    const a = await idempotencyKey({ runId: 'run-1', nodeId: 'node-A', inputs: { payload } });
+    const b = await idempotencyKey({ runId: 'run-1', nodeId: 'node-B', inputs: { payload } });
+    expect(a.outputs.key).not.toBe(b.outputs.key);
+  });
+
+  it('hash mode is deterministic in the payload alone (run/node ignored)', async () => {
+    if (!packAvailable) return;
+    const payload = { request: 'payload-here', id: 42 };
+    const a = await idempotencyKey({ config: { mode: 'hash' }, runId: 'run-1', nodeId: 'node-1', inputs: { payload } });
+    const b = await idempotencyKey({ config: { mode: 'hash' }, runId: 'run-2', nodeId: 'node-2', inputs: { payload } });
+    expect(a.outputs.key, 'hash mode MUST ignore run/node — useful for global remote-dedup caches').toBe(b.outputs.key);
+    expect(a.outputs.key).toMatch(KEY_PATTERN);
+  });
+
+  it('output shape — every emitted key matches openwop-<sha256-prefix-16>', async () => {
+    if (!packAvailable) return;
+    const samples: IdempotencyKeyCtx[] = [
+      { runId: 'r', nodeId: 'n', inputs: { payload: null } },
+      { runId: 'r', nodeId: 'n', inputs: { payload: 'string-payload' } },
+      { runId: 'r', nodeId: 'n', inputs: { payload: [1, 2, 3] } },
+      { runId: 'r', nodeId: 'n', inputs: { payload: { nested: { value: true } } } },
+      { config: { mode: 'hash' }, inputs: { payload: 'x' } },
+    ];
+    for (const ctx of samples) {
+      const result = await idempotencyKey(ctx);
+      expect(result.outputs.key, `key shape for ctx=${JSON.stringify(ctx)}`).toMatch(KEY_PATTERN);
+    }
+  });
+
+  it('uuid mode rejects with CONFIG_INVALID (safety-fix per 1.1.2)', async () => {
+    if (!packAvailable) return;
+    // The removed mode names the safety-fix in its error message so
+    // pinned-version callers diagnosing a regression find the fix.
+    let caught: unknown;
+    try {
+      await idempotencyKey({ config: { mode: 'uuid' }, inputs: { payload: 'x' } });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught, 'mode: uuid MUST be rejected — the 1.1.0/1.1.1 non-deterministic default was removed').toBeInstanceOf(Error);
+    expect((caught as Error & { code?: string }).code).toBe('CONFIG_INVALID');
+    expect((caught as Error).message).toMatch(/uuid.*removed|safety-fix/i);
+  });
+
+  it('cross-impl invariant — pack output equals canonical SHA-256 formula', async () => {
+    if (!packAvailable) return;
+    // Five fixed vectors. A third-party core.openwop.http reimplementation
+    // can run the same scenario against its runtime — agreement on these
+    // vectors proves wire-level interop on the Idempotency-Key shape.
+    const vectors = [
+      { runId: 'run-A', nodeId: 'node-1', payload: { task: 'create-charge', amount: 100 } },
+      { runId: 'run-A', nodeId: 'node-2', payload: { task: 'create-charge', amount: 100 } },
+      { runId: 'run-B', nodeId: 'node-1', payload: { task: 'create-charge', amount: 100 } },
+      { runId: 'r', nodeId: 'n', payload: null },
+      { runId: 'r', nodeId: 'n', payload: 'just-a-string' },
+    ];
+    for (const v of vectors) {
+      const packed = await idempotencyKey({
+        runId: v.runId,
+        nodeId: v.nodeId,
+        inputs: { payload: v.payload },
+      });
+      const expected = canonicalCompositeKey(v.runId, v.nodeId, v.payload);
+      expect(
+        packed.outputs.key,
+        `vector ${JSON.stringify(v)} — pack output MUST match canonical sha256(runId\\0nodeId\\0JSON(payload))`,
+      ).toBe(expected);
+    }
+
+    // Hash-mode vectors: same formula independent of run/node.
+    for (const payload of [null, 'x', { nested: 1 }, [1, 2]]) {
+      const packed = await idempotencyKey({ config: { mode: 'hash' }, inputs: { payload } });
+      expect(packed.outputs.key).toBe(canonicalHashKey(payload));
+    }
+  });
+});

package/src/scenarios/interrupt-token-matrix.test.ts

@@ -0,0 +1,126 @@
+/**
+ * CF-3 close-out — interrupt token matrix coverage per
+ * `plans/openwop-protocol-gap-closure-plan.md` Workstream 2.
+ *
+ * Verifies the negative + replay paths on `GET /v1/interrupts/{token}`
+ * and `POST /v1/interrupts/{token}` that complement the existing
+ * positive-path coverage in `interrupt-external-event-correlation.test.ts`:
+ *
+ *   1. Malformed token (random bytes) — inspect MUST return 400 or 404.
+ *   2. Unknown token (well-formed but no interrupt) — inspect MUST
+ *      return 404 with `not_found` or similar.
+ *   3. Already-resolved token — resolve once (positive path),
+ *      then replay the same `POST` — MUST return 409 or 404 (host
+ *      MAY treat already-resolved as gone OR as conflict).
+ *   4. Wrong action — `POST` with a payload whose `action` field is
+ *      NOT in the interrupt's allowed-actions list MUST return 400
+ *      `validation_error`.
+ *   5. Cross-run-id leak — synthesize a token with `runId=other-run`
+ *      embedded but valid HMAC envelope — MUST return 401 or 404
+ *      (NEVER 200 from a different run's scope).
+ *
+ * Gating identical to interrupt-external-event-correlation: skips when
+ * the `conformance-external-event` fixture isn't advertised.
+ *
+ * @see spec/v1/interrupt.md §"Signed-token callback"
+ * @see spec/v1/rest-endpoints.md §"GET /v1/interrupts/{token}" + §"POST /v1/interrupts/{token}"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilStatus } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const FIXTURE = 'conformance-external-event';
+const SKIP = !isFixtureAdvertised(FIXTURE);
+
+function randomBytesB64(length: number): string {
+  return Buffer.from(
+    Array.from({ length }, () => Math.floor(Math.random() * 256)),
+  ).toString('base64url');
+}
+
+describe.skipIf(SKIP)('interrupt-token-matrix: GET /v1/interrupts/{token} negative paths', () => {
+  it('malformed token returns 400 or 404 (NEVER 200)', async () => {
+    const malformed = '!!!not-a-valid-token!!!';
+    const res = await driver.get(`/v1/interrupts/${encodeURIComponent(malformed)}`);
+    expect([400, 404]).toContain(res.status);
+    expect(res.status, driver.describe(
+      'rest-endpoints.md GET /v1/interrupts/{token}',
+      'malformed interrupt token MUST NOT return 200',
+    )).not.toBe(200);
+  });
+
+  it('well-formed but unknown token returns 404', async () => {
+    // Plausibly-shaped opaque token that the host has no record of.
+    const unknown = `tok_${randomBytesB64(32)}`;
+    const res = await driver.get(`/v1/interrupts/${encodeURIComponent(unknown)}`);
+    expect(res.status, driver.describe(
+      'rest-endpoints.md GET /v1/interrupts/{token}',
+      'unknown interrupt token MUST return 404',
+    )).toBe(404);
+  });
+});
+
+describe.skipIf(SKIP)('interrupt-token-matrix: POST /v1/interrupts/{token} negative paths', () => {
+  it('replay after successful resolve returns 409 or 404', async () => {
+    // Drive a run to suspension; capture the real token; resolve once;
+    // replay the same POST and assert it doesn't succeed twice.
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    await pollUntilStatus(runId, 'waiting-external-event', { timeoutMs: 10_000 }).catch(() => null);
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const interrupts =
+      ((snap.json as { interrupts?: Array<{ token?: string }> }).interrupts ?? [])
+        .filter((i) => typeof i.token === 'string');
+    const token = interrupts[0]?.token;
+    if (typeof token !== 'string') {
+      // eslint-disable-next-line no-console
+      console.warn('[interrupt-token-matrix] host did not surface an interrupt token; skipping replay subtest');
+      await driver.post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, {
+        reason: 'conformance-cleanup',
+      });
+      return;
+    }
+
+    const resolve1 = await driver.post(`/v1/interrupts/${encodeURIComponent(token)}`, {
+      correlation: { orderId: 'order-token-matrix', status: 'accepted' },
+    });
+    if (resolve1.status !== 200 && resolve1.status !== 202) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[interrupt-token-matrix] first resolve returned ${resolve1.status}; can't exercise replay path. Skipping.`,
+      );
+      await driver.post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, {
+        reason: 'conformance-cleanup',
+      });
+      return;
+    }
+
+    const resolve2 = await driver.post(`/v1/interrupts/${encodeURIComponent(token)}`, {
+      correlation: { orderId: 'order-token-matrix', status: 'accepted' },
+    });
+    expect([404, 409, 410], driver.describe(
+      'rest-endpoints.md POST /v1/interrupts/{token}',
+      'replay of an already-resolved interrupt token MUST NOT return 2xx (host MAY 404/409/410)',
+    )).toContain(resolve2.status);
+
+    await driver.post(`/v1/runs/${encodeURIComponent(runId)}/cancel`, {
+      reason: 'conformance-cleanup',
+    });
+  });
+
+  it('unknown token returns 404 on POST', async () => {
+    const unknown = `tok_${randomBytesB64(32)}`;
+    const res = await driver.post(`/v1/interrupts/${encodeURIComponent(unknown)}`, {
+      correlation: { orderId: 'noop', status: 'whatever' },
+    });
+    expect(res.status, driver.describe(
+      'rest-endpoints.md POST /v1/interrupts/{token}',
+      'POST on an unknown interrupt token MUST return 404',
+    )).toBe(404);
+  });
+});

package/src/scenarios/kv-atomic-increment.test.ts

@@ -0,0 +1,74 @@
+/**
+ * kv-atomic-increment — RFC 0015 §B point 4 (atomic increment).
+ *
+ * Status: ACTIVE (advertisement + behavioral). Behavioral half drives N
+ * concurrent +1 increments through the reference-host test seam and asserts
+ * the final value equals N. Hosts that don't expose the seam soft-skip.
+ *
+ * @see RFCS/0015-host-kv-storage-capability.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["kvStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'kv', op, args });
+}
+
+describe('kv-atomic-increment: advertisement shape (RFC 0015)', () => {
+  it('capabilities.kvStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return;
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §kvStorage',
+        'capabilities.kvStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('atomicIncrement is a boolean when set', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const sub = cap.atomicIncrement;
+    if (sub === undefined) return;
+    expect(typeof sub, driver.describe('RFC 0015 §A', 'atomicIncrement MUST be boolean when present')).toBe('boolean');
+  });
+});
+
+describe('kv-atomic-increment: behavioral (RFC 0015 §B point 4)', () => {
+  it('N concurrent +1 increments converge to exactly N', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true || cap.atomicIncrement !== true) return;
+    const key = `atomic-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const probe = await call('atomicIncrement', { key, delta: 0 });
+    if (probe.status === 404) return; // seam not exposed
+
+    const N = 50;
+    const results = await Promise.all(
+      Array.from({ length: N }, () => call('atomicIncrement', { key, delta: 1 })),
+    );
+    for (const r of results) {
+      expect(r.status, 'each increment MUST succeed').toBe(200);
+    }
+    const finalRes = await call('get', { key });
+    const finalBody = finalRes.json as { value?: unknown };
+    expect(
+      finalBody.value,
+      driver.describe('RFC 0015 §B point 4', `${N} concurrent increments MUST converge to exactly ${N}`),
+    ).toBe(N);
+  });
+});

package/src/scenarios/kv-cas.test.ts

@@ -0,0 +1,75 @@
+/**
+ * kv-cas — RFC 0015 §B point 5 (compare-and-swap atomicity).
+ *
+ * Status: ACTIVE (advertisement + behavioral). Asserts that a matching
+ * `expect` swaps and a stale `expect` rejects with `swapped:false` and
+ * returns the current actual value.
+ *
+ * @see RFCS/0015-host-kv-storage-capability.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["kvStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'kv', op, args });
+}
+
+describe('kv-cas: advertisement shape (RFC 0015)', () => {
+  it('capabilities.kvStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return;
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §kvStorage',
+        'capabilities.kvStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('compareAndSwap is a boolean when set', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const sub = cap.compareAndSwap;
+    if (sub === undefined) return;
+    expect(typeof sub, driver.describe('RFC 0015 §A', 'compareAndSwap MUST be boolean when present')).toBe('boolean');
+  });
+});
+
+describe('kv-cas: behavioral (RFC 0015 §B point 5)', () => {
+  it('CAS with matching expect succeeds; stale expect fails with swapped:false', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true || cap.compareAndSwap !== true) return;
+    const key = `cas-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const setRes = await call('set', { key, value: 'v1' });
+    if (setRes.status === 404) return;
+    expect(setRes.status).toBe(200);
+
+    // Matching expect → swaps.
+    const okRes = await call('cas', { key, expect: 'v1', set: 'v2' });
+    expect(okRes.status, 'matching CAS MUST 200').toBe(200);
+    const okBody = okRes.json as { swapped?: boolean };
+    expect(okBody.swapped, 'matching expect MUST swap').toBe(true);
+
+    // Stale expect → no swap.
+    const staleRes = await call('cas', { key, expect: 'v1', set: 'v3' });
+    expect(staleRes.status, 'stale CAS MUST 200 (CAS is non-throwing)').toBe(200);
+    const staleBody = staleRes.json as { swapped?: boolean; actual?: unknown };
+    expect(staleBody.swapped, 'stale expect MUST NOT swap').toBe(false);
+    expect(staleBody.actual, 'stale CAS MUST surface current value').toBe('v2');
+  });
+});