@volter/world-runtime 2.0.55 → 3.0.0

package/dist/src/up-cli.js

@@ -0,0 +1,55 @@
+// `volter-world up`, loaded on its own (./cli.ts): it hands the boot to its owner process (./up-task.ts) before
+// any other command's modules load, so a World's start never waits on them. Where each module is compiled as
+// the process starts (a browser tab's engine compiles every module it loads), those modules were most of the
+// CLI's time before the owner process began.
+import { optionValue, ownerOption } from "./cli-args.js";
+import { superviseWorldUp } from "./up-task.js";
+export async function upCommand(subject, rest, root) {
+    if (rest.some(arg => arg === '--env-file' || arg.startsWith('--env-file=')))
+        throw new Error('--env-file is not an input for this command. Use --env-out=<new-output-path>; never pass credentials or custody as an output.');
+    if (!subject)
+        throw new Error('volter-world up: missing config');
+    const envFile = optionValue(rest, '--env-out');
+    if (!envFile)
+        throw new Error('volter-world up: missing required --env-out=<path>');
+    const name = optionValue(rest, '--name') || undefined;
+    const mode = optionValue(rest, '--mode', 'local');
+    const isolationArg = optionValue(rest, '--isolation');
+    if (isolationArg && isolationArg !== 'process' && isolationArg !== 'colocated' && isolationArg !== 'worker') {
+        throw new Error(`volter-world up: invalid --isolation "${isolationArg}" (want process|colocated|worker)`);
+    }
+    const isolation = (isolationArg || undefined);
+    // The boot runs in its own owner process (./up-task.ts): a closed terminal does not leave it half-done.
+    // --keep-state: boot over the state the World's directory already holds (a World carried somewhere else, e.g. a
+    // browser tab's image, comes up over its data instead of starting empty, as a fresh `up` does)
+    const keepState = rest.includes('--keep-state');
+    const instance = await superviseWorldUp(subject, { name, root, mode, envFile, forceEnvOutput: rest.includes('--force'), owner: ownerOption(rest), ...(isolation ? { isolation } : {}), ...(keepState ? { keepState: true } : {}) });
+    printReady(instance);
+}
+export function printReady(instance) {
+    process.stdout.write(`World ${instance.name} is ready (${instance.config})
+
+Services:
+${Object.values(instance.services).map((service) => `  ${service.id}: ${service.url ?? '(no listener — a World output)'}`).join('\n')}
+
+This instance started CLEAN (a world's state lives only while it runs; the world dir is the
+reproducible story) — set the clock and run your seed now, after every up.
+
+The two moves: if the twin stores it, create it through the vendor's own API (seed as the
+person, move the clock first for history). Everything else — judgment, lookups, faults — is
+a handler in the world dir's handlers/<vendor>.json. EVERY twin explains itself at
+GET <url>/twin; a scripted twin's GET <url>/twin/scenario lists handlers + misses.
+
+Env:
+  ${instance.envFile}
+
+Instance:
+  ${instance.dirs.instance}/instance.json
+
+Stop:
+  volter-world down ${instance.name}
+
+For a bounded job, use volter-world run ... -- <command> to tear down automatically on exit.
+Persistent up does not expire or infer that your sessions are idle.
+`);
+}

package/dist/src/websocket-relay.d.ts

@@ -1,3 +1,3 @@
-import type { ServeHttpOptions } from '@volter/world-core';
+import type { ServeHttpOptions } from '@volter/world-core/runtime';
 /** A message relay for the World's TLS fronts. Transport state is connection-local. */
 export declare function websocketRelay(targetFor: (request: Request) => string | undefined): NonNullable<ServeHttpOptions['upgrade']>;

package/dist/src/world-origins.d.ts

