@volter/world-machine 2.0.0

package/src/agent.py

@@ -0,0 +1,92 @@
+# world-machine-agent: runs inside the guest, started once when the warm base is built, so it is in
+# every snapshot. It answers the machine host on the guest's one link: it steps the wall clock to the
+# instant it is sent (a restored guest wakes at its snapshot's wall time), resets the connections a restore
+# left stale and writes the World's env file. One JSON object per line each way.
+import json, os, socket, socketserver, struct, time
+
+# After a restore every established TCP connection to the host on this link is stale by construction: its far
+# end belongs to the host as it was at the snapshot (a server listening here keeps the mark's client attached, a
+# client here waits out its own timeout). reset_stale resets each (the kernel's sock_destroy, what `ss -K` does:
+# CONFIG_INET_DIAG_DESTROY), the agent's own connection excepted (its port serves one connection at a time), over
+# sock_diag netlink in this process: measured, spawning `ss` from a just-restored guest took 1.0-2.3 s.
+NETLINK_SOCK_DIAG, SOCK_DIAG_BY_FAMILY, SOCK_DESTROY = 4, 20, 21
+NLM_F_REQUEST, NLM_F_ACK, NLM_F_DUMP, NLMSG_ERROR, NLMSG_DONE = 1, 4, 0x300, 2, 3
+TCP_ESTABLISHED = 1
+
+def _diag(family, states, sockid=b"\0" * 48):
+    return struct.pack("=BBBBI", family, socket.IPPROTO_TCP, 0, 0, states) + sockid
+
+def _talk(nl, kind, flags, payload, seq):
+    nl.send(struct.pack("=IHHII", 16 + len(payload), kind, flags, seq, 0) + payload)
+
+def reset_stale(host, own_port):
+    peer = socket.inet_aton(host)
+    nl = socket.socket(socket.AF_NETLINK, socket.SOCK_RAW, NETLINK_SOCK_DIAG)
+    try:
+        _talk(nl, SOCK_DIAG_BY_FAMILY, NLM_F_REQUEST | NLM_F_DUMP, _diag(socket.AF_INET, 1 << TCP_ESTABLISHED), 1)
+        stale, done = [], False
+        while not done:
+            data, off = nl.recv(65536), 0
+            while off + 16 <= len(data):
+                length, kind = struct.unpack_from("=IH", data, off)
+                if kind == NLMSG_DONE: done = True; break
+                if kind == NLMSG_ERROR: raise OSError(-struct.unpack_from("=i", data, off + 16)[0], "sock_diag dump failed")
+                sockid = data[off + 20:off + 68]  # inet_diag_msg: family, state, timer, retrans, then the id
+                sport = struct.unpack_from("!H", sockid, 0)[0]
+                if sockid[20:24] == peer and sport != own_port: stale.append(sockid)
+                off += (length + 3) & ~3
+        for i, sockid in enumerate(stale):
+            _talk(nl, SOCK_DESTROY, NLM_F_REQUEST | NLM_F_ACK, _diag(socket.AF_INET, 1 << TCP_ESTABLISHED, sockid), 2 + i)
+            data = nl.recv(65536)
+            err = -struct.unpack_from("=i", data, 16)[0]
+            if err and err != 2: raise OSError(err, "sock_destroy: %s" % os.strerror(err))  # ENOENT: it closed meanwhile
+        return len(stale)
+    finally:
+        nl.close()
+
+class Handler(socketserver.StreamRequestHandler):
+    def handle(self):
+        accepted = time.perf_counter()
+        setup_ms = round((accepted - Server.accepted_at) * 1000, 2)  # from accept() returning to this handler running
+        for line in self.rfile:
+            got = time.perf_counter()
+            try:
+                req = json.loads(line)
+                op = req.get("op")
+                if op == "clock":
+                    time.clock_settime(time.CLOCK_REALTIME, float(req["t"]))
+                    res = {"t": time.time()}
+                elif op == "shift":
+                    # moved by an amount against its own clock, read here: the step does not depend on when it arrives
+                    time.clock_settime(time.CLOCK_REALTIME, time.time() + float(req["by"]))
+                    res = {"t": time.time()}
+                elif op == "reset":
+                    res = {"reset": reset_stale(self.client_address[0], self.server.server_address[1])}
+                elif op == "now":
+                    res = {"t": time.time()}
+                elif op == "write":
+                    path = req["path"]; tmp = path + ".tmp"
+                    os.makedirs(os.path.dirname(path) or "/", exist_ok=True)
+                    with open(tmp, "w") as f: f.write(req["content"])
+                    os.replace(tmp, path)
+                    res = {"ok": True}
+                else:
+                    res = {"error": "unknown op %r" % op}
+            except Exception as e:
+                res = {"error": str(e)}
+            # where a reply's time goes inside the guest: waiting for the line since the connection was accepted, and
+            # handling it (a first request after a load faults this process's pages in from the snapshot file)
+            res["setupMs"] = setup_ms; setup_ms = 0.0
+            res["waitMs"] = round((got - accepted) * 1000, 2); res["handleMs"] = round((time.perf_counter() - got) * 1000, 2)
+            accepted = time.perf_counter()
+            self.wfile.write((json.dumps(res) + "\n").encode()); self.wfile.flush()
+
+# One connection at a time, on the serving thread: the first request after a load pays for every guest
+# page it touches (faulted in from the snapshot file), and a thread per connection touched more.
+class Server(socketserver.TCPServer):
+    allow_reuse_address = True
+    accepted_at = 0.0
+    def get_request(self):
+        r = super().get_request(); Server.accepted_at = time.perf_counter(); return r
+
+Server(("0.0.0.0", int(os.environ.get("WM_AGENT_PORT", "7070"))), Handler).serve_forever()

