cc-viewer 1.6.348 → 1.7.0

package/server/lib/v2/replay.js

@@ -0,0 +1,191 @@
+// Wire Format v2 — session-dir readers + MECHANICAL wire replay.
+//
+// Replay here is deliberately interpretation-free: conversation events are
+// applied exactly as the write side derived them from wire state
+// (snapshot → replace state; append → concat; ctl replace-tail → swap last;
+// ctl compact → no-op, the surrounding snapshot already carries the state).
+// This reproduces the EXACT wire messages of every request — byte-equal to
+// what v1's delta reconstruction yields for the same request — without any
+// reverse-anchor/session semantics (those belong to the S5 materializer,
+// which presents conversations; verify only needs wire truth).
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createHash } from 'node:crypto';
+import { messageFingerprint, normalizeMsgForEquality } from '../session-boundary.js';
+import { isSupportedWireFormat } from './layout.js';
+
+/** Parse a JSONL file tolerating a truncated tail line (spec §14). */
+export function readJsonlTolerant(path) {
+  if (!existsSync(path)) return [];
+  const out = [];
+  for (const line of readFileSync(path, 'utf-8').split('\n')) {
+    const t = line.trim();
+    if (!t) continue;
+    try { out.push(JSON.parse(t)); } catch { /* truncated tail — drop */ }
+  }
+  return out;
+}
+
+/** List session ids under LOG_DIR/<project>/sessions/ (or a staging sibling
+ *  when the offline converter passes `sessionsDirName`). */
+export function listSessionIds(projectDir, sessionsDirName = 'sessions') {
+  const root = join(projectDir, sessionsDirName);
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true }).filter(e => e.isDirectory()).map(e => e.name);
+}
+
+/**
+ * Read one session dir into a folded structure:
+ * { sessionId, meta, wireFormat, reqs: Map<seq, reqLine>,
+ *   dones: Map<seq, doneLine>, convEvents: Map<convKey, event[] (sorted by seq)> }
+ *
+ * Reader version gate (spec §14): the version is taken from meta.json and the
+ * journal sentinel (`ph:'meta'` first line). A session stamped with a version
+ * this build doesn't understand returns `unsupported: true` with EMPTY folds —
+ * callers must refuse it loudly instead of interpreting bytes they can't parse.
+ * A missing version (torn creation) is treated as the current one.
+ */
+export function readSession(projectDir, sessionId, sessionsDirName = 'sessions') {
+  const dir = join(projectDir, sessionsDirName, sessionId);
+  let meta = null;
+  try { meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf-8')); } catch { }
+  let wireFormat = meta && typeof meta.wireFormat === 'number' ? meta.wireFormat : null;
+  const unsupportedOf = (v) => ({
+    sessionId, dir, meta, wireFormat: v, unsupported: true,
+    reqs: new Map(), dones: new Map(), convEvents: new Map(),
+  });
+  if (!isSupportedWireFormat(wireFormat)) return unsupportedOf(wireFormat);
+  const reqs = new Map();
+  const dones = new Map();
+  for (const line of readJsonlTolerant(join(dir, 'journal.jsonl'))) {
+    if (line.ph === 'req') reqs.set(line.seq, line);
+    else if (line.ph === 'done' && !dones.has(line.seq)) dones.set(line.seq, line);
+    else if (line.ph === 'meta' && typeof line.wireFormat === 'number') {
+      // Journal sentinel wins over meta.json (per-file self-description).
+      wireFormat = line.wireFormat;
+      if (!isSupportedWireFormat(wireFormat)) return unsupportedOf(wireFormat);
+    }
+  }
+  const convEvents = new Map();
+  const convRoot = join(dir, 'conversations');
+  if (existsSync(convRoot)) {
+    for (const entry of readdirSync(convRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const events = [];
+      for (const f of readdirSync(join(convRoot, entry.name))) {
+        if (!/^e\d+\.jsonl$/.test(f)) continue;
+        events.push(...readJsonlTolerant(join(convRoot, entry.name, f)));
+      }
+      events.sort((a, b) => a.seq - b.seq);
+      convEvents.set(entry.name, events);
+    }
+  }
+  return { sessionId, dir, meta, wireFormat, reqs, dones, convEvents };
+}
+
+/** Digest of a messages array: sha256 over the per-message fingerprint list.
+ *  Shared formula between the v1 and v2 sides of verify. Messages are
+ *  normalized first (S4 decision 2026-07-14): the client's cache_control
+ *  breakpoint migration rewrites OLD messages (string → block array with
+ *  cache_control) — v1 delta cannot express that mutation, so without
+ *  normalization every real active day fails the soak gate on false
+ *  positives (plan S4 table, 2026-07-13 row). */
+export function messagesDigest(messages) {
+  const h = createHash('sha256');
+  for (const m of messages) h.update(messageFingerprint(normalizeMsgForEquality(m)) + '\n');
+  return h.digest('hex').slice(0, 16);
+}
+
+/** Same content-hash formula as BlobStore.put — lets verify compare v1 inline
+ *  tools/system against v2 blob refs WITHOUT reading blob files.
+ *  KEEP IN SYNC: server/lib/v2/blob-store.js `put` is the writing twin of this
+ *  formula; any change to hash/slice/serialization must land in both. */
+export function blobRefOf(value) {
+  if (value === undefined || value === null) return null;
+  return 'sha256-' + createHash('sha256').update(JSON.stringify(value)).digest('hex').slice(0, 16);
+}
+
+/**
+ * Mechanically replay one conversation's events, yielding the wire state
+ * digest after each event: Map<seq, {digest, len}>. Also returns integrity
+ * violations against the journal's msgTo counts (checked by the caller,
+ * which owns the journal).
+ */
+export function replayConversation(events) {
+  let state = [];
+  const bySeq = new Map();
+  for (const ev of events) {
+    if (ev.t === 'snapshot') {
+      state = Array.isArray(ev.msgs) ? ev.msgs : [];
+    } else if (ev.t === 'append') {
+      if (Array.isArray(ev.msgs) && ev.msgs.length > 0) state = state.concat(ev.msgs);
+    } else if (ev.t === 'ctl') {
+      if (ev.op === 'replace-tail' && ev.msg && state.length > 0) {
+        state = state.slice(0, -1).concat([ev.msg]);
+      }
+      // 'compact' is a marker for the materializer; wire state came via the
+      // snapshot event of the same request.
+    }
+    bySeq.set(ev.seq, { digest: messagesDigest(state), len: state.length });
+  }
+  return bySeq;
+}
+
+/**
+ * Build the per-request wire index of one session:
+ * Map<`${ts}|${url}`, Array<{seq, kind, conv, epoch, digest, len, toolsRef,
+ *                            sysRef, done, status, msgTo}>>
+ * — an ARRAY per key: `${ts}|${url}` is not unique in real logs (same-ms
+ * countTokens bursts), and collapsing twins loses their done lines/digests
+ * (real-data finding 2026-07-14). Also returns integrity violations
+ * (journal msgTo vs replayed length).
+ */
+export function indexSession(session) {
+  const replayed = new Map(); // convKey → Map<seq, {digest, len}>
+  for (const [convKey, events] of session.convEvents) replayed.set(convKey, replayConversation(events));
+
+  const index = new Map();
+  const integrity = [];
+  // Walk reqs in seq order; for reqs without a conv event (unchanged wire),
+  // carry the conv's latest replayed state at or before that seq.
+  const lastStateOf = new Map(); // convKey → {digest, len}
+  const seqs = [...session.reqs.keys()].sort((a, b) => a - b);
+  for (const seq of seqs) {
+    const req = session.reqs.get(seq);
+    const done = session.dones.get(seq) || null;
+    let digest = null;
+    let len = null;
+    if (req.conv) {
+      const conv = replayed.get(req.conv);
+      const hit = conv && conv.get(seq);
+      if (hit) {
+        lastStateOf.set(req.conv, hit);
+        digest = hit.digest; len = hit.len;
+      } else {
+        const carried = lastStateOf.get(req.conv);
+        if (carried) { digest = carried.digest; len = carried.len; }
+      }
+      if (typeof req.msgTo === 'number' && len != null && req.msgTo !== len) {
+        integrity.push({ sessionId: session.sessionId, seq, conv: req.conv, msgTo: req.msgTo, replayedLen: len });
+      }
+    }
+    const key = `${req.ts}|${req.url}`;
+    const rec = {
+      sessionId: session.sessionId,
+      seq,
+      kind: req.kind,
+      conv: req.conv || null,
+      epoch: req.epoch,
+      digest,
+      len,
+      toolsRef: (req.blobs && req.blobs.tools) || null,
+      sysRef: (req.blobs && req.blobs.sys) || null,
+      done: !!done,
+      status: done ? done.status : null,
+    };
+    const arr = index.get(key);
+    if (arr) arr.push(rec); else index.set(key, [rec]);
+  }
+  return { index, integrity };
+}

package/server/lib/v2/session-select.js

@@ -0,0 +1,222 @@
+// Cold-load fallback session selection (task B, 2026-07-15).
+//
+// On `ccv`/`ccv -c` startup the current session's dir does not exist until its
+// first API request resolves a sid, so `getLiveLogSource()` would return '' and
+// the [对话] panel loads empty. This picker supplies the session to cold-load:
+// the most-recent MAIN (non-teammate) session that actually has a main turn,
+// so the panel shows the last real conversation.
+//
+// CONTENT REQUIREMENT (2026-07-15 refresh-bug fix): a session can be the
+// writer's "current" session (its sid resolved) while having NO main turn yet —
+// e.g. `-c` startup, or a background sub / count_tokens request sets _currentSid
+// before the user sends anything. Cold-loading such an empty session renders a
+// blank panel (the symptom: fresh load shows data, a refresh once the empty
+// current session exists shows nothing, and it only fills after the user sends
+// a request). So selection requires at least one `kind:'main'` request — the
+// "activated" session — and both getLiveLogSource and the picker apply it.
+//
+// Deliberately lightweight — meta.json + a bounded journal HEAD read only. It
+// does NOT use listV2Sessions (dirSizeSync recursion + prompts head-reads +
+// full turn counting): this runs on every cold `/events` connection.
+
+import { existsSync, readFileSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { listSessionIds } from './replay.js';
+import { isSupportedWireFormat } from './layout.js';
+
+/**
+ * Find the on-disk dir NAME of an existing session for `sessionId` (a UUID), or
+ * null. Task C: dir names are `<ts>_<uuid>` (new) or `<uuid>` (legacy/staging),
+ * so the identity UUID is recovered by suffix. Used by the writer (restart /
+ * `-c` re-attach: must reuse the existing dir, not mint a second one) and by
+ * convert's dual-write skip. Match precedence: exact `=== sessionId` (legacy),
+ * then `endsWith('_'+sessionId)`; on >1 suffix match prefer meta.sessionId===id,
+ * else the newest meta.startTs (partial-migration / live-skip can leave both).
+ * @returns {string|null} the dir basename, or null if none exists
+ */
+export function resolveSessionDirName(projectDir, sessionId, sessionsDirName = 'sessions') {
+  if (!projectDir || !sessionId) return null;
+  const suffix = '_' + sessionId;
+  let bestSuffix = null; // { name, startTs, idMatch }
+  for (const name of listSessionIds(projectDir, sessionsDirName)) {
+    if (name === sessionId) return name; // exact legacy dir — unambiguous
+    if (!name.endsWith(suffix)) continue;
+    let meta = null;
+    try { meta = JSON.parse(readFileSync(join(projectDir, sessionsDirName, name, 'meta.json'), 'utf-8')); } catch { /* tolerate */ }
+    const idMatch = !!(meta && meta.sessionId === sessionId);
+    const startTs = (meta && meta.startTs) || '';
+    if (bestSuffix === null
+      || (idMatch && !bestSuffix.idMatch)
+      || (idMatch === bestSuffix.idMatch && startTs > bestSuffix.startTs)) {
+      bestSuffix = { name, startTs, idMatch };
+    }
+  }
+  return bestSuffix ? bestSuffix.name : null;
+}
+
+const MAIN_REQ_SCAN_BUDGET = 256 * 1024; // a session's first main req sits at the journal head
+// The first main turn's `done` can land far past the head: journal lines are
+// metadata-only (~0.5–2 KB each; bodies live in conversation/blob stores), but a
+// heavy multi-agent first turn interleaves many sub/heartbeat req+done lines
+// before the main done. 8 MB ≈ thousands of journal lines — far beyond any
+// realistic first turn — and the streaming scanner early-exits on the first hit,
+// so a session with a completed turn stops within its first few hundred lines.
+const COMPLETED_TURN_SCAN_BUDGET = 8 * 1024 * 1024;
+const SCAN_CHUNK = 64 * 1024;
+
+/**
+ * Stream journal.jsonl through `onLine(line)` (trimmed, non-empty lines only),
+ * reading fixed-size chunks so memory stays bounded regardless of file size.
+ * Stops as soon as `onLine` returns truthy (→ true) or `budget` bytes have been
+ * read (→ false). The final unterminated line (possibly torn mid-write) is
+ * delivered too — predicates JSON.parse and ignore what doesn't parse. Missing
+ * file / any read error → false (callers treat that as "not activated").
+ * @param {string} dir - absolute session dir
+ * @param {number} budget - max bytes to read before giving up
+ * @param {(line:string) => boolean} onLine
+ * @returns {boolean}
+ */
+function scanJournal(dir, budget, onLine) {
+  const journal = join(dir, 'journal.jsonl');
+  if (!existsSync(journal)) return false;
+  let fd;
+  try {
+    fd = openSync(journal, 'r');
+    const chunk = Buffer.alloc(Math.min(SCAN_CHUNK, budget));
+    const decoder = new StringDecoder('utf-8'); // multi-byte chars may straddle chunks
+    let read = 0;
+    let carry = ''; // unterminated tail of the previous chunk
+    while (read < budget) {
+      const n = readSync(fd, chunk, 0, Math.min(chunk.length, budget - read), read);
+      if (n <= 0) break;
+      read += n;
+      carry += decoder.write(n === chunk.length ? chunk : chunk.subarray(0, n));
+      let start = 0;
+      for (;;) {
+        const nl = carry.indexOf('\n', start);
+        if (nl === -1) break;
+        const line = carry.slice(start, nl).trim();
+        start = nl + 1;
+        if (line && onLine(line)) return true;
+      }
+      if (start > 0) carry = carry.slice(start);
+    }
+    const last = (carry + decoder.end()).trim();
+    return !!(last && onLine(last));
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) { try { closeSync(fd); } catch {} }
+  }
+}
+
+/**
+ * Does this session dir have at least one `kind:'main'` request on disk? A
+ * bounded head scan of journal.jsonl — the opening main request is at the top,
+ * so a session that has ANY main turn is detected within the budget. An empty /
+ * sub-only / not-yet-activated session returns false.
+ * @param {string} dir - absolute session dir
+ * @returns {boolean}
+ */
+export function sessionHasMainTurn(dir) {
+  return scanJournal(dir, MAIN_REQ_SCAN_BUDGET, (line) => {
+    // Cheap prefilter before JSON.parse: a main req line carries both.
+    if (!line.includes('"ph":"req"') || !line.includes('"kind":"main"')) return false;
+    try {
+      const o = JSON.parse(line);
+      return !!(o && o.ph === 'req' && o.kind === 'main');
+    } catch { return false; } // torn line — keep scanning
+  });
+}
+
+/**
+ * Does this session dir have at least one COMPLETED main turn — a `kind:'main'`
+ * request whose `done` line is also present? A streaming scan correlating
+ * main-req seqs with done seqs (either arrival order), bounded by
+ * COMPLETED_TURN_SCAN_BUDGET — wide enough that a heavy multi-agent first turn
+ * whose done lands megabytes past the head is still found. Stronger than
+ * `sessionHasMainTurn`: a session with only an in-flight first main request (req
+ * written, response still streaming) returns false, so cold-load keeps showing
+ * the previous conversation until the current one has renderable content.
+ * @param {string} dir - absolute session dir
+ * @returns {boolean}
+ */
+export function sessionHasCompletedMainTurn(dir) {
+  const mainSeqs = new Set(); // seqs of kind:'main' req lines seen so far
+  const doneSeqs = new Set(); // seqs of done lines seen so far
+  return scanJournal(dir, COMPLETED_TURN_SCAN_BUDGET, (line) => {
+    if (line.includes('"ph":"req"') && line.includes('"kind":"main"')) {
+      try {
+        const o = JSON.parse(line);
+        if (o && o.ph === 'req' && o.kind === 'main' && o.seq != null) {
+          if (doneSeqs.has(o.seq)) return true;
+          mainSeqs.add(o.seq);
+        }
+      } catch { /* torn line — keep scanning */ }
+    } else if (line.includes('"ph":"done"')) {
+      try {
+        const o = JSON.parse(line);
+        if (o && o.ph === 'done' && o.seq != null) {
+          if (mainSeqs.has(o.seq)) return true;
+          doneSeqs.add(o.seq);
+        }
+      } catch { /* torn line — keep scanning */ }
+    }
+    return false;
+  });
+}
+
+/**
+ * The newest readable, non-teammate session that HAS a main turn, as
+ * `{ dir, sessionId }`, or null. "Readable" mirrors listV2Sessions' gates (spec
+ * §14): journal.jsonl exists and the wireFormat is supported. Candidates are
+ * ordered by meta.startTs (desc) and the first with a main turn wins. Returns
+ * the identity UUID (meta.sessionId) alongside the dir so a `-c` continuation
+ * can adopt this session's folder while preserving its identity.
+ *
+ * `excludeDir` skips one absolute session dir entirely: getLiveLogSource passes
+ * its current in-flight session here, because this picker's weaker
+ * has-a-main-req gate would otherwise re-select exactly the dir the caller's
+ * completed-turn gate just rejected (it IS the newest once its first main req
+ * is written), nullifying the fallback.
+ * @param {string} projectDir - absolute LOG_DIR/<project>
+ * @param {{excludeDir?: string}} [opts]
+ * @returns {{dir:string, sessionId:string}|null}
+ */
+export function latestMainSession(projectDir, { excludeDir = '' } = {}) {
+  if (!projectDir) return null;
+  const candidates = []; // { dir, sessionId, startTs }
+  for (const name of listSessionIds(projectDir)) {
+    const dir = join(projectDir, 'sessions', name);
+    if (excludeDir && dir === excludeDir) continue;
+    if (!existsSync(join(dir, 'journal.jsonl'))) continue;
+    let meta = null;
+    try { meta = JSON.parse(readFileSync(join(dir, 'meta.json'), 'utf-8')); } catch { continue; }
+    if (!meta) continue;
+    if (meta.wireFormat != null && !isSupportedWireFormat(meta.wireFormat)) continue;
+    // Teammate/sub sessions carry a `leader` pointer; only a leader session
+    // folds in its siblings when rendered, so a teammate dir loaded directly
+    // renders wrong. Keep only main (leader-less) sessions.
+    if (meta.leader) continue;
+    candidates.push({ dir, sessionId: meta.sessionId || '', startTs: meta.startTs || '' });
+  }
+  // Newest first, then return the first that actually has a main turn — skipping
+  // a not-yet-activated newest session (the refresh-bug fix).
+  candidates.sort((a, b) => (a.startTs < b.startTs ? 1 : a.startTs > b.startTs ? -1 : 0));
+  for (const c of candidates) {
+    if (sessionHasMainTurn(c.dir)) return { dir: c.dir, sessionId: c.sessionId };
+  }
+  return null;
+}
+
+/**
+ * Absolute dir of the newest readable, non-teammate session that HAS a main
+ * turn, or '' if there is none. Thin wrapper over {@link latestMainSession}.
+ * @param {string} projectDir - absolute LOG_DIR/<project>
+ * @param {{excludeDir?: string}} [opts] - see {@link latestMainSession}
+ * @returns {string} absolute session dir, or ''
+ */
+export function latestMainSessionDir(projectDir, opts) {
+  return latestMainSession(projectDir, opts)?.dir || '';
+}

package/server/lib/v2/singleflight.js

@@ -0,0 +1,104 @@
+// wire-v2 S10b — in-flight coalescing + bounded TTL micro-cache for the
+// windowed v2 reads (docs/refactor/WIRE_FORMAT_V2.md §14.1).
+//
+// Concurrent windowed loads of the SAME session (multi-tab /events cold loads,
+// EventSource auto-reconnect storms, /api/local-log + IM popup on the live
+// session) used to run one full synthesis EACH — 2-3 concurrent 1.5GB
+// syntheses was the 2026-07-15 OOM trigger. Coalescing shares one run.
+//
+// Cache semantics (algorithm review F5b): callers pass `cached` per run.
+//   cached=true  — read-only historical surfaces (/api/local-log tail, IM
+//                  popup): may consume a ≤ttl-stale result. IM freshness is
+//                  backfilled by the im_log_update SSE stream.
+//   cached=false — the /events live-attach path: NEVER reads the ≤ttl cache,
+//                  and still populates the cache for later historical readers.
+//                  NOTE it does NOT guarantee a maximally-fresh window: it
+//                  still JOINS a currently-executing run for the same key, so
+//                  its result reflects the moment that run STARTED (staleness ≤
+//                  one in-flight run's duration). For /events this is bounded
+//                  because the live-attach path only uses the LEVEL-1 scan
+//                  flight (a light descriptor pass), not the level-2 window
+//                  flight; the client's next `since` reconnect heals any gap.
+//                  Refusing to join would reopen the reconnect-storm OOM.
+// Failed runs are never cached; the in-flight slot is always released.
+//
+// Bounded cache: a whole window object (entries: string[]) can be hundreds of
+// MB, so beyond the TTL sweep the cache is capped at MAX_CACHE_ENTRIES
+// (oldest-inserted evicted) — a burst of distinct keys (rapid `before`
+// pagination, many sessions) within one TTL must not re-accumulate the very
+// memory pressure S10 removes.
+const MAX_CACHE_ENTRIES = 8;
+
+export class SingleFlight {
+  /**
+   * @param {{ttlMs?: number, now?: () => number}} [opts] - ttlMs bounds the
+   *   micro-cache; now is clock injection for tests.
+   */
+  constructor(opts = {}) {
+    this._ttlMs = typeof opts.ttlMs === 'number' ? opts.ttlMs : 500;
+    this._now = opts.now || Date.now;
+    this._inflight = new Map(); // key → Promise
+    this._cache = new Map();    // key → {value, expiresAt}
+  }
+
+  /**
+   * Run `fn` under `key`, coalescing with any in-flight run of the same key.
+   * @param {string} key
+   * @param {() => Promise<any>|any} fn
+   * @param {{cached?: boolean}} [opts] - cached=false bypasses the cache READ
+   *   (live-attach safety) while still joining/populating.
+   * @returns {Promise<any>}
+   */
+  run(key, fn, opts = {}) {
+    const cached = opts.cached !== false;
+    this._sweep();
+    if (cached) {
+      const c = this._cache.get(key);
+      if (c && this._now() < c.expiresAt) return Promise.resolve(c.value);
+    }
+    const existing = this._inflight.get(key);
+    if (existing) return existing;
+    // Cache write + in-flight cleanup settle in the SAME continuation as the
+    // run, BEFORE the returned promise resolves — so a later caller never joins
+    // an already-settled run (which would defeat cached=false freshness) and
+    // never sees a populated cache without the slot cleared.
+    const p = (async () => {
+      // Defer fn to a microtask so this._inflight.set(key, p) below runs FIRST
+      // — otherwise a synchronous throw in fn would run the finally (delete)
+      // before the slot is even registered, stranding it.
+      try {
+        const value = await Promise.resolve().then(fn);
+        this._cache.set(key, { value, expiresAt: this._now() + this._ttlMs });
+        this._evict();
+        return value;
+      } finally {
+        this._inflight.delete(key); // errors are never cached; slot always released
+      }
+    })();
+    this._inflight.set(key, p);
+    return p;
+  }
+
+  /** Drop expired cache entries — values can be large (window objects), so
+   *  they must not outlive their TTL just because no one asked again. */
+  _sweep() {
+    const t = this._now();
+    for (const [key, e] of this._cache) {
+      if (t >= e.expiresAt) this._cache.delete(key);
+    }
+  }
+
+  /** Enforce the size cap: Map preserves insertion order, so the first keys are
+   *  the oldest — evict them until at/under MAX_CACHE_ENTRIES. */
+  _evict() {
+    while (this._cache.size > MAX_CACHE_ENTRIES) {
+      const oldest = this._cache.keys().next().value;
+      this._cache.delete(oldest);
+    }
+  }
+
+  /** Test hook: current cache/in-flight sizes. */
+  _statsForTest() {
+    return { cacheSize: this._cache.size, inflightSize: this._inflight.size };
+  }
+}