@volter/world-core 2.0.37 → 3.0.1

package/dist/src/pack-fetch.js

@@ -0,0 +1,449 @@
+// A Protocol 3 pack's whole HTTP surface, served by the kernel from the pack's declarations (docs/contributing/
+// architecture.md, "The pack contract: the kernel's root"): the discovery door (`GET /twin`, the manifest's
+// `discovery`), the vendor's own moves as time passes (`semantics/clock.ts`), the World's doors (the manifest's `doors`,
+// answered by `semantics/doors.ts`), the vendor's screens (the manifest's `screens`, each answered by its
+// `screens/<id>.tsx`), and the API (the derived dispatch over the generated surface, the handlers and the core). Every
+// one of them is answered over the contract's context, which the kernel opens: a pack opens none, reads the tree and
+// writes it only through one.
+import { ORIGINAL_PATH_HEADER } from "./sigv4.js";
+import { TWIN_PREFIX_HEADER } from "./twin-fetch.js";
+import { PREFIX_PARAMS_HEADER } from "./derived.js";
+import { authRefusal, bindSemantics, contextFor, LANE_HEADER, SCENARIO_DECISION_HEADER, coreFor, crossCutting, derivedRequestScopes, vendorError } from "./derived-core.js";
+import { compileSurface, createDerivedFetch, matchOperation } from "./derived.js";
+import { isReadOnlyRequest, READ_ONLY_REQUEST_HEADER, runAsVendorMove } from "./request-scope.js";
+import { parseScenarioDocument, ScenarioEngine, ScenarioError, statefulTwinManifest, twinManifest } from "./scenario.js";
+import { getActiveWorldStore } from "./world-store.js";
+import { runWithCorrelationId } from "./actions.js";
+import { deferPerform, performRequestGroup, RefusedWriteError, VendorWriteError } from "./head.js";
+import { withCors } from "./cors.js";
+import { socketUpgrade } from "./sockets.js";
+import { MACHINE_POOL, POOL_KINDS } from "./machines.js";
+import { applyTwinWrite } from "./serve.js";
+import { graphqlEndpoint } from "./graphql-wire.js";
+import { brotliDecompressSync, gunzipSync, gzipSync, inflateSync, zstdDecompressSync } from 'node:zlib';
+/** A declared path (`/{account}/r2/api-tokens`, `/<room>`, a door's `/_twin/users/{email}`) as a matcher of a request's
+ *  path: the path itself, or `prefix` a path under it too (a screen answers its page and the forms it posts). */
+function pathMatcher(pattern, prefix) {
+    const names = [];
+    const body = pattern.replace(/\/+$/, '').split('/').map((seg) => {
+        const m = /^(?:\{([^}]+)\}|<([^>]+)>|:(\w+))$/.exec(seg);
+        if (!m)
+            return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        names.push(m[1] ?? m[2] ?? m[3]);
+        return '([^/]+)';
+    }).join('/');
+    const re = new RegExp(`^${body}${prefix ? '(?:/.*)?' : ''}/?$`);
+    return (path) => {
+        const hit = re.exec(path);
+        return hit ? { params: Object.fromEntries(names.map((n, i) => [n, decodeURIComponent(hit[i + 1])])) } : undefined;
+    };
+}
+/** A declared host (`dash.cloudflare.com`, `<domain>.daily.co`) as a matcher of a request's host. */
+function hostMatcher(pattern) {
+    const names = [];
+    const re = new RegExp(`^${pattern.split('.').map((label) => {
+        const m = /^(?:\{([^}]+)\}|<([^>]+)>)$/.exec(label);
+        if (!m)
+            return label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        names.push(m[1] ?? m[2]);
+        return '([^.]+)';
+    }).join('\\.')}$`, 'i');
+    return (host) => {
+        const hit = re.exec(host);
+        return hit ? { params: Object.fromEntries(names.map((n, i) => [n, hit[i + 1]])) } : undefined;
+    };
+}
+/** The host a request is for: the vendor host the World's injector names, else its own. */
+const hostOf = (request) => (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? new URL(request.url).host).split(':')[0].toLowerCase();
+/** The answer for a path no operation, door or screen serves, and for an operation nothing models: the manifest's
+ *  `gap`, its `{method}` and `{path}` filled, else the manifest's not-found refusal. */
+function gapAnswer(m, request, otherMethod = false) {
+    const nf = m.notFound;
+    const gap = (otherMethod ? m.wrongMethod : undefined) ?? m.gap ?? { status: nf.status, message: nf.message, ...(nf.code !== undefined ? { code: nf.code } : {}), ...(nf.kind !== undefined ? { kind: nf.kind } : {}) };
+    const path = new URL(request.url).pathname;
+    return vendorError(m, { ...gap, message: gap.message.replace(/\{method\}/g, request.method).replace(/\{path\}/g, path) });
+}
+const METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const DECODE = { gzip: gunzipSync, zstd: zstdDecompressSync, deflate: inflateSync, br: brotliDecompressSync };
+/** A request with its body decoded as its Content-Encoding says, when the manifest's `encodings` reads that coding;
+ *  undefined when the bytes are not what the header names. */
+async function decoded(m, request) {
+    const coding = (request.headers.get('content-encoding') ?? '').trim().toLowerCase();
+    if (!m.encodings?.request?.includes(coding) || request.method === 'GET' || request.method === 'HEAD')
+        return request;
+    let body;
+    try {
+        body = DECODE[coding](new Uint8Array(await request.arrayBuffer()));
+    }
+    catch {
+        return undefined;
+    }
+    const headers = new Headers(request.headers);
+    headers.delete('content-encoding');
+    headers.delete('content-length');
+    // a copy over an ArrayBuffer of its own: zlib's result may view a shared buffer, which a request body does not take
+    return new Request(request.url, { method: request.method, headers, body: new Uint8Array(body) });
+}
+/** An answer in the coding the request accepts, when the manifest's `encodings` answers in it. */
+async function encoded(m, request, res) {
+    if (!m.encodings?.response?.includes('gzip') || res.body === null || res.status === 204 || res.status === 205 || res.headers.has('content-encoding'))
+        return res;
+    const accepts = (request.headers.get('accept-encoding') ?? '').split(',').some((e) => e.trim().split(';')[0].toLowerCase() === 'gzip');
+    if (!accepts)
+        return res;
+    const headers = new Headers(res.headers);
+    headers.set('content-encoding', 'gzip');
+    headers.delete('content-length');
+    headers.append('vary', 'Accept-Encoding');
+    return new Response(gzipSync(new Uint8Array(await res.arrayBuffer())), { status: res.status, statusText: res.statusText, headers });
+}
+/** A pack's HTTP surface, as the kernel serves it from the pack's parts. */
+export function createPackFetch(parts, options = {}) {
+    const m = parts.manifest;
+    const scope = {
+        ...(options.root !== undefined ? { root: options.root } : {}),
+        ...(options.clock ? { clock: options.clock } : {}),
+        ...(options.database !== undefined ? { database: options.database, readOnly: options.readOnly ?? false } : {}),
+        ...(parts.tenant ? { tenant: parts.tenant } : {}),
+    };
+    // a command table's surface (Redis's, a vendor that carries Redis over HTTP) names no HTTP operation: its wire is the
+    // pack's front (its `around`), and the table is the denominator the grade counts
+    const surface = { ...parts.surface, operations: parts.surface.operations ?? [], ...(m.spanning?.length ? { spanning: [...(parts.surface.spanning ?? []), ...m.spanning] } : {}) };
+    const routes = compileSurface(surface);
+    const rest = createDerivedFetch({
+        surface,
+        handlers: bindSemantics(m, (parts.handlers ?? {}), scope),
+        core: coreFor(m, scope),
+        around: crossCutting(m, { readOnly: options.readOnly ?? false, ...scope }),
+        gap: async (request, operation) => {
+            const refused = m.auth?.beforeRouting ? authRefusal(m, request, options.root) : undefined;
+            if (refused)
+                return refused;
+            if (parts.gap) {
+                const url = new URL(request.url);
+                const matched = operation ? matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers) : undefined;
+                return parts.gap(await contextFor(m, { request, operation: operation ?? { id: 'unmatched', method: request.method, path: url.pathname, class: request.method === 'GET' ? 'retrieve' : 'action' }, params: matched?.params ?? {} }, scope));
+            }
+            const url = new URL(request.url);
+            const other = !matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers)
+                && METHODS.some((x) => x !== request.method && matchOperation(routes, x, url.pathname, url.searchParams, request.headers));
+            return gapAnswer(m, request, other);
+        },
+    });
+    // the GraphQL wire over the same state, at the paths the manifest names (graphql-wire.ts)
+    const gql = m.graphql && parts.graphql ? m.graphql : undefined;
+    const graphql = gql && parts.graphql ? graphqlEndpoint({
+        sdl: parts.graphql.sdl, part: parts.graphql,
+        context: async (request) => contextFor(m, { request: request.clone(), operation: { id: 'graphql', method: 'POST', path: gql.paths[0], class: 'action' }, params: {} }, scope),
+        unmodeled: ({ type, field }) => Response.json({ errors: [{ ...(gql.unmodeled.type ? { type: gql.unmodeled.type } : {}), message: gql.unmodeled.message.replace('{field}', field).replace('{type}', type) }] }, { status: gql.unmodeled.status ?? 200 }),
+        mutationRefused: (request) => ((options.readOnly ?? false) || isReadOnlyRequest(request) ? vendorError(m, m.readOnly) : undefined),
+    }) : undefined;
+    const api = Object.assign(async (request) => {
+        if (graphql && gql && request.method === 'POST' && gql.paths.includes(new URL(request.url).pathname.replace(/\/+$/, '')))
+            return graphql(request);
+        return rest(request);
+    }, { owners: rest.owners });
+    // the World's scenario, read from the World's store at every turn, HTTP or socket alike: a file the World rewrites takes
+    // effect at the next turn, with no reboot; the engine (its handlers' counts) is kept while the file is unchanged
+    let engine;
+    let engineRaw;
+    const engineOf = () => {
+        if (!parts.scenario || options.scenarioPath === undefined)
+            return undefined;
+        const raw = getActiveWorldStore().read(options.scenarioPath);
+        if (raw === null)
+            throw new ScenarioError(`${m.vendor} scenario: no file at ${options.scenarioPath}`);
+        if (!engine || raw !== engineRaw) {
+            engine = new ScenarioEngine(parts.scenario.adapter, parseScenarioDocument(JSON.parse(raw), parts.scenario.adapter));
+            engineRaw = raw;
+        }
+        return engine;
+    };
+    /** The API, a turn the scenario decides handed its decision (ctx.scenario), or answered as the fault it names. */
+    const decided = async (arrived) => {
+        if (!parts.scenario)
+            return api(arrived);
+        // the body is read once and the request made again from its bytes: a served request's body cloned (for the turn's
+        // context) and then forwarded tees a stream whose second branch a Bun server never finishes, and every turn hung
+        // (measured on merge served with --scenario: no answer in 8 s, matched or not; t_c0279b69)
+        const bytes = arrived.method === 'GET' || arrived.method === 'HEAD' ? undefined : await arrived.arrayBuffer();
+        const request = new Request(arrived.url, { method: arrived.method, headers: arrived.headers, ...(bytes ? { body: bytes } : {}) });
+        const url = new URL(request.url);
+        const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
+        if (!matched || !parts.scenario.operations.includes(matched.operation.id))
+            return api(request);
+        // the credential is the vendor's first question: a request it refuses takes no scripted turn
+        if (!m.auth?.exempt?.includes(matched.operation.id)) {
+            const refused = authRefusal(m, request, options.root);
+            if (refused)
+                return refused;
+        }
+        let decision;
+        try {
+            const turns = engineOf();
+            if (!turns)
+                return api(request);
+            const asked = parts.scenario.request(await contextFor(m, { request: request.clone(), operation: matched.operation, params: matched.params }, scope));
+            if (asked === undefined)
+                return api(request);
+            decision = await turns.serve(asked);
+        }
+        catch (error) {
+            if (!(error instanceof ScenarioError))
+                throw error;
+            return vendorError(m, { status: 500, code: 'scenario_error', message: `the World's scenario: ${error.message}` });
+        }
+        if (decision.kind === 'fault')
+            return Response.json(decision.result.body, { status: decision.result.status, headers: decision.result.headers ?? {} });
+        return api(new Request(request, { headers: new Headers([...request.headers, [SCENARIO_DECISION_HEADER, JSON.stringify(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(d.path.startsWith('/_twin/') ? d.path : `/_twin${d.path.startsWith('/') ? '' : '/'}${d.path}`, false), answer };
+    });
+    const screens = (m.screens ?? []).filter((s) => s.status === 'done' && parts.screens?.[s.id]).map((s) => {
+        const hosts = [s.host, ...(s.hosts ?? [])].map(hostMatcher);
+        return { decl: s, host: (h) => hosts.map((match) => match(h)).find(Boolean), path: pathMatcher(s.path, true), answer: parts.screens[s.id] };
+    });
+    // a context the kernel opens for what no surface operation names: a door, a screen, the clock
+    const open = (request, id, method, path, params) => contextFor(m, { request, operation: { id, method, path, class: method === 'GET' ? 'retrieve' : 'action' }, params }, scope);
+    const refusedReadOnly = () => vendorError(m, m.readOnly);
+    const prefix = m.pathPrefix ? new RegExp(`^(?:${m.pathPrefix})(?=/)`) : undefined;
+    const hostPath = m.pathFromHost ? new RegExp(m.pathFromHost, 'i') : undefined;
+    const hostParams = m.hostParams ? new RegExp(m.hostParams, 'i') : undefined;
+    /** The request as its vendor routes it: duplicate slashes collapsed, the manifest's path prefix taken off, a host's
+     *  path label (pathFromHost) put in front. */
+    const routed = (request) => {
+        const url = new URL(request.url);
+        let path = url.pathname.replace(/\/{2,}/g, '/');
+        // a prefix's named groups (Jira's `/ex/jira/(?<cloudId>[^/]+)`) and the host's (E2B's envd at
+        // `49983-(?<sandboxID>…).e2b.app`) join the operation's parameters
+        const groups = { ...(prefix?.exec(path)?.groups ?? {}), ...(hostParams?.exec(hostOf(request))?.groups ?? {}) };
+        if (prefix)
+            path = path.replace(prefix, '') || '/';
+        const label = hostPath?.exec(hostOf(request))?.[1];
+        if (label)
+            path = `/${label}${path === '/' ? '' : path}`;
+        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);
+        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, ...(request.body ? { duplex: 'half' } : {}) });
+    };
+    const rootServes = (method, path) => Boolean(matchOperation(routes, method, path));
+    const lane = m.lanes ? laneRouter(m.vendor, m.lanes, parts.lanes ?? {}, rootServes) : undefined;
+    const fetch = async (arrived) => {
+        // the discovery door is the pack's own, whichever lane would take its path
+        const asked = new URL(arrived.url).pathname.replace(/\/+$/, '') || '/';
+        const discovery = arrived.method === 'GET' && m.discovery !== undefined && (asked === '/twin' || asked === '/twin/scenario');
+        const toLane = discovery ? undefined : lane?.(arrived);
+        if (toLane)
+            return toLane(arrived);
+        // only the kernel names a scenario's decision, or a path prefix's parameters
+        if (arrived.headers.has(SCENARIO_DECISION_HEADER) || arrived.headers.has(PREFIX_PARAMS_HEADER)) {
+            const headers = new Headers(arrived.headers);
+            headers.delete(SCENARIO_DECISION_HEADER);
+            headers.delete(PREFIX_PARAMS_HEADER);
+            arrived = new Request(arrived, { headers });
+        }
+        const readable = await decoded(m, arrived);
+        if (!readable)
+            return vendorError(m, m.encodings?.undecodable ?? { status: 400, message: `the body does not decode as its Content-Encoding (${arrived.headers.get('content-encoding')}) says` });
+        const incoming = routed(readable);
+        // a twin started read-only marks every request so, so every context it opens knows (isReadOnlyRequest)
+        const request = options.readOnly && !isReadOnlyRequest(incoming) ? new Request(incoming, { headers: new Headers([...incoming.headers, [READ_ONLY_REQUEST_HEADER, '1']]) }) : incoming;
+        const url = new URL(request.url);
+        const path = url.pathname.replace(/\/+$/, '') || '/';
+        const readOnly = (options.readOnly ?? false) || isReadOnlyRequest(request);
+        if (request.method === 'GET' && path === '/twin' && m.discovery) {
+            const d = m.discovery;
+            // the workspaces a person can be shown (Viewing a World): each built workspace screen's id and path
+            const workspaces = (m.screens ?? []).filter((s) => s.kind === 'workspace' && s.status === 'done' && parts.screens?.[s.id]).map((s) => ({ id: s.id, path: s.path }));
+            const shown = workspaces.length ? { screens: workspaces } : {};
+            // a model vendor's: its state, and what its scenario scripts, with the scenario's live counts
+            if (parts.scenario && d.behavior) {
+                return Response.json({ ...shown, ...twinManifest({
+                        vendor: m.vendor, twinOf: d.twinOf,
+                        stateSentence: `Stateful: it stores ${d.stores}. Create state through the vendor's OWN API with the real SDK or plain fetch pointed here.`,
+                        behaviorSentence: d.behavior, exampleHandler: d.exampleHandler ?? null, ...(engineOf() ? { engine: engineOf() } : {}),
+                    }) });
+            }
+            return Response.json({ ...statefulTwinManifest({ vendor: m.vendor, twinOf: d.twinOf, stores: d.stores, ...(d.identity ? { identity: d.identity } : {}), ...(d.notes ? { notes: d.notes } : {}) }), ...shown });
+        }
+        // the scenario's handlers with their match counts, and the recent misses
+        if (request.method === 'GET' && path === '/twin/scenario' && parts.scenario)
+            return Response.json(engineOf()?.status() ?? { vendor: m.vendor, handlers: [], misses: 0, recentMisses: [] });
+        // the vendor's own moves, not the caller's: its context carries none of the request's headers (a Stripe-Account
+        // header would make a payout time makes the caller's), but a tenant's, when the vendor keeps tenants apart
+        if (parts.clock)
+            await runAsVendorMove(async () => parts.clock(await open(new Request(request.url, m.tenant ? { headers: request.headers } : {}), 'clock', 'POST', '/_twin/clock', {})));
+        if (path.startsWith('/_twin/')) {
+            // the World's machine pool, enrolled by the kernel for a vendor that runs images (machines.ts)
+            if (m.machines && path === '/_twin/machine-pool' && request.method === 'POST') {
+                if (readOnly)
+                    return refusedReadOnly();
+                let kind;
+                try {
+                    kind = JSON.parse(await request.clone().text()).kind;
+                }
+                catch {
+                    kind = undefined;
+                }
+                if (!POOL_KINDS.includes(kind))
+                    return Response.json({ message: `kind must be one of ${POOL_KINDS.join(', ')}` }, { status: 400 });
+                await applyTwinWrite(m.service, { operation: 'machine_pool.enroll', subjectType: MACHINE_POOL, subjectId: 'pool', fields: { kind }, occurredAt: (await open(request, 'machine-pool', 'POST', '/_twin/machine-pool', {})).occurredAt, actor: { kind: 'system' } }, options.root);
+                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;
+                if (readOnly && request.method !== 'GET')
+                    return refusedReadOnly();
+                return d.answer(await open(request, d.decl.id, d.decl.method, d.decl.path, hit.params));
+            }
+            return gapAnswer(m, request);
+        }
+        // a screen on a host it names exactly answers there first (a dashboard's /login on dash.cloudflare.com, where the
+        // API's /{Bucket} would take it); then a path the vendor's API names is the API's; then a screen on a host it names by
+        // pattern (a room's page on <domain>.daily.co, which api.daily.co also matches); then a screen by its path alone, at
+        // whichever host the twin is reached (its links carry the twin's own base), never a root screen off its own host
+        const host = hostOf(request);
+        const exact = (s) => [s.decl.host, ...(s.decl.hosts ?? [])].some((h) => !/[{<]/.test(h) && h.toLowerCase() === host);
+        const hits = screens.map((s) => ({ s, hit: s.path(path), onHost: s.host(host) })).filter((x) => x.hit);
+        const apiPath = Boolean(matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers));
+        // reached at a World's place for the twin (`x-forwarded-prefix`, served-world's wire), the host is the World's: a
+        // workspace is shown there by its path alone, its root too (the console frames it so)
+        const placed = request.headers.has(TWIN_PREFIX_HEADER);
+        const byPath = hits.find((x) => x.onHost && exact(x.s))
+            ?? (apiPath ? undefined : hits.find((x) => x.onHost) ?? hits.find((x) => x.s.decl.path.replace(/\/+$/, '') !== '')
+                ?? (placed ? hits.find((x) => x.s.decl.kind === 'workspace') : undefined));
+        if (byPath) {
+            if (readOnly && request.method !== 'GET' && request.method !== 'HEAD')
+                return refusedReadOnly();
+            return byPath.s.answer(await open(request, byPath.s.decl.id, request.method, byPath.s.decl.path, { ...(byPath.onHost?.params ?? {}), ...byPath.hit.params }));
+        }
+        if (!parts.around)
+            return encoded(m, request, await decided(request));
+        const matched = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
+        const operation = matched?.operation ?? { id: 'unmatched', method: request.method, path: url.pathname, class: request.method === 'GET' ? 'retrieve' : 'action' };
+        const ctx = await contextFor(m, { request: request.clone(), operation, params: matched?.params ?? {} }, scope);
+        return encoded(m, request, await parts.around(ctx, (rewritten) => decided(rewritten ?? request)));
+    };
+    // the request's id is the correlation of every entry it appends (runtime contract D3), minted here, always: it is the
+    // group a perform sends as one call (the real-system adapters, "Perform"). Under `auto` the group is performed once
+    // the handler has answered, and the answer names the subjects by the ids the vendor gave them.
+    const correlated = async (request) => {
+        const id = `req_${globalThis.crypto.randomUUID()}`;
+        const { value: answer, appended } = await runWithCorrelationId(id, () => deferPerform(id, () => fetch(request)));
+        if (!appended)
+            return answer;
+        const performed = await runWithCorrelationId(id, () => performRequestGroup(m.service, id, options.root));
+        // 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 });
+        if (!performed.ids.size || !(answer.headers.get('content-type') ?? '').includes('json'))
+            return answer;
+        let text = await answer.text();
+        for (const [local, vendor] of performed.ids)
+            text = text.split(JSON.stringify(local)).join(JSON.stringify(vendor));
+        const headers = new Headers(answer.headers);
+        headers.delete('content-length');
+        return new Response(text, { status: answer.status, statusText: answer.statusText, headers });
+    };
+    // the vendor's CORS, as its gateway answers a browser: every answer, a preflight at any path
+    // a JSON answer labelled as the vendor labels it
+    const labelled = m.jsonContentType === undefined ? correlated : async (request) => {
+        const res = await correlated(request);
+        const type = res.headers.get('content-type') ?? '';
+        if (!type.startsWith('application/json') || type === m.jsonContentType)
+            return res;
+        const headers = new Headers(res.headers);
+        headers.set('content-type', m.jsonContentType);
+        return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
+    };
+    const served = m.cors ? withCors(m.cors, labelled) : labelled;
+    // which paths this pack's API serves, for a vendor's lane router that asks (unlessOnlyRoot)
+    const serves = (method, path) => Boolean(matchOperation(routes, method, path));
+    // the vendor's sockets: a request to a declared socket's path opens a session of its engine, over a context of the
+    // request that opened it (operation `socket:<id>`)
+    for (const d of m.sockets ?? [])
+        if (!parts.sockets?.[d.id])
+            throw new Error(`${m.vendor}: the manifest declares the socket ${d.id}, and semantics/sockets.ts exports no ${d.id}`);
+    const upgrade = m.sockets?.length ? socketUpgrade(m.service, options.root, m.sockets, parts.sockets, (request, d) => open(request, `socket:${d.id}`, 'GET', d.path, {}), hostOf, (request) => new URL(routed(request).url).pathname, 
+    // a turn a session speaks (a voice agent's reply) is the World's scenario's, as a turn over HTTP is
+    async (asked) => engineOf()?.serve(asked)) : undefined;
+    // what serves each operation: the pack's own, and each lane's
+    const owners = () => ({ ...api.owners(), ...lanesOwners(parts.lanes ?? {}) });
+    return derivedRequestScopes(m, Object.assign(served, { owners, serves, ...(upgrade ? { upgrade } : {}) }));
+}
+/** 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(new Request(request, { headers, ...(request.body ? { duplex: 'half' } : {}) }));
+        };
+        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),
+    })));
+    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),
+            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))
+                && !except.includes(name)
+                && !(r.unlessOnlyRoot && rootServes(request.method, path) && !(own?.(request.method, path) ?? false)),
+        };
+    });
+    const fallback = decl.default !== undefined ? served(decl.default) : undefined;
+    return (request) => {
+        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 name = hostOf(request);
+        return laneRoutes.find((r) => r.holds(request, path, name))?.lane ?? fallback;
+    };
+}
+/** A vendor whose every API is a lane (Cloudflare's API v4 and R2, AWS's services), served from its manifest: the
+ *  discovery door, then its lanes as its gateway sends them; a request no lane takes is the vendor's not-found. */
+/** What serves each of a vendor's lanes' operations (a handler, the core, or the gap), as one map. */
+const lanesOwners = (lanes) => Object.assign({}, ...Object.values(lanes).map((l) => l.fetch.owners?.() ?? {}));
+export function createVendorFetch(manifest, lanes) {
+    const lane = laneRouter(manifest.vendor, manifest.lanes, lanes);
+    return Object.assign(async (request) => {
+        const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+        if (request.method === 'GET' && path === '/twin' && manifest.discovery)
+            return Response.json(statefulTwinManifest({ vendor: manifest.vendor, ...manifest.discovery }));
+        const to = lane(request);
+        return to ? to(request) : Response.json({ error: `${manifest.vendor}: no lane serves ${request.method} ${path}` }, { status: 404 });
+    }, { owners: () => lanesOwners(lanes) });
+}

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

@@ -0,0 +1,12 @@
+/** 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 the P3 repository beside a platform checkout. Applications do not acquire a
+ *  sibling checkout merely because one happens to be beside them. */
+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;
+/** Whether a directory holds a derived pack: a generated surface, its own or a lane's (a vendor whose APIs are all
+ *  lanes). A catalog lists no other package as a twin. This is what it is, not its grade. */
+export declare function isDerivedPack(dir: string): boolean;
+/** Package identity from a selected module, independent of the checkout's folder name and a service's alias. */
+export declare function vendorOfPackModule(modulePath: string): string | undefined;

package/dist/src/pack-paths.js

@@ -0,0 +1,86 @@
+// Host-side package locations. Pure at import: the browser-facing kernel does not discover packages or read files
+// until its host asks. Architecture, "The catalog: where twins come from"; ADR 0005.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+function packageName(dir) {
+    try {
+        return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).name;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Node's nearest installed package, including linked packages and hoisted workspace dependencies. */
+export function installedPackageDir(from, name) {
+    let dir = resolve(from);
+    for (;;) {
+        const candidate = join(dir, 'node_modules', ...name.split('/'));
+        if (existsSync(join(candidate, 'package.json')))
+            return candidate;
+        const up = dirname(dir);
+        if (up === dir)
+            return undefined;
+        dir = up;
+    }
+}
+/** A pack repository itself, or the P3 repository beside a platform checkout. Applications do not acquire a
+ *  sibling checkout merely because one happens to be beside them. */
+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 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;
+    }
+}
+/** Resolve one vendor's package directory for host-side reads (assets, infrastructure launchers). */
+export function vendorPackageDir(from, vendor) {
+    if (!/^[a-z][a-z0-9-]*$/.test(vendor))
+        return undefined;
+    const candidate = installedPackageDir(from, `@volter/twin-${vendor}`);
+    const installed = candidate && isDerivedPack(candidate) ? candidate : undefined;
+    const repo = packRepository(from);
+    const checkout = repo === undefined ? undefined : join(repo, vendor);
+    if (!checkout || packageName(checkout) !== `@volter/twin-${vendor}` || !isDerivedPack(checkout))
+        return installed;
+    if (!installed)
+        return checkout;
+    const major = (dir) => {
+        try {
+            return Number(/^(\d+)/.exec(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version ?? '')?.[1] ?? 0);
+        }
+        catch {
+            return 0;
+        }
+    };
+    return major(installed) > major(checkout) ? installed : checkout;
+}
+/** Whether a directory holds a derived pack: a generated surface, its own or a lane's (a vendor whose APIs are all
+ *  lanes). A catalog lists no other package as a twin. This is what it is, not its grade. */
+export function isDerivedPack(dir) {
+    const surface = (unit) => existsSync(join(unit, 'src', 'generated', 'surface.gen.json')) || existsSync(join(unit, 'src', 'generated', 'proto.gen.json'));
+    if (surface(dir))
+        return true;
+    return existsSync(dir) && readdirSync(dir, { withFileTypes: true }).some((entry) => entry.isDirectory() && surface(join(dir, entry.name)));
+}
+/** Package identity from a selected module, independent of the checkout's folder name and a service's alias. */
+export function vendorOfPackModule(modulePath) {
+    let dir = dirname(resolve(modulePath));
+    for (;;) {
+        const name = packageName(dir);
+        if (name !== undefined)
+            return name.startsWith('@volter/twin-') ? name.slice('@volter/twin-'.length) : undefined;
+        const up = dirname(dir);
+        if (up === dir)
+            return undefined;
+        dir = up;
+    }
+}