@volter/world-machine 2.0.0

package/dist/src/host.sh

@@ -0,0 +1,302 @@
+# The machine host's half of @volter/world-machine: sourced once into the persistent shell the service
+# holds on the machine host (the Linux box itself, or the Lima VM on a Mac). Every function prints its
+# result as one `@{json}` line; diagnostics go to stderr, which the session folds into the output.
+# The caller sets WM_STORE, WM_SLOT, WM_FC, WM_SE, WM_KEY, WM_TAP, WM_HOSTIP, WM_GUESTIP before sourcing.
+WM_SLOTDIR="$WM_STORE/slots/$WM_SLOT"
+WM_SOCK="$WM_SLOTDIR/api.sock"
+WM_AGENT_PORT=7070
+
+wm_ns() { date +%s%N; }
+# wm_timed <name> <command...>: runs it and reports `<name>Ms`
+wm_timed() { local n="$1" s="$EPOCHREALTIME" rc e; shift; "$@"; rc=$?; e="$EPOCHREALTIME"; printf '@{"%sMs":%s}\n' "$n" "$(( (${e/./} - ${s/./}) / 1000 ))"; return $rc; }
+wm_ms_since() { echo $(( ($(date +%s%N) - $1) / 1000000 )); }
+wm_fail() { printf '@{"error":%s}\n' "$(printf '%s' "$*" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"; return 1; }
+
+# A job backgrounded from a function of this session holds the copies bash keeps of the session's own descriptors while
+# the function runs with redirections (the service's pipes, the slot lock): `world-machine base` stayed until its tree's
+# fill ended (23 s measured). Such a job closes them first; one that execs a program does not need to (they close on exec).
+# (listed first, and closed with no redirection of its own: one would be saved to a high descriptor the loop then closes,
+# leaving stderr lost)
+wm_closefds() { local fds=(/proc/$BASHPID/fd/*) f n; for f in "${fds[@]}"; do n=${f##*/}; case "$n" in 0|1|2|*[!0-9]*) ;; *) eval "exec $n>&-" ;; esac; done; return 0; }
+
+wm_init() {
+  mkdir -p "$WM_STORE/snapshots" "$WM_SLOTDIR" || return 1
+  printf '@{"home":"%s","store":"%s"}\n' "$HOME" "$WM_STORE"
+}
+
+# A reflink-capable store is a precondition, never a preference: a whole-image copy dominated every
+# pause it was part of (1–13 s measured), so there is no fallback to one.
+wm_reflink_check() {
+  local probe="$WM_STORE/.reflink-probe"
+  head -c 4096 /dev/zero > "$probe" 2>/dev/null || { wm_fail "cannot write the store $WM_STORE"; return 1; }
+  if ! cp --reflink=always "$probe" "$probe.clone" 2>/dev/null; then
+    rm -f "$probe" "$probe.clone"
+    wm_fail "the store $WM_STORE is on $(stat -f -c %T "$WM_STORE") and cannot reflink; world-machine needs XFS (reflink=1) or btrfs there and never falls back to a full copy (run \`world-machine setup --make-store <size>\`)"
+    return 1
+  fi
+  rm -f "$probe" "$probe.clone"
+  wm_store_dio
+  printf '@{"reflink":true,"fs":"%s"}\n' "$(stat -f -c %T "$WM_STORE")"
+}
+
+# A store that is a loop image (setup --make-store) reads and writes its backing file with direct I/O: through the
+# page cache every page was cached twice, and a mark's 1.3 GB dump waited on writeback with the memory full
+# (measured: 7.5 s paused, 0.7-1.0 s with direct I/O). fstab cannot ask for it, so it is set here, on each use.
+wm_store_dio() {
+  local dev; dev=$(findmnt -no SOURCE --target "$WM_STORE" 2>/dev/null); dev=${dev%%[*}
+  case "$dev" in /dev/loop*) [ "$(cat "/sys/block/${dev#/dev/}/loop/dio" 2>/dev/null)" = 1 ] || sudo -n losetup --direct-io=on "$dev" 2>/dev/null || true ;; esac
+}
+
+# The guest's one link: a tap with the host end at WM_HOSTIP, forwarding from it dropped.
+wm_net() {
+  [ -n "$WM_NET_READY" ] && { printf '@{"tap":"%s"}\n' "$WM_TAP"; return 0; }
+  if ! ip link show "$WM_TAP" >/dev/null 2>&1; then
+    sudo -n ip tuntap add "$WM_TAP" mode tap user "$(id -un)" || { wm_fail "cannot create tap $WM_TAP (needs sudo; run world-machine setup)"; return 1; }
+    sudo -n ip addr add "$WM_HOSTIP/30" dev "$WM_TAP" && sudo -n ip link set "$WM_TAP" up || { wm_fail "cannot address tap $WM_TAP"; return 1; }
+  fi
+  if command -v iptables >/dev/null && ! sudo -n iptables -C FORWARD -i "$WM_TAP" -j DROP 2>/dev/null; then
+    sudo -n iptables -I FORWARD -i "$WM_TAP" -j DROP 2>/dev/null || true
+  fi
+  WM_NET_READY=1
+  printf '@{"tap":"%s"}\n' "$WM_TAP"
+}
+
+wm_api() {
+  local code
+  code=$(curl -s --unix-socket "$WM_SOCK" -X "$1" "http://localhost/$2" -H 'Content-Type: application/json' ${3:+-d "$3"} -o "$WM_SLOTDIR/api.out" -w '%{http_code}')
+  case "$code" in 2*) return 0 ;; esac
+  wm_fail "firecracker $1 /$2 answered $code: $(cat "$WM_SLOTDIR/api.out" 2>/dev/null)"
+}
+
+wm_fc_pid() {
+  local pid
+  pid=$(cat "$WM_SLOTDIR/fc.pid" 2>/dev/null) || return 1
+  [ -n "$pid" ] && [ -r "/proc/$pid/comm" ] && case "$(cat /proc/$pid/comm)" in firecracker*) echo "$pid"; return 0 ;; esac
+  return 1
+}
+
+wm_fc_stop() {
+  local pid i
+  if pid=$(wm_fc_pid); then
+    kill -KILL "$pid" 2>/dev/null
+    for i in $(seq 1 400); do [ -d "/proc/$pid" ] || break; sleep 0.005; done
+  fi
+  rm -f "$WM_SLOTDIR/fc.pid" "$WM_SOCK"
+}
+
+wm_fc_start() {
+  local i
+  rm -f "$WM_SOCK"
+  # the pid is written by the process that becomes firecracker (setsid may fork, so $! can be its parent).
+  # `exec`: the backgrounded `cd && …` list is a forked copy of this session's shell, holding the session's
+  # stdout; without it that copy waits on Firecracker for the machine's whole life, so the service's pipe to
+  # this shell never closes (on Linux `world-machine base` then never exits; over Lima's ssh it was hidden)
+  ( cd "$WM_SLOTDIR" && exec setsid bash -c 'echo $$ > "$1"; shift; exec "$@"' _ "$WM_SLOTDIR/fc.pid" "$WM_FC" --api-sock "$WM_SOCK" > "$WM_SLOTDIR/fc.log" 2>&1 < /dev/null & )
+  for i in $(seq 1 1000); do [ -S "$WM_SOCK" ] && return 0; sleep 0.002; done
+  wm_fail "firecracker did not open $WM_SOCK: $(tail -3 "$WM_SLOTDIR/fc.log")"
+}
+
+wm_running() {
+  local pid state='stopped'
+  if pid=$(wm_fc_pid); then
+    state=$(curl -s --unix-socket "$WM_SOCK" http://localhost/ 2>/dev/null | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("state","unknown"))
+except Exception: print("unknown")')
+  fi
+  printf '@{"fc":"%s","owner":%s}\n' "$state" "$(cat "$WM_SLOTDIR/owner.json" 2>/dev/null || echo null)"
+}
+
+wm_own() { printf '%s\n' "$1" > "$WM_SLOTDIR/owner.json"; }
+wm_release() { rm -f "$WM_SLOTDIR/owner.json"; }
+
+# wm_boot <kernel> <disk-source> <vcpus> <mem-mib> <boot-args>: a cold boot on a reflink clone of the source disk.
+wm_boot() {
+  wm_fc_stop
+  cp --reflink=always "$2" "$WM_SLOTDIR/disk.ext4" || { wm_fail "cannot reflink $2 into the slot"; return 1; }
+  wm_fc_start || return 1
+  wm_api PUT machine-config "{\"vcpu_count\":$3,\"mem_size_mib\":$4,\"track_dirty_pages\":true}" || return 1
+  wm_api PUT boot-source "{\"kernel_image_path\":\"$1\",\"boot_args\":\"$5\"}" || return 1
+  wm_api PUT drives/rootfs "{\"drive_id\":\"rootfs\",\"path_on_host\":\"$WM_SLOTDIR/disk.ext4\",\"is_root_device\":true,\"is_read_only\":false}" || return 1
+  wm_api PUT network-interfaces/eth0 "{\"iface_id\":\"eth0\",\"host_dev_name\":\"$WM_TAP\",\"guest_mac\":\"06:00:AC:10:00:02\"}" || return 1
+  wm_api PUT actions '{"action_type":"InstanceStart"}' || return 1
+  printf '@{"booted":true}\n'
+}
+
+# wm_snapshot <dir> <Full|Diff>: the pause. Memory (all of it, or the pages dirtied since the last
+# snapshot or load) and the device state are written, the disk is reflink-cloned beside them, and the
+# guest runs again. A diff and the device state are written to memory (/dev/shm) and moved into the
+# store after the guest resumes: written into the store they made the pause (447 ms for 13 MB measured
+# on a loaded Mac). The disk's dirty pages are flushed before pausing, since a clone flushes them first.
+wm_snapshot() {
+  local d="$1" mem state t0 tw tp shm="/dev/shm/wm-$WM_SLOT-$$"
+  mkdir -p "$d" || return 1
+  if [ "$2" = Diff ]; then mem="$shm.diff"; state="$shm.vmstate"; else mem="$d/mem"; state="$d/vmstate"; fi
+  sync "$WM_SLOTDIR/disk.ext4"
+  t0=$(wm_ns)
+  wm_api PATCH vm '{"state":"Paused"}' || return 1
+  tp=$(wm_ns)
+  if ! wm_api PUT snapshot/create "{\"snapshot_type\":\"$2\",\"snapshot_path\":\"$state\",\"mem_file_path\":\"$mem\"}"; then wm_api PATCH vm '{"state":"Resumed"}'; return 1; fi
+  tw=$(wm_ns)
+  if ! cp --reflink=always "$WM_SLOTDIR/disk.ext4" "$d/disk.ext4"; then wm_api PATCH vm '{"state":"Resumed"}'; wm_fail "cannot reflink the disk into $d"; return 1; fi
+  wm_api PATCH vm '{"state":"Resumed"}' || return 1
+  printf '@{"pauseMs":%s,"memWriteMs":%s,"diskCloneMs":%s,"memBytes":%s}\n' \
+    "$(( ($(wm_ns) - t0) / 1000000 ))" "$(( (tw - tp) / 1000000 ))" "$(( ($(wm_ns) - tw) / 1000000 ))" "$(du -B1 "$mem" | cut -f1)"
+  WM_LAST_DIFF="$mem"
+  if [ "$2" = Diff ]; then mv "$state" "$d/vmstate" || { rm -f "$state" "$mem"; wm_fail "cannot move the device state into $d"; return 1; }; fi
+}
+
+# wm_materialize <parent-mem> <dir>: one full memory file per entry, so a restore loads one file:
+# a reflink copy of the parent's, with the diff wm_snapshot left in /dev/shm applied by Firecracker's
+# snapshot-editor.
+wm_materialize() {
+  local t0; t0=$(wm_ns)
+  cp --reflink=always "$1" "$2/mem.tmp" || { rm -f "$WM_LAST_DIFF"; wm_fail "cannot reflink $1"; return 1; }
+  if ! "$WM_SE" edit-memory rebase --memory-path "$2/mem.tmp" --diff-path "$WM_LAST_DIFF" >/dev/null; then rm -f "$WM_LAST_DIFF"; wm_fail "snapshot-editor rebase failed for $2"; return 1; fi
+  mv "$2/mem.tmp" "$2/mem" && rm -f "$WM_LAST_DIFF"
+  printf '@{"materializeMs":%s}\n' "$(wm_ms_since "$t0")"
+}
+
+# wm_restore <dir>: in place. The slot's process is replaced, the disk becomes a reflink clone of the
+# snapshot's, and the memory file is loaded as the backing of guest memory, resumed.
+wm_restore() {
+  local d="$1" t0 tl
+  [ -f "$d/vmstate" ] && [ -f "$d/mem" ] && [ -f "$d/disk.ext4" ] || { wm_fail "snapshot $d is incomplete"; return 1; }
+  t0=$(wm_ns)
+  wm_fc_stop
+  cp --reflink=always "$d/disk.ext4" "$WM_SLOTDIR/disk.ext4" || { wm_fail "cannot reflink the disk of $d"; return 1; }
+  wm_fc_start || return 1
+  tl=$(wm_ns)
+  wm_api PUT snapshot/load "{\"snapshot_path\":\"$d/vmstate\",\"mem_backend\":{\"backend_type\":\"File\",\"backend_path\":\"$d/mem\"},\"track_dirty_pages\":true,\"resume_vm\":true}" || return 1
+  printf '%s' "$d" > "$WM_SLOTDIR/loaded"   # what the collector must keep while this machine runs
+  printf '@{"loadMs":%s,"restoreMs":%s}\n' "$(wm_ms_since "$tl")" "$(wm_ms_since "$t0")"
+}
+
+# Retention (gc.ts). The store's registry of Worlds, kept under a lock since every serve writes it.
+wm_register() {
+  ( flock 9; python3 - "$WM_STORE/roots.json" "$1" <<'PY'
+import json, os, sys
+path, root = sys.argv[1:3]
+roots = json.load(open(path)) if os.path.exists(path) else []
+if root not in roots: roots.append(root)
+tmp = path + '.tmp'; json.dump(roots, open(tmp, 'w'), indent=1); os.replace(tmp, path)
+PY
+  ) 9> "$WM_STORE/.roots.lock" || { wm_fail "cannot register $1 in $WM_STORE/roots.json"; return 1; }
+  printf '@{"registered":%s}\n' "$(printf '%s' "$1" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+}
+
+# The store as the collector sees it: registered Worlds, snapshot directories (those a checkpoint is still
+# writing marked pending), warm bases, and what each slot's machine was loaded from.
+wm_store_list() {
+  python3 - "$WM_STORE" <<'PY'
+import json, os, sys
+s = sys.argv[1]
+ls = lambda d: sorted(os.listdir(d)) if os.path.isdir(d) else []
+snaps = [n for n in ls(os.path.join(s, 'snapshots')) if os.path.isdir(os.path.join(s, 'snapshots', n))]
+loaded = []
+for slot in ls(os.path.join(s, 'slots')):
+    # only a slot whose Firecracker is running holds what it was loaded from
+    f, pid = os.path.join(s, 'slots', slot, 'loaded'), os.path.join(s, 'slots', slot, 'fc.pid')
+    try: running = open('/proc/%s/comm' % open(pid).read().strip()).read().startswith('firecracker')
+    except OSError: running = False
+    if running:
+        try: loaded.append(open(f).read().strip())
+        except OSError: pass
+    # a container slot being restored or prepared holds the snapshot it is reading (ct.sh wm_ct_restore, container.ts
+    # prepare), and a prepared slot the snapshot it hands over, until the branch adopting it names it in its ledger; a
+    # container slot holds what its machine was restored from (ct-loaded) until that machine's service stops
+    for name in ('restoring', 'preparing', 'ct-loaded', 'comparing'):  # comparing: ct.sh wm_ct_compare's mount
+        try: loaded.append(open(os.path.join(s, 'slots', slot, name)).read().strip())
+        except OSError: pass
+    try: handover = json.load(open(os.path.join(s, 'slots', slot, 'owner.json'))).get('handover')
+    except (OSError, ValueError, AttributeError): handover = None
+    if handover: loaded.append(handover)
+roots = json.load(open(os.path.join(s, 'roots.json'))) if os.path.exists(os.path.join(s, 'roots.json')) else []
+# each container base's (or base build's) filled tree; one deleted during the scan names none
+base_trees = {}
+for n in ls(s):
+    if not n.startswith('base-'): continue
+    try: base_trees[n] = open(os.path.join(s, n, 'tree')).read().strip()
+    except OSError: pass
+print('@' + json.dumps({'roots': roots, 'snapshots': snaps, 'pending': [n for n in snaps if os.path.exists(os.path.join(s, 'snapshots', n, '.pending'))],
+  'bases': [n for n in ls(s) if n.startswith('base-')], 'trees': [n for n in ls(s) if n.startswith('tree-')],
+  'baseTrees': base_trees, 'loaded': loaded}))
+PY
+}
+
+# wm_gc_delete <dropped-roots-json> <store-relative path...>: delete, drop the gone registrations, give the
+# space back to the host (fstrim on the store's filesystem), and report the store's use before and after.
+wm_gc_delete() {
+  local dropped="$1" before after p mnt trimmed=""; shift
+  sync -f "$WM_STORE"; before=$(df -B1 --output=used "$WM_STORE" | tail -1 | tr -d ' ')
+  for p in "$@"; do case "$p" in snapshots/snap-*|base-*|tree-*) rm -rf -- "${WM_STORE:?}/$p" ;; *) wm_fail "refusing to delete $p"; return 1 ;; esac; done
+  ( flock 9; python3 - "$WM_STORE/roots.json" "$dropped" <<'PY'
+import json, os, sys
+path, dropped = sys.argv[1], set(json.loads(sys.argv[2]))
+if os.path.exists(path):
+    roots = [r for r in json.load(open(path)) if r not in dropped]
+    tmp = path + '.tmp'; json.dump(roots, open(tmp, 'w'), indent=1); os.replace(tmp, path)
+PY
+  ) 9> "$WM_STORE/.roots.lock"
+  mnt=$(findmnt -n -o TARGET --target "$WM_STORE")
+  # the deletes committed first: btrfs frees their extents only then, and a trim before it gave nothing back (measured:
+  # 1.66 GB deleted, the store's image unchanged until a later trim returned 1.45 GB)
+  sync -f "$WM_STORE"
+  trimmed=$(sudo -n fstrim -v "$mnt" 2>&1 | tail -1)
+  sync -f "$WM_STORE"; after=$(df -B1 --output=used "$WM_STORE" | tail -1 | tr -d ' ')
+  printf '@{"usedBefore":%s,"usedAfter":%s,"trimmed":%s}\n' "$before" "$after" "$(printf '%s' "$trimmed" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+}
+
+# wm_room <bytes> [path...]: refused (wm_fail) unless every filesystem a store write lands on has <bytes> free: the
+# store, the file backing it when it is a loop image (a sparse XFS image promises room its backing filesystem may not
+# have), and each path named (on a Mac, the home the Lima VM mounts: its free space is the Mac's, beneath the VM's own
+# sparse disk). A write the lowest layer cannot hold fails as an I/O error in the layers above it, which is how a
+# store is corrupted; a mark refused first is only a mark not taken.
+wm_room() {
+  local need="$1" p dev back line av tg least="" at=""; shift
+  set -- "$WM_STORE" "$@"
+  dev=$(findmnt -no SOURCE --target "$WM_STORE" 2>/dev/null); dev=${dev%%[*}   # btrfs names a subvolume: /dev/loop0[/sub]
+  case "$dev" in /dev/loop*) back=$(losetup -nO BACK-FILE "$dev" 2>/dev/null | tr -d ' '); [ -n "$back" ] && set -- "$@" "$(dirname "$back")" ;; esac
+  for p in "$@"; do
+    [ -e "$p" ] || continue
+    line=$(df -B1 --output=avail,target "$p" 2>/dev/null | tail -1) || continue
+    read -r av tg <<<"$line"
+    if [ -z "$least" ] || [ "$av" -lt "$least" ]; then least=$av; at=$tg; fi
+  done
+  [ -n "$least" ] || { wm_fail "cannot read the free space under $WM_STORE"; return 1; }
+  [ "$least" -ge "$need" ] || { wm_fail "no room for a mark: $at has $((least / 1048576)) MB free and a mark needs about $((need / 1048576)) MB there (its estimate and the reserve); nothing was written. Free space there, or collect the snapshots no branch names (world-machine gc)"; return 1; }
+  printf '@{"room":%s,"at":"%s"}\n' "$least" "$at"
+}
+
+# the store's used bytes, after a syncfs: XFS frees an unlinked file's blocks in the background, and
+# a df read without it counted a just-deleted memory diff (+43 MB measured)
+wm_used() { sync -f "$WM_STORE"; printf '@{"used":%s}\n' "$(df -B1 --output=used "$WM_STORE" | tail -1 | tr -d ' ')"; }
+
+# wm_egress <host-port>=<target-host>:<target-port> ...: the guest's only way out. Each stable
+# guest-visible port on the tap's host address forwards to one twin of the World that owns the slot.
+wm_egress() {
+  local pid m
+  # unchanged and all alive: nothing to re-point
+  if [ "$*" = "$(cat "$WM_SLOTDIR/egress.spec" 2>/dev/null)" ] && [ -s "$WM_SLOTDIR/egress.pids" ]; then
+    m=0; for pid in $(cat "$WM_SLOTDIR/egress.pids"); do [ "$(cat /proc/$pid/comm 2>/dev/null)" = socat ] || m=1; done
+    [ "$m" = 0 ] && { printf '@{"forwarders":%s,"unchanged":true}\n' "$#"; return 0; }
+  fi
+  for pid in $(cat "$WM_SLOTDIR/egress.pids" 2>/dev/null); do
+    [ -r "/proc/$pid/comm" ] && [ "$(cat /proc/$pid/comm)" = socat ] && kill "$pid" 2>/dev/null
+  done
+  : > "$WM_SLOTDIR/egress.pids"
+  for m in "$@"; do
+    # to this host's loopback, from 127.0.0.2: the World's proxy knows a machine's connection by it and keeps the
+    # machine off this host's own network (world-runtime redirect-proxy.ts isGuestSource)
+    local src=""; case "${m#*=}" in 127.*|localhost:*) src=",bind=127.0.0.2" ;; esac
+    # 9>&-: the container backend's slot lock (host.ts) is never held by a forwarder that outlives the shell
+    setsid bash -c 'echo $$ >> "$1"; shift; exec "$@"' _ "$WM_SLOTDIR/egress.pids" socat "TCP-LISTEN:${m%%=*},bind=$WM_HOSTIP,fork,reuseaddr" "TCP:${m#*=}$src" > /dev/null 2>&1 < /dev/null 9>&- &
+  done
+  printf '%s' "$*" > "$WM_SLOTDIR/egress.spec"
+  printf '@{"forwarders":%s}\n' "$#"
+}
+
+# The guest agent (agent.py, inside the guest): the clock and the World's env file.
+wm_agent() { python3 "$WM_SLOTDIR/agentc.py" "$WM_GUESTIP" "$WM_AGENT_PORT" "$@"; }
+
+# bounded: under load a guest ssh login has taken 18 s
+wm_gssh() { timeout "${WM_GSSH_TIMEOUT:-20}" ssh -q -i "$WM_KEY" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ConnectTimeout=2 -o BatchMode=yes "root@$WM_GUESTIP" "$@"; }

