cursedbelt-core 1.0.0

package/dist/core/wire/__fixtures__/rowsMarshalWorker.js

@@ -0,0 +1,23 @@
+/**
+ * A REAL marshalling worker entry, used by `marshalWorker.spec.ts` to prove the
+ * round-trip over an actual OS thread rather than over an injected fake.
+ *
+ * This is also the shape every production entry has, so it doubles as the
+ * reference an app author copies: construct the marshaller, hand it to
+ * `serveMarshalWorker`, done. The host never imports this file — it names it,
+ * and the worker imports it.
+ */
+import { z } from 'zod';
+import { serveMarshalWorker } from '../marshalWorker';
+const schema = z.object({ rows: z.array(z.object({ id: z.string() })) });
+await serveMarshalWorker({
+    id: 'rows',
+    validate: (inbound) => Array.isArray(inbound?.rows),
+    transform: (inbound) => {
+        // `boom` is the spec's hook for "the transform throws" — a worker must
+        // report that failure and stay alive for the next payload.
+        if (inbound.rows.some((row) => row.id === 'boom'))
+            throw new Error('transform exploded');
+        return { rows: inbound.rows.map((row) => ({ id: `worker:${row.id}` })) };
+    },
+});

package/dist/core/wire/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `cursedbelt-core/wire` — the wire tier's public surface.
+ *
+ * This entry exists because of Law #1, for the same reason `client/index.ts`
+ * gives that reason for `createWireHub`: an ingress route has to be able to
+ * IMPORT the marshalling seam, and a worker entry has to be able to import
+ * `serveMarshalWorker`. Until the Worker commit (05 §B1) neither symbol had any
+ * export path at all — `marshalInbound` was reachable only from inside this
+ * package, which is most of why it went three arcs with zero callers.
+ *
+ * `wireHub` is re-exported from `cursedbelt-cc/client` as well; that entry is where
+ * a shell host looks, this one is where the wire tier lives.
+ */
+export { type CCWireMarshaller, createMarshallerRegistry, MARSHALLER_PAYLOAD_TOO_LARGE, MARSHALLER_SCHEMA_VIOLATION, MARSHALLER_VALIDATION_FAILED, MARSHALLER_WORKER_OFFLOAD_BYTES, type MarshallerRegistry, type MarshalOptions, type MarshalWorker, marshalInbound, payloadBytes, requiresWorkerOffload, } from './marshalling';
+export { createMarshalWorkerClient, MARSHAL_WORKER_DEFAULT_TIMEOUT_MS, MARSHALLER_WORKER_FAILED, MARSHALLER_WORKER_TIMEOUT, type MarshalWorkerClient, type MarshalWorkerClientOptions, type MarshalWorkerRequest, type MarshalWorkerResponse, serveMarshalWorker, } from './marshalWorker';
+export { createMarshalledIngress, INGRESS_TOKEN_UNKNOWN, type MarshalledIngress, type MarshalledIngressOptions, } from './ingress';
+export { createInstanceRuntime, createWireHub, type InstanceRuntime, type InstanceRuntimeOptions, type WireEnvelope, type WireHub, type WireHubOptions, } from './wireHub';

package/dist/core/wire/index.js

@@ -0,0 +1,17 @@
+/**
+ * `cursedbelt-core/wire` — the wire tier's public surface.
+ *
+ * This entry exists because of Law #1, for the same reason `client/index.ts`
+ * gives that reason for `createWireHub`: an ingress route has to be able to
+ * IMPORT the marshalling seam, and a worker entry has to be able to import
+ * `serveMarshalWorker`. Until the Worker commit (05 §B1) neither symbol had any
+ * export path at all — `marshalInbound` was reachable only from inside this
+ * package, which is most of why it went three arcs with zero callers.
+ *
+ * `wireHub` is re-exported from `cursedbelt-cc/client` as well; that entry is where
+ * a shell host looks, this one is where the wire tier lives.
+ */
+export { createMarshallerRegistry, MARSHALLER_PAYLOAD_TOO_LARGE, MARSHALLER_SCHEMA_VIOLATION, MARSHALLER_VALIDATION_FAILED, MARSHALLER_WORKER_OFFLOAD_BYTES, marshalInbound, payloadBytes, requiresWorkerOffload, } from './marshalling';
+export { createMarshalWorkerClient, MARSHAL_WORKER_DEFAULT_TIMEOUT_MS, MARSHALLER_WORKER_FAILED, MARSHALLER_WORKER_TIMEOUT, serveMarshalWorker, } from './marshalWorker';
+export { createMarshalledIngress, INGRESS_TOKEN_UNKNOWN, } from './ingress';
+export { createInstanceRuntime, createWireHub, } from './wireHub';

