@openwop/openwop-conformance 1.1.1 → 1.3.0

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');
+  });
+});

package/src/scenarios/kv-cross-tenant-isolation.test.ts

@@ -0,0 +1,85 @@
+/**
+ * kv-cross-tenant-isolation — RFC 0015 §B + SECURITY/invariants.yaml
+ * `kv-cross-tenant-isolation`.
+ *
+ * Status: ACTIVE (advertisement + behavioral). The behavioral half drives
+ * cross-tenant proof through the optional reference-host test seam at
+ * `POST /v1/host/sample/test/surface` (env-gated on `OPENWOP_TEST_SEAM_ENABLED=true`).
+ * Hosts that don't expose the seam (HTTP 404) soft-skip the behavioral
+ * assertions and verify advertisement shape only.
+ *
+ * Summary: host.kvStorage MUST partition values by tenant. A `set` issued
+ * under tenant A MUST NOT be visible to a `get` under tenant B at the
+ * same key.
+ *
+ * @see RFCS/0015-host-kv-storage-capability.md
+ * @see SECURITY/invariants.yaml — kv-cross-tenant-isolation
+ */
+
+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(tenantId: string, op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId, surface: 'kv', op, args });
+}
+
+describe('kv-cross-tenant-isolation: 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');
+  });
+});
+
+describe('kv-cross-tenant-isolation: behavioral (RFC 0015 §B)', () => {
+  it('set under tenant A → get under tenant B with same key returns found:false', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const key = `xtenant-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const setRes = await call('tenant-a', 'set', { key, value: 'from-A' });
+    if (setRes.status === 404) return; // host doesn't expose test seam
+    expect(setRes.status, driver.describe('RFC 0015 §B', 'set MUST succeed')).toBe(200);
+
+    const getRes = await call('tenant-b', 'get', { key });
+    expect(getRes.status).toBe(200);
+    const body = getRes.json as { value?: unknown; found?: boolean };
+    expect(
+      body.found,
+      driver.describe(
+        'SECURITY/invariants.yaml kv-cross-tenant-isolation',
+        'tenant B MUST NOT see tenant A value at the same key',
+      ),
+    ).toBe(false);
+  });
+
+  it('same-tenant set→get round-trips the value', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    const key = `roundtrip-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const setRes = await call('tenant-a', 'set', { key, value: 'rt-A' });
+    if (setRes.status === 404) return;
+    expect(setRes.status).toBe(200);
+    const getRes = await call('tenant-a', 'get', { key });
+    const body = getRes.json as { value?: unknown; found?: boolean };
+    expect(body.found, 'same-tenant get MUST succeed').toBe(true);
+    expect(body.value, 'same-tenant get MUST return the stored value').toBe('rt-A');
+  });
+});

package/src/scenarios/kv-ttl-expiry.test.ts

