@volter/world-core 3.0.37 → 3.0.39

package/dist/src/pack-fetch.js

@@ -1,3 +1,5 @@
+import { parseExactJson } from "./exact-json.js";
+import { readHostPort } from "./host-port.js";
 // A Protocol 3 pack's whole HTTP surface, served by the kernel from the pack's declarations (docs/contributing/
 // architecture.md, "The pack contract: the kernel's root"): the discovery door (`GET /twin`, the manifest's
 // `discovery`), the vendor's own moves as time passes (`semantics/clock.ts`), the World's doors (the manifest's `doors`,
@@ -10,7 +12,7 @@ import { placedCookies, TWIN_PREFIX_HEADER } from "./twin-fetch.js";
 import { PREFIX_PARAMS_HEADER } from "./derived.js";
 import { withHeaders } from "./with-headers.js";
 import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
-import { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
+import { compileSurface, createDerivedFetch, matchOperation, pathParams } from "./derived.js";
 import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from "./request-scope.js";
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
 import { getActiveWorldStore } from "./world-store.js";
@@ -21,10 +23,12 @@ import { contentAddressOf } from "./content-route.js";
 import { getPack } from "./packRegistry.js";
 import { hostRules } from '../host-routing.cjs';
 import { socketUpgrade } from "./sockets.js";
-import { MACHINE_POOL, POOL_KINDS } from "./machines.js";
+import { MACHINE_POOL, POOL_KINDS, resetFakePool } from "./machines.js";
 import { applyTwinWrite } from "./serve.js";
 import { graphqlEndpoint } from "./graphql-wire.js";
-import { brotliDecompressSync, gunzipSync, gzipSync, inflateSync, zstdDecompressSync } from 'node:zlib';
+import { gzipSync } from 'node:zlib';
+import { decompress } from "./bytes.js";
+import { decodedBodyLimit, oversizedBody, RequestBodyTooLargeError } from "./request-body.js";
 /** A declared path (`/{account}/r2/api-tokens`, `/<room>`, a door's `/_twin/users/{email}`) as a matcher of a request's
  *  path: the path itself, or `prefix` a path under it too (a screen answers its page and the forms it posts). */
 function pathMatcher(pattern, prefix) {
@@ -44,6 +48,9 @@ function pathMatcher(pattern, prefix) {
 }
 /** A declared host (`dash.cloudflare.com`, `<domain>.daily.co`) as a matcher of a request's host. */
 function hostMatcher(pattern) {
+    const whole = /^(?:\{([^}]+)\}|<([^>]+)>)$/.exec(pattern);
+    if (whole)
+        return (host) => host ? { params: { [whole[1] ?? whole[2]]: host } } : undefined;
     const names = [];
     const re = new RegExp(`^${pattern.split('.').map((label) => {
         const m = /^(?:\{([^}]+)\}|<([^>]+)>)$/.exec(label);
@@ -58,7 +65,7 @@ function hostMatcher(pattern) {
     };
 }
 /** The host a request is for: the vendor host the World's injector names, else its own. */
-const hostOf = (request) => (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host).split(':')[0].toLowerCase();
+const hostOf = (request) => readHostPort(request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host)?.host ?? '';
 /** The answer for a path no operation, door or screen serves, and for an operation nothing models: the manifest's
  *  `gap`, its `{method}` and `{path}` filled, else the manifest's not-found refusal. */
 function gapAnswer(m, request, otherMethod = false) {
@@ -68,31 +75,34 @@ function gapAnswer(m, request, otherMethod = false) {
     return vendorError(m, { ...gap, message: gap.message.replace(/\{method\}/g, request.method).replace(/\{path\}/g, path) });
 }
 const METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
-const DECODE = { gzip: gunzipSync, zstd: zstdDecompressSync, deflate: inflateSync, br: brotliDecompressSync };
 /** A request with its body decoded as its Content-Encoding says, when the manifest's `encodings` reads that coding;
  *  undefined when the bytes are not what the header names. */
 async function decoded(m, request) {
+    const codings = (request.headers.get('content-encoding') ?? '').split(',').map(c => c.trim().toLowerCase()).filter(Boolean);
+    if (codings.length > 1)
+        return new Response('Unsupported Content-Encoding', { status: 415 });
     if (request.method === 'GET' || request.method === 'HEAD' || request.body === null)
         return request;
     // the body read once, here, and every part of the pack given a request made again from its bytes: a served request's
     // body read through a clone and then read again (an `around` that checks a body before its handler does) tees a stream
     // whose second branch a Bun server never finishes, and the request hung
     const raw = new Uint8Array(await request.arrayBuffer());
-    const coding = (request.headers.get('content-encoding') ?? '').trim().toLowerCase();
+    const coding = (codings[0] ?? '');
     if (!m.encodings?.request?.includes(coding))
         return new Request(request.url, { method: request.method, headers: request.headers, body: raw });
     let body;
     try {
-        body = DECODE[coding](raw);
+        body = await decompress(raw, coding, decodedBodyLimit(m.descriptor?.maxRequestBodySize));
     }
-    catch {
-        return undefined;
+    catch (error) {
+        return error instanceof RequestBodyTooLargeError ? oversizedBody() : undefined;
     }
     const headers = new Headers(request.headers);
     headers.delete('content-encoding');
     headers.delete('content-length');
-    // a copy over an ArrayBuffer of its own: zlib's result may view a shared buffer, which a request body does not take
-    return new Request(request.url, { method: request.method, headers, body: new Uint8Array(body) });
+    // A finite single-chunk stream holds the decoder's buffer; BufferSource extraction would copy the entire body.
+    const buffered = new ReadableStream({ start(controller) { controller.enqueue(body); controller.close(); } });
+    return new Request(request.url, { method: request.method, headers, body: buffered, duplex: 'half' });
 }
 /** An answer in the coding the request accepts, when the manifest's `encodings` answers in it. */
 async function encoded(m, request, res) {
@@ -108,6 +118,8 @@ async function encoded(m, request, res) {
     return new Response(gzipSync(new Uint8Array(await res.arrayBuffer())), { 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}`);
 export function createPackFetch(parts, options = {}) {
     const m = parts.manifest;
     const scope = {
@@ -133,7 +145,7 @@ export function createPackFetch(parts, options = {}) {
             if (parts.gap) {
                 const url = new URL(request.url);
                 const matched = operation ? matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers) : undefined;
-                return parts.gap(await contextFor(m, { request, operation: operation ?? { id: 'unmatched', method: request.method, path: url.pathname, class: request.method === 'GET' ? 'retrieve' : 'action' }, params: matched?.params ?? {} }, scope));
+                return parts.gap(await contextFor(m, { request, operation: operation ?? { id: 'unmatched', method: request.method, path: url.pathname, class: request.method === 'GET' ? 'retrieve' : 'action' }, params: matched?.params ?? pathParams(routes, url.pathname) }, scope));
             }
             const url = new URL(request.url);
             const other = !matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers)
@@ -165,7 +177,7 @@ export function createPackFetch(parts, options = {}) {
         if (raw === null)
             throw new ScenarioError(`${m.vendor} scenario: no file at ${options.scenarioPath}`);
         if (!engine || raw !== engineRaw) {
-            engine = new ScenarioEngine(parts.scenario.adapter, parseScenarioDocument(JSON.parse(raw), parts.scenario.adapter));
+            engine = new ScenarioEngine(parts.scenario.adapter, parseScenarioDocument(parseExactJson(raw), parts.scenario.adapter));
             engineRaw = raw;
         }
         return engine;
@@ -174,11 +186,13 @@ export function createPackFetch(parts, options = {}) {
     const decided = async (arrived) => {
         if (!parts.scenario)
             return api(arrived);
-        // the body is read once and the request made again from its bytes: a served request's body cloned (for the turn's
-        // context) and then forwarded tees a stream whose second branch a Bun server never finishes, and every turn hung
-        // (measured on merge served with --scenario: no answer in 8 s, matched or not; t_c0279b69)
+        // the body is read once and the request made again from its bytes, so the turn's context and the API each read their
+        // own. Merge served with --scenario once answered no turn in 8 s (t_c0279b69), and this change came with the cure;
+        // putting the earlier read back (the served request cloned for the context, then forwarded) does not reproduce the
+        // hang on its own (2026-10-01: merge's CLI with --scenario, and its life walked over HTTP: every turn answered), so
+        // what hung is UNEXPLAINED, and this is no proof of its cause
         const bytes = arrived.method === 'GET' || arrived.method === 'HEAD' ? undefined : await arrived.arrayBuffer();
-        const request = new Request(arrived.url, { method: arrived.method, headers: arrived.headers, ...(bytes ? { body: bytes } : {}) });
+        const request = new Request(arrived.url, { method: arrived.method, headers: arrived.headers, signal: arrived.signal, ...(bytes ? { body: bytes } : {}) });
         const url = new URL(request.url);
         const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
         if (!matched || !parts.scenario.operations.includes(matched.operation.id))
@@ -212,7 +226,7 @@ export function createPackFetch(parts, options = {}) {
         const answer = parts.doors?.[d.id];
         if (!answer)
             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(d.path.startsWith('/_twin/') ? d.path : `/_twin${d.path.startsWith('/') ? '' : '/'}${d.path}`, false), answer };
+        return { decl: d, path: pathMatcher(doorPath(d.path), false), answer };
     });
     const screens = (m.screens ?? []).filter((s) => s.status === 'done' && parts.screens?.[s.id]).map((s) => {
         const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
@@ -240,23 +254,52 @@ export function createPackFetch(parts, options = {}) {
     };
     // a context the kernel opens for what no surface operation names: a door, a screen, the clock, the board
     const open = (request, id, method, path, params) => contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' }, params }, scope);
+    const advanceClock = async (request) => {
+        if (parts.clock)
+            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;
-    /** The request as its vendor routes it: duplicate slashes collapsed, the manifest's path prefix taken off, a host's
+    // 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 routed = (request) => {
-        const url = new URL(request.url);
-        let path = 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(path)?.groups ?? {}), ...(hostParams?.exec(hostOf(request))?.groups ?? {}) };
+    const rewritten = (pathname, host) => {
+        let path = pathname;
         if (prefix)
             path = path.replace(prefix, '') || '/';
-        const label = hostPath?.exec(hostOf(request))?.[1];
+        // 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
@@ -271,6 +314,8 @@ export function createPackFetch(parts, options = {}) {
     };
     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.
+    const laneDoor = (request, path) => laneDoors(parts.lanes ?? {}, request, path);
     // at a World's place, a page's asset or upload on another of the pack's content hosts is `<base>/@<host>/<path>`
     // (architecture, "A page at a World's place"): answered by the built content screen that names that host exactly,
     // routed from it, and by nothing else; a request naming no such host is general routing's
@@ -341,7 +386,7 @@ export function createPackFetch(parts, options = {}) {
         if (!address || !contentHosts.includes(address.host))
             return undefined;
         const readable = await prepared(arrived);
-        return readable ? atContentHost(readable) : undecodable(arrived);
+        return readable instanceof Response ? readable : readable ? atContentHost(readable) : undecodable(arrived);
     };
     const fetch = async (arrived) => {
         // the discovery door is the pack's own, whichever lane would take its path
@@ -362,10 +407,14 @@ export function createPackFetch(parts, options = {}) {
         const own = await answerContent(arrived);
         if (own)
             return own;
-        const toLane = discovery ? undefined : lane?.(arrived);
+        // 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 toLane = discovery || rootDoor ? undefined : lane?.(arrived);
         if (toLane)
             return toLane(arrived);
         const readable = await prepared(arrived);
+        if (readable instanceof Response)
+            return readable;
         if (!readable)
             return undecodable(arrived);
         const incoming = routed(readable);
@@ -376,40 +425,48 @@ export function createPackFetch(parts, options = {}) {
         const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
         if (request.method === 'GET' && path === '/twin' && m.discovery) {
             const d = m.discovery;
+            const discoveryDoors = [...(m.doors ?? []), ...(m.machines ? [{ id: 'machine-pool', method: 'POST', path: '/_twin/machine-pool', note: 'Enroll the World execution pool: { kind: light | docker | none | fake, images?: { image: { context, command?, runtime? } } }.' }] : [])];
             // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
-            const shown = workspaces().length ? { screens: workspaces() } : {};
+            const laneDiscovery = await laneDoor(request, '/twin');
+            const shown = { ...(workspaces().length ? { screens: workspaces() } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) };
+            const identity = d.identity ?? (m.auth?.held ? 'Authenticate as the vendor does, using a credential issued in this World; unknown credentials are refused.' : undefined);
             // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
             if (parts.scenario && d.behavior) {
-                return Response.json({ ...shown, ...twinManifest({
-                        vendor: m.vendor, twinOf: d.twinOf,
-                        stateSentence: `Stateful: it stores ${d.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here.`,
-                        behaviorSentence: d.behavior, exampleHandler: d.exampleHandler ?? null, ...(engineOf() ? { engine: engineOf() } : {}),
-                    }) });
+                const body = twinManifest({
+                    vendor: m.vendor, twinOf: d.twinOf,
+                    stateSentence: `Stateful: it stores ${d.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here${discoveryDoors.length ? "; what the vendor does on its own pages (not its API) is a door of the World, listed under doors" : ''}.`,
+                    behaviorSentence: d.behavior, exampleHandler: d.exampleHandler ?? null, ...(engineOf() ? { engine: engineOf() } : {}),
+                });
+                const declared = Object.fromEntries(discoveryDoors.map((door) => [`${door.method} ${doorPath(door.path)}`, door.note ?? 'a door of the World']));
+                return Response.json({ ...shown, ...body, program: { ...body.program, ...(identity ? { identity } : {}) }, doors: { ...body.doors, ...declared } });
             }
-            return Response.json({ ...statefulTwinManifest({ vendor: m.vendor, twinOf: d.twinOf, stores: d.stores, ...(d.identity ? { identity: d.identity } : {}), ...(d.notes ? { notes: d.notes } : {}) }), ...shown });
+            return Response.json({ ...statefulTwinManifest({ vendor: m.vendor, twinOf: d.twinOf, stores: d.stores, ...(identity ? { identity } : {}), ...(d.behavior ? { behavior: d.behavior } : {}), ...(d.notes ? { notes: d.notes } : {}), ...(discoveryDoors.length ? { doors: discoveryDoors.map((door) => ({ ...door, path: doorPath(door.path) })) } : {}) }), ...shown });
         }
         // the scenario's handlers with their match counts, and the recent misses
-        if (request.method === 'GET' && path === '/twin/scenario' && parts.scenario)
-            return Response.json(engineOf()?.status() ?? { vendor: m.vendor, handlers: [], misses: 0, recentMisses: [] });
+        if (request.method === 'GET' && path === '/twin/scenario') {
+            const lanes = await laneDoor(request, '/twin/scenario');
+            if (parts.scenario || Object.keys(lanes).length)
+                return Response.json({ ...(engineOf()?.status() ?? { vendor: m.vendor, handlers: [], misses: 0, recentMisses: [] }), ...(Object.keys(lanes).length ? { lanes } : {}) });
+        }
         // the vendor's own moves, not the caller's: its context carries none of the request's headers (a Stripe-Account
         // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
-        if (parts.clock)
-            await runAsVendorMove(async () => parts.clock(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
+        await advanceClock(request);
         if (path.startsWith('/_twin/')) {
             // the World's machine pool, enrolled by the kernel for a vendor that runs images (machines.ts)
             if (m.machines && path === '/_twin/machine-pool' && request.method === 'POST') {
                 if (readOnly)
                     return refusedReadOnly();
-                let kind;
+                let enrollment = {};
                 try {
-                    kind = JSON.parse(await request.clone().text()).kind;
-                }
-                catch {
-                    kind = undefined;
+                    enrollment = parseExactJson(await request.clone().text());
                 }
+                catch { }
+                const kind = enrollment.kind;
                 if (!POOL_KINDS.includes(kind))
                     return Response.json({ message: `kind must be one of ${POOL_KINDS.join(', ')}` }, { status: 400 });
-                await applyTwinWrite(m.service, { operation: 'machine_pool.enroll', subjectType: MACHINE_POOL, subjectId: 'pool', fields: { kind }, occurredAt: (await open(request, 'machine-pool', 'POST', '/_twin/machine-pool', {})).occurredAt, actor: { kind: 'system' } }, options.root);
+                await applyTwinWrite(m.service, { operation: 'machine_pool.enroll', subjectType: MACHINE_POOL, subjectId: 'pool', fields: { kind, ...(kind === 'fake' && Array.isArray(enrollment.httpReplies) ? { httpReplies: enrollment.httpReplies } : {}), ...(kind === 'light' ? { images: enrollment.images ?? {} } : {}) }, occurredAt: (await open(request, 'machine-pool', 'POST', '/_twin/machine-pool', {})).occurredAt, actor: { kind: 'system' } }, options.root);
+                if (kind === 'fake')
+                    resetFakePool(m.service, options.root);
                 return Response.json({ kind }, { status: 201 });
             }
             for (const d of doors) {
@@ -455,12 +512,34 @@ export function createPackFetch(parts, options = {}) {
                 return refusedReadOnly();
             return byPath.s.answer(await open(request, byPath.s.decl.id, request.method, byPath.s.decl.path, { ...(byPath.onHost?.params ?? {}), ...byPath.hit.params }));
         }
+        for (const route of m.machineRoutes ?? []) {
+            const host = request.headers.get('x-volter-twin-original-host') ?? new URL(request.url).hostname;
+            const match = new RegExp(route.host).exec(host);
+            if (!match)
+                continue;
+            const ctx = await open(request, 'machine.traffic', request.method, url.pathname, match.groups ?? {});
+            const field = (row, path) => path.split('.').reduce((value, key) => value && typeof value === 'object' ? value[key] : undefined, row);
+            const fill = (value, row = {}) => value.replace(/\{([^}]+)\}/g, (_, key) => String(match.groups?.[key] ?? field(row, key) ?? ''));
+            const row = ctx.rowsRaw(route.resource).find(row => Object.entries(route.where).every(([key, value]) => String(field(row, key)) === fill(value)));
+            if (!row)
+                return new Response('Guest is unavailable', { status: 503 });
+            try {
+                return await ctx.machines.request(String(field(row, route.name)), Number(typeof route.port === 'string' ? fill(route.port, row) : route.port), request);
+            }
+            catch {
+                return new Response('Guest is unavailable', { status: 503 });
+            }
+        }
         if (!parts.around)
             return encoded(m, request, await decided(request));
-        const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
-        const operation = matched?.operation ?? { id: 'unmatched', method: request.method, path: url.pathname, class: request.method === 'GET' ? 'retrieve' : 'action' };
-        const ctx = await contextFor(m, { request: request.clone(), operation, params: matched?.params ?? {} }, scope);
-        return encoded(m, request, await parts.around(ctx, (rewritten) => decided(rewritten ?? request)));
+        // The front reads a context before forwarding (possibly with new headers). Materialize a transport body before
+        // those independent reads, rather than chaining tees of the incoming stream through the front and the scenario.
+        const bytes = request.method === 'GET' || request.method === 'HEAD' ? undefined : await request.arrayBuffer();
+        const buffered = new Request(request.url, { method: request.method, headers: request.headers, signal: request.signal, ...(bytes ? { body: bytes } : {}) });
+        const matched = matchOperation(routes, buffered.method, url.pathname, url.searchParams, buffered.headers);
+        const operation = matched?.operation ?? { id: 'unmatched', method: buffered.method, path: url.pathname, class: buffered.method === 'GET' ? 'retrieve' : 'action' };
+        const ctx = await contextFor(m, { request: buffered.clone(), operation, params: matched?.params ?? pathParams(routes, url.pathname) }, scope);
+        return encoded(m, buffered, await parts.around(ctx, (rewritten) => decided(rewritten ?? buffered)));
     };
     // the request's id is the correlation of every entry it appends (runtime contract D3), minted here, always: it is the
     // group a perform sends as one call (the real-system adapters, "Perform"). Under `auto` the group is performed once
@@ -508,12 +587,20 @@ export function createPackFetch(parts, options = {}) {
     for (const d of m.sockets ?? [])
         if (!parts.sockets?.[d.id])
             throw new Error(`${m.vendor}: the manifest declares the socket ${d.id}, and semantics/sockets.ts exports no ${d.id}`);
-    const upgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets, (request, d) => open(request, `socket:${d.id}`, 'GET', d.path, {}), hostOf, (request) => new URL(routed(request).url).pathname, 
+    const ownUpgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets, (request, d) => open(request, `socket:${d.id}`, 'GET', d.path, {}), hostOf, (request) => new URL(routed(request).url).pathname, 
     // a turn a session speaks (a voice agent's reply) is the World's scenario's, as a turn over HTTP is
     async (asked) => engineOf()?.serve(asked)) : undefined;
-    // what serves each operation: the pack's own, and each lane's
-    const owners = () => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
-    return derivedRequestScopes(m, Object.assign(served, { owners, serves, workspaces, boards: Boolean(parts.board), draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }));
+    const upgrade = laneUpgrades(parts.lanes ?? {}, ownUpgrade);
+    // what serves each operation: the pack's own, and each lane's, each unit's under its own name
+    const ownersByUnit = () => ({
+        '': {
+            ...((surface.format === 'command-reply' || surface.format === 'command-table' && m.descriptor?.transport === 'raw-tcp') ? Object.fromEntries((surface.commands ?? []).map((c) => [c.id, parts.around && !m.unmodeled?.includes(c.id) ? 'handler' : 'gap'])) : api.owners()),
+            ...Object.fromEntries((parts.graphql?.operations ?? []).map((op) => [op.id, `${op.kind === 'query' ? 'Query' : 'Mutation'}.${op.field}` in (parts.graphql?.resolvers ?? {}) ? 'handler' : 'gap'])),
+        },
+        ...lanesOwners(parts.lanes ?? {}),
+    });
+    const owners = () => flatOwners(ownersByUnit());
+    return derivedRequestScopes(m, Object.assign(served, { owners, ownersByUnit, serves, advanceClock, workspaces, boards: Boolean(parts.board), maxRequestBodySize: m.descriptor?.maxRequestBodySize, draws: drawsUrl, contentHosts, ...(upgrade ? { upgrade } : {}) }), 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. */
@@ -568,13 +655,52 @@ function laneRouter(vendor, decl, lanes, rootServes = () => false) {
 }
 /** A vendor whose every API is a lane (Cloudflare's API v4 and R2, AWS's services), served from its manifest: the
  *  discovery door, then its lanes as its gateway sends them; a request no lane takes is the vendor's not-found. */
-/** What serves each of a vendor's lanes' operations (a handler, the core, or the gap), as one map. */
-const lanesOwners = (lanes) => Object.assign({}, ...Object.values(lanes).map((l) => l.fetch.owners?.() ?? {}));
+/** Each lane's answer at one of its World doors (`/twin`, `/twin/scenario`), by lane, read from the lane directly rather
+ *  than routed back through the vendor's front: a vendor's discovery holds its lanes' (their doors, their scripts). */
+async function laneDoors(lanes, request, path) {
+    const entries = await Promise.all(Object.entries(lanes).map(async ([name, part]) => {
+        const url = new URL(request.url);
+        url.pathname = path;
+        url.search = '';
+        const answer = await part.fetch(new Request(url, { headers: request.headers, signal: request.signal }));
+        return answer.ok ? [name, await answer.json()] : undefined;
+    }));
+    return Object.fromEntries(entries.filter((entry) => entry !== undefined));
+}
+/** What serves each of a vendor's lanes' operations (a handler, the core, or the gap), by lane: a lane's operation is the
+ *  lane's own, so an id it shares with its root or another lane (Clerk's Backend and Frontend APIs both name
+ *  `ListOrganizationMemberships`) keeps the lane's own owner, and a lane's gap stays a gap whoever else serves the id. */
+const lanesOwners = (lanes) => Object.fromEntries(Object.entries(lanes).map(([name, l]) => [name, l.fetch.owners?.() ?? {}]));
+/** A vendor's owners as one map, for its breadth: its own API's operations by id, a lane's as `<lane>:<id>`. */
+const flatOwners = (byUnit) => Object.fromEntries(Object.entries(byUnit).flatMap(([unit, map]) => Object.entries(map).map(([id, owner]) => [unit ? `${unit}:${id}` : id, owner])));
 /** The workspaces a vendor's lanes draw, as one list. */
 const lanesWorkspaces = (lanes) => Object.values(lanes).flatMap((l) => l.fetch.workspaces?.() ?? []);
+/** Keep each upgraded peer on the vendor or lane engine that accepted its opening request. */
+function laneUpgrades(lanes, own) {
+    const choices = [own, ...Object.values(lanes).map(lane => lane.fetch.upgrade)].filter((choice) => choice !== undefined);
+    if (choices.length === 0)
+        return undefined;
+    if (choices.length === 1)
+        return choices[0];
+    const held = new WeakMap();
+    const select = (request) => choices.find(choice => choice.accepts(request));
+    return {
+        accepts: request => select(request) !== undefined,
+        protocol: request => select(request)?.protocol?.(request),
+        open(peer, request) { const selected = select(request); if (selected) {
+            held.set(peer, selected);
+            selected.open(peer, request);
+        } },
+        message(peer, data) { return held.get(peer)?.message(peer, data); },
+        close(peer) { const selected = held.get(peer); held.delete(peer); selected?.close(peer); },
+    };
+}
 export function createVendorFetch(manifest, lanes) {
+    const upgrade = laneUpgrades(lanes);
     const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
     return Object.assign(async (request) => {
+        for (const part of Object.values(lanes))
+            await part.fetch.advanceClock?.(request);
         const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
         // the vendor's board is the frames of the lanes that lay one out, each drawn when any lane's screen takes its url
         if (request.method === 'GET' && path === '/twin/board') {
@@ -595,9 +721,15 @@ export function createVendorFetch(manifest, lanes) {
         if (request.method === 'GET' && path === '/twin' && manifest.discovery) {
             // the vendor's screens are its lanes' (a dashboard drawn by one lane is the vendor's)
             const screens = lanesWorkspaces(lanes);
-            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}) });
+            const laneDiscovery = await laneDoors(lanes, request, '/twin');
+            return Response.json({ ...statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }), ...(screens.length ? { screens } : {}), ...(Object.keys(laneDiscovery).length ? { lanes: laneDiscovery } : {}) });
+        }
+        if (request.method === 'GET' && path === '/twin/scenario') {
+            const laneScenarios = await laneDoors(lanes, request, '/twin/scenario');
+            if (Object.keys(laneScenarios).length)
+                return Response.json({ vendor: manifest.vendor, lanes: laneScenarios });
         }
         const to = lane(request);
         return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });
-    }, { owners: () => lanesOwners(lanes), workspaces: () => lanesWorkspaces(lanes) });
+    }, { maxRequestBodySize: manifest.descriptor?.maxRequestBodySize, owners: () => flatOwners(lanesOwners(lanes)), ownersByUnit: () => lanesOwners(lanes), workspaces: () => lanesWorkspaces(lanes), ...(upgrade ? { upgrade } : {}) });
 }

