@openwop/openwop-conformance 1.6.1 → 1.11.0

package/src/scenarios/trigger-bridge-shape.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Durable trigger + channel bridge — subscription + events + profile shapes (RFC 0083).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `trigger-subscription.schema.json` round-trips a conforming
+ *     `TriggerSubscription` and rejects the malformed (missing REQUIRED `state`;
+ *     an out-of-enum `source`; an unknown property under
+ *     `additionalProperties:false`).
+ *   - the four-state vocabulary (`active`/`paused`/`failed`/`dead-lettered`) is
+ *     stable on the subscription `state` + the event `fromState`/`toState`.
+ *   - the `trigger.subscription.state.changed` + `trigger.delivery.attempted`
+ *     payload $defs validate conforming content-free records and reject malformed
+ *     ones (a missing `outcome`; an out-of-enum `outcome`), and both event names
+ *     appear in the RunEventType enum.
+ *   - `capabilities.triggerBridge` (+ `webhooks.durable`) is declared.
+ *   - `deriveProfiles` surfaces `openwop-trigger-bridge` for a host advertising
+ *     the bridge + a dead-letter sink + a durable source, and withholds it when
+ *     the dead-letter sink is absent (the §D predicate's OR + sink requirement).
+ *
+ * Behavioral assertions (the dedup → retry → dead-letter → causation delivery
+ * loop) are gated on the `openwop-trigger-bridge` profile and land in
+ * `trigger-bridge-delivery.test.ts` (deferred per RFC 0083 §Conformance —
+ * reference host deferred). This scenario asserts the wire contract, not host
+ * behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/trigger-bridge.md
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/profiles.md (§`openwop-trigger-bridge`)
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0083-durable-trigger-and-channel-bridge-profile.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { deriveProfiles } from '../lib/profiles.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+const STATES = ['active', 'paused', 'failed', 'dead-lettered'] as const;
+
+describe('trigger-bridge-shape: TriggerSubscription (RFC 0083 §B, server-free)', () => {
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const sub = loadSchema('trigger-subscription.schema.json');
+  const validate = ajv.compile(sub);
+
+  it('a conforming subscription validates', () => {
+    expect(
+      validate({ subscriptionId: 'sub-1', source: 'webhook', state: 'active', dedupEnabled: true, retryPolicy: { maxAttempts: 8, backoff: 'exponential' }, webhookId: 'wh-1', secretFingerprint: 'fp-abc' }),
+      why('trigger-bridge.md §B', 'a conforming TriggerSubscription MUST validate'),
+    ).toBe(true);
+  });
+
+  it('rejects a missing REQUIRED state, an out-of-enum source, and an unknown property', () => {
+    expect(validate({ subscriptionId: 's', source: 'webhook' }), why('trigger-bridge.md §B', 'state is REQUIRED')).toBe(false);
+    expect(validate({ subscriptionId: 's', source: 'carrier-pigeon', state: 'active' }), why('trigger-bridge.md §B', 'source is a closed enum')).toBe(false);
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', body: 'inbound' }), why('trigger-bridge.md §B', 'TriggerSubscription MUST be additionalProperties:false')).toBe(false);
+  });
+
+  it('secretFingerprint MUST be bounded — a full 64-hex (unsalted-hash-smelling) digest is rejected', () => {
+    const truncated = 'a1b2c3d4e5f6a7b8';      // 16 hex — a truncated host-keyed fingerprint
+    const fullDigest = 'a'.repeat(64);          // 64 hex — smells like an unsalted SHA256(secret)
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', secretFingerprint: truncated }), why('trigger-bridge.md §B', 'a truncated fingerprint MUST validate')).toBe(true);
+    expect(validate({ subscriptionId: 's', source: 'webhook', state: 'active', secretFingerprint: fullDigest }), why('SR-1', 'a full 64-hex digest MUST be rejected (brute-force oracle)')).toBe(false);
+  });
+
+  it('the state enum is exactly the four §B states', () => {
+    const stateEnum = ((sub.properties as Record<string, { enum?: string[] }>).state?.enum) ?? [];
+    expect([...stateEnum].sort(), why('trigger-bridge.md §B', 'the four-state vocabulary MUST be stable')).toEqual([...STATES].sort());
+  });
+});
+
+describe('trigger-bridge-shape: trigger.* events (RFC 0083 §C, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = addFormats(new Ajv2020({ strict: false }));
+  const compile = (defName: string) => ajv.compile({
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $defs: (payloads as { $defs: Record<string, unknown> }).$defs,
+    $ref: `#/$defs/${defName}`,
+  } as Record<string, unknown>);
+
+  it('trigger.subscription.state.changed validates + reason is a CLOSED enum (no URL-bearing free text)', () => {
+    const v = compile('triggerSubscriptionStateChanged');
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active', toState: 'dead-lettered', reason: 'retry-exhausted' }), why('trigger-bridge.md §C', 'state-changed MUST validate')).toBe(true);
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active' }), why('trigger-bridge.md §C', 'toState is REQUIRED')).toBe(false);
+    expect(v({ subscriptionId: 's', source: 'webhook', fromState: 'active', toState: 'failed', reason: 'https://attacker.example/leak?token=sk' }), why('SR-1', 'a free-form / URL-bearing reason MUST be rejected')).toBe(false);
+  });
+
+  it('trigger.delivery.attempted validates + enforces the outcome enum', () => {
+    const v = compile('triggerDeliveryAttempted');
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1, outcome: 'delivered', runId: 'run_x' }), why('trigger-bridge.md §C', 'delivery-attempted MUST validate')).toBe(true);
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1 }), why('trigger-bridge.md §C', 'outcome is REQUIRED')).toBe(false);
+    expect(v({ subscriptionId: 's', dedupKey: 'evt-9f3', attempt: 1, outcome: 'exploded' }), why('trigger-bridge.md §C', 'outcome is a closed enum')).toBe(false);
+  });
+
+  it('both trigger event names appear in the RunEventType enum', () => {
+    const runEvent = loadSchema('run-event.schema.json');
+    const enumVals = ((runEvent.$defs as Record<string, { enum?: string[] }>).RunEventType?.enum) ?? [];
+    for (const name of ['trigger.subscription.state.changed', 'trigger.delivery.attempted']) {
+      expect(enumVals.includes(name), why('run-event.schema.json', `${name} MUST be in the RunEventType enum`)).toBe(true);
+    }
+  });
+});
+
+describe('trigger-bridge-shape: capability + profile derivation (RFC 0083 §A/§D, server-free)', () => {
+  it('capabilities.triggerBridge + webhooks.durable are declared', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const props = caps.properties as Record<string, { properties?: Record<string, unknown> }>;
+    expect(props.triggerBridge?.properties?.supported, why('trigger-bridge.md §A', 'triggerBridge.supported MUST be declared')).toBeDefined();
+    expect(props.webhooks?.properties?.durable, why('trigger-bridge.md §A', 'webhooks.durable MUST be declared')).toBeDefined();
+  });
+
+  const coreBase = {
+    protocolVersion: '1.0',
+    supportedEnvelopes: ['clarification.request'],
+    schemaVersions: {},
+    limits: { clarificationRounds: 1, schemaRounds: 1, envelopesPerTurn: 1 },
+  };
+
+  it('deriveProfiles surfaces openwop-trigger-bridge for bridge + deadLetter + a durable source', () => {
+    const c = { ...coreBase, triggerBridge: { supported: true }, deadLetter: { supported: true }, queueBus: { supported: true } } as Record<string, unknown>;
+    expect(deriveProfiles(c).includes('openwop-trigger-bridge'), why('profiles.md §openwop-trigger-bridge', 'bridge + sink + durable source MUST derive the profile')).toBe(true);
+  });
+
+  it('deriveProfiles withholds openwop-trigger-bridge when the dead-letter sink is absent', () => {
+    const c = { ...coreBase, triggerBridge: { supported: true }, webhooks: { durable: true } } as Record<string, unknown>;
+    expect(deriveProfiles(c).includes('openwop-trigger-bridge'), why('profiles.md §openwop-trigger-bridge', 'no deadLetter sink ⇒ MUST NOT derive the profile')).toBe(false);
+  });
+});

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

