@volter/twin-standard 1.0.158 → 1.0.159

package/src/walk/serve-pack.ts

@@ -1,17 +1,26 @@
 // The standard serves a pack with its declared backing, as the runtime binds it in a World.
 import { join } from 'node:path';
 import type { TwinPack } from '@volter/world-core/runtime';
-import { startTwinDatabase, type TwinDatabase } from './walk-database.ts';
+import { startTwinDatabase, type ManagedDatabaseWalk, type TwinDatabase } from './walk-database.ts';
 
 export type ServedPack = {
   port: number;
   inspectPort?: number;
   wirePort?: number;
   stop: () => void | Promise<void>;
-  managedDatabaseUrl?: () => Promise<string>;
-};
+} & Omit<ManagedDatabaseWalk, 'stopDatabase'>;
 
 export async function servePack(pack: string, options: { root?: string; scenarioPath?: string }): Promise<ServedPack> {
+  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: string, options: { root?: string; scenarioPath?: string }): Promise<ServedPack> {
   const mod = await import(join(pack, 'src', 'server.ts')) as Record<string, unknown>;
   const create = Object.entries(mod).find(([name, value]) => /^create\w+TwinServer$/.test(name) && typeof value === 'function')?.[1] as ((options: Record<string, unknown>) => Promise<ServedPack>) | undefined;
   if (!create) throw new Error('src/server.ts exports no create<Vendor>TwinServer');
@@ -20,13 +29,24 @@ export async function servePack(pack: string, options: { root?: string; scenario
   if (descriptor?.managedDatabase?.kind === 'postgres') database = await startTwinDatabase(pack, descriptor);
   let server: ServedPack;
   try { server = await create({ port: 0, ...options, ...(database ? { database: database.url } : {}) }); }
-  catch (error) { await database?.stop(); throw error; }
+  catch (error) {
+    try { await database?.stop(); }
+    catch (cleanup) { throw new AggregateError([error, cleanup], 'Pack startup and backing retirement failed'); }
+    throw error;
+  }
   if (!database) return server;
   const backing = database;
   let stopping: Promise<void> | undefined;
   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: unknown[] = [];
+      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/src/walk/shape.ts

@@ -2,57 +2,156 @@
 // 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 type { DerivedManifest } from '@volter/world-core';
+import { parseExactJson } from '@volter/world-core/exact-json';
+import { hostRules } from '@volter/world-core/host-routing';
 import { binaryMedia } from '../spec-ir.ts';
+import { schemaFieldNames } from '../spec-documents.ts';
+import { unitsIn } from '../lanes.ts';
+import { xmlMembers } from './xml-view.ts';
+import { parse, visit } from 'graphql';
 
 export type ShapeOperation = { id: string; method: string; path: string; class: string; resource?: string; successStatus?: number; responseMedia?: Record<string, string[]>; defaultResponseMedia?: Record<string, string>; answers?: { resource: string; list: boolean; key?: string; extends?: string[]; alternatives?: string[] } };
 type Resource = { name: string; fields: Array<{ name: string; required?: boolean; enum?: string[] }> };
 /** Whether a resource is one of the objects `said` names (a union's `object` lists every alternative's). */
 const isObject = (r: Resource, said: unknown): boolean => typeof said === 'string' && (r.fields.find((f) => f.name === 'object')?.enum ?? []).includes(said);
 type Surface = { version: string; basePath?: string; operations: ShapeOperation[]; resources: Resource[] };
+type FieldSurface = { resources?: Array<{ fields: Array<{ name: string } | string> }> };
+
+/** Field names owned by the vendor's resource schemas and native error templates. */
+function vendorFieldNames(surface: FieldSurface | undefined, ...errors: unknown[]): Set<string> {
+  const fields = new Set((surface?.resources ?? []).flatMap((resource) => resource.fields.map((field) => typeof field === 'string' ? field : field.name)));
+  const visit = (value: unknown): void => {
+    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: string): Promise<Set<string>> {
+  const fields = new Set<string>();
+  for (const unit of unitsIn(pkg)) {
+    const manifestPath = join(unit, 'src', 'manifest.ts');
+    const { manifest } = existsSync(manifestPath) ? await import(manifestPath) as { manifest?: { error?: unknown; auth?: { wires?: Array<{ error: unknown }> } } } : {};
+    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')) as FieldSurface)) 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: string, mediaType: string | undefined): unknown {
+  let body: unknown;
+  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: unknown, vendorFields: Set<string>, at = '', unshaped = false): string[] {
+  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: ReadonlySet<string>, graphqlBody: unknown): Set<string> {
+  const fields = new Set(schemaFields);
+  if (graphqlBody && typeof graphqlBody === 'object' && typeof (graphqlBody as { query?: unknown }).query === 'string') {
+    try { visit(parse((graphqlBody as { query: string }).query), { Field: (field) => { fields.add(field.alias?.value ?? field.name.value); } }); } catch { /* malformed documents have no selected response keys */ }
+  }
+  return fields;
+}
 
 export type ShapeChecker = {
-  /** The spec operation a request matches, if any. An RPC wire answers a method whatever the HTTP method. */
-  operationOf: (method: string, path: string, headers?: Record<string, string>) => { op: ShapeOperation; params: Record<string, string> } | undefined;
+  /** 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; responseText: string }) => 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;
 };
 
+type UnitChecker = Omit<ShapeChecker, 'pathOf'> & { serves: (method: string, path: string) => boolean };
+type UnitResponseOwner = { pathOf: ShapeChecker['pathOf']; checker?: UnitChecker };
+
+/** The same response rules apply to a life's requests and the unscripted surface sweep. */
+export 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[] } {
+  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: string): string[] {
-  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: string): Promise<ShapeChecker | undefined> {
-  const units = (await Promise.all([pkg, ...lanesOf(pkg)].map((dir) => unitChecker(dir)))).filter((c): c is ShapeChecker => !!c);
-  if (!units.length) return undefined;
-  if (units.length === 1) return units[0];
-  const owner = new WeakMap<ShapeOperation, ShapeChecker>();
+  const units = await Promise.all(unitsIn(pkg).map(async (dir) => {
+    const path = join(dir, 'src', 'manifest.ts');
+    const { manifest } = existsSync(path) ? await import(path) as { manifest?: Partial<DerivedManifest> } : {};
+    return { dir, manifest, response: unitResponseOwner(dir, manifest), door: worldDoorMatcher(manifest?.doors ?? []) };
+  }));
+  if (!units.some((unit) => unit.response?.checker)) return undefined;
+  const root = units[0]!;
+  const arrival = (method: string, path: string, headers: Record<string, string> | undefined): Request => {
+    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<ShapeOperation, UnitChecker>();
+  const selectedRequest = (method: string, path: string, headers: Record<string, string> | undefined) => {
+    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: ShapeChecker['operationOf'] = (method, path, headers) => {
+    const selected = selectedRequest(method, path, headers);
+    if (!selected.hit) return undefined;
+    owner.set(selected.hit.op, selected.checker!);
+    return selected.hit;
+  };
   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; }
-      }
-      return undefined;
-    },
-    failures: (op, body, mediaType, accept, status, exchange) => (owner.get(op) ?? units[0]!).failures(op, body, mediaType, accept, status, exchange),
+    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),
   };
 }
 
@@ -71,48 +170,49 @@ function acceptsMedia(accept: string | undefined, media: string, defaultMedia?:
   return (matches[0]?.q ?? 0) > 0;
 }
 
-async function unitChecker(pkg: string): Promise<ShapeChecker | undefined> {
+function unitResponseOwner(pkg: string, manifest: Partial<DerivedManifest> | undefined): UnitResponseOwner | undefined {
   const surfacePath = join(pkg, 'src', 'generated', 'surface.gen.json');
   if (!existsSync(surfacePath)) return undefined;
-  const surface = JSON.parse(readFileSync(surfacePath, 'utf8')) as Surface;
-  // 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 as { format?: string }).format))) return undefined;
-  const manifestModule = existsSync(join(pkg, 'src', 'manifest.ts')) ? ((await import(join(pkg, 'src', 'manifest.ts'))) as { manifest?: { doors?: ReadonlyArray<{ method: string; path: string }>; worldFields?: Record<string, Record<string, { type: 'array' | 'object' | 'string' | 'number' | 'boolean'; why: string }>>; version?: { header: string }; hosts?: ReadonlyArray<{ host?: string; suffix?: string }>; spanning?: ReadonlyArray<string>; pathFromHost?: string } }) : {};
-  // 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: string): string => {
-    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')) as Surface;
+  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: string): boolean => !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 as { spanning?: string[] }).spanning ?? []), ...(manifestModule.manifest?.spanning ?? [])];
-  const routes = compileSurface({ ...surface, ...(spans.length ? { spanning: spans } : {}) });
+  const spans = [...((surface as { spanning?: string[] }).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: string, path: string, headers: Record<string, string> | undefined): Request => {
+    const request = new Request(new URL(path, 'http://twin.local'), { method, headers });
+    return routed(manifest?.mergeSlashes ? slashesMerged(request) : request);
+  };
+  const pathOf: ShapeChecker['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 as { format?: string }).format))) return { pathOf };
   const resources = new Map(surface.resources.map((r) => [r.name, r]));
-  return {
+  const checker: UnitChecker = {
+    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)) 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);
+      if (door(request.method, url.pathname)) return undefined;
+      const hit = matchOperation(routes, request.method, url.pathname, url.searchParams, request.headers);
       return hit ? { op: hit.operation as ShapeOperation, params: hit.params } : undefined;
     },
     failures: (op, body, mediaType, accept, status = op.successStatus ?? 200, exchange) => {
@@ -128,6 +228,7 @@ async function unitChecker(pkg: string): Promise<ShapeChecker | undefined> {
       if (binary && declared.some((value) => value.toLowerCase() === media) && acceptsMedia(accept, media, defaultMedia)) return [];
       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
       const alternatives = [primary, ...(op.answers!.alternatives ?? []).map((n) => resources.get(n)).filter((x): x is Resource => !!x)];
@@ -144,7 +245,7 @@ async function unitChecker(pkg: string): Promise<ShapeChecker | undefined> {
           const known = new Map<string, { enum?: string[] }>([...r.fields.map((f) => [f.name, f] as const), ...(op.answers!.extends ?? []).map((name) => [name, {}] as const)]);
           for (const [k, v] of Object.entries(item as Record<string, unknown>)) {
             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`);
               const type = Array.isArray(v) ? 'array' : v === null ? 'null' : typeof v;
@@ -170,6 +271,7 @@ async function unitChecker(pkg: string): Promise<ShapeChecker | undefined> {
       return [...new Set(out)];
     },
   };
+  return { pathOf, checker };
 }
 
 // ── a line protocol's replies ─────────────────────────────────────────────────────────────────

package/src/walk/vendor-fetch.ts

@@ -2,7 +2,7 @@
 // index. What the catalog's walkers drive (behavior journeys, the spec census probe, the invariants)
 // since the worker render left with the v1 host.
 import { join } from 'node:path';
-import { type TwinDatabase, startTwinDatabase } from './walk-database.ts';
+import { type ManagedDatabaseWalk, type TwinDatabase, startTwinDatabase } from './walk-database.ts';
 import { type TwinStream, type TwinPack } from '@volter/world-core/runtime';
 import type { PackFetchOptions } from '@volter/world-core';
 import { walkPackDirectory } from './pack-directory.ts';
@@ -11,11 +11,16 @@ 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?: { scenarioPath?: string; application?: ApplicationStandIn }) => (request: Request) => Response | Promise<Response>;
+export type VendorFetchFactory = ((root: string, options?: { scenarioPath?: string; application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & ManagedDatabaseWalk) & { managedDatabaseDoor?: string };
 
 export async function vendorFetch(twinDir: string, vendor: string, dependenciesFrom = twinDir): Promise<VendorFetchFactory | undefined> {
   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: string): Promise<VendorFetchFactory | undefined> {
   let mod: Record<string, unknown>;
   try { mod = (await import(join(directory, 'src', 'index.ts'))) as Record<string, unknown>; } catch { return undefined; }
   // a pack exports create<Name>Fetch (its generated fetch.ts)
@@ -24,9 +29,10 @@ export async function vendorFetch(twinDir: string, vendor: string, dependenciesF
   const factory = mod[name] as (options: { root: string; database?: string; scenarioPath?: string; application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & Record<string, unknown>;
   const descriptor = mod.pack as TwinPack | undefined;
   if (!descriptor?.managedDatabase) return (root: string, 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: string, options = {}) => {
+  const backed: VendorFetchFactory = (root, options = {}) => {
     const bare = factory({ root, ...options });
     let bound: Promise<(request: Request) => Response | Promise<Response>> | undefined;
     let host: TwinDatabase | undefined;
@@ -34,10 +40,16 @@ export async function vendorFetch(twinDir: string, vendor: string, dependenciesF
     const served = (request: 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: TwinDatabase['connection'] = 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;
 }
 
 

package/src/walk/walk-database.ts

@@ -3,7 +3,8 @@
 import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
-import type { TwinPack } from '@volter/world-core/runtime';
+import { worldDoorMatcher, type TwinPack } from '@volter/world-core/runtime';
+import type { ReplayStep } from './replay.ts';
 
 type Runtime = typeof import('@volter/world-runtime');
 let loaded: Promise<Runtime> | undefined;
@@ -13,13 +14,24 @@ const worldRuntime = () => loaded ??= (async () => {
   return import('@volter/world-runtime');
 })();
 
-export type TwinDatabase = { url: string; stop: () => Promise<void> };
+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 async function startTwinDatabase(pack: string, descriptor: TwinPack): Promise<TwinDatabase> {
   if (!process.env.VOLTER_WORLD) throw new Error('A managed SQL walk requires its enclosing World');
   const definition = descriptor.managedDatabase, door = descriptor.credentialDoor;
   if (!definition || !door || !definition.credentialField) throw new Error('The selected twin must declare its SQL credential door field');
-  const { runWorld, worldConfigDocument } = await worldRuntime();
+  const { runWorld, worldConfigDocument, verifyPrivateTwinDatabaseConnection } = await worldRuntime();
   // Keep the disposable World on the pack's own volume and package-resolution ancestry.
   const root = mkdtempSync(join(dirname(pack), '.walk-database-'));
   const manifest = JSON.parse(readFileSync(join(pack, 'package.json'), 'utf8')) as { name: string };
@@ -30,10 +42,10 @@ export async function startTwinDatabase(pack: string, descriptor: TwinPack): Pro
   const readyFile = join(root, 'ready.json'), releaseFile = join(root, 'release');
   // Ask the selected twin's actual product door. The runtime alone allocates and owns its engine.
   const hold = `
-    import { existsSync, readFileSync, renameSync, watch, writeFileSync } from 'node:fs';
-    import { dirname } from 'node:path';
+    import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+    import { join } from 'node:path';
     const [ready, release, vendor, path, body, field] = process.argv.slice(1);
-    if (!process.env.VOLTER_WORLD_INSTANCE) throw new Error('Missing held World instance');
+    if (!process.env.VOLTER_WORLD_INSTANCE || !process.env.VOLTER_WORLD_DATA) throw new Error('Missing held World instance');
     const instance = JSON.parse(readFileSync(process.env.VOLTER_WORLD_INSTANCE, 'utf8'));
     const service = instance.services[vendor];
     if (!service?.url) throw new Error('Selected twin has no product endpoint');
@@ -42,8 +54,8 @@ export async function startTwinDatabase(pack: string, descriptor: TwinPack): Pro
     const result = await response.json();
     if (typeof result[field] !== 'string' || !result[field]) throw new Error('SQL credential door omitted its declared field');
     const done = () => { if (existsSync(release)) process.exit(0); };
-    watch(dirname(release), done);
-    writeFileSync(ready + '.tmp', JSON.stringify({ url: result[field] }), {mode:0o600});
+    setInterval(done, 100);
+    writeFileSync(ready + '.tmp', JSON.stringify({ url: result[field], databaseRoot: join(process.env.VOLTER_WORLD_DATA, vendor) }), {mode:0o600});
     renameSync(ready + '.tmp', ready);
     done();`;
   let finished: { result?: Awaited<ReturnType<Runtime['runWorld']>>; error?: unknown; failed: boolean } | undefined;
@@ -61,13 +73,27 @@ export async function startTwinDatabase(pack: string, descriptor: TwinPack): Pro
     }
     await new Promise(resolve => setTimeout(resolve, 100));
   }
-  const ready = JSON.parse(readFileSync(readyFile, 'utf8')) as { url: string };
+  const ready = JSON.parse(readFileSync(readyFile, 'utf8')) as { url: string; databaseRoot: string };
   let stopping: Promise<void> | undefined;
-  return { url: ready.url,
-    stop: () => stopping ??= (async () => {
-      writeFileSync(releaseFile, 'released\n');
-      const result = await task;
-      if (result.exitCode !== 0) throw new Error(`Twin SQL World consumer exited ${result.exitCode}; evidence: ${root}`);
-    })(),
+  const stop = () => stopping ??= (async () => {
+    writeFileSync(releaseFile, 'released\n');
+    const result = await task;
+    if (result.exitCode !== 0) throw new Error(`Twin SQL World consumer exited ${result.exitCode}; evidence: ${root}`);
+  })();
+  const verify = (value: unknown) => verifyPrivateTwinDatabaseConnection(descriptor.vendor, ready.databaseRoot, value);
+  try { await verify(ready.url); }
+  catch (error) {
+    try { await stop(); }
+    catch (cleanup) { throw new AggregateError([error, cleanup], 'Native connection verification and World retirement failed'); }
+    throw error;
+  }
+  const matches = worldDoorMatcher([{ method: 'POST', path: door.path }]);
+  return { url: ready.url, stop,
+    connection: async (method, path, status, body) => {
+      if (status < 200 || status >= 300 || !matches(method, path)) return undefined;
+      const value = body && typeof body === 'object' ? (body as Record<string, unknown>)[definition.credentialField] : undefined;
+      await verify(value);
+      return { kind: definition.kind, field: definition.credentialField, authenticated: true };
+    },
   };
 }

package/src/walk/xml-view.ts

@@ -3,15 +3,16 @@
 // text. What a restXml output structure's members are on the wire, so a journey asserts and captures them (`Contents.0.Key`)
 // and SHAPE checks them as it checks a JSON answer's. Attributes and namespaces are not members and are dropped. XML
 // cannot say a lone element is a list: one `<Contents>` reads as an object, two as a list. A root with no children is
-// its one member, by its name.
+// its one member, by its name. When a resource schema is supplied, an empty root is a member only if the schema names it.
 
 const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
 const decode = (s: string): string => s.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e: string) => (e[0] === '#' ? String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))) : ENTITIES[e] ?? m));
 
 type Node = { name: string; children: Node[]; text: string };
 
-/** The root element's members, or undefined when the text is not one XML document. */
-export function xmlMembers(text: string): Record<string, unknown> | undefined {
+/** The root element's members, or undefined when the text is not one XML document.
+ *  A schema distinguishes an empty structure from an empty scalar member such as LocationConstraint. */
+export function xmlMembers(text: string, rootFields?: ReadonlyArray<string>): Record<string, unknown> | undefined {
   const src = text.replace(/<\?[\s\S]*?\?>/g, '').replace(/<!--[\s\S]*?-->/g, '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, c: string) => c.replace(/&/g, '&amp;').replace(/</g, '&lt;'));
   const stack: Node[] = [{ name: '', children: [], text: '' }];
   const tag = /<(\/?)([\w:.-]+)[^>]*?(\/?)>|([^<]+)/g;
@@ -39,6 +40,6 @@ export function xmlMembers(text: string): Record<string, unknown> | undefined {
     return out;
   };
   // a document whose root is a leaf (S3's `<LocationConstraint>auto</LocationConstraint>`) is that one member
-  if (!root.children.length) return { [root.name]: value(root) };
+  if (!root.children.length) return !root.text.trim() && rootFields && !rootFields.includes(root.name) ? {} : { [root.name]: value(root) };
   return value(root) as Record<string, unknown>;
 }