@volter/world-machine 2.0.0

package/dist/src/cli.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// world-machine — the machine as a World `process` service (README.md).
+//
+//   world-machine setup --config <file> [--make-store <size>]   prepare the machine host (idempotent)
+//   world-machine base  --config <file>                         advance the warm base build one step; rerun until ready
+//   world-machine gc    --config <file>                         delete the snapshots and warm bases no World's branch names
+//   world-machine serve --config <file> --port <n> --root <dir> the service (the World passes --port and --root)
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, linkSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { dirname, join, resolve } from 'node:path';
+import { stepBase } from "./base.js";
+import { ContainerMachine, stepContainerBase } from "./container.js";
+import { loadConfig } from "./config.js";
+import { HostSession, q } from "./host.js";
+import { hp, Machine } from "./machine.js";
+import { collect, register } from "./gc.js";
+// when this module's own code first runs: every import is done (the process started at performance.timeOrigin)
+const importedAt = Math.round(performance.now());
+const args = process.argv.slice(2);
+const flag = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const command = args[0];
+const out = (value) => { process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value, null, 2)}\n`); };
+function configFromArgs() {
+    const path = flag('--config');
+    if (!path)
+        throw new Error(`world-machine ${command}: --config <machine.json> is required`);
+    return loadConfig(path);
+}
+const FC_VERSION = 'v1.17.0';
+/** The doors' key, a file beside the machine's configuration (serve). */
+export const DOOR_TOKEN_FILE = '.world-machine-token';
+async function setup(config) {
+    const session = new HostSession(config);
+    try {
+        const size = flag('--make-store');
+        const container = config.backend === 'container';
+        const lines = container ? [
+            // the container backend needs no KVM: crun and CRIU run the machine, podman fills its tree from the image
+            'for p in socat crun criu podman; do command -v $p >/dev/null || sudo -n apt-get install -y -qq $p >/dev/null || { wm_fail "$p is missing"; return 1; }; done',
+            'sudo -n criu check >/dev/null 2>&1 || { wm_fail "criu check fails on this kernel: $(sudo -n criu check 2>&1 | tail -1)"; return 1; }',
+            // CRIU refuses a listener with a connection the kernel accepted but the paused process has not (measured: a mark failed
+            // under requests to a published port); skipped, the client sees a reset and retries. crun reads CRIU's default config
+            "{ sudo -n mkdir -p /etc/criu && { grep -qx skip-in-flight /etc/criu/default.conf 2>/dev/null || echo skip-in-flight | sudo -n tee -a /etc/criu/default.conf >/dev/null; }; } || { wm_fail \"cannot write /etc/criu/default.conf\"; return 1; }",
+            // the tree's export: the host's NFS server, v3 only, mountd on the port the machine's forward names
+            ...(config.export ? [
+                'command -v exportfs >/dev/null || sudo -n apt-get install -y -qq nfs-kernel-server >/dev/null || { wm_fail "nfs-kernel-server is missing"; return 1; }',
+                `printf '[mountd]\\nport=20048\\n[nfsd]\\nvers3=y\\nvers4=n\\nudp=n\\n' | sudo -n tee /etc/nfs.conf.d/world-machine.conf >/dev/null && sudo -n mkdir -p /etc/exports.d && sudo -n rm -f /etc/exports.d/world-machine-$WM_SLOT.exports && sudo -n systemctl restart nfs-server || { wm_fail "cannot configure the NFS server"; return 1; }`,
+            ] : []),
+        ] : [
+            // udev resets /dev/kvm on change events; a rule keeps it usable where a one-off chmod does not
+            `if [ ! -w /dev/kvm ] || [ ! -f /etc/udev/rules.d/99-world-machine-kvm.rules ]; then echo 'KERNEL=="kvm", MODE="0666"' | sudo -n tee /etc/udev/rules.d/99-world-machine-kvm.rules >/dev/null && sudo -n udevadm control --reload && sudo -n udevadm trigger --name-match=kvm && sudo -n udevadm settle; fi`,
+            '[ -w /dev/kvm ] || { wm_fail "/dev/kvm is not writable (no KVM here: on a Mac, a Lima >= 2 VM with nestedVirtualization: true)"; return 1; }',
+            'command -v socat >/dev/null || sudo -n apt-get install -y -qq socat >/dev/null || { wm_fail "socat is missing"; return 1; }',
+        ];
+        if (size) {
+            // a loop-mounted image when the host's own filesystem cannot reflink; persisted in fstab. btrfs with zstd where the
+            // host has it: a mark's pages composed against its parent's (compose.py) keep only the new ones, compressed
+            // (measured: 25 MB for a 1.3 GB dump; 254 MB compressed alone). compress-force: with `compress` btrfs's heuristic
+            // left a mark's new pages uncompressed (687 MB), and it also compresses the tree's image (chattr +m does not stop
+            // it; a first compile measured 1.03-1.23x the Mac's). An XFS image made before is used as it is.
+            lines.push(
+            // only where the store cannot reflink already (a store on XFS or btrfs is used as it is)
+            'mkdir -p "$WM_STORE"; t="$WM_STORE/.reflink-probe"; : > "$t"; if cp --reflink=always "$t" "$t.2" 2>/dev/null; then cow=1; else cow=0; fi; rm -f "$t" "$t.2"', 'if [ "$cow" = 0 ] && ! mountpoint -q "$WM_STORE"; then', `  sudo -n mkdir -p /var/lib/volter-world-machine; old=/var/lib/volter-world-machine/store-$WM_SLOT.xfs; img=/var/lib/volter-world-machine/store-$WM_SLOT.btrfs`, '  if [ -f "$old" ]; then img=$old; fs=xfs; opts=loop,nofail', 
+            // a btrfs store made before is never replaced: without btrfs here, setup fails rather than mount an empty XFS over it
+            '  elif [ -f "$img" ]; then { command -v mkfs.btrfs >/dev/null || sudo -n apt-get install -y -qq btrfs-progs >/dev/null; } && sudo -n modprobe btrfs || { wm_fail "the store $img is btrfs and btrfs is not available here"; return 1; }; fs=btrfs; opts=loop,nofail,compress-force=zstd:1', '  elif { command -v mkfs.btrfs >/dev/null || sudo -n apt-get install -y -qq btrfs-progs >/dev/null; } && sudo -n modprobe btrfs 2>/dev/null; then fs=btrfs; opts=loop,nofail,compress-force=zstd:1', '  else img=$old; fs=xfs; opts=loop,nofail; command -v mkfs.xfs >/dev/null || sudo -n apt-get install -y -qq xfsprogs >/dev/null || { wm_fail "xfsprogs is missing"; return 1; }; fi', `  [ -f "$img" ] || { sudo -n truncate -s ${q(size)} "$img" && if [ "$fs" = btrfs ]; then sudo -n mkfs.btrfs -q "$img"; else sudo -n mkfs.xfs -q -m reflink=1 "$img"; fi; } || { wm_fail "cannot make $img"; return 1; }`, '  mkdir -p "$WM_STORE" && sudo -n mount -t "$fs" -o "$opts" "$img" "$WM_STORE" && sudo -n chown "$(id -u):$(id -g)" "$WM_STORE" || { wm_fail "cannot mount $img at $WM_STORE"; return 1; }', '  grep -q "$img" /etc/fstab || { echo "$img $WM_STORE $fs $opts 0 0" | sudo -n tee -a /etc/fstab >/dev/null && sudo -n systemctl daemon-reload; }', 'fi', 'mkdir -p "$WM_STORE/snapshots" "$WM_SLOTDIR"');
+        }
+        if (container)
+            lines.push('wm_reflink_check || return 1', 'wm_ct_net || return 1', 'printf \'@{"crun":"%s","criu":"%s","store":"%s"}\\n\' "$(crun --version | head -1)" "$(criu --version | head -1)" "$WM_STORE"');
+        else
+            lines.push('wm_reflink_check || return 1', 
+            // Firecracker and its snapshot-editor, the pinned release, when the configured paths hold nothing
+            `if [ ! -x "$WM_FC" ] || [ ! -x "$WM_SE" ]; then`, `  a=$(uname -m); t=$(mktemp -d); curl -fsSL -o "$t/fc.tgz" https://github.com/firecracker-microvm/firecracker/releases/download/${FC_VERSION}/firecracker-${FC_VERSION}-$a.tgz && tar -xzf "$t/fc.tgz" -C "$t" || { wm_fail "cannot download Firecracker ${FC_VERSION}"; return 1; }`, `  mkdir -p "$(dirname "$WM_FC")" "$(dirname "$WM_SE")"; [ -x "$WM_FC" ] || install -m 755 "$t/release-${FC_VERSION}-$a/firecracker-${FC_VERSION}-$a" "$WM_FC"; [ -x "$WM_SE" ] || install -m 755 "$t/release-${FC_VERSION}-$a/snapshot-editor-${FC_VERSION}-$a" "$WM_SE"; rm -rf "$t"`, 'fi', `for f in ${hp(config.kernel)} ${hp(config.rootfs)} ${hp(config.sshKey)}; do [ -r "$f" ] || { wm_fail "the configured $f is not readable on the machine host"; return 1; }; done`, 'wm_net || return 1', 'printf \'@{"firecracker":"%s","store":"%s"}\\n\' "$("$WM_FC" --version | head -1)" "$WM_STORE"');
+        out(await session.call(lines.join('\n')));
+    }
+    finally {
+        session.close();
+    }
+}
+async function base(config) {
+    const session = new HostSession(config);
+    try {
+        const step = config.backend === 'container' ? await stepContainerBase(config, session) : await stepBase(config, session);
+        out(step);
+        if (!step.ready)
+            process.exitCode = 3;
+    }
+    finally {
+        session.close();
+    }
+}
+async function gc(config) {
+    const session = new HostSession(config);
+    try {
+        out(await collect(config, session));
+    }
+    finally {
+        session.close();
+    }
+}
+function send(res, status, body) {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(`${JSON.stringify(body)}\n`);
+}
+async function readJson(req) {
+    let text = '';
+    for await (const chunk of req)
+        text += chunk;
+    if (!text.trim())
+        return {};
+    const value = JSON.parse(text);
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw Object.assign(new Error('the body must be a JSON object'), { status: 400 });
+    return value;
+}
+async function serve(config) {
+    const port = Number(flag('--port') ?? process.env.PORT);
+    const root = flag('--root');
+    if (!Number.isInteger(port) || port <= 0)
+        throw new Error('world-machine serve: --port (or PORT) is required');
+    if (!root)
+        throw new Error('world-machine serve: --root <dir> is required (the World passes the service data dir)');
+    const machine = config.backend === 'container' ? new ContainerMachine(config, root, process.env, port) : new Machine(config, root, process.env, port);
+    // The doors' key: every request names it (`authorization: Bearer <token>`). Loopback is not enough: the machine's own
+    // processes reach this host's loopback through the World's egress proxy, which forwards local destinations, and a
+    // door can restore, copy into and run commands in the machine. The key is a file beside this configuration, on this
+    // host only (the machine never mounts it), made once and shared by every branch's machine of the World; a caller
+    // (supercode-retake) reads it there.
+    const tokenFile = join(dirname(resolve(flag('--config'))), DOOR_TOKEN_FILE);
+    // written whole beside and linked into place (never an empty or half-written key another serve reads), and only
+    // served with a key of its full length
+    if (!existsSync(tokenFile)) {
+        const tmp = `${tokenFile}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${randomBytes(32).toString('hex')}\n`, { mode: 0o600 });
+        try {
+            linkSync(tmp, tokenFile);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        finally {
+            unlinkSync(tmp);
+        }
+    }
+    const key = readFileSync(tokenFile, 'utf8').trim();
+    if (!/^[0-9a-f]{64}$/.test(key))
+        throw new Error(`world-machine serve: the door key ${tokenFile} is not a 64-hex-digit key; remove it and serve again`);
+    const doorToken = Buffer.from(`Bearer ${key}`);
+    // One operation at a time: a restore and a checkpoint never interleave.
+    let chain = Promise.resolve();
+    const serial = (fn) => { const next = chain.then(fn); chain = next.catch(() => undefined); return next; };
+    // Nothing is booted here: the machine comes up when a door first needs it (Machine.ensure).
+    const bringUp = async () => {
+        const started = Date.now();
+        const up = await machine.ensure();
+        if (up)
+            process.stderr.write(`world-machine: brought up (${up.from}) in ${Date.now() - started} ms\n`);
+        // the collection at start follows the first bring-up, never precedes it (measured: a first GET waited 1.5 s behind
+        // one deleting two bases)
+        startCollection();
+        return up;
+    };
+    // the store-wide collection: no operation on the slot, so it neither waits on nor holds the slot's lock
+    let marks = 0;
+    let collectedAtStart = false;
+    function startCollection() {
+        if (collectedAtStart || stopping)
+            return;
+        collectedAtStart = true;
+        void serial(collectUnlocked).catch((error) => process.stderr.write(`world-machine: gc at start: ${error.message}\n`));
+    }
+    const collectUnlocked = async () => {
+        machine.session.unlocked = true;
+        try {
+            const r = await collect(config, machine.session, root);
+            process.stderr.write(`world-machine: gc kept ${r.live} snapshots over ${r.branches} branches, deleted ${r.deletedSnapshots.length} snapshots (${r.expired.length} past retain), ${r.deletedBases.length} bases and ${r.deletedTrees.length} filled trees, freed ${r.freedBytes} bytes\n`);
+        }
+        finally {
+            machine.session.unlocked = false;
+        }
+    };
+    const server = createServer((req, res) => {
+        const route = `${req.method} ${(req.url ?? '').split('?')[0]}`;
+        // A browser on the host must not drive this: the port is loopback, and a VM's loopback is forwarded to its host (Lima),
+        // where any web page can send a cross-origin POST and a rebound DNS name can read an answer. A request a page sends
+        // carries Origin, or a Host that is not this listener's; a cross-origin POST with a JSON body must pass a preflight,
+        // which nothing here answers. Callers (the SDK, the World) send neither Origin nor another Host.
+        const host = String(req.headers.host ?? '');
+        const refusal = req.headers.origin !== undefined ? 'a request from a web page (it carries Origin)'
+            : !new RegExp(`^(127\\.0\\.0\\.1|localhost|\\[::1\\]):${port}$`).test(host) ? `a request for another host (${host.slice(0, 80) || 'none'})`
+                : req.method === 'POST' && !/^application\/json\b/i.test(String(req.headers['content-type'] ?? '')) ? 'a POST whose body is not application/json'
+                    : null;
+        if (refusal) {
+            send(res, 403, { error: `refused: ${refusal}` });
+            req.resume();
+            return;
+        }
+        const given = Buffer.from(String(req.headers.authorization ?? ''));
+        if (given.length !== doorToken.length || !timingSafeEqual(given, doorToken)) {
+            send(res, 401, { error: `refused: this door needs its key (authorization: Bearer <the token in ${DOOR_TOKEN_FILE} beside the machine's configuration>)` });
+            req.resume();
+            return;
+        }
+        const handle = async () => {
+            switch (route) {
+                case 'GET /machine': return [200, await serial(async () => { const up = await bringUp(); await machine.refresh().catch(() => undefined); return { ...machine.status(), ...(up ? { broughtUp: up } : {}) }; })];
+                case 'POST /machine/checkpoint': {
+                    const body = await readJson(req);
+                    const label = typeof body.label === 'string' ? body.label : '';
+                    // keep: a snapshot retention never lets go (with `thin`: a mark the agent pinned)
+                    const done = await serial(async () => { await bringUp(); return machine.checkpoint(label, body.keep === true); });
+                    // with `retain`, every tenth mark lets the oldest go, after the answer (the store-wide collection, unlocked)
+                    if (config.retain && ++marks % 10 === 0)
+                        void serial(collectUnlocked).catch((error) => process.stderr.write(`world-machine: gc after a mark: ${error.message}\n`));
+                    return [200, done];
+                }
+                case 'POST /machine/present': {
+                    const body = await readJson(req);
+                    const positions = Array.isArray(body.positions) ? body.positions.map(Number).filter((n) => Number.isInteger(n) && n > 0) : [];
+                    return [200, { snapshots: await serial(() => machine.present(positions)) }];
+                }
+                case 'POST /machine/compare': {
+                    // what a restore to that position would change (the container backend): files under a path, and processes
+                    const body = await readJson(req);
+                    const position = Number(body.position);
+                    if (!Number.isInteger(position) || position <= 0)
+                        return [400, { error: 'POST /machine/compare needs {position} (a machine ledger position)' }];
+                    if (!('compare' in machine))
+                        return [501, { error: 'compare is the container backend\'s' }];
+                    return [200, await serial(() => machine.compare(position, typeof body.path === 'string' ? body.path : undefined))];
+                }
+                case 'POST /machine/run': {
+                    // a command in the running machine (the container backend): {argv, user?, timeoutMs?} -> {code, stdout, stderr}
+                    const body = await readJson(req);
+                    const argv = Array.isArray(body.argv) && body.argv.length && body.argv.every((a) => typeof a === 'string') ? body.argv : null;
+                    if (!argv)
+                        return [400, { error: 'POST /machine/run needs {argv: [<program>, …], user?, timeoutMs?}' }];
+                    if (!(machine instanceof ContainerMachine))
+                        return [501, { error: 'run is the container backend\'s' }];
+                    const user = typeof body.user === 'string' && body.user ? body.user : undefined;
+                    const timeoutMs = Number.isFinite(body.timeoutMs) ? Number(body.timeoutMs) : undefined;
+                    return [200, await serial(() => machine.run(argv, user, timeoutMs))];
+                }
+                case 'POST /machine/files': {
+                    // part of the disk back at a position, the machine running on (the container backend): {position, paths}
+                    const body = await readJson(req);
+                    const position = Number(body.position);
+                    const paths = Array.isArray(body.paths) ? body.paths.filter((p) => typeof p === 'string' && p) : [];
+                    if (!Number.isInteger(position) || position <= 0 || !paths.length)
+                        return [400, { error: 'POST /machine/files needs {position, paths: [<path>, …]}' }];
+                    if (!(machine instanceof ContainerMachine))
+                        return [501, { error: 'files is the container backend\'s' }];
+                    // noLinks: a tree that must be whole in itself (a data directory): one holding a symlink is refused;
+                    // dryRun: the checks only, nothing touched
+                    return [200, await serial(() => machine.restoreFiles(position, paths, { noLinks: body.noLinks === true, dryRun: body.dryRun === true }))];
+                }
+                case 'POST /machine/restore': return [200, await serial(() => machine.restore())];
+                case 'POST /machine/prepare': {
+                    const body = await readJson(req);
+                    const position = Number(body.position);
+                    if (!Number.isInteger(position) || position <= 0)
+                        throw Object.assign(new Error('prepare needs {"position": <machine ledger position>, "live"?: true}'), { status: 400 });
+                    if (!(machine instanceof ContainerMachine))
+                        throw Object.assign(new Error('prepare is the container backend\'s'), { status: 501 });
+                    // live: the running machine itself handed over, neither restored nor paused (a partial retake: the machine stays)
+                    return [200, await serial(() => machine.prepare(position, body.live === true))];
+                }
+                case 'GET /machine/clock': return [200, await serial(async () => { if (machine.state !== 'running')
+                        throw Object.assign(new Error(`no clock to read: the machine is ${machine.state}`), { status: 409 }); return machine.clock(); })];
+                default: return [404, { error: `no route ${route}`, routes: ['GET /machine', 'POST /machine/checkpoint', 'POST /machine/restore', 'POST /machine/prepare', 'POST /machine/present', 'POST /machine/compare', 'POST /machine/files', 'POST /machine/run', 'GET /machine/clock'] }];
+            }
+        };
+        handle().then(([status, body]) => send(res, status, body), (error) => send(res, error.status ?? 500, { error: error.message }));
+    });
+    server.listen(port, '127.0.0.1', () => process.stderr.write(`world-machine: answering on ${port} at ${new Date().toISOString()}, ${Math.round(performance.now())} ms after the process started (imports done at ${importedAt} ms)\n`));
+    // This World joins the store's registry at once, and the store is collected (what no branch of any registered World
+    // names goes, gc.ts) after the machine's first bring-up, or 10 s after start when nothing brings it up by then. In the
+    // background, serialized with the machine's own operations.
+    void serial(async () => {
+        machine.session.unlocked = true;
+        try {
+            await register(machine.session, root);
+        }
+        finally {
+            machine.session.unlocked = false;
+        }
+    }).catch((error) => process.stderr.write(`world-machine: registering at start: ${error.message}\n`));
+    setTimeout(startCollection, 10_000).unref();
+    let stopping = false;
+    const stop = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        server.close();
+        serial(() => machine.stop()).finally(() => process.exit(0));
+        setTimeout(() => process.exit(0), 5000).unref();
+    };
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+}
+try {
+    if (command === 'setup')
+        await setup(configFromArgs());
+    else if (command === 'base')
+        await base(configFromArgs());
+    else if (command === 'serve')
+        await serve(configFromArgs());
+    else if (command === 'gc')
+        await gc(configFromArgs());
+    else {
+        process.stderr.write('Usage: world-machine setup|base|gc|serve --config <machine.json> (serve also takes --port and --root)\n');
+        process.exitCode = 2;
+    }
+}
+catch (error) {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+}

