@deepseek-ai/dsh-experimental-webworker-runtime 0.1.6-alpha.1

package/lib/types/transport/frames.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Tunnel frame protocol between the page and the worker host. Frames cross
+ * `postMessage`, so inbound frames are validated before use.
+ * @module @deepseek-ai/dsh-experimental-webworker-runtime/src/transport/frames
+ */
+/** Request identifier minted by the page. */
+export type TunnelRequestId = string | number;
+/** One request; `body` carries cloneable or transferable raw bytes. */
+export interface TunnelRequestFrame {
+    readonly t: 'req';
+    readonly id: TunnelRequestId;
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body?: ArrayBuffer | Blob | ReadableStream<Uint8Array> | undefined;
+}
+/** Open one Gateway Remote stream over the worker-local carrier. */
+export interface TunnelStreamOpenFrame {
+    readonly t: 'stream-open';
+    readonly id: TunnelRequestId;
+    readonly endpoint: string;
+    readonly payload: unknown;
+}
+/** Page-side cancellation of an in-flight request or stream. */
+export interface TunnelAbortFrame {
+    readonly t: 'abort';
+    readonly id: TunnelRequestId;
+}
+/** Frames the worker accepts. */
+/**
+ * First inbound frame: the base image URL and ordered data overlays selected
+ * before the worker assembly starts.
+ */
+export interface TunnelInitFrame {
+    readonly t: 'init';
+    readonly image: string;
+    readonly overlays: readonly string[];
+}
+/** Every frame the page sends the worker. */
+export type TunnelInboundFrame = TunnelInitFrame | TunnelRequestFrame | TunnelStreamOpenFrame | TunnelAbortFrame;
+/** Complete response for unary requests and static files. */
+export interface TunnelResponseFrame {
+    readonly t: 'res';
+    readonly id: TunnelRequestId;
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    readonly body?: ArrayBuffer | undefined;
+    /** Present when the worker itself refused the request, so the page can surface the reason. */
+    readonly message?: string | undefined;
+}
+/** Head of a streamed response, followed by chunks and one terminator. */
+export interface TunnelResponseHeadFrame {
+    readonly t: 'res-head';
+    readonly id: TunnelRequestId;
+    readonly status: number;
+    readonly headers: Record<string, string>;
+}
+/** One body chunk of a streamed response. */
+export interface TunnelResponseChunkFrame {
+    readonly t: 'res-chunk';
+    readonly id: TunnelRequestId;
+    readonly chunk: ArrayBuffer;
+}
+/** Normal end of a streamed response. */
+export interface TunnelResponseEndFrame {
+    readonly t: 'res-end';
+    readonly id: TunnelRequestId;
+}
+/** Failure of a streamed response after its head was sent. */
+export interface TunnelResponseErrorFrame {
+    readonly t: 'res-err';
+    readonly id: TunnelRequestId;
+    readonly message: string;
+}
+/** One decoded value from a worker-local Gateway Remote stream. */
+export interface TunnelStreamItemFrame {
+    readonly t: 'stream-item';
+    readonly id: TunnelRequestId;
+    readonly value?: unknown;
+}
+/** Normal completion of a worker-local Gateway Remote stream. */
+export interface TunnelStreamEndFrame {
+    readonly t: 'stream-end';
+    readonly id: TunnelRequestId;
+}
+/** Stable Host failure or worker-carrier failure for one logical stream. */
+export interface TunnelStreamErrorFrame {
+    readonly t: 'stream-error';
+    readonly id: TunnelRequestId;
+    readonly failure: {
+        readonly kind: 'remote';
+        readonly code: string;
+        readonly message: string;
+        readonly details: object;
+    } | {
+        readonly kind: 'carrier';
+        readonly message: string;
+    };
+}
+/** Frames the worker emits. */
+export type TunnelOutboundFrame = TunnelResponseFrame | TunnelResponseHeadFrame | TunnelResponseChunkFrame | TunnelResponseEndFrame | TunnelResponseErrorFrame | TunnelStreamItemFrame | TunnelStreamEndFrame | TunnelStreamErrorFrame;
+/**
+ * Validate a `postMessage` payload as a tunnel frame.
+ * @param data - Message data received by the worker.
+ * @returns The frame.
+ */
+export declare function parseInboundFrame(data: unknown): TunnelInboundFrame;
+//# sourceMappingURL=frames.d.ts.map

