@openwop/openwop-conformance 1.6.0 → 1.10.0

package/src/scenarios/prompt-all-four-kinds-events.test.ts

@@ -34,6 +34,7 @@ import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const WORKFLOW_ID = 'conformance-prompt-all-four-kinds';
 const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
@@ -64,7 +65,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function promptsSupported(d: DiscoveryDoc | null): boolean {
-  return d?.capabilities?.prompts?.supported === true;
+  return capabilityFamily(d, 'prompts')?.supported === true;
 }
 
 async function readAllEvents(runId: string): Promise<RunEventDoc[]> {

package/src/scenarios/prompt-composed-secret-redaction.test.ts

@@ -33,6 +33,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 DiscoveryDoc {
   capabilities?: {
@@ -63,7 +64,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function promptsSupportFull(d: DiscoveryDoc | null): boolean {
-  const p = d?.capabilities?.prompts;
+  const p = capabilityFamily(d, 'prompts');
   if (!p) return false;
   return p.supported === true && p.observability === 'full';
 }

package/src/scenarios/prompt-composed-trust-marker.test.ts

@@ -32,6 +32,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 DiscoveryDoc {
   capabilities?: {
@@ -59,7 +60,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function promptsSupportFull(d: DiscoveryDoc | null): boolean {
-  const p = d?.capabilities?.prompts;
+  const p = capabilityFamily(d, 'prompts');
   if (!p) return false;
   return p.supported === true && p.observability === 'full';
 }

package/src/scenarios/prompt-end-to-end-events.test.ts

@@ -34,6 +34,7 @@ import { driver } from '../lib/driver.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const WORKFLOW_ID = 'conformance-prompt-end-to-end';
 const SKIP_NO_FIXTURE = !isFixtureAdvertised(WORKFLOW_ID);
@@ -64,7 +65,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function promptsSupported(d: DiscoveryDoc | null): boolean {
-  return d?.capabilities?.prompts?.supported === true;
+  return capabilityFamily(d, 'prompts')?.supported === true;
 }
 
 /** Drain the run's event log via polling. The fixture is tiny so all

package/src/scenarios/prompt-list-and-fetch.test.ts

@@ -34,6 +34,7 @@ import { join } from 'node:path';
 import { driver } from '../lib/driver.js';
 import { SCHEMAS_DIR } from '../lib/paths.js';
 import { behaviorGate } from '../lib/behavior-gate.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 interface DiscoveryDoc {
   capabilities?: {
@@ -65,7 +66,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function endpointsSupported(d: DiscoveryDoc | null): boolean {
-  return d?.capabilities?.prompts?.endpointsSupported === true;
+  return capabilityFamily(d, 'prompts')?.endpointsSupported === true;
 }
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;

package/src/scenarios/prompt-mutable-lifecycle.test.ts

@@ -35,6 +35,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 DiscoveryDoc {
   capabilities?: {
@@ -60,7 +61,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function mutableSupport(d: DiscoveryDoc | null): boolean {
-  const p = d?.capabilities?.prompts;
+  const p = capabilityFamily(d, 'prompts');
   return p?.endpointsSupported === true && p?.mutableLibrary === true;
 }
 

package/src/scenarios/prompt-mutation-workspace-membership-enforced.test.ts

@@ -41,6 +41,7 @@
 import { describe, it, expect } from 'vitest';
 import { randomUUID } from 'node:crypto';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -71,7 +72,7 @@ describe.skipIf(HTTP_SKIP)(
         ctx.skip();
         return;
       }
-      const mutableLibrary = d.capabilities?.prompts?.mutableLibrary;
+      const mutableLibrary = capabilityFamily(d, 'prompts')?.mutableLibrary;
       if (mutableLibrary !== true) {
         ctx.skip();
         return;

package/src/scenarios/prompt-pack-install.test.ts

@@ -46,6 +46,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 DiscoveryDoc {
   capabilities?: {
@@ -79,7 +80,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function endpointsSupported(d: DiscoveryDoc | null): boolean {
-  return d?.capabilities?.prompts?.endpointsSupported === true;
+  return capabilityFamily(d, 'prompts')?.endpointsSupported === true;
 }
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;

package/src/scenarios/prompt-read-workspace-membership-enforced.test.ts

@@ -67,6 +67,7 @@
 import { describe, it, expect } from 'vitest';
 import { randomUUID } from 'node:crypto';
 import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -101,7 +102,7 @@ describe.skipIf(HTTP_SKIP)(
         ctx.skip();
         return;
       }
-      const promptsSupported = d.capabilities?.prompts?.supported;
+      const promptsSupported = capabilityFamily(d, 'prompts')?.supported;
       if (promptsSupported !== true) {
         ctx.skip();
         return;

package/src/scenarios/prompt-render-deterministic.test.ts

@@ -23,6 +23,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 DiscoveryDoc {
   capabilities?: {
@@ -60,7 +61,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function endpointsSupported(d: DiscoveryDoc | null): boolean {
-  return d?.capabilities?.prompts?.endpointsSupported === true;
+  return capabilityFamily(d, 'prompts')?.endpointsSupported === true;
 }
 
 /** Pick a template that has at least one input-source variable

package/src/scenarios/prompt-resolution-chain-agent-intrinsic.test.ts

@@ -30,6 +30,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 DiscoveryDoc {
   capabilities?: {
@@ -60,7 +61,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function promptsAgentBindings(d: DiscoveryDoc | null): boolean {
-  const p = d?.capabilities?.prompts;
+  const p = capabilityFamily(d, 'prompts');
   if (!p) return false;
   return p.supported === true && p.agentBindings === true;
 }

package/src/scenarios/prompt-resolution-chain-fallback-cascade.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 DiscoveryDoc {
   capabilities?: {
@@ -60,7 +61,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function promptsSupported(d: DiscoveryDoc | null): boolean {
-  return d?.capabilities?.prompts?.supported === true;
+  return capabilityFamily(d, 'prompts')?.supported === true;
 }
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;

package/src/scenarios/prompt-resolution-chain-node-wins.test.ts

@@ -29,6 +29,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 DiscoveryDoc {
   capabilities?: {
@@ -58,7 +59,7 @@ async function readDiscovery(): Promise<DiscoveryDoc | null> {
 }
 
 function promptsSupported(d: DiscoveryDoc | null): boolean {
-  return d?.capabilities?.prompts?.supported === true;
+  return capabilityFamily(d, 'prompts')?.supported === true;
 }
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;

package/src/scenarios/prompt-template-shape.test.ts

@@ -33,6 +33,7 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { driver } from '../lib/driver.js';
 import { SCHEMAS_DIR } from '../lib/paths.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const PROMPT_KIND_VALUES = ['system', 'user', 'few-shot', 'schema-hint'] as const;
 
@@ -326,7 +327,7 @@ describe.skipIf(HTTP_SKIP)('prompt-template-shape: capabilities.prompts advertis
   it('capabilities.prompts (when present) carries the optional shape per RFC 0027 §D', async () => {
     const d = await readDiscovery();
     if (d === null) return;
-    const prompts = d.capabilities?.prompts;
+    const prompts = capabilityFamily(d, 'prompts');
     if (prompts === undefined) return; // optional block; host MAY omit
     expect(
       typeof prompts.supported,

package/src/scenarios/provider-usage.test.ts

@@ -26,6 +26,7 @@ import { join } from 'node:path';
 import { driver } from '../lib/driver.js';
 import { SCHEMAS_DIR } from '../lib/paths.js';
 import { queryTestEvents, isEventLogSeamAvailable, resetTestSeam } from '../lib/event-log-query.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 interface DiscoveryDoc {
   capabilities?: {
@@ -36,7 +37,7 @@ interface DiscoveryDoc {
 async function readProviderUsageCap(): Promise<{ supported?: boolean; costEstimates?: boolean; currency?: string } | null> {
   const res = await driver.get('/.well-known/openwop');
   const body = res.json as DiscoveryDoc | undefined;
-  const cap = body?.capabilities?.providerUsage;
+  const cap = capabilityFamily(body, 'providerUsage');
   return cap && typeof cap === 'object' ? cap : null;
 }
 

package/src/scenarios/redaction.test.ts

@@ -100,7 +100,10 @@ describe('redaction: /.well-known/openwop secrets+aiProviders shape contract', (
         'when secrets.supported is true, scopes MUST be non-empty',
       )).toBeGreaterThanOrEqual(1);
       for (const scope of scopes) {
-        expect(['tenant', 'user', 'run']).toContain(scope);
+        // Allowlist MUST track the `secrets.scopes` enum in capabilities.schema.json
+        // (`["tenant", "user", "run", "workspace"]`). `workspace` is the RFC 0046/0048
+        // sub-tenant scope — additive; hosts that advertise it (e.g. MyndHyve) are conformant.
+        expect(['tenant', 'user', 'run', 'workspace']).toContain(scope);
       }
       expect(s.resolution, driver.describe(
         'capabilities.md §"Secrets"',

package/src/scenarios/replay-divergence-at-refusal.test.ts

@@ -46,6 +46,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;
 
@@ -79,7 +80,7 @@ describe.skipIf(HTTP_SKIP)('replay-divergence-at-refusal: advertisement shape (R
       ctx.skip();
       return;
     }
-    const rd = d.capabilities?.multiAgent?.executionModel?.replayDeterminism;
+    const rd = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.replayDeterminism;
     if (rd === undefined) {
       ctx.skip(); // optional advertisement — host hasn't opted in
       return;
@@ -94,7 +95,7 @@ describe.skipIf(HTTP_SKIP)('replay-divergence-at-refusal: advertisement shape (R
     ).toBe('boolean');
 
     if (rd.supported === true) {
-      const version = d.capabilities?.multiAgent?.executionModel?.version as number | undefined;
+      const version = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.version as number | undefined;
       expect(
         typeof version === 'number' && version >= 4,
         driver.describe(
@@ -170,7 +171,7 @@ describe.skipIf(HTTP_SKIP)('replay-divergence-at-refusal: behavioral (RFC 0041
 
   async function gateOnPhase4(ctx: { skip: () => void }): Promise<boolean> {
     const d = await readDiscovery();
-    const rd = d?.capabilities?.multiAgent?.executionModel?.replayDeterminism;
+    const rd = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel?.replayDeterminism;
     if (rd?.supported !== true || rd?.refusalDivergenceEmission !== true) {
       ctx.skip();
       return false;

package/src/scenarios/replay-fork-arbitrary.test.ts

@@ -110,7 +110,9 @@ function structuralShape(
   return events.map((e) => ({
     type: e.type,
     nodeId: e.nodeId ?? null,
-    data: e.data ?? null,
+    // Canonical `payload` (run-event.schema.json) with the legacy `data`
+    // field as a fallback for hosts that haven't migrated their envelope.
+    data: e.payload ?? e.data ?? null,
   }));
 }
 

package/src/scenarios/replay-llm-cache-key-portable.test.ts

@@ -53,6 +53,7 @@
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { expectedCacheKey, callCacheKeySeam as callSeam } from '../lib/llm-cache-key-recipe.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -167,7 +168,7 @@ describe.skipIf(HTTP_SKIP)('replay-llm-cache-key-portable: non-recipe-field inva
 describe.skipIf(HTTP_SKIP)('replay-llm-cache-key-portable: Phase 4 advertisement alignment (RFC 0041 §D)', () => {
   it('hosts advertising version: 4 MUST advertise replayDeterminism.llmCacheKeyRecipe', async (ctx) => {
     const d = await readDiscovery();
-    const em = d?.capabilities?.multiAgent?.executionModel;
+    const em = capabilityFamily<{ executionModel?: { [k: string]: unknown; crossHostCausation?: Record<string, unknown>; replayDeterminism?: Record<string, unknown> } }>(d, 'multiAgent')?.executionModel;
     const version = em?.version;
     if (typeof version !== 'number' || version < 4) {
       ctx.skip(); // pre-Phase-4 or no multiAgent advertisement

package/src/scenarios/replayDeterminism.test.ts

@@ -60,7 +60,9 @@ function structuralShape(events: readonly RawEvent[]): Array<{ type: unknown; no
   return events.map((e) => ({
     type: e.type,
     nodeId: e.nodeId ?? null,
-    data: e.data ?? null,
+    // Canonical `payload` (run-event.schema.json) with the legacy `data`
+    // field as a fallback for hosts that haven't migrated their envelope.
+    data: e.payload ?? e.data ?? null,
   }));
 }
 

package/src/scenarios/run-execution-bounds-shape.test.ts

@@ -0,0 +1,133 @@
+/**
+ * run-execution-bounds-shape — RFC 0058 advertisement-shape + breach-contract
+ * verification for the two run-scoped execution bounds.
+ *
+ * Status: ACTIVE. RFC 0058 (run execution bounds) is `Active`. The
+ * `capabilities.limits.{maxRunDurationMs,maxLoopIterations}` fields and the
+ * `run-duration` / `loop-iterations` kinds on `cap.breached` have landed in
+ * `schemas/capabilities.schema.json` + `schemas/run-event-payloads.schema.json`.
+ *
+ * Always runs (shape-only): when the host advertises either limit, its value
+ * MUST be well-formed. Behavior is capability- AND fixture-gated. The
+ * `run-duration` (wall-clock timeout) block is now enforced + green against the
+ * in-memory reference host. The `loop-iterations` block stays soft-skipped until
+ * an execution-loop host advertises `multiAgent.executionModel` (RFC 0061),
+ * mirroring the RFC 0052 scheduling pattern.
+ *
+ * What this scenario asserts:
+ *   1. `capabilities.limits.maxRunDurationMs`, when present, is an integer ≥ 1000.
+ *   2. `capabilities.limits.maxLoopIterations`, when present, is an integer ≥ 1.
+ *   3. (gated) A run with `configurable.runTimeoutMs` below its real duration
+ *      reaches terminal `failed` with `error.code = "run_timeout"` and emits
+ *      `cap.breached { kind: "run-duration" }` whose `observed > limit`.
+ *
+ * @see RFCS/0058-run-execution-bounds.md
+ * @see spec/v1/run-options.md §Reserved keys (runTimeoutMs / maxLoopIterations)
+ * @see spec/v1/capabilities.md §"Engine-enforced limits and the cap.breached event"
+ * @see schemas/run-event-payloads.schema.json §capBreached
+ */
+
+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';
+
+interface DiscoveryLimits {
+  maxRunDurationMs?: number;
+  maxLoopIterations?: number;
+}
+
+interface DiscoveryDoc {
+  capabilities?: { limits?: DiscoveryLimits };
+}
+
+interface RunEvent {
+  readonly type: string;
+  readonly sequence: number;
+  readonly payload?: unknown;
+}
+
+const TIMEOUT_FIXTURE = 'conformance-run-duration-breach';
+
+async function readLimits(): Promise<DiscoveryLimits | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  return capabilityFamily(body, 'limits') ?? null;
+}
+
+describe('run-execution-bounds-shape: advertisement shape (RFC 0058)', () => {
+  it('maxRunDurationMs is an integer >= 1000 when present', async () => {
+    const limits = await readLimits();
+    if (limits?.maxRunDurationMs === undefined) return; // not advertised
+    expect(
+      Number.isInteger(limits.maxRunDurationMs) && limits.maxRunDurationMs >= 1000,
+      driver.describe(
+        'capabilities.schema.json §limits.maxRunDurationMs',
+        `capabilities.limits.maxRunDurationMs MUST be an integer >= 1000, got: ${limits.maxRunDurationMs}`,
+      ),
+    ).toBe(true);
+  });
+
+  it('maxLoopIterations is an integer >= 1 when present', async () => {
+    const limits = await readLimits();
+    if (limits?.maxLoopIterations === undefined) return; // not advertised
+    expect(
+      Number.isInteger(limits.maxLoopIterations) && limits.maxLoopIterations >= 1,
+      driver.describe(
+        'capabilities.schema.json §limits.maxLoopIterations',
+        `capabilities.limits.maxLoopIterations MUST be an integer >= 1, got: ${limits.maxLoopIterations}`,
+      ),
+    ).toBe(true);
+  });
+});
+
+// Behavior: capability- AND fixture-gated. Skips on hosts that do not enforce
+// run-duration timeouts (incl. the reference hosts) until one wires the seam.
+const SKIP_TIMEOUT = !isFixtureAdvertised(TIMEOUT_FIXTURE);
+
+describe.skipIf(SKIP_TIMEOUT)('run-execution-bounds: run-duration breach (RFC 0058)', () => {
+  it('a run with runTimeoutMs below its real duration fails with run_timeout + cap.breached{run-duration}', async () => {
+    const create = await driver.post('/v1/runs', {
+      workflowId: TIMEOUT_FIXTURE,
+      configurable: { runTimeoutMs: 1000 },
+    });
+    expect(create.status, driver.describe(
+      'rest-endpoints.md POST /v1/runs',
+      'run creation MUST accept a runTimeoutMs override',
+    )).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId);
+    expect(terminal.status, driver.describe(
+      'run-options.md §runTimeoutMs',
+      'a run exceeding its runTimeoutMs MUST reach terminal `failed`',
+    )).toBe('failed');
+    expect(terminal.error?.code, driver.describe(
+      'rest-endpoints.md §run_timeout',
+      'RunSnapshot.error.code MUST equal "run_timeout" on wall-clock timeout',
+    )).toBe('run_timeout');
+
+    const eventsRes = await driver.get(
+      `/v1/runs/${encodeURIComponent(runId)}/events/poll?lastSequence=0&timeout=1`,
+    );
+    const events = (eventsRes.json as { events?: RunEvent[] } | undefined)?.events ?? [];
+    const breach = events.find((e) => e.type === 'cap.breached');
+    expect(breach, driver.describe(
+      'capabilities.md §Engine-enforced limits',
+      'a cap.breached event MUST be emitted on run-duration breach',
+    )).toBeDefined();
+    const payload = breach!.payload as { kind?: string; limit?: number; observed?: number } | undefined;
+    expect(payload?.kind, driver.describe(
+      'run-event-payloads.schema.json §capBreached.kind',
+      'cap.breached payload MUST carry kind="run-duration"',
+    )).toBe('run-duration');
+    expect(
+      typeof payload?.observed === 'number' && typeof payload?.limit === 'number' && payload!.observed > payload!.limit,
+      driver.describe(
+        'run-event-payloads.schema.json §capBreached.observed',
+        'observed (elapsedMs) MUST be strictly greater than limit (resolved timeout)',
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/sandbox-memory-cap.test.ts

@@ -15,6 +15,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;
 
@@ -26,7 +27,7 @@ async function readSandbox(): Promise<{ supported: boolean; memoryLimitBytes?: n
   try {
     const r = await driver.get('/.well-known/openwop');
     if (r.status !== 200) return null;
-    const sb = (r.json as D).capabilities?.sandbox;
+    const sb = capabilityFamily((r.json as D), 'sandbox');
     if (!sb || sb.supported !== true) return null;
     return {
       supported: true,

package/src/scenarios/sandbox-mvp-behavior.test.ts

@@ -37,6 +37,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;
 
@@ -66,7 +67,7 @@ async function isSandboxAdvertised(): Promise<boolean> {
   try {
     const res = await driver.get('/.well-known/openwop');
     if (res.status !== 200) return false;
-    return (res.json as DiscoveryDoc).capabilities?.sandbox?.supported === true;
+    return capabilityFamily((res.json as DiscoveryDoc), 'sandbox')?.supported === true;
   } catch {
     return false;
   }

package/src/scenarios/sandbox-no-host-fs-escape.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 HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 
@@ -45,7 +46,7 @@ async function readSandboxCaps(): Promise<SandboxCaps | null> {
   try {
     const res = await driver.get('/.well-known/openwop');
     if (res.status !== 200) return null;
-    return (res.json as DiscoveryDoc).capabilities?.sandbox ?? null;
+    return capabilityFamily((res.json as DiscoveryDoc), 'sandbox') ?? null;
   } catch {
     return null;
   }

package/src/scenarios/sandbox-timeout-cap.test.ts

@@ -15,6 +15,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;
 
@@ -26,7 +27,7 @@ async function readSandbox(): Promise<{ supported: boolean; wallClockLimitMs?: n
   try {
     const r = await driver.get('/.well-known/openwop');
     if (r.status !== 200) return null;
-    const sb = (r.json as D).capabilities?.sandbox;
+    const sb = capabilityFamily((r.json as D), 'sandbox');
     if (!sb || sb.supported !== true) return null;
     return {
       supported: true,

package/src/scenarios/scheduling-capability-shape.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';
 
 interface DiscoveryScheduling {
   supported?: boolean;
@@ -39,7 +40,7 @@ const ISO_DURATION = /^P(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M
 async function readScheduling(): Promise<DiscoveryScheduling | null> {
   const res = await driver.get('/.well-known/openwop');
   const body = res.json as DiscoveryDoc | undefined;
-  return body?.capabilities?.scheduling ?? null;
+  return capabilityFamily(body, 'scheduling') ?? null;
 }
 
 describe('scheduling-capability-shape: advertisement shape (RFC 0052 §A)', () => {

package/src/scenarios/scheduling-cron-fires-once.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 DiscoveryDoc {
   capabilities?: { scheduling?: { supported?: boolean; cron?: boolean } };
@@ -33,7 +34,7 @@ interface DiscoveryDoc {
 
 async function readScheduling(): Promise<{ supported?: boolean; cron?: boolean } | null> {
   const res = await driver.get('/.well-known/openwop');
-  return (res.json as DiscoveryDoc | undefined)?.capabilities?.scheduling ?? null;
+  return capabilityFamily((res.json as DiscoveryDoc | undefined), 'scheduling') ?? null;
 }
 
 describe('scheduling-cron-fires-once: once-per-tick + missed-tick (RFC 0052 §B)', () => {

package/src/scenarios/secret-leakage-otel-attribute.test.ts

@@ -55,6 +55,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 HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
 const BYOK_WORKFLOW_ID = 'openwop-smoke-byok-roundtrip';
@@ -99,8 +100,8 @@ describe.skipIf(HTTP_SKIP || FIXTURE_SKIP)(
         return;
       }
       const d = await readDiscovery();
-      const secretsOk = d?.capabilities?.secrets?.supported === true;
-      const seamOk = d?.capabilities?.observability?.testSeams?.otelScrape === true;
+      const secretsOk = capabilityFamily<{ supported?: unknown }>(d, 'secrets')?.supported === true;
+      const seamOk = capabilityFamily<{ testSeams?: Record<string, unknown> }>(d, 'observability')?.testSeams?.otelScrape === true;
       if (!secretsOk || !seamOk) {
         ctx.skip();
         return;
@@ -168,8 +169,8 @@ describe.skipIf(HTTP_SKIP || FIXTURE_SKIP)(
         return;
       }
       const d = await readDiscovery();
-      const secretsOk = d?.capabilities?.secrets?.supported === true;
-      const seamOk = d?.capabilities?.observability?.testSeams?.debugBundleExport === true;
+      const secretsOk = capabilityFamily<{ supported?: unknown }>(d, 'secrets')?.supported === true;
+      const seamOk = capabilityFamily<{ testSeams?: Record<string, unknown> }>(d, 'observability')?.testSeams?.debugBundleExport === true;
       if (!secretsOk || !seamOk) {
         ctx.skip();
         return;
@@ -209,11 +210,11 @@ describe.skipIf(HTTP_SKIP || FIXTURE_SKIP)(
   () => {
     it('when secrets.supported is true, observability.testSeams advertisements MUST be boolean if present', async (ctx) => {
       const d = await readDiscovery();
-      if (d?.capabilities?.secrets?.supported !== true) {
+      if (capabilityFamily<{ supported?: unknown }>(d, 'secrets')?.supported !== true) {
         ctx.skip();
         return;
       }
-      const seams = d?.capabilities?.observability?.testSeams;
+      const seams = capabilityFamily<{ testSeams?: Record<string, unknown> }>(d, 'observability')?.testSeams;
       if (seams === undefined) {
         ctx.skip(); // host honest about not exposing the seams — Drift #17 path
         return;