package/src/agentc.py

@@ -0,0 +1,81 @@
+# The machine host's client for the guest agent (agent.py). Clock arguments are seconds:
+# OFFSET is this host's clock minus the World host's clock, DELTA the World clock minus the World
+# host's clock (0 unless the World's clock is frozen). The target instant is therefore
+# time.time() - OFFSET + DELTA, read the moment before it is sent.
+import json, socket, sys, time
+
+ip, port, op = sys.argv[1], int(sys.argv[2]), sys.argv[3]
+started = time.time()
+deadline = time.time() + 3
+while True:
+    try:
+        s = socket.create_connection((ip, port), timeout=1); break
+    except OSError as e:
+        if time.time() > deadline: print('@' + json.dumps({"error": "guest agent unreachable at %s:%d: %s" % (ip, port, e)})); sys.exit(1)
+        time.sleep(0.005)
+# the first request after a load can wait on guest memory faulted in from the file
+s.settimeout(10); f = s.makefile("rwb")
+connectMs = round((time.time() - started) * 1000, 1)
+
+def call(req):
+    f.write((json.dumps(req) + "\n").encode()); f.flush()
+    return json.loads(f.readline())
+
+def probe(offset, delta, n=5):
+    best = None
+    for _ in range(n):
+        h0 = time.time(); g = call({"op": "now"})["t"]; h1 = time.time()
+        err = g - ((h0 + h1) / 2 - offset + delta)
+        if best is None or h1 - h0 < best[1]: best = (err, h1 - h0)
+    return best
+
+def write_files(files, out):
+    for path, content in files.items():
+        res = call({"op": "write", "path": path, "content": content})
+        if "error" in res: out["error"] = "guest agent: writing %s: %s" % (path, res["error"]); return False
+    return True
+
+if op in ("clock", "now"):
+    offset, delta = float(sys.argv[4]), float(sys.argv[5])
+    out = {}
+    # files to write on the same connection: one path, its content on stdin, or `-` and a JSON object of path ->
+    # content on stdin
+    files = (json.load(sys.stdin) if sys.argv[6] == "-" else {sys.argv[6]: sys.stdin.read()}) if len(sys.argv) > 6 else {}
+    # the restore id first, the first request after the load: a restored connection the guest drops while the clock
+    # is stepped (a second or more under load) must already find the new id
+    rid = [k for k in files if k == "/run/world-machine/restore-id"]
+    if rid and not write_files({rid[0]: files.pop(rid[0])}, out): print('@' + json.dumps(out)); sys.exit(0)
+    if op == "clock":
+        # The first request after a load waits on the guest waking (measured: its own handling 11 ms of a 288 ms
+        # reply); it is only the warm-up.
+        t0 = time.time(); first = call({"op": "now"}); before = first["t"]
+        out["connectMs"] = connectMs; out["firstReplyMs"] = round((time.time() - t0) * 1000, 1)
+        out["firstHandleMs"] = first.get("handleMs"); out["firstWaitMs"] = first.get("waitMs"); out["firstSetupMs"] = first.get("setupMs")
+        # Measure the guest's clock against the target over warm round trips, then move it by the difference,
+        # relative to its own time (op shift): unlike stepping to an instant sent ahead, the step does not land late
+        # by however long the request takes to be read (the first requests after a load wait on guest pages).
+        steps = 0
+        while True:
+            err, rtt = probe(offset, delta, 3)
+            if abs(err) <= 0.003 or steps == 4: break
+            call({"op": "shift", "by": -err}); steps += 1
+        out["clockMs"] = round((time.time() - t0) * 1000, 1)
+        out["steps"] = steps
+        out["steppedByMs"] = round(((time.time() - offset + delta) - before) * 1000)
+        # the files before the reset: a program whose connection the reset ends reads the new restore id (and the
+        # World's env) when it reconnects
+        if not write_files(files, out): print('@' + json.dumps(out)); sys.exit(0)
+        files = {}
+        # then the connections the restore left stale, once the clock reads now (a reset peer reconnects at once)
+        r0 = time.time(); res = call({"op": "reset"})
+        if "error" in res: print('@' + json.dumps({"error": "guest agent: resetting the stale connections: " + res["error"]})); sys.exit(1)
+        out["staleReset"] = res["reset"]; out["resetMs"] = round((time.time() - r0) * 1000, 1)
+    err, rtt = probe(offset, delta)
+    out.update({"errorMs": round(err * 1000, 2), "probeRttMs": round(rtt * 1000, 2)})
+    write_files(files, out)
+    print('@' + json.dumps(out))
+elif op == "write":
+    res = call({"op": "write", "path": sys.argv[4], "content": sys.stdin.read()})
+    print('@' + json.dumps(res))
+else:
+    print('@' + json.dumps({"error": "unknown op " + op})); sys.exit(1)

