@volter/world-core 3.0.163 → 3.0.165

package/dist/src/pack-fetch.js

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

package/dist/src/pack-paths.d.ts

@@ -8,9 +8,8 @@ export declare function installedVendorPacks(from: string, options?: {
 }): Map<string, string>;
 /** Node's nearest installed package, including linked packages and hoisted workspace dependencies. */
 export declare function installedPackageDir(from: string, name: string): string | undefined;
-/** 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 declare function packRepository(from: string): string | undefined;
 /** Resolve one vendor's package directory for host-side reads (assets, infrastructure launchers). */
 export declare function vendorPackageDir(from: string, vendor: string): string | undefined;

package/dist/src/pack-paths.js

@@ -121,23 +121,13 @@ export function installedPackageDir(from, name) {
         dir = up;
     }
 }
-/** 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) {
     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;
@@ -148,7 +138,7 @@ export function packRepository(from) {
 export function vendorPackageDir(from, vendor) {
     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))

package/dist/src/packRegistry.d.ts

@@ -118,7 +118,9 @@ export declare function pullOnSchedule<T>(vendor: PullVendor, pull: () => Promis
  * 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;
@@ -131,6 +133,7 @@ export type HostRule = ({
     demandPathPattern?: string | false;
     key?: string;
     exclude?: true;
+    basic?: string;
 };
 export type RoundTripWrite = {
     method: string;
@@ -255,6 +258,19 @@ export type TwinPack = {
         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?: {

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

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

package/dist/src/request-body.js

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

package/dist/src/runtime.d.ts

@@ -7,11 +7,12 @@ export { ORIGINAL_PATH_HEADER } from './sigv4.js';
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from './twin-fetch.js';
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from './request-scope.js';
 export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from './derived.js';
+export { hostOf, laneSelector, slashesMerged, unitRequestRouter, worldDoorMatcher } from './pack-fetch.js';
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from './trace-context.js';
 export type { Traceparent } from './trace-context.js';
 export type { DerivedCall, DerivedCoreOutcome, DerivedDispatch, DerivedFetch, DerivedFetchOptions, DerivedHandler, DerivedOperation, DerivedOwner, DerivedSurface, BoardFrame } from './derived.js';
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from './derived-core.js';
-export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from './events.js';
+export { deliverEvents, fillEnvelope, setDeliveryObserver, settleEventDeliveries, signEvent, signEventAll, verifyEvent } from './events.js';
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from './signing.js';
 export type { HandlerCrypto, Jwk, Jwks, JwtDecodeOptions, JwtSignatureOptions, JwtVerdict, JwtVerificationKey, SigningKey } from './signing.js';
 export type { EventDelivery, EventRender, EventScheme, EventsDecl, EventTransport, EventWrite } from './events.js';
@@ -54,6 +55,7 @@ export { installedPackageDir, installedVendorPacks, packVendor, packRepository,
 export * as git from './git/index.js';
 export * as s3 from './s3/wire.js';
 export * as xml from './xml.js';
+export * as html from './html.js';
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from './placeholder-remote.js';
 export { aliasesFrom, ownFields, subjectHistory, rebaseBranch, cutCheckpoint, appendParentEntry, wholeLog, branchEntries, branchLogPath, branchMetaPath, CHECKPOINT_EVERY, dropCheckpoint, foldEntries, landedCopy, landedIds, parentEntries, parentLogPath, position, readBranchMeta, readTree, toEntry, toEvent, unpushedEntries, writeBranchMeta } from './log.js';
 export type { BranchMeta, Entry, EntryOp, Receipt } from './log.js';
@@ -78,6 +80,7 @@ export { brandTokensResponse } from './brand-tokens.js';
 export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBoundary, multipartDelimiterPattern, type MultipartPart, type MultipartFramedPart, type MultipartEnvelope } from './multipart.js';
 export { corsHeaders, withCors, type CorsDecl } from './cors.js';
 export { setInProcessTwins, vendorFetch, VendorUnreachableError, type InProcessTwin } from './vendor-call.js';
+export { setInProcessMailServers } from './smtp.js';
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver, type DatabaseDriver, type DatabaseSession } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
 export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from './resource-blob.js';

package/dist/src/runtime.js

@@ -15,9 +15,10 @@ export { ORIGINAL_PATH_HEADER } from "./sigv4.js";
 export { createTwinFetchFromHandler, placedCookies, TWIN_PREFIX_HEADER, TWIN_REQUEST_SCOPES, TWIN_SITES_HEADER, TWIN_SITE_HEADER, siteLabel, siteUrlOf, twinPublicBase, twinSiteUrl, twinVendorUrl, withRequestScopes } from "./twin-fetch.js";
 export { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, ReadOnlyRequestError, runAsReadOnlyRequest, runAsVendorMove, writesRefused } from "./request-scope.js";
 export { compileSurface, createDerivedFetch, matchOperation, observeDerivedDispatch } from "./derived.js";
+export { hostOf, laneSelector, slashesMerged, unitRequestRouter, worldDoorMatcher } from "./pack-fetch.js";
 export { currentTraceparent, deliveryTraceHeaders, newTraceparent, parseTraceparent, runWithRequestTrace, runWithTraceparent, TRACEPARENT_HEADER, traceparentForDelivery, validTraceparent } from "./trace-context.js";
 export { authRefusal, bindSemantics, coreFor, crossCutting, flagOf, derivedRequestScopes, observeTransitions, resourcesOfType as twinResourcesOfType, semanticsContext, stateOf, transitionFor, parseBracketForm, readParams, render as renderDerived, serveCore, sse, vendorError } from "./derived-core.js";
-export { deliverEvents, fillEnvelope, setDeliveryObserver, signEvent, signEventAll, verifyEvent } from "./events.js";
+export { deliverEvents, fillEnvelope, setDeliveryObserver, settleEventDeliveries, signEvent, signEventAll, verifyEvent } from "./events.js";
 export { equalSecrets, hmac, jwks, jwtDecode, jwtSign, jwtSignClaims, jwtVerify, jwtVerifySignature, keyId, lettersFrom, md5, sha256, SIGNING_ALGORITHMS, uuidFrom } from "./signing.js";
 export { emitTwinEvent, eventSubscriptionMatches, listEmittable, runEmitCli } from "./emit.js";
 // The vendor-agnostic CLIENT-SIDE RATE BUDGET — the fail-closed backstop a pack's guarded client
@@ -77,6 +78,8 @@ export * as git from "./git/index.js";
 export * as s3 from "./s3/wire.js";
 // Generic strict XML grammar; vendor interpretation remains in its consumer.
 export * as xml from "./xml.js";
+// Generic WHATWG HTML grammar; what a pack keeps of received HTML remains the pack's policy.
+export * as html from "./html.js";
 // The push arm: the kernel's transaction over a pack's one `perform<Name>Action` (contract section of that name).
 // The placeholder remote (contract section of that name): the seed is a pull, never a pending write.
 export { PLACEHOLDER_REMOTE, beginPlaceholderPull, endPlaceholderPull, placeholderPullActive, placeholderPullMarkerPath, withPlaceholderPull, placeholderEventsFor } from "./placeholder-remote.js";
@@ -101,6 +104,7 @@ export { brandTokensResponse } from "./brand-tokens.js";
 export { multipartBoundary, multipartParts, multipartEnvelope, inferMultipartBoundary, multipartDelimiterPattern } from "./multipart.js";
 export { corsHeaders, withCors } from "./cors.js";
 export { setInProcessTwins, vendorFetch, VendorUnreachableError } from "./vendor-call.js";
+export { setInProcessMailServers } from "./smtp.js";
 export { closeManagedDatabases, databaseSession, EngineDatabaseError, EngineUnavailableError, managedDatabase, quoteIdent, useDatabaseDriver } from "./managed-database.js";
 export { readResourceBlob, readResourceBlobRange, removeResourceBlob, resourceBlobFile, resourceBlobKey, resourceBlobSize, resourceChain, writeResourceBlob, writeResourceBlobStream } from "./resource-blob.js";
 export { assertStateRemovable, checkParent, stateGeneration, withAncestryLock, withHistoryLock, withHistoryLocks, withStateLock, withStateRemoval } from "./ancestry.js";

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

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