@iislee/opencodex 2.11.0

package/src/lib/abort.ts

@@ -0,0 +1,146 @@
+export interface LinkedAbortSignal {
+  signal: AbortSignal;
+  cleanup: () => void;
+}
+
+export interface ClearableDeadline {
+  /** Parent-linked signal passed to fetch; remains parent-linked after clear(). */
+  signal: AbortSignal;
+  /** Stable reason object used when this deadline wins the abort race. */
+  timeoutReason: DOMException;
+  /** True only when this deadline, rather than the parent, fired first. */
+  didExpire: () => boolean;
+  /** Clear only the timer. Never aborts the deadline controller or detaches the parent. */
+  clear: () => void;
+}
+
+export interface IdleDeadline {
+  /** (Re-)arm the timer for one idle window. Call when a wait for progress BEGINS. No-op after fire/cancel. */
+  reset: () => void;
+  /** Disarm the timer WITHOUT retiring the deadline (call when the awaited progress arrives). No-op after fire/cancel. */
+  pause: () => void;
+  /** Retire permanently (success/teardown paths). Idempotent. */
+  cancel: () => void;
+}
+
+/**
+ * Resettable inactivity deadline (devlog 260716_passthrough_followups/010).
+ *
+ * Fires `onIdle` at most ONCE after `idleMs` elapses with no `reset()`/`pause()`.
+ * Contract:
+ * - `idleMs <= 0` returns an inert no-op deadline — the 0-disable responsibility
+ *   lives here so callers cannot mis-handle it.
+ * - The timer starts DISARMED: callers arm it with `reset()` when a wait begins and
+ *   `pause()` it when the wait settles, so pull-based relays never count downstream
+ *   backpressure (no pending read) as upstream inactivity.
+ * - First terminal wins: after `onIdle` runs or `cancel()` is called, every method
+ *   is a no-op and `onIdle` never runs again.
+ * - Never linked to fetch signals — the consumer decides how to kill its stream
+ *   (e.g. reader.cancel), keeping body-lifetime semantics unchanged.
+ */
+export function idleDeadline(idleMs: number, onIdle: () => void): IdleDeadline {
+  if (idleMs <= 0) return { reset: () => {}, pause: () => {}, cancel: () => {} };
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let done = false;
+  const disarm = () => {
+    if (timer !== undefined) clearTimeout(timer);
+    timer = undefined;
+  };
+  return {
+    reset: () => {
+      if (done) return;
+      disarm();
+      timer = setTimeout(() => {
+        if (done) return;
+        done = true;
+        timer = undefined;
+        onIdle();
+      }, idleMs);
+    },
+    pause: () => {
+      if (done) return;
+      disarm();
+    },
+    cancel: () => {
+      if (done) return;
+      done = true;
+      disarm();
+    },
+  };
+}
+
+/**
+ * Response-header deadline whose timer can be cleared without severing body-lifetime cancellation.
+ *
+ * `signalWithTimeout().cleanup()` intentionally removes its parent listener and is therefore suited
+ * to operations that are completely finished at cleanup. A fetch response body is different: once
+ * headers arrive the deadline ends, but the original parent/client signal must remain attached to
+ * the body. `AbortSignal.any()` supplies that direct lifetime link while `clear()` owns only the
+ * timer.
+ */
+export function clearableDeadline(timeoutMs: number, parent?: AbortSignal): ClearableDeadline {
+  const deadline = new AbortController();
+  const timeoutReason = new DOMException("Timeout elapsed", "TimeoutError");
+  let timer: ReturnType<typeof setTimeout> | undefined = setTimeout(() => {
+    timer = undefined;
+    if (!deadline.signal.aborted) deadline.abort(timeoutReason);
+  }, timeoutMs);
+  const signal = parent ? AbortSignal.any([parent, deadline.signal]) : deadline.signal;
+
+  return {
+    signal,
+    timeoutReason,
+    didExpire: () => signal.aborted && signal.reason === timeoutReason,
+    clear: () => {
+      if (timer !== undefined) clearTimeout(timer);
+      timer = undefined;
+    },
+  };
+}
+
+export function signalWithTimeout(timeoutMs: number, parent?: AbortSignal): LinkedAbortSignal {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => {
+    if (!controller.signal.aborted) controller.abort(new DOMException("Timeout elapsed", "TimeoutError"));
+  }, timeoutMs);
+
+  const abortFromParent = () => {
+    if (!controller.signal.aborted) controller.abort(parent?.reason);
+  };
+
+  if (parent?.aborted) {
+    abortFromParent();
+  } else {
+    parent?.addEventListener("abort", abortFromParent, { once: true });
+  }
+
+  return {
+    signal: controller.signal,
+    cleanup: () => {
+      clearTimeout(timeout);
+      parent?.removeEventListener("abort", abortFromParent);
+    },
+  };
+}
+
+/**
+ * Bind a response body's lifetime to an abort signal.
+ *
+ * Bun's HTTP client, when a `fetch(..., { signal })` is aborted AFTER the response resolved, tears
+ * down the response body stream and rejects any in-flight internal read. If our code hasn't attached
+ * a reader yet (e.g. the abort lands between `await fetch()` and the decoder's first read), that
+ * rejection is orphaned off the awaited path and Bun reports it as
+ * `unhandledRejection: TypeError: null is not an object` (native-only stack) — uncatchable by any
+ * caller try/catch. Proactively cancelling the body on abort makes US the consumer that settles it,
+ * so the rejection is absorbed. Returns a cleanup to detach the listener on the normal path.
+ */
+export function cancelBodyOnAbort(body: ReadableStream<Uint8Array> | null, signal?: AbortSignal): () => void {
+  if (!body || !signal) return () => {};
+  const onAbort = () => { void body.cancel().catch(() => {}); };
+  if (signal.aborted) {
+    onAbort();
+    return () => {};
+  }
+  signal.addEventListener("abort", onAbort, { once: true });
+  return () => signal.removeEventListener("abort", onAbort);
+}

