@volter/world-core 2.0.0

package/dist/src/serve-http.js

@@ -0,0 +1,340 @@
+// The HTTP server seam of the kernel (docs/contributing/architecture.md#the-serve-seam): a fetch handler on
+// a port, in the shape every `Bun.serve` call already has, so the serve path meets the runtime in
+// ONE place. Bun-backed where Bun is the runtime; `node:http`-backed otherwise, the request rebuilt
+// as a standard Request and the handler's Response written back. Async, because binding a port is
+// asynchronous on Node — Bun's synchronous bind is the special case.
+//
+// Nothing here runs at module scope, and `node:http` is reached through `process.getBuiltinModule`
+// rather than a static import: this module rides into mirror-UI client bundles through the kernel's
+// entrypoint, where a static `node:` import is the 2026-09-06 class of break.
+/** A decorator the request journal installs: every server made through the seam serves through it. */
+let decorate;
+export function setServeDecorator(fn) { decorate = fn; }
+const bunRuntime = () => { const b = globalThis.Bun; return b && typeof b.serve === 'function' ? b : undefined; };
+/** The path a World asks a service it booted, when that service's port answers, which boot it belongs to. */
+export const WORLD_BOOT_PATH = '/__volter/world-boot';
+export async function serveHttp(options) {
+    // Inside a World every server made through the seam answers which boot it belongs to, so the World can tell its own
+    // twin from a leftover World's that holds the same port. Outside a World nothing changes.
+    const worldBoot = globalThis.process?.env?.VOLTER_WORLD_BOOT_ID;
+    if (worldBoot) {
+        const served = options.fetch;
+        options = { ...options, fetch: (request) => (new URL(request.url).pathname === WORLD_BOOT_PATH ? Response.json({ boot: worldBoot }) : served(request)) };
+    }
+    // loopback by default: an unnamed interface is never every interface
+    const hostname = options.hostname ?? '127.0.0.1';
+    const urlHost = options.hostname ?? '127.0.0.1';
+    const bun = bunRuntime();
+    if (bun) {
+        // the global `Bun.serve` — the request journal's wrap of it (serve.ts) applies to packs and to
+        // this seam alike, so the seam never decorates twice on Bun
+        const upgrade = options.upgrade;
+        const server = bun.serve({ ...options, hostname, port: options.port ?? 0,
+            ...(upgrade ? {
+                fetch: (request, server) => {
+                    if (request.headers.get('upgrade')?.toLowerCase() === 'websocket' && upgrade.accepts(request) && server.upgrade(request, { data: { request } }))
+                        return undefined;
+                    return options.fetch(request);
+                },
+                websocket: {
+                    open: (peer) => upgrade.open(peer, peer.data.request),
+                    message: (peer, data) => upgrade.message(peer, data),
+                    close: upgrade.close,
+                },
+            } : {}),
+        });
+        const port = server.port ?? 0;
+        return { hostname, port, url: server.url instanceof URL ? server.url : new URL(`http://${urlHost}:${port}/`), stop: async (closeActive = true) => { await server.stop(closeActive); } };
+    }
+    return serveOnNode({ ...options, hostname, urlHost, fetch: decorate ? decorate(options) : options.fetch });
+}
+/** A Node builtin without a static import — `process.getBuiltinModule` (Node 22.3+, Bun): what a
+ *  module that also rides into a browser bundle reaches `node:crypto` with. A bare `require()`
+ *  is Bun's alone; Node's ESM has none (found 2026-09-07 by the pages running under node). */
+export function nodeBuiltin(name) { return builtin(name); }
+function builtin(name) {
+    const get = process.getBuiltinModule;
+    if (typeof get !== 'function')
+        throw new Error(`serveHttp: this runtime is neither Bun nor a Node with process.getBuiltinModule (Node 22.3+)`);
+    return get(name);
+}
+async function serveOnNode(options) {
+    const http = builtin('node:http');
+    const { Readable } = builtin('node:stream');
+    if ('websocket' in options)
+        throw new Error('serveHttp: use the portable upgrade callbacks for WebSocket support on Node');
+    const protocol = options.tls ? 'https' : 'http';
+    const factory = (handler) => options.tls
+        ? builtin('node:https').createServer({ key: typeof options.tls.key === 'string' ? options.tls.key : Buffer.from(options.tls.key), cert: typeof options.tls.cert === 'string' ? options.tls.cert : Buffer.from(options.tls.cert) }, handler)
+        : http.createServer(handler);
+    let cleanupReports = 0;
+    const reportCleanup = (stage, error) => {
+        // A disconnected peer cannot receive an error response. Keep bounded
+        // ownership evidence without printing request URLs, headers or bodies.
+        cleanupReports++;
+        if (cleanupReports > 32) {
+            if (cleanupReports === 33)
+                try {
+                    process.stderr.write('serveHttp further cleanup failures suppressed\n');
+                }
+                catch { /* best-effort */ }
+            return;
+        }
+        let detail = 'unknown failure';
+        try {
+            detail = error instanceof Error
+                ? `${error.name.slice(0, 64)}: ${error.message.slice(0, 512)}`
+                : String(error).slice(0, 512);
+        }
+        catch { /* hostile thrown values are still reported by stage */ }
+        try {
+            process.stderr.write(`serveHttp ${stage}: ${detail.slice(0, 512)}\n`);
+        }
+        catch { /* stderr is best-effort */ }
+    };
+    const active = new Set();
+    // Node's Request signal is dependent on the source signal. Neither a pending
+    // handler nor a streaming response necessarily keeps the Request alive, so
+    // retain it until the whole HTTP response path (including body cleanup) ends.
+    const activeRequests = new Set();
+    const server = factory((req, res) => {
+        const controller = new AbortController();
+        active.add(controller);
+        const abort = () => { if (!controller.signal.aborted)
+            controller.abort(); };
+        const onRequestClose = () => { if (!req.complete)
+            abort(); };
+        const onResponseClose = () => { if (!res.writableFinished)
+            abort(); };
+        const onSocketClose = () => { if (!res.writableFinished)
+            abort(); };
+        req.on('aborted', abort);
+        req.on('close', onRequestClose);
+        req.on('error', abort);
+        req.socket.on('close', onSocketClose);
+        req.socket.on('error', abort);
+        res.on('close', onResponseClose);
+        res.on('error', abort);
+        const disconnected = () => controller.signal.aborted || res.destroyed;
+        const cancelBody = async (body) => {
+            if (!body)
+                return;
+            try {
+                await body.cancel(controller.signal.reason);
+            }
+            catch (error) {
+                reportCleanup('late response body cancellation failed', error);
+            }
+        };
+        const waitForDrain = () => new Promise((resolve, reject) => {
+            if (disconnected()) {
+                reject(new Error('HTTP client disconnected'));
+                return;
+            }
+            const retire = () => {
+                res.off('drain', drained);
+                res.off('close', closed);
+                res.off('error', errored);
+                controller.signal.removeEventListener('abort', closed);
+            };
+            const drained = () => { retire(); resolve(); };
+            const closed = () => { retire(); reject(new Error('HTTP client disconnected')); };
+            const errored = (error) => { retire(); reject(error); };
+            res.once('drain', drained);
+            res.once('close', closed);
+            res.once('error', errored);
+            controller.signal.addEventListener('abort', closed, { once: true });
+            if (disconnected())
+                closed();
+        });
+        let request;
+        const handle = async () => {
+            const method = req.method ?? 'GET';
+            let response;
+            try {
+                const headers = new Headers();
+                for (const [k, v] of Object.entries(req.headers)) {
+                    if (v === undefined)
+                        continue;
+                    if (Array.isArray(v))
+                        for (const one of v)
+                            headers.append(k, one);
+                    else
+                        headers.set(k, v);
+                }
+                const url = `${protocol}://${req.headers.host ?? `${options.hostname}:${server.address()?.port ?? 0}`}${req.url ?? '/'}`;
+                const withBody = method !== 'GET' && method !== 'HEAD';
+                const init = { method, headers, signal: controller.signal, ...(withBody ? { body: Readable.toWeb(req), duplex: 'half' } : {}) };
+                request = new Request(url, init);
+                activeRequests.add(request);
+                response = await options.fetch(request);
+            }
+            catch (error) {
+                if (disconnected())
+                    return;
+                // Preserve the existing Bun-shaped pre-header error hook and default 500.
+                const err = error instanceof Error ? error : new Error(String(error));
+                try {
+                    response = options.error ? await options.error(err) : new Response(`${err.stack ?? err.message}\n`, { status: 500, headers: { 'content-type': 'text/plain' } });
+                }
+                catch (again) {
+                    response = new Response(`${again instanceof Error ? again.stack ?? again.message : String(again)}\n`, { status: 500, headers: { 'content-type': 'text/plain' } });
+                }
+            }
+            if (disconnected()) {
+                await cancelBody(response.body);
+                return;
+            }
+            let reader;
+            let cancelReader;
+            const cancelOwnedReader = () => {
+                if (!reader)
+                    return Promise.resolve();
+                if (!cancelReader) {
+                    cancelReader = Promise.resolve().then(() => reader.cancel(controller.signal.reason)).catch((error) => {
+                        reportCleanup('response reader cancellation failed', error);
+                    });
+                }
+                return cancelReader;
+            };
+            const onAbort = () => { void cancelOwnedReader(); };
+            try {
+                if (method === 'HEAD') {
+                    // A HEAD body is never sent, but its producer is still ours to stop.
+                    // Failure here is not a successful response completion.
+                    try {
+                        await response.body?.cancel(controller.signal.reason);
+                    }
+                    catch (error) {
+                        reportCleanup('HEAD response body cancellation failed', error);
+                        throw error;
+                    }
+                    if (!disconnected()) {
+                        res.statusCode = response.status;
+                        for (const [k, v] of response.headers) {
+                            if (k !== 'set-cookie')
+                                res.setHeader(k, v);
+                        }
+                        const cookies = response.headers.getSetCookie?.() ?? [];
+                        if (cookies.length)
+                            res.setHeader('set-cookie', cookies);
+                        res.end();
+                    }
+                    return;
+                }
+                if (response.body)
+                    reader = response.body.getReader();
+                controller.signal.addEventListener('abort', onAbort, { once: true });
+                if (disconnected()) {
+                    await cancelOwnedReader();
+                    return;
+                }
+                res.statusCode = response.status;
+                for (const [k, v] of response.headers) {
+                    if (k !== 'set-cookie')
+                        res.setHeader(k, v);
+                }
+                const cookies = response.headers.getSetCookie?.() ?? [];
+                if (cookies.length)
+                    res.setHeader('set-cookie', cookies);
+                if (reader) {
+                    while (true) {
+                        if (disconnected())
+                            throw new Error('HTTP client disconnected');
+                        const next = await reader.read();
+                        if (disconnected())
+                            throw new Error('HTTP client disconnected');
+                        if (next.done)
+                            break;
+                        if (!res.write(next.value))
+                            await waitForDrain();
+                    }
+                }
+                if (!disconnected())
+                    res.end();
+            }
+            catch (error) {
+                // Once headers/body may have gone out, a second error response or clean EOF is false.
+                abort();
+                if (!res.destroyed)
+                    res.destroy(error instanceof Error ? error : new Error(String(error)));
+            }
+            finally {
+                controller.signal.removeEventListener('abort', onAbort);
+                if (reader) {
+                    if (controller.signal.aborted)
+                        await cancelOwnedReader();
+                    try {
+                        reader.releaseLock();
+                    }
+                    catch (error) {
+                        reportCleanup('response reader release failed', error);
+                    }
+                }
+            }
+        };
+        const responseSettled = new Promise((resolve) => {
+            const settled = () => {
+                res.off('finish', settled);
+                res.off('close', settled);
+                resolve();
+            };
+            res.once('finish', settled);
+            res.once('close', settled);
+            if (res.writableFinished || res.destroyed)
+                settled();
+        });
+        void handle().finally(() => {
+            if (request)
+                activeRequests.delete(request);
+        }).catch((error) => {
+            abort();
+            if (!res.destroyed)
+                res.destroy(error instanceof Error ? error : new Error(String(error)));
+        }).then(async () => {
+            await responseSettled;
+            active.delete(controller);
+            req.off('aborted', abort);
+            req.off('close', onRequestClose);
+            req.off('error', abort);
+            req.socket.off('close', onSocketClose);
+            req.socket.off('error', abort);
+            res.off('close', onResponseClose);
+            res.off('error', abort);
+        });
+    });
+    let socketServer;
+    if (options.upgrade) {
+        const { WebSocketServer } = await import('ws');
+        socketServer = new WebSocketServer({ noServer: true });
+        const upgrade = options.upgrade;
+        server.on('upgrade', (req, socket, head) => {
+            const request = new Request(`${protocol}://${req.headers.host ?? 'localhost'}${req.url ?? '/'}`, { headers: Object.fromEntries(Object.entries(req.headers).filter((entry) => typeof entry[1] === 'string')) });
+            if (!upgrade.accepts(request)) {
+                socket.end('HTTP/1.1 404 Not Found\r\nConnection: close\r\nContent-Length: 0\r\n\r\n');
+                return;
+            }
+            socketServer.handleUpgrade(req, socket, head, (peer) => {
+                peer.on('message', (data, binary) => { const bytes = Array.isArray(data) ? Buffer.concat(data) : data instanceof ArrayBuffer ? new Uint8Array(data) : data; Promise.resolve(upgrade.message(peer, binary ? new Uint8Array(bytes) : Buffer.from(bytes).toString())).catch(() => peer.close(1011, 'handler failed')); });
+                peer.on('close', () => upgrade.close(peer));
+                peer.on('error', () => peer.close());
+                upgrade.open(peer, request);
+            });
+        });
+    }
+    if (options.idleTimeout !== undefined)
+        server.keepAliveTimeout = options.idleTimeout * 1000;
+    await new Promise((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, options.hostname, () => { server.off('error', reject); resolve(); }); });
+    const port = server.address().port;
+    return {
+        hostname: options.hostname, port, url: new URL(`${protocol}://${options.urlHost}:${port}/`),
+        stop: (closeActive = true) => new Promise((resolve) => { if (closeActive) {
+            for (const controller of active)
+                controller.abort();
+            for (const peer of socketServer?.clients ?? [])
+                peer.terminate();
+        } socketServer?.close(); server.close(() => { if (closeActive && active.size)
+            reportCleanup('forced stop left pending handler cleanup', `${active.size} request(s)`); resolve(); }); if (closeActive)
+            server.closeAllConnections(); }),
+    };
+}