package/dist/src/compose.py

@@ -0,0 +1,82 @@
+#!/usr/bin/python3
+"""compose.py <parent criu dir> <mark criu dir>: a mark's CRIU page files rewritten in place so that every page
+identical to one of its parent's shares the parent's blocks (FICLONERANGE, runs coalesced), and only the other pages
+are new data. The container backend runs it detached after each mark (ct.sh wm_ct_compose). A mark is a full dump
+(arm64 has no soft-dirty tracking), and one turn later most of its pages are the parent's (measured on a `next dev`:
+95%). Written by reference from the start, the new data extents hold only new pages, so a compressing store (btrfs,
+compress-force=zstd) keeps only those, compressed: 25 MB for a 1.3 GB dump. A store's own block dedup after the fact
+(duperemove) freed almost nothing there, since a compressed extent lives while any page of it is unique. Each file is
+replaced by one rename (made beside the dump, with the file's own mode and owner), its content byte for byte the same,
+so a restore reading it meanwhile reads either copy.
+Prints one @{...} line: pages, duplicates, ranges cloned, seconds."""
+import fcntl, glob, hashlib, json, os, struct, sys, time
+
+FICLONERANGE = 0x4020940d
+PAGE = 4096
+CHUNK = PAGE * 256
+
+
+def pages(path):
+    """(offset, page) over a file, 4 KiB at a time."""
+    with open(path, 'rb') as fh:
+        off = 0
+        while True:
+            block = fh.read(CHUNK)
+            if not block: return
+            for i in range(0, len(block), PAGE): yield off + i, block[i:i + PAGE]
+            off += len(block)
+
+
+def main(parent, mark):
+    t0 = time.time()
+    index, fds = {}, {}
+    for f in sorted(glob.glob(os.path.join(parent, 'pages-*.img'))):
+        fds[f] = os.open(f, os.O_RDONLY)
+        for off, page in pages(f):
+            if len(page) == PAGE: index.setdefault(hashlib.blake2b(page, digest_size=16).digest(), (f, off))
+    total = dups = clones = 0
+    # the temporary files live beside the dump, not in it: a reader listing criu/ never sees a half-written one
+    work = os.path.join(os.path.dirname(os.path.abspath(mark)), '.compose')
+    os.makedirs(work, exist_ok=True)
+    for f in sorted(glob.glob(os.path.join(mark, 'pages-*.img'))):
+        tmp = os.path.join(work, os.path.basename(f))
+        st = os.stat(f)
+        # the file's own mode and owner (CRIU writes some 0600: a process's memory holds its secrets)
+        dst = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        os.fchown(dst, st.st_uid, st.st_gid); os.fchmod(dst, st.st_mode & 0o7777)
+        run = None  # [src path, src offset, dst offset, length]: the clonable run being gathered
+
+        def flush():
+            nonlocal clones
+            if run:
+                fcntl.ioctl(dst, FICLONERANGE, struct.pack('qQQQ', fds[run[0]], run[1], run[3], run[2]))
+                clones += 1
+        try:
+            size = 0
+            for off, page in pages(f):
+                total += 1; size = off + len(page)
+                hit = index.get(hashlib.blake2b(page, digest_size=16).digest()) if len(page) == PAGE else None
+                if hit:
+                    dups += 1
+                    if run and run[0] == hit[0] and run[1] + run[3] == hit[1] and run[2] + run[3] == off: run[3] += PAGE
+                    else: flush(); run = [hit[0], hit[1], off, PAGE]
+                else:
+                    flush(); run = None
+                    os.pwrite(dst, page, off)
+            flush()
+            os.ftruncate(dst, size)
+            os.fsync(dst)
+        except OSError as error:
+            # a store that cannot clone ranges (or a page file gone meanwhile): the mark stays as CRIU wrote it
+            os.close(dst); os.unlink(tmp)
+            try: os.rmdir(work)
+            except OSError: pass
+            print('@' + json.dumps({'composed': False, 'error': str(error)})); return
+        os.close(dst)
+        os.rename(tmp, f)
+    os.rmdir(work)
+    print('@' + json.dumps({'composed': True, 'pages': total, 'dups': dups, 'clones': clones, 'seconds': round(time.time() - t0, 2)}))
+
+
+if __name__ == '__main__':
+    main(*sys.argv[1:3])

