@volter/twin-standard 1.0.153 → 1.0.155

package/src/create-pack.ts

@@ -360,7 +360,7 @@ export function cliFile(vendor: string, live = false): string {
   const Name = pascal(vendor);
   const ingest = live ? `// the RTMP ingest's side port, which the World allocates (the manifest's sidePorts)\nconst ingestPort = Number(optionValue(rest, '--ingest-port', '0')) || undefined;\n` : '';
   const served = live ? `  process.stdout.write(s.ingestPort ? \`${vendor} twin ingest at rtmp://127.0.0.1:\${s.ingestPort}\\n\` : '${vendor} twin: no RTMP ingest\\n');\n` : '';
-  return `#!/usr/bin/env node\n// world-${vendor}: serve the ${vendor} twin.\nimport { hasFlag, optionValue } from '@volter/world-core/args';\nimport { keepProcessAlive } from '@volter/world-core/lifecycle';\nimport { create${Name}TwinServer } from './server.ts';\n\nconst [cmd, ...rest] = process.argv.slice(2);\nconst port = Number(optionValue(rest, '--port', '0')) || undefined;\nconst root = optionValue(rest, '--root') || undefined;\nconst readOnly = hasFlag(rest, '--read-only');\n// the World's managed Postgres, which the runtime binds a pack declaring managedDatabase to\nconst database = optionValue(rest, '--database') || undefined;\n// the World's scenario file, for a model vendor's turns\nconst scenarioPath = optionValue(rest, '--scenario') || undefined;\n${ingest}\nif (cmd === 'serve' || cmd === undefined) {\n  const s = await create${Name}TwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {})${live ? ', ...(ingestPort ? { ingestPort } : {})' : ''} });\n  process.stdout.write(\`${vendor} twin\${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:\${s.port}\\n\`);\n${served}  await keepProcessAlive();\n} else {\n  process.stdout.write('Usage: world-${vendor} serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]${live ? ' [--ingest-port N]' : ''}\\n');\n}\n`;
+  return `#!/usr/bin/env node\n// world-${vendor}: serve the ${vendor} twin.\nimport { hasFlag, optionValue } from '@volter/world-core/args';\nimport { keepProcessAlive } from '@volter/world-core/lifecycle';\nimport { create${Name}TwinServer } from './server.ts';\n\nconst [cmd, ...rest] = process.argv.slice(2);\nconst port = Number(optionValue(rest, '--port', '0')) || undefined;\nconst root = optionValue(rest, '--root') || undefined;\nconst readOnly = hasFlag(rest, '--read-only');\n// the selected twin's private Postgres, which the runtime binds a pack declaring managedDatabase to\nconst database = optionValue(rest, '--database') || undefined;\n// the World's scenario file, for a model vendor's turns\nconst scenarioPath = optionValue(rest, '--scenario') || undefined;\n${ingest}\nif (cmd === 'serve' || cmd === undefined) {\n  const s = await create${Name}TwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {})${live ? ', ...(ingestPort ? { ingestPort } : {})' : ''} });\n  process.stdout.write(\`${vendor} twin\${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:\${s.port}\\n\`);\n${served}  await keepProcessAlive();\n} else {\n  process.stdout.write('Usage: world-${vendor} serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]${live ? ' [--ingest-port N]' : ''}\\n');\n}\n`;
 }
 
 /** A vendor id as a name in code: `npm-registry` is `NpmRegistry`. */
