@nimbus-sh/core 0.1.0

package/dist/vfs/symlink-registry.d.ts

@@ -0,0 +1,60 @@
+/**
+ * symlink-registry.ts — virtual symlink table backed by a special
+ * JSON file in the SqliteVFS.
+ *
+ * Native symlinks now live in SqliteVFS. This registry remains the durable
+ * compatibility path for symlinks created by older sessions.
+ *
+ * Storage: `/.nimbus-symlinks.json` with shape `{ [linkPath]: target }`.
+ * The registry cache tracks the backing inode revision so direct durable
+ * writes cannot leave clone destination proofs on a stale view.
+ *
+ * Native inodes take precedence when both representations exist.
+ *
+ * Loop guard: `resolveSymlinkChain` follows at most 40 hops (matches
+ * POSIX SYMLOOP_MAX).
+ */
+import type { SqliteVFS } from './sqlite-vfs.js';
+export declare const LEGACY_SYMLINK_REGISTRY_PATH = ".nimbus-symlinks.json";
+export declare class SymlinkRegistry {
+    private vfs;
+    private view;
+    private cache;
+    private cacheRevision;
+    constructor(vfs: SqliteVFS);
+    /** Lazy-load the registry and refresh it after direct backing-file writes. */
+    private load;
+    /** Persist a complete registry snapshot before publishing it to readers. */
+    private persist;
+    /** Normalize a path to the VFS internal key convention. */
+    private norm;
+    /** Create or replace a symlink. Target is stored verbatim (can be
+     *  absolute or relative — interpretation happens at resolve time). */
+    set(linkPath: string, target: string): void;
+    /** Remove a symlink. Returns true if it existed. */
+    delete(linkPath: string): boolean;
+    assertMutable(...paths: string[]): void;
+    /** Check if `path` is registered as a symlink (no chain resolution). */
+    isSymlink(path: string): boolean;
+    /** Get the immediate target of a symlink. Returns null if not a symlink. */
+    readlink(path: string): string | null;
+    /**
+     * Follow a symlink chain until we hit a non-symlink (or run out of
+     * hops). Returns the resolved path (canonicalized to no-leading-slash).
+     * If the chain breaks (max-hops or missing target), returns the
+     * last-resolved path or null.
+     *
+     * `cwd` is used to resolve RELATIVE symlink targets (target without
+     * leading `/`). POSIX semantics: relative targets resolve from the
+     * symlink's directory, not the current cwd.
+     */
+    resolveChain(startPath: string): string | null;
+    /** List all currently-registered symlinks (debugging / ls -la support). */
+    list(): {
+        link: string;
+        target: string;
+    }[];
+    hasAtOrBelow(path: string): boolean;
+}
+export declare function getSymlinkRegistry(vfs: SqliteVFS): SymlinkRegistry;
+//# sourceMappingURL=symlink-registry.d.ts.map

package/dist/vfs/symlink-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symlink-registry.d.ts","sourceRoot":"","sources":["../../src/vfs/symlink-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAmB,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIlE,eAAO,MAAM,4BAA4B,0BAA0B,CAAC;AAEpE,qBAAa,eAAe;IAC1B,OAAO,CAAC,GAAG,CAAY;IACvB,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,aAAa,CAAM;gBAEf,GAAG,EAAE,SAAS;IAK1B,8EAA8E;IAC9E,OAAO,CAAC,IAAI;IAuBZ,4EAA4E;IAC5E,OAAO,CAAC,OAAO;IAUf,2DAA2D;IAC3D,OAAO,CAAC,IAAI;IAIZ;0EACsE;IACtE,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ3C,oDAAoD;IACpD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAYjC,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAKvC,wEAAwE;IACxE,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIhC,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKrC;;;;;;;;;OASG;IACH,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAiB9C,2EAA2E;IAC3E,IAAI,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE;IAQ1C,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAOpC;AASD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,SAAS,GAAG,eAAe,CAMlE"}

package/dist/vfs/symlink-registry.js

