@hydraharness/harness-code-runtime-worker-thread 0.1.1-rc.6

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-code-runtime-worker-thread`.
+* @module @hydraharness/harness-code-runtime-worker-thread/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-code-runtime-worker-thread";
+/** Cordis companion plugin name. */
+const name = "code-runtime-worker-thread-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this process-boundary implementation exposes no same-process event relation;
+* worker protocol and built-worker tests cover it.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/bootstrap.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Worker-side execution logic, written as plain functions over an injected port so the unit
+ * suite can run every line IN-PROCESS against a fake port (a real worker thread is a separate
+ * V8 isolate the coverage provider cannot observe).
+ * @module @hydraharness/harness-code-runtime-worker-thread/src/bootstrap
+ */
+import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts';
+/** The port API the bootstrap needs — satisfied by `parentPort` and by the tests' fake. */
+export interface BootstrapPort {
+    postMessage(message: WorkerToHost): void;
+    on(event: 'message', listener: (message: ReplyMessage) => void): void;
+}
+/**
+ * A writable stream's `write` slot, as the bootstrap patches it (see
+ * {@link captureStreamWrites}). Method-typed so the real
+ * `process.stdout`/`process.stderr` (narrower chunk parameters) remain
+ * assignable.
+ */
+export interface PatchableStream {
+    write(chunk: unknown, ...rest: unknown[]): boolean;
+}
+/**
+ * Ordered text capture under the shared outer JSON-byte budget, delivered to
+ * a sink as each item lands (the real sink streams text over the port eagerly,
+ * so captured output survives a mid-run termination). It includes the log
+ * array syntax and string escaping in its accounting. Once exhausted it emits
+ * the fitting prefix and reports the limit once; the host turns that condition
+ * into an explicit `output-limit` run failure.
+ */
+export declare class LogBuffer {
+    private bytes;
+    private entries;
+    private truncated;
+    private readonly sink;
+    private readonly onLimit;
+    private readonly maxBytes;
+    constructor(maxBytes: number, sink: (text: string) => void, onLimit?: () => void);
+    /**
+     * Emit text to the sink, charging it against the budget (drops + marks once exhausted).
+     * @param text - the captured text to deliver.
+     */
+    push(text: string): void;
+    /** Remaining exact JSON-byte budget for the completion value or failure message. */
+    remainingOutputBytes(): number;
+}
+/** The five console methods the shim captures, in the seam's level vocabulary. */
+declare const CONSOLE_LEVELS: readonly ["log", "info", "warn", "error", "debug"];
+/**
+ * A `console` replacement whose five leveled methods render their arguments
+ * `util.inspect`-style (matching real console formatting closely enough for
+ * a model to recognize its own output) into the buffer. Only these five
+ * exist — the program gets a deliberately small console, not Node's full
+ * console API.
+ * @param logs - the buffer every rendered line is pushed into.
+ * @returns the five-method console object handed to the program.
+ */
+export declare function makeConsoleShim(logs: LogBuffer): Record<(typeof CONSOLE_LEVELS)[number], (...args: unknown[]) => void>;
+/**
+ * Redirect a stream's `write` into the log buffer (the program-visible
+ * `process.stdout`/`process.stderr` in the real worker), so raw writes land in emission order
+ * alongside console output instead of racing down a pipe. It preserves Node's optional callback
+ * contract: the callback runs asynchronously after admission, even when the log budget drops
+ * the write.
+ *
+ * @param logs - the buffer captured writes are pushed into.
+ * @param stream - the stream whose `write` slot is patched.
+ * @returns the restore function (the in-process tests un-patch; the real
+ *   worker never needs to).
+ */
+export declare function captureStreamWrites(logs: LogBuffer, stream: PatchableStream): () => void;
+/**
+ * Prepare the program's completion value for the done message. Only lossless
+ * JSON crosses, and a value that does not fit the remaining combined outer
+ * budget reports `output-limit`; the host revalidates hostile traffic and
+ * remains authoritative for native pipe writes the worker cannot observe.
+ *
+ * @param value - the program's completion value.
+ * @param remainingOutputBytes - exact bytes left after captured logs.
+ * @param maxOutputBytes - the configured cap named in an overflow diagnostic.
+ * @returns the done-message fragment: `{}` for `undefined`, else a flat wire `{ value }`.
+ */
+export declare function prepareCompletion(value: unknown, remainingOutputBytes: number, maxOutputBytes?: number): Omit<DoneMessage, 'type'>;
+/**
+ * Prepare a thrown program value without sending an unbounded stack or
+ * string across the worker port.
+ * @param error - the value thrown by the program.
+ * @param remainingOutputBytes - exact bytes left after captured logs.
+ * @param maxOutputBytes - the configured cap named in an overflow diagnostic.
+ * @returns a bounded exception or fixed output-limit fragment.
+ */
+export declare function prepareException(error: unknown, remainingOutputBytes: number, maxOutputBytes?: number): Omit<DoneMessage, 'type'>;
+/** One awaited binding call's settlement handles, keyed by call id in the pending map. */
+export interface PendingCall {
+    resolve(value: unknown): void;
+    reject(error: Error): void;
+}
+/** Constructor type for one program-visible binding rejection class. */
+export type BindingErrorConstructor = new (memberName: string, message: string) => Error;
+/**
+ * Build each declared error class once so calls and `instanceof` share constructor identity.
+ * @param data - binding namespace declarations from the boot payload.
+ * @returns constructors keyed by their owning namespace global.
+ */
+export declare function makeBindingErrorClasses(data: Pick<WorkerBootData, 'namespaces'>): Map<string, BindingErrorConstructor>;
+/**
+ * Route host replies into the pending-call map: each reply settles its call
+ * at most once, and a reply for an unknown id (stray, or a duplicate answer
+ * to an id already settled) is ignored. Shared wiring between
+ * {@link runWorkerMain} and the tests that exercise {@link makeNamespaces}
+ * standalone.
+ * @param port - the port whose `message` events carry the replies.
+ * @param pending - the id-keyed map of unsettled binding calls.
+ */
+export declare function wireReplies(port: BootstrapPort, pending: Map<number, PendingCall>): void;
+/**
+ * Build the binding namespace objects the program sees: one null-prototype global per
+ * namespace, each declared name an own enumerable async function that bridges over the port
+ * (`__proto__`/`constructor`/`toString` are ordinary keys, never prototype collisions).
+ * Lossy arguments reject before posting; clone failures and host failure
+ * replies reject only the corresponding call.
+ *
+ * @param data - the boot payload's namespace declarations (globals + names).
+ * @param port - the port binding calls are posted to.
+ * @param pending - the id-keyed map each posted call parks its handles in.
+ * @param nextId - the shared mutable id counter (worker-issued correlation ids).
+ * @param errorClasses - per-namespace constructors shared with program globals.
+ * @returns one namespace object per declaration, in declaration order.
+ */
+export declare function makeNamespaces(data: Pick<WorkerBootData, 'namespaces'>, port: BootstrapPort, pending: Map<number, PendingCall>, nextId: {
+    value: number;
+}, errorClasses?: Map<string, BindingErrorConstructor>): Record<string, unknown>[];
+/**
+ * Run one strict async-function body, allowing top-level `await` and `return`, and post exactly
+ * one terminal {@link DoneMessage}; a thrown program error becomes its `error` field.
+ * @param port - host message port or test double.
+ * @param data - the boot payload the host sent.
+ * @param streams - stdout/stderr objects captured as program logs.
+ * @returns after posting the done message.
+ */
+export declare function runWorkerMain(port: BootstrapPort, data: WorkerBootData, streams: {
+    stdout: PatchableStream;
+    stderr: PatchableStream;
+}): Promise<void>;
+export {};
+//# sourceMappingURL=bootstrap.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Worker-thread code runtime: a fresh worker runs each host-type-stripped TypeScript program
+ * and bridges bindings over its message port. This is containment, not a security boundary:
+ * model code has bash-equivalent trust despite an empty environment, a heap cap, measured
+ * event-loop busy-time and wall-time budgets, and termination that also stops synchronous loops.
+ * @module @hydraharness/harness-code-runtime-worker-thread
+ */
+import { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import { CodeRuntime } from '@hydraharness/harness-code-runtime';
+import type { CodeRunRequest, CodeRunResult } from '@hydraharness/harness-code-runtime';
+/** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
+export interface Config {
+    /**
+     * Busy-time budget in milliseconds: the run fails with kind `'timeout'`
+     * once the worker's MEASURED event-loop active time
+     * (`worker.performance.eventLoopUtilization()`) exceeds this. Metering
+     * measured busy time — not wall time, not host-side pending-call
+     * bookkeeping — is what makes the budget both fair (a program awaiting a
+     * slow tool accrues nothing) and ungameable (a hot loop accrues whether
+     * or not a decoy dispatch is in flight).
+     */
+    computeMs?: number;
+    /**
+     * Wall-clock ceiling in milliseconds; never pauses for anything. The
+     * backstop for what busy-time cannot see (a program awaiting a promise
+     * nobody will resolve). At most `2_147_483_647` (Node's maximum
+     * `setTimeout` delay, about 24.9 days): a longer value is rejected at load
+     * because `setTimeout` would clamp it to 1 ms.
+     */
+    maxWallMs?: number;
+    /**
+     * Hard cap for serialized log-array, completion-value, and failure-message payloads;
+     * fixed result-envelope syntax is excluded.
+     */
+    maxOutputBytes?: number;
+    /** The worker's max old-generation heap in MiB (`resourceLimits`); overflow kills the worker, surfacing as kind `'worker-exit'`. */
+    maxOldGenerationSizeMb?: number;
+}
+/**
+ * The shipped {@link CodeRuntime} backend (`ctx.codeRuntime`). Registers as
+ * the `codeRuntime` service; every cap comes from validated config. See the
+ * module doc for the containment model and the Service Definition's class JSDoc for
+ * the contract this implements (error-as-field, hostile-peer port,
+ * no cross-run state, dispose to quiescence).
+ */
+export declare class WorkerThreadCodeRuntime extends CodeRuntime {
+    static Config: z<Config>;
+    readonly language = "typescript";
+    readonly isolation = "worker-thread";
+    private readonly config;
+    private readonly live;
+    private disposed;
+    constructor(ctx: Context, config: Config);
+    /**
+     * Dispose to quiescence: mark the service unusable, fail every in-flight
+     * run as aborted, and AWAIT each worker's exit so no worker outlives the
+     * fiber.
+     */
+    private teardown;
+    /**
+     * Execute one program in a fresh worker. Program outcomes — including a
+     * type-strip syntax error, which never spawns a worker — resolve with
+     * `result.error`; the method rejects only for Service Definition contract misuse (a disposed
+     * runtime, an invalid binding namespace).
+     * @param request - the program, its bindings, and the abort signal.
+     * @returns the run's outcome per the seam contract.
+     */
+    run(request: CodeRunRequest): Promise<CodeRunResult>;
+    /** Apply the outer-output ledger to failures that occur before a worker owns one. */
+    private failureBeforeWorker;
+    /** Reject malformed binding globals or typed-error declarations as Service Definition contract misuse. */
+    private validateBindings;
+    /** Spawn the worker for one validated, type-stripped run and drive it to settlement. */
+    private execute;
+}
+export default WorkerThreadCodeRuntime;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-code-runtime-worker-thread`.
+ * @module @hydraharness/harness-code-runtime-worker-thread/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "code-runtime-worker-thread-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/output-json.d.ts

