@nimbus-sh/worker 0.1.0

package/dist/session/programmatic.d.ts

@@ -0,0 +1,105 @@
+/**
+ * session/programmatic.ts - public sandbox RPC helpers.
+ *
+ * These helpers are called by NimbusSession one-line delegators so the
+ * Durable Object exposes a typed, programmatic sandbox surface without
+ * duplicating the interactive terminal boot path.
+ */
+type Host = any;
+export interface ProgrammaticReadyOptions {
+    preinstall?: string[];
+}
+export interface ProgrammaticExecOptions extends ProgrammaticReadyOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    stdin?: string;
+}
+export interface ProgrammaticExecResult {
+    command: string;
+    exitCode: number;
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    duration: number;
+    timestamp: number;
+}
+export interface ProgrammaticStartResult extends ProgrammaticExecResult {
+    pid: number | null;
+    process: SerializedProcess | null;
+    ports: SerializedPort[];
+}
+export interface SerializedProcess {
+    pid: number;
+    command: string;
+    argv: string[];
+    cwd: string;
+    state: string;
+    exitCode: number | null;
+    startTime: number;
+    endTime: number | null;
+    longRunning: boolean;
+}
+export interface SerializedPort {
+    port: number;
+    pid: number;
+    registeredAt: number;
+}
+export declare function ensureProgrammaticReady(self: Host, options?: ProgrammaticReadyOptions): Promise<{
+    ok: true;
+    preinstalled: string[];
+}>;
+export declare function rpcExec(self: Host, command: string, options?: ProgrammaticExecOptions): Promise<ProgrammaticExecResult>;
+export declare function rpcStartProcess(self: Host, command: string, options?: ProgrammaticExecOptions): Promise<ProgrammaticStartResult>;
+export declare function rpcRunCode(self: Host, code: string, options?: ProgrammaticExecOptions & {
+    language?: 'javascript' | 'typescript' | 'python' | 'ruby' | 'shell';
+    install?: 'never' | 'ifMissing';
+}): Promise<ProgrammaticExecResult>;
+export declare function rpcInstallRuntime(self: Host, spec: string, options?: {
+    force?: boolean;
+}): Promise<import("../runtime/package-manager.js").RuntimeInstallSummary>;
+export declare function rpcEnsureRuntimes(self: Host, specs: string[], options?: {
+    force?: boolean;
+}): Promise<import("../runtime/package-manager.js").RuntimeInstallSummary[]>;
+export declare function rpcListRuntimes(self: Host): Promise<{
+    installed: import("../runtime/package-manager.js").RuntimeSummary[];
+    available: {
+        name: string;
+        defaultVersion: string;
+        versions: Array<{
+            version: string;
+            sizeBytes: number;
+            license: string;
+        }>;
+    }[];
+}>;
+export declare function rpcListProcesses(self: Host): Promise<SerializedProcess[]>;
+export declare function rpcKillProcess(self: Host, pid: number): Promise<{
+    ok: boolean;
+    pid: number;
+}>;
+export declare function rpcProcessLogs(self: Host, pid: number, options?: {
+    lines?: number;
+    bytes?: number;
+}): Promise<{
+    pid: number;
+    chunks: any;
+    text: any;
+    exit: any;
+}>;
+export declare function rpcListPorts(self: Host): Promise<SerializedPort[]>;
+export declare function rpcExposePort(self: Host, port: number): Promise<{
+    port: number;
+    listening: boolean;
+    pid: any;
+    registeredAt: any;
+}>;
+export declare function rpcUnexposePort(self: Host, port: number): Promise<{
+    port: number;
+    ok: any;
+}>;
+export declare function rpcDeleteFile(self: Host, path: string, options?: {
+    recursive?: boolean;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=programmatic.d.ts.map

package/dist/session/programmatic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"programmatic.d.ts","sourceRoot":"","sources":["../../src/session/programmatic.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,KAAK,IAAI,GAAG,GAAG,CAAC;AAEhB,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,uBAAwB,SAAQ,sBAAsB;IACrE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;CACtB;AAkDD,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,IAAI,EACV,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwB/C;AAED,wBAAsB,OAAO,CAC3B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAyDjC;AAqBD,wBAAsB,eAAe,CACnC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,uBAAuB,CAAC,CAgBlC;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,uBAAuB,GAAG;IACjC,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;IACrE,OAAO,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;CAC5B,GACL,OAAO,CAAC,sBAAsB,CAAC,CAcjC;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,0EAIlC;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EAAE,EACf,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,4EAQlC;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI;;;;;;;;;;;GAM/C;AAED,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAG/E;AAED,wBAAsB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CA0BnG;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO;;;;;GAUjD;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAGxE;AAED,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM;;;;;GAU3D;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM;;;GAI7D;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GACpC,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/dist/session/programmatic.js

@@ -0,0 +1,326 @@
+/**
+ * session/programmatic.ts - public sandbox RPC helpers.
+ *
+ * These helpers are called by NimbusSession one-line delegators so the
+ * Durable Object exposes a typed, programmatic sandbox surface without
+ * duplicating the interactive terminal boot path.
+ */
+import { ensureRuntimesProgrammatic, installRuntimeProgrammatic, listAvailableRuntimes, listInstalledRuntimes, } from '../runtime/package-manager.js';
+function makeHeadlessWebSocket() {
+    const listeners = new Map();
+    const ws = {
+        readyState: 1,
+        send(_data) { },
+        close() {
+            ws.readyState = 3;
+            for (const cb of listeners.get('close') ?? []) {
+                try {
+                    cb();
+                }
+                catch { }
+            }
+        },
+        accept() { },
+        addEventListener(type, cb) {
+            const set = listeners.get(type) ?? new Set();
+            set.add(cb);
+            listeners.set(type, set);
+        },
+        removeEventListener(type, cb) {
+            listeners.get(type)?.delete(cb);
+        },
+        serializeAttachment(_value) { },
+        deserializeAttachment() { return { kind: 'programmatic' }; },
+    };
+    return ws;
+}
+function getHome(self) {
+    try {
+        const envHome = self.shell?.env?.HOME;
+        if (envHome)
+            return String(envHome);
+    }
+    catch { }
+    try {
+        const shellEnv = self.shell?.getEnv?.();
+        if (shellEnv?.HOME)
+            return String(shellEnv.HOME);
+    }
+    catch { }
+    return '/home/user';
+}
+function runtimeDeps(self) {
+    self.ensureSqliteFs();
+    return {
+        env: self.env,
+        vfs: self.sqliteFs,
+        registry: self._cpRegistry,
+        getHome: () => getHome(self),
+    };
+}
+export async function ensureProgrammaticReady(self, options = {}) {
+    if (!self.shell) {
+        self.initSession(makeHeadlessWebSocket());
+        // Programmatic boot owns no real terminal socket. Mark the session
+        // drained so a later browser /ws can warm-join instead of 409ing.
+        self._b4Phase = 'drained';
+    }
+    else {
+        self.ensureSqliteFs();
+        self.ensureFacetManager();
+    }
+    const preinstall = Array.from(new Set(options.preinstall ?? []))
+        .map((s) => String(s).trim())
+        .filter(Boolean);
+    if (preinstall.length > 0) {
+        const results = await ensureRuntimesProgrammatic(runtimeDeps(self), preinstall);
+        const failed = results.filter((r) => r.exitCode !== 0);
+        if (failed.length > 0) {
+            const details = failed.map((r) => `${r.spec}: ${r.stderr || r.stdout}`).join('\n');
+            throw new Error(`runtime preinstall failed:\n${details}`);
+        }
+    }
+    return { ok: true, preinstalled: preinstall };
+}
+export async function rpcExec(self, command, options = {}) {
+    await ensureProgrammaticReady(self, options);
+    const shell = self.shell;
+    if (!shell)
+        throw new Error('Nimbus shell did not initialize');
+    const stdout = [];
+    const stderr = [];
+    const started = Date.now();
+    const beforePids = new Set(self.processTable.getAll().map((p) => p.pid));
+    const controller = new AbortController();
+    let timeout = null;
+    let timedOut = false;
+    const run = shell.execute(String(command), {
+        cwd: options.cwd ?? shell.getCwd?.() ?? '/home/user',
+        env: { ...(shell.getEnv?.() ?? {}), ...(options.env ?? {}) },
+        onStdout: (d) => stdout.push(String(d)),
+        onStderr: (d) => stderr.push(String(d)),
+        signal: controller.signal,
+        stdin: options.stdin,
+    });
+    const result = await (options.timeoutMs && options.timeoutMs > 0
+        ? Promise.race([
+            run,
+            new Promise((resolve) => {
+                timeout = setTimeout(() => {
+                    timedOut = true;
+                    try {
+                        controller.abort();
+                    }
+                    catch { }
+                    resolve({ exitCode: 124 });
+                }, options.timeoutMs);
+            }),
+        ])
+        : run);
+    if (timeout)
+        clearTimeout(timeout);
+    const exitCode = Number(result?.exitCode ?? (timedOut ? 124 : 0));
+    if (timedOut) {
+        stderr.push(`command timed out after ${options.timeoutMs}ms\n`);
+    }
+    const logged = collectNewProcessOutput(self, beforePids);
+    if (stdout.length === 0 && logged.stdout)
+        stdout.push(logged.stdout);
+    if (stderr.length === 0 && logged.stderr)
+        stderr.push(logged.stderr);
+    return {
+        command: String(command),
+        exitCode,
+        success: exitCode === 0,
+        stdout: stdout.join(''),
+        stderr: stderr.join(''),
+        duration: Date.now() - started,
+        timestamp: Date.now(),
+    };
+}
+function collectNewProcessOutput(self, beforePids) {
+    const created = self.processTable.getAll()
+        .filter((p) => !beforePids.has(p.pid))
+        .sort((a, b) => a.startTime - b.startTime);
+    const stdout = [];
+    const stderr = [];
+    for (const entry of created) {
+        const chunks = self.processLogs.all(Number(entry.pid));
+        for (const chunk of chunks) {
+            if (chunk.stream === 'stderr')
+                stderr.push(String(chunk.data));
+            else
+                stdout.push(String(chunk.data));
+        }
+    }
+    return { stdout: stdout.join(''), stderr: stderr.join('') };
+}
+export async function rpcStartProcess(self, command, options = {}) {
+    await ensureProgrammaticReady(self, options);
+    const before = new Set(self.processTable.getAll().map((p) => p.pid));
+    const result = await rpcExec(self, command, options);
+    const created = self.processTable.getAll()
+        .filter((p) => !before.has(p.pid))
+        .sort((a, b) => b.startTime - a.startTime);
+    const running = created.find((p) => p.state === 'running') ?? null;
+    const pid = running?.pid ?? created[0]?.pid ?? null;
+    const process = pid != null ? serializeProcess(self.processTable.get(pid)) : null;
+    const ports = pid != null
+        ? self.portRegistry.getAll().filter((p) => p.pid === pid).map(serializePort)
+        : [];
+    return { ...result, pid, process, ports };
+}
+export async function rpcRunCode(self, code, options = {}) {
+    const language = options.language ?? 'javascript';
+    if (language === 'python' && options.install === 'ifMissing') {
+        await ensureProgrammaticReady(self, { ...options, preinstall: ['python'] });
+    }
+    else if (language === 'ruby' && options.install === 'ifMissing') {
+        await ensureProgrammaticReady(self, { ...options, preinstall: ['ruby'] });
+    }
+    else {
+        await ensureProgrammaticReady(self, options);
+    }
+    if (language === 'shell')
+        return rpcExec(self, code, options);
+    if (language === 'python')
+        return rpcExec(self, `python -c ${shellQuote(code)}`, options);
+    if (language === 'ruby')
+        return rpcExec(self, `ruby -e ${shellQuote(code)}`, options);
+    return rpcExec(self, `node -e ${shellQuote(code)}`, options);
+}
+export async function rpcInstallRuntime(self, spec, options = {}) {
+    await ensureProgrammaticReady(self);
+    return installRuntimeProgrammatic(runtimeDeps(self), String(spec), options);
+}
+export async function rpcEnsureRuntimes(self, specs, options = {}) {
+    await ensureProgrammaticReady(self);
+    return ensureRuntimesProgrammatic(runtimeDeps(self), specs.map((s) => String(s)), options);
+}
+export async function rpcListRuntimes(self) {
+    await ensureProgrammaticReady(self);
+    return {
+        installed: listInstalledRuntimes(self.sqliteFs, getHome(self)),
+        available: await listAvailableRuntimes(self.env),
+    };
+}
+export async function rpcListProcesses(self) {
+    await ensureProgrammaticReady(self);
+    return self.processTable.getAll().map((p) => serializeProcess(p));
+}
+export async function rpcKillProcess(self, pid) {
+    await ensureProgrammaticReady(self);
+    const n = Number(pid);
+    let ok = false;
+    if (self._viteShimPid === n) {
+        try {
+            if (self.cirrusReal?.isRunning) {
+                self.cirrusReal.stop(self.ctx);
+                self.cirrusReal = null;
+            }
+            if (self.viteDevServer?.isRunning) {
+                self.viteDevServer.stop();
+                self.viteDevServer = null;
+                try {
+                    await self.ctx.storage.delete('vite-config');
+                }
+                catch { }
+            }
+        }
+        catch { }
+        try {
+            self.portRegistry.unregisterByPid(n);
+        }
+        catch { }
+        ok = self.processTable.kill(n);
+        self._viteShimPid = null;
+        self._viteShimPort = null;
+    }
+    else if (self.facetManager) {
+        ok = self.facetManager.kill(n);
+    }
+    else {
+        ok = self.processTable.kill(n);
+    }
+    return { ok, pid: n };
+}
+export async function rpcProcessLogs(self, pid, options = {}) {
+    await ensureProgrammaticReady(self);
+    const chunks = self.processLogs.tail(Number(pid), options.bytes ? { bytes: options.bytes } : { lines: options.lines ?? 200 });
+    return {
+        pid: Number(pid),
+        chunks,
+        text: chunks.map((c) => c.data).join(''),
+        exit: self.processLogs.getExit(Number(pid)),
+    };
+}
+export async function rpcListPorts(self) {
+    await ensureProgrammaticReady(self);
+    return self.portRegistry.getAll().map(serializePort);
+}
+export async function rpcExposePort(self, port) {
+    await ensureProgrammaticReady(self);
+    const n = Number(port);
+    const entry = self.portRegistry.get(n);
+    return {
+        port: n,
+        listening: !!entry,
+        pid: entry?.pid ?? null,
+        registeredAt: entry?.registeredAt ?? null,
+    };
+}
+export async function rpcUnexposePort(self, port) {
+    await ensureProgrammaticReady(self);
+    const n = Number(port);
+    return { port: n, ok: self.portRegistry.unregister(n) };
+}
+export async function rpcDeleteFile(self, path, options = {}) {
+    await ensureProgrammaticReady(self);
+    const p = String(path).replace(/^\/+/, '');
+    if (!self.sqliteFs.exists(p))
+        return;
+    if (self.sqliteFs.isDirectory(p)) {
+        if (!options.recursive) {
+            self.sqliteFs.rmdir(p);
+            return;
+        }
+        rmrf(self.sqliteFs, p);
+        return;
+    }
+    self.sqliteFs.unlink(p);
+}
+function rmrf(vfs, path) {
+    for (const entry of vfs.readdir(path)) {
+        const child = `${path}/${entry.name}`;
+        if (entry.type === 'directory')
+            rmrf(vfs, child);
+        else
+            vfs.unlink(child);
+    }
+    vfs.rmdir(path);
+}
+function serializeProcess(p) {
+    if (!p)
+        return null;
+    return {
+        pid: p.pid,
+        command: p.command,
+        argv: p.argv,
+        cwd: p.cwd,
+        state: p.state,
+        exitCode: p.exitCode,
+        startTime: p.startTime,
+        endTime: p.endTime,
+        longRunning: p.longRunning === true,
+    };
+}
+function serializePort(p) {
+    return {
+        port: Number(p.port),
+        pid: Number(p.pid),
+        registeredAt: Number(p.registeredAt),
+    };
+}
+function shellQuote(s) {
+    return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}

package/dist/session/replica-routes.d.ts

@@ -0,0 +1,68 @@
+/**
+ * session/replica-routes.ts — W12 DO read-replica state helpers.
+ *
+ * Two free functions paired with class delegators on NimbusSession:
+ *
+ *   wireReplicasOnConstruct(self) — runs `tryEnableReplicas(ctx)` from
+ *     the DO ctor; graceful-degrades to `{ state: 'error', error }` on
+ *     throw. Result is stored on `self._w12EnableResult`.
+ *
+ *   getReplicaState(self) — composes `_w12EnableResult` (constructor-time
+ *     enable result) + live `inspectReplicaState(ctx)` (per-fetch isReplica
+ *     + bookmark) + `replicasSuspended()` (write-burst guard). Surfaced
+ *     via `/api/_diag/memory.replica` so operators (and the CT1 drift
+ *     detector) can confirm replicas landed and observe replication lag.
+ *
+ * No module-level state. The W12 enable-result lives on the class
+ * (`self._w12EnableResult`); this file is pure logic.
+ */
+import { type TryEnableReplicasResult as W12EnableResult } from '../replica/routing.js';
+export type { W12EnableResult };
+/**
+ * Minimal shape of `NimbusSession` that the replica helpers need to
+ * read/write. Per plan §IX.1 (refined option b'), the class fields used
+ * here drop `private`, so this interface declares them as public.
+ *
+ * NOTE on `ctx`: the parent `CloudflareDurableObject` class declares
+ * `ctx` as `protected`, which is nominal-typed in TS. The interface
+ * cannot declare `ctx` (TS-2412). Helpers that need ctx must extract
+ * it from the call site (passed as a separate arg). We use `any` here
+ * for the field set, but `ctx` is never accessed via this interface —
+ * the helpers below accept ctx as a parameter when needed.
+ */
+export interface ReplicaHost {
+    _w12EnableResult: W12EnableResult | null;
+}
+/**
+ * Run at DO ctor time. Calls `tryEnableReplicas(ctx)` and returns the
+ * result. Pre-GA runtimes lacking the SPEC API yield
+ * `{ state: 'unsupported' }` and the DO behaves exactly as pre-W12. A
+ * throw (which `tryEnableReplicas` itself catches but we belt-and-braces)
+ * yields `{ state: 'error', error }`.
+ *
+ * `ctx` is the DurableObjectState (typed `any` because the class member
+ * is `protected` and can't be put on a public interface).
+ */
+export declare function wireReplicasOnConstruct(ctx: any): W12EnableResult;
+/**
+ * Compose the full operator-facing replica state for
+ * `/api/_diag/memory.replica`.
+ *
+ * - `state` / `error` come from the ctor-time enable result on `host`.
+ * - `isReplica` / `bookmark` come from per-fetch `inspectReplicaState(ctx)`.
+ * - `suspended` reflects the global write-burst guard
+ *   (npm install / git clone in flight) per CF research §G.4.
+ *
+ * Never throws. Callers can rely on the shape always being filled.
+ *
+ * Two args (host + ctx) because `ctx` is `protected` on the parent class
+ * and can't be reached through a public interface; see ReplicaHost docs.
+ */
+export declare function getReplicaState(host: ReplicaHost, ctx: any): {
+    state: string;
+    error: string | null;
+    isReplica: boolean;
+    bookmark: string | null;
+    suspended: boolean;
+};
+//# sourceMappingURL=replica-routes.d.ts.map

package/dist/session/replica-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replica-routes.d.ts","sourceRoot":"","sources":["../../src/session/replica-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,uBAAuB,IAAI,eAAe,EAChD,MAAM,uBAAuB,CAAC;AAG/B,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,gBAAgB,EAAE,eAAe,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,GAAG,GAAG,eAAe,CAQjE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,GAAG,EAAE,GAAG,GAAG;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,OAAO,CAAC;CACpB,CAkBA"}

package/dist/session/replica-routes.js

@@ -0,0 +1,77 @@
+/**
+ * session/replica-routes.ts — W12 DO read-replica state helpers.
+ *
+ * Two free functions paired with class delegators on NimbusSession:
+ *
+ *   wireReplicasOnConstruct(self) — runs `tryEnableReplicas(ctx)` from
+ *     the DO ctor; graceful-degrades to `{ state: 'error', error }` on
+ *     throw. Result is stored on `self._w12EnableResult`.
+ *
+ *   getReplicaState(self) — composes `_w12EnableResult` (constructor-time
+ *     enable result) + live `inspectReplicaState(ctx)` (per-fetch isReplica
+ *     + bookmark) + `replicasSuspended()` (write-burst guard). Surfaced
+ *     via `/api/_diag/memory.replica` so operators (and the CT1 drift
+ *     detector) can confirm replicas landed and observe replication lag.
+ *
+ * No module-level state. The W12 enable-result lives on the class
+ * (`self._w12EnableResult`); this file is pure logic.
+ */
+import { tryEnableReplicas as _w12TryEnableReplicas, inspectReplicaState as _w12InspectReplicaState, } from '../replica/routing.js';
+import { replicasSuspended as _w12ReplicasSuspended } from '../replica/suspension.js';
+/**
+ * Run at DO ctor time. Calls `tryEnableReplicas(ctx)` and returns the
+ * result. Pre-GA runtimes lacking the SPEC API yield
+ * `{ state: 'unsupported' }` and the DO behaves exactly as pre-W12. A
+ * throw (which `tryEnableReplicas` itself catches but we belt-and-braces)
+ * yields `{ state: 'error', error }`.
+ *
+ * `ctx` is the DurableObjectState (typed `any` because the class member
+ * is `protected` and can't be put on a public interface).
+ */
+export function wireReplicasOnConstruct(ctx) {
+    try {
+        return _w12TryEnableReplicas(ctx);
+    }
+    catch (e) {
+        // tryEnableReplicas itself never throws (it catches), but keep this
+        // belt-and-braces so a future change doesn't break the constructor.
+        return { state: 'error', error: e?.message ?? String(e) };
+    }
+}
+/**
+ * Compose the full operator-facing replica state for
+ * `/api/_diag/memory.replica`.
+ *
+ * - `state` / `error` come from the ctor-time enable result on `host`.
+ * - `isReplica` / `bookmark` come from per-fetch `inspectReplicaState(ctx)`.
+ * - `suspended` reflects the global write-burst guard
+ *   (npm install / git clone in flight) per CF research §G.4.
+ *
+ * Never throws. Callers can rely on the shape always being filled.
+ *
+ * Two args (host + ctx) because `ctx` is `protected` on the parent class
+ * and can't be reached through a public interface; see ReplicaHost docs.
+ */
+export function getReplicaState(host, ctx) {
+    const enable = host._w12EnableResult ?? { state: 'unknown', error: null };
+    let isReplica = false;
+    let bookmark = null;
+    try {
+        const inspect = _w12InspectReplicaState(ctx);
+        isReplica = inspect.isReplica;
+        bookmark = inspect.bookmark;
+    }
+    catch { /* never throw from a diag helper */ }
+    let suspended = false;
+    try {
+        suspended = _w12ReplicasSuspended();
+    }
+    catch { }
+    return {
+        state: enable.state,
+        error: enable.error,
+        isReplica,
+        bookmark,
+        suspended,
+    };
+}

package/dist/session/routes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * session/routes.ts — HTTP/WS fetch routing for the supervisor DO.
+ *
+ * One handleRequest function for everything the DO speaks:
+ *   /ws upgrade        → cold-init / warm-rejoin (B'.5) / 409
+ *   /preview/*         → cirrus-real or vite-dev-server forward
+ *   /port/:n/*         → user http-server proxy via port-registry
+ *   /worker/*          → nimbus-wrangler dev forward
+ *   /api/_diag/*       → forensic surfaces (memory, session, cirrus)
+ *   /api/_test/*       → NIMBUS_DEBUG-gated probe endpoints
+ *   /api/* (other)     → small JSON endpoints (write-file, mkdir, ...)
+ *
+ * The dispatcher is one big if/else by design — pattern-matching
+ * URL paths cleanly is easier to read than a Map-based router for
+ * this many one-off shapes, and grep-ability matters when debugging.
+ *
+ * Surfaces:
+ *   - handleFetch(self, request) — top-level dispatcher; was _handleFetch.
+ *
+ * The class retains `fetch` (DO contract) + `_handleFetch` as delegators
+ * per plan §IX.4 R1.
+ *
+ * Per DEFECT-D1: route handlers read self.ctx + self.env extensively
+ * (~30 sites). RoutesHost = any pragmatic deviation, like InitHost in S6.
+ */
+type RoutesHost = any;
+export declare function handleFetch(self: RoutesHost, request: Request): Promise<Response>;
+export {};
+//# sourceMappingURL=routes.d.ts.map

package/dist/session/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/session/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA+BH,KAAK,UAAU,GAAG,GAAG,CAAC;AAEtB,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAi/BvF"}