@volter/world-core 3.0.163 → 3.0.164

package/dist/src/pack-fetch.js

@@ -71,7 +71,7 @@ function hostMatcher(pattern) {
     };
 }
 /** The host a request is for: the vendor host the World's injector names, else its own. */
-const hostOf = (request) => readHostPort(request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host)?.host ?? '';
+export const hostOf = (request) => readHostPort(request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host)?.host ?? '';
 /** Where a workspace asked `?show=<type>:<id>` opens the record (architecture, "Workspace"): the built workspace page
  *  that shows that type, its parameter the id; else the one that lists the type; else the workspace's home (its root
  *  page). Every other parameter a page's path names is the asking page's, and a page that cannot be filled is passed
@@ -152,12 +152,26 @@ async function encoded(m, request, res) {
     const buffered = new ReadableStream({ start(controller) { controller.enqueue(body); controller.close(); } });
     return new Response(buffered, { status: res.status, statusText: res.statusText, headers });
 }
-/** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 /** A door's path as it is served and listed: under `/_twin/`, whether the manifest writes the prefix or not. */
 const doorPath = (path) => (path.startsWith('/_twin/') ? path : `/_twin${path.startsWith('/') ? '' : '/'}${path}`);
+/** A declared World door, matched by the same normalized path for serving and response ownership. */
+export function worldDoorMatcher(doors) {
+    const routes = doors.map((door) => ({ door, method: door.method.toUpperCase(), matches: pathMatcher(doorPath(door.path), false) }));
+    return (method, path) => {
+        const at = path.replace(/\/+$/, '') || '/';
+        for (const route of routes) {
+            if (route.method !== method.toUpperCase())
+                continue;
+            const hit = route.matches(at);
+            if (hit)
+                return { door: route.door, params: hit.params };
+        }
+        return undefined;
+    };
+}
 /** A request with its path's repeated slashes merged, as a front that merges them routes it (the manifest's
  *  `mergeSlashes`); one with none is itself. */