package/dist/src/ledger.d.ts

@@ -0,0 +1,25 @@
+export declare const LEDGER = "machine";
+export type SnapshotRecord = {
+    id: string;
+    label: string;
+    type: 'Full' | 'Diff';
+    /** the entry this one's memory diff was taken against, or the warm base */
+    parent: string;
+    base: string;
+    /** directory of vmstate, mem and disk.ext4, relative to the store */
+    dir: string;
+    memBytes: number;
+    diskBytes: number;
+    storeBytes: number;
+    pauseMs: number;
+    created: string;
+    /** taken to be kept (a mark the agent pinned): retention (`thin`) never lets it go */
+    keep?: boolean;
+};
+export declare function appendSnapshot(root: string, record: SnapshotRecord): Promise<void>;
+/** The last snapshot in this branch's view of the ledger, or null. */
+export declare function headSnapshot(root: string): SnapshotRecord | null;
+/** The head a branch forked from this one at `position` (entries of this branch's whole log) starts with: what
+ *  `world branch --at machine@<position>` gives the branch's machine to restore. */
+export declare function headAt(root: string, position: number): SnapshotRecord | null;
+export declare const worldInstant: () => string;

package/dist/src/ledger.js

@@ -0,0 +1,38 @@
+// The machine's ledger: one World state service, `machine`, one entry per checkpoint, written through
+// the kernel's own write path (applyTwinWrite, as every twin records its writes). The World's `mark`
+// finds it like any twin's log and `branch --at machine@N` forks it at N; the head a branch restores is
+// the last snapshot in the branch's view, its parent's history up to the fork position and its own
+// entries after it.
+import { applyTwinWrite, wholeLog, worldNow } from '@volter/world-core';
+export const LEDGER = 'machine';
+export async function appendSnapshot(root, record) {
+    const { id, ...fields } = record;
+    await applyTwinWrite(LEDGER, {
+        operation: 'snapshot.create',
+        subjectType: 'snapshot',
+        subjectId: id,
+        fields,
+        occurredAt: record.created,
+        actor: { kind: 'system', id: 'world-machine' },
+    }, root);
+}
+/** The last snapshot in this branch's view of the ledger, or null. */
+export function headSnapshot(root) {
+    return headOf(wholeLog(LEDGER, root));
+}
+/** The head a branch forked from this one at `position` (entries of this branch's whole log) starts with: what
+ *  `world branch --at machine@<position>` gives the branch's machine to restore. */
+export function headAt(root, position) {
+    const seen = new Set();
+    return headOf(wholeLog(LEDGER, root).filter((e) => (seen.has(e.id) ? false : (seen.add(e.id), true))).slice(0, position));
+}
+function headOf(log) {
+    const reverted = new Set(log.filter((e) => e.op === 'revert' && e.revertsActionId).map((e) => e.revertsActionId));
+    for (let i = log.length - 1; i >= 0; i--) {
+        const e = log[i];
+        if (e.op === 'set' && e.subject.type === 'snapshot' && !reverted.has(e.id))
+            return { id: e.subject.id, ...e.fields };
+    }
+    return null;
+}
+export const worldInstant = () => worldNow();