package/dist/src/packRegistry.d.ts

@@ -140,6 +140,7 @@ export type HostRule = ({
     hostPattern: string;
 }) & {
     pathPattern?: string;
+    demandPathPattern?: string | false;
     key?: string;
     exclude?: true;
 };
@@ -171,6 +172,8 @@ export type TwinPack = {
     rateBudget?: RateBudgetDeclaration;
     emitter?: TwinEmitter;
     serveExport?: string;
+    /** Declared HTTP transport cap, in bytes; the serve seam and World fronts honor it. */
+    maxRequestBodySize?: number;
     adoption?: {
         sdks?: string[];
         pypi?: string[];
@@ -187,6 +190,9 @@ export type TwinPack = {
             usage: 'build' | 'deployment';
         }>;
     };
+    /** Why no client case is owed though `adoption.sdks` names npm clients: the vendor maintains no official SDK, or the
+     *  demand's applications use none (architecture, "The descriptor"; `conform`'s client check reads it). */
+    clientCasesNone?: string;
     hosts?: HostRule[];
     hostsNone?: string;
     hostsClaimed?: {
@@ -202,7 +208,7 @@ export type TwinPack = {
     /** The door that issues the application the credentials the twin will accept (a key made on the vendor's dashboard,
      *  and whatever names it: a database's URL, a project's id), and the env names it fills, each from a field of the
      *  answer: `init` writes `$issue:<service>` for each, and `up`, once this twin is running, POSTs the body to the door
-     *  and sets each name to its field. A twin that holds its keys (refusing any it
+     *  and sets each name to its field (`file:<field>` materializes one file; `directory:<field>` a relative-file map). A twin that holds its keys (refusing any it
      *  did not issue) declares one, so a World's applications hold keys it issued rather than fixtures it refuses. */
     credentialDoor?: {
         path: string;

package/dist/src/packRegistry.js

@@ -117,12 +117,29 @@ beside = {}) {
     if (hand.length)
         throw new Error(`${manifest.vendor}: the descriptor declares ${hand.join(', ')} by hand; the kernel derives them from the manifest (architecture, "The real-system adapters")`);
     const pack = { vendor: manifest.vendor, ...manifest.descriptor, ...(manifest.rateBudget ? { rateBudget: manifest.rateBudget } : {}) };
-    // a pack with no vendor-backed half says why, and derives no adapters
-    if (manifest.vendorBacked?.none)
+    // a pack with no vendor-backed half says why, and derives no adapters; one whose own surface has none beside lanes
+    // that do derives its lanes' adapters, its own writes settled as the World's (`unsent`)
+    const live = Object.fromEntries(Object.entries(beside).filter(([, l]) => !l.manifest.vendorBacked?.none));
+    if (manifest.vendorBacked?.none && !Object.keys(live).length)
         return { ...pack, vendorBacked: { none: manifest.vendorBacked.none } };
     if (!surface)
         return pack;
-    const lanes = 'operations' in surface ? undefined : surface;
+    // the unit's own surface: its operations, or a command table (a vendor that carries Redis over HTTP: architecture,
+    // "Other wires"), which names no operation a derived adapter performs; anything else is a map of lanes
+    const ownSurface = 'operations' in surface || 'commands' in surface;
+    if (manifest.vendorBacked?.none && ownSurface) {
+        const own = new Set((surface.operations ?? []).map((o) => o.id));
+        // a command table's every write is the unit's own (no operation of it is performed)
+        const commandTable = !('operations' in surface);
+        const why = manifest.vendorBacked.none;
+        const references = [manifest, ...Object.values(beside).map((l) => l.manifest)].flatMap(derivedReferences);
+        return {
+            ...pack,
+            stateSystem: { ...deriveVendorStateSystem(manifest, live), unsent: (input) => (input && typeof input.lane !== 'string' && (commandTable || own.has(String(input.operationId))) ? why : undefined) },
+            ...(references.length ? { references } : {}),
+        };
+    }
+    const lanes = ownSurface ? undefined : surface;
     const units = lanes ? Object.values(lanes).map((l) => l.manifest) : [manifest, ...Object.values(beside).map((l) => l.manifest)];
     const references = units.flatMap(derivedReferences);
     return {

package/dist/src/private-transport.d.ts

@@ -0,0 +1 @@
+export declare function privateTransportKey(namespace: string): string;

package/dist/src/private-transport.js

@@ -0,0 +1,11 @@
+// Process-local ingress capabilities for byte-stream fronts using an internal request seam.
+// Lazy: importing the pack contract creates no key and opens no process handle.
+const keys = new Map();
+export function privateTransportKey(namespace) {
+    let key = keys.get(namespace);
+    if (!key) {
+        key = crypto.randomUUID();
+        keys.set(namespace, key);
+    }
+    return key;
+}

package/dist/src/protobuf.js

@@ -87,7 +87,7 @@ function writeScalar(w, type, v) {
             break;
         case 'fixed32':
         case 'sfixed32':
-            w.fixed(Number(v), 4);
+            w.fixed(BigInt(v), 4);
             break;
         case 'float':
             w.fixed(Number(v), 4, true);
@@ -228,7 +228,7 @@ function readScalar(r, type) {
         case 'uint32': return Number(BigInt.asUintN(32, r.varint()));
         case 'int64': return String(BigInt.asIntN(64, r.varint()));
         case 'uint64': return String(BigInt.asUintN(64, r.varint()));
-        case 'sint32': return Number(unzigzag(r.varint()));
+        case 'sint32': return Number(BigInt.asIntN(32, unzigzag(r.varint())));
         case 'sint64': return String(unzigzag(r.varint()));
         case 'bool': return r.varint() !== 0n;
         case 'fixed64': return String(new DataView(r.take(8).slice().buffer).getBigUint64(0, true));
@@ -291,7 +291,10 @@ export function decodeMessage(schema, type, bytes) {
     const out = {};
     const r = new Reader(bytes);
     while (!r.done) {
-        const key = Number(r.varint());
+        const rawKey = r.varint();
+        if (rawKey > 0xffffffffn)
+            throw new Error('protobuf: field tag exceeds 32 bits');
+        const key = Number(rawKey);
         const number = key >>> 3;
         const wire = key & 7;
         const f = byNumber.get(number);
@@ -304,7 +307,10 @@ export function decodeMessage(schema, type, bytes) {
             let k;
             let v;
             while (!entry.done) {
-                const ek = Number(entry.varint());
+                const rawKey = entry.varint();
+                if (rawKey > 0xffffffffn)
+                    throw new Error('protobuf: map field tag exceeds 32 bits');
+                const ek = Number(rawKey);
                 if ((ek >>> 3) === 1)
                     k = readValue(schema, entry, { type: f.map.key, kind: 'scalar' }, ek & 7);
                 else if ((ek >>> 3) === 2)

package/dist/src/rateBudget.d.ts

@@ -86,6 +86,13 @@ export type RateBudgetDeclaration = {
      * review, and the ceiling is the one number that can cost days if it is wrong.
      */
     reason: string;
+    /** The vendor's documented allowance, in calls a minute, and the page that documents it, which the pack cites on a
+     *  `// source:` line (checked like every other vendor fact): required of a budget that admits more than the fallback
+     *  (`scripts/rate-budget-check.ts`). */
+    allowance?: {
+        perMinute: number;
+        source: string;
+    };
 };
 /**
  * A declaration bound to the vendor it governs, with every pattern already compiled. The `RegExp`s
@@ -94,7 +101,7 @@ export type RateBudgetDeclaration = {
  * pattern. (Declarations are repo source, not user input — this is a performance fix, not a
  * sanitizer.)
  */
-export type RateBudgetPolicy = Required<Omit<RateBudgetDeclaration, 'rules'>> & {
+export type RateBudgetPolicy = Required<Omit<RateBudgetDeclaration, 'rules' | 'allowance'>> & Pick<RateBudgetDeclaration, 'allowance'> & {
     vendor: string;
     rules: RateBudgetWeightRule[];
     /** `compiled[i]` is `rules[i].match`, compiled. Same length, same order. */

package/dist/src/rateBudget.js

@@ -248,6 +248,7 @@ function normalize(vendor, decl) {
     return {
         vendor,
         reason: decl.reason,
+        ...(decl.allowance ? { allowance: { ...decl.allowance } } : {}),
         windowMs,
         ceiling,
         burstCeiling,