@@ -26,6 +26,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const MISBEHAVING_PACK_NAME = 'vendor.openwop.misbehaving-abi';
 const WELL_BEHAVED_PACK_NAME = 'vendor.openwop.rust-hello';
@@ -34,9 +35,7 @@ describe('wasm-pack-abi-version-rejection: host advertises supported ABI version
   it('abiVersions[] contains positive integers; loader rejects unsupported versions', async () => {
     const disco = await driver.get('/.well-known/openwop');
     const wasm =
-      (disco.json as {
-        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean; abiVersions?: unknown } } };
-      }).capabilities?.nodePackRuntimes?.wasm;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
 
     if (!wasm?.supported) return;
 
@@ -62,13 +61,7 @@ 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;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
 
     if (!wasm?.supported) return;
 

package/src/scenarios/wasm-pack-invoke-completed.test.ts

@@ -16,14 +16,14 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.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,
+    capabilityFamily<{ wasm?: { supported?: boolean } }>(disco.json, 'nodePackRuntimes')?.wasm?.supported,
   );
 }
 

package/src/scenarios/wasm-pack-invoke-suspended.test.ts

@@ -20,14 +20,14 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.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,
+    capabilityFamily<{ wasm?: { supported?: boolean } }>(disco.json, 'nodePackRuntimes')?.wasm?.supported,
   );
 }
 

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

