akanjs 3.0.0-alpha.0 → 3.0.0-alpha.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-alpha.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/SSR_MEMORY_DIAGNOSIS.md

@@ -23,14 +23,31 @@ Read snapshots from:
 curl http://localhost:8080/_akan/app/metrics
 ```
 
+A replica and its RSC worker are separate processes and are reported separately. **`rssBytes` is the
+replica's own; the worker's is `rscWorkerRssBytes`.** Sum them for what the pod pays.
+
 Key fields:
 
-- `rssBytes`, `heapUsedBytes`, `jscHeapSizeBytes`: distinguish RSS-only native retention from JS heap retention.
+- `rssBytes`, `heapUsedBytes`, `jscHeapSizeBytes`: the replica. Distinguish RSS-only native retention from JS
+  heap retention.
+- `rscWorkerRssBytes`, `rscWorkerHeapUsedBytes`, `rscWorkerJscHeapSizeBytes`, `rscWorkerJscExtraMemorySizeBytes`:
+  the same for the worker. `jscExtra` is off-heap, mostly typed-array backing stores.
 - `rscRenderCount`, `rscInFlightRenderCount`: detect request lifecycle leaks.
 - `rscLoadedRouteModuleCount`, `rscRouteModuleCacheHits`, `rscRouteModuleCacheMisses`: detect route module warm-up.
-- `ssrChunkRegistrySize`, `ssrChunkLoadCount`: detect full-document SSR client chunk retention.
+- `ssrChunkRegistrySize`, `ssrChunkLoadCount`: full-document SSR client chunk loading. **`…RegistrySize` counts
+  keys, not bytes** — evicting does not unload the module, so it can never fall on its own.
+- `httpHtmlCacheEntries` / `httpHtmlCacheBytes`, `rscResultCacheEntries` / `rscResultCacheBytes`,
+  `rscPatchResultCacheEntries` / `rscPatchResultCacheBytes`: what each cache actually holds. Entry count alone
+  says nothing when entries span three orders of magnitude.
 - `httpFullSsrCount`, `httpRscNavigationCount`, `httpStaticAssetCount`, `httpImageCount`: separate request kinds.
 
+Two things measured on `apps/akan` that shape how to read all of the above:
+
+- **Growth converges; it is not a leak.** Ten passes over the same routes plateau by roughly the sixth, with a
+  flat JS heap throughout. Three passes is not enough to tell a plateau from a ratchet.
+- **Freeing JS objects does not lower RSS.** Emptying both result caches returns their bytes to the heap and
+  leaves RSS unchanged. Only not allocating, or restarting the process, reduces what the pod pays.
+
 ## Scenarios
 
 ### Same Route Repeated

package/server/cachePolicy.ts

@@ -234,20 +234,62 @@ export function shouldInvalidateRouteCacheEntry(
   return false;
 }
 
-export class LruTtlCache<T> {
-  readonly #entries = new Map<string, { value: T; expiresAt: number }>();
+export interface LruTtlCacheOptions<T> {
+  /**
+   * Measures one entry's payload. Entry count alone says nothing about a cache whose entries span
+   * three orders of magnitude, and a byte ceiling needs a running total to enforce. The default
+   * reports 0 rather than guessing, so `byteSize` stays honest about not knowing.
+   */
+  sizeOf?: (value: T) => number;
+  /** Total payload ceiling. 0 leaves the cache bounded only by `maxEntries`. */
+  maxBytes?: number;
+  /** An entry over this is not stored at all, rather than evicting everything else to fit it. */
+  maxEntryBytes?: number;
+  /**
+   * Cadence of the idle sweep. Without one a filled cache never shrinks: an entry is dropped only
+   * when its own key is fetched after expiry or when a write evicts it, so a pod that stops
+   * serving holds its peak forever — measured at 100 entries / 21.4 MiB still resident 310s after
+   * the last request, with a 30s TTL. 0 disables it.
+   */
+  sweepIntervalMs?: number;
+}
 
-  constructor(readonly maxEntries = 100) {}
+export class LruTtlCache<T> {
+  readonly #entries = new Map<string, { value: T; expiresAt: number; byteLength: number }>();
+  #byteLength = 0;
+  #sweepTimer: ReturnType<typeof setInterval> | null = null;
+  readonly #sizeOf: (value: T) => number;
+  readonly #maxBytes: number;
+  readonly #maxEntryBytes: number;
+
+  constructor(
+    readonly maxEntries = 100,
+    options: LruTtlCacheOptions<T> = {},
+  ) {
+    this.#sizeOf = options.sizeOf ?? (() => 0);
+    this.#maxBytes = options.maxBytes ?? 0;
+    this.#maxEntryBytes = options.maxEntryBytes ?? 0;
+    const sweepIntervalMs = options.sweepIntervalMs ?? 0;
+    if (sweepIntervalMs > 0) {
+      this.#sweepTimer = setInterval(() => this.sweepExpired(), sweepIntervalMs);
+      
+      (this.#sweepTimer as { unref?: () => void }).unref?.();
+    }
+  }
 
   get size(): number {
     return this.#entries.size;
   }
 
+  get byteSize(): number {
+    return this.#byteLength;
+  }
+
   get(key: string): T | null {
     const entry = this.#entries.get(key);
     if (!entry) return null;
     if (entry.expiresAt <= Date.now()) {
-      this.#entries.delete(key);
+      this.#remove(key);
       return null;
     }
     this.#entries.delete(key);
@@ -255,26 +297,56 @@ export class LruTtlCache<T> {
     return entry.value;
   }
 
-  set(key: string, value: T, ttlSeconds: number): void {
-    this.#entries.delete(key);
+  /** Returns whether the entry was stored; a payload over `maxEntryBytes` is rejected. */
+  set(key: string, value: T, ttlSeconds: number): boolean {
+    this.#remove(key);
+    const byteLength = LruTtlCache.#measure(this.#sizeOf, value);
+    if (this.#maxEntryBytes > 0 && byteLength > this.#maxEntryBytes) return false;
+    this.sweepExpired();
     const maxEntries = this.maxEntries > 0 ? this.maxEntries : 100;
     while (this.#entries.size >= maxEntries) {
-      const oldest = this.#entries.keys().next().value;
-      if (!oldest) break;
-      this.#entries.delete(oldest);
+      if (!this.#removeOldest()) break;
+    }
+    while (this.#maxBytes > 0 && this.#entries.size > 0 && this.#byteLength + byteLength > this.#maxBytes) {
+      if (!this.#removeOldest()) break;
     }
-    this.#entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000 });
+    this.#entries.set(key, { value, expiresAt: Date.now() + ttlSeconds * 1000, byteLength });
+    this.#byteLength += byteLength;
+    return true;
+  }
+
+  /**
+   * Drops every expired entry. Deliberately a full scan rather than a walk from the oldest that
+   * stops at the first live entry: insertion order is *LRU* order because `get` reinserts, and TTLs
+   * differ per entry, so expiry is not monotonic in map order and an early break would leave
+   * expired entries behind. The map is bounded by `maxEntries`, so the scan is cheap.
+   */
+  sweepExpired(now = Date.now()): number {
+    let removed = 0;
+    for (const [key, entry] of this.#entries) {
+      if (entry.expiresAt > now) continue;
+      this.#remove(key);
+      removed += 1;
+    }
+    return removed;
+  }
+
+  /** Stops the idle sweep. The cache stays usable; only the timer goes away. */
+  dispose(): void {
+    if (!this.#sweepTimer) return;
+    clearInterval(this.#sweepTimer);
+    this.#sweepTimer = null;
   }
 
   delete(key: string): boolean {
-    return this.#entries.delete(key);
+    return this.#remove(key);
   }
 
   invalidate(predicate: (key: string, value: T) => boolean): number {
     let count = 0;
     for (const [key, entry] of this.#entries) {
       if (!predicate(key, entry.value)) continue;
-      this.#entries.delete(key);
+      this.#remove(key);
       count += 1;
     }
     return count;
@@ -282,5 +354,35 @@ export class LruTtlCache<T> {
 
   clear(): void {
     this.#entries.clear();
+    this.#byteLength = 0;
+  }
+
+  static parseByteCeiling(value: string | undefined | null, fallback = 0): number {
+    const parsed = Number.parseInt(value ?? "", 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+  }
+
+  #remove(key: string): boolean {
+    const entry = this.#entries.get(key);
+    if (!entry) return false;
+    this.#entries.delete(key);
+    this.#byteLength -= entry.byteLength;
+    return true;
+  }
+
+  #removeOldest(): boolean {
+    const oldest = this.#entries.keys().next().value;
+    if (!oldest) return false;
+    return this.#remove(oldest);
+  }
+
+  /** A measurement must never fail a cache write, and a bad measurement must never skew the total. */
+  static #measure<T>(sizeOf: (value: T) => number, value: T): number {
+    try {
+      const measured = sizeOf(value);
+      return Number.isFinite(measured) && measured > 0 ? measured : 0;
+    } catch {
+      return 0;
+    }
   }
 }

package/server/processMetricsCollector.ts

@@ -138,6 +138,10 @@ export class ProcessMetricsCollector {
       ...(metrics.jscHeapSizeBytes !== undefined
         ? [`jscHeap=${ProcessMetricsCollector.formatBytes(metrics.jscHeapSizeBytes)}`]
         : []),
+
+      ...(metrics.rscWorkerRssBytes !== undefined
+        ? [`rscWorkerRss=${ProcessMetricsCollector.formatBytes(metrics.rscWorkerRssBytes)}`]
+        : []),
       ...(metrics.eventLoopLagMeanMs !== undefined
         ? [`elLag=${metrics.eventLoopLagMeanMs}/${metrics.eventLoopLagP99Ms ?? 0}/${metrics.eventLoopLagMaxMs ?? 0}ms`]
         : []),

package/server/rscWorker.tsx

@@ -24,6 +24,7 @@ import { renderToReadableStream } from "react-server-dom-webpack/server.node";
 import type { ClientManifest } from "./artifact";
 import {
   LruTtlCache,
+  type LruTtlCacheOptions,
   parsePositiveInt,
   type RouteCacheEntry,
   type RouteCacheInvalidation,
@@ -122,6 +123,9 @@ interface FlightRenderResult {
   cancelled: boolean;
 }
 
+/** Well above any sensible TTL: this reclaims a cache nobody is reading, not tracks expiry closely. */
+const RESULT_CACHE_SWEEP_INTERVAL_MS = 60_000;
+
 function hashRscTraceCacheKey(cacheKey: string): string {
   let hash = 5381;
   for (let index = 0; index < cacheKey.length; index += 1) hash = (hash * 33) ^ cacheKey.charCodeAt(index);
@@ -197,11 +201,14 @@ export class RscRenderer {
     pagesBundleBuildId: 0,
   };
   readonly #routeStats = new Map<string, RouteRenderStats>();
+
   #resultCache = new LruTtlCache<CachedRscResult>(
     parsePositiveInt(process.env.AKAN_RSC_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+    RscRenderer.#resultCacheOptions(),
   );
   #patchResultCache = new LruTtlCache<CachedRscResult>(
     parsePositiveInt(process.env.AKAN_RSC_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+    RscRenderer.#resultCacheOptions(),
   );
   readonly #activeRenderReaders = new Map<string, ReadableStreamDefaultReader<Uint8Array>>();
   readonly #cancelledRenderRequests = new Set<string>();
@@ -818,7 +825,11 @@ export class RscRenderer {
       rscLoadedRouteModuleKeys: routeStats.loadedModuleKeys,
       rscTopRoutesByRenderCount: this.#topRoutes((route) => route.count),
       rscTopRoutesByFlightBytes: this.#topRoutes((route) => route.flightBytes),
-      rscResultCacheEntries: this.#resultCache.size + this.#patchResultCache.size,
+
+      rscResultCacheEntries: this.#resultCache.size,
+      rscResultCacheBytes: this.#resultCache.byteSize,
+      rscPatchResultCacheEntries: this.#patchResultCache.size,
+      rscPatchResultCacheBytes: this.#patchResultCache.byteSize,
       rscResultCacheHits: this.#resultCacheHits,
       rscResultCacheMisses: this.#resultCacheMisses,
       rscResultCacheBypass: this.#resultCacheBypass,
@@ -899,7 +910,7 @@ export class RscRenderer {
       });
     };
     try {
-      while (true) {
+      for (;;) {
         if (options.requestId && this.#cancelledRenderRequests.has(options.requestId)) {
           await reader.cancel();
           return { chunks, bytes, chunksCount, control: null, lateControlSent, cancelled: true };
@@ -1125,6 +1136,15 @@ export class RscRenderer {
     return decision;
   }
 
+  static #resultCacheOptions(): LruTtlCacheOptions<CachedRscResult> {
+    return {
+      sizeOf: (result) => result.bytes,
+      maxBytes: LruTtlCache.parseByteCeiling(process.env.AKAN_RSC_RESULT_CACHE_MAX_BYTES),
+      maxEntryBytes: LruTtlCache.parseByteCeiling(process.env.AKAN_RSC_RESULT_CACHE_MAX_BODY_BYTES),
+      sweepIntervalMs: RESULT_CACHE_SWEEP_INTERVAL_MS,
+    };
+  }
+
   #getCachedResult(cacheKey: string): CachedRscResult | null {
     const cached = this.#resultCache.get(cacheKey);
     if (!cached) {
@@ -1146,11 +1166,19 @@ export class RscRenderer {
   }
 
   #setCachedResult(cacheKey: string, result: CachedRscResult, ttl: number): void {
-    this.#resultCache.set(cacheKey, result, ttl);
+    this.#logRejectedStore("full", result, this.#resultCache.set(cacheKey, result, ttl));
   }
 
   #setCachedPatchResult(cacheKey: string, result: CachedRscResult, ttl: number): void {
-    this.#patchResultCache.set(cacheKey, result, ttl);
+    this.#logRejectedStore("patch", result, this.#patchResultCache.set(cacheKey, result, ttl));
+  }
+
+  /** A silently dropped store looks identical to a cache miss; say which route is too big to cache. */
+  #logRejectedStore(kind: string, result: CachedRscResult, stored: boolean): void {
+    if (stored) return;
+    this.#logger.verbose(
+      `${kind} result cache store skipped pathname=${result.pathname} bytes=${result.bytes} reason=body-too-large`,
+    );
   }
 
   #runWithRequest<T>(request: Request, fn: () => Promise<T>): Promise<T> {

package/server/rscWorkerHost.ts

@@ -89,6 +89,66 @@ export function createRscWorkerInvalidateCacheMessage(
   };
 }
 
+/**
+ * The RSC worker samples its own process with the same `ProcessMetricsCollector.collect` its host
+ * replica uses, so its report carries `pid` / `rssBytes` / `role` / … under the identical names.
+ * `AkanServer` spreads the host's report into its own `collect({ role, ...webRouter.getMetrics() })`
+ * and `collect` spreads `extra` last (`processMetricsCollector.ts:122`) — so passing these through
+ * unprefixed silently overwrote the replica's own process fields, and the replica's RSS was reported
+ * nowhere. Rename them onto `rscWorker*`; the `rsc*` render counters, which only the worker
+ * produces, pass through untouched.
+ *
+ * XXX A new process-level field in `ProcessMetricsCollector.collect` must be added here too, or it
+ * starts shadowing the replica again.
+ */
+export function projectRscWorkerProcessMetrics(metrics: AkanMetricsReport): AkanMetricsReport {
+  const {
+    role: _role,
+    pid: _pid,
+    trace: _trace,
+    reportedAt,
+    rssBytes,
+    heapTotalBytes,
+    heapUsedBytes,
+    externalBytes,
+    arrayBuffersBytes,
+    cpuUserMicros,
+    cpuSystemMicros,
+    maxRssKb,
+    jscHeapSizeBytes,
+    jscHeapCapacityBytes,
+    jscExtraMemorySizeBytes,
+    jscObjectCount,
+    jscProtectedObjectCount,
+    eventLoopLagMeanMs,
+    eventLoopLagP99Ms,
+    eventLoopLagMaxMs,
+    gcDurationMs,
+    ...renderMetrics
+  } = metrics;
+  return {
+    ...renderMetrics,
+    rscWorkerReportedAt: reportedAt,
+    rscWorkerRssBytes: rssBytes,
+    rscWorkerHeapTotalBytes: heapTotalBytes,
+    rscWorkerHeapUsedBytes: heapUsedBytes,
+    rscWorkerExternalBytes: externalBytes,
+    rscWorkerArrayBuffersBytes: arrayBuffersBytes,
+    rscWorkerCpuUserMicros: cpuUserMicros,
+    rscWorkerCpuSystemMicros: cpuSystemMicros,
+    rscWorkerMaxRssKb: maxRssKb,
+    rscWorkerJscHeapSizeBytes: jscHeapSizeBytes,
+    rscWorkerJscHeapCapacityBytes: jscHeapCapacityBytes,
+    rscWorkerJscExtraMemorySizeBytes: jscExtraMemorySizeBytes,
+    rscWorkerJscObjectCount: jscObjectCount,
+    rscWorkerJscProtectedObjectCount: jscProtectedObjectCount,
+    rscWorkerEventLoopLagMeanMs: eventLoopLagMeanMs,
+    rscWorkerEventLoopLagP99Ms: eventLoopLagP99Ms,
+    rscWorkerEventLoopLagMaxMs: eventLoopLagMaxMs,
+    rscWorkerGcDurationMs: gcDurationMs,
+  };
+}
+
 export function createRscHostRenderStream(input: {
   setPending: (pending: RscPending) => void;
   deletePending: () => void;
@@ -464,18 +524,7 @@ export class RscWorker {
   }
 
   getMetrics(): AkanMetricsReport {
-    const {
-      rscWorkerPid: _rscWorkerPid,
-      rscWorkerStatus: _rscWorkerStatus,
-      rscWorkerRestartCount: _rscWorkerRestartCount,
-      rscWorkerRecycleCount: _rscWorkerRecycleCount,
-      rscWorkerLastRecycleReason: _rscWorkerLastRecycleReason,
-      rscPendingRenderCount: _rscPendingRenderCount,
-      rscQueuedSendCount: _rscQueuedSendCount,
-      rscHostPendingChunkOverflowCount: _rscHostPendingChunkOverflowCount,
-      ...workerMetrics
-    } = this.#lastWorkerMetrics;
-    return Object.assign(workerMetrics, {
+    return Object.assign(projectRscWorkerProcessMetrics(this.#lastWorkerMetrics), {
       rscWorkerPid: this.#proc.pid,
       rscWorkerStatus: this.#status,
       rscWorkerRestartCount: this.#restartCount,

package/server/ssrFromRscRenderer.tsx

@@ -411,7 +411,7 @@ export function interleaveRscScriptsWithHtml(
       const pumpRscScripts = async () => {
         rscReader = rscClientStream.getReader();
         try {
-          while (true) {
+          for (;;) {
             const { value, done } = await rscReader.read();
             if (done || errored) break;
             await waitForRscQueueDrain();
@@ -446,7 +446,7 @@ export function interleaveRscScriptsWithHtml(
 
         htmlReader = htmlStream.getReader();
         try {
-          while (true) {
+          for (;;) {
             const { value, done } = await htmlReader.read();
             if (done || errored) break;
             controller.enqueue(value);

package/server/webRouter.ts

@@ -56,6 +56,8 @@ import type { BaseBuildArtifact, HttpRoutes, RenderState } from "./types";
 
 const CLIENT_CLOSED_REQUEST_STATUS = 499;
 export const DEFAULT_HTML_RESULT_CACHE_MAX_BODY_BYTES = 2 * 1024 * 1024;
+/** Well above any sensible TTL: this only has to reclaim a cache nobody is reading, not track expiry closely. */
+const ROUTE_CACHE_SWEEP_INTERVAL_MS = 60_000;
 const APPLE_APP_SITE_ASSOCIATION_PATH = "/.well-known/apple-app-site-association";
 const ANDROID_ASSET_LINKS_PATH = "/.well-known/assetlinks.json";
 
@@ -286,6 +288,11 @@ export class WebRouter {
   };
   readonly #htmlCache = new LruTtlCache<CachedHtmlResult>(
     parsePositiveInt(process.env.AKAN_HTML_RESULT_CACHE_MAX_ENTRIES) ?? 100,
+    {
+      sizeOf: (result) => result.html.length,
+      maxBytes: LruTtlCache.parseByteCeiling(process.env.AKAN_HTML_RESULT_CACHE_MAX_BYTES),
+      sweepIntervalMs: ROUTE_CACHE_SWEEP_INTERVAL_MS,
+    },
   );
   #htmlCacheHits = 0;
   #htmlCacheMisses = 0;
@@ -669,6 +676,7 @@ export class WebRouter {
     this.#devHmr?.dispose();
     this.#devHmr = null;
     this.#builderRpc = null;
+    this.#htmlCache.dispose();
     this.#rsc.kill();
     this.#hub = null;
   }
@@ -686,6 +694,7 @@ export class WebRouter {
       httpCsrCount: this.#requestStats.csr,
       httpImageCount: this.#requestStats.image,
       httpHtmlCacheEntries: this.#htmlCache.size,
+      httpHtmlCacheBytes: this.#htmlCache.byteSize,
       httpHtmlCacheHits: this.#htmlCacheHits,
       httpHtmlCacheMisses: this.#htmlCacheMisses,
       httpHtmlCacheBypass: this.#htmlCacheBypass,

package/service/ipcTypes.ts

@@ -55,6 +55,26 @@ export interface AkanMetricsReport {
   rscWorkerRestartCount?: number;
   rscWorkerRecycleCount?: number;
   rscWorkerLastRecycleReason?: string;
+
+  rscWorkerReportedAt?: number;
+  rscWorkerRssBytes?: number;
+  rscWorkerHeapTotalBytes?: number;
+  rscWorkerHeapUsedBytes?: number;
+  rscWorkerExternalBytes?: number;
+  rscWorkerArrayBuffersBytes?: number;
+  rscWorkerCpuUserMicros?: number;
+  rscWorkerCpuSystemMicros?: number;
+  rscWorkerMaxRssKb?: number;
+  rscWorkerJscHeapSizeBytes?: number;
+  rscWorkerJscHeapCapacityBytes?: number;
+  /** Off-heap bytes JSC attributes to JS objects — typed-array backing stores, i.e. cached Flight chunks. */
+  rscWorkerJscExtraMemorySizeBytes?: number;
+  rscWorkerJscObjectCount?: number;
+  rscWorkerJscProtectedObjectCount?: number;
+  rscWorkerEventLoopLagMeanMs?: number;
+  rscWorkerEventLoopLagP99Ms?: number;
+  rscWorkerEventLoopLagMaxMs?: number;
+  rscWorkerGcDurationMs?: number;
   rscPendingRenderCount?: number;
   rscQueuedSendCount?: number;
   rscHostPendingChunkOverflowCount?: number;
@@ -80,9 +100,13 @@ export interface AkanMetricsReport {
   rscLastRenderLoadedModuleDelta?: number;
   rscLastRenderLoadedModules?: string[];
   rscResultCacheEntries?: number;
+  rscResultCacheBytes?: number;
+  rscPatchResultCacheEntries?: number;
+  rscPatchResultCacheBytes?: number;
   rscResultCacheHits?: number;
   rscResultCacheMisses?: number;
   rscResultCacheBypass?: number;
+  /** Keys the SSR chunk registry tracks — NOT a memory bound; the modules stay in Bun's ESM registry. */
   ssrChunkRegistrySize?: number;
   ssrChunkLoadCount?: number;
   ssrChunkCacheHitCount?: number;
@@ -93,6 +117,7 @@ export interface AkanMetricsReport {
   httpCsrCount?: number;
   httpImageCount?: number;
   httpHtmlCacheEntries?: number;
+  httpHtmlCacheBytes?: number;
   httpHtmlCacheHits?: number;
   httpHtmlCacheMisses?: number;
   httpHtmlCacheBypass?: number;

package/types/server/cachePolicy.d.ts

@@ -78,14 +78,45 @@ export declare function shouldStoreRouteCache(input: {
 }): RouteCacheRenderState;
 export declare function hasRouteCacheInvalidationScope(invalidation?: RouteCacheInvalidation): boolean;
 export declare function shouldInvalidateRouteCacheEntry(metadata: RouteCacheMetadata, invalidation: RouteCacheInvalidation): boolean;
+export interface LruTtlCacheOptions<T> {
+    /**
+     * Measures one entry's payload. Entry count alone says nothing about a cache whose entries span
+     * three orders of magnitude, and a byte ceiling needs a running total to enforce. The default
+     * reports 0 rather than guessing, so `byteSize` stays honest about not knowing.
+     */
+    sizeOf?: (value: T) => number;
+    /** Total payload ceiling. 0 leaves the cache bounded only by `maxEntries`. */
+    maxBytes?: number;
+    /** An entry over this is not stored at all, rather than evicting everything else to fit it. */
+    maxEntryBytes?: number;
+    /**
+     * Cadence of the idle sweep. Without one a filled cache never shrinks: an entry is dropped only
+     * when its own key is fetched after expiry or when a write evicts it, so a pod that stops
+     * serving holds its peak forever — measured at 100 entries / 21.4 MiB still resident 310s after
+     * the last request, with a 30s TTL. 0 disables it.
+     */
+    sweepIntervalMs?: number;
+}
 export declare class LruTtlCache<T> {
     #private;
     readonly maxEntries: number;
-    constructor(maxEntries?: number);
+    constructor(maxEntries?: number, options?: LruTtlCacheOptions<T>);
     get size(): number;
+    get byteSize(): number;
     get(key: string): T | null;
-    set(key: string, value: T, ttlSeconds: number): void;
+    /** Returns whether the entry was stored; a payload over `maxEntryBytes` is rejected. */
+    set(key: string, value: T, ttlSeconds: number): boolean;
+    /**
+     * Drops every expired entry. Deliberately a full scan rather than a walk from the oldest that
+     * stops at the first live entry: insertion order is *LRU* order because `get` reinserts, and TTLs
+     * differ per entry, so expiry is not monotonic in map order and an early break would leave
+     * expired entries behind. The map is bounded by `maxEntries`, so the scan is cheap.
+     */
+    sweepExpired(now?: number): number;
+    /** Stops the idle sweep. The cache stays usable; only the timer goes away. */
+    dispose(): void;
     delete(key: string): boolean;
     invalidate(predicate: (key: string, value: T) => boolean): number;
     clear(): void;
+    static parseByteCeiling(value: string | undefined | null, fallback?: number): number;
 }

package/types/server/rscWorkerHost.d.ts

@@ -49,6 +49,19 @@ export declare function nextRscHostPendingChunkCount(currentPendingChunks: numbe
 export declare function isRscHostPendingChunkOverflow(pendingChunks: number, maxPendingChunks: number): boolean;
 export declare function createIdempotentRscRenderCancel(onCancel: (reason?: unknown) => void): (reason?: unknown) => void;
 export declare function createRscWorkerInvalidateCacheMessage(invalidation?: string | RouteCacheInvalidation): RscWorkerInvalidateCacheMessage;
+/**
+ * The RSC worker samples its own process with the same `ProcessMetricsCollector.collect` its host
+ * replica uses, so its report carries `pid` / `rssBytes` / `role` / … under the identical names.
+ * `AkanServer` spreads the host's report into its own `collect({ role, ...webRouter.getMetrics() })`
+ * and `collect` spreads `extra` last (`processMetricsCollector.ts:122`) — so passing these through
+ * unprefixed silently overwrote the replica's own process fields, and the replica's RSS was reported
+ * nowhere. Rename them onto `rscWorker*`; the `rsc*` render counters, which only the worker
+ * produces, pass through untouched.
+ *
+ * XXX A new process-level field in `ProcessMetricsCollector.collect` must be added here too, or it
+ * starts shadowing the replica again.
+ */
+export declare function projectRscWorkerProcessMetrics(metrics: AkanMetricsReport): AkanMetricsReport;
 export declare function createRscHostRenderStream(input: {
     setPending: (pending: RscPending) => void;
     deletePending: () => void;

package/types/service/ipcTypes.d.ts

@@ -59,6 +59,25 @@ export interface AkanMetricsReport {
     rscWorkerRestartCount?: number;
     rscWorkerRecycleCount?: number;
     rscWorkerLastRecycleReason?: string;
+    rscWorkerReportedAt?: number;
+    rscWorkerRssBytes?: number;
+    rscWorkerHeapTotalBytes?: number;
+    rscWorkerHeapUsedBytes?: number;
+    rscWorkerExternalBytes?: number;
+    rscWorkerArrayBuffersBytes?: number;
+    rscWorkerCpuUserMicros?: number;
+    rscWorkerCpuSystemMicros?: number;
+    rscWorkerMaxRssKb?: number;
+    rscWorkerJscHeapSizeBytes?: number;
+    rscWorkerJscHeapCapacityBytes?: number;
+    /** Off-heap bytes JSC attributes to JS objects — typed-array backing stores, i.e. cached Flight chunks. */
+    rscWorkerJscExtraMemorySizeBytes?: number;
+    rscWorkerJscObjectCount?: number;
+    rscWorkerJscProtectedObjectCount?: number;
+    rscWorkerEventLoopLagMeanMs?: number;
+    rscWorkerEventLoopLagP99Ms?: number;
+    rscWorkerEventLoopLagMaxMs?: number;
+    rscWorkerGcDurationMs?: number;
     rscPendingRenderCount?: number;
     rscQueuedSendCount?: number;
     rscHostPendingChunkOverflowCount?: number;
@@ -94,9 +113,13 @@ export interface AkanMetricsReport {
     rscLastRenderLoadedModuleDelta?: number;
     rscLastRenderLoadedModules?: string[];
     rscResultCacheEntries?: number;
+    rscResultCacheBytes?: number;
+    rscPatchResultCacheEntries?: number;
+    rscPatchResultCacheBytes?: number;
     rscResultCacheHits?: number;
     rscResultCacheMisses?: number;
     rscResultCacheBypass?: number;
+    /** Keys the SSR chunk registry tracks — NOT a memory bound; the modules stay in Bun's ESM registry. */
     ssrChunkRegistrySize?: number;
     ssrChunkLoadCount?: number;
     ssrChunkCacheHitCount?: number;
@@ -107,6 +130,7 @@ export interface AkanMetricsReport {
     httpCsrCount?: number;
     httpImageCount?: number;
     httpHtmlCacheEntries?: number;
+    httpHtmlCacheBytes?: number;
     httpHtmlCacheHits?: number;
     httpHtmlCacheMisses?: number;
     httpHtmlCacheBypass?: number;