@@ -0,0 +1,162 @@
+/**
+ * symlink-registry.ts — virtual symlink table backed by a special
+ * JSON file in the SqliteVFS.
+ *
+ * Native symlinks now live in SqliteVFS. This registry remains the durable
+ * compatibility path for symlinks created by older sessions.
+ *
+ * Storage: `/.nimbus-symlinks.json` with shape `{ [linkPath]: target }`.
+ * The registry cache tracks the backing inode revision so direct durable
+ * writes cannot leave clone destination proofs on a stale view.
+ *
+ * Native inodes take precedence when both representations exist.
+ *
+ * Loop guard: `resolveSymlinkChain` follows at most 40 hops (matches
+ * POSIX SYMLOOP_MAX).
+ */
+import { CRED_KERNEL } from '../runtime/os-contracts.js';
+import { normalizeVfsPath } from './path.js';
+export const LEGACY_SYMLINK_REGISTRY_PATH = '.nimbus-symlinks.json';
+export class SymlinkRegistry {
+    vfs;
+    view;
+    cache = null;
+    cacheRevision = -1;
+    constructor(vfs) {
+        this.vfs = vfs;
+        this.view = vfs.as(CRED_KERNEL);
+    }
+    /** Lazy-load the registry and refresh it after direct backing-file writes. */
+    load() {
+        const revision = this.vfs.revision(LEGACY_SYMLINK_REGISTRY_PATH);
+        if (this.cache && this.cacheRevision === revision)
+            return this.cache;
+        const next = new Map();
+        if (this.view.exists(LEGACY_SYMLINK_REGISTRY_PATH)) {
+            const raw = this.view.readFileString(LEGACY_SYMLINK_REGISTRY_PATH);
+            const parsed = JSON.parse(raw);
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                throw new Error(`[symlink-registry] invalid ${LEGACY_SYMLINK_REGISTRY_PATH}`);
+            }
+            for (const [link, target] of Object.entries(parsed)) {
+                if (typeof target !== 'string') {
+                    throw new Error(`[symlink-registry] invalid target for ${link}`);
+                }
+                next.set(link, target);
+            }
+        }
+        this.cache = next;
+        this.cacheRevision = revision;
+        return next;
+    }
+    /** Persist a complete registry snapshot before publishing it to readers. */
+    persist(next) {
+        const obj = {};
+        for (const [k, v] of next)
+            obj[k] = v;
+        const created = !this.view.exists(LEGACY_SYMLINK_REGISTRY_PATH);
+        this.view.writeFile(LEGACY_SYMLINK_REGISTRY_PATH, JSON.stringify(obj));
+        if (created)
+            this.view.chown(LEGACY_SYMLINK_REGISTRY_PATH, 1000, 1000);
+        this.cache = next;
+        this.cacheRevision = this.vfs.revision(LEGACY_SYMLINK_REGISTRY_PATH);
+    }
+    /** Normalize a path to the VFS internal key convention. */
+    norm(p) {
+        return normalizeVfsPath(p);
+    }
+    /** Create or replace a symlink. Target is stored verbatim (can be
+     *  absolute or relative — interpretation happens at resolve time). */
+    set(linkPath, target) {
+        this.vfs.assertMutationAllowed(linkPath);
+        this.vfs.assertMutationAllowed(LEGACY_SYMLINK_REGISTRY_PATH);
+        const next = new Map(this.load());
+        next.set(this.norm(linkPath), target);
+        this.persist(next);
+    }
+    /** Remove a symlink. Returns true if it existed. */
+    delete(linkPath) {
+        const cache = this.load();
+        const normalized = this.norm(linkPath);
+        if (!cache.has(normalized))
+            return false;
+        this.vfs.assertMutationAllowed(normalized);
+        this.vfs.assertMutationAllowed(LEGACY_SYMLINK_REGISTRY_PATH);
+        const next = new Map(cache);
+        next.delete(normalized);
+        this.persist(next);
+        return true;
+    }
+    assertMutable(...paths) {
+        for (const path of paths)
+            this.vfs.assertMutationAllowed(path);
+        this.vfs.assertMutationAllowed(LEGACY_SYMLINK_REGISTRY_PATH);
+    }
+    /** Check if `path` is registered as a symlink (no chain resolution). */
+    isSymlink(path) {
+        return this.load().has(this.norm(path));
+    }
+    /** Get the immediate target of a symlink. Returns null if not a symlink. */
+    readlink(path) {
+        const v = this.load().get(this.norm(path));
+        return v === undefined ? null : v;
+    }
+    /**
+     * Follow a symlink chain until we hit a non-symlink (or run out of
+     * hops). Returns the resolved path (canonicalized to no-leading-slash).
+     * If the chain breaks (max-hops or missing target), returns the
+     * last-resolved path or null.
+     *
+     * `cwd` is used to resolve RELATIVE symlink targets (target without
+     * leading `/`). POSIX semantics: relative targets resolve from the
+     * symlink's directory, not the current cwd.
+     */
+    resolveChain(startPath) {
+        let cur = this.norm(startPath);
+        for (let hops = 0; hops < 40; hops++) {
+            const target = this.load().get(cur);
+            if (target === undefined)
+                return cur; // not a symlink — done
+            if (target.startsWith('/')) {
+                cur = this.norm(target);
+            }
+            else {
+                // Relative target: resolve from symlink's parent dir.
+                const parent = cur.includes('/') ? cur.substring(0, cur.lastIndexOf('/')) : '';
+                cur = normalizeVfsPath(`${parent}/${target}`);
+            }
+        }
+        // ELOOP
+        return null;
+    }
+    /** List all currently-registered symlinks (debugging / ls -la support). */
+    list() {
+        const out = [];
+        for (const [k, v] of this.load()) {
+            out.push({ link: k, target: v });
+        }
+        return out;
+    }
+    hasAtOrBelow(path) {
+        const root = this.norm(path);
+        for (const link of this.load().keys()) {
+            if (link === root || link.startsWith(`${root}/`))
+                return true;
+        }
+        return false;
+    }
+}
+/**
+ * Return the session-wide registry for a VFS instance. The registry has an
+ * in-memory cache, so all runtime surfaces that share one SqliteVFS must also
+ * share the registry instance to avoid stale symlink reads.
+ */
+const registries = new WeakMap();
+export function getSymlinkRegistry(vfs) {
+    const existing = registries.get(vfs);
+    if (existing)
+        return existing;
+    const registry = new SymlinkRegistry(vfs);
+    registries.set(vfs, registry);
+    return registry;
+}

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