package/src/lib/admin-secrets.ts

@@ -0,0 +1,25 @@
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+
+export const ADMIN_TOKEN_FILE = "admin-api-token";
+
+export function adminApiTokenFilePath(configDir = getConfigDir()): string {
+  return join(configDir, ADMIN_TOKEN_FILE);
+}
+
+export function loadAdminTokenFromFile(configDir = getConfigDir()): string | null {
+  const path = adminApiTokenFilePath(configDir);
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 512) return null;
+    const token = readFileSync(path, "utf8").trim();
+    return /^ocx_admin_[A-Za-z0-9_-]{43}$/.test(token) ? token : null;
+  } catch {
+    return null;
+  }
+}
+
+export function configuredAdminToken(configDir = getConfigDir(), env: NodeJS.ProcessEnv = process.env): string | null {
+  return env.OPENCODEX_ADMIN_AUTH_TOKEN?.trim() || loadAdminTokenFromFile(configDir);
+}

package/src/lib/admission.ts

@@ -0,0 +1,83 @@
+export const RETAINED_TRUNCATION_MARKER = "\n…[truncated by opencodex]";
+
+export class ResourceAdmissionError extends Error {
+  readonly code: string = "server_busy";
+
+  constructor(readonly resource: string, readonly limit: number) {
+    super(`${resource} capacity reached (${limit})`);
+    this.name = "ResourceAdmissionError";
+  }
+}
+
+export interface AdmissionMetrics {
+  active: number;
+  peak: number;
+  admitted: number;
+  rejected: number;
+  releaseMisses: number;
+}
+
+export interface AdmissionLease {
+  release(): void;
+}
+
+export interface AdmissionReservation<T> extends AdmissionLease {
+  bind(value: T): void;
+}
+
+export function createAdmissionGate(name: string, limit: number): {
+  tryAcquire(): AdmissionLease | null;
+  metrics(): Readonly<AdmissionMetrics>;
+} {
+  if (!Number.isSafeInteger(limit) || limit < 1) throw new RangeError(`${name} admission limit must be positive`);
+  const state: AdmissionMetrics = { active: 0, peak: 0, admitted: 0, rejected: 0, releaseMisses: 0 };
+  return {
+    tryAcquire() {
+      if (state.active >= limit) {
+        state.rejected += 1;
+        return null;
+      }
+      state.active += 1;
+      state.admitted += 1;
+      state.peak = Math.max(state.peak, state.active);
+      let active = true;
+      return {
+        release() {
+          if (!active) {
+            return;
+          }
+          active = false;
+          state.active -= 1;
+        },
+      };
+    },
+    metrics() {
+      return { ...state };
+    },
+  };
+}
+
+export function retainedUtf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function utf8Prefix(value: string, maxBytes: number): string {
+  if (maxBytes <= 0) return "";
+  let bytes = 0;
+  let result = "";
+  for (const character of value) {
+    const size = retainedUtf8Bytes(character);
+    if (bytes + size > maxBytes) break;
+    result += character;
+    bytes += size;
+  }
+  return result;
+}
+
+export function truncateRetainedUtf8(value: string, maxBytes: number): string {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) throw new RangeError("maxBytes must be a non-negative integer");
+  if (retainedUtf8Bytes(value) <= maxBytes) return value;
+  const markerBytes = retainedUtf8Bytes(RETAINED_TRUNCATION_MARKER);
+  if (markerBytes > maxBytes) return utf8Prefix(RETAINED_TRUNCATION_MARKER, maxBytes);
+  return utf8Prefix(value, maxBytes - markerBytes) + RETAINED_TRUNCATION_MARKER;
+}

