@volter/world-core 3.0.162 → 3.0.164

package/src/events.ts

@@ -7,11 +7,12 @@
 // Imports stay free of side effects: the delivery's transport (Node's http, the World's egress policy) is loaded when a
 // delivery is made, never when a browser client imports the kernel.
 import { createHash, createHmac } from 'node:crypto';
+import { resolve } from 'node:path';
 import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from './serve.ts';
 import { equalSecrets as same, ksuidFrom } from './signing.ts';
 import { deliveryTraceHeaders } from './trace-context.ts';
 import { sendRecordedEvent } from './event-delivery.ts';
-import { getActiveWorldStore, withWorldStore } from './world-store.ts';
+import { getActiveWorldStore, withWorldStore, type WorldStore } from './world-store.ts';
 import { worldPaths } from './storage.ts';
 
 /** How the vendor signs a delivery. */
@@ -306,6 +307,26 @@ const worldTransport: EventTransport = async (url, body, headers) => {
   try { return ((await appFetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body })) as { status: number }).status; } catch { return 0; }
 };
 
+const pendingDeliveries = new WeakMap<WorldStore, Map<string, Set<Promise<void>>>>();
+
+function forgetDeliveries(store: WorldStore, root: string, deliveries: Iterable<Promise<void>>): void {
+  const roots = pendingDeliveries.get(store), pending = roots?.get(root);
+  if (!pending) return;
+  for (const delivery of deliveries) pending.delete(delivery);
+  if (!pending.size) roots!.delete(root);
+  if (!roots!.size) pendingDeliveries.delete(store);
+}
+
+/** Await already-scheduled first dispatches and consume their retained persistence failures. */
+export async function settleEventDeliveries(root: string): Promise<void> {
+  const store = getActiveWorldStore(), path = resolve(root);
+  const deliveries = [...(pendingDeliveries.get(store)?.get(path) ?? [])];
+  const outcomes = await Promise.allSettled(deliveries);
+  forgetDeliveries(store, path, deliveries);
+  const failures = outcomes.flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+  if (failures.length) throw new AggregateError(failures, 'Declared-event dispatch failed');
+}
+
 /** Who watches signed packets before dispatch (a walk reading each as its receiver would). This is not evidence of
  *  transport or acceptance. Set and restored by the walk, as its World store is; unset, nothing watches. */
 export type DeliveryObserver = (delivery: EventDelivery & { service: string }) => void;
@@ -321,13 +342,14 @@ export function setDeliveryObserver(observer: DeliveryObserver | undefined): Del
  *  (`unreachable`), or it did not answer in time (`timeout`). */
 export type ApplicationAnswer = { status: number; headers: Record<string, string>; body: string; missed?: 'timeout' | 'unreachable' };
 