package/lib/types/transport/synthetic-http.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `IncomingMessage`/`ServerResponse` synthesis for tunnel requests. The app's
+ * `node:http` proxy reports a successful bind and captures the webserver's
+ * request listener; the tunnel feeds that listener these pairs, so the real
+ * route table, its trust fences, and every handler run unchanged.
+ *
+ * Synthesized members are exactly the ones the route handlers read; anything
+ * else is absent on purpose so a new consumer
+ * fails loud instead of silently reading a stub.
+ * @module @deepseek-ai/dsh-experimental-webworker-runtime/src/transport/synthetic-http
+ */
+import type { TunnelRequestFrame } from './frames.ts';
+/** Where a synthesized response writes to. */
+export interface ResponseSink {
+    /** Head of a streaming response. */
+    head(status: number, headers: Record<string, string>): void;
+    /** One body chunk after {@link ResponseSink.head}. */
+    chunk(bytes: Uint8Array): void;
+    /** Completion; the payload is present only for unary answers. */
+    end(payload?: {
+        status: number;
+        headers: Record<string, string>;
+        body?: Uint8Array | undefined;
+    }): void;
+    /** Failure of the exchange. */
+    fail(message: string): void;
+}
+/** Request listener shape the app's `createServer` captured. */
+export type RequestListener = (req: unknown, res: unknown) => void;
+/** The pair a route handler consumes, plus abort control for the tunnel. */
+export interface SyntheticExchange {
+    readonly req: unknown;
+    readonly res: unknown;
+    /** Whether the page abandoned the request before it finished. */
+    readonly aborted: boolean;
+    /** Mark the page as gone: emits `close` and stops further frames. */
+    abort(): void;
+}
+/**
+ * Build the request/response pair for one tunnel request.
+ *
+ * `res.end()` is the settle point: the captured listener returns void, so the
+ * response object itself reports completion. `write()` always returns true,
+ * which skips backpressure waiting the tunnel cannot observe anyway.
+ * @param frame - Validated request frame.
+ * @param sink - Frame emitter for the response.
+ * @returns The pair handed to the captured request listener.
+ */
+export declare function createSyntheticExchange(frame: TunnelRequestFrame, sink: ResponseSink): SyntheticExchange;
+//# sourceMappingURL=synthetic-http.d.ts.map

