@volter/world-core 2.0.0

package/src/schemas.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+export const WorldActorSchema = z.object({
+  id: z.string().min(1).optional(),
+  name: z.string().min(1).optional(),
+  kind: z.enum(['human', 'agent', 'bot', 'system']),
+});
+
+export const WorldSubjectSchema = z.object({
+  type: z.string().min(1),
+  id: z.string().min(1),
+});
+
+export const WorldExternalRefSchema = z.object({
+  provider: z.string().min(1),
+  id: z.string().min(1).optional(),
+  url: z.string().min(1).optional(),
+  cursor: z.string().min(1).optional(),
+  rawRef: z.string().min(1).optional(),
+});
+
+export const WorldServiceEventSchema = z.object({
+  id: z.string().min(1),
+  service: z.string().min(1),
+  type: z.string().min(1),
+  schemaVersion: z.number().int().positive(),
+  idempotencyKey: z.string().min(1),
+  occurredAt: z.string().min(1),
+  observedAt: z.string().min(1),
+  origin: z.enum(['virtual', 'external', 'agent', 'connector', 'replay', 'migration']),
+  actor: WorldActorSchema.optional(),
+  subject: WorldSubjectSchema,
+  causationId: z.string().min(1).optional(),
+  correlationId: z.string().min(1).optional(),
+  external: WorldExternalRefSchema.optional(),
+  data: z.record(z.string(), z.unknown()),
+  raw: z.record(z.string(), z.unknown()).optional(),
+});
+
+// NOTE: WorldAnnotationSchema moved to @volter/tracker/world-annotations — annotating
+// world events as sources/noise is a tracker (verification) concern, not the twin's.
+
+export const GenericWorldStateSchema = z.object({
+  version: z.literal(1),
+  service: z.string().min(1),
+  rebuiltAt: z.string().min(1),
+  eventCount: z.number().int().nonnegative(),
+  latestEventId: z.string().min(1).optional(),
+  subjects: z.record(z.string(), z.object({
+    type: z.string().min(1),
+    id: z.string().min(1),
+    latestEventId: z.string().min(1),
+    latestType: z.string().min(1),
+    updatedAt: z.string().min(1),
+  })),
+});

package/src/serve-http.ts

@@ -0,0 +1,299 @@
+// 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.
+
+export type HttpHandler = (request: Request) => Response | Promise<Response>;
+export type WebSocketPeer = { send: (data: string | Uint8Array) => unknown; close: (code?: number, reason?: string) => unknown };
+export type WebSocketUpgrade = {
+  accepts: (request: Request) => boolean;
+  open: (peer: WebSocketPeer, request: Request) => void;
+  message: (peer: WebSocketPeer, data: string | Uint8Array) => void | Promise<void>;
+  close: (peer: WebSocketPeer) => void;
+};
+export type ServeHttpOptions = {
+  /** Multiplexing infrastructure fronts leave vendor journaling to the downstream twins. */
+  twinRequestJournal?: boolean;
+  /** Optional persistent transport, with the same callbacks on Node and Bun. */
+  upgrade?: WebSocketUpgrade;
+  tls?: { key: string | Uint8Array; cert: string | Uint8Array };
+  /** the interface to listen on: loopback unless a caller names another. A twin is reached by its
+   *  World over loopback; a front that is meant to be reached (a served world, a host) names its own. */
+  hostname?: string;
+  port?: number;
+  fetch: HttpHandler;
+  /** seconds a connection may idle (Bun honors it; Node's keep-alive timeout is set from it) */
+  idleTimeout?: number;
+  /** the largest request body accepted, in bytes (Bun's default is 128 MB; Node sets none) */
+  maxRequestBodySize?: number;
+  /** what a thrown handler answers with; absent, a 500 carrying the error (as Bun.serve) */
+  error?: (error: Error) => Response | Promise<Response>;
+};
+export type HttpServer = {
+  hostname: string;
+  port: number;
+  /** as Bun's: a URL, whose string form ends in `/` — packs build `${server.url}path` on that */
+  url: URL;
+  /** stop listening; `closeActive` (default true) drops in-flight connections as well */
+  stop: (closeActive?: boolean) => Promise<void>;
+};
+
+/** A decorator the request journal installs: every server made through the seam serves through it. */
+let decorate: ((options: ServeHttpOptions) => HttpHandler) | undefined;
+export function setServeDecorator(fn: ((options: ServeHttpOptions) => HttpHandler) | undefined): void { decorate = fn; }
+
+type BunLike = { serve: (o: unknown) => { port?: number; hostname?: string; url?: URL; stop: (closeActive?: boolean) => unknown } };
+const bunRuntime = (): BunLike | undefined => { const b = (globalThis as { Bun?: Partial<BunLike> }).Bun; return b && typeof b.serve === 'function' ? (b as BunLike) : 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: ServeHttpOptions): Promise<HttpServer> {
+  // 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 as { process?: { env?: Record<string, string | undefined> } }).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: Request, server: { upgrade: (request: Request, options: { data: { request: Request } }) => boolean }) => {
+          if (request.headers.get('upgrade')?.toLowerCase() === 'websocket' && upgrade.accepts(request) && server.upgrade(request, { data: { request } })) return undefined;
+          return options.fetch(request);
+        },
+        websocket: {
+          open: (peer: WebSocketPeer & { data: { request: Request } }) => upgrade.open(peer, peer.data.request),
+          message: (peer: WebSocketPeer, data: string | Uint8Array) => 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 });
+}
+
+type NodeHttp = typeof import('node:http');
+type NodeStream = typeof import('node:stream');
+/** 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<T = unknown>(name: string): T { return builtin<T>(name); }
+function builtin<T>(name: string): T {
+  const get = (process as { getBuiltinModule?: (id: string) => unknown }).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) as T;
+}
+
+async function serveOnNode(options: ServeHttpOptions & { hostname: string; urlHost: string }): Promise<HttpServer> {
+  const http = builtin<NodeHttp>('node:http');
+  const { Readable } = builtin<NodeStream>('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: import('node:http').RequestListener) => options.tls
+    ? builtin<typeof import('node:https')>('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: string, error: unknown) => {
+    // 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<AbortController>();
+  // 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<Request>();
+  const server = factory((req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => {
+    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: ReadableStream<Uint8Array> | null) => {
+      if (!body) return;
+      try { await body.cancel(controller.signal.reason); }
+      catch (error) { reportCleanup('late response body cancellation failed', error); }
+    };
+    const waitForDrain = () => new Promise<void>((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: 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: Request | undefined;
+    const handle = async () => {
+      const method = req.method ?? 'GET';
+      let response: 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() as { port: number } | null)?.port ?? 0}`}${req.url ?? '/'}`;
+        const withBody = method !== 'GET' && method !== 'HEAD';
+        const init: RequestInit & { duplex?: 'half' } = { method, headers, signal: controller.signal, ...(withBody ? { body: Readable.toWeb(req) as unknown as ReadableStream, 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: ReadableStreamDefaultReader<Uint8Array> | undefined;
+      let cancelReader: Promise<void> | undefined;
+      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<void>((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: import('ws').WebSocketServer | undefined;
+  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): entry is [string, string] => 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<void>((resolve, reject) => { server.once('error', reject); server.listen(options.port ?? 0, options.hostname, () => { server.off('error', reject); resolve(); }); });
+  const port = (server.address() as { port: number }).port;
+  return {
+    hostname: options.hostname, port, url: new URL(`${protocol}://${options.urlHost}:${port}/`),
+    stop: (closeActive = true) => new Promise<void>((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(); }),
+  };
+}