@nimbus-sh/core 0.6.0 → 0.8.0

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;
@@ -38,8 +41,14 @@ export interface NimbusWorkspaceOptions {
      * Every atomic write in the filesystem rests on this being a real
      * transaction. An implementation that merely calls the callback converts
      * each one into a torn write that reports success.
+     *
+     * `NimbusWorkspace.create` is a first-write-wins composition root beside
+     * `worker/index.ts` and `loom/actor.ts`: when `ctxExports` is absent the
+     * host's ctx `exports` bag is adopted as the isolate's.
      */
-    readonly transactions?: TransactionHost;
+    readonly transactions?: TransactionHost & {
+        readonly exports?: CtxExports;
+    };
     /**
      * The filesystem already open over `sql`, for a host that has one.
      *
@@ -106,6 +115,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 +138,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 +161,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,11 @@ 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 +127,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 +259,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,107 @@
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+import { type VfsCred } from '../runtime/os-contracts.js';
+import { SqliteRuntimeFsBridge } from '../runtime/sqlite-runtime-fs-bridge.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: SupervisorOpName;
+    readonly args?: readonly unknown[];
+    readonly pid?: number;
+    readonly writerId?: string;
+    readonly mutationOwner?: string;
+    readonly stream?: ReadableStream<Uint8Array>;
+}
+export type SupervisorOpHandler = (envelope: SupervisorOpEnvelope, tools: SupervisorOpTools) => 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;
+    /**
+     * The host's `_rpc*` surface for ops beyond the native set — an in-process
+     * workspace's dispatch record, or the session itself for
+     * `sessionSupervisorOps`. A native op never consults it.
+     */
+    readonly host?: SupervisorOpHost;
+    /**
+     * A pid-keyed bridge cache to serve the native ops from. Supplied by the
+     * session so `supervisorBridge` hands callers the same bridges the handler
+     * uses; in-process workspaces let the handler build its own.
+     */
+    readonly bridge?: SupervisorOpBridgeStore;
+    readonly extend?: Partial<Record<SupervisorOpName, SupervisorOpHandler>>;
+}
+/**
+ * One slot in an op's argument plan: a number takes `envelope.args[n]`, a
+ * name takes the envelope's identity field (`pid`, `writerId`, `stream`,
+ * `mutationOwner`). The envelope is always the shape — a host never
+ * re-parses it.
+ */
+export type SupervisorOpArg = number | 'pid' | 'writerId' | 'stream' | 'mutationOwner';
+export interface SupervisorOpRoute {
+    /** The host method this op dispatches to. */
+    readonly method: string;
+    /** Positional plan for the host call — envelope fields, not raw args. */
+    readonly args: readonly SupervisorOpArg[];
+}
+/**
+ * The embedder's dispatch surface — the `_rpc*` methods SUPERVISOR_OP_ROUTES
+ * names. The session satisfies it with its own class; an in-process
+ * workspace supplies its host object.
+ */
+export interface SupervisorOpHost {
+    readonly [method: string]: unknown;
+}
+/**
+ * The canonical supervisor op set — every operation the supervisor RPC
+ * serves. Three consumers key on these names:
+ *
+ *   - `sessionSupervisorOp` (worker): the DO's host — `extend` overrides for
+ *     hosted accounting plus the non-filesystem ops it answers itself.
+ *   - `createSupervisorOpHandler`: an in-process workspace — filesystem ops
+ *     run against the VFS directly; every other op dispatches to
+ *     `deps.host` through SUPERVISOR_OP_ROUTES, the embedder's `_rpc*`
+ *     surface.
+ *   - `supervisor-host-dispatch`: the test — derives every case's delegate
+ *     and expected arguments from SUPERVISOR_OP_ROUTES, not a copied list.
+ *
+ * An op absent here is not served, on any host.
+ */
+export declare const SUPERVISOR_OPS: readonly ["readFile", "readFileBytes", "writeFile", "stat", "lstat", "hasLegacySymlinkUnder", "utimes", "chmod", "access", "chown", "setUmask", "readdir", "exists", "mkdir", "rmdir", "rename", "unlink", "readlink", "symlink", "fsAcquire", "fsRevision", "fsList", "wsOpen", "wsPoll", "wsSend", "wsClose", "fsOpen", "fsRead", "fsWrite", "fsClose", "fsReadRange", "fsReadRangeUncached", "fsReadBatch", "fsWriteRange", "fsAppend", "fsAppendAck", "fsTruncate", "writeBatch", "writeBatchStream", "putRegistryEntries", "stdout", "stderr", "prefetch", "registerPort", "unregisterPort", "reportExit", "routeLoopback", "transform", "cpSpawn", "cpStdinWrite", "cpStdinEnd", "cpReadStdin", "cpReadOutput", "cpDrainOutput", "cpKill", "cpWait", "cpDispatchInline"];
+export type SupervisorOpName = (typeof SUPERVISOR_OPS)[number];
+/**
+ * What the shared handler hands a host override: the pid-keyed bridge and
+ * the deps it was built with, so an override that wraps a filesystem op
+ * (read-allocation accounting, stream-drain timing) reuses the same bridge
+ * the default handler would have used instead of caching its own.
+ */
+export interface SupervisorOpTools {
+    readonly bridge: (pid?: number) => SqliteRuntimeFsBridge;
+    readonly vfs: SqliteVFS;
+    readonly cred: (pid?: number) => VfsCred;
+    readonly output?: (stream: 'stdout' | 'stderr', pid: number, data: string) => void;
+}
+/** The host-side argument plan per op — how an envelope becomes an _rpc* call. */
+export declare const SUPERVISOR_OP_ROUTES: Readonly<Record<SupervisorOpName, SupervisorOpRoute>>;
+/**
+ * The ops `createSupervisorOpHandler` serves natively — one pid-keyed
+ * filesystem bridge, plus the output stream. A session's `extend` overrides
+ * never cover these by accident: `sessionSupervisorOps` builds its delegate
+ * set from this name list, not a hand-copied table.
+ */
+export declare const SUPERVISOR_NATIVE_OPS: ReadonlySet<string>;
+/** The pid-keyed bridge cache behind the native filesystem ops. */
+export interface SupervisorOpBridgeStore {
+    readonly bridge: (pid?: number) => SqliteRuntimeFsBridge;
+    /** Drop a pid's bridge — a process exit ends its credential's validity. */
+    readonly forget: (pid: number) => void;
+}
+/**
+ * Exported so the session's `supervisorBridge` — used by RPC bodies the
+ * envelope delegates back to (fsOpen, fsAppend, writeBatch, …) — is the
+ * same cache the handler's native ops serve from, never a second one.
+ */
+export declare function createSupervisorBridgeStore(deps: Pick<SupervisorOpDeps, 'vfs' | 'processes'>): SupervisorOpBridgeStore;
+/** 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":"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"}

package/dist/workspace/supervisor-op.js

@@ -0,0 +1,224 @@
+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;
+}
+/**
+ * The canonical supervisor op set — every operation the supervisor RPC
+ * serves. Three consumers key on these names:
+ *
+ *   - `sessionSupervisorOp` (worker): the DO's host — `extend` overrides for
+ *     hosted accounting plus the non-filesystem ops it answers itself.
+ *   - `createSupervisorOpHandler`: an in-process workspace — filesystem ops
+ *     run against the VFS directly; every other op dispatches to
+ *     `deps.host` through SUPERVISOR_OP_ROUTES, the embedder's `_rpc*`
+ *     surface.
+ *   - `supervisor-host-dispatch`: the test — derives every case's delegate
+ *     and expected arguments from SUPERVISOR_OP_ROUTES, not a copied list.
+ *
+ * An op absent here is not served, on any host.
+ */
+export const SUPERVISOR_OPS = [
+    'readFile', 'readFileBytes', 'writeFile', 'stat', 'lstat',
+    'hasLegacySymlinkUnder', 'utimes', 'chmod', 'access', 'chown', 'setUmask',
+    'readdir', 'exists', 'mkdir', 'rmdir', 'rename', 'unlink', 'readlink',
+    'symlink', 'fsAcquire', 'fsRevision', 'fsList', 'wsOpen', 'wsPoll',
+    'wsSend', 'wsClose', 'fsOpen', 'fsRead', 'fsWrite', 'fsClose',
+    'fsReadRange', 'fsReadRangeUncached', 'fsReadBatch', 'fsWriteRange',
+    'fsAppend', 'fsAppendAck', 'fsTruncate', 'writeBatch', 'writeBatchStream',
+    'putRegistryEntries', 'stdout', 'stderr', 'prefetch', 'registerPort',
+    'unregisterPort', 'reportExit', 'routeLoopback', 'transform', 'cpSpawn',
+    'cpStdinWrite', 'cpStdinEnd', 'cpReadStdin', 'cpReadOutput',
+    'cpDrainOutput', 'cpKill', 'cpWait', 'cpDispatchInline',
+];
+/** The host-side argument plan per op — how an envelope becomes an _rpc* call. */
+export const SUPERVISOR_OP_ROUTES = {
+    readFile: { method: '_rpcReadFile', args: [0, 'pid'] },
+    readFileBytes: { method: '_rpcReadFileBytes', args: [0, 'pid'] },
+    writeFile: { method: '_rpcWriteFile', args: [0, 1, 'pid'] },
+    stat: { method: '_rpcStat', args: [0, 'pid'] },
+    lstat: { method: '_rpcLstat', args: [0, 'pid'] },
+    hasLegacySymlinkUnder: { method: '_rpcHasLegacySymlinkUnder', args: [0, 'pid'] },
+    utimes: { method: '_rpcUtimes', args: [0, 1, 2, 'pid'] },
+    chmod: { method: '_rpcChmod', args: [0, 1, 'pid'] },
+    access: { method: '_rpcAccess', args: [0, 1, 'pid'] },
+    chown: { method: '_rpcChown', args: [0, 1, 2, 'pid', 3] },
+    setUmask: { method: '_rpcSetUmask', args: [0, 'pid'] },
+    readdir: { method: '_rpcReaddir', args: [0, 'pid'] },
+    exists: { method: '_rpcExists', args: [0, 'pid'] },
+    mkdir: { method: '_rpcMkdir', args: [0, 'pid'] },
+    rmdir: { method: '_rpcRmdir', args: [0, 'pid'] },
+    rename: { method: '_rpcRename', args: [0, 1, 'pid'] },
+    unlink: { method: '_rpcUnlink', args: [0, 'pid'] },
+    readlink: { method: '_rpcReadlink', args: [0, 'pid'] },
+    symlink: { method: '_rpcSymlink', args: [0, 1, 'pid'] },
+    fsAcquire: { method: '_rpcFsAcquire', args: [0, 1, 'pid'] },
+    fsRevision: { method: '_rpcFsRevision', args: [0, 'pid'] },
+    fsList: { method: '_rpcFsList', args: [0, 1, 'pid'] },
+    wsOpen: { method: '_rpcWsOpen', args: [0, 1, 'pid'] },
+    wsPoll: { method: '_rpcWsPoll', args: [0, 1, 'pid'] },
+    wsSend: { method: '_rpcWsSend', args: [0, 1, 2, 'pid'] },
+    wsClose: { method: '_rpcWsClose', args: [0, 1, 2, 'pid'] },
+    fsOpen: { method: '_rpcFsOpen', args: [0, 1, 'pid'] },
+    fsRead: { method: '_rpcFsRead', args: [0, 1, 2, 'pid'] },
+    fsWrite: { method: '_rpcFsWrite', args: [0, 1, 2, 'pid'] },
+    fsClose: { method: '_rpcFsClose', args: [0, 'pid'] },
+    fsReadRange: { method: '_rpcFsReadRange', args: [0, 1, 2, 'pid'] },
+    fsReadRangeUncached: { method: '_rpcFsReadRangeUncached', args: [0, 1, 2, 'pid'] },
+    fsReadBatch: { method: '_rpcFsReadBatch', args: [0, 'pid'] },
+    fsWriteRange: { method: '_rpcFsWriteRange', args: [0, 1, 2, 'pid'] },
+    fsAppend: { method: '_rpcFsAppend', args: [0, 'writerId', 1, 2, 3, 'pid'] },
+    fsAppendAck: { method: '_rpcFsAppendAck', args: ['writerId', 0, 1, 'pid'] },
+    fsTruncate: { method: '_rpcFsTruncate', args: [0, 1, 'pid'] },
+    writeBatch: { method: '_rpcWriteBatch', args: [0, 'pid'] },
+    writeBatchStream: { method: '_rpcWriteBatchStream', args: ['stream', 'mutationOwner', 'pid'] },
+    putRegistryEntries: { method: '_rpcPutRegistryEntries', args: [0] },
+    stdout: { method: '_rpcStdout', args: ['pid', 0] },
+    stderr: { method: '_rpcStderr', args: ['pid', 0] },
+    prefetch: { method: '_rpcPrefetch', args: [0, 1] },
+    registerPort: { method: '_rpcRegisterPort', args: ['pid', 0] },
+    unregisterPort: { method: '_rpcUnregisterPort', args: [0] },
+    reportExit: { method: '_rpcReportExit', args: ['pid', 0, 1] },
+    routeLoopback: { method: '_rpcRouteLoopback', args: [0, 1] },
+    transform: { method: '_rpcTransform', args: [0, 1] },
+    cpSpawn: { method: '_rpcCpSpawn', args: [0] },
+    cpStdinWrite: { method: '_rpcCpStdinWrite', args: [0, 1] },
+    cpStdinEnd: { method: '_rpcCpStdinEnd', args: [0] },
+    cpReadStdin: { method: '_rpcCpReadStdin', args: [0, 1] },
+    cpReadOutput: { method: '_rpcCpReadOutput', args: [0, 1, 2, 3] },
+    cpDrainOutput: { method: '_rpcCpDrainOutput', args: [0] },
+    cpKill: { method: '_rpcCpKill', args: [0, 1] },
+    cpWait: { method: '_rpcCpWait', args: [0, 1] },
+    cpDispatchInline: { method: '_rpcCpDispatchInline', args: [0, 1] },
+};
+/**
+ * The ops `createSupervisorOpHandler` serves natively — one pid-keyed
+ * filesystem bridge, plus the output stream. A session's `extend` overrides
+ * never cover these by accident: `sessionSupervisorOps` builds its delegate
+ * set from this name list, not a hand-copied table.
+ */
+export const SUPERVISOR_NATIVE_OPS = new Set([
+    'readFile', 'readFileBytes', 'stat', 'lstat', 'exists', 'readdir',
+    'readlink', 'fsReadRange', 'fsReadRangeUncached', 'fsRevision',
+    'hasLegacySymlinkUnder', 'writeFile', 'mkdir', 'rmdir', 'unlink',
+    'rename', 'symlink', 'chmod', 'utimes', 'fsTruncate',
+    'writeBatchStream', 'stdout', 'stderr',
+]);
+/**
+ * Exported so the session's `supervisorBridge` — used by RPC bodies the
+ * envelope delegates back to (fsOpen, fsAppend, writeBatch, …) — is the
+ * same cache the handler's native ops serve from, never a second one.
+ */
+export function createSupervisorBridgeStore(deps) {
+    const bridges = new Map();
+    return {
+        bridge: (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;
+        },
+        forget: (pid) => { bridges.delete(pid); },
+    };
+}
+/** One dispatch method lets any host serve its workspace to process facets. */
+export function createSupervisorOpHandler(deps) {
+    const bridgeFor = deps.bridge?.bridge ?? createSupervisorBridgeStore(deps).bridge;
+    const tools = {
+        bridge: bridgeFor,
+        vfs: deps.vfs,
+        cred: (pid) => credFor(deps, pid),
+        output: deps.output,
+    };
+    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');
+        }
+        // Priority: the embedder's own handler → the native filesystem op → the
+        // canonical route table onto the host's _rpc* methods. An op in none of
+        // these is not served by this host.
+        const handler = Object.hasOwn(extend, envelope.op) ? extend[envelope.op]
+            : Object.hasOwn(ops, envelope.op) ? ops[envelope.op] : undefined;
+        if (handler)
+            return handler(envelope, tools);
+        const route = Object.hasOwn(SUPERVISOR_OP_ROUTES, envelope.op)
+            ? SUPERVISOR_OP_ROUTES[envelope.op] : undefined;
+        if (!route)
+            throw new Error(`supervisor op: '${envelope.op}' is not served by this host`);
+        const host = deps.host;
+        if (!host)
+            throw new Error(`supervisor op: '${envelope.op}' needs a host that this workspace does not have`);
+        const method = host[route.method];
+        if (typeof method !== 'function')
+            throw new Error(`supervisor op: missing host method ${route.method}`);
+        const args = route.args.map((slot) => typeof slot === 'number' ? envelope.args?.[slot] : envelope[slot]);
+        return Reflect.apply(method, host, args);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/core",
-  "version": "0.6.0",
+  "version": "0.8.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",
@@ -55,7 +55,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nimbus-sh/platform": "^0.1.0",
+    "@nimbus-sh/platform": "^0.3.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/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/tarball.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,10 +7,8 @@
  * 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 {
@@ -18,6 +16,63 @@ import {
   readableStreamToAsyncIterable,
 } from './tarball-stream.js';
 
+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;
+}
+
+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: ReadableStream<Uint8Array>,
+  targetDir: string,
+  vfs: TarballWriteTarget,
+): Promise<TarballWriteResult> {
+  const ensureDir = (path: string): void => {
+    if (!vfs.exists(path)) vfs.mkdir(path, { recursive: true });
+  };
+  ensureDir(targetDir);
+  let files = 0;
+  let bytes = 0;
+  let manifest: Uint8Array | null = 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: ArrayBuffer,