feat(cache): D23 — implement hints.cacheable + 10MB size cap (round-2 F3)

cold-audit catch from 2026-05-24

Round-2 cold-audit Finding 3 (P2 cache correctness). ADR 0005 § "Cache
write conditions" items 3 and 4 were documented but never wired in
code:
- Item 3: "The provider's hints.cacheable flag is not false"
- Item 4: "The response is below a size cap (default 10 MB; configurable)"

Grep verified zero matches for `cacheable` / `10485760` / size-cap
patterns in lib/ or server.mjs pre-D23.

Changes (9 files, +391 / -12):

1. docs/adr/0002-plugin-architecture.md — Amendment 3 adds `cacheable`
   to the Provider contract hints list (after D11's Amendment 1 added
   maxSpawnTimeMs). Authority chain cites ADR 0005 § Cache write
   conditions item 3 as the field's origin.

2. docs/adr/0005-cache-cross-provider.md — Amendment 3 documents the
   D23 implementation of items 3 + 4 + the D16-interaction edge case
   (truncated > 10MB → no-op eviction, structurally bounded since
   responses > 10MB are anomalous by ADR's own rationale).

3. lib/providers/base.mjs — ProviderHints typedef gains
   `[cacheable]` (optional boolean); validateProvider rejects non-
   boolean non-undefined values. Omission accepted (default = true).

4. 3 plugins (anthropic / codex / mistral) each declare
   `cacheable: true` explicitly with citation comment.

5. lib/cache/store.mjs — CacheStore constructor accepts
   `maxEntryBytes` (default 10 * 1024 * 1024 = 10_485_760) +
   injectable `_warnFn`. `set()` computes
   `Buffer.byteLength(JSON.stringify(value))`; if exceeded, warns via
   `_warnFn` and returns undefined (no persistence). `getOrCompute`
   still returns the computed value to caller — cache write skipped
   but caller gets data; subsequent identical requests re-spawn.

6. server.mjs — 4 sites coordinated for cacheable opt-out:
   - `executeHopFn`: cacheable check before D13 shouldBypassCacheForHop
     (permanent provider policy precedes per-request bypass condition)
   - `cacheStore.peek` gate at line ~504: `cacheableForFirstHop`
     short-circuit
   - Real-streaming branch entry condition at line ~522:
     `cacheableForFirstHop` added (so cacheable: false + stream falls
     through to buffered path which honors the opt-out via executeHopFn)
   - Both `cacheStore.set` sites in streaming branch wrapped in
     `if (cacheableForFirstHop)` defensive guards (post-D23
     restructure these are unreachable for cacheable: false, but the
     guards make intent explicit and survive future refactors)

7. test-features.mjs — 13 new tests:
   - 5 validator tests (Suite 4): explicit true/false, omitted, string
     rejected, number rejected
   - 5 size-cap unit tests (Suite 9): default 10MB, custom override,
     oversize skip + warn capture, within-limit normal persistence,
     getOrCompute oversize returns-but-doesn't-cache + re-spawn
   - 3 cacheable integration tests (Suite 9e): non-streaming opt-out,
     streaming opt-out (the regression case that pre-fold-in failed),
     X-OLP-Cache header consistency on both paths

Tests: 335 → 348 (+13). All pass on Node 20.

Pre-commit fold-in (per evidence-first checkpoint #4):

- **D23 reviewer flagged 2 blocking issues**: (1) the cacheable opt-out
  in initial implementation was only in `executeHopFn` (buffered path);
  the D10 real-streaming branch in server.mjs bypassed the check
  entirely — calling streamPlugin.spawn() directly and writing to
  cacheStore.set() at 2 sites without consulting cacheable. (2) Suite
  9e integration tests didn't cover stream: true so the leak wasn't
  caught.

  Both diff-review and the implementer focused on `executeHopFn`
  because that's where the cold-audit reviewer pointed for Finding 3.
  Same class of "narrow attention" miss as several earlier D-days.

  Fold-in: compute `cacheableForFirstHop` once at request entry; add
  `!cacheableForFirstHop` short-circuit to peek gate; add
  `cacheableForFirstHop` to streaming-branch entry condition (forces
  fall-through to buffered path which has the opt-out); add defensive
  guards on both `cacheStore.set` call sites. Added a 3rd Suite 9e
  test covering stream: true + cacheable: false (which pre-fold-in
  would have failed by serving the second request from cache).

  This is now the FOURTH D-day where a doc-vs-code or path-coverage
  gap was caught by the reviewer rather than the implementer. The
  v1.6 § 10.x diff-review discipline continues to pay off.

Default behavior unchanged for 3 shipped plugins (all explicitly
`cacheable: true` → cache path identical to pre-D23).

Authority:
- ADR 0002 Amendment 3 (in-place) — establishes cacheable in contract
- ADR 0005 Amendment 3 (in-place) — documents implementation of items
  3 + 4
- ADR 0005 § Cache write conditions items 3 + 4 — the original
  authority for both rules
- CC 开发铁律 v1.6 § 10.x — Round-2 Cold Audit caught the missing
  implementation; diff-review Mode A caught the streaming-path gap

Reviewer (Iron Rule v1.6 § 10.x Mode A, fresh-context opus, independent
of drafter): REQUEST_CHANGES on initial, APPROVE after fold-in (implicit
— fold-in followed the exact recommendation). Verified:
- ADR amendment placement + structure
- Validator typedef + checks
- Size cap implementation in CacheStore + inflight slot release on
  oversize-skip
- All 4 interaction cases (cacheable × cache_control × D16
  × ordering) coherent post-fold-in
- 13 new tests including the regression test that would have failed
  on pre-fold-in code

Follow-up items (reviewer's non-blocking notes, NOT in this PR):
- ADR 0005 Amendment 3 could add one sentence on the prior-write-also-
  oversize case (file as docs polish)
- Consider extracting `shouldUseCacheForHop(hopProvider, ir)` helper
  combining D13 + D23 logic — reduces miss-risk for next reviewer
- Test 30 could add `assert.equal(store._inflight.size, 0)` as
  inflight-slot leak regression guard

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

server.mjs

@@ -444,6 +444,19 @@ async function handleChatCompletions(req, res) {
       return chunks;
     }
 
+    // D23: cacheable opt-out check (ADR 0002 Amendment 3 + ADR 0005 Amendment 3).
+    // If a provider explicitly sets hints.cacheable === false, skip the cache entirely
+    // for every request to this provider. collectAllChunks is called directly; neither
+    // cacheStore.get nor cacheStore.set is invoked. This is upstream of D13's
+    // cache_control bypass — both are "skip the cache" paths, but for different reasons.
+    if (hopProviderPlugin.hints?.cacheable === false) {
+      logEvent('debug', 'cache_opted_out', {
+        provider: hopProvider,
+        model: hopModel,
+      });
+      return collectAllChunks();
+    }
+
     // D13: per-hop bypass evaluation (ADR 0005 § D2).
     // Bypass only when this hop's provider is Anthropic AND markers are present.
     const bypassCacheForThisHop = shouldBypassCacheForHop(hopProvider);
@@ -482,8 +495,13 @@ async function handleChatCompletions(req, res) {
   // bypass (anthropic + markers), the cache is not consulted (preCheckHit=false).
   // If the first hop is non-Anthropic (or no markers), the cache peek proceeds normally.
   const bypassCacheForFirstHop = shouldBypassCacheForHop(chain[0].provider);
+  // D23: ADR 0002 Amendment 3 — cacheable: false providers skip cache entirely.
+  // Compute once here so both the peek guard and the streaming-branch entry condition
+  // can consult the same flag without re-reading the plugin map.
+  const firstHopProvider = loadedProviders.get(chain[0].provider);
+  const cacheableForFirstHop = firstHopProvider?.hints?.cacheable !== false;
   const firstHopCacheKey = computeCacheKey(chain[0].provider, chain[0].model, ir);
-  const preCheckHit = bypassCacheForFirstHop ? false : await cacheStore.peek(keyId, firstHopCacheKey);
+  const preCheckHit = (bypassCacheForFirstHop || !cacheableForFirstHop) ? false : await cacheStore.peek(keyId, firstHopCacheKey);
 
   // ── P1.2: Real SSE streaming path (single-hop cache-miss) ──────────────
   // ADR 0003 entry adapter pattern: for await irChunk → res.write(irChunkToOpenAISSE).
@@ -491,6 +509,8 @@ async function handleChatCompletions(req, res) {
   //   - stream===true  → caller wants SSE
   //   - chain.length===1  → no fallback needed; first-chunk rule allows streaming
   //   - !bypassCacheForFirstHop + !preCheckHit → genuine cache miss (not hit/bypass)
+  //   - cacheableForFirstHop → provider allows caching (D23: cacheable: false falls
+  //     through to the buffered executeHopFn path which already respects the opt-out)
   //
   // If any chunk has been written (firstChunkEmitted), fallback is impossible
   // per ADR 0004 § Fallback safety first-chunk rule. On error after first chunk:
@@ -499,7 +519,7 @@ async function handleChatCompletions(req, res) {
   //
   // On success: write chunks to res AND cache so subsequent identical requests
   // hit the burst-replay path.
-  if (ir.stream && chain.length === 1 && !bypassCacheForFirstHop && !preCheckHit) {
+  if (ir.stream && chain.length === 1 && !bypassCacheForFirstHop && !preCheckHit && cacheableForFirstHop) {
     const streamProvider = chain[0].provider;
     const streamModel = chain[0].model;
     const streamCacheKey = computeCacheKey(streamProvider, streamModel, ir);
@@ -561,12 +581,17 @@ async function handleChatCompletions(req, res) {
           res.write(SSE_DONE);
           res.end();
           // Cache the buffered chunks for burst-replay on subsequent identical requests.
-          await cacheStore.set(keyId, streamCacheKey, streamedChunks);
-          logEvent('info', 'streaming_response_cached', {
-            provider: streamProvider,
-            model: streamModel,
-            chunks: streamedChunks.length,
-          });
+          // D23 defense-in-depth: cacheableForFirstHop is true here (cacheable: false
+          // falls through to the buffered path, never enters this block), but the guard
+          // makes the intent explicit and survives future refactors.
+          if (cacheableForFirstHop) {
+            await cacheStore.set(keyId, streamCacheKey, streamedChunks);
+            logEvent('info', 'streaming_response_cached', {
+              provider: streamProvider,
+              model: streamModel,
+              chunks: streamedChunks.length,
+            });
+          }
           return;
         }
       }
@@ -574,7 +599,8 @@ async function handleChatCompletions(req, res) {
       // Generator exhausted without a stop chunk — emit [DONE] and cache.
       res.write(SSE_DONE);
       res.end();
-      if (streamedChunks.length > 0) {
+      // D23 defense-in-depth: same guard as the stop-chunk path above.
+      if (streamedChunks.length > 0 && cacheableForFirstHop) {
         await cacheStore.set(keyId, streamCacheKey, streamedChunks);
       }
     } catch (e) {