@nimbus-sh/core 0.6.0 → 0.8.0

package/README.md

@@ -5,16 +5,23 @@
 > presented as-is.
 
 The backend-agnostic half of Nimbus: a durable POSIX-like filesystem, a shell
-with 60+ Unix commands, and the WASI runtime layer — with no Cloudflare
-dependency. You hand it a SQLite and get back `.fs` and `.exec`. On
-Cloudflare that SQLite is `ctx.storage.sql` inside your Durable Object; in bun
-or node it is `bun:sqlite` or `node:sqlite`.
+with 60+ Unix commands, and the WASI runtime layer. It has no Cloudflare
+dependency.
 
-I extracted this package because I kept wanting Nimbus *inside* other
-projects — a Durable Object that already does something else but needs a real
-workspace, or a local script that needs the same filesystem semantics the
-hosted product has. The whole of it runs on two narrow ports (`SqlDatabase`
-and `SqlTransactions`), so the same code serves both hosts.
+You hand it a SQLite and get back `.fs` and `.exec`. On Cloudflare that
+SQLite is `ctx.storage.sql` inside your Durable Object; in bun or node it is
+`bun:sqlite` or `node:sqlite`. The whole package rests on two narrow ports
+(`SqlDatabase` and `SqlTransactions`), so the same code serves both hosts.
+
+Use it when something you already run needs a real workspace. A Durable
+Object that does something else and needs somewhere to work. A local script
+that needs the filesystem semantics the hosted product has.
+
+## Install
+
+```bash
+npm install @nimbus-sh/core
+```
 
 ## Quick start
 