@@ -15,6 +15,7 @@
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const FIXTURE = 'conformance-wasm-pack-roundtrip';
 
@@ -28,8 +29,7 @@ interface WasmCaps {
 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;
+    capabilityFamily<{ wasm?: WasmCaps }>(disco.json, 'nodePackRuntimes')?.wasm ?? null;
   return caps;
 }
 

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

@@ -26,6 +26,7 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const CAP_BREACH_FIXTURE = 'conformance-wasm-pack-memory-cap-breach';
 
@@ -33,9 +34,7 @@ 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;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
 
     if (!wasm?.supported) return;
 
@@ -64,9 +63,7 @@ describe('wasm-pack-memory-cap: positive path via misbehaving pack', () => {
     }
     const disco = await driver.get('/.well-known/openwop');
     const wasm =
-      (disco.json as {
-        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } };
-      }).capabilities?.nodePackRuntimes?.wasm;
+      capabilityFamily<{ wasm?: Record<string, unknown> }>(disco.json, 'nodePackRuntimes')?.wasm;
     if (!wasm?.supported) return;
 
     const create = await driver.post('/v1/runs', {

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

@@ -14,14 +14,14 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.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,
+    capabilityFamily<{ wasm?: { supported?: boolean } }>(disco.json, 'nodePackRuntimes')?.wasm?.supported,
   );
 }
 

package/src/scenarios/workflow-primary-output-annotation.test.ts

