@volter/world-runtime 3.0.162 → 3.0.164

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "3.0.162",
+  "version": "3.0.164",
   "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",
@@ -70,8 +70,8 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.154",
-    "@volter/world-console": "3.0.150"
+    "@volter/world-core": "3.0.156",
+    "@volter/world-console": "3.0.151"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
@@ -80,7 +80,7 @@
     "@volter/browser-runtime": "0.1.104",
     "@volter/browser-sandboxes": "0.1.84",
     "@volter/world-access": "3.0.1",
-    "@volter/world-core": "3.0.154",
+    "@volter/world-core": "3.0.156",
     "modern-screenshot": "4.7.0",
     "mongodb": "~6.20.0",
     "pg-gateway": "0.3.0-beta.4",

package/src/ancestry.ts

@@ -2,7 +2,7 @@
 // carry parent-side pins, including clones across checkouts, without a global World registry.
 import { existsSync, readdirSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
-import { assertStateRemovable, readBranchMeta, stateDirName, withAncestryLock, withStateRemoval, getActiveWorldStore, worldPaths, worldStateRoot } from '@volter/world-core/runtime';
+import { assertStateRemovable, readBranchMeta, stateDirName, withAncestryLock, withStateRemoval, getActiveWorldStore, worldPaths, worldStateRoot } from '@volter/world-core/runtime-state';
 
 function checkWorldAncestry(root: string, path: string): void {
   const base = join(root, stateDirName(), 'worlds');
@@ -28,7 +28,7 @@ function checkWorldAncestry(root: string, path: string): void {
 }
 
 export function assertWorldStateRemovable(root: string, path: string): void {
-  withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); });
+  withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); }, { operation: 'removal preflight' });
 }
 
 export function removeWorldState<T>(root: string, path: string, remove: () => T): T {

package/src/app-url.ts

@@ -21,7 +21,7 @@
 // instance it described.
 import { errorMessage } from './error-message.ts';
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { withFileLock } from '@volter/world-core/runtime';
+import { withFileLock } from '@volter/world-core/runtime-state';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import net from 'node:net';
@@ -113,11 +113,18 @@ function assertHttpUrl(url: string): URL {
 /** Record `url` as the app endpoint of the RUNNING/booted instance `name`. The instance must
  * exist (a record for a world that was never upped would describe nothing); the app itself is
  * deliberately NOT probed — the booter declaring "this is where I put the app" is the truth. */
-export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string; app?: string } = {}): AppUrlRecord {
+export function setAppUrl(name: string, url: string, options: { root?: string; via?: Exclude<AppUrlSource, 'service'>; detail?: string; app?: string; /** An instrument: filled with how long the World's status and the record's write each took. */ timings?: { statusMs?: number; writeMs?: number } } = {}): AppUrlRecord {
   const root = options.root ?? process.cwd();
   const app = appName(options.app);
+  const began = Date.now();
   const status = statusWorld(name, root); // throws "World instance not found" — the loud path
+  const statusRead = Date.now();
+  if (options.timings) options.timings.statusMs = statusRead - began;
   assertHttpUrl(url);
+  try { return setAppUrlEntry(root, name, app, url, status, options); }
+  finally { if (options.timings) options.timings.writeMs = Date.now() - statusRead; }
+}
+function setAppUrlEntry(root: string, name: string, app: string, url: string, status: ReturnType<typeof statusWorld>, options: { via?: Exclude<AppUrlSource, 'service'>; detail?: string }): AppUrlRecord {
   return writeEntry(root, name, app, (file) => {
     // a new URL keeps the hosts recorded for the app (they name the app, not where it listens)
     const hosts = entryOf(file, app)?.hosts;

package/src/branch.ts

@@ -7,7 +7,7 @@
 // base running at once share the database port its definition names; run one at a time (the SDK does). `checkout <name>`
 // brings a stopped world back up from its own instance record, state intact.
 import { runInfrastructure } from './infra.ts';
-import { cpSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import { cpSync, existsSync, lstatSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withHistoryLocks, worldPaths, worldStateRoot } from '@volter/world-core/runtime';
@@ -49,7 +49,7 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
       const position = options.at?.positions?.[service] ?? options.at?.positions?.[state] ?? timed?.position;
       return { state, view, position, generation: stateGeneration(worldPaths(state, fromRoot).dir) };
     }) };
-  }));
+  }), { operation: 'capture' });
   // the base's managed databases (checked before the branch boots: its database would share the base's port)
   const databases = managedDatabases(from);
   if (databases.length && (options.at?.instant || options.at?.positions || options.at?.views)) {
@@ -83,23 +83,28 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
 }
 
 /** The base's containerless managed databases: each PGlite `pglite-<kind>-data`, MongoDB's
- *  `mongod-mongodb-data` (pglite-backing.ts), the redis twin's `redis-twin` tree (redis-backing.ts), and native PostgreSQL. A stopped World's
+ *  `mongod-mongodb-data` (pglite-backing.ts), the declared Redis/ClickHouse twin trees, and native PostgreSQL. A stopped World's
  *  hosts leave no pid file; a docker-backed World keeps its data under the container's volume, which a branch does not
  *  carry. */
 function managedDatabases(from: WorldInstance): string[] {
   const data = from.dirs.data;
   if (!existsSync(data)) return [];
-  const known = (name: string) => /^pglite-[a-z0-9_-]+-data$/.test(name) || name === 'mongod-mongodb-data' || name === 'native-postgres-data';
+  const known = (name: string) => /^pglite-[a-z0-9_-]+-data$/.test(name) || name === 'mongod-mongodb-data' || ['native-postgres-data', 'native-mariadb-data'].includes(name);
   if (readdirSync(data).some(name => name.endsWith('-data') && !known(name) && !from.services[name])) {
     throw new Error('volter-world branch: unrecognised storage; retain the original World');
   }
-  return readdirSync(data).filter((n) => /^pglite-[a-z0-9_-]+-data$/.test(n) || n === 'mongod-mongodb-data' || n === 'redis-twin' || n === 'native-postgres-data');
+  return readdirSync(data).filter((n) => /^pglite-[a-z0-9_-]+-data$/.test(n) || n === 'mongod-mongodb-data' || ['redis-twin', 'clickhouse-twin', 'native-postgres-data', 'native-mariadb-data'].includes(n));
 }
 
 /** The pid files of the hosts serving one managed database directory. */
 function hostPidFiles(data: string, db: string): string[] {
+  if (db === 'native-mariadb-data') return readdirSync(data).filter(name => /^native-mariadb\.(?:owner|starting)\.json(?:\.spawn\.json)?$/u.test(name)
+    || /^native-mariadb-tool-.*\.json(?:\.spawn\.json)?$/u.test(name)).map(name => join(data, name));
   if (db === 'native-postgres-data') return [join(data, 'native-postgres.owner.json')];
   if (db === 'redis-twin') return readdirSync(data).filter((n) => /^redis-twin-\d+\.pid$/.test(n)).map((n) => join(data, n));
+  if (db === 'clickhouse-twin') return [...new Set(readdirSync(data)
+    .filter(n => new RegExp(`^${db}-\\d+\\.pid(?:\\.spawn\\.json)?$`).test(n))
+    .map(n => join(data, n.replace(/\.spawn\.json$/, ''))))];
   return [join(data, `${db.slice(0, -'-data'.length)}.pid`)];
 }
 
