@openwop/openwop-conformance 1.37.0 → 1.44.0

package/src/scenarios/frontend-plugin-packs.test.ts

@@ -0,0 +1,230 @@
+/**
+ * Front-end plugin packs — `frontend-plugin-packs.md` (RFC 0117). Public test for
+ * the four protocol-tier SECURITY invariants `frontend-plugin-isolation` /
+ * `frontend-plugin-egress` / `frontend-plugin-rpc-allowlist` / `frontend-plugin-no-byok`,
+ * plus the manifest shape and the `ui-plugin/1` host-RPC + version-token concurrency
+ * contract.
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free schema probe — `frontend-plugin-manifest.schema.json`
+ *      and `ui-plugin-message.schema.json` enforce the wire shape: a valid manifest /
+ *      message validates; a backend `runtime` member, a `uiPlugins[]` entry missing
+ *      `entry`, an out-of-allowlist `method`, and any envelope `additionalProperties`
+ *      are rejected. The `version`-token concurrency contract (the `artifact_conflict`
+ *      error code + `currentVersion`) is schema-pinned. No credential-bearing field is
+ *      admitted on the envelope (`frontend-plugin-no-byok`).
+ *
+ *   B. Capability-gated behavioral leg — on a host advertising
+ *      `capabilities.uiPlugins.supported: true` that exposes the
+ *      `POST /v1/host/sample/ui-plugin/rpc` test seam, an undeclared-method request
+ *      MUST be refused with `method_not_allowed` (`frontend-plugin-rpc-allowlist`), and
+ *      a stale `artifact.write` MUST be refused with `artifact_conflict` + `currentVersion`
+ *      and MUST NOT persist (§Concurrency). Hosts without the seam soft-skip (404);
+ *      unadvertised hosts skip via the behavior gate. (No conformant host advertises
+ *      `uiPlugins` yet — these legs soft-skip until the openwop-app reference host (ADR
+ *      0153) lands, the first witness that graduates the invariants to protocol.)
+ *
+ * @see spec/v1/frontend-plugin-packs.md
+ * @see SECURITY/invariants.yaml ids: frontend-plugin-{isolation,egress,rpc-allowlist,no-byok}
+ * @see RFCS/0117-frontend-plugin-packs.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 { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const MANIFEST_SCHEMA = join(SCHEMAS_DIR, 'frontend-plugin-manifest.schema.json');
+const MESSAGE_SCHEMA = join(SCHEMAS_DIR, 'ui-plugin-message.schema.json');
+
+function validManifest(): Record<string, unknown> {
+  return {
+    name: 'vendor.acme.canvas-editor',
+    version: '1.0.0',
+    kind: 'frontend-plugin',
+    engines: { openwop: '>=1.2.0' },
+    uiPlugins: [
+      {
+        pluginId: 'app-builder',
+        surface: 'artifact-viewer',
+        entry: 'ui/app-builder.mjs',
+        hostApi: ['artifact.read', 'artifact.write'],
+      },
+    ],
+  };
+}
+
+describe('frontend-plugin manifest: schema layer (always-on, server-free)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(JSON.parse(readFileSync(MANIFEST_SCHEMA, 'utf8')));
+
+  it('a well-formed frontend-plugin manifest validates', () => {
+    expect(
+      validate(validManifest()),
+      `frontend-plugin-packs.md §The pack — a valid manifest MUST validate. Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('a backend `runtime` member is rejected (a plugin is sandboxed UI, not a node entry)', () => {
+    const m = { ...validManifest(), runtime: { language: 'javascript', entry: 'index.mjs' } };
+    expect(
+      validate(m),
+      'node-packs.md §Pack kinds — a kind:"frontend-plugin" manifest carrying `runtime` MUST be rejected (pack_kind_invalid)',
+    ).toBe(false);
+  });
+
+  it('a uiPlugins[] entry missing `entry` is rejected', () => {
+    const m = validManifest();
+    delete (m.uiPlugins as Array<Record<string, unknown>>)[0].entry;
+    expect(validate(m), 'a uiPlugins[] entry missing `entry` MUST NOT validate').toBe(false);
+  });
+
+  it('an `entry` path with `..` traversal is rejected', () => {
+    const m = validManifest();
+    (m.uiPlugins as Array<Record<string, unknown>>)[0].entry = '../escape.mjs';
+    expect(validate(m), 'an `entry` path MUST NOT contain `..` (path-traversal)').toBe(false);
+  });
+
+  it('a hostApi method outside the closed allowlist is rejected (frontend-plugin-rpc-allowlist)', () => {
+    const m = validManifest();
+    (m.uiPlugins as Array<Record<string, unknown>>)[0].hostApi = ['artifact.read', 'host.exec'];
+    expect(
+      validate(m),
+      'frontend-plugin-packs.md §Host-RPC — only the closed allowlist methods are permitted; `host.exec` MUST NOT validate',
+    ).toBe(false);
+  });
+
+  it('an empty uiPlugins[] is rejected (a pack MUST declare at least one plugin)', () => {
+    const m = { ...validManifest(), uiPlugins: [] };
+    expect(validate(m), 'a frontend-plugin pack MUST declare at least one uiPlugins[] entry').toBe(false);
+  });
+});
+
+describe('ui-plugin/1 message: schema layer (always-on, server-free)', () => {
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validate = ajv.compile(JSON.parse(readFileSync(MESSAGE_SCHEMA, 'utf8')));
+
+  it('a valid artifact.write request carrying a version token validates', () => {
+    const req = {
+      openwop: 'ui-plugin/1',
+      type: 'request',
+      id: 7,
+      method: 'artifact.write',
+      params: { artifactId: 'a-1', version: 'opaque-v1', payload: {} },
+    };
+    expect(validate(req), `a valid artifact.write request MUST validate. Errors: ${JSON.stringify(validate.errors)}`).toBe(true);
+  });
+
+  it('an artifact_conflict response carries currentVersion (version-token concurrency)', () => {
+    const res = {
+      openwop: 'ui-plugin/1',
+      type: 'response',
+      id: 7,
+      ok: false,
+      error: { code: 'artifact_conflict', currentVersion: 'opaque-v2' },
+    };
+    expect(
+      validate(res),
+      `frontend-plugin-packs.md §Concurrency — a stale write surfaces artifact_conflict + currentVersion. Errors: ${JSON.stringify(validate.errors)}`,
+    ).toBe(true);
+  });
+
+  it('a request with a method outside the allowlist is schema-rejected', () => {
+    const req = { openwop: 'ui-plugin/1', type: 'request', id: 1, method: 'host.exec' };
+    expect(validate(req), 'a method outside the ui-plugin/1 allowlist MUST NOT validate').toBe(false);
+  });
+
+  it('a message without the ui-plugin/1 protocol tag is rejected', () => {
+    const req = { openwop: 'ui-plugin/2', type: 'request', id: 1, method: 'artifact.read' };
+    expect(validate(req), 'a host MUST ignore messages whose ui-plugin tag it does not recognize').toBe(false);
+  });
+
+  it('no credential-bearing field is admitted on the envelope (frontend-plugin-no-byok)', () => {
+    // additionalProperties:false on every envelope variant — a stray apiKey/token at the
+    // envelope root cannot ride the boundary.
+    for (const leak of ['apiKey', 'token', 'clientSecret', 'authorization']) {
+      const req = { openwop: 'ui-plugin/1', type: 'request', id: 1, method: 'artifact.read', [leak]: 'xxx' };
+      expect(
+        validate(req),
+        `frontend-plugin-no-byok — a credential-named envelope field ("${leak}") MUST NOT validate (additionalProperties:false)`,
+      ).toBe(false);
+    }
+  });
+});
+
+describe('frontend-plugin: isolation advertisement (always-on, capability shape)', () => {
+  it('a host advertising uiPlugins MUST pin isolation to cross-origin-iframe', async () => {
+    const uiPlugins = await readCapabilityFamily<{ supported?: boolean; isolation?: string }>('uiPlugins');
+    if (!uiPlugins?.supported) return; // unadvertised → out of scope (graceful degradation)
+    expect(
+      uiPlugins.isolation,
+      driver.describe(
+        'frontend-plugin-packs.md §Isolation',
+        'frontend-plugin-isolation — the ONLY conformant isolation model is cross-origin-iframe (in-process is a protocol-tier MUST NOT)',
+      ),
+    ).toBe('cross-origin-iframe');
+  });
+});
+
+describe('frontend-plugin: host-RPC behavior (capability-gated)', () => {
+  it('an undeclared host-RPC method is refused with method_not_allowed', async () => {
+    const uiPlugins = await readCapabilityFamily<{ supported?: boolean }>('uiPlugins');
+    if (!behaviorGate('uiPlugins.supported', uiPlugins?.supported === true)) return;
+
+    const res = await driver.post('/v1/host/sample/ui-plugin/rpc', {
+      message: { openwop: 'ui-plugin/1', type: 'request', id: 1, method: 'host.exec' },
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { ok?: boolean; error?: { code?: string } } | undefined;
+    expect(
+      body?.ok,
+      driver.describe('frontend-plugin-packs.md §Host-RPC', 'an undeclared method MUST NOT execute'),
+    ).toBe(false);
+    expect(
+      body?.error?.code,
+      driver.describe(
+        'frontend-plugin-packs.md §Host-RPC',
+        'frontend-plugin-rpc-allowlist — an undeclared method surfaces method_not_allowed',
+      ),
+    ).toBe('method_not_allowed');
+  });
+
+  it('a stale artifact.write is refused with artifact_conflict + currentVersion (no persist)', async () => {
+    const uiPlugins = await readCapabilityFamily<{ supported?: boolean; hostApi?: string[] }>('uiPlugins');
+    if (!behaviorGate('uiPlugins.supported', uiPlugins?.supported === true)) return;
+    if (!(uiPlugins?.hostApi ?? []).includes('artifact.write')) return; // write unsupported → out of scope
+
+    const res = await driver.post('/v1/host/sample/ui-plugin/rpc', {
+      message: {
+        openwop: 'ui-plugin/1',
+        type: 'request',
+        id: 2,
+        method: 'artifact.write',
+        params: { artifactId: 'conformance-canary', version: 'stale-token', payload: {} },
+      },
+    });
+    if (res.status === 404 || res.status === 403) return; // seam unwired — soft-skip
+
+    const body = res.json as { ok?: boolean; error?: { code?: string; currentVersion?: string } } | undefined;
+    expect(
+      body?.error?.code,
+      driver.describe(
+        'frontend-plugin-packs.md §Concurrency',
+        'a stale artifact.write version surfaces artifact_conflict (host MUST NOT persist)',
+      ),
+    ).toBe('artifact_conflict');
+    expect(
+      typeof body?.error?.currentVersion,
+      driver.describe('frontend-plugin-packs.md §Concurrency', 'artifact_conflict carries the host currentVersion for re-read/merge'),
+    ).toBe('string');
+  });
+});

package/src/scenarios/memory-injection-budget.test.ts

@@ -0,0 +1,188 @@
+/**
+ * RFC 0113 — Memory Injection Budget.
+ *
+ * Verifies the new token-denominated bound on the live injection read:
+ * `MemoryAdapter.list(memoryRef, { tokenBudget, rank, query })`
+ * (`spec/v1/agent-memory.md` §"Injection budget"). The genuinely new
+ * contribution is `tokenBudget`; `rank:'relevance'` DELEGATES to the
+ * existing `memory.search` semantic mode (RFC 0080) — this scenario does
+ * NOT assert a parallel ranking primitive, and the relevance leg soft-skips
+ * unless the host ALSO advertises `memory.search` semantic.
+ *
+ * Capability-gated on `capabilities.memory.injectionBudget.supported === true`
+ * (root-first per RFC 0073) via `behaviorGate`. Driven through the host-sample
+ * memory seam — the `conformance-agent-memory-injection-budget` fixture (the
+ * same `/v1/runs` + run-variable seam the other `agentMemory*` scenarios use to
+ * reach the adapter), which seeds a set whose total exceeds the budget AND
+ * includes one single entry larger than the whole budget, plus a BYOK-redacted
+ * entry and a cross-tenant probe.
+ *
+ * Asserts: cumulative tokens ≤ `tokenBudget`; an over-budget single entry is
+ * omitted (not truncated); `rank:'relevance'` ordering differs from recency on
+ * the crafted fixture (only when `memory.search` semantic is advertised, else
+ * soft-skip); and re-asserts SR-1 (redacted content) + CTI-1 (cross-tenant
+ * probe empty) on the budgeted path as a regression guard.
+ *
+ * @see RFCS/0113-memory-injection-budget.md
+ * @see spec/v1/agent-memory.md §"Injection budget"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const FIXTURE = 'conformance-agent-memory-injection-budget';
+const PROFILE = 'openwop-memory-injection-budget';
+
+interface MemoryInjectionBudgetCap {
+  readonly supported?: boolean;
+  readonly tokenCounter?: string;
+}
+interface MemorySearchCap {
+  readonly supported?: boolean;
+  readonly modes?: readonly string[];
+}
+interface MemoryCap {
+  readonly injectionBudget?: MemoryInjectionBudgetCap;
+  readonly search?: MemorySearchCap;
+}
+
+// ── cast-free typed accessors (no `as`) ──────────────────────────────────
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isString(v: unknown): v is string {
+  return typeof v === 'string';
+}
+function isNumber(v: unknown): v is number {
+  return typeof v === 'number';
+}
+function isBoolean(v: unknown): v is boolean {
+  return typeof v === 'boolean';
+}
+function stringOf(v: unknown): string | undefined {
+  return isString(v) ? v : undefined;
+}
+function numberOf(v: unknown): number | undefined {
+  return isNumber(v) ? v : undefined;
+}
+function booleanOf(v: unknown): boolean | undefined {
+  return isBoolean(v) ? v : undefined;
+}
+function stringArrayOf(v: unknown): string[] | undefined {
+  return Array.isArray(v) && v.every(isString) ? v : undefined;
+}
+function recordArrayOf(v: unknown): Record<string, unknown>[] | undefined {
+  return Array.isArray(v) && v.every(isRecord) ? v : undefined;
+}
+function runIdOf(v: unknown): string | undefined {
+  return isRecord(v) ? stringOf(v['runId']) : undefined;
+}
+function variablesOf(v: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(v)) return undefined;
+  const vars = v['variables'];
+  return isRecord(vars) ? vars : undefined;
+}
+
+function advertisesSemanticSearch(mem: MemoryCap | undefined): boolean {
+  const modes = mem?.search?.modes;
+  return mem?.search?.supported === true && Array.isArray(modes) && modes.includes('semantic');
+}
+
+async function driveFixtureVariables(): Promise<Record<string, unknown> | undefined> {
+  const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+  expect(create.status).toBe(201);
+  const runId = runIdOf(create.json);
+  expect(runId, 'POST /v1/runs MUST return a runId').toBeDefined();
+  if (runId === undefined) return undefined;
+
+  const terminal = await pollUntilTerminal(runId);
+  expect(terminal.status).toBe('completed');
+
+  const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+  return variablesOf(snap.json);
+}
+
+describe('memory-injection-budget (RFC 0113)', () => {
+  it('token-bounds the injection read, omits the over-budget entry, and preserves SR-1 + CTI-1', async () => {
+    const mem = await readCapabilityFamily<MemoryCap>('memory');
+    if (!behaviorGate(PROFILE, mem?.injectionBudget?.supported === true)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return; // fixture-gated soft-skip
+
+    const v = await driveFixtureVariables();
+    expect(v, 'fixture MUST surface run variables').toBeDefined();
+    if (v === undefined) return;
+
+    // ── tokenBudget bound (the new lever) ──────────────────────────────
+    const tokenBudget = numberOf(v['tokenBudget']);
+    const total = numberOf(v['budgetedTokenTotal']);
+    expect(tokenBudget, 'fixture MUST echo the requested tokenBudget').toBeDefined();
+    expect(total, 'fixture MUST surface the budgeted cumulative token total').toBeDefined();
+    // Cumulative tokens across the returned prefix MUST NOT exceed the budget.
+    if (tokenBudget !== undefined && total !== undefined) {
+      expect(total).toBeLessThanOrEqual(tokenBudget);
+    }
+
+    // ── over-budget single entry omitted (not truncated) ───────────────
+    expect(
+      booleanOf(v['overBudgetEntryOmitted']),
+      'an entry larger than the whole budget MUST be omitted, not truncated mid-entry',
+    ).toBe(true);
+    const entries = recordArrayOf(v['budgetedEntries']);
+    expect(entries, 'fixture MUST surface the budgeted entry slice').toBeDefined();
+    const overId = stringOf(v['overBudgetEntryId']);
+    if (entries !== undefined && overId !== undefined) {
+      const ids = entries.map((e) => stringOf(e['id']));
+      expect(ids, 'the over-budget entry MUST NOT appear in the returned slice').not.toContain(overId);
+    }
+
+    // ── SR-1 re-assertion on the budgeted path ─────────────────────────
+    // A budgeted/ranked read ranks over already-redacted content; the read
+    // surface MUST carry the redaction marker, never the plaintext.
+    const redacted = stringOf(v['redactedContentSample']);
+    expect(redacted, 'budgeted read MUST surface a redacted-content sample').toBeDefined();
+    if (redacted !== undefined) {
+      expect(redacted).toMatch(/\[REDACTED:[^\]]+\]/);
+    }
+
+    // ── CTI-1 re-assertion on the budgeted path ────────────────────────
+    // A budget/rank prefix of an already-single-tenant list stays single-tenant:
+    // the cross-tenant probe under the budgeted path MUST return empty.
+    const probe = v['crossTenantBudgetedProbe'];
+    if (Array.isArray(probe)) {
+      expect(probe.length, 'cross-tenant probe on the budgeted path MUST return []').toBe(0);
+    } else {
+      expect(probe, 'cross-tenant probe on the budgeted path MUST return [] / null').toBeFalsy();
+    }
+  });
+
+  it("rank:'relevance' reorders vs recency — only when memory.search semantic is ALSO advertised", async () => {
+    const mem = await readCapabilityFamily<MemoryCap>('memory');
+    if (!behaviorGate(PROFILE, mem?.injectionBudget?.supported === true)) return;
+    // RFC 0113: rank:'relevance' DELEGATES to memory.search semantic (RFC 0080).
+    // A host that does not advertise memory.search semantic MUST NOT fabricate a
+    // relevance ranking — the relevance leg soft-skips here (it is not a new
+    // ranking surface advertised by injectionBudget).
+    if (!advertisesSemanticSearch(mem)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[${PROFILE}] memory.search semantic not advertised; relevance leg soft-skipped`);
+      return;
+    }
+    if (!isFixtureAdvertised(FIXTURE)) return;
+
+    const v = await driveFixtureVariables();
+    expect(v, 'fixture MUST surface run variables').toBeDefined();
+    if (v === undefined) return;
+
+    const recencyOrder = stringArrayOf(v['recencyOrder']);
+    const relevanceOrder = stringArrayOf(v['relevanceOrder']);
+    expect(recencyOrder, 'fixture MUST surface the recency ordering').toBeDefined();
+    expect(relevanceOrder, 'fixture MUST surface the relevance ordering').toBeDefined();
+    // The crafted fixture pins a query whose semantic top-k differs from the
+    // most-recent-first order — relevance MUST reorder (not echo recency).
+    expect(relevanceOrder).not.toEqual(recencyOrder);
+  });
+});

package/src/scenarios/prompt-prefix-cache.test.ts

@@ -0,0 +1,200 @@
+/**
+ * prompt-prefix-cache — RFC 0116 + SECURITY/invariants.yaml
+ * `prompt-prefix-cache-cross-tenant-isolation`.
+ *
+ * Status: ACTIVE (advertisement-shape + behavioral). The behavioral legs drive
+ * the host's real envelope/provider generate path through the OPTIONAL test
+ * seam `POST /v1/host/sample/ai/generate` (`host-sample-test-seams.md` §16,
+ * env-gated on `OPENWOP_TEST_SEAM_ENABLED=true`). Hosts that don't advertise
+ * `aiProviders.promptPrefixCache.supported` soft-skip; hosts that advertise it
+ * but don't wire the seam (HTTP 404/405) soft-skip the behavioral legs and
+ * verify advertisement shape only.
+ *
+ * RFC 0116 makes the optional `cachePrefixId` generate hint safe + testable via
+ * three pillars, each asserted here:
+ *   (a) outcome-invariance — a generate with `cachePrefixId` and a control
+ *       without produce the same accepted envelope + identical
+ *       `inputTokens`/`outputTokens` (cost-hint-only, replay-invariant).
+ *   (b) cache hit observable — a repeat generate shows
+ *       `provider.usage.cacheReadTokens > 0`.
+ *   (c) cross-tenant isolation — tenant B's first use of tenant A's
+ *       `cachePrefixId` shows `cacheReadTokens == 0` (no cross-tenant share).
+ *       THIS is the public test for the `prompt-prefix-cache-cross-tenant-isolation`
+ *       invariant: the host MUST key its provider cache by `(tenant, cachePrefixId)`.
+ *   (d) secret-free — a `cachePrefixId` is never emitted where SR-1 would
+ *       redact, and the usage block carries no prompt substrings.
+ *
+ * @see RFCS/0116-prompt-prefix-cache.md
+ * @see spec/v1/ai-envelope.md §"Prompt-prefix cache (RFC 0116)"
+ * @see SECURITY/invariants.yaml — prompt-prefix-cache-cross-tenant-isolation
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+interface PromptPrefixCacheCap {
+  supported?: unknown;
+  providers?: unknown;
+}
+
+interface AiProvidersCap {
+  promptPrefixCache?: PromptPrefixCacheCap;
+}
+
+interface GenerateUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+interface GenerateResponse {
+  envelope?: { envelopeType?: string; payload?: unknown; envelopeId?: string };
+  usage?: GenerateUsage;
+}
+
+async function readCap(): Promise<PromptPrefixCacheCap | null> {
+  const fam = await readCapabilityFamily<AiProvidersCap>('aiProviders');
+  const block = fam?.promptPrefixCache;
+  return block && typeof block === 'object' ? block : null;
+}
+
+async function generate(args: {
+  tenantId: string;
+  cachePrefixId?: string;
+}): Promise<{ status: number; body: GenerateResponse }> {
+  const res = await driver.post('/v1/host/sample/ai/generate', {
+    tenantId: args.tenantId,
+    envelopeType: 'clarification.request',
+    systemPrompt: 'You are a helpful assistant. Answer concisely.',
+    ...(args.cachePrefixId !== undefined ? { cachePrefixId: args.cachePrefixId } : {}),
+  });
+  return { status: res.status, body: (res.json ?? {}) as GenerateResponse };
+}
+
+describe('prompt-prefix-cache: advertisement shape (RFC 0116)', () => {
+  it('aiProviders.promptPrefixCache is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // not advertised — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §aiProviders.promptPrefixCache',
+        'promptPrefixCache.supported MUST be a boolean when the block is present',
+      ),
+    ).toBe('boolean');
+    if (cap.providers !== undefined) {
+      expect(
+        Array.isArray(cap.providers),
+        driver.describe(
+          'capabilities.schema.json §aiProviders.promptPrefixCache',
+          'promptPrefixCache.providers MUST be an array of provider ids when present (provider-scoped)',
+        ),
+      ).toBe(true);
+    }
+  });
+});
+
+describe('prompt-prefix-cache: behavioral (RFC 0116 §"Normative requirements")', () => {
+  it('(a) outcome-invariance — cachePrefixId vs control → same envelope + identical input/output tokens', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `inv-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const control = await generate({ tenantId: 'tenant-a' });
+    if (control.status === 404 || control.status === 405) return; // seam not wired
+    expect(control.status, driver.describe('host-sample-test-seams.md §16', 'generate seam MUST return 200')).toBe(200);
+
+    const withPrefix = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    expect(withPrefix.status).toBe(200);
+
+    expect(
+      withPrefix.body.envelope?.envelopeType,
+      driver.describe(
+        'ai-envelope.md §"Prompt-prefix cache (RFC 0116)" rule 3',
+        'cachePrefixId is a cost hint, never semantic: the accepted envelope MUST be identical hit-vs-miss',
+      ),
+    ).toBe(control.body.envelope?.envelopeType);
+    expect(withPrefix.body.usage?.inputTokens).toBe(control.body.usage?.inputTokens);
+    expect(
+      withPrefix.body.usage?.outputTokens,
+      driver.describe(
+        'ai-envelope.md §"Prompt-prefix cache (RFC 0116)" rule 3',
+        'provider.usage.inputTokens/outputTokens MUST be identical hit-vs-miss (replay-invariant)',
+      ),
+    ).toBe(control.body.usage?.outputTokens);
+  });
+
+  it('(b) cache hit observable — a repeat generate shows cacheReadTokens > 0 while tokens stay invariant', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `hit-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    const prime = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    if (prime.status === 404 || prime.status === 405) return; // seam not wired
+    expect(prime.status).toBe(200);
+
+    const repeat = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    expect(repeat.status).toBe(200);
+    expect(
+      repeat.body.usage?.cacheReadTokens ?? 0,
+      driver.describe(
+        'ai-envelope.md §"Prompt-prefix cache (RFC 0116)" rule 4',
+        'a repeat generate with the same cachePrefixId for the SAME tenant MUST be an observable cache hit (cacheReadTokens > 0)',
+      ),
+    ).toBeGreaterThan(0);
+    // The cost-only witness MUST NOT have changed the recorded outcome.
+    expect(repeat.body.usage?.inputTokens).toBe(prime.body.usage?.inputTokens);
+    expect(repeat.body.usage?.outputTokens).toBe(prime.body.usage?.outputTokens);
+  });
+
+  it('(c) cross-tenant isolation — tenant B first use of tenant A\'s cachePrefixId → cacheReadTokens == 0', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `xtenant-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    // Tenant A primes the cache under a shared, predictable cachePrefixId.
+    const aPrime = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    if (aPrime.status === 404 || aPrime.status === 405) return; // seam not wired
+    expect(aPrime.status).toBe(200);
+
+    // Tenant B's FIRST use of the SAME cachePrefixId MUST be a miss — the host
+    // keys its provider cache by (resolved tenant, cachePrefixId), never global.
+    const bFirst = await generate({ tenantId: 'tenant-b', cachePrefixId: prefixId });
+    expect(bFirst.status).toBe(200);
+    expect(
+      bFirst.body.usage?.cacheReadTokens ?? 0,
+      driver.describe(
+        'SECURITY/invariants.yaml prompt-prefix-cache-cross-tenant-isolation',
+        'tenant B\'s first use of tenant A\'s cachePrefixId MUST be a cache MISS (cacheReadTokens == 0) — the cache MUST be keyed by (tenant, cachePrefixId), never global; cross-tenant sharing is context leakage',
+      ),
+    ).toBe(0);
+  });
+
+  it('(d) secret-free — the response never echoes cachePrefixId in a SR-1-sensitive position', async () => {
+    const cap = await readCap();
+    if (!cap || cap.supported !== true) return; // not advertised — skip
+    const prefixId = `secretfree-${Date.now()}`;
+
+    const res = await generate({ tenantId: 'tenant-a', cachePrefixId: prefixId });
+    if (res.status === 404 || res.status === 405) return; // seam not wired
+    expect(res.status).toBe(200);
+    // The usage block is cost-only; it MUST NOT carry prompt/response substrings
+    // (SR-1). cachePrefixId is a public cache key, but the cost witness fields
+    // themselves are integers — assert the usage block is shape-clean.
+    const usage = res.body.usage ?? {};
+    for (const k of ['inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens'] as const) {
+      const v = usage[k];
+      if (v !== undefined) {
+        expect(
+          typeof v,
+          driver.describe(
+            'run-event-payloads.schema.json §providerUsage',
+            `provider.usage.${k} MUST be a cost-only integer (no prompt substrings per SR-1)`,
+          ),
+        ).toBe('number');
+      }
+    }
+  });
+});