-function slashesMerged(request) {
+export function slashesMerged(request) {
     const url = new URL(request.url);
     const merged = url.pathname.replace(/\/{2,}/g, '/');
     if (merged === url.pathname)
@@ -165,6 +179,63 @@ function slashesMerged(request) {
     url.pathname = merged;
     return new Request(url, request);
 }
+/** The selected unit's request transformation, shared by serving and response judgment. */
+export function unitRequestRouter(m, surface, routes) {
+    const prefix = m.pathPrefix ? new RegExp(`^(?:${m.pathPrefix})(?=/)`) : undefined;
+    const base = surface.basePath ?? '';
+    const baseAlias = m.basePathAlias && base ? new RegExp(`^(?:${m.basePathAlias})(?=/)`) : undefined;
+    const hostPath = m.pathFromHost ? new RegExp(m.pathFromHost, 'i') : undefined;
+    const hostParams = m.hostParams ? new RegExp(m.hostParams, 'i') : undefined;
+    // each operation's spanning parameters, keyed by the operation and the parameter as the route compiles them (a whole
+    // segment's label whose name the surface or the manifest declares spanning), so one operation's spanning name never
+    // keeps another's slashes, nor a label that only part of a segment holds
+    const spanningNames = new Set(surface.spanning ?? []);
+    const spanningOf = new Set(surface.operations.flatMap((op) => ((op.basePath ?? base) + op.path).split('/').flatMap((seg) => {
+        const label = /^\{([^}]+)\}$/.exec(seg)?.[1];
+        return label !== undefined && spanningNames.has(label) ? [`${op.id}\u0000${label}`] : [];
+    })));
+    /** A path as the vendor routes it: the manifest's path prefix taken off, the spec's base in an alias's place, a host's
+     *  path label (pathFromHost) put in front. */
+    const rewritten = (pathname, host) => {
+        let path = pathname;
+        if (prefix)
+            path = path.replace(prefix, '') || '/';
+        // a base the vendor serves as its own: the spec's base in its place (a path already under the spec's base stays)
+        if (baseAlias && !(path === base || path.startsWith(`${base}/`)))
+            path = path.replace(baseAlias, base);
+        const label = hostPath?.exec(host)?.[1];
+        if (label)
+            path = `/${label}${path === '/' ? '' : path}`;
+        return path;
+    };
+    /** The request as its vendor routes it: duplicate slashes collapsed, unless the rewritten path matches an operation
+     *  through one of that operation's spanning parameters (the surface's and the manifest's), whose value keeps its
+     *  slashes; then rewritten. */
+    return (request) => {
+        const url = new URL(request.url);
+        const host = hostOf(request);
+        const kept = rewritten(url.pathname, host);
+        const matched = matchOperation(routes, request.method, kept);
+        const spanning = matched !== undefined && Object.keys(matched.params).some((name) => spanningOf.has(`${matched.operation.id}\u0000${name}`));
+        const source = spanning ? url.pathname : url.pathname.replace(/\/{2,}/g, '/');
+        // a prefix's named groups (Jira's `/ex/jira/(?<cloudId>[^/]+)`) and the host's (E2B's envd at
+        // `49983-(?<sandboxID>…).e2b.app`) join the operation's parameters
+        const groups = { ...(prefix?.exec(source)?.groups ?? {}), ...(hostParams?.exec(host)?.groups ?? {}), ...Object.fromEntries(Object.entries(m.headerParams ?? {}).flatMap(([param, header]) => { const value = request.headers.get(header); return value === null ? [] : [[param, value]]; })) };
+        const path = spanning ? kept : rewritten(source, host);
+        if (path === url.pathname && !Object.keys(groups).length)
+            return request;
+        // the path the client sent, which a signature over the request (SigV4's canonical URI) covers
+        const headers = new Headers(request.headers);
+        // the path as first sent: a front before this (an attach bridge) may have named the one its client signed
+        if (!headers.has(ORIGINAL_PATH_HEADER))
+            headers.set(ORIGINAL_PATH_HEADER, url.pathname);
+        if (Object.keys(groups).length)
+            headers.set(PREFIX_PARAMS_HEADER, JSON.stringify(groups));
+        url.pathname = path;
+        return new Request(url, { method: request.method, headers, body: request.body, signal: request.signal, ...(request.body ? { duplex: 'half' } : {}) });
+    };
+}
+/** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export function createPackFetch(parts, options = {}) {
     const m = parts.manifest;
     const scope = {
@@ -267,12 +338,10 @@ export function createPackFetch(parts, options = {}) {
             return Response.json(decision.result.body, { status: decision.result.status, headers: decision.result.headers ?? {} });
         return api(withHeaders(request, new Headers([...request.headers, [SCENARIO_DECISION_HEADER, scenarioDecisionHeader(decision)]])));
     };
-    const doors = (m.doors ?? []).map((d) => {
-        const answer = parts.doors?.[d.id];
-        if (!answer)
+    for (const d of m.doors ?? [])
+        if (!parts.doors?.[d.id])
             throw new Error(`${m.vendor}: the manifest declares the door ${d.id}, and semantics/doors.ts exports no ${d.id}`);
-        return { decl: d, path: pathMatcher(doorPath(d.path), false), answer };
-    });
+    const door = worldDoorMatcher(m.doors ?? []);
     const screens = (m.screens ?? []).filter((s) => s.status === 'done' && parts.screens?.[s.id]).map((s) => {
         const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
         return { decl: s, host: (h) => hosts.map((match) => match(h)).find(Boolean), path: pathMatcher(s.path, true), answer: parts.screens[s.id] };
@@ -304,59 +373,7 @@ export function createPackFetch(parts, options = {}) {
             await runAsVendorMove(async () => parts.clock(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
     };
     const refusedReadOnly = () => vendorError(m, m.readOnly);
-    const prefix = m.pathPrefix ? new RegExp(`^(?:${m.pathPrefix})(?=/)`) : undefined;
-    const base = surface.basePath ?? '';
-    const baseAlias = m.basePathAlias && base ? new RegExp(`^(?:${m.basePathAlias})(?=/)`) : undefined;
-    const hostPath = m.pathFromHost ? new RegExp(m.pathFromHost, 'i') : undefined;
-    const hostParams = m.hostParams ? new RegExp(m.hostParams, 'i') : undefined;
-    // each operation's spanning parameters, keyed by the operation and the parameter as the route compiles them (a whole
-    // segment's label whose name the surface or the manifest declares spanning), so one operation's spanning name never
-    // keeps another's slashes, nor a label that only part of a segment holds
-    const spanningNames = new Set(surface.spanning ?? []);
-    const spanningOf = new Set(surface.operations.flatMap((op) => ((op.basePath ?? base) + op.path).split('/').flatMap((seg) => {
-        const label = /^\{([^}]+)\}$/.exec(seg)?.[1];
-        return label !== undefined && spanningNames.has(label) ? [`${op.id}\u0000${label}`] : [];
-    })));
-    /** A path as the vendor routes it: the manifest's path prefix taken off, the spec's base in an alias's place, a host's
-     *  path label (pathFromHost) put in front. */
-    const rewritten = (pathname, host) => {
-        let path = pathname;
-        if (prefix)
-            path = path.replace(prefix, '') || '/';
-        // a base the vendor serves as its own: the spec's base in its place (a path already under the spec's base stays)
-        if (baseAlias && !(path === base || path.startsWith(`${base}/`)))
-            path = path.replace(baseAlias, base);
-        const label = hostPath?.exec(host)?.[1];
-        if (label)
-            path = `/${label}${path === '/' ? '' : path}`;
-        return path;
-    };
-    /** The request as its vendor routes it: duplicate slashes collapsed, unless the rewritten path matches an operation
-     *  through one of that operation's spanning parameters (the surface's and the manifest's), whose value keeps its
-     *  slashes; then rewritten. */
-    const routed = (request) => {
-        const url = new URL(request.url);
-        const host = hostOf(request);
-        const kept = rewritten(url.pathname, host);
-        const matched = matchOperation(routes, request.method, kept);
-        const spanning = matched !== undefined && Object.keys(matched.params).some((name) => spanningOf.has(`${matched.operation.id}\u0000${name}`));
-        const source = spanning ? url.pathname : url.pathname.replace(/\/{2,}/g, '/');
-        // a prefix's named groups (Jira's `/ex/jira/(?<cloudId>[^/]+)`) and the host's (E2B's envd at
-        // `49983-(?<sandboxID>…).e2b.app`) join the operation's parameters
-        const groups = { ...(prefix?.exec(source)?.groups ?? {}), ...(hostParams?.exec(host)?.groups ?? {}), ...Object.fromEntries(Object.entries(m.headerParams ?? {}).flatMap(([param, header]) => { const value = request.headers.get(header); return value === null ? [] : [[param, value]]; })) };
-        const path = spanning ? kept : rewritten(source, host);
-        if (path === url.pathname && !Object.keys(groups).length)
-            return request;
-        // the path the client sent, which a signature over the request (SigV4's canonical URI) covers
-        const headers = new Headers(request.headers);
-        // the path as first sent: a front before this (an attach bridge) may have named the one its client signed
-        if (!headers.has(ORIGINAL_PATH_HEADER))
-            headers.set(ORIGINAL_PATH_HEADER, url.pathname);
-        if (Object.keys(groups).length)
-            headers.set(PREFIX_PARAMS_HEADER, JSON.stringify(groups));
-        url.pathname = path;
-        return new Request(url, { method: request.method, headers, body: request.body, signal: request.signal, ...(request.body ? { duplex: 'half' } : {}) });
-    };
+    const routed = unitRequestRouter(m, surface, routes);
     const rootServes = (method, path) => Boolean(matchOperation(routes, method, path));
     const lane = m.lanes ? laneRouter(m.vendor, m.lanes, parts.lanes ?? {}, rootServes) : undefined;
     // Inspect lane-owned World doors directly, without routing them back through the vendor gateway.
@@ -455,7 +472,7 @@ export function createPackFetch(parts, options = {}) {
         if (own)
             return own;
         // Root World doors belong to the pack at every routed host, including a lane's host.
-        const rootDoor = doors.some((d) => d.decl.method.toUpperCase() === arrived.method && d.path(asked));
+        const rootDoor = door(arrived.method, asked);
         const toLane = discovery || rootDoor ? undefined : lane?.(arrived);
         if (toLane)
             return toLane(arrived);
@@ -531,15 +548,12 @@ export function createPackFetch(parts, options = {}) {
                     resetFakePool(m.service, options.root);
                 return Response.json({ kind }, { status: 201 });
             }
-            for (const d of doors) {
-                if (d.decl.method.toUpperCase() !== request.method)
-                    continue;
-                const hit = d.path(path);
-                if (!hit)
-                    continue;
+            const hit = door(request.method, path);
+            if (hit) {
                 if (readOnly && request.method !== 'GET')
                     return refusedReadOnly();
-                return d.answer(await open(request, d.decl.id, d.decl.method, d.decl.path, hit.params));
+                const d = hit.door;
+                return parts.doors[d.id](await open(request, d.id, d.method, d.path, hit.params));
             }
             return gapAnswer(m, request);
         }
@@ -720,31 +734,16 @@ export function createPackFetch(parts, options = {}) {
     const owners = () => flatOwners(ownersByUnit());
     return derivedRequestScopes(m, Object.assign(served, { owners, ownersByUnit, serves, advanceClock: async (request) => runWithStorageTenant(m.service, await selectedAccount(request), () => advanceClock(request)), workspaces, boards: Boolean(parts.board), maxRequestBodySize: m.descriptor?.maxRequestBodySize, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}), ...(ingest ? { ingest } : {}) }), options.readOnly);
 }
