@volter/world-runtime 2.0.54 → 3.0.0

package/src/catalog-index.ts

@@ -0,0 +1,44 @@
+// The catalog index as the runtime reads it (docs/contributing/architecture.md, "The catalog: where twins come from"):
+// its sources, its vendors' packages and versions, and each vendor's default twin. The index is a directory of data (the
+// `volter-ai/twin-catalog` repository, published as the npm package `@volter/twin-catalog`); scripts/twin-catalog.ts
+// checks and writes it, and `init` reads the defaults from the installed package.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** The index as npm carries it. */
+export const CATALOG_INDEX_PACKAGE = '@volter/twin-catalog';
+
+/** A source; `workflow` is the file under `.github/workflows/` its packages are released by (release.yml unless named). */
+export type Source = { name: string; repository: string; scope: string; official: boolean; protocol: '3'; workflow?: string };
+export type Version = { version: string; status: 'live' | 'pending' | 'rejected'; at: string; by: string; reason?: string; commit?: string };
+export type Entry = { vendor: string; packages: Array<{ name: string; source: string; versions: Version[] }> };
+
+export const readSources = (index: string): Source[] => JSON.parse(readFileSync(join(index, 'sources.json'), 'utf8')) as Source[];
+export function readVendors(index: string): Entry[] {
+  const dir = join(index, 'vendors');
+  return existsSync(dir) ? readdirSync(dir).filter((f) => f.endsWith('.json')).sort().map((f) => JSON.parse(readFileSync(join(dir, f), 'utf8')) as Entry) : [];
+}
+/** A package's vendor: `@volter/twin-<vendor>`, or the part after `twin-` in any scope. */
+export const vendorOf = (name: string): string => name.replace(/^@[^/]+\//, '').replace(/^twin-/, '');
+
+const semver = (v: string): number[] => v.split(/[.-]/).slice(0, 3).map((n) => Number(n) || 0);
+const newer = (a: string, b: string): number => { const x = semver(a); const y = semver(b); for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i]! - y[i]!; return 0; };
+
+/** Each vendor's default twin: its official package, else its live outside package; the
+ *  highest live version of it. */
+export function defaults(index: string): Record<string, { name: string; version: string; source: string }> {
+  const sources = new Map(readSources(index).map((s) => [s.name, s]));
+  const rank = (s: Source | undefined): number => (!s ? 0 : s.official ? 2 : 1);
+  const out: Record<string, { name: string; version: string; source: string }> = {};
+  for (const e of readVendors(index)) {
+    const candidates = e.packages
+      .map((p) => ({ p, s: sources.get(p.source), live: p.versions.filter((v) => v.status === 'live').sort((a, b) => newer(b.version, a.version))[0] }))
+      .filter((c) => c.live && c.s)
+      .sort((a, b) => rank(b.s) - rank(a.s));
+    const best = candidates[0];
+    // an outside twin is a default only where no official twin is
+    if (best && (best.s!.official || candidates.every((c) => !c.s!.official))) out[e.vendor] = { name: best.p.name, version: best.live!.version, source: best.p.source };
+  }
+  return out;
+}
+

package/src/catalog.ts

@@ -1,18 +1,18 @@
 // 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, type PackFacts } from './pack-facts.ts';
+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: string): string { return `${TWIN_PACKAGE_PREFIX}${vendor}`; }
 
 export type CatalogKind = 'checkout' | 'installed';
@@ -29,15 +29,22 @@ export type Catalog = {
   version(vendor: string): string | undefined;
   /** The birth stamp: the checkout's git sha, or a digest of the installed versions. */
   sha(): string;
+  /** Where the vendor's pack comes from: this checkout or an installed package (a merged catalog's sources differ per
+   *  vendor, so a World boots each twin the way its own source serves it). */
+  kindOf(vendor: string): CatalogKind;
 };
 
+/** A derived (Protocol 3) pack carries the surface derive-pack generated from its spec. */
+const major = (version: string | undefined): number => Number(/^(\d+)/.exec(version ?? '')?.[1] ?? 0);
+
 function packageVersion(dir: string): string | undefined {
   const p = join(dir, 'package.json');
   if (!existsSync(p)) return undefined;
   try { const v = (JSON.parse(readFileSync(p, 'utf8')) as { version?: unknown }).version; return typeof v === 'string' ? v : undefined; } catch { return undefined; }
 }
 
-function isPackDir(dir: string): boolean { return packCli(dir) !== undefined; }
+/** A twin a catalog lists: a derived pack with its CLI. */
+function isPackDir(dir: string): boolean { return packCli(dir) !== undefined && isDerivedPack(dir); }
 
 type Manifest = { name?: string; exports?: unknown; main?: string; bin?: Record<string, string> | string };
 function manifest(dir: string): Manifest | undefined { const p = join(dir, 'package.json'); if (!existsSync(p)) return undefined; try { return JSON.parse(readFileSync(p, 'utf8')) as Manifest; } catch { return undefined; } }
