@nimbus-sh/worker 0.1.0

package/dist/runtime/package-manager.d.ts

@@ -0,0 +1,118 @@
+/**
+ * package-manager.ts — `nimbus install <runtime>` shell verb.
+ *
+ * Implements True-OS Wave-3's package-manager surface per
+ * /workspace/.seal-internal/2026-05-10-true-os/plan.md §2.
+ *
+ * Subcommands (all under `nimbus install`):
+ *
+ *   nimbus install <name>                 install latest of <name>
+ *   nimbus install <name>@<version>       install specific version
+ *   nimbus install --list                 show installed runtimes
+ *   nimbus install --available            show catalog of installables
+ *   nimbus install --reinstall <name>     force refetch
+ *   nimbus uninstall <name>               remove installed runtime
+ *
+ * Per-user-VFS layout (decision D-install-1 (a) baked):
+ *
+ *   ~/.nimbus/runtimes/<name>/<version>/
+ *     manifest.json
+ *     bin/<entry>
+ *     share/<name>/...
+ *     LICENSE
+ *
+ * Survives DO eviction (SqliteFS-backed). Boot-time rehydration reads
+ * every `~/.nimbus/runtimes/STAR/STAR/manifest.json` and re-registers
+ * each `entrypoints[].binName` as a shell command pointing at the
+ * named runner factory.
+ *
+ * Anti-reqs (inherited from plan §8.1):
+ *   - NO setTimeout / NO retry / NO defensive-catch in dispatch path.
+ *   - Errors throw + bubble up to the user as a single diagnostic line.
+ */
+import { type RuntimeCatalogEnv, type RuntimeManifest } from './runtime-catalog.js';
+import type { SqliteVFS } from '../vfs/sqlite-vfs.js';
+/** Minimal shell-registry shape we depend on. */
+export interface MinShellRegistry {
+    register(name: string, handler: (ctx: any) => Promise<number>): void;
+    unregister?(name: string): void;
+    resolve?(name: string): any;
+}
+/** Runner-factory contract. Each registered runner produces a shell-
+ *  command handler given the manifest + the installed root dir. The
+ *  package manager invokes the factory at install-time + at boot-time
+ *  rehydration. */
+export type RunnerFactory = (manifest: RuntimeManifest, installRoot: string, binName: string, binKind: string | undefined) => (ctx: any) => Promise<number>;
+export declare function registerRunnerFactory(key: string, factory: RunnerFactory): void;
+export declare function getRegisteredRunners(): string[];
+export interface RuntimeInstallSummary {
+    spec: string;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export interface RuntimeSummary {
+    name: string;
+    version: string;
+    root: string;
+    bins: string[];
+    sizeBytes: number;
+    license: string;
+}
+/** Compute the per-user install root for (name, version). Uses
+ *  `process.env.HOME` if present; falls back to `/home/user`. */
+export declare function installRoot(homeDir: string, name: string, version: string): string;
+/** Read all installed manifests off SqliteFS. Used by both `--list`
+ *  and boot-time rehydration. */
+export declare function listInstalledManifests(vfs: SqliteVFS, homeDir: string): Array<{
+    root: string;
+    manifest: RuntimeManifest;
+}>;
+/**
+ * Re-register every installed runtime's entrypoints in the shell
+ * registry. Call once at session-init time after all runner factories
+ * are registered (init.ts:registerRunnerFactory blocks).
+ */
+export declare function rehydrateInstalledRuntimes(vfs: SqliteVFS, registry: MinShellRegistry, homeDir: string): {
+    count: number;
+    bins: string[];
+};
+export declare function listInstalledRuntimes(vfs: SqliteVFS, homeDir: string): RuntimeSummary[];
+export declare function listAvailableRuntimes(env: RuntimeCatalogEnv): Promise<Array<{
+    name: string;
+    defaultVersion: string;
+    versions: Array<{
+        version: string;
+        sizeBytes: number;
+        license: string;
+    }>;
+}>>;
+export declare function installRuntimeProgrammatic(deps: {
+    env: RuntimeCatalogEnv;
+    vfs: SqliteVFS;
+    registry: MinShellRegistry;
+    getHome(): string;
+}, spec: string, opts?: {
+    force?: boolean;
+}): Promise<RuntimeInstallSummary>;
+export declare function ensureRuntimesProgrammatic(deps: {
+    env: RuntimeCatalogEnv;
+    vfs: SqliteVFS;
+    registry: MinShellRegistry;
+    getHome(): string;
+}, specs: string[], opts?: {
+    force?: boolean;
+}): Promise<RuntimeInstallSummary[]>;
+/**
+ * Build the shell-command handler that implements `nimbus install …`,
+ * `nimbus uninstall …`. Registered under the name `nimbus`.
+ */
+export declare function makeNimbusVerbHandler(deps: {
+    env: RuntimeCatalogEnv;
+    vfs: SqliteVFS;
+    registry: MinShellRegistry;
+    /** Returns `process.env.HOME` for the session. Computed by the
+     *  caller (init.ts) from the shell env. */
+    getHome(): string;
+}): (ctx: any) => Promise<number>;
+//# sourceMappingURL=package-manager.d.ts.map

package/dist/runtime/package-manager.d.ts.map

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

package/dist/runtime/package-manager.js

@@ -0,0 +1,420 @@
+/**
+ * package-manager.ts — `nimbus install <runtime>` shell verb.
+ *
+ * Implements True-OS Wave-3's package-manager surface per
+ * /workspace/.seal-internal/2026-05-10-true-os/plan.md §2.
+ *
+ * Subcommands (all under `nimbus install`):
+ *
+ *   nimbus install <name>                 install latest of <name>
+ *   nimbus install <name>@<version>       install specific version
+ *   nimbus install --list                 show installed runtimes
+ *   nimbus install --available            show catalog of installables
+ *   nimbus install --reinstall <name>     force refetch
+ *   nimbus uninstall <name>               remove installed runtime
+ *
+ * Per-user-VFS layout (decision D-install-1 (a) baked):
+ *
+ *   ~/.nimbus/runtimes/<name>/<version>/
+ *     manifest.json
+ *     bin/<entry>
+ *     share/<name>/...
+ *     LICENSE
+ *
+ * Survives DO eviction (SqliteFS-backed). Boot-time rehydration reads
+ * every `~/.nimbus/runtimes/STAR/STAR/manifest.json` and re-registers
+ * each `entrypoints[].binName` as a shell command pointing at the
+ * named runner factory.
+ *
+ * Anti-reqs (inherited from plan §8.1):
+ *   - NO setTimeout / NO retry / NO defensive-catch in dispatch path.
+ *   - Errors throw + bubble up to the user as a single diagnostic line.
+ */
+import { fetchCatalog, fetchManifest, fetchBlob } from './runtime-catalog.js';
+/** Map of runner-key → factory. Populated by init.ts before install. */
+const runnerFactories = {};
+export function registerRunnerFactory(key, factory) {
+    runnerFactories[key] = factory;
+}
+export function getRegisteredRunners() {
+    return Object.keys(runnerFactories);
+}
+/** Compute the per-user install root for (name, version). Uses
+ *  `process.env.HOME` if present; falls back to `/home/user`. */
+export function installRoot(homeDir, name, version) {
+    // Strip leading slash so SqliteFS sees a relative-looking VFS path,
+    // matching the convention used elsewhere in src/session/init.ts.
+    const home = homeDir.replace(/^\/+/, '').replace(/\/+$/, '');
+    return `${home}/.nimbus/runtimes/${name}/${version}`;
+}
+/** Read all installed manifests off SqliteFS. Used by both `--list`
+ *  and boot-time rehydration. */
+export function listInstalledManifests(vfs, homeDir) {
+    const home = homeDir.replace(/^\/+/, '').replace(/\/+$/, '');
+    const runtimesRoot = `${home}/.nimbus/runtimes`;
+    const out = [];
+    if (!vfs.exists(runtimesRoot))
+        return out;
+    // Each entry under runtimesRoot is a <name>; each entry under that
+    // is a <version>; each <version> dir has a manifest.json.
+    for (const nameEntry of vfs.readdir(runtimesRoot)) {
+        if (nameEntry.type !== 'directory')
+            continue;
+        const nameDir = `${runtimesRoot}/${nameEntry.name}`;
+        for (const verEntry of vfs.readdir(nameDir)) {
+            if (verEntry.type !== 'directory')
+                continue;
+            const verDir = `${nameDir}/${verEntry.name}`;
+            const manifestPath = `${verDir}/manifest.json`;
+            if (!vfs.exists(manifestPath))
+                continue;
+            try {
+                const manifest = JSON.parse(vfs.readFileString(manifestPath));
+                out.push({ root: verDir, manifest });
+            }
+            catch {
+                // Malformed manifest — skip silently. Surfacing via stderr
+                // would require a ctx we don't have at boot-time rehydration.
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Re-register every installed runtime's entrypoints in the shell
+ * registry. Call once at session-init time after all runner factories
+ * are registered (init.ts:registerRunnerFactory blocks).
+ */
+export function rehydrateInstalledRuntimes(vfs, registry, homeDir) {
+    const bins = [];
+    for (const { root, manifest } of listInstalledManifests(vfs, homeDir)) {
+        for (const ep of manifest.entrypoints) {
+            const factory = runnerFactories[ep.runner];
+            if (!factory)
+                continue; // runner not registered yet — skip
+            const handler = factory(manifest, root, ep.binName, ep.kind);
+            registry.register(ep.binName, handler);
+            bins.push(ep.binName);
+        }
+    }
+    return { count: bins.length, bins };
+}
+export function listInstalledRuntimes(vfs, homeDir) {
+    return listInstalledManifests(vfs, homeDir).map(({ root, manifest }) => ({
+        name: manifest.name,
+        version: manifest.version,
+        root,
+        bins: manifest.entrypoints.map((e) => e.binName),
+        sizeBytes: manifest.files.reduce((a, f) => a + f.size, 0),
+        license: manifest.license,
+    }));
+}
+export async function listAvailableRuntimes(env) {
+    const catalog = await fetchCatalog(env);
+    return Object.entries(catalog.runtimes)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, entry]) => ({
+        name,
+        defaultVersion: entry.default,
+        versions: Object.entries(entry.versions)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([version, v]) => ({
+            version,
+            sizeBytes: v.size_bytes,
+            license: v.license,
+        })),
+    }));
+}
+export async function installRuntimeProgrammatic(deps, spec, opts = {}) {
+    const stdout = [];
+    const stderr = [];
+    const ctx = {
+        args: [],
+        env: {},
+        cwd: deps.getHome(),
+        stdout: { write: (s) => stdout.push(String(s)) },
+        stderr: { write: (s) => stderr.push(String(s)) },
+    };
+    const args = opts.force ? ['--reinstall', spec] : [spec];
+    const exitCode = await runInstall(args, ctx, deps);
+    return {
+        spec,
+        exitCode,
+        stdout: stdout.join(''),
+        stderr: stderr.join(''),
+    };
+}
+export async function ensureRuntimesProgrammatic(deps, specs, opts = {}) {
+    const results = [];
+    for (const spec of specs) {
+        results.push(await installRuntimeProgrammatic(deps, spec, opts));
+    }
+    return results;
+}
+/**
+ * Build the shell-command handler that implements `nimbus install …`,
+ * `nimbus uninstall …`. Registered under the name `nimbus`.
+ */
+export function makeNimbusVerbHandler(deps) {
+    const { env, vfs, registry, getHome } = deps;
+    return async function nimbus(ctx) {
+        const argv = ctx.args || [];
+        const verb = argv[0];
+        const rest = argv.slice(1);
+        if (verb === 'install') {
+            return runInstall(rest, ctx, { env, vfs, registry, getHome });
+        }
+        if (verb === 'uninstall') {
+            return runUninstall(rest, ctx, { vfs, registry, getHome });
+        }
+        // Unknown verb.
+        ctx.stderr.write(`nimbus: unknown subcommand '${verb || '(none)'}'\n`);
+        ctx.stderr.write(`usage: nimbus install <name>[@<version>] | nimbus install --list | nimbus install --available | nimbus uninstall <name>\n`);
+        return 2;
+    };
+}
+// ── install ──────────────────────────────────────────────────────────
+async function runInstall(args, ctx, deps) {
+    // Flag parsing.
+    const listOnly = args.includes('--list');
+    const availOnly = args.includes('--available');
+    const force = args.includes('--reinstall') || args.includes('--force');
+    const positional = args.filter((a) => !a.startsWith('--'));
+    if (listOnly)
+        return runList(ctx, deps);
+    if (availOnly)
+        return runAvailable(ctx, deps);
+    if (positional.length === 0) {
+        ctx.stderr.write('nimbus install: missing runtime name\n');
+        ctx.stderr.write('usage: nimbus install <name>[@<version>]\n');
+        return 2;
+    }
+    // Parse `<name>` or `<name>@<version>`.
+    const spec = positional[0];
+    const atIdx = spec.indexOf('@');
+    const name = atIdx >= 0 ? spec.slice(0, atIdx) : spec;
+    const versionOverride = atIdx >= 0 ? spec.slice(atIdx + 1) : null;
+    // Fetch catalog.
+    let catalog;
+    try {
+        catalog = await fetchCatalog(deps.env);
+    }
+    catch (e) {
+        ctx.stderr.write(`nimbus install: ${e?.message || e}\n`);
+        return 1;
+    }
+    const runtimeEntry = catalog.runtimes[name];
+    if (!runtimeEntry) {
+        ctx.stderr.write(`nimbus install: '${name}' is not in catalog\n`);
+        ctx.stderr.write(`nimbus install: try 'nimbus install --available' to see installable runtimes\n`);
+        return 1;
+    }
+    const version = versionOverride || runtimeEntry.default;
+    const versionEntry = runtimeEntry.versions[version];
+    if (!versionEntry) {
+        ctx.stderr.write(`nimbus install: '${name}@${version}' not in catalog\n`);
+        return 1;
+    }
+    const home = deps.getHome();
+    const root = installRoot(home, name, version);
+    // Idempotent: if manifest already on disk + sha-equivalent, skip.
+    if (!force && deps.vfs.exists(`${root}/manifest.json`)) {
+        // We could re-verify all blob sha256s, but that's expensive. The
+        // manifest's presence implies the install completed; we trust it.
+        ctx.stdout.write(`[${name}] already installed at ${root} (use --reinstall to refetch)\n`);
+        // Still re-register bins in case the registry lost them — idempotent.
+        rehydrateInstalledRuntimes(deps.vfs, deps.registry, home);
+        return 0;
+    }
+    // Fetch manifest from R2.
+    ctx.stdout.write(`[${name}] fetching manifest...\n`);
+    let manifest;
+    try {
+        manifest = await fetchManifest(deps.env, versionEntry.manifest);
+    }
+    catch (e) {
+        ctx.stderr.write(`nimbus install: ${e?.message || e}\n`);
+        return 1;
+    }
+    // Pre-flight: budget check.
+    const totalBytes = manifest.files.reduce((a, f) => a + f.size, 0);
+    ctx.stdout.write(`[${name}] manifest: ${manifest.files.length} files, ${(totalBytes / 1024 / 1024).toFixed(1)} MiB\n`);
+    // Create install root.
+    deps.vfs.mkdir(root, { recursive: true });
+    // Write manifest.json first (so a partial install can be retried
+    // and the manifest is the source of truth).
+    deps.vfs.writeFile(`${root}/manifest.json`, JSON.stringify(manifest, null, 2));
+    // W2: bounded-parallel blob fetch (concurrency=3).
+    //
+    // Pre-W2 this was a serial for-loop awaiting fetchBlob one at a time.
+    // For multi-blob bundles (clang has 5 blobs with the two largest
+    // dominating wall-clock at ~31 MB + ~19 MB), overlap of network/L2
+    // reads cuts cold-install wall-clock by 30-50%. Concurrency capped
+    // at 3 to bound memory peak: worst-case clang holds 3 in-flight
+    // blobs ≈ ~50-60 MB; well under the DO's 128 MB cap. Memory peak
+    // is further bounded by sqlite-vfs.ts pendingWrites auto-flush at
+    // 500 chunks / ~32 MiB (`src/vfs/sqlite-vfs.ts:606`).
+    //
+    // mkdir-parent is hoisted OUT of the worker body so concurrent
+    // workers don't race against vfs.mkdir for the same parent. Each
+    // unique parent dir is created exactly once, synchronously, BEFORE
+    // any worker starts.
+    //
+    // Manifest-first invariant preserved: this loop runs AFTER the
+    // manifest.json write above. Partial-install detection unchanged.
+    //
+    // Progress UX: with parallel workers, lines arrive in completion
+    // order, not start order. The final "[name] installed at … (Y MiB)"
+    // line is still the authoritative completion signal.
+    const FETCH_CONCURRENCY = 3;
+    // Pre-compute + create all unique parent dirs sync. Avoids a
+    // mkdir race between workers and is faster than per-blob exists()
+    // checks.
+    const uniqueParents = new Set();
+    for (const f of manifest.files) {
+        const target = `${root}/${f.path}`;
+        const lastSlash = target.lastIndexOf('/');
+        if (lastSlash > 0) {
+            uniqueParents.add(target.slice(0, lastSlash));
+        }
+    }
+    for (const parent of uniqueParents) {
+        if (!deps.vfs.exists(parent))
+            deps.vfs.mkdir(parent, { recursive: true });
+    }
+    // Hand-rolled worker pool: N workers consume indices off a shared
+    // cursor until the queue is empty. Avoids head-of-line blocking
+    // that chunked Promise.all suffers (a slow blob in batch i doesn't
+    // delay blob i+N from starting).
+    const files = manifest.files;
+    const total = files.length;
+    let nextIdx = 0;
+    let completed = 0;
+    const workers = Array.from({ length: Math.min(FETCH_CONCURRENCY, total) }, async () => {
+        while (true) {
+            const i = nextIdx++;
+            if (i >= total)
+                return;
+            const f = files[i];
+            const target = `${root}/${f.path}`;
+            const bytes = await fetchBlob(deps.env, f.content, f.sha256);
+            deps.vfs.writeFile(target, bytes);
+            completed++;
+            ctx.stdout.write(`[${name}] fetched ${f.path} (${(f.size / 1024 / 1024).toFixed(2)} MiB) ${completed}/${total}\n`);
+        }
+    });
+    await Promise.all(workers);
+    // Register entrypoints.
+    for (const ep of manifest.entrypoints) {
+        const factory = runnerFactories[ep.runner];
+        if (!factory) {
+            ctx.stderr.write(`[${name}] warning: runner '${ep.runner}' not registered; bin '${ep.binName}' will not be invokable\n`);
+            continue;
+        }
+        const handler = factory(manifest, root, ep.binName, ep.kind);
+        deps.registry.register(ep.binName, handler);
+    }
+    ctx.stdout.write(`[${name}] installed at ${root} (${(totalBytes / 1024 / 1024).toFixed(1)} MiB)\n`);
+    return 0;
+}
+// ── --list ───────────────────────────────────────────────────────────
+async function runList(ctx, deps) {
+    const home = deps.getHome();
+    const installed = listInstalledManifests(deps.vfs, home);
+    if (installed.length === 0) {
+        ctx.stdout.write('(no runtimes installed)\n');
+        return 0;
+    }
+    ctx.stdout.write(`installed runtimes (${installed.length}):\n`);
+    for (const { root, manifest } of installed) {
+        const totalBytes = manifest.files.reduce((a, f) => a + f.size, 0);
+        const bins = manifest.entrypoints.map((e) => e.binName).join(', ');
+        ctx.stdout.write(`  ${manifest.name}@${manifest.version}  ${(totalBytes / 1024 / 1024).toFixed(1)} MiB  bins=[${bins}]  ${root}\n`);
+    }
+    return 0;
+}
+// ── --available ──────────────────────────────────────────────────────
+async function runAvailable(ctx, deps) {
+    let catalog;
+    try {
+        catalog = await fetchCatalog(deps.env);
+    }
+    catch (e) {
+        ctx.stderr.write(`nimbus install --available: ${e?.message || e}\n`);
+        return 1;
+    }
+    const names = Object.keys(catalog.runtimes).sort();
+    if (names.length === 0) {
+        ctx.stdout.write('(no runtimes in catalog)\n');
+        return 0;
+    }
+    ctx.stdout.write(`available runtimes (${names.length}):\n`);
+    for (const name of names) {
+        const r = catalog.runtimes[name];
+        const versions = Object.keys(r.versions);
+        ctx.stdout.write(`  ${name}  default=${r.default}  versions=[${versions.join(', ')}]\n`);
+        for (const v of versions) {
+            const ve = r.versions[v];
+            ctx.stdout.write(`    ${v}  ${(ve.size_bytes / 1024 / 1024).toFixed(1)} MiB  license=${ve.license}\n`);
+        }
+    }
+    return 0;
+}
+// ── uninstall ────────────────────────────────────────────────────────
+async function runUninstall(args, ctx, deps) {
+    if (args.length === 0 || args[0].startsWith('--')) {
+        ctx.stderr.write('nimbus uninstall: missing runtime name\n');
+        return 2;
+    }
+    const spec = args[0];
+    const atIdx = spec.indexOf('@');
+    const name = atIdx >= 0 ? spec.slice(0, atIdx) : spec;
+    const versionOverride = atIdx >= 0 ? spec.slice(atIdx + 1) : null;
+    const home = deps.getHome();
+    const installed = listInstalledManifests(deps.vfs, home);
+    const matches = installed.filter((x) => x.manifest.name === name && (!versionOverride || x.manifest.version === versionOverride));
+    if (matches.length === 0) {
+        ctx.stderr.write(`nimbus uninstall: '${name}' is not installed\n`);
+        return 1;
+    }
+    for (const m of matches) {
+        // Unregister bins.
+        for (const ep of m.manifest.entrypoints) {
+            // We don't have a guaranteed `unregister`; bins shadowing is OK
+            // because boot-rehydration only re-registers what's still on disk.
+            if (typeof deps.registry.unregister === 'function') {
+                deps.registry.unregister(ep.binName);
+            }
+        }
+        // Recursive delete via VFS — readdir + unlink + rmdir.
+        rmrfVfs(deps.vfs, m.root);
+        ctx.stdout.write(`[${m.manifest.name}@${m.manifest.version}] uninstalled (removed ${m.root})\n`);
+    }
+    // Clean up empty parent dirs (~/.nimbus/runtimes/<name>/ if no
+    // versions left; runtimes/ if no runtimes left).
+    const runtimeDir = `${home.replace(/^\/+/, '').replace(/\/+$/, '')}/.nimbus/runtimes/${name}`;
+    cleanupEmpty(deps.vfs, runtimeDir);
+    cleanupEmpty(deps.vfs, `${home.replace(/^\/+/, '').replace(/\/+$/, '')}/.nimbus/runtimes`);
+    return 0;
+}
+function rmrfVfs(vfs, path) {
+    if (!vfs.exists(path))
+        return;
+    for (const entry of vfs.readdir(path)) {
+        const child = `${path}/${entry.name}`;
+        if (entry.type === 'directory') {
+            rmrfVfs(vfs, child);
+        }
+        else {
+            vfs.unlink(child);
+        }
+    }
+    vfs.rmdir(path);
+}
+function cleanupEmpty(vfs, path) {
+    if (!vfs.exists(path))
+        return;
+    if (vfs.readdir(path).length === 0) {
+        vfs.rmdir(path);
+    }
+}

package/dist/runtime/port-registry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * port-registry.ts — Maps virtual ports to facet stubs.
+ *
+ * When a facet calls http.createServer().listen(3000), it notifies the
+ * supervisor via SupervisorRPC.registerPort(3000). The supervisor stores
+ * the facet stub here. When the DO receives a request to /port/3000/*,
+ * it looks up the facet and forwards the request.
+ *
+ * Transport (audit C2):
+ *   The proxy forwards a real Request and returns a real Response.
+ *   Workers RPC natively transfers Request/Response values between
+ *   isolates with streaming bodies and flow control (they are NOT
+ *   structured-cloneable — RPC has its own transfer mechanism for
+ *   these types). Binary payloads (images, wasm, gzip, multipart
+ *   uploads, audio/video) go through byte-for-byte with no UTF-8
+ *   coercion or JSON envelope anywhere in the path.
+ *
+ *   Facet contract for handleHttpRequest:
+ *     async handleHttpRequest(request: Request): Promise<Response>
+ *
+ *   where `request.url` is the inner URL the user's HTTP server
+ *   expects (pathname + search, absolute against a synthetic origin),
+ *   `request.method`/`headers` mirror the outer request, and
+ *   `request.body` is a ReadableStream (or null for GET/HEAD) that
+ *   the facet can consume once. The returned Response is returned
+ *   to the outer fetch as-is; its body is streamed directly.
+ */
+export interface PortEntry {
+    port: number;
+    pid: number;
+    /**
+     * Facet stub exposing `handleHttpRequest(Request): Promise<Response>`.
+     * May be null when a facet has reserved a port but not yet wired up
+     * the request handler (see _rpcRegisterPort in nimbus-session.ts).
+     */
+    facetStub: any;
+    registeredAt: number;
+}
+export declare class PortRegistry {
+    private ports;
+    /** Register a facet as listening on a port. */
+    register(port: number, pid: number, facetStub: any): void;
+    /** Unregister a port. */
+    unregister(port: number): boolean;
+    /** Unregister all ports owned by a specific PID. */
+    unregisterByPid(pid: number): number;
+    /** Look up a port entry. */
+    get(port: number): PortEntry | undefined;
+    /** Check if a port is registered. */
+    has(port: number): boolean;
+    /** Get all registered ports. */
+    getAll(): PortEntry[];
+    /**
+     * Forward an HTTP request to the facet owning a port.
+     *
+     * Returns null if no facet is listening on this port (or if a port
+     * is registered but its stub is not yet attached — see PortEntry).
+     *
+     * The Request passed to the facet has a rewritten URL whose pathname
+     * is the inner path (without the `/port/<n>` prefix) and whose origin
+     * matches the outer request, so user code reading `request.url`
+     * sees a URL shape consistent with "my server is running at this
+     * port". Headers and body are forwarded unchanged; the body is a
+     * ReadableStream so binary payloads aren't materialised in memory.
+     *
+     * Binary safety: both directions use structured-cloneable Request/
+     * Response values over Workers RPC. No UTF-8 round-trip anywhere.
+     * A user-facet serving a PNG will return the exact same bytes the
+     * client receives.
+     */
+    routeRequest(port: number, request: Request, pathname: string): Promise<Response | null>;
+    get stats(): {
+        activePorts: number;
+        ports: {
+            port: number;
+            pid: number;
+        }[];
+    };
+}
+//# sourceMappingURL=port-registry.d.ts.map

package/dist/runtime/port-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-registry.d.ts","sourceRoot":"","sources":["../../src/runtime/port-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,SAAS,EAAE,GAAG,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAE7C,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI;IAIzD,yBAAyB;IACzB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,oDAAoD;IACpD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAWpC,4BAA4B;IAC5B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIxC,qCAAqC;IACrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,gCAAgC;IAChC,MAAM,IAAI,SAAS,EAAE;IAIrB;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IA8F9F,IAAI,KAAK;;;;;;MAKR;CACF"}