@nimbus-sh/core 0.4.0 → 0.6.0

package/src/_shared/weighted-credit-pool.ts

@@ -1,244 +0,0 @@
-export interface CreditLease {
-  readonly bytes: number;
-  release(): void;
-}
-
-export interface ResizableCreditLease extends CreditLease {
-  shrinkTo(bytes: number): void;
-}
-
-export interface WeightedCreditPoolStats {
-  readonly current: number;
-  readonly peak: number;
-  readonly queued: number;
-}
-
-export interface WeightedCreditPoolOptions {
-  /**
-   * Requests at or below this size draw from `reserve` instead of the shared
-   * capacity. Omit to keep a single lane.
-   */
-  readonly smallRequestBytes?: number;
-  /**
-   * Bytes set aside for small requests. Held apart from `capacity` so a
-   * full-capacity owner stays grantable and small requests stay servable
-   * while it works.
-   */
-  readonly reserve?: number;
-}
-
-interface CreditWaiter {
-  readonly bytes: number;
-  readonly resolve: (lease: ResizableCreditLease) => void;
-  readonly reject: (error: Error) => void;
-  readonly signal?: AbortSignal;
-  readonly onAbort?: () => void;
-}
-
-/** One FIFO queue over one byte capacity. */
-class CreditLane {
-  private current = 0;
-  private peak = 0;
-  private readonly waiters: CreditWaiter[] = [];
-
-  constructor(readonly capacity: number) {}
-
-  get stats(): WeightedCreditPoolStats {
-    return { current: this.current, peak: this.peak, queued: this.waiters.length };
-  }
-
-  tryAcquire(bytes: number): ResizableCreditLease | null {
-    if (this.waiters.length > 0 || this.current + bytes > this.capacity) return null;
-    return this.grant(bytes);
-  }
-
-  acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
-    if (signal?.aborted) return Promise.reject(abortError(signal));
-    const immediate = this.tryAcquire(bytes);
-    if (immediate) return Promise.resolve(immediate);
-
-    return new Promise<ResizableCreditLease>((resolve, reject) => {
-      const waiter: CreditWaiter = {
-        bytes,
-        resolve,
-        reject,
-        signal,
-        onAbort: signal
-          ? () => {
-              const index = this.waiters.indexOf(waiter);
-              if (index < 0) return;
-              this.waiters.splice(index, 1);
-              signal.removeEventListener('abort', waiter.onAbort!);
-              reject(abortError(signal));
-              this.drain();
-            }
-          : undefined,
-      };
-      this.waiters.push(waiter);
-      signal?.addEventListener('abort', waiter.onAbort!, { once: true });
-      if (signal?.aborted) {
-        waiter.onAbort!();
-        return;
-      }
-      this.drain();
-    });
-  }
-
-  private grant(bytes: number): ResizableCreditLease {
-    this.current += bytes;
-    this.peak = Math.max(this.peak, this.current);
-    let leasedBytes = bytes;
-    let released = false;
-    return {
-      get bytes() {
-        return leasedBytes;
-      },
-      shrinkTo: (nextBytes: number) => {
-        if (released) {
-          throw new Error('cannot shrink a released weighted credit lease');
-        }
-        if (
-          !Number.isSafeInteger(nextBytes)
-          || nextBytes <= 0
-          || nextBytes > leasedBytes
-        ) {
-          throw new RangeError(
-            `weighted credit lease can only shrink to a positive safe integer no larger than ${leasedBytes}: ${nextBytes}`,
-          );
-        }
-        this.current -= leasedBytes - nextBytes;
-        leasedBytes = nextBytes;
-        this.drain();
-      },
-      release: () => {
-        if (released) return;
-        released = true;
-        this.current -= leasedBytes;
-        if (this.current < 0) {
-          throw new Error('weighted credit accounting underflow');
-        }
-        this.drain();
-      },
-    };
-  }
-
-  private drain(): void {
-    while (this.waiters.length > 0) {
-      const waiter = this.waiters[0];
-      if (waiter.signal?.aborted) {
-        this.waiters.shift();
-        waiter.signal.removeEventListener('abort', waiter.onAbort!);
-        waiter.reject(abortError(waiter.signal));
-        continue;
-      }
-      if (this.current + waiter.bytes > this.capacity) return;
-      this.waiters.shift();
-      waiter.signal?.removeEventListener('abort', waiter.onAbort!);
-      waiter.resolve(this.grant(waiter.bytes));
-    }
-  }
-}
-
-/**
- * FIFO byte-credit pool shared by concurrent allocation owners.
- * Capacity is measured in retained bytes, not operation count.
- *
- * One FIFO queue makes every request wait behind the one ahead of it even
- * when the pool has room to spare — `tryAcquire` refuses outright while
- * anyone is queued — so a single multi-megabyte owner parks every request
- * behind it for as long as it holds. Between owners of comparable size that
- * is the point. For a chunk-sized filesystem read it means a wait with
- * nothing to do with its own cost.
- *
- * So a request at or below `smallRequestBytes` takes shared capacity when
- * that can be granted outright, and otherwise falls back to a separate
- * `reserve` where it queues only among its own kind. It never joins the
- * shared queue, so it is never parked behind a larger owner.
- *
- * Neither side can starve the other. Shared capacity stops admitting small
- * requests the moment anything is queued for it, so a large waiter is never
- * overtaken; and the reserve is held apart from `capacity`, so a
- * full-capacity owner stays grantable while small requests stay servable.
- * Peak occupancy only reaches `capacity + reserve` while the shared lane is
- * contended.
- */
-export class WeightedCreditPool {
-  private readonly general: CreditLane;
-  private readonly small: CreditLane | null;
-  private readonly smallRequestBytes: number;
-
-  constructor(readonly capacity: number, options: WeightedCreditPoolOptions = {}) {
-    if (!Number.isSafeInteger(capacity) || capacity <= 0) {
-      throw new RangeError(`weighted credit capacity must be a positive safe integer: ${capacity}`);
-    }
-    const smallRequestBytes = options.smallRequestBytes ?? 0;
-    const reserve = options.reserve ?? 0;
-    if (!Number.isSafeInteger(smallRequestBytes) || smallRequestBytes < 0
-      || !Number.isSafeInteger(reserve) || reserve < 0) {
-      throw new RangeError('weighted credit reserve and small-request size must be non-negative safe integers');
-    }
-    if (smallRequestBytes > reserve) {
-      throw new RangeError(
-        `a small request (${smallRequestBytes}) must fit in the reserve (${reserve}) or it could never be granted`,
-      );
-    }
-    this.general = new CreditLane(capacity);
-    this.smallRequestBytes = smallRequestBytes;
-    this.small = smallRequestBytes > 0 ? new CreditLane(reserve) : null;
-  }
-
-  get stats(): WeightedCreditPoolStats {
-    const general = this.general.stats;
-    if (!this.small) return general;
-    const small = this.small.stats;
-    return {
-      current: general.current + small.current,
-      peak: general.peak + small.peak,
-      queued: general.queued + small.queued,
-    };
-  }
-
-  private isSmall(bytes: number): boolean {
-    return this.small !== null && bytes <= this.smallRequestBytes;
-  }
-
-  tryAcquire(bytes: number): ResizableCreditLease | null {
-    this.validateRequest(bytes);
-    const shared = this.general.tryAcquire(bytes);
-    if (shared || !this.isSmall(bytes)) return shared;
-    return this.small!.tryAcquire(bytes);
-  }
-
-  acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
-    try {
-      this.validateRequest(bytes);
-    } catch (error) {
-      return Promise.reject(error as Error);
-    }
-    if (this.isSmall(bytes)) {
-      // Shared capacity while it is free — a small request should get the
-      // same concurrency as any other when nothing is contending. It never
-      // joins the shared queue, so it cannot be parked behind a large owner.
-      const shared = this.general.tryAcquire(bytes);
-      if (shared) return Promise.resolve(shared);
-      return this.small!.acquire(bytes, signal);
-    }
-    return this.general.acquire(bytes, signal);
-  }
-
-  private validateRequest(bytes: number): void {
-    if (!Number.isSafeInteger(bytes) || bytes <= 0 || bytes > this.capacity) {
-      throw new RangeError(
-        `weighted credit request must be a positive safe integer no larger than ${this.capacity}: ${bytes}`,
-      );
-    }
-  }
-}
-
-function abortError(signal: AbortSignal): DOMException {
-  const reason = signal.reason;
-  return new DOMException(
-    reason instanceof Error ? reason.message : String(reason ?? 'The operation was aborted'),
-    'AbortError',
-  );
-}

