@nimbus-sh/worker 0.1.0

package/dist/npm/resolve-facet.d.ts

@@ -0,0 +1,202 @@
+/**
+ * npm-resolve-facet.ts — NimbusLoaderPool entry for the npm resolver phase.
+ *
+ * Why this exists
+ * ───────────────
+ * The resolver crashes the supervisor DO during `npm install` of any
+ * non-trivial app:
+ *   1. `await resp.json()` at src/npm-resolver.ts:306 deserializes the
+ *      ENTIRE packument as a JS object. Packuments for widely-versioned
+ *      packages (lucide-react, react-router-dom, framer-motion, …) can
+ *      be 5–20 MB; parsed object expands ~3× in V8. With pLimit(6),
+ *      6 concurrent slots can hold ~360 MB transient peak — well over
+ *      the 128 MB DO heap cap.
+ *   2. The fetch-proxy worker (src/nimbus-session.ts:1666-1714) is a
+ *      singleton that buffers each response via `resp.arrayBuffer()`.
+ *      With 6 concurrent calls in flight, ONE 128 MB isolate holds
+ *      6 × packument-bytes simultaneously.
+ *
+ * The fix is to dispatch the entire resolver phase to a NimbusLoaderPool
+ * isolate. The facet has its own 128 MB; the supervisor's heap stays
+ * flat through phase 1 (the smoking gun: cumulativePackumentBytesDecoded
+ * stays near 0 in the supervisor counters post-fix).
+ *
+ * Topology choice (per /workspace plan): ONE facet for the whole walk,
+ * not pool.map per-spec. Rationale:
+ *   - 456-spec walk × per-spec dispatch overhead = excessive cold-starts.
+ *   - The CPU work per spec is small; the heap is the issue.
+ *   - A single facet running the breadth-first walk has its own 128 MB,
+ *     reuses the same fetch handle, batches RPC writes back via
+ *     env.SUPERVISOR.putRegistryEntries, and has its heap fully released
+ *     when the facet returns.
+ *
+ * Concurrency inside the facet uses pLimit(6) — same value as today's
+ * in-supervisor resolver, but now with a fresh 128 MB to absorb the
+ * transient parse spikes.
+ *
+ * Worst-case facet heap budget (with concurrency 4, set by the
+ * supervisor dispatcher):
+ *   - cachedEntries map: ≤ 2.5 MiB (capped at 5000 × ~500 B)
+ *   - 4 concurrent packument text+parse buffers: up to 4 × ~20 MiB
+ *     for pathologically large packuments = 80 MiB transient peak.
+ *     For typical npm packages (<2 MiB packument), this is ~8 MiB.
+ *   - resolved Map: ~228 KiB for a 456-package install.
+ *   - Total worst-case: ~85 MiB. Comfortably under the 128 MB cap with
+ *     ~40 MiB headroom for V8 overhead + esbuild-runtime shim.
+ *
+ * Stability invariants (cloudflare-parallel serialises via fn.toString):
+ *   - No `this` references.
+ *   - No closure capture other than args + preamble names.
+ *   - All helpers (semver match, exports field, skip list) live in the
+ *     preamble (src/parallel/npm-resolve-preamble.ts) so the facet has
+ *     them in its lexical scope.
+ *
+ * Cache strategy:
+ *   The supervisor pre-loads cached registry entries (already-resolved
+ *   packages from prior installs) and ships them in the spec. The facet
+ *   reconstructs a name → versions[] map and uses it to short-circuit
+ *   fetches on hits. For cold sessions, the cache is empty (~0 bytes
+ *   over the wire). For warm sessions, ~500 B per cached entry × at
+ *   most 5000 entries = 2.5 MB, well under the 32 MB RPC cap.
+ *
+ *   Cache writes flow back via env.SUPERVISOR.putRegistryEntries in
+ *   waves (every 50 resolved packages or end-of-phase, whichever first).
+ *   Doesn't block forward progress.
+ */
+import type { ResolvedPackage } from './resolver.js';
+export interface FacetCachedEntry {
+    /** Same shape as RegistryCacheEntry from src/npm-cache.ts. JSON-only
+     *  fields so the structured-clone over RPC doesn't choke. */
+    name: string;
+    version: string;
+    tarballUrl: string;
+    integrity: string;
+    depsJson: string;
+    /** X.5-F R2: required peerDependencies (optionals filtered). Optional
+     *  for backward compat with supervisor builds that pre-date X.5-F. */
+    peerDepsJson?: string;
+    exportsJson: string;
+    main: string;
+    moduleField: string;
+    binJson: string;
+    fetchedAt: number;
+}
+export interface ResolveFacetSpec {
+    /** Root specs from the caller's package.json — { name → semver range }. */
+    specs: Record<string, string>;
+    /** Cached registry entries the supervisor already has. The facet uses
+     *  these to skip fetches for packages whose resolved version is
+     *  already known. Empty on cold sessions. */
+    cachedEntries: FacetCachedEntry[];
+    /** Concurrency cap (default 6 — same as in-supervisor RESOLVE_CONCURRENCY). */
+    concurrency: number;
+    /** Per-fetch timeout (ms). */
+    fetchTimeoutMs: number;
+    /** Cap on retries for transient failures. */
+    retries: number;
+    /** W11: when true, FRAMEWORK_REQUIRED_PACKAGES (vite, …) are exempted
+     *  from the skip list. See audit/sections/W11-plan.md §3.0. */
+    frameworkAware?: boolean;
+}
+/**
+ * W6.5: Telemetry-event mirror of `RegistryEvent` (defined in
+ * `src/wasm-swap-registry.ts`). The facet cannot import the registry
+ * (preamble has no import surface), so the type is duplicated here.
+ * Parity is gated by audit/probes/w6.5/regression/event-fires-from-facet.mjs.
+ */
+export type FacetRegistryEvent = {
+    type: 'swap';
+    from: string;
+    to: string;
+    ctx: 'transitive';
+} | {
+    type: 'reject';
+    from: string;
+    reason: string;
+    suggest?: string;
+    ctx: 'transitive';
+} | {
+    type: 'transitive-skip';
+    from: string;
+    reason: string;
+};
+export interface ResolveFacetResult {
+    /** Resolved packages, lean (no packument retained). */
+    resolved: ResolvedPackage[];
+    /** Per-spec status messages — surfaced into the install log as
+     *  `[resolve-facet] <line>`. Bounded to ~one line per resolved spec. */
+    messages: string[];
+    /**
+     * W6.5: registry decisions taken inside the facet (swap / transitive-
+     * skip / reject). Drained by the supervisor and forwarded to the
+     * registry sink via `emitRegistryEvent`. See npm-installer.ts.
+     *
+     * Note: throw-path reject events do NOT reach this field today (the
+     * facet throws before returning). Documented gap in W6.5-plan §5.3.
+     */
+    registryEvents: FacetRegistryEvent[];
+    /** Counter snapshot at end of phase. Mirrors src/diag-counters.ts shape
+     *  for the resolver subset, so the supervisor can fold these into its
+     *  own counters before responding to /api/_diag/memory. */
+    facetCounters: {
+        inFlightPeak: number;
+        cumulativeBytesDecoded: number;
+        packumentsDecoded: number;
+        lastPackumentName: string;
+        lastPackumentBytes: number;
+        /** [W4] Pipelined-RPC race outcomes for the packument cache. */
+        pipelinedPackumentRaceWins: number;
+        pipelinedPackumentRaceLosses: number;
+    };
+    /**
+     * cache-obs-2: per-tier cache events for the packument tier
+     * (L2/L3 spliced from supervisor RPC return; L4 from registry
+     * fetches). Folded supervisor-side in installer.ts via
+     * recordCacheStatEvents.
+     */
+    cacheStatEvents: Array<{
+        kind: 'hit';
+        tier: 'L2' | 'L3' | 'L4';
+        cacheKind: 'packument';
+        bytes: number;
+    } | {
+        kind: 'miss';
+        tier: 'L2' | 'L3' | 'L4';
+        cacheKind: 'packument';
+    }>;
+    /** Wall-clock elapsed inside the facet. */
+    elapsed: number;
+    /** Cache writes the facet flushed back via env.SUPERVISOR.putRegistryEntries. */
+    cacheWriteCount: number;
+}
+export declare const resolveTreeInFacet: (spec: ResolveFacetSpec, env: {
+    SUPERVISOR: {
+        putRegistryEntries(entries: any[]): Promise<{
+            written: number;
+            failed: number;
+        }>;
+        getCachedPackument?: (name: string) => Promise<{
+            json: string;
+            ageMs: number;
+            expired: boolean;
+        } | null | {
+            cached: {
+                json: string;
+                ageMs: number;
+                expired: boolean;
+            } | null;
+            events: Array<{
+                kind: "hit";
+                tier: string;
+                cacheKind: string;
+                bytes: number;
+            } | {
+                kind: "miss";
+                tier: string;
+                cacheKind: string;
+            }>;
+        }>;
+        putCachedPackument?: (name: string, json: string) => Promise<boolean>;
+    };
+}) => Promise<ResolveFacetResult>;
+//# sourceMappingURL=resolve-facet.d.ts.map

package/dist/npm/resolve-facet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-facet.d.ts","sourceRoot":"","sources":["../../src/npm/resolve-facet.ts"],"names":[],"mappings":"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"}