-/** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
- *  route whose conditions all hold, then the default), behind the gateway's CORS; undefined when none takes it. */
-function laneRouter(vendor, decl, lanes, rootServes = () => false) {
-    const served = (name) => {
-        const part = lanes[name];
-        if (!part)
-            throw new Error(`${vendor}: the manifest routes to the lane ${name}, and the vendor's fetch is given no ${name}`);
-        // the lane is named on the request, so a write it makes records which lane's API made it (LANE_HEADER)
-        const named = (request) => {
-            const headers = new Headers(request.headers);
-            headers.set(LANE_HEADER, name);
-            return part.fetch(withHeaders(request, headers));
-        };
-        return decl.cors ? withCors(decl.cors, named) : named;
-    };
-    const doors = Object.entries(lanes).flatMap(([name, part]) => (part.manifest.doors ?? []).map((d) => ({
-        name, method: d.method.toUpperCase(), matches: pathMatcher(d.path.startsWith('/_twin/') ? d.path : `/_twin/${d.path.replace(/^\//, '')}`, false),
-    })));
+/** The lane selected by the vendor gateway, shared by serving and response judgment. */
+export function laneSelector(decl, lanes, rootServes = () => false) {
+    const door = worldDoorMatcher(Object.entries(lanes).flatMap(([name, part]) => (part.manifest.doors ?? []).map((d) => ({ ...d, name }))));
     const laneRoutes = decl.routes.map((r) => {
         const at = r.path?.replace(/\/+$/, '');
         const host = r.host !== undefined ? new RegExp(r.host, 'i') : undefined;
         const except = (r.exceptHosts ?? []).map((h) => h.toLowerCase());
         const own = lanes[r.lane]?.fetch.serves;
         return {
-            lane: served(r.lane),
+            lane: r.lane,
             holds: (request, path, name) => (at === undefined || path === at || path.startsWith(`${at}/`))
                 && (host === undefined || host.test(name))
                 && (r.header === undefined || (request.headers.get(r.header.name) ?? '').startsWith(r.header.prefix) !== (r.header.absent === true))
@@ -752,7 +751,6 @@ function laneRouter(vendor, decl, lanes, rootServes = () => false) {
                 && !(r.unlessOnlyRoot && rootServes(request.method, path) && !(own?.(request.method, path) ?? false)),
         };
     });
-    const fallback = decl.default !== undefined ? served(decl.default) : undefined;
     return (request) => {
         // `<base>/@<host>/<path>` at a World's place, for a host a lane's built content screen names, goes to that lane, before
         // any lane is picked by the request's host or path: its own fetch answers it by its content route, under the vendor's
@@ -760,15 +758,37 @@ function laneRouter(vendor, decl, lanes, rootServes = () => false) {
         const address = request.headers.has(TWIN_PREFIX_HEADER) ? contentAddressOf(new URL(request.url).pathname) : undefined;
         const content = address && Object.keys(lanes).find((l) => lanes[l].fetch.contentHosts?.includes(address.host));
         if (content)
-            return served(content);
+            return content;
         const path = new URL(request.url).pathname.replace(/\/{2,}/g, '/');
         if (path.startsWith('/_twin/')) {
-            const door = doors.find((d) => d.method === request.method && d.matches(path));
-            if (door)
-                return served(door.name);
+            const hit = door(request.method, path);
+            if (hit)
+                return hit.door.name;
         }
         const name = hostOf(request);
-        return laneRoutes.find((r) => r.holds(request, path, name))?.lane ?? fallback;
+        return laneRoutes.find((r) => r.holds(request, path, name))?.lane ?? decl.default;
+    };
+}
+/** The vendor's gateway over its lanes: the lane a request goes to (a door to the lane that declares it, then the first
+ *  route whose conditions all hold, then the default), behind the gateway's CORS; undefined when none takes it. */
+function laneRouter(vendor, decl, lanes, rootServes = () => false) {
+    const served = (name) => {
+        const part = lanes[name];
+        if (!part)
+            throw new Error(`${vendor}: the manifest routes to the lane ${name}, and the vendor's fetch is given no ${name}`);
+        // the lane is named on the request, so a write it makes records which lane's API made it (LANE_HEADER)
+        const named = (request) => {
+            const headers = new Headers(request.headers);
+            headers.set(LANE_HEADER, name);
+            return part.fetch(withHeaders(request, headers));
+        };
+        return decl.cors ? withCors(decl.cors, named) : named;
+    };
+    const selected = laneSelector(decl, lanes, rootServes);
+    const handlers = new Map([...new Set([...decl.routes.map((route) => route.lane), ...(decl.default === undefined ? [] : [decl.default]), ...Object.keys(lanes)])].map((name) => [name, served(name)]));
+    return (request) => {
+        const name = selected(request);
+        return name === undefined ? undefined : handlers.get(name);
     };
 }
 /** A vendor whose every API is a lane (Cloudflare's API v4 and R2, AWS's services), served from its manifest: the

package/dist/src/request-body.d.ts

@@ -1,8 +1,7 @@
-/** Compressed-request output only: Node's plain requests remain uncapped; Bun retains its own plain-body limit.
- * The default is Bun's existing largest plain body (128 MiB), so both runtimes decode the same.
+/** The shared HTTP transport and compressed-request output retain Bun's 128 MiB plain-body default.
  * Source: bun-types/serve.d.ts, ServeOptions.maxRequestBodySize (@default 1024 * 1024 * 128),
  * https://github.com/oven-sh/bun/blob/main/packages/bun-types/serve.d.ts .
- * A pack's descriptor.maxRequestBodySize overrides decoded output as it does Bun's plain-body limit. */
+ * A pack's descriptor.maxRequestBodySize overrides both the transport and decoded-output limits. */
 export declare const DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE: number;
 export declare class RequestBodyTooLargeError extends Error {
     constructor();

package/dist/src/request-body.js

@@ -1,8 +1,7 @@
-/** Compressed-request output only: Node's plain requests remain uncapped; Bun retains its own plain-body limit.
- * The default is Bun's existing largest plain body (128 MiB), so both runtimes decode the same.
+/** The shared HTTP transport and compressed-request output retain Bun's 128 MiB plain-body default.
  * Source: bun-types/serve.d.ts, ServeOptions.maxRequestBodySize (@default 1024 * 1024 * 128),
  * https://github.com/oven-sh/bun/blob/main/packages/bun-types/serve.d.ts .
- * A pack's descriptor.maxRequestBodySize overrides decoded output as it does Bun's plain-body limit. */
+ * A pack's descriptor.maxRequestBodySize overrides both the transport and decoded-output limits. */
 export const DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE = 128 * 1024 * 1024;
 export class RequestBodyTooLargeError extends Error {
     constructor() { super('Payload Too Large'); this.name = 'RequestBodyTooLargeError'; }

package/dist/src/runtime.d.ts

@@ -7,11 +7,12 @@ export { ORIGINAL_PATH_HEADER } from './sigv4.js';
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from './twin-fetch.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
 export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from './derived.js';
+export { hostOf, laneSelector, slashesMerged, unitRequestRouter, worldDoorMatcher } from './pack-fetch.js';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
 export type { Traceparent } from './trace-context.js';
 export type { DerivedCall, DerivedCoreOutcome, DerivedDispatch, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.js';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
-export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.js';
+export { deliverEvents, fillEnvelope, setDeliveryObserver, settleEventDeliveries, signEvent, signEventAll, verifyEvent } from './events.js';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.js';
 export type { HandlerCrypto, Jwk, Jwks, JwtDecodeOptions, JwtSignatureOptions, JwtVerdict, JwtVerificationKey, SigningKey } from './signing.js';
 export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTransport, EventWrite } from './events.js';

package/dist/src/runtime.js

@@ -15,9 +15,10 @@ export { ORIGINAL_PATH_HEADER } from "./sigv4.js";
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from "./derived.js";
+export { hostOf, laneSelector, slashesMerged, unitRequestRouter, worldDoorMatcher } from "./pack-fetch.js";
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
-export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from "./events.js";
+export { deliverEvents, fillEnvelope, setDeliveryObserver, settleEventDeliveries, signEvent, signEventAll, verifyEvent } from "./events.js";
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from "./signing.js";
 export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from "./emit.js";
 // The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client

package/dist/src/serve-http.d.ts

@@ -29,7 +29,7 @@ export type ServeHttpOptions = {
     fetch: HttpHandler;
     /** seconds a connection may idle (Bun honors it; Node's keep-alive timeout is set from it) */
     idleTimeout?: number;
-    /** Explicit transport limit in bytes; absent, Bun retains its 128 MiB default. */
+    /** Explicit transport limit in bytes; absent, 128 MiB on both runtimes. */
     maxRequestBodySize?: number;
     /** what a thrown handler answers with; absent, a 500 carrying the error (as Bun.serve) */
     error?: (error: Error) => Response | Promise<Response>;

package/dist/src/serve-http.js

@@ -1,13 +1,14 @@
 // 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
+// ONE place. Ordinary HTTP uses `node:http`; requested WebSockets retain Bun's native backend.
+// The request is 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 (the served-handler registry is made on first use), and `node:http` is reached through `process.getBuiltinModule`
 // rather than a static import: this module rides into browser client bundles through the kernel's
 // entrypoint, where a static `node:` import is the 2026-09-06 class of break.
 import { worldBootAnswer } from "./world-boot.js";
+import { DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE, RequestBodyTooLargeError } from "./request-body.js";
 /** One socket library at the host seam, shared by inbound upgrades and authenticated outbound relays. */
 const socketLibrary = () => import('ws');
 export async function connectWebSocket(url, headers, protocols = []) {
@@ -56,7 +57,7 @@ export async function serveHttp(options) {
     const hostname = options.hostname ?? '127.0.0.1';
     const urlHost = options.hostname ?? '127.0.0.1';
     const bun = bunRuntime();
-    if (bun) {
+    if (bun && (options.upgrade !== undefined || 'websocket' in options)) {
         // 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;
@@ -191,7 +192,8 @@ function builtin(name) {
 }
 async function serveOnNode(options) {
     const http = builtin('node:http');
-    const { Readable } = builtin('node:stream');
+    const { Readable, Transform } = builtin('node:stream');
+    const requestLimit = options.maxRequestBodySize ?? DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE;
     if ('websocket' in options)
         throw new Error('serveHttp: use the portable upgrade callbacks for WebSocket support on Node');
     const protocol = options.tls ? 'https' : 'http';
@@ -230,20 +232,35 @@ async function serveOnNode(options) {
     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 socket = req.socket;
+        const hasInputBody = req.headers['transfer-encoding'] !== undefined || Number(req.headers['content-length']) > 0;
+        let incoming;
+        let flushingBodyRefusal = false;
+        const abort = () => {
+            if (!controller.signal.aborted)
+                controller.abort();
+            incoming?.destroy(controller.signal.reason);
+            if (!flushingBodyRefusal) {
+                req.destroy();
+                if (!res.writableFinished)
+                    res.destroy();
+                socket.destroy();
+            }
+        };
+        active.add(abort);
         const onRequestClose = () => { if (!req.complete)
             abort(); };
-        const onResponseClose = () => { if (!res.writableFinished)
-            abort(); };
+        const onResponseClose = () => { if (!res.writableFinished) {
+            flushingBodyRefusal = false;
+            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);
+        socket.on('close', onSocketClose);
+        socket.on('error', abort);
         res.on('close', onResponseClose);
         res.on('error', abort);
         const disconnected = () => controller.signal.aborted || res.destroyed;
@@ -279,8 +296,38 @@ async function serveOnNode(options) {
                 closed();
         });
         let request;
+        let bodyTooLarge = false;
+        const rejectBody = () => {
+            if (bodyTooLarge)
+                return;
+            bodyTooLarge = true;
+            const error = new RequestBodyTooLargeError();
+            if (incoming)
+                req.unpipe(incoming);
+            req.pause();
+            if (!res.headersSent && !res.destroyed) {
+                for (const name of res.getHeaderNames())
+                    res.removeHeader(name);
+                flushingBodyRefusal = true;
+                res.writeHead(413, { 'connection': 'close', 'content-type': 'text/plain', 'content-length': Buffer.byteLength(error.message) });
+                res.once('finish', () => { flushingBodyRefusal = false; req.destroy(); });
+                res.end(error.message);
+            }
+            else if (!res.destroyed)
+                res.destroy(error);
+            abort();
+        };
+        const inputSettled = new Promise((resolve) => {
+            const settled = () => { req.off('end', settled); req.off('close', settled); resolve(); };
+            req.once('end', settled);
+            req.once('close', settled);
+        });
         const handle = async () => {
             const method = req.method ?? 'GET';
+            if (Number(req.headers['content-length']) > requestLimit) {
+                rejectBody();
+                return;
+            }
             let response;
             try {
                 const headers = new Headers();
@@ -295,9 +342,26 @@ async function serveOnNode(options) {
                 }
                 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' } : {}) };
+                let received = 0;
+                incoming = new Transform({ transform(chunk, _encoding, callback) {
+                        received += chunk.byteLength;
+                        if (received > requestLimit) {
+                            rejectBody();
+                            callback(new RequestBodyTooLargeError());
+                        }
+                        else
+                            callback(null, chunk);
+                    } });
+                const inputClosed = () => { if (!req.readableEnded)
+                    abort(); };
+                incoming.on('error', inputClosed);
+                incoming.once('close', inputClosed);
+                const init = { method, headers, signal: controller.signal, ...(withBody ? { body: Readable.toWeb(incoming), duplex: 'half' } : {}) };
                 request = new Request(url, init);
                 activeRequests.add(request);
+                req.pipe(incoming);
+                if (!withBody)
+                    incoming.resume();
                 response = await options.fetch(request);
             }
             catch (error) {
@@ -365,6 +429,7 @@ async function serveOnNode(options) {
                     if (k !== 'set-cookie')
                         res.setHeader(k, v);
                 }
+                res.strictContentLength = response.headers.has('content-length');
                 const cookies = response.headers.getSetCookie?.() ?? [];
                 if (cookies.length)
                     res.setHeader('set-cookie', cookies);
@@ -424,12 +489,23 @@ async function serveOnNode(options) {
                 res.destroy(error instanceof Error ? error : new Error(String(error)));
         }).then(async () => {
             await responseSettled;
-            active.delete(controller);
+            // A runtime may retire its native body forwarding when the response ends.
+            // Close unfinished input after the response flushes; a consumed upload keeps its connection.
+            if (hasInputBody && !incoming?.readableEnded)
+                abort();
+            else
+                incoming?.resume();
+            await inputSettled;
+            if (incoming) {
+                req.unpipe(incoming);
+                incoming.destroy();
+            }
+            active.delete(abort);
             req.off('aborted', abort);
             req.off('close', onRequestClose);
             req.off('error', abort);
-            req.socket.off('close', onSocketClose);
-            req.socket.off('error', abort);
+            socket.off('close', onSocketClose);
+            socket.off('error', abort);
             res.off('close', onResponseClose);
             res.off('error', abort);
         });
@@ -462,8 +538,8 @@ async function serveOnNode(options) {
     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 abort of active)
+                abort();
             for (const peer of socketServer?.clients ?? [])
                 peer.terminate();
         } socketServer?.close(); server.close(() => { if (closeActive && active.size)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.163",
+  "version": "3.0.164",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/browser-session.ts

@@ -1,19 +1,31 @@
 // A vendor's browser session: the bookkeeping used by its own sign-in and sign-out pages.
 import type { HandlerContext } from './derived-core.ts';
+import { personOf, type Person } from './people.ts';
 
 type Writer = Pick<HandlerContext, 'record' | 'secret' | 'occurredAt'>;
 
-/** The named cookie, without interpreting any other vendor's cookie. */
-export function browserSessionToken(request: Request, name: string): string | undefined {
+/** The value of the cookie `name` the request carries, as a browser sends it back. */
+export function cookieOf(request: Request, name: string): string | undefined {
   for (const part of (request.headers.get('cookie') ?? '').split(';')) {
     const at = part.indexOf('=');
-    if (at > 0 && part.slice(0, at).trim() === name) {
-      try { return decodeURIComponent(part.slice(at + 1).trim()); } catch { return undefined; }
-    }
+    if (at > 0 && part.slice(0, at).trim() === name) return decodeURIComponent(part.slice(at + 1).trim());
   }
   return undefined;
 }
 
+/** The named session cookie; malformed encodings do not name a session. */
+export function browserSessionToken(request: Request, name: string): string | undefined {
+  try { return cookieOf(request, name); } catch { return undefined; }
+}
+
+/** The person the request's session cookie names, or undefined when nobody is signed in; with `scope`, only a session
+ *  begun in it (a vendor's sandbox dashboard and its production one sign a person in apart). */
+export function signedIn(ctx: HandlerContext, cookie: string, scope?: string): Person | undefined {
+  const token = cookieOf(ctx.call.request, cookie);
+  const session = token ? ctx.rowsRaw('_web_session').find((s) => s.token === token && (scope === undefined || s.scope === scope)) : undefined;
+  return session ? personOf(ctx, String(session.email)) : undefined;
+}
+
 /** A new, independent sign-in, returning the cookie the vendor places on its response. */
 export async function startBrowserSession(ctx: Writer, email: string, cookie: string, scope?: string): Promise<string> {
   const issued = await ctx.record('_web_session_issue', { email, ...(scope !== undefined ? { scope } : {}) });