@openwop/openwop-conformance 1.6.0 → 1.10.0

package/src/scenarios/memory-attribution-replay-stable.test.ts

@@ -0,0 +1,60 @@
+/**
+ * memory-attribution-replay-stable — RFC 0057 §D. `memory.written` is an
+ * immutable recorded fact: a `replay`-mode fork MUST NOT mint a new
+ * `memoryId` for a write the source run already recorded. This asserts the
+ * "MUST NOT regenerate" half — every `memory.written` on a replayed run
+ * reuses a `memoryId` the source run recorded (a compliant host that
+ * suppresses re-mint on replay satisfies this vacuously with zero events).
+ *
+ * Gated on `capabilities.memory.attribution.emitsWriteEvents`; soft-skips
+ * when unadvertised, when the seeded run wrote no memory, or when the host
+ * doesn't support `:fork` in `replay` mode.
+ *
+ * @see RFCS/0057-memory-write-attribution-event.md §D
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { readMemoryAttributionCap, emitsWriteEvents, seedRun, memoryWrittenEvents } from '../lib/memoryAttribution.js';
+
+function memoryIdOf(payload: Record<string, unknown> | undefined): string | null {
+  const id = (payload ?? {})['memoryId'];
+  return typeof id === 'string' ? id : null;
+}
+
+describe('memory-attribution-replay-stable (RFC 0057 §D)', () => {
+  it('a replay-mode fork introduces no memory.written with a new memoryId', async () => {
+    const cap = await readMemoryAttributionCap();
+    if (!emitsWriteEvents(cap)) return;
+    const runId = await seedRun('mem-attr-replay');
+    if (!runId) return;
+    try {
+      await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+    } catch {
+      return;
+    }
+    const original = await memoryWrittenEvents(runId);
+    if (original.length === 0) return; // run wrote no memory — nothing to test
+    const recordedIds = new Set(original.map((e) => memoryIdOf(e.payload)).filter((x): x is string => x !== null));
+
+    const fork = await driver.post(`/v1/runs/${runId}:fork`, { fromSeq: 0, mode: 'replay' });
+    if (fork.status !== 200 && fork.status !== 201) return; // replay fork unsupported — soft-skip
+    const forkId = (fork.json as { runId?: string } | undefined)?.runId;
+    if (!forkId) return;
+    try {
+      await pollUntilTerminal(forkId, { timeoutMs: 10_000 });
+    } catch {
+      /* still assert on whatever the replay emitted */
+    }
+
+    const replayed = await memoryWrittenEvents(forkId);
+    for (const e of replayed) {
+      const id = memoryIdOf(e.payload);
+      expect(
+        id !== null && recordedIds.has(id),
+        driver.describe('RFC 0057 §D', 'a replay MUST NOT regenerate memoryId — every replayed memory.written reuses a recorded id'),
+      ).toBe(true);
+    }
+  });
+});

package/src/scenarios/memory-attribution-shape.test.ts