package/lib/types/transport/tunnel.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Worker end of the postMessage tunnel. It owns the dispatch lanes and the queue
+ * that holds requests until the host tree is serving:
+ *
+ * - `GET /__boot__` answers from tunnel glue, never from the host API surface,
+ *   because the page needs the boot payload before its Cordis tree exists.
+ * - Privileged `/api` methods take that same direct entry. The method set is not
+ *   restated here: a 401 or 403 from the route lane is retried on the direct
+ *   lane because the page owns the worker and needs no network authentication.
+ * - Everything else is fed into the real webserver route table through the
+ *   request listener the app's fake `node:http` captured, keeping the trust
+ *   fences, byte limits, and status semantics intact.
+ *
+ * A boot failure rejects the whole queue with 503 rather than leaving the page
+ * waiting.
+ * @module @deepseek-ai/dsh-experimental-webworker-runtime/src/transport/tunnel
+ */
+import { type TunnelOutboundFrame } from './frames.ts';
+import { type RequestListener } from './synthetic-http.ts';
+/** Prefix owning the API methods. */
+export declare const API_PREFIX = "/api";
+/** Host header the synthesized requests carry; the API trust fence requires one. */
+export declare const SYNTHETIC_HOST = "127.0.0.1";
+/**
+ * Render a failure with everything nested inside it.
+ *
+ * A boot failure is usually an `AggregateError` of per-entry failures, each
+ * wrapping the plugin's own error as `cause`; only the outermost message names
+ * "loader entries failed to apply", which says nothing about which row broke.
+ *
+ * The page logs the rendered text verbatim for refusals; keep it stable for
+ * anyone matching boot-failure output.
+ * @param reason - Thrown value.
+ * @returns One line per nested failure, indented by depth.
+ */
+export declare function describeFailure(reason: unknown): string;
+/** Message channel the tunnel posts frames on. */
+export interface TunnelPort {
+    postMessage(message: TunnelOutboundFrame, transfer?: Transferable[]): void;
+}
+/** What the tunnel gains once the host tree is up. */
+export interface TunnelSeams {
+    /**
+     * Direct entry to the API fetch handler for privileged methods and any unary
+     * call the route lane refused with 401 or 403.
+     */
+    readonly directFetch: (request: Request) => Promise<Response>;
+    /** Boot payload for `GET /__boot__`: the structured index injection table. */
+    readonly bootPayload: () => unknown;
+    /** Open one decoded Gateway Remote stream without another network carrier. */
+    readonly openStream: (endpoint: string, payload: unknown, signal: AbortSignal) => Promise<AsyncIterable<unknown>>;
+    /** Convert a Gateway stream failure to stable Client fields. */
+    readonly streamFailure: (error: unknown) => {
+        readonly code: string;
+        readonly message: string;
+        readonly details: object;
+    };
+}
+/** Construction inputs for {@link TunnelServer}. */
+export interface TunnelServerOptions {
+    /** Channel back to the page. */
+    readonly port: TunnelPort;
+    /**
+     * The webserver's request listener, captured by the app's fake `node:http`.
+     * Awaited on first use, so requests may arrive before the server binds.
+     */
+    readonly requestListener: () => Promise<RequestListener>;
+    /**
+     * Methods that skip the route lane outright. Supply the host's own privileged
+     * set when it is reachable; omitting it leaves the 401/403 retry as the mechanism.
+     */
+    readonly privilegedMethods?: ReadonlySet<string>;
+    /**
+     * Escape hatch for the unary `/api` lane. `route` (default) keeps every fence
+     * and byte limit with a 401/403 retry on the direct lane; `direct` sends every
+     * unary `/api` call straight to the fetch handler.
+     */
+    readonly unaryApiLane?: 'route' | 'direct';
+}
+/** One tunnel per worker; wire {@link TunnelServer.handleMessage} to `onmessage` first. */
+export declare class TunnelServer {
+    private readonly port;
+    private readonly requestListener;
+    private readonly privilegedMethods;
+    private readonly unaryApiLane;
+    private readonly queue;
+    private readonly inFlight;
+    private seams;
+    private failure;
+    private listener;
+    constructor(options: TunnelServerOptions);
+    /**
+     * Accept one `postMessage` payload.
+     * @param data - Message data from the page.
+     */
+    handleMessage(data: unknown): void;
+    /**
+     * Start serving: drains everything queued during boot.
+     * @param seams - Faces that exist only after the host tree is up.
+     */
+    serve(seams: TunnelSeams): void;
+    /**
+     * Refuse every queued and future request; the page renders this like a server
+     * that failed to start.
+     * @param reason - Boot failure to report.
+     */
+    fail(reason: unknown): void;
+    private send;
+    private refuse;
+    private dispatchFrame;
+    private serveStream;
+    private sinkFor;
+    /** The page sends an absolute URL; route handlers read `req.url` as a path. */
+    private pathFrame;
+    private serveRequest;
+    /**
+     * The listener is captured once and reused, so only requests that arrive
+     * before the web server binds pay an await.
+     * @returns The webserver request listener.
+     */
+    private whenListener;
+    /** Feed the real route table through the captured listener. */
+    private dispatch;
+    /**
+     * Unary `/api`: keep the route lane's fences, but fall back to the direct lane
+     * when network authentication or trust rejects the worker-owning page.
+     */
+    private serveApi;
+    private serveBoot;
+    private serveDirect;
+}
+//# sourceMappingURL=tunnel.d.ts.map

