@volter/world-runtime 3.0.72 → 3.0.73

package/dist/src/infra.js

@@ -128,8 +128,8 @@ export async function runInfrastructure(phase, env, io, signal) {
     //   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite|native — explicit, for tests/operators;
     //   2. a working container runtime — the compose path, byte-identical to before;
     //   3. no container runtime + a definition of postgres and/or mongodb services —
-    //      the containerless backing (pglite-backing.ts: PGlite for postgres, the
-    //      MongoDB's own server for mongodb), announced loudly;
+    //      the containerless backing (the machine's own PostgreSQL where it has one, else PGlite,
+    //      for postgres — containerlessPostgres below; MongoDB's own server for mongodb), announced loudly;
     //   4. otherwise the honest refusal naming what this machine cannot serve.
     async function selectBacking() {
         const forced = env.VOLTER_WORLD_INFRA_BACKING;
@@ -161,6 +161,33 @@ export async function runInfrastructure(phase, env, io, signal) {
         const reason = classify(`${probe.stdout ?? ''}\n${probe.stderr ?? ''}`);
         return reason === 'local execution capacity is unavailable' ? 'pglite' : 'docker';
     }
+    // Without a container runtime a declared PostgreSQL is the machine's own wherever it has one, as MongoDB is its own
+    // mongod (architecture, managed infrastructure): retained data keeps the backing that made it, then an installed
+    // server selects native, then PGlite. A forced backing, several PostgreSQLs or an unservable kind beside it keep
+    // the selection made above.
+    async function containerlessPostgres(selected) {
+        if (selected !== 'pglite' || env.VOLTER_WORLD_INFRA_BACKING === 'pglite')
+            return selected;
+        const { unsupportedKinds } = await import("./pglite-backing.js");
+        const { nativePostgresTools } = await import("./native-postgres-backing.js");
+        const postgres = declared.filter(s => s.kind === 'postgres');
+        if (postgres.length !== 1 || unsupportedKinds(declared.filter(s => s.kind !== 'postgres' && !twinned.includes(s))).length)
+            return selected;
+        const native = existsSync(join(worldData, 'native-postgres-data'));
+        const pglite = existsSync(join(worldData, 'pglite-postgres-data'));
+        if (native && pglite) {
+            // teardown follows the recorded lifecycle, never startup's refusal
+            if (phase === 'down')
+                return existsSync(join(worldData, 'native-postgres.owner.json')) ? 'native' : 'pglite';
+            io.err('managed infrastructure: this World retains both native and PGlite PostgreSQL data; purge it before booting again\n');
+            return 1;
+        }
+        if (native)
+            return 'native';
+        if (pglite)
+            return 'pglite';
+        return nativePostgresTools(env) ? 'native' : 'pglite';
+    }
     async function runPglite() {
         const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import("./pglite-backing.js");
         const services = parseInfraDefinition(readFileSync(definition, 'utf8')).filter((s) => composed === null || composed.includes(s.kind));
@@ -175,6 +202,11 @@ export async function runInfrastructure(phase, env, io, signal) {
         }
         if (phase === 'up') {
             io.out('managed infrastructure backing: containerless (no container runtime)\n');
+            if (services.some((s) => s.kind === 'postgres')) {
+                io.out('managed infrastructure: PostgreSQL is PGlite, one session every connection takes in turn; a read through '
+                    + 'the pool inside a transaction waits on itself until that transaction ends. A postgres server on PATH, or '
+                    + 'VOLTER_WORLD_POSTGRES_BIN, gives a fresh World independent sessions.\n');
+            }
             try {
                 await pgliteUp(services, worldData, launch);
             }
@@ -265,7 +297,7 @@ export async function runInfrastructure(phase, env, io, signal) {
             io.out('managed infrastructure stopped\n');
         return 0;
     }
-    const backing = await selectBacking();
+    const backing = await containerlessPostgres(await selectBacking());
     if (typeof backing === 'number')
         return backing;
     if (backing === 'pglite')

package/dist/src/native-postgres-backing.d.ts

@@ -1,4 +1,9 @@
 import type { HostLaunch, InfraService } from './pglite-backing.js';
+/** The PostgreSQL tool directory this machine offers, or undefined: `VOLTER_WORLD_POSTGRES_BIN` as named, else the
+ *  directory of a `postgres` server on PATH, resolved through its links, holding the server's own tools beside it
+ *  (libpq's client tools on PATH name no server). Read from executable files; nothing is launched or installed
+ *  (architecture, managed infrastructure). */
+export declare function nativePostgresTools(env: NodeJS.ProcessEnv): string | undefined;
 export declare function nativePostgresUp(services: InfraService[], root: string, definition: string, launch: HostLaunch): Promise<void>;
 export declare function nativePostgresStatus(root: string): Promise<boolean>;
 export declare function nativePostgresDown(root: string): Promise<void>;

package/dist/src/native-postgres-backing.js

@@ -1,9 +1,9 @@
 // World-managed multi-session PostgreSQL. The declaration, data, process and teardown
 // belong to the infrastructure service; a recipe never operates postgres itself.
 import { spawn } from 'node:child_process';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { accessSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
 import { connect } from 'node:net';
-import { join, resolve } from 'node:path';
+import { delimiter, dirname, join, resolve } from 'node:path';
 import { commandLifetime, COMMAND_GRACE_MS, CommandRetirementError } from "./command-lifetime.js";
 import { survivingOwnedGroups } from "./process-groups.js";
 import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess } from "./process-receipt.js";
@@ -220,15 +220,41 @@ function settings(definition) {
     }
     return { user, database };
 }
+const TOOLS = ['initdb', 'postgres', 'createdb', 'psql'];
+const executable = (file) => {
+    try {
+        accessSync(file, constants.X_OK);
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+/** The PostgreSQL tool directory this machine offers, or undefined: `VOLTER_WORLD_POSTGRES_BIN` as named, else the
+ *  directory of a `postgres` server on PATH, resolved through its links, holding the server's own tools beside it
+ *  (libpq's client tools on PATH name no server). Read from executable files; nothing is launched or installed
+ *  (architecture, managed infrastructure). */
+export function nativePostgresTools(env) {
+    if (env.VOLTER_WORLD_POSTGRES_BIN)
+        return env.VOLTER_WORLD_POSTGRES_BIN;
+    for (const directory of (env.PATH ?? '').split(delimiter)) {
+        if (!directory || !executable(join(directory, 'postgres')))
+            continue;
+        const tools = dirname(realpathSync(join(directory, 'postgres')));
+        if (TOOLS.every(name => executable(join(tools, name))))
+            return tools;
+    }
+    return undefined;
+}
 export async function nativePostgresUp(services, root, definition, launch) {
     if (services.length !== 1 || services[0].kind !== 'postgres')
         throw new Error('native postgres requires one declared postgres service');
     const deadline = Date.now() + READY_TIMEOUT_MS;
     const env = { ...(launch.env ?? process.env), LC_ALL: launch.env?.LC_ALL || 'C' };
-    const binaries = env.VOLTER_WORLD_POSTGRES_BIN;
+    const binaries = nativePostgresTools(env);
     if (!binaries)
-        throw new Error('native postgres requires VOLTER_WORLD_POSTGRES_BIN (an installed PostgreSQL tool directory)');
-    for (const name of ['initdb', 'postgres', 'createdb', 'psql']) {
+        throw new Error('native postgres requires an installed PostgreSQL: a postgres server on PATH, or VOLTER_WORLD_POSTGRES_BIN naming its tool directory');
+    for (const name of TOOLS) {
         if (!existsSync(join(binaries, name)))
             throw new Error(`native postgres tool is missing: ${join(binaries, name)}`);
     }

package/dist/src/pglite-backing.js

@@ -1,7 +1,8 @@
 // The containerless backing for World-managed infrastructure, instead of docker
 // compose: a POSTGRES service is a PGlite host (see pglite-host.mjs), a MONGODB
-// service is MongoDB's own mongod (mongodb-backing.ts). MongoDB is always native; Postgres is selected
-// when no container runtime is available (or by VOLTER_WORLD_INFRA_BACKING=pglite). The
+// service is MongoDB's own mongod (mongodb-backing.ts). MongoDB is always native; PGlite serves Postgres
+// when no container runtime is available and the machine has no PostgreSQL of its own (infra.ts,
+// containerlessPostgres), or by VOLTER_WORLD_INFRA_BACKING=pglite. The
 // world config, definition file, injected env, and declared-service contract are
 // byte-identical either way — backing is private, exactly as the boundary comment
 // in infra-cli.ts promises. Each service's bytes live under VOLTER_WORLD_DATA, so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.72",
+  "version": "3.0.73",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -69,14 +69,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.72",
-    "@volter/world-console": "3.0.67"
+    "@volter/world-core": "3.0.73",
+    "@volter/world-console": "3.0.68"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.72",
+    "@volter/world-core": "3.0.73",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0",

package/src/infra.ts

@@ -115,8 +115,8 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
   //   1. VOLTER_WORLD_INFRA_BACKING=docker|pglite|native — explicit, for tests/operators;
   //   2. a working container runtime — the compose path, byte-identical to before;
   //   3. no container runtime + a definition of postgres and/or mongodb services —
-  //      the containerless backing (pglite-backing.ts: PGlite for postgres, the
-  //      MongoDB's own server for mongodb), announced loudly;
+  //      the containerless backing (the machine's own PostgreSQL where it has one, else PGlite,
+  //      for postgres — containerlessPostgres below; MongoDB's own server for mongodb), announced loudly;
   //   4. otherwise the honest refusal naming what this machine cannot serve.
   async function selectBacking(): Promise<'docker' | 'pglite' | 'native' | number> {
     const forced = env.VOLTER_WORLD_INFRA_BACKING;
@@ -145,6 +145,29 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     return reason === 'local execution capacity is unavailable' ? 'pglite' : 'docker';
   }
 
+  // Without a container runtime a declared PostgreSQL is the machine's own wherever it has one, as MongoDB is its own
+  // mongod (architecture, managed infrastructure): retained data keeps the backing that made it, then an installed
+  // server selects native, then PGlite. A forced backing, several PostgreSQLs or an unservable kind beside it keep
+  // the selection made above.
+  async function containerlessPostgres(selected: 'docker' | 'pglite' | 'native' | number): Promise<'docker' | 'pglite' | 'native' | number> {
+    if (selected !== 'pglite' || env.VOLTER_WORLD_INFRA_BACKING === 'pglite') return selected;
+    const { unsupportedKinds } = await import('./pglite-backing.ts');
+    const { nativePostgresTools } = await import('./native-postgres-backing.ts');
+    const postgres = declared.filter(s => s.kind === 'postgres');
+    if (postgres.length !== 1 || unsupportedKinds(declared.filter(s => s.kind !== 'postgres' && !twinned.includes(s))).length) return selected;
+    const native = existsSync(join(worldData!, 'native-postgres-data'));
+    const pglite = existsSync(join(worldData!, 'pglite-postgres-data'));
+    if (native && pglite) {
+      // teardown follows the recorded lifecycle, never startup's refusal
+      if (phase === 'down') return existsSync(join(worldData!, 'native-postgres.owner.json')) ? 'native' : 'pglite';
+      io.err('managed infrastructure: this World retains both native and PGlite PostgreSQL data; purge it before booting again\n');
+      return 1;
+    }
+    if (native) return 'native';
+    if (pglite) return 'pglite';
+    return nativePostgresTools(env) ? 'native' : 'pglite';
+  }
+
   async function runPglite(): Promise<number> {
     const { unsupportedKinds, pgliteUp, pgliteStatus, pgliteDown } = await import('./pglite-backing.ts');
     const services = parseInfraDefinition(readFileSync(definition, 'utf8')).filter((s) => composed === null || composed.includes(s.kind));
@@ -159,6 +182,11 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     }
     if (phase === 'up') {
       io.out('managed infrastructure backing: containerless (no container runtime)\n');
+      if (services.some((s) => s.kind === 'postgres')) {
+        io.out('managed infrastructure: PostgreSQL is PGlite, one session every connection takes in turn; a read through '
+          + 'the pool inside a transaction waits on itself until that transaction ends. A postgres server on PATH, or '
+          + 'VOLTER_WORLD_POSTGRES_BIN, gives a fresh World independent sessions.\n');
+      }
       try {
         await pgliteUp(services, worldData!, launch);
       } catch (error) {
@@ -240,7 +268,7 @@ export async function runInfrastructure(phase: string, env: NodeJS.ProcessEnv, i
     return 0;
   }
 
-  const backing = await selectBacking();
+  const backing = await containerlessPostgres(await selectBacking());
   if (typeof backing === 'number') return backing;
   if (backing === 'pglite') return runPglite();
   if (backing === 'native') {

package/src/native-postgres-backing.ts

@@ -1,9 +1,9 @@
 // World-managed multi-session PostgreSQL. The declaration, data, process and teardown
 // belong to the infrastructure service; a recipe never operates postgres itself.
 import { spawn, type ChildProcess } from 'node:child_process';
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { accessSync, closeSync, constants, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from 'node:fs';
 import { connect } from 'node:net';
-import { join, resolve } from 'node:path';
+import { delimiter, dirname, join, resolve } from 'node:path';
 import { commandLifetime, COMMAND_GRACE_MS, CommandRetirementError } from './command-lifetime.ts';
 import { survivingOwnedGroups } from './process-groups.ts';
 import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess, type SpawnIdentity } from './process-receipt.ts';
@@ -181,13 +181,32 @@ function settings(definition: string): { user: string; database: string } {
   return { user, database };
 }
 
+const TOOLS = ['initdb', 'postgres', 'createdb', 'psql'];
+const executable = (file: string): boolean => {
+  try { accessSync(file, constants.X_OK); return statSync(file).isFile(); } catch { return false; }
+};
+
+/** The PostgreSQL tool directory this machine offers, or undefined: `VOLTER_WORLD_POSTGRES_BIN` as named, else the
+ *  directory of a `postgres` server on PATH, resolved through its links, holding the server's own tools beside it
+ *  (libpq's client tools on PATH name no server). Read from executable files; nothing is launched or installed
+ *  (architecture, managed infrastructure). */
+export function nativePostgresTools(env: NodeJS.ProcessEnv): string | undefined {
+  if (env.VOLTER_WORLD_POSTGRES_BIN) return env.VOLTER_WORLD_POSTGRES_BIN;
+  for (const directory of (env.PATH ?? '').split(delimiter)) {
+    if (!directory || !executable(join(directory, 'postgres'))) continue;
+    const tools = dirname(realpathSync(join(directory, 'postgres')));
+    if (TOOLS.every(name => executable(join(tools, name)))) return tools;
+  }
+  return undefined;
+}
+
 export async function nativePostgresUp(services: InfraService[], root: string, definition: string, launch: HostLaunch): Promise<void> {
   if (services.length !== 1 || services[0]!.kind !== 'postgres') throw new Error('native postgres requires one declared postgres service');
   const deadline = Date.now() + READY_TIMEOUT_MS;
   const env: NodeJS.ProcessEnv = { ...(launch.env ?? process.env), LC_ALL: launch.env?.LC_ALL || 'C' };
-  const binaries = env.VOLTER_WORLD_POSTGRES_BIN;
-  if (!binaries) throw new Error('native postgres requires VOLTER_WORLD_POSTGRES_BIN (an installed PostgreSQL tool directory)');
-  for (const name of ['initdb', 'postgres', 'createdb', 'psql']) {
+  const binaries = nativePostgresTools(env);
+  if (!binaries) throw new Error('native postgres requires an installed PostgreSQL: a postgres server on PATH, or VOLTER_WORLD_POSTGRES_BIN naming its tool directory');
+  for (const name of TOOLS) {
     if (!existsSync(join(binaries, name))) throw new Error(`native postgres tool is missing: ${join(binaries, name)}`);
   }
   const previous = ownership(root);

package/src/pglite-backing.ts

@@ -1,7 +1,8 @@
 // The containerless backing for World-managed infrastructure, instead of docker
 // compose: a POSTGRES service is a PGlite host (see pglite-host.mjs), a MONGODB
-// service is MongoDB's own mongod (mongodb-backing.ts). MongoDB is always native; Postgres is selected
-// when no container runtime is available (or by VOLTER_WORLD_INFRA_BACKING=pglite). The
+// service is MongoDB's own mongod (mongodb-backing.ts). MongoDB is always native; PGlite serves Postgres
+// when no container runtime is available and the machine has no PostgreSQL of its own (infra.ts,
+// containerlessPostgres), or by VOLTER_WORLD_INFRA_BACKING=pglite. The
 // world config, definition file, injected env, and declared-service contract are
 // byte-identical either way — backing is private, exactly as the boundary comment
 // in infra-cli.ts promises. Each service's bytes live under VOLTER_WORLD_DATA, so