@openwop/openwop-conformance 1.6.1 → 1.11.0

package/src/scenarios/oauth-authorization-code-roundtrip.test.ts

@@ -0,0 +1,145 @@
+/**
+ * oauth-authorization-code-roundtrip — RFC 0047 §C (the authorization-code grant
+ * end-to-end) + §C.2 / `credential-payload-redaction`.
+ *
+ * Closes the RFC 0047 Tier-2 gap: `oauth-capability-shape` proves the discovery
+ * block is well-formed and `oauth-connector-redaction` proves an already-acquired
+ * token doesn't leak — but nothing exercised the actual authorization-code DANCE
+ * (redirect → callback → token exchange) against a known provider. This scenario
+ * drives that roundtrip against ONE canonical synthetic provider whose endpoints a
+ * conformance test double serves, so a host can prove the grant without a live IdP.
+ *
+ * The synthetic provider + its canned exchange are defined in
+ * `fixtures/oauth-providers/synthetic.json`; the constants below mirror it (kept
+ * inline so the scenario runs from the published tarball without fixture-path
+ * resolution, exactly like `oauth-connector-redaction`'s TOKEN_CANARY).
+ *
+ * Capability-gated: skips unless the host advertises
+ * `capabilities.oauth.supported = true` AND lists `authorization_code` in
+ * `capabilities.oauth.grants`. Behavioral probe drives the optional host seam
+ * `POST /v1/host/sample/oauth/authorize-code-roundtrip`; a 404 (seam not wired)
+ * is a soft-skip — this is a Tier-2 host-pending scenario.
+ *
+ * Asserts, when the seam is present:
+ *   1. The roundtrip succeeds and returns a credential REFERENCE (the token was
+ *      acquired + persisted as a host.credentials entry), never the token itself.
+ *   2. `connector.authorized` carries `{ provider, credentialRef, scopes }` and
+ *      none of the token / refresh / code / state / redirectUri / codeVerifier.
+ *   3. RFC 0047 §C — the authorization code, redirect URI, state, and PKCE
+ *      verifier MUST NOT appear on ANY run-visible surface; §C.2 — neither MUST
+ *      the access/refresh token (the canaries are absent from the whole response).
+ *
+ * @see RFCS/0047-host-oauth-connector-flows.md §C
+ * @see conformance/fixtures/oauth-providers/synthetic.json
+ * @see SECURITY/invariants.yaml id: credential-payload-redaction
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+interface DiscoveryOAuth {
+  supported?: boolean;
+  grants?: string[];
+}
+
+// Mirrors fixtures/oauth-providers/synthetic.json — keep in sync.
+const SYNTHETIC = {
+  provider: 'synthetic',
+  authUrl: 'https://oauth.synthetic.openwop.test/authorize',
+  tokenUrl: 'https://oauth.synthetic.openwop.test/token',
+  scopes: ['openwop.read', 'openwop.write'],
+  authorizationCode: 'openwop-synthetic-auth-code-1f4b9e',
+  state: 'openwop-synthetic-state-7c2a8d',
+  redirectUri: 'https://host.example/openwop/oauth/callback',
+  codeVerifier: 'openwop-synthetic-pkce-verifier-3e9f1b2c5a7d4e8f0a1b2c3d4e5f6a7b',
+  accessTokenCanary: 'OPENWOP_OAUTH_TOKEN_CANARY_9d4c1f7a',
+  refreshTokenCanary: 'OPENWOP_OAUTH_REFRESH_CANARY_2b8e6a3f',
+} as const;
+
+// Values that MUST NOT appear on any run-visible surface (RFC 0047 §C + §C.2).
+const SECRET_VALUES: readonly string[] = [
+  SYNTHETIC.accessTokenCanary,
+  SYNTHETIC.refreshTokenCanary,
+  SYNTHETIC.authorizationCode,
+  SYNTHETIC.state,
+  SYNTHETIC.codeVerifier,
+];
+
+async function readOAuth(): Promise<DiscoveryOAuth | null> {
+  const res = await driver.get('/.well-known/openwop');
+  return capabilityFamily<DiscoveryOAuth>(res.json, 'oauth') ?? null;
+}
+
+describe('oauth-authorization-code-roundtrip: the grant dance (RFC 0047 §C)', () => {
+  it('acquires a token via authorization_code and returns a reference, never the token', async () => {
+    const oauth = await readOAuth();
+    if (!oauth?.supported) return; // capability-gated
+    if (!Array.isArray(oauth.grants) || !oauth.grants.includes('authorization_code')) return; // grant-gated
+
+    // Seam contract: the host performs the full authorization-code roundtrip
+    // against the synthetic provider's authUrl/tokenUrl, persists the acquired
+    // token as a host.credentials entry, and returns the run-observable surfaces
+    // (events incl. connector.authorized + snapshot + any debug bundle) plus the
+    // resulting credentialRef.
+    const res = await driver.post('/v1/host/sample/oauth/authorize-code-roundtrip', {
+      provider: SYNTHETIC.provider,
+      authUrl: SYNTHETIC.authUrl,
+      tokenUrl: SYNTHETIC.tokenUrl,
+      scopes: SYNTHETIC.scopes,
+      authorizationCode: SYNTHETIC.authorizationCode,
+      state: SYNTHETIC.state,
+      redirectUri: SYNTHETIC.redirectUri,
+      codeVerifier: SYNTHETIC.codeVerifier,
+      accessTokenCanary: SYNTHETIC.accessTokenCanary,
+      refreshTokenCanary: SYNTHETIC.refreshTokenCanary,
+    });
+    // A host that hasn't wired the seam soft-skips (Tier-2, host-pending).
+    if (res.status === 404) return;
+
+    expect(
+      res.status,
+      driver.describe(
+        'RFC 0047 §C',
+        'the authorize-code-roundtrip seam MUST perform the authorization_code grant against the synthetic provider and return the run observable surfaces',
+      ),
+    ).toBeLessThan(400);
+
+    const body = (res.json ?? {}) as { credentialRef?: unknown };
+    expect(
+      typeof body.credentialRef === 'string' && body.credentialRef.length > 0,
+      driver.describe(
+        'RFC 0047 §C',
+        'a successful roundtrip MUST resolve to a credential REFERENCE (token persisted as a host.credentials entry), not the raw token',
+      ),
+    ).toBe(true);
+
+    // §C + §C.2 — no secret material anywhere in the observable response.
+    const serialized = JSON.stringify(res.json ?? {});
+    for (const secret of SECRET_VALUES) {
+      expect(
+        serialized.includes(secret),
+        driver.describe(
+          'RFC 0047 §C / SECURITY/invariants.yaml credential-payload-redaction',
+          `the authorization code, state, PKCE verifier, and acquired token material MUST NOT appear on any run-visible surface — leaked: ${secret.slice(0, 16)}…`,
+        ),
+      ).toBe(false);
+    }
+
+    // §C — connector.authorized carries the reference + scopes, never the token.
+    const events = (res.json as { events?: Array<{ type?: string; payload?: Record<string, unknown> }> })?.events;
+    if (Array.isArray(events)) {
+      const authorized = events.find((e) => e?.type === 'connector.authorized');
+      if (authorized?.payload) {
+        const keys = Object.keys(authorized.payload);
+        expect(
+          keys.includes('credentialRef') && !keys.includes('access_token') && !keys.includes('refresh_token'),
+          driver.describe(
+            'RFC 0047 §C',
+            'connector.authorized MUST carry { provider, credentialRef, scopes } and MUST NOT carry token material',
+          ),
+        ).toBe(true);
+      }
+    }
+  });
+});

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 {

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/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,
   }));
 }