package/dist/src/serve.d.ts

@@ -0,0 +1,147 @@
+import type { SubjectFields } from './hash.js';
+import type { ActionProjection, TwinActionPrecondition } from './actions.js';
+export type TwinCredentialShape = {
+    /** header name (lowercased) or query-param name the credential arrived under. */
+    name: string;
+    /** where it sat on the request. */
+    in: 'header' | 'query';
+    /** the auth SCHEME when the value carried one (`Bearer`, `Basic`, `AWS4-HMAC-SHA256`). A scheme
+     *  is not a secret, and it is what distinguishes "a bearer token arrived" from "a named vendor
+     *  header arrived" — the exact confusion this journal was added to end. */
+    scheme?: string;
+    /** `sha256:<16 hex>` of the value (of the credential part when a scheme was present). Stable
+     *  across processes and runs, so equal fingerprints mean equal values; non-reversible. */
+    fp?: string;
+    /** the name arrived with an EMPTY value — the "the SDK sent the header but no key" case. */
+    empty?: true;
+};
+export type TwinRequestJournalEntry = {
+    at?: string;
+    method: string;
+    path: string;
+    status: number;
+    /** the serve's wall time in milliseconds (layer 8: a world's response-time report) */
+    ms?: number;
+    /** credential-looking headers/query params that arrived, named + fingerprinted, never quoted. */
+    credentials?: TwinCredentialShape[];
+};
+/** The journal read back: every entry kept for a service, oldest first (an empty list when the journal is off or empty). */
+export declare function readTwinRequestJournal(service: string, root?: string): TwinRequestJournalEntry[];
+/** Non-reversible, stable fingerprint. 64 bits of sha256 — enough that two distinct credentials
+ *  never collide in a journal, far too little to walk back to a real key. */
+export declare function credentialFingerprint(value: string): string;
+/**
+ * The credential SHAPE of one request: every credential-looking header and query param, named and
+ * fingerprinted, sorted for stable diffing. Values never leave this function.
+ */
+export declare function twinRequestCredentials(headers: Headers | Record<string, string>, url?: string | URL): TwinCredentialShape[];
+export declare function twinRequestJournalEnabled(env?: Record<string, string | undefined>): boolean;
+/** Where a service's request journal lives: beside its `actions.jsonl`. */
+export declare function twinRequestJournalPath(service: string, root?: string): string;
+/**
+ * Append one served request to the journal — a no-op unless VOLTER_TWIN_REQUEST_JOURNAL=1, so
+ * the default path does zero I/O. Never throws: an observability append must not fail a serve.
+ */
+export declare function journalTwinRequest(service: string, entry: TwinRequestJournalEntry, root?: string): void;
+export declare const TWIN_JOURNAL_IDENTITY: unique symbol;
+export type TwinJournalIdentity = {
+    service: string;
+    root?: string;
+};
+export declare function vendorFromStack(stack: string | undefined): string | undefined;
+/**
+ * Wrap `Bun.serve` so EVERY twin's HTTP surface journals, with no per-pack line. Idempotent
+ * (a `Symbol.for` marker survives a second copy of this module) and a strict pass-through when
+ * VOLTER_TWIN_REQUEST_JOURNAL is not `1` — the default path adds one function call per request
+ * and does zero I/O. Called once at module load, below; exported so a test can assert it.
+ *
+ * A pack that knows its own identity may declare it by putting `{service, root}` on the serve
+ * options under `TWIN_JOURNAL_IDENTITY` (a symbol key Bun's option reader ignores). Nothing in
+ * the estate needs to: `createTwinServer` is the only caller, because it is the one server whose
+ * service is an argument rather than a fact about the pack.
+ */
+export declare function installTwinRequestJournal(): boolean;
+export type TwinResource = {
+    id: string;
+    type: string;
+    updatedAt: string;
+} & Record<string, unknown>;
+export declare function twinResources(service: string, root?: string): TwinResource[];
+export type TwinWriteResult = {
+    status: 'performed' | 'replayed';
+    actionId: string; /** the id the vendor minted when the head performed the write */
+    externalId?: string; /** what the vendor answered when the head performed the write, as the adapter returned it */
+    vendorData?: unknown;
+};
+export type TwinWriteInput = {
+    operation: string;
+    provider?: string;
+    subjectType: string;
+    subjectId: string;
+    fields: SubjectFields;
+    input?: Record<string, unknown>;
+    projection?: ActionProjection;
+    occurredAt?: string;
+    actor?: {
+        kind: 'agent' | 'human' | 'bot' | 'system';
+        id?: string;
+    };
+    preconditions?: TwinActionPrecondition[];
+    correlationId?: string;
+    uniqueness?: string;
+    /** AT-MOST-ONCE, opt in. A local vendor write is an OCCURRENCE by default: two calls are two
+     *  actions, even byte-identical in the same instant. Pass a caller-supplied key when a re-issue
+     *  of the SAME request must collapse onto the first. Without a key the kernel cannot tell a retry
+     *  from a repeat, and guessing from content is what silently dropped writes.
+     *
+     *  SCOPE, stated plainly because an earlier version of this comment overclaimed: the key dedupes
+     *  on (service, operation, subjectId, key). It therefore helps only when the CALLER supplies the
+     *  subject id. A create whose id the twin mints gets a fresh id per call and is NOT deduped by
+     *  this — which is the commonest shape a vendor's own idempotency header covers — so a pack
+     *  modelling such a header for creates keeps doing it itself, by request signature and stored
+     *  response (the payments pack in this catalog does). Reuse of a key with a DIFFERENT payload
+     *  raises a conflict, which the generic twin server answers as a 400 (2026-09-04). */
+    idempotencyKey?: string;
+    /** The EXACT identity of an action being re-materialized, when the caller already has one —
+     *  replay reproducing a source changeset's actions into a target world. Distinct from
+     *  `idempotencyKey`, which is a REQUEST key the kernel derives an id from: this IS the id, so a
+     *  replayed action keeps the identity it had in the source world. Implies at-most-once, because
+     *  identity equality is what at-most-once means. Not for packs. */
+    actionId?: string;
+};
+export type AtomicTwinWriteDecision<T> = {
+    kind: 'skip';
+    value: T;
+} | {
+    kind: 'write';
+    value: T;
+    write: TwinWriteInput;
+};
+/**
+ * Decide a state-dependent local write and append it under the same cross-process action lock.
+ * Use this when acceptance or the new fields depend on current projected state; a caller-side
+ * read followed by `applyTwinWrite` is not atomic across processes.
+ */
+export declare function applyTwinWriteAtomic<T>(service: string, prepare: (resources: readonly TwinResource[]) => AtomicTwinWriteDecision<T>, root?: string): Promise<{
+    value: T;
+    result?: TwinWriteResult;
+}>;
+export declare function resolveTwinRead(service: string, pathname: string, opts?: {
+    root?: string;
+}): {
+    status: number;
+    body: unknown;
+};
+export declare function applyTwinWrite(service: string, write: TwinWriteInput, root?: string): Promise<{
+    result: TwinWriteResult;
+    resource: TwinResource;
+}>;
+export declare function createTwinServer(options: {
+    service: string;
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;