@volter/world-core 3.0.163 → 3.0.165

package/src/pack-fetch.ts

@@ -19,7 +19,9 @@ import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from './
 import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest, type PackScenarioAdapter } from './scenario.ts';
 import { getActiveWorldStore } from './world-store.ts';
 import { runWithCorrelationId } from './actions.ts';
-import { deferPerform, performRequestGroup, RefusedWriteError, VendorWriteError } from './head.ts';
+import { deferPerform, deployableEntries, performRequestGroup, RefusedWriteError, VendorWriteError } from './head.ts';
+import { FLUSH, ZERO_SHA, pktLine, readPktLines } from './git/smart-http.ts';
+import { concat } from './git/objects.ts';
 import { withCors } from './cors.ts';
 import type { ApplicationStandIn } from './events.ts';
 import { contentAddressOf } from './content-route.ts';
@@ -32,7 +34,7 @@ import { expireSocketWaits, socketUpgrade, type SocketEngine } from './sockets.t
 import { liveIngest } from './live/ingest.ts';
 import type { LiveEngine } from './live/types.ts';
 import { readResourceBlob, removeResourceBlob, writeResourceBlob } from './resource-blob.ts';
-import { resourcesOfType } from './derived-core.ts';
+import { gitRepositoryOf, resourcesOfType } from './derived-core.ts';
 import { worldNow } from './world-clock.ts';
 import type { WebSocketUpgrade, WebSocketPeer } from './serve-http.ts';
 import { MACHINE_POOL, POOL_KINDS, resetFakePool } from './machines.ts';
@@ -105,7 +107,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 +145,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 +220,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 +247,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 +389,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 +419,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 +506,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 +569,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);
     }
@@ -628,7 +645,38 @@ export function createPackFetch(parts: PackParts, options: PackFetchOptions = {}
     const id = `req_${globalThis.crypto.randomUUID()}`;
     const { value: answer, appended } = await runWithCorrelationId(id, () => deferPerform(id, () => fetch(request)));
     if (!appended) return answer;
+    // a receive-pack's pushes (derived-core.ts pushedInput): what the World's refs held before and after each
+    const pushes = m.git ? deployableEntries(m.service, options.root).filter((e) => e.correlationId === id && e.input?.git).map((e) => ({ actionId: e.id, ...(e.input!.git as { name: string; ref: string; before: string; after: string }) })) : [];
     const performed = await runWithCorrelationId(id, () => performRequestGroup(m.service, id, options.root));
+    // under `auto`, what the root did is what the World keeps (ADR 0031): a ref it refused goes back to its value before
+    // the push, by compare-and-set under the ref lock (a later push built on it keeps its value), its push and effects
+    // are reverted (head.ts), and the client hears git's own report, `ok` or `ng` for each ref
+    if (pushes.length) {
+      const whole = performed instanceof RefusedWriteError ? performed.reason : performed instanceof VendorWriteError ? performed.message : undefined;
+      const refused = new Map<string, string>();
+      for (const p of pushes) {
+        const reason = whole ?? (performed as { refused?: Array<{ actionId: string; reason: string }> }).refused?.find((r) => r.actionId === p.actionId)?.reason;
+        if (reason !== undefined) refused.set(p.actionId, reason);
+      }
+      if (refused.size) {
+        for (const p of [...pushes].reverse()) {
+          if (!refused.has(p.actionId)) continue;
+          const { refs } = gitRepositoryOf(m, p.name, options.root);
+          refs.withLock(() => {
+            if ((refs.get(p.ref) ?? ZERO_SHA) !== p.after) return;
+            if (p.before === ZERO_SHA) refs.delete(p.ref); else refs.set(p.ref, p.before);
+          });
+        }
+        const ng = new Map(pushes.filter((p) => refused.has(p.actionId)).map((p) => [p.ref, refused.get(p.actionId)!.replace(/\s+/g, ' ')]));
+        const report = concat(...readPktLines(new Uint8Array(await answer.arrayBuffer())).lines.map((line) => {
+          const ref = line.startsWith('ok ') ? line.slice(3).trim() : undefined;
+          return pktLine(ref !== undefined && ng.has(ref) ? `ng ${ref} ${ng.get(ref)}\n` : line);
+        }), FLUSH);
+        const headers = new Headers(answer.headers);
+        headers.delete('content-length');
+        return new Response(report as unknown as BodyInit, { status: answer.status, headers });
+      }
+    }
     // the vendor's refusal, as its status and words (perform names them `<status>: <message>`), in the vendor's error body
     if (performed instanceof RefusedWriteError) { const said = /^(\d{3}): ([\s\S]*)$/.exec(performed.reason); return vendorError(m, { status: said ? Number(said[1]) : 400, message: said ? said[2]! : performed.reason }); }
     if (performed instanceof VendorWriteError) return vendorError(m, { status: 502, message: performed.message });
@@ -717,30 +765,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 +783,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/pack-paths.ts

@@ -102,20 +102,12 @@ export function installedPackageDir(from: string, name: string): string | undefi
   }
 }
 