package/dist/src/config.d.ts

@@ -0,0 +1,74 @@
+export type MachineHost = {
+    kind: 'linux';
+} | {
+    kind: 'lima';
+    instance: string;
+    limaHome: string;
+};
+/** The firecracker backend: a microVM on KVM, snapshotted by Firecracker (memory diffs, a reflinked disk). The
+ *  container backend (ct.sh): the host's own processes in a container, dumped by CRIU with their tree in one reflinked
+ *  image; for a host where a VM would be nested (a Mac: first-touch memory faulted through two hypervisors ran a real
+ *  install 20–80x slower). */
+export type MachineBackend = 'firecracker' | 'container';
+export type MachineConfig = {
+    host: MachineHost;
+    backend: MachineBackend;
+    /** container: the OCI image the machine's tree is made from, and the tree's size (a sparse ext4 image). */
+    image: string;
+    imageSize: string;
+    /** container: host directories bound read-only into the container (binaries the machine runs that its image lacks). */
+    binds: Array<{
+        source: string;
+        destination: string;
+    }>;
+    /** container: which of the machine's listening ports are published on the host's loopback at the same port, as the
+     *  machine's own localhost (publish.py): a twin delivering to `http://localhost:<port>` reaches the app, and a Lima host
+     *  forwards them on to the Mac. Only allowed ports: the machine runs code the user did not write, and a port it held
+     *  first would be taken from a host service that binds it later. None unless set. */
+    publishPorts?: {
+        ranges: Array<[number, number]>;
+        except: number[];
+    };
+    /** container: a path in the machine's tree served to `client` by the host's NFS server (v3), as `uid`:`gid`. */
+    export?: {
+        path: string;
+        client: string;
+        uid: number;
+        gid: number;
+    };
+    /** The reflink-capable directory (XFS or btrfs) holding warm bases, snapshots and the slot. */
+    store: string;
+    /** A mark is refused unless the store, the file backing it and each of `paths` (machine-host paths on the
+     *  filesystems beneath it, such as a Mac's home mounted in its Lima VM) have its estimate plus `reserveBytes` free. */
+    room: {
+        paths: string[];
+        reserveBytes: number;
+    };
+    /** How many of this World's snapshots the store keeps beyond every branch's head, the newest by when the host took
+     *  them; older ones are let go by gc (and named in the store's expired.list, so a restore of one says it was let go).
+     *  Another World on the store keeps its own. Every snapshot kept while a ledger names it when unset. */
+    retain?: number;
+    /** With `retain`: past the newest `retain`, the newest snapshot of each hour for a day and of each day for a month
+     *  stay too (thin.ts), and a snapshot taken with `keep` is never let go. */
+    thin?: boolean;
+    /** The one machine this service runs in place; its tap, addresses and disk path are fixed. */
+    slot: string;
+    firecracker: string;
+    snapshotEditor: string;
+    kernel: string;
+    rootfs: string;
+    /** The private key whose public half the rootfs authorizes for root. */
+    sshKey: string;
+    /** Absolute path of the provisioning script on the World's host, or undefined for none. */
+    provision?: string;
+    vcpus: number;
+    memMib: number;
+    tap: string;
+    hostIp: string;
+    guestIp: string;
+    /** A fixed guest-visible port per vendor, overriding the derived one. */
+    egressPorts: Record<string, number>;
+    /** Where the machine host reaches a twin listening on the World host's loopback. */
+    twinHost: string;
+};
+export declare function loadConfig(path: string): MachineConfig;