@@ -8,6 +8,6 @@ export declare function worldOfHost(hostname: string, served: Iterable<string>,
 /** Whether a path under the console's base is a door of a World served here: a World whose org shares the console's
  *  name (`console/<world>`) has its doors at `/-/console/<world>/…`, and they are the World's, never the console's. */
 export declare function worldDoorUnderConsole(path: string, served: (name: string) => boolean, consoleBase: string): boolean;
-/** Whether a path on a World's origin belongs to that World (its wire, its doors, its mirrors) or to
+/** Whether a path on a World's origin belongs to that World (its wire, its doors, its vendors' screens) or to
  *  what every origin carries (`/-/ping`, the console): a World's origin serves no other World. */
 export declare function pathOfWorld(path: string, served: string, consoleBase: string): boolean;

package/dist/src/world-origins.js

@@ -30,7 +30,7 @@ export function worldDoorUnderConsole(path, served, consoleBase) {
     const m = /^\/-\/([^/]+)\/([^/]+)/.exec(path);
     return Boolean(m && served(`${m[1]}/${m[2]}`));
 }
-/** Whether a path on a World's origin belongs to that World (its wire, its doors, its mirrors) or to
+/** Whether a path on a World's origin belongs to that World (its wire, its doors, its vendors' screens) or to
  *  what every origin carries (`/-/ping`, the console): a World's origin serves no other World. */
 export function pathOfWorld(path, served, consoleBase) {
     return path === '/-/ping' || path === consoleBase || path.startsWith(`${consoleBase}/`) || path.startsWith(`/${served}/`) || path.startsWith(`/-/${served}/`) || path === `/${served}` || path === `/-/${served}`;

package/dist/src/world-view.d.ts

@@ -22,7 +22,7 @@ export declare function serveWorldView(name: string, opts?: {
     host?: string;
     console?: ViewConsole;
     announce?: (line: string) => void; /** each World a browser steps into at an origin of its own (on by default on loopback) */
-    origins?: boolean; /** the World's own origin as a browser reaches it through a proxy on this machine (a desktop serving it as an app):
+    origins?: boolean; /** the World's own origin as a browser reaches it through a proxy on this machine (an app that serves it as one of its own pages):
        *  a request the proxy forwards from that host (X-Forwarded-Host) is answered as at that origin, its local session included */
     origin?: string;
 }): Promise<WorldView>;

package/dist/src/world-view.js

@@ -1,11 +1,11 @@
-// THE LOCAL VIEW: one World served for a person to step into — its doors, its mirrors, its branches
+// THE LOCAL VIEW: one World served for a person to step into — its doors, its vendors' screens, its branches
 // ("as of" views) and the console, on one origin (docs/contributing/architecture.md, "Viewing a
 // World"). `volter world view` is this; the runtime's `up` gains no step. A host that serves many
 // Worlds (world-host) answers the same doors; this serves one, and the branches made of it.
 import { existsSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { loadWorldConfig } from "./configs.js";
 import { join, resolve } from 'node:path';
-import { serveHttp, stateDirName } from '@volter/world-core';
+import { serveHttp, stateDirName } from '@volter/world-core/runtime';
 import { LocalBranches } from "./local-branches.js";
 import { mountWorld } from "./served-world.js";
 import { localWorldOrigin, pathOfWorld, worldDoorUnderConsole, worldOfHost } from "./world-origins.js";

package/known-external-services.json

@@ -1,5 +1,5 @@
 {
-  "//": "PACKLESS-VENDOR REGISTRY — every external-service-shaped npm dep / env stem the catalog KNOWS but has no pack for, plus the not-a-service suppressions and the external-shape patterns. ONE home (absorbs covers.ts's inline NOT_AN_EXTERNAL_SERVICE / UNKNOWN_DEP_KNOWN_SERVICES / UNKNOWN_DEP_PATTERNS and the 2026-08-31 census rulings ledger — company-layer notes/census-rulings-2026-08-31.md). disposition 'demanded' = a real coverage gap, stays LOUD (the demand queue); 'acknowledged' = adjudicated acceptable, covers auto-acknowledges with the recorded reason. AN ENTRY DIES THE DAY ITS PACK IS BORN (scripts/packless-claims.test.ts enforces disjointness with pack adoption + SDK_TWINS).",
+  "//": "PACKLESS-VENDOR REGISTRY — every external-service-shaped npm dep / env stem the catalog KNOWS but has no pack for, plus the not-a-service suppressions and the external-shape patterns. ONE home (absorbs covers.ts's inline NOT_AN_EXTERNAL_SERVICE / UNKNOWN_DEP_KNOWN_SERVICES / UNKNOWN_DEP_PATTERNS and the 2026-08-31 census rulings ledger — company-layer notes/census-rulings-2026-08-31.md). disposition 'demanded' = a real coverage gap, stays LOUD (the demand queue); 'acknowledged' = adjudicated acceptable, covers auto-acknowledges with the recorded reason. AN ENTRY DIES THE DAY ITS PACK IS BORN (scripts/packless-claims.ts enforces disjointness with pack adoption + SDK_TWINS).",
   "deps": {
     "@1password/sdk": {
       "disposition": "demanded",
@@ -407,11 +407,11 @@
     },
     "bitly": {
       "disposition": "demanded",
-      "reason": "vendor bitly — the twin EXISTS (packages/twin/bitly, born 2026-09-02) and serves this client's traffic through the api-ssl.bitly.com injector entry. The npm name stays listed here rather than in the pack's adoption.sdks because `bitly` is a COMMUNITY wrapper, not a Bitly-published client (Bitly ships no first-party npm SDK; Dub's own importer uses plain fetch), and adoption.sdks is for official clients only."
+      "reason": "vendor bitly — the twin EXISTS (@volter/twin-bitly, born 2026-09-02) and serves this client's traffic through the api-ssl.bitly.com injector entry. The npm name stays listed here rather than in the pack's adoption.sdks because `bitly` is a COMMUNITY wrapper, not a Bitly-published client (Bitly ships no first-party npm SDK; Dub's own importer uses plain fetch), and adoption.sdks is for official clients only."
     },
     "paypal": {
       "disposition": "demanded",
-      "reason": "vendor paypal — the twin EXISTS (packages/twin/paypal, born 2026-09-13) and serves this consumer's payouts, webhooks and Log-in-with-PayPal traffic through the api(-m).(sandbox.)paypal.com and www.(sandbox.)paypal.com injector entries. The bare `paypal` npm name stays listed here rather than in the pack's adoption.sdks because it is NOT a PayPal-published client (PayPal's own npm clients are `paypal-rest-sdk`, which the pack DOES claim, and the @paypal/* checkout SDKs, which model Orders/Payments/Vault — surface this twin does not serve), and adoption.sdks is for official clients of the surface the pack can honor. The bitly precedent."
+      "reason": "vendor paypal — the twin EXISTS (@volter/twin-paypal, born 2026-09-13) and serves this consumer's payouts, webhooks and Log-in-with-PayPal traffic through the api(-m).(sandbox.)paypal.com and www.(sandbox.)paypal.com injector entries. The bare `paypal` npm name stays listed here rather than in the pack's adoption.sdks because it is NOT a PayPal-published client (PayPal's own npm clients are `paypal-rest-sdk`, which the pack DOES claim, and the @paypal/* checkout SDKs, which model Orders/Payments/Vault — surface this twin does not serve), and adoption.sdks is for official clients of the surface the pack can honor. The bitly precedent."
     },
     "googleads": {
       "disposition": "demanded",
@@ -419,7 +419,7 @@
     },
     "tiktok": {
       "disposition": "demanded",
-      "reason": "vendor tiktok — the twin EXISTS (packages/twin/tiktok, born 2026-09-13) and serves this vendor's traffic through the www.tiktok.com and open.tiktokapis.com injector entries. The npm name stays listed here rather than in the pack's adoption.sdks because `tiktok` is a COMMUNITY wrapper, not a TikTok-published client (TikTok ships no first-party npm SDK for Login Kit or the Display API; Dub's own integration uses plain fetch), and adoption.sdks is for official clients only."
+      "reason": "vendor tiktok — the twin EXISTS (@volter/twin-tiktok, born 2026-09-13) and serves this vendor's traffic through the www.tiktok.com and open.tiktokapis.com injector entries. The npm name stays listed here rather than in the pack's adoption.sdks because `tiktok` is a COMMUNITY wrapper, not a TikTok-published client (TikTok ships no first-party npm SDK for Login Kit or the Display API; Dub's own integration uses plain fetch), and adoption.sdks is for official clients only."
     }
   },
   "envStems": {
@@ -969,6 +969,7 @@
     "@nocobase/sdk": "self-instance client; targets the app's own self-hosted deployment, which is local in a keyless world",
     "@opentelemetry/instrumentation-aws-sdk": "OpenTelemetry instrumentation wrapper, not a service client",
     "@payloadcms/sdk": "self-instance client; targets the app's own self-hosted deployment, which is local in a keyless world",
+    "@prisma/client": "the Prisma ORM client, not a service: its database is a connection, judged by the schema's datasource",
     "@restatedev/restate-sdk": "self-instance client; targets the app's own self-hosted deployment, which is local in a keyless world",
     "@rocket.chat/api-client": "Rocket.Chat monorepo internal package, not an external service",
     "@rocket.chat/federation-sdk": "Rocket.Chat monorepo internal package, not an external service",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.55",
+  "version": "3.0.0",
   "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",
@@ -32,7 +32,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/volter-ai/twin.git",
+    "url": "git+https://github.com/volter-ai/twin-world.git",
     "directory": "packages/world-runtime"
   },
   "homepage": "https://world.volter.ai/docs/reference/cli",
@@ -47,7 +47,8 @@
     "volter-world": "dist/src/cli.js",
     "volter-world-browser-proxy": "dist/src/browser-proxy-cli.js",
     "volter-world-host": "dist/src/host-cli.js",
-    "volter-world-infra": "dist/src/infra-cli.js"
+    "volter-world-infra": "dist/src/infra-cli.js",
+    "volter-world-actions-runner": "dist/src/actions-runner-cli.js"
   },
   "scripts": {
     "test": "bun test src/*.test.ts",
@@ -67,23 +68,22 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.37",
-    "@volter/world-console": "2.0.18"
+    "@volter/world-core": "3.0.0",
+    "@volter/world-console": "3.0.0"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
-    "@volter/world-access": "2.0.2",
-    "@volter/world-core": "2.0.37",
+    "@volter/world-access": "3.0.0",
+    "@volter/world-core": "3.0.0",
     "pg-gateway": "0.3.0-beta.4",
-    "smol-toml": "^1.8.0"
+    "smol-toml": "^1.8.0",
+    "yaml": "2.9.0"
   },
   "peerDependenciesMeta": {
     "@volter/world-console": {
       "optional": true
     }
   },
-  "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.37"
-  }
+  "optionalDependencies": {}
 }

package/src/actions-runner-cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// volter-world-actions-runner: the World's Actions runner as a process (architecture, "The World's Actions runner").
+//   volter-world-actions-runner --github <the World's GitHub twin> --token <a World user's token> --work <dir> [--once]
+// It runs every queued workflow run, then (without --once) looks again every two seconds. Steps inherit this process's
+// environment: start it with the World's (volter-world run), so every call a step makes reaches the World's twins.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { mkdirSync } from 'node:fs';
+import { runQueued } from './actions-runner.ts';
+
+const args = process.argv.slice(2);
+const github = optionValue(args, '--github') ?? process.env.GITHUB_API_URL;
+const token = optionValue(args, '--token') ?? process.env.GITHUB_TOKEN;
+const work = optionValue(args, '--work') ?? '.volter/actions-runner';
+if (!github || !token) {
+  process.stderr.write('usage: volter-world-actions-runner --github <url> --token <token> [--work <dir>] [--once]\n');
+  process.exit(2);
+}
+mkdirSync(work, { recursive: true });
+const opts = { github, token, workRoot: work, env: {}, log: (line: string) => process.stdout.write(`${line}\n`) };
+for (;;) {
+  const ran = await runQueued(opts);
+  if (hasFlag(args, '--once')) process.exit(0);
+  if (ran === 0) await new Promise((r) => setTimeout(r, 2000));
+}

package/src/actions-runner.ts

@@ -0,0 +1,244 @@
+// THE WORLD'S ACTIONS RUNNER — GitHub's hosted runner as a World service (docs/contributing/architecture.md, "The World's
+// Actions runner"). It takes queued workflow runs from the World's GitHub twin (the Actions API lists them; the twin's
+// runner door starts and completes them), checks each run's repository out at its commit over the twin's git plane,
+// and runs its jobs' steps on this machine with GitHub's job environment and the World's own, so every call a step makes
+// to a vendor goes to the World's twin of it. GitHub's own actions it performs itself; any other action fails its step
+// by name.
+//
+// What it does not do (named, so a workflow that needs them fails plainly): matrices beyond their first combination,
+// services and containers, composite and JavaScript actions from the marketplace, reusable workflows, concurrency groups.
+import { spawn } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export type ActionsRunnerOptions = {
+  /** The World's GitHub twin (its API and its git plane at the same origin). */
+  github: string;
+  /** A token of the World's GitHub user, which lists the runs it may run. */
+  token: string;
+  /** Where job workspaces are made (under the World's data). */
+  workRoot: string;
+  /** The World's environment, which every step inherits (its twins' addresses and keys). */
+  env: Record<string, string>;
+  /** Written to as the runner works. */
+  log?: (line: string) => void;
+};
+
+type Row = Record<string, unknown>;
+type Step = { name?: string; id?: string; uses?: string; run?: string; with?: Record<string, unknown>; env?: Record<string, unknown>; if?: string; shell?: string; 'working-directory'?: string; 'continue-on-error'?: boolean };
+type Job = { name?: string; 'runs-on'?: unknown; needs?: string | string[]; env?: Record<string, unknown>; steps?: Step[]; if?: string; defaults?: { run?: { 'working-directory'?: string; shell?: string } }; strategy?: { matrix?: Record<string, unknown> } };
+type Workflow = { name?: string; env?: Record<string, unknown>; jobs?: Record<string, Job> };
+
+async function api(opts: ActionsRunnerOptions, method: string, path: string, body?: unknown, token = opts.token): Promise<{ status: number; body: Row }> {
+  const res = await fetch(`${opts.github.replace(/\/$/, '')}${path}`, {
+    method, headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', ...(body === undefined ? {} : { 'content-type': 'application/json' }) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  });
+  const text = await res.text();
+  let parsed: Row = {};
+  try { parsed = text ? JSON.parse(text) as Row : {}; } catch { parsed = { text }; }
+  return { status: res.status, body: parsed };
+}
+
+/** The repositories the runner serves: the user's own and its organizations'. */
+async function repositories(opts: ActionsRunnerOptions): Promise<string[]> {
+  const out = new Set<string>();
+  const mine = await api(opts, 'GET', '/user/repos?per_page=100');
+  for (const r of (mine.body as unknown as Row[]) ?? []) if (typeof r?.full_name === 'string') out.add(r.full_name);
+  const orgs = await api(opts, 'GET', '/user/orgs?per_page=100');
+  for (const o of (orgs.body as unknown as Row[]) ?? []) {
+    const repos = await api(opts, 'GET', `/orgs/${String(o.login)}/repos?per_page=100`);
+    for (const r of (repos.body as unknown as Row[]) ?? []) if (typeof r?.full_name === 'string') out.add(r.full_name);
+  }
+  return [...out].sort();
+}
+
+/** `${{ … }}` in a string, as far as workflows use it: secrets, env, github, inputs, matrix, steps' outputs, literals. */
+function expand(text: string, scope: Row): string {
+  return text.replace(/\$\{\{\s*([^}]+?)\s*\}\}/g, (_, expr: string) => {
+    const v = evaluate(expr, scope);
+    return v === undefined || v === null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v);
+  });
+}
+function lookup(path: string, scope: Row): unknown {
+  return path.split('.').reduce<unknown>((o, k) => (o && typeof o === 'object' ? (o as Row)[k] : undefined), scope);
+}
+/** An expression: a literal, a context path, `a == b`, `a != b`, `a && b`, `a || b`, `!a`, and the status functions. */
+function evaluate(expr: string, scope: Row): unknown {
+  const e = expr.trim();
+  if (e.includes('||')) return e.split('||').map((p) => evaluate(p, scope)).find(Boolean) ?? false;
+  if (e.includes('&&')) return e.split('&&').every((p) => Boolean(evaluate(p, scope)));
+  const cmp = /^(.+?)\s*(==|!=)\s*(.+)$/.exec(e);
+  if (cmp) { const a = evaluate(cmp[1]!, scope); const b = evaluate(cmp[3]!, scope); return cmp[2] === '==' ? String(a) === String(b) : String(a) !== String(b); }
+  if (e.startsWith('!')) return !evaluate(e.slice(1), scope);
+  if (/^'.*'$/.test(e)) return e.slice(1, -1).replace(/''/g, "'");
+  if (/^-?\d+(\.\d+)?$/.test(e)) return Number(e);
+  if (e === 'true' || e === 'false') return e === 'true';
+  if (e === 'always()') return true;
+  if (e === 'success()') return scope.__failed !== true;
+  if (e === 'failure()') return scope.__failed === true;
+  if (e === 'cancelled()') return false;
+  const fn = /^(startsWith|endsWith|contains)\((.+),(.+)\)$/.exec(e);
+  if (fn) { const a = String(evaluate(fn[2]!, scope) ?? ''); const b = String(evaluate(fn[3]!, scope) ?? ''); return fn[1] === 'startsWith' ? a.startsWith(b) : fn[1] === 'endsWith' ? a.endsWith(b) : a.includes(b); }
+  return lookup(e, scope);
+}
+const condition = (cond: string | undefined, scope: Row): boolean => (cond === undefined ? scope.__failed !== true : Boolean(evaluate(cond.replace(/^\$\{\{\s*|\s*\}\}$/g, ''), scope)));
+
+/** A `KEY=value` file (GITHUB_ENV, GITHUB_OUTPUT), heredoc form (`KEY<<EOF … EOF`) included. */
+function readKv(file: string): Record<string, string> {
+  if (!existsSync(file)) return {};
+  const out: Record<string, string> = {};
+  const lines = readFileSync(file, 'utf8').split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!;
+    const heredoc = /^([^=<]+)<<(.+)$/.exec(line);
+    if (heredoc) {
+      const value: string[] = [];
+      for (i++; i < lines.length && lines[i] !== heredoc[2]; i++) value.push(lines[i]!);
+      out[heredoc[1]!] = value.join('\n');
+    } else if (line.includes('=')) out[line.slice(0, line.indexOf('='))] = line.slice(line.indexOf('=') + 1);
+  }
+  return out;
+}
+
+function sh(command: string, cwd: string, env: Record<string, string>, shell: string, log: (l: string) => void): Promise<number> {
+  return new Promise((resolve) => {
+    const file = join(cwd, `.volter-step-${Date.now()}-${Math.random().toString(36).slice(2)}.sh`);
+    writeFileSync(file, command);
+    const argv = shell === 'pwsh' ? ['pwsh', ['-File', file]] as const : shell === 'sh' ? ['sh', ['-e', file]] as const : ['bash', ['--noprofile', '--norc', '-eo', 'pipefail', file]] as const;
+    const child = spawn(argv[0], [...argv[1]], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    child.stdout.on('data', (d: Buffer) => { for (const l of d.toString().split('\n')) if (l) log(`  ${l}`); });
+    child.stderr.on('data', (d: Buffer) => { for (const l of d.toString().split('\n')) if (l) log(`  ${l}`); });
+    child.on('close', (code) => { rmSync(file, { force: true }); resolve(code ?? 1); });
+  });
+}
+
+/** One of GitHub's own actions, performed by the runner; an action it cannot perform fails by name. */
+function builtin(step: Step, env: Record<string, string>, workspace: string): { ok: boolean; message: string } {
+  const uses = String(step.uses);
+  const name = uses.replace(/@.*$/, '');
+  if (name === 'actions/checkout') return { ok: true, message: 'checked out (the workspace is the run\'s commit)' };
+  if (name === 'actions/setup-node') {
+    // setup-node with a registry-url writes an .npmrc naming it and NODE_AUTH_TOKEN, and points npm at it
+    const registry = typeof step.with?.['registry-url'] === 'string' ? String(step.with['registry-url']) : undefined;
+    if (registry) {
+      const npmrc = join(workspace, '..', '.npmrc-setup-node');
+      const host = registry.replace(/^https?:/, '').replace(/\/?$/, '/');
+      writeFileSync(npmrc, `registry=${registry}\n${host}:_authToken=\${NODE_AUTH_TOKEN}\nalways-auth=true\n`);
+      appendFileSync(env.GITHUB_ENV!, `NPM_CONFIG_USERCONFIG=${npmrc}\n`);
+    }
+    return { ok: true, message: 'node: the World machine\'s' };
+  }
+  if (name === 'oven-sh/setup-bun') return { ok: true, message: 'bun: the World machine\'s' };
+  if (name === 'actions/upload-artifact' || name === 'actions/download-artifact' || name === 'actions/cache') return { ok: true, message: `${name}: recorded by the GitHub twin` };
+  return { ok: false, message: `${uses} is not an action the World's runner performs (GitHub's own: checkout, setup-node, setup-bun, upload-artifact, download-artifact, cache)` };
+}
+
+/** One run: started, each job's steps run in order of `needs`, completed with its conclusion. */
+export async function runOnce(opts: ActionsRunnerOptions, repo: string, run: Row): Promise<'success' | 'failure'> {
+  const log = opts.log ?? (() => {});
+  const id = Number(run.id);
+  const started = await api(opts, 'POST', `/_twin/repos/${repo}/actions/runs/${id}/start`);
+  if (started.status !== 200) { log(`run ${repo}#${id}: not started (${started.status})`); return 'failure'; }
+  const jobToken = String(started.body.token);
+  const secrets = (started.body.secrets as Record<string, string> | undefined) ?? {};
+  // a workflow granting id-token: write: where the job asks GitHub's OIDC provider for its token, and with what
+  const idTokenRequest = started.body.id_token_request as { url: string; token: string } | undefined;
+  // the repository's configuration variables (`vars`), its organization's under them
+  const vars: Record<string, string> = {};
+  for (const path of [`/orgs/${repo.split('/')[0]}/actions/variables?per_page=30`, `/repos/${repo}/actions/variables?per_page=30`]) {
+    const v = await api(opts, 'GET', path);
+    for (const x of (v.body.variables as Row[] | undefined) ?? []) vars[String(x.name)] = String(x.value);
+  }
+  const file = await api(opts, 'GET', `/repos/${repo}/contents/${encodeURI(String(run.path))}?ref=${String(run.head_sha)}`);
+  // the repository's and its owner's ids, which a hosted runner's job environment names
+  const repoInfo = (await api(opts, 'GET', `/repos/${repo}`)).body;
+  const workflow = parseYaml(Buffer.from(String(file.body.content ?? ''), 'base64').toString('utf8')) as Workflow;
+  const root = mkdtempSync(join(opts.workRoot, `run-${id}-`));
+  const workspace = join(root, 'workspace');
+  const clone = `${opts.github.replace(/\/$/, '').replace(/^(https?:\/\/)/, `$1x-access-token:${jobToken}@`)}/${repo}.git`;
+  const git = async (args: string[], cwd: string): Promise<number> => sh(`git ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, cwd, { ...process.env as Record<string, string>, ...opts.env }, 'bash', log);
+  let conclusion: 'success' | 'failure' = 'success';
+  try {
+    mkdirSync(root, { recursive: true });
+    if (await git(['clone', '--quiet', clone, workspace], root) !== 0 || await git(['checkout', '--quiet', String(run.head_sha)], workspace) !== 0) throw new Error('the repository could not be checked out from the GitHub twin');
+    const jobs = Object.entries(workflow.jobs ?? {});
+    const done = new Map<string, 'success' | 'failure' | 'skipped'>();
+    const ready = (j: Job): boolean => ([] as string[]).concat(j.needs ?? []).every((n) => done.has(n));
+    while (done.size < jobs.length) {
+      const next = jobs.find(([k, j]) => !done.has(k) && ready(j));
+      if (!next) break;
+      const [key, job] = next;
+      const needsFailed = ([] as string[]).concat(job.needs ?? []).some((n) => done.get(n) !== 'success');
+      const matrix = Object.fromEntries(Object.entries(job.strategy?.matrix ?? {}).filter(([k]) => k !== 'include' && k !== 'exclude').map(([k, v]) => [k, Array.isArray(v) ? v[0] : v]));
+      const github = { server_url: opts.github, api_url: opts.github, repository: repo, repository_owner: repo.split('/')[0], sha: run.head_sha, ref: `refs/heads/${String(run.head_branch)}`, ref_name: run.head_branch, event_name: run.event, run_id: id, run_number: run.run_number, workflow: workflow.name, job: key, token: jobToken, workspace, actor: run.actor && typeof run.actor === 'object' ? (run.actor as Row).login : 'github-actions' };
+      const scope: Row = { github, secrets: { ...secrets, GITHUB_TOKEN: jobToken }, vars, matrix, needs: {}, steps: {}, env: {}, __failed: needsFailed };
+      if (needsFailed || !condition(job.if, scope)) { done.set(key, 'skipped'); log(`job ${key}: skipped`); continue; }
+      log(`job ${key}: ${job.name ?? key}`);
+      const files = { env: join(root, `${key}.env`), output: join(root, `${key}.output`), path: join(root, `${key}.path`) };
+      // a hosted runner is a fresh machine: no package manifest cached from an earlier job (a release just published
+      // may be newer than it). The tarballs this machine holds are kept, being content-addressed by version; bun's
+      // manifests are not read, by a global bunfig for the job
+      const config = join(root, `${key}.config`);
+      mkdirSync(config, { recursive: true });
+      writeFileSync(join(config, '.bunfig.toml'), '[install.cache]\ndisableManifest = true\n');
+      for (const f of Object.values(files)) writeFileSync(f, '');
+      const baseEnv: Record<string, string> = {
+        ...process.env as Record<string, string>, ...opts.env, CI: 'true', GITHUB_ACTIONS: 'true', GITHUB_REPOSITORY: repo, GITHUB_REPOSITORY_OWNER: repo.split('/')[0]!,
+        GITHUB_SHA: String(run.head_sha), GITHUB_REF: String(github.ref), GITHUB_REF_NAME: String(run.head_branch), GITHUB_EVENT_NAME: String(run.event), GITHUB_RUN_ID: String(id),
+        GITHUB_RUN_NUMBER: String(run.run_number ?? 1), GITHUB_WORKFLOW: String(workflow.name ?? ''), GITHUB_JOB: key, GITHUB_WORKSPACE: workspace, GITHUB_SERVER_URL: opts.github,
+        GITHUB_API_URL: opts.github, GITHUB_ENV: files.env, GITHUB_OUTPUT: files.output, GITHUB_PATH: files.path, RUNNER_OS: process.platform === 'darwin' ? 'macOS' : 'Linux', RUNNER_TEMP: root,
+        GITHUB_TOKEN: jobToken, XDG_CONFIG_HOME: config,
+        // what else a GitHub-hosted runner's job environment holds (npm's provenance reads each of these)
+        GITHUB_WORKFLOW_REF: `${repo}/${String(run.path)}@${String(github.ref)}`, GITHUB_RUN_ATTEMPT: '1', RUNNER_ENVIRONMENT: 'github-hosted',
+        GITHUB_REPOSITORY_ID: String(repoInfo.id ?? ''), GITHUB_REPOSITORY_OWNER_ID: String((repoInfo.owner as Row | undefined)?.id ?? ''),
+        ...(idTokenRequest ? { ACTIONS_ID_TOKEN_REQUEST_URL: idTokenRequest.url, ACTIONS_ID_TOKEN_REQUEST_TOKEN: idTokenRequest.token } : {}),
+      };
+      let failed = false;
+      for (const [i, step] of (job.steps ?? []).entries()) {
+        const env: Record<string, string> = { ...baseEnv, ...readKv(files.env) };
+        const extraPath = readFileSync(files.path, 'utf8').split('\n').filter(Boolean).reverse();
+        if (extraPath.length) env.PATH = `${extraPath.join(':')}:${env.PATH ?? ''}`;
+        const stepScope: Row = { ...scope, env: { ...Object.fromEntries(Object.entries({ ...workflow.env, ...job.env, ...step.env }).map(([k, v]) => [k, expand(String(v), scope)])) }, __failed: failed };
+        for (const [k, v] of Object.entries(stepScope.env as Row)) env[k] = String(v);
+        if (!condition(step.if, stepScope)) { log(`  step ${i + 1} ${step.name ?? step.uses ?? 'run'}: skipped`); continue; }
+        log(`  step ${i + 1}: ${step.name ?? step.uses ?? String(step.run).split('\n')[0]}`);
+        let ok: boolean;
+        if (step.uses) {
+          // its inputs are expressions too (`registry-url: ${{ vars.NPM_REGISTRY }}`)
+          const inputs = Object.fromEntries(Object.entries(step.with ?? {}).map(([k, v]) => [k, typeof v === 'string' ? expand(v, stepScope) : v]));
+          const r = builtin({ ...step, with: inputs }, env, workspace);
+          log(`  ${r.message}`);
+          ok = r.ok;
+        } else {
+          const cwd = join(workspace, step['working-directory'] ?? job.defaults?.run?.['working-directory'] ?? '');
+          ok = (await sh(expand(String(step.run ?? ''), stepScope), cwd, env, step.shell ?? job.defaults?.run?.shell ?? 'bash', log)) === 0;
+        }
+        if (step.id) (scope.steps as Row)[step.id] = { outputs: readKv(files.output), outcome: ok ? 'success' : 'failure', conclusion: ok || step['continue-on-error'] ? 'success' : 'failure' };
+        if (!ok && !step['continue-on-error']) failed = true;
+      }
+      done.set(key, failed ? 'failure' : 'success');
+      (scope.needs as Row)[key] = { result: failed ? 'failure' : 'success', outputs: readKv(files.output) };
+      if (failed) conclusion = 'failure';
+    }
+  } catch (error) {
+    log(`run ${repo}#${id}: ${(error as Error).message}`);
+    conclusion = 'failure';
+  } finally {
+    await api(opts, 'POST', `/_twin/repos/${repo}/actions/runs/${id}/complete`, { conclusion });
+    rmSync(root, { recursive: true, force: true });
+  }
+  log(`run ${repo}#${id}: ${conclusion}`);
+  return conclusion;
+}
+
+/** Every queued run of every repository, one at a time, oldest first. */
+export async function runQueued(opts: ActionsRunnerOptions): Promise<number> {
+  let ran = 0;
+  for (const repo of await repositories(opts)) {
+    const runs = await api(opts, 'GET', `/repos/${repo}/actions/runs?status=queued&per_page=100`);
+    const queued = ((runs.body.workflow_runs as Row[] | undefined) ?? []).sort((a, b) => Number(a.id) - Number(b.id));
+    for (const run of queued) { await runOnce(opts, repo, run); ran += 1; }
+  }
+  return ran;
+}

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';
+import { assertStateRemovable, readBranchMeta, stateDirName, withAncestryLock, withStateRemoval, getActiveWorldStore, worldPaths, worldStateRoot } from '@volter/world-core/runtime';
 
 function checkWorldAncestry(root: string, path: string): void {
   const base = join(root, stateDirName(), 'worlds');

package/src/app-url.ts

@@ -20,7 +20,7 @@
 // a re-`up` (which wipes the dir) or `down --purge` clears it: a recorded URL never outlives the
 // instance it described.
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { withFileLock } from '@volter/world-core';
+import { withFileLock } from '@volter/world-core/runtime';
 import { join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import net from 'node:net';

package/src/backings.ts

@@ -0,0 +1,55 @@
+import type { WorldServiceConfig } from './schema.ts';
+
+export type ServerBackingFacts = {
+  serverBacking: { command: string };
+  adoption: { sdks: string[]; pypi: string[]; envStems: string[] };
+  hostsNone: string;
+  endpointEnv: { name: string; templates: Record<string, string>; note: string };
+};
+
+/**
+ * A vendor whose open-source server a World runs as its service instead of a twin (architecture, "A vendor's own
+ * server as a backing"): the media plane no pack can hold as data. The service is the vendor's own binary on an 'auto'
+ * port, loopback only; the application's key and secret are the ones the server is started with, so its SDK signs
+ * what the server verifies. What the server does not do on its own (LiveKit's egress, a separate service) the
+ * service's note names.
+ */
+export const VENDOR_SERVER_BACKINGS: Record<string, { service: WorldServiceConfig; env: Record<string, string>; facts: ServerBackingFacts }> = (() => {
+  const key = 'twin-livekit-key';
+  // livekit-server wants a secret of at least 32 characters
+  const secret = 'twin-livekit-secret-for-the-worlds-own-server';
+  return {
+    livekit: {
+      service: {
+        '//': 'LiveKit\'s own server (livekit-server, Apache-2.0; `brew install livekit` or LiveKit\'s install script puts it '
+          + 'on PATH), loopback only, rooms in its memory until `down`. Egress is a separate LiveKit service this does not run: '
+          + 'EgressService calls answer its error. Its webhooks go where the application says: add `--config-body` '
+          + `"webhook: {api_key: ${key}, urls: [<the app's webhook URL>]}" to args.`,
+        id: 'livekit',
+        type: 'twin',
+        command: 'livekit-server',
+        // media on the loopback address over UDP from LiveKit's default range; ICE over TCP off (its fixed 7881 would
+        // collide with a second server)
+        args: ['--bind', '127.0.0.1', '--node-ip', '127.0.0.1', '--keys', `${key}: ${secret}`, '--rtc.tcp_port', '0'],
+        port: 'auto',
+        rootArg: false,
+        controlPlane: true,
+        ready: { httpUrl: '${url}/' },
+        injectEnvTemplates: {
+          LIVEKIT_URL: 'ws://${host}:${port}',
+          LIVEKIT_API_KEY: key,
+          LIVEKIT_API_SECRET: secret,
+        },
+      },
+      env: { LIVEKIT_API_KEY: key, LIVEKIT_API_SECRET: secret },
+      facts: {
+        // Current consumers: RH2's package.json and server SDK imports; LiveKit's server is the backing, not a pack.
+        serverBacking: { command: 'livekit-server' },
+        adoption: { sdks: ['livekit-client', 'livekit-server-sdk', '@livekit/rtc-node'], pypi: ['livekit', 'livekit-agents', 'livekit-api'], envStems: ['LIVEKIT'] },
+        hostsNone: 'The World runs the vendor server on its declared endpoint; SDKs read LIVEKIT_URL.',
+        endpointEnv: { name: 'LIVEKIT_URL', templates: { LIVEKIT_URL: 'ws://${host}:${port}', LIVEKIT_API_KEY: key, LIVEKIT_API_SECRET: secret }, note: 'Credentials and URL are the same ones the World starts its LiveKit server with.' },
+      },
+    },
+  };
+})();
+

package/src/branch.ts

@@ -9,7 +9,7 @@
 import { cpSync, existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withAncestryLock, worldPaths, worldStateRoot } from '@volter/world-core';
+import { captureHistory, historyAtInstant, forkTwin, stateGeneration, withHistoryLocks, worldPaths, worldStateRoot } from '@volter/world-core/runtime';
 import { downWorld, saveWorldInstance, statusWorld, upWorld } from './runtime.ts';
 import type { WorldInstance } from './schema.ts';
 import { parseInfraDefinition, pgliteDown, pgliteUp } from './pglite-backing.ts';
@@ -32,7 +32,8 @@ export async function branchWorld(base: string, name: string, options: BranchOpt
   const at = (options.now ?? new Date()).toISOString();
   // Capture source identity before awaiting child compute. A concurrent reset may win;
   // in that case forking fails and the task-owned child is torn down, never an empty success.
-  const source = withAncestryLock(() => Object.keys(from.services).sort().map(service => {
+  const baseDirs = Object.keys(from.services).flatMap((service) => { const fromRoot = join(from.dirs.data, service); return stateServices(fromRoot).map((state) => worldPaths(state, fromRoot).dir); });
+  const source = withHistoryLocks(baseDirs, () => Object.keys(from.services).sort().map(service => {
     const fromRoot = join(from.dirs.data, service);
     return { service, fromRoot, states: stateServices(fromRoot).map(state => {
       let view = options.at?.views?.[service] ?? options.at?.views?.[state] ?? captureHistory(state, fromRoot).view;

package/src/browser-proxy-cli.ts

@@ -6,7 +6,7 @@ import { keepProcessAlive } from '@volter/world-core/lifecycle';
 // NOT in the vendor-agnostic kernel — control-plane must never name a vendor (A2). The kernel
 // only exports the vendor-INDEPENDENT `createTwinProxy` utility; choosing which vendors a given
 // app world proxies is the orchestrator's job.
-import { createTwinProxy } from '@volter/world-core';
+import { createTwinProxy } from '@volter/world-core/runtime';
 
 const port = Number(process.env.PORT || 0);
 const target = process.env.TARGET_URL;