@volter/world-runtime 3.0.162 → 3.0.164

package/src/pglite-backing.ts

@@ -16,73 +16,20 @@ import { appendFileSync, closeSync, copyFileSync, cpSync, existsSync, lstatSync,
 import { createHash, randomUUID } from 'node:crypto';
 import { assertWorldConfig, type WorldDatabasePrepare } from './schema.ts';
 import { connect } from 'node:net';
-import { dirname, join } from 'node:path';
+import { delimiter, dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { spawn, type ChildProcess } from 'node:child_process';
-import { commandLifetime, COMMAND_GRACE_MS, COMMAND_CONFIRM_MS } from './command-lifetime.ts';
-import { survivingOwnedGroups } from './process-groups.ts';
+import { commandLifetime, COMMAND_CONFIRM_MS } from './command-lifetime.ts';
+import { survivingOwnedGroups, worldEvent } from './process-groups.ts';
 import { publishProcessReceipt, readProcessReceipt, readSpawnReceipt, spawnReceiptPath, verifySpawnIdentity, signalOwnedProcess, type SpawnIdentity } from './process-receipt.ts';
 import { errorMessage } from './error-message.ts';
 import { runtimeManifest } from './package-manifest.ts';
 import { fileURLToPath } from 'node:url';
-import { parse } from 'yaml';
 import { mongodbArgv, mongodbReady, mongodbServes } from './mongodb-backing.ts';
 
-export interface InfraService { kind: string; hostPort: number; replicaSet?: string; postgres?: { user: string; database: string; password?: string } }
-
-/** Read the generated definition's loopback port mappings. MongoDB may explicitly request
- *  one replica-set member through its Compose-compatible command; other mongod options are refused. */
-export function parseInfraDefinition(text: string): InfraService[] {
-  const definition = parse(text);
-  const services: InfraService[] = [];
-  for (const [kind, value] of Object.entries(definition?.services ?? {})) {
-    const declared = value as { ports?: unknown[]; command?: unknown; environment?: Record<string, unknown> };
-    let replicaSet: string | undefined;
-    if (kind === 'mongodb' && declared.command !== undefined) {
-      const command = declared.command;
-      if (!Array.isArray(command) || command.length !== 3 || command[0] !== 'mongod' || command[1] !== '--replSet'
-        || typeof command[2] !== 'string' || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(command[2])) {
-        throw new Error('World-managed MongoDB command must be ["mongod", "--replSet", "<name>"] or absent for standalone');
-      }
-      replicaSet = command[2];
-    }
-    const ports = (declared.ports ?? []).flatMap((port) => {
-      const match = typeof port === 'string' ? port.match(/^127\.0\.0\.1:(\d+):\d+$/) : null;
-      return match ? [Number(match[1])] : [];
-    });
-    if (ports.length !== 1) throw new Error(`managed infrastructure ${kind} needs exactly one declared loopback port`);
-    let postgres: InfraService['postgres'];
-    if (kind === 'postgres') {
-      const environment = declared.environment ?? {};
-      const user = environment.POSTGRES_USER ?? 'postgres';
-      const database = environment.POSTGRES_DB ?? user;
-      const password = environment.POSTGRES_PASSWORD;
-      if ([user, database, password].some(value => value !== undefined && (typeof value !== 'string' || !value || /[\r\n\0]|\$\{/.test(value)))) {
-        throw new Error('World-managed PGlite requires literal POSTGRES_USER, POSTGRES_DB and POSTGRES_PASSWORD');
-      }
-      if ([user, database].some(value => Buffer.byteLength(value as string, 'utf8') > 63)) throw new Error('World-managed PGlite identifiers must fit PostgreSQL\'s 63-byte name limit');
-      postgres = { user: user as string, database: database as string, ...(password !== undefined ? { password: password as string } : {}) };
-    }
-    services.push({ kind, hostPort: ports[0]!, ...(replicaSet ? { replicaSet } : {}), ...(postgres ? { postgres } : {}) });
-  }
-  return services;
-}
-
-/** Endpoints of the declared infrastructure, published through external.discover. Only URLs
- * whose protocol and loopback port match a declared service belong to this lifecycle. */
-export function infraConnections(services: InfraService[], env: Record<string, string | undefined>): Record<string, string> {
-  const connections: Record<string, string> = {};
-  for (const [name, value] of Object.entries(env)) {
-    if (value === undefined) continue;
-    try {
-      const url = new URL(value);
-      if (url.hostname !== '127.0.0.1') continue;
-      const kind = url.protocol === 'postgresql:' ? 'postgres' : url.protocol.slice(0, -1);
-      if (services.some((service) => service.kind === kind && service.hostPort === Number(url.port))) connections[name] = value;
-    } catch { /* not an infrastructure endpoint */ }
-  }
-  return connections;
-}
+import type { InfraService } from './infra-definition.ts';
+export { parseInfraDefinition, infraConnections } from './infra-definition.ts';
+export type { InfraService } from './infra-definition.ts';
 
 // this module's directory under Node as under Bun: `volter-world-infra` is a node-shebang bin, where
 // `import.meta.dir` (Bun's) is undefined
@@ -127,7 +74,9 @@ function hostOwnership(pidFile: string) {
  *  the control plane's NODE_OPTIONS and proxies), and the boot's abort. The `volter-world-infra` process passes
  *  nothing and its hosts inherit its own environment, which is that same service environment. The World's `up`,
  *  running the up phase in its own process, passes it: its own process.env is the operator's, not the service's. */
-export interface HostLaunch { env?: NodeJS.ProcessEnv; signal?: AbortSignal; note?: (what: string) => void }
+export interface HostLaunch { env?: NodeJS.ProcessEnv; signal?: AbortSignal; note?: (what: string) => void;
+  /** Said once the database's cluster is chosen, placed and its server spawned, before its readiness is waited on (S2 R79). */
+  onPlaced?: () => void }
 
 /** The argv that serves one service on its declared loopback port, with its bytes in `serviceData`. */
 function hostArgv(service: InfraService, serviceData: string): string[] {
@@ -168,13 +117,14 @@ function listeningReceiptPath(pidFile: string): string {
   return pidFile.replace(/\.pid$/, '.listening.json');
 }
 
-function listeningReceipt(path: string): { pid: number; port: number; boot: string | null } | undefined {
+function listeningReceipt(path: string): { pid: number; port: number; boot: string | null; openSplit?: string } | undefined {
   let text: string;
   try { text = readFileSync(path, 'utf8'); } catch { return undefined; }
   try {
-    const value = JSON.parse(text) as { version?: unknown; pid?: unknown; port?: unknown; boot?: unknown };
+    const value = JSON.parse(text) as { version?: unknown; pid?: unknown; port?: unknown; boot?: unknown; openSplit?: unknown };
     if (value.version !== 1 || !Number.isSafeInteger(value.pid) || !Number.isSafeInteger(value.port)) return undefined;
-    return { pid: value.pid as number, port: value.port as number, boot: typeof value.boot === 'string' ? value.boot : null };
+    return { pid: value.pid as number, port: value.port as number, boot: typeof value.boot === 'string' ? value.boot : null,
+      ...(typeof value.openSplit === 'string' ? { openSplit: value.openSplit } : {}) };
   } catch { return undefined; }
 }
 
@@ -223,8 +173,92 @@ export function preparedCluster(worldConfig: string): { directory: string; stamp
  * another password takes the same cluster and authenticates against its own. Extensions are loaded into the module
  * at each open, never created in the cluster by the open path.
  */
+/**
+ * A managed store other than the cluster that a step run with the World up may have written (architecture, "A step
+ * may need the World"): where the preparation stages it, beside the cluster, and its stamp.
+ */
+export function preparedStore(worldConfig: string, name: string): { directory: string; stamp: string } {
+  const directory = join(dirname(worldConfig), PREPARED_DIRECTORY, name);
+  return { directory, stamp: `${directory}.json` };
+}
+
+const canonical = (value: unknown): string => JSON.stringify(value, (_key, item) => item && typeof item === 'object' && !Array.isArray(item)
+  ? Object.fromEntries(Object.entries(item as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b))) : item);
+
+/** The state directory a preparation with the World up runs in, beside the World's own (native-postgres-backing.ts). */
+export const PREPARE_STATE_DIRECTORY = '.volter-prepare';
+
+/** The stamp of a staged store: the migration it was written by. */
+export function preparedStoreStamp(migration: PreparedMigration): string {
+  return `${canonical({ migration })}\n`;
+}
+
+/**
+ * Place a staged store where its service serves from, at `up`: only into a place that holds nothing, and only when
+ * its stamp is the migration this World expects (the rule a prepared cluster is taken by). Anything else leaves the
+ * service to start empty, and the note says why.
+ */
+export function takePreparedStore(worldConfig: string | undefined, env: NodeJS.ProcessEnv, name: string, target: string): { placed: boolean; note?: string } {
+  if (!worldConfig) return { placed: false };
+  const { directory, stamp } = preparedStore(worldConfig, name);
+  if (!existsSync(directory) || !existsSync(stamp)) return { placed: false };
+  if (existsSync(target) && readdirSync(target).length) return { placed: false };
+  const wanted = expectedMigration(worldConfig, env, directory);
+  if ('note' in wanted) return { placed: false, note: wanted.note.replace('prepared cluster', `prepared ${name}`) };
+  if (!wanted.migration || readFileSync(stamp, 'utf8') !== preparedStoreStamp(wanted.migration)) return { placed: false, note: `prepared ${name} ${directory} not taken: its stamp names another migration` };
+  // A STORE GOES WITH ITS CLUSTER. Placed beside a database that does not carry the same migration, the World would
+  // have an unprepared database and a prepared store, and an application told to run the step itself would run it
+  // on a store that already holds what the step wrote. On `up` the twin-served kinds come up after the native
+  // backing's onPlaced (cluster placed) or after the database (infra.ts), so the live cluster is there to be read
+  // and must carry the migration. Where no cluster is live
+  // (a caller that starts a twin alone), a prepared cluster stamped with it must at least be waiting.
+  const data = dirname(target), prepared = join(dirname(worldConfig), PREPARED_DIRECTORY);
+  const clusters = [...new Set(['native-postgres-data', containerlessDataDirectory('postgres')!])];
+  const live = clusters.map((cluster) => join(data, cluster)).filter((cluster) => existsSync(join(cluster, 'PG_VERSION')));
+  const carried = live.length > 0
+    ? live.some((cluster) => liveDatabaseMigration(worldConfig, env, cluster) !== undefined)
+    : clusters.map((cluster) => join(prepared, cluster)).some((cluster) => {
+      if (!existsSync(join(cluster, 'PG_VERSION')) || !existsSync(`${cluster}.json`)) return false;
+      try { return canonical((JSON.parse(readFileSync(`${cluster}.json`, 'utf8')) as { migration?: unknown }).migration ?? null) === canonical(wanted.migration); }
+      catch { return false; }
+    });
+  if (!carried) return { placed: false, note: `prepared ${name} ${directory} not taken: ${live.length > 0 ? 'the live database does not carry its migration' : 'no prepared cluster of its migration is there to be taken with it'}` };
+  if (existsSync(target)) rmdirSync(target);
+  mkdirSync(dirname(target), { recursive: true });
+  try { renameSync(directory, target); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error;
+    cpSync(directory, target, { recursive: true });
+  }
+  // THE STORE IS READ UNDER THE NAME THIS UP USES. A twin keeps its state inside its root under the state directory's
+  // name; the preparation ran with its own (PREPARE_STATE_DIRECTORY) and this `up` runs with another, so the root as
+  // it was written is read by nobody. The one the preparation wrote under is renamed to the one the twin is about to
+  // be given, and the note says both, or says that nothing was there to rename.
+  const wrote = join(target, PREPARE_STATE_DIRECTORY), reads = join(target, env.VOLTER_STATE_DIR || '.volter');
+  let under = `nothing in it is under ${PREPARE_STATE_DIRECTORY}`;
+  if (existsSync(wrote) && wrote !== reads) {
+    if (existsSync(reads)) return { placed: true, note: `prepared ${name} ${directory} placed at ${target}, and its ${PREPARE_STATE_DIRECTORY} NOT renamed: ${reads} is there already; the service reads that one` };
+    renameSync(wrote, reads);
+    under = `what the preparation wrote under ${PREPARE_STATE_DIRECTORY} is now under ${env.VOLTER_STATE_DIR || '.volter'}, where this up's service reads`;
+  }
+  return { placed: true, note: `prepared ${name} ${directory} placed at ${target}; ${under}` };
+}
+
 /** A prepared cluster's migration, as its stamp records it: the step's command and the digest of each of its inputs. */
-export interface PreparedMigration { command: string[]; inputs: Record<string, string> }
+/** What a prepared cluster was migrated by: the step's command, its inputs' digests and, for a step run with the
+ *  World up (`with: "world"`), the twins that were up for it, each by its version. */
+export interface PreparedMigration { command: string[]; inputs: Record<string, string>; world?: Record<string, string> }
+
+/**
+ * The twins a step declared `with: "world"` runs beside, each by the version the World names: part of what the
+ * cluster was migrated with, so a World whose twins moved does not take a cluster another set of them wrote into.
+ * Read from the document itself, in id order.
+ */
+export function preparedWorldServices(worldConfig: string): Record<string, string> {
+  const document = JSON.parse(readFileSync(worldConfig, 'utf8')) as { services?: Array<{ id?: unknown; type?: unknown; source?: { version?: unknown } }> };
+  const twins = (document.services ?? []).filter((service) => service.type === 'twin' && typeof service.id === 'string');
+  return Object.fromEntries(twins.map((service) => [service.id as string, typeof service.source?.version === 'string' ? service.source.version : 'unversioned'] as const).sort(([a], [b]) => a.localeCompare(b)));
+}
 
 function preparedStamp(service: InfraService, migration?: PreparedMigration): string {
   const manifest = runtimeManifest();
@@ -234,6 +268,18 @@ function preparedStamp(service: InfraService, migration?: PreparedMigration): st
     ...(migration ? { migration } : {}) })}\n`;
 }
 
+const declaredDatabaseReceipt = (serviceData: string): string => join(serviceData, '.volter-declared-database.json');
+
+/** This cluster served the declared database and role; this is not a migration or process-ownership receipt. */
+function hasDeclaredDatabase(serviceData: string, identity: string): boolean {
+  if (!existsSync(join(serviceData, 'PG_VERSION'))) return false;
+  try { return readFileSync(declaredDatabaseReceipt(serviceData), 'utf8') === identity; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
 /**
  * The SHA-256 of each of a migration step's inputs, under its cwd in the app's tree: a file's bytes; a directory's
  * sorted relative paths, each with its type, its mode and its bytes (a link, its target). What the image build records
@@ -266,7 +312,7 @@ export function databasePrepareOf(worldConfig: string): WorldDatabasePrepare | u
 }
 
 /** `NAME=value` lines (an image's environment, VOLTER_WORLD_APP_ENV), as an environment. */
-function environmentFile(path: string): Record<string, string> {
+export function environmentFile(path: string): Record<string, string> {
   const values: Record<string, string> = {};
   for (const line of readFileSync(path, 'utf8').split('\n')) {
     const at = line.indexOf('=');
@@ -301,6 +347,17 @@ export function keepFailureEvidence(name: string, evidence: string | { file: str
   }
 }
 
+/** A package script's own path: each `node_modules/.bin` from the working directory up to the application's root. */
+export function packageScriptPath(cwd: string, appRoot: string): string[] {
+  const found: string[] = [];
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    const bin = join(dir, 'node_modules', '.bin');
+    if (existsSync(bin)) found.push(bin);
+    if (dir === appRoot || dirname(dir) === dir || !dir.startsWith(appRoot)) break;
+  }
+  return found;
+}
+
 export async function runDatabasePrepare(step: WorldDatabasePrepare, worldConfig: string, launch: HostLaunch): Promise<PreparedMigration> {
   const env = launch.env ?? process.env;
   const appRoot = env.VOLTER_WORLD_APP_ROOT;
@@ -310,12 +367,26 @@ export async function runDatabasePrepare(step: WorldDatabasePrepare, worldConfig
   const { PATH: _imagePath, ...imageValues } = imageEnv;
   const worldValues = assertWorldConfig(JSON.parse(readFileSync(worldConfig, 'utf8')), worldConfig).env ?? {};
   const [program, ...words] = step.command;
-  const migration = spawn(program!, words, { windowsHide: true, cwd, env: { ...env, ...imageValues, ...worldValues }, stdio: ['ignore', 'pipe', 'pipe'] });
+  // THE STEP'S PROGRAM IS FOUND WHERE THE APPLICATION'S OWN START FINDS IT. A start written `yarn prisma:deploy`
+  // runs `prisma migrate deploy` with the package manager's path: each `node_modules/.bin` from the working
+  // directory up to the application's root, before PATH. The step is that script's command, so it is given that
+  // path; declared as a bare `prisma` and looked for on this process's PATH alone, it was not found, and a spawn
+  // that never started was reported as "exited null" with nothing else (linkwarden).
+  const scriptPath = packageScriptPath(cwd, appRoot);
+  const stepEnv: NodeJS.ProcessEnv = { ...env, ...imageValues, ...worldValues };
+  stepEnv.PATH = [...scriptPath, stepEnv.PATH ?? ''].filter(Boolean).join(delimiter);
+  const migration = spawn(program!, words, { windowsHide: true, cwd, env: stepEnv, stdio: ['ignore', 'pipe', 'pipe'] });
   let output = '';
+  // A spawn that fails has no exit: what it met is kept and said, with where the program was looked for.
+  let notStarted: NodeJS.ErrnoException | undefined;
+  migration.once('error', (error: NodeJS.ErrnoException) => { notStarted = error; });
   migration.stdout!.on('data', (chunk: Buffer) => { output += chunk.toString('utf8'); });
   migration.stderr!.on('data', (chunk: Buffer) => { output += chunk.toString('utf8'); });
-  const { code } = await commandLifetime(migration, launch.signal).finish();
-  if (code !== 0) throw new Error(`the World's database prepare step (${step.command.join(' ')}) exited ${code ?? 'null'}\n${output.trim().split('\n').slice(-40).join('\n')}${keepFailureEvidence('database-prepare-step-output', output, env)}`);
+  const { code, signal: endedBy } = await commandLifetime(migration, launch.signal).finish();
+  if (notStarted) {
+    throw new Error(`the World's database prepare step (${step.command.join(' ')}) was NOT STARTED: ${notStarted.code ?? ''} ${notStarted.message}. Its program is ${program}; its working directory ${cwd} ${existsSync(cwd) ? 'is there' : 'IS NOT THERE (a missing directory is reported by the system as the program not found)'}; it was looked for in ${scriptPath.length ? scriptPath.join(', ') : 'no node_modules/.bin between that directory and the application\'s root'}, then on PATH (${(env.PATH ?? '').split(delimiter).filter(Boolean).length} entries)`);
+  }
+  if (code !== 0) throw new Error(`the World's database prepare step (${step.command.join(' ')}) ${code === null ? `was ended by ${endedBy ?? 'no exit status and no signal'}` : `exited ${code}`}\n${output.trim().split('\n').slice(-40).join('\n')}${keepFailureEvidence('database-prepare-step-output', output, env)}`);
   launch.note?.(`database prepare step: ${step.command.join(' ')}\n${output.trim()}`);
   return { command: [...step.command], inputs: migrationInputDigests(cwd, step.inputs) };
 }
@@ -329,14 +400,16 @@ async function migratePreparedCluster(service: InfraService, directory: string,
   const pidFile = join(dirname(directory), 'pglite-prepare.pid');
   const boot = randomUUID();
   rmSync(listeningReceiptPath(pidFile), { force: true });
-  const [command, ...args] = [...hostArgv(service, directory), '--prepared', '--listening-file', listeningReceiptPath(pidFile), '--boot', boot];
+  // --record-extensions: the step's host writes the extensions the migrations left beside the cluster, which a prepared
+  // open then loads alone (pglite-host.mjs DECLARED_EXTENSIONS, S2 R66b).
+  const [command, ...args] = [...hostArgv(service, directory), '--prepared', '--record-extensions', '--listening-file', listeningReceiptPath(pidFile), '--boot', boot];
   let hostOutput = '';
   const host = spawn(command!, args, { windowsHide: true,
     env: { ...env, VOLTER_WORLD_PGLITE_USER: service.postgres!.user, VOLTER_WORLD_PGLITE_DATABASE: service.postgres!.database, VOLTER_WORLD_PGLITE_PASSWORD: service.postgres!.password! },
     stdio: ['ignore', 'pipe', 'pipe'] });
   host.stdout!.on('data', (chunk: Buffer) => { hostOutput += chunk.toString('utf8'); });
   host.stderr!.on('data', (chunk: Buffer) => { hostOutput += chunk.toString('utf8'); });
-  const hostLifetime = commandLifetime(host, launch.signal);
+  const hostLifetime = commandLifetime(host, launch.signal, false, READY_TIMEOUT_MS);
   try {
     const deadline = Date.now() + READY_TIMEOUT_MS;
     while (!(host.pid && alive(host.pid) && await hostServes(service, pidFile, host.pid, boot))) {
@@ -379,6 +452,10 @@ export async function pglitePrepare(service: InfraService, worldConfig: string,
   // The app's own migration, where the World declares one: a cluster it did not complete is never stamped.
   const step = databasePrepareOf(worldConfig);
   let migration: PreparedMigration | undefined;
+  if (step?.with === 'world') {
+    rmSync(directory, { recursive: true, force: true });
+    throw new Error('the World\'s database prepare step is declared with: "world", which is prepared on the native PostgreSQL backing only; this preparation is on PGlite (no PostgreSQL programs on PATH or in VOLTER_WORLD_POSTGRES_BIN, or VOLTER_WORLD_INFRA_BACKING=pglite)');
+  }
   if (step) {
     try { migration = await migratePreparedCluster(service, directory, step, worldConfig, launch); }
     catch (error) { rmSync(directory, { recursive: true, force: true }); throw error; }
@@ -418,7 +495,8 @@ export function expectedMigration(worldConfig: string, env: NodeJS.ProcessEnv, d
     inputs = recorded as Record<string, string>;
   } else if (env.VOLTER_WORLD_APP_ROOT) inputs = migrationInputDigests(join(env.VOLTER_WORLD_APP_ROOT, step.cwd), step.inputs);
   if (!inputs) return { note: `prepared cluster ${directory} not taken: it is migrated, and neither the app's recorded digests nor its tree were given to compare (VOLTER_WORLD_APP_DIGESTS, VOLTER_WORLD_APP_ROOT)` };
-  return { migration: { command: [...step.command], inputs: Object.fromEntries(step.inputs.map((input) => [input, inputs![input] ?? ''])) } };
+  return { migration: { command: [...step.command], inputs: Object.fromEntries(step.inputs.map((input) => [input, inputs![input] ?? ''])),
+    ...(step.with === 'world' ? { world: preparedWorldServices(worldConfig) } : {}) } };
 }
 
 /** Beside a service's data: the migration its live cluster carries, written when a migrated cluster is placed. */
@@ -470,7 +548,7 @@ export const DEVELOPMENT_MIGRATION_NOTICE = 'development World: its database mig
  * it becomes (liveDatabaseMigration).
  */
 export function takePreparedCluster(prepared: { directory: string; stamp: string }, expected: string | ((stamp: string) => boolean), serviceData: string,
-  mismatch: string, migration?: PreparedMigration): { placed: boolean; note?: string } {
+  mismatch: string, migration?: PreparedMigration, copy: (from: string, to: string) => void = (from, to) => cpSync(from, to, { recursive: true })): { placed: boolean; copied?: boolean; note?: string } {
   const { directory, stamp } = prepared;
   if (existsSync(join(serviceData, 'PG_VERSION'))) return { placed: false };
   if (!existsSync(join(directory, 'PG_VERSION')) || !existsSync(stamp)) return { placed: false };
@@ -482,13 +560,22 @@ export function takePreparedCluster(prepared: { directory: string; stamp: string
   }
   mkdirSync(dirname(serviceData), { recursive: true });
   // A rename moves the cluster without writing its files; across file systems it is copied.
+  // A caller may copy its own way (the native backing copies as the server's owner, so its cluster is walked once).
+  let copied = false;
   try { renameSync(directory, serviceData); }
   catch (error) {
     if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error;
-    cpSync(directory, serviceData, { recursive: true });
+    // Copied beside its place and moved in whole: a copy cut short (ENOSPC, a crash) never leaves a part of a cluster
+    // where the next up would refuse it, or, holding PG_VERSION, take it as placed and boot it truncated. A sibling an
+    // earlier start left behind is removed first.
+    const placing = `${serviceData}.placing`;
+    rmSync(placing, { recursive: true, force: true });
+    try { copy(directory, placing); renameSync(placing, serviceData); }
+    catch (failure) { rmSync(placing, { recursive: true, force: true }); throw failure; }
+    copied = true;
   }
   if (migration) writeFileSync(migrationRecord(serviceData), `${JSON.stringify(migration)}\n`);
-  return { placed: true, note: `prepared cluster ${directory} placed at ${serviceData}` };
+  return { placed: true, copied, note: `prepared cluster ${directory} placed at ${serviceData}${copied ? ' (copied: another file system)' : ''}` };
 }
 
 export async function pgliteUp(services: InfraService[], dataDir: string, launch: HostLaunch = {}): Promise<void> {
@@ -521,10 +608,24 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
       mkdirSync(serviceData, { recursive: true });
       mkdirSync(dirname(log), { recursive: true });
       if (placed.note) { appendFileSync(log, `${placed.note}\n`); launch.note?.(placed.note); }
+      const identity = service.kind === 'postgres' ? preparedStamp(service) : undefined;
+      const keptIdentity = identity !== undefined && hasDeclaredDatabase(serviceData, identity);
+      const direct = service.kind === 'postgres' && (placed.placed || keptIdentity);
+      if (identity !== undefined) {
+        // Maintenance may rename a legacy database. Its old identity must not survive a partial initialization.
+        if (!direct) rmSync(declaredDatabaseReceipt(serviceData), { force: true });
+        const note = `${name} opening ${direct ? 'declared database directly' : 'template1 for database identity setup'} (${placed.placed ? 'placed prepared identity' : keptIdentity ? 'kept declared identity' : 'identity not established'})`;
+        appendFileSync(log, `${note}\n`); launch.note?.(note);
+      }
       // This boot's token, which the host writes into its listener receipt; an earlier receipt is never this one's.
       const boot = randomUUID();
       rmSync(listeningReceiptPath(pidFile), { force: true });
-      const [command, ...args] = [...(placed.placed ? [...argv, '--prepared'] : argv), ...(service.kind === 'postgres' ? ['--listening-file', listeningReceiptPath(pidFile), '--boot', boot] : [])];
+      // The declared migrations' extensions alone, only for a cluster this boot placed whose live data carries the image's
+      // migration (S2 R66b, review): kept data, data a newer image migrates, or a cluster opened another way loads every
+      // extension, and the host drops the record.
+      const declaredOnly = service.kind === 'postgres' && placed.placed && env.VOLTER_WORLD_CONFIG !== undefined
+        && liveDatabaseMigration(env.VOLTER_WORLD_CONFIG, env, serviceData) !== undefined;
+      const [command, ...args] = [...(direct ? [...argv, '--prepared'] : argv), ...(declaredOnly ? ['--declared-extensions'] : []), ...(service.kind === 'postgres' ? ['--listening-file', listeningReceiptPath(pidFile), '--boot', boot] : [])];
       // a real fd, not a pipe: the host must outlive this process untethered
       const logFd = openSync(log, 'a');
       const child = spawn(command!, args, {
@@ -535,7 +636,7 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
         stdio: ['ignore', logFd, logFd],
       });
       // Retain the actual child BEFORE descriptor close or either publication can fail.
-      const lifetime = commandLifetime(child, launch.signal);
+      const lifetime = commandLifetime(child, launch.signal, false, READY_TIMEOUT_MS);
       const host: Host = { child, lifetime, closed: false };
       child.once('close', () => { host.closed = true; });
       hosts.set(pidFile, host); started.push(pidFile);
@@ -562,7 +663,13 @@ export async function pgliteUp(services: InfraService[], dataDir: string, launch
         launch.signal?.throwIfAborted();
         await sleep(25);
       }
-      launch.note?.(`${name} serving on 127.0.0.1:${service.hostPort}`);
+      // Publish atomically only after this boot's own listener and protocol answer proved the database open.
+      // Kept opens read their identity once and need no extra write or fsync.
+      if (identity !== undefined && !keptIdentity) publishProcessReceipt(declaredDatabaseReceipt(serviceData), identity);
+      // The host's own open split (pglite-host.mjs, THE OPEN'S SPLIT), from its receipt: said where a run's console
+      // sees it, as the host's stdout goes to its log alone (S2 R66).
+      const openSplit = service.kind === 'postgres' ? listeningReceipt(listeningReceiptPath(pidFile))?.openSplit : undefined;
+      launch.note?.(`${name} serving on 127.0.0.1:${service.hostPort}${openSplit ? ` (open split: ${openSplit})` : ''}`);
       if (service.kind === 'mongodb') await mongodbReady(service, launch, deadline);
       child.unref();
     }
@@ -614,13 +721,18 @@ async function stopHost(pidFile: string): Promise<void> {
     if (live()) {
       if (ownership.identity) await verifySpawnIdentity(ownership.identity);
       else throw new AggregateError(ownership.errors, 'Managed host spawn identity missing or unreadable; ownership retained');
-      // Reuse commandLifetime's existing grace and confirmation budgets; no new limit.
-      for (const [signal, limit] of [['SIGTERM', COMMAND_GRACE_MS], ['SIGKILL', COMMAND_CONFIRM_MS]] as const) {
+      // A STORE IS AWAITED AT ITS STOP on the lifecycle's own budget, not a command's grace: between the signal and
+      // its exit it writes its state down, and a SIGKILL in the middle of that leaves a root nothing may take.
+      // Its stop, its exit and the time between are events in the World's log; a kill is said as a kill.
+      const stopAsked = Date.now();
+      for (const [signal, limit] of [['SIGTERM', READY_TIMEOUT_MS], ['SIGKILL', COMMAND_CONFIRM_MS]] as const) {
         if (!live()) break;
-        await signalOwnedProcess(ownership.identity, signal, true);
+        worldEvent({ event: signal === 'SIGTERM' ? 'world.service.stop' : 'world.service.killed', service: 'managed host', by: 'down', signal, to: 'group', pid, ...(signal === 'SIGKILL' ? { afterMs: Date.now() - stopAsked, doing: 'its stop had not ended within the lifecycle budget' } : {}) });
+        await signalOwnedProcess(ownership.identity, signal, true, 'down');
         const deadline = Date.now() + limit;
         while (live() && Date.now() < deadline) await sleep(20);
       }
+      if (!live()) worldEvent({ event: 'world.service.exited', service: 'managed host', by: 'down', pid, shutdownMs: Date.now() - stopAsked });
       if (live()) throw new Error(`managed infrastructure group ${pid} did not stop; retained ${pidFile}`);
     }
   } else if (ownership.present) {