@nimbus-sh/core 0.4.0 → 0.6.0

package/dist/vfs/sqlite-vfs.js

@@ -41,21 +41,33 @@
  */
 import { VfsEventEmitter } from './events.js';
 import { normalizeVfsPath } from './path.js';
-import { CHUNK_SIZE, LRU_MAX_ENTRIES, MAX_TX_BLOB_BYTES, MAX_TX_LOGICAL_ROWS, MAX_TX_SQL_EXECS, MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES, FS_LIST_PAGE_LIMIT, } from '../constants.js';
-import { recordFailure } from '../observability/oom-discriminator.js';
-import { classifyError } from '../observability/oom-classify.js';
-import { acquireSupervisorAllocation } from '../observability/heavy-alloc-coord.js';
+import { LRU_MAX_ENTRIES, FS_LIST_PAGE_LIMIT, } from '../constants.js';
+import { CHUNK_SIZE, MAX_TX_BLOB_BYTES, MAX_TX_LOGICAL_ROWS, MAX_TX_SQL_EXECS, MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES, } from '@nimbus-sh/platform/limits.js';
+import { recordFailure } from '@nimbus-sh/platform/oom-discriminator.js';
+import { classifyError } from '@nimbus-sh/platform/oom-classify.js';
+import { acquireSupervisorAllocation } from '@nimbus-sh/platform/heavy-alloc-coord.js';
 import { enc, dec } from '../_shared/bytes.js';
-import { decodeWriteBatchStream, } from '../_shared/w7-frame.js';
-import { WeightedCreditPool, } from '../_shared/weighted-credit-pool.js';
+import { decodeWriteBatchStream, } from '@nimbus-sh/platform/w7-frame.js';
+import { WeightedCreditPool, } from '@nimbus-sh/platform/weighted-credit-pool.js';
 import { LEGACY_SYMLINK_REGISTRY_PATH } from './symlink-registry.js';
 import { CRED_KERNEL, } from '../runtime/os-contracts.js';
 const CONTENT_ID_ALLOCATION_ATTEMPTS = 8;
+/**
+ * Live view of the global object. `process` is not in the Workers lib, so its
+ * shape is declared here rather than assumed present.
+ */
+const nodeHost = globalThis;
+/** Single gate for the W2.5b install-pipeline diagnostics below. */
+function installPipelineDiagEnabled() {
+    return nodeHost.process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1';
+}
 const INODE_ROWS_PER_SQL_EXEC = 9;
 const CHUNK_ROWS_PER_SQL_EXEC = 33;
 const CONTENT_IDS_PER_SQL_EXEC = 50;
 const TRANSACTION_DURATION_SAMPLE_COUNT = 128;
 const CONTENT_SCHEMA_MIGRATION = 'content_generations_v1';
+/** Storage key of the shared scratch tree. `normalizeVfsPath` drops the slash. */
+const TMP_ROOT = 'tmp';
 export const VFS_APPEND_RECEIPT_LIMIT = 2048;
 const INODE_KIND_FILE = 0;
 const INODE_KIND_DIRECTORY = 1;
