@nimbus-sh/core 0.1.0

package/dist/_shared/install-phase.d.ts

@@ -0,0 +1,47 @@
+/**
+ * _shared/install-phase.ts — single source of truth for the npm-install
+ * state-machine phase enum.
+ *
+ * History: CLN-1 (2026-05-11) — consolidated from two diverged copies.
+ *   - `npm/installer.ts:93-95` was the progress-event variant. Included
+ *     'lock-check' (a real progress event emitted while parsing
+ *     package-lock.json) but lacked 'idle'.
+ *   - `observability/diag-counters.ts:33-35` was the counter-state variant.
+ *     Included 'idle' (the resting state when no install is in flight)
+ *     but lacked 'lock-check'. The diag-counter's `setInstallPhase()`
+ *     was actually called with 'idle' (installer.ts:184,201) — passing
+ *     a value not declared in installer.ts's local type. The type check
+ *     fell through to diag-counters' type because installer.ts imports
+ *     setInstallPhase from there; the local `InstallPhase` definition
+ *     in installer.ts was only used by `InstallProgress.phase`.
+ *
+ * Going forward both consumers import from this module; any new phase
+ * value added here is automatically available everywhere.
+ *
+ * Phase semantics (chronological order for a single install run):
+ *
+ *   idle         resting state, no install in flight
+ *     ↓
+ *   lock-check   parsing existing package-lock.json (if present)
+ *     ↓
+ *   resolve      walking the dep tree, fetching packuments
+ *     ↓
+ *   hoist        hoisting peer-deps + flattening node_modules
+ *     ↓
+ *   diff         comparing target tree against current install state
+ *     ↓
+ *   fetch        downloading missing tarballs
+ *     ↓
+ *   write        extracting tarballs into the VFS
+ *     ↓
+ *   link-bins    creating bin/ symlinks
+ *     ↓
+ *   bundle       (post-install) pre-bundling for esbuild fast path
+ *     ↓
+ *   done         install complete; about to return to 'idle'
+ *
+ * The phase strings are surfaced via /api/_diag/install-pipeline and
+ * displayed in the install-progress UI; treat them as a public API.
+ */
+export type InstallPhase = 'idle' | 'lock-check' | 'resolve' | 'hoist' | 'diff' | 'fetch' | 'write' | 'link-bins' | 'bundle' | 'done';
+//# sourceMappingURL=install-phase.d.ts.map

package/dist/_shared/install-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-phase.d.ts","sourceRoot":"","sources":["../../src/_shared/install-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,MAAM,CAAC"}

package/dist/_shared/install-phase.js

@@ -0,0 +1 @@
+export {};

package/dist/_shared/lru-map.d.ts

@@ -0,0 +1,25 @@
+/**
+ * LruMap — a bounded, insertion-order LRU keyed map.
+ *
+ * Uses the standard JS `Map` insertion-order idiom the VFS content cache
+ * relies on (sqlite-vfs.ts): a read or write moves the key to the most-
+ * recently-used position (delete + re-set), and inserting past capacity
+ * evicts the least-recently-used key (`keys().next().value`).
+ *
+ * Exposes only the `Map` surface its callers use so it can drop in for a
+ * raw `Map` without churn: `get`, `set`, `delete`, `has`, `keys`,
+ * `clear`, and `size`.
+ */
+export declare class LruMap<K, V> {
+    private readonly maxEntries;
+    private readonly map;
+    constructor(maxEntries: number);
+    get size(): number;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+    keys(): IterableIterator<K>;
+}
+//# sourceMappingURL=lru-map.d.ts.map

package/dist/_shared/lru-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-map.d.ts","sourceRoot":"","sources":["../../src/_shared/lru-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,qBAAa,MAAM,CAAC,CAAC,EAAE,CAAC;IAGV,OAAO,CAAC,QAAQ,CAAC,UAAU;IAFvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmB;gBAEV,UAAU,EAAE,MAAM;IAI/C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAS1B,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIpB,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAW3B,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAIvB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,gBAAgB,CAAC,CAAC,CAAC;CAG5B"}

package/dist/_shared/lru-map.js

