@volter/world-runtime 2.0.54 → 3.0.0

package/dist/src/catalog.js

@@ -1,16 +1,19 @@
 // The catalog — where the twins a world can run come from (docs/concepts/worlds.md
-// #the-config-and-the-running-world). Two sources answer one interface: this CHECKOUT (`packages/twin/<vendor>/`, the
-// catalog as the repo holds it) and an INSTALLED catalog (`@volter/twin-<vendor>` packages under
+// #the-config-and-the-running-world). Two sources answer one interface: a pack-repository CHECKOUT and an
+// INSTALLED catalog (`@volter/twin-<vendor>` packages under
 // `node_modules`, walked up from the world root — hoisting-proof, and independent of the
 // packages' `exports` maps, which do not expose `package.json`). A world born in an app repo
 // names its twins as packages and the runtime resolves them at boot; a world born here names the
-// checkout-relative paths, as before.
+// selected checkout paths.
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
+import { overlayPackFacts } from "./pack-facts.js";
+import { installedPackageDir, isDerivedPack, packRepository } from '@volter/world-core/runtime';
 export const TWIN_PACKAGE_PREFIX = '@volter/twin-';
-/** Packages under the `@volter/twin-` prefix that are NOT twins. */
 export function twinPackageName(vendor) { return `${TWIN_PACKAGE_PREFIX}${vendor}`; }
+/** A derived (Protocol 3) pack carries the surface derive-pack generated from its spec. */
+const major = (version) => Number(/^(\d+)/.exec(version ?? '')?.[1] ?? 0);
 function packageVersion(dir) {
     const p = join(dir, 'package.json');
     if (!existsSync(p))
@@ -23,7 +26,8 @@ function packageVersion(dir) {
         return undefined;
     }
 }