package/src/observability/diag-counters.ts

@@ -1,343 +0,0 @@
-/**
- * diag-counters.ts — application-level memory + phase observability.
- *
- * Why: workerd's `process.memoryUsage()` returns 0 for all fields inside
- * a Durable Object class context (only dynamic-worker isolates under
- * nodejs_compat get the real implementation). Without a working heap
- * probe we have no way to confirm OOM hypotheses or verify a fix.
- *
- * Replacement: deterministic counters bumped at known allocation sites.
- * Cumulative bytes decoded, in-flight stub counts, and phase markers
- * give us the same operational signal as a heap probe — and they're
- * exact, not estimated.
- *
- * Singleton-per-isolate. Lives at module scope so any code path in the
- * supervisor bundle can write to it (installer and RPC handlers) and
- * the request handler in nimbus-session.ts:/api/_diag/memory can read
- * it. Survives across requests within the same isolate; resets on DO
- * reboot — itself a useful signal (counters at 0 immediately after the
- * banner reprinted = the killed isolate took its state with it).
- */
-
-/**
- * Phase tags surfaced via /api/_diag/memory. Strings are ASCII so
- * humans can grep for them in logs.
- *
- * installPhase tracks the high-level npm-install state machine:
- *   idle → resolve → hoist → diff → fetch → write → link-bins → bundle → done
- *
- */
-// CLN-1 (2026-05-11): InstallPhase moved to _shared/install-phase.ts so
-// it can't drift between this module and npm/installer.ts again. The
-// merged union includes both 'idle' (resting state) and 'lock-check'
-// (parsing package-lock.json). See _shared/install-phase.ts for full
-// semantics documentation.
-import type { InstallPhase } from '../_shared/install-phase.js';
-
-export interface DiagCounters {
-  /** Top-level install phase. */
-  installPhase: InstallPhase;
-  /**
-   * Sum of payload bytes claimed by RPCs currently in flight on the
-   * SUPERVISOR boundary [Phase 2 A'.2].
-   *
-   * Bumped at RPC entry by `rpcPayloadStart(bytes)` in the DO-side
-   * byte-returning handlers in src/session/rpc.ts; debited at exit by
-   * `rpcPayloadEnd(bytes)`. Goes back to zero after every RPC settles.
-   *
-   * The C'.1 heap estimator surfaces this as
-   * `breakdown.streamingBuffersBytes` so any RPC path that buffers
-   * MORE than the W7 streaming guarantee shows up as supervisor heap
-   * pressure rather than disappearing into the bundle baseline.
-   *
-   * Streamed payloads (writeBatchStream over W7 frames) report -1
-   * up-front; we substitute 0 here because the bytes flow with
-   * backpressure and the supervisor-resident buffer is bounded by
-   * the W7 chunk size (a few KiB), not by the total payload.
-   */
-  inFlightRpcPayloadBytes: number;
-  /**
-   * Bytes reserved by prefetch-bundle builds currently in flight.
-   *
-   * `buildPrefetchBundle` accumulates raw VFS file contents into an in-heap
-   * bundle object, and used to do so with nothing observing it: the estimator
-   * read 9.4 MiB while those bytes were resetting the DO. Each build now takes
-   * an `acquireSupervisorAllocation` lease for the budget it may use and bumps
-   * this alongside it, so the reservation is ATTRIBUTED to the bundle path
-   * rather than landing in `unattributedReservationBytes`.
-   *
-   * Surfaced as `breakdown.prefetchBundleBytes`. Back to zero between builds.
-   */
-  prefetchBundleBytes: number;
-  /**
-   * Bytes retained by the FacetManager's prefetch-bundle LRU right now.
-   *
-   * Unlike the counter above these bytes persist ACROSS execs — each entry
-   * holds the raw bundle plus its serialized source, manifest and metadata.
-   * The LRU used to be bounded by entry count alone, which bounded nothing:
-   * 16 pi-sized entries exceed the supervisor ceiling several times over. It
-   * is now bounded by PREFETCH_CACHE_MAX_BYTES and reports its live total
-   * here, so the retained cost is a measurement rather than a cap.
-   *
-   * Surfaced as `breakdown.prefetchCacheBytes`. A gauge, not a delta.
-   */
-  prefetchCacheBytes: number;
-  /** Install-facet counters. Populated by npm-installer after a
-   *  successful batch-facet dispatch returns. Confirms the install ran
-   *  in the facet (tarballsCompleted > 0) and surfaces the
-   *  facet-internal byte count. */
-  installFacet: {
-    /** Number of tarballs the install-batch-facet successfully streamed. */
-    tarballsCompleted: number;
-    /** Cumulative tarball body bytes the facet decoded (gunzip input). */
-    cumulativeBytesDecoded: number;
-    /** Peak in-flight tarball pipelines inside the facet at any one moment. */
-    peakInFlight: number;
-  };
-  /** Pre-bundle facet counters. Tracks the fire-and-forget pre-bundle
-   *  phase. Aggregates across all dispatches in this DO's lifetime. */
-  preBundleFacet: {
-    /** Specifiers attempted (queue depth at start of phase). */
-    attempted: number;
-    /** Bundles that completed successfully (esmCode produced). */
-    bundlesCompleted: number;
-    /** Bundles that failed (errorText set on PrebundleResult). */
-    errors: number;
-    /** Bundles skipped before facet dispatch (e.g. slice cap exceeded). */
-    skipped: number;
-    /** First-call wasm-fetch payload size. 0 until first successful dispatch
-     *  records it; stays at first-seen value (RPC returns the same Module
-     *  every time, but the cumulativeBytes the FACET reports may grow on
-     *  retries). */
-    wasmBootBytes: number;
-    /** Per-module errors from the MOST RECENT pre-bundle batch, keyed by
-     *  specifier (e.g. "lucide-react", "framer-motion"). REPLACED on each
-     *  recordPreBundleSummary() call so the map is bounded by the batch
-     *  size (≤ pending.length, typically <20).
-     *
-     *  Example: { "lucide-react": "Worker exceeded memory limit." }
-     *
-     *  Empty when the most recent batch had zero errors. */
-    errorsByModule: Record<string, string>;
-  };
-  /** Pipelined R2 race outcomes. All counts are cumulative since
-   *  DO-isolate start. Per-tier cache statistics live in cache-stats. */
-  r2: {
-    /** Pipelined-RPC race wins for tarballs (R2 came back first; network
-     *  was cancelled). */
-    pipelinedTarballRaceWins: number;
-    /** Pipelined-RPC race losses for tarballs (R2 came back too slow or
-     *  empty; network response used). */
-    pipelinedTarballRaceLosses: number;
-    /** Pipelined-RPC race wins for packuments. */
-    pipelinedPackumentRaceWins: number;
-    /** Pipelined-RPC race losses for packuments. */
-    pipelinedPackumentRaceLosses: number;
-  };
-}
-
-const _counters: DiagCounters = {
-  installPhase: 'idle',
-  inFlightRpcPayloadBytes: 0,
-  prefetchBundleBytes: 0,
-  prefetchCacheBytes: 0,
-  installFacet: {
-    tarballsCompleted: 0,
-    cumulativeBytesDecoded: 0,
-    peakInFlight: 0,
-  },
-  preBundleFacet: {
-    attempted: 0,
-    bundlesCompleted: 0,
-    errors: 0,
-    skipped: 0,
-    wasmBootBytes: 0,
-    errorsByModule: {},
-  },
-  r2: {
-    pipelinedTarballRaceWins: 0,
-    pipelinedTarballRaceLosses: 0,
-    pipelinedPackumentRaceWins: 0,
-    pipelinedPackumentRaceLosses: 0,
-  },
-};
-
-/** Read a snapshot — caller-side mutations don't affect the singleton. */
-export function readDiagCounters(): DiagCounters {
-  return { ..._counters };
-}
-
-/** Set the install phase. */
-export function setInstallPhase(p: InstallPhase): void {
-  _counters.installPhase = p;
-}
-
-/**
- * Track an in-flight supervisor RPC payload [Phase 2 A'.2].
- *
- * Call at RPC entry, BEFORE awaiting any work that depends on
- * `payload`. Pair with `rpcPayloadEnd(bytes)` in the matching `finally`
- * so the counter goes back to zero on both success and failure.
- *
- * `bytes` is the supervisor-resident byte cost of the RPC's argument
- * (or return value, whichever is bigger). For structured-clone RPCs
- * this is the size of the cloned payload in bytes.
- *
- * Streamed payloads (ReadableStream-over-RPC) flow with backpressure
- * and the supervisor-resident bound is the chunk size, not the total
- * payload. Pass the chunk-size estimate (typically ≤ 1 MiB) — never
- * the unknown total. -1 is silently coerced to 0 to keep the counter
- * non-negative; callers that don't know the size should call this
- * with 0 explicitly rather than relying on coercion.
- */
-export function rpcPayloadStart(bytes: number): void {
-  const n = Number(bytes);
-  if (!Number.isFinite(n) || n <= 0) return;
-  _counters.inFlightRpcPayloadBytes += n;
-}
-
-/**
- * Release an in-flight supervisor RPC payload [Phase 2 A'.2].
- * Pass the same byte count given to the matching `rpcPayloadStart`.
- *
- * Floors at 0 to absorb arithmetic drift (e.g. if a payload-byte
- * counter rounding gave a slightly different number on entry vs.
- * exit). Drift in routine paths should be zero — a non-zero floor
- * hit is a bug worth investigating.
- */
-export function rpcPayloadEnd(bytes: number): void {
-  const n = Number(bytes);
-  if (!Number.isFinite(n) || n <= 0) return;
-  _counters.inFlightRpcPayloadBytes -= n;
-  if (_counters.inFlightRpcPayloadBytes < 0) {
-    _counters.inFlightRpcPayloadBytes = 0;
-  }
-}
-
-/**
- * Track an in-flight prefetch-bundle build. Call with the byte reservation the
- * build took from the supervisor allocation budget, and pair with
- * `prefetchBundleEnd` in the matching `finally` so it returns to zero whether
- * the build succeeded or threw.
- */
-export function prefetchBundleStart(bytes: number): void {
-  const n = Number(bytes);
-  if (!Number.isFinite(n) || n <= 0) return;
-  _counters.prefetchBundleBytes += n;
-}
-
-/** Release an in-flight prefetch-bundle reservation. Floors at 0. */
-export function prefetchBundleEnd(bytes: number): void {
-  const n = Number(bytes);
-  if (!Number.isFinite(n) || n <= 0) return;
-  _counters.prefetchBundleBytes -= n;
-  if (_counters.prefetchBundleBytes < 0) _counters.prefetchBundleBytes = 0;
-}
-
-/**
- * Publish the prefetch-bundle LRU's live retained total. A gauge: the cache
- * owns the number and reports it whenever it admits or evicts an entry.
- */
-export function setPrefetchCacheBytes(bytes: number): void {
-  const n = Number(bytes);
-  _counters.prefetchCacheBytes = Number.isFinite(n) && n > 0 ? n : 0;
-}
-
-/** Fold facet-returned counters into the supervisor's diag state.
- *  Called by npm-installer after the batch-facet returns; aggregates
- *  rather than replaces so multiple install runs in the same DO
- *  lifetime accumulate in cumulativeBytesDecoded. */
-export function recordInstallFacetCounters(c: {
-  tarballsCompleted: number;
-  cumulativeBytesDecoded: number;
-  peakInFlight: number;
-}): void {
-  _counters.installFacet.tarballsCompleted += c.tarballsCompleted;
-  _counters.installFacet.cumulativeBytesDecoded += c.cumulativeBytesDecoded;
-  if (c.peakInFlight > _counters.installFacet.peakInFlight) {
-    _counters.installFacet.peakInFlight = c.peakInFlight;
-  }
-}
-
-/** Record pre-bundle phase summary. Aggregates lifetime totals across
- *  all phases run in this DO's lifetime, but REPLACES the
- *  errorsByModule map every call so it reflects only the most recent
- *  batch. Losing prior-batch errors is fine — they're already aggregated
- *  into `errors` (count); the map is for "which modules failed this
- *  time." */
-export function recordPreBundleSummary(s: {
-  attempted: number;
-  bundlesCompleted: number;
-  errors: number;
-  skipped: number;
-  wasmBootBytes?: number;
-  errorsByModule?: Record<string, string>;
-}): void {
-  _counters.preBundleFacet.attempted += s.attempted;
-  _counters.preBundleFacet.bundlesCompleted += s.bundlesCompleted;
-  _counters.preBundleFacet.errors += s.errors;
-  _counters.preBundleFacet.skipped += s.skipped;
-  if (s.wasmBootBytes && _counters.preBundleFacet.wasmBootBytes === 0) {
-    _counters.preBundleFacet.wasmBootBytes = s.wasmBootBytes;
-  }
-  // Replace (not merge) so we capture only the most recent batch.
-  // Bounded by batch size; truncate each value to 200 chars.
-  if (s.errorsByModule) {
-    const trimmed: Record<string, string> = {};
-    for (const [name, msg] of Object.entries(s.errorsByModule)) {
-      trimmed[name] = String(msg).slice(0, 200);
-    }
-    _counters.preBundleFacet.errorsByModule = trimmed;
-  }
-}
-
-/** Bump pipelined-RPC race outcome counters. The facet returns these
- *  in its result counters; the supervisor folds them in alongside the
- *  existing installFacet counters. */
-export function recordR2RaceCounters(c: {
-  pipelinedTarballRaceWins: number;
-  pipelinedTarballRaceLosses: number;
-  pipelinedPackumentRaceWins: number;
-  pipelinedPackumentRaceLosses: number;
-}): void {
-  _counters.r2.pipelinedTarballRaceWins += c.pipelinedTarballRaceWins;
-  _counters.r2.pipelinedTarballRaceLosses += c.pipelinedTarballRaceLosses;
-  _counters.r2.pipelinedPackumentRaceWins += c.pipelinedPackumentRaceWins;
-  _counters.r2.pipelinedPackumentRaceLosses += c.pipelinedPackumentRaceLosses;
-}
-
-/**
- * cache-obs-2: fold facet-collected per-tier cache events into the
- * DO-side cache-stats singleton. Called from installer.ts after a
- * batch-facet / resolve-facet returns — mirrors recordR2RaceCounters
- * (the facet collects metrics in its result and the supervisor folds
- * them into the DO isolate).
- *
- * Each event has shape:
- *   { kind: 'hit', tier: 'L2'|'L3'|'L4', cacheKind: 'tarball'|'packument'|'asset', bytes: number }
- *   { kind: 'miss', tier: ..., cacheKind: ... }
- *
- * The recordHit/recordMiss surface is defined in
- * src/_shared/cache-stats.ts.
- */
-import {
-  recordHit as _cacheRecordHit,
-  recordMiss as _cacheRecordMiss,
-  type CacheTier,
-  type CacheKind,
-} from '../_shared/cache-stats.js';
-
-export type CacheStatEvent =
-  | { kind: 'hit'; tier: CacheTier; cacheKind: CacheKind; bytes: number }
-  | { kind: 'miss'; tier: CacheTier; cacheKind: CacheKind };
-
-export function recordCacheStatEvents(events: readonly CacheStatEvent[] | undefined): void {
-  if (!events || events.length === 0) return;
-  for (const e of events) {
-    if (e.kind === 'hit') {
-      _cacheRecordHit(e.tier, e.cacheKind, e.bytes);
-    } else {
-      _cacheRecordMiss(e.tier, e.cacheKind);
-    }
-  }
-}