@@ -0,0 +1,57 @@
+/**
+ * LruMap — a bounded, insertion-order LRU keyed map.
+ *
+ * Uses the standard JS `Map` insertion-order idiom the VFS content cache
+ * relies on (sqlite-vfs.ts): a read or write moves the key to the most-
+ * recently-used position (delete + re-set), and inserting past capacity
+ * evicts the least-recently-used key (`keys().next().value`).
+ *
+ * Exposes only the `Map` surface its callers use so it can drop in for a
+ * raw `Map` without churn: `get`, `set`, `delete`, `has`, `keys`,
+ * `clear`, and `size`.
+ */
+export class LruMap {
+    maxEntries;
+    map = new Map();
+    constructor(maxEntries) {
+        this.maxEntries = maxEntries;
+        if (maxEntries <= 0)
+            throw new Error('LruMap maxEntries must be > 0');
+    }
+    get size() {
+        return this.map.size;
+    }
+    get(key) {
+        const value = this.map.get(key);
+        if (value === undefined)
+            return undefined;
+        // Move to MRU position.
+        this.map.delete(key);
+        this.map.set(key, value);
+        return value;
+    }
+    has(key) {
+        return this.map.has(key);
+    }
+    set(key, value) {
+        if (this.map.has(key)) {
+            this.map.delete(key);
+        }
+        else if (this.map.size >= this.maxEntries) {
+            const lru = this.map.keys().next().value;
+            if (lru !== undefined)
+                this.map.delete(lru);
+        }
+        this.map.set(key, value);
+        return this;
+    }
+    delete(key) {
+        return this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
+    }
+    keys() {
+        return this.map.keys();
+    }
+}

package/dist/_shared/real-node-imports.d.ts

@@ -0,0 +1,43 @@
+/**
+ * real-node-imports.ts — single source of truth for the static
+ * `import * as __real_X from 'node:X'` block that generated runtime
+ * workers prepend so the SHIMS string can forward to workerd's real
+ * `node:*` builtins.
+ *
+ * Used by:
+ *   - src/facet-manager.ts one-shot runtime worker template
+ *   - src/facet-manager.ts long-running process worker template
+ *
+ * Symmetry constraint (W3 plan §3): both templates MUST consume this
+ * helper to prevent drift. If you add a new `import * as __real_X`,
+ * also wire it into the matching shim block in node-shims.ts.
+ *
+ * Why this lives in _shared/ alongside exports-resolver.ts: same
+ * pattern — JS-string emitter consumed by the facet-code generators
+ * that can't `import` at runtime because the surrounding code is a
+ * raw string template.
+ *
+ * Workerd availability matrix (probe-verified 2026-05-04 at compat
+ * date 2026-04-01, flag `nodejs_compat`):
+ *   - node:crypto       — full Node 20 surface
+ *   - node:tls          — connect/TLSSocket/createSecureContext/...
+ *   - node:async_hooks  — AsyncLocalStorage + AsyncResource + createHook
+ *   - node:fs/promises  — full surface (BUT operates on real-host FS,
+ *                         not our VFS, so we shim VFS-backed instead
+ *                         of forwarding fs/promises)
+ *   - node:diagnostics_channel — full surface incl. tracingChannel +
+ *                                Channel.runStores (fastify-critical)
+ *   - node:repl         — surface stub (start/REPLServer)
+ *   - node:vm           — surface stub: classes/constants present BUT
+ *                         every code-running method throws
+ *                         ERR_METHOD_NOT_IMPLEMENTED. Hybrid shim:
+ *                         forward surface, wrap eval methods with
+ *                         honest error.
+ *   - node:inspector    — Session/console/url surface present; the V8
+ *                         debugger isn't attachable in workerd, so a
+ *                         constructed Session's connect/post are inert.
+ *                         Tools (e.g. nuxi) that open a Session purely
+ *                         for optional profiling degrade cleanly.
+ */
+export declare function getRealNodeImportsCode(): string;
+//# sourceMappingURL=real-node-imports.d.ts.map

package/dist/_shared/real-node-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-node-imports.d.ts","sourceRoot":"","sources":["../../src/_shared/real-node-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,wBAAgB,sBAAsB,IAAI,MAAM,CAU/C"}