package/src/base.ts

@@ -0,0 +1,67 @@
+// The warm base: the declared guest image, cold-booted once, provisioned by the declared script, and
+// snapshotted whole, in a store-wide cache keyed by everything that shapes it. A World's machine never
+// cold-boots (20-60 s measured); it loads this or a snapshot. The build is a sequence of short steps,
+// each run by one `world-machine base` call that advances as far as it can without waiting and says
+// what it is waiting on; the caller runs it again.
+import { readFileSync } from 'node:fs';
+import type { MachineConfig } from './config.ts';
+import { GUEST_AGENT, GUEST_PROFILE, type HostSession } from './host.ts';
+import { baseHash, bootArgs, hp } from './machine.ts';
+import { q } from './host.ts';
+
+export type BaseStep = { base: string; stage: string; ready: boolean; detail?: string };
+
+export async function stepBase(config: MachineConfig, session: HostSession): Promise<BaseStep> {
+  await session.call('wm_reflink_check');
+  const hash = await baseHash(config, session);
+  const base = `base-${hash}`;
+  const B = `"$WM_STORE/${base}"`;
+  const W = `"$WM_STORE/${base}.building"`;
+  const has = async (test: string): Promise<boolean> => (await session.call<{ ok: boolean }>(`if ${test}; then echo '@{"ok":true}'; else echo '@{"ok":false}'; fi`)).ok;
+  const provision = config.provision ? readFileSync(config.provision, 'utf8') : '';
+
+  if (await has(`[ -f ${B}/vmstate ]`)) return { base, stage: 'ready', ready: true };
+
+  // 1. the rootfs, copied once into the store (it may not be on a reflink filesystem), in the background
+  if (!(await has(`[ -f ${W}/copied ]`))) {
+    // a copy that is no longer running (the host restarted, the store was remounted) is started again
+    if (!(await has(`[ ! -f ${W}/copying ] || kill -0 "$(cat ${W}/copy.pid 2>/dev/null)" 2>/dev/null`))) await session.call(`rm -f ${W}/copying ${W}/disk.ext4; echo '@{"ok":true}'`);
+    if (!(await has(`[ -f ${W}/copying ]`))) {
+      // a slot builds one base at a time: another base left half-built by this slot (its inputs moved on) is abandoned,
+      // and goes before this one starts; one with no slot recorded predates the record and is taken as this slot's
+      await session.call(`for d in "$WM_STORE"/base-*.building; do [ -d "$d" ] && [ "$d" != ${W} ] || continue; s=$(cat "$d/slot" 2>/dev/null || echo "$WM_SLOT"); [ "$s" = "$WM_SLOT" ] && rm -rf "$d"; done; echo '@{"ok":true}'`);
+      await session.call(`mkdir -p ${W} && printf '%s' "$WM_SLOT" > ${W}/slot && : > ${W}/copying && (setsid bash -c "echo \\$\\$ > ${W.replace(/"/g, '\\"')}/copy.pid; cp --sparse=always ${hp(config.rootfs).replace(/"/g, '\\"')} ${W.replace(/"/g, '\\"')}/disk.ext4 && : > ${W.replace(/"/g, '\\"')}/copied" > ${W}/copy.log 2>&1 < /dev/null &) ; echo '@{"ok":true}'`);
+      return { base, stage: 'copying the rootfs into the store', ready: false };
+    }
+    return { base, stage: 'copying the rootfs into the store', ready: false, detail: 'run again' };
+  }
+
+  // 2. a cold boot in the slot (the snapshot records the slot's disk path and tap)
+  if (!(await has(`[ -f ${W}/booted ]`))) {
+    await session.call(`wm_net >/dev/null && wm_boot ${hp(config.kernel)} ${W}/disk.ext4 ${config.vcpus} ${config.memMib} ${q(bootArgs(config))} && wm_own '{"token":"base-build"}' && : > ${W}/booted`);
+    return { base, stage: 'booting the guest', ready: false, detail: 'run again once it answers ssh' };
+  }
+
+  // 3. the guest agent and the provisioning script, started in the guest
+  if (!(await has(`[ -f ${W}/provisioning ]`))) {
+    if (!(await has('WM_GSSH_TIMEOUT=6 wm_gssh true'))) return { base, stage: 'waiting for the guest to answer ssh', ready: false };
+    await session.call([
+      `wm_gssh 'mkdir -p /usr/local/sbin && cat > /usr/local/sbin/world-machine-agent' <<'__WM_AGENT__'\n${GUEST_AGENT}\n__WM_AGENT__`,
+      `wm_gssh 'cat > /etc/profile.d/volter-world.sh' <<'__WM_PROFILE__'\n${GUEST_PROFILE}\n__WM_PROFILE__`,
+      `wm_gssh 'cat > /root/.world-machine-provision.sh' <<'__WM_PROVISION__'\n${provision}\n__WM_PROVISION__`,
+      `wm_gssh 'setsid nohup python3 /usr/local/sbin/world-machine-agent > /var/log/world-machine-agent.log 2>&1 < /dev/null & setsid nohup bash -c "bash /root/.world-machine-provision.sh > /root/.world-machine-provision.log 2>&1; echo \\$? > /root/.world-machine-provision.done" > /dev/null 2>&1 < /dev/null &' || return 1`,
+      `: > ${W}/provisioning; echo '@{"ok":true}'`,
+    ].join('\n'));
+    return { base, stage: 'provisioning', ready: false, detail: 'run again' };
+  }
+
+  // 4. provisioning finished, and finished well
+  const done = await session.call<{ code: string; log: string }>(`printf '@{"code":"%s","log":%s}\\n' "$(wm_gssh 'cat /root/.world-machine-provision.done 2>/dev/null')" "$(wm_gssh 'tail -c 600 /root/.world-machine-provision.log 2>/dev/null' | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"`);
+  if (done.code === '') return { base, stage: 'provisioning', ready: false, detail: done.log.trim().split('\n').pop() };
+  if (done.code.trim() !== '0') throw new Error(`world-machine base: the provisioning script exited ${done.code.trim()}:\n${done.log}\n(remove ${config.store}/${base}.building to start over)`);
+
+  // 5. the Full snapshot: memory, device state and disk, then the slot is freed
+  const snap = await session.call<{ pauseMs: number; memBytes: number }>(`wm_agent now 0 0 >/dev/null || return 1\nwm_snapshot ${W} Full || return 1\nwm_fc_stop; wm_release\nrm -f ${W}/copying ${W}/copied ${W}/booted ${W}/provisioning ${W}/copy.log\nmv ${W} ${B}`);
+  return { base, stage: 'ready', ready: true, detail: `full snapshot in ${snap.pauseMs} ms, ${Math.round(snap.memBytes / 1048576)} MiB of memory` };
+}
+