@@ -0,0 +1,142 @@
+/**
+ * workflow-primary-output-annotation — RFC 0065 schema shape conformance.
+ *
+ * Server-free schema assertions that the optional `outputRole` field on
+ * `WorkflowNode` is exactly that — optional, additive, and a closed enum:
+ *   1. A WorkflowDefinition with one node declaring `outputRole: "primary"`
+ *      and another declaring `outputRole: "secondary"` validates.
+ *   2. A WorkflowDefinition with the field absent (legacy shape) still
+ *      validates — preserves the additive promise.
+ *   3. An unknown `outputRole` value is rejected by the closed enum.
+ *   4. The field set to a non-string is rejected.
+ *
+ * Always runs (pure on-disk Ajv2020 validation; no host involvement —
+ * the field has no engine-observable effect by design).
+ *
+ * @see RFCS/0065-workflow-node-primary-output-annotation.md
+ * @see schemas/workflow-definition.schema.json ($defs.WorkflowNode.outputRole)
+ */
+
+import { describe, it, expect } from 'vitest';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+function compileWorkflowDefinition(): ReturnType<Ajv2020['compile']> {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  // Register cross-file `$ref` targets — same pattern as
+  // `fixtures-valid.test.ts`. Without these, Ajv throws
+  // `missingRef` when compiling `workflow-definition.schema.json`
+  // because it references agent-ref + prompt-ref by URL.
+  const agentRefSchema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'agent-ref.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  const promptRefSchema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'prompt-ref.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  const promptKindSchema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'prompt-kind.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  ajv.addSchema(agentRefSchema, 'agent-ref.schema.json');
+  ajv.addSchema(promptRefSchema, 'prompt-ref.schema.json');
+  ajv.addSchema(promptRefSchema, './prompt-ref.schema.json');
+  ajv.addSchema(promptKindSchema, 'prompt-kind.schema.json');
+  ajv.addSchema(promptKindSchema, './prompt-kind.schema.json');
+  const schema = JSON.parse(
+    readFileSync(join(SCHEMAS_DIR, 'workflow-definition.schema.json'), 'utf8'),
+  ) as Record<string, unknown>;
+  return ajv.compile(schema);
+}
+
+/** Build the minimal-required shape of a WorkflowDefinition. Tests
+ *  inject per-case node overrides via the `nodes` arg. */
+function baseDefinition(nodes: Array<Record<string, unknown>>): Record<string, unknown> {
+  return {
+    id: 'wf-test',
+    name: 'Test',
+    version: '1.0.0',
+    nodes,
+    edges: [],
+    triggers: [],
+    variables: [],
+    metadata: { createdAt: '2026-05-25T00:00:00Z' },
+    settings: {},
+  };
+}
+
+function baseNode(id: string, extras: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id,
+    typeId: 'core.test.noop',
+    name: id,
+    position: { x: 0, y: 0 },
+    config: {},
+    inputs: {},
+    ...extras,
+  };
+}
+
+describe('workflow-primary-output-annotation: outputRole shape (RFC 0065)', () => {
+  const validate = compileWorkflowDefinition();
+
+  it('accepts a workflow with one node declaring outputRole="primary"', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'primary' }),
+      baseNode('b'),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  it('accepts primary AND secondary annotations on different nodes', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'primary' }),
+      baseNode('b', { outputRole: 'secondary' }),
+      baseNode('c'),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  it('accepts a workflow with the field absent (additive promise)', () => {
+    const def = baseDefinition([
+      baseNode('a'),
+      baseNode('b'),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+
+  it('rejects an unknown outputRole enum value', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'tertiary' }),
+    ]);
+    const ok = validate(def);
+    expect(ok).toBe(false);
+    expect(validate.errors).toBeTruthy();
+  });
+
+  it('rejects outputRole set to a non-string', () => {
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 1 }),
+    ]);
+    const ok = validate(def);
+    expect(ok).toBe(false);
+  });
+
+  it('permits multiple nodes declaring outputRole="primary" (tooling decides)', () => {
+    // The schema doesn't reject multiple primaries — tooling MAY pick
+    // any (lexicographic node id is the RFC's recommended tiebreaker).
+    // This test pins that the schema-layer doesn't enforce uniqueness,
+    // matching the RFC's "schema permits N primaries" promise.
+    const def = baseDefinition([
+      baseNode('a', { outputRole: 'primary' }),
+      baseNode('b', { outputRole: 'primary' }),
+    ]);
+    const ok = validate(def);
+    expect(ok, JSON.stringify(validate.errors, null, 2)).toBe(true);
+  });
+});

package/src/scenarios/workspace-behavior.test.ts