package/dist/_shared/real-node-imports.js

@@ -0,0 +1,52 @@
+/**
+ * real-node-imports.ts — single source of truth for the static
+ * `import * as __real_X from 'node:X'` block that generated runtime
+ * workers prepend so the SHIMS string can forward to workerd's real
+ * `node:*` builtins.
+ *
+ * Used by:
+ *   - src/facet-manager.ts one-shot runtime worker template
+ *   - src/facet-manager.ts long-running process worker template
+ *
+ * Symmetry constraint (W3 plan §3): both templates MUST consume this
+ * helper to prevent drift. If you add a new `import * as __real_X`,
+ * also wire it into the matching shim block in node-shims.ts.
+ *
+ * Why this lives in _shared/ alongside exports-resolver.ts: same
+ * pattern — JS-string emitter consumed by the facet-code generators
+ * that can't `import` at runtime because the surrounding code is a
+ * raw string template.
+ *
+ * Workerd availability matrix (probe-verified 2026-05-04 at compat
+ * date 2026-04-01, flag `nodejs_compat`):
+ *   - node:crypto       — full Node 20 surface
+ *   - node:tls          — connect/TLSSocket/createSecureContext/...
+ *   - node:async_hooks  — AsyncLocalStorage + AsyncResource + createHook
+ *   - node:fs/promises  — full surface (BUT operates on real-host FS,
+ *                         not our VFS, so we shim VFS-backed instead
+ *                         of forwarding fs/promises)
+ *   - node:diagnostics_channel — full surface incl. tracingChannel +
+ *                                Channel.runStores (fastify-critical)
+ *   - node:repl         — surface stub (start/REPLServer)
+ *   - node:vm           — surface stub: classes/constants present BUT
+ *                         every code-running method throws
+ *                         ERR_METHOD_NOT_IMPLEMENTED. Hybrid shim:
+ *                         forward surface, wrap eval methods with
+ *                         honest error.
+ *   - node:inspector    — Session/console/url surface present; the V8
+ *                         debugger isn't attachable in workerd, so a
+ *                         constructed Session's connect/post are inert.
+ *                         Tools (e.g. nuxi) that open a Session purely
+ *                         for optional profiling degrade cleanly.
+ */
+export function getRealNodeImportsCode() {
+    return `
+import * as __real_crypto from 'node:crypto';
+import * as __real_tls from 'node:tls';
+import * as __real_async_hooks from 'node:async_hooks';
+import * as __real_diagnostics_channel from 'node:diagnostics_channel';
+import * as __real_repl from 'node:repl';
+import * as __real_vm from 'node:vm';
+import * as __real_inspector from 'node:inspector';
+`.trim();
+}

package/dist/_shared/retry.d.ts