package/dist/core/wire/ingress.d.ts

@@ -0,0 +1,44 @@
+import { type MarshallerRegistry } from './marshalling';
+/** No marshaller is registered for the token an ingress was asked to feed. */
+export declare const INGRESS_TOKEN_UNKNOWN = "INGRESS_TOKEN_UNKNOWN";
+export interface MarshalledIngressOptions {
+    /** The registry the app's wire tokens were registered on. */
+    readonly registry: MarshallerRegistry;
+    /**
+     * Per-payload worker ceiling. A marshalling worker that hangs would otherwise
+     * hold the request open for as long as the client is willing to wait.
+     */
+    readonly workerTimeoutMs?: number;
+    /**
+     * Spawn override — the seam a test uses to run the offload path without a real
+     * OS thread. Production never sets it.
+     */
+    readonly spawn?: (entry: string | URL) => unknown;
+}
+export interface MarshalledIngress {
+    /**
+     * Marshal an already-decoded payload for `tokenId`.
+     *
+     * @throws {AppError} `INGRESS_TOKEN_UNKNOWN` (404) when nothing is registered;
+     *   `MARSHALLER_PAYLOAD_TOO_LARGE` (413/503), `MARSHALLER_VALIDATION_FAILED`
+     *   (400) or `MARSHALLER_SCHEMA_VIOLATION` (502) from the marshaller itself.
+     */
+    ingest<Out = unknown>(tokenId: string, payload: unknown): Promise<Out>;
+    /**
+     * Read a `Request` body and marshal it for `tokenId`. JSON bodies are parsed;
+     * anything else is handed to the marshaller as bytes, because a marshaller for
+     * a CSV or a binary feed wants the bytes and re-encoding them would be lossy.
+     */
+    ingestRequest<Out = unknown>(tokenId: string, request: Request): Promise<Out>;
+    /**
+     * Stop every worker this ingress spawned. Idempotent. A host calls it on
+     * shutdown; forgetting to is a thread leak, which is why the ingress owns the
+     * threads rather than each route.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Build the ingress. One per app — it caches a worker per `workerEntry`, and two
+ * ingresses over the same registry would each spawn their own set.
+ */
+export declare const createMarshalledIngress: (options: MarshalledIngressOptions) => MarshalledIngress;

package/dist/core/wire/ingress.js

@@ -0,0 +1,134 @@
+/**
+ * The composable ingress seam (05 §B1, owner decision E16/D8) — the ONE thing
+ * between `marshalInbound` and a route that accepts external data.
+ *
+ * ## Why this exists rather than a webhook endpoint
+ *
+ * D8 asked which ingress should call `marshalInbound` first: an inbound webhook,
+ * a CSV/spreadsheet import, or neither. The owner delegated the choice with a
+ * binding condition — *"ensure the architecture is ready to add it later, so we
+ * don't have to refactor and can just build on top of it."*
+ *
+ * The answer is neither, yet, and the condition is the deliverable. Shipping a
+ * webhook endpoint that no product asked for would create a new orphan seam of
+ * exactly the kind Law #1 exists to prevent, and it would guess wrong about the
+ * part that actually differs between a webhook and an import (authentication,
+ * routing, what the marshalled value is handed to). What does NOT differ — and
+ * what every ingress would otherwise re-derive, differently — is this:
+ *
+ *   1. reading the body as bytes without buffering a stream into RAM twice;
+ *   2. finding the marshaller for the token being fed;
+ *   3. owning a worker per `workerEntry` — a live OS thread, so exactly one
+ *      thing must own disposing of it — and resolving it lazily and cached;
+ *   4. handing those failures up as errors that already KNOW their HTTP status,
+ *      so no route re-derives the mapping. The marshalling tier's codes are
+ *      unchanged and deliberately distinct: 413 over the declared ceiling, 400
+ *      for a payload `validate` refuses (the caller's shape is wrong), 502 when
+ *      the TRANSFORM OUTPUT violates the token's canonical schema (an upstream
+ *      provider changed shape under us — not our error budget), 503 for a
+ *      payload that needs offload from a marshaller with no worker.
+ *
+ * Step 3 is the one that would go wrong. `createMarshalWorkerClient` spawns a
+ * thread per call; a route handler that called it per request would leak one
+ * OS thread per webhook, and the symptom would be a server that gets slower for
+ * a week and then dies. Nothing about that is discoverable from the marshalling
+ * API, which is precisely why it belongs here once instead of in each ingress.
+ *
+ * ## Adding an ingress later
+ *
+ * It is a route, not a refactor:
+ *
+ * ```ts
+ * const ingress = createMarshalledIngress({ registry });
+ * app.post('/api/hooks/:token', session, async (c) => {
+ *   const value = await ingress.ingestRequest(c.req.param('token'), c.req.raw);
+ *   await service.acceptExternal(scopeOf(c), value);
+ *   return c.json({ success: true }, 202);
+ * });
+ * ```
+ *
+ * A CSV import is the same three lines with a different marshaller and a
+ * different service call. Neither needs to know that a worker exists.
+ */
+import { AppError } from '../../shared/errors';
+import { createMarshalWorkerClient } from './marshalWorker';
+import { marshalInbound, } from './marshalling';
+/** No marshaller is registered for the token an ingress was asked to feed. */
+export const INGRESS_TOKEN_UNKNOWN = 'INGRESS_TOKEN_UNKNOWN';
+/**
+ * Build the ingress. One per app — it caches a worker per `workerEntry`, and two
+ * ingresses over the same registry would each spawn their own set.
+ */
+export const createMarshalledIngress = (options) => {
+    /** entry → client. The cache IS the point: see the header, step 3. */
+    const workers = new Map();
+    let disposed = false;
+    const resolveWorker = (marshaller) => {
+        const entry = marshaller.workerEntry;
+        if (entry === undefined)
+            return undefined;
+        if (disposed)
+            throw new AppError('This ingress has been disposed and cannot spawn a marshalling worker.', {
+                code: 'INGRESS_DISPOSED',
+                status: 503,
+                isOperational: false,
+                context: { marshaller: marshaller.id },
+            });
+        const existing = workers.get(entry);
+        if (existing)
+            return existing;
+        const client = createMarshalWorkerClient({
+            entry,
+            ...(options.workerTimeoutMs === undefined ? {} : { timeoutMs: options.workerTimeoutMs }),
+            ...(options.spawn === undefined ? {} : { spawn: options.spawn }),
+        });
+        workers.set(entry, client);
+        return client;
+    };
+    const marshallerFor = (tokenId) => {
+        const marshaller = options.registry.forToken(tokenId);
+        if (!marshaller)
+            // 404, not 400: from outside, a token with no marshaller and a token that
+            // does not exist are the same fact, and distinguishing them would make
+            // this endpoint an enumeration oracle for the app's wire surface.
+            throw new AppError(`No marshaller is registered for wire token '${tokenId}'.`, {
+                code: INGRESS_TOKEN_UNKNOWN,
+                status: 404,
+                context: { tokenId },
+            });
+        return marshaller;
+    };
+    return {
+        async ingest(tokenId, payload) {
+            return (await marshalInbound(marshallerFor(tokenId), payload, {
+                resolveWorker,
+            }));
+        },
+        async ingestRequest(tokenId, request) {
+            const contentType = request.headers.get('content-type') ?? '';
+            // JSON is parsed here so the marshaller sees a value rather than a string
+            // it would have to parse itself (and parse DIFFERENTLY per marshaller).
+            // A malformed body is the CALLER's error — 400 — and must not read as a
+            // validation failure of a payload we never managed to decode.
+            const payload = contentType.includes('application/json')
+                ? await request.json().catch(() => {
+                    throw new AppError('Request body is not valid JSON.', {
+                        code: 'INGRESS_BODY_MALFORMED',
+                        status: 400,
+                        context: { tokenId, contentType },
+                    });
+                })
+                : new Uint8Array(await request.arrayBuffer());
+            return await this.ingest(tokenId, payload);
+        },
+        async dispose() {
+            disposed = true;
+            const clients = [...workers.values()];
+            workers.clear();
+            // `allSettled`: one thread that refuses to die must not prevent the rest
+            // from being reaped, and a shutdown path that throws leaves the others
+            // running forever.
+            await Promise.allSettled(clients.map((client) => client.dispose()));
+        },
+    };
+};

package/dist/core/wire/marshalWorker.d.ts

@@ -0,0 +1,70 @@
+import { type CCWireMarshaller, MARSHALLER_SCHEMA_VIOLATION, MARSHALLER_VALIDATION_FAILED, type MarshalWorker } from './marshalling';
+export declare const MARSHALLER_WORKER_FAILED = "MARSHALLER_WORKER_FAILED";
+export declare const MARSHALLER_WORKER_TIMEOUT = "MARSHALLER_WORKER_TIMEOUT";
+/** How long one payload may occupy the worker before the host gives up. */
+export declare const MARSHAL_WORKER_DEFAULT_TIMEOUT_MS = 30000;
+export interface MarshalWorkerRequest {
+    /** Correlates the reply — several payloads are in flight at once. */
+    id: number;
+    payload: unknown;
+}
+export type MarshalWorkerResponse = {
+    id: number;
+    ok: true;
+    value: unknown;
+} | {
+    id: number;
+    ok: false;
+    code: string;
+    message: string;
+};
+/**
+ * Run `marshaller` inside a worker, answering one payload per message.
+ *
+ * A worker entry is three lines:
+ *
+ * ```ts
+ * import { serveMarshalWorker } from 'cursedbelt-core/wire';
+ * import { sheetRowsMarshaller } from './sheetRows';
+ * await serveMarshalWorker(sheetRowsMarshaller);
+ * ```
+ *
+ * **The schema check is deliberately NOT run here.** `marshalInbound` re-checks
+ * every worker result against the token's canonical schema on the host side,
+ * because a worker is a thread boundary, not a trust boundary — a result that
+ * validated itself is exactly the kind of assurance that stops being true the
+ * day someone edits the worker entry. Doing it in both places would also mean
+ * two implementations of one law, and the worker's copy is the one no test
+ * would cover.
+ */
+export declare function serveMarshalWorker<Inbound, Out>(marshaller: Pick<CCWireMarshaller<Inbound, Out>, 'id' | 'validate' | 'transform'>): Promise<void>;
+/** The subset of both runtimes' Worker the client below needs. */
+interface HostWorker {
+    post(data: unknown): void;
+    onMessage(handler: (data: unknown) => void): void;
+    onError(handler: (error: unknown) => void): void;
+    terminate(): void;
+}
+export interface MarshalWorkerClientOptions {
+    /** Module specifier / URL of the entry that calls {@link serveMarshalWorker}. */
+    entry: string | URL;
+    /** Per-payload ceiling. Defaults to {@link MARSHAL_WORKER_DEFAULT_TIMEOUT_MS}. */
+    timeoutMs?: number;
+    /** Spawn override — the seam tests use to run without a real thread. */
+    spawn?: (entry: string | URL) => HostWorker;
+}
+export interface MarshalWorkerClient extends MarshalWorker {
+    /** Stop the thread. Pending payloads reject; further calls are refused. */
+    dispose(): Promise<void>;
+}
+/**
+ * A long-lived worker for ONE marshaller, multiplexing concurrent payloads.
+ *
+ * Long-lived rather than one-worker-per-payload deliberately: thread startup
+ * plus module load is tens of milliseconds, which on a burst of imports would
+ * cost more than the parse it is avoiding, and a spawn-per-payload design lets
+ * an import storm fork unbounded threads.
+ */
+export declare function createMarshalWorkerClient(options: MarshalWorkerClientOptions): MarshalWorkerClient;
+/** Re-exported so a caller catching worker failures needs one import. */
+export { MARSHALLER_SCHEMA_VIOLATION, MARSHALLER_VALIDATION_FAILED };

package/dist/core/wire/marshalWorker.js

@@ -0,0 +1,273 @@
+/**
+ * The marshalling Worker (05 §B1, second half) — `validate` + `transform` for a
+ * large inbound payload, off the thread that has to answer requests.
+ *
+ * `marshalling.ts` has always had the SIZE BOUNDARY and the injection seam; what
+ * it never had was anything to hand a large payload to, so a >512KB webhook body
+ * got a 503 with no documentation anywhere that a limit existed. This module is
+ * the missing half: a real, long-lived worker with a request/response protocol,
+ * on both runtimes cursedbelt ships to.
+ *
+ * ## Why the marshaller names its own worker entry
+ *
+ * A marshaller is mostly FUNCTIONS (`validate`, `transform`, a Zod schema), and
+ * functions do not survive structured clone — a worker cannot be handed one, it
+ * has to `import` it. The obvious design (one shared worker that resolves any
+ * marshaller by id from a registry module) needs the host to declare, register
+ * and keep in sync a second module listing every marshaller, and it gives that
+ * one worker the authority to run all of them.
+ *
+ * Instead each marshaller declares `workerEntry`: the module that constructs
+ * exactly that marshaller and calls {@link serveMarshalWorker}. The worker can
+ * therefore only ever run the one marshaller it was built for, the host wires
+ * nothing, and — the part that matters for the gate — "can this marshaller
+ * offload?" stops being a boolean somebody remembered to set and becomes a
+ * question about an artifact that either exists or does not. V3 checks it
+ * statically (`marshaller-worker-offload-missing`), so the 503 path below is
+ * unreachable in any app that passed verification.
+ *
+ * ## The two runtimes
+ *
+ * Server (Bun/Node) uses `node:worker_threads`; the browser uses a module
+ * `Worker`. The import of `node:worker_threads` is deliberately DYNAMIC and
+ * inside the server branch — a static import would put a Node builtin in the
+ * module graph of every client bundle that touches wire code.
+ */
+import { AppError } from '../../shared/errors';
+import { MARSHALLER_SCHEMA_VIOLATION, MARSHALLER_VALIDATION_FAILED, } from './marshalling';
+export const MARSHALLER_WORKER_FAILED = 'MARSHALLER_WORKER_FAILED';
+export const MARSHALLER_WORKER_TIMEOUT = 'MARSHALLER_WORKER_TIMEOUT';
+/** How long one payload may occupy the worker before the host gives up. */
+export const MARSHAL_WORKER_DEFAULT_TIMEOUT_MS = 30_000;
+async function resolveWorkerChannel() {
+    // Browser/Web Worker: `self` has postMessage and no `window`.
+    const maybeSelf = globalThis;
+    if (maybeSelf.window === undefined &&
+        typeof maybeSelf.postMessage === 'function' &&
+        typeof maybeSelf.addEventListener === 'function') {
+        const post = maybeSelf.postMessage.bind(globalThis);
+        const listen = maybeSelf.addEventListener.bind(globalThis);
+        return {
+            onMessage: (handler) => listen('message', (event) => handler(event.data)),
+            post,
+        };
+    }
+    const { parentPort } = await import('node:worker_threads');
+    if (!parentPort)
+        throw new AppError('serveMarshalWorker was called outside a worker thread.', {
+            code: MARSHALLER_WORKER_FAILED,
+            status: 500,
+        });
+    return {
+        onMessage: (handler) => parentPort.on('message', handler),
+        post: (data) => parentPort.postMessage(data),
+    };
+}
+/**
+ * Run `marshaller` inside a worker, answering one payload per message.
+ *
+ * A worker entry is three lines:
+ *
+ * ```ts
+ * import { serveMarshalWorker } from 'cursedbelt-core/wire';
+ * import { sheetRowsMarshaller } from './sheetRows';
+ * await serveMarshalWorker(sheetRowsMarshaller);
+ * ```
+ *
+ * **The schema check is deliberately NOT run here.** `marshalInbound` re-checks
+ * every worker result against the token's canonical schema on the host side,
+ * because a worker is a thread boundary, not a trust boundary — a result that
+ * validated itself is exactly the kind of assurance that stops being true the
+ * day someone edits the worker entry. Doing it in both places would also mean
+ * two implementations of one law, and the worker's copy is the one no test
+ * would cover.
+ */
+export async function serveMarshalWorker(marshaller) {
+    const channel = await resolveWorkerChannel();
+    channel.onMessage((data) => {
+        const request = data;
+        if (typeof request?.id !== 'number')
+            return; // not ours; ignore rather than crash the worker
+        try {
+            if (!marshaller.validate(request.payload)) {
+                channel.post({
+                    id: request.id,
+                    ok: false,
+                    code: MARSHALLER_VALIDATION_FAILED,
+                    message: `Inbound payload rejected by marshaller '${marshaller.id}'.`,
+                });
+                return;
+            }
+            const value = marshaller.transform(request.payload);
+            channel.post({ id: request.id, ok: true, value });
+        }
+        catch (error) {
+            // A throwing transform must not take the worker down with it: the next
+            // payload is a different payload, and a dead worker turns one bad webhook
+            // into an outage.
+            channel.post({
+                id: request.id,
+                ok: false,
+                code: MARSHALLER_WORKER_FAILED,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    });
+}
+function spawnHostWorker(entry) {
+    const WebWorker = globalThis
+        .Worker;
+    // A browser (or Bun's web-Worker shim) — `type: 'module'` so the entry may use
+    // static imports, which every entry will.
+    if (typeof WebWorker === 'function') {
+        const worker = new WebWorker(entry, { type: 'module' });
+        return {
+            post: (data) => worker.postMessage(data),
+            onMessage: (handler) => worker.addEventListener('message', (event) => handler(event.data)),
+            onError: (handler) => worker.addEventListener('error', (event) => handler(event.message ?? event)),
+            terminate: () => worker.terminate(),
+        };
+    }
+    // Node/Bun worker_threads. Constructed lazily and synchronously-wrapped: the
+    // client below queues sends until the thread exists, so callers never see the
+    // construction race.
+    let pending = [];
+    let realPost = null;
+    let terminated = false;
+    const messageHandlers = [];
+    const errorHandlers = [];
+    let terminateReal = null;
+    void (async () => {
+        try {
+            const { Worker } = await import('node:worker_threads');
+            if (terminated)
+                return;
+            const worker = new Worker(entry);
+            worker.on('message', (data) => {
+                for (const handler of messageHandlers)
+                    handler(data);
+            });
+            worker.on('error', (error) => {
+                for (const handler of errorHandlers)
+                    handler(error);
+            });
+            // ANY exit is a failure for this client: the worker is long-lived by
+            // design, so it should outlive every payload. Gating this on `code !== 0`
+            // left a cleanly-exited thread invisible — payloads in flight waited out
+            // their full timeout instead of failing at once, and every later `run()`
+            // posted into a dead thread and did the same.
+            worker.on('exit', (code) => {
+                const how = code === 0 ? 'exited cleanly while still in use' : `exited with code ${code}`;
+                for (const handler of errorHandlers)
+                    handler(new Error(`marshal worker ${how}`));
+            });
+            // `unref` would let the process exit with payloads in flight; the client's
+            // own timeout is the liveness backstop instead.
+            realPost = (data) => worker.postMessage(data);
+            terminateReal = () => void worker.terminate();
+            for (const queued of pending)
+                realPost(queued);
+            pending = [];
+        }
+        catch (error) {
+            for (const handler of errorHandlers)
+                handler(error);
+        }
+    })();
+    return {
+        post: (data) => (realPost ? realPost(data) : pending.push(data)),
+        onMessage: (handler) => messageHandlers.push(handler),
+        onError: (handler) => errorHandlers.push(handler),
+        terminate: () => {
+            terminated = true;
+            terminateReal?.();
+        },
+    };
+}
+/**
+ * A long-lived worker for ONE marshaller, multiplexing concurrent payloads.
+ *
+ * Long-lived rather than one-worker-per-payload deliberately: thread startup
+ * plus module load is tens of milliseconds, which on a burst of imports would
+ * cost more than the parse it is avoiding, and a spawn-per-payload design lets
+ * an import storm fork unbounded threads.
+ */
+export function createMarshalWorkerClient(options) {
+    const timeoutMs = options.timeoutMs ?? MARSHAL_WORKER_DEFAULT_TIMEOUT_MS;
+    const worker = (options.spawn ?? spawnHostWorker)(options.entry);
+    const pending = new Map();
+    let nextId = 1;
+    let disposed = false;
+    const settle = (id, apply) => {
+        const entry = pending.get(id);
+        if (!entry)
+            return; // already timed out — the late reply is discarded
+        pending.delete(id);
+        clearTimeout(entry.timer);
+        apply(entry);
+    };
+    worker.onMessage((data) => {
+        const response = data;
+        if (typeof response?.id !== 'number')
+            return;
+        settle(response.id, (p) => {
+            if (response.ok) {
+                p.resolve(response.value);
+                return;
+            }
+            p.reject(new AppError(response.message, {
+                // A validation failure is the CALLER's fault (400) and must keep its
+                // own code; anything else the worker reports is ours (500).
+                code: response.code,
+                status: response.code === MARSHALLER_VALIDATION_FAILED ? 400 : 500,
+                context: { worker: String(options.entry) },
+            }));
+        });
+    });
+    // A worker that dies takes every payload in flight with it — failing them all
+    // now beats each one waiting out its own timeout.
+    worker.onError((error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        for (const id of [...pending.keys()])
+            settle(id, (p) => p.reject(new AppError(`Marshalling worker failed: ${message}`, {
+                code: MARSHALLER_WORKER_FAILED,
+                status: 500,
+                context: { worker: String(options.entry) },
+            })));
+    });
+    return {
+        run(_marshallerId, payload) {
+            if (disposed)
+                return Promise.reject(new AppError('Marshalling worker has been disposed.', {
+                    code: MARSHALLER_WORKER_FAILED,
+                    status: 500,
+                    context: { worker: String(options.entry) },
+                }));
+            const id = nextId++;
+            return new Promise((resolve, reject) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    reject(new AppError(`Marshalling worker did not answer within ${timeoutMs}ms.`, {
+                        code: MARSHALLER_WORKER_TIMEOUT,
+                        status: 504,
+                        context: { worker: String(options.entry), timeoutMs },
+                    }));
+                }, timeoutMs);
+                pending.set(id, { resolve: resolve, reject, timer });
+                worker.post({ id, payload });
+            });
+        },
+        async dispose() {
+            disposed = true;
+            for (const id of [...pending.keys()])
+                settle(id, (p) => p.reject(new AppError('Marshalling worker was disposed while a payload was in flight.', {
+                    code: MARSHALLER_WORKER_FAILED,
+                    status: 503,
+                    context: { worker: String(options.entry) },
+                })));
+            worker.terminate();
+        },
+    };
+}
+/** Re-exported so a caller catching worker failures needs one import. */
+export { MARSHALLER_SCHEMA_VIOLATION, MARSHALLER_VALIDATION_FAILED };