@@ -0,0 +1,94 @@
+/**
+ * nimbus-workspace.ts — Nimbus as a component someone else can hold.
+ *
+ * A workspace is a durable filesystem plus a shell over it. It owns no
+ * transport, no session, no socket and no Durable Object: the host supplies
+ * SQLite and gets back `.fs` and `.exec`. That is what makes it embeddable in
+ * a Durable Object that is already busy powering something else, and what
+ * makes it runnable in a plain bun process over `bun:sqlite`.
+ *
+ * The composition here is not new. It is the one `session/init.ts` performs,
+ * lifted out of the session so there is one recipe rather than one per caller
+ * — five unit tests were already hand-rolling it, one of them reaching a
+ * private field to do so. The boot itself still belongs to `Sandbox.create`;
+ * this adds only what a durable, credentialed filesystem needs on top and
+ * nothing the sandbox already knows how to do.
+ */
+import type { CommandResult, RunOptions, SandboxFs } from '../substrate/lifo/sandbox/types.js';
+import type { Kernel } from '../substrate/lifo/kernel/index.js';
+import type { Shell } from '../substrate/lifo/shell/Shell.js';
+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';
+export interface NimbusWorkspaceOptions {
+    /** The host's SQLite. In a Durable Object: `ctx.storage.sql`. */
+    readonly sql: SqlDatabase;
+    /**
+     * Carries `transactionSync`. In a Durable Object: `ctx`.
+     *
+     * 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.
+     */
+    readonly transactions?: TransactionHost;
+    /**
+     * Process-id generation. The workspace revokes every append capability at
+     * or below `generation * 1_000_000` before serving anything, so a value
+     * that repeats across restarts hands a dead process live write authority.
+     * Hosts that persist must supply a counter that never repeats.
+     */
+    readonly generation?: number;
+    /** Top-level directories backed by `sql`. Defaults to DEFAULT_MOUNT_POINTS. */
+    readonly mounts?: readonly string[];
+    readonly env?: Record<string, string>;
+    readonly cwd?: string;
+    /** Absent means headless: `.exec` captures output and nothing is drawn. */
+    readonly terminal?: ITerminal;
+}
+/**
+ * A durable filesystem and a shell over it.
+ *
+ * Created with {@link NimbusWorkspace.create} rather than `new` because the
+ * boot it delegates to sources `/etc/profile`, which is genuinely async. A
+ * Durable Object constructor cannot await, so a host constructs the workspace
+ * in its first request rather than in its constructor.
+ */
+export declare class NimbusWorkspace {
+    private readonly sandbox;
+    private readonly sql;
+    /**
+     * 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
+     * writes files for (see CRED_SESSION_USER in os-contracts.ts).
+     */
+    readonly fs: SandboxFs;
+    /** The raw durable filesystem, for hosts that need uid-aware operations. */
+    readonly vfs: SqliteVFS;
+    readonly kernel: Kernel;
+    readonly shell: Shell;
+    private constructor();
+    static create(options: NimbusWorkspaceOptions): Promise<NimbusWorkspace>;
+    exec(command: string, options?: RunOptions): Promise<CommandResult>;
+    /**
+     * Files, directories and bytes this workspace occupies.
+     *
+     * A host sharing its Durable Object needs this because the filesystem's own
+     * `df` reports the workspace's usage against the whole 10 GB limit, and the
+     * host's rows draw on that same limit without appearing here.
+     */
+    stats(): {
+        files: number;
+        dirs: number;
+        usedBytes: number;
+    };
+    /**
+     * Drop this workspace's tables. The host's own rows are untouched.
+     *
+     * Deliberately not `ctx.storage.deleteAll()`, which is what the session's
+     * own destroy uses: a session owns its Durable Object, and a workspace does
+     * not. Calling deleteAll here would erase the data of whatever else the host
+     * keeps in that object.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=nimbus-workspace.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"nimbus-workspace.d.ts","sourceRoot":"","sources":["../../src/workspace/nimbus-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,SAAS,EAAqB,MAAM,sBAAsB,CAAC;AAGpE,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAO/E,MAAM,WAAW,sBAAsB;IACrC,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAaxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAdtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,OAAO;WAiBM,MAAM,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC;IAyB9E,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAInE;;;;;;OAMG;IACH,KAAK,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE;IAK3D;;;;;;;OAOG;IACH,OAAO,IAAI,IAAI;CAKhB"}

package/dist/workspace/nimbus-workspace.js

@@ -0,0 +1,167 @@
+/**
+ * nimbus-workspace.ts — Nimbus as a component someone else can hold.
+ *
+ * A workspace is a durable filesystem plus a shell over it. It owns no
+ * transport, no session, no socket and no Durable Object: the host supplies
+ * SQLite and gets back `.fs` and `.exec`. That is what makes it embeddable in
+ * a Durable Object that is already busy powering something else, and what
+ * makes it runnable in a plain bun process over `bun:sqlite`.
+ *
+ * The composition here is not new. It is the one `session/init.ts` performs,
+ * lifted out of the session so there is one recipe rather than one per caller
+ * — five unit tests were already hand-rolling it, one of them reaching a
+ * private field to do so. The boot itself still belongs to `Sandbox.create`;
+ * this adds only what a durable, credentialed filesystem needs on top and
+ * nothing the sandbox already knows how to do.
+ */
+import { Sandbox } from '../substrate/lifo/sandbox/Sandbox.js';
+import { SandboxFsImpl } from '../substrate/lifo/sandbox/SandboxFs.js';
+import { SqliteVFS, SqliteVFSProvider } from '../vfs/sqlite-vfs.js';
+import { DEFAULT_MOUNT_POINTS, DEFAULT_PATH } from '../constants.js';
+import { CRED_KERNEL, CRED_SESSION_USER } from '../runtime/os-contracts.js';
+import { registerUnixCommands } from '../shell/unix-commands.js';
+import { installPathExecResolver } from '../shell/exec-dispatch.js';
+/** Pids are `generation * PID_GEN_STRIDE + seq`; mirrors process-table.ts. */
+const PID_GEN_STRIDE = 1_000_000;
+/**
+ * A durable filesystem and a shell over it.
+ *
+ * Created with {@link NimbusWorkspace.create} rather than `new` because the
+ * boot it delegates to sources `/etc/profile`, which is genuinely async. A
+ * Durable Object constructor cannot await, so a host constructs the workspace
+ * in its first request rather than in its constructor.
+ */
+export class NimbusWorkspace {
+    sandbox;
+    sql;
+    /**
+     * 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
+     * writes files for (see CRED_SESSION_USER in os-contracts.ts).
+     */
+    fs;
+    /** The raw durable filesystem, for hosts that need uid-aware operations. */
+    vfs;
+    kernel;
+    shell;
+    constructor(sandbox, vfs, sql) {
+        this.sandbox = sandbox;
+        this.sql = sql;
+        this.vfs = vfs;
+        this.kernel = sandbox.kernel;
+        this.shell = sandbox.shell;
+        // NOT `sandbox.fs`, which wraps the raw kernel VFS. The mount is
+        // kernel-credentialed because the shell re-credentials per command; a host
+        // calling `.fs` has no process behind it and must not inherit that.
+        this.fs = new SandboxFsImpl(sandbox.kernel.vfs.as(CRED_SESSION_USER), () => sandbox.shell.getCwd());
+    }
+    static async create(options) {
+        const vfs = new SqliteVFS(options.sql, options.transactions);
+        vfs.revokeAppendWritersThrough((options.generation ?? 1) * PID_GEN_STRIDE);
+        const mounts = options.mounts ?? DEFAULT_MOUNT_POINTS;
+        seedBaseFilesystem(vfs, mounts);
+        const sandbox = await Sandbox.create({
+            env: options.env,
+            cwd: options.cwd,
+            terminal: options.terminal,
+            providerMounts: mounts.map((mount) => ({
+                virtualPath: '/' + mount,
+                provider: new SqliteVFSProvider(vfs, mount),
+            })),
+        });
+        // The durable coreutils replace ~25 lifo builtins. They are the ones that
+        // carry credentials and read this filesystem's uid/gid, so they must win.
+        registerUnixCommands(sandbox.commands.registry, vfs);
+        installPathExecResolver(sandbox.commands.registry, vfs.as(CRED_SESSION_USER), () => sandbox.shell.getCwd());
+        return new NimbusWorkspace(sandbox, vfs, options.sql);
+    }
+    exec(command, options) {
+        return this.sandbox.commands.run(command, options);
+    }
+    /**
+     * Files, directories and bytes this workspace occupies.
+     *
+     * A host sharing its Durable Object needs this because the filesystem's own
+     * `df` reports the workspace's usage against the whole 10 GB limit, and the
+     * host's rows draw on that same limit without appearing here.
+     */
+    stats() {
+        const s = this.vfs.getStats();
+        return { files: s.files, dirs: s.directories, usedBytes: s.usedBytes };
+    }
+    /**
+     * Drop this workspace's tables. The host's own rows are untouched.
+     *
+     * Deliberately not `ctx.storage.deleteAll()`, which is what the session's
+     * own destroy uses: a session owns its Durable Object, and a workspace does
+     * not. Calling deleteAll here would erase the data of whatever else the host
+     * keeps in that object.
+     */
+    destroy() {
+        for (const table of WORKSPACE_TABLES) {
+            this.sql.exec(`DROP TABLE IF EXISTS ${table}`);
+        }
+    }
+}
+/**
+ * Every table the filesystem creates.
+ *
+ * Listed rather than discovered because the namespace is the contract an
+ * embedder is owed: these names, and nothing else in their database, belong
+ * to the workspace. `inodes`, `file_chunks` and `content_lifecycle` are the
+ * three that carry no `vfs_` prefix and so are the ones most likely to
+ * collide with a host's own schema.
+ */
+const WORKSPACE_TABLES = [
+    'inodes',
+    'file_chunks',
+    'content_lifecycle',
+    'vfs_schema_migrations',
+    'vfs_append_receipts',
+    'vfs_append_writer_state',
+    'vfs_append_module_state',
+    'vfs_append_pid_revocations',
+    'vfs_append_acked_gaps',
+];
+/**
+ * The directories and account files the shell cannot start without.
+ *
+ * Idempotent by construction: every write is guarded by an existence check, so
+ * a workspace reopened over a populated database keeps whatever the user did
+ * to these files. `/etc/passwd` and `/etc/group` are load-bearing rather than
+ * decorative — `id`, `chown` and `su` resolve names through them.
+ */
+function seedBaseFilesystem(vfs, mounts) {
+    const fs = vfs.as(CRED_SESSION_USER);
+    const rootFs = vfs.as(CRED_KERNEL);
+    // Created AS the session user, so the user owns their own tree. Seeding
+    // these as the kernel is what makes a workspace where `.fs` cannot write.
+    for (const mount of mounts) {
+        if (mount !== 'etc' && !fs.exists(mount))
+            fs.mkdir(mount, { recursive: true });
+    }
+    for (const dir of ['home/user', 'usr/bin', 'usr/local/bin', 'var/log', 'tmp']) {
+        if (!fs.exists(dir))
+            fs.mkdir(dir, { recursive: true });
+    }
+    if (!rootFs.exists('etc'))
+        rootFs.mkdir('etc', { mode: 0o755 });
+    // Root-owned 0644, and re-asserted rather than only created: these decide
+    // what `id`, `chown` and `su` believe, so a user-writable /etc/passwd would
+    // be an authority bug rather than an untidy file.
+    const accountFile = (path, content) => {
+        if (!rootFs.exists(path))
+            rootFs.writeFile(path, content, { mode: 0o644 });
+        const stat = rootFs.stat(path);
+        if (stat.uid !== 0 || stat.gid !== 0)
+            rootFs.chown(path, 0, 0);
+        if ((stat.mode & 0o7777) !== 0o644)
+            rootFs.chmod(path, 0o644);
+    };
+    accountFile('etc/passwd', 'root:x:0:0:root:/root:/bin/sh\nuser:x:1000:1000:Nimbus User:/home/user:/bin/sh\n');
+    accountFile('etc/group', 'root:x:0:\nuser:x:1000:user\n');
+    if (!rootFs.exists('etc/profile')) {
+        rootFs.writeFile('etc/profile', `export PATH=${DEFAULT_PATH}\nexport EDITOR=nano\n`);
+        rootFs.chown('etc/profile', CRED_SESSION_USER.uid, CRED_SESSION_USER.gid);
+    }
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@nimbus-sh/core",
+  "version": "0.1.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",
+    "sandbox",
+    "sqlite",
+    "webassembly",
+    "wasi"
+  ],
+  "homepage": "https://github.com/AshishKumar4/Nimbus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AshishKumar4/Nimbus.git",
+    "directory": "packages/core"
+  },
+  "bugs": "https://github.com/AshishKumar4/Nimbus/issues",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "workspace": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./workspace": {
+      "workspace": "./src/workspace/nimbus-workspace.ts",
+      "bun": "./src/workspace/nimbus-workspace.ts",
+      "types": "./dist/workspace/nimbus-workspace.d.ts",
+      "import": "./dist/workspace/nimbus-workspace.js"
+    },
+    "./*.js": {
+      "workspace": "./src/*.ts",
+      "bun": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json --noCheck --noEmit false --declaration true --declarationMap true --outDir dist --rootDir src",
+    "prepack": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "acorn": "^8.15.0",
+    "acorn-walk": "^8.3.5",
+    "esbuild-wasm": "0.24.2",
+    "magic-string": "^0.30.21",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250327.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/_shared/ai-egress.ts

@@ -0,0 +1,91 @@
+/**
+ * _shared/ai-egress.ts — how the OS recognises a request as the session's own
+ * inference, wherever in the sandbox it was made.
+ *
+ * The problem this solves
+ * ──────────────────────
+ * Nimbus serves an OpenAI-compatible endpoint on session loopback
+ * (session/ai.ts) and advertises it as OPENAI_BASE_URL. Tools that follow that
+ * convention find it with no configuration. Plenty of tools do not: they hold a
+ * baked-in vendor base URL and only read the *key* from the environment, so the
+ * gateway is invisible to them and the seeded key is worse than useless — it
+ * tells them a provider is configured when the endpoint they will call is not
+ * reachable.
+ *
+ * Which vendor the OS names therefore matters as much as the mediation itself.
+ * A tool that reads a vendor key also holds that vendor's model catalogue, and
+ * this session runs Cloudflare Workers AI: every model it can serve is a
+ * `@cf/…` id. So the key is seeded as CLOUDFLARE_API_KEY, the interface for the
+ * account the session actually has. The tool then picks a model that exists
+ * here and addresses Cloudflare's host, and mediation makes that request land
+ * on the session's own gateway. Naming a vendor whose catalogue the session
+ * cannot serve would deliver the request and then fail on the model id, which
+ * is not a working capability.
+ *
+ * The mediation
+ * ─────────────
+ * The seeded key is a session capability token, and any request leaving the
+ * sandbox that presents it is inference this session owns. Those requests are
+ * served by the session's own gateway rather than sent to the network; the
+ * supervisor substitutes the real Cloudflare credential at the boundary, so the
+ * token is all the sandbox ever holds. The tool is not configured, adapted or
+ * special-cased anywhere — it makes the request it always makes, and the OS
+ * answers it. Same shape as a transparent proxy or /etc/resolv.conf.
+ *
+ * Why match on the credential and not on the destination
+ * ─────────────────────────────────────────────────────
+ * A list of AI vendor hostnames would need maintaining forever and would still
+ * hijack traffic that is not ours — a user's own OpenAI key, sent to OpenAI,
+ * would be captured by a host match. Matching the token instead makes the
+ * fallback correct by construction: a request carrying anything other than this
+ * session's token is not ours, is not touched, and reaches the real provider.
+ *
+ * The mediators live where egress happens — the facet's patched global fetch
+ * (runtime/node-shims.ts) and the shell's curl (substrate/lifo/commands/net) —
+ * and both decide with `requestCarriesSessionAiToken` over these constants, so
+ * the policy has one definition.
+ */
+
+/**
+ * Env var holding the session's AI capability token.
+ *
+ * Carried under its own name as well as CLOUDFLARE_API_KEY because
+ * CLOUDFLARE_API_KEY is the user's to overwrite: someone who exports a real
+ * Cloudflare token must still reach their own account. Mediation compares
+ * against THIS variable, never against whatever the vendor variable holds.
+ */
+export const NIMBUS_AI_TOKEN_ENV = 'NIMBUS_AI_TOKEN';
+
+/**
+ * Headers an API credential is carried in, lowercased: `Authorization: Bearer`
+ * for OpenAI-shaped clients, `x-api-key` for Anthropic-shaped ones.
+ */
+export const NIMBUS_AI_CREDENTIAL_HEADERS = ['authorization', 'x-api-key'] as const;
+
+/**
+ * Mint a session's token. Shaped like an OpenAI secret key because tools
+ * validate that shape before they will even attempt a request, and unguessable
+ * so that a string which merely *mentions* Nimbus can never be mistaken for it.
+ */
+export function mintSessionAiToken(): string {
+  return `sk-nimbus-${crypto.randomUUID().replace(/-/g, '')}`;
+}
+
+/** The credential a request presents, with any `Bearer ` prefix removed. */
+function presentedCredential(value: string): string {
+  const trimmed = value.trim();
+  return /^bearer\s+/i.test(trimmed) ? trimmed.replace(/^bearer\s+/i, '') : trimmed;
+}
+
+/**
+ * True when `headers` present `token`. False for an empty token, so a session
+ * that never seeded one mediates nothing.
+ */
+export function requestCarriesSessionAiToken(headers: Headers, token: string): boolean {
+  if (!token) return false;
+  for (const name of NIMBUS_AI_CREDENTIAL_HEADERS) {
+    const raw = headers.get(name);
+    if (raw && presentedCredential(raw) === token) return true;
+  }
+  return false;
+}