@volter/world 2.0.0

package/dist/src/world.js

@@ -0,0 +1,491 @@
+// WORLD — the twins an app needs, running together (docs/concepts/the-model.md,
+// docs/concepts/worlds.md#the-config-and-the-running-world): a branch with compute attached. `World.open()` finds the world of the cwd the
+// way git finds its repository; every method is a name for a world-runtime verb, in the words a
+// user reads. The `volter` command is one client of this class and adds nothing.
+import { rebaseChangeset, worldBootMarker, listActions, isTwinBookkeeping, pushablePendingActions, pendingActions, applyTwinWrite, twinResources } from '@volter/world-core';
+import { spawnSync } from 'node:child_process';
+import { activateScript, approveWorldChangeset, branchWorld, clockFile, checkoutWorld, createWorldChangeset, diffWorld, downWorld, fetchFromOrigin, findWorldChangeset, initWorld, listWorldChangesets, listWorldMarks, listWorlds, markWorld, pushWorldChangeset, rebaseWorldChangeset, replayWorldChangeset, resetWorld, runWithWorldEnv, seedWorld, shellWorld, statusWorld, statusWorldChangeset, upWorld, verifyWorldChangeset, worldLedgers, worldOrigin, deployWorld, loadWorldConfig, writeWorldConfig, readServeRecord, refreshTwin, serveWorld, findInstalledPackage, rootForControlRoot, sealTwinCredential, sealedCredentialInfo, setTwinRoot, credentialPayloadFrom, materializeRoots } from '@volter/world-runtime';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { requireToken, storeToken } from "./credentials.js";
+import { currentBranch, findWorldRoot, mainBranch, requireWorldRoot, setCurrentBranch, worldConfigRelative, worldEnvPath, worldSeedPath } from "./locate.js";
+import { parentEntries, rebaseBranch } from '@volter/world-core';
+/** One change as `log` shows it: the write, and the receipt the vendor answered with once pushed. */
+/** A twin's branch log as the world reads it: the twin's name, the state service it records under, its control root. */
+export class TwinLog {
+    service;
+    stateService;
+    root;
+    constructor(service, stateService, root) {
+        this.service = service;
+        this.stateService = stateService;
+        this.root = root;
+    }
+    /** this branch's own entries, bookkeeping aside */
+    log() { return listActions(this.stateService, this.root).filter((a) => !isTwinBookkeeping(a)); }
+    /** entries the parent does not hold */
+    unpushed(opts = {}) { return opts.pushable ? pushablePendingActions(this.stateService, this.root) : pendingActions(this.stateService, this.root); }
+    /** the tree: this twin's resources as a read sees them */
+    state() { return twinResources(this.stateService, this.root); }
+    /** one write through the kernel's write path (the head performs it when this twin's root says so) */
+    change(write) { return applyTwinWrite(this.stateService, write, this.root); }
+}
+/** `https://host/org/world` → the remote's base URL and the namespace it addresses. */
+export function parseOriginUrl(url) {
+    // a PATH is a world on this machine (git's file transport): its directory, and its served name
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) {
+        const root = resolve(url);
+        const configPath = join(root, '.volter', 'world.json');
+        if (!existsSync(configPath))
+            throw new Error(`Not a remote URL or world directory: ${url} (want https://<host>/<org>/<world>, or a directory holding .volter/world.json)`);
+        const config = loadWorldConfig(configPath, root).config;
+        return { url: root, namespace: config.bare?.name ?? `${config.id}/${config.id}` };
+    }
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Not a remote URL: ${url} (want https://<host>/<org>/<world>)`);
+    }
+    const parts = parsed.pathname.split('/').filter(Boolean);
+    if (parts.length !== 2)
+        throw new Error(`A remote URL names one world: https://<host>/<org>/<world>, got ${url}`);
+    return { url: `${parsed.origin}`, namespace: `${parts[0]}/${parts[1]}` };
+}
+export class World {
+    /** The branch this handle is on — the instance name in the kernel. */
+    name;
+    /** The world root: the app repo. */
+    root;
+    constructor(name, root) { this.name = name; this.root = root; }
+    // ── finding and making worlds ───────────────────────────────────────────────────────────
+    /** The world of the cwd (or of `ref.root`), on its checked-out branch (or `ref.name`). */
+    /** The config `loadWorldConfig` resolves for this world: the in-repo world.json, else the world's name. */
+    configRef() { const inRepo = join(this.root, '.volter', 'world.json'); return existsSync(inRepo) ? inRepo : this.name; }
+    static open(ref = {}) {
+        const root = ref.root === undefined ? requireWorldRoot() : requireWorldRoot(ref.root);
+        return new World(ref.name ?? currentBranch(root), root);
+    }
+    /** Whether `from` (default: the cwd) is inside a world. */
+    static find(from) {
+        const root = findWorldRoot(from);
+        return root === null ? null : new World(currentBranch(root), root);
+    }
+    /** `volter world init --bare <org>/<world> --twins a,b`: a world with no app — a package.json naming the
+     *  twins (installed with bun), then the world over them, served as `/<org>/<world>/`. */
+    static initBare(dir, served, twins, opts = {}) {
+        if (!/^[a-z0-9_-]+\/[a-z0-9_-]+$/i.test(served))
+            throw new Error(`a bare world is named <org>/<world>, got ${served}`);
+        if (twins.length === 0)
+            throw new Error('a bare world needs its twins: --twins github,slack');
+        mkdirSync(dir, { recursive: true });
+        const pkgPath = join(dir, 'package.json');
+        if (!existsSync(pkgPath))
+            writeFileSync(pkgPath, `${JSON.stringify({ name: served.split('/')[1], private: true, devDependencies: Object.fromEntries(twins.map((t) => [`@volter/twin-${t}`, '*'])) }, null, 2)}\n`);
+        if (opts.install !== false && !twins.every((t) => findInstalledPackage(dir, `@volter/twin-${t}`))) {
+            // the runtime's own installer: bun under Bun, npm under Node — never assumed
+            const cmd = typeof Bun !== 'undefined' ? ['bun', 'add', '-d'] : ['npm', 'install', '--save-dev'];
+            const r = spawnSync(cmd[0], [...cmd.slice(1), ...twins.map((t) => `@volter/twin-${t}`)], { cwd: dir, stdio: 'inherit' });
+            if (r.status !== 0)
+                throw new Error(`installing the twins failed (${cmd.join(' ')} exited ${r.status})`);
+        }
+        const name = served.split('/')[1];
+        const result = initWorld(name, dir, { root: dir, vendors: twins, bare: served, force: opts.force ?? false });
+        return { world: new World(name, dir), result };
+    }
+    /** `volter world init`: detect the app's vendors and write `.volter/world.json` beside the code. */
+    static init(app = process.cwd(), opts = {}) {
+        const name = opts.name ?? worldNameFor(app);
+        const { name: _n, root: _r, ...rest } = opts;
+        const result = initWorld(name, app, { root: opts.root ?? app, ...rest });
+        return { world: new World(name, opts.root ?? app), result };
+    }
+    // ── lifecycle ───────────────────────────────────────────────────────────────────────────
+    /**
+     * Start the twins on this branch. A branch that has run before comes back with its state (down
+     * stops compute, up resumes it — `reset` is the way back to the default data); a fresh branch
+     * boots clean and loads the default data unless `seed: false`.
+     */
+    async up(opts = {}) {
+        const existing = this.instance();
+        if (existing?.running)
+            return existing; // already up: nothing to do
+        const instance = await upWorld(worldConfigRelative(), {
+            name: this.name, root: this.root, envFile: worldEnvPath(this.root),
+            ...(opts.mode ? { mode: opts.mode } : existing ? { mode: existing.mode } : {}),
+            ...(existing ? { keepState: true } : {}),
+        });
+        try {
+            if (!existing && opts.seed !== false && existsSync(worldSeedPath(this.root))) {
+                // a story that fails is a loud failure: the world is up, but not the world the app expects
+                const seeded = await seedWorld(this.name, { root: this.root, cwd: opts.cwd ?? this.root });
+                if (seeded.exitCode !== 0)
+                    throw new Error(`the story failed (${seeded.entry} exited ${seeded.exitCode}); the world is up without it — fix the seed and \`volter world seed\``);
+            }
+        }
+        finally {
+            // a root set while the world was stopped reaches the twins' state after the default data (which a
+            // fresh boot runs simulated), where the deploy reads it — also when the seed failed
+            materializeRoots(loadWorldConfig(this.configRef(), this.root).config, instance.dirs.data, this.root);
+        }
+        return instance;
+    }
+    /** Stop the twins; the branch's state stays (`up` resumes). `purge` forgets it. */
+    down(opts = {}) { return downWorld(this.name, this.root, opts); }
+    /** Run a command inside the world: the app or its tests, with the twins' URLs and fake credentials in its env. */
+    run(command, opts = {}) { return runWithWorldEnv(this.name, command, this.root, { ...opts, cwd: opts.cwd ?? this.root }); }
+    /** The shell script that activates the world in the current shell: `eval "$(volter world activate)"` — vendor CLIs and curl reach the twins. */
+    activateScript() { return activateScript(this.name, this.root); }
+    /** A subshell with the world active; resolves to its exit code. */
+    shell() { return shellWorld(this.name, this.root); }
+    /** The kernel's instance record, or null before the first `up`. */
+    instance() {
+        try {
+            return statusWorld(this.name, this.root);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The world, the branch, the origin, what is unpushed, what is running. */
+    status() {
+        const instance = this.instance();
+        const changesets = instance ? this.changesets() : [];
+        const services = {};
+        if (instance)
+            for (const [id, s] of Object.entries(instance.services))
+                services[id] = { ...(s.url ? { url: s.url } : {}), running: s.type === 'external' || instance.livePids.includes(s.pid), ...(s.protocol ? { protocol: { major: s.protocol.major, standing: s.protocol.standing } } : {}) };
+        return {
+            world: this.name, root: this.root, branch: this.name,
+            branches: listWorlds(this.root).map((w) => w.name).sort(),
+            running: instance?.running ?? false,
+            served: (() => { const r = readServeRecord(this.root); return r ? { base: r.base, pid: r.pid, startedAt: r.startedAt } : null; })(),
+            origin: instance?.origin ? { url: instance.origin.url, namespace: instance.origin.namespace, ...(instance.origin.fetchedAt ? { fetchedAt: instance.origin.fetchedAt } : {}) } : null,
+            unpushed: instance ? this.unpushed().length : 0,
+            changesets: { total: changesets.length, pushed: changesets.filter((c) => c.changeset.applied?.outcome === 'applied').length },
+            services,
+            ...(instance ? { envFile: instance.envFile } : {}),
+        };
+    }
+    // ── the repos ───────────────────────────────────────────────────────────────────────────
+    /** One twin log per twin the world runs: its branch entries and what is unpushed. */
+    repos() { return worldLedgers(this.name, this.root).map((l) => new TwinLog(l.service, l.stateService, l.controlRoot)); }
+    repo(service) {
+        const found = this.repos().find((r) => r.service === service);
+        if (!found) {
+            const instance = statusWorld(this.name, this.root);
+            if (!instance.services[service])
+                throw new Error(`World "${this.name}" has no twin "${service}" (has: ${Object.keys(instance.services).sort().join(', ') || 'none'})`);
+            return new TwinLog(service, service, join(instance.dirs.data, service));
+        }
+        return found;
+    }
+    // ── the log ─────────────────────────────────────────────────────────────────────────────
+    /** Every write the app made, across the twins, oldest first, with the receipt against each pushed one. */
+    log() {
+        const receipts = new Map();
+        for (const located of this.changesets())
+            for (const receipt of located.changeset.applied?.receipts ?? [])
+                receipts.set(receipt.actionId, { receipt, changeset: located.changeset.name });
+        const rows = [];
+        for (const repo of this.repos()) {
+            // v2 (log.ts): the parent log first — what origin holds, minus the default data (a placeholder
+            // row) and minus this branch's own landed copies (shown once, as the branch entry with its receipt)
+            const landed = new Map();
+            const own = new Set(repo.log().map((a) => a.id));
+            // the position of each entry in this twin's whole log: the parent view, then the branch
+            const positionOf = new Map();
+            {
+                let n = 0;
+                for (const e of parentEntries(repo.stateService, repo.root))
+                    positionOf.set(e.id, ++n);
+                for (const e of repo.log())
+                    if (!positionOf.has(e.id))
+                        positionOf.set(e.id, ++n);
+            }
+            for (const e of parentEntries(repo.stateService, repo.root)) {
+                // the settled receipt wins over a provisional `landed` one: origin's copy says deployed/refused/failed after this branch's own copy said landed
+                if (e.landsId && e.receipt) {
+                    const prior = landed.get(e.landsId);
+                    if (!prior || prior.status === 'landed' || e.receipt.status !== 'landed')
+                        landed.set(e.landsId, e.receipt);
+                }
+                if (e.landsId && own.has(e.landsId))
+                    continue;
+                if (own.has(e.id))
+                    continue;
+                if (e.provenance === 'placeholder')
+                    continue;
+                if (e.op !== 'set' || !e.fields || e.subject.type.startsWith('_'))
+                    continue;
+                rows.push({ ...e, service: repo.service, ...(e.receipt ? { landed: e.receipt } : {}), ...(positionOf.has(e.id) ? { position: positionOf.get(e.id) } : {}) });
+            }
+            for (const action of repo.log()) {
+                const r = receipts.get(action.id);
+                const l = landed.get(action.id);
+                // the row names the TWIN (slack), not the state service it records under (chat)
+                const row = { ...action, service: repo.service, ...(positionOf.has(action.id) ? { position: positionOf.get(action.id) } : {}) };
+                rows.push(l ? { ...row, landed: l } : r ? { ...row, receipt: r.receipt, changeset: r.changeset } : row);
+            }
+        }
+        return rows.sort((a, b) => a.occurredAt.localeCompare(b.occurredAt) || a.id.localeCompare(b.id));
+    }
+    /** Changes not yet pushed (`log origin..HEAD`), across the twins. */
+    unpushed() { return this.repos().flatMap((r) => r.unpushed({ pushable: true })).sort((a, b) => a.occurredAt.localeCompare(b.occurredAt)); }
+    diff(base) { return diffWorld(this.name, { root: this.root, ...(base ? { base } : {}) }); }
+    // ── default data ────────────────────────────────────────────────────────────────────────
+    /** Load the default data: the seed runs with every twin recording what it creates as data that was already there. */
+    seed(opts = {}) { return seedWorld(this.name, { root: this.root, cwd: this.root, ...opts }); }
+    /** Back to the default data: forget this branch's state, boot, seed. */
+    reset(opts = {}) { return resetWorld(this.name, { root: this.root, cwd: this.root, ...opts }); }
+    // ── branches ────────────────────────────────────────────────────────────────────────────
+    /**
+     * A new branch from here — its own log over this branch's mirrors — checked out. One branch runs
+     * at a time in a world (the app's env names one set of twins), so this branch stops as the new
+     * one starts; `checkout` brings it back with its state.
+     */
+    async branch(name, opts = {}) {
+        if (listWorlds(this.root).some((w) => w.name === name))
+            throw new Error(`A branch "${name}" already exists — \`volter world checkout ${name}\` switches to it`);
+        await branchWorld(this.name, name, { root: this.root, envFile: worldEnvPath(this.root), ...(opts.at ? { at: opts.at } : {}) });
+        if (this.instance()?.running)
+            await downWorld(this.name, this.root);
+        setCurrentBranch(this.root, name);
+        return new World(name, this.root);
+    }
+    /** Switch to a branch: its twins come back with their state; this branch's stop. */
+    async checkout(name) {
+        if (name === 'main')
+            name = mainBranch(this.root); // the main branch answers to its name and to `main`
+        if (name === this.name)
+            return this;
+        if (!listWorlds(this.root).some((w) => w.name === name))
+            throw new Error(`No branch "${name}" in this world (branches: ${listWorlds(this.root).map((w) => w.name).sort().join(', ') || 'none'})`);
+        const wasRunning = this.instance()?.running ?? false;
+        if (wasRunning)
+            await downWorld(this.name, this.root);
+        const target = new World(name, this.root);
+        if (wasRunning && !target.instance()?.running)
+            await checkoutWorld(name, { root: this.root });
+        setCurrentBranch(this.root, name);
+        return target;
+    }
+    branches() { return listWorlds(this.root).map((w) => w.name).sort(); }
+    /** Is this the main branch? */
+    isMain() { return this.name === mainBranch(this.root); }
+    /** What this branch's changes are measured from, as `diff` says it: the branch point, origin, or the story. */
+    diffBase() {
+        if (!this.isMain())
+            return `branch ${this.name}`;
+        if (this.remote('origin'))
+            return 'origin';
+        return existsSync(worldSeedPath(this.root)) ? 'the story' : 'the default data';
+    }
+    // ── the clock ───────────────────────────────────────────────────────────────────────────
+    /** The world's clock: the frozen instant every twin stamps from, or the wall clock when unset. */
+    clock() {
+        const file = clockFile(this.root, this.name);
+        return existsSync(file) ? { at: readFileSync(file, 'utf8').trim(), frozen: true } : { at: new Date().toISOString(), frozen: false };
+    }
+    /** Set the world's clock to an instant; every twin stamps from it until it moves. */
+    setClock(iso) {
+        const parsed = Date.parse(iso);
+        if (Number.isNaN(parsed))
+            throw new Error(`${JSON.stringify(iso)} is not an ISO-8601 instant`);
+        const file = clockFile(this.root, this.name);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, `${new Date(parsed).toISOString()}\n`);
+        return new Date(parsed).toISOString();
+    }
+    /** Move a set clock forward: `30d`, `12h`, `5m`, `90s`. */
+    advanceClock(by) {
+        const m = /^(\d+(?:\.\d+)?)(s|m|h|d)$/.exec(by.trim());
+        if (!m)
+            throw new Error(`${JSON.stringify(by)} is not <N>(s|m|h|d)`);
+        const current = this.clock();
+        if (!current.frozen)
+            throw new Error('the clock is not set — `volter world clock set <iso>` first; advancing the wall clock would freeze time as a side effect');
+        const ms = Number(m[1]) * { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2]];
+        return this.setClock(new Date(Date.parse(current.at) + ms).toISOString());
+    }
+    /** Rebase this branch onto its base's current position, every twin; conflicts named per subject and field. */
+    rebaseBranch() { return this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root) })); }
+    /** Replay a changeset's changes into another branch's twins, in order, with the same ids. */
+    replay(name, into) { return replayWorldChangeset(name, { root: this.root, world: this.name, into }); }
+    // ── serving ─────────────────────────────────────────────────────────────────────────────
+    /** Serve this world on a port under `/<org>/<world>/`; returns when listening. */
+    serve(opts = {}) { return serveWorld(this.name, { root: this.root, ...opts }); }
+    // ── remotes ─────────────────────────────────────────────────────────────────────────────
+    /** The remotes named in world.json (`volter remote add`), name → url or path. */
+    remotes() { return { ...(loadWorldConfig(this.configRef(), this.root).config.remotes ?? {}) }; }
+    /** Name a remote; `origin` is the one fetch and push use by default. A token given is remembered for it. */
+    addRemote(name, target, opts = {}) {
+        const { path, config } = loadWorldConfig(this.configRef(), this.root);
+        const remotes = { ...(config.remotes ?? {}), [name]: target };
+        writeWorldConfig(path, { ...config, remotes });
+        if (opts.token)
+            storeToken(parseOriginUrl(target).url, opts.token);
+    }
+    removeRemote(name) {
+        const { path, config } = loadWorldConfig(this.configRef(), this.root);
+        const remotes = { ...(config.remotes ?? {}) };
+        delete remotes[name];
+        writeWorldConfig(path, { ...config, remotes });
+    }
+    /** The remote a verb uses: the named one, else origin from world.json, else the instance's recorded origin. */
+    remote(name = 'origin') {
+        const target = this.remotes()[name];
+        if (target)
+            return parseOriginUrl(target);
+        if (name !== 'origin')
+            return null;
+        const recorded = worldOrigin(this.name, this.root);
+        return recorded ? { url: recorded.url, namespace: recorded.namespace } : null;
+    }
+    // ── the origin ──────────────────────────────────────────────────────────────────────────
+    /** The origin this world clones from and pushes to, or null: the default data is its only origin. */
+    origin() { const r = this.remote('origin'); const recorded = worldOrigin(this.name, this.root); return r ? { ...(recorded ?? {}), url: r.url, namespace: r.namespace } : recorded; }
+    /**
+     * Clone a remote's canonical history into this world: record the origin, remember the token,
+     * fetch everything. With the world's token (namespace or read), the history arrives through the
+     * mirror, from the beginning; with `adminToken` as well, the remote's whole tree is copied in one
+     * move, which is what an admin can do and a reader cannot. Either way one token is remembered:
+     * the world's, which is what `fetch` and `push` use afterwards.
+     */
+    async clone(url, opts = {}) {
+        const origin = parseOriginUrl(url);
+        if (opts.token !== undefined && opts.token !== '')
+            storeToken(origin.url, opts.token);
+        if (opts.adminToken !== undefined && opts.adminToken !== '') {
+            if (opts.token === undefined || opts.token === '')
+                storeToken(origin.url, opts.adminToken);
+            return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key: opts.adminToken, full: true });
+        }
+        const key = requireToken(origin.url, opts.token);
+        // v2: a clone brings the served world's whole log in from position zero, and names it origin;
+        // a world that has never run is booted first (no story: its history is the origin's)
+        this.addRemote('origin', url);
+        if (!this.instance())
+            await this.up({ seed: false });
+        return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key, full: true });
+    }
+    /** Fetch, then move this branch onto what came in: git's pull. */
+    async pull(opts = {}) {
+        const fetched = await this.fetch(opts);
+        return { fetched, rebased: this.repos().map((r) => ({ service: r.service, ...rebaseBranch(r.stateService, r.root, { origin: true }) })) };
+    }
+    /** Fetch what the origin observed since the last fetch. */
+    fetch(opts = {}) {
+        const origin = this.origin();
+        if (!origin)
+            throw new Error(`World "${this.name}" has no origin — its only origin is the default data. \`volter world clone <url>\` connects a remote.`);
+        if (opts.token !== undefined && opts.token !== '')
+            storeToken(origin.url, opts.token); // the last token given for a remote is the one remembered
+        return fetchFromOrigin(this.name, { root: this.root, url: origin.url, namespace: origin.namespace, key: requireToken(origin.url, opts.token), ...(opts.services ? { services: opts.services } : {}) });
+    }
+    // ── changesets and push ─────────────────────────────────────────────────────────────────
+    /** Cut a changeset from the unpushed changes: the reviewable unit, with the author's message. */
+    changeset(opts = {}) {
+        const name = opts.name ?? (opts.message ? slugName(opts.message, this.changesets()) : nextChangesetName(this.changesets()));
+        return createWorldChangeset(this.name, name, { root: this.root, ...(opts.message !== undefined ? { message: opts.message } : {}), ...(opts.base ? { base: opts.base } : {}), ...(opts.verifiers ? { verifiers: opts.verifiers } : {}), ...(opts.overwrite ? { overwrite: true } : {}) });
+    }
+    changesets() { return listWorldChangesets({ root: this.root, world: this.name }); }
+    /**
+     * Push to the origin, which deploys to the vendor with its own keys and answers with receipts:
+     * the named changeset, or every changeset not yet pushed, oldest first. A local world never
+     * holds a vendor credential.
+     */
+    async push(opts = {}) {
+        const origin = this.origin();
+        if (!origin)
+            throw new Error(`World "${this.name}" has no origin to push to — the default data cannot be pushed to. \`volter world clone <url>\` connects a remote.`);
+        if (opts.token !== undefined && opts.token !== '')
+            storeToken(origin.url, opts.token);
+        const key = requireToken(origin.url, opts.token);
+        const to = { to: origin.url, namespace: origin.namespace };
+        const queue = opts.name !== undefined
+            ? [findWorldChangeset(opts.name, { root: this.root, world: this.name })]
+            : this.changesets().filter((c) => c.changeset.applied === null || c.changeset.applied.outcome === 'refused').sort((a, b) => a.changeset.createdAt.localeCompare(b.changeset.createdAt));
+        if (queue.length === 0)
+            throw new Error(this.unpushed().length ? 'Nothing to push: cut a changeset first — `volter world changeset -m "<what and why>"`' : 'Nothing to push: no unpushed changes');
+        const outcomes = [];
+        for (const located of queue) {
+            const outcome = await pushWorldChangeset(located.changeset.name, { root: this.root, world: this.name, ...to, key, ...(opts.force ? { force: true } : {}) });
+            outcomes.push(outcome);
+            if (outcome.application.outcome === 'refused')
+                break;
+        }
+        return outcomes;
+    }
+    // ── review (the operator's verbs, kept on the SDK for the remote and for CI) ────────────
+    mark(id, now) { return markWorld(this.name, { root: this.root, ...(id ? { id } : {}), ...(now ? { now } : {}) }); }
+    marks() { return listWorldMarks(this.name, this.root); }
+    verify(name, opts = { ephemeral: true }) { return verifyWorldChangeset(name, { root: this.root, world: this.name, ...opts }); }
+    approve(name, principal, note) { return approveWorldChangeset(name, { root: this.root, world: this.name, principal, ...(note ? { note } : {}) }); }
+    readiness(name) { return statusWorldChangeset(name, { root: this.root, world: this.name }); }
+    rebase(name) { return rebaseWorldChangeset(name, { root: this.root, world: this.name }); }
+    // ── roots (docs/concepts/the-model.md: a twin on a shared world whose root is the vendor) ──
+    /** The twin's root and credential, as `volter twin <vendor>` prints them. */
+    twin(vendor) {
+        const { config } = loadWorldConfig(this.configRef(), this.root);
+        const service = config.services.find((s) => s.id === vendor);
+        if (!service)
+            throw new Error(`no twin "${vendor}" in this world`);
+        const inst = this.instance();
+        return { vendor, ...(inst?.services[vendor]?.url ? { url: inst.services[vendor].url } : {}), root: service.root ?? null, credential: sealedCredentialInfo(this.root, vendor) };
+    }
+    /** Set (or clear) the twin's root: the vendor's API and the deploy policy, in world.json. Takes effect at the next `up` or `serve`, or now when the world runs. */
+    setTwinRoot(vendor, root) {
+        setTwinRoot(this.root, vendor, root, { config: this.configRef() });
+        const inst = this.instance();
+        if (inst?.running) {
+            materializeRoots(loadWorldConfig(this.configRef(), this.root).config, inst.dirs.data, this.root);
+        }
+    }
+    /** Seal the vendor's credential beside the world (a bare token, or a JSON payload). Never readable back. */
+    sealTwinCredential(vendor, input) { return sealTwinCredential(this.root, vendor, credentialPayloadFrom(input, vendor)); }
+    /** Refresh one twin from its root now. */
+    async refreshTwin(vendor, opts = {}) {
+        const { controlRoot, root } = this.rootOf(vendor);
+        return refreshTwin({ worldRoot: this.root, vendor, controlRoot, root, ...(opts.force ? { force: true } : {}) });
+    }
+    rootOf(vendor) {
+        const inst = statusWorld(this.name, this.root);
+        const controlRoot = join(inst.dirs.data, vendor);
+        const root = rootForControlRoot(controlRoot, vendor);
+        if (!root)
+            throw new Error(`the ${vendor} twin has no root — \`volter twin ${vendor} root <url>\` sets one`);
+        return { controlRoot, root };
+    }
+    /** DEPLOY: perform landed entries against each root twin's vendor, by policy (runtime `deployWorld`). */
+    deploy(name) { return deployWorld(this.name, { root: this.root, ...(name ? { changeset: name } : {}) }); }
+}
+/** The world's name when none is given: the app directory's basename, made safe. */
+export function worldNameFor(app) {
+    const base = app.replace(/[\\/]+$/, '').split(/[\\/]/).pop() ?? 'world';
+    const safe = base.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[^a-z0-9]+/, '');
+    return safe === '' ? 'world' : safe;
+}
+/** A name from the message (`Triage acme/web#1 as OPS-1` → `triage-acme-web-1-as-ops-1`), suffixed when taken. */
+function slugName(message, existing) {
+    const base = message.toLowerCase().replace(/['’]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'changeset';
+    const taken = new Set(existing.map((c) => c.changeset.name));
+    if (!taken.has(base))
+        return base;
+    for (let n = 2;; n += 1) {
+        const name = `${base}-${n}`;
+        if (!taken.has(name))
+            return name;
+    }
+}
+/** `changeset-1`, `changeset-2`, … — the next free name when the author gives none. */
+function nextChangesetName(existing) {
+    const taken = new Set(existing.map((c) => c.changeset.name));
+    for (let n = existing.length + 1;; n += 1) {
+        const name = `changeset-${n}`;
+        if (!taken.has(name))
+            return name;
+    }
+}
+export { rebaseChangeset, worldBootMarker };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@volter/world",
+  "version": "2.0.0",
+  "description": "Run your app against a world of twins. `World` and `Repo` — one method per verb: init, up, run, log, diff, reset, branch, checkout, clone, fetch, changeset, push — and the `volter` command, one client of them.",
+  "keywords": [
+    "volter",
+    "world",
+    "twin",
+    "sdk",
+    "cli",
+    "version-control",
+    "changeset"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/src/index.js",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "dependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-runtime": "2.0.0"
+  },
+  "bin": {
+    "volter": "dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "node ../../scripts/publish/build.mjs",
+    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+  }
+}