@volter/world-runtime 3.0.163 → 3.0.164

package/src/pglite-host.mjs

@@ -29,7 +29,11 @@
 // "extension … is not available" error. Loading the set costs boot time:
 // PGlite.create() in-memory, node 22 on darwin arm64 (this repo's dev box,
 // 2026-09-27, nothing else running in the process) took 1.66s bare and
-// 2.47s with the set; RSS was within 50 MB either way.
+// 2.47s with the set; RSS was within 50 MB either way. One open loads less:
+// a migrated prepared cluster this boot placed (`--declared-extensions`)
+// loads its installed extensions and startup preloads, including the retained
+// configuration's preloads (DECLARED_EXTENSIONS below); uncertain evidence
+// and every other open load the whole set.
 //
 // Limits, stated plainly (measured on 0.5.8 through this gateway with `pg`
 // clients; pglite-backing.test.ts holds the extension and database checks):
@@ -63,7 +67,12 @@
 // Randomness remains the host's own; no database schema objects are installed.
 import { errorMessage } from './error-message.mjs';
 import net from 'node:net';
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { closeSync, fsyncSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { gunzipSync } from 'node:zlib';
+import * as nodeModule from 'node:module';
+import { dirname, join } from 'node:path';
 import clockForm from '@volter/world-core/world-clock';
 import { fromNodeSocket } from 'pg-gateway/node';
 import { BackendError } from 'pg-gateway';
@@ -97,6 +106,109 @@ const CONTRIB = [
   'pg_trgm', 'pg_visibility', 'pg_walinspect', 'pgcrypto', 'seg', 'tablefunc',
   'tcn', 'tsm_system_rows', 'tsm_system_time', 'unaccent', 'uuid_ossp',
 ];
+// THE OPEN'S SPLIT (S2, Rallly's World): a tab's World waited 0.50 s from this host's spawn to its serving, against
+// ~0.12 s for the same reopen of a prepared cluster natively, and nothing said where. Said once, on stdout beside the
+// serving line: ms from this process's start to the imports done, to create() called and done, the wasm compile and
+// instantiate inside it (WebAssembly's own calls, timed where create makes them), and to serving.
+//
+// THE EXTENSION PHASE inside create() (S2 R66): a prepared open loads every extension bundle it is given (34 here) before
+// the backend starts. For each, PGlite 0.5.8 reads the .tar.gz through zlib's createGunzip, untars it into the
+// Emscripten file system, and preloads each .so, a side module: its preload plugin calls loadWebAssemblyModule with
+// loadAsync, which for bytes is WebAssembly.instantiate(bytes) (dist/chunk-*.js; the synchronous `new
+// WebAssembly.Module` and `new WebAssembly.Instance` are its path for a dlopen of a library not preloaded, and for the
+// few-byte modules it makes to wrap a JS function in a table). Said beside the rest: the bundles' gunzips (count, ms
+// summed and the wall they spanned), the side modules (count, bytes, compile+instantiate ms summed and their wall), the
+// main module's own wasm, the wrapper stubs, and the time between, inside the extension window, that none of them
+// covers (the untar and the file writes, and anything else there). All four WebAssembly entries are timed, the
+// constructors too, so a side module made either way is a side module, never "between". Not seen: work that is
+// none of these (an extension's own JS), which lands in "between". The whole line also rides the listener receipt, so
+// the World's serving line (pglite-backing.ts) carries it where a run's console sees it.
+const openSplit = { importsDoneMs: 0, createStartMs: 0, createDoneMs: 0, wasm: { compileMs: 0, instantiateMs: 0, calls: 0, bytes: 0 }, sessionDoneMs: 0 };
+const split = (value) => Math.round(value * 10) / 10;
+/** [start, end, kind, bytes] of every timed piece; kind 'gunzip', 'stub' (under 1 KiB), 'side' (under 1 MiB) or 'main'. */
+const pieces = [];
+// Keep only the opening observation: process-wide wrappers may still see later serving work.
+let collectingOpenPieces = true;
+const STUB_MODULE_BYTES = 1024, SIDE_MODULE_BYTES = 1024 * 1024;
+{
+  const wasm = openSplit.wasm, compile = WebAssembly.compile, instantiate = WebAssembly.instantiate;
+  // A compiled module's bytes, so its instantiation is counted as the module it is (a side module compiled, then
+  // instantiated from its Module, is a side module twice, not main wasm).
+  const moduleBytes = new WeakMap();
+  const sizeOf = (source) => (source instanceof WebAssembly.Module ? moduleBytes.get(source) ?? 0 : source?.byteLength ?? 0);
+  const kindOf = (bytes) => (bytes === 0 || bytes >= SIDE_MODULE_BYTES ? 'main' : bytes < STUB_MODULE_BYTES ? 'stub' : 'side');
+  const counted = (began, bytes, field) => {
+    if (!collectingOpenPieces) return;
+    const ended = performance.now(); wasm[field] += ended - began; pieces.push([began, ended, kindOf(bytes), bytes]);
+  };
+  WebAssembly.compile = async function (...args) {
+    const began = performance.now(), bytes = sizeOf(args[0]); wasm.calls += 1; wasm.bytes += bytes;
+    try { const module = await compile.apply(this, args); moduleBytes.set(module, bytes); return module; } finally { counted(began, bytes, 'compileMs'); }
+  };
+  WebAssembly.instantiate = async function (...args) {
+    const began = performance.now(), bytes = sizeOf(args[0]); wasm.calls += 1; if (!(args[0] instanceof WebAssembly.Module)) wasm.bytes += bytes;
+    try { return await instantiate.apply(this, args); } finally { counted(began, bytes, 'instantiateMs'); }
+  };
+  // The synchronous constructors, as proxies whose construct trap times them: `instanceof` still answers through the
+  // target's prototype, and what they make is the target's own.
+  WebAssembly.Module = new Proxy(WebAssembly.Module, {
+    construct(target, args) {
+      const began = performance.now(), bytes = sizeOf(args[0]); wasm.calls += 1; wasm.bytes += bytes;
+      try { const module = Reflect.construct(target, args); moduleBytes.set(module, bytes); return module; } finally { counted(began, bytes, 'compileMs'); }
+    },
+  });
+  WebAssembly.Instance = new Proxy(WebAssembly.Instance, {
+    construct(target, args) {
+      const began = performance.now(), bytes = sizeOf(args[0]); wasm.calls += 1;
+      try { return Reflect.construct(target, args); } finally { counted(began, bytes, 'instantiateMs'); }
+    },
+  });
+  // Node's CommonJS createGunzip is configurable but not writable (lib/zlib.js createProperty): assignment throws.
+  // Redefine only that configurable data property, preserving its flags, then sync its ESM binding for PGlite.
+  // Timing is optional: a runtime that cannot redefine or sync the builtin leaves gunzip timing unobserved.
+  const { createRequire, syncBuiltinESMExports } = nodeModule;
+  let zlib, property, wrapped;
+  try {
+    zlib = typeof createRequire === 'function' ? createRequire(import.meta.url)('node:zlib') : undefined;
+    property = zlib ? Object.getOwnPropertyDescriptor(zlib, 'createGunzip') : undefined;
+    if (property?.configurable && typeof property.value === 'function' && typeof syncBuiltinESMExports === 'function') {
+      const createGunzip = property.value;
+      wrapped = function (...args) {
+        const began = performance.now(), stream = createGunzip.apply(this, args);
+        stream.once('end', () => { if (collectingOpenPieces) pieces.push([began, performance.now(), 'gunzip', 0]); });
+        return stream;
+      };
+      Object.defineProperty(zlib, 'createGunzip', { ...property, value: wrapped });
+      syncBuiltinESMExports();
+    }
+  } catch {
+    // A missing observation cannot prevent the database opening. Restore an installed wrapper if sync refused it.
+    if (zlib && property && Object.getOwnPropertyDescriptor(zlib, 'createGunzip')?.value === wrapped) {
+      try { Object.defineProperty(zlib, 'createGunzip', property); syncBuiltinESMExports?.(); } catch { /* timing only */ }
+    }
+  }
+}
+/** The extension phase, from the timed pieces: see THE EXTENSION PHASE above. */
+function extensionPhase() {
+  const of = (kind) => pieces.filter(piece => piece[2] === kind);
+  const sum = (list) => list.reduce((total, [start, end]) => total + (end - start), 0);
+  const wall = (list) => (list.length ? Math.max(...list.map(piece => piece[1])) - Math.min(...list.map(piece => piece[0])) : 0);
+  const gunzips = of('gunzip'), sides = of('side'), main = of('main'), stubs = of('stub'), phase = [...gunzips, ...sides, ...stubs];
+  let between = 0;
+  if (phase.length) {
+    // The window's time no gunzip or side module covers: the union of their intervals, taken from the window.
+    const sorted = [...phase].sort((left, right) => left[0] - right[0]);
+    let covered = 0, [from, to] = sorted[0];
+    for (const [start, end] of sorted.slice(1)) {
+      if (start > to) { covered += to - from; [from, to] = [start, end]; } else to = Math.max(to, end);
+    }
+    covered += to - from;
+    between = wall(phase) - covered;
+  }
+  return `extensions ${split(wall(phase))} ms wall: ${gunzips.length} gunzips ${split(sum(gunzips))} ms (wall ${split(wall(gunzips))}), `
+    + `${sides.length} side modules ${sides.reduce((total, piece) => total + piece[3], 0)} bytes ${split(sum(sides))} ms (wall ${split(wall(sides))}), `
+    + `${stubs.length} stubs ${split(sum(stubs))} ms, between ${split(between)} ms; main wasm ${main.length} calls ${split(sum(main))} ms`;
+}
 const { PGlite } = await import('@electric-sql/pglite');
 const { vector } = await import('@electric-sql/pglite-pgvector');
 const extensions = { vector };
@@ -107,6 +219,7 @@ for (const [name, module] of await Promise.all(CONTRIB.map(async name => [name,
   if (!extension) throw new Error(`pglite-host: @electric-sql/pglite/contrib/${name} exports no ${name}`);
   extensions[name] = extension;
 }
+openSplit.importsDoneMs = performance.now();
 
 function arg(name) {
   const index = process.argv.indexOf(name);
@@ -128,9 +241,18 @@ const preparing = process.argv.includes('--prepare');
 const optional = (name) => { const index = process.argv.indexOf(name); return index >= 0 ? process.argv[index + 1] : undefined; };
 const listeningFile = optional('--listening-file');
 const bootToken = optional('--boot');
-// --prepared: the data directory is a cluster `--prepare` made for this declared identity (pglite-backing.ts checks
-// its stamp before passing this), so the declared database and role exist and the maintenance open is skipped.
+// --prepared: pglite-backing.ts proved this declared identity from a placed preparation stamp or a kept cluster's
+// serving receipt, so the declared database and role exist and the maintenance open is skipped.
 const prepared = process.argv.includes('--prepared');
+// --record-extensions: this host serves the World's declared database step (pglite-backing.ts migratePreparedCluster),
+// so the extensions the cluster has when it closes are the declared migrations' own: they are written beside the
+// cluster (DECLARED_EXTENSIONS) for a prepared open to load those alone (S2 R66b).
+const recordingExtensions = process.argv.includes('--record-extensions');
+// --declared-extensions: pglite-backing.ts placed this cluster from the World's preparation this boot and the live
+// database carries the image's migration (liveDatabaseMigration), so its record is the declared migrations' set and
+// nothing has created an extension in it since. Every other open loads the whole set and removes the record, which a
+// later extension (kept data migrated by a newer image, or created through a whole-set open) would make stale.
+const declaredOnly = process.argv.includes('--declared-extensions');
 const port = preparing ? 0 : Number(arg('--port'));
 const dataDir = arg('--data');
 const databaseUser = process.env.VOLTER_WORLD_PGLITE_USER;
@@ -153,15 +275,361 @@ process.stderr.on('error', () => {});
 // listening starts AFTER readiness so "port answers" means "serves queries"
 const initKeepAlive = setInterval(() => {}, 500);
 const quoteIdentifier = value => `"${value.replaceAll('"', '""')}"`;
+/** PGlite's default printErr suppresses backend startup errors when debug is off. Its public extension setup seam
+ * keeps backend stderr in the child log without enabling debug. PostgreSQL may include a failed statement's SQL. */
+function withBackendStderr(bundles) {
+  return { ...bundles, world_backend_stderr: {
+    name: 'world_backend_stderr',
+    setup: async (_db, emscriptenOpts) => ({ emscriptenOpts: { ...emscriptenOpts, printErr: line => {
+      try { process.stderr.write(`pglite-host backend: ${String(line)}\n`); } catch { /* a closed log cannot fail startup */ }
+    } } }),
+  } };
+}
+/**
+ * EXTENSIONS AS POSTGRES LOADS THEM: THEIR FILES ONCE, THEIR LIBRARIES WHEN USED (S2 T12). PGlite 0.5.8 loads each
+ * extension it is given at every open: it gunzips the bundle (.tar.gz), untars it into the Emscripten file system and
+ * preloads every .so, a side module compiled and instantiated into the instance (THE EXTENSION PHASE above: Rallly's
+ * prepared open, 34 bundles, ~166-183 ms of extension wall, of which gunzips ~76-90 ms, side modules ~57-62 ms and the
+ * untar and file writes ~76 ms). Native Postgres has the files on disk once, loads its shared_preload_libraries once at
+ * the postmaster's start, and loads any other extension's library at its first use (dfmgr's load_external_function:
+ * dlopen). This host does the same:
+ * - a bundle is gunzipped and untarred once per cache, its files kept unpacked beside the cluster's data directory
+ *   (`.volter-pglite-extensions/<name>-<sha256 of the bundle, 16 hex>/`, with `.files.json` naming the digest and the
+ *   files); every later open whose bundle has that digest reads the kept files and writes them into the instance's
+ *   file system before it starts (a preRun), with no gunzip and no untar. The cache is the data directory's parent's:
+ *   the image build's --prepare host keeps its own, so a World's first `up` unpacks once more;
+ * - no .so is preloaded: Postgres's own dlopen loads a library when it is first used, and the shared preload
+ *   libraries (pg_stat_statements, which PGlite's preload list and the retained configuration name) at the backend's
+ *   start, through Emscripten's dlopen, which reads the file and compiles and instantiates it synchronously (the path
+ *   PGlite itself leaves for a library not preloaded).
+ * A bundle that cannot be read or unpacked is said and given no files, as PGlite logs a failed bundle and goes on; a
+ * cache that cannot be kept (no space, no permission, a read-only directory) is counted as keepFailed with its error,
+ * and that open's files are the ones it unpacked.
+ * THE CEILING, from source: an instantiated side module cannot be kept across opens. Each open is its own Emscripten
+ * instance with its own memory and table, and a side module is linked into those: libdylink's loadWebAssemblyModule
+ * places its data at a memoryBase it allocates in that instance's heap and its functions in that instance's table, then
+ * instantiates with that instance's memory and table as imports. So the library's instantiation is per open, as a
+ * process's dlopen is per process natively; only the files are kept.
+ * The gain is unmeasured: the reading is the next Rallly lap's serving line, its extension phase (no gunzips, no side
+ * module preloads) and its `extension files` account (kept, unpacked, keepFailed, ms).
+ */
+const EXTENSION_FILES = join(dirname(dataDir), '.volter-pglite-extensions');
+/** A tar member's name is a relative path inside the bundle: no absolute path, no `..` or empty segment. */
+function safeMemberName(name) {
+  return typeof name === 'string' && name.length > 0 && !name.startsWith('/') && !name.includes('\0')
+    && name.split('/').every((segment, at, all) => segment !== '..' && segment !== '.' && (segment !== '' || at === all.length - 1));
+}
+/** A bundle's tar members: ustar (its magic and checksum checked), a pax header's path or a GNU long name where one is given. */
+function untarMembers(tar) {
+  const members = [];
+  let longName;
+  const text = (at, length) => { const end = tar.indexOf(0, at); return tar.toString('utf8', at, end >= 0 && end < at + length ? end : at + length); };
+  const octal = (at, length, what) => {
+    const field = text(at, length).trim();
+    if (!/^[0-7]*$/.test(field)) throw new Error(`tar: ${what} is not octal`);
+    return field ? parseInt(field, 8) : 0;
+  };
+  for (let at = 0; at + 512 <= tar.length;) {
+    if (tar.subarray(at, at + 512).every(byte => byte === 0)) break;
+    if (!text(at + 257, 6).startsWith('ustar')) throw new Error('tar: a header without the ustar magic');
+    let sum = 0;
+    for (let index = 0; index < 512; index += 1) sum += index >= 148 && index < 156 ? 0x20 : tar[at + index];
+    if (sum !== octal(at + 148, 8, 'a header checksum')) throw new Error('tar: a header checksum does not match');
+    const size = octal(at + 124, 12, 'a member size');
+    const type = String.fromCharCode(tar[at + 156] || 0x30);
+    const prefix = text(at + 345, 155);
+    const name = longName ?? (prefix ? `${prefix}/${text(at, 100)}` : text(at, 100));
+    if (at + 512 + size > tar.length) throw new Error('tar: a member runs past the archive');
+    const data = tar.subarray(at + 512, at + 512 + size);
+    at += 512 + Math.ceil(size / 512) * 512;
+    if (type === 'x') {
+      const record = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(data.toString('utf8'));
+      longName = record ? record[1] : undefined;
+      continue;
+    }
+    if (type === 'L') { longName = data.toString('utf8').replace(/\0+$/, ''); continue; }
+    longName = undefined;
+    if (type === 'g') continue;
+    if (type !== '0' && type !== '\0') continue;
+    if (!safeMemberName(name)) throw new Error(`tar: a member named outside the bundle (${JSON.stringify(name).slice(0, 80)})`);
+    members.push({ name, data });
+  }
+  return members;
+}
+/** An open's account of its bundles: kept and unpacked bundles, their files, failures to keep, kept lists unreadable. */
+const accountFor = (create) => ({ create, bundles: 0, kept: 0, unpacked: 0, tarRefused: 0, keepFailed: 0, keepErrors: new Set(), keptUnread: 0, files: 0, ms: 0 });
+// Every create's account, in order. A host that is not prepared opens twice (template1, then the declared database),
+// and the extension phase's timed pieces span both creates, so the account is said for both (review of T12b, D): the
+// timed gunzips are every create's unpacked plus its tarRefused (a bundle gunzipped whose tar the reader refused).
+const creates = [];
+const KEPT_LIST = '.files.json';
+// The kept list's form: changed with the tar reader, its member filter, this list's fields or how a keep is made
+// durable, so a cache another form wrote is unpacked again rather than read. 2: each file with its size, checked on
+// read. 3: each file synced before the keep's rename, so a v2 keep (unsynced, possibly a zero-filled file at its full
+// size after a crash) is never served (review of T12c, B1).
+const KEPT_VERSION = 3;
+/** A kept list that cannot be read is said and counted once per bundle, however many times the bundle looks at it. */
+function keptUnreadable(bundle, what, error) {
+  if (bundle.unread) return;
+  bundle.unread = true;
+  bundle.account.keptUnread += 1;
+  process.stderr.write(`pglite-host: extension ${bundle.name}: ${what} cannot be read (${errorMessage(error)}); unpacked again\n`);
+}
+/** The files `kept` lists, where its list has this form and this digest; else undefined. */
+function keptList(bundle, kept, digest) {
+  let listed;
+  try { listed = JSON.parse(readFileSync(join(kept, KEPT_LIST), 'utf8')); }
+  catch (error) {
+    if (error?.code !== 'ENOENT') keptUnreadable(bundle, 'its kept files', error);
+    return undefined;
+  }
+  if (listed?.version !== KEPT_VERSION || listed.digest !== digest || !Array.isArray(listed.files)
+    || !listed.files.every(file => safeMemberName(file?.name) && Number.isSafeInteger(file?.size) && file.size >= 0)) return undefined;
+  return listed.files;
+}
+/** The kept files of `kept`, read, where its list stands and every file is present at its size; else undefined. */
+function keptFiles(bundle, kept, digest) {
+  const listed = keptList(bundle, kept, digest);
+  if (!listed) return undefined;
+  try {
+    const files = listed.map(file => [file.name, readFileSync(join(kept, file.name))]);
+    // A file cut short after a power loss (a zero-length .so) is not served: every size must be the one kept.
+    if (files.some(([_file, data], at) => data.length !== listed[at].size)) return undefined;
+    return files;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') keptUnreadable(bundle, 'a kept file', error);
+    return undefined;
+  }
+}
+/** Whether `kept` stands whole, by its list and each file's size as stat says it: no file read back (review of T12b, B). */
+function keptStands(bundle, kept, digest) {
+  const listed = keptList(bundle, kept, digest);
+  if (!listed) return false;
+  try { return listed.every(file => { const stat = statSync(join(kept, file.name)); return stat.isFile() && stat.size === file.size; }); }
+  catch (error) {
+    if (error?.code !== 'ENOENT') keptUnreadable(bundle, 'a kept file', error);
+    return false;
+  }
+}
+/**
+ * `data` written to `path` and synced before the keep's rename, so a crash cannot leave a kept file at its listed size
+ * with blocks never written (a zero-filled .so the size check would pass; review of T12b, C). The directories are not
+ * synced: a rename a crash loses leaves the cache cold, never wrong, and the next open unpacks again. Where fsync fails
+ * though writes work (some FUSE, 9p or network file systems), nothing is kept: every open there unpacks, as before T12.
+ * A failure to close is thrown only where the write and the sync succeeded, so it never hides theirs.
+ */
+function writeSynced(path, data) {
+  const fd = openSync(path, 'w');
+  let failure;
+  try { writeFileSync(fd, data); fsyncSync(fd); } catch (error) { failure = error; }
+  try { closeSync(fd); } catch (error) { failure ??= error; }
+  if (failure) throw failure;
+}
+/** A bundle's files (relative path, bytes) as PGlite would write them, unpacked once and kept beside the cluster. */
+function bundleFiles(name, bundlePath, account) {
+  let packed;
+  try { packed = readFileSync(bundlePath instanceof URL ? fileURLToPath(bundlePath) : String(bundlePath)); }
+  catch (error) {
+    process.stderr.write(`pglite-host: extension ${name}: its bundle cannot be read (${errorMessage(error)}); it is not loaded\n`);
+    return [];
+  }
+  const bundle = { name, account, unread: false };
+  const digest = createHash('sha256').update(packed).digest('hex');
+  const keptName = `${name}-${digest.slice(0, 16)}`;
+  const kept = join(EXTENSION_FILES, keptName);
+  const standing = keptFiles(bundle, kept, digest);
+  if (standing) { account.kept += 1; return standing; }
+  let files;
+  let gunzipped = false;
+  try {
+    // As PGlite's own untar (dist/index.js Et): members whose names start with "." are not written. A bundle the
+    // reader refuses (a bad checksum or magic, a member outside the bundle) is logged and given no files, where
+    // PGlite's own untar would throw out of the open.
+    const began = performance.now();
+    const tar = gunzipSync(packed);
+    if (collectingOpenPieces) pieces.push([began, performance.now(), 'gunzip', 0]);
+    gunzipped = true;
+    files = untarMembers(tar).filter(member => !member.name.startsWith('.') && !member.name.endsWith('/'))
+      .map(member => [member.name, member.data]);
+  } catch (error) {
+    if (gunzipped) account.tarRefused += 1;
+    process.stderr.write(`pglite-host: extension ${name}: its bundle cannot be unpacked (${errorMessage(error)}); it is not loaded\n`);
+    return [];
+  }
+  account.unpacked += 1;
+  // Kept by a rename of a whole directory, so a reader never sees half of one; a host that lost the race keeps nothing.
+  const writing = `${kept}.${process.pid}.${randomUUID()}`;
+  let keepError;
+  try {
+    mkdirSync(EXTENSION_FILES, { recursive: true });
+    for (const [file, data] of files) { mkdirSync(dirname(join(writing, file)), { recursive: true }); writeSynced(join(writing, file), data); }
+    writeSynced(join(writing, KEPT_LIST), JSON.stringify({ version: KEPT_VERSION, digest, files: files.map(([file, data]) => ({ name: file, size: data.length })) }));
+    // A directory left by an earlier keep that lacks a file is replaced; one another host kept meanwhile stands.
+    try { renameSync(writing, kept); }
+    catch (error) {
+      if (error?.code !== 'ENOTEMPTY' && error?.code !== 'EEXIST') throw error;
+      if (!keptStands(bundle, kept, digest)) { rmSync(kept, { recursive: true, force: true }); renameSync(writing, kept); }
+    }
+  } catch (error) { keepError = error; }
+  // Whatever is left of the staging, and an earlier digest's directory or an ended host's staging of this name, goes.
+  // Cleaning is best effort and neither said nor counted: a staging that cannot be removed, or whose pid answers as live
+  // (its host, or another process now holding a reused pid), stays until a later keep of this name finds it removable.
+  try { rmSync(writing, { recursive: true, force: true }); } catch { /* left for a later keep */ }
+  try {
+    for (const entry of readdirSync(EXTENSION_FILES)) {
+      if (!entry.startsWith(`${name}-`) || entry === keptName) continue;
+      const staging = /\.(\d+)\.[0-9a-f-]{36}$/.exec(entry);
+      if (staging) { try { process.kill(Number(staging[1]), 0); continue; } catch (error) { if (error?.code === 'EPERM') continue; } }
+      rmSync(join(EXTENSION_FILES, entry), { recursive: true, force: true });
+    }
+  } catch { /* left for a later keep */ }
+  // Kept or not is what stands at the end: another host's directory, or ours, holding every file at its size.
+  if (!keptStands(bundle, kept, digest)) {
+    account.keepFailed += 1;
+    account.keepErrors.add(keepError?.code ?? (keepError ? errorMessage(keepError).slice(0, 60) : 'not kept'));
+  }
+  return files;
+}
+/** One create's extension-files account. */
+function accountSaid(account) {
+  return `${account.bundles} bundles (${account.kept} kept, ${account.unpacked} unpacked${account.tarRefused ? `, ${account.tarRefused} tars refused` : ''}, ${account.keepFailed} not kept`
+    + `${account.keepErrors.size ? `: ${[...account.keepErrors].join(', ')}` : ''}${account.keptUnread ? `, ${account.keptUnread} kept unreadable` : ''}), `
+    + `${account.files} files in ${split(account.ms)} ms`;
+}
+/** The open's extension-files account, every create's, as the serving line (and a --prepare host's own line) says it. */
+function extensionFilesSaid() {
+  const said = creates.length === 1 ? accountSaid(creates[0]) : creates.map(account => `${account.create}: ${accountSaid(account)}`).join('; ');
+  return `extension files: ${said || 'no create'}, no library preloaded (S2 T12)`;
+}
+/** Each bundle extension as one whose files are written into the instance before it starts, its libraries not preloaded. */
+function unpackedOnce(bundles, create) {
+  const account = accountFor(create);
+  creates.push(account);
+  const wrapped = {};
+  for (const [name, extension] of Object.entries(bundles)) {
+    wrapped[name] = { name: extension.name ?? name, setup: async (db, emscriptenOpts, clientOnly) => {
+      const given = await extension.setup(db, emscriptenOpts, clientOnly);
+      if (!given?.bundlePath) return given;
+      const { bundlePath, ...rest } = given;
+      const began = performance.now();
+      const files = bundleFiles(name, bundlePath, account);
+      account.bundles += 1; account.files += files.length; account.ms += performance.now() - began;
+      const base = rest.emscriptenOpts ?? emscriptenOpts;
+      return { ...rest, emscriptenOpts: { ...base, preRun: [...(base.preRun ?? []), (module) => {
+        for (const [file, data] of files) {
+          const target = `${module.WASM_PREFIX}/${file}`;
+          const parent = target.slice(0, target.lastIndexOf('/'));
+          if (!module.FS.analyzePath(parent).exists) module.FS.mkdirTree(parent);
+          module.FS.writeFile(target, data);
+        }
+      }] } };
+    } };
+  }
+  return wrapped;
+}
+
+/**
+ * THE DECLARED MIGRATIONS' EXTENSIONS (S2 R66b). A prepared open loaded every extension bundle the host offers (34) at
+ * create(), each a gunzip, an untar into the Emscripten file system and a side module's instantiate, whatever the
+ * cluster uses: Rallly's World waited 0.50 s from spawn to serving against ~0.12 s natively. Where the cluster was
+ * prepared with the World's declared database step, its installed extensions and preload libraries are recorded
+ * beside it (`.volter-declared-extensions.json`, under the data directory, which Postgres leaves alone). Only an open
+ * given `--declared-extensions` (the boot that placed the cluster, see `declaredOnly` above) loads those and the retained
+ * configuration's preload libraries: pg_extension alone omits a required preload without CREATE EXTENSION. An
+ * extension the migrations created is loaded; one they did not is absent, as it is from the freshly placed cluster, and
+ * a `CREATE EXTENSION` of it refuses "is not available". Such an open of a cluster with no record (prepared with no
+ * declared step, or before the record existed), or of a record naming an extension this host does not offer, loads every
+ * bundle, as every other open does.
+ */
+const DECLARED_EXTENSIONS = join(dataDir, '.volter-declared-extensions.json');
+/** The bundles a prepared open loads: the record's, where every name in it is one this host offers; else all. */
+function declaredExtensions() {
+  let named;
+  try { named = JSON.parse(readFileSync(DECLARED_EXTENSIONS, 'utf8')); } catch { return extensions; }
+  // A v1 record says nothing about startup preloads: keep the full set, including for existing prepared images.
+  if (named?.version !== 2 || !Array.isArray(named.extensions) || !Array.isArray(named.preloadLibraries)) return extensions;
+  const configured = configuredPreloads();
+  if (configured === undefined) return extensions;
+  const chosen = {};
+  for (const name of [...named.extensions, ...named.preloadLibraries, ...configured]) {
+    if (typeof name !== 'string') return extensions;
+    // plpgsql is the server's own; uuid-ossp's module is uuid_ossp (the module name; see CONTRIB).
+    if (name === 'plpgsql') continue;
+    const module = name === 'uuid-ossp' ? 'uuid_ossp' : name;
+    if (!Object.hasOwn(extensions, module)) return extensions;
+    chosen[module] = extensions[module];
+  }
+  return chosen;
+}
+/** Only simple library names this host supplies can narrow the bundle set; uncertain syntax keeps every bundle. */
+function preloadNames(value) {
+  if (typeof value !== 'string') return undefined;
+  if (!value.trim()) return [];
+  const names = value.split(',').map(name => name.trim());
+  return names.every(name => /^[a-z][a-z0-9_-]*$/.test(name) && Object.hasOwn(extensions, name)) ? names : undefined;
+}
+/** The files PostgreSQL will read are the truth at boot. Union both files' preloads, even a superseded assignment;
+ * includes and unsupported value syntax fall back to all bundles rather than guessing their dependency closure. */
+function configuredPreloads() {
+  const names = new Set();
+  for (const file of ['postgresql.conf', 'postgresql.auto.conf']) {
+    let text;
+    try { text = readFileSync(join(dataDir, file), 'utf8'); }
+    catch (error) { if (file === 'postgresql.auto.conf' && error?.code === 'ENOENT') continue; return undefined; }
+    for (const source of text.split(/\r?\n/)) {
+      const line = source.trim();
+      if (!line || line.startsWith('#')) continue;
+      if (/^include(?:_dir|_if_exists)?\b/i.test(line)) return undefined;
+      if (!/^shared_preload_libraries\b/i.test(line)) continue;
+      const setting = /^shared_preload_libraries\s*=\s*(?:'([^'\\]*)'|([a-z0-9_, \t-]*?))\s*(?:#.*)?$/i.exec(line);
+      if (!setting) return undefined;
+      const libraries = preloadNames(setting[1] ?? setting[2]);
+      if (libraries === undefined) return undefined;
+      for (const name of libraries) names.add(name);
+    }
+  }
+  return [...names];
+}
+/** The cluster's extensions now, written beside it for the next prepared open (only where this host records them). */
+async function recordExtensions(db) {
+  if (!recordingExtensions) return;
+  try {
+    const rows = (await db.query('SELECT extname FROM pg_extension ORDER BY extname')).rows;
+    const startup = (await db.query("SELECT current_setting('session_preload_libraries') AS session, current_setting('local_preload_libraries') AS local")).rows[0];
+    // Database/role defaults can supply these outside the conf files; no narrowed record is safe while either is set.
+    if (typeof startup?.session !== 'string' || typeof startup?.local !== 'string' || startup.session.trim() || startup.local.trim()) {
+      throw new Error('Session or local preload libraries prevent a narrowed extension record.');
+    }
+    const setting = (await db.query("SELECT current_setting('shared_preload_libraries') AS libraries")).rows[0]?.libraries;
+    const preloadLibraries = preloadNames(setting);
+    if (preloadLibraries === undefined) throw new Error('The cluster preload libraries cannot be recorded as known bundles.');
+    const temporary = `${DECLARED_EXTENSIONS}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify({ version: 2, extensions: rows.map(row => row.extname), preloadLibraries })}\n`);
+    renameSync(temporary, DECLARED_EXTENSIONS);
+  } catch (error) {
+    // No record is the full set at the next open: never a narrower one than the cluster needs.
+    rmSync(DECLARED_EXTENSIONS, { force: true });
+    process.stderr.write(`pglite-host: the cluster's extensions were not recorded: ${errorMessage(error)}\n`);
+  }
+}
 async function openDeclaredDatabase() {
+  // A record a narrowed open did not ask for is gone before anything can create an extension it lacks (review of R66b).
+  if (!declaredOnly && !recordingExtensions) rmSync(DECLARED_EXTENSIONS, { force: true });
   if (prepared) {
-    const db = await PGlite.create({ dataDir, extensions, database: databaseName });
+    process.stdout.write('pglite-host opening declared database directly\n');
+    openSplit.createStartMs = performance.now();
+    const loading = declaredOnly && !recordingExtensions ? declaredExtensions() : extensions;
+    if (loading !== extensions) process.stdout.write(`pglite-host loading the declared migrations' extensions: ${Object.keys(loading).join(', ') || 'none'}\n`);
+    const db = await PGlite.create({ dataDir, extensions: withBackendStderr(unpackedOnce(loading, databaseName)), database: databaseName });
+    openSplit.createDoneMs = performance.now();
     await db.exec(`SET SESSION AUTHORIZATION ${quoteIdentifier(databaseUser)}`);
+    openSplit.sessionDoneMs = performance.now();
     return db;
   }
   // PostgreSQL cannot rename its current database. Use its maintenance database
   // before opening the declared one; old Worlds' rows in postgres stay intact.
-  const maintenance = await PGlite.create({ dataDir, extensions, database: 'template1' });
+  process.stdout.write('pglite-host opening template1 for database identity setup\n');
+  const maintenance = await PGlite.create({ dataDir, extensions: withBackendStderr(unpackedOnce(extensions, 'template1')), database: 'template1' });
   try {
     const existing = await maintenance.query('SELECT datname FROM pg_database WHERE datname = $1', [databaseName]);
     if (!existing.rows.length) {
@@ -173,7 +641,7 @@ async function openDeclaredDatabase() {
     const role = await maintenance.query('SELECT rolname FROM pg_roles WHERE rolname = $1', [databaseUser]);
     if (!role.rows.length) await maintenance.exec(`CREATE ROLE ${quoteIdentifier(databaseUser)} LOGIN SUPERUSER`);
   } finally { await maintenance.close(); }
-  const db = await PGlite.create({ dataDir, extensions, database: databaseName });
+  const db = await PGlite.create({ dataDir, extensions: withBackendStderr(unpackedOnce(extensions, databaseName)), database: databaseName });
   await db.exec(`SET SESSION AUTHORIZATION ${quoteIdentifier(databaseUser)}`);
   return db;
 }
@@ -649,17 +1117,21 @@ const server = net.createServer((socket) => {
 if (preparing) void dbReady.then(async (db) => {
   await db.close();
   clearInterval(initKeepAlive);
-  process.stdout.write(`pglite-host prepared ${dataDir}\n`);
+  process.stdout.write(`pglite-host prepared ${dataDir} (${extensionFilesSaid()})\n`);
   process.exit(0);
 });
 else void dbReady.then(() => {
   clearInterval(initKeepAlive);
   server.listen(port, '127.0.0.1', () => {
+    const wasm = openSplit.wasm;
+    const said = `imports ${split(openSplit.importsDoneMs)} ms, create ${split(openSplit.createStartMs)} -> ${split(openSplit.createDoneMs)} ms (wasm ${wasm.calls} calls, ${wasm.bytes} bytes: compile ${split(wasm.compileMs)} ms, instantiate ${split(wasm.instantiateMs)} ms; ${extensionPhase()}; ${extensionFilesSaid()}), session ${split(openSplit.sessionDoneMs)} ms, serving ${split(performance.now())} ms from this process's start`;
+    collectingOpenPieces = false;
     if (listeningFile) {
       const temporary = `${listeningFile}.${process.pid}.tmp`;
-      writeFileSync(temporary, `${JSON.stringify({ version: 1, pid: process.pid, port, boot: bootToken ?? null })}\n`, { mode: 0o600 });
+      writeFileSync(temporary, `${JSON.stringify({ version: 1, pid: process.pid, port, boot: bootToken ?? null, openSplit: said })}\n`, { mode: 0o600 });
       renameSync(temporary, listeningFile);
     }
+    process.stdout.write(`pglite-host open split: ${said}\n`);
     process.stdout.write(`pglite-host serving postgres wire protocol on 127.0.0.1:${port}\n`);
   });
 });
@@ -667,7 +1139,7 @@ else void dbReady.then(() => {
 for (const signal of ['SIGTERM', 'SIGINT']) {
   process.on(signal, () => {
     server.close(() => {
-      void dbReady.then((db) => db.close()).finally(() => process.exit(0));
+      void dbReady.then(async (db) => { await recordExtensions(db); await db.close(); }).finally(() => process.exit(0));
     });
     // a hung close must not make `down` hang the world
     setTimeout(() => process.exit(0), 3000).unref();

package/src/process-groups.d.mts

@@ -1,2 +1,7 @@
-export function survivingOwnedGroups(pids: number[]): number[];
+/** One reading of the process table, shared by the questions of one decision: made empty by the caller, filled by the first question that needs it. */
+export type ProcessListing = { table?: unknown; proc?: unknown };
+export function survivingOwnedGroups(pids: number[], listing?: ProcessListing): number[];
+export function setWorldEventsFile(path: string | undefined): void;
+export function worldEvent(record: Record<string, unknown>): void;
+export function sayProbe(command: string, startedAt: number, outcome: string): void;
 export function processStarts(pids: number[]): Map<number, string>;