@@ -0,0 +1,26 @@
+/** JSON string-prefix accounting for the outer-output ledger. @module @hydraharness/harness-code-runtime-worker-thread/output-json */
+import type { CodeJsonValue } from '@hydraharness/harness-code-runtime';
+/**
+ * Measure one JSON string without materializing its complete escaped form.
+ * @param text - the candidate string.
+ * @param maxBytes - largest serialized size the caller can admit.
+ * @returns Exact serialized bytes, or `undefined` as soon as the cap is crossed.
+ */
+export declare function jsonStringBytesUpTo(text: string, maxBytes: number): number | undefined;
+/**
+ * Measure one lossless JSON value without allocating its serialized form.
+ * @param value - already validated lossless JSON.
+ * @param maxBytes - largest serialized size the caller can admit.
+ * @returns Exact serialized bytes, or `undefined` as soon as the cap is crossed.
+ */
+export declare function jsonValueBytesUpTo(value: CodeJsonValue, maxBytes: number): number | undefined;
+/**
+ * Return the longest code-point-aligned prefix whose JSON string encoding,
+ * including its surrounding quotes, fits `maxBytes`.
+ *
+ * @param text - the candidate string.
+ * @param maxBytes - serialized JSON-string bytes available.
+ * @returns the fitting prefix, or an empty string when even useful content cannot fit.
+ */
+export declare function truncateJsonStringBytes(text: string, maxBytes: number): string;
+//# sourceMappingURL=output-json.d.ts.map