package/dist/src/machine.d.ts

@@ -0,0 +1,82 @@
+import type { MachineConfig } from './config.js';
+import { HostSession } from './host.js';
+type Loaded = {
+    id: string;
+    label: string;
+    dir: string;
+} | null;
+/** Rewritten with a new id at each restore, before stale connections are reset (see guestFiles). */
+export declare const RESTORE_ID_FILE = "/run/world-machine/restore-id";
+export type MachineState = 'idle' | 'running' | 'displaced' | 'no-base' | 'error';
+/** A machine-host path as one shell word: `~/x` expands on that host. */
+export declare const hp: (path: string) => string;
+/** Every `<VENDOR>_TWIN_URL` the World handed this service. */
+export declare function twinUrls(env: Record<string, string | undefined>): Record<string, URL>;
+/** A stable guest-visible port per vendor: derived from the name (FNV-1a into 20000-29999), a
+ *  collision moving the later name in sorted order up by one; a configured port wins. */
+export declare function egressPorts(vendors: string[], fixed: Record<string, number>): Record<string, number>;
+/** The guest kernel's command line. The guest's address is on-link with the tap's host end and it
+ *  has no gateway: no route leads anywhere but the machine host. */
+export declare const bootArgs: (config: MachineConfig) => string;
+export declare function baseHash(config: MachineConfig, session: HostSession): Promise<string>;
+export declare class Machine {
+    readonly config: MachineConfig;
+    readonly root: string;
+    readonly env: Record<string, string | undefined>;
+    readonly port: number;
+    state: MachineState;
+    message: string | undefined;
+    loaded: Loaded;
+    protected base: string | undefined;
+    protected lastUsed: Promise<number>;
+    protected readonly token: string;
+    /** This load's restore id (RESTORE_ID_FILE); a backend that can write it before the machine runs sets it first. */
+    protected restoreId: string;
+    readonly session: HostSession;
+    protected readonly ports: Record<string, number>;
+    protected readonly twins: Record<string, URL>;
+    constructor(config: MachineConfig, root: string, env: Record<string, string | undefined>, port: number);
+    /** What the guest sees: vendor → its stable URL on the tap's host address. */
+    egress(): Record<string, string>;
+    /** The World's live env (VOLTER_WORLD_ENV_FILE), `export K='v'` lines. */
+    protected worldEnv(): Record<string, string>;
+    /** The World's proxy as the machine reaches it, read from its live env at each load: its guests' listener
+     *  (`VOLTER_WORLD_GUEST_PROXY`, where every connection is kept off this host's own network, whatever NAT makes its
+     *  source look like; world-runtime redirect-proxy.ts), else, from an older World, its one listener. */
+    protected proxy(): URL | null;
+    /** What the guest is given at each start and restore: /etc/world.env, the World's live env as the guest sees it,
+     *  and the files it names. Twin URLs become the stable egress ones, the World's proxy its forwarder (the twins'
+     *  own addresses bypass it), NODE_OPTIONS the guest's copy of the redirect, and a value naming a certificate file on the
+     *  World's host (its CA and trust bundle, PEM) a copy of it under /etc; what only that host can use (a
+     *  directory there, a loopback URL of its other listeners) is left out and named, and an empty value is left unset. */
+    protected guestFiles(): Record<string, string>;
+    protected forwarders(): string;
+    protected owner(): string;
+    protected baseDir(): string;
+    /** The machine, brought up when first asked for: nothing runs until a door needs it, so a new branch's
+     *  machine is loaded once, by the restore that retakes to its mark, instead of booting its head at start and
+     *  being replaced a moment later. `GET /machine` and `checkpoint` bring up the head if the ledger has one,
+     *  else the warm base; `restore` loads the head itself. Returns the restore's facts when it brought it up. */
+    ensure(): Promise<Record<string, unknown> | null>;
+    /** This branch's head, loaded in place; with no head, the warm base. */
+    restore(): Promise<Record<string, unknown>>;
+    /** Is the slot still this service's? A later restore by another World's machine takes it. */
+    refresh(): Promise<void>;
+    checkpoint(label: string, keep?: boolean): Promise<Record<string, unknown>>;
+    /** Refused (507) unless every filesystem beneath the store has room for a mark: the last mark's store growth, at
+     *  least `firstMarkBytes` when there is none, plus the configured reserve. Checked before anything is written. */
+    protected room(firstMarkBytes?: number): Promise<void>;
+    /** For each position of this machine's ledger (a mark's `machine@N`), the snapshot a branch forked there would restore
+     *  and whether the store still holds it: gc with `retain` lets old ones go. */
+    present(positions: number[]): Promise<Array<{
+        position: number;
+        id: string | null;
+        present: boolean;
+    }>>;
+    /** The guest's wall clock against the World's, now. */
+    clock(): Promise<Record<string, unknown>>;
+    status(): Record<string, unknown>;
+    /** On service stop: the slot is released only if it is still this service's. */
+    stop(): Promise<void>;
+}
+export {};