@@ -0,0 +1,92 @@
+/**
+ * retry.ts — small, dependency-free retry helper for flaky HTTP GETs.
+ *
+ * The npm path (resolver packument fetches + tarball fetches) talks to
+ * registry.npmjs.org via Cloudflare's edge. Either hop can produce a
+ * transient 5xx — we've seen HTTP 503 on a single tarball out of 456
+ * kill a whole install. npm's client retries 5xx by default; we didn't,
+ * until this file. Any single transient failure across hundreds of
+ * packages = whole install dead.
+ *
+ * Scope:
+ *   - Retries on 5xx (500/502/503/504 especially) and network errors
+ *     (fetch rejection, AbortError timeout, etc.).
+ *   - Does NOT retry on 4xx (those are hard: 404 means the package or
+ *     version genuinely doesn't exist; retrying is wrong and wastes time).
+ *   - Budget: 3 retries with jittered exponential backoff (500/1500/4500 ms
+ *     ±25% jitter). Worst-case added latency per package ≈ 6.5 s in the
+ *     fully-degraded path. Tighter than npm's ~5×60s because dev iteration
+ *     speed matters more than absolute resilience here.
+ *
+ * Facet tasks are serialized via fn.toString() and cannot import this
+ * helper. resolve-one-facet.ts and install-batch-facet.ts therefore keep
+ * equivalent retry loops inside their isolated function bodies.
+ */
+/** Default retry count AFTER the first attempt (3 = up to 4 total attempts). */
+export declare const DEFAULT_RETRIES = 3;
+/** Base backoff delays in ms. Index = retry attempt (0-indexed). */
+export declare const BACKOFF_MS: readonly number[];
+/** Jitter ±25% of the base delay, uniformly distributed. */
+export declare function jittered(baseMs: number): number;
+/** True if an HTTP status should trigger a retry. */
+export declare function isRetriableStatus(status: number): boolean;
+/**
+ * Signature of a fetch-compatible callable. Lets callers inject a proxy
+ * (e.g. the Nimbus supervisor-fetch RPC) without forcing global fetch.
+ */
+export type FetchCallable = (url: string, init?: RequestInit) => Promise<Response>;
+export interface RetryableFetchOptions {
+    /**
+     * Retries AFTER the initial attempt. Default DEFAULT_RETRIES (3).
+     * 0 = behave as a plain fetch.
+     */
+    retries?: number;
+    /**
+     * Fetch implementation. Defaults to globalThis.fetch. Pass a proxy
+     * fetch (e.g. env.SUPERVISOR-backed fetchFn) to route through it while
+     * keeping the retry semantics.
+     */
+    fetchImpl?: FetchCallable;
+    /**
+     * Human-readable name for the resource (used only in log messages).
+     * Typically "<pkg>@<version>" for npm or the URL.
+     */
+    name?: string;
+    /**
+     * Per-attempt timeout in ms. A fresh AbortController is used per attempt
+     * so a slow-to-fail upstream doesn't eat the whole retry budget on a
+     * single hang. Merges with any caller-provided `init.signal` (both are
+     * honored: whichever aborts first wins).
+     *
+     * Default: undefined (no timeout; caller is responsible for its own
+     * signal if it wants one).
+     */
+    perAttemptTimeoutMs?: number;
+    /**
+     * Optional logger called on each retry decision. Signature:
+     *   onRetry(attempt /* 1-indexed *\/, totalRetries, delayMs, reason)
+     *
+     * Caller uses this to surface visible progress ("retry 1/3 after 500ms
+     * (HTTP 503)") rather than have the whole install silently hang for
+     * several seconds.
+     */
+    onRetry?: (attempt: number, totalRetries: number, delayMs: number, reason: string) => void;
+}
+/**
+ * fetch() wrapper with 5xx + network-error retry and jittered backoff.
+ *
+ * On a 4xx response, returns the Response object as-is (caller decides
+ * whether that's an error). On a 5xx or network-level failure, retries
+ * up to `retries` times with BACKOFF_MS[attempt] ± 25% jitter.
+ *
+ * When retries are exhausted, either:
+ *   - Returns the last (5xx) Response, so the caller can read .status for
+ *     error reporting, OR
+ *   - Re-throws the last network error (caller never sees a Response).
+ *
+ * Callers that previously did `if (!resp.ok) throw ...` retain that shape;
+ * the only change is that transient failures are recovered before the
+ * throw instead of killing the whole install on the first hiccup.
+ */
+export declare function retryableFetch(url: string, init?: RequestInit, opts?: RetryableFetchOptions): Promise<Response>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/_shared/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/_shared/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH,gFAAgF;AAChF,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,oEAAoE;AACpE,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAAsB,CAAC;AAE/D,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAM/C;AAED,qDAAqD;AACrD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOzD;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEnF,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,IAAI,CAAC,EAAE,qBAAqB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAqFnB"}

package/dist/_shared/retry.js

