@nimbus-sh/core 0.5.0 → 0.7.0

package/src/substrate/lifo/shell/terminal-stdin.ts

@@ -1,14 +1,18 @@
+import { encode } from '../utils/encoding.js';
 import type { TerminalInputStream } from '../commands/types.js';
 
 /**
- * A bridge between terminal keyboard input and command stdin.
- * The Shell feeds lines in via feed(), commands consume via read()/readAll().
+ * A bridge between terminal keyboard input and command stdin. The Shell
+ * feeds lines in via feed(); commands consume bytes or text. Bytes are the
+ * storage format, so a byte read always makes progress even when maxLength
+ * splits a multi-byte code point — `dd bs=1` over `é` yields c3, then a9.
  */
 export class TerminalStdin implements TerminalInputStream {
-  private buffer: string[] = [];
+  private buffer: Uint8Array[] = [];
   private closed = false;
-  private resolvers: Array<(value: string | null) => void> = [];
+  private resolvers: Array<(value: Uint8Array | null) => void> = [];
   private _rawMode = false;
+  private decoder = new TextDecoder('utf-8');
 
   /** True when a command has called read() and is waiting for input. */
   get isWaiting(): boolean {
@@ -26,16 +30,13 @@ export class TerminalStdin implements TerminalInputStream {
 
   /** Shell calls this on Enter (with line + '\n'). */
   feed(text: string): void {
-    if (this.closed) return;
-
-    this.deliver(text, 'back');
+    if (this.closed || text === '') return;
+    this.deliver(encode(text), 'back');
   }
 
   /** Shell calls this on Ctrl+D to signal EOF. */
   close(): void {
-    if (this.closed) return;
     this.closed = true;
-
     while (this.resolvers.length > 0) {
       const resolve = this.resolvers.shift()!;
       resolve(null);
@@ -44,15 +45,15 @@ export class TerminalStdin implements TerminalInputStream {
 
   /** Commands consume input. Returns null on EOF. */
   async read(): Promise<string | null> {
-    if (this.buffer.length > 0) {
-      return this.buffer.shift()!;
-    }
-    if (this.closed) {
-      return null;
+    while (true) {
+      const bytes = await this.pull();
+      if (bytes === null) {
+        const tail = this.decoder.decode();
+        return tail.length > 0 ? tail : null;
+      }
+      const text = this.decoder.decode(bytes, { stream: true });
+      if (text.length > 0) return text;
     }
-    return new Promise<string | null>((resolve) => {
-      this.resolvers.push(resolve);
-    });
   }
 
   async readLine(): Promise<string | null> {
@@ -64,7 +65,7 @@ export class TerminalStdin implements TerminalInputStream {
       const newline = chunk.indexOf('\n');
       if (newline >= 0) {
         const rest = chunk.slice(newline + 1);
-        if (rest.length > 0) this.deliver(rest, 'front');
+        if (rest.length > 0) this.deliverBackText(rest);
         return line + chunk.slice(0, newline);
       }
 
@@ -72,15 +73,21 @@ export class TerminalStdin implements TerminalInputStream {
     }
   }
 
-  async readBytes(maxLength: number): Promise<string | null> {
-    if (maxLength <= 0) return '';
-
-    const chunk = await this.read();
+  /**
+   * Bounded byte read: returns whatever the user has already typed, capped
+   * at maxLength. maxLength bounds the result, it is never a fill target —
+   * a command reading bytes must not stall until maxLength arrive. A larger
+   * queued chunk keeps only its first maxLength bytes; the remainder stays
+   * queued, so `dd bs=1` over `é` still yields c3, then a9.
+   */
+  async readBytes(maxLength: number): Promise<Uint8Array | null> {
+    if (maxLength <= 0) return new Uint8Array(0);
+
+    const chunk = await this.pull();
     if (chunk === null) return null;
     if (chunk.length <= maxLength) return chunk;
-
-    this.deliver(chunk.slice(maxLength), 'front');
-    return chunk.slice(0, maxLength);
+    this.buffer.unshift(chunk.subarray(maxLength));
+    return chunk.subarray(0, maxLength);
   }
 
   /** Read all remaining input until EOF, joined together. */
@@ -94,16 +101,45 @@ export class TerminalStdin implements TerminalInputStream {
     return parts.join('');
   }
 
-  private deliver(text: string, position: 'front' | 'back'): void {
-    if (text.length === 0) return;
+  /**
+   * Text snapshot of everything queued but not yet consumed. The shell's
+   * wrap layer uses this for commands that want drained terminal input.
+   */
+  drainBuffered(): string {
+    let text = '';
+    while (this.buffer.length > 0) {
+      text += this.decoder.decode(this.buffer.shift()!, { stream: true });
+    }
+    text += this.decoder.decode();
+    return text;
+  }
+
+  private pull(): Promise<Uint8Array | null> {
+    if (this.buffer.length > 0) {
+      return Promise.resolve(this.buffer.shift() ?? null);
+    }
+    if (this.closed) {
+      return Promise.resolve(null);
+    }
+    return new Promise<Uint8Array | null>((resolve) => {
+      this.resolvers.push(resolve);
+    });
+  }
+
+  private deliver(bytes: Uint8Array, position: 'front' | 'back'): void {
+    if (bytes.length === 0) return;
 
     if (this.resolvers.length > 0) {
       const resolve = this.resolvers.shift()!;
-      resolve(text);
+      resolve(bytes);
       return;
     }
 
-    if (position === 'front') this.buffer.unshift(text);
-    else this.buffer.push(text);
+    if (position === 'front') this.buffer.unshift(bytes);
+    else this.buffer.push(bytes);
+  }
+
+  private deliverBackText(text: string): void {
+    this.deliver(encode(text), 'front');
   }
 }

package/src/vfs/seed-project.ts

@@ -18,12 +18,12 @@
  *   - Basename injection (commit 2) handles the /preview/ basepath wiring.
  */
 
+import type { SqliteVFS } from './sqlite-vfs.js';
 import type {
-  SqliteVFS,
   BatchInodeEntry,
   BatchChunkEntry,
-} from './sqlite-vfs.js';
-import { CHUNK_SIZE } from '../constants.js';
+} from '@nimbus-sh/platform/w7-frame.js';
+import { CHUNK_SIZE } from '@nimbus-sh/platform/limits.js';
 import { enc } from '../_shared/bytes.js';
 import { errorText } from '../_shared/error-text.js';
 import { CRED_KERNEL } from '../runtime/os-contracts.js';

package/src/vfs/sqlite-vfs.ts

@@ -43,27 +43,33 @@
 import { VfsEventEmitter, type VfsEventType } from './events.js';
 import { normalizeVfsPath } from './path.js';
 import {
-  CHUNK_SIZE,
   LRU_MAX_ENTRIES,
   BATCH_SIZE,
+  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,
-  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';
+} 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,
+  type BatchChunkEntry,
+  type BatchInodeEntry,
+  type BatchWritePayload,
+  type VfsInodeKind,
   type W7DecodedRecord,
-} from '../_shared/w7-frame.js';
+} from '@nimbus-sh/platform/w7-frame.js';
 import {
   WeightedCreditPool,
   type CreditLease,
-} from '../_shared/weighted-credit-pool.js';
+} from '@nimbus-sh/platform/weighted-credit-pool.js';
 import { LEGACY_SYMLINK_REGISTRY_PATH } from './symlink-registry.js';
 import {
   CRED_KERNEL,
@@ -104,8 +110,16 @@ function installPipelineDiagEnabled(): boolean {
 }
 
 // ── Types ───────────────────────────────────────────────────────────────────
-
-export type VfsInodeKind = 'file' | 'directory' | 'symlink';
+// VfsInodeKind and the writeBatch payload types (BatchInodeEntry,
+// BatchChunkEntry, BatchWritePayload) live with the wire format that encodes
+// them: @nimbus-sh/platform/w7-frame.js. Forwarded here because core@0.5.0
+// published them from this module; platform stays the definition.
+export type {
+  BatchChunkEntry,
+  BatchInodeEntry,
+  BatchWritePayload,
+  VfsInodeKind,
+} from '@nimbus-sh/platform/w7-frame.js';
 
 export interface ExclusiveMutationLease {
   readonly root: string;
@@ -133,22 +147,6 @@ interface INode {
   contentId: string | null;
 }
 
-/** Entry for bulk inode creation via writeBatch(). */
-export interface BatchInodeEntry {
-  path: string;
-  parentPath: string;
-  /** Defaults to isDir ? directory : file for legacy/non-symlink producers. */
-  kind?: VfsInodeKind;
-  isDir: boolean;
-  size: number;
-  atime?: number;
-  mtime: number;
-  mode: number;
-  uid?: number;
-  gid?: number;
-  chunkCount: number;
-}
-
 export interface VfsStat {
   type: VfsInodeKind;
   size: number;
@@ -233,21 +231,6 @@ export interface CredentialedVfs {
   readonly epoch: string;
 }
 
-/** Entry for bulk chunk creation via writeBatch(). */
-export interface BatchChunkEntry {
-  path: string;
-  chunkId: number;
-  data: Uint8Array;
-}
-
-/** Payload for writeBatch() — all inodes + chunks written in ONE transactionSync(). */
-export interface BatchWritePayload {
-  inodes: BatchInodeEntry[];
-  chunks: BatchChunkEntry[];
-  /** Paths to delete before writing (for clean reinstall). */
-  deletePaths?: string[];
-}
-
 export interface WriteBatchStreamProgress {
   /** 1-based sequence of the last durable publish group; zero means none. */
   committedGroupSequence: number;
@@ -631,10 +614,9 @@ export class SqliteVFS {
 
   // ── 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.
   private _totalFiles = 0;
   private _totalDirs = 0;
   private _usedBytes = 0;
@@ -649,6 +631,10 @@ 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.
   private _pathRevisions = new Map<string, number>();
+  private transactionPublication: {
+    paths: Set<string>;
+    events: { type: VfsEventType; path: string; oldPath?: string }[];
+  } | null = null;
 
   // ── Invalidation log (facet cache coherence) ──────────────────────────
   // A facet's resident set is a cache of this VFS, and it learns what to
@@ -1690,6 +1676,10 @@ export class SqliteVFS {
    * additional coverage, since no facet view keys on a grandparent.
    */
   private bumpRevision(paths: readonly string[]): void {
+    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);
@@ -1901,7 +1891,7 @@ export class SqliteVFS {
     this._addToChildrenIndex(pp, path);
     this._totalDirs++; // B3
     this.bumpRevision([path]);
-    this.events.emit('addDir', path);
+    this.emitMutation('addDir', path);
   }
 
   private writeFile(
@@ -2922,11 +2912,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);
   }
 
   /**
@@ -2966,10 +2956,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);
   }
 
   private chown(
@@ -2992,18 +2982,21 @@ 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;
+    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 = ?',
-      inode.uid,
-      inode.gid,
-      inode.mode,
+      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);
   }
 
   /**
@@ -3216,15 +3209,19 @@ export class SqliteVFS {
 
   private rename(oldPath: string, newPath: string, cred: VfsCred): void {
     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) return;
     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
@@ -3234,7 +3231,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) {
@@ -3398,7 +3395,7 @@ export class SqliteVFS {
     }
 
     this.bumpRevision([...touchedPaths]);
-    this.events.emit('rename', newPath, oldPath);
+    this.emitMutation('rename', newPath, oldPath);
     this.runContentMaintenanceSafely(1);
   }
 
@@ -4097,6 +4094,72 @@ 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<T>(callback: () => T): T {
+    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<string>(),
+      events: new Array<{ type: VfsEventType; path: string; oldPath?: string }>(),
+    };
+    const maintenancePending = this.maintenancePending;
+    this.transactionPublication = publication;
+    let result: T;
+    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;
+  }
+
+  private emitMutation(type: VfsEventType, path: string, oldPath?: string): void {
+    if (this.transactionPublication) {
+      this.transactionPublication.events.push({ type, path, oldPath });
+    } else {
+      this.events.emit(type, path, oldPath);
+    }
+  }
+
   private transactionSync(callback: () => void): void {
     if (!this.ctx?.storage?.transactionSync) {
       throw new Error('[sqlite-vfs] atomic storage operation requires transactionSync');
@@ -4465,6 +4528,7 @@ export class SqliteVFS {
   }
 
   private runContentMaintenanceSafely(maxTransactions: number, force = false): void {
+    if (this.transactionPublication) return;
     if (!force && !this.maintenancePending) return;
     const startedAt = performance.now();
     try {
@@ -4790,10 +4854,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);

package/src/workspace/nimbus-workspace.ts

@@ -48,6 +48,8 @@ import { seedRuntimePackage, type RuntimePackage } from '../runtime/runtime-pack
 import type { EsbuildService } from '../runtime/esbuild-service.js';
 import { registerUnixCommands } from '../shell/unix-commands.js';
 import { installPathExecResolver } from '../shell/exec-dispatch.js';
+import { adoptCtxExports, composeFabric, type CtxExports, type FabricComposition } from '@nimbus-sh/platform/composition.js';
+import { createSupervisorOpHandler, type SupervisorOpEnvelope, type SupervisorOpHandler } from './supervisor-op.js';
 
 export interface NimbusWorkspaceOptions {
   /** The host's SQLite. In a Durable Object: `ctx.storage.sql`. */
@@ -126,6 +128,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>>;
 }
 
 /**
@@ -168,6 +179,7 @@ export class NimbusWorkspace {
     registry: CommandRegistry,
     env: Record<string, string>,
     private readonly sql: SqlDatabase,
+    private readonly supervisorOps: (envelope: SupervisorOpEnvelope) => Promise<unknown>,
   ) {
     this.vfs = vfs;
     this.kernel = kernel;
@@ -182,6 +194,10 @@ export class NimbusWorkspace {
   }
 
   static async create(options: NimbusWorkspaceOptions): Promise<NimbusWorkspace> {
+    if (options.fabric) composeFabric(options.fabric);
+    const exports = options.ctxExports
+      ?? (options.transactions as (TransactionHost & { exports?: CtxExports }) | undefined)?.exports;
+    if (exports) adoptCtxExports(exports);
     const vfs = options.vfs ?? openFilesystem(options);
     const mounts = options.mounts ?? DEFAULT_MOUNT_POINTS;
     seedBaseFilesystem(vfs, mounts);
@@ -234,13 +250,21 @@ export class NimbusWorkspace {
       });
     }
 
-    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: string, options?: RunOptions): Promise<CommandResult> {
     return this.commands.run(command, options);
   }
 
+  /** The hosting object forwards its supervisorOp RPC to this method. */
+  supervisorOp(envelope: SupervisorOpEnvelope): Promise<unknown> {
+    return this.supervisorOps(envelope);
+  }
+
   /**
    * Apply the login files, and begin reading the terminal when there is one.
    *
@@ -383,7 +407,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;
       },