@remodex/rmx 1.0.2

package/src/server/management/system-restart.ts

@@ -0,0 +1,433 @@
+/**
+ * Dashboard memory-card drain-and-restart (#563).
+ *
+ * Longer than POST /api/stop's short drain: waits up to 60s for active turns,
+ * then respawns. Never runs restoreNativeCodex / stripGrokConfig — this is a
+ * recycle to reclaim RSS, not a teardown.
+ *
+ * Respawn policy (matches real supervisor configs in src/service.ts):
+ * - Supervised child (`OCX_SERVICE=1` + viable service): exit(1) so
+ *   failure-only supervisors (systemd Restart=on-failure, WinSW onfailure,
+ *   Task Scheduler ERRORLEVEL loop) bring the proxy back.
+ * - Otherwise: detached `rmx start --port <live>` (bypasses ensure's
+ *   codexAutoStart gate), mark recycle so exit cleanup keeps injection, exit(0).
+ *   Installed-but-stale/missing service assets are NOT treated as supervised —
+ *   exit(1) would leave the proxy dead with `Service: installed, stale or missing
+ *   service assets` and a /healthz timeout.
+ * - If detached spawn fails (sync throw or pre-start `error`): exit(1) without
+ *   markRecycling — after drain the listen socket is already closed, so a latch
+ *   reset cannot recover serving. Clear inherited `OCX_SERVICE` so exit cleanup
+ *   can restore Codex/Grok fences when a stale service marker has no viable
+ *   supervisor. Log only a stable errno code — never the raw message
+ *   (paths in ENOENT often include the OS username).
+ */
+import { spawn } from "node:child_process";
+import {
+  beginShutdownDrain,
+  drainAndShutdown,
+  getActiveTurnCount,
+  getServerListenPort,
+  isDraining,
+  isShutdownDraining,
+  markRecyclingForExit,
+  stopServerListener,
+} from "../lifecycle";
+import { isServiceViable } from "../../service";
+import { readRuntimePort } from "../../config";
+import { withProcessRuntimeProvenance } from "../../lib/bun-runtime";
+import {
+  MEMORY_DRAIN_RESTART_MS,
+  REPLACEMENT_READY_TIMEOUT_MS,
+} from "../../lib/system-restart-contract";
+import { findLiveProxy } from "../proxy-liveness";
+
+export { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../../lib/system-restart-contract";
+export const DEADLINE_LISTENER_STOP_TIMEOUT_MS = 5_000;
+const REPLACEMENT_READY_POLL_MS = 150;
+
+export interface ReplacementReadinessIo {
+  findLive?: typeof findLiveProxy;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface SystemRestartIo {
+  drainAndShutdown?: typeof drainAndShutdown;
+  /** True when a background service can actually respawn this process after exit(1). */
+  isServiceViable?: () => boolean;
+  isSupervisedServiceChild?: () => boolean;
+  /** Ordinary start; deadline handoff may defer health until parent exit releases OS locks. */
+  spawnStart?: (port?: number, waitForHealthBeforeParentExit?: boolean) => void | Promise<void>;
+  /** Idempotent listener close; must settle before an ordinary start is spawned. */
+  stopListener?: () => void | Promise<void>;
+  markRecycling?: () => void;
+  exitProcess?: (code: number) => void;
+  schedule?: (fn: () => void | Promise<void>, ms: number) => void;
+  scheduleDeadline?: (fn: () => void, ms: number) => () => void;
+  isDraining?: () => boolean;
+  isShutdownDraining?: () => boolean;
+  beginShutdownDrain?: () => boolean;
+  setDraining?: (value: boolean) => void;
+  getActiveTurnCount?: () => number;
+  listenPort?: () => number | undefined;
+  now?: () => number;
+}
+
+let restartIo: SystemRestartIo = {};
+/** Prevents double-scheduling in the 200ms window before drainAndShutdown sets draining. */
+let restartAccepted = false;
+
+type RestartDrainOutcome = "completed" | "rejected" | "deadline";
+type BoundedSettlementOutcome = "completed" | "rejected" | "deadline";
+
+function waitForRestartDrain(
+  drainPromise: Promise<void>,
+  deadlineMs: number,
+  now: () => number,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<RestartDrainOutcome> {
+  const remainingMs = Math.max(0, deadlineMs - now());
+  if (remainingMs === 0) {
+    // Observe any late rejection even though orchestration is already terminal.
+    void drainPromise.catch(() => {});
+    return Promise.resolve("deadline");
+  }
+  return new Promise<RestartDrainOutcome>((resolve) => {
+    let settled = false;
+    let cancelDeadline: (() => void) | undefined;
+    const finish = (outcome: RestartDrainOutcome) => {
+      if (settled) return;
+      settled = true;
+      cancelDeadline?.();
+      resolve(outcome);
+    };
+    cancelDeadline = scheduleDeadline(() => finish("deadline"), remainingMs);
+    if (settled) cancelDeadline();
+    void drainPromise.then(
+      () => finish("completed"),
+      () => finish("rejected"),
+    );
+  });
+}
+
+function waitForBoundedSettlement(
+  promise: Promise<void>,
+  timeoutMs: number,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<BoundedSettlementOutcome> {
+  return new Promise<BoundedSettlementOutcome>((resolve) => {
+    let settled = false;
+    let cancelDeadline: (() => void) | undefined;
+    const finish = (outcome: BoundedSettlementOutcome) => {
+      if (settled) return;
+      settled = true;
+      cancelDeadline?.();
+      resolve(outcome);
+    };
+    cancelDeadline = scheduleDeadline(() => finish("deadline"), timeoutMs);
+    if (settled) cancelDeadline();
+    void promise.then(
+      () => finish("completed"),
+      () => finish("rejected"),
+    );
+  });
+}
+
+/** Test seam — reset between tests. */
+export function setSystemRestartIoForTests(io: SystemRestartIo = {}): void {
+  restartIo = io;
+  restartAccepted = false;
+}
+
+function resolveListenPort(): number | undefined {
+  const live = getServerListenPort();
+  if (live) return live;
+  const runtime = readRuntimePort(process.pid);
+  if (runtime && runtime.port > 0) return runtime.port;
+  return undefined;
+}
+
+function isSupervisedServiceChild(io: SystemRestartIo = {}): boolean {
+  if (process.env.OCX_SERVICE !== "1") return false;
+  // Presence is not enough: stale/missing service assets report installed but will not
+  // respawn after exit(1). Dashboard status/recovery must fall through to detached start.
+  return (io.isServiceViable ?? isServiceViable)();
+}
+
+/** Stable, path-free spawn failure label for logs (never interpolate err.message). */
+function spawnFailureCode(err: unknown): string {
+  if (err && typeof err === "object" && "code" in err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (typeof code === "string" && code.length > 0 && code.length <= 64) return code;
+  }
+  return "spawn_failed";
+}
+
+function handoffError(code: string): NodeJS.ErrnoException {
+  const error = new Error(code) as NodeJS.ErrnoException;
+  error.code = code;
+  return error;
+}
+
+export async function waitForReplacementReady(
+  expectedPid: number | undefined,
+  parentPid: number,
+  expectedPort: number | undefined,
+  io: ReplacementReadinessIo = {},
+): Promise<boolean> {
+  const findLive = io.findLive ?? findLiveProxy;
+  const now = io.now ?? Date.now;
+  const sleep = io.sleep ?? Bun.sleep;
+  const deadline = now() + REPLACEMENT_READY_TIMEOUT_MS;
+  while (now() < deadline) {
+    try {
+      const live = await findLive({
+        deadlineAt: deadline,
+        nowFn: now,
+        sleepFn: sleep,
+      });
+      // A probe that began within budget can still return after it. Never accept
+      // delayed health as proof once the shared absolute handoff budget expired.
+      if (now() >= deadline) return false;
+      if (
+        live
+        && live.pid !== null
+        && live.pid !== parentPid
+        && (expectedPid === undefined || live.pid === expectedPid)
+        && (expectedPort === undefined || live.port === expectedPort)
+      ) {
+        return true;
+      }
+    } catch {
+      // A not-yet-bound replacement is indistinguishable from a transient
+      // liveness failure here; keep polling inside the one bounded window.
+    }
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) break;
+    await sleep(Math.min(REPLACEMENT_READY_POLL_MS, remainingMs));
+  }
+  return false;
+}
+
+function spawnDetachedStart(
+  port?: number,
+  waitForHealthBeforeParentExit = true,
+): Promise<void> {
+  const args = [process.argv[1], "start"];
+  const expectedPort = typeof port === "number" && Number.isFinite(port) && port > 0 && port <= 65535
+    ? Math.trunc(port)
+    : undefined;
+  if (expectedPort !== undefined) {
+    args.push("--port", String(expectedPort));
+  }
+  return new Promise<void>((resolve, reject) => {
+    let child: ReturnType<typeof spawn>;
+    try {
+      const env: NodeJS.ProcessEnv = { ...process.env };
+      delete env.OCX_SERVICE;
+      child = spawn(process.execPath, args, {
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+        env: withProcessRuntimeProvenance(env),
+      });
+    } catch (err) {
+      reject(err);
+      return;
+    }
+    let settled = false;
+    const cleanup = () => {
+      child.off("error", onError);
+      child.off("exit", onExit);
+      child.off("spawn", onSpawn);
+    };
+    const finish = (error?: unknown) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (error !== undefined) {
+        if (child.exitCode === null && child.signalCode === null) {
+          try { child.kill(); } catch { /* best-effort failed-start cleanup */ }
+        }
+        try { child.unref(); } catch { /* best-effort */ }
+        reject(error);
+        return;
+      }
+      child.unref();
+      resolve();
+    };
+    const onError = (err: Error) => { finish(err); };
+    const onExit = () => { finish(handoffError("child_exit")); };
+    const onSpawn = () => {
+      if (!waitForHealthBeforeParentExit) {
+        // A deadline may have been caused by native-main ownership cleanup.
+        // Let the ordinary child survive parent exit, which releases those OS locks.
+        finish();
+        return;
+      }
+      void waitForReplacementReady(child.pid, process.pid, expectedPort).then(
+        ready => {
+          if (!ready) {
+            console.warn(
+              "Drain-and-restart replacement is still alive after the readiness window; allowing it to continue after parent exit",
+            );
+          }
+          // Never kill a live ordinary start at its valid reclaim boundary. Parent
+          // exit is the final resource release the child may still be waiting for.
+          finish();
+        },
+        err => finish(err),
+      );
+    };
+    child.once("error", onError);
+    child.once("exit", onExit);
+    child.once("spawn", onSpawn);
+  });
+}
+
+async function completeDeferredParentExitHandoff(
+  io: SystemRestartIo,
+  exitProcess: (code: number) => void,
+  port: number | undefined,
+  phase: "deadline" | "listener-stop fallback",
+): Promise<void> {
+  try {
+    await (io.spawnStart ?? spawnDetachedStart)(port, false);
+  } catch (err) {
+    console.warn(
+      `Drain-and-restart ${phase} spawn failed (${spawnFailureCode(err)}); exiting without replacement`,
+    );
+    delete process.env.OCX_SERVICE;
+    exitProcess(1);
+    return;
+  }
+  (io.markRecycling ?? markRecyclingForExit)();
+  exitProcess(0);
+}
+
+async function completeDeadlineRestartHandoff(
+  io: SystemRestartIo,
+  exitProcess: (code: number) => void,
+  port: number | undefined,
+  scheduleDeadline: NonNullable<SystemRestartIo["scheduleDeadline"]>,
+): Promise<void> {
+  const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
+  if (supervised) {
+    // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
+    exitProcess(1);
+    return;
+  }
+
+  const stopPromise = Promise.resolve().then(
+    () => (io.stopListener ?? (() => stopServerListener()))(),
+  );
+  const stopOutcome = await waitForBoundedSettlement(
+    stopPromise,
+    DEADLINE_LISTENER_STOP_TIMEOUT_MS,
+    scheduleDeadline,
+  );
+  if (stopOutcome === "rejected") {
+    console.warn("Drain-and-restart deadline listener stop failed; continuing parent-exit handoff");
+  } else if (stopOutcome === "deadline") {
+    console.warn("Drain-and-restart deadline listener stop timed out; continuing parent-exit handoff");
+  }
+  // The ordinary child must survive parent exit: a failed/pending socket close
+  // or overdue cleanup is completed by process teardown, without a hidden mode.
+  await completeDeferredParentExitHandoff(io, exitProcess, port, "deadline");
+}
+
+/**
+ * Accept a drain-and-restart request. Returns immediately; the drain +
+ * respawn runs on a short timer so the HTTP response can flush first.
+ * Idempotent while already draining: returns the accepted shape again.
+ */
+export function acceptSystemRestart(io: SystemRestartIo = restartIo): {
+  accepted: true;
+  alreadyDraining: boolean;
+  activeTurnCount: number;
+  drainTimeoutMs: number;
+} {
+  const shutdownActive = io.isShutdownDraining
+    ?? io.isDraining
+    ?? isShutdownDraining;
+  const alreadyDraining = restartAccepted || shutdownActive();
+  const activeTurnCount = (io.getActiveTurnCount ?? getActiveTurnCount)();
+  const schedule = io.schedule ?? ((fn, ms) => { setTimeout(() => { void fn(); }, ms); });
+
+  if (!alreadyDraining) {
+    restartAccepted = true;
+    const now = io.now ?? Date.now;
+    const restartDeadlineMs = now() + MEMORY_DRAIN_RESTART_MS;
+    // Reject new data-plane traffic immediately (503), before the 200ms response-flush delay.
+    if (io.beginShutdownDrain) io.beginShutdownDrain();
+    else if (io.setDraining) io.setDraining(true);
+    else beginShutdownDrain();
+    schedule(async () => {
+      // Preserve the live binding before drainAndShutdown (or its deadline race)
+      // closes the listener and makes both the server ref and runtime metadata stale.
+      const restartPort = (io.listenPort ?? resolveListenPort)();
+      const drain = io.drainAndShutdown ?? drainAndShutdown;
+      const remainingMs = Math.max(0, restartDeadlineMs - now());
+      const drainPromise = Promise.resolve().then(() => drain(undefined, remainingMs));
+      const scheduleDeadline = io.scheduleDeadline ?? ((fn, ms) => {
+        const timer = setTimeout(fn, ms);
+        return () => clearTimeout(timer);
+      });
+      const drainOutcome = await waitForRestartDrain(drainPromise, restartDeadlineMs, now, scheduleDeadline);
+      const exitProcess = io.exitProcess ?? ((code: number) => { process.exit(code); });
+      if (drainOutcome === "deadline") {
+        console.warn("Drain-and-restart deadline expired; forcing terminal restart handoff");
+        await completeDeadlineRestartHandoff(io, exitProcess, restartPort, scheduleDeadline);
+        return;
+      }
+      if (drainOutcome === "rejected") {
+        // drainAndShutdown stops the listener in finally. Even if ancillary cleanup
+        // rejects, an accepted restart must still reach replacement or terminal exit.
+        console.warn("Drain-and-restart cleanup failed; continuing terminal restart handoff");
+      }
+      const supervised = (io.isSupervisedServiceChild ?? (() => isSupervisedServiceChild(io)))();
+      if (supervised) {
+        // Failure-only supervisors ignore exit(0); intentional non-zero triggers respawn.
+        (io.exitProcess ?? ((code: number) => { process.exit(code); }))(1);
+        return;
+      }
+      try {
+        await (io.stopListener ?? (() => stopServerListener()))();
+      } catch {
+        console.warn("Drain-and-restart listener stop failed; continuing parent-exit handoff");
+        await completeDeferredParentExitHandoff(
+          io,
+          exitProcess,
+          restartPort,
+          "listener-stop fallback",
+        );
+        return;
+      }
+      try {
+        // A rejected drain has uncertain cleanup ownership, so it uses the same
+        // parent-exit handoff as a deadline. Only a fully completed drain waits
+        // for replacement health in the old process.
+        await (io.spawnStart ?? spawnDetachedStart)(restartPort, drainOutcome === "completed");
+      } catch (err) {
+        console.warn(
+          `⚠️  Drain-and-restart spawn failed (${spawnFailureCode(err)}); exiting without replacement`,
+        );
+        // Listen socket is already stopped; do not markRecycling — no child to inherit fences.
+        // No replacement inherited the routing. Clear a stale service marker so
+        // this unsupervised parent restores clients after the failed handoff.
+        delete process.env.OCX_SERVICE;
+        exitProcess(1);
+        return;
+      }
+      (io.markRecycling ?? markRecyclingForExit)();
+      exitProcess(0);
+    }, 200);
+  }
+
+  return {
+    accepted: true,
+    alreadyDraining,
+    activeTurnCount,
+    drainTimeoutMs: MEMORY_DRAIN_RESTART_MS,
+  };
+}

package/src/server/management/system-routes.ts

@@ -0,0 +1,141 @@
+/**
+ * /api/system/* — service-process runtime/memory introspection (#314 WP3)
+ * and the memory-card drain-and-restart action (#563).
+ *
+ * Rides the standard management gate: every /api/* request already passed
+ * the independent management-auth gate + the origin check before dispatch, so these
+ * routes add no auth of their own. NEVER expose this data on the
+ * unauthenticated /healthz surface.
+ *
+ * The payload is scalar-only (numbers, enum strings, booleans): no paths, no
+ * tokens, no account identifiers. `external` and `arrayBuffers` keep Windows
+ * diagnostics honest when RSS/working-set counters under-report committed
+ * retention. `jscHeap` (bun:jsc heapStats) is useful context, but on Bun 1.3.14
+ * it is not a standalone leak discriminator. `responseState` attributes growth
+ * further: it is the proxy's previous_response_id continuation store, so a
+ * growing responseState.totalBytes under rising observed memory points at
+ * conversation retention rather than the runtime allocator. Spill counts,
+ * payload-byte totals, tombstones, and failure counters remain finite scalars;
+ * response ids, filenames, digests, paths, and payload content never leave the owner.
+ *
+ * `activeTurnCount` / `isDraining` are scalar lifecycle counters for the
+ * dashboard drain-and-restart confirm UX — never request bodies or IDs.
+ */
+import { selectEagerPath } from "../../lib/bun-stream-caps";
+import { reportedBunRuntimeSource } from "../../lib/bun-runtime";
+import { getActiveTurnCount, isDraining } from "../lifecycle";
+import { getActiveMemoryWatchdog, observedMemoryCounter } from "../memory-watchdog";
+import { responseStateMetrics } from "../../responses/state";
+import { appOwnedBytesSnapshot } from "../../lib/app-owned-memory";
+import {
+  SYSTEM_RESTART_EXPECTED_PID_HEADER,
+  parseExpectedSystemRestartPid,
+} from "../../lib/system-restart-contract";
+import { jsonResponse } from "../auth-cors";
+import { getInspectionCounters } from "../relay";
+import type { ManagementContext } from "./context";
+import { acceptSystemRestart } from "./system-restart";
+
+const ENDPOINT_SAMPLE_LIMIT = 60;
+
+export async function handleSystemRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config } = ctx;
+  if (url.pathname === "/api/system/memory" && req.method === "GET") {
+    const usage = process.memoryUsage();
+    let jscHeap: { heapSize: number; heapCapacity: number; objectCount: number } | null = null;
+    try {
+      const { heapStats } = await import("bun:jsc");
+      const stats = heapStats();
+      jscHeap = {
+        heapSize: stats.heapSize,
+        heapCapacity: stats.heapCapacity,
+        objectCount: stats.objectCount,
+      };
+    } catch {
+      /* non-Bun tooling or unavailable introspection — omit the discriminator */
+    }
+	    const watchdogInstance = getActiveMemoryWatchdog();
+	    const observed = observedMemoryCounter({
+	      rss: usage.rss,
+	      external: usage.external,
+	      arrayBuffers: usage.arrayBuffers,
+	    });
+    const watchdog = watchdogInstance
+      ? (() => {
+        const snap = watchdogInstance.snapshot();
+	        return {
+	          warnThresholdBytes: snap.warnThresholdBytes,
+	          lastWarnAt: snap.lastWarnAt,
+	          observedBytes: snap.observedBytes,
+	          observedMetric: snap.observedMetric,
+	          samples: snap.samples.slice(-ENDPOINT_SAMPLE_LIMIT),
+	        };
+      })()
+      : null;
+    const streamMode = config.streamMode ?? "auto";
+    /**
+     * No request-specific rewrite context exists on this route, so report the
+     * effective no-client-rewrite baseline. Individual rewrite requests still
+     * stay on tee even when this baseline says eager.
+     */
+    const eagerRelay = selectEagerPath(process.platform, false, streamMode);
+    return jsonResponse({
+      pid: process.pid,
+      bunVersion: Bun.version,
+      bunRevision: Bun.revision,
+      // Recorded at launch, not resolved now: absent means "this service predates the
+      // marker", which callers must report as unknown rather than guess.
+      bunRuntimeSource: reportedBunRuntimeSource(),
+      platform: process.platform,
+      uptimeSeconds: process.uptime(),
+      rss: usage.rss,
+      heapUsed: usage.heapUsed,
+	      heapTotal: usage.heapTotal,
+	      external: usage.external,
+	      arrayBuffers: usage.arrayBuffers,
+	      observedBytes: observed.observedBytes,
+	      observedMetric: observed.observedMetric,
+	      jscHeap,
+      responseState: responseStateMetrics(),
+      appOwnedBytes: appOwnedBytesSnapshot(),
+      inspectionCounters: getInspectionCounters(),
+      streamMode,
+      eagerRelay,
+      watchdog,
+      activeTurnCount: getActiveTurnCount(),
+      isDraining: isDraining(),
+    });
+  }
+
+  if (url.pathname === "/api/system/restart" && req.method === "POST") {
+    const expectedPid = parseExpectedSystemRestartPid(
+      req.headers.get(SYSTEM_RESTART_EXPECTED_PID_HEADER),
+    );
+    if (expectedPid.kind === "invalid") {
+      return jsonResponse({
+        success: false,
+        error: "Invalid restart target identity.",
+      }, 400, req, config);
+    }
+    if (expectedPid.kind === "present" && expectedPid.pid !== process.pid) {
+      return jsonResponse({
+        success: false,
+        error: "Restart target identity changed.",
+      }, 409, req, config);
+    }
+
+    // Longer informed drain than /api/stop; does not tear down Codex/Grok injection.
+    const result = acceptSystemRestart();
+    return jsonResponse({
+      success: true,
+      message: result.alreadyDraining
+        ? "Drain already in progress."
+        : "Draining in-flight requests, then restarting.",
+      activeTurnCount: result.activeTurnCount,
+      drainTimeoutMs: result.drainTimeoutMs,
+      alreadyDraining: result.alreadyDraining,
+    }, 202, req, config);
+  }
+
+  return null;
+}

