@nimbus-sh/worker 0.1.0

package/dist/facets/wasm-swap-registry.js

@@ -0,0 +1,551 @@
+/**
+ * W6 — WASM swap + REJECT_INSTALL registry.
+ *
+ * The contract:
+ *   - WASM_SWAPS    : name→name rewrite at the resolver/installer boundary.
+ *                     Only `compat: 'drop-in'` swaps qualify (the consumer's
+ *                     `require()` call site works unchanged). Different-
+ *                     require-name candidates (bcrypt → bcryptjs, argon2 →
+ *                     hash-wasm, …) are NOT swaps until the resolver supports
+ *                     `npm:` aliases. They live in REJECT_INSTALL with a
+ *                     code-change suggestion.
+ *
+ *   - REJECT_INSTALL: deny list with helpful messages. Each entry has a
+ *                     per-entry `transitive` policy:
+ *                       'fail' = hard-fail at any depth (top + transitive).
+ *                       'warn' = top-level fails; transitive logs `[skip]`
+ *                                and continues (matches the existing
+ *                                `shouldSkipPackage` UX for build-only).
+ *
+ * IMPORTANT: This module is the single source of truth in the supervisor
+ * isolate. The same data is *duplicated* into
+ * `src/parallel/npm-resolve-preamble.ts` because that preamble is shipped
+ * into NimbusLoaderPool isolates as a string (cannot `import`). The
+ * `audit/probes/w6/functional/preamble-parity.mjs` snapshot test gates
+ * the duplication.
+ *
+ * See `audit/sections/W6-plan.md` §3.
+ */
+// ─────────────────────────────────────────────────────────────────────────
+// Registries
+// ─────────────────────────────────────────────────────────────────────────
+export const WASM_SWAPS = [
+    // Different-require-name candidates (bcrypt → bcryptjs, argon2 →
+    // hash-wasm, node-sass → sass, grpc → @grpc/grpc-js, @swc/core →
+    // @swc/wasm-web) are intentionally NOT here. Without npm-alias
+    // support, swapping them would silently break the user's
+    // `require(originalName)` call site. They are in REJECT_INSTALL
+    // with a code-change suggestion. Tracked as W6.5 to add alias
+    // support. See plan §2 + §10.
+    {
+        from: 'esbuild',
+        to: 'esbuild-wasm',
+        reason: 'Native esbuild not available in Workers; esbuild-wasm exposes the same build/transform/version/initialize API.',
+        compat: 'drop-in',
+    },
+    // X.5-G G2: rollup ships native platform shards as
+    // `optionalDependencies` (26 of them). On any host where the matching
+    // shard isn't present, rollup's own `native.js` throws the famous
+    // 'npm has a bug related to optional dependencies (#4828)'. Even
+    // when the matching shard IS installed, the .node binary cannot
+    // load in workerd. @rollup/wasm-node is the upstream-published
+    // pure-WASM build with byte-identical exports (verified via registry
+    // packument compare 2026-05-05; both ship `dist/rollup.js` with the
+    // same `exports` map). Drop-in swap.
+    {
+        from: 'rollup',
+        to: '@rollup/wasm-node',
+        reason: 'Native rollup uses optionalDependencies for 26 platform shards (npm CLI bug #4828) ' +
+            'and ships .node binaries that workerd cannot load. @rollup/wasm-node is the upstream ' +
+            'pure-WASM build with identical exports.',
+        compat: 'drop-in',
+    },
+];
+export const REJECT_INSTALL = [
+    // ── Same-require-name natives that crash at load time ────────────────
+    {
+        from: 'sharp',
+        reason: 'Native libvips bindings; not portable to Workers.',
+        suggest: 'no Workers-compatible target — render server-side or use Cloudflare Images. ' +
+            'For the wasm32 build see @img/sharp-wasm32 entry below.',
+        transitive: 'fail',
+    },
+    {
+        from: 'sqlite3',
+        reason: 'Native sqlite3 .node binding.',
+        suggest: 'better-sqlite3-wasm (untested by Nimbus) or sql.js (loader gap — see audit/probes/w6.5/spike/sql-js.verdict.md).',
+        transitive: 'fail',
+    },
+    {
+        from: 'better-sqlite3',
+        reason: 'Native sqlite .node binding.',
+        suggest: 'better-sqlite3-wasm (untested by Nimbus) or @libsql/client (resolver subpath gap — see audit/probes/w6.5/spike/libsql-client.verdict.md; may already work post-W2.6a).',
+        transitive: 'fail',
+    },
+    {
+        from: 'canvas',
+        reason: 'Native Cairo bindings.',
+        suggest: 'canvaskit-wasm (Skia → WASM, canvas-API-compatible, ~7MB; untested by Nimbus) ' +
+            'or @resvg/resvg-wasm for SVG (verified — see audit/probes/wasm/resvg-wasm.out.txt).',
+        transitive: 'fail',
+    },
+    {
+        from: 'sodium-native',
+        reason: 'Native libsodium.',
+        suggest: 'tweetnacl (pure JS, untested by Nimbus) or libsodium-wrappers (WASM, untested by Nimbus).',
+        transitive: 'fail',
+    },
+    {
+        from: 'fsevents',
+        reason: 'macOS-only filesystem watcher; never runs in Workers.',
+        suggest: 'optional dep — chokidar/watchpack work without it (untested by Nimbus). ' +
+            'Move to optionalDependencies in your package.json.',
+        transitive: 'warn',
+    },
+    {
+        from: 'bufferutil',
+        reason: 'Native binding for ws speedups; install requires node-gyp.',
+        suggest: 'optional dep — ws works without it (slower frames; untested by Nimbus). ' +
+            'Move to optionalDependencies.',
+        transitive: 'warn',
+    },
+    {
+        from: 'utf-8-validate',
+        reason: 'Native binding for ws speedups; install requires node-gyp.',
+        suggest: 'optional dep — ws works without it (untested by Nimbus). Same as bufferutil.',
+        transitive: 'warn',
+    },
+    {
+        from: 'node-pty',
+        reason: 'PTY syscalls unavailable in workerd.',
+        suggest: 'no Workers-compatible target — use the Nimbus built-in shell.',
+        transitive: 'fail',
+    },
+    {
+        from: 'robotjs',
+        reason: 'Desktop automation; sandboxed Workers cannot access OS UI.',
+        suggest: 'no Workers-compatible target.',
+        transitive: 'fail',
+    },
+    {
+        from: 'electron',
+        reason: 'Embedded Chromium runtime; not applicable to Workers.',
+        suggest: 'no Workers-compatible target.',
+        transitive: 'fail',
+    },
+    // ── Different-require-name natives (would be swaps with alias support) ─
+    {
+        from: 'bcrypt',
+        reason: 'Native bcrypt; pure-JS bcryptjs has identical sync API but the require() name differs and Nimbus does not yet support `npm:` aliases (W6.6).',
+        suggest: 'change `require("bcrypt")` to `require("bcryptjs")`, then `npm install bcryptjs` (verified — see audit/probes/wasm/bcryptjs.out.txt). APIs are sync-compatible.',
+        transitive: 'fail',
+    },
+    {
+        from: 'argon2',
+        reason: 'Native Argon2 C bindings.',
+        suggest: 'hash-wasm (argon2d/argon2i/argon2id; verified — see audit/probes/wasm/hash-wasm.out.txt).',
+        transitive: 'fail',
+    },
+    {
+        from: 'node-sass',
+        reason: 'Native libsass; deprecated upstream.',
+        suggest: 'sass (dart-sass, pure JS — partial support: top-level CJS load fails today, see audit/probes/wasm/sass.out.txt; untested for ESM imports).',
+        transitive: 'fail',
+    },
+    {
+        from: 'grpc',
+        reason: 'Deprecated native gRPC.',
+        suggest: '@grpc/grpc-js (pure JS — runtime resolver gap on internal subpath today, see audit/probes/wasm/grpc-grpc-js.out.txt; untested end-to-end).',
+        transitive: 'fail',
+    },
+    {
+        from: '@swc/core',
+        reason: 'Native Rust SWC.',
+        suggest: '@swc/wasm-web (transform/parse only; no Plugin API; loader gap — see audit/probes/wasm/swc-wasm-web.out.txt and audit/probes/w6.5/spike/swc-wasm-web.verdict.md).',
+        transitive: 'fail',
+    },
+    // ── ORM natives ──────────────────────────────────────────────────────
+    {
+        from: 'prisma',
+        reason: 'Native query engine; not portable to Workers in this configuration.',
+        suggest: '@prisma/adapter-d1 (Prisma official Workers adapter, untested by Nimbus), ' +
+            'or migrate to drizzle-orm + @libsql/client (untested; @libsql/client has known resolver gap — see audit/probes/wasm/libsql-client.out.txt).',
+        transitive: 'fail',
+    },
+    {
+        from: '@prisma/client',
+        reason: 'Same as `prisma` (native query engine).',
+        suggest: '@prisma/adapter-d1 (untested by Nimbus), or drizzle-orm + @libsql/client (untested).',
+        transitive: 'fail',
+    },
+    // ── Build-time native compilers (always wrong in Workers) ───────────
+    {
+        from: 'node-gyp',
+        reason: 'Build-time native compiler; never runs in Workers.',
+        suggest: 'no Workers-compatible target — remove from dependencies. Nimbus pre-skips build-only tools transitively.',
+        transitive: 'warn',
+    },
+    {
+        from: 'node-pre-gyp',
+        reason: 'Build-time native compiler; never runs in Workers.',
+        suggest: 'no Workers-compatible target — remove from dependencies.',
+        transitive: 'warn',
+    },
+    // ── Bundled-binary giants ──────────────────────────────────────────
+    {
+        from: 'puppeteer',
+        reason: 'Bundled Chromium binary (~150 MB).',
+        suggest: 'no Workers-compatible target for the bundled binary — use puppeteer-core + Cloudflare Browser Rendering (untested by Nimbus).',
+        transitive: 'fail',
+    },
+    {
+        from: 'playwright',
+        reason: 'Bundled browsers (~300 MB).',
+        suggest: 'no Workers-compatible target for bundled browsers — use @playwright/test against a remote browser endpoint (untested by Nimbus).',
+        transitive: 'fail',
+    },
+    // ── Loader-gap honesty (install OK; runtime FAIL today) ─────────────
+    // These come out of REJECT once the loader work lands. Spike verdicts
+    // (audit/probes/w6.5/spike/) confirmed both gaps span >1 src/ file.
+    {
+        from: 'sql.js',
+        reason: 'Installs but fails at runtime: ENOENT on dist/sql-wasm.wasm. Loader gap NOT in tar extraction — likely between streamTarEntries and writeBatch RPC handler, or in cirrus-real fs shim. See audit/probes/w6.5/spike/sql-js.verdict.md.',
+        suggest: 'no Workers-compatible target today — tracked for W6.5.x (multi-file fix exceeded W6.5 surface-area gate). For SQL in Workers consider Cloudflare D1 or @libsql/client (loader gap — see audit/probes/w6.5/spike/libsql-client.verdict.md).',
+        transitive: 'fail',
+    },
+    {
+        from: '@swc/wasm-web',
+        reason: 'Installs but fails at runtime: node-shims.ts:2058 throws "Cannot load module … file was not pre-bundled" — this is a workerd CSP-like new-Function block, not a slice walker gap. See audit/probes/w6.5/spike/swc-wasm-web.verdict.md.',
+        suggest: 'no Workers-compatible target today — tracked for W6.5.x (general facet-runtime issue, not @swc/wasm-web-specific). For ESM transforms consider esbuild-wasm (verified — see audit/probes/wasm/esbuild-wasm.out.txt; a Nimbus W6 swap target).',
+        transitive: 'fail',
+    },
+    // ── W6.5 additions: WASM/wasi-flavour packages that don't load ──────
+    {
+        from: '@img/sharp-wasm32',
+        reason: 'WASM build of sharp; package is wasm32-cpu-only (npm refuses install on x64) AND libvips initThreads() fails under workerd (no pthread support — see audit/sections/07-workerd-hard-limits.md).',
+        suggest: 'wasm-vips (verified install + load, default-export-only API — see audit/probes/wasm/wasm-vips.out.txt). For complex pipelines: render server-side and ship pixels.',
+        transitive: 'fail',
+    },
+    {
+        from: '@napi-rs/canvas',
+        reason: 'Native bindings only (linux-x64-gnu/musl, darwin-arm64/x64, android-arm64, linux-arm64-gnu/musl, win32-x64-msvc, linux-arm-gnueabihf). No WASM build published.',
+        suggest: 'canvaskit-wasm (Skia → WASM, canvas-API-compatible, ~7MB; untested by Nimbus) ' +
+            'or @resvg/resvg-wasm for SVG (verified — see audit/probes/wasm/resvg-wasm.out.txt).',
+        transitive: 'fail',
+    },
+    {
+        from: '@napi-rs/canvas-wasm32-wasi',
+        reason: '@napi-rs/canvas does not publish a wasm32-wasi variant on npm (404). The @napi-rs/canvas project ships only native bindings. No WASM/WASI build exists.',
+        suggest: 'canvaskit-wasm (Skia → WASM, canvas-API-compatible; untested by Nimbus) ' +
+            'or @resvg/resvg-wasm (verified — see audit/probes/wasm/resvg-wasm.out.txt) for SVG.',
+        transitive: 'fail',
+    },
+    // ── X.5-26b additions: Tailwind v4 oxide + lightningcss native parents ─
+    // Both ship only platform-native .node bindings + a wasm32-wasi shard.
+    // workerd has no node:wasi (W6.5 hard limit), so neither path loads.
+    // Without these REJECT entries, both parents install fine and surface
+    // a misleading runtime error (npm-4828 fallthrough for oxide, detect-
+    // libc execSync gap for lightningcss). With transitive='fail', the
+    // install is loud-rejected at resolve time → ⚠ → ⛔ classifier flip.
+    // Investigation: audit/probes/x526b/investigation/{tailwindcss-oxide,lightningcss}.out.txt
+    // Plan: audit/sections/X526b-plan.md §3.1
+    // Functional probes: audit/probes/x526b/functional/{oxide,lightningcss}-rejected.mjs
+    // E2E probes: audit/probes/x526b/e2e/{oxide,lightningcss,tailwindcss-vite-transitive}-e2e.mjs
+    {
+        from: '@tailwindcss/oxide',
+        reason: 'Native Rust Tailwind v4 oxide engine; ships only platform-specific .node bindings (linux-x64-gnu/musl, darwin-x64/arm64, freebsd-x64, win32-x64-msvc, etc.) plus a wasm32-wasi shard. workerd has no node:wasi (W6.5 hard limit; see audit/sections/07-workerd-hard-limits.md), and bare native bindings cannot dlopen. The parent index.js throws an npm-4828 message at runtime when no sibling shard loads.',
+        suggest: 'no Workers-compatible target — Tailwind v3 (`tailwindcss@^3`) is pure JS and works in Workers (untested by Nimbus). Tailwind v4 inherently requires the Rust oxide engine.',
+        transitive: 'fail',
+    },
+    {
+        from: 'lightningcss',
+        reason: 'Native Rust CSS parser; ships platform-specific .node bindings + a wasm32-wasi-only `lightningcss-wasm` package (cpu=wasm32; npm refuses install on x64). workerd has no node:wasi (W6.5). Even before the binding load, the detect-libc dependency throws because child_process.execSync returns undefined inside workerd.',
+        suggest: 'no Workers-compatible target today — postcss + cssnano (pure JS, untested by Nimbus) cover most lightningcss use cases. For CSS minification only: clean-css (pure JS, untested by Nimbus).',
+        transitive: 'fail',
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────
+// Lookup API
+// ─────────────────────────────────────────────────────────────────────────
+const _swapByFrom = new Map(WASM_SWAPS.map((e) => [e.from, e]));
+const _rejectByFrom = new Map(REJECT_INSTALL.map((e) => [e.from, e]));
+export function lookupSwap(name) {
+    return _swapByFrom.get(name);
+}
+export function lookupReject(name) {
+    return _rejectByFrom.get(name);
+}
+/**
+ * Pure: return a new specs map with every WASM_SWAPS.from key rewritten
+ * to its swap target. Records the swaps actually performed.
+ *
+ * Idempotent: running on already-swapped specs is a no-op.
+ *
+ * Range carry-over: the original spec range is preserved on the new key.
+ * (Future W6.5 may want 'latest' to force pulling the current swap-target
+ * version, but for now we honour the user's intent.)
+ */
+export function applySwaps(specs) {
+    const out = {};
+    const swaps = [];
+    for (const [name, range] of Object.entries(specs)) {
+        const swap = _swapByFrom.get(name);
+        if (swap) {
+            out[swap.to] = range;
+            swaps.push(swap);
+        }
+        else {
+            out[name] = range;
+        }
+    }
+    return { specs: out, swaps };
+}
+/**
+ * Return rejects whose policy applies at this depth.
+ *   ctx='top'        → all matching rejects (any policy).
+ *   ctx='transitive' → only `transitive: 'fail'` rejects (the 'warn'
+ *                      policy is handled by the caller as a `[skip]`
+ *                      log + continue).
+ */
+export function findRejects(specs, ctx) {
+    const out = [];
+    for (const name of Object.keys(specs)) {
+        const r = _rejectByFrom.get(name);
+        if (!r)
+            continue;
+        if (ctx === 'transitive' && r.transitive !== 'fail')
+            continue;
+        out.push(r);
+    }
+    return out;
+}
+/**
+ * Lookup that the resolver uses at depth>0 to decide between throw and
+ * `[skip]`+continue. Returns the entry only when its policy is 'warn'
+ * (i.e., this is a transitive-skip case). 'fail' entries return undefined
+ * here; the caller handles those via findRejects/throw.
+ */
+export function shouldWarnSkipTransitive(name) {
+    const r = _rejectByFrom.get(name);
+    if (r && r.transitive === 'warn')
+        return r;
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Formatters
+// ─────────────────────────────────────────────────────────────────────────
+const ANSI_RED = '\x1b[31m';
+const ANSI_YELLOW = '\x1b[33m';
+const ANSI_DIM = '\x1b[2m';
+const ANSI_RESET = '\x1b[0m';
+/**
+ * Single-line yellow notice emitted to onProgress when a swap fires.
+ *   `[npm] [swap] esbuild → esbuild-wasm (Native esbuild not available …)`
+ */
+export function formatSwapNotice(s) {
+    return `[npm] ${ANSI_YELLOW}[swap]${ANSI_RESET} ${s.from} → ${s.to} (${s.reason})`;
+}
+/**
+ * Multi-line red error thrown when one or more top-level rejects fire.
+ * Includes a leading summary line and a `try:` suggestion per package
+ * (when present).
+ */
+export function formatRejectError(rejects) {
+    if (rejects.length === 0)
+        return '';
+    const head = `${ANSI_RED}npm install rejected:${ANSI_RESET} ${rejects.length} package${rejects.length === 1 ? '' : 's'} not supported on Nimbus.`;
+    const lines = rejects.map((r) => {
+        const main = `  ❌ ${r.from} — ${r.reason}`;
+        if (r.suggest) {
+            return `${main}\n     ${ANSI_DIM}try:${ANSI_RESET} ${r.suggest}`;
+        }
+        return main;
+    });
+    return [head, ...lines].join('\n');
+}
+/**
+ * Single-line yellow notice emitted for a transitive `[skip]`.
+ *   `[npm] [skip] fsevents — macOS-only filesystem watcher; never runs in Workers`
+ */
+export function formatTransitiveSkip(r) {
+    return `[npm] ${ANSI_YELLOW}[skip]${ANSI_RESET} ${r.from} — ${r.reason}`;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Error class — used to mark registry-driven rejects across the
+// supervisor/facet boundary
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Tag class for registry-driven rejects. Both the supervisor-side path
+ * (npm-installer.ts:applyW6Registry, npm-resolver.ts:resolveTree) and the
+ * facet-side path (npm-resolve-facet.ts:resolveTreeInFacet) throw errors
+ * tagged for this case.
+ *
+ * Supervisor-side: throw `new RegistryRejectError(rejects)` directly.
+ * Facet-side: cannot import this class (preamble has no import surface),
+ *   so the facet throws `new Error(...)` with `err.__w6_reject = true`.
+ *   Both are detected via `isRegistryReject()`.
+ *
+ * The own-property `__w6_reject = true` survives any boundary that
+ * preserves error own-properties (NimbusLoaderPool's loadable contract
+ * is checked in audit/probes/w6/ ...).
+ */
+export class RegistryRejectError extends Error {
+    rejects;
+    __w6_reject = true;
+    constructor(rejects) {
+        super(formatRejectError(rejects));
+        this.name = 'RegistryRejectError';
+        this.rejects = rejects;
+    }
+}
+/**
+ * Robust check that survives the supervisor↔facet boundary: prototypes
+ * are lost across that boundary, so we tag via an own-property.
+ */
+export function isRegistryReject(e) {
+    return !!(e && typeof e === 'object' && e.__w6_reject === true);
+}
+let _sink = null;
+let _sinkThrowCount = 0;
+/**
+ * Install (or clear, with `null`) the global registry event sink.
+ *
+ * The sink is a per-isolate singleton. The supervisor isolate's sink does
+ * NOT propagate to facet isolates — facet emits travel through
+ * `ResolveFacetResult.registryEvents` and are flushed by the supervisor
+ * after the facet returns. See W6.5-plan.md §5.5 for the per-isolate
+ * invariant.
+ */
+export function setRegistryEventSink(s) {
+    _sink = s;
+}
+export function getRegistryEventSink() {
+    return _sink;
+}
+/**
+ * Forward an event to the sink. Sink throws are caught (telemetry must
+ * never break install) and counted.
+ */
+export function emitRegistryEvent(e) {
+    if (!_sink)
+        return;
+    try {
+        _sink(e);
+    }
+    catch {
+        _sinkThrowCount++;
+    }
+}
+/**
+ * Number of sink invocations that threw (and were caught). Useful for
+ * production monitoring (and probes).
+ */
+export function getSinkThrowCount() {
+    return _sinkThrowCount;
+}
+// Known native-shard name globs. Matched as `prefix-` (so the parent
+// package name without a platform suffix never matches).
+const NATIVE_SHARD_PREFIXES = [
+    '@rollup/rollup-',
+    '@parcel/watcher-',
+    '@swc/core-',
+    '@next/swc-',
+    '@tailwindcss/oxide-',
+    '@img/sharp-',
+    '@napi-rs/canvas-',
+    '@biomejs/cli-',
+    '@esbuild/',
+];
+/**
+ * Heuristic: does this packument represent a platform-native binding
+ * that workerd cannot load?
+ *
+ * Returns true when ANY of:
+ *   - `os`, `cpu`, or `libc` field is non-empty (npm spec platform
+ *     constraints — package is opting out of cross-platform installs).
+ *   - `main` ends in `.node` (Node.js N-API binary, not workerd-loadable).
+ *   - name matches a known native-shard glob (see NATIVE_SHARD_PREFIXES).
+ *
+ * Returns false for pure-JS packages, parent wrappers (e.g. the
+ * non-platform `@parcel/watcher` itself), and packuments with empty
+ * platform-constraint arrays.
+ *
+ * X.5-G G1: the resolver consults this on every packument fetched from
+ * a transitive `optionalDependencies` entry. Returns-true → silent-skip
+ * (emit a `transitive-skip` RegistryEvent, drop the package from the
+ * resolved tree).
+ */
+export function isOptionalNativeBinding(p) {
+    if (!p)
+        return false;
+    if (Array.isArray(p.os) && p.os.length > 0)
+        return true;
+    if (Array.isArray(p.cpu) && p.cpu.length > 0)
+        return true;
+    if (Array.isArray(p.libc) && p.libc.length > 0)
+        return true;
+    if (typeof p.main === 'string' && /\.node$/.test(p.main))
+        return true;
+    if (typeof p.name === 'string') {
+        for (const prefix of NATIVE_SHARD_PREFIXES) {
+            // Require the prefix-then-something-else shape. The parent package
+            // (e.g. `@parcel/watcher`, `@rollup/wasm-node`) does not match.
+            if (p.name.startsWith(prefix) && p.name.length > prefix.length) {
+                // Carve out @rollup/wasm-node: it's the WASM build, not a native shard.
+                if (p.name === '@rollup/wasm-node')
+                    return false;
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Select which entries in `peerDependencies` should be auto-installed.
+ *
+ * npm v7+ default behaviour:
+ *   - All `peerDependencies` entries auto-install.
+ *   - Entries marked `optional: true` in `peerDependenciesMeta` STILL
+ *     auto-install (with `--include=peer` default-on) — but tools may
+ *     opt-out with `--no-include=peer`.
+ *   - Entries that exist ONLY in `peerDependenciesMeta` (NOT in
+ *     `peerDependencies`) are NEVER auto-installed (they're feature-
+ *     detect signals, e.g. ts-jest's `esbuild`).
+ *
+ * X.5-G strict mode (the default here): we only iterate `peerDependencies`
+ * keys. peer-meta-only entries are excluded by construction.
+ *
+ * The `requiredOnly` flag, when true, also filters out entries marked
+ * optional in meta — used for transitive (depth>0) enqueue per X5F R2.
+ * When false (top-level / X5F R2.5), all `peerDependencies` entries are
+ * returned including optional-marked-in-meta ones (npm CLI default).
+ */
+export function selectAutoInstallPeers(pkg, opts = {}) {
+    const peers = pkg.peerDependencies || {};
+    const meta = pkg.peerDependenciesMeta || {};
+    const out = [];
+    for (const name of Object.keys(peers)) {
+        if (opts.requiredOnly && meta[name]?.optional)
+            continue;
+        out.push(name);
+    }
+    return out;
+}
+export function classifyInstallError(e, ctx = {}) {
+    if (isRegistryReject(e))
+        return 'registry-reject';
+    if (ctx.isOptional)
+        return 'optional-dep-skip';
+    return 'real-resolve-fail';
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Module-load assertion: WASM_SWAPS.from and REJECT_INSTALL.from are disjoint
+// ─────────────────────────────────────────────────────────────────────────
+(() => {
+    for (const s of WASM_SWAPS) {
+        if (_rejectByFrom.has(s.from)) {
+            throw new Error(`W6 registry conflict: '${s.from}' is in both WASM_SWAPS and REJECT_INSTALL. ` +
+                `A name must own one role.`);
+        }
+    }
+})();

package/dist/facets/ws-terminal.d.ts

@@ -0,0 +1,107 @@
+/**
+ * WebSocket-backed terminal matching Nimbus's ITerminal interface.
+ * HeadlessTerminal has: write, writeln, onData, sendData, cols, rows, focus, clear
+ *
+ * [B'.5] The `ws` ref is no longer readonly: a wsClose leaves the
+ * Shell + this terminal alive in-memory; the next /ws upgrade calls
+ * `attach(newWs, ...)` to swap in the new socket. The buffer/flush
+ * timer state is preserved across the swap so any in-flight
+ * coalescing continues seamlessly.
+ */
+export declare class WebSocketTerminal {
+    ws: WebSocket;
+    private dataCallback;
+    /**
+     * REPL-W1: secondary input callback installed by interactive runtimes
+     * (e.g. `python` no-args). When non-null, sendData() routes input to
+     * this callback INSTEAD of the shell. Set via attachRepl(); cleared
+     * by the disposer the attach call returns. Supports nesting (the
+     * disposer restores the prior callback).
+     *
+     * Reasoning per /workspace/.seal-internal/2026-05-11-repl-plan/plan.md
+     * §3 (Layer 2): the explicit handoff mirrors how `vim`/`less` swap
+     * the parent shell's terminal handler. Auto-detect was rejected as
+     * fragile. Additive only — when null, behavior is identical to pre-W1.
+     */
+    private replCallback;
+    /**
+     * monaco-wave-a (2026-05-13): Editor-pane file-system bridge.
+     *
+     * When non-null, fs-* messages (fs-read / fs-write / fs-list) are
+     * routed to this callback INSTEAD of the shell. The callback is
+     * supplied by init.ts which holds the SqliteVFS handle; it uses
+     * the same `reply` lambda we provide to send back fs-*-result
+     * frames over the live WS.
+     *
+     * Additive — when null, fs-* messages are silently dropped (same
+     * pre-Wave-A behavior, since handleMessage's switch had no case
+     * for them).
+     */
+    private fsCallback;
+    private _cols;
+    private _rows;
+    private buffer;
+    private flushTimer;
+    /** [B'.3] Optional tee called from flush() with the final coalesced
+     *  frame data. Used by initSession to mirror every WS output frame
+     *  into nimbus_terminal_scrollback. Single-frame granularity (not
+     *  per-write) keeps the row count bounded by the 5 ms flush cadence. */
+    private onFlush;
+    constructor(ws: WebSocket, onFlush?: (data: string) => void);
+    /**
+     * [B'.5] Swap the underlying WebSocket on a warm rejoin. The Shell
+     * keeps `terminal` as a stable instance reference (it stored
+     * `this.terminal = e` in its ctor); we just point our ws ref at
+     * the new socket. The optional onFlush replaces the prior tee
+     * (initSession passes a fresh closure capturing the same
+     * self.ctx, but TypeScript-wise it's a fresh function value).
+     */
+    attach(ws: WebSocket, onFlush?: (data: string) => void): void;
+    get cols(): number;
+    get rows(): number;
+    write(data: string): void;
+    writeln(data: string): void;
+    /**
+     * REPL-A1 (master plan §1): drain the buffer synchronously, bypassing
+     * the 5 ms coalescer. Used by ReplSession.submitLine to emit stdout,
+     * stderr, and the next-prompt as three discrete frames in deterministic
+     * order. Without this, all three coalesce into one `{type:'output'}`
+     * frame and probes asserting frame-order (stderr-before-stdout or
+     * prompt-after-output) see false-RED.
+     *
+     * Idempotent: cancels the pending timer + sends current buffer (if any).
+     * Safe to call on an empty buffer (no-op).
+     */
+    flushNow(): void;
+    private flush;
+    onData(callback: (data: string) => void): void;
+    handleMessage(msg: {
+        type: string;
+        data?: string;
+        cols?: number;
+        rows?: number;
+        path?: string;
+        content?: string;
+        dir?: string;
+        recursive?: boolean;
+    }): void;
+    /**
+     * monaco-wave-a (2026-05-13): install the fs-* message handler.
+     * The callback receives the raw message + a reply lambda that
+     * accepts a JSON-serializable frame and pushes it over this WS.
+     * Single-slot (last call wins) — init.ts is the only caller and
+     * reinstalls on warm rejoin via `attach()`.
+     */
+    onFs(cb: (msg: any, reply: (frame: any) => void) => void): void;
+    sendData(data: string): void;
+    /**
+     * REPL-W1: install a runtime-side input handler. Returns a disposer
+     * that restores the prior handler (supports nesting). Calling this
+     * does NOT change the shell's dataCallback — it just shadows it
+     * until the disposer runs.
+     */
+    attachRepl(cb: (data: string) => void): () => void;
+    focus(): void;
+    clear(): void;
+}
+//# sourceMappingURL=ws-terminal.d.ts.map

package/dist/facets/ws-terminal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-terminal.d.ts","sourceRoot":"","sources":["../../src/facets/ws-terminal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,iBAAiB;IACrB,EAAE,EAAE,SAAS,CAAC;IACrB,OAAO,CAAC,YAAY,CAAyC;IAC7D;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,YAAY,CAAyC;IAC7D;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,UAAU,CAAkE;IACpF,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,KAAK,CAAc;IAC3B,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAA8C;IAChE;;;4EAGwE;IACxE,OAAO,CAAC,OAAO,CAAkC;gBAErC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI;IAK3D;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAK7D,IAAI,IAAI,IAAI,MAAM,CAAuB;IACzC,IAAI,IAAI,IAAI,MAAM,CAAuB;IAEzC,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAOzB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAE3B;;;;;;;;;;OAUG;IACH,QAAQ,IAAI,IAAI;IAQhB,OAAO,CAAC,KAAK;IAeb,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAE9C,aAAa,CAAC,GAAG,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI;IA+C3J;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,KAAK,IAAI,GAAG,IAAI;IAI/D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO5B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAWlD,KAAK,IAAI,IAAI;IACb,KAAK,IAAI,IAAI;CACd"}