@volter/world-runtime 2.0.0

package/dist/src/changeset.js

@@ -0,0 +1,570 @@
+import { blobDigest, captureHistory, captureParentHistory, getActiveBlobStore, getActiveWorldStore, withAncestryLock, worldPaths } from '@volter/world-core';
+// `volter-world mark` / `diff` / `changeset` — the WORLD-side verbs over the changeset
+// primitive (docs/concepts/the-model.md v0). Thin, exactly like `covers` and `tail` are thin: all
+// the state logic (markers, deltas, content hashing, replay) lives in @volter/world-core's
+// control-plane, beside the `actions.jsonl` ledgers it reads. What lives HERE is the only thing
+// the control plane cannot know — where a world keeps its twins' data, and where a world keeps
+// its own marks and changesets.
+//
+// Discovery mirrors `tail.ts`: a world service's ledgers are
+// `<data>/<service>/<state-dir>/world/<state-service>/actions.jsonl`, and one world service may
+// record under more than one state service. Re-discovered on every call, because a twin's ledger
+// dir does not exist until its first action.
+//
+// STORAGE. Marks and changesets are the world's own artifacts, so they live in the world's state
+// dir beside `instance.json`: `.volter/worlds/<world>/{marks,changesets}/<name>.json`. That makes
+// a changeset share its world's lifecycle — `down --purge` takes the twin data AND the changesets
+// cut from it, which is the honest coupling (a changeset whose ledgers were purged is a fossil).
+// `changeset show|replay|list` take a bare name because a changeset is world-scoped but
+// world-PORTABLE: they scan every world's changeset dir, and an ambiguous name is a loud error
+// asking for `--world`, never a silent pick.
+//
+// Read-only over the twins' data at rest, like `tail` — except `replay`, which is the one verb
+// here that WRITES, and it writes only through the control plane's kernel write path.
+import { tmpdir } from 'node:os';
+import { join, relative, resolve } from 'node:path';
+import { approveChangeset, rebaseChangeset, buildChangeset, captureMarker, changesetHashMatches, changesetReadiness, diffLedgers, normalizeChangeset, replayChangeset, runChangesetVerifiers, stateDirName, withApplication, withVerification, worldBootMarker, assertSafeChangesetName, assertMarkerBelongsTo, CHANGESET_KIND, MARKER_KIND, WORLD_BOOT_MARKER_ID, } from '@volter/world-core';
+import { instanceDir, listWorlds, statusWorld } from "./runtime.js";
+import { fetchFromOrigin } from "./origin.js";
+import { fetchReady, isPathRemote, landChangeset, landReceipts, localWorld, TOKEN_HEADER } from "./served-world.js";
+import { loadWorldChecks } from "./root.js";
+import { readBranchMeta, readTree, rebaseBranch, runChecks, wholeLog, writeBranchMeta } from '@volter/world-core';
+function resolveRoot(root) {
+    return resolve(root ?? process.cwd());
+}
+/** The world instance, or a loud error that names what this repo actually has. `statusWorld`'s
+ *  own "not found" is correct but bare; a verb an operator reaches for by name should say which
+ *  names exist. */
+function requireWorld(name, root) {
+    try {
+        return statusWorld(name, root);
+    }
+    catch (error) {
+        if (!/World instance not found/.test(String(error.message)))
+            throw error;
+        const known = listWorlds(root).map((world) => world.name);
+        throw new Error(`World "${name}" not found in ${root}${known.length ? ` (known worlds: ${known.join(', ')})` : ' (no worlds here)'} — boot it with \`volter-world up <config> --env-file <path> --name ${name}\``);
+    }
+}
+/** Every state service a world service currently records actions under (often exactly one). */
+function stateServicesFor(controlRoot) {
+    const stateRoot = join(controlRoot, stateDirName(), 'world');
+    const store = getActiveWorldStore();
+    return store.list(stateRoot)
+        .filter((name) => store.stat(join(stateRoot, name))?.isDirectory && ['actions.jsonl', 'events.jsonl', 'branch.json'].some((f) => store.exists(join(stateRoot, name, f))))
+        .sort();
+}
+/** Every action ledger in a world, as control-plane ledger references. */
+export function worldLedgers(name, root) {
+    const resolvedRoot = resolveRoot(root);
+    const instance = requireWorld(name, resolvedRoot);
+    const ledgers = [];
+    for (const service of Object.keys(instance.services).sort()) {
+        const controlRoot = join(instance.dirs.data, service);
+        for (const stateService of stateServicesFor(controlRoot)) {
+            ledgers.push({ service, stateService, controlRoot });
+        }
+    }
+    return ledgers;
+}
+// ── marks ──────────────────────────────────────────────────────────────────────────────────────
+export function worldMarksDir(name, root) {
+    return join(instanceDir(resolveRoot(root), name), 'marks');
+}
+export function worldChangesetsDir(name, root) {
+    return join(instanceDir(resolveRoot(root), name), 'changesets');
+}
+/** `mark-<compact-utc>-<rand>` — sortable by name, collision-free within a millisecond. */
+function defaultMarkerId(now) {
+    const stamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z');
+    return `mark-${stamp}-${Math.random().toString(36).slice(2, 6)}`;
+}
+/** The longest note a mark keeps; a longer one is cut. */
+export const MARK_NOTE_MAX = 600;
+export function markWorld(name, options = {}) {
+    const root = resolveRoot(options.root);
+    requireWorld(name, root);
+    const now = options.now ?? new Date();
+    const id = options.id ?? defaultMarkerId(now);
+    assertSafeChangesetName(id, 'marker');
+    const captured = captureMarker({ id, world: name, ledgers: worldLedgers(name, root), createdAt: now.toISOString() });
+    const note = options.note?.trim().slice(0, MARK_NOTE_MAX);
+    const marker = note ? { ...captured, note } : captured;
+    getActiveWorldStore().writeAtomic(join(worldMarksDir(name, root), `${id}.json`), `${JSON.stringify(marker, null, 2)}\n`);
+    return marker;
+}
+/** Every mark recorded in a world, oldest first. */
+export function listWorldMarks(name, root) {
+    const dir = worldMarksDir(name, root);
+    return getActiveWorldStore().list(dir)
+        .filter((file) => file.endsWith('.json'))
+        .map((file) => readMarkerFile(join(dir, file)))
+        .sort((a, b) => (a.createdAt < b.createdAt ? -1 : a.createdAt > b.createdAt ? 1 : a.id < b.id ? -1 : 1));
+}
+function readMarkerFile(path) {
+    const marker = JSON.parse(readStored(path));
+    if (marker.kind !== MARKER_KIND)
+        throw new Error(`${path}: not a world marker (kind=${JSON.stringify(marker.kind)})`);
+    return marker;
+}
+/**
+ * The base a diff/changeset is taken against:
+ *   explicit `--base <id>` → that mark (which must belong to THIS world),
+ *   otherwise the world's most recent mark,
+ *   otherwise `world-boot` — position 0 on every ledger, i.e. everything this world recorded.
+ *
+ * `--base world-boot` is spellable explicitly, so "show me the whole session" never requires
+ * deleting marks.
+ */
+export function resolveBaseMarker(name, options = {}) {
+    const root = resolveRoot(options.root);
+    const instance = requireWorld(name, root);
+    const boot = () => worldBootMarker(name, instance.createdAt);
+    if (options.base === WORLD_BOOT_MARKER_ID)
+        return boot();
+    if (options.base) {
+        // A marker id may address a mark in ANOTHER world — read it wherever it lives so the
+        // cross-world case fails with "captured in world X, not Y" rather than "no such mark".
+        const found = findMarkerAnywhere(root, options.base);
+        if (!found) {
+            const known = listWorldMarks(name, root).map((mark) => mark.id);
+            throw new Error(`No marker "${options.base}" (world "${name}" has: ${known.length ? known.join(', ') : 'no marks yet — run `volter-world mark ' + name + '`'})`);
+        }
+        assertMarkerBelongsTo(found, name);
+        return found;
+    }
+    const marks = listWorldMarks(name, root);
+    return marks.length ? marks[marks.length - 1] : boot();
+}
+/** Look for a marker id in every world under `root` — the seam that makes a wrong-world base a
+ *  precise error instead of a confusing "not found". */
+function findMarkerAnywhere(root, id) {
+    for (const world of listWorlds(root)) {
+        const path = join(worldMarksDir(world.name, root), `${id}.json`);
+        if (getActiveWorldStore().exists(path))
+            return readMarkerFile(path);
+    }
+    return null;
+}
+// ── diff ───────────────────────────────────────────────────────────────────────────────────────
+/** The world's ledger delta since `base` (default: the last mark, else world-boot). */
+export function diffWorld(name, options = {}) {
+    const root = resolveRoot(options.root);
+    const base = resolveBaseMarker(name, { root, ...(options.base === undefined ? {} : { base: options.base }) });
+    return diffLedgers({ world: name, ledgers: worldLedgers(name, root), base });
+}
+/** Freeze the current delta into `<world>/changesets/<name>.json`. */
+export function createWorldChangeset(world, name, options = {}) {
+    const root = resolveRoot(options.root);
+    assertSafeChangesetName(name);
+    const dir = worldChangesetsDir(world, root);
+    const path = join(dir, `${name}.json`);
+    if (getActiveWorldStore().exists(path) && !options.overwrite) {
+        throw new Error(`Changeset "${name}" already exists in world "${world}" (${path}) — pick another name, or pass --force to replace it`);
+    }
+    // re-cutting an existing name (overwrite) starts from that changeset's own base, not from its cut
+    const base = options.base ?? (getActiveWorldStore().exists(path) ? readChangesetFile(path).base : undefined);
+    const delta = diffWorld(world, { root, ...(base === undefined ? {} : { base }) });
+    // where the parent log stands for each twin the changeset touches (PROTOCOL 2: the cut position a rebase reads from)
+    const cutInstance = requireWorld(world, root);
+    const cut = {};
+    for (const a of delta.actions)
+        if (!(a.service in cut)) {
+            const cr = join(cutInstance.dirs.data, a.service);
+            const st = a.stateService ?? a.service;
+            cut[a.service] = captureParentHistory(st, cr);
+        }
+    const changeset = buildChangeset({
+        name,
+        world,
+        base: delta.base.id,
+        actions: delta.actions,
+        cut,
+        ...(options.verifiers ? { verifiers: options.verifiers } : {}),
+        ...(options.now ? { createdAt: options.now.toISOString() } : {}),
+        ...(options.message === undefined ? {} : { message: options.message }),
+    });
+    getActiveWorldStore().write(path, `${JSON.stringify(changeset, null, 2)}\n`);
+    // a changeset records where the log was cut (contract "The model"): the next one starts here
+    markWorld(world, { root, id: `cut-${name}`, ...(options.now ? { now: options.now } : {}) });
+    return changeset;
+}
+function readChangesetFile(path) {
+    const changeset = JSON.parse(readStored(path));
+    if (changeset.kind !== CHANGESET_KIND)
+        throw new Error(`${path}: not a changeset (kind=${JSON.stringify(changeset.kind)})`);
+    // a v0 object lacks the v1 lifecycle fields on disk; filling them is hash-neutral
+    return normalizeChangeset(changeset);
+}
+/** Persist a changeset back where it was found — verify/approve write THROUGH this, so the
+ *  object on disk is always the object the verbs returned. */
+function writeChangesetFile(path, changeset) {
+    getActiveWorldStore().write(path, `${JSON.stringify(changeset, null, 2)}\n`);
+}
+/** A world file's content through the active store; a missing file is an error naming it. */
+function readStored(path) {
+    const text = getActiveWorldStore().read(path);
+    if (text === null)
+        throw new Error(`ENOENT: no such file, open '${path}'`);
+    return text;
+}
+/** Every changeset in every world under `root` (or one world with `world`), newest first. */
+export function listWorldChangesets(options = {}) {
+    const root = resolveRoot(options.root);
+    const worldNames = options.world ? [options.world] : listWorlds(root).map((world) => world.name);
+    const found = [];
+    for (const world of worldNames) {
+        const dir = worldChangesetsDir(world, root);
+        for (const file of getActiveWorldStore().list(dir).filter((entry) => entry.endsWith('.json')).sort()) {
+            const path = join(dir, file);
+            found.push({ changeset: readChangesetFile(path), world, path });
+        }
+    }
+    return found.sort((a, b) => (a.changeset.createdAt > b.changeset.createdAt ? -1 : a.changeset.createdAt < b.changeset.createdAt ? 1 : 0));
+}
+/** Resolve a bare changeset name across worlds. Ambiguity is an error, never a guess. */
+export function findWorldChangeset(name, options = {}) {
+    const root = resolveRoot(options.root);
+    assertSafeChangesetName(name);
+    const matches = listWorldChangesets({ root, ...(options.world ? { world: options.world } : {}) }).filter((entry) => entry.changeset.name === name);
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new Error(`Changeset "${name}" exists in more than one world (${matches.map((m) => m.world).sort().join(', ')}) — disambiguate with --world <name>`);
+    }
+    const known = listWorldChangesets({ root, ...(options.world ? { world: options.world } : {}) });
+    const scope = options.world ? `world "${options.world}"` : `${root}`;
+    throw new Error(`No changeset "${name}" in ${scope} (have: ${known.length ? known.map((entry) => `${entry.changeset.name} [${entry.world}]`).join(', ') : 'none — create one with `volter-world changeset create <world> <name>`'})`);
+}
+// ── replay ─────────────────────────────────────────────────────────────────────────────────────
+/**
+ * Which state service a replayed action lands in for a given target world service:
+ * the changeset's own state service when the target already records under it (or records
+ * nothing yet — a fresh world, the CI case), the target's single existing state service when
+ * it uses a different name, and a loud error when the target records under several and none of
+ * them is the one the changeset names (there is no correct guess there).
+ */
+function resolveTargetStateService(into, service, controlRoot, wanted) {
+    const existing = stateServicesFor(controlRoot);
+    if (existing.length === 0 || existing.includes(wanted))
+        return wanted;
+    if (existing.length === 1)
+        return existing[0];
+    throw new Error(`World "${into}" service "${service}" records actions under multiple state services (${existing.join(', ')}) and none is "${wanted}" — cannot decide where to replay`);
+}
+/** The replay targets a changeset needs inside an existing world (services the world lacks are
+ *  left out — `replayChangeset` reports them loudly by name). */
+function worldReplayTargets(changeset, into, root) {
+    const instance = requireWorld(into, root);
+    const available = Object.keys(instance.services).sort();
+    const targets = [];
+    for (const service of [...new Set(changeset.actions.map((entry) => entry.service))]) {
+        if (!instance.services[service])
+            continue; // reported as a missing twin by replayChangeset
+        const controlRoot = join(instance.dirs.data, service);
+        const wanted = changeset.actions.find((entry) => entry.service === service).stateService;
+        targets.push({ service, stateService: resolveTargetStateService(into, service, controlRoot, wanted), controlRoot });
+    }
+    return { targets, available, dataDir: instance.dirs.data };
+}
+/** Replay a changeset into `into`'s twins, through the control plane's kernel write path. */
+export async function replayWorldChangeset(name, options) {
+    const root = resolveRoot(options.root);
+    const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+    const { targets, available } = worldReplayTargets(located.changeset, options.into, root);
+    return replayChangeset(located.changeset, { into: options.into, targets, available });
+}
+/** The label a throwaway verify target reports as `into` — not a world name on purpose. */
+export const EPHEMERAL_VERIFY_TARGET = 'ephemeral';
+/**
+ * `volter-world changeset verify <name> --into <world> | --ephemeral`: replay the changeset
+ * into a clean target, run its verifiers against the post-replay projected state, and record
+ * the outcome ON the object as `verification` — REPLACING any prior run (the record carries
+ * its own provenance: when, into what, against which body hash and world digest). The body
+ * hash never moves: verification is about-the-body metadata, like approvals.
+ *
+ * `--ephemeral` builds a throwaway replay target (fresh empty ledgers per twin, no world
+ * booted), verifies against it, and removes it — the zero-setup CI check. `--into` verifies
+ * inside an existing world, whose twins must cover the changeset AND its verifiers.
+ */
+export async function verifyWorldChangeset(name, options) {
+    const root = resolveRoot(options.root);
+    if (Boolean(options.into) === Boolean(options.ephemeral)) {
+        throw new Error('volter-world changeset verify: pass exactly one of --into <world> (verify inside an existing world) or --ephemeral (a throwaway replay target)');
+    }
+    const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+    const changeset = located.changeset;
+    if (!changesetHashMatches(changeset)) {
+        throw new Error(`Refusing to verify changeset "${name}": its stored contentHash does not match its body — the object drifted after authoring, and a verification would launder that drift`);
+    }
+    const intoLabel = options.into ?? EPHEMERAL_VERIFY_TARGET;
+    let scratch = null;
+    let targets;
+    let available;
+    if (options.into) {
+        const resolved = worldReplayTargets(changeset, options.into, root);
+        targets = resolved.targets;
+        available = resolved.available;
+        // a verifier may check a twin the actions never touched — it still needs a real target
+        for (const verifier of changeset.verifiers) {
+            if (targets.some((target) => target.service === verifier.service))
+                continue;
+            if (!available.includes(verifier.service)) {
+                throw new Error(`Cannot verify changeset "${name}" in world "${options.into}": verifier "${verifier.id}" checks twin "${verifier.service}", which that world does not have (world "${options.into}" has: ${available.join(', ') || 'no services'})`);
+            }
+            const controlRoot = join(resolved.dataDir, verifier.service);
+            targets.push({ service: verifier.service, stateService: resolveTargetStateService(options.into, verifier.service, controlRoot, verifier.service), controlRoot });
+        }
+    }
+    else {
+        scratch = join(tmpdir(), `volter-world-verify-${crypto.randomUUID()}`);
+        const pairs = new Map();
+        for (const entry of changeset.actions) {
+            pairs.set(`${entry.service} ${entry.stateService}`, { service: entry.service, stateService: entry.stateService, controlRoot: join(scratch, entry.service) });
+        }
+        for (const verifier of changeset.verifiers) {
+            if (![...pairs.values()].some((target) => target.service === verifier.service)) {
+                pairs.set(`${verifier.service} ${verifier.service}`, { service: verifier.service, stateService: verifier.service, controlRoot: join(scratch, verifier.service) });
+            }
+        }
+        targets = [...pairs.values()];
+    }
+    try {
+        const report = await replayChangeset(changeset, { into: intoLabel, targets, ...(available ? { available } : {}) });
+        const at = (options.now ?? new Date()).toISOString();
+        const verification = runChangesetVerifiers(changeset, targets, { at, into: intoLabel });
+        // the world's checks (CI on deployment): every entry, against the replayed tree
+        const checks = await loadWorldChecks(root);
+        const refusals = [];
+        for (const entry of changeset.actions) {
+            const target = targets.find((t) => t.service === entry.service && t.stateService === entry.stateService) ?? targets.find((t) => t.service === entry.service);
+            const verdict = await runChecks(checks, entry.action, target ? readTree(target.stateService, target.controlRoot) : []);
+            if (verdict)
+                refusals.push({ actionId: entry.action.id, service: entry.service, check: verdict.name, reason: verdict.reason });
+        }
+        if (refusals.length) {
+            verification.refusals = refusals;
+            verification.passed = false;
+        }
+        const updated = withVerification(changeset, verification);
+        writeChangesetFile(located.path, updated);
+        return { changeset: updated, verification, report, world: located.world, path: located.path };
+    }
+    finally {
+        if (scratch)
+            getActiveWorldStore().remove(scratch);
+    }
+}
+/** `volter-world changeset approve <name> --as <principal>`: append an approval bound to the
+ *  current body hash. The control plane refuses a drifted object loudly. */
+export function approveWorldChangeset(name, options) {
+    const root = resolveRoot(options.root);
+    const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+    const { changeset, approval } = approveChangeset(located.changeset, {
+        principal: options.principal,
+        ...(options.note ? { note: options.note } : {}),
+        ...(options.now ? { at: options.now.toISOString() } : {}),
+    });
+    writeChangesetFile(located.path, changeset);
+    return { changeset, approval, world: located.world, path: located.path };
+}
+/** `volter-world changeset status <name>`: the apply-readiness gate, recomputed from the
+ *  object. Truth only — pushing is v2's job. */
+export function statusWorldChangeset(name, options = {}) {
+    const root = resolveRoot(options.root);
+    const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+    return changesetReadiness(located.changeset);
+}
+export async function pushWorldChangeset(name, options) {
+    // PUSH (docs/concepts/the-model.md): the changeset goes to the served world's push door; its
+    // entries land on that world's log, and each receipt (landed under gated/hold, deployed/refused/
+    // failed under auto) is landed here on the parent log too, so `log --receipts` shows it and the
+    // entry stops being unpushed. The changeset object records the application as before.
+    const root = resolveRoot(options.root);
+    const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+    const instance = requireWorld(located.world, root);
+    const url = (options.to ?? instance.origin?.url)?.replace(/\/+$/, '');
+    const namespace = options.namespace ?? instance.origin?.namespace;
+    if (!url || !namespace)
+        throw new Error(`World "${located.world}" has no origin to push to — \`volter remote add origin <url> --token <token>\` names one`);
+    // over http to a served world's push door, or straight into a world at a path (git's file transport)
+    let res;
+    let body;
+    const expect = {};
+    for (const a of located.changeset.actions) {
+        const meta = readBranchMeta(a.stateService ?? a.service, join(instance.dirs.data, a.service));
+        const pointer = meta?.origin ?? meta?.parent;
+        if (meta?.origin?.incomplete)
+            throw new Error('The branch cuts through its tracked origin; pull and rebase before pushing');
+        const view = isPathRemote(url) ? pointer?.view : pointer?.remoteView;
+        if (pointer && view)
+            expect[a.service] = { view, position: pointer.position };
+    }
+    // THE RESOURCE PAYLOADS the entries name (uploaded media, file bytes), in two phases. Content-addressed
+    // blobs (a key segment that IS a sha256) never change, so they go before the entries: a refused push
+    // leaves only bytes nothing names yet. Records kept by name (an upload's status, a media record) are the
+    // branch's state moving forward and go only after the entries landed, so a push the origin refuses
+    // (drift) never overwrites the origin's newer records.
+    const blobs = getActiveBlobStore();
+    const twins = [...new Map(located.changeset.actions.map((a) => [a.service, a.stateService ?? a.service])).entries()];
+    const ownBlobs = async (twin, state) => {
+        const dir = worldPaths(state, join(instance.dirs.data, twin)).resources;
+        return (await blobs.list(dir)).map((path) => ({ key: relative(dir, path).split('\\').join('/'), path }));
+    };
+    // content-addressed means a segment of the key IS the digest of the bytes it holds: such bytes never
+    // change. A name built on a digest of something else (a record keyed by a hash of an action id, a
+    // type keyed by its blob's digest) may change, so it is a record kept by name.
+    // each blob is read and hashed once per push, and a key with no 64-hex segment is never read to classify it
+    const digests = new Map();
+    const digestOf = async (path) => {
+        if (!digests.has(path)) {
+            const bytes = await blobs.get(path);
+            digests.set(path, bytes === null ? null : blobDigest(bytes));
+        }
+        return digests.get(path);
+    };
+    const contentAddressed = async (key, path) => {
+        if (!key.split('/').some((seg) => /^[0-9a-f]{64}$/.test(seg)))
+            return false;
+        const digest = await digestOf(path);
+        return digest !== null && key.split('/').includes(digest);
+    };
+    const sendBlobs = async (phase) => {
+        const wanted = async (key, path) => (phase === 'content') === (await contentAddressed(key, path));
+        if (isPathRemote(url)) {
+            const target = localWorld(url);
+            for (const [twin, state] of twins) {
+                const there = worldPaths(state, join(target.instance.dirs.data, twin)).resources;
+                for (const { key, path } of await ownBlobs(twin, state)) {
+                    if (!(await wanted(key, path)))
+                        continue;
+                    const held = await blobs.get(join(there, key));
+                    if (held !== null && blobDigest(held) === (await digestOf(path)))
+                        continue;
+                    const bytes = await blobs.get(path);
+                    if (bytes)
+                        await blobs.put(join(there, key), bytes);
+                }
+            }
+            return;
+        }
+        for (const [twin, state] of twins) {
+            for (const { key, path } of await ownBlobs(twin, state)) {
+                if (!(await wanted(key, path)))
+                    continue;
+                const at = `${url}/-/${namespace}/blobs/${twin}/${key.split('/').map(encodeURIComponent).join('/')}`;
+                const head = await fetch(at, { method: 'HEAD', headers: { [TOKEN_HEADER]: options.key } });
+                // no blobs door for this twin there (older code, or the twin is not in that World): it takes entries only
+                if (head.status === 404 && head.headers.get('x-volter-blob') !== 'absent')
+                    break;
+                if (head.status === 200 && head.headers.get('x-volter-blob-sha256') === (await digestOf(path)))
+                    continue;
+                const bytes = await blobs.get(path);
+                if (!bytes)
+                    continue;
+                const put = await fetch(at, { method: 'PUT', headers: { [TOKEN_HEADER]: options.key, 'content-type': 'application/octet-stream' }, body: new Blob([bytes]) });
+                if (!put.ok)
+                    throw new Error(`push: the origin refused ${twin}'s ${key} (${put.status} ${(await put.text()).slice(0, 200)})`);
+            }
+        }
+    };
+    await sendBlobs('content');
+    if (isPathRemote(url)) {
+        try {
+            const target = localWorld(url);
+            const receipts = await landChangeset(target.name, target.root, target.instance, located.changeset, expect);
+            const position = Object.fromEntries([...new Set(located.changeset.actions.map((a) => a.service))].map((twin) => { const st = located.changeset.actions.find((e) => e.service === twin)?.stateService ?? twin; return [twin, wholeLog(st, join(target.instance.dirs.data, twin)).length]; }));
+            const snapshots = Object.fromEntries(Object.keys(position).map(twin => { const state = located.changeset.actions.find(a => a.service === twin)?.stateService ?? twin; const head = captureHistory(state, join(target.instance.dirs.data, twin)); return [twin, { view: head.view, position: head.position }]; }));
+            body = { receipts, position, snapshots };
+            res = { ok: true, status: 200 };
+        }
+        catch (error) {
+            body = { error: error instanceof Error ? error.message : String(error) };
+            res = { ok: false, status: 409 };
+        }
+    }
+    else {
+        // the client's position on each twin rides along (its fetch cursor): the door refuses when origin moved past it
+        const answer = await fetchReady(`${url}/-/${namespace}/push`, { method: 'POST', headers: { [TOKEN_HEADER]: options.key, 'content-type': 'application/json' }, body: JSON.stringify({ changeset: located.changeset, expect }) });
+        body = (await answer.json());
+        res = { ok: answer.ok, status: answer.status };
+    }
+    const at = new Date().toISOString();
+    if (!res.ok || !body.receipts) {
+        const refusal = body.refusal ?? [body.error ?? `the remote answered ${res.status}`];
+        const application = { at, contentHash: located.changeset.contentHash, outcome: 'refused', refusal, receipts: [], compensation: [] };
+        writeChangesetFile(located.path, withApplication(located.changeset, application));
+        return { application, changeset: withApplication(located.changeset, application), world: located.world, path: located.path, remote: { url, namespace } };
+    }
+    // the entries landed: the records they name follow (retried; a failure is reported only after this
+    // push's application and receipts are recorded, so the entries that landed are never forgotten here)
+    let namedFailure = null;
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            await sendBlobs('named');
+            namedFailure = null;
+            break;
+        }
+        catch (error) {
+            namedFailure = error;
+        }
+    }
+    // origin advanced by what landed (and what it performed): the cursor moves with it, so the next
+    // fetch and the next push start from where origin now stands
+    if (body.snapshots && instance.origin) {
+        const twins = Object.keys(body.snapshots);
+        const fetched = await fetchFromOrigin(located.world, { root, url, namespace, key: options.key, services: twins, views: body.snapshots });
+        for (const twin of twins) {
+            const st = located.changeset.actions.find(e => e.service === twin)?.stateService ?? twin;
+            const cr = join(instance.dirs.data, twin);
+            const meta = readBranchMeta(st, cr);
+            if (!meta?.parent)
+                continue;
+            if (meta.origin)
+                rebaseBranch(st, cr, { origin: true });
+            else {
+                const snapshot = fetched.snapshots[twin];
+                writeBranchMeta(st, { ...meta, parent: { ...meta.parent, ...snapshot } }, cr);
+            }
+        }
+    }
+    // land each receipt on this world's parent log, per twin's state service
+    const byTwin = new Map();
+    for (const r of body.receipts)
+        byTwin.set(r.twin, [...(byTwin.get(r.twin) ?? []), r]);
+    for (const [twin, receipts] of byTwin) {
+        const entry = located.changeset.actions.find((e) => e.service === twin);
+        const state = entry?.stateService ?? twin;
+        landReceipts(join(instance.dirs.data, twin), state, receipts, at);
+    }
+    const statusOf = (s) => (s === 'deployed' ? 'confirmed' : s === 'landed' ? 'replayed' : s === 'refused' || s === 'failed' ? 'failed' : 'skipped');
+    const receipts = body.receipts.map((r) => ({ actionId: r.actionId, service: r.twin, stateService: located.changeset.actions.find((e) => e.service === r.twin)?.stateService ?? r.twin, status: statusOf(r.status), ...(r.externalId ? { externalId: r.externalId } : {}), ...(r.reason ? { error: r.reason } : {}) }));
+    const outcome = receipts.every((r) => r.status !== 'failed') ? 'applied' : receipts.some((r) => r.status === 'confirmed') ? 'partial' : 'refused';
+    const application = { at, contentHash: located.changeset.contentHash, outcome, receipts, compensation: [], ...(outcome === 'refused' ? { refusal: receipts.filter((r) => r.error).map((r) => r.error) } : {}) };
+    const changeset = withApplication(located.changeset, application);
+    writeChangesetFile(located.path, changeset);
+    const unsent = namedFailure ? `records the landed entries name did not reach the origin (${namedFailure instanceof Error ? namedFailure.message : String(namedFailure)}); the next push from this branch that touches ${twins.map(([t]) => t).join(', ')} sends them` : undefined;
+    return { ...(unsent ? { unsent } : {}), application, changeset, world: located.world, path: located.path, remote: { url, namespace } };
+}
+/** `volter-world changeset rebase <name>`: the merge onto the authoring world's moved mirror. */
+export function rebaseWorldChangeset(name, options = {}) {
+    const root = resolveRoot(options.root);
+    const located = findWorldChangeset(name, { root, ...(options.world ? { world: options.world } : {}) });
+    // the branch first: its pointer moves to the parent's current position (what a fetch brought in)
+    withAncestryLock(() => {
+        const inst = requireWorld(located.world, root);
+        for (const service of new Set(located.changeset.actions.map((e) => e.service))) {
+            const st = located.changeset.actions.find((e) => e.service === service)?.stateService ?? service;
+            const controlRoot = join(inst.dirs.data, service);
+            rebaseBranch(st, controlRoot, { origin: Boolean(readBranchMeta(st, controlRoot)?.origin) });
+        }
+    });
+    if (!changesetHashMatches(located.changeset))
+        throw new Error(`Refusing to rebase changeset "${name}": its stored contentHash does not match its body — the object drifted after authoring`);
+    const instance = requireWorld(located.world, root);
+    const targets = [...new Set(located.changeset.actions.map((entry) => entry.service))].map((service) => ({ service, stateService: located.changeset.actions.find((entry) => entry.service === service).stateService, controlRoot: join(instance.dirs.data, service) }));
+    const { changeset, report } = rebaseChangeset(located.changeset, { targets, ...(options.now ? { at: options.now.toISOString() } : {}) });
+    if (report.outcome === 'rebased')
+        writeChangesetFile(located.path, changeset);
+    return { changeset, report, world: located.world, path: located.path };
+}

package/dist/src/cli.d.ts

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