@@ -357,6 +369,9 @@ export class SqliteVFS {
     activeStagingContentIds = new Set();
     /** True only while durable GC work or a known abandoned staging row exists. */
     maintenancePending = false;
+    // Keyset cursor for the orphan scan: each maintenance call reads one bounded
+    // page of distinct content ids past this bound, wrapping to '' at the end.
+    orphanScanCursor = '';
     // Stage 2 transaction/phase telemetry. Scalar writes stay cheap; the
     // percentile is computed from the fixed ring only when diagnostics read it.
     _activeTransaction = null;
@@ -939,6 +954,85 @@ export class SqliteVFS {
             return null;
         return this.blobToUint8Array(rows[0].data);
     }
+    /**
+     * Principals whose `/tmp` is private, keyed by uid, valued by the storage
+     * root their `/tmp` resolves to.
+     *
+     * `/tmp` keeps its path in every view and only the bytes behind it differ,
+     * so nothing has to be told which principal it is. The credential is the
+     * only per-process state visible where paths are RESOLVED — there is no pid
+     * and no cwd down here — so it is what the private view is keyed on.
+     *
+     * Resolution rather than a mount, because a mount diverges the two planes:
+     * the shell writing `/tmp/a` and the file API writing `/tmp/b` landed in
+     * different trees under the same name. `resolvePath` already takes `cred`,
+     * and every plane goes through it.
+     *
+     * Registration is also what makes a principal CONFINED for `chmod`. The two
+     * properties travel together because they answer one question: is this
+     * principal a guest in this filesystem. Nothing here applies to an
+     * unregistered credential, so the ordinary session user is untouched.
+     */
+    confinedTmpRoots = new Map();
+    /**
+     * Confine a principal. `tmpRoot` is a storage key, not a logical path — the
+     * caller owns creating and chowning it, because a per-principal `chown` is
+     * uid-0 only and a guest cannot provision its own.
+     */
+    confinePrincipal(uid, tmpRoot) {
+        const root = normalizeVfsPath(tmpRoot);
+        if (root === '')
+            throw vfsError('EINVAL', 'a private /tmp root cannot be the filesystem root');
+        this.confinedTmpRoots.set(uid, root);
+    }
+    /** Drop a confinement. A principal's `/tmp` dies with it; its home does not. */
+    releasePrincipal(uid) {
+        this.confinedTmpRoots.delete(uid);
+    }
+    /**
+     * Logical path -> storage key, for one credential.
+     *
+     * Everything under `/tmp` belongs to the caller's own private root, which is
+     * what makes the same path mean different bytes per principal. Idempotent: a
+     * key already inside that root is returned untouched, so the several methods
+     * that derive a key before handing it on cannot stack the rewrite.
+     */
+    storageKey(path, cred) {
+        const key = normalizeVfsPath(path);
+        const root = this.confinedTmpRoots.get(cred.uid);
+        if (root === undefined)
+            return key;
+        if (key === root || key.startsWith(`${root}/`))
+            return key;
+        if (key === TMP_ROOT)
+            return root;
+        if (!key.startsWith(`${TMP_ROOT}/`))
+            return key;
+        return `${root}/${key.slice(TMP_ROOT.length + 1)}`;
+    }
+    /**
+     * Storage key -> the name this credential knows it by, or `null` when it has
+     * none. The inverse of {@link storageKey}, for the one surface that reports
+     * paths it was not asked about: {@link list}.
+     *
+     * A confined caller has no name for the shared scratch tree — `/tmp` is its
+     * own root — nor for another principal's, so both answer `null` and are
+     * omitted. An unconfined caller sees storage as it is, which is what the
+     * kernel and the session user need.
+     */
+    logicalPath(key, cred) {
+        const root = this.confinedTmpRoots.get(cred.uid);
+        if (root === undefined)
+            return key;
+        if (key === root)
+            return TMP_ROOT;
+        if (key.startsWith(`${root}/`))
+            return `${TMP_ROOT}/${key.slice(root.length + 1)}`;
+        // The SHARED scratch root has no name here — this caller's `/tmp` is its
+        // own root, which already supplied that entry. Returning it too would
+        // enumerate one name twice, for two different directories.
+        return key === TMP_ROOT || key.startsWith(`${TMP_ROOT}/`) ? null : key;
+    }
     // ── Filesystem operations ─────────────────────────────────────────────
     as(cred) {
         const bound = Object.freeze({
@@ -983,7 +1077,7 @@ export class SqliteVFS {
             writeBatch: (payload) => this.writeBatch(payload, bound),
             writeStream: (stream, options) => this.writeStream(stream, options, bound),
             mkdirBatch: (paths) => this.mkdirBatch(paths, bound),
-            revision: (path) => this.revision(path),
+            revision: (path) => this.revision(path, bound),
             epoch: this._epoch,
         };
     }
@@ -1007,7 +1101,7 @@ export class SqliteVFS {
         return (granted & requested) === requested;
     }
     resolvePath(path, cred, followLeaf, allowMissing) {
-        let current = normalizeVfsPath(path);
+        let current = this.storageKey(path, cred);
         const seen = new Set();
         for (let hops = 0; hops <= 40; hops++) {
             const parts = current.split('/').filter(Boolean);
@@ -1028,8 +1122,13 @@ export class SqliteVFS {
                     seen.add(prefix);
                     const target = dec.decode(this.readInodeBytes(prefix, inode));
                     const suffix = parts.slice(index + 1).join('/');
+                    // An ABSOLUTE target is a logical path the same way the caller's
+                    // was, so it goes through the same rewrite: otherwise a symlink to
+                    // /tmp/y stored inside a private tree would read the shared one,
+                    // which is the one way out of the confinement. A RELATIVE target
+                    // resolves against a key that is already private, so it stays there.
                     const resolvedTarget = target.startsWith('/')
-                        ? normalizeVfsPath(target)
+                        ? this.storageKey(target, cred)
                         : normalizeVfsPath(`${this.parentPath(prefix)}/${target}`);
                     current = suffix ? normalizeVfsPath(`${resolvedTarget}/${suffix}`) : resolvedTarget;
                     restarted = true;
@@ -1068,6 +1167,29 @@ export class SqliteVFS {
         if (resolved.inode?.kind !== 'directory')
             throw vfsError('ENOTDIR', parent);
     }
+    /**
+     * POSIX sticky-bit restriction on a shared directory.
+     *
+     * Write permission on a directory is normally enough to remove or rename
+     * anything inside it, which is why `/tmp` is `1777` and not `0777`: the
+     * sticky bit narrows that to the entry's owner, the directory's owner, and
+     * root. Nothing enforced it here, so a world-writable shared directory gave
+     * every principal the ability to delete every other principal's files —
+     * the mode said one thing and the filesystem did another.
+     */
+    checkStickyParentMutation(path, inode, cred) {
+        if (cred.uid === 0)
+            return;
+        const parent = this.parentPath(normalizeVfsPath(path));
+        if (parent === '')
+            return;
+        const parentInode = this.inodes.get(parent);
+        if (!parentInode || (parentInode.mode & 0o1000) === 0)
+            return;
+        if (cred.uid !== parentInode.uid && cred.uid !== inode.uid) {
+            throw vfsError('EPERM', normalizeVfsPath(path));
+        }
+    }
     /**
      * Shared resolver for the boolean probes (exists/isDirectory/isFile/
      * isSymlink). Resolution-structure failures — a missing or non-directory
@@ -1105,10 +1227,12 @@ export class SqliteVFS {
      * under it changed in this DO lifetime). `revision('')` equals the
      * global clock by construction (every mutation stamps all ancestors).
      */
-    revision(path) {
+    revision(path, cred) {
         if (path === undefined)
             return this._revision;
-        const p = normalizeVfsPath(path);
+        // A credentialed caller asks about its own view; a confined one asking
+        // after /tmp/x means its own file, so the counter must be that file's.
+        const p = cred === undefined ? normalizeVfsPath(path) : this.storageKey(path, cred);
         if (p === '')
             return this._revision;
         return this._pathRevisions.get(p) ?? 0;
@@ -1288,7 +1412,7 @@ export class SqliteVFS {
         }
     }
     mkdir(path, options, cred) {
-        const normalized = normalizeVfsPath(path);
+        const normalized = this.storageKey(path, cred);
         this.assertMutationsAllowed([normalized]);
         if (this.exists(normalized, cred))
             return;
@@ -1389,7 +1513,7 @@ export class SqliteVFS {
     }
     symlink(target, path, cred) {
         this.assertMutationsAllowed([path]);
-        const normalized = normalizeVfsPath(path);
+        const normalized = this.storageKey(path, cred);
         const prior = this.checkAccess(normalized, 0, cred, { followLeaf: false, allowMissingLeaf: true });
         if (prior.inode)
             throw vfsError('EEXIST', normalized);
@@ -2124,6 +2248,22 @@ export class SqliteVFS {
             throw vfsError('ENOENT', path);
         if (cred.uid !== 0 && cred.uid !== inode.uid)
             throw vfsError('EPERM', resolved.path);
+        // A confined principal owns its own triad and nothing else. Refusing chmod
+        // outright would be simpler and wrong: execution is gated on the x bit, so
+        // a guest that writes build.sh and cannot chmod it cannot run it. What
+        // must not happen is WIDENING past its own principal, so the group, other
+        // and setuid/setgid/sticky bits keep the value they were provisioned with
+        // while the owner triad moves freely. `u+x` works; `+x` and `777` do not.
+        //
+        // Refused, never clamped. Quietly narrowing a mutation to the part that
+        // was allowed reports success for something other than what was asked, so
+        // the refusal names the spelling that works instead.
+        if (cred.uid !== 0 && this.confinedTmpRoots.has(cred.uid)) {
+            const beyondOwner = (mode & 0o7777) & ~0o700;
+            if (beyondOwner !== ((inode.mode & 0o7777) & ~0o700)) {
+                throw vfsError('EPERM', `${resolved.path}: mode change would grant permission outside your own principal; use u+x`);
+            }
+        }
         this.assertMutationsAllowed([inode.path]);
         const full = inodeTypeBits(inode.kind) | (mode & 0o7777);
         inode.mode = full;
@@ -2183,7 +2323,7 @@ export class SqliteVFS {
         // Before the walk, deliberately — see VfsListPage.
         const epoch = this._epoch;
         const rev = this._revision;
-        const from = after === null || after === undefined ? '' : normalizeVfsPath(after);
+        const from = after === null || after === undefined ? '' : this.storageKey(after, cred);
         // this.inodes is insertion-ordered, not path-ordered, so the sort is what
         // makes `after` a resume key at all. Paid once per page against a map the
         // DO already holds whole.
@@ -2210,8 +2350,16 @@ export class SqliteVFS {
             catch {
                 continue;
             }
+            // Reported in the caller's OWN path space. Enumerating raw storage keys
+            // would name a private root the caller cannot address and does not know
+            // it has, and a caller feeding such a path back would be asking about
+            // someone else's tree. `null` means the path has no name for this
+            // caller, which is the same OMIT the access check above performs.
+            const logical = this.logicalPath(path, cred);
+            if (logical === null)
+                continue;
             entries.push({
-                path,
+                path: logical,
                 kind: inode.kind,
                 size: inode.size,
                 rev: this._pathRevisions.get(path) ?? 0,
@@ -2220,7 +2368,7 @@ export class SqliteVFS {
         return { epoch, rev, entries, next };
     }
     readdir(path, cred) {
-        const np = path.replace(/^\/+/, '').replace(/\/+$/, '');
+        const np = this.storageKey(path, cred);
         const resolved = np ? this.checkAccess(np, 0o4, cred) : { path: '', inode: undefined };
         const inode = resolved.inode;
         if (inode && inode.kind !== 'directory')
@@ -2229,7 +2377,7 @@ export class SqliteVFS {
         if (!kids) {
             // W2.5b diagnostic: empty children-set for a directory we expected
             // to be populated.
-            if (globalThis.process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1') {
+            if (installPipelineDiagEnabled()) {
                 // eslint-disable-next-line no-console
                 console.warn('[sqlite-vfs/W2.5b] readdir miss path=' + np +
                     ' kidsUndefined=true inodeExists=' + this.inodes.has(np));
@@ -2248,7 +2396,7 @@ export class SqliteVFS {
         // fewer (some entries' inodes are missing from this.inodes), log it.
         // This distinguishes (a) "children index broken" from (b) "inodes
         // map lost entries".
-        if (globalThis.process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1' &&
+        if (installPipelineDiagEnabled() &&
             kids.size !== results.length) {
             // eslint-disable-next-line no-console
             console.warn('[sqlite-vfs/W2.5b] readdir size mismatch path=' + np +
@@ -2273,23 +2421,25 @@ export class SqliteVFS {
         if (!inode)
             throw vfsError('ENOENT', path);
         this.checkParentAccess(resolved.path, cred);
+        this.checkStickyParentMutation(resolved.path, inode, cred);
         if (inode.isDir)
             throw vfsError('EISDIR', resolved.path);
         this.writeBatch({ inodes: [], chunks: [], deletePaths: [resolved.path] }, cred);
     }
     rmdir(path, cred) {
         this.assertMutationsAllowed([path]);
-        const np = path.replace(/^\/+/, '').replace(/\/+$/, '');
+        const np = this.storageKey(path, cred);
         const resolved = this.checkAccess(np, 0, cred, { followLeaf: false });
         this.checkParentAccess(resolved.path, cred);
+        const inode = this.inodes.get(np);
+        if (!inode)
+            throw vfsError('ENOENT', path);
+        this.checkStickyParentMutation(resolved.path, inode, cred);
         // Check if empty using children index (O(1) instead of O(N))
         const kids = this.children.get(np);
         if (kids && kids.size > 0) {
             throw vfsError('ENOTEMPTY', path);
         }
-        const inode = this.inodes.get(np);
-        if (!inode)
-            throw vfsError('ENOENT', path);
         if (!inode.isDir)
             throw vfsError('ENOTDIR', path);
         this.writeBatch({ inodes: [], chunks: [], deletePaths: [np] }, cred);
@@ -2316,6 +2466,7 @@ export class SqliteVFS {
         if (!resolved.inode)
             throw vfsError('ENOENT', normalizeVfsPath(path));
         this.checkParentAccess(resolved.path, cred);
+        this.checkStickyParentMutation(resolved.path, resolved.inode, cred);
         const removable = this.collectSubtreeInodes([resolved.path]);
         // The directories the recursive walk used to enumerate are exactly the
         // directory inodes of the subtree, and enumerating one needed read
@@ -2367,6 +2518,7 @@ export class SqliteVFS {
         const inode = this.inodes.get(oldPath);
         if (!inode)
             throw new Error("ENOENT: " + oldPath);
+        this.checkStickyParentMutation(oldPath, inode, cred);
         // W-3 (WASI filesystem WASI): if newPath already exists, unlink it first so the
         // SQL UPDATE doesn't conflict on inodes.path uniqueness. POSIX rename(2)
         // overwrites the destination atomically; clang's atomic-write pattern
@@ -2376,6 +2528,7 @@ export class SqliteVFS {
         // (the latter is rare but POSIX permits it for empty dirs).
         const destInode = this.inodes.get(newPath);
         if (destInode) {
+            this.checkStickyParentMutation(newPath, destInode, cred);
             if (destInode.isDir) {
                 // POSIX semantics: rename onto a non-empty dir is an error
                 // (ENOTEMPTY); rename onto an empty dir is allowed. We surface
@@ -2590,14 +2743,14 @@ export class SqliteVFS {
     }
     // ── Batch write (npm install fast path) ───────────────────────────────
     normalizeBatchInode(entry, cred) {
-        const path = normalizeVfsPath(entry.path);
+        const path = this.storageKey(entry.path, cred);
         const prior = this.inodes.get(path);
         const newUid = cred.uid === 0 ? (entry.uid ?? 1000) : cred.uid;
         const newGid = cred.uid === 0 ? (entry.gid ?? 1000) : cred.gid;
         return {
             ...entry,
             path,
-            parentPath: normalizeVfsPath(entry.parentPath),
+            parentPath: this.storageKey(entry.parentPath, cred),
             mode: prior
                 ? prior.mode
                 : inodeKind(entry) === 'symlink'
@@ -2632,7 +2785,7 @@ export class SqliteVFS {
             }
         };
         for (const path of payload.deletePaths ?? []) {
-            const normalized = normalizeVfsPath(path);
+            const normalized = this.storageKey(path, cred);
             const existing = this.checkAccess(normalized, 0, cred, {
                 followLeaf: false,
                 allowMissingLeaf: true,
@@ -2648,14 +2801,14 @@ export class SqliteVFS {
                 checkParent(entry.path);
         }
         for (const chunk of payload.chunks) {
-            const path = normalizeVfsPath(chunk.path);
+            const path = this.storageKey(chunk.path, cred);
             if (!pending.has(path))
                 this.checkAccess(path, 0o2, cred, { followLeaf: false });
         }
         return {
             ...payload,
             inodes,
-            deletePaths: payload.deletePaths?.map(normalizeVfsPath),
+            deletePaths: payload.deletePaths?.map((path) => this.storageKey(path, cred)),
         };
     }
     /**
@@ -3307,18 +3460,30 @@ export class SqliteVFS {
         let orphanScanComplete = true;
         let stagingScanComplete = true;
         if (transactions < maximum) {
-            const orphanRows = [...this.sql.exec(`SELECT chunks.content_id
-         FROM file_chunks AS chunks
-         WHERE NOT EXISTS (
-             SELECT 1 FROM content_lifecycle AS lifecycle
-             WHERE lifecycle.content_id = chunks.content_id
-           )
-           AND ${sqlNoInodeContentReference('chunks.content_id')}
-         GROUP BY chunks.content_id
-         ORDER BY chunks.content_id
-         LIMIT ?`, CONTENT_IDS_PER_SQL_EXEC)];
-            orphanScanComplete = orphanRows.length < CONTENT_IDS_PER_SQL_EXEC;
-            const contentIds = orphanRows.map((row) => String(row.content_id));
+            // The page is selected before the orphan predicates so a scan that finds
+            // nothing still reads only one page, not the whole covering index.
+            const pageRows = [...this.sql.exec(`SELECT page.content_id AS content_id,
+                (NOT EXISTS (
+                   SELECT 1 FROM content_lifecycle AS lifecycle
+                   WHERE lifecycle.content_id = page.content_id
+                 )
+                 AND ${sqlNoInodeContentReference('page.content_id')}) AS orphaned
+         FROM (
+           SELECT chunks.content_id
+           FROM file_chunks AS chunks
+           WHERE chunks.content_id > ?
+           GROUP BY chunks.content_id
+           ORDER BY chunks.content_id
+           LIMIT ?
+         ) AS page
+         ORDER BY page.content_id`, this.orphanScanCursor, CONTENT_IDS_PER_SQL_EXEC)];
+            orphanScanComplete = pageRows.length < CONTENT_IDS_PER_SQL_EXEC;
+            this.orphanScanCursor = orphanScanComplete
+                ? ''
+                : String(pageRows[pageRows.length - 1].content_id);
+            const contentIds = pageRows
+                .filter((row) => Number(row.orphaned) === 1)
+                .map((row) => String(row.content_id));
             if (contentIds.length > 0) {
                 const candidates = contentIds
                     .map((_, index) => index === 0 ? 'SELECT ? AS content_id' : 'SELECT ?')
@@ -3480,7 +3645,7 @@ export class SqliteVFS {
     /** Best-effort process.memoryUsage().heapUsed; 0 in DO contexts. */
     _safeHeapUsed() {
         try {
-            const mu = globalThis.process?.memoryUsage?.();
+            const mu = nodeHost.process?.memoryUsage?.();
             return Number(mu?.heapUsed) || 0;
         }
         catch {
@@ -3658,7 +3823,7 @@ export class SqliteVFS {
         // `_addToChildrenIndex` uses Set.add so repeated calls are idempotent;
         // gating it on `prior === undefined` was the bug. Counters remain
         // gated correctly so they don't double-count.
-        const __diag = (globalThis.process?.env?.NIMBUS_DIAG_INSTALL_PIPELINE === '1');
+        const __diag = installPipelineDiagEnabled();
         const replacedPaths = new Set();
         for (const entry of plan.inodes) {
             const prior = this.inodes.get(entry.path);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nimbus-sh/core",
-  "version": "0.4.0",
-  "description": "Backend-agnostic half of Nimbus \u2014 the durable filesystem, the shell, and the OS/process contracts, over a host-supplied SQL port.",
+  "version": "0.6.0",
+  "description": "Backend-agnostic half of Nimbus — the durable filesystem, the shell, and the OS/process contracts, over a host-supplied SQL port.",
   "keywords": [
     "filesystem",
     "shell",
@@ -55,6 +55,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@nimbus-sh/platform": "^0.1.0",
     "@renovatebot/pep440": "^5.0.0",
     "acorn": "^8.15.0",
     "acorn-walk": "^8.3.5",

package/src/_shared/cache-stats.ts

@@ -11,7 +11,7 @@
  *   L4 — registry.npmjs.org origin                   ~100-300 ms cross-region
  *
  * Pre-cache metrics support: hit/miss counters lived in
- * src/observability/diag-counters.ts but only tracked the RPC-call
+ * @nimbus-sh/platform/diag-counters.js but only tracked the RPC-call
  * boundary, not per-tier. Those flat counters have since been removed.
  *
  * This module adds per-tier × per-kind counters. SAME singleton-per-
@@ -229,3 +229,29 @@ export function reset(): void {
   }
   _lastResetAt = Date.now();
 }
+
+/**
+ * cache-obs-2: fold facet-collected per-tier cache events into the
+ * DO-side cache-stats singleton. Called from installer.ts after a
+ * batch-facet / resolve-facet returns — mirrors recordR2RaceCounters
+ * (the facet collects metrics in its result and the supervisor folds
+ * them into the DO isolate).
+ *
+ * Each event has shape:
+ *   { kind: 'hit', tier: 'L2'|'L3'|'L4', cacheKind: 'tarball'|'packument'|'asset', bytes: number }
+ *   { kind: 'miss', tier: ..., cacheKind: ... }
+ */
+export type CacheStatEvent =
+  | { kind: 'hit'; tier: CacheTier; cacheKind: CacheKind; bytes: number }
+  | { kind: 'miss'; tier: CacheTier; cacheKind: CacheKind };
+
+export function recordCacheStatEvents(events: readonly CacheStatEvent[] | undefined): void {
+  if (!events || events.length === 0) return;
+  for (const e of events) {
+    if (e.kind === 'hit') {
+      recordHit(e.tier, e.cacheKind, e.bytes);
+    } else {
+      recordMiss(e.tier, e.cacheKind);
+    }
+  }
+}

package/src/_shared/error-text.ts

@@ -0,0 +1,21 @@
+/**
+ * error-text.ts — the text a caught value carries.
+ *
+ * A `catch` binding is `unknown`: the throw site may have thrown an Error, a
+ * string, or a plain object with a `message`, and the shell and runtime paths
+ * report all three the same way. This is that report, in one place, so a
+ * command's diagnostics do not depend on which of those a facet threw.
+ */
+
+/**
+ * The message a thrown value names, or the value itself when it names none.
+ * Empty and other falsy messages fall through to the value, so an
+ * `new Error('')` still reports as `Error` rather than as nothing.
+ */
+export function errorText(error: unknown): string {
+  if (typeof error === 'object' && error !== null && 'message' in error) {
+    const { message } = error;
+    if (message) return String(message);
+  }
+  return String(error);
+}

package/src/_shared/exports-resolver.ts

@@ -7,7 +7,7 @@
  *   1. Install-time supervisor (TS) — `src/npm-resolver.ts` re-exports the
  *      typed functions for tree resolution.
  *
- *   2. NimbusLoaderPool isolates (JS string) — `src/loaders/pre-bundle-preamble.ts`
+ *   2. IsolatePool isolates (JS string) — `src/loaders/pre-bundle-preamble.ts`
  *      embeds `getExportsResolverJS()` as part of the pool preamble so the
  *      pre-bundle facet uses identical resolution semantics to the supervisor.
  *
@@ -37,6 +37,26 @@ export const DEFAULT_ESM_CONDITIONS = ['import', 'module', 'browser', 'default']
 /** Default conditions for CJS runtime resolution (user-shell node). */
 export const DEFAULT_CJS_CONDITIONS = ['require', 'node', 'default'];
 
+/**
+ * A `package.json#exports` / `#imports` value: a target path, an ordered list
+ * of fallbacks to try in turn, or a map keyed by subpath (`"./client"`) or by
+ * condition (`"import"`) whose values are the same shape again. `null` is the
+ * spec's "this subpath is not exported" marker, and blocks fallback.
+ */
+export type ExportsField =
+  | string
+  | null
+  | ExportsField[]
+  | { [key: string]: ExportsField };
+
+/** The package.json fields entry-point resolution reads. */
+export interface ResolvablePackageJson {
+  exports?: ExportsField;
+  imports?: ExportsField;
+  main?: string;
+  module?: string;
+}
+
 /**
  * Resolve `package.json#exports` (or `#imports`) per Node spec.
  *
@@ -46,7 +66,7 @@ export const DEFAULT_CJS_CONDITIONS = ['require', 'node', 'default'];
  * @returns             Relative path target string, or null if not found / forbidden
  */
 export function resolveExports(
-  exportsField: any,
+  exportsField: ExportsField | undefined,
   subpath: string = '.',
   conditions: string[] = DEFAULT_ESM_CONDITIONS,
 ): string | null {
@@ -123,7 +143,7 @@ export function resolveExports(
  * array (Node spec).
  */
 function resolveConditionValue(
-  target: any,
+  target: ExportsField | undefined,
   conditions: string[],
 ): string | null {
   if (target === null || target === undefined) return null;
@@ -162,7 +182,7 @@ function resolveConditionValue(
  * itself (caller probes filesystem with extension-list).
  */
 export function resolvePackageEntry(
-  pkg: { exports?: any; module?: string; main?: string },
+  pkg: ResolvablePackageJson,
   subpath: string = '.',
   conditions: string[] = DEFAULT_ESM_CONDITIONS,
 ): string | null {

package/src/_shared/retry.ts

@@ -23,7 +23,8 @@
  * equivalent retry loops inside their isolated function bodies.
  */
 
-import { disposeRpcResource } from './rpc-dispose.js';
+import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { errorText } from './error-text.js';
 
 /** Default retry count AFTER the first attempt (3 = up to 4 total attempts). */
 export const DEFAULT_RETRIES = 3;
@@ -179,7 +180,7 @@ export async function retryableFetch(
       const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
       opts?.onRetry?.(attempt + 1, totalRetries, delayMs, `HTTP ${resp.status}`);
       await new Promise<void>((r) => setTimeout(r, delayMs));
-    } catch (e: any) {
+    } catch (e) {
       if (timer) clearTimeout(timer);
       // Network-level failure (fetch rejection, timeout via AbortError,
       // DNS, connection reset). Retry the same way as a 5xx.
@@ -189,7 +190,8 @@ export async function retryableFetch(
         throw e;
       }
       const delayMs = jittered(BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)]);
-      const reason = e?.name === 'AbortError' ? 'timeout' : (e?.message || String(e));
+      const isAbort = typeof e === 'object' && e !== null && 'name' in e && e.name === 'AbortError';
+      const reason = isAbort ? 'timeout' : errorText(e);
       opts?.onRetry?.(attempt + 1, totalRetries, delayMs, reason);
       await new Promise<void>((r) => setTimeout(r, delayMs));
     }