-/** Who answers what the vendor asks the application (`ctx.ask`) before the World's application route does, given to a
+/** Who answers a vendor's requests to the application before the World's application route does, given to a
  *  pack's fetch (`PackFetchOptions.application`) and belonging to that fetch alone: an answer it gives is the
  *  application's; `'unreachable'` is a question nobody answers (a walk's life, a sealed World, takes no other); undefined
  *  is a question it does not take, which goes on as any other does: the application route, the World's egress rule, the
  *  network. A walk's stand-in answers every question (its life's answers, else unreachable); a hosted World's router
  *  answers only what it can answer truthfully (WorldDoors.askInWorld) and leaves the rest. `bodyError` models a
- *  disconnect after the response headers; a caller needing the complete body receives no complete answer. */
+ *  disconnect after the response headers; a caller needing the complete body receives no complete answer, while an
+ *  event dispatch acknowledges the response status without reading its body. */
 export type ApplicationStandIn = (url: string, init: RequestInit) => Promise<{ status: number; headers?: Record<string, string>; body: string; bodyError?: string } | 'unreachable' | undefined>;
 
 /** A message the vendor sends the application's server and decides by its answer (Stripe's real-time authorization
@@ -367,10 +389,15 @@ export async function deliverEvents(
   data: (type: string) => Promise<Record<string, unknown>>,
   transport: EventTransport = worldTransport,
   values?: (type: string) => Promise<Record<string, unknown>>,
+  application?: ApplicationStandIn,
 ): Promise<EventDelivery[]> {
   if (write.storedType === decl.store) return [];
+  const dispatch: EventTransport = application ? async (url, body, headers) => {
+    const answer = await application(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body });
+    return answer === undefined ? transport(url, body, headers) : answer === 'unreachable' ? 0 : answer.status;
+  } : transport;
   const sent: EventDelivery[] = [];
-  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, transport, values, type)));
+  for (const type of eventTypesOf(decl, write.operation)) sent.push(...(await deliverEventType(service, decl, write, data, dispatch, values, type)));
   return sent;
 }
 
@@ -466,10 +493,28 @@ async function deliverEventType(
   // active before it runs. Transport completion writes to the same retained state.
   const store = getActiveWorldStore(), deliveryRoot = worldPaths(service, write.root).root;
   for (const d of sent) deliveryObserver?.({ ...d, service });
-  for (const packet of recorded) setTimeout(() => {
-    // Persistence failure leaves a queued/sending claim for explicit recovery;
-    // it must not fail the already-committed vendor write or cause a blind resend.
-    void withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace)).catch(() => {});
-  }, 0);
+  const roots = pendingDeliveries.get(store) ?? new Map<string, Set<Promise<void>>>();
+  pendingDeliveries.set(store, roots);
+  const pending = roots.get(deliveryRoot) ?? new Set<Promise<void>>();
+  roots.set(deliveryRoot, pending);
+  for (const packet of recorded) {
+    let finish!: () => void;
+    let fail!: (reason: unknown) => void;
+    const dispatched = new Promise<void>((done, reject) => { finish = done; fail = reject; });
+    // Live writes return before dispatch; an explicit settlement reports persistence failures.
+    void dispatched.catch(() => {});
+    pending.add(dispatched);
+    setTimeout(async () => {
+      try {
+        await withWorldStore(store, () => sendRecordedEvent(service, packet.type, packet.id, deliveryRoot, transport, trace));
+        finish();
+        forgetDeliveries(store, deliveryRoot, [dispatched]);
+      } catch (error) {
+        // Keep the rejection until explicit settlement consumes it. The queued/sending claim remains for
+        // native recovery; this must not fail the already-committed vendor write or cause a blind resend.
+        fail(error);
+      }
+    }, 0);
+  }
   return sent;
 }

package/src/file-response.ts

@@ -25,10 +25,16 @@ export function fileResponse(path: string, init?: ResponseInit): Response {
  * Stored bytes as a response, honouring a single `Range: bytes=` as RFC 9110 §14 has it: every satisfiable range is a
  * 206 with its Content-Range, `bytes=0-` (the whole body) included; a range that does not parse, a first-byte-pos past
  * its last-byte-pos (`bytes=5-2`) included, is ignored and the whole body is a 200; a well-formed range that starts past
- * the end (any range of an empty body) is a 416. `nosniff` stops a browser second-guessing the content type the vendor gave.
+ * the end (any range of an empty body) is a 416. Lazy sources supply inclusive ranges and stream in bounded reads.
+ * `nosniff` stops a browser second-guessing the content type the vendor gave.
  */
