@openwop/openwop-conformance 1.36.0 → 1.43.0

package/src/scenarios/context-summarization-replay.test.ts

@@ -0,0 +1,155 @@
+/**
+ * RFC 0111 — Context Economy: declared summarization is replay-deterministic.
+ *
+ * A host-produced summary is NONDETERMINISTIC host output that breaks the
+ * purity of the transcript-as-event-log-projection, so RFC 0111 governs it
+ * exactly like an RFC 0041 nondeterministic envelope: each substitution is
+ * recorded as a `context.summarized` event whose `summaryRef` artifact a
+ * `:fork mode:replay` MUST REUSE — the host MUST NOT re-summarize and produce
+ * a different model-facing transcript (`spec/v1/multi-agent-execution.md`
+ * §"Context economy" → "Replay determinism").
+ *
+ * Capability-gated on `multiAgent.executionModel.contextBudget.summarization.supported`
+ * (root-first per RFC 0073) via `behaviorGate`. Drives the multi-turn
+ * orchestrator fixture, reads the recorded `context.summarized` events from the
+ * run event-log (`/v1/host/sample/test/runs/:runId/events`), then replays the
+ * run via `POST /v1/runs/{runId}:fork {mode:"replay"}` and asserts the replayed
+ * run re-emits the SAME `context.summarized` records (same `summaryRef` +
+ * `replacedTurns`) — i.e. the recorded summary is reused, not regenerated.
+ *
+ * The event-log seam + replay are both OPTIONAL — the scenario soft-skips when
+ * the event-log seam is unwired (`404`), when the host advertises no `replay`
+ * mode, or when the run produced no summarization (no `context.summarized`).
+ * The RFC defers reference-host implementation; the witness comes from a host
+ * that runs real orchestrator turns and summarizes.
+ *
+ * @see RFCS/0111-context-economy.md
+ * @see spec/v1/multi-agent-execution.md §"Context economy (RFC 0111)"
+ */
+
+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';
+import { queryTestEvents, type TestEvent } from '../lib/event-log-query.js';
+
+const FIXTURE = 'conformance-context-budget-multiturn';
+const PROFILE = 'openwop-context-summarization';
+
+interface SummarizationCap {
+  readonly supported?: boolean;
+}
+interface ContextBudgetCap {
+  readonly summarization?: SummarizationCap;
+}
+interface ExecutionModelCap {
+  readonly contextBudget?: ContextBudgetCap;
+}
+interface MultiAgentCap {
+  readonly executionModel?: ExecutionModelCap;
+}
+
+// ── 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 stringOf(v: unknown): string | undefined {
+  return isString(v) ? v : undefined;
+}
+function stringArrayOf(v: unknown): string[] | undefined {
+  return Array.isArray(v) && v.every(isString) ? v : undefined;
+}
+function runIdOf(v: unknown): string | undefined {
+  return isRecord(v) ? stringOf(v['runId']) : undefined;
+}
+function replayModesOf(v: unknown): string[] {
+  if (!isRecord(v)) return [];
+  const replay = v['replay'];
+  if (!isRecord(replay)) return [];
+  return stringArrayOf(replay['modes']) ?? [];
+}
+
+/** A summary fingerprint: summaryRef plus the (ordered) replaced-turn ids. */
+function summaryFingerprint(e: TestEvent): string | undefined {
+  const ref = stringOf(e.payload['summaryRef']);
+  const replaced = stringArrayOf(e.payload['replacedTurns']);
+  if (ref === undefined || replaced === undefined) return undefined;
+  return `${ref}::${replaced.join(',')}`;
+}
+
+function summaryFingerprints(events: readonly TestEvent[]): string[] {
+  const out: string[] = [];
+  for (const e of events) {
+    if (e.type !== 'context.summarized') continue;
+    const fp = summaryFingerprint(e);
+    expect(fp, 'a context.summarized event MUST carry summaryRef + replacedTurns').toBeDefined();
+    if (fp !== undefined) out.push(fp);
+  }
+  return out.sort();
+}
+
+describe('context-summarization-replay (RFC 0111 §"Replay determinism")', () => {
+  it('replay reuses the recorded context.summarized summaryRef — never re-summarizes', async () => {
+    const ma = await readCapabilityFamily<MultiAgentCap>('multiAgent');
+    const summarizationSupported = ma?.executionModel?.contextBudget?.summarization?.supported === true;
+    if (!behaviorGate(PROFILE, summarizationSupported)) return;
+    if (!isFixtureAdvertised(FIXTURE)) return; // fixture-gated soft-skip
+
+    // Drive the multi-turn orchestrator run.
+    const create = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(create.status).toBe(201);
+    const sourceRunId = runIdOf(create.json);
+    expect(sourceRunId, 'POST /v1/runs MUST return a runId').toBeDefined();
+    if (sourceRunId === undefined) return;
+    await pollUntilTerminal(sourceRunId);
+
+    // Read the recorded summarization records (OPTIONAL event-log seam).
+    const sourceQ = await queryTestEvents(sourceRunId, { type: 'context.summarized' });
+    if (!sourceQ.ok) return; // event-log seam unwired — soft-skip
+    const sourceFingerprints = summaryFingerprints(sourceQ.events);
+    if (sourceFingerprints.length === 0) {
+      // The run did not summarize (budget not exceeded on this host) — nothing
+      // to prove about reuse. Honest soft-skip; not a vacuous pass of the MUST.
+      // eslint-disable-next-line no-console
+      console.warn(`[${PROFILE}] run produced no context.summarized events; replay-reuse leg soft-skipped`);
+      return;
+    }
+
+    // Only attempt replay when the host advertises the replay fork mode.
+    const wellKnown = await driver.get('/.well-known/openwop');
+    if (!replayModesOf(wellKnown.json).includes('replay')) return;
+
+    const fork = await driver.post(
+      `/v1/runs/${encodeURIComponent(sourceRunId)}:fork`,
+      { fromSeq: 0, mode: 'replay' },
+    );
+    if (fork.status === 501 || fork.status === 404) return; // replay not implemented for this run — soft-skip
+    expect(
+      fork.status,
+      driver.describe('rest-endpoints.md POST /v1/runs/{runId}:fork', 'replay fork MUST return 201'),
+    ).toBe(201);
+    const forkRunId = runIdOf(fork.json);
+    expect(forkRunId, 'replay fork MUST return a runId').toBeDefined();
+    if (forkRunId === undefined) return;
+    await pollUntilTerminal(forkRunId);
+
+    const forkQ = await queryTestEvents(forkRunId, { type: 'context.summarized' });
+    if (!forkQ.ok) return; // event-log seam unwired for the fork — soft-skip
+    const forkFingerprints = summaryFingerprints(forkQ.events);
+
+    // The replay MUST reuse the recorded summaries (same summaryRef + replacedTurns),
+    // NOT regenerate them — the direct analogue of RFC 0041 envelope-refusal recovery.
+    expect(
+      forkFingerprints,
+      driver.describe(
+        'RFC 0111 §"Replay determinism"',
+        'a replay fork MUST reuse the recorded context.summarized summaryRef (never re-summarize to a different transcript)',
+      ),
+    ).toEqual(sourceFingerprints);
+  });
+});