@@ -0,0 +1,155 @@
+/**
+ * retry.ts — small, dependency-free retry helper for flaky HTTP GETs.
+ *
+ * The npm path (resolver packument fetches + tarball fetches) talks to
+ * registry.npmjs.org via Cloudflare's edge. Either hop can produce a
+ * transient 5xx — we've seen HTTP 503 on a single tarball out of 456
+ * kill a whole install. npm's client retries 5xx by default; we didn't,
+ * until this file. Any single transient failure across hundreds of
+ * packages = whole install dead.
+ *
+ * Scope:
+ *   - Retries on 5xx (500/502/503/504 especially) and network errors
+ *     (fetch rejection, AbortError timeout, etc.).
+ *   - Does NOT retry on 4xx (those are hard: 404 means the package or
+ *     version genuinely doesn't exist; retrying is wrong and wastes time).
+ *   - Budget: 3 retries with jittered exponential backoff (500/1500/4500 ms
+ *     ±25% jitter). Worst-case added latency per package ≈ 6.5 s in the
+ *     fully-degraded path. Tighter than npm's ~5×60s because dev iteration
+ *     speed matters more than absolute resilience here.
+ *
+ * Facet tasks are serialized via fn.toString() and cannot import this
+ * helper. resolve-one-facet.ts and install-batch-facet.ts therefore keep
+ * equivalent retry loops inside their isolated function bodies.
+ */
+import { disposeRpcResource } from './rpc-dispose.js';
+/** Default retry count AFTER the first attempt (3 = up to 4 total attempts). */
+export const DEFAULT_RETRIES = 3;
+/** Base backoff delays in ms. Index = retry attempt (0-indexed). */
+export const BACKOFF_MS = [500, 1500, 4500];
+/** Jitter ±25% of the base delay, uniformly distributed. */
+export function jittered(baseMs) {
+    const span = baseMs * 0.25;
+    // Math.random is fine here — cryptographic randomness is not required;
+    // the goal is to break up synchronized retries across concurrent fetches
+    // after a shared upstream hiccup.
+    return Math.max(0, Math.round(baseMs + (Math.random() * 2 - 1) * span));
+}
+/** True if an HTTP status should trigger a retry. */
+export function isRetriableStatus(status) {
+    // 5xx only. 429 (Too Many Requests) is arguably retriable too, but
+    // registry.npmjs.org is fronted by Cloudflare which generally rate-
+    // limits per-IP silently rather than with 429, and if we ever DO see
+    // 429 the right handling is Retry-After header honor, which we don't
+    // implement here. Keep the surface minimal.
+    return status >= 500 && status <= 599;
+}
+/**
+ * fetch() wrapper with 5xx + network-error retry and jittered backoff.
+ *
+ * On a 4xx response, returns the Response object as-is (caller decides
+ * whether that's an error). On a 5xx or network-level failure, retries
+ * up to `retries` times with BACKOFF_MS[attempt] ± 25% jitter.
+ *
+ * When retries are exhausted, either:
+ *   - Returns the last (5xx) Response, so the caller can read .status for
+ *     error reporting, OR
+ *   - Re-throws the last network error (caller never sees a Response).
+ *
+ * Callers that previously did `if (!resp.ok) throw ...` retain that shape;
+ * the only change is that transient failures are recovered before the
+ * throw instead of killing the whole install on the first hiccup.
+ */
+export async function retryableFetch(url, init, opts) {
+    const totalRetries = Math.max(0, opts?.retries ?? DEFAULT_RETRIES);
+    const name = opts?.name ?? url;
+    const doFetch = opts?.fetchImpl ?? globalThis.fetch.bind(globalThis);
+    let lastError;
+    let lastResp;
+    for (let attempt = 0; attempt <= totalRetries; attempt++) {
+        // Per-attempt timeout via a fresh AbortController so a single slow
+        // response can't consume the whole retry budget. We merge the caller's
+        // signal (if any) by forwarding its abort to ours.
+        let timer;
+        let attemptInit = init;
+        const perAttemptMs = opts?.perAttemptTimeoutMs;
+        let localController;
+        if (perAttemptMs && perAttemptMs > 0) {
+            localController = new AbortController();
+            timer = setTimeout(() => localController.abort(), perAttemptMs);
+            const callerSignal = init?.signal;
+            if (callerSignal) {
+                if (callerSignal.aborted)
+                    localController.abort();
+                else
+                    callerSignal.addEventListener('abort', () => localController.abort(), { once: true });
+            }
+            attemptInit = { ...(init ?? {}), signal: localController.signal };
+        }
+        try {
+            const resp = await doFetch(url, attemptInit);
+            if (timer)
+                clearTimeout(timer);
+            if (resp.ok || !isRetriableStatus(resp.status)) {
+                // Success or 4xx — don't retry. Return as-is; caller checks .ok.
+                return resp;
+            }
+            // 5xx: drain the body to release the underlying stream.
+            try {
+                await resp.body?.cancel();
+            }
+            catch { /* best-effort */ }
+            lastResp = resp;
+            lastError = undefined;
+            if (attempt === totalRetries) {
+                // Out of retries — return the 5xx Response so the caller can
+                // surface the final status. Caller (e.g. npm-resolver.ts) is
+                // responsible for disposing the stub via Symbol.dispose after
+                // reading status. (Matches the previous !resp.ok throw shape if
+                // the caller checks .ok next.)
+                return resp;
+            }
+            // We're going to retry — dispose the stub NOW so it doesn't leak.
+            //
+            // When `doFetch` is the supervisor's fetch-proxy entrypoint
+            // (src/nimbus-session.ts:1729-1747), `resp` is an RPC stub returned
+            // from `entrypoint.fetch(...)`. Workerd auto-disposes such stubs
+            // only at the end of the enclosing event-handler context — which
+            // for `npm install` means "until the whole install completes".
+            // Cancelling `resp.body` (above) releases the underlying stream
+            // but does NOT release the stub itself. Across an install with N
+            // retries fired, that's N leaked stubs accumulating alongside the
+            // resolver's own per-packument stubs (already disposed in
+            // npm-resolver.ts:307-317). Each leaked stub keeps its server-side
+            // counterpart pinned until the deferred-destruction queue runs at
+            // request end, contributing to the queueState != ACTIVE fatal
+            // documented in WORKERD-CRASH.md.
+            //
+            // Same disposer pattern as src/npm-resolver.ts:312-316.
+            disposeRpcResource(resp);
+            const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
+            opts?.onRetry?.(attempt + 1, totalRetries, delayMs, `HTTP ${resp.status}`);
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+        catch (e) {
+            if (timer)
+                clearTimeout(timer);
+            // Network-level failure (fetch rejection, timeout via AbortError,
+            // DNS, connection reset). Retry the same way as a 5xx.
+            lastError = e;
+            lastResp = undefined;
+            if (attempt === totalRetries) {
+                throw e;
+            }
+            const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
+            const reason = e?.name === 'AbortError' ? 'timeout' : (e?.message || String(e));
+            opts?.onRetry?.(attempt + 1, totalRetries, delayMs, reason);
+            await new Promise((r) => setTimeout(r, delayMs));
+        }
+    }
+    // Unreachable: the loop either returns (on success / non-retriable /
+    // final 5xx) or throws (on final network error).
+    if (lastResp)
+        return lastResp;
+    throw lastError ?? new Error(`retryableFetch: exhausted for ${name}`);
+}

package/dist/_shared/rpc-dispose.d.ts

@@ -0,0 +1,4 @@
+export declare function disposeRpcResource(value: unknown): boolean;
+export declare function disposeRpcResources(values: Iterable<unknown>): void;
+export declare function useRpcResource<T, R>(promise: Promise<T>, use: (value: T) => R | Promise<R>): Promise<R>;
+//# sourceMappingURL=rpc-dispose.d.ts.map

package/dist/_shared/rpc-dispose.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-dispose.d.ts","sourceRoot":"","sources":["../../src/_shared/rpc-dispose.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAY1D;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,CAEnE;AAED,wBAAsB,cAAc,CAAC,CAAC,EAAE,CAAC,EACvC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChC,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/_shared/rpc-dispose.js

@@ -0,0 +1,30 @@
+export function disposeRpcResource(value) {
+    if ((typeof value !== 'object' && typeof value !== 'function') || value === null)
+        return false;
+    const disposerKey = Symbol.dispose;
+    if (!disposerKey)
+        return false;
+    const disposer = Reflect.get(value, disposerKey);
+    if (typeof disposer !== 'function')
+        return false;
+    try {
+        Reflect.apply(disposer, value, []);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function disposeRpcResources(values) {
+    for (const value of values)
+        disposeRpcResource(value);
+}
+export async function useRpcResource(promise, use) {
+    const value = await promise;
+    try {
+        return await use(value);
+    }
+    finally {
+        disposeRpcResource(value);
+    }
+}

package/dist/_shared/terminal.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizeTerminalNewlines(text: string): string;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/_shared/terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminal.d.ts","sourceRoot":"","sources":["../../src/_shared/terminal.ts"],"names":[],"mappings":"AAAA,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9D"}

package/dist/_shared/terminal.js

@@ -0,0 +1,3 @@
+export function normalizeTerminalNewlines(text) {
+    return text.replace(/\r?\n/g, '\r\n');
+}

package/dist/_shared/typescript-specifiers.d.ts

@@ -0,0 +1,58 @@
+/**
+ * typescript-specifiers.ts — the one definition of how a module specifier
+ * reaches a TypeScript source, shared by the install-time prefetch resolver
+ * and the `require()` inside a running facet.
+ *
+ * TypeScript's `"moduleResolution": "NodeNext"` requires authors to write the
+ * OUTPUT extension in a specifier that names a TypeScript source:
+ *
+ *     // packages/cli/bin/cli.ts
+ *     import '../src/program.js';        // means ../src/program.ts
+ *
+ * That is not one project's quirk, it is what every modern TS project on
+ * NodeNext looks like. Real bun resolves it; node does not.
+ *
+ * SCOPE — this resolver serves node as well, so the rule is deliberately a
+ * FALLBACK rather than a reordering: these candidates are probed only after
+ * every candidate node itself would try has missed, and they only ever name a
+ * TypeScript source. The inputs whose resolution changes are therefore exactly
+ * the inputs that resolve to nothing today, where node's own answer is
+ * "Cannot find module". No module graph that resolves now resolves
+ * differently, so nothing about node's semantics moves — while the TypeScript
+ * projects Nimbus already transforms and runs become resolvable.
+ *
+ * The one bun behaviour deliberately NOT adopted is its probe ORDER. Bun tries
+ * `.tsx, .ts, .jsx, .js`, so for `./m` with both `m.ts` and `m.js` present bun
+ * answers `m.ts` and node answers `m.js`. Preferring the TypeScript file there
+ * would change a specifier that already resolves, which is the one thing this
+ * scoping promises not to do.
+ *
+ * Mapping measured against bun 1.3.1, not recalled:
+ *   ./m.js   → m.ts, m.tsx      (and m.js itself still wins when it exists)
+ *   ./m.mjs  → m.mts
+ *   ./m.cjs  → nothing; bun does not map it to m.cts
+ *   ./m      → m.ts, m.tsx
+ *
+ * `getTypescriptSpecifiersJS()` emits the same mapping for the facet shim.
+ * The two bodies are checked against each other mechanically —
+ * tests/unit/typescript-specifier-resolution.mjs evaluates the emitted one and
+ * compares it to this one over the whole table — because a "keep in sync"
+ * comment has never once caught a drift.
+ */
+/**
+ * TypeScript sources a specifier may name once every path node itself would
+ * take has missed. Empty when the specifier cannot name one.
+ */
+export declare function typescriptFallbackCandidates(base: string): string[];
+/** Directory entry points, probed after node's `index.{js,cjs,mjs,json}`. */
+export declare const TYPESCRIPT_INDEX_CANDIDATES: readonly ["/index.ts", "/index.tsx"];
+/**
+ * The same mapping as raw JS, for embedding in the facet shim.
+ *
+ * The regex and the index list are interpolated from the definitions above so
+ * only the four-branch body is written twice, and the equivalence of the two
+ * bodies is asserted over the whole table by the unit test rather than
+ * asserted by a comment.
+ */
+export declare function getTypescriptSpecifiersJS(): string;
+//# sourceMappingURL=typescript-specifiers.d.ts.map

package/dist/_shared/typescript-specifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-specifiers.d.ts","sourceRoot":"","sources":["../../src/_shared/typescript-specifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAKH;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQnE;AAED,6EAA6E;AAC7E,eAAO,MAAM,2BAA2B,sCAAuC,CAAC;AAEhF;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAelD"}