@nimbus-sh/core 0.1.0

package/dist/runtime/os-contracts.d.ts

@@ -0,0 +1,436 @@
+import type { VfsEvent } from '../vfs/events.js';
+/**
+ * A value SQLite can return in a row.
+ *
+ * `ArrayBufferView` is in the union because the host decides the blob
+ * representation and the hosts disagree: workerd's SqlStorage hands back an
+ * `ArrayBuffer`, `bun:sqlite` and `better-sqlite3` hand back a `Uint8Array`.
+ * Both are read through `blobToUint8Array`, which has always accepted either.
+ */
+export type SqlValue = ArrayBuffer | ArrayBufferView | string | number | bigint | null;
+export type SqlRow = Record<string, SqlValue>;
+/**
+ * The whole of the SQL surface the Nimbus filesystem needs.
+ *
+ * One method, because that is what the filesystem actually calls — 88 sites,
+ * all `exec`, all consuming the result by spreading it. workerd's `SqlStorage`
+ * satisfies this structurally, so the Durable Object path passes
+ * `ctx.storage.sql` unchanged and pays nothing for the indirection.
+ *
+ * NOT named `SqlStorage`, deliberately. That name is an ambient global from
+ * `@cloudflare/workers-types`: a port sharing it would still resolve in any
+ * file that forgot the import, silently re-binding to workerd's type while
+ * appearing decoupled. A distinct name makes the choice visible at the import.
+ */
+export interface SqlDatabase {
+    exec(query: string, ...bindings: unknown[]): Iterable<SqlRow>;
+}
+/**
+ * Synchronous, all-or-nothing grouping of `exec` calls.
+ *
+ * Separate from {@link NimbusSqlDatabase} because it is a property of the
+ * STORE, not of the statement runner, and because hosts expose it apart from
+ * `exec`: workerd puts it on `ctx.storage`, `bun:sqlite` builds one with
+ * `db.transaction(fn)`. The filesystem's atomicity guarantees rest entirely on
+ * this being a real transaction — an implementation that merely calls the
+ * callback silently converts every atomic write into a torn one.
+ */
+export interface SqlTransactions {
+    transactionSync<T>(callback: () => T): T;
+}
+/** Host object carrying the transaction primitive (workerd: `ctx`). */
+export interface TransactionHost {
+    readonly storage?: SqlTransactions;
+}
+export interface VfsCred {
+    readonly uid: number;
+    readonly gid: number;
+    readonly groups: readonly number[];
+    readonly umask: number;
+}
+export declare const CRED_KERNEL: VfsCred;
+/**
+ * The session's unprivileged login identity — `user` in /etc/passwd, the
+ * credential every process inherits unless it deliberately transitions.
+ *
+ * It is also the credential the embedder-facing surfaces act with: the SDK
+ * filesystem API, the remote `/rpc` file ops, and the static asset server are
+ * host callers, not processes, and files they create must be owned by the same
+ * identity `exec` runs as. Never CRED_KERNEL — a pid-less caller must never
+ * gain more authority than the shell it is writing files for.
+ */
+export declare const CRED_SESSION_USER: VfsCred;
+export declare function requireVfsCred(value: unknown, source: string): VfsCred;
+export type RuntimeFileType = 'file' | 'directory' | 'symlink';
+export interface RuntimeVfsStat {
+    type: RuntimeFileType;
+    size: number;
+    ctime: number;
+    atime: number;
+    mtime: number;
+    mode: number;
+    uid: number;
+    gid: number;
+    /** Per-path revision: changes iff this path (or its subtree) mutated. */
+    revision: number;
+}
+export interface RuntimeVfsDirEntry {
+    name: string;
+    type: RuntimeFileType;
+}
+export interface RuntimeOpenFlags {
+    read?: boolean;
+    write?: boolean;
+    append?: boolean;
+    create?: boolean;
+    truncate?: boolean;
+    followSymlinks?: boolean;
+    expectedRevision?: number;
+}
+export interface RuntimeFileHandle {
+    id: number;
+    path: string;
+    flags: Required<Omit<RuntimeOpenFlags, 'expectedRevision'>> & {
+        expectedRevision?: number;
+    };
+    position: number;
+    baseRevision: number;
+    closed: boolean;
+}
+export interface RuntimeFsBridge {
+    stat(path: string, options?: {
+        followSymlinks?: boolean;
+    }): Promise<RuntimeVfsStat | null>;
+    readFile(path: string, options?: {
+        followSymlinks?: boolean;
+    }): Promise<Uint8Array | null>;
+    /**
+     * Whole-file write. Returns the revision the write produced, so a caller
+     * holding the bytes it just sent can tell its own mutation apart from a
+     * peer's when {@link RuntimeFsBridge.acquire} reports the path back.
+     */
+    writeFile(path: string, bytes: string | Uint8Array, options?: {
+        createParents?: boolean;
+        expectedRevision?: number;
+    }): Promise<number>;
+    /** Stateless ranged read: clamped at EOF; null when the path is absent. */
+    readRange(path: string, offset: number, length: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<Uint8Array | null>;
+    /**
+     * Stateless ranged write: updates only the chunks the range touches
+     * (never a whole-file rewrite), zero-filling any gap past EOF.
+     * Creates the file when missing. Returns bytes written.
+     */
+    writeRange(path: string, offset: number, bytes: Uint8Array, options?: {
+        createParents?: boolean;
+        expectedRevision?: number;
+    }): Promise<number>;
+    /** Truncate or zero-extend to `size`, touching only the boundary chunk. */
+    truncate(path: string, size: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<void>;
+    utimes(path: string, atimeMs: number, mtimeMs: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<void>;
+    /** Set permission bits (POSIX chmod — follows symlinks). */
+    chmod(path: string, mode: number): Promise<void>;
+    /** Check access using the bridge's process credential. */
+    access(path: string, mode: number): Promise<void>;
+    /** Change stored ownership, optionally operating on a symlink itself. */
+    chown(path: string, uid: number, gid: number, options?: {
+        followSymlinks?: boolean;
+    }): Promise<void>;
+    open(path: string, flags: RuntimeOpenFlags): Promise<RuntimeFileHandle>;
+    read(handleId: number, offset: number | null, length: number): Promise<Uint8Array>;
+    write(handleId: number, offset: number | null, bytes: Uint8Array): Promise<number>;
+    close(handleId: number): Promise<void>;
+    readdir(path: string, options?: {
+        followSymlinks?: boolean;
+    }): Promise<RuntimeVfsDirEntry[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<void>;
+    unlink(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    readlink(path: string): Promise<string | null>;
+    symlink(target: string, path: string): Promise<void>;
+    fsync(handleId?: number): Promise<void>;
+    /**
+     * Without a path: the global VFS mutation watermark. With a path: a
+     * per-path subtree watermark — it changes iff that path or anything
+     * under it mutated, so consumers can cache without global invalidation.
+     */
+    revision(path?: string): Promise<number>;
+    /**
+     * The cache-coherence barrier. A caller holding a resident cache stamped
+     * at `(epoch, cursor)` gets back every path mutated since, and re-stamps.
+     *
+     * `poison` means the view cannot be repaired incrementally — a different
+     * supervisor incarnation, or a cursor older than the retained log — and
+     * the caller must drop its entire resident set. That costs a cold cache;
+     * the alternative would be serving a stale byte.
+     */
+    acquire(epoch: string | null, cursor: number): Promise<VfsAcquireResult>;
+    /**
+     * Enumerate every path this bridge's credential can see, one bounded page at
+     * a time, resuming past `after`.
+     *
+     * {@link RuntimeFsBridge.acquire} tells a caller what CHANGED; this tells it
+     * what EXISTS. A resident cache can be kept coherent with the barrier alone,
+     * but it can only be made COMPLETE with this: every map a process is shipped
+     * describes what it was GIVEN, so a cache enumerated from them can never
+     * hold a path that was not already staged.
+     */
+    list(after?: string | null, limit?: number): Promise<VfsListPage>;
+    subscribe?(path: string, listener: (event: VfsEvent) => void): () => void;
+}
+/**
+ * One path in an {@link RuntimeFsBridge.acquire} delta, with the revision it
+ * was last mutated at. The revision is what makes the delta usable by the
+ * process that caused it: a caller holding the revision its own write
+ * produced keeps that cell, while a peer's later write to the same path
+ * reports a higher revision and still invalidates.
+ */
+export interface VfsInvalidatedPath {
+    path: string;
+    rev: number;
+}
+/** Result of a {@link RuntimeFsBridge.acquire} barrier. */
+export interface VfsAcquireResult {
+    epoch: string;
+    rev: number;
+    paths: VfsInvalidatedPath[];
+    poison: boolean;
+}
+/**
+ * One path in a {@link RuntimeFsBridge.list} page.
+ *
+ * `size` is here because the only consumer of an enumeration is a filler that
+ * must then FETCH the bytes, and every batch read is bounded by a byte total
+ * the caller has to compute before it asks. A list without sizes forces a stat
+ * per path just to pack a request — the round trip the enumeration exists to
+ * remove.
+ *
+ * `rev` is the path's own last-mutation revision for a file and a subtree
+ * watermark for a directory ({@link RuntimeFsBridge.revision} semantics
+ * unchanged). It is what lets a cached row be DATED, and an undated row is
+ * exactly the row that can never be invalidated.
+ */
+export interface VfsListEntry {
+    path: string;
+    kind: RuntimeFileType;
+    size: number;
+    rev: number;
+}
+/**
+ * One page of {@link RuntimeFsBridge.list}.
+ *
+ * `next` is the resume key, and `null` means the listing is COMPLETE. That
+ * distinction is the contract: a caller that cannot tell a truncated page from
+ * a finished one treats a partial filesystem as the whole one — the same class
+ * of defect as reading a truncated file as a complete one, which is why
+ * `_rpcFsReadBatch` rejects rather than truncates.
+ *
+ * `epoch`/`rev` are read BEFORE the page is walked, for the same reason
+ * `buildPrefetchBundle` reads its cursor before its walk: a mutation landing
+ * during enumeration must be reported by the next ACQUIRE, never silently
+ * missed. Dating rows at a cursor OLDER than their bytes costs a refetch;
+ * dating them newer would serve a stale byte.
+ */
+export interface VfsListPage {
+    epoch: string;
+    rev: number;
+    entries: VfsListEntry[];
+    next: string | null;
+}
+export interface RuntimeProcessBridge {
+    spawn(command: string, args: string[], options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        tty?: RuntimeTtyOptions;
+    }): Promise<{
+        pid: number;
+    }>;
+    writeStdin(pid: number, bytes: string | Uint8Array): Promise<void>;
+    endStdin(pid: number): Promise<void>;
+    kill(pid: number, signal?: string): Promise<void>;
+    wait(pid: number, timeoutMs?: number): Promise<{
+        exitCode: number | null;
+    }>;
+}
+export interface RuntimeTtyOptions {
+    stdinIsTTY?: boolean;
+    stdoutIsTTY?: boolean;
+    stderrIsTTY?: boolean;
+    columns?: number;
+    rows?: number;
+    raw?: boolean;
+}
+/**
+ * Where a registered port's traffic goes: one process, reached by HTTP.
+ *
+ * The whole of what a listening process exposes, deliberately. A resident
+ * process never receives a WebSocket — every inbound socket Nimbus serves
+ * terminates on the session and reaches the process, if at all, as events on a
+ * poll — so a target that could return a 101 would describe a case no runner
+ * produces.
+ *
+ * Lives here rather than beside the registry because both ends need it and
+ * neither owns it: the port registry stores these, and the process fabric
+ * hands one back for every resident process it starts. Defining it in either
+ * would make the other import a peer's internals to name its own contract.
+ */
+export interface RouteableFacetTarget {
+    handleHttpRequest(request: Request): Promise<Response>;
+}
+export interface RuntimePortBridge {
+    register(port: number, processId: number, handler: (request: Request) => Promise<Response>): Promise<void>;
+    unregister(port: number, processId?: number): Promise<void>;
+    list(): Promise<Array<{
+        port: number;
+        processId: number;
+        registeredAt: number;
+    }>>;
+}
+export declare const NIMBUS_OS_NAME = "nimbus";
+export declare const NIMBUS_ABI_TARGET = "wasm32-wasi-nimbus";
+export declare const NIMBUS_ABI_ID = "wasm32-wasi-nimbus";
+/** Canonical Pyodide package artifact ABI label. The single source of
+ *  truth for the label — runtime manifests, the pip planner, and
+ *  diagnostics all consume this constant. */
+export declare const PYODIDE_PACKAGE_ABI = "pyodide-emscripten-2025_0-wasm32";
+/** Canonical artifact class for native platform binaries Nimbus cannot
+ *  execute (Linux/Windows/macOS executables, .node bindings, native
+ *  wheels/gems). */
+export declare const NATIVE_UNSUPPORTED_ABI = "native-unsupported";
+export type RuntimePackageAbi = 'javascript' | typeof NIMBUS_ABI_TARGET | typeof PYODIDE_PACKAGE_ABI | 'py3-none-any' | 'python-source-pure' | 'pyodide' | 'ruby-wasm' | typeof NATIVE_UNSUPPORTED_ABI;
+export declare const NIMBUS_RUNTIME_ABIS: Readonly<Record<string, RuntimePackageAbi>>;
+/** Name-to-name package rewrite at the resolver/installer boundary. */
+export interface PackageSwapEntry {
+    /** Original package name the user (or a transitive dep) asked for. */
+    from: string;
+    /** Package name we install instead. */
+    to: string;
+    /** One-line reason shown to the user. */
+    reason: string;
+    /**
+     * 'drop-in' = `require(from)` and `require(to)` work identically — same
+     *             export shape.
+     * 'shim'    = (reserved) we write package.json `dependencies` so consumer
+     *             imports `from`, gets `to`.
+     * 'manual'  = (reserved) consumer code change required. Demoted to
+     *             rejects because listing it here would silently break
+     *             user code.
+     */
+    compat: 'drop-in' | 'shim' | 'manual';
+}
+/**
+ * Staged-artifact entry: a package whose only published runnable form is a
+ * platform-native binary (so it would otherwise hit the native-artifact
+ * reject), but for which Nimbus ships a prebuilt JS/WASM bundle in the
+ * static-assets layer. At resolve time the package's native shards
+ * (optionalDependencies) and lifecycle scripts are dropped and its `bin` is
+ * rewritten to a Nimbus shim that loads the staged bundle.
+ */
+export interface PackageStagedArtifactEntry {
+    /** Package name the user installs (e.g. `opencode-ai`). */
+    from: string;
+    /** Bin name the staged artifact provides (e.g. `opencode`). */
+    bin: string;
+    /** Stable artifact id the node runtime resolves to a staged asset path. */
+    artifact: string;
+    /** One-line reason shown to the user. */
+    reason: string;
+}
+/** Deny-list entry with a helpful, always-actionable message. */
+export interface PackageRejectEntry {
+    from: string;
+    reason: string;
+    /** Optional swap-target suggestion shown inline. */
+    suggest?: string;
+    /**
+     * 'fail' = hard-fail at any depth.
+     * 'warn' = top-level hard-fails; transitive logs `[skip]` and drops the
+     *          package from the resolved tree (matches genuinely-optional
+     *          natives like fsevents).
+     */
+    transitive: 'fail' | 'warn';
+}
+/**
+ * The one typed package-ABI policy. Defined once in supervisor code
+ * (`facets/wasm-swap-registry.ts: PACKAGE_ABI_POLICY`) and serialized
+ * verbatim into resolver/loader facet preambles — generated dynamic
+ * Workers cannot import supervisor modules, so the policy travels as
+ * JSON plus serialized policy functions. The preamble parity unit test
+ * (`tests/unit/package-abi-policy.mjs`) extracts the injected policy and
+ * asserts equality with this object so the two can never drift.
+ */
+export interface PackageAbiPolicy {
+    /** Public compiled-artifact target string (`wasm32-wasi-nimbus`). */
+    abiTarget: typeof NIMBUS_ABI_TARGET;
+    /** Artifact classes Nimbus can install and execute. */
+    acceptedArtifactClasses: readonly RuntimePackageAbi[];
+    /** Artifact class assigned to rejected native platform artifacts. */
+    nativeArtifactClass: typeof NATIVE_UNSUPPORTED_ABI;
+    /** Drop-in name rewrites (native package → published WASM build). */
+    swaps: readonly PackageSwapEntry[];
+    /** Native-only packages Nimbus ships a prebuilt JS/WASM artifact for. */
+    stagedArtifacts: readonly PackageStagedArtifactEntry[];
+    /** Known-native deny list with per-entry transitive policy. */
+    rejects: readonly PackageRejectEntry[];
+    /** Build-only packages skipped at transitive depth. */
+    skipPackages: readonly string[];
+    /** Build-only package name prefixes skipped at transitive depth. */
+    skipPrefixes: readonly string[];
+    /** Packages exempted from skipPackages when a framework needs them. */
+    frameworkRequiredPackages: readonly string[];
+    /** Known native-shard name globs, matched as `prefix-…`. */
+    nativeShardPrefixes: readonly string[];
+    /** Exact names exempted from nativeShardPrefixes (pure WASM builds). */
+    nativeShardExemptions: readonly string[];
+    /** bin-target file extensions that mark a native executable. */
+    nativeBinExtensions: readonly string[];
+}
+export type RuntimeAbiCapability = 'wasi.snapshot-preview1' | 'wasi.unstable-import-alias' | 'vfs.snapshot-diff' | 'stdio' | 'argv' | 'env' | 'clock' | 'random' | 'path' | 'symlink' | 'hardlink' | 'poll' | 'outbound-tcp-devtcp' | 'wasi.threads';
+export interface RuntimeAbiDescriptor {
+    os: typeof NIMBUS_OS_NAME;
+    target: typeof NIMBUS_ABI_TARGET;
+    id: typeof NIMBUS_ABI_ID;
+    env: Readonly<Record<string, string>>;
+    capabilities: readonly RuntimeAbiCapability[];
+}
+export declare const WASM32_WASI_NIMBUS_ABI: RuntimeAbiDescriptor;
+export interface RuntimeCommandProvider {
+    runtimeName: string;
+    version: string;
+    abi: RuntimePackageAbi;
+    commands: string[];
+    packageManagers?: string[];
+    libraries?: string[];
+}
+export type RuntimeDiagnosticEvent = {
+    type: 'fs-cache';
+    hit: boolean;
+    path: string;
+    bytes?: number;
+    revision?: number;
+} | {
+    type: 'fs-flush';
+    path?: string;
+    bytes: number;
+    durationMs: number;
+} | {
+    type: 'fs-invalidation';
+    path: string;
+    revision: number;
+    lagMs?: number;
+} | {
+    type: 'unsupported-abi';
+    packageName?: string;
+    abi: string;
+    message: string;
+};
+//# sourceMappingURL=os-contracts.d.ts.map

package/dist/runtime/os-contracts.d.ts.map

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

package/dist/runtime/os-contracts.js

@@ -0,0 +1,101 @@
+export const CRED_KERNEL = Object.freeze({
+    uid: 0,
+    gid: 0,
+    groups: Object.freeze([0]),
+    umask: 0o022,
+});
+/**
+ * The session's unprivileged login identity — `user` in /etc/passwd, the
+ * credential every process inherits unless it deliberately transitions.
+ *
+ * It is also the credential the embedder-facing surfaces act with: the SDK
+ * filesystem API, the remote `/rpc` file ops, and the static asset server are
+ * host callers, not processes, and files they create must be owned by the same
+ * identity `exec` runs as. Never CRED_KERNEL — a pid-less caller must never
+ * gain more authority than the shell it is writing files for.
+ */
+export const CRED_SESSION_USER = Object.freeze({
+    uid: 1000,
+    gid: 1000,
+    groups: Object.freeze([1000]),
+    umask: 0o022,
+});
+export function requireVfsCred(value, source) {
+    if (typeof value !== 'object' || value === null) {
+        throw new Error(`${source} requires process credentials`);
+    }
+    const uid = 'uid' in value ? value.uid : undefined;
+    const gid = 'gid' in value ? value.gid : undefined;
+    const groups = 'groups' in value ? value.groups : undefined;
+    const umask = 'umask' in value ? value.umask : undefined;
+    if (typeof uid !== 'number' || !Number.isInteger(uid)
+        || typeof gid !== 'number' || !Number.isInteger(gid)
+        || !Array.isArray(groups)
+        || typeof umask !== 'number' || !Number.isInteger(umask)) {
+        throw new Error(`${source} requires process credentials`);
+    }
+    const normalizedGroups = [];
+    for (const group of groups) {
+        if (typeof group !== 'number' || !Number.isInteger(group)) {
+            throw new Error(`${source} requires process credentials`);
+        }
+        normalizedGroups.push(group);
+    }
+    return {
+        uid,
+        gid,
+        groups: normalizedGroups,
+        umask,
+    };
+}
+export const NIMBUS_OS_NAME = 'nimbus';
+export const NIMBUS_ABI_TARGET = 'wasm32-wasi-nimbus';
+export const NIMBUS_ABI_ID = NIMBUS_ABI_TARGET;
+/** Canonical Pyodide package artifact ABI label. The single source of
+ *  truth for the label — runtime manifests, the pip planner, and
+ *  diagnostics all consume this constant. */
+export const PYODIDE_PACKAGE_ABI = 'pyodide-emscripten-2025_0-wasm32';
+/** Canonical artifact class for native platform binaries Nimbus cannot
+ *  execute (Linux/Windows/macOS executables, .node bindings, native
+ *  wheels/gems). */
+export const NATIVE_UNSUPPORTED_ABI = 'native-unsupported';
+export const NIMBUS_RUNTIME_ABIS = Object.freeze({
+    bash: NIMBUS_ABI_TARGET,
+    clang: NIMBUS_ABI_TARGET,
+    python: 'pyodide',
+    // The wasm32-wasi interpreter. It does have compiled packages — numpy, and
+    // markupsafe's speedups — but they are linked into a prebuilt interpreter
+    // variant rather than loaded at run time, so no wheel carrying a native
+    // extension can be installed. See packages/worker/wasm/python/EXTENSIONS.md.
+    cpython: NATIVE_UNSUPPORTED_ABI,
+    ruby: 'ruby-wasm',
+    node: 'javascript',
+    bun: 'javascript',
+});
+export const WASM32_WASI_NIMBUS_ABI = {
+    os: NIMBUS_OS_NAME,
+    target: NIMBUS_ABI_TARGET,
+    id: NIMBUS_ABI_ID,
+    env: Object.freeze({
+        NIMBUS_OS: NIMBUS_OS_NAME,
+        NIMBUS_ABI: NIMBUS_ABI_ID,
+        NIMBUS_ABI_TARGET,
+    }),
+    capabilities: Object.freeze([
+        'wasi.snapshot-preview1',
+        'wasi.unstable-import-alias',
+        'vfs.snapshot-diff',
+        'stdio',
+        'argv',
+        'env',
+        'clock',
+        'random',
+        'path',
+        'symlink',
+        'hardlink',
+        'poll',
+        'outbound-tcp-devtcp',
+        // Cooperative, correct, and not parallel — see runtime/wasi-threads.ts.
+        'wasi.threads',
+    ]),
+};

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

@@ -0,0 +1,100 @@
+/**
+ * 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` and application headers mirror the outer request,
+ *   Nimbus credentials/internal headers are removed, 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.
+ */
+import type { RouteableFacetTarget } from './os-contracts.js';
+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: RouteableFacetTarget | null;
+    registeredAt: number;
+}
+export declare class PortRegistry {
+    private ports;
+    private facetStubsByPid;
+    private portWaitersByPid;
+    /** Remember the available facet capabilities for a running process. */
+    bindFacetStub(pid: number, facetStub: unknown): void;
+    /**
+     * Register a process as listening on a port. The route target comes from
+     * the pid's binding — one target per process, owned by whoever started it —
+     * so a port announced by the facet itself and one reserved by the spawn
+     * resolve to the same handler.
+     */
+    register(port: number, pid: number): 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;
+    /** Attach a normalized route target to ports previously reserved by a PID. */
+    private attachFacetStubByPid;
+    getRouteablePortsByPid(pid: number): number[];
+    waitForRouteablePortsByPid(pid: number, timeoutMs: number): Promise<number[]>;
+    /** 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". Application headers and the body are forwarded; Nimbus
+     * credentials and internal routing headers are removed before crossing
+     * the user-code trust boundary. The body remains a ReadableStream so
+     * binary payloads aren't materialised in memory.
+     *
+     * Binary safety: Workers RPC transfers Request/Response values with
+     * their streaming bodies; it does not structured-clone them. No UTF-8
+     * round-trip occurs 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;
+        }[];
+    };
+    private waitForPidPortChange;
+    private notifyPortWaiters;
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,SAAS,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACvC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,eAAe,CAA2C;IAClE,OAAO,CAAC,gBAAgB,CAAsC;IAE9D,uEAAuE;IACvE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI;IAQpD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzC,yBAAyB;IACzB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC,oDAAoD;IACpD,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM;IAYpC,4BAA4B;IAC5B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIxC,8EAA8E;IAC9E,OAAO,CAAC,oBAAoB;IAW5B,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE;IAMvC,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAOnF,qCAAqC;IACrC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,gCAAgC;IAChC,MAAM,IAAI,SAAS,EAAE;IAIrB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAoG9F,IAAI,KAAK;;;;;;MAKR;IAED,OAAO,CAAC,oBAAoB;IAsB5B,OAAO,CAAC,iBAAiB;CAM1B"}