package/src/scenarios/conversation-turn-model-provenance-shape.test.ts

@@ -0,0 +1,120 @@
+/**
+ * Conversation-turn model provenance — `agent.model` (RFC 0109).
+ *
+ * Always-on, server-free schema-shape probe. Verifies the additive, normative
+ * RFC 0109 wire facts on the published schemas:
+ *
+ *   1. `conversation-turn.schema.json` `agent.model` is an OPTIONAL object that
+ *      validates a conforming `{ provider, model }`, REQUIRES both fields, and is
+ *      CLOSED (`additionalProperties: false`) — the SR-1 secret-redaction guard:
+ *      no credential / endpoint / prompt can ride in the provenance stamp.
+ *   2. `agent.model` is OPTIONAL — an agent turn that omits it still validates
+ *      (additive; pre-RFC-0109 producers + hosts that do not advertise).
+ *   3. `capabilities.schema.json` declares the `conversationTurnModelProvenance`
+ *      block with its `supported` flag, and it is closed (`additionalProperties: false`).
+ *
+ * The host-side MUST (a host that advertises `supported: true` MUST stamp
+ * `agent.model`; one that does NOT advertise MUST omit it) is a behavioral
+ * contract gated on `conversationTurnModelProvenance.supported`, landing at the
+ * reference-host implementation (RFC 0109 §Conformance — same staging as RFC
+ * 0101's non-participant-rejection behavioral leg). This scenario asserts the
+ * wire SHAPE; the behavioral leg is gated.
+ *
+ * Normative references:
+ *   - RFCS/0109-conversation-turn-model-provenance.md (§Proposal / §Conformance)
+ *   - RFCS/0005-conversation.md (the conversation primitive this extends)
+ *   - schemas/conversation-turn.schema.json (agent.model)
+ *   - schemas/capabilities.schema.json (conversationTurnModelProvenance)
+ *
+ * @see RFCS/0109-conversation-turn-model-provenance.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';
+
+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>;
+}
+
+describe('conversation-turn-model-provenance-shape: agent.model on a role:agent turn (RFC 0109 §Proposal, server-free)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  const turn = ajv.compile(loadSchema('conversation-turn.schema.json'));
+
+  const agentBase = {
+    messageId: 'council-q1:1:agent',
+    from: 'host:advisor-cfo',
+    content: 'From a cash-runway view I would push the launch one quarter.',
+    ts: 1718900000000,
+    role: 'agent' as const,
+    turnIndex: 1,
+    speakerId: 'host:advisor-cfo',
+  };
+
+  it('an agent turn carrying a conforming agent.model { provider, model } validates', () => {
+    expect(
+      turn({ ...agentBase, agent: { agentId: 'advisor-cfo', model: { provider: 'anthropic', model: 'claude-opus-4-8' } } }),
+      why('RFC 0109 §Proposal', "a role:'agent' turn with agent.model { provider, model } MUST validate"),
+    ).toBe(true);
+  });
+
+  it('agent.model REQUIRES both provider and model', () => {
+    expect(
+      turn({ ...agentBase, agent: { model: { provider: 'anthropic' } } }),
+      why('RFC 0109 §Proposal', 'agent.model without `model` MUST be rejected'),
+    ).toBe(false);
+    expect(
+      turn({ ...agentBase, agent: { model: { model: 'claude-opus-4-8' } } }),
+      why('RFC 0109 §Proposal', 'agent.model without `provider` MUST be rejected'),
+    ).toBe(false);
+  });
+
+  it('agent.model is CLOSED — an extra key (a secret/endpoint/prompt) MUST be rejected (the SR-1 guard)', () => {
+    expect(
+      turn({ ...agentBase, agent: { model: { provider: 'anthropic', model: 'claude-opus-4-8', apiKey: 'sk-secret' } } }),
+      why('RFC 0109 §Proposal', 'agent.model MUST forbid extra keys — no credential/endpoint/prompt rides the provenance stamp'),
+    ).toBe(false);
+  });
+
+  it('agent.model is OPTIONAL — an agent turn that omits it still validates (additive, back-compat)', () => {
+    expect(
+      turn({ ...agentBase, agent: { agentId: 'advisor-cfo' } }),
+      why('RFC 0109 §Compatibility', 'agent.model is additive — a turn without it MUST still validate'),
+    ).toBe(true);
+    expect(
+      turn(agentBase),
+      why('RFC 0109 §Compatibility', 'a turn with no agent object at all MUST still validate'),
+    ).toBe(true);
+  });
+});
+
+describe('conversation-turn-model-provenance-shape: capability advertisement (RFC 0109 §Conformance, server-free)', () => {
+  it('capabilities.schema.json declares conversationTurnModelProvenance with supported, closed', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const props = caps.properties as Record<string, Record<string, unknown>>;
+    const block = props.conversationTurnModelProvenance as
+      | { properties?: Record<string, unknown>; required?: string[]; additionalProperties?: boolean }
+      | undefined;
+    expect(block, why('RFC 0109 §Conformance', 'capabilities.conversationTurnModelProvenance MUST be declared')).toBeDefined();
+    expect(block?.properties?.supported, why('RFC 0109 §Conformance', 'conversationTurnModelProvenance.supported MUST be declared')).toBeDefined();
+    expect(block?.required, why('RFC 0109 §Conformance', 'supported MUST be required on the block')).toContain('supported');
+    expect(block?.additionalProperties, why('RFC 0109 §Conformance', 'the block MUST be closed')).toBe(false);
+  });
+
+  it('the conversationTurnModelProvenance block validates a conforming advertisement and rejects extras', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const block = (caps.properties as Record<string, Record<string, unknown>>).conversationTurnModelProvenance;
+    const ajv = new Ajv2020({ strict: false, allErrors: true });
+    addFormats(ajv);
+    const validate = ajv.compile(block);
+    expect(validate({ supported: true }), why('RFC 0109 §Conformance', 'a conforming advertisement MUST validate')).toBe(true);
+    expect(validate({}), why('RFC 0109 §Conformance', 'supported is required')).toBe(false);
+    expect(validate({ supported: true, unexpected: 1 }), why('RFC 0109 §Conformance', 'an extra key MUST be rejected (closed block)')).toBe(false);
+  });
+});

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');
+      }
+    }
+  });
+});