@@ -0,0 +1,78 @@
+/**
+ * kv-ttl-expiry — RFC 0015 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0015 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.kvStorage` block has landed in
+ * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
+ * shape against any host that boots the conformance suite, and keeps the
+ * deeper behavioral assertions as `it.todo()` until a reference host wires
+ * a test seam.
+ *
+ * Summary: TTL honored with at most a 1-second drift on expiry visibility.
+ *
+ * @see RFCS/0015-*.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);
+}
+
+describe('kv-ttl-expiry: advertisement shape (RFC 0015)', () => {
+  it('capabilities.kvStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §kvStorage',
+        'capabilities.kvStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+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-ttl-expiry: behavioral (RFC 0015 §B point 3 — 1s TTL drift)', () => {
+  it('set with ttlSeconds=2 → get before expiry returns value; get after expiry returns found:false', async () => {
+    const probe = await call('get', { key: '__ttl-probe__' });
+    if (probe.status === 404) return; // host doesn't expose the seam
+    const key = `ttl-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const setRes = await call('set', { key, value: 'expires-soon', ttlSeconds: 2 });
+    expect(setRes.status).toBe(200);
+
+    // Read within the window
+    const within = await call('get', { key });
+    expect(within.status).toBe(200);
+    const withinBody = within.json as { value?: unknown; found?: boolean };
+    expect(
+      withinBody.value,
+      driver.describe('RFC 0015 §B point 3', 'get within TTL window MUST return the stored value'),
+    ).toBe('expires-soon');
+    expect(withinBody.found).toBe(true);
+
+    // Wait past expiry (2s TTL + 1s drift allowance per RFC 0015 §B point 3)
+    await new Promise((r) => setTimeout(r, 3000));
+
+    const after = await call('get', { key });
+    expect(after.status).toBe(200);
+    const afterBody = after.json as { value?: unknown; found?: boolean };
+    expect(
+      afterBody.found,
+      driver.describe('RFC 0015 §B point 3', 'get after TTL expiry MUST surface as found:false (≤1s drift)'),
+    ).toBe(false);
+  });
+});

package/src/scenarios/mcp-server-elicitation-bridge.test.ts

@@ -0,0 +1,92 @@
+/**
+ * mcp-server-elicitation-bridge — RFC 0020 §A point 3 (bidirectional elicitation).
+ *
+ * Status: ACTIVE (advertisement + behavioral). Asserts that when a workflow
+ * has a `core.openwop.mcp.handle-elicitation` node, inbound `elicitation/create`
+ * is bridged into the workflow's `ctx.suspend({kind: 'clarification', profile:
+ * 'openwop-mcp-elicitation'})`. The host returns either a `pending` action
+ * (run suspended awaiting input) OR an accept/decline/cancel response (run
+ * completed without suspending).
+ *
+ * @see RFCS/0020-host-mcp-server-composition.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 cur = (top && typeof top === 'object') ? (top as Record<string, unknown>)["mcp"] : undefined;
+  const final = (cur && typeof cur === 'object') ? (cur as Record<string, unknown>)["serverMount"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function rpc(method: string, params?: Record<string, unknown>) {
+  const id = Math.floor(Math.random() * 1e6);
+  const req: Record<string, unknown> = { jsonrpc: '2.0', id, method };
+  if (params !== undefined) req.params = params;
+  const res = await driver.post('/v1/host/sample/mcp', req);
+  return { status: res.status, body: res.json as { result?: unknown; error?: { code: number; message: string } } };
+}
+
+async function registerElicitationHandlerWorkflow(): Promise<boolean> {
+  const res = await driver.post('/v1/host/sample/workflows', {
+    workflowId: `mcp.elicit.${Date.now()}`,
+    nodes: [
+      { nodeId: 'elicit', typeId: 'core.openwop.mcp.handle-elicitation' },
+    ],
+  });
+  return res.status === 200 || res.status === 201;
+}
+
+describe('mcp-server-elicitation-bridge: advertisement shape (RFC 0020)', () => {
+  it('elicitationBridge is a boolean when serverMount.supported', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    if (cap.elicitationBridge === undefined) return;
+    expect(
+      typeof cap.elicitationBridge,
+      driver.describe('RFC 0020 §B', 'mcp.serverMount.elicitationBridge MUST be boolean when present'),
+    ).toBe('boolean');
+  });
+});
+
+describe('mcp-server-elicitation-bridge: behavioral (RFC 0020 §A point 3)', () => {
+  it('elicitation/create bridges into a handle-elicitation workflow', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true || cap.elicitationBridge !== true) return;
+    if (!(await registerElicitationHandlerWorkflow())) return;
+
+    const r = await rpc('elicitation/create', {
+      message: 'What is your name?',
+      requestedSchema: {
+        type: 'object',
+        properties: { name: { type: 'string' } },
+        required: ['name'],
+      },
+    });
+    if (r.status === 404) return;
+    expect(r.status, 'JSON-RPC envelope MUST 200').toBe(200);
+    const dispatched = !!r.body.result || (!!r.body.error && r.body.error.code !== -32601);
+    expect(
+      dispatched,
+      driver.describe(
+        'RFC 0020 §A point 3',
+        'elicitation/create MUST dispatch to handle-elicitation workflow (not return method_not_found)',
+      ),
+    ).toBe(true);
+    if (r.body.result) {
+      const result = r.body.result as { action?: string };
+      expect(
+        ['pending', 'accept', 'decline', 'cancel'].includes(result.action ?? ''),
+        'elicitation response action MUST be one of {pending,accept,decline,cancel}',
+      ).toBe(true);
+    }
+  });
+});

package/src/scenarios/mcp-server-prompt-roundtrip.test.ts

@@ -0,0 +1,80 @@
+/**
+ * mcp-server-prompt-roundtrip — RFC 0020 §A (prompts/list + prompts/get).
+ *
+ * Status: ACTIVE (advertisement + behavioral).
+ *
+ * @see RFCS/0020-host-mcp-server-composition.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 cur = (top && typeof top === 'object') ? (top as Record<string, unknown>)["mcp"] : undefined;
+  const final = (cur && typeof cur === 'object') ? (cur as Record<string, unknown>)["serverMount"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function rpc(method: string, params?: Record<string, unknown>) {
+  const id = Math.floor(Math.random() * 1e6);
+  const req: Record<string, unknown> = { jsonrpc: '2.0', id, method };
+  if (params !== undefined) req.params = params;
+  const res = await driver.post('/v1/host/sample/mcp', req);
+  return { status: res.status, body: res.json as { result?: unknown; error?: { code: number; message: string } } };
+}
+
+const PROMPT_NAME = `prompt_${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+
+async function registerPromptWorkflow(): Promise<boolean> {
+  const res = await driver.post('/v1/host/sample/workflows', {
+    workflowId: `mcp.prompt.${Date.now()}`,
+    nodes: [
+      {
+        nodeId: 'expose',
+        typeId: 'core.openwop.mcp.expose-prompt',
+        config: {
+          name: PROMPT_NAME,
+          description: 'Conformance prompt',
+          arguments: [{ name: 'topic', description: 'subject of the prompt', required: false }],
+        },
+      },
+    ],
+  });
+  return res.status === 200 || res.status === 201;
+}
+
+describe('mcp-server-prompt-roundtrip: advertisement shape (RFC 0020)', () => {
+  it('capabilities.mcp.serverMount is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return;
+    expect(typeof cap.supported).toBe('boolean');
+  });
+});
+
+describe('mcp-server-prompt-roundtrip: behavioral (RFC 0020)', () => {
+  it('prompts/list returns the exposed prompt and prompts/get returns messages', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    if (!(await registerPromptWorkflow())) return;
+
+    const list = await rpc('prompts/list');
+    if (list.status === 404) return;
+    const prompts = (list.body.result as { prompts?: Array<{ name: string }> } | undefined)?.prompts ?? [];
+    expect(
+      prompts.find((p) => p.name === PROMPT_NAME),
+      driver.describe('RFC 0020 §A', 'prompts/list MUST include exposed prompts'),
+    ).toBeDefined();
+
+    const get = await rpc('prompts/get', { name: PROMPT_NAME, arguments: { topic: 'openwop' } });
+    expect(get.status).toBe(200);
+    const messages = (get.body.result as { messages?: Array<{ role: string }> } | undefined)?.messages;
+    expect(Array.isArray(messages), 'prompts/get MUST return messages[]').toBe(true);
+  });
+});

package/src/scenarios/mcp-server-resource-roundtrip.test.ts

@@ -0,0 +1,82 @@
+/**
+ * mcp-server-resource-roundtrip — RFC 0020 §A (resources/list + resources/read).
+ *
+ * Status: ACTIVE (advertisement + behavioral). Registers a workflow with
+ * `core.openwop.mcp.expose-resource`, then asserts the resource appears
+ * in `resources/list` and yields bound content from `resources/read`.
+ *
+ * @see RFCS/0020-host-mcp-server-composition.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 cur = (top && typeof top === 'object') ? (top as Record<string, unknown>)["mcp"] : undefined;
+  const final = (cur && typeof cur === 'object') ? (cur as Record<string, unknown>)["serverMount"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function rpc(method: string, params?: Record<string, unknown>) {
+  const id = Math.floor(Math.random() * 1e6);
+  const req: Record<string, unknown> = { jsonrpc: '2.0', id, method };
+  if (params !== undefined) req.params = params;
+  const res = await driver.post('/v1/host/sample/mcp', req);
+  return { status: res.status, body: res.json as { result?: unknown; error?: { code: number; message: string } } };
+}
+
+const RESOURCE_URI = `mcp://test/${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+
+async function registerResourceWorkflow(): Promise<boolean> {
+  const res = await driver.post('/v1/host/sample/workflows', {
+    workflowId: `mcp.resource.${Date.now()}`,
+    nodes: [
+      {
+        nodeId: 'expose',
+        typeId: 'core.openwop.mcp.expose-resource',
+        config: {
+          uri: RESOURCE_URI,
+          name: 'conformance-test-resource',
+          mimeType: 'text/plain',
+        },
+      },
+    ],
+  });
+  return res.status === 200 || res.status === 201;
+}
+
+describe('mcp-server-resource-roundtrip: advertisement shape (RFC 0020)', () => {
+  it('capabilities.mcp.serverMount is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return;
+    expect(typeof cap.supported, 'mcp.serverMount.supported MUST be boolean').toBe('boolean');
+  });
+});
+
+describe('mcp-server-resource-roundtrip: behavioral (RFC 0020)', () => {
+  it('resources/list returns the exposed resource and resources/read returns content', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    if (!(await registerResourceWorkflow())) return;
+
+    const list = await rpc('resources/list');
+    if (list.status === 404) return;
+    const resources = (list.body.result as { resources?: Array<{ uri: string }> } | undefined)?.resources ?? [];
+    expect(
+      resources.find((r) => r.uri === RESOURCE_URI),
+      driver.describe('RFC 0020 §A', 'resources/list MUST include exposed resources'),
+    ).toBeDefined();
+
+    const read = await rpc('resources/read', { uri: RESOURCE_URI });
+    expect(read.status).toBe(200);
+    const contents = (read.body.result as { contents?: Array<{ uri: string }> } | undefined)?.contents;
+    expect(Array.isArray(contents), 'resources/read MUST return contents[]').toBe(true);
+  });
+});

package/src/scenarios/mcp-server-sampling-bridge.test.ts

@@ -0,0 +1,84 @@
+/**
+ * mcp-server-sampling-bridge — RFC 0020 §A point 3 (bidirectional sampling).
+ *
+ * Status: ACTIVE (advertisement + behavioral). Asserts that when a workflow
+ * has a `core.openwop.mcp.handle-sampling` node, inbound `sampling/createMessage`
+ * is bridged into the workflow's `ctx.callAI` and returns a sampling result.
+ * Gated on `capabilities.mcp.serverMount.samplingBridge: true`.
+ *
+ * Acceptance test: dispatch produces either a sampling response (when AI
+ * keys are provisioned) OR a clean error envelope (proves bridge dispatched
+ * but BYOK is absent). Either outcome proves the bridge wired up correctly;
+ * a method_not_found (-32601) means the bridge did NOT dispatch.
+ *
+ * @see RFCS/0020-host-mcp-server-composition.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 cur = (top && typeof top === 'object') ? (top as Record<string, unknown>)["mcp"] : undefined;
+  const final = (cur && typeof cur === 'object') ? (cur as Record<string, unknown>)["serverMount"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+async function rpc(method: string, params?: Record<string, unknown>) {
+  const id = Math.floor(Math.random() * 1e6);
+  const req: Record<string, unknown> = { jsonrpc: '2.0', id, method };
+  if (params !== undefined) req.params = params;
+  const res = await driver.post('/v1/host/sample/mcp', req);
+  return { status: res.status, body: res.json as { result?: unknown; error?: { code: number; message: string } } };
+}
+
+async function registerSamplingHandlerWorkflow(): Promise<boolean> {
+  const res = await driver.post('/v1/host/sample/workflows', {
+    workflowId: `mcp.sampling.${Date.now()}`,
+    nodes: [
+      { nodeId: 'sample', typeId: 'core.openwop.mcp.handle-sampling' },
+    ],
+  });
+  return res.status === 200 || res.status === 201;
+}
+
+describe('mcp-server-sampling-bridge: advertisement shape (RFC 0020)', () => {
+  it('samplingBridge is a boolean when serverMount.supported', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return;
+    if (cap.samplingBridge === undefined) return;
+    expect(
+      typeof cap.samplingBridge,
+      driver.describe('RFC 0020 §B', 'mcp.serverMount.samplingBridge MUST be boolean when present'),
+    ).toBe('boolean');
+  });
+});
+
+describe('mcp-server-sampling-bridge: behavioral (RFC 0020 §A point 3)', () => {
+  it('sampling/createMessage bridges into a handle-sampling workflow', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true || cap.samplingBridge !== true) return;
+    if (!(await registerSamplingHandlerWorkflow())) return;
+
+    const r = await rpc('sampling/createMessage', {
+      messages: [{ role: 'user', content: { type: 'text', text: 'ping' } }],
+      maxTokens: 16,
+    });
+    if (r.status === 404) return;
+    expect(r.status, 'JSON-RPC envelope MUST 200').toBe(200);
+    const dispatched = !!r.body.result || (!!r.body.error && r.body.error.code !== -32601);
+    expect(
+      dispatched,
+      driver.describe(
+        'RFC 0020 §A point 3',
+        'sampling/createMessage MUST dispatch to handle-sampling workflow (not return method_not_found)',
+      ),
+    ).toBe(true);
+  });
+});