@nimbus-sh/core 0.5.0 → 0.7.0

package/dist/vfs/sqlite-vfs.js

@@ -41,13 +41,14 @@
  */
 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;
@@ -305,10 +306,9 @@ export class SqliteVFS {
     _lruShrinkRefcount = 0;
     // ── Running counters for O(1) getStats() (B3 / AUDIT M10 / M-S8) ──
     // Replaces the triple scan of this.inodes on every /api/stats poll.
-    // Bootstrapped in loadInodes(); maintained at every mutator entry:
-    //   mkdir/rmdir/writeFile/unlink/writeBatch (rename is a no-op —
-    //   same inode, new path). Invariant: these match a fresh O(N)
-    //   walk of this.inodes. Unit-tested in the A5/B3 runtime tests.
+    // Bootstrapped in loadInodes(); maintained at committed publication by
+    // mkdir, batch writes/deletes and rename. These match a fresh O(N)
+    // walk of this.inodes; rollback reloads them from the durable rows.
     _totalFiles = 0;
     _totalDirs = 0;
     _usedBytes = 0;
@@ -322,6 +322,7 @@ export class SqliteVFS {
     // so unrelated writes no longer invalidate them. In-memory only — the
     // clock resets with the DO lifetime, exactly like the caches keyed on it.
     _pathRevisions = new Map();
+    transactionPublication = null;
     // ── Invalidation log (facet cache coherence) ──────────────────────────
     // A facet's resident set is a cache of this VFS, and it learns what to
     // drop by asking `invalidatedSince(cursor)` for the delta. _pathRevisions
@@ -1254,6 +1255,11 @@ export class SqliteVFS {
      * additional coverage, since no facet view keys on a grandparent.
      */
     bumpRevision(paths) {
+        if (this.transactionPublication) {
+            for (const path of paths)
+                this.transactionPublication.paths.add(path);
+            return;
+        }
         const rev = ++this._revision;
         for (const path of paths) {
             let p = normalizeVfsPath(path);
@@ -1454,7 +1460,7 @@ export class SqliteVFS {
         this._addToChildrenIndex(pp, path);
         this._totalDirs++; // B3
         this.bumpRevision([path]);
-        this.events.emit('addDir', path);
+        this.emitMutation('addDir', path);
     }
     writeFile(path, content, options, cred, onCommit) {
         this.assertMutationsAllowed([path]);
@@ -2223,11 +2229,11 @@ export class SqliteVFS {
         }
         const atime = atimeMs !== null && Number.isFinite(atimeMs) ? Math.trunc(atimeMs) : this.now();
         const mtime = mtimeMs !== null && Number.isFinite(mtimeMs) ? Math.trunc(mtimeMs) : this.now();
+        this.sql.exec("UPDATE inodes SET atime = ?, mtime = ? WHERE path = ?", atime, mtime, inode.path);
         inode.atime = atime;
         inode.mtime = mtime;
-        this.sql.exec("UPDATE inodes SET atime = ?, mtime = ? WHERE path = ?", atime, mtime, inode.path);
         this.bumpRevision([inode.path]);
-        this.events.emit('change', inode.path);
+        this.emitMutation('change', inode.path);
     }
     /**
      * Set the permission bits durably. Follows symlinks (POSIX chmod).
@@ -2265,10 +2271,10 @@ export class SqliteVFS {
         }
         this.assertMutationsAllowed([inode.path]);
         const full = inodeTypeBits(inode.kind) | (mode & 0o7777);
-        inode.mode = full;
         this.sql.exec("UPDATE inodes SET mode = ? WHERE path = ?", full, inode.path);
+        inode.mode = full;
         this.bumpRevision([inode.path]);
-        this.events.emit('change', inode.path);
+        this.emitMutation('change', inode.path);
     }
     chown(path, uid, gid, cred, followLeaf) {
         const resolved = this.checkAccess(path, 0, cred, { followLeaf });
@@ -2290,13 +2296,15 @@ export class SqliteVFS {
         if (gid !== null && gid === inode.gid && cred.uid !== 0 && !owner)
             throw vfsError('EPERM', resolved.path);
         this.assertMutationsAllowed([inode.path]);
-        inode.uid = uid ?? inode.uid;
-        inode.gid = gid ?? inode.gid;
-        if (cred.uid !== 0)
-            inode.mode &= ~0o6000;
-        this.sql.exec('UPDATE inodes SET uid = ?, gid = ?, mode = ? WHERE path = ?', inode.uid, inode.gid, inode.mode, inode.path);
+        const nextUid = uid ?? inode.uid;
+        const nextGid = gid ?? inode.gid;
+        const nextMode = cred.uid === 0 ? inode.mode : inode.mode & ~0o6000;
+        this.sql.exec('UPDATE inodes SET uid = ?, gid = ?, mode = ? WHERE path = ?', nextUid, nextGid, nextMode, inode.path);
+        inode.uid = nextUid;
+        inode.gid = nextGid;
+        inode.mode = nextMode;
         this.bumpRevision([inode.path]);
-        this.events.emit('change', inode.path);
+        this.emitMutation('change', inode.path);
     }
     /**
      * Enumerate the filesystem, one bounded page at a time.
@@ -2506,7 +2514,14 @@ export class SqliteVFS {
     }
     rename(oldPath, newPath, cred) {
         this.assertMutationsAllowed([oldPath, newPath]);
-        this.checkAccess(oldPath, 0, cred, { followLeaf: false });
+        // Resolve private /tmp names to storage keys before reading or mutating.
+        const source = this.checkAccess(oldPath, 0, cred, { followLeaf: false });
+        const inode = source.inode;
+        if (!inode)
+            throw vfsError('ENOENT', oldPath);
+        const target = this.checkAccess(newPath, 0, cred, { followLeaf: false, allowMissingLeaf: true });
+        oldPath = source.path;
+        newPath = target.path;
         this.checkParentAccess(oldPath, cred);
         this.checkParentAccess(newPath, cred);
         if (oldPath === newPath)
@@ -2514,9 +2529,6 @@ export class SqliteVFS {
         if (newPath.startsWith(`${oldPath}/`)) {
             throw new Error(`EINVAL: cannot move ${oldPath} inside itself`);
         }
-        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)
@@ -2525,7 +2537,7 @@ export class SqliteVFS {
         // a 2nd `make` after a prior successful build throws on UPDATE
         // failure. Pre-unlink covers both file-over-file and file-over-dir
         // (the latter is rare but POSIX permits it for empty dirs).
-        const destInode = this.inodes.get(newPath);
+        const destInode = target.inode;
         if (destInode) {
             this.checkStickyParentMutation(newPath, destInode, cred);
             if (destInode.isDir) {
@@ -2697,7 +2709,7 @@ export class SqliteVFS {
             }
         }
         this.bumpRevision([...touchedPaths]);
-        this.events.emit('rename', newPath, oldPath);
+        this.emitMutation('rename', newPath, oldPath);
         this.runContentMaintenanceSafely(1);
     }
     /**
@@ -3346,6 +3358,76 @@ export class SqliteVFS {
         }
         return this.errorMessage(error).toUpperCase().includes('SQLITE_NOMEM');
     }
+    /**
+     * Participate in an embedder's synchronous transaction: VFS writes and SQL
+     * issued by callback commit together; on rollback the in-memory mirror
+     * returns to the committed state before the error is rethrown with cause.
+     *
+     * This method MUST own the outermost transaction on this VFS's SQL host;
+     * use it instead of wrapping VFS calls in storage.transactionSync. Do not
+     * nest it, return a Promise/thenable, or start asynchronous work inside it.
+     * The callback may read its writes. Revisions and events publish only on
+     * commit, once for the combined mutation. Existing credential checks apply.
+     *
+     * Inodes are an always-resident cache (absence means ENOENT), so rollback
+     * discards cached chunks and rebuilds metadata/children/counters from SQL.
+     * No inode snapshot or undo log is retained. Recovery failure is surfaced
+     * with both errors; the embedder must discard this VFS in that case.
+     */
+    withTransaction(callback) {
+        if (this.transactionPublication !== null) {
+            throw new Error('[sqlite-vfs] nested embedder transactions are not supported');
+        }
+        const storage = this.ctx.storage;
+        if (!storage)
+            throw new Error('[sqlite-vfs] atomic storage operation requires transactionSync');
+        const publication = {
+            paths: new Set(),
+            events: new Array(),
+        };
+        const maintenancePending = this.maintenancePending;
+        this.transactionPublication = publication;
+        let result;
+        try {
+            result = storage.transactionSync(() => {
+                const value = callback();
+                if (value !== null && (typeof value === 'object' || typeof value === 'function')
+                    && 'then' in value && typeof value.then === 'function') {
+                    throw new TypeError('[sqlite-vfs] transaction callback must be synchronous');
+                }
+                return value;
+            });
+        }
+        catch (error) {
+            this.evictAll();
+            this.maintenancePending = maintenancePending;
+            try {
+                this.loadInodes();
+            }
+            catch (reloadError) {
+                throw new AggregateError([error, reloadError], '[sqlite-vfs] transaction rollback reload failed', { cause: error });
+            }
+            throw new Error('[sqlite-vfs] embedder transaction rolled back', { cause: error });
+        }
+        finally {
+            this.transactionPublication = null;
+        }
+        if (publication.paths.size > 0)
+            this.bumpRevision([...publication.paths]);
+        for (const event of publication.events) {
+            this.events.emit(event.type, event.path, event.oldPath);
+        }
+        this.runContentMaintenanceSafely(1);
+        return result;
+    }
+    emitMutation(type, path, oldPath) {
+        if (this.transactionPublication) {
+            this.transactionPublication.events.push({ type, path, oldPath });
+        }
+        else {
+            this.events.emit(type, path, oldPath);
+        }
+    }
     transactionSync(callback) {
         if (!this.ctx?.storage?.transactionSync) {
             throw new Error('[sqlite-vfs] atomic storage operation requires transactionSync');
@@ -3601,6 +3683,8 @@ export class SqliteVFS {
         return { transactions };
     }
     runContentMaintenanceSafely(maxTransactions, force = false) {
+        if (this.transactionPublication)
+            return;
         if (!force && !this.maintenancePending)
             return;
         const startedAt = performance.now();
@@ -3906,10 +3990,10 @@ export class SqliteVFS {
         }
         // 5. Events observe the already-published metadata and revision.
         for (const inode of deletedInodes) {
-            this.events.emit(inode.isDir ? 'unlinkDir' : 'unlink', inode.path);
+            this.emitMutation(inode.isDir ? 'unlinkDir' : 'unlink', inode.path);
         }
         for (const entry of plan.inodes) {
-            this.events.emit(entry.isDir ? 'addDir' : replacedPaths.has(entry.path) ? 'change' : 'add', entry.path);
+            this.emitMutation(entry.isDir ? 'addDir' : replacedPaths.has(entry.path) ? 'change' : 'add', entry.path);
         }
         this.recordDuration(this._postCommitDuration, performance.now() - postCommitStartedAt);
         return { inodes: inodeCount, chunks: chunkCount };

package/dist/workspace/nimbus-workspace.d.ts

@@ -27,8 +27,11 @@ import type { CommandResult, RunOptions, SandboxFs } from '../substrate/lifo/san
 import type { ITerminal } from '../substrate/lifo/terminal/ITerminal.js';
 import { SqliteVFS } from '../vfs/sqlite-vfs.js';
 import type { SqlDatabase, TransactionHost } from '../runtime/os-contracts.js';
+import { SessionProcessSupervisor } from '../runtime/session-process-supervisor.js';
 import type { FacetHost } from '../runtime/facet-host.js';
 import { type RuntimePackage } from '../runtime/runtime-package.js';
+import { type CtxExports, type FabricComposition } from '@nimbus-sh/platform/composition.js';
+import { type SupervisorOpEnvelope, type SupervisorOpHandler } from './supervisor-op.js';
 export interface NimbusWorkspaceOptions {
     /** The host's SQLite. In a Durable Object: `ctx.storage.sql`. */
     readonly sql: SqlDatabase;
@@ -106,6 +109,15 @@ export interface NimbusWorkspaceOptions {
      * carry REPLs and a resident-process substrate this cannot reach.
      */
     readonly facets?: FacetHost;
+    /** Isolate-wide fabric composition, including the hosting namespace. */
+    readonly fabric?: FabricComposition;
+    /** Explicit exports override the bag on the transaction host. */
+    readonly ctxExports?: CtxExports;
+    /** The process table that allocated supervisor-binding pids. */
+    readonly processes?: SessionProcessSupervisor;
+    readonly processOutput?: (stream: 'stdout' | 'stderr', pid: number, data: string) => void;
+    /** Host operations, including overrides for host-specific accounting. */
+    readonly supervisorOps?: Readonly<Record<string, SupervisorOpHandler>>;
 }
 /**
  * A durable filesystem and a shell over it.
@@ -120,6 +132,7 @@ export interface NimbusWorkspaceOptions {
  */
 export declare class NimbusWorkspace {
     private readonly sql;
+    private readonly supervisorOps;
     /**
      * Credentialed and mount-aware. Acts as the session user, never as the
      * kernel: a pid-less caller must not gain more authority than the shell it
@@ -142,6 +155,8 @@ export declare class NimbusWorkspace {
     private constructor();
     static create(options: NimbusWorkspaceOptions): Promise<NimbusWorkspace>;
     exec(command: string, options?: RunOptions): Promise<CommandResult>;
+    /** The hosting object forwards its supervisorOp RPC to this method. */
+    supervisorOp(envelope: SupervisorOpEnvelope): Promise<unknown>;
     /**
      * Apply the login files, and begin reading the terminal when there is one.
      *

package/dist/workspace/nimbus-workspace.d.ts.map

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

package/dist/workspace/nimbus-workspace.js

@@ -34,6 +34,8 @@ import { rehydrateInstalledRuntimesView, } from '../runtime/installed-runtimes.j
 import { seedRuntimePackage } from '../runtime/runtime-package.js';
 import { registerUnixCommands } from '../shell/unix-commands.js';
 import { installPathExecResolver } from '../shell/exec-dispatch.js';
+import { adoptCtxExports, composeFabric } from '@nimbus-sh/platform/composition.js';
+import { createSupervisorOpHandler } from './supervisor-op.js';
 /**
  * A durable filesystem and a shell over it.
  *
@@ -47,6 +49,7 @@ import { installPathExecResolver } from '../shell/exec-dispatch.js';
  */
 export class NimbusWorkspace {
     sql;
+    supervisorOps;
     /**
      * Credentialed and mount-aware. Acts as the session user, never as the
      * kernel: a pid-less caller must not gain more authority than the shell it
@@ -66,8 +69,9 @@ export class NimbusWorkspace {
      */
     env;
     commands;
-    constructor(vfs, kernel, shell, registry, env, sql) {
+    constructor(vfs, kernel, shell, registry, env, sql, supervisorOps) {
         this.sql = sql;
+        this.supervisorOps = supervisorOps;
         this.vfs = vfs;
         this.kernel = kernel;
         this.shell = shell;
@@ -80,6 +84,12 @@ export class NimbusWorkspace {
         this.fs = new SandboxFsImpl(kernel.vfs.as(CRED_SESSION_USER), () => shell.getCwd());
     }
     static async create(options) {
+        if (options.fabric)
+            composeFabric(options.fabric);
+        const exports = options.ctxExports
+            ?? options.transactions?.exports;
+        if (exports)
+            adoptCtxExports(exports);
         const vfs = options.vfs ?? openFilesystem(options);
         const mounts = options.mounts ?? DEFAULT_MOUNT_POINTS;
         seedBaseFilesystem(vfs, mounts);
@@ -118,11 +128,18 @@ export class NimbusWorkspace {
                 home,
             });
         }
-        return new NimbusWorkspace(vfs, kernel, shell, registry, env, options.sql);
+        const supervisorOps = createSupervisorOpHandler({
+            vfs, processes: options.processes, output: options.processOutput, extend: options.supervisorOps,
+        });
+        return new NimbusWorkspace(vfs, kernel, shell, registry, env, options.sql, supervisorOps);
     }
     exec(command, options) {
         return this.commands.run(command, options);
     }
+    /** The hosting object forwards its supervisorOp RPC to this method. */
+    supervisorOp(envelope) {
+        return this.supervisorOps(envelope);
+    }
     /**
      * Apply the login files, and begin reading the terminal when there is one.
      *
@@ -243,7 +260,7 @@ async function registerWasmRuntimes(deps) {
         getEsbuild: () => {
             if (!esbuild) {
                 esbuild = import('../runtime/esbuild-service.js')
-                    .then((module) => new module.EsbuildService(deps.vfs));
+                    .then((module) => new module.EsbuildService(deps.vfs.as(CRED_KERNEL)));
             }
             return esbuild;
         },

package/dist/workspace/supervisor-op.d.ts

@@ -0,0 +1,23 @@
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+import type { SessionProcessSupervisor } from '../runtime/session-process-supervisor.js';
+/** Identity comes from the supervisor binding, never from facet arguments. */
+export interface SupervisorOpEnvelope {
+    readonly op: string;
+    readonly args?: readonly unknown[];
+    readonly pid?: number;
+    readonly writerId?: string;
+    readonly mutationOwner?: string;
+    readonly stream?: ReadableStream<Uint8Array>;
+}
+export type SupervisorOpHandler = (envelope: SupervisorOpEnvelope) => unknown;
+export interface SupervisorOpDeps {
+    readonly vfs: SqliteVFS;
+    /** Absent a process table, operations use the unprivileged session user. */
+    readonly processes?: SessionProcessSupervisor;
+    readonly output?: (stream: 'stdout' | 'stderr', pid: number, data: string) => void;
+    /** Host handlers override defaults, for example to account for stream drains. */
+    readonly extend?: Readonly<Record<string, SupervisorOpHandler>>;
+}
+/** One dispatch method lets any host serve its workspace to process facets. */
+export declare function createSupervisorOpHandler(deps: SupervisorOpDeps): (envelope: SupervisorOpEnvelope) => Promise<unknown>;
+//# sourceMappingURL=supervisor-op.d.ts.map

package/dist/workspace/supervisor-op.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor-op.d.ts","sourceRoot":"","sources":["../../src/workspace/supervisor-op.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAItD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAEzF,8EAA8E;AAC9E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;CAC9C;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,wBAAwB,CAAC;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACnF,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;CACjE;AAiCD,+EAA+E;AAC/E,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,gBAAgB,GACrB,CAAC,QAAQ,EAAE,oBAAoB,KAAK,OAAO,CAAC,OAAO,CAAC,CAuDtD"}

package/dist/workspace/supervisor-op.js

@@ -0,0 +1,92 @@
+import { CRED_SESSION_USER } from '../runtime/os-contracts.js';
+import { SqliteRuntimeFsBridge } from '../runtime/sqlite-runtime-fs-bridge.js';
+import { getSymlinkRegistry } from '../vfs/symlink-registry.js';
+function stringArg(envelope, index) {
+    const value = envelope.args?.[index];
+    if (typeof value !== 'string') {
+        throw new Error(`supervisor op ${envelope.op}: argument ${index} must be a string`);
+    }
+    return value;
+}
+function numberArg(envelope, index) {
+    const value = envelope.args?.[index];
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`supervisor op ${envelope.op}: argument ${index} must be a number`);
+    }
+    return value;
+}
+function contentArg(envelope, index) {
+    const value = envelope.args?.[index];
+    if (typeof value === 'string' || value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    throw new Error(`supervisor op ${envelope.op}: argument ${index} must be bytes or text`);
+}
+function credFor(deps, pid) {
+    if (pid === undefined)
+        return CRED_SESSION_USER;
+    if (!Number.isInteger(pid) || pid <= 0) {
+        throw new Error('supervisor op: filesystem operation requires a valid process pid');
+    }
+    return deps.processes ? deps.processes.cred(pid) : CRED_SESSION_USER;
+}
+/** One dispatch method lets any host serve its workspace to process facets. */
+export function createSupervisorOpHandler(deps) {
+    const bridges = new Map();
+    const bridgeFor = (pid) => {
+        const key = pid ?? 0;
+        const credentialed = deps.vfs.as(credFor(deps, pid));
+        const held = bridges.get(key);
+        if (held) {
+            held.updateCredential(credentialed);
+            return held;
+        }
+        const built = new SqliteRuntimeFsBridge(credentialed, deps.vfs);
+        bridges.set(key, built);
+        return built;
+    };
+    const ops = {
+        readFile: async (e) => {
+            const bytes = await bridgeFor(e.pid).readFile(stringArg(e, 0));
+            return bytes === null ? null : new TextDecoder().decode(bytes);
+        },
+        readFileBytes: (e) => bridgeFor(e.pid).readFile(stringArg(e, 0)),
+        stat: (e) => bridgeFor(e.pid).stat(stringArg(e, 0)),
+        lstat: (e) => bridgeFor(e.pid).stat(stringArg(e, 0), { followSymlinks: false }),
+        exists: async (e) => (await bridgeFor(e.pid).stat(stringArg(e, 0))) !== null,
+        readdir: (e) => bridgeFor(e.pid).readdir(stringArg(e, 0)),
+        readlink: (e) => bridgeFor(e.pid).readlink(stringArg(e, 0)),
+        fsReadRange: (e) => bridgeFor(e.pid).readRange(stringArg(e, 0), numberArg(e, 1), numberArg(e, 2)),
+        fsReadRangeUncached: (e) => bridgeFor(e.pid).readRange(stringArg(e, 0), numberArg(e, 1), numberArg(e, 2), { cached: false }),
+        fsRevision: (e) => bridgeFor(e.pid).revision(e.args?.[0] === undefined ? undefined : stringArg(e, 0)),
+        hasLegacySymlinkUnder: (e) => getSymlinkRegistry(deps.vfs).hasAtOrBelow(stringArg(e, 0)),
+        writeFile: (e) => bridgeFor(e.pid).writeFile(stringArg(e, 0), contentArg(e, 1)),
+        mkdir: (e) => bridgeFor(e.pid).mkdir(stringArg(e, 0), { recursive: true }),
+        rmdir: (e) => bridgeFor(e.pid).rmdir(stringArg(e, 0)),
+        unlink: (e) => bridgeFor(e.pid).unlink(stringArg(e, 0)),
+        rename: (e) => bridgeFor(e.pid).rename(stringArg(e, 0), stringArg(e, 1)),
+        symlink: (e) => bridgeFor(e.pid).symlink(stringArg(e, 0), stringArg(e, 1)),
+        chmod: (e) => bridgeFor(e.pid).chmod(stringArg(e, 0), numberArg(e, 1)),
+        utimes: (e) => bridgeFor(e.pid).utimes(stringArg(e, 0), numberArg(e, 1), numberArg(e, 2)),
+        fsTruncate: (e) => bridgeFor(e.pid).truncate(stringArg(e, 0), numberArg(e, 1)),
+        writeBatchStream: (e) => {
+            if (!e.stream)
+                throw new Error('supervisor op writeBatchStream: no stream');
+            return deps.vfs.as(credFor(deps, e.pid)).writeStream(e.stream, { mutationOwner: e.mutationOwner });
+        },
+        stdout: (e) => { deps.output?.('stdout', e.pid ?? 0, stringArg(e, 0)); },
+        stderr: (e) => { deps.output?.('stderr', e.pid ?? 0, stringArg(e, 0)); },
+    };
+    const extend = deps.extend ?? {};
+    return async (envelope) => {
+        if (!envelope || typeof envelope.op !== 'string') {
+            throw new Error('supervisor op: envelope names no operation');
+        }
+        const handler = Object.hasOwn(extend, envelope.op) ? extend[envelope.op]
+            : Object.hasOwn(ops, envelope.op) ? ops[envelope.op] : undefined;
+        if (!handler)
+            throw new Error(`supervisor op: '${envelope.op}' is not served by this host`);
+        return handler(envelope);
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nimbus-sh/core",
-  "version": "0.5.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.7.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.2.0",
     "@renovatebot/pep440": "^5.0.0",
     "acorn": "^8.15.0",
     "acorn-walk": "^8.3.5",

package/src/_shared/byte-stream.ts

@@ -18,10 +18,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/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/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. LoaderPool 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.
  *

package/src/_shared/real-node-imports.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 function getRealNodeImportsCode(): string {
@@ -49,5 +56,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/src/_shared/retry.ts

@@ -23,7 +23,7 @@
  * 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). */