@volter/twin-standard 1.0.154 → 1.0.155

package/dist/src/create-pack.js

@@ -371,7 +371,7 @@ export function cliFile(vendor, live = false) {
     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`. */
 const pascal = (vendor) => vendor.split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
@@ -421,7 +421,6 @@ Contributor mechanics belong to the [pack procedure](https://world-docs.volter.a
 }
 export function initFiles(vendor) {
     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',
@@ -454,8 +453,6 @@ export function initFiles(vendor) {
  *  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, lanes) {
-    const Name = pascal(vendor);
-    const camel = (s) => { const p = pascal(s); return `${p[0].toLowerCase()}${p.slice(1)}`; };
     const single = initFiles(vendor);
     const files = {
         'package.json': single['package.json'].replace('"spec",', lanes.map((l) => `"${l}",`).join('\n    ')),

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

@@ -1,3 +1,4 @@
+import { type TwinPack } from '@volter/world-core/runtime';
 export type PackFacts = {
     /** Explicit vendor-server backing; this entry declares no pack protocol or factory. */
     serverBacking?: {
@@ -62,11 +63,7 @@ export type PackFacts = {
     };
     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?: {
@@ -88,10 +85,14 @@ export type PackFacts = {
             paths: string[];
         };
     };
-    /** The World's managed database the runtime binds the twin to (see TwinPack.managedDatabase). */
+    /** 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). */

package/dist/src/pack-facts.js

@@ -175,9 +175,16 @@ export async function compilePackFacts(dirs) {
         if (pack.managedDatabase !== undefined) {
             const md = pack.managedDatabase;
             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`);
+                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'])
+                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/dist/src/walk/journey-kit.d.ts

@@ -367,8 +367,8 @@ export type WaitStep = {
     wait: string;
 };
 export declare const isWait: (step: Step) => step is WaitStep;
-/** 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/dist/src/walk/serve-pack.d.ts

@@ -4,4 +4,7 @@ export type ServedPack = {
     stop: () => void | Promise<void>;
     managedDatabaseUrl?: () => Promise<string>;
 };
-export declare function servePack(pack: string, options: Record<string, unknown>): Promise<ServedPack>;
+export declare function servePack(pack: string, options: {
+    root?: string;
+    scenarioPath?: string;
+}): Promise<ServedPack>;

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

@@ -8,8 +8,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 };
 // 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 } from "./walk-database.js";
+import { startTwinDatabase } from "./walk-database.js";
 export async function servePack(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];
@@ -17,8 +16,8 @@ export async function servePack(pack, options) {
         throw new Error('src/server.ts exports no create<Vendor>TwinServer');
     const descriptor = (await import(__rewriteRelativeImportExtension(join(pack, 'src', 'index.ts')))).pack;
     let database;
-    if (descriptor?.managedDatabase?.kind === 'postgres' && options.database === undefined)
-        database = await startPgliteHost();
+    if (descriptor?.managedDatabase?.kind === 'postgres')
+        database = await startTwinDatabase(pack, descriptor);
     let server;
     try {
         server = await create({ port: 0, ...options, ...(database ? { database: database.url } : {}) });
@@ -33,7 +32,7 @@ export async function servePack(pack, options) {
     let stopping;
     return {
         ...server,
-        managedDatabaseUrl: async () => { backing.clock(worldNow()); return backing.url; },
+        managedDatabaseUrl: async () => backing.url,
         stop: () => stopping ??= (async () => { await server.stop(); await backing.stop(); })(),
     };
 }

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

@@ -10,8 +10,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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 { startPgliteHost } from "./walk-database.js";
-import { worldNow } from '@volter/world-core/runtime';
+import { startTwinDatabase } from "./walk-database.js";
 import { walkPackDirectory } from "./pack-directory.js";
 export async function vendorFetch(twinDir, vendor, dependenciesFrom = twinDir) {
     const directory = walkPackDirectory(twinDir, vendor, dependenciesFrom);
@@ -29,20 +28,20 @@ export async function vendorFetch(twinDir, vendor, dependenciesFrom = twinDir) {
     if (!name)
         return undefined;
     const factory = mod[name];
-    if (!mod.pack?.managedDatabase)
+    const descriptor = mod.pack;
+    if (!descriptor?.managedDatabase)
         return (root, 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).
+    // 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 bare = factory({ root, ...options });
         let bound;
         let host;
-        const bind = () => (bound ??= startPgliteHost().then((started) => { host = started; return factory({ root, database: started.url, ...options }); }));
-        const served = (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
+        const bind = () => (bound ??= startTwinDatabase(directory, descriptor).then((started) => { host = started; return factory({ root, database: started.url, ...options }); }));
+        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; });
+        // 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/dist/src/walk/walk-database.d.ts

@@ -1,7 +1,6 @@
-export type PgliteHost = {
+import type { TwinPack } from '@volter/world-core/runtime';
+export type TwinDatabase = {
     url: string;
-    port: number;
-    clock: (at: string) => void;
     stop: () => Promise<void>;
 };
-export declare function startPgliteHost(): Promise<PgliteHost>;
+export declare function startTwinDatabase(pack: string, descriptor: TwinPack): Promise<TwinDatabase>;

package/dist/src/walk/walk-database.js

@@ -1,108 +1,76 @@
-// 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';
 let loaded;
 const worldRuntime = () => loaded ??= (async () => {
-    let entry;
     try {
-        entry = createRequire(import.meta.url).resolve('@volter/world-runtime');
+        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');
+        throw new Error('A managed SQL walk needs @volter/world-runtime installed beside @volter/twin-standard');
     }
-    return { runtime: await import('@volter/world-runtime'), infrastructureCli: join(dirname(entry), `infra-cli${extname(entry)}`) };
+    return import('@volter/world-runtime');
 })();
-async function freePort() {
-    return new Promise((done, fail) => {
-        const server = createServer();
-        server.once('error', fail);
-        server.listen(0, '127.0.0.1', () => {
-            const port = server.address().port;
-            server.close(() => done(port));
-        });
-    });
-}
-// 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;
-let declaredHeld = false;
-export async function startPgliteHost() {
+export async function startTwinDatabase(pack, descriptor) {
     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}`;
+        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'));
     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;
-    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'));
     let stopping;
-    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;
+                throw new Error(`Twin SQL World consumer exited ${result.exitCode}; evidence: ${root}`);
         })(),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.154",
+  "version": "1.0.155",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -76,7 +76,7 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.161",
+    "@volter/world-core": "3.0.163",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

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/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/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}`);
     })(),
   };
 }