@@ -62,16 +69,7 @@ export function packCli(dir: string): string | undefined {
 }
 
 /** The nearest `node_modules/<name>` above `from` that holds a package.json — node's own walk. */
-export function findInstalledPackage(from: string, name: string): string | undefined {
-  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: string): Map<string, string> {
@@ -83,6 +81,7 @@ function installedTwins(from: string): Map<string, string> {
       for (const entry of readdirSync(scope, { withFileTypes: true })) {
         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);
         const packDir = join(scope, entry.name);
@@ -103,17 +102,18 @@ function fnv1a(text: string): string {
 }
 
 export function checkoutCatalog(root: string): Catalog {
-  const packsDir = resolve(root, 'packages', 'twin');
+  const packsDir = resolve(root);
   const vendors = (): string[] => 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() : '';
@@ -130,22 +130,65 @@ export function installedCatalog(root: string): Catalog {
     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: Catalog[]): Catalog {
+  const chosen = new Map<string, Catalog>();
+  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: string): Catalog | undefined => 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: string): void {
+  try { overlayPackFacts((JSON.parse(readFileSync(file, 'utf8')) as { packs?: Record<string, PackFacts> }).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: string): string | undefined {
+  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: string): Catalog {
   const resolved = resolve(root);
-  if (existsSync(join(resolved, 'packages', 'twin'))) return checkoutCatalog(resolved);
   const installed = installedCatalog(resolved);
-  if (installed.vendors().length === 0) {
+  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 \`packages/twin\` catalog here and no \`@volter/twin-<vendor>\` package installed above it. `
+      `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. */

package/src/changeset.ts

@@ -1,5 +1,5 @@
 import { worldChangesetRules } from './configs.ts';
-import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, originHead, withAncestryLock, worldPaths, type HistoryReference } from '@volter/world-core';
+import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, originHead, withHistoryLocks, worldPaths, type HistoryReference } 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
@@ -44,14 +44,14 @@ import {
   CHANGESET_KIND,
   MARKER_KIND,
   WORLD_BOOT_MARKER_ID,
-} from '@volter/world-core';
-import type { ApplyReceipt, Receipt, ChangesetApplication, RebaseReport, RebaseTarget, Changeset, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, LedgerDelta, LedgerRef, ReplayReport, ReplayTarget, WorldMarker } from '@volter/world-core';
+} from '@volter/world-core/runtime';
+import type { ApplyReceipt, Receipt, ChangesetApplication, RebaseReport, RebaseTarget, Changeset, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, LedgerDelta, LedgerRef, ReplayReport, ReplayTarget, WorldMarker } from '@volter/world-core/runtime';
 import { instanceDir, listWorlds, saveWorldInstance, statusWorld } from './runtime.ts';
 import { fetchFromOrigin } from './origin.ts';
 import type { WorldInstance } from './schema.ts';
 import { fetchReady, isPathRemote, landChangeset, landReceipts, localWorld, TOKEN_HEADER } from './served-world.ts';
 import { loadWorldChecks } from './root.ts';
-import { originEntries, parentEntries, readBranchMeta, readTree, rebaseBranch, runChecks, wholeLog, writeBranchMeta } from '@volter/world-core';
+import { originEntries, parentEntries, readBranchMeta, readTree, rebaseBranch, runChecks, wholeLog, writeBranchMeta } from '@volter/world-core/runtime';
 
 export type WorldRootOptions = { root?: string };
 
@@ -68,7 +68,7 @@ function requireWorld(name: string, root: string): WorldInstance {
   } catch (error) {
     if (!/World instance not found/.test(String((error as 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}\`)`);
   }
 }
 
@@ -215,7 +215,7 @@ export function createWorldChangeset(
   // 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: Record<string, HistoryReference> = {};
   for (const a of delta.actions) if (!(a.service in cut)) { const cr = join(cutInstance.dirs.data, a.service); const st = a.stateService ?? a.service; cut[a.service] = captureParentHistory(st, cr); }
@@ -614,13 +614,10 @@ export function rebaseWorldChangeset(name: string, options: WorldRootOptions & {
   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);
-      rebaseBranch(st, controlRoot, { origin: Boolean(readBranchMeta(st, controlRoot)?.origin) });
-    }
+  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`);
   const instance = requireWorld(located.world, root);

package/src/cli-args.ts

@@ -0,0 +1,17 @@
+/** 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: string[], name: string, fallback = ''): string {
+  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: string[]): string | undefined {
+  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;
+}