@volter/twin-standard 1.0.158 → 1.0.160

package/dist/src/walk/replay.js

@@ -0,0 +1,118 @@
+/** PostgreSQL's ISO timestamp text, retaining its six fractional digits and timezone offset. */
+function timestamp(value, oid) {
+    if (value === 'infinity')
+        return 10n ** 30n;
+    if (value === '-infinity')
+        return -(10n ** 30n);
+    if (typeof value !== 'string')
+        return undefined;
+    const m = /^(\d{4,6})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,6}))?(Z|([+-])(\d{2})(?::?(\d{2}))?(?::?(\d{2}))?)?( BC)?$/.exec(value);
+    if (!m || (oid === 1184) !== (m[8] !== undefined))
+        return undefined;
+    const [year, month, day, hour, minute, second] = m.slice(1, 7).map(Number);
+    if (!year || !month || month > 12 || !day || hour > 23 || minute > 59 || second > 59)
+        return undefined;
+    const astronomicalYear = m[13] ? 1 - year : year;
+    const leap = astronomicalYear % 4 === 0 && (astronomicalYear % 100 !== 0 || astronomicalYear % 400 === 0);
+    if (day > [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1])
+        return undefined;
+    const zoneHour = Number(m[10] ?? 0), zoneMinute = Number(m[11] ?? 0), zoneSecond = Number(m[12] ?? 0);
+    if (zoneHour > 15 || zoneMinute > 59 || zoneSecond > 59)
+        return undefined;
+    const adjustedYear = astronomicalYear - (month <= 2 ? 1 : 0);
+    const era = Math.floor(adjustedYear / 400), yearOfEra = adjustedYear - era * 400;
+    const dayOfYear = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
+    const days = era * 146097 + yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100) + dayOfYear - 719468;
+    const offset = (zoneHour * 3600 + zoneMinute * 60 + zoneSecond) * (m[9] === '-' ? -1 : 1);
+    return BigInt(days) * 86400000000n + BigInt(hour * 3600 + minute * 60 + second - offset) * 1000000n + BigInt((m[7] ?? '').padEnd(6, '0'));
+}
+/** A journey's declared native timestamp columns are present, valid and nondecreasing down the returned rows. */
+export function timestampOrderFailures(body, timeFields, columns) {
+    if (!columns.length)
+        return [];
+    const rows = body && typeof body === 'object' ? body.rows : undefined;
+    if (!Array.isArray(rows))
+        return ['timestamp ordering requires SQL result rows'];
+    const failures = [];
+    for (const column of columns) {
+        const oid = timeFields[column];
+        if (oid !== 1114 && oid !== 1184) {
+            failures.push(`${column} is not a native timestamp column`);
+            continue;
+        }
+        let previous;
+        for (const [i, row] of rows.entries()) {
+            const at = timestamp(row && typeof row === 'object' ? row[column] : undefined, oid);
+            if (at === undefined)
+                failures.push(`rows.${i}.${column} is not a non-null native timestamp`);
+            else if (previous !== undefined && at < previous)
+                failures.push(`rows.${i}.${column} precedes the previous row's timestamp`);
+            previous = at;
+        }
+    }
+    return failures;
+}
+/** Compare received traces by their selected engine declarations, retaining every undeclared byte. */
+export function compareReplays(first, second) {
+    const diagnostics = [];
+    if (!first.length)
+        diagnostics.push('the journey answered no steps');
+    if (first.length !== second.length)
+        diagnostics.push(`the replays answered ${first.length} and ${second.length} steps`);
+    const times = new Map();
+    for (let i = 0; i < Math.min(first.length, second.length); i++) {
+        const a = first[i], b = second[i];
+        const where = `step ${i + 1} (${a.name})`;
+        if (a.name !== b.name || a.path !== b.path || a.status !== b.status || JSON.stringify(a.sql) !== JSON.stringify(b.sql) || JSON.stringify(a.connection) !== JSON.stringify(b.connection)) {
+            diagnostics.push(`${where}: request, status or native engine provenance differs`);
+            continue;
+        }
+        const fields = a.sql?.clock === 'wall' ? a.sql.timeFields : {};
+        const same = (left, right, path) => {
+            if (path.length === 1 && a.connection?.kind === 'postgres' && a.connection.authenticated === true && path[0] === a.connection.field)
+                return typeof left === 'string' && typeof right === 'string';
+            const oid = path.length === 3 && path[0] === 'rows' ? fields[path[2]] : undefined;
+            if ((oid === 1114 || oid === 1184) && left !== null && right !== null) {
+                const x = timestamp(left, oid), y = timestamp(right, oid);
+                if (x === undefined || y === undefined) {
+                    diagnostics.push(`${where}: ${path.join('.')} is not a valid native timestamp`);
+                    return false;
+                }
+                const values = times.get(oid) ?? [];
+                values.push({ first: x, second: y, where: `${where}: ${path.join('.')}` });
+                times.set(oid, values);
+                return true;
+            }
+            if (Array.isArray(left) || Array.isArray(right))
+                return Array.isArray(left) && Array.isArray(right) && left.length === right.length && left.every((value, n) => same(value, right[n], [...path, String(n)]));
+            if (left && right && typeof left === 'object' && typeof right === 'object') {
+                const keys = Object.keys(left);
+                return JSON.stringify(keys) === JSON.stringify(Object.keys(right)) && keys.every(key => same(left[key], right[key], [...path, key]));
+            }
+            return JSON.stringify(left) === JSON.stringify(right);
+        };
+        if (!same(a.body, b.body, []))
+            diagnostics.push(`${where}: response bytes differ`);
+    }
+    // Equal timestamps form one group: ties may split or coincide, while a strict order cannot reverse.
+    for (const values of times.values()) {
+        values.sort((a, b) => a.first < b.first ? -1 : a.first > b.first ? 1 : 0);
+        let greatest;
+        for (let i = 0; i < values.length;) {
+            let end = i + 1;
+            while (end < values.length && values[end].first === values[i].first)
+                end++;
+            let next = greatest;
+            for (let n = i; n < end; n++) {
+                const at = values[n];
+                if (greatest && at.second < greatest.value)
+                    diagnostics.push(`${at.where}: timestamp order reverses relative to ${greatest.where}`);
+                if (!next || at.second > next.value)
+                    next = { value: at.second, where: at.where };
+            }
+            greatest = next;
+            i = end;
+        }
+    }
+    return { equal: diagnostics.length === 0, diagnostics };
+}