package/src/server/management/usage-summary-cache.ts

@@ -0,0 +1,86 @@
+import { enforceAppOwnedMemoryBudget, type RetainedStoreSnapshot } from "../../lib/app-owned-memory";
+import type { UsageSummary } from "../../usage/summary";
+
+export type CachedUsageSummary = UsageSummary & {
+  historyTruncated: boolean;
+  truncatedPrefixBytes: number;
+  entriesTruncated: boolean;
+  entriesDropped: number;
+};
+
+interface UsageSummaryCacheEntry {
+  revisionKey: string;
+  expiresAt: number;
+  summary: CachedUsageSummary;
+  revisionReadAt: number;
+  sizeBytes: number;
+}
+
+const usageSummaryCache = new Map<string, UsageSummaryCacheEntry>();
+let usageSummaryCacheBytes = 0;
+let oldestUsageSummaryKey: string | undefined;
+let oldestUsageSummaryAt: number | null = null;
+
+function recomputeOldestUsageSummary(): void {
+  oldestUsageSummaryKey = undefined;
+  oldestUsageSummaryAt = null;
+  for (const [key, entry] of usageSummaryCache) {
+    const readAt = entry.revisionReadAt;
+    if (oldestUsageSummaryAt !== null && readAt >= oldestUsageSummaryAt) continue;
+    oldestUsageSummaryKey = key;
+    oldestUsageSummaryAt = readAt;
+  }
+}
+
+function deleteUsageSummaryCacheEntry(key: string): number {
+  const entry = usageSummaryCache.get(key);
+  if (!entry) return 0;
+  usageSummaryCache.delete(key);
+  usageSummaryCacheBytes = Math.max(0, usageSummaryCacheBytes - entry.sizeBytes);
+  if (oldestUsageSummaryKey === key) recomputeOldestUsageSummary();
+  return entry.sizeBytes;
+}
+
+export function getUsageSummaryCacheEntry(key: string): UsageSummaryCacheEntry | undefined {
+  return usageSummaryCache.get(key);
+}
+
+export function discardUsageSummaryCacheEntry(key: string): number {
+  return deleteUsageSummaryCacheEntry(key);
+}
+
+export function setUsageSummaryCacheEntry(
+  key: string,
+  entry: Omit<UsageSummaryCacheEntry, "sizeBytes">,
+): void {
+  deleteUsageSummaryCacheEntry(key);
+  const sizeBytes = Buffer.byteLength(JSON.stringify({ key, ...entry }), "utf8");
+  usageSummaryCache.set(key, { ...entry, sizeBytes });
+  usageSummaryCacheBytes += sizeBytes;
+  if (oldestUsageSummaryAt === null || entry.revisionReadAt < oldestUsageSummaryAt) {
+    oldestUsageSummaryKey = key;
+    oldestUsageSummaryAt = entry.revisionReadAt;
+  }
+  enforceAppOwnedMemoryBudget();
+}
+
+export function usageSummaryRetainedStoreSnapshot(): RetainedStoreSnapshot {
+  return {
+    count: usageSummaryCache.size,
+    bytes: usageSummaryCacheBytes,
+    evictableBytes: usageSummaryCacheBytes,
+    pinnedBytes: 0,
+    oldestAt: oldestUsageSummaryAt,
+  };
+}
+
+export function evictOldestUsageSummaryForBudget(): number {
+  return oldestUsageSummaryKey === undefined ? 0 : deleteUsageSummaryCacheEntry(oldestUsageSummaryKey);
+}
+
+export function resetUsageSummaryCacheForTests(): void {
+  usageSummaryCache.clear();
+  usageSummaryCacheBytes = 0;
+  oldestUsageSummaryKey = undefined;
+  oldestUsageSummaryAt = null;
+}