@@ -107,7 +112,19 @@ function hostPidFiles(data: string, db: string): string[] {
  *  port: the base must be stopped first (`volter world branch` stops it, as a branch replaces its base). */
 function refuseLiveDatabases(from: WorldInstance, dbs: string[]): void {
   for (const db of dbs) {
+    if (db === 'native-mariadb-data' && (existsSync(join(from.dirs.data, db, 'server.pid')) || existsSync(join(from.dirs.data, db, 'server.sock'))))
+      throw new Error(`volter-world branch: ${from.name}'s managed MariaDB retains PID/socket files; verified down is required`);
+    if (db === 'native-mariadb-data') {
+      const stamp = join(from.dirs.data, db, '.world-policy.json');
+      if (!existsSync(stamp) || !lstatSync(stamp).isFile() || existsSync(join(from.dirs.data, db, '.world-initializing.json')))
+        throw new Error(`volter-world branch: ${from.name}'s MariaDB has incomplete initialization; original data retained`);
+    }
     for (const pidFile of hostPidFiles(from.dirs.data, db)) {
+      // Successful managed-twin down removes both receipts. A partial publication or an
+      // uncertain retirement must finish there before branch copies this store.
+      if (db === 'clickhouse-twin' || db === 'native-mariadb-data') {
+        throw new Error(`volter-world branch: ${from.name}'s managed ${db} retains ownership receipts; stop ${from.name} before copying its store`);
+      }
       const recorded = existsSync(pidFile) ? readFileSync(pidFile, 'utf8').trim() : '';
       const pid = db === 'native-postgres-data' && recorded ? JSON.parse(recorded).pid : Number(recorded);
       let live = false;
@@ -121,6 +138,7 @@ function refuseLiveDatabases(from: WorldInstance, dbs: string[]): void {
 function requireMatchingBackings(source: string[], child: string[]): void {
   const kinds = {
     postgres: ['native-postgres-data', 'pglite-postgres-data'],
+    mysql: ['native-mariadb-data'],
     mongodb: ['mongod-mongodb-data'],
   };
   for (const [kind, formats] of Object.entries(kinds)) {
@@ -158,15 +176,15 @@ async function branchManagedDatabases(from: WorldInstance, instance: WorldInstan
   const infrastructure = config.services.find((service) => service.type === 'external' && (service.external?.up[0] === 'volter-world-infra' || service.id === 'infrastructure'));
   if (!infrastructure) throw new Error(`volter-world branch: ${instance.name}'s managed databases have no declared infrastructure service`);
   const launch = { env: externalServiceEnv(infrastructure, instance.dirs, instance.env, config.stripEnv) };
-  if (dbs.includes('native-postgres-data')) {
+  if (dbs.some(directory => ['native-postgres-data', 'native-mariadb-data', 'clickhouse-twin'].includes(directory))) {
     const io = { out: (text: string) => process.stdout.write(text), err: (text: string) => process.stderr.write(text) };
-    if (await runInfrastructure('down', launch.env, io) !== 0) throw new Error('managed native database branch could not stop its new backing');
+    if (await runInfrastructure('down', launch.env, io) !== 0) throw new Error('managed database branch could not stop its new backing');
     for (const db of dbs) {
       const to = join(instance.dirs.data, db);
       rmSync(to, { recursive: true, force: true });
       cpSync(join(from.dirs.data, db), to, { recursive: true });
     }
-    if (await runInfrastructure('up', launch.env, io) !== 0) throw new Error('managed native database branch could not resume its copied backing');
+    if (await runInfrastructure('up', launch.env, io) !== 0) throw new Error('managed database branch could not resume its copied backing');
     return;
   }
   const redisCli = dbs.includes('redis-twin') && redis.length ? redisTwinCli([dirname(fileURLToPath(import.meta.url)), dirname(instance.configPath)]) : undefined;

package/src/browser-files.ts

@@ -0,0 +1,15 @@
+import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime-state';
+import { dirname, join } from 'node:path';
+
+/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
+export const browsersDir = (data: string): string => join(dirname(data), 'browser-records');
+
+/** Empty Worlds need no browser validators or cookie/load machinery. A prior
+ * projection still loads the ordinary materializer to remove stale files. */
+export async function materializeWorldBrowserFiles(data: string, root: string, name: string, main = name): Promise<void> {
+  const store = getActiveWorldStore();
+  if (!store.list(browsersDir(data)).some(file => file.endsWith('.json'))
+    && store.read(join(root, stateDirName(), 'browsers', '.source.json')) === null) return;
+  const { materializeBrowserFiles } = await import('./browsers.ts');
+  materializeBrowserFiles(data, root, name, main);
+}

package/src/browsers.ts

@@ -1,11 +1,11 @@
-import { assertBrowserName, validateBrowserState, type BrowserState } from '@volter/world-core';
-import { getActiveWorldStore, stateDirName, type WorldStore } from '@volter/world-core/runtime';
+import { assertBrowserName, validateBrowserState, type BrowserState } from '@volter/world-core/browser-state';
+import { getActiveWorldStore, stateDirName, type WorldStore } from '@volter/world-core/runtime-state';
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
 
 export type WorldBrowser = { name: string; state: BrowserState; version: string };
-/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
-export const browsersDir = (data: string): string => join(dirname(data), 'browser-records');
+import { browsersDir } from './browser-files.ts';
+export { browsersDir } from './browser-files.ts';
 const path = (data: string, name: string): string => { assertBrowserName(name); return join(browsersDir(data), `${name}.json`); };
 const records = new WeakMap<WorldStore, Map<string, { version: string; text: string; record: WorldBrowser }>>();
 export function worldBrowser(data: string, name: string): WorldBrowser | null {

package/src/catalog.ts

@@ -9,7 +9,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { join, resolve } from 'node:path';
 import { overlayPackFacts, type PackFacts } from './pack-facts.ts';
-import { installedPackageDir, installedVendorPacks, isDerivedPack, packRepository } from '@volter/world-core/runtime';
+import { installedPackageDir, installedVendorPacks, isDerivedPack, packRepository } from '@volter/world-core/runtime-state';
 
 export const TWIN_PACKAGE_PREFIX = '@volter/twin-';
 
@@ -156,7 +156,7 @@ export function packFactsFile(dir: string): string | undefined {
 
 /** The catalog for a World root: its pack repository (or the one beside its platform checkout), merged with installed
  *  packages. Only the selected packs' own facts are overlaid on the kernel's. */
-export function resolveCatalog(root: string, options: { sources?: Readonly<Record<string, string>>; vendors?: readonly string[] } = {}): Catalog {
+export function resolveCatalog(root: string, options: { sources?: Readonly<Record<string, string>>; vendors?: readonly string[]; mayBeEmpty?: boolean } = {}): Catalog {
   const resolved = resolve(root);
   const installed = installedCatalog(resolved, options);
   const repo = packRepository(resolved);
@@ -165,7 +165,8 @@ export function resolveCatalog(root: string, options: { sources?: Readonly<Recor
     const file = packFactsFile(catalog.packDir(vendor)!);
     if (file) overlayPackFactsFile(file);
   }
-  if (catalog.vendors().length === 0) {
+  // A World whose application runs beside infrastructure alone has no twin to find (`init --needs`, architecture).
+  if (catalog.vendors().length === 0 && !options.mayBeEmpty) {
     throw new Error(
       `No twins found for ${resolved}: no pack repository and no \`@volter/twin-<vendor>\` package installed above it. `
       + `Install the twins your app needs (e.g. \`bun add -d @volter/twin-stripe\`) and run init again.`,

package/src/changeset.ts

@@ -641,7 +641,7 @@ export function rebaseWorldChangeset(name: string, options: WorldRootOptions & {
   const moved = [...new Set(located.changeset.actions.map((e) => e.service))].map((service) => ({ st: located.changeset.actions.find((e) => e.service === service)?.stateService ?? service, controlRoot: join(inst.dirs.data, service) }));
   withHistoryLocks(moved.map(({ st, controlRoot }) => worldPaths(st, controlRoot).dir), () => {
     for (const { st, controlRoot } of moved) rebaseBranch(st, controlRoot, { origin: Boolean(readBranchMeta(st, controlRoot)?.origin) });
-  });
+  }, { operation: 'branch-pointer adjustment' });
   if (!changesetHashMatches(located.changeset)) throw new Error(`Refusing to rebase changeset "${name}": its stored contentHash does not match its body — the object drifted after authoring`);
   const instance = requireWorld(located.world, root);
   const targets: RebaseTarget[] = [...new Set(located.changeset.actions.map((entry) => entry.service))].map((service) => ({ service, stateService: located.changeset.actions.find((entry) => entry.service === service)!.stateService, controlRoot: join(instance.dirs.data, service) }));