@@ -0,0 +1,28 @@
+/**
+ * memory-attribution-shape — RFC 0057 §A. The `capabilities.memory.attribution`
+ * advertisement block is either absent or a well-formed object.
+ *
+ * Status: ACTIVE (advertisement-shape; always runs). Behavioral coverage lives
+ * in the sibling memory-attribution-*.test.ts scenarios, gated on
+ * `capabilities.memory.attribution.emitsWriteEvents`.
+ *
+ * @see RFCS/0057-memory-write-attribution-event.md §A
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readMemoryAttributionCap } from '../lib/memoryAttribution.js';
+
+describe('memory-attribution-shape: advertisement (RFC 0057 §A)', () => {
+  it('capabilities.memory.attribution is absent or a well-formed object', async () => {
+    const cap = await readMemoryAttributionCap();
+    if (cap === null) return; // not advertised — valid
+    expect(
+      cap.supported,
+      driver.describe('capabilities.schema.json §memory.attribution', 'memory.attribution.supported MUST be the literal true when the block is present'),
+    ).toBe(true);
+    if (cap.emitsWriteEvents !== undefined) {
+      expect(typeof cap.emitsWriteEvents).toBe('boolean');
+    }
+  });
+});

package/src/scenarios/memory-attribution-tenant-scoped.test.ts

@@ -0,0 +1,44 @@
+/**
+ * memory-attribution-tenant-scoped — RFC 0057 §C + SECURITY/invariants.yaml
+ * `memory-attribution-tenant-scoped`. A run's `memory.written` events appear
+ * only on that run's stream (mirrors CTI-1). The full cross-tenant proof
+ * (tenant B cannot read tenant A's run stream) needs a multi-tenant auth seam
+ * not standardized for this surface — that half soft-skips, mirroring
+ * `feedback-cross-tenant-isolation`.
+ *
+ * Gated on `capabilities.memory.attribution.emitsWriteEvents`.
+ *
+ * @see RFCS/0057-memory-write-attribution-event.md §C
+ * @see SECURITY/invariants.yaml — memory-attribution-tenant-scoped
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { readMemoryAttributionCap, emitsWriteEvents, seedRun, memoryWrittenEvents } from '../lib/memoryAttribution.js';
+
+describe('memory-attribution-tenant-scoped (RFC 0057 §C)', () => {
+  it("a run's memory.written events appear only on that run's stream", async () => {
+    const cap = await readMemoryAttributionCap();
+    if (!emitsWriteEvents(cap)) return;
+    const runId = await seedRun('mem-attr-cti');
+    if (!runId) return;
+    try {
+      await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+    } catch {
+      return;
+    }
+    const events = await memoryWrittenEvents(runId);
+    if (events.length === 0) return;
+    // Every memory.written we read came from THIS run's /events stream; if the
+    // host echoes a runId in the event it MUST be this run's (no cross-run leak).
+    for (const e of events) {
+      if (typeof e.runId === 'string') {
+        expect(
+          e.runId,
+          driver.describe('RFC 0057 §C', "a memory.written event MUST belong to its own run's stream (CTI-1)"),
+        ).toBe(runId);
+      }
+    }
+  });
+});

package/src/scenarios/memory-compaction-event-emitted.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 MEMORY_REF = 'mem_tenant:default_agent:conformance-rfc0012-event_longTerm';
 
@@ -35,7 +36,7 @@ interface MemoryCaps {
 
 async function isCompactionAdvertised(): Promise<boolean> {
   const disco = await driver.get('/.well-known/openwop');
-  const memory = (disco.json as { capabilities?: { memory?: MemoryCaps } }).capabilities?.memory;
+  const memory = capabilityFamily<MemoryCaps>(disco.json, 'memory');
   return memory?.compaction?.supported === true;
 }
 

package/src/scenarios/memory-compaction-provenance-tag.test.ts

@@ -20,6 +20,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const MEMORY_REF = 'mem_tenant:default_agent:conformance-rfc0012-tag_longTerm';
 const COMPACTED_FROM_RE = /^compacted-from:[^\s:][^\s]*$/;
@@ -34,7 +35,7 @@ interface MemoryListResponse {
 
 async function isCompactionAdvertised(): Promise<boolean> {
   const disco = await driver.get('/.well-known/openwop');
-  const memory = (disco.json as { capabilities?: { memory?: MemoryCaps } }).capabilities?.memory;
+  const memory = capabilityFamily<MemoryCaps>(disco.json, 'memory');
   return memory?.compaction?.supported === true;
 }
 

package/src/scenarios/memory-compaction-sr1-carry-forward.test.ts

@@ -28,6 +28,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const MEMORY_REF = 'mem_tenant:default_agent:conformance-rfc0012-sr1_longTerm';
 
@@ -37,7 +38,7 @@ interface MemoryCaps {
 
 async function isCompactionAdvertised(): Promise<boolean> {
   const disco = await driver.get('/.well-known/openwop');
-  const memory = (disco.json as { capabilities?: { memory?: MemoryCaps } }).capabilities?.memory;
+  const memory = capabilityFamily<MemoryCaps>(disco.json, 'memory');
   return memory?.compaction?.supported === true;
 }
 

package/src/scenarios/memory-consolidation-idempotent.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Background memory consolidation — idempotence + SR-1 carry-forward
+ * (RFC 0068, `Draft`).
+ *
+ * Gated on `capabilities.agents.memoryConsolidation.supported`. Drives the
+ * documented host seam `POST /v1/host/sample/memory/consolidate` (staged
+ * per the RFC 0027 §G precedent — soft-skips on 404/501 until a reference
+ * host wires it). Asserts:
+ *   - a consolidation pass emits `agent.memory.consolidated` with
+ *     `outputCount <= inputCount` (RFC 0068 §D);
+ *   - a second pass over the unchanged corpus is a no-op
+ *     (`inputCount == outputCount`) — the idempotence MUST that bounds
+ *     runaway consolidation;
+ *   - SR-1 carry-forward — a redacted secret in a source entry stays
+ *     redacted in a consolidated entry.
+ *
+ * Hosts that omit the capability skip cleanly.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/agent-memory.md §"Background consolidation"
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0068-memory-consolidation-and-standing-commitments.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface ConsolidationCaps {
+  agents?: { memoryConsolidation?: { supported?: boolean } };
+}
+
+interface ConsolidateResult {
+  event?: { inputCount?: number; outputCount?: number };
+  secretLeaked?: boolean;
+}
+
+async function consolidationSupported(): Promise<boolean> {
+  const res = await driver.get('/.well-known/openwop', { authenticated: false });
+  if (res.status !== 200) return false;
+  return Boolean((res.json as ConsolidationCaps).agents?.memoryConsolidation?.supported);
+}
+
+describe('memory-consolidation-idempotent: pass contract (RFC 0068 §D, capability-gated)', () => {
+  it('a consolidation pass reduces or holds entry count and is idempotent on a stable corpus', async () => {
+    if (!(await consolidationSupported())) return; // capability absent — gated skip
+
+    const first = await driver.post('/v1/host/sample/memory/consolidate', {
+      memoryRef: 'mem://conformance/consolidation',
+      includeSecretCanary: true,
+    });
+    if (first.status === 404 || first.status === 501) return; // seam not wired — soft-skip
+
+    expect(first.status, driver.describe('RFC 0068 §D', 'an advertised consolidation seam MUST succeed')).toBe(200);
+    const r1 = first.json as ConsolidateResult;
+    const in1 = r1.event?.inputCount ?? 0;
+    const out1 = r1.event?.outputCount ?? 0;
+    expect(out1, driver.describe('RFC 0068 §D.1', 'outputCount MUST be <= inputCount for a merge/dedup pass')).toBeLessThanOrEqual(in1);
+
+    // §D.2 — a second pass over the unchanged corpus is a no-op.
+    const second = await driver.post('/v1/host/sample/memory/consolidate', {
+      memoryRef: 'mem://conformance/consolidation',
+    });
+    if (second.status === 404 || second.status === 501) return;
+    const r2 = second.json as ConsolidateResult;
+    expect(
+      r2.event?.inputCount,
+      driver.describe('RFC 0068 §D.2', 'a second pass over an unchanged corpus MUST be a no-op (inputCount == outputCount)'),
+    ).toBe(r2.event?.outputCount);
+
+    // §D.3 — SR-1 carry-forward: a redacted secret stays redacted in the consolidated entry.
+    if (typeof r1.secretLeaked === 'boolean') {
+      expect(
+        r1.secretLeaked,
+        driver.describe('RFC 0068 §D.3 / agent-memory.md §SR-1', 'a redacted secret MUST NOT re-appear in a consolidated entry'),
+      ).toBe(false);
+    }
+  });
+});

package/src/scenarios/memory-consolidation-shape.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Memory-consolidation + commitment event shapes (RFC 0068, `Draft`).
+ *
+ * Always-on, server-free schema-shape probe. Verifies that:
+ *   - `capabilities.agents.memoryConsolidation` + `agents.commitments`
+ *     sub-blocks are declared on the capabilities schema.
+ *   - the `agent.memory.consolidated` + `commitment.fired` payload $defs
+ *     validate conforming payloads and reject malformed ones (a
+ *     `commitment.fired` missing `memoryRef` is rejected — a commitment
+ *     with no memory provenance is not an *inferred* commitment).
+ *   - both event names appear in the RunEventType enum.
+ *
+ * Distinct from RFC 0062 distillation (`memory.compacted`): consolidation
+ * reconciles long-term memory; this scenario asserts the new event
+ * contract, not host behavior.
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/agent-memory.md §"Background consolidation"
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/agent-memory.md §"Inferred commitments"
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0068-memory-consolidation-and-standing-commitments.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';
+
+/** Server-free assertion-message helper (mirrors driver.describe's "spec — requirement" shape without requiring OPENWOP_BASE_URL). */
+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>;
+}
+
+describe('memory-consolidation-shape: capability advertisement (RFC 0068, server-free)', () => {
+  it('the capabilities schema declares agents.memoryConsolidation + agents.commitments', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const agents = (caps.properties as Record<string, { properties?: Record<string, unknown> }>).agents;
+    expect(
+      agents?.properties?.memoryConsolidation,
+      why('capabilities.md §agents', 'agents.memoryConsolidation MUST be declared'),
+    ).toBeDefined();
+    expect(
+      agents?.properties?.commitments,
+      why('capabilities.md §agents', 'agents.commitments MUST be declared'),
+    ).toBeDefined();
+  });
+});
+
+describe('memory-consolidation-shape: event payloads (RFC 0068, server-free)', () => {
+  const payloads = loadSchema('run-event-payloads.schema.json');
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  ajv.addSchema(payloads, 'payloads');
+
+  const consolidated = ajv.getSchema('payloads#/$defs/agentMemoryConsolidated');
+  const fired = ajv.getSchema('payloads#/$defs/commitmentFired');
+
+  it('agent.memory.consolidated validates a content-free pass summary', () => {
+    expect(consolidated, 'the agentMemoryConsolidated $def MUST exist').toBeTruthy();
+    expect(
+      consolidated!({ memoryRef: 'mem://a/agent-1', inputCount: 240, outputCount: 201, trigger: 'host-managed' }),
+      why('RFC 0068 §B', 'a conforming agent.memory.consolidated payload MUST validate'),
+    ).toBe(true);
+    // Negative: outputCount as string fails the integer type.
+    expect(consolidated!({ memoryRef: 'mem://a/agent-1', inputCount: 1, outputCount: 'x' })).toBe(false);
+  });
+
+  it('commitment.fired validates a content-free fire record and requires memoryRef', () => {
+    expect(fired, 'the commitmentFired $def MUST exist').toBeTruthy();
+    expect(
+      fired!({ commitmentId: 'cmt-1', memoryRef: 'mem://a/agent-1', condition: 'predicate', enqueuedRunId: 'run-1' }),
+      why('RFC 0068 §C', 'a conforming commitment.fired payload MUST validate'),
+    ).toBe(true);
+    // Negative: missing memoryRef — a commitment with no provenance breaks CTI-1 binding.
+    expect(
+      fired!({ commitmentId: 'cmt-1', condition: 'time' }),
+      why('RFC 0068 §C', 'commitment.fired without memoryRef MUST be rejected'),
+    ).toBe(false);
+  });
+
+  it('both 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 ?? [];
+    expect(enumVals).toContain('agent.memory.consolidated');
+    expect(enumVals).toContain('commitment.fired');
+  });
+});

