@volter/world-runtime 3.0.163 → 3.0.165

package/dist/src/ancestry.js

@@ -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, path) {
     const base = join(root, stateDirName(), 'worlds');
     if (!existsSync(base))
@@ -35,7 +35,7 @@ function checkWorldAncestry(root, path) {
     }
 }
 export function assertWorldStateRemovable(root, path) {
-    withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); });
+    withAncestryLock(() => { checkWorldAncestry(root, path); assertStateRemovable(path); }, { operation: 'removal preflight' });
 }
 export function removeWorldState(root, path, remove) {
     return withStateRemoval(path, remove, () => checkWorldAncestry(root, path));

package/dist/src/app-url.d.ts

@@ -22,7 +22,11 @@ export declare function setAppUrl(name: string, url: string, options?: {
     root?: string;
     via?: Exclude<AppUrlSource, 'service'>;
     detail?: string;
-    app?: 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;
 /** Record `hosts` as the app's own production hostnames, beside its recorded URL (or its `app` service's). */
 export declare function addAppHosts(name: string, hosts: string[], options?: {

package/dist/src/app-url.js

@@ -21,7 +21,7 @@
 // instance it described.
 import { errorMessage } from "./error-message.js";
 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';
@@ -89,8 +89,21 @@ function assertHttpUrl(url) {
 export function setAppUrl(name, url, options = {}) {
     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, name, app, url, status, options) {
     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/dist/src/branch.js

@@ -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.js";
-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';
@@ -48,7 +48,7 @@ export async function branchWorld(base, name, options = {}) {
                 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)) {
@@ -90,32 +90,51 @@ export async function branchWorld(base, name, options = {}) {
     return { instance, forked };
 }
 /** 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) {
     const data = from.dirs.data;
     if (!existsSync(data))
         return [];
-    const known = (name) => /^pglite-[a-z0-9_-]+-data$/.test(name) || name === 'mongod-mongodb-data' || name === 'native-postgres-data';
+    const known = (name) => /^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, db) {
+    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`)];
 }
 /** A copy of a live database directory is not a consistent one, and the branch's database would answer on the base's
  *  port: the base must be stopped first (`volter world branch` stops it, as a branch replaces its base). */
 function refuseLiveDatabases(from, dbs) {
     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;
@@ -137,6 +156,7 @@ function refuseLiveDatabases(from, dbs) {
 function requireMatchingBackings(source, child) {
     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)) {
@@ -179,17 +199,17 @@ async function branchManagedDatabases(from, instance, dbs) {
     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) => process.stdout.write(text), err: (text) => 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');
+            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');
+            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/dist/src/browser-files.d.ts

@@ -0,0 +1,5 @@
+/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
+export declare const browsersDir: (data: string) => string;
+/** Empty Worlds need no browser validators or cookie/load machinery. A prior
+ * projection still loads the ordinary materializer to remove stale files. */
+export declare function materializeWorldBrowserFiles(data: string, root: string, name: string, main?: string): Promise<void>;

package/dist/src/browser-files.js

@@ -0,0 +1,14 @@
+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) => 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, root, name, main = name) {
+    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.js");
+    materializeBrowserFiles(data, root, name, main);
+}

package/dist/src/browsers.d.ts

@@ -1,11 +1,10 @@
-import { type BrowserState } from '@volter/world-core';
+import { type BrowserState } from '@volter/world-core/browser-state';
 export type WorldBrowser = {
     name: string;
     state: BrowserState;
     version: string;
 };
-/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
-export declare const browsersDir: (data: string) => string;
+export { browsersDir } from './browser-files.js';
 export declare function worldBrowser(data: string, name: string): WorldBrowser | null;
 export declare function worldBrowsers(data: string): WorldBrowser[];
 export declare function putWorldBrowser(data: string, name: string, state: unknown): WorldBrowser;

package/dist/src/browsers.js

@@ -1,9 +1,9 @@
-import { assertBrowserName, validateBrowserState } from '@volter/world-core';
-import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime';
+import { assertBrowserName, validateBrowserState } from '@volter/world-core/browser-state';
+import { getActiveWorldStore, stateDirName } from '@volter/world-core/runtime-state';
 import { createHash, randomUUID } from 'node:crypto';
 import { dirname, join } from 'node:path';
-/** Instance bookkeeping, alongside the clock; retained at down, discarded at reset. */
-export const browsersDir = (data) => join(dirname(data), 'browser-records');
+import { browsersDir } from "./browser-files.js";
+export { browsersDir } from "./browser-files.js";
 const path = (data, name) => { assertBrowserName(name); return join(browsersDir(data), `${name}.json`); };
 const records = new WeakMap();
 export function worldBrowser(data, name) {

package/dist/src/catalog.d.ts

@@ -1,4 +1,4 @@
-import { installedPackageDir } from '@volter/world-core/runtime';
+import { installedPackageDir } from '@volter/world-core/runtime-state';
 export declare const TWIN_PACKAGE_PREFIX = "@volter/twin-";
 export declare function twinPackageName(vendor: string): string;
 export type CatalogKind = 'checkout' | 'installed';
@@ -45,6 +45,7 @@ export declare function packFactsFile(dir: string): string | undefined;
 export declare function resolveCatalog(root: string, options?: {
     sources?: Readonly<Record<string, string>>;
     vendors?: readonly string[];
+    mayBeEmpty?: boolean;
 }): Catalog;
 /** The pack directory a service boots from: its `package` resolved from the world root at boot. */
 export declare function resolveServicePackage(root: string, pkg: string): string;

package/dist/src/catalog.js

@@ -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 } from "./pack-facts.js";
-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-';
 export function twinPackageName(vendor) { return `${TWIN_PACKAGE_PREFIX}${vendor}`; }
 /** A derived (Protocol 3) pack carries the surface derive-pack generated from its spec. */
@@ -85,7 +85,10 @@ export function checkoutCatalog(root) {
     };
 }
 export function installedCatalog(root, options = {}) {
-    const twins = new Map([...installedVendorPacks(root, options)].filter(([, dir]) => packCli(dir) !== undefined));
+    // An explicit empty selection needs no package discovery or publisher choice.
+    const twins = options.vendors?.length === 0
+        ? new Map()
+        : new Map([...installedVendorPacks(root, options)].filter(([, dir]) => packCli(dir) !== undefined));
     return {
         kind: 'installed',
         root: resolve(root),
@@ -152,6 +155,8 @@ export function packFactsFile(dir) {
 export function resolveCatalog(root, options = {}) {
     const resolved = resolve(root);
     const installed = installedCatalog(resolved, options);
+    if (options.vendors?.length === 0)
+        return installed;
     const repo = packRepository(resolved);
     const catalog = repo === undefined ? installed : mergedCatalog([checkoutCatalog(repo), installed]);
     for (const vendor of catalog.vendors()) {
@@ -159,7 +164,8 @@ export function resolveCatalog(root, options = {}) {
         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/dist/src/changeset.js

@@ -586,7 +586,7 @@ export function rebaseWorldChangeset(name, options = {}) {
     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);