@@ -0,0 +1,134 @@
+/**
+ * workspace-behavior — RFC 0059 §C/§D behavioral verification for a host
+ * advertising `capabilities.workspace.supported: true`.
+ *
+ * Status: ACTIVE. Capability-gated: every block soft-skips when the host does
+ * not advertise the workspace store.
+ *
+ * What this scenario asserts:
+ *   1. §C CRUD round-trip — PUT create (version 1, etag), GET, list (metadata
+ *      only, no `content`), DELETE, then GET → 404.
+ *   2. §C optimistic concurrency — a PUT with a stale `If-Match` MUST return
+ *      `409 workspace_conflict` with `details.currentVersion`; a matching
+ *      `If-Match` MUST bump `version`.
+ *   3. §C size ceiling — `content` beyond `maxFileBytes` MUST return
+ *      `workspace_too_large`.
+ *   4. §D run snapshot — a run started after a write exposes the workspace
+ *      read snapshot on its run snapshot.
+ *
+ * @see RFCS/0059-agent-workspace.md §C §D
+ * @see spec/v1/agent-workspace.md §"§C — Endpoints" / §"§D — Run-time exposure"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+interface DiscoveryWorkspace {
+  supported?: boolean;
+  maxFileBytes?: number;
+}
+interface DiscoveryDoc {
+  capabilities?: { workspace?: DiscoveryWorkspace };
+}
+
+async function workspaceCap(): Promise<DiscoveryWorkspace | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const ws = capabilityFamily((res.json as DiscoveryDoc | undefined), 'workspace');
+  return ws?.supported === true ? ws : null;
+}
+
+const FILES = '/v1/host/workspace/files';
+
+interface WorkspaceFile {
+  path: string;
+  content?: string;
+  version: number;
+  etag?: string;
+}
+
+describe('workspace-behavior: §C CRUD round-trip (RFC 0059)', () => {
+  it('PUT creates v1, GET returns it, list omits content, DELETE removes it', async () => {
+    if (!(await workspaceCap())) return;
+    const path = 'behavior/CRUD.md';
+
+    const created = await driver.put(`${FILES}/${encodeURIComponent(path)}`, { content: 'first body' });
+    expect(created.status, driver.describe('agent-workspace.md §C PUT', 'create MUST return 200')).toBe(200);
+    const file = created.json as WorkspaceFile;
+    expect(file.version, driver.describe('agent-workspace.md §File model', 'version MUST start at 1')).toBe(1);
+    expect(typeof file.etag, driver.describe('agent-workspace.md §File model', 'PUT MUST return an etag')).toBe('string');
+
+    const got = await driver.get(`${FILES}/${encodeURIComponent(path)}`);
+    expect((got.json as WorkspaceFile).content, driver.describe('agent-workspace.md §C GET', 'GET MUST return the content')).toBe('first body');
+
+    const list = await driver.get(FILES);
+    const rows = (list.json as { files?: WorkspaceFile[] }).files ?? [];
+    const row = rows.find((r) => r.path === path);
+    expect(row, driver.describe('agent-workspace.md §C list', 'list MUST include the created file')).toBeDefined();
+    expect('content' in (row as object), driver.describe('agent-workspace.md §C list', 'list MUST NOT include file bodies (metadata only)')).toBe(false);
+
+    const del = await driver.del(`${FILES}/${encodeURIComponent(path)}`);
+    expect(del.status, driver.describe('agent-workspace.md §C DELETE', 'DELETE MUST return 2xx')).toBeGreaterThanOrEqual(200);
+    expect(del.status, 'DELETE MUST be < 300').toBeLessThan(300);
+
+    const gone = await driver.get(`${FILES}/${encodeURIComponent(path)}`);
+    expect(gone.status, driver.describe('agent-workspace.md §C GET', 'GET after DELETE MUST be 404')).toBe(404);
+  });
+});
+
+describe('workspace-behavior: §C optimistic concurrency (RFC 0059)', () => {
+  it('stale If-Match → 409 workspace_conflict; matching If-Match bumps version', async () => {
+    if (!(await workspaceCap())) return;
+    const path = 'behavior/ETAG.md';
+
+    const v1 = await driver.put(`${FILES}/${encodeURIComponent(path)}`, { content: 'v1' });
+    const etag = (v1.json as WorkspaceFile).etag!;
+
+    const stale = await driver.put(`${FILES}/${encodeURIComponent(path)}`, { content: 'nope' }, { headers: { 'If-Match': '"definitely-stale"' } });
+    expect(stale.status, driver.describe('agent-workspace.md §C PUT', 'a stale If-Match MUST return 409 workspace_conflict')).toBe(409);
+    expect((stale.json as { error?: string }).error, driver.describe('rest-endpoints.md workspace_conflict', 'error code MUST be workspace_conflict')).toBe('workspace_conflict');
+    const details = (stale.json as { details?: { currentVersion?: number } }).details;
+    expect(typeof details?.currentVersion, driver.describe('agent-workspace.md §C PUT', '409 MUST carry details.currentVersion')).toBe('number');
+
+    const v2 = await driver.put(`${FILES}/${encodeURIComponent(path)}`, { content: 'v2' }, { headers: { 'If-Match': etag } });
+    expect(v2.status, 'a matching If-Match MUST succeed').toBe(200);
+    expect((v2.json as WorkspaceFile).version, driver.describe('agent-workspace.md §File model', 'a successful PUT MUST bump version')).toBe(2);
+
+    await driver.del(`${FILES}/${encodeURIComponent(path)}`);
+  });
+});
+
+describe('workspace-behavior: §C size ceiling (RFC 0059)', () => {
+  it('content beyond maxFileBytes returns workspace_too_large', async () => {
+    const cap = await workspaceCap();
+    if (cap === null) return;
+    const max = typeof cap.maxFileBytes === 'number' ? cap.maxFileBytes : 1_048_576;
+    const tooBig = 'x'.repeat(max + 1);
+    const res = await driver.put(`${FILES}/${encodeURIComponent('behavior/TOOBIG.md')}`, { content: tooBig });
+    expect(res.status, driver.describe('agent-workspace.md §C PUT', 'oversize content MUST be rejected (4xx)')).toBeGreaterThanOrEqual(400);
+    expect((res.json as { error?: string }).error, driver.describe('rest-endpoints.md workspace_too_large', 'error code MUST be workspace_too_large')).toBe('workspace_too_large');
+  });
+});
+
+describe('workspace-behavior: §D run-start snapshot (RFC 0059)', () => {
+  it('a run started after a write exposes the workspace snapshot', async () => {
+    if (!(await workspaceCap())) return;
+    const path = 'behavior/SNAPSHOT.md';
+    await driver.put(`${FILES}/${encodeURIComponent(path)}`, { content: 'snapshot body' });
+
+    const create = await driver.post('/v1/runs', { workflowId: 'conformance-noop' });
+    if (create.status !== 201 && create.status !== 200) return; // host lacks the noop fixture — skip
+    const runId = (create.json as { runId?: string }).runId;
+    if (runId === undefined) return;
+
+    const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+    const ws = (snap.json as { workspace?: Array<{ path: string }> }).workspace;
+    if (ws === undefined) return; // host doesn't expose the snapshot field — skip
+    expect(
+      ws.some((f) => f.path === path),
+      driver.describe('agent-workspace.md §D', 'the run snapshot MUST reflect a workspace file present at run start'),
+    ).toBe(true);
+
+    await driver.del(`${FILES}/${encodeURIComponent(path)}`);
+  });
+});

package/src/scenarios/workspace-capability-shape.test.ts

@@ -0,0 +1,73 @@
+/**
+ * workspace-capability-shape — RFC 0059 §A advertisement-shape verification.
+ *
+ * Status: ACTIVE (advertisement-shape; always runs). RFC 0059 (agent
+ * workspace) promoted Draft → Active 2026-05-25 — the `capabilities.workspace`
+ * block has landed in `schemas/capabilities.schema.json`.
+ *
+ * Always runs (shape-only): when the host advertises `capabilities.workspace`,
+ * its fields MUST be well-formed.
+ *
+ * What this scenario asserts:
+ *   1. `capabilities.workspace` is either absent or a well-formed object.
+ *   2. `supported` is a boolean when the block is present.
+ *   3. `maxFileBytes` / `maxFiles` / `maxVersions` are positive integers when present.
+ *
+ * Behavioral coverage (CRUD / ETag / cross-tenant isolation / run-snapshot)
+ * lands at the implementation milestone (RFC 0059 §E), capability-gated on
+ * `capabilities.workspace.supported`.
+ *
+ * @see RFCS/0059-agent-workspace.md §A
+ * @see spec/v1/agent-workspace.md §"Capability advertisement"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+interface DiscoveryWorkspace {
+  supported?: boolean;
+  versioned?: boolean;
+  maxFileBytes?: number;
+  maxFiles?: number;
+  maxVersions?: number;
+}
+
+interface DiscoveryDoc {
+  capabilities?: { workspace?: DiscoveryWorkspace };
+}
+
+async function readWorkspace(): Promise<DiscoveryWorkspace | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return capabilityFamily(body, 'workspace') ?? null;
+}
+
+const POSITIVE_INT_FIELDS = ['maxFileBytes', 'maxFiles', 'maxVersions'] as const;
+
+describe('workspace-capability-shape: advertisement shape (RFC 0059 §A)', () => {
+  it('capabilities.workspace is either absent or well-formed', async () => {
+    const ws = await readWorkspace();
+    if (ws === null) return; // host doesn't advertise workspace at all
+    expect(
+      typeof ws.supported,
+      driver.describe(
+        'capabilities.schema.json §workspace',
+        'capabilities.workspace.supported MUST be a boolean when workspace is advertised',
+      ),
+    ).toBe('boolean');
+  });
+
+  it('maxFileBytes / maxFiles / maxVersions are positive integers when present', async () => {
+    const ws = await readWorkspace();
+    if (ws === null) return;
+    for (const field of POSITIVE_INT_FIELDS) {
+      const v = ws[field];
+      if (v === undefined) continue;
+      expect(
+        Number.isInteger(v) && v >= 1,
+        driver.describe('RFC 0059 §A', `capabilities.workspace.${field} MUST be an integer >= 1, got: ${v}`),
+      ).toBe(true);
+    }
+  });
+});