@openwop/openwop-conformance 1.20.0 → 1.23.0

package/src/scenarios/connection-pack-reach-exclusive.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Connection-pack reach exclusivity — `connection-packs.md` §Manifest clause 5
+ * (RFC 0095 §B.5).
+ *
+ * Always-on, server-free schema probe. `provider.reach` MUST specify exactly
+ * ONE of `mcp` / `openapi` / `integration` — the schema pins this with
+ * `minProperties: 1` + `maxProperties: 1` + `additionalProperties: false`:
+ *
+ *   1. Positive: each of the three reach modes validates alone.
+ *   2. Negative — two modes (`mcp` + `openapi`) → `maxProperties` violation.
+ *   3. Negative — zero modes (`reach: {}`) → `minProperties` violation.
+ *   4. Negative — an unknown mode (`grpc`) → `additionalProperties` violation.
+ *
+ * @see spec/v1/connection-packs.md
+ * @see schemas/connection-pack-manifest.schema.json
+ * @see RFCS/0095-connection-packs-portable-provider-definitions.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 type { ErrorObject } from 'ajv';
+import { SCHEMAS_DIR, FIXTURES_DIR } from '../lib/paths.js';
+
+const SCHEMA_PATH = join(SCHEMAS_DIR, 'connection-pack-manifest.schema.json');
+const FIXTURE_PATH = join(FIXTURES_DIR, 'connection-packs', 'connection-pack-github.json');
+
+const MCP = { mcp: { server: { url: 'https://api.githubcopilot.com/mcp/', transport: 'http' } } };
+const OPENAPI = { openapi: { ref: 'https://api.github.com/openapi.json' } };
+const INTEGRATION = { integration: { node: 'core.openwop.integration.github' } };
+
+type Manifest = Record<string, unknown> & { provider: Record<string, unknown> };
+
+function withReach(reach: Record<string, unknown>): Manifest {
+  const m = JSON.parse(readFileSync(FIXTURE_PATH, 'utf8')) as Manifest;
+  m.provider.reach = reach;
+  return m;
+}
+
+describe('connection-pack-reach-exclusive (RFC 0095 §B.5)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(JSON.parse(readFileSync(SCHEMA_PATH, 'utf8')));
+
+  const failsWith = (manifest: unknown, keyword: string): ErrorObject[] => {
+    const ok = validate(manifest);
+    expect(ok).toBe(false);
+    return (validate.errors ?? []).filter((e) => e.keyword === keyword);
+  };
+
+  it('positive: each reach mode validates alone', () => {
+    for (const reach of [MCP, OPENAPI, INTEGRATION]) {
+      expect(
+        validate(withReach(reach)),
+        `connection-packs.md §Manifest clause 5: a single reach mode (${Object.keys(reach)[0]}) MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+      ).toBe(true);
+    }
+  });
+
+  it('negative: two reach modes are rejected (maxProperties:1)', () => {
+    const errs = failsWith(withReach({ ...MCP, ...OPENAPI }), 'maxProperties');
+    expect(
+      errs.length,
+      'connection-packs.md §Manifest clause 5: reach MUST specify exactly one of mcp/openapi/integration',
+    ).toBeGreaterThan(0);
+  });
+
+  it('negative: an empty reach is rejected (minProperties:1)', () => {
+    const errs = failsWith(withReach({}), 'minProperties');
+    expect(
+      errs.length,
+      'connection-packs.md §Manifest clause 5: reach MUST declare a mode — an empty object is invalid',
+    ).toBeGreaterThan(0);
+  });
+
+  it('negative: an unknown reach mode is rejected (additionalProperties:false)', () => {
+    const errs = failsWith(withReach({ grpc: { url: 'https://example.com' } }), 'additionalProperties');
+    expect(
+      errs.some((e) => (e.params as { additionalProperty?: string }).additionalProperty === 'grpc'),
+      'connection-packs.md §Manifest clause 5: the reach vocabulary is closed (mcp | openapi | integration)',
+    ).toBe(true);
+  });
+});

package/src/scenarios/connection-pack-write-reconsent.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Connection-pack write re-consent — `connection-packs.md` §Manifest clause 4
+ * (RFC 0095 §B.4) — behavioral.
+ *
+ * Capability-gated on `capabilities.connections.packsSupported: true`
+ * (soft-skips when unadvertised; hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`). Drives the
+ * `POST /v1/host/sample/connection-packs/consent-plan` test seam
+ * (`host-sample-test-seams.md`); hosts that haven't wired the seam
+ * soft-skip (404).
+ *
+ * For a `scopeModel: "groups"` oauth2 provider, requesting read AND write
+ * scope groups MUST plan write as a SEPARATE consent step — a host MUST NOT
+ * bundle write scopes into the initial read authorization (composes with the
+ * RFC 0047 write-re-consent pattern):
+ *
+ *   1. The plan has ≥ 2 steps when both read and write groups are requested.
+ *   2. The FIRST (initial) authorization step carries no write scope group.
+ *   3. A read-only request plans a single step (no spurious re-consent).
+ *
+ * @see spec/v1/connection-packs.md
+ * @see spec/v1/host-sample-test-seams.md
+ * @see RFCS/0095-connection-packs-portable-provider-definitions.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { FIXTURES_DIR } from '../lib/paths.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const FIXTURE_PATH = join(FIXTURES_DIR, 'connection-packs', 'connection-pack-github.json');
+
+interface ConsentStep {
+  groups?: Array<{ key?: string; access?: 'read' | 'write' }>;
+  includesWrite?: boolean;
+}
+
+interface ConsentPlan {
+  steps?: ConsentStep[];
+}
+
+describe('connection-pack-write-reconsent (RFC 0095 §B.4)', () => {
+  it('write scope groups are a separate consent step, never bundled into the initial read authorization', async () => {
+    const connections = await readCapabilityFamily<{ packsSupported?: boolean }>('connections');
+    if (!behaviorGate('connections.packsSupported', connections?.packsSupported === true)) return;
+
+    const manifest = JSON.parse(readFileSync(FIXTURE_PATH, 'utf8')) as Record<string, unknown>;
+    await driver.post('/v1/host/sample/connection-packs/install', { manifest });
+
+    const res = await driver.post('/v1/host/sample/connection-packs/consent-plan', {
+      provider: 'github',
+      requested: ['read', 'write'],
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const plan = res.json as ConsentPlan | undefined;
+    const steps = plan?.steps ?? [];
+    expect(
+      steps.length >= 2,
+      driver.describe(
+        'connection-packs.md §Manifest clause 4',
+        'requesting read + write scope groups MUST plan write as a SEPARATE consent step (≥ 2 steps)',
+      ),
+    ).toBe(true);
+    const first = steps[0] ?? {};
+    const firstHasWrite =
+      first.includesWrite === true || (first.groups ?? []).some((g) => g.access === 'write');
+    expect(
+      firstHasWrite,
+      driver.describe(
+        'connection-packs.md §Manifest clause 4',
+        'the INITIAL authorization step MUST NOT bundle write scopes',
+      ),
+    ).toBe(false);
+
+    const readOnly = await driver.post('/v1/host/sample/connection-packs/consent-plan', {
+      provider: 'github',
+      requested: ['read'],
+    });
+    if (readOnly.status !== 404 && readOnly.status !== 403) {
+      const roSteps = (readOnly.json as ConsentPlan | undefined)?.steps ?? [];
+      expect(
+        roSteps.length,
+        driver.describe('connection-packs.md §Manifest clause 4', 'a read-only request plans a single consent step'),
+      ).toBe(1);
+    }
+  });
+});

package/src/scenarios/connection-provider-resolution.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Connection-pack provider resolution — `connection-packs.md` §Manifest
+ * clauses 6 + 8 (RFC 0095 §B.6/§B.8) — behavioral.
+ *
+ * Capability-gated on `capabilities.connections.packsSupported: true`
+ * (soft-skips when unadvertised; hard-fails under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true`). Drives the host through the
+ * `POST /v1/host/sample/connection-packs/{install,resolve}` test seams
+ * (`host-sample-test-seams.md`); hosts that haven't wired the seams
+ * soft-skip (404).
+ *
+ *   1. INSTALL + RESOLVE (§B.6) — installing the `connection-pack-github`
+ *      fixture makes `provider: "github"` resolve with `source: "pack"`.
+ *   2. UNRESOLVED (§B.6) — a provider with no installed pack and no
+ *      built-in fails with `connection_provider_unresolved`.
+ *   3. PRERELEASE CONFLICT (§B.6, SemVer §11) — an installed prerelease
+ *      (`1.0.0-alpha.1`) does NOT outrank a built-in `1.0.0` (prerelease <
+ *      release); the host MUST surface `connection_provider_conflict`
+ *      rather than silently choosing.
+ *   4. REJECTION ISOLATION (§B.8) — a rejected manifest (credential
+ *      material) means NOT INSTALLED, nothing more: a subsequent valid
+ *      install on the same host MUST still succeed (one bad pack never
+ *      takes down the install path).
+ *
+ * @see spec/v1/connection-packs.md
+ * @see spec/v1/host-sample-test-seams.md
+ * @see RFCS/0095-connection-packs-portable-provider-definitions.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { FIXTURES_DIR } from '../lib/paths.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const FIXTURE_PATH = join(FIXTURES_DIR, 'connection-packs', 'connection-pack-github.json');
+
+type Manifest = Record<string, unknown> & {
+  provider: Record<string, unknown> & { id: string };
+};
+
+interface InstallResult {
+  installed?: boolean;
+  errors?: Array<{ code?: string; path?: string }>;
+}
+
+interface ResolveResult {
+  resolved?: boolean;
+  source?: 'pack' | 'builtin';
+  version?: string;
+  code?: string;
+}
+
+function fixture(): Manifest {
+  return JSON.parse(readFileSync(FIXTURE_PATH, 'utf8')) as Manifest;
+}
+
+async function gate(): Promise<boolean> {
+  const connections = await readCapabilityFamily<{ packsSupported?: boolean }>('connections');
+  return behaviorGate('connections.packsSupported', connections?.packsSupported === true);
+}
+
+describe('connection-provider-resolution (RFC 0095 §B.6/§B.8)', () => {
+  it('an installed pack resolves its provider id; an unknown provider is unresolved', async () => {
+    if (!(await gate())) return;
+
+    const install = await driver.post('/v1/host/sample/connection-packs/install', { manifest: fixture() });
+    if (install.status === 404 || install.status === 403) return; // seam unwired — soft-skip
+    const installed = install.json as InstallResult | undefined;
+    expect(
+      installed?.installed,
+      driver.describe('connection-packs.md §Manifest clause 1', 'a well-formed connection pack MUST install'),
+    ).toBe(true);
+
+    const hit = await driver.post('/v1/host/sample/connection-packs/resolve', { provider: 'github' });
+    const resolved = hit.json as ResolveResult | undefined;
+    expect(
+      resolved?.resolved,
+      driver.describe('connection-packs.md §Manifest clause 6', 'provider "github" MUST resolve against the installed pack whose provider.id matches'),
+    ).toBe(true);
+    expect(
+      resolved?.source,
+      driver.describe('connection-packs.md §Manifest clause 6', 'the installed pack is the resolution source'),
+    ).toBe('pack');
+
+    const miss = await driver.post('/v1/host/sample/connection-packs/resolve', {
+      provider: 'conformance-nonexistent-provider-xyz',
+    });
+    const unresolved = miss.json as ResolveResult | undefined;
+    expect(
+      unresolved?.resolved,
+      driver.describe('connection-packs.md §Manifest clause 6', 'a provider with no installed pack and no built-in MUST NOT resolve'),
+    ).toBe(false);
+    expect(
+      unresolved?.code,
+      driver.describe('connection-packs.md §Manifest clause 6', 'the refusal code MUST be connection_provider_unresolved'),
+    ).toBe('connection_provider_unresolved');
+  });
+
+  it('an installed prerelease does not outrank a built-in release — conflict surfaces (SemVer §11)', async () => {
+    if (!(await gate())) return;
+
+    const prerelease = { ...fixture(), version: '1.0.0-alpha.1' };
+    prerelease.provider = { ...prerelease.provider, id: 'conformance-prerelease-probe' };
+    const install = await driver.post('/v1/host/sample/connection-packs/install', { manifest: prerelease });
+    if (install.status === 404 || install.status === 403) return; // seam unwired — soft-skip
+    expect(
+      (install.json as InstallResult | undefined)?.installed,
+      driver.describe('connection-packs.md §Manifest clause 1', 'a prerelease-versioned pack is shape-valid and MUST install'),
+    ).toBe(true);
+
+    const res = await driver.post('/v1/host/sample/connection-packs/resolve', {
+      provider: 'conformance-prerelease-probe',
+      simulateBuiltinVersion: '1.0.0',
+    });
+    if (res.status === 404 || res.status === 403) return; // simulate knob unwired — soft-skip
+    const body = res.json as ResolveResult | undefined;
+    expect(
+      body?.code,
+      driver.describe(
+        'connection-packs.md §Manifest clause 6',
+        'SemVer §11: 1.0.0-alpha.1 < 1.0.0 — the installed pack is NOT greater-or-equal, so the host MUST surface connection_provider_conflict rather than silently choosing',
+      ),
+    ).toBe('connection_provider_conflict');
+  });
+
+  it('rejection isolation: one rejected pack never takes down the install path (§B.8)', async () => {
+    if (!(await gate())) return;
+
+    const leaky = fixture();
+    leaky.provider = { ...leaky.provider, id: 'conformance-isolation-probe' };
+    (leaky.provider.auth as Record<string, unknown>).clientSecret = 'ghs_conformance_canary';
+    const bad = await driver.post('/v1/host/sample/connection-packs/install', { manifest: leaky });
+    if (bad.status === 404 || bad.status === 403) return; // seam unwired — soft-skip
+    expect(
+      (bad.json as InstallResult | undefined)?.installed,
+      driver.describe('connection-packs.md §Manifest clause 2', 'the credential-carrying manifest MUST NOT install'),
+    ).toBe(false);
+
+    const good = { ...fixture() };
+    good.provider = { ...good.provider, id: 'conformance-isolation-survivor' };
+    const after = await driver.post('/v1/host/sample/connection-packs/install', { manifest: good });
+    expect(
+      (after.json as InstallResult | undefined)?.installed,
+      driver.describe(
+        'connection-packs.md §Manifest clause 8',
+        'a rejected pack means NOT INSTALLED — nothing more; a subsequent valid install MUST succeed',
+      ),
+    ).toBe(true);
+  });
+});

package/src/scenarios/cross-host-traceparent-propagation.test.ts

@@ -35,10 +35,10 @@
 
 import { describe, it } from 'vitest';
 
-// Behavioral assertions in this file are currently `it.todo` placeholders;
+// Behavioral assertions in this file are currently `it.skip` placeholders;
 // the cross-host MCP / A2A peer harness (gated on OPENWOP_MCP_REAL_SERVER_URL
 // / OPENWOP_A2A_REAL_PEER_URL) hasn't landed yet. When it does, the
-// `it.todo` calls flip back to runnable `it(...)` bodies that read discovery
+// `it.skip` calls flip back to runnable `it(...)` bodies that read discovery
 // (via `driver.get('/.well-known/openwop')`), gate on `Phase 3` advertisement,
 // and drive the workflow through the configured real peer.
 
@@ -48,7 +48,7 @@ describe('cross-host-traceparent-propagation: behavioral (RFC 0040 §B)', () =>
   // OPENWOP_MCP_REAL_SERVER_URL) records inbound headers; the test reads
   // the recorded headers and asserts `traceparent` is present + matches
   // the format `00-{traceId}-{spanId}-{flags}` per W3C tracecontext.
-  // Until the peer harness lands, the assertion is surfaced as `todo` so
+  // Until the peer harness lands, the assertion is surfaced as `it.skip` so
   // test reporters track the gap rather than reporting a vacuous PASS.
   // Marked out of stable profile via RFC 0042 §B (experimental tier):
   // RFC 0040 remains Active. Hosts that wire Phase 3 cross-host causation

package/src/scenarios/experimental-tier-shape.test.ts

@@ -29,6 +29,7 @@
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
 import { experimentalGate } from '../lib/behavior-gate.js';
+import { __resetEnvCacheForTests } from '../lib/env.js';
 import { capabilityFamily } from '../lib/discovery-capabilities.js';
 
 const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
@@ -180,6 +181,12 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §D experimentalGate helper
   it('experimentalGate routes through behaviorGate when tier === undefined or "stable"', () => {
     const prevReqBeh = process.env.OPENWOP_REQUIRE_BEHAVIOR;
     delete process.env.OPENWOP_REQUIRE_BEHAVIOR;
+    // behaviorGate/experimentalGate read a memoized loadEnv() snapshot. Under a
+    // strict suite run (e.g. the conformance-soak sets OPENWOP_REQUIRE_BEHAVIOR=true
+    // process-wide) an earlier scenario has already cached requireBehavior=true, so
+    // the delete above is a no-op against the cache and the default-mode assertions
+    // below would wrongly throw. Bust the memo so this self-test sees default mode.
+    __resetEnvCacheForTests();
     try {
       // Stable + advertised → proceed.
       expect(experimentalGate('test-stable', true, 'stable')).toBe(true);
@@ -188,6 +195,10 @@ describe.skipIf(HTTP_SKIP)('experimental-tier-shape: §D experimentalGate helper
       expect(experimentalGate('test-not-adv', false, 'stable')).toBe(false);
     } finally {
       if (prevReqBeh !== undefined) process.env.OPENWOP_REQUIRE_BEHAVIOR = prevReqBeh;
+      // Restore the real env into the memo so later scenarios gate correctly (a
+      // leaked default-mode cache would turn their strict behaviorGates into
+      // silent soft-skips — a coverage hole).
+      __resetEnvCacheForTests();
     }
   });
 });

package/src/scenarios/fixtures-valid.test.ts

@@ -154,6 +154,40 @@ describe('fixtures: node-pack-manifest schema validity', () => {
   });
 });
 
+describe('fixtures: connection-pack-manifest schema validity', () => {
+  // Connection-pack fixtures live in `fixtures/connection-packs/` (RFC 0095)
+  // so the node-pack validator above doesn't apply the wrong schema. They are
+  // schema-level proof points AND the canonical install payloads for the
+  // capability-gated `connection-provider-resolution` behavioral scenario.
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const schema = JSON.parse(readFileSync(join(SCHEMAS_DIR, 'connection-pack-manifest.schema.json'), 'utf8'));
+  const validate = ajv.compile(schema);
+
+  const dir = join(FIXTURES_DIR, 'connection-packs');
+  const files = readdirSync(dir)
+    .filter((f) => f.endsWith('.json'))
+    .sort();
+
+  it('finds at least one connection-pack fixture (RFC 0095 coverage)', () => {
+    expect(files.length).toBeGreaterThan(0);
+  });
+
+  for (const file of files) {
+    it(`connection-packs/${file} validates against connection-pack-manifest.schema.json`, () => {
+      const data = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+      const ok = validate(data);
+      const errors = (validate.errors ?? [])
+        .map((e: ErrorObject) => `${e.instancePath || '/'}: ${e.message}`)
+        .join('\n');
+      expect(
+        ok,
+        `Fixture connection-packs/${file} fails connection-pack-manifest schema:\n${errors}`,
+      ).toBe(true);
+    });
+  }
+});
+
 describe('fixtures: prompt-template schema validity', () => {
   // PromptTemplate fixtures live in `fixtures/prompt-templates/` per
   // RFC 0027 §A. Like pack manifests, they're schema-level proof points,

package/src/scenarios/grpc-transport.test.ts

@@ -0,0 +1,108 @@
+/**
+ * grpc-transport — `spec/v1/grpc-transport.md` advertisement-shape scenario
+ * (capability-gated on `capabilities.grpc`; the schema block lands with
+ * RFC 0094 §H on this branch).
+ *
+ * SHAPE-ONLY by design: this scenario validates the advertised
+ * `capabilities.grpc` block against the doc's MUSTs without dialing gRPC
+ * (the suite ships no gRPC client — see grpc-transport.md §Implementation
+ * notes). The end-to-end legs (GetCapabilities equivalence, run
+ * round-trip, error-envelope mapping, auth metadata) are listed in
+ * grpc-transport.md §Conformance and stay future work for a host-side
+ * gRPC harness.
+ *
+ * Gated via `behaviorGate('openwop-grpc-transport', grpc !== undefined)`
+ * — soft-skip when the block is absent (absent ⇒ no gRPC transport,
+ * which is conformant), hard-fail under `OPENWOP_REQUIRE_BEHAVIOR=true`
+ * unless honestly opted out (root-first family read per RFC 0073).
+ *
+ * Asserted MUSTs (grpc-transport.md §"Field semantics"):
+ *   - `supported` is a boolean;
+ *   - `service` is the canonical `openwop.v1.Engine` for v1;
+ *   - `tls` ∈ {"required", "optional", "disabled"};
+ *   - `endpoint`, when present, is a `grpc://` or `grpcs://` URI;
+ *   - when `supported: true`, root `supportedTransports` includes
+ *     `"grpc"` ("presence required when gRPC is exposed");
+ *   - a production-profile claimant (root `production` block advertised)
+ *     MUST set `tls: "required"`.
+ *
+ * @see spec/v1/grpc-transport.md §"Field semantics" + §Conformance
+ * @see RFCS/0094-wire-shape-reconciliation.md §H
+ */
+
+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';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+const TLS_VALUES = ['required', 'optional', 'disabled'];
+const V1_SERVICE = 'openwop.v1.Engine';
+
+interface GrpcCap {
+  readonly supported?: unknown;
+  readonly endpoint?: unknown;
+  readonly service?: unknown;
+  readonly tls?: unknown;
+}
+
+describe.skipIf(HTTP_SKIP)('grpc-transport: advertisement shape (grpc-transport.md §Field semantics)', () => {
+  it('an advertised capabilities.grpc block satisfies every doc MUST', async () => {
+    const res = await driver.get('/.well-known/openwop');
+    if (res.status !== 200) return;
+    const grpc = capabilityFamily<GrpcCap>(res.json, 'grpc');
+    if (!behaviorGate('openwop-grpc-transport', grpc !== undefined)) return;
+
+    expect(
+      typeof grpc!.supported,
+      driver.describe('grpc-transport.md §Field semantics', 'capabilities.grpc.supported MUST be a boolean'),
+    ).toBe('boolean');
+
+    expect(
+      grpc!.service,
+      driver.describe('grpc-transport.md §Field semantics', 'v1 hosts MUST use the canonical service name openwop.v1.Engine'),
+    ).toBe(V1_SERVICE);
+
+    expect(
+      TLS_VALUES,
+      driver.describe(
+        'grpc-transport.md §Field semantics',
+        `capabilities.grpc.tls MUST be one of ${TLS_VALUES.join(' / ')} (got ${String(grpc!.tls)})`,
+      ),
+    ).toContain(grpc!.tls);
+
+    if (grpc!.endpoint !== undefined) {
+      expect(
+        typeof grpc!.endpoint === 'string' && /^grpcs?:\/\/.+/.test(grpc!.endpoint),
+        driver.describe(
+          'grpc-transport.md §Field semantics',
+          `capabilities.grpc.endpoint MUST be a grpc:// (cleartext) or grpcs:// (TLS) URI (got ${String(grpc!.endpoint)})`,
+        ),
+      ).toBe(true);
+    }
+
+    if (grpc!.supported === true) {
+      const transports = capabilityFamily<unknown>(res.json, 'supportedTransports');
+      expect(
+        Array.isArray(transports) && transports.includes('grpc'),
+        driver.describe(
+          'grpc-transport.md §Field semantics',
+          'supportedTransports MUST include "grpc" when the gRPC surface is exposed',
+        ),
+      ).toBe(true);
+    }
+
+    // Production-profile claimants MUST require TLS on the gRPC listener.
+    const production = capabilityFamily<unknown>(res.json, 'production');
+    if (production !== undefined && grpc!.supported === true) {
+      expect(
+        grpc!.tls,
+        driver.describe(
+          'grpc-transport.md §Field semantics',
+          'production hosts MUST set capabilities.grpc.tls: "required"',
+        ),
+      ).toBe('required');
+    }
+  });
+});