-export function bytesResponse(request: Request, bytes: Uint8Array, contentType: string, cacheControl = 'public, max-age=604800, immutable'): Response {
-  const total = bytes.length;
+export function bytesResponse(
+  request: Request,
+  bytes: Uint8Array | { size: number; range(start: number, end: number): Promise<Uint8Array | null> },
+  contentType: string,
+  cacheControl = 'public, max-age=604800, immutable',
+): Response {
+  const total = bytes instanceof Uint8Array ? bytes.length : bytes.size;
   const base = { 'content-type': contentType, 'x-content-type-options': 'nosniff', 'accept-ranges': 'bytes', 'cache-control': cacheControl };
   const range = /^bytes=(\d*)-(\d*)$/.exec((request.headers.get('range') ?? '').trim());
   let start = 0;
@@ -44,9 +50,25 @@ export function bytesResponse(request: Request, bytes: Uint8Array, contentType:
   // every satisfiable range is answered as one, the whole body's `bytes=0-` included: a media player (Safari's) reads a
   // 206 with its Content-Range as the server taking ranges, and a 200 as one it cannot seek in
   const partial = valid;
-  const body = bytes.slice(start, end + 1);
-  return new Response(request.method === 'HEAD' ? null : new Blob([body]), {
+  let body: BodyInit | null = null;
+  if (request.method !== 'HEAD') {
+    if (bytes instanceof Uint8Array) body = new Blob([bytes.slice(start, end + 1)]);
+    else {
+      let at = start;
+      body = new ReadableStream<Uint8Array>({
+        async pull(controller) {
+          if (at > end) { controller.close(); return; }
+          const last = Math.min(at + 8 * 1024 * 1024 - 1, end);
+          const chunk = await bytes.range(at, last);
+          if (!chunk) { controller.error(new Error('stored bytes are gone')); return; }
+          controller.enqueue(chunk);
+          at = last + 1;
+        },
+      });
+    }
+  }
+  return new Response(body, {
     status: partial ? 206 : 200,
-    headers: { ...base, 'content-length': String(body.length), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
+    headers: { ...base, 'content-length': String(end + 1 - start), ...(partial ? { 'content-range': `bytes ${start}-${end}/${total}` } : {}) },
   });
 }

package/src/index.ts

@@ -89,6 +89,7 @@ export * as protobuf from './protobuf.ts';
 export * as grpc from './grpc-wire.ts';
 export { acceptH2Connection, type H2Handler, type Http1Handler } from './h2.ts';
 export { placeholderPng } from './placeholder-image.ts';
+export { imageDimensions, readImageHeader, readMp4Header } from './media-header.ts';
 export { presignSigV4, signSigV4, verifySigV4, type SigV4Verdict } from './sigv4.ts';
 export * as redis from './redis/index.ts';
 export * as mysql from './mysql/index.ts';
@@ -102,7 +103,7 @@ export type { PackScenarioAdapter, ScenarioDecision, ScenarioDocument, ScenarioE
 
 export { verifyAttestationBundle } from './attestation.ts';
 
-export { browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';
+export { cookieOf, signedIn, browserSessionToken, startBrowserSession, endBrowserSession } from './browser-session.ts';
 
 export { readHostPort } from './host-port.ts';
 export { assertBrowserName, browserOrigin, validateBrowserState, validateBrowserStorageState, validateBrowserContext, browserAcceptLanguage, cookieMatchesHost, type BrowserCookie, type BrowserState, type BrowserStorageState, type BrowserContext, type BrowserIndexedDB } from './browser-state.ts';

package/src/managed-database.ts

@@ -254,10 +254,10 @@ export function managedDatabase(url: string, options: { readOnly?: boolean } = {
  *  walk/journey-kit.ts), its statements sent as its client sends them: a text alone as one simple Query (a migration
  *  file, a `BEGIN`), a text with values as one extended-protocol statement, the values bind parameters. A transaction it
  *  opens stays open across its statements until it ends it, as on the application's own connection. Each statement's
- *  answer is its results in Postgres's text format, untyped. */
-export type DatabaseSession = { query(text: string, values?: ReadonlyArray<string | null>): Promise<StatementResult[]>; end(): Promise<void> };
+ *  answer is its results in Postgres's text format, with native column type OIDs retained beside the values. */
+export type DatabaseSession = { query(text: string, values?: ReadonlyArray<string | null>): Promise<Array<StatementResult & { fieldTypes: number[] }>>; end(): Promise<void> };
 
-type PgResult = { command?: string | null; rowCount?: number | null; fields?: Array<{ name: string }>; rows?: Array<Array<string | null>> };
+type PgResult = { command?: string | null; rowCount?: number | null; fields?: Array<{ name: string; dataTypeID: number }>; rows?: Array<Array<string | null>> };
 
 /** The World's Postgres at `url` as one connection held until `end()`. */
 export async function databaseSession(url: string): Promise<DatabaseSession> {
@@ -277,6 +277,7 @@ export async function databaseSession(url: string): Promise<DatabaseSession> {
         const answer = (await (client.query({ text, ...(values === undefined ? {} : { values }), rowMode: 'array', types: raw }) as Promise<PgResult | PgResult[]>));
         return (Array.isArray(answer) ? answer : [answer]).map((r) => ({
           fields: (r.fields ?? []).map((f) => f.name),
+          fieldTypes: (r.fields ?? []).map((f) => f.dataTypeID),
           rows: r.rows ?? [],
           command: [r.command ?? '', r.command === 'INSERT' ? '0' : '', r.rowCount ?? ''].filter((part) => part !== '').join(' '),
         }));

package/src/media-header.ts

@@ -0,0 +1,108 @@
+// File-format headers only: no decoding, vendor limits, processing or rendition policy.
+type ImageType = 'image/png' | 'image/gif' | 'image/jpeg' | 'image/webp';
+type Dimensions = { width: number; height: number };
+type ImageHeader = Dimensions & { jpeg?: { frameEnd: number; nonMarkerBytes: boolean; standaloneMarkers: boolean; fillBytes: boolean; shortSegments: boolean } };
+
+const tag = (bytes: Uint8Array, at: number): string => String.fromCharCode(...bytes.subarray(at, at + 4));
+
+/** Dimensions in a caller-declared image format, or undefined for an incomplete header. */
+export function imageDimensions(bytes: Uint8Array, type: ImageType): ImageHeader | undefined {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (type === 'image/png') return bytes.length >= 24 ? { width: view.getUint32(16), height: view.getUint32(20) } : undefined;
+  if (type === 'image/gif') return bytes.length >= 10 ? { width: view.getUint16(6, true), height: view.getUint16(8, true) } : undefined;
+  if (type === 'image/webp') {
+    if (bytes.length < 30) return undefined;
+    const chunk = tag(bytes, 12);
+    if (chunk === 'VP8 ') return { width: view.getUint16(26, true) & 0x3fff, height: view.getUint16(28, true) & 0x3fff };
+    if (chunk === 'VP8L') {
+      const bits = view.getUint32(21, true);
+      return { width: 1 + (bits & 0x3fff), height: 1 + ((bits >>> 14) & 0x3fff) };
+    }
+    if (chunk === 'VP8X') {
+      const u24 = (at: number): number => bytes[at]! | (bytes[at + 1]! << 8) | (bytes[at + 2]! << 16);
+      return { width: 1 + u24(24), height: 1 + u24(27) };
+    }
+    return undefined;
+  }
+  let at = 2;
+  const jpeg = { frameEnd: 0, nonMarkerBytes: false, standaloneMarkers: false, fillBytes: false, shortSegments: false };
+  while (at + 4 <= bytes.length) {
+    if (bytes[at] !== 0xff) { jpeg.nonMarkerBytes = true; at += 1; continue; }
+    const marker = bytes[at + 1]!;
+    if (marker === 0xff) { jpeg.fillBytes = true; at += 1; continue; }
+    if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) { jpeg.standaloneMarkers = true; at += 2; continue; }
+    const length = view.getUint16(at + 2);
+    if (length < 2) jpeg.shortSegments = true;
+    if (marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc) {
+      return at + 9 <= bytes.length ? { width: view.getUint16(at + 7), height: view.getUint16(at + 5), jpeg: { ...jpeg, frameEnd: at + 9 } } : undefined;
+    }
+    if (marker === 0xda) return undefined;
+    at += 2 + length;
+  }
+  return undefined;
+}
+
+/** An image's signature and dimensions, without deciding whether a vendor accepts that format or size. */
+export function readImageHeader(bytes: Uint8Array): (ImageHeader & { type: ImageType }) | undefined {
+  let type: ImageType;
+  if (bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47) type = 'image/png';
+  else if (tag(bytes, 0).startsWith('GIF')) type = 'image/gif';
+  else if (bytes[0] === 0xff && bytes[1] === 0xd8) type = 'image/jpeg';
+  else if (tag(bytes, 0) === 'RIFF' && tag(bytes, 8) === 'WEBP') type = 'image/webp';
+  else return undefined;
+  const dimensions = imageDimensions(bytes, type);
+  return dimensions ? { type, ...dimensions } : undefined;
+}
+
+/** ISO BMFF's bounded top-level boxes and movie headers, with raw duration and 16.16 track dimensions. */
+export function readMp4Header(bytes: Uint8Array): {
+  fileType: boolean;
+  hasMediaData: boolean;
+  movies: Array<{ headers: Array<{ timescale: number; duration: number; payloadSize: number }>; tracks: Dimensions[] }>;
+} {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  function* boxes(from: number, to: number): Generator<{ type: string; start: number; end: number }> {
+    let at = from;
+    while (at + 8 <= to) {
+      let size = view.getUint32(at);
+      const type = tag(bytes, at + 4);
+      let header = 8;
+      if (size === 1) {
+        if (at + 16 > to) return;
+        size = Number(view.getBigUint64(at + 8));
+        header = 16;
+      }
+      if (size === 0) size = to - at;
+      if (!Number.isSafeInteger(size) || size < header || size > to - at) return;
+      yield { type, start: at + header, end: at + size };
+      at += size;
+    }
+  }
+  const result: ReturnType<typeof readMp4Header> = { fileType: bytes.length >= 8 && tag(bytes, 4) === 'ftyp', hasMediaData: false, movies: [] };
+  for (const box of boxes(0, bytes.length)) {
+    if (box.type === 'mdat' && box.end > box.start) result.hasMediaData = true;
+    if (box.type !== 'moov') continue;
+    const movie: (typeof result.movies)[number] = { headers: [], tracks: [] };
+    result.movies.push(movie);
+    for (const child of boxes(box.start, box.end)) {
+      const { type, start, end } = child;
+      if (type === 'mvhd' && start < end) {
+        const version = bytes[start];
+        const payloadSize = end - start;
+        if (version === 0 && payloadSize >= 20) movie.headers.push({ timescale: view.getUint32(start + 12), duration: view.getUint32(start + 16), payloadSize });
+        if (version === 1 && payloadSize >= 32) movie.headers.push({ timescale: view.getUint32(start + 20), duration: Number(view.getBigUint64(start + 24)), payloadSize });
+      }
+      if (type !== 'trak') continue;
+      for (const track of boxes(start, end)) {
+        if (track.type !== 'tkhd' || track.start >= track.end) continue;
+        const version = bytes[track.start];
+        const at = version === 1 ? track.start + 88 : version === 0 ? track.start + 76 : track.end;
+        if (at + 8 > track.end) continue;
+        const width = view.getUint32(at) / 65536;
+        const height = view.getUint32(at + 4) / 65536;
+        movie.tracks.push({ width, height });
+      }
+    }
+  }
+  return result;
+}

package/src/pack-fetch.ts

@@ -105,7 +105,7 @@ export type LanePart = {
  *  World's scenario file for a model vendor's turns (`scenarioPath`, the runtime's `--scenario`). */
 export type PackFetchOptions = {
   root?: string; readOnly?: boolean; clock?: () => string; database?: string; scenarioPath?: string;
-  /** the application a walk stands in for (a life's `application` answers): this fetch's `ctx.ask` is answered by it */
+  /** the application a walk stands in for: this fetch's requests and declared events are answered by it */
   application?: ApplicationStandIn;
 };
 
@@ -143,7 +143,7 @@ function hostMatcher(pattern: string): (host: string) => Match | undefined {
   };
 }
 /** The host a request is for: the vendor host the World's injector names, else its own. */
-const hostOf = (request: Request): string => readHostPort(request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host)?.host ?? '';
+export const hostOf = (request: Request): string => 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
@@ -218,13 +218,26 @@ async function encoded(m: DerivedManifest, request: Request, res: Response): Pro
   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: string): string => (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<Door extends { method: string; path: string }>(doors: ReadonlyArray<Door>): (method: string, path: string) => { door: Door; params: Record<string, string> } | undefined {
+  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: Request): Request {
+export function slashesMerged(request: Request): Request {
   const url = new URL(request.url);
   const merged = url.pathname.replace(/\/{2,}/g, '/');
   if (merged === url.pathname) return request;
@@ -232,6 +245,58 @@ function slashesMerged(request: Request): Request {
   return new Request(url, request);
 }
 
+/** The selected unit's request transformation, shared by serving and response judgment. */
+export function unitRequestRouter(m: Pick<DerivedManifest, 'pathPrefix' | 'basePathAlias' | 'pathFromHost' | 'hostParams' | 'headerParams'>, surface: DerivedSurface, routes: ReturnType<typeof compileSurface>): (request: Request) => Request {
+  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: string, host: string): string => {
+    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: Request): 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' } : {}) } as RequestInit);
+  };
+}
+
+/** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
 export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}): DerivedFetch {
   const m = parts.manifest;
   const scope: CoreScope = {
@@ -322,11 +387,8 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     if (decision.kind === 'fault') 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) 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 };
-  });
+  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}`);
+  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: string) => hosts.map((match) => match(h)).find(Boolean), path: pathMatcher(s.path, true), answer: parts.screens![s.id]! };
@@ -355,53 +417,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   };
   const refusedReadOnly = (): Response => 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: string, host: string): string => {
-    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: Request): 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' } : {}) } as RequestInit);
-  };
+  const routed = unitRequestRouter(m, surface, routes);
   const rootServes = (method: string, path: string): boolean => 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.
@@ -488,7 +504,7 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const own = await answerContent(arrived);
     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);
     const readable = await prepared(arrived);
@@ -551,12 +567,11 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
         if (kind === 'fake') 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);
     }
@@ -717,30 +732,16 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
   return derivedRequestScopes(m, Object.assign(served, { owners, ownersByUnit, serves, advanceClock: async (request: 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: string, decl: LanesDecl, lanes: Record<string, LanePart>, rootServes: (method: string, path: string) => boolean = () => false): (request: Request) => ((request: Request) => Promise<Response>) | undefined {
-  const served = (name: string): ((request: Request) => Promise<Response>) => {
-    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: Request): Promise<Response> => {
-      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: LanesDecl, lanes: Record<string, { manifest: LanePart['manifest']; fetch: Pick<LanePart['fetch'], 'serves' | 'contentHosts'> }>, rootServes: (method: string, path: string) => boolean = () => false): (request: Request) => string | undefined {
+  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: Request, path: string, name: string): boolean =>
         (at === undefined || path === at || path.startsWith(`${at}/`))
         && (host === undefined || host.test(name))
@@ -749,21 +750,42 @@ function laneRouter(vendor: string, decl: LanesDecl, lanes: Record<string, LaneP
         && !(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
     // host rules (architecture, "A page at a World's place")
     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);
+    if (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: string, decl: LanesDecl, lanes: Record<string, LanePart>, rootServes: (method: string, path: string) => boolean = () => false): (request: Request) => ((request: Request) => Promise<Response>) | undefined {
+  const served = (name: string): ((request: Request) => Promise<Response>) => {
+    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: Request): Promise<Response> => {
+      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);
   };
 }
 

package/src/packRegistry.ts

@@ -221,7 +221,13 @@ export type TwinPack = {
    *  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 (`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; body: Record<string, unknown>; fill: Record<string, string>; account?: { field: string } };
+  credentialDoor?: {
+    path: string;
+    body: Record<string, unknown>;
+    fill: Record<string, string>;
+    account?: { field: string } & ({ tenancy?: never; source?: never } | { tenancy: string; source: string });
+    deployment?: { field: string; object: string; source: string; organizationOutputs?: string[] };
+  };
   /** Another pack of this vendor issues the API's credentials; architecture, descriptor World wiring. */
   credentialIssuer?: string;
   prismaAdapter?: { adapter: string; export: string; urlEnv: string };

package/src/request-body.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 const DEFAULT_MAX_DECODED_REQUEST_BODY_SIZE = 128 * 1024 * 1024;
 
 export class RequestBodyTooLargeError extends Error {