package/dist/src/config.js

@@ -0,0 +1,120 @@
+// The machine's declaration: a JSON file the World service names with `--config`. Paths to the
+// guest image, Firecracker and the store are paths ON THE MACHINE HOST (`~/` is that host's home);
+// `provision` is a script beside the config on the World's host, shipped into the guest when the warm
+// base is built.
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+const FIELDS = ['host', 'backend', 'image', 'imageSize', 'binds', 'export', 'publishPorts', 'store', 'room', 'retain', 'thin', 'slot', 'firecracker', 'snapshotEditor', 'kernel', 'rootfs', 'sshKey', 'provision', 'vcpus', 'memMib', 'tap', 'hostIp', 'guestIp', 'egressPorts'];
+export function loadConfig(path) {
+    const file = resolve(path);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`world-machine: cannot read the machine config ${file}: ${error.message}`);
+    }
+    for (const key of Object.keys(raw))
+        if (!FIELDS.includes(key) && !key.startsWith('//'))
+            throw new Error(`world-machine: unknown field "${key}" in ${file} (known: ${FIELDS.join(', ')})`);
+    const str = (key, fallback) => {
+        const v = raw[key] ?? fallback;
+        if (typeof v !== 'string' || v === '')
+            throw new Error(`world-machine: "${key}" must be a non-empty string in ${file}`);
+        return v;
+    };
+    const num = (key, fallback) => {
+        const v = raw[key] ?? fallback;
+        if (typeof v !== 'number' || !Number.isInteger(v) || v <= 0)
+            throw new Error(`world-machine: "${key}" must be a positive integer in ${file}`);
+        return v;
+    };
+    const hostRaw = (raw.host ?? (process.platform === 'darwin' ? undefined : { kind: 'linux' }));
+    let host;
+    if (hostRaw?.kind === 'linux')
+        host = { kind: 'linux' };
+    else if (hostRaw?.kind === 'lima' && typeof hostRaw.instance === 'string') {
+        const home = typeof hostRaw.limaHome === 'string' ? hostRaw.limaHome : process.env.LIMA_HOME ?? '~/.lima';
+        host = { kind: 'lima', instance: hostRaw.instance, limaHome: home.startsWith('~/') ? resolve(homedir(), home.slice(2)) : resolve(dirname(file), home) };
+    }
+    else
+        throw new Error(`world-machine: "host" must be {"kind":"linux"} or {"kind":"lima","instance":"<name>","limaHome":"<dir>"} in ${file} (on a Mac Firecracker runs inside a Lima >= 2 VM with nestedVirtualization: true)`);
+    const backend = str('backend', 'firecracker');
+    if (backend !== 'firecracker' && backend !== 'container')
+        throw new Error(`world-machine: "backend" must be "firecracker" or "container" in ${file}`);
+    const vm = backend === 'firecracker';
+    const store = str('store', '~/.cache/volter-world-machine');
+    const egressPorts = (raw.egressPorts ?? {});
+    if (typeof egressPorts !== 'object' || Object.values(egressPorts).some((p) => !Number.isInteger(p)))
+        throw new Error(`world-machine: "egressPorts" must map a vendor to a port in ${file}`);
+    const slot = str('slot', 'default');
+    if (!/^[a-z0-9-]+$/.test(slot))
+        throw new Error(`world-machine: "slot" must be lowercase letters, digits and dashes in ${file}`);
+    return {
+        host,
+        backend,
+        image: vm ? '' : str('image'),
+        imageSize: vm ? '' : str('imageSize', '40G'),
+        binds: vm ? [] : binds(raw.binds, file),
+        ...(raw.publishPorts === undefined ? {} : vm ? (() => { throw new Error(`world-machine: "publishPorts" is for the container backend only, in ${file}`); })() : { publishPorts: publishOf(raw.publishPorts, file) }),
+        ...(vm || raw.export === undefined ? {} : { export: exportOf(raw.export, file) }),
+        store,
+        room: roomOf(raw.room, file),
+        ...(raw.retain === undefined ? {} : { retain: num('retain', 1) }),
+        ...(raw.thin === undefined ? {} : typeof raw.thin !== 'boolean' ? (() => { throw new Error(`world-machine: "thin" must be true or false in ${file}`); })()
+            : raw.thin && raw.retain === undefined ? (() => { throw new Error(`world-machine: "thin" thins what "retain" lets go, and needs it, in ${file}`); })() : { thin: raw.thin }),
+        slot,
+        firecracker: str('firecracker', `${store}/bin/firecracker`),
+        snapshotEditor: str('snapshotEditor', `${store}/bin/snapshot-editor`),
+        kernel: vm ? str('kernel') : '',
+        rootfs: vm ? str('rootfs') : '',
+        sshKey: vm ? str('sshKey') : '',
+        ...(raw.provision === undefined ? {} : { provision: resolve(dirname(file), str('provision')) }),
+        vcpus: num('vcpus', 2),
+        memMib: num('memMib', 1024),
+        tap: str('tap', 'wm0'),
+        hostIp: str('hostIp', '172.16.0.1'),
+        guestIp: str('guestIp', '172.16.0.2'),
+        egressPorts,
+        twinHost: host.kind === 'lima' ? 'host.lima.internal' : '127.0.0.1',
+    };
+}
+function binds(raw, file) {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw) || raw.some((b) => typeof b?.source !== 'string' || typeof b?.destination !== 'string' || !b.destination.startsWith('/'))) {
+        throw new Error(`world-machine: "binds" must be [{"source":"<host dir>","destination":"/<path in the machine>"}] in ${file}`);
+    }
+    return raw;
+}
+function exportOf(raw, file) {
+    const e = raw;
+    if (typeof e?.path !== 'string' || !e.path.startsWith('/') || typeof e.client !== 'string' || !Number.isInteger(e.uid) || !Number.isInteger(e.gid)) {
+        throw new Error(`world-machine: "export" must be {"path":"/<path in the machine>","client":"<address>","uid":<n>,"gid":<n>} in ${file}`);
+    }
+    return { path: e.path, client: e.client, uid: e.uid, gid: e.gid };
+}
+function roomOf(raw, file) {
+    const r = (raw ?? {});
+    const paths = r.paths ?? [];
+    const reserveBytes = r.reserveBytes ?? 2 * 2 ** 30;
+    if (typeof r !== 'object' || !Array.isArray(paths) || paths.some((p) => typeof p !== 'string' || p === '') || !Number.isInteger(reserveBytes) || reserveBytes < 0) {
+        throw new Error(`world-machine: "room" must be {"paths":["<machine-host path>", ...],"reserveBytes":<n>} in ${file}`);
+    }
+    return { paths: paths, reserveBytes: reserveBytes };
+}
+function publishOf(raw, file) {
+    const r = raw;
+    const port = (n) => Number.isInteger(n) && n >= 1024 && n <= 65535;
+    const ranges = r?.ranges;
+    const except = r?.except ?? [];
+    if (!Array.isArray(ranges) || ranges.some((x) => !Array.isArray(x) || x.length !== 2 || !port(x[0]) || !port(x[1]) || x[0] > x[1]) || !Array.isArray(except) || except.some((n) => !port(n))) {
+        throw new Error(`world-machine: "publishPorts" must be {"ranges":[[from,to],...],"except":[port,...]} with ports 1024-65535 in ${file}`);
+    }
+    // the kernel hands out ephemeral ports from 32768 (Linux's default range): the World's own services take theirs there
+    if (ranges.some(([lo, hi]) => hi >= 32768 && lo <= 60999)) {
+        throw new Error(`world-machine: "publishPorts" ranges must stay below 32768 (the ephemeral ports the World's services use) in ${file}`);
+    }
+    return { ranges: ranges, except: except };
+}