@@ -414,7 +414,6 @@ Contributor mechanics belong to the [pack procedure](https://world-docs.volter.a
 
 export function initFiles(vendor: string): Record<string, string> {
   const Name = pascal(vendor);
-  const semantics = `${Name[0]!.toLowerCase()}${Name.slice(1)}Semantics`;
   return {
     'package.json': `${JSON.stringify({
       name: `@volter/twin-${vendor}`, version: '1.0.0', description: `The ${vendor} twin (Protocol 3).`, author: 'Volter (https://github.com/volter-ai)', license: 'Apache-2.0',
@@ -448,8 +447,6 @@ export function initFiles(vendor: string): Record<string, string> {
  *  surface of its own under `<lane>/src`, keeping the vendor's one store and sharing its `src/semantics/shared.ts`, and the
  *  pack's server routing each lane's host to it. */
 export function laneInitFiles(vendor: string, lanes: string[]): Record<string, string> {
-  const Name = pascal(vendor);
-  const camel = (s: string): string => { const p = pascal(s); return `${p[0]!.toLowerCase()}${p.slice(1)}`; };
   const single = initFiles(vendor);
   const files: Record<string, string> = {
     'package.json': single['package.json']!.replace('"spec",', lanes.map((l) => `"${l}",`).join('\n    ')),

package/src/dependency-lock.ts

@@ -0,0 +1,27 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseAllDocuments } from 'yaml';
+
+/** The application's selected direct dependency, including the exact installer's integrity. */
+export function dependencyLock(root: string) {
+  const pnpm = join(root, 'pnpm-lock.yaml');
+  if (existsSync(pnpm)) {
+    const bytes = readFileSync(pnpm);
+    const documents = parseAllDocuments(bytes.toString());
+    for (const doc of documents) if (doc.errors.length) throw doc.errors[0];
+    const lock = documents.map(doc => doc.toJS()).find(doc => doc?.importers?.['.'] && !doc.importers['.'].packageManagerDependencies);
+    if (!lock) throw new Error('No pnpm application importer');
+    return { bytes, file: pnpm, entry(name: string) {
+      const importer = lock.importers['.'];
+      const selected = importer.dependencies?.[name] ?? importer.devDependencies?.[name] ?? importer.optionalDependencies?.[name];
+      if (!selected) return undefined;
+      const selectedRef = String(selected.version);
+      const ref = lock.packages?.[`${name}@${selectedRef}`] ? selectedRef : selectedRef.replace(/\(.*$/, '');
+      const pkg = lock.packages?.[`${name}@${ref}`];
+      return { version: pkg?.version ?? ref, integrity: pkg?.resolution?.integrity };
+    } };
+  }
+  const file = join(root, 'package-lock.json'), bytes = readFileSync(file);
+  const lock = JSON.parse(bytes.toString());
+  return { bytes, file, entry(name: string) { return lock.packages?.[`node_modules/${name}`] as { version?: string; integrity?: string } | undefined; } };
+}

package/src/pack-facts.ts

@@ -1,7 +1,7 @@
 // Published descriptor compiler. Pack locations are explicit; imports happen only when called by a publisher.
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { PACK_ARCHETYPES, PROTOCOL_VERSION, protocolStanding } from '@volter/world-core/runtime';
+import { PACK_ARCHETYPES, PROTOCOL_VERSION, protocolStanding, type TwinPack } from '@volter/world-core/runtime';
 
 export type PackFacts = {
   /** Explicit vendor-server backing; this entry declares no pack protocol or factory. */
@@ -32,14 +32,14 @@ export type PackFacts = {
   endpointEnv?: { name: string; templates?: Record<string, string> };
   endpointEnvNone?: string;
   /** The door that issues the application a credential the twin accepts (see TwinPack.credentialDoor). */
-  credentialDoor?: { path: string; body: Record<string, unknown>; fill: Record<string, string> };
+  credentialDoor?: TwinPack['credentialDoor'];
   credentialIssuer?: string;
   /** The Prisma driver adapter this database twin is reached through (see TwinPack.prismaAdapter). */
   prismaAdapter?: { adapter: string; export: string; urlEnv: string };
   /** The managed-infrastructure kind this pack is the World's backing for (architecture.md, "The descriptor"). */
   managedService?: { kind: 'redis' | 'mongodb' | 'clickhouse'; scheme: string; note: string; configurationArg?: '--configuration'; originalInputs?: { version: 1; manifestArg: '--original-inputs'; rootArg: '--original-root'; digestArg: '--original-inputs-sha256'; paths: string[] } };
-  /** The World's managed database the runtime binds the twin to (see TwinPack.managedDatabase). */
-  managedDatabase?: { kind: 'postgres'; arg: string; note: string };
+  /** The selected twin's private SQL identity and credential field (see TwinPack.managedDatabase). */
+  managedDatabase?: { kind: 'postgres'; arg: string; user: string; database: string; clock: 'wall'; credentialField: string; note: string };
   /** Listeners the twin opens beside its main port (see TwinPack.sidePorts). */
   sidePorts?: Array<{ name: string; option: string; flag: string; path?: string; scheme?: string; note: string }>;
   /** DERIVED, never declared: the pack's `create<Name>TwinServer` factory export — the
@@ -184,9 +184,12 @@ export async function compilePackFacts(dirs: Array<{ vendor: string; dir: string
       facts.prismaAdapter = pack.prismaAdapter;
     }
     if (pack.managedDatabase !== undefined) {
-      const md = pack.managedDatabase as { kind?: unknown; arg?: unknown; note?: unknown };
-      if (md.kind !== 'postgres') throw new Error(`pack-facts: ${vendor} declares managedDatabase.kind "${String(md.kind)}"; the runtime binds only the World's managed postgres`);
+      const md = pack.managedDatabase as { kind?: unknown; arg?: unknown; user?: unknown; database?: unknown; clock?: unknown; credentialField?: unknown; note?: unknown };
+      if (md.kind !== 'postgres') throw new Error(`pack-facts: ${vendor} declares managedDatabase.kind "${String(md.kind)}"; private SQL supports postgres`);
       if (typeof md.arg !== 'string' || !/^--[a-z][a-z-]*$/.test(md.arg)) throw new Error(`pack-facts: ${vendor} declares managedDatabase.arg "${String(md.arg)}"; it is the serve flag the URL follows (--name)`);
+      for (const key of ['user', 'database'] as const) if (typeof md[key] !== 'string' || !md[key] || /[\r\n\0$]/u.test(md[key]) || Buffer.byteLength(md[key], 'utf8') > 63) throw new Error(`pack-facts: ${vendor} private database ${key} must be a literal PostgreSQL identifier of at most 63 bytes`);
+      if (md.clock !== 'wall') throw new Error(`pack-facts: ${vendor} private postgres must declare its wall clock`);
+      if (typeof md.credentialField !== 'string' || !Object.values(pack.credentialDoor?.fill ?? {}).includes(md.credentialField) || /^(?:file|directory|side):/.test(md.credentialField)) throw new Error(`pack-facts: ${vendor} private database must name its credential door's scalar URL field`);
       if (typeof md.note !== 'string' || md.note.trim() === '') throw new Error(`pack-facts: ${vendor} declares managedDatabase with no note`);
       facts.managedDatabase = pack.managedDatabase;
     }

package/src/published.ts

@@ -19,7 +19,7 @@ export const vendorOfPackage = (name: string): string => name.replace(/^@[^/]+\/
 async function withPublished<T>(spec: string, opts: { registry?: string }, use: (dir: string, tmp: string) => Promise<T>): Promise<T> {
   const tmp = mkdtempSync(join(tmpdir(), 'twin-standard-'));
   try {
-    const pack = spawnSync('npm', ['pack', spec, '--pack-destination', tmp, '--silent', ...(opts.registry ? ['--registry', opts.registry] : [])], { encoding: 'utf8' });
+    const pack = spawnSync('npm', ['pack', '--force', spec, '--pack-destination', tmp, '--silent', ...(opts.registry ? ['--registry', opts.registry] : [])], { encoding: 'utf8' });
     const tarball = readdirSync(tmp).find((f) => f.endsWith('.tgz'));
     if (pack.status !== 0 || !tarball) throw new Error(`${spec}: the registry gave no tarball (${String(pack.stderr).trim().split('\n').at(-1) ?? ''})`);
     const untar = spawnSync('tar', ['-xzf', join(tmp, tarball), '-C', tmp], { encoding: 'utf8' });
@@ -66,7 +66,7 @@ export async function conformPublished(spec: string, opts: { registry?: string }
     const platform = Object.keys(deps).filter((d) => d.startsWith('@volter/'));
     const others = Object.entries(deps).filter(([d]) => !d.startsWith('@volter/')).map(([d, v]) => `${d}@${v}`);
     if (others.length) {
-      const install = spawnSync('npm', ['install', '--no-save', '--omit=dev', '--omit=peer', '--ignore-scripts', '--no-audit', '--no-fund', '--no-package-lock', ...(opts.registry ? ['--registry', opts.registry] : []), ...others], { cwd: dirname(dir), encoding: 'utf8' });
+      const install = spawnSync('pnpm', ['add', '--prod', '--config.autoInstallPeers=false', '--package-import-method=hardlink', '--config.nodeLinker=hoisted', '--ignore-scripts', ...(opts.registry ? ['--registry', opts.registry] : []), ...others], { cwd: dirname(dir), encoding: 'utf8' });
       if (install.status !== 0) throw new Error(`${spec}: its dependencies do not install (${String(install.stderr).trim().split('\n').at(-1) ?? ''})`);
     }
     mkdirSync(join(dir, 'node_modules', '@volter'), { recursive: true });

package/src/walk/journey-kit.ts

@@ -436,8 +436,8 @@ export const isGit = (step: Step): step is GitStep => 'git' in step;
 export type WaitStep = { name: string; wait: string };
 export const isWait = (step: Step): step is WaitStep => 'wait' in step;
 
-/** What an application sends the World's managed database over the database's own wire, not through the vendor's API (a
- *  pack whose data plane is the World's Postgres, the descriptor's `managedDatabase`): its migrations as its deploy applies
+/** What an application sends the selected twin's database over its SQL wire, not through the vendor's HTTP API (a
+ *  pack whose descriptor declares a private SQL product (`managedDatabase`)): its migrations as its deploy applies
  *  them and the queries it sends, each on the application's one connection to the walked World's database (world-core
  *  `databaseSession`), so a transaction it begins stays open into its next steps, as on its own connection. `sql` alone is
  *  one simple Query (a migration file, a `BEGIN`); with `values` it is one extended-protocol statement, the values bind

package/src/walk/serve-pack.ts

@@ -1,7 +1,7 @@
 // The standard serves a pack with its declared backing, as the runtime binds it in a World.
 import { join } from 'node:path';
-import { worldNow } from '@volter/world-core/runtime';
-import { startPgliteHost, type PgliteHost } from './walk-database.ts';
+import type { TwinPack } from '@volter/world-core/runtime';
+import { startTwinDatabase, type TwinDatabase } from './walk-database.ts';
 
 export type ServedPack = {
   port: number;
@@ -10,13 +10,13 @@ export type ServedPack = {
   managedDatabaseUrl?: () => Promise<string>;
 };
 
-export async function servePack(pack: string, options: Record<string, unknown>): Promise<ServedPack> {
+export async function servePack(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');
-  const descriptor = (await import(join(pack, 'src', 'index.ts'))).pack as { managedDatabase?: { kind: string } } | undefined;
-  let database: PgliteHost | undefined;
-  if (descriptor?.managedDatabase?.kind === 'postgres' && options.database === undefined) database = await startPgliteHost();
+  const descriptor = (await import(join(pack, 'src', 'index.ts'))).pack as TwinPack | undefined;
+  let database: TwinDatabase | undefined;
+  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; }
@@ -25,7 +25,7 @@ export async function servePack(pack: string, options: Record<string, unknown>):
   let stopping: Promise<void> | undefined;
   return {
     ...server,
-    managedDatabaseUrl: async () => { backing.clock(worldNow()); return backing.url; },
+    managedDatabaseUrl: async () => backing.url,
     stop: () => stopping ??= (async () => { await server.stop(); await backing.stop(); })(),
   };
 }

package/src/walk/vendor-fetch.ts

@@ -2,8 +2,8 @@
 // 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 PgliteHost, startPgliteHost } from './walk-database.ts';
-import { type TwinStream, worldNow } from '@volter/world-core/runtime';
+import { 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';
 
@@ -22,19 +22,19 @@ export async function vendorFetch(twinDir: string, vendor: string, dependenciesF
   const name = Object.keys(mod).find((k) => /^create\w+?Fetch$/.test(k) && !/TwinFetch$/.test(k) && typeof mod[k] === 'function');
   if (!name) return undefined;
   const factory = mod[name] as (options: { root: string; database?: string; scenarioPath?: string; application?: ApplicationStandIn }) => ((request: Request) => Response | Promise<Response>) & Record<string, unknown>;
-  if (!(mod.pack as { managedDatabase?: unknown } | undefined)?.managedDatabase) return (root: string, options = {}) => factory({ root, ...options });
-  // A pack whose data plane is the World's managed Postgres is walked over one, as a World binds it: each World (each
-  // root) its own fresh database, started on its first request and stopped when the walk's process ends, its clock the
-  // walked World's (set before each request: the walk moves the World clock between steps).
+  const descriptor = mod.pack as TwinPack | undefined;
+  if (!descriptor?.managedDatabase) return (root: string, options = {}) => factory({ root, ...options });
+  // 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 bare = factory({ root, ...options });
     let bound: Promise<(request: Request) => Response | Promise<Response>> | undefined;
-    let host: PgliteHost | undefined;
-    const bind = () => (bound ??= startPgliteHost().then((started) => { host = started; return factory({ root, database: started.url, ...options }); }));
-    const served = (request: Request) => bind().then((fetch) => { host!.clock(worldNow()); return fetch(request); });
-    // the World's database itself, for what an application sends it over its own wire (a SQL step: journey-kit.ts)
-    const managedDatabaseUrl = () => bind().then(() => { host!.clock(worldNow()); return host!.url; });
-    // the walk's end stops its World's database, so the next World walked declares it at the same port
+    let host: TwinDatabase | undefined;
+    const bind = () => (bound ??= startTwinDatabase(directory, descriptor).then((started) => { host = started; return factory({ root, database: started.url, ...options }); }));
+    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; });
+    // 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 });
   };

package/src/walk/walk-database.ts

@@ -1,106 +1,73 @@
-// The walker's Postgres is a declared, task-owned World. The runtime supervises its lifetime and backing;
-// the walker owns when to use and release it, never the backend's process or data directory.
+// A managed SQL walk selects the pack in a task-owned World. The same private twin
+// engine lifecycle serves both the World and the walker; no infrastructure is assembled here.
 import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
-import { createServer } from 'node:net';
-import { tmpdir } from 'node:os';
 import { createRequire } from 'node:module';
-import { dirname, extname, join } from 'node:path';
-import { worldNow } from '@volter/world-core/runtime';
+import { dirname, join } from 'node:path';
+import type { TwinPack } from '@volter/world-core/runtime';
 
-// The runtime is this package's optional peer: only a walk over a managed database needs it, so it is loaded here, on
-// that walk's first database, and every command that starts none runs with the standard alone installed.
 type Runtime = typeof import('@volter/world-runtime');
-let loaded: Promise<{ runtime: Runtime; infrastructureCli: string }> | undefined;
+let loaded: Promise<Runtime> | undefined;
 const worldRuntime = () => loaded ??= (async () => {
-  let entry: string;
-  try { entry = createRequire(import.meta.url).resolve('@volter/world-runtime'); }
-  catch { throw new Error('A managed database walk needs @volter/world-runtime installed beside @volter/twin-standard: npm i @volter/world-runtime'); }
-  return { runtime: await import('@volter/world-runtime'), infrastructureCli: join(dirname(entry), `infra-cli${extname(entry)}`) };
+  try { createRequire(import.meta.url).resolve('@volter/world-runtime'); }
+  catch { throw new Error('A managed SQL walk needs @volter/world-runtime installed beside @volter/twin-standard'); }
+  return import('@volter/world-runtime');
 })();
 
-async function freePort(): Promise<number> {
-  return new Promise((done, fail) => {
-    const server = createServer();
-    server.once('error', fail);
-    server.listen(0, '127.0.0.1', () => {
-      const port = (server.address() as { port: number }).port;
-      server.close(() => done(port));
-    });
-  });
-}
-
-export type PgliteHost = { url: string; port: number; clock: (at: string) => void; stop: () => Promise<void> };
-
-// Sequential replays declare the same database endpoint. A concurrent walk declares its own port. Only a successful
-// runtime teardown releases this slot; unknown cleanup never licenses reusing its port or deleting its state.
-let declaredPort: number | undefined;
-let declaredHeld = false;
+export type TwinDatabase = { url: string; stop: () => Promise<void> };
 
-export async function startPgliteHost(): Promise<PgliteHost> {
-  if (!process.env.VOLTER_WORLD) throw new Error('A managed database walk requires its enclosing World');
-  const { runtime: { runWorld, setWorldClock, worldConfigDocument }, infrastructureCli } = await worldRuntime();
-  const root = mkdtempSync(join(tmpdir(), 'walk-database-world-'));
-  const name = 'pack-walk-postgres';
-  const port = declaredPort !== undefined && !declaredHeld ? declaredPort : await freePort();
-  declaredPort ??= port;
-  const holdsDeclared = port === declaredPort;
-  if (holdsDeclared) declaredHeld = true;
-  const fake = { user: 'world', database: 'world', password: 'walk-only-fake-password' };
-  const url = `postgresql://${fake.user}:${fake.password}@127.0.0.1:${port}/${fake.database}`;
+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();
+  // 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 };
   const config = join(root, 'world.json');
-  const command = [process.execPath, infrastructureCli];
-  writeFileSync(join(root, 'world.infrastructure.yml'), JSON.stringify({ services: { postgres: {
-    image: 'postgres:18-alpine', ports: [`127.0.0.1:${port}:5432`],
-    environment: { POSTGRES_USER: fake.user, POSTGRES_DB: fake.database, POSTGRES_PASSWORD: fake.password },
-  } } }, null, 2) + '\n');
-  writeFileSync(config, JSON.stringify(worldConfigDocument({ id: name,
-    env: { DATABASE_URL: url, VOLTER_WORLD_INFRA_BACKING: 'pglite' }, network: { egress: [] },
-    services: [{ id: 'infrastructure', type: 'external', controlPlane: true, external: {
-      up: [...command, 'up'], status: [...command, 'status'], down: [...command, 'down'],
-      discover: [{ as: 'DATABASE_URL', jsonPath: 'connections.DATABASE_URL', protocol: 'postgres' }],
-      readyWhen: { command: command[0], args: [...command.slice(1), 'status'], timeoutMs: 120_000, intervalMs: 500 },
-    } }],
+  writeFileSync(config, JSON.stringify(worldConfigDocument({ id: 'pack-walk-sql', stripEnv: ['*'], network: { egress: [] },
+    services: [{ id: descriptor.vendor, type: 'twin', package: manifest.name }],
   }), null, 2) + '\n');
-  setWorldClock(name, root, worldNow());
   const readyFile = join(root, 'ready.json'), releaseFile = join(root, 'release');
-  // This is the registered consumer held by runWorld, not an infrastructure supervisor. It exposes only its own
-  // connection env, and exits when the caller's sequence is done. Caller loss belongs to the runtime's run guardian.
+  // Ask the selected twin's actual product door. The runtime alone allocates and owns its engine.
   const hold = `
-    import { existsSync, renameSync, watch, writeFileSync } from 'node:fs';
+    import { existsSync, readFileSync, renameSync, watch, writeFileSync } from 'node:fs';
     import { dirname } from 'node:path';
-    const [ready, release] = process.argv.slice(1);
-    if (!process.env.VOLTER_WORLD || !process.env.DATABASE_URL) throw new Error('Missing held World connection');
+    const [ready, release, vendor, path, body, field] = process.argv.slice(1);
+    if (!process.env.VOLTER_WORLD_INSTANCE) 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');
+    const response = await fetch(new URL(path, service.url), {method:'POST',headers:{'content-type':'application/json'},body});
+    if (!response.ok) throw new Error('Selected twin SQL credential door refused: ' + response.status);
+    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: process.env.DATABASE_URL }));
+    writeFileSync(ready + '.tmp', JSON.stringify({ url: result[field] }), {mode:0o600});
     renameSync(ready + '.tmp', ready);
     done();`;
   let finished: { result?: Awaited<ReturnType<Runtime['runWorld']>>; error?: unknown; failed: boolean } | undefined;
-  const task = runWorld(config, [process.execPath, '--input-type=module', '-e', hold, readyFile, releaseFile], {
-    root, cwd: root, owner: 'pack-walk-managed-database',
+  const task = runWorld(config, [process.execPath, '--input-type=module', '-e', hold, readyFile, releaseFile,
+    descriptor.vendor, door.path, JSON.stringify(door.body), definition.credentialField], {
+    root, cwd: root, owner: 'pack-walk-twin-private-sql',
   }).then(result => { finished = { result, failed: false }; return result; }, error => {
     finished = { error, failed: true }; throw error;
   });
-  // Startup and normal stop await this promise; keep an early rejection handled while waiting for readiness.
   void task.catch(() => undefined);
   while (!existsSync(readyFile)) {
     if (finished) {
-      if (!finished.failed && holdsDeclared) declaredHeld = false;
       if (finished.failed) throw finished.error;
-      throw new Error(`Managed database World ended before its consumer was ready (exit ${finished.result!.exitCode}); evidence: ${root}`);
+      throw new Error(`Twin SQL World ended before its consumer was ready (exit ${finished.result!.exitCode}); evidence: ${root}`);
     }
     await new Promise(resolve => setTimeout(resolve, 100));
   }
   const ready = JSON.parse(readFileSync(readyFile, 'utf8')) as { url: string };
   let stopping: Promise<void> | undefined;
-  return {
-    url: ready.url, port: Number(new URL(ready.url).port),
-    clock: at => setWorldClock(name, root, at),
+  return { url: ready.url,
     stop: () => stopping ??= (async () => {
       writeFileSync(releaseFile, 'released\n');
       const result = await task;
-      if (result.exitCode !== 0) throw new Error(`Managed database World consumer exited ${result.exitCode}; evidence: ${root}`);
-      if (holdsDeclared) declaredHeld = false;
+      if (result.exitCode !== 0) throw new Error(`Twin SQL World consumer exited ${result.exitCode}; evidence: ${root}`);
     })(),
   };
 }