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>

lib/cache/store.mjs

@@ -58,12 +58,21 @@ export class CacheStore {
    * @param {object} [opts]
    * @param {number} [opts.maxEntriesPerKey=1000]   — evict oldest entries when exceeded
    * @param {number} [opts.maxAgeMs=86400000]        — default TTL: 24 hours
+   * @param {number} [opts.maxEntryBytes=10485760]   — max serialized size per entry (default 10 MB).
+   *   Entries whose JSON.stringify serialization exceeds this limit are not persisted.
+   *   ADR 0005 § "Cache write conditions" item 4 (D23). Cache is for hot-path repeat
+   *   requests, not bulk archive. Configurable so tests can exercise the cap cheaply.
    * @param {() => number} [opts._nowFn=Date.now]   — injectable for TTL testing
+   * @param {(msg: string, meta?: object) => void} [opts._warnFn] — injectable for warn testing
    */
   constructor(opts = {}) {
     this._maxEntriesPerKey = opts.maxEntriesPerKey ?? 1000;
     this._maxAgeMs = opts.maxAgeMs ?? 24 * 60 * 60 * 1000; // 24 hours
+    // ADR 0005 § "Cache write conditions" item 4 (D23): default 10 MB = 10 * 1024 * 1024 bytes.
+    this._maxEntryBytes = opts.maxEntryBytes ?? 10 * 1024 * 1024;
     this._nowFn = opts._nowFn ?? (() => Date.now());
+    // Injectable warn function for testing (defaults to console.warn).
+    this._warnFn = opts._warnFn ?? ((msg, meta) => console.warn(msg, meta ?? ''));
 
     // D1 per-key isolation: keyId → Map<cacheKey, CacheEntry>
     /** @type {Map<string, Map<string, CacheEntry>>} */
@@ -161,6 +170,11 @@ export class CacheStore {
   /**
    * Stores a value in the cache.
    *
+   * ADR 0005 § "Cache write conditions" item 4 (D23): if the serialized size of `value`
+   * exceeds `maxEntryBytes`, the entry is NOT persisted. A `cache_skip_oversize` warn
+   * event is logged. The caller still receives the value (this method returns undefined
+   * either way); only persistent caching is skipped.
+   *
    * @param {string} keyId
    * @param {string} cacheKey
    * @param {*} value
@@ -168,6 +182,18 @@ export class CacheStore {
    * @returns {Promise<void>}
    */
   async set(keyId, cacheKey, value, ttlMs) {
+    // ADR 0005 § "Cache write conditions" item 4 (D23): size cap check.
+    const byteLength = Buffer.byteLength(JSON.stringify(value));
+    if (byteLength > this._maxEntryBytes) {
+      this._warnFn('cache_skip_oversize', {
+        byteLength,
+        maxEntryBytes: this._maxEntryBytes,
+        keyId,
+        cacheKey,
+      });
+      return; // Do not persist; caller still receives the value from computeFn.
+    }
+
     const ns = this._getNamespace(keyId);
     const entry = {
       value,