package/lib/types/protocol.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Versionless, structured-clone wire protocol between co-shipped host and worker code. The host
+ * treats inbound traffic as hostile because model code can forge `parentPort` messages; the
+ * worker trusts host replies.
+ * @module @hydraharness/harness-code-runtime-worker-thread/src/protocol
+ */
+import type { WorkerJsonWire } from './worker-json.ts';
+/** What the host hands the worker at spawn, via `workerData`. */
+export interface WorkerBootData {
+    /** The type-stripped (plain JS) program body. */
+    code: string;
+    /** Binding namespaces to materialize; functions themselves stay host-side. */
+    namespaces: {
+        global: string;
+        names: string[];
+        errorClass?: {
+            name: string;
+            memberNameProperty: string;
+        };
+    }[];
+    /** Hard cap for the combined serialized outer logs plus completion value or failure diagnostic. */
+    maxOutputBytes: number;
+}
+/** Worker → host: one bridged binding call. */
+interface CallMessage {
+    type: 'call';
+    /** Worker-issued correlation id; the host answers each id at most once and ignores duplicates. */
+    id: number;
+    /** The namespace global the call targets. */
+    global: string;
+    /** The function name within the namespace. */
+    name: string;
+    /** The single argument as a flat lossless-JSON wire value. */
+    args: WorkerJsonWire;
+}
+/** Worker → host: captured text, streamed eagerly so output survives a mid-run termination (timeout, abort, OOM). */
+interface LogMessage {
+    type: 'log';
+    text: string;
+}
+/** Worker → host: worker-side capture or completion measurement exceeded the outer cap. */
+interface OutputLimitMessage {
+    type: 'output-limit';
+}
+/**
+ * Worker → host: the program settled. `error` carries a program exception,
+ * invalid completion, or output overflow (budgets, aborts, and substrate death
+ * are observed host-side). `value` is present only on a clean completion that
+ * produced one, as a flat wire value already lossless and admitted against
+ * the remaining combined output cap. Logs are NOT carried here — they streamed
+ * eagerly as {@link LogMessage}s.
+ */
+export interface DoneMessage {
+    type: 'done';
+    value?: WorkerJsonWire;
+    error?: {
+        kind: 'exception' | 'invalid-output' | 'output-limit';
+        message: string;
+    };
+}
+/** Every message the worker sends. */
+export type WorkerToHost = CallMessage | LogMessage | OutputLimitMessage | DoneMessage;
+/** Host → worker: the answer to one {@link CallMessage}. */
+export type ReplyMessage = {
+    type: 'reply';
+    id: number;
+    ok: true;
+    value: WorkerJsonWire;
+} | {
+    type: 'reply';
+    id: number;
+    ok: false;
+    message: string;
+};
+export {};
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -0,0 +1,46 @@
+/**
+ * Lossless-JSON snapshots for the dependency-free source worker closure.
+ * @module @hydraharness/harness-code-runtime-worker-thread/worker-json
+ */
+import type { CodeJsonValue } from '@hydraharness/harness-code-runtime';
+/**
+ * Validate and detach one worker-boundary value without loading another
+ * workspace package at runtime. This mirrors the session-owned canonical
+ * JSON boundary while remaining safe to import from the unbuilt worker.
+ * Its iterative traversal adds no JavaScript call-stack depth limit.
+ *
+ * @param value - the candidate completion value.
+ * @returns a detached lossless-JSON snapshot, or `undefined` when invalid.
+ */
+export declare function snapshotCodeJsonValue(value: unknown): CodeJsonValue | undefined;
+interface ArrayWireToken {
+    kind: 'array';
+    length: number;
+}
+interface ObjectWireToken {
+    kind: 'object';
+    keys: string[];
+}
+type WorkerJsonToken = null | boolean | number | string | ArrayWireToken | ObjectWireToken;
+/**
+ * A pre-order, bounded-depth transport for one lossless JSON value. Container
+ * markers and scalar leaves share one flat token array, so `worker_threads`
+ * never has to structured-clone the value's application nesting.
+ */
+export type WorkerJsonWire = WorkerJsonToken[];
+/**
+ * Flatten one validated JSON value for the worker-thread message port.
+ * @param value - the lossless JSON value to transport.
+ * @returns a pre-order token stream whose own nesting is bounded.
+ */
+export declare function encodeWorkerJson(value: CodeJsonValue): WorkerJsonWire;
+/**
+ * Rebuild one lossless JSON value from the flat worker-thread wire format.
+ * Malformed or incomplete traffic returns `undefined`; traversal is iterative
+ * and therefore independent of the transported value's application depth.
+ * @param input - untrusted message-port payload.
+ * @returns the detached JSON value, or `undefined` when the wire is invalid.
+ */
+export declare function decodeWorkerJson(input: unknown): CodeJsonValue | undefined;
+export {};
+//# sourceMappingURL=worker-json.d.ts.map

package/lib/types/worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Spawn-only worker entrypoint over {@link runWorkerMain}. Executable logic stays in
+ * `bootstrap.ts` for in-process coverage; real-worker tests cover this glue.
+ * @module @hydraharness/harness-code-runtime-worker-thread/src/worker
+ */
+export {};
+//# sourceMappingURL=worker.d.ts.map