package/src/lib/app-owned-memory-stores.ts

@@ -0,0 +1,173 @@
+import {
+  enforceAppOwnedMemoryBudget,
+  registerRetainedStore,
+  registerObservedBuffer,
+  type RetainedStoreRegistration,
+  type RetainedStoreSnapshot,
+} from "./app-owned-memory";
+import { registerStateSweepAfterTick } from "./state-store-sweeper";
+import { debugBufferMetrics, evictOldestDebugEntryForBudget } from "./debug-log-buffer";
+import { injectionBufferMetrics, evictOldestInjectionEntryForBudget } from "./injection-debug-log";
+import { crashRingMetrics, evictOldestCrashTraceForBudget } from "./crash-guard";
+import { claudeInboundDebugMetrics, evictOldestClaudeInboundForBudget } from "../claude/inbound-debug";
+import {
+  evictOldestRequestLogForBudget,
+  requestLogRetainedStoreSnapshot,
+} from "../server/request-log";
+import {
+  anthropicImageNormalizeRetainedStoreSnapshot,
+  evictOldestAnthropicImageNormalizeForBudget,
+} from "../adapters/anthropic-image-normalize";
+import {
+  evictOldestVisionDescriptionForBudget,
+  visionDescriptionRetainedStoreSnapshot,
+} from "../vision";
+import {
+  antigravityReplayRetainedStoreSnapshot,
+  evictOldestAntigravityReplayForBudget,
+} from "../adapters/google-antigravity-replay";
+import {
+  evictOldestModelCacheForBudget,
+  modelCacheRetainedStoreSnapshot,
+} from "../codex/model-cache";
+import {
+  evictOldestUsageSummaryForBudget,
+  usageSummaryRetainedStoreSnapshot,
+} from "../server/management/usage-summary-cache";
+import {
+  cursorBlobRetainedStoreSnapshot,
+  evictOldestCursorBlobForBudget,
+} from "../adapters/cursor/native-exec";
+import {
+  evictOldestResponseContinuationForBudget,
+  responseContinuationRetainedStoreSnapshot,
+} from "../responses/state";
+import { translatorObservedBufferSnapshot } from "./translator-budget";
+import { imageFulfillmentTailSnapshot } from "../images/fulfill";
+import { oauthMutationTailSnapshot } from "../oauth/store";
+import { grokApplyFlightSnapshot } from "../server/management/agent-settings-routes";
+
+function ringSnapshot(metrics: { entries: number; bytes: number; oldestAt: number | null }): RetainedStoreSnapshot {
+  return {
+    count: metrics.entries,
+    bytes: metrics.bytes,
+    evictableBytes: metrics.bytes,
+    pinnedBytes: 0,
+    oldestAt: metrics.oldestAt,
+  };
+}
+
+function providerDebugSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(debugBufferMetrics());
+}
+
+function injectionDebugSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(injectionBufferMetrics());
+}
+
+function claudeDebugSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(claudeInboundDebugMetrics());
+}
+
+function crashRingSnapshot(): RetainedStoreSnapshot {
+  return ringSnapshot(crashRingMetrics());
+}
+
+export const APP_OWNED_RETAINED_STORE_REGISTRATIONS = [
+  {
+    id: "request_log",
+    category: "logs",
+    snapshot: requestLogRetainedStoreSnapshot,
+    evictOldest: evictOldestRequestLogForBudget,
+  },
+  {
+    id: "provider_debug",
+    category: "logs",
+    snapshot: providerDebugSnapshot,
+    evictOldest: evictOldestDebugEntryForBudget,
+  },
+  {
+    id: "injection_debug",
+    category: "logs",
+    snapshot: injectionDebugSnapshot,
+    evictOldest: evictOldestInjectionEntryForBudget,
+  },
+  {
+    id: "claude_debug",
+    category: "logs",
+    snapshot: claudeDebugSnapshot,
+    evictOldest: evictOldestClaudeInboundForBudget,
+  },
+  {
+    id: "crash_ring",
+    category: "logs",
+    snapshot: crashRingSnapshot,
+    evictOldest: evictOldestCrashTraceForBudget,
+  },
+  {
+    id: "image_normalize",
+    category: "caches",
+    snapshot: anthropicImageNormalizeRetainedStoreSnapshot,
+    evictOldest: evictOldestAnthropicImageNormalizeForBudget,
+  },
+  {
+    id: "vision_descriptions",
+    category: "caches",
+    snapshot: visionDescriptionRetainedStoreSnapshot,
+    evictOldest: evictOldestVisionDescriptionForBudget,
+  },
+  {
+    id: "antigravity_replay",
+    category: "caches",
+    snapshot: antigravityReplayRetainedStoreSnapshot,
+    evictOldest: evictOldestAntigravityReplayForBudget,
+  },
+  {
+    id: "model_cache",
+    category: "caches",
+    snapshot: modelCacheRetainedStoreSnapshot,
+    evictOldest: evictOldestModelCacheForBudget,
+  },
+  {
+    id: "usage_summary",
+    category: "caches",
+    snapshot: usageSummaryRetainedStoreSnapshot,
+    evictOldest: evictOldestUsageSummaryForBudget,
+  },
+  {
+    id: "cursor_blobs",
+    category: "blobs",
+    snapshot: cursorBlobRetainedStoreSnapshot,
+    evictOldest: evictOldestCursorBlobForBudget,
+  },
+  {
+    id: "responses_continuation",
+    category: "continuation",
+    snapshot: responseContinuationRetainedStoreSnapshot,
+    evictOldest: evictOldestResponseContinuationForBudget,
+  },
+] as const satisfies readonly RetainedStoreRegistration[];
+
+export function registerDefaultAppOwnedMemoryStores(): void {
+  for (const registration of APP_OWNED_RETAINED_STORE_REGISTRATIONS) {
+    registerRetainedStore(registration);
+  }
+}
+
+export const APP_OWNED_OBSERVED_BUFFER_REGISTRATIONS = [
+  { id: "translator_buffers", category: "translator", snapshot: translatorObservedBufferSnapshot },
+  { id: "image_fulfillment_tail", category: "serialized_tails", snapshot: imageFulfillmentTailSnapshot },
+  { id: "oauth_mutation_tail", category: "serialized_tails", snapshot: oauthMutationTailSnapshot },
+  { id: "grok_apply_flight", category: "serialized_tails", snapshot: grokApplyFlightSnapshot },
+] as const;
+
+export function registerDefaultAppOwnedObservedBuffers(): void {
+  for (const registration of APP_OWNED_OBSERVED_BUFFER_REGISTRATIONS) registerObservedBuffer(registration);
+}
+
+export function registerAppOwnedMemorySweepFallback(): void {
+  registerStateSweepAfterTick({
+    name: "app-owned-memory-budget",
+    afterTick: enforceAppOwnedMemoryBudget,
+  });
+}

