deepline 0.3.461 → 0.3.463

package/dist/bundling-sources/shared_libs/play-runtime/map-memory-limits.ts

@@ -20,6 +20,7 @@ import {
   onMemoryPressure as subscribeRuntimeMemoryPressure,
   reportMemoryLedger as publishRuntimeMemoryLedger,
 } from './memory-pressure-signal';
+import { DEFAULT_AUTOMATIC_UNMEASURED_ROW_CONCURRENCY } from './governor/policy';
 
 export const NODE_RUNTIME_MAP_MEMORY_BUDGET_BYTES = 512 * 1024 * 1024;
 export const NODE_RUNTIME_MAP_MATERIALIZED_MEMORY_MULTIPLIER = 4;
@@ -184,6 +185,8 @@ export type RuntimeMapHeapSnapshot = {
    * of the live footprint the map can actually shrink.
    */
   externalBytes?: number;
+  /** Subset of externalBytes, retained only for decomposition diagnostics. */
+  arrayBuffersBytes?: number;
   /**
    * The process working set. It is what the sandbox cgroup kills on, but Node
    * rarely returns freed pages to the OS, so RSS only proves proximity to the
@@ -314,6 +317,10 @@ export type RuntimeMapHeapAdmissionSnapshot = {
  * post-collection re-probe replaces the reading it supersedes.
  */
 type HeapReading = {
+  heapUsedBytes: number | null;
+  externalBytes: number | null;
+  arrayBuffersBytes: number | null;
+  lastLedgerMutationAtMs: number | null;
   heapLimitBytes: number;
   heapTargetBytes: number;
   liveBytes: number;
@@ -336,6 +343,10 @@ export type RuntimeMapHeapAdmission = {
   acquire(): Promise<RuntimeMapHeapAdmissionLease>;
   /** Sample V8 and admit any newly safe waiting rows. Useful for deterministic tests. */
   reconcile(): void;
+  /** Current confirmed pressure only; row width is not a tool-call limit. */
+  readExternalExecutionPressure(): boolean;
+  /** Reuse this controller's reconciliation; no second policy timer. */
+  subscribeExternalExecutionPressure(changed: () => void): () => void;
   /** Reject waiters after a row failure, or release the timer after normal completion. */
   close(error?: unknown): RuntimeMapHeapAdmissionSnapshot;
   snapshot(): RuntimeMapHeapAdmissionSnapshot;
@@ -549,6 +560,11 @@ export function readRuntimeMapHeapSnapshot(): RuntimeMapHeapSnapshot | null {
         Number.isFinite(memoryUsage.external) && memoryUsage.external >= 0
           ? memoryUsage.external
           : undefined,
+      arrayBuffersBytes:
+        Number.isFinite(memoryUsage.arrayBuffers) &&
+        memoryUsage.arrayBuffers >= 0
+          ? memoryUsage.arrayBuffers
+          : undefined,
       residentBytes: Number.isFinite(memoryUsage.rss)
         ? memoryUsage.rss
         : undefined,
@@ -730,6 +746,35 @@ export type RuntimeMemoryOccupancyReader = {
   };
 };
 
+function isFreshRuntimeMajorGc(
+  completedAtMs: number | null,
+  probeAtMs: number,
+  windowMs: number,
+  watermarkMs: number | null,
+  ledger?: RuntimeMemoryLedger | null,
+): completedAtMs is number {
+  const mutationAtMs = ledger?.lastMutationAtMs?.() ?? null;
+  return (
+    completedAtMs !== null &&
+    Number.isFinite(completedAtMs) &&
+    completedAtMs >= 0 &&
+    Number.isFinite(probeAtMs) &&
+    completedAtMs <= probeAtMs &&
+    // A recent collection cannot have collected a later registered/released
+    // graph. Integer mutation clocks cannot order the GC's fractional same
+    // millisecond either, so that known ambiguity is conservative as well.
+    (mutationAtMs === null ||
+      (Number.isFinite(mutationAtMs) &&
+        mutationAtMs >= 0 &&
+        Math.floor(mutationAtMs) < Math.floor(completedAtMs))) &&
+    probeAtMs - completedAtMs < windowMs &&
+    // Performance GC entries are fractional; Date.now watermarks are integral.
+    // An event in an explicit collection's same millisecond is not independent evidence.
+    Math.floor(completedAtMs) >
+      Math.floor(watermarkMs ?? Number.NEGATIVE_INFINITY)
+  );
+}
+
 /**
  * A process-wide occupancy reader.
  *
@@ -831,9 +876,13 @@ export function createRuntimeMemoryOccupancyReader(input: {
       const lastMajorAtMs =
         gcObserver?.().byKind.major.lastCompletedAtMs ?? null;
       if (
-        lastMajorAtMs !== null &&
-        startedAt - lastMajorAtMs < gcMinIntervalMs &&
-        lastMajorAtMs > (lastGcAtMs ?? Number.NEGATIVE_INFINITY)
+        isFreshRuntimeMajorGc(
+          lastMajorAtMs,
+          startedAt,
+          gcMinIntervalMs,
+          lastGcAtMs,
+          input.memoryLedger,
+        )
       ) {
         // V8 already swept inside the interval; re-probing reads live objects
         // without paying for a second sweep of them.
@@ -904,6 +953,8 @@ export function createRuntimeMemoryOccupancyReader(input: {
  */
 export function createRuntimeMapHeapAdmission(input: {
   maxConcurrency: number;
+  /** Omission preserves existing explicitly configured admission semantics. */
+  concurrencySource?: 'automatic' | 'requested';
   heapProbe?: () => RuntimeMapHeapSnapshot | null;
   initialConcurrency?: number;
   probeIntervalMs?: number;
@@ -976,6 +1027,10 @@ export function createRuntimeMapHeapAdmission(input: {
   now?: () => number;
 }): RuntimeMapHeapAdmission {
   const maxConcurrency = positiveBudget(input.maxConcurrency, 1);
+  const unmeasuredMaxConcurrency =
+    input.concurrencySource === 'automatic'
+      ? Math.min(maxConcurrency, DEFAULT_AUTOMATIC_UNMEASURED_ROW_CONCURRENCY)
+      : maxConcurrency;
   const initialConcurrency = Math.min(
     maxConcurrency,
     positiveBudget(
@@ -1076,6 +1131,10 @@ export function createRuntimeMapHeapAdmission(input: {
   let admittedRows = 0;
   let settledRows = 0;
   let heapLimitBytes: number | null = null;
+  let heapProbeAvailable = false;
+  // The last existing controller pressure verdict survives loss of its probe.
+  let externalExecutionPressure = false;
+  const externalPressureListeners = new Set<() => void>();
   let heapTargetBytes: number | null = null;
   let heapUsedBytes: number | null = null;
   let heapUsedPeakBytes: number | null = null;
@@ -1143,9 +1202,13 @@ export function createRuntimeMapHeapAdmission(input: {
       lastGcAtMs = finishedAt;
     }
     const initial = heapProbe();
+    heapProbeAvailable = initial !== null;
     if (initial) {
       liveBaselineBytes =
         initial.usedHeapBytes + Math.max(0, initial.externalBytes ?? 0);
+      if (runtimeGc !== null) {
+        memoryLedger?.recordCollectedBaseline?.(liveBaselineBytes);
+      }
       // The opening width is spent before any probe: every row worker calls
       // acquire() at once, and a granted lease cannot be taken back. So the
       // unmeasured reserve has to bound the first wave too, not just the
@@ -1173,6 +1236,8 @@ export function createRuntimeMapHeapAdmission(input: {
           Math.floor(openingHeadroomBytes / openingRowReserveBytes),
         ),
       );
+    } else {
+      concurrency = Math.min(concurrency, unmeasuredMaxConcurrency);
     }
   }
 
@@ -1272,11 +1337,13 @@ export function createRuntimeMapHeapAdmission(input: {
   };
 
   const pauseAdmission = () => {
+    externalExecutionPressure = true;
     admissionHolds += 1;
     admissionPaused = true;
   };
 
   const applyHeapSample = (heap: RuntimeMapHeapSnapshot): HeapReading => {
+    heapProbeAvailable = true;
     heapLimitBytes = heap.heapLimitBytes;
     heapUsedBytes = heap.usedHeapBytes;
     heapUsedPeakBytes = Math.max(heapUsedPeakBytes ?? 0, heap.usedHeapBytes);
@@ -1304,7 +1371,13 @@ export function createRuntimeMapHeapAdmission(input: {
         : Math.floor(
             cgroupLimitBytes * RUNTIME_MAP_RESIDENT_GUARD_CGROUP_FRACTION,
           );
+    const component = (value: number | null | undefined): number | null =>
+      value != null && Number.isFinite(value) && value >= 0 ? value : null;
     return {
+      heapUsedBytes: component(heap.usedHeapBytes),
+      externalBytes: component(heap.externalBytes),
+      arrayBuffersBytes: component(heap.arrayBuffersBytes),
+      lastLedgerMutationAtMs: component(memoryLedger?.lastMutationAtMs?.()),
       heapLimitBytes: heap.heapLimitBytes,
       heapTargetBytes,
       liveBytes,
@@ -1326,17 +1399,31 @@ export function createRuntimeMapHeapAdmission(input: {
    * Returns the post-collection reading, or null when no collection happened
    * and the caller's reading still stands.
    */
-  const collectAndReprobe = (): HeapReading | null => {
+  const collectAndReprobe = () => {
     const startedAt = now();
     const lastMajorAtMs = gcObserver?.().byKind.major.lastCompletedAtMs ?? null;
     if (
-      lastMajorAtMs !== null &&
-      startedAt - lastMajorAtMs < gcMinIntervalMs &&
-      lastMajorAtMs > (lastGcAtMs ?? Number.NEGATIVE_INFINITY)
+      isFreshRuntimeMajorGc(
+        lastMajorAtMs,
+        startedAt,
+        gcMinIntervalMs,
+        lastGcAtMs,
+        memoryLedger,
+      )
     ) {
       lastGcAtMs = lastMajorAtMs;
       const swept = heapProbe();
-      return swept ? applyHeapSample(swept) : null;
+      const probeAtMs = now();
+      return swept
+        ? {
+            reading: applyHeapSample(swept),
+            observation: {
+              probeAtMs,
+              gcCompletedAtMs: lastMajorAtMs,
+              reason: 'natural-major-gc' as const,
+            },
+          }
+        : null;
     }
     if (runtimeGc === null) return null;
     if (lastGcAtMs !== null && startedAt - lastGcAtMs < gcMinIntervalMs) {
@@ -1348,7 +1435,17 @@ export function createRuntimeMapHeapAdmission(input: {
     gcExplicitTotalMs += Math.max(0, finishedAt - startedAt);
     lastGcAtMs = finishedAt;
     const collected = heapProbe();
-    return collected ? applyHeapSample(collected) : null;
+    const probeAtMs = now();
+    return collected
+      ? {
+          reading: applyHeapSample(collected),
+          observation: {
+            probeAtMs,
+            gcCompletedAtMs: finishedAt,
+            reason: 'explicit-gc' as const,
+          },
+        }
+      : null;
   };
 
   /**
@@ -1373,32 +1470,56 @@ export function createRuntimeMapHeapAdmission(input: {
         : safeWidth;
   };
 
-  const reconcile = () => {
+  const reconcileState = () => {
     if (closed) return;
     const heap = heapProbe();
     if (!heap) {
+      heapProbeAvailable = false;
       admissionPaused = false;
-      concurrency = maxConcurrency;
+      concurrency = unmeasuredMaxConcurrency;
       drain();
       return;
     }
+    const probeAtMs = now();
     let reading = applyHeapSample(heap);
+    let observation: {
+      probeAtMs: number;
+      gcCompletedAtMs: number | null;
+      reason: 'explicit-gc' | 'natural-major-gc' | 'gc-unavailable';
+    } = { probeAtMs, gcCompletedAtMs: null, reason: 'gc-unavailable' };
     // A collection the watchdog just asked for makes this probe a collected
     // one, which is the only kind the ledger may calibrate from.
     let postCollectionSample = nextProbeIsPostCollection;
     nextProbeIsPostCollection = false;
+    if (postCollectionSample)
+      observation = {
+        probeAtMs: observation.probeAtMs,
+        gcCompletedAtMs: lastGcAtMs,
+        reason: 'explicit-gc',
+      };
     // V8's own major collections count too: a probe taken right after one
     // reads live objects, not garbage, so a light map that never crosses the
     // target still calibrates instead of keeping the prior for its whole life.
     const naturalMajorAtMs =
       gcObserver?.().byKind.major.lastCompletedAtMs ?? null;
     if (
-      naturalMajorAtMs !== null &&
+      isFreshRuntimeMajorGc(
+        naturalMajorAtMs,
+        observation.probeAtMs,
+        gcMinIntervalMs,
+        lastGcAtMs,
+        memoryLedger,
+      ) &&
       naturalMajorAtMs >
         (lastNaturalMajorCalibratedAtMs ?? Number.NEGATIVE_INFINITY)
     ) {
       lastNaturalMajorCalibratedAtMs = naturalMajorAtMs;
       postCollectionSample = true;
+      observation = {
+        probeAtMs: observation.probeAtMs,
+        gcCompletedAtMs: naturalMajorAtMs,
+        reason: 'natural-major-gc',
+      };
     }
 
     // Observed live over the target is a question about garbage, not a verdict
@@ -1412,7 +1533,8 @@ export function createRuntimeMapHeapAdmission(input: {
     } else {
       const collected = collectAndReprobe();
       if (collected) {
-        reading = collected;
+        reading = collected.reading;
+        observation = collected.observation;
         postCollectionSample = true;
       }
       if (postCollectionSample || !gcAvailable) {
@@ -1460,6 +1582,13 @@ export function createRuntimeMapHeapAdmission(input: {
         observedLiveBytes: reading.liveBytes,
         baselineBytes: reading.liveBaselineBytes,
         admittedRowReserveBytes,
+        observation: {
+          ...observation,
+          heapUsedBytes: reading.heapUsedBytes,
+          externalBytes: reading.externalBytes,
+          arrayBuffersBytes: reading.arrayBuffersBytes,
+          lastLedgerMutationAtMs: reading.lastLedgerMutationAtMs,
+        },
       });
     }
     memorySnapshot = memoryLedger?.snapshot() ?? null;
@@ -1564,7 +1693,11 @@ export function createRuntimeMapHeapAdmission(input: {
       return;
     }
     eventLoopPressureActive = false;
-    if (eventLoopLagMs !== null && eventLoopCeiling < maxConcurrency && adjustDue) {
+    if (
+      eventLoopLagMs !== null &&
+      eventLoopCeiling < maxConcurrency &&
+      adjustDue
+    ) {
       lastEventLoopAdjustAtMs = now();
       eventLoopCeiling = Math.min(
         maxConcurrency,
@@ -1600,6 +1733,32 @@ export function createRuntimeMapHeapAdmission(input: {
     drain();
   };
 
+  const reconcile = () => {
+    if (closed) return;
+    try {
+      reconcileState();
+    } finally {
+      // Only a current complete healthy observation may clear a known hold.
+      if (
+        admissionPaused ||
+        (eventLoopLagMs !== null && eventLoopLagMs >= eventLoopLagHoldMs)
+      ) {
+        externalExecutionPressure = true;
+      } else if (
+        heapProbeAvailable &&
+        residentBytes !== null &&
+        Number.isFinite(residentBytes) &&
+        residentGuardBytes !== null &&
+        Number.isFinite(residentGuardBytes) &&
+        eventLoopLagMs !== null &&
+        Number.isFinite(eventLoopLagMs)
+      ) {
+        externalExecutionPressure = false;
+      }
+      for (const changed of externalPressureListeners) changed();
+    }
+  };
+
   const unsubscribeMemoryPressure = subscribeMemoryPressure(() => {
     if (closed) return;
     externalPressureSignals += 1;
@@ -1647,12 +1806,29 @@ export function createRuntimeMapHeapAdmission(input: {
       );
     },
     reconcile,
+    readExternalExecutionPressure() {
+      return (
+        !closed &&
+        (externalExecutionPressure ||
+          admissionPaused ||
+          (eventLoopLagMs !== null && eventLoopLagMs >= eventLoopLagHoldMs))
+      );
+    },
+    subscribeExternalExecutionPressure(changed) {
+      if (closed) return () => {};
+      externalPressureListeners.add(changed);
+      return () => {
+        externalPressureListeners.delete(changed);
+      };
+    },
     close(error) {
       if (!closed) {
         closed = true;
         closeError = error ?? new Error('Runtime map row admission is closed.');
         clearInterval(timer);
         unsubscribeMemoryPressure();
+        for (const changed of externalPressureListeners) changed();
+        externalPressureListeners.clear();
         while (waiters.length > 0) {
           waiters.shift()?.reject(closeError);
         }

package/dist/bundling-sources/shared_libs/play-runtime/memory-ledger.ts

@@ -180,6 +180,32 @@ export type RuntimeMemoryLedgerHandle = {
   release(): void;
 };
 
+export type RuntimeMemoryLedgerObservationMetadata = {
+  /** Same scored probe; ArrayBuffers are a subset of external, not additive. */
+  heapUsedBytes?: number | null;
+  externalBytes?: number | null;
+  arrayBuffersBytes?: number | null;
+  lastLedgerMutationAtMs?: number | null;
+
+  probeAtMs?: number | null;
+  gcCompletedAtMs?: number | null;
+  reason?: 'explicit-gc' | 'natural-major-gc' | 'gc-unavailable' | null;
+};
+
+export type RuntimeMemoryLedgerPeakObservation = {
+  /** Same scored probe; ArrayBuffers are a subset of external, not additive. */
+  heapUsedBytes?: number | null;
+  externalBytes?: number | null;
+  arrayBuffersBytes?: number | null;
+  lastLedgerMutationAtMs?: number | null;
+
+  probeAtMs: number | null;
+  gcCompletedAtMs: number | null;
+  reason: Exclude<RuntimeMemoryLedgerObservationMetadata['reason'], undefined>;
+  bytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+  predictedBytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+};
+
 export type RuntimeMemoryLedgerSnapshot = {
   bytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
   /** Per-category high-water marks. These are independent maxima. */
@@ -242,6 +268,10 @@ export type RuntimeMemoryLedgerSnapshot = {
    * same as `predictedLiveBytes`.
    */
   predictedAtObservedPeakBytes: number | null;
+  /** Baseline from that SAME probe; absence keeps historical reader behavior. */
+  baselineAtObservedPeakBytes?: number | null;
+  /** Fixed scalar/category evidence, before fitting; absent on older snapshots. */
+  observationAtObservedPeak?: RuntimeMemoryLedgerPeakObservation | null;
   /** Ledger bytes registered at that same instant, for the same reason. */
   ledgerBytesAtObservedPeak: number | null;
   /**
@@ -254,6 +284,8 @@ export type RuntimeMemoryLedgerSnapshot = {
 };
 
 export type RuntimeMemoryLedger = {
+  /** Internal ownership clock; absent on legacy ledgers. Never a wire field. */
+  lastMutationAtMs?(): number | null;
   register(input: {
     category: RuntimeMemoryLedgerCategory;
     ownerId?: string | null;
@@ -268,6 +300,8 @@ export type RuntimeMemoryLedger = {
   settleOwner(ownerId: string): number | null;
   /** Bytes currently registered to an owner, or null if it is not tracked. */
   ownerBytes(ownerId: string): number | null;
+  /** Retain an actual collected opening baseline without fitting or scoring a sample. */
+  recordCollectedBaseline?(bytes: number): void;
   /**
    * Fit the ledger to the process. `observedLiveBytes` is heapUsed + external
    * from the same probe that paces admission; `baselineBytes` is the reading
@@ -283,6 +317,7 @@ export type RuntimeMemoryLedger = {
      * promise about in-flight work rather than a retained object.
      */
     admittedRowReserveBytes?: number;
+    observation?: RuntimeMemoryLedgerObservationMetadata;
   }): void;
   snapshot(): RuntimeMemoryLedgerSnapshot;
 };
@@ -308,6 +343,8 @@ type SettledOwnerPeak = {
 };
 
 export function createRuntimeMemoryLedger(options?: {
+  /** Same wall-clock authority as GC completion timestamps; injectable for tests. */
+  now?: () => number;
   settledReservoirSize?: number;
   calibrationFloorBytes?: number;
   calibrationAlpha?: number;
@@ -325,6 +362,16 @@ export function createRuntimeMemoryLedger(options?: {
    */
   random?: () => number;
 }): RuntimeMemoryLedger {
+  const now = options?.now ?? Date.now;
+  let lastMutationAtMs: number | null = null;
+  const recordMutation = () => {
+    const at = now();
+    if (!Number.isFinite(at) || at < 0)
+      throw new RangeError(
+        'Memory ownership clock must be finite and non-negative.',
+      );
+    lastMutationAtMs = Math.max(lastMutationAtMs ?? at, at);
+  };
   const random = typeof options?.random === 'function' ? options.random : null;
   const uniform = (): number => {
     const value = random ? random() : Math.random();
@@ -481,6 +528,9 @@ export function createRuntimeMemoryLedger(options?: {
   let observedLiveBytes: number | null = null;
   let observedCollectedPeakBytes: number | null = null;
   let predictedAtObservedPeakBytes: number | null = null;
+  let baselineAtObservedPeakBytes: number | null = null;
+  let observationAtObservedPeak: RuntimeMemoryLedgerPeakObservation | null =
+    null;
   let ledgerBytesAtObservedPeak: number | null = null;
   let admittedRowReserveBytesAtObservedPeak: number | null = null;
   let baselineBytes: number | null = null;
@@ -535,6 +585,7 @@ export function createRuntimeMemoryLedger(options?: {
 
   const releaseEntry = (entry: LedgerEntry): void => {
     if (entry.released) return;
+    recordMutation();
     entry.released = true;
     liveEntries = Math.max(0, liveEntries - 1);
     applyDelta(entry, -entry.bytes);
@@ -545,6 +596,7 @@ export function createRuntimeMemoryLedger(options?: {
   };
 
   return {
+    lastMutationAtMs: () => lastMutationAtMs,
     register({ category, ownerId, bytes }) {
       const normalizedBytes = requireByteCount(bytes);
       if (!RUNTIME_MEMORY_LEDGER_CATEGORIES.includes(category)) {
@@ -552,6 +604,7 @@ export function createRuntimeMemoryLedger(options?: {
           `Runtime memory ledger received an unknown category "${String(category)}".`,
         );
       }
+      recordMutation();
       const normalizedOwnerId =
         typeof ownerId === 'string' && ownerId.length > 0 ? ownerId : null;
       const entry: LedgerEntry = {
@@ -581,6 +634,8 @@ export function createRuntimeMemoryLedger(options?: {
         update(nextBytes) {
           if (entry.released) return;
           const normalizedNext = requireByteCount(nextBytes);
+          // Equal byte counts can replace the entire retained object graph.
+          recordMutation();
           const delta = normalizedNext - entry.bytes;
           entry.bytes = normalizedNext;
           applyDelta(entry, delta);
@@ -625,16 +680,38 @@ export function createRuntimeMemoryLedger(options?: {
       return owners.get(ownerId)?.bytes ?? null;
     },
 
+    recordCollectedBaseline(bytes) {
+      const value = requireByteCount(bytes);
+      // An opening reading must never replace an already observed/scored baseline.
+      baselineBytes ??= value;
+    },
     calibrate({
       observedLiveBytes: observed,
       baselineBytes: baseline,
       admittedRowReserveBytes: admittedRowReserve = 0,
+      observation,
     }) {
       // The prediction admission was acting on at this probe, judged before
       // this probe is allowed to change it. Learning first and then scoring
       // would grade the fit against itself.
       const predictedBefore = predictedLiveBytesNow();
       const reservedBytes = requireByteCount(admittedRowReserve);
+      const time = (value: number | null | undefined): number | null => {
+        if (value == null) return null;
+        if (!Number.isFinite(value) || value < 0)
+          throw new RangeError(
+            'Memory observation time must be finite and non-negative.',
+          );
+        return value;
+      };
+      const probeAtMs = time(observation?.probeAtMs);
+      const gcCompletedAtMs = time(observation?.gcCompletedAtMs);
+      const reason = observation?.reason ?? null;
+      if (
+        reason !== null &&
+        !['explicit-gc', 'natural-major-gc', 'gc-unavailable'].includes(reason)
+      )
+        throw new RangeError('Memory observation reason is invalid.');
       if (Number.isFinite(observed) && observed >= 0) {
         observedLiveBytes = observed;
         if (observed > (observedCollectedPeakBytes ?? -1)) {
@@ -644,6 +721,47 @@ export function createRuntimeMemoryLedger(options?: {
           // readouts can explain an unaccounted gap, but judge the ledger's
           // prediction only on bytes its owners actually registered.
           predictedAtObservedPeakBytes = Math.round(predictedBefore);
+          baselineAtObservedPeakBytes =
+            baseline != null && Number.isFinite(baseline) && baseline >= 0
+              ? baseline
+              : null;
+          // Diagnostics never change scoring or fit. Preserve absent legacy
+          // fields, and freeze only these four finite/nonnegative scalars.
+          const components: Pick<
+            RuntimeMemoryLedgerObservationMetadata,
+            | 'heapUsedBytes'
+            | 'externalBytes'
+            | 'arrayBuffersBytes'
+            | 'lastLedgerMutationAtMs'
+          > = {};
+          for (const key of [
+            'heapUsedBytes',
+            'externalBytes',
+            'arrayBuffersBytes',
+            'lastLedgerMutationAtMs',
+          ] as const) {
+            const value = observation?.[key];
+            if (value !== undefined)
+              components[key] =
+                value !== null && Number.isFinite(value) && value >= 0
+                  ? value
+                  : null;
+          }
+          observationAtObservedPeak = {
+            ...components,
+            probeAtMs,
+            gcCompletedAtMs,
+            reason,
+            bytesByCategory: { ...bytesByCategory },
+            predictedBytesByCategory: Object.fromEntries(
+              RUNTIME_MEMORY_LEDGER_CATEGORIES.map((category) => [
+                category,
+                Math.round(
+                  bytesByCategory[category] * categoryFactors[category],
+                ),
+              ]),
+            ) as Record<RuntimeMemoryLedgerCategory, number>,
+          };
           ledgerBytesAtObservedPeak = liveBytes;
           admittedRowReserveBytesAtObservedPeak = reservedBytes;
         }
@@ -721,6 +839,19 @@ export function createRuntimeMemoryLedger(options?: {
         observedLiveBytes,
         observedCollectedPeakBytes,
         predictedAtObservedPeakBytes,
+        baselineAtObservedPeakBytes,
+        observationAtObservedPeak:
+          observationAtObservedPeak === null
+            ? null
+            : {
+                ...observationAtObservedPeak,
+                bytesByCategory: {
+                  ...observationAtObservedPeak.bytesByCategory,
+                },
+                predictedBytesByCategory: {
+                  ...observationAtObservedPeak.predictedBytesByCategory,
+                },
+              },
         ledgerBytesAtObservedPeak,
         admittedRowReserveBytesAtObservedPeak,
         baselineBytes,