-function isPackDir(dir) { return packCli(dir) !== undefined; }
+/** A twin a catalog lists: a derived pack with its CLI. */
+function isPackDir(dir) { return packCli(dir) !== undefined && isDerivedPack(dir); }
 function manifest(dir) { const p = join(dir, 'package.json'); if (!existsSync(p))
     return undefined; try {
     return JSON.parse(readFileSync(p, 'utf8'));
@@ -51,18 +55,7 @@ export function packCli(dir) {
     return existsSync(join(dir, 'src', 'cli.ts')) ? join(dir, 'src', 'cli.ts') : undefined;
 }
 /** The nearest `node_modules/<name>` above `from` that holds a package.json — node's own walk. */
-export function findInstalledPackage(from, name) {
-    let dir = resolve(from);
-    for (;;) {
-        const candidate = join(dir, 'node_modules', ...name.split('/'));
-        if (existsSync(join(candidate, 'package.json')))
-            return candidate;
-        const up = dirname(dir);
-        if (up === dir)
-            return undefined;
-        dir = up;
-    }
-}
+export const findInstalledPackage = installedPackageDir;
 /** Every installed `@volter/twin-<vendor>` visible from `from`, nearest wins. */
 function installedTwins(from) {
     const found = new Map();
@@ -74,6 +67,8 @@ function installedTwins(from) {
                 if (!entry.isDirectory() && !entry.isSymbolicLink())
                     continue;
                 const name = `@volter/${entry.name}`;
+                if (name === '@volter/twin-standard')
+                    continue; // the platform's standard is tooling, not a vendor pack
                 if (!name.startsWith(TWIN_PACKAGE_PREFIX))
                     continue; // the platform's packages are `@volter/world-*`: outside the prefix by name
                 const vendor = name.slice(TWIN_PACKAGE_PREFIX.length);
@@ -98,17 +93,18 @@ function fnv1a(text) {
     return h.toString(16).padStart(8, '0');
 }
 export function checkoutCatalog(root) {
-    const packsDir = resolve(root, 'packages', 'twin');
+    const packsDir = resolve(root);
     const vendors = () => readdirSync(packsDir, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory() && isPackDir(join(packsDir, entry.name)))
+        .filter((entry) => (entry.isDirectory() || entry.isSymbolicLink()) && manifest(join(packsDir, entry.name))?.name === twinPackageName(entry.name) && isPackDir(join(packsDir, entry.name)))
         .map((entry) => entry.name)
         .sort();
     return {
         kind: 'checkout',
         root: resolve(root),
         vendors,
-        packDir: (vendor) => (isPackDir(join(packsDir, vendor)) ? join(packsDir, vendor) : undefined),
+        packDir: (vendor) => (/^[a-z][a-z0-9-]*$/.test(vendor) && manifest(join(packsDir, vendor))?.name === twinPackageName(vendor) && isPackDir(join(packsDir, vendor)) ? join(packsDir, vendor) : undefined),
         version: (vendor) => packageVersion(join(packsDir, vendor)),
+        kindOf: () => 'checkout',
         sha: () => {
             const proc = spawnSync('git', ['-C', root, 'rev-parse', 'HEAD'], { windowsHide: true, encoding: 'utf8' });
             const sha = proc.status === 0 ? proc.stdout.trim() : '';
@@ -124,20 +120,67 @@ export function installedCatalog(root) {
         vendors: () => [...twins.keys()].sort(),
         packDir: (vendor) => twins.get(vendor),
         version: (vendor) => { const dir = twins.get(vendor); return dir === undefined ? undefined : packageVersion(dir); },
+        kindOf: () => 'installed',
         sha: () => `installed-${fnv1a([...twins.keys()].sort().map((v) => `${v}@${packageVersion(twins.get(v)) ?? '?'}`).join(','))}`,
     };
 }
-/** The catalog for a world root: the checkout when `packages/twin` is there, else what is installed. */
+/**
+ * One catalog over several sources (docs/contributing/architecture.md, "The catalog: where twins come from"): each
+ * vendor is served by the pack of the higher major; on a tie the earlier source keeps it. `kind` is the first source's.
+ */
+export function mergedCatalog(sources) {
+    const chosen = new Map();
+    for (const source of sources) {
+        for (const vendor of source.vendors()) {
+            const held = chosen.get(vendor);
+            if (held === undefined) {
+                chosen.set(vendor, source);
+                continue;
+            }
+            if (major(source.version(vendor)) > major(held.version(vendor)))
+                chosen.set(vendor, source);
+        }
+    }
+    const of = (vendor) => chosen.get(vendor);
+    return {
+        kind: sources[0].kind,
+        root: sources[0].root,
+        vendors: () => [...chosen.keys()].sort(),
+        packDir: (vendor) => of(vendor)?.packDir(vendor),
+        version: (vendor) => of(vendor)?.version(vendor),
+        kindOf: (vendor) => of(vendor)?.kindOf(vendor) ?? sources[0].kind,
+        sha: () => sources.map((s) => s.sha()).join('+'),
+    };
+}
+/** Overlays one facts file on the kernel's (a file that does not read is skipped: the kernel's facts stand). */
+export function overlayPackFactsFile(file) {
+    try {
+        overlayPackFacts(JSON.parse(readFileSync(file, 'utf8')).packs ?? {});
+    }
+    catch { /* the kernel's facts stand */ }
+}
+/** The facts file a released pack carries (`generated/pack-facts.json`, written by pack-release), when it has one. */
+export function packFactsFile(dir) {
+    const file = join(dir, 'generated', 'pack-facts.json');
+    return existsSync(file) ? file : 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) {
     const resolved = resolve(root);
-    if (existsSync(join(resolved, 'packages', 'twin')))
-        return checkoutCatalog(resolved);
     const installed = installedCatalog(resolved);
-    if (installed.vendors().length === 0) {
-        throw new Error(`No twins found for ${resolved}: no \`packages/twin\` catalog here and no \`@volter/twin-<vendor>\` package installed above it. `
+    const repo = packRepository(resolved);
+    const catalog = repo === undefined ? installed : mergedCatalog([checkoutCatalog(repo), installed]);
+    for (const vendor of catalog.vendors()) {
+        const file = packFactsFile(catalog.packDir(vendor));
+        if (file)
+            overlayPackFactsFile(file);
+    }
+    if (catalog.vendors().length === 0) {
+        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.`);
     }
-    return installed;
+    return catalog;
 }
 /** The pack directory a service boots from: its `package` resolved from the world root at boot. */
 export function resolveServicePackage(root, pkg) {

package/dist/src/changeset.d.ts

@@ -1,4 +1,4 @@
-import type { ChangesetApplication, RebaseReport, Changeset, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, LedgerDelta, LedgerRef, ReplayReport, WorldMarker } from '@volter/world-core';
+import type { ChangesetApplication, RebaseReport, Changeset, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, LedgerDelta, LedgerRef, ReplayReport, WorldMarker } from '@volter/world-core/runtime';
 export type WorldRootOptions = {
     root?: string;
 };

package/dist/src/changeset.js

@@ -1,5 +1,5 @@
 import { worldChangesetRules } from "./configs.js";
-import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, withAncestryLock, worldPaths } from '@volter/world-core';
+import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, withHistoryLocks, worldPaths } from '@volter/world-core/runtime';
 // `volter-world mark` / `diff` / `changeset` — the WORLD-side verbs over the changeset
 // primitive (docs/concepts/the-model.md v0). Thin, exactly like `covers` and `tail` are thin: all
 // the state logic (markers, deltas, content hashing, replay) lives in @volter/world-core's
@@ -24,12 +24,12 @@ import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, g
 // here that WRITES, and it writes only through the control plane's kernel write path.
 import { tmpdir } from 'node:os';
 import { join, relative, resolve } from 'node:path';
-import { approveChangeset, rebaseChangeset, buildChangeset, captureMarker, changesetHashMatches, changesetReadiness, diffLedgers, normalizeChangeset, replayChangeset, runChangesetVerifiers, stateDirName, withApplication, withVerification, worldBootMarker, assertSafeChangesetName, assertMarkerBelongsTo, CHANGESET_KIND, MARKER_KIND, WORLD_BOOT_MARKER_ID, } from '@volter/world-core';
+import { approveChangeset, rebaseChangeset, buildChangeset, captureMarker, changesetHashMatches, changesetReadiness, diffLedgers, normalizeChangeset, replayChangeset, runChangesetVerifiers, stateDirName, withApplication, withVerification, worldBootMarker, assertSafeChangesetName, assertMarkerBelongsTo, CHANGESET_KIND, MARKER_KIND, WORLD_BOOT_MARKER_ID, } from '@volter/world-core/runtime';
 import { instanceDir, listWorlds, statusWorld } from "./runtime.js";
 import { fetchFromOrigin } from "./origin.js";
 import { fetchReady, isPathRemote, landChangeset, landReceipts, localWorld, TOKEN_HEADER } from "./served-world.js";
 import { loadWorldChecks } from "./root.js";
-import { readBranchMeta, readTree, rebaseBranch, runChecks, wholeLog, writeBranchMeta } from '@volter/world-core';
+import { readBranchMeta, readTree, rebaseBranch, runChecks, wholeLog, writeBranchMeta } from '@volter/world-core/runtime';
 function resolveRoot(root) {
     return resolve(root ?? process.cwd());
 }
@@ -44,7 +44,7 @@ function requireWorld(name, root) {
         if (!/World instance not found/.test(String(error.message)))
             throw error;
         const known = listWorlds(root).map((world) => world.name);
-        throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-out <path> --name ${name}\``);
+        throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — start it with \`volter world up\` in the app's folder (the operator's own: \`volter-world up <config> --env-out <path> --name ${name}\`)`);
     }
 }
 /** Every state service a world service currently records actions under (often exactly one). */
@@ -166,7 +166,7 @@ export function createWorldChangeset(world, name, options = {}) {
     // re-cutting an existing name (overwrite) starts from that changeset's own base, not from its cut
     const base = options.base ?? (getActiveWorldStore().exists(path) ? readChangesetFile(path).base : undefined);
     const delta = diffWorld(world, { root, ...(base === undefined ? {} : { base }) });
-    // where the parent log stands for each twin the changeset touches (PROTOCOL 2: the cut position a rebase reads from)
+    // where the parent log stands for each twin the changeset touches (the cut position a rebase reads from)
     const cutInstance = requireWorld(world, root);
     const cut = {};
     for (const a of delta.actions)
@@ -555,13 +555,11 @@ export function rebaseWorldChangeset(name, options = {}) {
     const root = resolveRoot(options.root);
     const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
     // the branch first: its pointer moves to the parent's current position (what a fetch brought in)
-    withAncestryLock(() => {
-        const inst = requireWorld(located.world, root);
-        for (const service of new Set(located.changeset.actions.map((e) => e.service))) {
-            const st = located.changeset.actions.find((e) => e.service === service)?.stateService ?? service;
-            const controlRoot = join(inst.dirs.data, service);
+    const inst = requireWorld(located.world, root);
+    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) });
-        }
     });
     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`);

package/dist/src/cli-args.d.ts

@@ -0,0 +1,4 @@
+/** The command line's option readers, shared by `up` (./up-cli.ts) and every other command (./cli-commands.ts). */
+/** An option's value, written `--name value` or `--name=value`. */
+export declare function optionValue(args: string[], name: string, fallback?: string): string;
+export declare function ownerOption(args: string[]): string | undefined;

package/dist/src/cli-args.js

@@ -0,0 +1,18 @@
+/** The command line's option readers, shared by `up` (./up-cli.ts) and every other command (./cli-commands.ts). */
+/** An option's value, written `--name value` or `--name=value`. */
+export function optionValue(args, name, fallback = '') {
+    const joined = args.find((arg) => arg.startsWith(`${name}=`));
+    if (joined !== undefined)
+        return joined.slice(name.length + 1);
+    const index = args.indexOf(name);
+    return index >= 0 && index + 1 < args.length ? args[index + 1] : fallback;
+}
+export function ownerOption(args) {
+    const index = args.indexOf('--owner');
+    if (index < 0)
+        return undefined;
+    const label = args[index + 1];
+    if (!label || label.startsWith('--'))
+        throw new Error('--owner requires a task label');
+    return label;
+}

package/dist/src/cli-commands.d.ts

@@ -0,0 +1 @@
+export declare function main(): Promise<void>;