package/src/lib/app-owned-memory.ts

@@ -0,0 +1,265 @@
+export type AppOwnedRetainedCategory = "logs" | "caches" | "blobs" | "continuation";
+export type AppOwnedObservedCategory = "translator" | "serialized_tails";
+
+export interface RetainedStoreSnapshot {
+  count: number;
+  bytes: number;
+  evictableBytes: number;
+  pinnedBytes: number;
+  oldestAt: number | null;
+}
+
+export interface RetainedStoreRegistration {
+  id: string;
+  category: AppOwnedRetainedCategory;
+  snapshot(): RetainedStoreSnapshot;
+  evictOldest(): number;
+}
+
+export interface ObservedBufferRegistration {
+  id: string;
+  category: AppOwnedObservedCategory;
+  snapshot(): { currentBytes: number; highWaterBytes: number; active: number };
+}
+
+export interface AppOwnedBytesSnapshot {
+  budgetBytes: number;
+  retainedBytes: number;
+  evictableBytes: number;
+  pinnedBytes: number;
+  overBudgetBytes: number;
+  stores: Record<string, RetainedStoreSnapshot>;
+  observedInFlight: Record<string, { currentBytes: number; highWaterBytes: number; active: number }>;
+  enforcement: {
+    runs: number;
+    entriesDemoted: number;
+    bytesReleased: number;
+    noEvictableCandidate: number;
+    snapshotFailures: number;
+    oldestAtContractViolations: number;
+  };
+}
+
+export const DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES = 256 * 1024 * 1024;
+/**
+ * The budget above is an eviction target, not a hard resident limit: active/pinned
+ * state may temporarily keep retained bytes above it. Every pin-capable owner has
+ * its own finite admission cap; their documented aggregate must remain below this
+ * process-owned hard ceiling.
+ */
+export const APP_OWNED_WORST_CASE_PINNED_BYTES = 512 * 1024 * 1024;
+export const MIN_APP_OWNED_MEMORY_BUDGET_MB = 64;
+export const MAX_APP_OWNED_MEMORY_BUDGET_MB = 4_096;
+
+const CATEGORY_ORDER: readonly AppOwnedRetainedCategory[] = [
+  "logs",
+  "caches",
+  "blobs",
+  "continuation",
+];
+const WARN_INTERVAL_MS = 60_000;
+const ZERO_RETAINED_SNAPSHOT: RetainedStoreSnapshot = {
+  count: 0,
+  bytes: 0,
+  evictableBytes: 0,
+  pinnedBytes: 0,
+  oldestAt: null,
+};
+const ZERO_OBSERVED_SNAPSHOT = { currentBytes: 0, highWaterBytes: 0, active: 0 };
+
+const retainedStores = new Map<string, RetainedStoreRegistration>();
+const observedBuffers = new Map<string, ObservedBufferRegistration>();
+let budgetBytes = DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES;
+let lastSaturationWarningAt = Number.NEGATIVE_INFINITY;
+const enforcementCounters = {
+  runs: 0,
+  entriesDemoted: 0,
+  bytesReleased: 0,
+  noEvictableCandidate: 0,
+  snapshotFailures: 0,
+  oldestAtContractViolations: 0,
+};
+let isEnforcing = false;
+
+export function resolveAppOwnedMemoryBudgetBytes(value: unknown): number {
+  return typeof value === "number"
+    && Number.isInteger(value)
+    && value >= MIN_APP_OWNED_MEMORY_BUDGET_MB
+    && value <= MAX_APP_OWNED_MEMORY_BUDGET_MB
+    ? value * 1024 * 1024
+    : DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES;
+}
+
+export function registerRetainedStore(registration: RetainedStoreRegistration): () => void {
+  retainedStores.set(registration.id, registration);
+  return () => {
+    if (retainedStores.get(registration.id) === registration) retainedStores.delete(registration.id);
+  };
+}
+
+export function registerObservedBuffer(registration: ObservedBufferRegistration): () => void {
+  observedBuffers.set(registration.id, registration);
+  return () => {
+    if (observedBuffers.get(registration.id) === registration) observedBuffers.delete(registration.id);
+  };
+}
+
+export function configureAppOwnedMemoryBudget(bytes: number): void {
+  budgetBytes = bytes;
+}
+
+function retainedSnapshot(registration: RetainedStoreRegistration): RetainedStoreSnapshot {
+  try {
+    return registration.snapshot();
+  } catch {
+    enforcementCounters.snapshotFailures += 1;
+    return { ...ZERO_RETAINED_SNAPSHOT };
+  }
+}
+
+function observedSnapshot(
+  registration: ObservedBufferRegistration,
+): { currentBytes: number; highWaterBytes: number; active: number } {
+  try {
+    return registration.snapshot();
+  } catch {
+    enforcementCounters.snapshotFailures += 1;
+    return { ...ZERO_OBSERVED_SNAPSHOT };
+  }
+}
+
+export function appOwnedBytesSnapshot(): AppOwnedBytesSnapshot {
+  return appOwnedBytesSnapshotFrom(retainedSnapshots().stores);
+}
+
+function appOwnedBytesSnapshotFrom(
+  retained: ReadonlyMap<string, RetainedStoreSnapshot>,
+): AppOwnedBytesSnapshot {
+  const stores: Record<string, RetainedStoreSnapshot> = {};
+  let retainedBytes = 0;
+  let evictableBytes = 0;
+  let pinnedBytes = 0;
+  for (const registration of retainedStores.values()) {
+    const snapshot = retained.get(registration.id) ?? ZERO_RETAINED_SNAPSHOT;
+    stores[registration.id] = snapshot;
+    retainedBytes += snapshot.bytes;
+    evictableBytes += snapshot.evictableBytes;
+    pinnedBytes += snapshot.pinnedBytes;
+  }
+
+  const observedInFlight: AppOwnedBytesSnapshot["observedInFlight"] = {};
+  for (const registration of observedBuffers.values()) {
+    observedInFlight[registration.id] = observedSnapshot(registration);
+  }
+
+  return {
+    budgetBytes,
+    retainedBytes,
+    evictableBytes,
+    pinnedBytes,
+    overBudgetBytes: Math.max(0, retainedBytes - budgetBytes),
+    stores,
+    observedInFlight,
+    enforcement: { ...enforcementCounters },
+  };
+}
+
+function nextCandidate(
+  snapshots: ReadonlyMap<string, RetainedStoreSnapshot>,
+  ineligible: Set<string>,
+): RetainedStoreRegistration | undefined {
+  for (const category of CATEGORY_ORDER) {
+    let candidate: RetainedStoreRegistration | undefined;
+    let candidateAt = Number.POSITIVE_INFINITY;
+    for (const registration of retainedStores.values()) {
+      if (registration.category !== category || ineligible.has(registration.id)) continue;
+      const snapshot = snapshots.get(registration.id);
+      if (!snapshot || snapshot.evictableBytes <= 0) continue;
+      const oldestAt = snapshot.oldestAt;
+      if (oldestAt === null || !Number.isFinite(oldestAt)) {
+        enforcementCounters.oldestAtContractViolations += 1;
+        ineligible.add(registration.id);
+        continue;
+      }
+      if (!candidate || oldestAt < candidateAt) {
+        candidate = registration;
+        candidateAt = oldestAt;
+      }
+    }
+    if (candidate) return candidate;
+  }
+  return undefined;
+}
+
+function retainedSnapshots(): { total: number; stores: Map<string, RetainedStoreSnapshot> } {
+  const stores = new Map<string, RetainedStoreSnapshot>();
+  let total = 0;
+  for (const registration of retainedStores.values()) {
+    const snapshot = retainedSnapshot(registration);
+    stores.set(registration.id, snapshot);
+    total += snapshot.bytes;
+  }
+  return { total, stores };
+}
+
+function warnPinnedSaturation(): void {
+  const at = Date.now();
+  if (at - lastSaturationWarningAt < WARN_INTERVAL_MS) return;
+  lastSaturationWarningAt = at;
+  console.warn("[app-owned-memory] retained state remains over budget with no evictable candidate");
+}
+
+export function enforceAppOwnedMemoryBudget(): AppOwnedBytesSnapshot {
+  if (isEnforcing) return appOwnedBytesSnapshot();
+  isEnforcing = true;
+  enforcementCounters.runs += 1;
+  try {
+    const ineligible = new Set<string>();
+    const current = retainedSnapshots();
+    while (current.total > budgetBytes) {
+      const candidate = nextCandidate(current.stores, ineligible);
+      if (!candidate) {
+        enforcementCounters.noEvictableCandidate += 1;
+        warnPinnedSaturation();
+        break;
+      }
+
+      let reportedReleased = 0;
+      try {
+        reportedReleased = candidate.evictOldest();
+      } catch {
+        ineligible.add(candidate.id);
+        continue;
+      }
+      const previousSnapshot = current.stores.get(candidate.id) ?? ZERO_RETAINED_SNAPSHOT;
+      const nextSnapshot = retainedSnapshot(candidate);
+      current.stores.set(candidate.id, nextSnapshot);
+      const nextTotal = Math.max(0, current.total - previousSnapshot.bytes + nextSnapshot.bytes);
+      const actualReleased = Math.max(0, current.total - nextTotal);
+      if (reportedReleased <= 0 || actualReleased <= 0) {
+        ineligible.add(candidate.id);
+      } else {
+        enforcementCounters.entriesDemoted += 1;
+        enforcementCounters.bytesReleased += actualReleased;
+      }
+      current.total = nextTotal;
+    }
+    return appOwnedBytesSnapshotFrom(current.stores);
+  } finally {
+    isEnforcing = false;
+  }
+}
+
+export function resetAppOwnedMemoryForTests(): void {
+  retainedStores.clear();
+  observedBuffers.clear();
+  budgetBytes = DEFAULT_APP_OWNED_MEMORY_BUDGET_BYTES;
+  lastSaturationWarningAt = Number.NEGATIVE_INFINITY;
+  enforcementCounters.runs = 0;
+  enforcementCounters.entriesDemoted = 0;
+  enforcementCounters.bytesReleased = 0;
+  enforcementCounters.noEvictableCandidate = 0;
+  enforcementCounters.snapshotFailures = 0;
+  enforcementCounters.oldestAtContractViolations = 0;
+  isEnforcing = false;
+}