package/dist/src/walk/serve-pack.d.ts

@@ -1,10 +1,10 @@
+import { type ManagedDatabaseWalk } from './walk-database.js';
 export type ServedPack = {
     port: number;
     inspectPort?: number;
     wirePort?: number;
     stop: () => void | Promise<void>;
-    managedDatabaseUrl?: () => Promise<string>;
-};
+} & Omit<ManagedDatabaseWalk, 'stopDatabase'>;
 export declare function servePack(pack: string, options: {
     root?: string;
     scenarioPath?: string;

package/dist/src/walk/serve-pack.js

@@ -10,6 +10,19 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { join } from 'node:path';
 import { startTwinDatabase } from "./walk-database.js";
 export async function servePack(pack, options) {
+    const previousBoot = process.env.VOLTER_WORLD_BOOT_ID;
+    process.env.VOLTER_WORLD_BOOT_ID = 'conformance';
+    try {
+        return await serve(pack, options);
+    }
+    finally {
+        if (previousBoot === undefined)
+            delete process.env.VOLTER_WORLD_BOOT_ID;
+        else
+            process.env.VOLTER_WORLD_BOOT_ID = previousBoot;
+    }
+}
+async function serve(pack, options) {
     const mod = await import(__rewriteRelativeImportExtension(join(pack, 'src', 'server.ts')));
     const create = Object.entries(mod).find(([name, value]) => /^create\w+TwinServer$/.test(name) && typeof value === 'function')?.[1];
     if (!create)
@@ -23,9 +36,20 @@ export async function servePack(pack, options) {
         server = await create({ port: 0, ...options, ...(database ? { database: database.url } : {}) });
     }
     catch (error) {
-        await database?.stop();
+        try {
+            await database?.stop();
+        }
+        catch (cleanup) {
+            throw new AggregateError([error, cleanup], 'Pack startup and backing retirement failed');
+        }
         throw error;
     }
+    // a raw-TCP pack's HTTP control seam is the side port its descriptor declares for HTTP (a mail relay's policy door),
+    // where the pack's factory names it by that side port's option
+    const declared = descriptor?.transport === 'raw-tcp' ? descriptor.sidePorts?.find((side) => (side.scheme ?? 'http') === 'http') : undefined;
+    const control = declared ? server[declared.option] : undefined;
+    if (server.inspectPort === undefined && typeof control === 'number')
+        server = { ...server, inspectPort: control };
     if (!database)
         return server;
     const backing = database;
@@ -33,6 +57,24 @@ export async function servePack(pack, options) {
     return {
         ...server,
         managedDatabaseUrl: async () => backing.url,
-        stop: () => stopping ??= (async () => { await server.stop(); await backing.stop(); })(),
+        managedDatabaseClock: descriptor.managedDatabase.clock,
+        managedDatabaseConnection: backing.connection,
+        stop: () => stopping ??= (async () => {
+            const failures = [];
+            try {
+                await server.stop();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            try {
+                await backing.stop();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            if (failures.length)
+                throw new AggregateError(failures, 'Pack retirement failed');
+        })(),
     };
 }

package/dist/src/walk/shape.d.ts

@@ -15,14 +15,21 @@ export type ShapeOperation = {
         alternatives?: string[];
     };
 };
+/** Every selected unit's vendor fields, including nested spec schemas, GraphQL and native error wires. */
+export declare function vendorFieldsOf(pkg: string): Promise<Set<string>>;
+/** Decode a vendor answer without rounding wire integers; XML reads as its root's members. */
+export declare function decodeResponse(text: string, mediaType: string | undefined): unknown;
+/** Private stored fields, except names the vendor owns, in any answer, event or frame. */
+export declare function leaked(v: unknown, vendorFields: Set<string>, at?: string, unshaped?: boolean): string[];
 export type ShapeChecker = {
-    /** The spec operation a request matches, if any. An RPC wire answers a method whatever the HTTP method. */
+    /** The spec operation the routed request matches, if any. */
     operationOf: (method: string, path: string, headers?: Record<string, string>) => {
         op: ShapeOperation;
         params: Record<string, string>;
+        lane?: string;
     } | undefined;
     /** A request's URL as the unit routes it (a virtual-hosted S3 request's bucket moved from its host into its path). */
-    pathOf?: (path: string) => string;
+    pathOf: (method: string, path: string, headers?: Record<string, string>) => string;
     /** What in an answer the spec does not give the operation's resource (or its view). */
     failures: (op: ShapeOperation, body: unknown, mediaType?: string, accept?: string, status?: number, exchange?: {
         method: string;
@@ -30,14 +37,28 @@ export type ShapeChecker = {
     }) => string[];
     /** Whether a request pins an API version before the spec's, whose answers the spec does not describe (a Stripe
      *  mobile SDK's `Stripe-Version: 2024-06-20`), by the version header the manifest declares. */
-    pinsOlder: (headers: Record<string, string> | undefined) => boolean;
+    pinsOlder: (headers: Record<string, string> | undefined, op: ShapeOperation) => boolean;
+};
+/** The same response rules apply to a life's requests and the unscripted surface sweep. */
+export declare function responseProblems(checker: ShapeChecker | undefined, schemaFields: Set<string>, exchange: {
+    method: string;
+    path: string;
+    requestHeaders: Record<string, string>;
+    graphqlBody: unknown;
+    status: number;
+    mediaType: string | undefined;
+    body: unknown;
+    text: string;
+}): {
+    shape: string[];
+    leaks: string[];
 };
 /** The directories under a pack that are lanes: a derived unit with its own generated surface
  *  (`../twin-packs-p3/aws/secretsmanager/`, `../twin-packs-p3/planetscale/api/`). */
 export declare function lanesOf(pkg: string): string[];
 /** A derived pack's shape checker, or undefined for a pack with no generated surface. A pack's walk reaches its lanes'
  *  operations through the pack's router (a psdb life creates its database's passwords through the management API), so
- *  a request is matched against the pack's own surface, then each lane's, and judged by the surface it matched. */
+ *  the core gateway selects the owning lane before its surface is matched and its answer judged. */
 export declare function shapeChecker(pkg: string): Promise<ShapeChecker | undefined>;
 /** Where one connection stands for the check: the command whose intermediate reply the next lines answer. */
 export type LineConnection = {
@@ -48,7 +69,7 @@ export type LineShape = {
      *  command-reply table reads them; moves `conn` past an intermediate reply. */
     check: (conn: LineConnection, line: string | null, codes: number[]) => string[];
 };
-/** The SHAPE of a line protocol (scripts/derive-pack.ts from an RFC's command-reply table): each reply a
+/** The SHAPE of a line protocol (the derivation, from an RFC's command-reply table): each reply a
  *  code the spec allows the command it answers, or one any command may answer. A line after an
  *  intermediate reply (DATA's payload, a SASL response) is answered as that command's `then`. */
 export declare function lineShape(pkg: string): LineShape | undefined;

package/dist/src/walk/shape.js

@@ -10,45 +10,151 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // candidate only the values the spec lists (docs/contributing/architecture.md, "Protocol 3",
 // State and The report), and every field the spec requires. The walk (behavior-journey.ts) runs it on every successful step of a derived
 // pack, so a walk an author iterates with fails where the score would; score-pack reads it from there.
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { compileSurface, matchOperation } from '@volter/world-core/runtime';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { compileSurface, hostOf, laneSelector, matchOperation, slashesMerged, unitRequestRouter, worldDoorMatcher } from '@volter/world-core/runtime';
+import { parseExactJson } from '@volter/world-core/exact-json';
+import { hostRules } from '@volter/world-core/host-routing';
 import { binaryMedia } from "../spec-ir.js";
+import { schemaFieldNames } from "../spec-documents.js";
+import { unitsIn } from "../lanes.js";
+import { xmlMembers } from "./xml-view.js";
+import { parse, visit } from 'graphql';
 /** Whether a resource is one of the objects `said` names (a union's `object` lists every alternative's). */
 const isObject = (r, said) => typeof said === 'string' && (r.fields.find((f) => f.name === 'object')?.enum ?? []).includes(said);
+/** Field names owned by the vendor's resource schemas and native error templates. */
+function vendorFieldNames(surface, ...errors) {
+    const fields = new Set((surface?.resources ?? []).flatMap((resource) => resource.fields.map((field) => typeof field === 'string' ? field : field.name)));
+    const visit = (value) => {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+        }
+        else if (value && typeof value === 'object')
+            for (const [name, item] of Object.entries(value)) {
+                fields.add(name);
+                visit(item);
+            }
+    };
+    for (const error of errors)
+        visit(error);
+    return fields;
+}
+/** Every selected unit's vendor fields, including nested spec schemas, GraphQL and native error wires. */
+export async function vendorFieldsOf(pkg) {
+    const fields = new Set();
+    for (const unit of unitsIn(pkg)) {
+        const manifestPath = join(unit, 'src', 'manifest.ts');
+        const { manifest } = existsSync(manifestPath) ? await import(__rewriteRelativeImportExtension(manifestPath)) : {};
+        for (const name of ['surface.gen.json', 'graphql.gen.json']) {
+            const path = join(unit, 'src', 'generated', name);
+            if (existsSync(path))
+                for (const field of vendorFieldNames(JSON.parse(readFileSync(path, 'utf8'))))
+                    fields.add(field);
+        }
+        for (const field of schemaFieldNames(join(unit, 'spec')))
+            fields.add(field);
+        for (const field of vendorFieldNames(undefined, manifest?.error, ...(manifest?.auth?.wires ?? []).map((wire) => wire.error)))
+            fields.add(field);
+    }
+    return fields;
+}
+/** Decode a vendor answer without rounding wire integers; XML reads as its root's members. */
+export function decodeResponse(text, mediaType) {
+    let body;
+    try {
+        body = parseExactJson(text);
+    }
+    catch {
+        body = text;
+    }
+    return typeof body === 'string' && /xml/.test(mediaType ?? '') ? xmlMembers(text) ?? text : body;
+}
+/** Private stored fields, except names the vendor owns, in any answer, event or frame. */
+export function leaked(v, vendorFields, at = '', unshaped = false) {
+    if (Array.isArray(v))
+        return v.flatMap((x, i) => leaked(x, vendorFields, `${at}[${i}]`, unshaped)).slice(0, 5);
+    if (!v || typeof v !== 'object')
+        return [];
+    return Object.entries(v).flatMap(([k, x]) => ((k.startsWith('_') || (unshaped && k === 'updatedAt')) && !vendorFields.has(k) ? [`${at}${at ? '.' : ''}${k}`] : leaked(x, vendorFields, `${at}${at ? '.' : ''}${k}`, unshaped))).slice(0, 5);
+}
+/** Vendor schema fields plus the response keys this GraphQL request selects, including aliases. */
+function responseFieldNames(schemaFields, graphqlBody) {
+    const fields = new Set(schemaFields);
+    if (graphqlBody && typeof graphqlBody === 'object' && typeof graphqlBody.query === 'string') {
+        try {
+            visit(parse(graphqlBody.query), { Field: (field) => { fields.add(field.alias?.value ?? field.name.value); } });
+        }
+        catch { /* malformed documents have no selected response keys */ }
+    }
+    return fields;
+}
+/** The same response rules apply to a life's requests and the unscripted surface sweep. */
+export function responseProblems(checker, schemaFields, exchange) {
+    const hit = checker?.operationOf(exchange.method, exchange.path, exchange.requestHeaders);
+    const shaped = exchange.status >= 200 && exchange.status < 300 && hit !== undefined && !checker.pinsOlder(exchange.requestHeaders, hit.op);
+    return {
+        shape: shaped ? checker.failures(hit.op, exchange.body, exchange.mediaType, new Headers(exchange.requestHeaders).get('accept') ?? undefined, exchange.status, { method: exchange.method, responseText: exchange.text }) : [],
+        leaks: leaked(exchange.body, responseFieldNames(schemaFields, exchange.graphqlBody), '', !shaped || !hit?.op.answers),
+    };
+}
 /** The directories under a pack that are lanes: a derived unit with its own generated surface
  *  (`../twin-packs-p3/aws/secretsmanager/`, `../twin-packs-p3/planetscale/api/`). */
 export function lanesOf(pkg) {
-    if (!existsSync(pkg))
-        return [];
-    return readdirSync(pkg, { withFileTypes: true })
-        .filter((e) => e.isDirectory() && !['src', 'spec', 'journeys', 'node_modules', 'scripts', 'test-fixtures'].includes(e.name) && existsSync(join(pkg, e.name, 'src', 'generated', 'surface.gen.json')))
-        .map((e) => join(pkg, e.name));
+    return unitsIn(pkg).filter((unit) => unit !== pkg && existsSync(join(unit, 'src', 'generated', 'surface.gen.json')));
 }
 /** A derived pack's shape checker, or undefined for a pack with no generated surface. A pack's walk reaches its lanes'
  *  operations through the pack's router (a psdb life creates its database's passwords through the management API), so
- *  a request is matched against the pack's own surface, then each lane's, and judged by the surface it matched. */
+ *  the core gateway selects the owning lane before its surface is matched and its answer judged. */
 export async function shapeChecker(pkg) {
-    const units = (await Promise.all([pkg, ...lanesOf(pkg)].map((dir) => unitChecker(dir)))).filter((c) => !!c);
-    if (!units.length)
+    const units = await Promise.all(unitsIn(pkg).map(async (dir) => {
+        const path = join(dir, 'src', 'manifest.ts');
+        const { manifest } = existsSync(path) ? await import(__rewriteRelativeImportExtension(path)) : {};
+        return { dir, manifest, response: unitResponseOwner(dir, manifest), door: worldDoorMatcher(manifest?.doors ?? []) };
+    }));
+    if (!units.some((unit) => unit.response?.checker))
         return undefined;
-    if (units.length === 1)
-        return units[0];
+    const root = units[0];
+    const arrival = (method, path, headers) => {
+        const request = new Request(new URL(path, 'http://twin.local'), { method, headers });
+        return root.manifest?.mergeSlashes ? slashesMerged(request) : request;
+    };
+    const selected = root.manifest?.lanes ? laneSelector(root.manifest.lanes, Object.fromEntries(units.slice(1).map((unit) => [basename(unit.dir), {
+            manifest: unit.manifest ?? {}, fetch: { serves: unit.response?.checker?.serves,
+                contentHosts: (unit.manifest?.screens ?? []).filter((screen) => screen.kind === 'content' && screen.status === 'done').flatMap((screen) => [screen.host, ...(screen.hosts ?? [])]).filter((host) => !/[{<]/.test(host)).map((host) => host.toLowerCase()) },
+        }])), root.response?.checker?.serves) : undefined;
     const owner = new WeakMap();
-    return {
-        pinsOlder: (headers) => units[0].pinsOlder(headers),
-        pathOf: (path) => units.find((u) => u.operationOf('GET', path) || u.operationOf('PUT', path))?.pathOf?.(path) ?? path,
-        operationOf: (method, path, headers) => {
-            for (const u of units) {
-                const hit = u.operationOf(method, path, headers);
-                if (hit) {
-                    owner.set(hit.op, u);
-                    return hit;
-                }
-            }
+    const selectedRequest = (method, path, headers) => {
+        const request = arrival(method, path, headers);
+        const source = root.manifest?.mergeSlashes ? request.url : path;
+        const rootDoor = root.door(request.method, new URL(request.url).pathname);
+        const name = rootDoor ? undefined : selected?.(request);
+        const candidates = rootDoor ? [root] : selected ? [name === undefined ? root : units.find((unit) => basename(unit.dir) === name)] : units;
+        for (const unit of candidates) {
+            if (!unit)
+                continue;
+            const routed = unit.response?.pathOf(method, source, headers) ?? request.url;
+            if (rootDoor || unit.door(method, new URL(routed).pathname))
+                return { path: routed };
+            const checker = unit.response?.checker;
+            const hit = checker?.operationOf(method, source, headers);
+            if (hit)
+                return { path: routed, checker, hit: unit === root ? hit : { ...hit, lane: basename(unit.dir) } };
+        }
+        return { path: candidates[0]?.response?.pathOf(method, source, headers) ?? request.url };
+    };
+    const operationOf = (method, path, headers) => {
+        const selected = selectedRequest(method, path, headers);
+        if (!selected.hit)
             return undefined;
-        },
-        failures: (op, body, mediaType, accept, status, exchange) => (owner.get(op) ?? units[0]).failures(op, body, mediaType, accept, status, exchange),
+        owner.set(selected.hit.op, selected.checker);
+        return selected.hit;
+    };
+    return {
+        pinsOlder: (headers, op) => owner.get(op).pinsOlder(headers, op),
+        pathOf: (method, path, headers) => selectedRequest(method, path, headers).path,
+        operationOf,
+        failures: (op, body, mediaType, accept, status, exchange) => owner.get(op).failures(op, body, mediaType, accept, status, exchange),
     };
 }
 /** Accept's most specific media range decides its quality; an explicit q=0 overrides a wildcard. */
@@ -67,53 +173,54 @@ function acceptsMedia(accept, media, defaultMedia) {
     }).sort((a, b) => b.specificity - a.specificity || b.q - a.q);
     return (matches[0]?.q ?? 0) > 0;
 }
-async function unitChecker(pkg) {
+function unitResponseOwner(pkg, manifest) {
     const surfacePath = join(pkg, 'src', 'generated', 'surface.gen.json');
     if (!existsSync(surfacePath))
         return undefined;
-    const surface = JSON.parse(readFileSync(surfacePath, 'utf8'));
-    // a line protocol's surface is its commands' replies (lineShape); a command table's commands ride in a request's body
-    // (Upstash's REST envelope), which a check by method and path cannot see: its replies are not shape-checked yet, and
-    // its examples assert what each answers
-    if (['command-reply', 'command-table'].includes(String(surface.format)))
-        return undefined;
-    const manifestModule = existsSync(join(pkg, 'src', 'manifest.ts')) ? (await import(__rewriteRelativeImportExtension(join(pkg, 'src', 'manifest.ts')))) : {};
-    // a unit whose host can name part of what its path names (S3's virtual-hosted bucket) is routed as the kernel routes it: a host whose label is part of the path (the manifest's pathFromHost, S3's virtual-hosted
-    // addressing) puts it in front of the path
-    const hostPath = manifestModule.manifest?.pathFromHost ? new RegExp(manifestModule.manifest.pathFromHost, 'i') : undefined;
-    const pathStyle = (u) => {
-        const url = new URL(u);
-        const label = hostPath?.exec(url.hostname)?.[1];
-        return label ? `${url.protocol}//${url.host}/${label}${url.pathname === '/' ? '' : url.pathname}${url.search}` : u;
-    };
+    const source = JSON.parse(readFileSync(surfacePath, 'utf8'));
+    const surface = { ...source, operations: source.operations ?? [] };
     // a lane is routed by host ("Other wires: lanes"): one whose manifest names the hosts it serves is judged on those
     // alone, so a page or door of its pack on another host (a dashboard, a World door) is never read as one of its operations
-    const hosts = manifestModule.manifest?.hosts;
-    const served = (hostname) => !hosts || hosts.some((h) => (h.host ? hostname === h.host : !!h.suffix && hostname.endsWith(h.suffix)));
-    const versionHeader = manifestModule.manifest?.version?.header.toLowerCase();
+    const hosts = manifest?.hosts;
+    const claims = hostRules(hosts);
+    const versionHeader = manifest?.version?.header.toLowerCase();
     const specDate = /^\d{4}-\d{2}-\d{2}/.exec(String(surface.version))?.[0];
     // the path parameters whose values hold slashes (a git ref, a file path): the surface's own `spanning`, and the
     // manifest's where the spec cannot say
-    const spans = [...(surface.spanning ?? []), ...(manifestModule.manifest?.spanning ?? [])];
-    const routes = compileSurface({ ...surface, ...(spans.length ? { spanning: spans } : {}) });
+    const spans = [...(surface.spanning ?? []), ...(manifest?.spanning ?? [])];
+    const effectiveSurface = { ...surface, ...(spans.length ? { spanning: spans } : {}) };
+    const routes = compileSurface(effectiveSurface);
+    const routed = unitRequestRouter(manifest ?? {}, effectiveSurface, routes);
+    const door = worldDoorMatcher(manifest?.doors ?? []);
+    const requestAt = (method, path, headers) => {
+        const request = new Request(new URL(path, 'http://twin.local'), { method, headers });
+        return routed(manifest?.mergeSlashes ? slashesMerged(request) : request);
+    };
+    const pathOf = (method, path, headers) => requestAt(method, path, headers).url;
+    // Command surfaces retain routing ownership; their replies are checked through their native protocol.
+    if (['command-reply', 'command-table'].includes(String(surface.format)))
+        return { pathOf };
     const resources = new Map(surface.resources.map((r) => [r.name, r]));
-    return {
+    const checker = {
+        serves: (method, path) => Boolean(matchOperation(routes, method, path)),
         pinsOlder: (headers) => {
             if (!versionHeader || !specDate || !headers)
                 return false;
             const pinned = Object.entries(headers).find(([k]) => k.toLowerCase() === versionHeader)?.[1];
             return typeof pinned === 'string' && pinned.slice(0, 10) < specDate;
         },
-        pathOf: (path) => (/^https?:\/\//.test(path) ? pathStyle(path) : path),
         operationOf: (method, path, headers) => {
-            const url = new URL(/^https?:\/\//.test(path) ? pathStyle(path) : path, 'http://twin.local');
-            if (/^https?:\/\//.test(path) && !served(new URL(path).hostname))
-                return undefined;
+            const request = requestAt(method, path, headers);
+            const url = new URL(request.url);
+            if (/^https?:\/\//.test(path)) {
+                const original = new URL(path);
+                if (hosts && !claims.takes(hostOf(request), original.pathname))
+                    return undefined;
+            }
             // a World door the manifest declares is that door, never the vendor's operation at a path it would also match
-            if (manifestModule.manifest?.doors?.some((door) => door.method.toUpperCase() === method.toUpperCase() && door.path === url.pathname))
+            if (door(request.method, url.pathname))
                 return undefined;
-            const h = new Headers(headers ?? {});
-            const hit = matchOperation(routes, method, url.pathname, url.searchParams, h) ?? [...routes.keys()].map((m) => matchOperation(routes, m, url.pathname, url.searchParams, h)).find(Boolean);
+            const hit = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
             return hit ? { op: hit.operation, params: hit.params } : undefined;
         },
         failures: (op, body, mediaType, accept, status = op.successStatus ?? 200, exchange) => {
@@ -131,6 +238,8 @@ async function unitChecker(pkg) {
             const primary = op.answers ? resources.get(op.answers.resource) : undefined;
             if (!primary)
                 return [];
+            if (exchange && /xml/.test(media ?? ''))
+                body = xmlMembers(exchange.responseText, primary.fields.map((field) => field.name)) ?? body;
             if (!body || typeof body !== 'object')
                 return binary ? [`the answer is not the operation's ${primary.name} resource`] : [];
             // an answer that may be one of several resources (a card or a bank account) is judged as the one it says it is
@@ -149,7 +258,7 @@ async function unitChecker(pkg) {
                     const known = new Map([...r.fields.map((f) => [f.name, f]), ...(op.answers.extends ?? []).map((name) => [name, {}])]);
                     for (const [k, v] of Object.entries(item)) {
                         const f = known.get(k);
-                        const local = manifestModule.manifest?.worldFields?.[r.name]?.[k];
+                        const local = manifest?.worldFields?.[r.name]?.[k];
                         if (local) {
                             if (!k.startsWith('twin_') || !local.why?.trim() || f)
                                 found.push(`${r.name}.${k}: a World field must have a twin_ name and reason and must not replace a vendor field`);
@@ -181,8 +290,9 @@ async function unitChecker(pkg) {
             return [...new Set(out)];
         },
     };
+    return { pathOf, checker };
 }
-/** The SHAPE of a line protocol (scripts/derive-pack.ts from an RFC's command-reply table): each reply a
+/** The SHAPE of a line protocol (the derivation, from an RFC's command-reply table): each reply a
  *  code the spec allows the command it answers, or one any command may answer. A line after an
  *  intermediate reply (DATA's payload, a SASL response) is answered as that command's `then`. */
 export function lineShape(pkg) {

package/dist/src/walk/vendor-fetch.d.ts

@@ -1,13 +1,18 @@
+import { type ManagedDatabaseWalk } from './walk-database.js';
 import { type TwinStream } from '@volter/world-core/runtime';
 import type { PackFetchOptions } from '@volter/world-core';
 type ApplicationStandIn = NonNullable<PackFetchOptions['application']>;
 /** A pack's fetch over a World's root; a walk whose life names a scenario loads it as the World's (`scenarioPath`), and a
  *  life's application answers stand in for the application the vendor asks (`application`, this fetch's alone). */
-export type VendorFetchFactory = (root: string, options?: {
+export type VendorFetchFactory = ((root: string, options?: {
     scenarioPath?: string;
     application?: ApplicationStandIn;
-}) => (request: Request) => Response | Promise<Response>;
+}) => ((request: Request) => Response | Promise<Response>) & ManagedDatabaseWalk) & {
+    managedDatabaseDoor?: string;
+};
 export declare function vendorFetch(twinDir: string, vendor: string, dependenciesFrom?: string): Promise<VendorFetchFactory | undefined>;
+/** The selected pack's same fetch and native backing for in-process and browser transports. */
+export declare function packFetch(directory: string): Promise<VendorFetchFactory | undefined>;
 /** Named views of an answer: what a journey step's `view` asserts against. The kit's own: `jwt:<field>`, the payload of the
  *  JSON Web Token at that field of the answer, decoded as the application verifying it reads it (a session token's
  *  claims). A pack's own (`answerViews` in its index) beside them. */

package/dist/src/walk/vendor-fetch.js

@@ -16,6 +16,10 @@ export async function vendorFetch(twinDir, vendor, dependenciesFrom = twinDir) {
     const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
     if (!directory)
         return undefined;
+    return packFetch(directory);
+}
+/** The selected pack's same fetch and native backing for in-process and browser transports. */
+export async function packFetch(directory) {
     let mod;
     try {
         mod = (await import(__rewriteRelativeImportExtension(join(directory, 'src', 'index.ts'))));
@@ -31,9 +35,10 @@ export async function vendorFetch(twinDir, vendor, dependenciesFrom = twinDir) {
     const descriptor = mod.pack;
     if (!descriptor?.managedDatabase)
         return (root, options = {}) => factory({ root, ...options });
+    const managedDatabaseClock = descriptor.managedDatabase.clock;
     // Each walked twin owns a fresh SQL product through the ordinary selected-twin lifecycle.
     // Native SQL uses the descriptor's explicit wall clock; kernel World time is not claimed for it.
-    return (root, options = {}) => {
+    const backed = (root, options = {}) => {
         const bare = factory({ root, ...options });
         let bound;
         let host;
@@ -41,11 +46,17 @@ export async function vendorFetch(twinDir, vendor, dependenciesFrom = twinDir) {
         const served = (request) => bind().then((fetch) => { return fetch(request); });
         // The twin's SQL product, for what an application sends over its own wire (journey-kit.ts).
         const managedDatabaseUrl = () => bind().then(() => { return host.url; });
+        const managedDatabaseConnection = async (...args) => {
+            await bind();
+            return host.connection(...args);
+        };
         // The walk's end retires the selected twin's private engine through its World.
         const stopDatabase = async () => { if (bound === undefined)
             return; await bound.catch(() => undefined); await host?.stop(); };
-        return Object.assign(served, bare, { managedDatabaseUrl, stopDatabase });
+        return Object.assign(served, bare, { managedDatabaseUrl, managedDatabaseClock, managedDatabaseConnection, stopDatabase });
     };
+    backed.managedDatabaseDoor = descriptor.credentialDoor?.path;
+    return backed;
 }
 const jwtView = (field) => (body) => {
     const token = body?.[field];

package/dist/src/walk/walk-database.d.ts

@@ -1,6 +1,14 @@
-import type { TwinPack } from '@volter/world-core/runtime';
+import { type TwinPack } from '@volter/world-core/runtime';
+import type { ReplayStep } from './replay.js';
 export type TwinDatabase = {
     url: string;
+    connection: (method: string, path: string, status: number, body: unknown) => Promise<ReplayStep['connection']>;
     stop: () => Promise<void>;
 };
+export type ManagedDatabaseWalk = {
+    managedDatabaseUrl?: () => Promise<string>;
+    managedDatabaseClock?: 'wall';
+    managedDatabaseConnection?: TwinDatabase['connection'];
+    stopDatabase?: () => Promise<void>;
+};
 export declare function startTwinDatabase(pack: string, descriptor: TwinPack): Promise<TwinDatabase>;