package/lib/types/worker-host.d.ts

@@ -0,0 +1,165 @@
+/**
+ * Worker assembly entry: the whole harness Cordis tree inside one dedicated
+ * Web Worker.
+ *
+ * Every platform object arrives through options — the `node:*` proxy table, the
+ * request listener the app's fake `node:http` captured, the image bytes — so this
+ * package never reaches back into the application that composes it. **Platform
+ * readiness before the call is the caller's responsibility**: anything the
+ * proxies need initialized (the zstd WebAssembly module, for one) must be ready
+ * before {@link startWorkerHost} runs.
+ *
+ * Construction is split in two on purpose. {@link createWorkerHost} is
+ * synchronous so the worker can accept messages and queue requests that arrive
+ * during boot; {@link WorkerHost.start} then mounts the image, the module
+ * loader, and the tree. {@link startWorkerHost} performs both and installs the
+ * message handler before its first await.
+ *
+ * The tree itself boots through the host's own `boot()` glue loaded from the
+ * image, so entry mounting, the activation audit, and its diagnostics are the
+ * same code the Node deployment runs. Only the module seam and the command line
+ * are supplied from here.
+ * @module @deepseek-ai/dsh-experimental-webworker-runtime/src/worker-host
+ */
+import { WorkerModuleLoader, type StaticModuleFactory } from './module-system/module-loader.ts';
+import type { AlsCausality } from './polyfill/async-context/als-runtime.ts';
+import type { RequestListener } from './transport/synthetic-http.ts';
+import { type TunnelPort } from './transport/tunnel.ts';
+import { MemoryVfs } from './storage/memory.ts';
+export { DEFAULT_ROOT } from './image-layout.ts';
+/** Port reported to the tree when the caller names none; the bind is fake either way. */
+export declare const DEFAULT_PORT = 3080;
+/** One structured log record, as cordis delivers it to an exporter. */
+export interface LogMessage {
+    readonly name: string;
+    readonly type: 'error' | 'info' | 'warn' | 'debug';
+    readonly args: readonly unknown[];
+}
+/** The exporter face `ctx.logger.exporter()` accepts. */
+export interface LogExporter {
+    readonly colors: false;
+    /** Verbosity gate, per logger name or `default`; cordis drops a message when its level exceeds this. */
+    readonly levels: {
+        readonly default: number;
+    };
+    export(message: LogMessage): void;
+}
+/** Minimal view of the Cordis context the entry itself touches. */
+export interface HostContext {
+    loader: {
+        internal: unknown;
+    };
+    logger: {
+        exporter(exporter: LogExporter): unknown;
+    };
+    get(service: string): unknown;
+    provide(name: string, value: unknown): void;
+    fiber: {
+        dispose(): Promise<void>;
+    };
+}
+/** Construction inputs for {@link createWorkerHost}. */
+export interface WorkerHostOptions {
+    /**
+     * Modules served from the worker bundle rather than the image: the `node:*`
+     * proxies, the not-implemented stubs for excluded npm packages, and anything else whose
+     * platform behavior differs. `node:process` and `process` are added when absent,
+     * as factories reading the installed global.
+     */
+    readonly staticModules: Readonly<Record<string, StaticModuleFactory>>;
+    /** Prefix-matched proxies, for packages whose subpaths are open-ended. */
+    readonly staticModulePrefixes?: Readonly<Record<string, StaticModuleFactory>>;
+    /**
+     * The webserver's request listener, captured by the app's fake `node:http`.
+     * Awaited on first tunnel use, so it may resolve after the tree binds.
+     */
+    readonly requestListener: () => Promise<RequestListener>;
+    /** Image bytes, or the URL the worker fetches them from. */
+    readonly image: Uint8Array | string;
+    /** Ordered data overlays applied after the base image and before boot. */
+    readonly overlays?: readonly (Uint8Array | string)[];
+    /** Virtual root; defaults to {@link DEFAULT_ROOT}. */
+    readonly root?: string;
+    /** Composed configuration inside the image; defaults to `<root>/config/cordis.yml`. */
+    readonly configPath?: string;
+    /**
+     * Inner arguments the tree parses. The default binds the web server to the
+     * loopback authority the tunnel synthesizes, which also keeps
+     * `networkInterfaces()` out of the trust snapshot.
+     */
+    readonly cmdlineArgs?: readonly string[];
+    /** Port named on the default command line; defaults to {@link DEFAULT_PORT}. */
+    readonly port?: number;
+    /** Environment for the process shim; `DSH_HOME` defaults to `<root>/home`. */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Image manifest path; defaults to `<root>/config/vfs-manifest.json`. Its
+     * `lowered` field must name this build's wrapper contract.
+     */
+    readonly manifestPath?: string;
+    /**
+     * Ambient-store snapshot face exported by the app's `node:async_hooks` proxy.
+     * The rewrite that carries stores across suspension points moves state through
+     * it; the proxy remains the only owner of that state.
+     */
+    readonly alsCausality?: AlsCausality;
+    /** Privileged API methods that skip the route lane; see {@link TunnelServer}. */
+    readonly privilegedMethods?: ReadonlySet<string>;
+    /** Escape hatch for the unary `/api` lane; see {@link TunnelServer}. */
+    readonly unaryApiLane?: 'route' | 'direct';
+    /** Channel back to the page; defaults to the worker global scope. */
+    readonly channel?: TunnelPort;
+}
+/** The assembled worker host. */
+export interface WorkerHost {
+    /** Feed one `postMessage` payload; safe before {@link WorkerHost.start}. */
+    handleMessage(data: unknown): void;
+    /**
+     * Mount the image and boot the tree, then start serving queued requests.
+     * @returns Resolves once the tree is active and the tunnel is serving.
+     */
+    start(): Promise<void>;
+    /** Dispose the tree; the tunnel keeps refusing afterwards. */
+    stop(): Promise<void>;
+    /** Filesystem the tree reads, once {@link WorkerHost.start} mounted it. */
+    readonly vfs: MemoryVfs | undefined;
+    /** Module loader behind the Cordis module seam. */
+    readonly modules: WorkerModuleLoader | undefined;
+}
+/**
+ * Build the worker host without touching the network or the image.
+ * @param options - Assembly inputs.
+ * @returns Handle whose `handleMessage` is ready immediately.
+ */
+export declare function createWorkerHost(options: WorkerHostOptions): WorkerHost;
+/** The cordis message renderer this sink formats through. */
+export interface LogRenderer {
+    format(exporter: LogExporter, message: LogMessage): string;
+}
+/**
+ * Send the tree's own warnings and errors to the worker console.
+ *
+ * Cordis's `LoggerService` always exists and always accepts messages, but with
+ * no exporter mounted it only fills a ring buffer — and no profile in this
+ * repository mounts one, so `ctx.logger.warn(...)` reaches nothing. A provider
+ * that fails and is skipped (the skill registry logs exactly that) then looks
+ * identical to one that found nothing, which is how an empty skill catalog hid a
+ * filesystem fault twice.
+ *
+ * Warnings and errors only: `info`/`debug` from 131 plugin rows would bury the
+ * page console, and this exists to make failures visible rather than to trace.
+ * @param ctx - Host context, before any entry mounts.
+ * @param require - Image resolver, for cordis's own message renderer.
+ */
+export declare function installLogSink(ctx: HostContext, require: (specifier: string) => unknown): void;
+/**
+ * Install the message handler and boot the tree.
+ *
+ * The handler is attached before the first await, so requests that arrive
+ * during boot queue instead of being dropped. A boot failure refuses the queue
+ * with 503 and rejects.
+ * @param options - Assembly inputs; `channel` also replaces the message source.
+ * @returns Resolves once the tunnel is serving.
+ */
+export declare function startWorkerHost(options: WorkerHostOptions): Promise<void>;
+//# sourceMappingURL=worker-host.d.ts.map

package/lib/types/worker.d.ts

@@ -0,0 +1,2 @@
+import './node/builtin_modules/implemented/buffer.ts';
+//# sourceMappingURL=worker.d.ts.map