package/src/scenarios/model-capability-substituted.test.ts

@@ -17,6 +17,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -64,7 +65,7 @@ describe.skipIf(HTTP_SKIP)('model-capability-substituted: advertisement shape (R
   it('capabilities.modelCapabilities (when present) conforms to RFC 0031 §E', async () => {
     const d = await readDiscovery();
     if (d === null) return;
-    const mc = d.capabilities?.modelCapabilities;
+    const mc = capabilityFamily(d, 'modelCapabilities');
     if (mc === undefined) return;
     expect(
       typeof mc.supported,

package/src/scenarios/multi-agent-confidence-escalation.test.ts

@@ -50,6 +50,7 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { pollUntilTerminal } from '../lib/polling.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 const FIXTURE = 'conformance-multi-agent-confidence-escalation';
@@ -84,7 +85,7 @@ describe.skipIf(HTTP_SKIP)('multi-agent-confidence-escalation: capability shape
   it('confidenceEscalationFloor (when advertised) MUST be in [0.5, 1.0]', async () => {
     const d = await readDiscovery();
     if (d === null) return;
-    const em = d.capabilities?.multiAgent?.executionModel;
+    const em = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel;
     if (em === undefined) return;
     const floor = em.confidenceEscalationFloor;
     if (floor === undefined) return;
@@ -101,8 +102,8 @@ describe.skipIf(HTTP_SKIP)('multi-agent-confidence-escalation: capability shape
 describe.skipIf(BEHAVIORAL_SKIP)('multi-agent-confidence-escalation: behavioral (RFC 0039 §A)', () => {
   it('happy-path: low-confidence decision → confidence-escalated event + clarification interrupt + zero dispatch events', async () => {
     const d = await readDiscovery();
-    const supported = d?.capabilities?.multiAgent?.executionModel?.supported === true;
-    const versionRaw = d?.capabilities?.multiAgent?.executionModel?.version;
+    const supported = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.supported === true;
+    const versionRaw = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.version;
     const version = typeof versionRaw === 'number' ? versionRaw : 0;
     if (!supported || version < 2) return; // soft-skip — `version: 1` hosts pass via this absence
 
@@ -125,7 +126,7 @@ describe.skipIf(BEHAVIORAL_SKIP)('multi-agent-confidence-escalation: behavioral
     // status — the host's own interrupt.md mapping determines the suffix).
     // When the host does NOT advertise the field, fall back to the canonical
     // either-status check.
-    const advertisedKind = d?.capabilities?.multiAgent?.executionModel?.confidenceEscalationInterruptKind;
+    const advertisedKind = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.confidenceEscalationInterruptKind;
     const isVendorKind = typeof advertisedKind === 'string' && /^x-host-[a-z][a-z0-9-]*-[a-z][a-z0-9-]*$/.test(advertisedKind);
     const isCanonicalKind = advertisedKind === 'clarification' || advertisedKind === 'approval';
 

package/src/scenarios/multi-agent-handoff-state-machine.test.ts

@@ -10,7 +10,7 @@
  * Asserts (Phase 1 — execution-loop + handoff state machine per spec/v1/multi-agent-execution.md):
  *
  *   1. Advertisement shape: when capabilities.multiAgent.executionModel.supported
- *      is present, version MUST be integer in [1, 4]; supported MUST be boolean.
+ *      is present, version MUST be integer in [1, 5]; supported MUST be boolean.
  *
  *   2. Behavioral (gated on supported: true + fixture availability): a
  *      supervisor → next-worker → child-completed run emits the 4 expected
@@ -34,6 +34,7 @@ import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { pollUntilTerminal } from '../lib/polling.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -62,7 +63,7 @@ describe.skipIf(HTTP_SKIP)('multi-agent-handoff-state-machine: advertisement sha
   it('capabilities.multiAgent.executionModel (when present) conforms to RFC 0037 §C', async () => {
     const d = await readDiscovery();
     if (d === null) return; // discovery unavailable — skip
-    const executionModel = d.capabilities?.multiAgent?.executionModel;
+    const executionModel = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel;
     if (executionModel === undefined) return; // host doesn't advertise — soft-skip
     expect(
       typeof executionModel.supported,
@@ -80,10 +81,10 @@ describe.skipIf(HTTP_SKIP)('multi-agent-handoff-state-machine: advertisement sha
     ).toBe('number');
     const v = executionModel.version as number;
     expect(
-      Number.isInteger(v) && v >= 1 && v <= 4,
+      Number.isInteger(v) && v >= 1 && v <= 5,
       driver.describe(
         'RFCS/0037-multi-agent-execution-model.md §C',
-        'version MUST be an integer in [1, 4] (1 = Phase 1 only; Phases 2-4 lift the ceiling additively)',
+        'version MUST be an integer in [1, 5] (1 = Phase 1 only; Phases 2-5 lift the ceiling additively — Phase 5 = RFC 0061 stateful agent-loop lifecycle, matching `capabilities.schema.json` §multiAgent.executionModel.version maximum)',
       ),
     ).toBe(true);
   });
@@ -104,7 +105,7 @@ const BEHAVIORAL_SKIP = HTTP_SKIP || !isFixtureAdvertised(PARENT_FIXTURE) || !is
 describe.skipIf(BEHAVIORAL_SKIP)('multi-agent-handoff-state-machine: behavioral 4-event causation chain (RFC 0037 §"Handoff state machine")', () => {
   it('happy-path: dispatch.began → dispatch.succeeded → child.completed → output.harvested fire in causation order', async () => {
     const d = await readDiscovery();
-    const advertised = d?.capabilities?.multiAgent?.executionModel?.supported === true;
+    const advertised = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.supported === true;
     if (!advertised) return; // soft-skip — host honest about not implementing
 
     const create = await driver.post('/v1/runs', { workflowId: PARENT_FIXTURE });

package/src/scenarios/multi-agent-memory-lifecycle.test.ts

@@ -48,6 +48,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -81,7 +82,7 @@ describe.skipIf(HTTP_SKIP)('multi-agent-memory-lifecycle: advertisement shape (R
       ctx.skip();
       return;
     }
-    const ccmc = d.capabilities?.multiAgent?.executionModel?.crossChildMemoryConcurrency;
+    const ccmc = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.crossChildMemoryConcurrency;
     if (ccmc === undefined) {
       ctx.skip(); // optional advertisement — host hasn't opted in
       return;
@@ -135,8 +136,8 @@ describe.skipIf(HTTP_SKIP)('multi-agent-memory-lifecycle: behavioral (RFC 0039
       ctx.skip();
       return;
     }
-    const v = d.capabilities?.multiAgent?.executionModel?.version;
-    const memorySupported = d.capabilities?.memory?.supported;
+    const v = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.version;
+    const memorySupported = capabilityFamily<{ supported?: unknown }>(d, 'memory')?.supported;
     const phase2OrLater = typeof v === 'number' && v >= 2;
     const expiredRunId = process.env.OPENWOP_TEST_EXPIRED_REPLAY_RUN_ID;
     if (!phase2OrLater || memorySupported !== true || !expiredRunId) {

package/src/scenarios/multi-region-idempotency.test.ts

@@ -20,6 +20,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const ALLOWED = new Set(['single-region', 'best-effort', 'strict']);
 const REQUIRED_METRICS_WHEN_MULTI_REGION = [
@@ -40,9 +41,7 @@ interface ObservabilityCaps {
 describe('multi-region-idempotency: capability shape', () => {
   it('idempotency.crossRegion (when advertised) MUST be one of the closed enum', async () => {
     const disco = await driver.get('/.well-known/openwop');
-    const idem =
-      (disco.json as { capabilities?: { idempotency?: IdempotencyCaps } }).capabilities
-        ?.idempotency;
+    const idem = capabilityFamily<IdempotencyCaps>(disco.json, 'idempotency');
 
     if (!idem || idem.crossRegion === undefined) {
       // eslint-disable-next-line no-console
@@ -67,16 +66,16 @@ describe('multi-region-idempotency: capability shape', () => {
 
   it('multi-region hosts SHOULD expose the cross-region conflict counter per §"Operator surface"', async () => {
     const disco = await driver.get('/.well-known/openwop');
-    const caps = (disco.json as { capabilities?: { idempotency?: IdempotencyCaps; observability?: ObservabilityCaps } })
-      .capabilities;
-    const crossRegion = caps?.idempotency?.crossRegion;
+    const idem = capabilityFamily<IdempotencyCaps>(disco.json, 'idempotency');
+    const observability = capabilityFamily<ObservabilityCaps>(disco.json, 'observability');
+    const crossRegion = idem?.crossRegion;
 
     if (crossRegion !== 'best-effort' && crossRegion !== 'strict') {
       // Single-region hosts have no conflicts to count — skip.
       return;
     }
 
-    const advertised = new Set(caps?.observability?.metrics?.names ?? []);
+    const advertised = new Set(observability?.metrics?.names ?? []);
     for (const name of REQUIRED_METRICS_WHEN_MULTI_REGION) {
       expect(advertised.has(name), driver.describe(
         'idempotency.md §"Operator surface"',
@@ -103,9 +102,10 @@ interface MultiRegionCaps {
 describe('multi-region-idempotency: granular multiRegion advertisement shape (RFC 0036 §A)', () => {
   it('capabilities.idempotency.multiRegion (when present) conforms to RFC 0036 §A', async () => {
     const disco = await driver.get('/.well-known/openwop');
-    const idem =
-      (disco.json as { capabilities?: { idempotency?: IdempotencyCaps & { multiRegion?: MultiRegionCaps } } })
-        .capabilities?.idempotency;
+    const idem = capabilityFamily<IdempotencyCaps & { multiRegion?: MultiRegionCaps }>(
+      disco.json,
+      'idempotency',
+    );
     const mr = idem?.multiRegion;
     if (mr === undefined) return; // host doesn't advertise the granular block — soft-skip
 

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

@@ -18,6 +18,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 interface DiscoveryOAuthProvider {
   id?: string;
@@ -47,7 +48,7 @@ const VALID_GRANTS: ReadonlySet<string> = new Set([
 async function readOAuth(): Promise<DiscoveryOAuth | null> {
   const res = await driver.get('/.well-known/openwop');
   const body = res.json as DiscoveryDoc | undefined;
-  return body?.capabilities?.oauth ?? null;
+  return capabilityFamily(body, 'oauth') ?? null;
 }
 
 describe('oauth-capability-shape: advertisement shape (RFC 0047 §A)', () => {

package/src/scenarios/oauth-connector-redaction.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';
 
 interface DiscoveryOAuth {
   supported?: boolean;
@@ -42,7 +43,7 @@ const TOKEN_CANARY = 'OPENWOP_OAUTH_CANARY_b7d3e1a9c2';
 async function readOAuth(): Promise<DiscoveryOAuth | null> {
   const res = await driver.get('/.well-known/openwop');
   const body = res.json as DiscoveryDoc | undefined;
-  return body?.capabilities?.oauth ?? null;
+  return capabilityFamily(body, 'oauth') ?? null;
 }
 
 describe('oauth-connector-redaction: advertisement shape (RFC 0047 §A)', () => {

package/src/scenarios/pause-resume.test.ts

@@ -19,6 +19,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 import { pollUntilStatus, pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 
@@ -235,9 +236,8 @@ describe.skipIf(SKIP)('pause/resume: drainPolicy discrimination per capabilities
   it('every drainPolicy advertised by the host is accepted on :pause', async () => {
     const disco = await driver.get('/.well-known/openwop');
     const drainPolicies =
-      (disco.json as {
-        capabilities?: { runs?: { pauseResume?: { drainPolicies?: string[] } } };
-      }).capabilities?.runs?.pauseResume?.drainPolicies ?? [];
+      capabilityFamily<{ pauseResume?: { drainPolicies?: string[] } }>(disco.json, 'runs')
+        ?.pauseResume?.drainPolicies ?? [];
     if (drainPolicies.length === 0) {
       // eslint-disable-next-line no-console
       console.warn('[pause-resume] host advertises no drainPolicies; skipping policy-discrimination subtest');

package/src/scenarios/production-backpressure.test.ts

@@ -40,6 +40,7 @@ import { driver } from '../lib/driver.js';
 import { loadEnv } from '../lib/env.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 interface BackpressureCaps {
   supported?: boolean;
@@ -54,8 +55,7 @@ interface ProductionCaps {
 
 async function readProductionCaps(): Promise<ProductionCaps | undefined> {
   const disco = await driver.get('/.well-known/openwop');
-  return (disco.json as { capabilities?: { production?: ProductionCaps } })
-    .capabilities?.production;
+  return capabilityFamily<ProductionCaps>(disco.json, 'production');
 }
 
 function isProfileAdvertised(prod: ProductionCaps | undefined): boolean {

package/src/scenarios/production-retention-expiry.test.ts

@@ -31,6 +31,7 @@
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 interface RetentionCaps {
   supported?: boolean;
@@ -45,8 +46,7 @@ interface ProductionCaps {
 
 async function readProductionCaps(): Promise<ProductionCaps | undefined> {
   const disco = await driver.get('/.well-known/openwop');
-  return (disco.json as { capabilities?: { production?: ProductionCaps } })
-    .capabilities?.production;
+  return capabilityFamily<ProductionCaps>(disco.json, 'production');
 }
 
 function isProfileAdvertised(prod: ProductionCaps | undefined): boolean {