@@ -73,13 +80,13 @@ export class Workspace extends DurableObject {
 ```
 
 Files written through `.fs` are owned by the session user (uid 1000), not
-root, and the shell enforces the same permission model either way: a
-root-owned `/etc/passwd` refuses a write from `.fs`, and `id` resolves names
-through it.
+root. The shell enforces the same permission model either way: a root-owned
+`/etc/passwd` refuses a write from `.fs`, and `id` resolves names through
+it.
 
 ## Real runtimes, off Cloudflare
 
-The wasm runtimes are separate npm packages so nobody downloads a Python
+The wasm runtimes are separate npm packages, so nobody downloads a Python
 interpreter to get a filesystem. Install the ones you want and pass them in:
 
 ```bash
@@ -104,35 +111,49 @@ await ws.exec(`python -c "import sqlite3; print('live')"`);  // CPython 3.13, re
 `@nimbus-sh/runtime-ruby` (Ruby 3.3) and `@nimbus-sh/runtime-clang` (clang →
 `wasm32-wasi`, compile and run C in the workspace) work the same way. Every
 package carries the same manifest and the same sha256-verified blobs the
-hosted product serves from R2 — one publisher, two transports.
+hosted product serves from R2.
+
+Without `facets` and `runtimes` you still get the full shell and coreutils.
+The wasm runtimes are a dependency you add.
 
-Without `facets` and `runtimes` you still get the full shell and coreutils;
-the wasm runtimes are a dependency you add, not a mode you enable. One caveat:
-`localFacetHost()` covers bun and node only — on workerd the CSP forbids
+`localFacetHost()` covers bun and node only. On workerd the CSP forbids
 request-time `WebAssembly.instantiate`, so wasm has to ride the Worker Loader
-module map, which is the machinery in `@nimbus-sh/worker` and
-`@nimbus-sh/fabric`; the shell, coreutils, and filesystem need none of it.
+module map. That machinery lives in `@nimbus-sh/worker` and
+`@nimbus-sh/fabric`. The shell, coreutils, and filesystem need none of it.
 
 ## Sharing a database with your own app
 
-The workspace is designed to be a tenant in a database you own, not the owner
-of it:
+The workspace is a tenant in a database you own:
 
 - It creates and touches only its own tables (`inodes`, `file_chunks`,
   `content_lifecycle`, `vfs_*`).
-- `destroy()` drops exactly those tables. It never calls `deleteAll()`.
+- `destroy()` drops those tables and does not call `deleteAll()`.
 - `transactionSync` must be a real transaction. An implementation that only
   calls the callback turns every atomic write into a torn one.
-- `generation` must never repeat across restarts of your host — pids derive
+- `generation` must never repeat across restarts of your host. Pids derive
   from it, and a repeated generation would hand a dead process live write
   authority.
 
-## What needs the Worker package instead
+When your own SQL rows must commit with filesystem bytes, use
+`SqliteVFS.withTransaction(callback)` instead of an outer
+`storage.transactionSync`. Use the credentialed synchronous VFS methods inside
+the callback, not the workspace's asynchronous file methods. The callback can
+read its writes; revisions and watch events publish only after commit. On
+rollback, Nimbus clears cached chunks and reloads the always-resident inode
+tree from SQLite before rethrowing with the original error as `cause`.
+
+The method must own the outermost transaction on the same SQL host. Do not
+nest it or start asynchronous work inside it. The host's transaction primitive
+must support nested savepoints for individual VFS writes. If rollback reload
+also fails, Nimbus throws an `AggregateError` carrying both failures; discard
+that VFS instance and reopen it after storage recovers.
+
+## What the worker package adds
 
 Resident processes (long-running servers, attached TUIs), the session
 protocol, port routing to the public internet, and the hosted terminal all
-live in [`@nimbus-sh/worker`](https://www.npmjs.com/package/@nimbus-sh/worker),
-which composes on this package. If you want the full hosted product shape,
+live in [`@nimbus-sh/worker`](https://www.npmjs.com/package/@nimbus-sh/worker).
+That package composes on this one. If you want the full hosted product shape,
 start from `npx create-nimbus-app`.
 
 ## License

package/dist/_shared/byte-stream.d.ts

@@ -17,10 +17,11 @@
 /**
  * A command's output destination.
  *
- * `writeBytes` is present on sinks that store bytes verbatim (files). Sinks
- * that are inherently textual — the terminal, shell pipes — omit it and
- * receive decoded text instead. This is a real capability difference, not a
- * fallback: a terminal has no way to hold a byte that is not text.
+ * `writeBytes` is present on sinks that store bytes verbatim — files,
+ * `/dev/null`, and shell pipes, which carry the producer's exact bytes.
+ * Sinks without it take decoded text instead. This is a real capability
+ * difference, not a fallback: a terminal has no way to hold a byte that is
+ * not text.
  */
 export interface ByteSink {
     write(text: string): void;

package/dist/_shared/byte-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"byte-stream.d.ts","sourceRoot":"","sources":["../../src/_shared/byte-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;AAEzE,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,QAAY,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,OAAO,CAAK;gBAES,IAAI,EAAE,QAAQ;IAI3C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAO9B,GAAG,IAAI,IAAI;CAKZ;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACvE,MAAM,CAkBR"}
+{"version":3,"file":"byte-stream.d.ts","sourceRoot":"","sources":["../../src/_shared/byte-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;AAEzE,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,QAAY,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,OAAO,CAAK;gBAES,IAAI,EAAE,QAAQ;IAI3C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAO9B,GAAG,IAAI,IAAI;CAKZ;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACvE,MAAM,CAkBR"}

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

@@ -38,6 +38,13 @@
  *                         constructed Session's connect/post are inert.
  *                         Tools (e.g. nuxi) that open a Session purely
  *                         for optional profiling degrade cleanly.
+ *   - node:zlib         — full surface: every *Sync variant, brotli/zstd,
+ *                         crc32, constants, and streaming create* factories
+ *                         (probe-verified 2026-08-23 at compat date
+ *                         2026-04-01). Forwarded verbatim by the zlib
+ *                         block in node-shims.ts; results are the host
+ *                         realm's own Buffers, which the widened
+ *                         __BufferMod.isBuffer recognizes.
  */
 export declare function getRealNodeImportsCode(): string;
 //# sourceMappingURL=real-node-imports.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"real-node-imports.d.ts","sourceRoot":"","sources":["../../src/_shared/real-node-imports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,wBAAgB,sBAAsB,IAAI,MAAM,CAW/C"}

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

@@ -38,6 +38,13 @@
  *                         constructed Session's connect/post are inert.
  *                         Tools (e.g. nuxi) that open a Session purely
  *                         for optional profiling degrade cleanly.
+ *   - node:zlib         — full surface: every *Sync variant, brotli/zstd,
+ *                         crc32, constants, and streaming create* factories
+ *                         (probe-verified 2026-08-23 at compat date
+ *                         2026-04-01). Forwarded verbatim by the zlib
+ *                         block in node-shims.ts; results are the host
+ *                         realm's own Buffers, which the widened
+ *                         __BufferMod.isBuffer recognizes.
  */
 export function getRealNodeImportsCode() {
     return `
@@ -48,5 +55,6 @@ 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';
+import * as __real_zlib from 'node:zlib';
 `.trim();
 }

package/dist/_shared/tarball.d.ts

@@ -1,5 +1,5 @@
 /**
- * tarball.ts — a whole tarball, in memory, as a path→bytes map.
+ * Tarball extraction for streaming installers and buffered archive consumers.
  *
  * The streaming primitives it walks with (`parseTarHeader`, `streamTarEntries`,
  * `readableStreamToAsyncIterable`) live in `./tarball-stream.ts` — a
@@ -7,11 +7,30 @@
  * into a string the loader pool injects into dynamic workers, where an import
  * would not resolve.
  *
- * This half is for a caller that already holds the bytes: `gem install`, which
- * fetches a `.gem` (a tar holding a gzipped tar) and needs both layers open at
- * once. An installer streaming a tarball it is still downloading should drive
- * `streamTarEntries` itself and never hold the whole thing.
+ * Installers use writeTarballStream. extractTarball retains a map for callers
+ * such as gem install, which must open an archive nested inside another one.
  */
+export interface TarballWriteTarget {
+    exists(path: string): boolean;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): void;
+    writeFile(path: string, data: Uint8Array | string): unknown;
+}
+export interface TarballWriteResult {
+    /** Regular files written, including the manifest. */
+    files: number;
+    /** Total decompressed bytes written. */
+    bytes: number;
+}
+/**
+ * Stream a gzipped npm archive into a package directory. Entry names are
+ * already canonical and prefix-stripped by streamTarEntries. Hold only the
+ * current entry and the manifest; write the manifest last so a failed install
+ * is not mistaken for a complete package on retry. A second manifest in one
+ * archive is a malformed package, not an overwrite. Filesystem failures reject.
+ */
+export declare function writeTarballStream(body: ReadableStream<Uint8Array>, targetDir: string, vfs: TarballWriteTarget): Promise<TarballWriteResult>;
 /** Extract every regular file. Gzipped input is decompressed first. */
 export declare function extractTarball(tarball: ArrayBuffer): Promise<Map<string, Uint8Array>>;
 //# sourceMappingURL=tarball.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../../src/_shared/tarball.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAOH,uEAAuE;AACvE,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAsBlC"}
+{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../../src/_shared/tarball.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAID;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,kBAAkB,GACtB,OAAO,CAAC,kBAAkB,CAAC,CA6B7B;AAED,uEAAuE;AACvE,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAsBlC"}

package/dist/_shared/tarball.js

@@ -1,5 +1,5 @@
 /**
- * tarball.ts — a whole tarball, in memory, as a path→bytes map.
+ * Tarball extraction for streaming installers and buffered archive consumers.
  *
  * The streaming primitives it walks with (`parseTarHeader`, `streamTarEntries`,
  * `readableStreamToAsyncIterable`) live in `./tarball-stream.ts` — a
@@ -7,12 +7,49 @@
  * into a string the loader pool injects into dynamic workers, where an import
  * would not resolve.
  *
- * This half is for a caller that already holds the bytes: `gem install`, which
- * fetches a `.gem` (a tar holding a gzipped tar) and needs both layers open at
- * once. An installer streaming a tarball it is still downloading should drive
- * `streamTarEntries` itself and never hold the whole thing.
+ * Installers use writeTarballStream. extractTarball retains a map for callers
+ * such as gem install, which must open an archive nested inside another one.
  */
 import { streamTarEntries, readableStreamToAsyncIterable, } from './tarball-stream.js';
+const PACKAGE_MANIFEST = 'package.json';
+/**
+ * Stream a gzipped npm archive into a package directory. Entry names are
+ * already canonical and prefix-stripped by streamTarEntries. Hold only the
+ * current entry and the manifest; write the manifest last so a failed install
+ * is not mistaken for a complete package on retry. A second manifest in one
+ * archive is a malformed package, not an overwrite. Filesystem failures reject.
+ */
+export async function writeTarballStream(body, targetDir, vfs) {
+    const ensureDir = (path) => {
+        if (!vfs.exists(path))
+            vfs.mkdir(path, { recursive: true });
+    };
+    ensureDir(targetDir);
+    let files = 0;
+    let bytes = 0;
+    let manifest = null;
+    const entries = streamTarEntries(readableStreamToAsyncIterable(body.pipeThrough(new DecompressionStream('gzip'))));
+    for await (const entry of entries) {
+        if (entry.name === PACKAGE_MANIFEST) {
+            if (manifest !== null) {
+                throw new Error(`tarball for ${targetDir} carried two ${PACKAGE_MANIFEST} entries`);
+            }
+            manifest = entry.data;
+            continue;
+        }
+        const fullPath = `${targetDir}/${entry.name}`;
+        const cut = fullPath.lastIndexOf('/');
+        if (cut > 0)
+            ensureDir(fullPath.slice(0, cut));
+        await vfs.writeFile(fullPath, entry.data);
+        files++;
+        bytes += entry.data.length;
+    }
+    if (!manifest)
+        throw new Error(`tarball for ${targetDir} carried no ${PACKAGE_MANIFEST}`);
+    await vfs.writeFile(`${targetDir}/${PACKAGE_MANIFEST}`, manifest);
+    return { files: files + 1, bytes: bytes + manifest.length };
+}
 /** Extract every regular file. Gzipped input is decompressed first. */
 export async function extractTarball(tarball) {
     const files = new Map();

package/dist/_shared/vfs-write-ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vfs-write-ledger.d.ts","sourceRoot":"","sources":["../../src/_shared/vfs-write-ledger.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,QAqZpC,CAAC;AAET,eAAO,MAAM,uBAAuB,QAgC5B,CAAC"}
+{"version":3,"file":"vfs-write-ledger.d.ts","sourceRoot":"","sources":["../../src/_shared/vfs-write-ledger.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,+BAA+B,QA2ZpC,CAAC;AAET,eAAO,MAAM,uBAAuB,QAgC5B,CAAC"}

package/dist/_shared/vfs-write-ledger.js

@@ -317,26 +317,32 @@ async function __nimbusPersistVfsWrite(supervisor, path, content, snapshot) {
 }
 
 /**
- * Write back everything parked, keeping any failure for the exit drain.
+ * Write back the cells parked at THIS instant, and only those.
  *
- * The write-back sites that are not the exit drain — the debounce below and
- * the RELEASE barrier ahead of egress — have no caller who could act on a
- * failure: there is no user frame to throw into, and rejecting the fetch that
- * happened to trigger the flush would blame the wrong operation. Retaining
- * the failure in the channel \`__nimbusDrainVfsMutations\` already drains means
- * the exit path still reports it, so a lost write is loud exactly once and
- * never silent.
+ * Bounded on purpose, and deliberately not routed through
+ * \`__nimbusDrainVfsWrites\`, whose \`while (pending > 0)\` waits for the mutation
+ * queue to be EMPTY. That wait is correct at process exit, where no new writes
+ * are coming. Anywhere else it is a livelock: a facet unpacking a tarball adds
+ * mutations faster than the loop retires them, so the loop never returns.
+ * Sited ahead of egress — where it was — that stopped the request from ever
+ * leaving the facet, and \`npx sv create\` ran, printed its intro, and then
+ * never reported an exit at all. A barrier may delay a request; it may not
+ * wait on a condition a busy process never reaches.
+ *
+ * Failures are retained rather than thrown. The two callers — the debounce
+ * below, and the RELEASE barrier ahead of egress — have no frame that could
+ * act on one: rejecting the fetch that happened to trigger the flush would
+ * blame the wrong operation. The exit drain reports what is retained, so a
+ * lost write is loud exactly once and never silent.
  */
 async function __nimbusFlushVfsWriteBack(supervisor) {
   if (!supervisor) return;
-  try {
-    await __nimbusDrainVfsWrites(supervisor);
-  } catch (error) {
-    if (!__nimbusHasPendingVfsMutationFailure) {
-      __nimbusHasPendingVfsMutationFailure = true;
-      __nimbusPendingVfsMutationFailure = error;
-    }
-  }
+  const paths = Object.keys(__vfsWrites);
+  if (paths.length === 0) return;
+  await Promise.allSettled(paths.map((path) => __nimbusFlushVfsWrite(
+    path,
+    (content, snapshot) => __nimbusPersistVfsWrite(supervisor, path, content, snapshot),
+  )));
 }
 
 /**

package/dist/runtime/comment-strip.d.ts

@@ -1,37 +1,40 @@
 /**
- * Minimal byte-aligned comment stripper for prefetch's import detection.
+ * One JavaScript source scanner shared by the two comment-stripping
+ * call sites — prefetch's import detection and the esbuild transform
+ * pipeline's classifiers.
  *
- * Scope: strip `//` line comments and `/* … *\/` block comments by
- * replacing each comment with a single space. Newlines INSIDE the
- * comment are preserved so that line numbers stay aligned with the
- * input (matches the strip-and-classify pattern used by
- * `esbuild-service.ts:stripCommentsAndStrings` for the transform
- * pipeline).
+ * `scanJsSource(src, literals)` walks `src` once and returns a
+ * byte-aligned copy in which `//` and `/* … *\/` comments are blanked
+ * (each comment becomes a space; newlines inside a block comment are
+ * preserved so line numbers still match the input). String, template
+ * and regex literals are what `literals` decides:
  *
- * Why a separate, smaller scanner: prefetch's IMPORT_RE / REQUIRE_RE
- * in `require-resolver.ts:41,87` are detection-only — they extract
- * specifier strings, not shapes. The full string-and-template-literal
- * stripper in `esbuild-service.ts` is overkill for that, and crossing
- * the anti-touch boundary on `esbuild-service.ts` to extend a single
- * shared helper isn't worth it right now.
+ *   - `'blank'`: literal content is replaced too — templates keep their
+ *     `${…}` interpolation expression as code so a depth-tracked caller
+ *     sees `await` etc. inside it. This is the transform pipeline's
+ *     classification view: nothing quoted can read as an `import`.
+ *   - `'keep'`: literals are copied verbatim. This is prefetch's
+ *     import-detection view: IMPORT_RE/REQUIRE_RE must see the
+ *     specifier string, and a `//` or `/*` inside a literal must NOT
+ *     open a comment that swallows a following real import.
  *
- * Empirical justification (esbuild-ast-rewrite wave, P2 measurement):
- *   - Per-file AST-based extraction: ~5 ms warm avg
- *   - 100-file session bootstrap with AST: ~553 ms (over the 500 ms gate)
- *   - Regex with this stripper: ~0.1 ms per file
- *   - Correctness gap closed: chalk `import { // eslint-disable\n   a,\n   b\n} from './utilities.js'` now matches
+ * The output is assembled from input slices and joined once. It used to
+ * be built one character at a time (`stripped += c`), which V8 keeps as
+ * a rope of one node per append — ~30 bytes of heap per character, all
+ * live until the string is first read. On typescript's 6.15 MB
+ * `lib/_tsc.js` that rope measured 174 MB against a 128 MB isolate —
+ * the session Durable Object was killed inside `tsc`'s spawn before the
+ * facet existed. Spans hold the input, the output and a short array.
  *
- * String-literal handling is intentionally OUT of scope. A literal
- * `import x from 'y'` inside a JavaScript string would still produce
- * a false-positive prefetch attempt. The resolver no-ops on misses,
- * so it's a minor wasted-work cost — see IMPORT_RE header comment in
- * `require-resolver.ts:84-86`.
- *
- * TODO(CLN-X): when the `src/runtime/esbuild-service.ts` anti-touch
- * window opens, unify with the canonical
- * `stripCommentsAndStrings(src)` helper there. Both implement the
- * same logical pass over comments; only the string/regex-literal
- * handling differs.
+ * Serialized by name: `generateEsbuildTransformRuntimeSource` embeds
+ * this function's `.toString()` in the transform runtime, so every
+ * constant it reads is declared inside the body.
+ */
+export declare function scanJsSource(src: string, literals: 'keep' | 'blank'): string;
+/**
+ * Strip comments for import/require detection. Literals are kept: the
+ * specifier the regexes extract lives inside a string, and a comment
+ * marker inside a string must not swallow the code that follows it.
  */
 export declare function stripCommentsForImports(src: string): string;
 //# sourceMappingURL=comment-strip.d.ts.map

package/dist/runtime/comment-strip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"comment-strip.d.ts","sourceRoot":"","sources":["../../src/runtime/comment-strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAqC3D"}
+{"version":3,"file":"comment-strip.d.ts","sourceRoot":"","sources":["../../src/runtime/comment-strip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAqM5E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE3D"}