@yansigit/opencodex 2.31.0

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;
+}

package/src/lib/bounded-body.ts

@@ -0,0 +1,346 @@
+/** Maximum number of response-body bytes that may be retained for an error. */
+export const BOUNDED_BODY_MAX_BYTES = 65_536;
+
+/** Default wall-clock and continuous-silence deadlines. */
+export const BOUNDED_BODY_TIMEOUT_MS = 5_000;
+
+export interface BoundedBodyOptions {
+	/** Abort the read with this signal. Its reason is rethrown by identity. */
+	signal?: AbortSignal;
+	/**
+	 * Reject the returned promise with TypeError on malformed or truncated UTF-8
+	 * instead of replacing invalid bytes, including during timeout-path flushes.
+	 * Reader cancellation and lock release still run. Defaults to false.
+	 */
+	fatalUtf8?: boolean;
+	/**
+	 * Byte ceiling for retained body data. Defaults to BOUNDED_BODY_MAX_BYTES (64 KiB),
+	 * which suits error bodies; callers materializing whole success payloads (e.g. a
+	 * non-streaming upstream JSON completion) pass a larger explicit budget.
+	 */
+	maxBytes?: number;
+	/** Total wall-clock deadline. Exposed for focused tests. */
+	totalTimeoutMs?: number;
+	/** Deadline between non-empty raw chunks. Exposed for focused tests. */
+	inactivityTimeoutMs?: number;
+	/** Deadline for the first non-empty raw chunk. Defaults to inactivityTimeoutMs. */
+	firstByteTimeoutMs?: number;
+}
+
+export interface BoundedBodyResult {
+	/** UTF-8 text retained from the response. Empty when the size limit was exceeded. */
+	text: string;
+	/** True when EOF was not observed. */
+	truncated: boolean;
+	/** True for either total-deadline or inactivity-deadline expiry. */
+	timedOut: boolean;
+	/** Distinguishes the wall-clock deadline from an inactivity deadline. */
+	totalTimedOut: boolean;
+	/** True only when continuous inactivity caused the timeout. */
+	inactivityTimedOut: boolean;
+	/** True when the body was observed to exceed the byte cap. */
+	oversized: boolean;
+	/** False means callers should use a status-only fallback, not `text`. */
+	displaySafe: boolean;
+}
+
+export interface BoundedBytesOptions {
+	/** Abort the read with this signal. Its reason is rethrown by identity. */
+	signal?: AbortSignal;
+	/** Maximum number of raw bytes retained from the response body. */
+	maxBytes: number;
+}
+
+export interface BoundedBytesResult {
+	/**
+	 * Exact raw bytes retained from the response. Empty when the cap was exceeded.
+	 *
+	 * This is a view over internal storage, so `bytes.buffer.byteLength` can exceed
+	 * `bytes.byteLength`. Consumers must honor the view's byteOffset and byteLength
+	 * instead of reading or transferring the backing buffer directly.
+	 */
+	bytes: Uint8Array<ArrayBuffer>;
+	/** True when the body was observed to exceed the byte cap. */
+	oversized: boolean;
+}
+
+const TOTAL_TIMEOUT = Symbol("bounded body total timeout");
+const INACTIVITY_TIMEOUT = Symbol("bounded body inactivity timeout");
+
+/**
+ * Test-only instrumentation: how many times the retained buffer was reallocated
+ * during the most recent read. The accumulator grows geometrically, so this is
+ * logarithmic in the body size and independent of how many chunks the peer sends.
+ * The per-chunk array it replaced retained one object per chunk instead, which a
+ * fragmenting peer can inflate far past the payload ceiling — a property no
+ * correctness assertion can see, which is why it is observable here.
+ */
+let bufferGrowthsForTests = 0;
+export function boundedBodyBufferGrowthsForTests(): number {
+	return bufferGrowthsForTests;
+}
+
+function timeoutPromise(ms: number, value: symbol): { promise: Promise<symbol>; clear: () => void } {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const promise = new Promise<symbol>((resolve) => {
+		timer = setTimeout(() => resolve(value), Math.max(0, ms));
+	});
+	return {
+		promise,
+		clear: () => {
+			if (timer !== undefined) clearTimeout(timer);
+		},
+	};
+}
+
+function cancelWithoutWaiting(reader: ReadableStreamDefaultReader<Uint8Array>, reason?: unknown): void {
+	// A hostile/broken stream may reject or never settle cancel(). Neither should
+	// escape as an unhandled rejection or extend this primitive's own deadline.
+	try {
+		void reader.cancel(reason).catch(() => undefined);
+	} catch {
+		// Some stream implementations throw synchronously from cancel().
+	}
+}
+
+/**
+ * Consume the original response body as raw bytes under a strict memory ceiling.
+ *
+ * The caller owns any wall-clock deadline through `signal`, which lets one budget
+ * cover both response headers and body consumption. No decoding, cloning, or teeing
+ * occurs, so arbitrary upstream bytes remain unchanged.
+ */
+export async function readBoundedResponseBytes(
+	response: Response,
+	options: BoundedBytesOptions,
+): Promise<BoundedBytesResult> {
+	const signal = options.signal;
+	if (signal?.aborted) throw signal.reason;
+
+	const body = response.body;
+	if (!body) return { bytes: new Uint8Array(0), oversized: false };
+
+	const reader = body.getReader();
+	const maxBytes = options.maxBytes;
+	let retained = new Uint8Array(Math.min(maxBytes, 64 * 1024));
+	let retainedBytes = 0;
+	let mustCancel = false;
+	let cancelReason: unknown;
+
+	let rejectForAbort: ((reason: unknown) => void) | undefined;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		rejectForAbort = reject;
+	});
+	const onAbort = () => rejectForAbort?.(signal?.reason);
+	signal?.addEventListener("abort", onAbort, { once: true });
+	// Close the narrow race between the preflight check and listener install.
+	if (signal?.aborted) onAbort();
+
+	try {
+		while (true) {
+			const read = reader.read();
+			// Observe a late read rejection when abort/cancellation wins the race.
+			void read.catch(() => undefined);
+			const outcome = await Promise.race([read, aborted]);
+			if (signal?.aborted) {
+				mustCancel = true;
+				cancelReason = signal.reason;
+				throw signal.reason;
+			}
+
+			const { value, done } = outcome;
+			if (done) {
+				return { bytes: retained.subarray(0, retainedBytes), oversized: false };
+			}
+			if (!value || value.byteLength === 0) continue;
+
+			if (value.byteLength > maxBytes - retainedBytes) {
+				mustCancel = true;
+				cancelReason = new DOMException("Response body size limit reached", "QuotaExceededError");
+				retained = new Uint8Array(0);
+				retainedBytes = 0;
+				return { bytes: retained, oversized: true };
+			}
+
+			if (retainedBytes + value.byteLength > retained.length) {
+				const grown = new Uint8Array(
+					Math.min(maxBytes, Math.max(retained.length * 2, retainedBytes + value.byteLength)),
+				);
+				grown.set(retained.subarray(0, retainedBytes));
+				retained = grown;
+			}
+			retained.set(value, retainedBytes);
+			retainedBytes += value.byteLength;
+		}
+	} catch (error) {
+		mustCancel = true;
+		cancelReason = error;
+		throw error;
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+		if (mustCancel) cancelWithoutWaiting(reader, cancelReason);
+		try {
+			reader.releaseLock();
+		} catch {
+			// A pending read can keep the lock briefly while cancel settles.
+		}
+	}
+}
+
+function decodeUtf8(chunks: readonly Uint8Array[], fatal: boolean): string {
+	const decoder = new TextDecoder("utf-8", { fatal });
+	let text = "";
+	for (const chunk of chunks) text += decoder.decode(chunk, { stream: true });
+	// Flush an incomplete trailing UTF-8 sequence deterministically.
+	text += decoder.decode();
+	return text;
+}
+
+/**
+ * Consume the original response body under strict memory and time bounds.
+ *
+ * This deliberately calls `getReader()` on `response.body`: it never clones or
+ * tees the response. Once an over-limit byte is observed, all retained raw data
+ * is discarded so an untrusted prefix can never become a client-facing error.
+ */
+export async function readBoundedResponseBody(
+	response: Response,
+	options: BoundedBodyOptions = {},
+): Promise<BoundedBodyResult> {
+	const signal = options.signal;
+	if (signal?.aborted) throw signal.reason;
+
+	const body = response.body;
+	if (!body) {
+		return {
+			text: "",
+			truncated: false,
+			timedOut: false,
+			totalTimedOut: false,
+			inactivityTimedOut: false,
+			oversized: false,
+			displaySafe: true,
+		};
+	}
+
+	const reader = body.getReader();
+	const maxBytes = options.maxBytes ?? BOUNDED_BODY_MAX_BYTES;
+	// Geometrically growing single buffer: per-chunk arrays would retain one object per
+	// transport chunk, which a hostile peer could inflate into metadata amplification far
+	// beyond the payload ceiling on large budgets.
+	let retained = new Uint8Array(Math.min(maxBytes, 64 * 1024));
+	let retainedBytes = 0;
+	bufferGrowthsForTests = 0;
+	let mustCancel = false;
+	let cancelReason: unknown;
+	const total = timeoutPromise(options.totalTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS, TOTAL_TIMEOUT);
+	let inactivity = timeoutPromise(
+		options.firstByteTimeoutMs ?? options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
+		INACTIVITY_TIMEOUT,
+	);
+
+	let rejectForAbort: ((reason: unknown) => void) | undefined;
+	const aborted = new Promise<never>((_resolve, reject) => {
+		rejectForAbort = reject;
+	});
+	const onAbort = () => rejectForAbort?.(signal?.reason);
+	signal?.addEventListener("abort", onAbort, { once: true });
+	// Close the narrow race between the preflight check and listener install.
+	if (signal?.aborted) onAbort();
+
+	try {
+		while (true) {
+			// Attach a rejection handler before racing. If a deadline wins and
+			// cancellation later rejects this read, it remains observed.
+			const read = reader.read();
+			void read.catch(() => undefined);
+			const outcome = await Promise.race([read, total.promise, inactivity.promise, aborted]);
+			// Cancellation owns the body lifetime even when EOF/readability settles in
+			// the same turn. Promise.race otherwise lets array order hide the abort.
+			if (signal?.aborted) {
+				mustCancel = true;
+				cancelReason = signal.reason;
+				throw signal.reason;
+			}
+
+			if (outcome === TOTAL_TIMEOUT || outcome === INACTIVITY_TIMEOUT) {
+				mustCancel = true;
+				cancelReason = new DOMException(
+					outcome === TOTAL_TIMEOUT ? "Error body total timeout" : "Error body inactivity timeout",
+					"TimeoutError",
+				);
+				return {
+					text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
+					truncated: true,
+					timedOut: true,
+					totalTimedOut: outcome === TOTAL_TIMEOUT,
+					inactivityTimedOut: outcome === INACTIVITY_TIMEOUT,
+					oversized: false,
+					displaySafe: false,
+				};
+			}
+
+			const { value, done } = outcome as ReadableStreamReadResult<Uint8Array>;
+			if (done) {
+				return {
+					text: decodeUtf8([retained.subarray(0, retainedBytes)], options.fatalUtf8 === true),
+					truncated: false,
+					timedOut: false,
+					totalTimedOut: false,
+					inactivityTimedOut: false,
+					oversized: false,
+					displaySafe: true,
+				};
+			}
+
+			if (!value || value.byteLength === 0) continue;
+
+			inactivity.clear();
+			inactivity = timeoutPromise(
+				options.inactivityTimeoutMs ?? BOUNDED_BODY_TIMEOUT_MS,
+				INACTIVITY_TIMEOUT,
+			);
+
+			if (value.byteLength > maxBytes - retainedBytes) {
+				mustCancel = true;
+				cancelReason = new DOMException("Error body size limit reached", "QuotaExceededError");
+				retained = new Uint8Array(0);
+				retainedBytes = 0;
+				return {
+					text: "",
+					truncated: true,
+					timedOut: false,
+					totalTimedOut: false,
+					inactivityTimedOut: false,
+					oversized: true,
+					displaySafe: false,
+				};
+			}
+
+			if (retainedBytes + value.byteLength > retained.length) {
+				const grown = new Uint8Array(
+					Math.min(maxBytes, Math.max(retained.length * 2, retainedBytes + value.byteLength)),
+				);
+				grown.set(retained.subarray(0, retainedBytes));
+				retained = grown;
+				bufferGrowthsForTests += 1;
+			}
+			retained.set(value, retainedBytes);
+			retainedBytes += value.byteLength;
+		}
+	} catch (error) {
+		mustCancel = true;
+		cancelReason = error;
+		throw error;
+	} finally {
+		total.clear();
+		inactivity.clear();
+		signal?.removeEventListener("abort", onAbort);
+		if (mustCancel) cancelWithoutWaiting(reader, cancelReason);
+		try {
+			reader.releaseLock();
+		} catch {
+			// A pending read can keep the lock briefly while cancel settles.
+		}
+	}
+}

package/src/lib/bun-binary-validator.d.mts

@@ -0,0 +1,3 @@
+export declare const REAL_BUN_MIN_BYTES: number;
+
+export declare function isRealBunBinary(path: string): boolean;

package/src/lib/bun-binary-validator.mjs

@@ -0,0 +1,18 @@
+import { existsSync, statSync } from "node:fs";
+
+// The `bun` package leaves a tiny ASCII placeholder at bin/bun.exe until its
+// postinstall downloads the real ~60MB binary. Keep the threshold and the
+// false-on-filesystem-error contract shared by the Node launcher and Bun code.
+export const REAL_BUN_MIN_BYTES = 1_000_000;
+
+/**
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isRealBunBinary(path) {
+  try {
+    return existsSync(path) && statSync(path).size >= REAL_BUN_MIN_BYTES;
+  } catch {
+    return false;
+  }
+}