deepline 0.3.128 → 0.3.129

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

@@ -0,0 +1,807 @@
+/**
+ * Explicit accounting of the bytes a Play Runtime process is retaining.
+ *
+ * Admission used to guess the per-row footprint by dividing observed heap
+ * growth by the rows in flight. That quotient is not a measurement: it read
+ * 0.9 MB/row while provider bodies were still on the wire and 48 MB/row while
+ * a drained map held uncollected garbage, and both readings were acted on. A
+ * ledger instead records what the runtime actually holds, at the site that
+ * holds it, with the serialized length that site already knows.
+ *
+ * The ledger is pure and dependency-free: it never probes the process, never
+ * schedules work, and never throws on anything but a caller passing a byte
+ * count that is not a byte count. The heap probe calibrates it; it does not
+ * replace the probe.
+ *
+ * Calibration is per category, not global. A ledger byte means a different
+ * number of live bytes depending on what holds it: `transportInFlight` is a JS
+ * string of exactly those bytes (a provider response OR a receipt-completion
+ * request serialized for the gateway), `providerBody` is the graph that a
+ * response string parsed into. One fitted factor across both is a weighted average of two
+ * regimes applied to whichever one is currently in front of it.
+ */
+
+export const RUNTIME_MEMORY_LEDGER_CATEGORIES = [
+  /** A decoded provider response body, retained until its row is durable. */
+  'providerBody',
+  /** A deep-cloned tool input retained while the call waits for provider admission. */
+  'toolInputSnapshot',
+  /** Cell provenance and status retained for map rows that have not durably settled. */
+  'mapCellMetadata',
+  /** Receipt completion inputs buffered by the runtime receipt writer. */
+  'receiptCompletionBuffer',
+  /** Completed map rows retained in memory for the caller's result. */
+  'materializedRows',
+  /** A response body or completion request held as text while in transport. */
+  'transportInFlight',
+  /** Durable-store read-backs of outputs the completion response omitted. */
+  'hydrationReadBack',
+  /** Buffered live-run events awaiting egress. */
+  'eventBuffer',
+] as const;
+
+export type RuntimeMemoryLedgerCategory =
+  (typeof RUNTIME_MEMORY_LEDGER_CATEGORIES)[number];
+
+/**
+ * Settled per-owner peaks kept for the percentile that sizes a row reserve.
+ *
+ * The sample is bounded, so past this many settled owners the ledger must
+ * choose which peaks to keep. It keeps a uniform sample of every owner the map
+ * has settled (see `settleOwner`), never the most recent ones: a map's rows do
+ * not settle in the order they were admitted, so "most recent" is a sample of
+ * whichever cohort happens to be slowest, not of the map.
+ */
+export const RUNTIME_MEMORY_LEDGER_SETTLED_RESERVOIR_SIZE = 256;
+/**
+ * Ledger total below which a calibration sample means nothing: at a few
+ * hundred kilobytes the runtime's own baseline noise dominates the quotient.
+ */
+export const RUNTIME_MEMORY_LEDGER_CALIBRATION_FLOOR_BYTES = 8 * 1024 * 1024;
+/**
+ * JSON bytes become 2-3x as V8 objects, so a runtime with no ledger at all
+ * assumes the middle of that range rather than parity. Inside the ledger every
+ * category carries its own prior (see
+ * `RUNTIME_MEMORY_LEDGER_CATEGORY_EXPANSION`); this constant is what lanes
+ * without a ledger snapshot fall back to.
+ */
+export const RUNTIME_MEMORY_LEDGER_INITIAL_FACTOR = 2.5;
+/** A factor below 1 would claim V8 stores a payload smaller than its bytes. */
+export const RUNTIME_MEMORY_LEDGER_MIN_FACTOR = 1;
+/** Above 6 the reading is unaccounted retention, not object overhead. */
+export const RUNTIME_MEMORY_LEDGER_MAX_FACTOR = 6;
+export const RUNTIME_MEMORY_LEDGER_CALIBRATION_ALPHA = 0.2;
+/**
+ * A parsed JSON graph: small string keys, boxed numbers, per-object headers.
+ * Measured between 3x and 5x its serialized length in V8.
+ */
+export const RUNTIME_MEMORY_LEDGER_OBJECT_PRIOR_FACTOR = 3;
+/**
+ * A payload still held as text. A JS string of JSON is one byte per character
+ * while V8 keeps it one-byte, so its live size is its serialized size plus a
+ * header; it is not a 3x object graph and must never be priced as one.
+ */
+export const RUNTIME_MEMORY_LEDGER_RAW_PRIOR_FACTOR = 1.1;
+/** A two-byte string of a one-byte payload is the worst honest text reading. */
+export const RUNTIME_MEMORY_LEDGER_RAW_MAX_FACTOR = 2.5;
+/**
+ * A category must own at least this share of the current prediction before a
+ * sample is allowed to move its factor. One heap reading is one equation in
+ * six unknowns: attributing it to a category that contributed 1% of the
+ * prediction is fitting noise, and it is how the transport regime ended up
+ * wearing the parsed-body regime's multiplier.
+ */
+export const RUNTIME_MEMORY_LEDGER_CATEGORY_SHARE_FLOOR = 0.05;
+
+/**
+ * Per-category live-bytes-per-ledger-byte priors and the band a fitted factor
+ * may occupy.
+ *
+ * One factor cannot describe this set. `transportInFlight` is a JS string of
+ * exactly the bytes it registered (whether response or completion request);
+ * `providerBody` is the object graph that
+ * string parsed into. Fitting a single number across both reads whichever
+ * regime happened to dominate the probes and then applies it to the other: on
+ * the jai 1,000-row fixture the fit landed at 4.6-4.8 and predicted a 1,019 MB
+ * peak against a 376 MB collected observation, so map admission believed the
+ * heap was full at ~35% of the target and issued thousands of holds.
+ */
+export const RUNTIME_MEMORY_LEDGER_CATEGORY_EXPANSION: Record<
+  RuntimeMemoryLedgerCategory,
+  { prior: number; min: number; max: number }
+> = {
+  // The decoded graph. This is the regime the single factor was fitted on.
+  providerBody: {
+    prior: RUNTIME_MEMORY_LEDGER_OBJECT_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_MAX_FACTOR,
+  },
+  // `callToolExecutionAPI` deep-clones caller input before provider admission
+  // so retries observe stable bytes. That graph stays live while a paced call
+  // waits in the shared provider queue, which is the same object regime as a
+  // decoded provider body.
+  toolInputSnapshot: {
+    prior: RUNTIME_MEMORY_LEDGER_OBJECT_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_MAX_FACTOR,
+  },
+  // Active map cell metadata is a nested object graph (status, provenance,
+  // producer attempts). It is released as soon as its terminal row is
+  // durably persisted, rather than accumulating for the whole map.
+  mapCellMetadata: {
+    prior: RUNTIME_MEMORY_LEDGER_OBJECT_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_MAX_FACTOR,
+  },
+  // Rows the caller will read: decoded cell values, same regime as a body.
+  materializedRows: {
+    prior: RUNTIME_MEMORY_LEDGER_OBJECT_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_MAX_FACTOR,
+  },
+  // Live-run events buffered as objects until egress serializes them.
+  eventBuffer: {
+    prior: RUNTIME_MEMORY_LEDGER_OBJECT_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_MAX_FACTOR,
+  },
+  // The buffered receipt's output is, for a mapped tool call, the same graph
+  // already charged at object rate under `providerBody`; charging it again at
+  // object rate double-counts one retained object. What the buffer adds is the
+  // receipt envelope around it, so it starts at the text prior. The band stays
+  // open to 6 because a receipt the runtime built itself is a real graph.
+  receiptCompletionBuffer: {
+    prior: RUNTIME_MEMORY_LEDGER_RAW_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_MAX_FACTOR,
+  },
+  // A hydration turn reserves the wire size it is about to read and holds the
+  // response text across the gateway round trip, then expands it. It opens at
+  // the text prior and the fit carries it up if the expansion is what a turn
+  // actually holds.
+  hydrationReadBack: {
+    prior: RUNTIME_MEMORY_LEDGER_RAW_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_MAX_FACTOR,
+  },
+  // A response or receipt-completion request JSON string, and nothing but a
+  // string. It cannot honestly read above 2.5.
+  transportInFlight: {
+    prior: RUNTIME_MEMORY_LEDGER_RAW_PRIOR_FACTOR,
+    min: RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+    max: RUNTIME_MEMORY_LEDGER_RAW_MAX_FACTOR,
+  },
+};
+
+export type RuntimeMemoryLedgerHandle = {
+  /** Resize this entry in place; a gauge (a buffer, a growing cache). */
+  update(bytes: number): void;
+  /** Drop the entry. Idempotent: a double release is not a double subtract. */
+  release(): void;
+};
+
+export type RuntimeMemoryLedgerSnapshot = {
+  bytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+  /** Per-category high-water marks. These are independent maxima. */
+  peakBytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+  /** Registered bytes the runtime still holds. */
+  liveBytes: number;
+  livePeakBytes: number;
+  /** Registered, unreleased entries. */
+  liveEntries: number;
+  /** Owners registered and not yet settled. */
+  ownersActive: number;
+  /** Owners settled over the ledger's lifetime. */
+  ownersSettled: number;
+  /** Settled owner peaks currently in the reservoir. */
+  ownerPeakSamples: number;
+  ownerPeakBytesP50: number | null;
+  ownerPeakBytesP90: number | null;
+  /**
+   * Per-category p90s from the same uniform settled-owner reservoir as the
+   * aggregate owner peak. This identifies the representation that priced a
+   * row reserve after the live ledger has drained.
+   */
+  ownerPeakBytesByCategoryP90: Record<
+    RuntimeMemoryLedgerCategory,
+    number | null
+  >;
+  /**
+   * The mix-weighted live bytes per ledger byte this ledger currently implies:
+   * `predictedLiveBytes / liveBytes`. It is a readout of the prediction, not
+   * the thing that is fitted — `categoryFactors` is. With nothing registered
+   * it reports the `providerBody` factor, the one that prices a row.
+   */
+  calibrationFactor: number;
+  calibrationSamples: number;
+  /** Live bytes per ledger byte, fitted per category. */
+  categoryFactors: Record<RuntimeMemoryLedgerCategory, number>;
+  /** Samples that were allowed to move each category's factor. */
+  categoryCalibrationSamples: Record<RuntimeMemoryLedgerCategory, number>;
+  /** `bytesByCategory` x `categoryFactors`, the prediction's own breakdown. */
+  predictedBytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+  /** Category composition at the instant the global predicted peak occurred. */
+  predictedPeakBytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+  /** Sum over categories of bytes x factor: the live footprint predicted. */
+  predictedLiveBytes: number;
+  /** High-water mark of `predictedLiveBytes` over this ledger's life. */
+  predictedLivePeakBytes: number;
+  /** heapUsed + external at the last calibration, or null before the first. */
+  observedLiveBytes: number | null;
+  /** Largest collected observation so far: the peak a prediction is judged against. */
+  observedCollectedPeakBytes: number | null;
+  /**
+   * The prediction the runtime was holding at the instant `observedCollected
+   * PeakBytes` was read, before that reading was allowed to move any factor.
+   *
+   * This is the only honest partner for the observed peak. `livePeakBytes x
+   * calibrationFactor` multiplies a ledger peak by a factor fitted later,
+   * against an observation taken at a third moment; the three need not
+   * coincide and on the jai fixture they did not, which is most of a 2.5x
+   * "divergence" that was never a prediction error. Excludes the baseline, the
+   * same as `predictedLiveBytes`.
+   */
+  predictedAtObservedPeakBytes: number | null;
+  /** Ledger bytes registered at that same instant, for the same reason. */
+  ledgerBytesAtObservedPeak: number | null;
+  /**
+   * The full p90 row reservations for rows already admitted at that same
+   * instant. These rows can be executing or waiting on a receipt before they
+   * have registered a body, so they are real retained-risk not ledger bytes.
+   */
+  admittedRowReserveBytesAtObservedPeak: number | null;
+  baselineBytes: number | null;
+};
+
+export type RuntimeMemoryLedger = {
+  register(input: {
+    category: RuntimeMemoryLedgerCategory;
+    ownerId?: string | null;
+    bytes: number;
+  }): RuntimeMemoryLedgerHandle;
+  /**
+   * Record an owner's peak into the settled reservoir and drop every entry it
+   * still holds. Called when a row's record is durable: from that point the
+   * runtime is entitled to hold none of the row's bytes, and anything it does
+   * hold is a leak the audit test is meant to catch.
+   */
+  settleOwner(ownerId: string): number | null;
+  /** Bytes currently registered to an owner, or null if it is not tracked. */
+  ownerBytes(ownerId: string): number | null;
+  /**
+   * Fit the ledger to the process. `observedLiveBytes` is heapUsed + external
+   * from the same probe that paces admission; `baselineBytes` is the reading
+   * taken before the first row was admitted.
+   */
+  calibrate(input: {
+    observedLiveBytes: number;
+    baselineBytes: number | null;
+    /**
+     * Full live-byte reservations for rows already admitted but not yet
+     * necessarily represented in the ledger. This is an input from map
+     * admission, not a new ledger category, because it is a conservative
+     * promise about in-flight work rather than a retained object.
+     */
+    admittedRowReserveBytes?: number;
+  }): void;
+  snapshot(): RuntimeMemoryLedgerSnapshot;
+};
+
+type LedgerEntry = {
+  category: RuntimeMemoryLedgerCategory;
+  ownerId: string | null;
+  bytes: number;
+  released: boolean;
+};
+
+type OwnerState = {
+  bytes: number;
+  peakBytes: number;
+  bytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+  peakBytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+  entries: Set<LedgerEntry>;
+};
+
+type SettledOwnerPeak = {
+  bytes: number;
+  bytesByCategory: Record<RuntimeMemoryLedgerCategory, number>;
+};
+
+export function createRuntimeMemoryLedger(options?: {
+  settledReservoirSize?: number;
+  calibrationFloorBytes?: number;
+  calibrationAlpha?: number;
+  /** Overrides every category prior; see the note where it is read. */
+  initialFactor?: number;
+  /** Overrides every category's lower band. */
+  minFactor?: number;
+  /** Overrides every category's upper band. */
+  maxFactor?: number;
+  /** Minimum share of the prediction a category needs to learn from a probe. */
+  categoryShareFloor?: number;
+  /**
+   * Uniform [0, 1) source for the settled-peak reservoir. Injected only so a
+   * test can state an exact eviction sequence; the runtime uses `Math.random`.
+   */
+  random?: () => number;
+}): RuntimeMemoryLedger {
+  const random = typeof options?.random === 'function' ? options.random : null;
+  const uniform = (): number => {
+    const value = random ? random() : Math.random();
+    return Number.isFinite(value)
+      ? Math.min(0.999999999, Math.max(0, value))
+      : 0;
+  };
+  const reservoirSize = positiveInteger(
+    options?.settledReservoirSize,
+    RUNTIME_MEMORY_LEDGER_SETTLED_RESERVOIR_SIZE,
+  );
+  const calibrationFloorBytes = positiveInteger(
+    options?.calibrationFloorBytes,
+    RUNTIME_MEMORY_LEDGER_CALIBRATION_FLOOR_BYTES,
+  );
+  const alpha = finiteInRange(
+    options?.calibrationAlpha,
+    RUNTIME_MEMORY_LEDGER_CALIBRATION_ALPHA,
+    0,
+    1,
+  );
+  const minFactor = positiveFinite(
+    options?.minFactor,
+    RUNTIME_MEMORY_LEDGER_MIN_FACTOR,
+  );
+  const maxFactor = Math.max(
+    minFactor,
+    positiveFinite(options?.maxFactor, RUNTIME_MEMORY_LEDGER_MAX_FACTOR),
+  );
+  const categoryShareFloor = finiteInRange(
+    options?.categoryShareFloor,
+    RUNTIME_MEMORY_LEDGER_CATEGORY_SHARE_FLOOR,
+    0,
+    1,
+  );
+  const bytesByCategory = emptyCategoryTotals();
+  const peakBytesByCategory = emptyCategoryTotals();
+  const owners = new Map<string, OwnerState>();
+  const settledPeaks: SettledOwnerPeak[] = [];
+
+  /**
+   * Keep a uniform sample of settled row peaks.
+   *
+   * Vitter's Algorithm R: the n-th settled owner takes a slot with probability
+   * reservoirSize/n, so the sample stays uniform over every row the map has
+   * settled.
+   *
+   * A ring buffer here kept the last `reservoirSize` peaks instead, and rows do
+   * not settle in the order they were admitted. Jai's 1,000-row fixture opens
+   * all of its rows at once and its three cohorts settle at wildly different
+   * speeds — person search averaged ~129 s per call against ~20 s for the agent
+   * cohort — so the last 256 rows to settle were all person rows, whose bodies
+   * are ~920 B, while the ~1 MB agent rows had all aged out. The p90 that
+   * prices admission read 920 B, and the same map at 100 rows (reservoir never
+   * full) read 992 KB from the same shape. A recency-biased sample is not a
+   * sample of the map.
+   */
+  /**
+   * Percentiles over `settledPeaks`, computed on demand.
+   *
+   * `snapshot()` reports nine of them - p50, p90, and a p90 per category - and
+   * each one used to copy the reservoir and sort it. Map row admission
+   * reconciles once per settled row and snapshots twice per reconcile, so a
+   * million-row map paid roughly eighteen million sorts of a 256-element
+   * array, which was the whole of its throughput regression. The reservoir
+   * changes only in `recordSettledPeak`, so the answer is stable between
+   * writes and is cached until one lands.
+   */
+  let settledPeakPercentiles: {
+    p50: number | null;
+    p90: number | null;
+    byCategory: Record<RuntimeMemoryLedgerCategory, number | null>;
+  } | null = null;
+
+  function settledPeakPercentileView(): {
+    ownerPeakBytesP50: number | null;
+    ownerPeakBytesP90: number | null;
+    ownerPeakBytesByCategoryP90: Record<
+      RuntimeMemoryLedgerCategory,
+      number | null
+    >;
+  } {
+    if (!settledPeakPercentiles) {
+      const bytes = settledPeaks.map((peak) => peak.bytes);
+      settledPeakPercentiles = {
+        p50: percentile(bytes, 0.5),
+        p90: percentile(bytes, 0.9),
+        byCategory: Object.fromEntries(
+          RUNTIME_MEMORY_LEDGER_CATEGORIES.map((category) => [
+            category,
+            percentile(
+              settledPeaks.map((peak) => peak.bytesByCategory[category]),
+              0.9,
+            ),
+          ]),
+        ) as Record<RuntimeMemoryLedgerCategory, number | null>,
+      };
+    }
+    return {
+      ownerPeakBytesP50: settledPeakPercentiles.p50,
+      ownerPeakBytesP90: settledPeakPercentiles.p90,
+      // Copied so a caller cannot mutate the cache it shares with the ledger.
+      ownerPeakBytesByCategoryP90: { ...settledPeakPercentiles.byCategory },
+    };
+  }
+
+  function recordSettledPeak(settledPeak: SettledOwnerPeak): void {
+    settledPeakPercentiles = null;
+    if (settledPeaks.length < reservoirSize) {
+      settledPeaks.push(settledPeak);
+      return;
+    }
+    const slot = Math.floor(uniform() * ownersSettled);
+    if (slot < reservoirSize) settledPeaks[slot] = settledPeak;
+  }
+  let liveBytes = 0;
+  let livePeakBytes = 0;
+  let liveEntries = 0;
+  let ownersSettled = 0;
+  // An explicit `initialFactor` overrides every category prior: a caller that
+  // states one is stating the whole model, and silently keeping six different
+  // priors underneath it would make the option a lie.
+  const initialFactorOverride =
+    options?.initialFactor === undefined ||
+    !Number.isFinite(options.initialFactor) ||
+    options.initialFactor <= 0
+      ? null
+      : options.initialFactor;
+  const categoryBand = (
+    category: RuntimeMemoryLedgerCategory,
+  ): { min: number; max: number } => {
+    const band = RUNTIME_MEMORY_LEDGER_CATEGORY_EXPANSION[category];
+    const min = options?.minFactor === undefined ? band.min : minFactor;
+    const max = Math.max(
+      min,
+      options?.maxFactor === undefined ? band.max : maxFactor,
+    );
+    return { min, max };
+  };
+  const categoryFactors = {} as Record<RuntimeMemoryLedgerCategory, number>;
+  const categoryCalibrationSamples = emptyCategoryTotals();
+  for (const category of RUNTIME_MEMORY_LEDGER_CATEGORIES) {
+    const band = categoryBand(category);
+    categoryFactors[category] = clamp(
+      initialFactorOverride ??
+        RUNTIME_MEMORY_LEDGER_CATEGORY_EXPANSION[category].prior,
+      band.min,
+      band.max,
+    );
+  }
+  let predictedLivePeakBytes = 0;
+  const predictedPeakBytesByCategory = emptyCategoryTotals();
+  let calibrationSamples = 0;
+  let observedLiveBytes: number | null = null;
+  let observedCollectedPeakBytes: number | null = null;
+  let predictedAtObservedPeakBytes: number | null = null;
+  let ledgerBytesAtObservedPeak: number | null = null;
+  let admittedRowReserveBytesAtObservedPeak: number | null = null;
+  let baselineBytes: number | null = null;
+
+  /** Sum over categories of registered bytes times that category's factor. */
+  const predictedLiveBytesNow = (): number => {
+    let total = 0;
+    for (const category of RUNTIME_MEMORY_LEDGER_CATEGORIES) {
+      total += bytesByCategory[category] * categoryFactors[category];
+    }
+    return total;
+  };
+
+  const recordPredictedPeak = (): void => {
+    const predicted = predictedLiveBytesNow();
+    if (predicted < predictedLivePeakBytes) return;
+    predictedLivePeakBytes = predicted;
+    for (const category of RUNTIME_MEMORY_LEDGER_CATEGORIES) {
+      predictedPeakBytesByCategory[category] = Math.round(
+        bytesByCategory[category] * categoryFactors[category],
+      );
+    }
+  };
+
+  const applyDelta = (entry: LedgerEntry, deltaBytes: number): void => {
+    if (deltaBytes === 0) return;
+    bytesByCategory[entry.category] = Math.max(
+      0,
+      bytesByCategory[entry.category] + deltaBytes,
+    );
+    peakBytesByCategory[entry.category] = Math.max(
+      peakBytesByCategory[entry.category],
+      bytesByCategory[entry.category],
+    );
+    liveBytes = Math.max(0, liveBytes + deltaBytes);
+    livePeakBytes = Math.max(livePeakBytes, liveBytes);
+    recordPredictedPeak();
+    if (entry.ownerId === null) return;
+    const owner = owners.get(entry.ownerId);
+    if (!owner) return;
+    owner.bytes = Math.max(0, owner.bytes + deltaBytes);
+    owner.peakBytes = Math.max(owner.peakBytes, owner.bytes);
+    owner.bytesByCategory[entry.category] = Math.max(
+      0,
+      owner.bytesByCategory[entry.category] + deltaBytes,
+    );
+    owner.peakBytesByCategory[entry.category] = Math.max(
+      owner.peakBytesByCategory[entry.category],
+      owner.bytesByCategory[entry.category],
+    );
+  };
+
+  const releaseEntry = (entry: LedgerEntry): void => {
+    if (entry.released) return;
+    entry.released = true;
+    liveEntries = Math.max(0, liveEntries - 1);
+    applyDelta(entry, -entry.bytes);
+    entry.bytes = 0;
+    if (entry.ownerId !== null) {
+      owners.get(entry.ownerId)?.entries.delete(entry);
+    }
+  };
+
+  return {
+    register({ category, ownerId, bytes }) {
+      const normalizedBytes = requireByteCount(bytes);
+      if (!RUNTIME_MEMORY_LEDGER_CATEGORIES.includes(category)) {
+        throw new RangeError(
+          `Runtime memory ledger received an unknown category "${String(category)}".`,
+        );
+      }
+      const normalizedOwnerId =
+        typeof ownerId === 'string' && ownerId.length > 0 ? ownerId : null;
+      const entry: LedgerEntry = {
+        category,
+        ownerId: normalizedOwnerId,
+        bytes: 0,
+        released: false,
+      };
+      liveEntries += 1;
+      if (normalizedOwnerId !== null) {
+        let owner = owners.get(normalizedOwnerId);
+        if (!owner) {
+          owner = {
+            bytes: 0,
+            peakBytes: 0,
+            bytesByCategory: emptyCategoryTotals(),
+            peakBytesByCategory: emptyCategoryTotals(),
+            entries: new Set(),
+          };
+          owners.set(normalizedOwnerId, owner);
+        }
+        owner.entries.add(entry);
+      }
+      entry.bytes = normalizedBytes;
+      applyDelta(entry, normalizedBytes);
+      return {
+        update(nextBytes) {
+          if (entry.released) return;
+          const normalizedNext = requireByteCount(nextBytes);
+          const delta = normalizedNext - entry.bytes;
+          entry.bytes = normalizedNext;
+          applyDelta(entry, delta);
+        },
+        release() {
+          releaseEntry(entry);
+        },
+      };
+    },
+
+    settleOwner(ownerId) {
+      const owner = owners.get(ownerId);
+      if (!owner) {
+        // A row settles here whether or not it ever registered tracked bytes.
+        // An owner is created lazily on the first tracked allocation, so a
+        // stage that performs only local work — no provider bodies — has none.
+        // Recording nothing leaves that stage with zero footprint samples, and
+        // an unmeasured reserve falls back to the conservative default. A map
+        // that provably holds nothing per row is then priced as if it held
+        // megabytes, and its admission concurrency is throttled for memory it
+        // never uses. "This row held nothing" is a measurement, not missing
+        // data, so record it as a zero-byte peak.
+        ownersSettled += 1;
+        recordSettledPeak({ bytes: 0, bytesByCategory: emptyCategoryTotals() });
+        // The return value still reports "no owner was tracked", which is what
+        // callers branch on; only the sample is new.
+        return null;
+      }
+      owners.delete(ownerId);
+      for (const entry of [...owner.entries]) {
+        releaseEntry(entry);
+      }
+      ownersSettled += 1;
+      recordSettledPeak({
+        bytes: owner.peakBytes,
+        bytesByCategory: { ...owner.peakBytesByCategory },
+      });
+      return owner.peakBytes;
+    },
+
+    ownerBytes(ownerId) {
+      return owners.get(ownerId)?.bytes ?? null;
+    },
+
+    calibrate({
+      observedLiveBytes: observed,
+      baselineBytes: baseline,
+      admittedRowReserveBytes: admittedRowReserve = 0,
+    }) {
+      // 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);
+      if (Number.isFinite(observed) && observed >= 0) {
+        observedLiveBytes = observed;
+        if (observed > (observedCollectedPeakBytes ?? -1)) {
+          observedCollectedPeakBytes = observed;
+          // An admission reserve bounds what an active row may materialize;
+          // it is not itself a retained object. Keep it beside this probe so
+          // readouts can explain an unaccounted gap, but judge the ledger's
+          // prediction only on bytes its owners actually registered.
+          predictedAtObservedPeakBytes = Math.round(predictedBefore);
+          ledgerBytesAtObservedPeak = liveBytes;
+          admittedRowReserveBytesAtObservedPeak = reservedBytes;
+        }
+      }
+      if (baseline != null && Number.isFinite(baseline) && baseline >= 0) {
+        baselineBytes = baseline;
+      }
+      if (observedLiveBytes === null || baselineBytes === null) return;
+      if (liveBytes < calibrationFloorBytes) return;
+      // A row reserve is a conservative admission promise, not evidence that
+      // a category is retaining fewer bytes. Fitting the ledger after
+      // subtracting it taught providerBody to ignore an actually observed
+      // body; recording the reserve above gives diagnostics that distinction
+      // without smuggling it into the retained-byte model.
+      const attributable = observedLiveBytes - baselineBytes;
+      if (!(attributable > 0)) return;
+      if (!(predictedBefore > 0)) return;
+      calibrationSamples += 1;
+      // One heap reading is one equation in as many unknowns as there are
+      // categories holding bytes, so it is not solved — it is descended.
+      // Each category is nudged toward the reading in proportion to how much
+      // of the prediction it was responsible for, which is exactly the
+      // gradient of the squared error in log-factor space. A probe taken while
+      // response text dominates therefore moves `transportInFlight` and barely
+      // touches `providerBody`, and a probe taken while parsed bodies dominate
+      // does the reverse. Under a mix that never varies the factors keep their
+      // priors' ratio, which is the correct answer to a question the data
+      // cannot distinguish.
+      const ratio = attributable / predictedBefore;
+      for (const category of RUNTIME_MEMORY_LEDGER_CATEGORIES) {
+        const bytes = bytesByCategory[category];
+        if (bytes <= 0) continue;
+        const share = (bytes * categoryFactors[category]) / predictedBefore;
+        if (share < categoryShareFloor) continue;
+        categoryCalibrationSamples[category] += 1;
+        const band = categoryBand(category);
+        categoryFactors[category] = clamp(
+          categoryFactors[category] * (1 + alpha * share * (ratio - 1)),
+          band.min,
+          band.max,
+        );
+      }
+      recordPredictedPeak();
+    },
+
+    snapshot() {
+      const predictedBytesByCategory = emptyCategoryTotals();
+      for (const category of RUNTIME_MEMORY_LEDGER_CATEGORIES) {
+        predictedBytesByCategory[category] = Math.round(
+          bytesByCategory[category] * categoryFactors[category],
+        );
+      }
+      const predictedLiveBytes = predictedLiveBytesNow();
+      return {
+        bytesByCategory: { ...bytesByCategory },
+        peakBytesByCategory: { ...peakBytesByCategory },
+        liveBytes,
+        livePeakBytes,
+        liveEntries,
+        ownersActive: owners.size,
+        ownersSettled,
+        ownerPeakSamples: settledPeaks.length,
+        ...settledPeakPercentileView(),
+        calibrationFactor:
+          liveBytes > 0
+            ? predictedLiveBytes / liveBytes
+            : categoryFactors.providerBody,
+        calibrationSamples,
+        categoryFactors: { ...categoryFactors },
+        categoryCalibrationSamples: { ...categoryCalibrationSamples },
+        predictedBytesByCategory,
+        predictedPeakBytesByCategory: { ...predictedPeakBytesByCategory },
+        predictedLiveBytes: Math.round(predictedLiveBytes),
+        predictedLivePeakBytes: Math.round(predictedLivePeakBytes),
+        observedLiveBytes,
+        observedCollectedPeakBytes,
+        predictedAtObservedPeakBytes,
+        ledgerBytesAtObservedPeak,
+        admittedRowReserveBytesAtObservedPeak,
+        baselineBytes,
+      };
+    },
+  };
+}
+
+const ledgerTextEncoder =
+  typeof TextEncoder === 'undefined' ? null : new TextEncoder();
+
+/**
+ * Serialized size of a value, in the unit every ledger entry is stated in.
+ *
+ * It lives here rather than beside map admission because every site that
+ * registers bytes needs it, including receipt hydration, which must not pull
+ * `node:v8` or `node:perf_hooks` into its module graph to ask how big a
+ * payload is.
+ */
+export function runtimeJsonByteLength(value: unknown): number {
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) return 0;
+  return ledgerTextEncoder?.encode(serialized).byteLength ?? serialized.length;
+}
+
+/** Nearest-rank percentile. A reservoir of settled peaks is never large. */
+export function percentile(
+  values: readonly number[],
+  fraction: number,
+): number | null {
+  if (values.length === 0) return null;
+  const sorted = [...values].sort((left, right) => left - right);
+  const rank = Math.ceil(fraction * sorted.length);
+  const index = Math.min(sorted.length - 1, Math.max(0, rank - 1));
+  return sorted[index] ?? null;
+}
+
+function emptyCategoryTotals(): Record<RuntimeMemoryLedgerCategory, number> {
+  const totals = {} as Record<RuntimeMemoryLedgerCategory, number>;
+  for (const category of RUNTIME_MEMORY_LEDGER_CATEGORIES) {
+    totals[category] = 0;
+  }
+  return totals;
+}
+
+/**
+ * A byte count that is not a finite, non-negative number is a defect at the
+ * call site, not a value to be coerced: silently rounding it to zero is how a
+ * ledger stops accounting for the bytes that kill the sandbox.
+ */
+function requireByteCount(bytes: number): number {
+  if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0) {
+    throw new RangeError(
+      `Runtime memory ledger requires a finite, non-negative byte count; received ${String(bytes)}.`,
+    );
+  }
+  return Math.ceil(bytes);
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+function positiveInteger(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return Math.max(1, Math.floor(value));
+}
+
+function positiveFinite(value: number | undefined, fallback: number): number {
+  if (value === undefined || !Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+  return value;
+}
+
+function finiteInRange(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return clamp(value, min, max);
+}