package/src/cli.ts

@@ -0,0 +1,283 @@
+#!/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, type IncomingMessage, type ServerResponse } from 'node:http';
+import { dirname, join, resolve } from 'node:path';
+import { stepBase } from './base.ts';
+import { ContainerMachine, stepContainerBase } from './container.ts';
+import { loadConfig, type MachineConfig } from './config.ts';
+import { HostSession, q } from './host.ts';
+import { hp, Machine } from './machine.ts';
+import { collect, register } from './gc.ts';
+
+// 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: string): string | undefined => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const command = args[0];
+const out = (value: unknown): void => { process.stdout.write(`${typeof value === 'string' ? value : JSON.stringify(value, null, 2)}\n`); };
+
+function configFromArgs(): MachineConfig {
+  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: MachineConfig): Promise<void> {
+  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: MachineConfig): Promise<void> {
+  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: MachineConfig): Promise<void> {
+  const session = new HostSession(config);
+  try { out(await collect(config, session)); } finally { session.close(); }
+}
+
+function send(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json' });
+  res.end(`${JSON.stringify(body)}\n`);
+}
+
+async function readJson(req: IncomingMessage): Promise<Record<string, unknown>> {
+  let text = '';
+  for await (const chunk of req) text += chunk;
+  if (!text.trim()) return {};
+  const value = JSON.parse(text) as unknown;
+  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 as Record<string, unknown>;
+}
+
+async function serve(config: MachineConfig): Promise<void> {
+  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 as NodeJS.ErrnoException).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<unknown> = Promise.resolve();
+  const serial = <T>(fn: () => Promise<T>): Promise<T> => { 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 (): Promise<Record<string, unknown> | null> => {
+    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(): void {
+    if (collectedAtStart || stopping) return;
+    collectedAtStart = true;
+    void serial(collectUnlocked).catch((error: Error) => process.stderr.write(`world-machine: gc at start: ${error.message}\n`));
+  }
+  const collectUnlocked = async (): Promise<void> => {
+    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 (): Promise<[number, unknown]> => {
+      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: 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) => 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 as unknown as { compare(p: number, path?: string): Promise<unknown> }).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: unknown) => typeof a === 'string') ? body.argv as string[] : 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: unknown) => 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: Error & { status?: number }) => 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: Error) => process.stderr.write(`world-machine: registering at start: ${error.message}\n`));
+  setTimeout(startCollection, 10_000).unref();
+  let stopping = false;
+  const stop = (): void => {
+    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 as Error).message}\n`);
+  process.exitCode = 1;
+}

package/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])