@openwop/openwop-conformance 1.25.0 → 1.28.0

package/src/scenarios/a2ui-surface-shape.test.ts

@@ -0,0 +1,162 @@
+/**
+ * a2ui-surface-shape — RFC 0102 §A wire-shape conformance (server-free).
+ *
+ * Asserts (always-on, Ajv2020, no host required):
+ *   1. `schemas/envelopes/ui.a2ui-surface.schema.json` compiles under Ajv2020.
+ *   2. A positive surface payload (closed catalog components, advertised
+ *      `catalogVersion`, a confined resume/exchange action) validates.
+ *   3. Negatives fail per the closed schema:
+ *        - missing required `catalogVersion` / `surface`
+ *        - an out-of-catalog component object (additionalProperties:false)
+ *        - a component carrying an extra/script-bearing property
+ *        - a `catalogVersion` the schema does not enumerate
+ *        - an `action.button` whose `action.target` is outside
+ *          `enum["resume","exchange"]` (the structural half of
+ *          `a2ui-action-confinement`), or carries an arbitrary URL field.
+ *
+ * The closed `anyOf` `surface` shape is the enabling precondition for the
+ * render-side invariants `a2ui-surface-no-code-exec` /
+ * `a2ui-surface-no-network-egress` (reference-app probes): a surface that
+ * smuggles a script-bearing field or an unconfined action target fails
+ * validation before it can reach a renderer.
+ *
+ * @see RFCS/0102-a2ui-agent-authored-interface-surfaces.md §A
+ * @see spec/v1/ai-envelope.md §"A2UI surfaces"
+ * @see schemas/envelopes/ui.a2ui-surface.schema.json
+ * @see SECURITY/invariants.yaml (a2ui-action-confinement)
+ */
+
+import { describe, it, expect } from 'vitest';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const ajv = new Ajv2020({ strict: false, allErrors: true });
+const schema = JSON.parse(
+  readFileSync(join(SCHEMAS_DIR, 'envelopes/ui.a2ui-surface.schema.json'), 'utf8'),
+) as Record<string, unknown>;
+
+function positivePayload(): Record<string, unknown> {
+  return {
+    catalogVersion: '0.9.1',
+    surface: {
+      title: 'Schedule the kickoff',
+      components: [
+        { component: 'heading', text: 'Kickoff', level: 2 },
+        { component: 'text', text: 'Pick a date and confirm.' },
+        { component: 'field.text', id: 'name', label: 'Your name', required: true },
+        { component: 'field.date', id: 'when', label: 'Date' },
+        {
+          component: 'field.select',
+          id: 'room',
+          label: 'Room',
+          options: [
+            { value: 'a', label: 'Room A' },
+            { value: 'b', label: 'Room B' },
+          ],
+        },
+        { component: 'field.checkbox', id: 'remind', label: 'Remind me', default: true },
+        { component: 'action.button', id: 'go', label: 'Confirm', action: { target: 'resume' } },
+      ],
+    },
+    reasoning: 'Collect the kickoff details.',
+  };
+}
+
+describe('a2ui-surface-shape: schema compile + round-trip (RFC 0102 §A)', () => {
+  const validate = ajv.compile(schema);
+
+  it('ui.a2ui-surface.schema.json compiles under Ajv2020', () => {
+    expect(
+      validate,
+      'RFC 0102 §A: the core ui.a2ui-surface payload schema MUST compile',
+    ).toBeTypeOf('function');
+  });
+
+  it('accepts a positive surface payload (closed catalog + confined action)', () => {
+    const ok = validate(positivePayload());
+    expect(
+      ok,
+      `RFC 0102 §A: positive surface MUST validate; errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('accepts an exchange-targeted action (the other confined target)', () => {
+    const p = positivePayload();
+    (p.surface as { components: Array<Record<string, unknown>> }).components = [
+      { component: 'action.button', id: 'send', label: 'Send', action: { target: 'exchange' } },
+    ];
+    expect(validate(p)).toBe(true);
+  });
+
+  it('rejects a payload missing required `catalogVersion`', () => {
+    const p = positivePayload();
+    delete p.catalogVersion;
+    expect(validate(p), 'RFC 0102 §A: `catalogVersion` is REQUIRED').toBe(false);
+  });
+
+  it('rejects a payload missing required `surface`', () => {
+    const p = positivePayload();
+    delete p.surface;
+    expect(validate(p), 'RFC 0102 §A: `surface` is REQUIRED').toBe(false);
+  });
+
+  it('rejects a `catalogVersion` the schema does not enumerate (unknown version)', () => {
+    const p = positivePayload();
+    p.catalogVersion = '9.9.9';
+    expect(
+      validate(p),
+      'RFC 0102 §A.3: an unadvertised catalogVersion MUST fail the enumerated set',
+    ).toBe(false);
+  });
+
+  it('rejects an out-of-catalog component object (additionalProperties:false)', () => {
+    const p = positivePayload();
+    (p.surface as { components: Array<Record<string, unknown>> }).components = [
+      { component: 'iframe', src: 'https://evil.example/x' } as Record<string, unknown>,
+    ];
+    expect(
+      validate(p),
+      'RFC 0102 §A.1: an out-of-catalog component MUST fail the closed anyOf',
+    ).toBe(false);
+  });
+
+  it('rejects a known component carrying an extra (script-bearing) property', () => {
+    const p = positivePayload();
+    (p.surface as { components: Array<Record<string, unknown>> }).components = [
+      { component: 'heading', text: 'Hi', onClick: "fetch('https://evil')" } as Record<string, unknown>,
+    ];
+    expect(
+      validate(p),
+      'RFC 0102 §A.1: additionalProperties:false MUST reject a smuggled code field',
+    ).toBe(false);
+  });
+
+  it('rejects an action whose target is outside enum["resume","exchange"] (action confinement)', () => {
+    const p = positivePayload();
+    (p.surface as { components: Array<Record<string, unknown>> }).components = [
+      { component: 'action.button', id: 'x', label: 'X', action: { target: 'http://evil.example' } },
+    ];
+    expect(
+      validate(p),
+      'RFC 0102 §A.4 / SECURITY a2ui-action-confinement: an action target outside resume/exchange MUST be rejected',
+    ).toBe(false);
+  });
+
+  it('rejects an action carrying an arbitrary URL field (no unconfined egress target)', () => {
+    const p = positivePayload();
+    (p.surface as { components: Array<Record<string, unknown>> }).components = [
+      {
+        component: 'action.button',
+        id: 'x',
+        label: 'X',
+        action: { target: 'resume', url: 'https://evil.example/exfil' } as Record<string, unknown>,
+      },
+    ];
+    expect(
+      validate(p),
+      'RFC 0102 §A.4: action additionalProperties:false MUST reject an arbitrary URL target',
+    ).toBe(false);
+  });
+});

package/src/scenarios/a2ui-surface-version-refusal.test.ts

@@ -0,0 +1,77 @@
+/**
+ * a2ui-surface-version-refusal — RFC 0102 §A.3 (C3): catalog version is a
+ * host-enumerated set, not a free string. A `catalogVersion` the host does
+ * not advertise MUST be refused with `unknown_schema_version`
+ * (ai-envelope.md §"Schema version advertisement"), and the stored surface
+ * MUST be self-contained for deterministic `:fork`/replay.
+ *
+ * Always-on (server-free): the core schema enumerates `catalogVersion`
+ * (closed set), so a non-advertised version fails validation; the schema
+ * carries no external `$ref` (surface is self-contained).
+ * Capability-gated (HTTP): a live host refuses an unadvertised version.
+ *
+ * @see RFCS/0102-a2ui-agent-authored-interface-surfaces.md §A.3
+ * @see spec/v1/ai-envelope.md §"A2UI surfaces", §"Schema version advertisement"
+ */
+
+import { describe, it, expect } from 'vitest';
+import Ajv2020 from 'ajv/dist/2020.js';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver } from '../lib/driver.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const schema = JSON.parse(
+  readFileSync(join(SCHEMAS_DIR, 'envelopes/ui.a2ui-surface.schema.json'), 'utf8'),
+) as Record<string, unknown>;
+
+function hasAbsoluteRef(node: unknown): boolean {
+  if (!node || typeof node !== 'object') return false;
+  if (Array.isArray(node)) return node.some(hasAbsoluteRef);
+  const obj = node as Record<string, unknown>;
+  if (typeof obj['$ref'] === 'string' && !(obj['$ref'] as string).startsWith('#')) return true;
+  return Object.values(obj).some(hasAbsoluteRef);
+}
+
+describe('a2ui-surface-version-refusal: enumerated catalogVersion (RFC 0102 §A.3)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  const validate = ajv.compile(schema);
+
+  it('catalogVersion is a closed enum — an unadvertised version fails validation', () => {
+    const ok = validate({ catalogVersion: '9.9.9', surface: { components: [] } });
+    expect(
+      ok,
+      'RFC 0102 §A.3: a catalogVersion outside the host-enumerated set MUST fail (→ unknown_schema_version at runtime)',
+    ).toBe(false);
+  });
+
+  it('surface payload is self-contained — no external $ref (replay determinism)', () => {
+    expect(
+      hasAbsoluteRef(schema),
+      'RFC 0102 §A.3: the surface MUST be self-contained, never a live external-catalog reference',
+    ).toBe(false);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('a2ui-surface-version-refusal: live host refuses unadvertised version (RFC 0102 §A.3)', () => {
+  it('ui.a2ui-surface with an unadvertised catalogVersion → refused', async () => {
+    const res = await driver.post('/v1/host/sample/envelope/accept', {
+      envelope: {
+        type: 'ui.a2ui-surface',
+        schemaVersion: 1,
+        envelopeId: 'env-a2ui-ver-1',
+        correlationId: 'run-a2ui:node-1:turn-0:ver',
+        payload: { catalogVersion: '9.9.9', surface: { components: [] } },
+        meta: { source: 'ai-generation', ts: '2026-06-15T10:00:00Z' },
+      },
+      hostSupportedEnvelopes: ['ui.a2ui-surface'],
+    });
+    if (res.status === 404) return; // seam absent — soft-skip
+    const body = res.json as { status?: string; reason?: string };
+    expect(
+      body.status === 'invalid' || body.status === 'refused',
+      driver.describe('RFC 0102 §A.3', 'an unadvertised catalogVersion MUST be refused'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/a2ui-untrusted-blocks-approval.test.ts

@@ -0,0 +1,68 @@
+/**
+ * a2ui-untrusted-blocks-approval — RFC 0102 §A.5: an untrusted-authored
+ * surface MUST NOT advance an approval gate.
+ *
+ * A `ui.a2ui-surface` emitted by a node that consumed untrusted MCP/A2A
+ * content carries `meta.contentTrust: 'untrusted'`; the existing
+ * `untrusted_content_blocks_approval` rule then blocks that surface from
+ * advancing an `approval` interrupt. This is a composition of the existing
+ * untrusted-content rule for the new kind, not a new taint primitive.
+ *
+ * Always-on (server-free): `ui.a2ui-surface` is an advertised (non-universal)
+ * kind, so the envelope trust-boundary machinery (`meta.contentTrust`) applies
+ * to it exactly as to any other envelope — the precondition for the block.
+ * Capability-gated (HTTP): an untrusted surface bound to an approval interrupt
+ * is refused.
+ *
+ * @see RFCS/0102-a2ui-agent-authored-interface-surfaces.md §A.5
+ * @see spec/v1/ai-envelope.md §"A2UI surfaces", §"Trust boundary"
+ * @see SECURITY/invariants.yaml (a2ui-untrusted-blocks-approval, untrusted_content_blocks_approval)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const UNIVERSAL_KINDS = ['clarification.request', 'schema.request', 'schema.response', 'error'];
+
+describe('a2ui-untrusted-blocks-approval: trust machinery applies (RFC 0102 §A.5)', () => {
+  it('ui.a2ui-surface is an advertised kind subject to meta.contentTrust gating (not universal/always-allowed)', () => {
+    expect(
+      UNIVERSAL_KINDS.includes('ui.a2ui-surface'),
+      'ai-envelope.md §"A2UI surfaces" / §"Trust boundary": a ui.a2ui-surface is trust-gated like any advertised envelope, so an untrusted surface is subject to untrusted_content_blocks_approval',
+    ).toBe(false);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('a2ui-untrusted-blocks-approval: untrusted surface cannot drive an approval (RFC 0102 §A.5)', () => {
+  it('an untrusted-marked ui.a2ui-surface bound to an approval interrupt is refused', async () => {
+    const res = await driver.post('/v1/host/sample/envelope/accept', {
+      envelope: {
+        type: 'ui.a2ui-surface',
+        schemaVersion: 1,
+        envelopeId: 'env-a2ui-untrusted-1',
+        correlationId: 'run-a2ui:node-1:turn-0:unt',
+        payload: {
+          catalogVersion: '0.9.1',
+          surface: {
+            components: [
+              { component: 'action.button', id: 'approve', label: 'Approve', action: { target: 'resume' } },
+            ],
+          },
+        },
+        meta: { source: 'ai-generation', ts: '2026-06-15T10:00:00Z', contentTrust: 'untrusted' },
+      },
+      hostSupportedEnvelopes: ['ui.a2ui-surface'],
+      boundInterruptKind: 'approval',
+    });
+    if (res.status === 404) return; // seam absent — soft-skip
+    const body = res.json as { status?: string; reason?: string };
+    expect(
+      body.status === 'blocked' || (body.reason ?? '').includes('untrusted'),
+      driver.describe(
+        'RFC 0102 §A.5',
+        'an untrusted ui.a2ui-surface MUST NOT advance an approval interrupt (untrusted_content_blocks_approval)',
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/i18n-negotiation.test.ts

@@ -166,16 +166,43 @@ describe.skipIf(HTTP_SKIP)('i18n-negotiation: behavioral (i18n.md §Accept-Langu
     // Prefer a non-default supported locale so localization actually engages.
     const negotiated = supported.find((t) => t !== defaultLocale) ?? defaultLocale;
 
+    // Baseline: the same probe under the host's DEFAULT locale. The i18n MUST is
+    // locale-INVARIANCE of the machine-readable code, not a specific vocabulary
+    // value. i18n.md §"`locale` field on `ErrorEnvelope.details`" requires the
+    // `error` code to "remain English / lowercase / underscore-cased regardless
+    // of locale" — it is an identifier, not human text. The spec does NOT pin a
+    // missing run to the literal `not_found`: error-envelope.schema.json says
+    // codes are SHOULD-snake_case, rest-endpoints.md §"Common error codes" is
+    // non-exhaustive, and `run_forbidden` (RFC 0048) sets precedent that hosts
+    // MAY use run-specific codes. Asserting a literal here would also pressure a
+    // conformant host into a COMPATIBILITY.md §2.2 breaking error-code change.
+    const baseRes = await driver.get(PROBE_PATH, {
+      headers: { 'Accept-Language': defaultLocale },
+    });
+    const baseCode = errCode(baseRes.json);
+
     const res = await driver.get(PROBE_PATH, {
       headers: { 'Accept-Language': negotiated },
     });
     expect(res.status).toBe(404);
+    const negotiatedCode = errCode(res.json);
+
+    // (a) the code is an English snake_case identifier (not localized prose)
+    expect(
+      typeof negotiatedCode === 'string' && /^[a-z][a-z0-9_]*$/.test(negotiatedCode),
+      driver.describe(
+        'i18n.md §"`locale` field on `ErrorEnvelope.details`"',
+        `the machine-readable error code MUST be an English lowercase snake_case identifier, not localized text (got ${String(negotiatedCode)} under ${negotiated})`,
+      ),
+    ).toBe(true);
+
+    // (b) it is byte-identical to the default-locale code — the actual invariance MUST
     expect(
-      errCode(res.json),
+      negotiatedCode,
       driver.describe(
         'i18n.md §"`locale` field on `ErrorEnvelope.details`"',
-        `the machine-readable error code MUST remain the canonical English token regardless of the negotiated locale (${negotiated})`,
+        `the machine-readable error code MUST remain identical regardless of the negotiated locale (default ${defaultLocale} → ${String(baseCode)}; negotiated ${negotiated})`,
       ),
-    ).toBe('not_found');
+    ).toBe(baseCode);
   });
 });

package/src/scenarios/interrupt-approver-routing.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Portable HITL approver routing (RFC 0104; `spec/v1/interrupt.md` §`kind: "approval"`).
+ *
+ * Adds three OPTIONAL, ADVISORY fields to the approval `InterruptPayload` so
+ * group/role approver routing is portable + capability-gated across hosts:
+ * `approverGroupRefs`, `approverRoleRefs`, and an `audience` notification hint.
+ * `approversList` advisory semantics are unchanged; enforcement stays host-side;
+ * refs are opaque to the engine and decision-time-snapshotted for replay.
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free legs — the `interrupt.approverRouting` capability
+ *      block shape, the additive optionality of the three fields on the
+ *      `ApprovalData` schema, and the §"Portable approver routing" reference
+ *      rule that `audience` DEFAULTS to the resolved eligibility union when
+ *      omitted and OVERRIDES it when present (`notifyTargets`).
+ *
+ *   B. Capability-gated advertisement-coherence leg — on a host advertising
+ *      `capabilities.interrupt.approverRouting.supported`, the advertised shape
+ *      MUST be honest: `refKinds` ⊆ {group, role}; `audience` boolean. Hosts
+ *      that do not advertise the capability soft-skip via the gate (the fields
+ *      are ignored and the host stays conformant).
+ *
+ * @see spec/v1/interrupt.md §"Portable approver routing (RFC 0104)"
+ * @see spec/v1/capabilities.md — interrupt.approverRouting.*
+ * @see schemas/suspend-request.schema.json — ApprovalData
+ * @see RFCS/0104-hitl-approver-routing.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 { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+import { behaviorGate } from '../lib/behavior-gate.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>;
+}
+
+interface ApproverRoutingCap {
+  supported?: boolean;
+  refKinds?: string[];
+  audience?: boolean;
+}
+interface InterruptCap {
+  approverRouting?: ApproverRoutingCap;
+}
+
+// ── §"Portable approver routing" reference rule — audience default/override ──
+type ApprovalPayload = {
+  approversList?: string[];
+  approverGroupRefs?: string[];
+  approverRoleRefs?: string[];
+  audience?: { subjects?: string[]; groups?: string[]; roles?: string[] };
+};
+/**
+ * The advisory routing union a notifying host SHOULD target. Mirrors the
+ * normative rule: omitted `audience` ⇒ the eligibility union
+ * (`approversList` ∪ `approverGroupRefs` ∪ `approverRoleRefs`); present
+ * `audience` ⇒ its own union, overriding the default. Refs stay opaque —
+ * this composes refs, it does NOT resolve membership.
+ */
+function notifyTargets(p: ApprovalPayload): string[] {
+  const uniq = (xs: string[]): string[] => [...new Set(xs)];
+  if (p.audience) {
+    return uniq([...(p.audience.subjects ?? []), ...(p.audience.groups ?? []), ...(p.audience.roles ?? [])]);
+  }
+  return uniq([...(p.approversList ?? []), ...(p.approverGroupRefs ?? []), ...(p.approverRoleRefs ?? [])]);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// A. Server-free legs
+// ════════════════════════════════════════════════════════════════════════════
+
+describe('interrupt-approver-routing: capability advertisement shape (capabilities.md, server-free)', () => {
+  const caps = loadSchema('capabilities.schema.json');
+  const interrupt = (caps.properties as Record<string, { properties?: Record<string, { required?: string[]; properties?: Record<string, unknown> }> }>).interrupt;
+
+  it('capabilities schema declares interrupt.approverRouting', () => {
+    expect(interrupt, why('capabilities.schema.json §interrupt', 'the interrupt block MUST be declared')).toBeDefined();
+    const ar = interrupt?.properties?.approverRouting;
+    expect(ar, why('RFC 0104', 'interrupt.approverRouting MUST be declared')).toBeDefined();
+    expect(ar?.required, why('RFC 0104', 'approverRouting.supported MUST be required')).toEqual(expect.arrayContaining(['supported']));
+    for (const f of ['supported', 'refKinds', 'audience']) {
+      expect(ar?.properties?.[f], why('RFC 0104', `approverRouting.${f} MUST be declared`)).toBeDefined();
+    }
+  });
+});
+
+describe('interrupt-approver-routing: ApprovalData additive optionality (interrupt.md §approval, server-free)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  const suspend = loadSchema('suspend-request.schema.json');
+  const validate = ajv.compile(suspend);
+
+  const baseApproval = {
+    kind: 'approval',
+    key: 'run:node:0',
+    data: { artifactId: 'a1', artifactType: 'prd', title: 'Approve budget', actions: ['accept', 'reject'] },
+  };
+
+  it('an approval payload WITHOUT the routing fields still validates (additive, optional)', () => {
+    expect(validate(baseApproval), why('RFC 0104 Compatibility', `the fields are optional — Errors: ${JSON.stringify(validate.errors)}`)).toBe(true);
+  });
+  it('an approval payload WITH group/role refs + audience validates', () => {
+    const withRouting = {
+      ...baseApproval,
+      data: {
+        ...baseApproval.data,
+        approverGroupRefs: ['grp:finance-approvers'],
+        approverRoleRefs: ['role:controller'],
+        audience: { groups: ['grp:finance-approvers'], roles: ['role:controller'], subjects: ['user:cfo'] },
+      },
+    };
+    expect(validate(withRouting), why('RFC 0104 §Proposal', `routing fields MUST validate — Errors: ${JSON.stringify(validate.errors)}`)).toBe(true);
+  });
+  it('an audience with an unknown key is rejected (audience object is closed)', () => {
+    const badAudience = { ...baseApproval, data: { ...baseApproval.data, audience: { teams: ['grp:x'] } } };
+    expect(validate(badAudience), why('RFC 0104', 'audience MUST be additionalProperties:false')).toBe(false);
+  });
+});
+
+describe('interrupt-approver-routing: audience default/override rule (interrupt.md §"Portable approver routing", server-free)', () => {
+  it('omitted audience ⇒ notify the resolved eligibility union', () => {
+    expect(
+      notifyTargets({ approversList: ['user:a'], approverGroupRefs: ['grp:fin'], approverRoleRefs: ['role:ctrl'] }),
+      why('RFC 0104', 'omitted audience MUST default to the eligibility union'),
+    ).toEqual(['user:a', 'grp:fin', 'role:ctrl']);
+  });
+  it('present audience ⇒ overrides the eligibility union', () => {
+    expect(
+      notifyTargets({ approverGroupRefs: ['grp:fin'], audience: { subjects: ['user:cfo'], groups: ['grp:audit'] } }),
+      why('RFC 0104', 'present audience MUST override the default'),
+    ).toEqual(['user:cfo', 'grp:audit']);
+  });
+  it('no eligibility refs and no audience ⇒ empty target set', () => {
+    expect(notifyTargets({}), why('RFC 0104', 'nothing to route when no refs')).toEqual([]);
+  });
+});
+
+// ════════════════════════════════════════════════════════════════════════════
+// B. Capability-gated advertisement-coherence leg
+// ════════════════════════════════════════════════════════════════════════════
+
+describe('interrupt-approver-routing: advertised shape is honest (capability-gated)', () => {
+  it('an advertising host advertises a coherent approverRouting block', async () => {
+    if (!process.env.OPENWOP_BASE_URL) return; // no live host → nothing to read
+    const interrupt = await readCapabilityFamily<InterruptCap>('interrupt');
+    const ar = interrupt?.approverRouting;
+    // Soft-skip: host does not advertise the capability (fields ignored; still conformant).
+    if (!behaviorGate('interrupt.approverRouting', ar?.supported === true)) return;
+
+    // Opt-in established (supported === true): the advertised shape MUST be honest.
+    const allowed = new Set(['group', 'role']);
+    for (const k of ar?.refKinds ?? []) {
+      expect(allowed.has(k), why('RFC 0104 capabilities.md', `refKinds MUST be a subset of {group, role} — saw ${k}`)).toBe(true);
+    }
+    if (ar?.audience !== undefined) {
+      expect(typeof ar.audience, why('RFC 0104 capabilities.md', 'approverRouting.audience MUST be boolean')).toBe('boolean');
+    }
+  });
+});