@volter/world-runtime 2.0.55 → 3.0.1

package/dist/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/dist/src/actions-runner-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/actions-runner-cli.js

@@ -0,0 +1,25 @@
+#!/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.js";
+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) => 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/dist/src/actions-runner.d.ts

@@ -0,0 +1,18 @@
+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>;
+/** One run: started, each job's steps run in order of `needs`, completed with its conclusion. */
+export declare function runOnce(opts: ActionsRunnerOptions, repo: string, run: Row): Promise<'success' | 'failure'>;
+/** Every queued run of every repository, one at a time, oldest first. */
+export declare function runQueued(opts: ActionsRunnerOptions): Promise<number>;
+export {};

package/dist/src/actions-runner.js

@@ -0,0 +1,281 @@
+// 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';
+async function api(opts, method, path, body, token = opts.token) {
+    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 = {};
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    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) {
+    const out = new Set();
+    const mine = await api(opts, 'GET', '/user/repos?per_page=100');
+    for (const r of mine.body ?? [])
+        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 ?? []) {
+        const repos = await api(opts, 'GET', `/orgs/${String(o.login)}/repos?per_page=100`);
+        for (const r of repos.body ?? [])
+            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, scope) {
+    return text.replace(/\$\{\{\s*([^}]+?)\s*\}\}/g, (_, expr) => {
+        const v = evaluate(expr, scope);
+        return v === undefined || v === null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v);
+    });
+}
+function lookup(path, scope) {
+    return path.split('.').reduce((o, k) => (o && typeof o === 'object' ? o[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, scope) {
+    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, scope) => (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) {
+    if (!existsSync(file))
+        return {};
+    const out = {};
+    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 = [];
+            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, cwd, env, shell, log) {
+    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]] : shell === 'sh' ? ['sh', ['-e', file]] : ['bash', ['--noprofile', '--norc', '-eo', 'pipefail', file]];
+        const child = spawn(argv[0], [...argv[1]], { cwd, env, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        child.stdout.on('data', (d) => { for (const l of d.toString().split('\n'))
+            if (l)
+                log(`  ${l}`); });
+        child.stderr.on('data', (d) => { 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, env, workspace) {
+    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, repo, run) {
+    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 ?? {};
+    // 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;
+    // the repository's configuration variables (`vars`), its organization's under them
+    const vars = {};
+    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 ?? [])
+            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'));
+    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, cwd) => sh(`git ${args.map((a) => `'${a.replace(/'/g, "'\\''")}'`).join(' ')}`, cwd, { ...process.env, ...opts.env }, 'bash', log);
+    let conclusion = '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();
+        const ready = (j) => [].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 = [].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.login : 'github-actions' };
+            const scope = { 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 = {
+                ...process.env, ...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?.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 = { ...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 = { ...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))
+                    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;
+                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[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[key] = { result: failed ? 'failure' : 'success', outputs: readKv(files.output) };
+            if (failed)
+                conclusion = 'failure';
+        }
+    }
+    catch (error) {
+        log(`run ${repo}#${id}: ${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) {
+    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 ?? []).sort((a, b) => Number(a.id) - Number(b.id));
+        for (const run of queued) {
+            await runOnce(opts, repo, run);
+            ran += 1;
+        }
+    }
+    return ran;
+}

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

package/dist/src/app-url.js

@@ -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/dist/src/backings.d.ts

@@ -0,0 +1,29 @@
+import type { WorldServiceConfig } from './schema.js';
+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 declare const VENDOR_SERVER_BACKINGS: Record<string, {
+    service: WorldServiceConfig;
+    env: Record<string, string>;
+    facts: ServerBackingFacts;
+}>;

package/dist/src/backings.js

@@ -0,0 +1,45 @@
+/**
+ * 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 = (() => {
+    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/dist/src/branch.js

@@ -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.js";
 import { parseInfraDefinition, pgliteDown, pgliteUp } from "./pglite-backing.js";
 import { redisTwinCli, redisTwinDown, redisTwinUp } from "./redis-backing.js";
@@ -29,7 +29,8 @@ export async function branchWorld(base, name, options = {}) {
     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/dist/src/browser-proxy-cli.js

@@ -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;
 if (!target)

package/dist/src/catalog-index.d.ts

@@ -0,0 +1,38 @@
+/** The index as npm carries it. */
+export declare 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 declare const readSources: (index: string) => Source[];
+export declare function readVendors(index: string): Entry[];
+/** A package's vendor: `@volter/twin-<vendor>`, or the part after `twin-` in any scope. */
+export declare const vendorOf: (name: string) => string;
+/** Each vendor's default twin: its official package, else its live outside package; the
+ *  highest live version of it. */
+export declare function defaults(index: string): Record<string, {
+    name: string;
+    version: string;
+    source: string;
+}>;

package/dist/src/catalog-index.js

@@ -0,0 +1,37 @@
+// 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';
+export const readSources = (index) => JSON.parse(readFileSync(join(index, 'sources.json'), 'utf8'));
+export function readVendors(index) {
+    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'))) : [];
+}
+/** A package's vendor: `@volter/twin-<vendor>`, or the part after `twin-` in any scope. */
+export const vendorOf = (name) => name.replace(/^@[^/]+\//, '').replace(/^twin-/, '');
+const semver = (v) => v.split(/[.-]/).slice(0, 3).map((n) => Number(n) || 0);
+const newer = (a, b) => { 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) {
+    const sources = new Map(readSources(index).map((s) => [s.name, s]));
+    const rank = (s) => (!s ? 0 : s.official ? 2 : 1);
+    const out = {};
+    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/dist/src/catalog.d.ts

@@ -1,5 +1,5 @@
+import { installedPackageDir } from '@volter/world-core/runtime';
 export declare const TWIN_PACKAGE_PREFIX = "@volter/twin-";
-/** Packages under the `@volter/twin-` prefix that are NOT twins. */
 export declare function twinPackageName(vendor: string): string;
 export type CatalogKind = 'checkout' | 'installed';
 export type Catalog = {
@@ -14,6 +14,9 @@ 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;
 };
 /** The pack's module entry, FROM ITS MANIFEST (docs/contributing/architecture.md#the-publishing-pipeline): `exports['.']`
  *  — `src/index.ts` in the checkout, `dist/src/index.js` once published — so the same resolution
@@ -22,10 +25,20 @@ export declare function packEntry(dir: string): string;
 /** The pack's cli, from its manifest's `bin` (`world-<vendor>` when named, else the first), or undefined when the directory is no pack. */
 export declare function packCli(dir: string): string | undefined;
 /** The nearest `node_modules/<name>` above `from` that holds a package.json — node's own walk. */
-export declare function findInstalledPackage(from: string, name: string): string | undefined;
+export declare const findInstalledPackage: typeof installedPackageDir;
 export declare function checkoutCatalog(root: string): Catalog;
 export declare function installedCatalog(root: string): Catalog;
-/** 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 declare function mergedCatalog(sources: Catalog[]): Catalog;
+/** Overlays one facts file on the kernel's (a file that does not read is skipped: the kernel's facts stand). */
+export declare function overlayPackFactsFile(file: string): void;
+/** The facts file a released pack carries (`generated/pack-facts.json`, written by pack-release), when it has one. */
+export declare function packFactsFile(dir: string): string | undefined;
+/** The catalog for a World root: its pack repository (or the one beside its platform checkout), merged with installed
+ *  packages. Only the selected packs' own facts are overlaid on the kernel's. */
 export declare function resolveCatalog(root: string): 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;