-/** A pack repository itself, or a platform checkout's P3 repository: the one `VOLTER_PACKS` names (a worktree's own
- *  pinned packs, as the repository's scripts read it), else the one beside it. Applications do not acquire a
- *  sibling checkout merely because one happens to be beside them. */
+/** The pack repository a World is rooted in, when it is one (ADR 0034: a platform checkout finds no pack repository
+ *  beside it; a pack reaches any other World as an installed or linked package). */
 export function packRepository(from: string): string | undefined {
   let dir = resolve(from);
   for (;;) {
     if (packageName(dir) === 'twin-packs-p3') return dir;
-    if (packageName(join(dir, 'packages', 'world-core')) === '@volter/world-core') {
-      const env = globalThis.process?.env?.VOLTER_PACKS;
-      const named = env ? resolve(env) : undefined;
-      if (named && packageName(named) === 'twin-packs-p3') return named;
-      const sibling = join(dirname(dir), 'twin-packs-p3');
-      if (packageName(sibling) === 'twin-packs-p3') return sibling;
-    }
     const up = dirname(dir);
     if (up === dir) return undefined;
     dir = up;
@@ -125,7 +117,7 @@ export function packRepository(from: string): string | undefined {
 /** Resolve one vendor's package directory for host-side reads (assets, infrastructure launchers). */
 export function vendorPackageDir(from: string, vendor: string): string | undefined {
   if (!/^[a-z][a-z0-9-]*$/.test(vendor)) return undefined;
-  const installed = installedVendorPacks(from).get(vendor);
+  const installed = installedVendorPacks(from, { vendors: [vendor] }).get(vendor);
   const repo = packRepository(from);
   const checkout = repo === undefined ? undefined : join(repo, vendor);
   if (!checkout || packageName(checkout) !== `@volter/twin-${vendor}` || !isDerivedPack(checkout)) return installed;

package/src/packRegistry.ts

@@ -166,13 +166,16 @@ export async function pullOnSchedule<T>(vendor: PullVendor, pull: () => Promise<
  * matches and no exclude does. Validated by scripts/pack-facts.ts: keys are `[a-z0-9-]+`, a
  * foreign key is never another pack's vendor id, belongs to one pack, and must appear in the
  * pack's `adoption.worldIds` (the world wires `<KEY>_TWIN_URL` from there); a pack must claim its
- * own vendor id too; no key is exclude-only; `exclude` is `true` or absent.
+ * own vendor id too; no key is exclude-only; `exclude` is `true` or absent. `basic` is a vendor fact for the executor: on
+ * a URL the rule names, the host takes the sealed token as HTTP Basic's password under this user (a vendor's git over
+ * HTTP whose API takes the same token as a bearer; ADR 0031).
  */
 export type HostRule = ({ host: string } | { suffix: string } | { hostPattern: string }) & {
   pathPattern?: string;
   demandPathPattern?: string | false;
   key?: string;
   exclude?: true;
+  basic?: string;
 };
 
 export type RoundTripWrite = { method: string; path: string; body?: unknown; headers?: Record<string, string> };
@@ -234,6 +237,11 @@ export type TwinPack = {
   managedService?: { kind: string; scheme: string; note: string; configurationArg?: '--configuration'; originalInputs?: { version: 1; manifestArg: '--original-inputs'; rootArg: '--original-root'; digestArg: '--original-inputs-sha256'; paths: string[] } };
   managedDatabase?: { kind: 'postgres'; arg: string; user: string; database: string; clock: 'wall'; credentialField: string; note: string };
   sidePorts?: Array<{ name: string; option: string; flag: string; path?: string; scheme?: string; note: string }>;
+  /** The vendor's own requests a World's generated seed makes for what its world.json declares (ADR 0033 §3), each a URL
+   *  at the vendor's own host, defined by the twin's own screen form for that act: its sign-up, and its domain screen's
+   *  add and verify with `record`, the one `/_twin/` stand-in, for a record at the domain's DNS host; `settles` is the
+   *  World-clock time the vendor takes to settle a verified domain (`10m`). */
+  seed?: { signUp?: string; domain?: { add: string; record: string; verify: string; settles: string } };
   stateSystem?: StateSystemAdapters;
   /** The pack has no vendor-backed half, and why (copied from the manifest by packOf). */
   vendorBacked?: { none: 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 {

package/src/runtime.ts

@@ -16,11 +16,12 @@ export { ORIGINAL_PATH_HEADER } from './sigv4.ts';
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from './twin-fetch.ts';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.ts';
 export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from './derived.ts';
+export { hostOf, laneSelector, slashesMerged, unitRequestRouter, worldDoorMatcher } from './pack-fetch.ts';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.ts';
 export type { Traceparent } from './trace-context.ts';
 export type { DerivedCall, DerivedCoreOutcome, DerivedDispatch, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.ts';
 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.ts';
-export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.ts';
+export { deliverEvents, fillEnvelope, setDeliveryObserver, settleEventDeliveries, signEvent, signEventAll, verifyEvent } from './events.ts';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.ts';
 export type { HandlerCrypto, Jwk, Jwks, JwtDecodeOptions, JwtSignatureOptions, JwtVerdict, JwtVerificationKey, SigningKey } from './signing.ts';
 export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTransport, EventWrite } from './events.ts';
@@ -306,6 +307,8 @@ export * as git from './git/index.ts';
 export * as s3 from './s3/wire.ts';
 // Generic strict XML grammar; vendor interpretation remains in its consumer.
 export * as xml from './xml.ts';
+// Generic WHATWG HTML grammar; what a pack keeps of received HTML remains the pack's policy.
+export * as html from './html.ts';
 
 // The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
 
@@ -342,6 +345,7 @@ export { brandTokensResponse } from './brand-tokens.ts';
 export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBoundary, multipartDelimiterPattern, type MultipartPart, type MultipartFramedPart, type MultipartEnvelope } from './multipart.ts';
 export { corsHeaders, withCors, type CorsDecl } from './cors.ts';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.ts';
+export { setInProcessMailServers } from './smtp.ts';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';
 export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from './resource-blob.ts';