@machinen/runtime 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -19,7 +19,14 @@ interface VsockExecOptions {
 }
 interface VsockExecResult {
     exitCode: number;
+    /**
+     * Concatenated stdout bytes, decoded as UTF-8. Always `""` when the
+     * caller passed `onStdout` — streaming callers already have the
+     * bytes and a parallel buffered copy would defeat the streaming
+     * (and at multi-GB volumes would crash with ERR_STRING_TOO_LONG).
+     */
     stdout: string;
+    /** Same shape as `stdout` for the stderr channel + `onStderr`. */
     stderr: string;
 }
 declare const VsockExec: {
@@ -121,6 +128,8 @@ interface PhaseLogEvent {
 type LogEvent = ChunkLogEvent | PhaseLogEvent;
 type OnLog = (evt: LogEvent) => void;
 
+type SnapshotEngine = "criu" | "vmstate";
+
 interface AttachOptions {
     /**
      * Look up a VM by the host pid of its VMM process. Kernel-unique
@@ -318,34 +327,45 @@ interface BootOptions {
         upperPath: string;
     };
     /**
-     * Host directories exposed to the guest as live-share FUSE mounts
-     * (#78). Unlike `mount` (copy-once into the boot rootfs), these stay
-     * connected to the host: the guest reads on demand via a vsock FUSE
-     * relay, and nothing is copied at boot. `mode` defaults to `"rw"` —
-     * guest writes land on the host (#151, #156). Set `"ro"` for a
-     * one-way share (host caches, untrusted guests).
+     * Vmstate engine restore: absolute path to the bundle's
+     * `state.vmstate`. Set by `restore()` when it detects a vmstate
+     * bundle. `boot()` forwards it to the VMM as `MACHINEN_RESTORE_PATH`
+     * — the VMM loads that whole-VM state before the first vCPU run, so
+     * the guest resumes mid-execution instead of cold-booting.
+     *
+     * @internal
+     */
+    _vmstateRestorePath?: string;
+    /**
+     * Host directories exposed to the guest as live-share mounts (#78,
+     * #332). Unlike `mount` (copy-once into the boot rootfs), these stay
+     * connected to the host: the guest reads on demand and nothing is
+     * copied at boot. `mode` defaults to `"rw"` — guest writes land on
+     * the host (#151, #156). Set `"ro"` for a one-way share (host
+     * caches, untrusted guests).
      *
      * Each guest path must live under `/mnt/` (same rule as `mount`).
-     * Repeatable; each entry gets its own vsock port.
+     * Repeatable up to 4 entries per VM — each is served by its own
+     * in-VMM virtio-fs device (the VMM wires 4 virtio-fs slots). The
+     * FUSE opcode handlers run inside the VMM and the guest mounts each
+     * share directly with `mount -t virtiofs` — no agent process, no
+     * vsock hop. Requires a guest kernel with `CONFIG_VIRTIO_FS` — every
+     * machinen-built kernel has it. (The older FUSE-over-vsock transport
+     * and its `protocol` knob were removed in #338.)
      *
      * Snapshot / restore / fork (#273): liveMount has no guest-side
      * state worth checkpointing — reads come from the host on demand,
-     * writes (in `"rw"`) land on the host immediately. The runtime
-     * unmounts each mount before CRIU dumps, then re-establishes a
-     * fresh window on the other side: for `vm.snapshot({ leaveRunning:
-     * true })` and `vm.fork()` the source's workload sees `/mnt/<guest>/`
-     * disappear for the dump duration (typically seconds, scales with
-     * memory size) before reappearing under fresh server state. Open
-     * fds across that window see EBADF on next syscall — same shape
-     * as "don't snapshot during a database write." Workloads that
-     * quiesce before snapshot are unaffected.
+     * writes (in `"rw"`) land on the host immediately. The in-VMM
+     * virtio-fs device persists across the CRIU dump, so the workload's
+     * view of `/mnt/<guest>/` survives `vm.snapshot({ leaveRunning:
+     * true })` and `vm.fork()` without an unmount/remount window.
      *
      * Concurrent writes from multiple forks against the same host
      * directory are no different from any other shared filesystem —
-     * the runtime re-establishes the window per-VM but doesn't
-     * coordinate writes between siblings. If two forks need
-     * non-overlapping write surfaces, point each at a distinct
-     * `host` path or use `mount` (copy-once, per-VM upper).
+     * each VM gets its own device but the runtime doesn't coordinate
+     * writes between siblings. If two forks need non-overlapping write
+     * surfaces, point each at a distinct `host` path or use `mount`
+     * (copy-once, per-VM upper).
      *
      * Restore on a host where the recorded `host` path doesn't exist:
      * fails loudly via `BOOT_MOUNT_HOST_NOT_FOUND`. Pass
@@ -469,23 +489,18 @@ interface BootOptions {
 declare function boot(opts?: BootOptions): Promise<VmHandle>;
 
 /**
- * A caller-provided `liveMounts` entry after validation, with the
- * vsock port + host UDS path allocated. Threaded from `boot()` into
- * the initramfs packer so the config and the host servers agree on
- * ports and guest paths.
+ * A caller-provided `liveMounts` entry after validation. Served by an
+ * in-VMM virtio-fs device (#332) — no detached process, no vsock port,
+ * no guest fuse-agent. `tag` is the device's config-space identifier;
+ * `/init` runs `mount -t virtiofs <tag> <guest>`. Threaded from
+ * `boot()` into the initramfs packer so the config and the VMM env
+ * agree on guest paths and per-mount tags.
  */
 interface ResolvedLiveMount {
     host: string;
     guest: string;
-    port: number;
-    udsPath: string;
-    /**
-     * Per-mount stats file the detached helper writes its
-     * bytesServedOnPagesImg counter to. Lives next to `udsPath` under
-     * `vsockTempDir` so the supervisor's cleanupPaths sweep covers it.
-     */
-    statsPath: string;
     mode: "ro" | "rw";
+    tag: string;
 }
 /**
  * Build the synthesized `machinen-config.json` payload that /init
@@ -517,9 +532,12 @@ declare function validateMemoryMib(mib: number): number;
 /**
  * Locate the VMM binary using the same lookup order as `@machinen/cli`:
  *   1. `MACHINEN_VMM` env var (dev-mode override)
- *   2. `require.resolve("@machinen/vmm-<arch>-<os>")` → `binary` export
+ *   2. `require.resolve("@machinen/native-<arch>-<os>")` → `binary` export
  *
- * Callers can pass an explicit `binary` to `boot()` to bypass this.
+ * `@machinen/native-arm64-{darwin,linux}` is the consolidated host-tool
+ * package — it carries the VMM, gvproxy, guest ELFs, mke2fs,
+ * mksquashfs, and the mount server. Callers can pass an explicit
+ * `binary` to `boot()` to bypass this.
  *
  * @throws {BootError} BOOT_VMM_MISSING | BOOT_VMM_PACKAGE_BROKEN
  */
@@ -930,10 +948,20 @@ interface SnapshotOptions {
     tcpClose?: boolean;
 }
 interface SnapshotResult {
+    /** Which backend produced the bundle. */
+    engine: SnapshotEngine;
     /** Absolute path to the snapshot bundle directory. */
     snapDir: string;
-    /** Absolute path to the CRIU image directory inside the bundle. */
-    imgDir: string;
+    /**
+     * Absolute path to the CRIU image directory inside the bundle.
+     * Set by the criu engine only; undefined for vmstate bundles.
+     */
+    imgDir?: string;
+    /**
+     * Absolute path to the `.vmstate` whole-VM state file inside the
+     * bundle. Set by the vmstate engine only; undefined for criu bundles.
+     */
+    vmstatePath?: string;
     /** Time from `snapshot()` entry to VMM exit, in milliseconds. */
     elapsedMs: number;
     /** Guest console output captured during the dump. */
@@ -944,6 +972,14 @@ interface SnapshotResult {
  * to reconstruct the source VM's name when registering the fork.
  */
 interface SnapshotMeta {
+    /**
+     * Which backend wrote this bundle — `"criu"` (process-tree images
+     * under `img/`) or `"vmstate"` (whole-VM `state.vmstate`). `restore()`
+     * also auto-detects from the bundle's contents; this field is the
+     * explicit record. Absent on bundles predating the vmstate engine
+     * (treated as `"criu"`).
+     */
+    engine?: SnapshotEngine;
     /** Name passed to `boot({ name })` when the source VM was started. */
     sourceName?: string;
     /**
@@ -972,20 +1008,20 @@ interface SnapshotMeta {
         upper: string;
     };
     /**
-     * #273: live-share FUSE mounts (`liveMounts: [...]` at boot) the
-     * source VM had at snapshot time. Unlike `mountDisk`, no bytes are
-     * captured — `host` is the path on the host that was being live-
-     * shared, recorded so `restore()` can re-establish the same window
-     * on the restoring host. Each entry is the resolved config from the
+     * #273: live-share mounts (`liveMounts: [...]` at boot) the source
+     * VM had at snapshot time. Unlike `mountDisk`, no bytes are captured
+     * — `host` is the path on the host that was being live-shared,
+     * recorded so `restore()` can re-establish the same window on the
+     * restoring host. Each entry is the resolved config from the
      * source's `resolveLiveMounts()`:
-     *   - `guest`: absolute guest path the FUSE mount lands at.
+     *   - `guest`: absolute guest path the mount lands at.
      *   - `host`:  absolute host path that was being shared.
      *   - `mode`:  `"ro"` or `"rw"`, the share's write semantics.
      *
      * Restore policy: the bundle's recorded mounts are re-established
      * verbatim by default. Pass `restore({ liveMounts })` to override
-     * per-guest `host`/`mode` — each override entry's `guest` must
-     * match a recorded entry, else BOOT_LIVE_MOUNT_OVERRIDE_UNKNOWN.
+     * per-guest `host`/`mode` — each override entry's `guest` must match
+     * a recorded entry, else BOOT_LIVE_MOUNT_OVERRIDE_UNKNOWN.
      * Cross-host bundles where a recorded `host` doesn't exist on the
      * restoring host fail loudly via the boot-time existence check —
      * users remap with the override knob.
@@ -1338,7 +1374,7 @@ interface ProvisionOptions {
     env?: Record<string, string>;
     /**
      * Optional VMM binary path. Same lookup rules as `boot()` — if
-     * omitted, resolves `@machinen/vmm-<arch>-<os>`.
+     * omitted, resolves `@machinen/native-<arch>-<os>`.
      */
     binary?: string;
     /** Working directory. Defaults to process.cwd(). */
@@ -1714,6 +1750,14 @@ interface RegistryEntry {
      * guest-side scratch disk that backs the in-VM dump.
      */
     diskPath?: string;
+    /**
+     * Vmstate engine only: absolute path the VMM writes its `.vmstate`
+     * whole-VM state file to (the `MACHINEN_SNAPSHOT_PATH` it booted
+     * with). Persisted so an attach-owned `vm.snapshot()` / `vm.fork()`
+     * can SIGUSR1 the VMM and pick the state file up. Undefined for VMs
+     * booted without the vmstate engine.
+     */
+    vmstatePath?: string;
     /**
      * Absolute path to the snapshot directory this VM was forked from
      * (set by `restore({ snapDir })`). Visible in `ls`; informational.
@@ -1797,14 +1841,6 @@ interface RegistryEntry {
      * `vm.memoryStats().lazyPagesPending`.
      */
     lazyPagesTotal?: number;
-    /**
-     * Absolute path under which the lazy-restore FUSE mount serves
-     * `pages-*.img` reads. The mount-server tracks bytes served below
-     * this prefix; `vm.memoryStats()` divides that by 4096 and
-     * subtracts from `lazyPagesTotal` to derive `lazyPagesPending`.
-     * Undefined when the VM wasn't lazy-restored.
-     */
-    lazyPagesMountRoot?: string;
     /**
      * #272: when the VM was booted with `mount: { host, guest }`, the
      * runtime materialized a squashfs RO lower + ext4 RW upper. Persist
@@ -1821,35 +1857,19 @@ interface RegistryEntry {
         upperPath: string;
     };
     /**
-     * #273: live-share FUSE mounts (`liveMounts: [...]` at boot) the
-     * VM was started with. Persisted so an attach-owned `vm.snapshot()`
-     * / `vm.fork()` can record the same `meta.liveMounts` block in the
-     * bundle and trigger /sbin/machinen-remount post-dump on
-     * leaveRunning paths. Host UDS paths and vsock ports are NOT
-     * recorded — those are the boot process's private state and aren't
-     * useful to other processes (the owning process keeps the servers
-     * listening through the dump, so attach reconnects without having
-     * to bind anything).
+     * #273: live-share mounts (`liveMounts: [...]` at boot) the VM was
+     * started with. Persisted so an attach-owned `vm.snapshot()` /
+     * `vm.fork()` can record the same `meta.liveMounts` block in the
+     * bundle. Since #332 every live mount is served by an in-VMM
+     * virtio-fs device — there's no host-side process to record, reap,
+     * or reconnect to. The per-mount virtio-fs tag isn't recorded
+     * either; it's re-derived from the resolved order on restore.
      */
     liveMounts?: Array<{
         guest: string;
         host: string;
         mode: "ro" | "rw";
     }>;
-    /**
-     * #150 phase 3: pids + exes of the detached mount-server helpers
-     * spawned alongside this VMM, one per live-mount. The helpers die
-     * with the VMM via `pdeathsig --watch-pid` already, but `machinen
-     * stop` SIGTERMs them up-front so the VMM exit hook doesn't race
-     * with the helper's own pdeathsig-driven shutdown, and `machinen
-     * gc` validates pid+exe to detect recycled pids the same way the
-     * VMM and gvproxy entries do. Empty / undefined for VMs booted
-     * without `liveMounts`.
-     */
-    liveMountServers?: Array<{
-        pid: number;
-        exe: string;
-    }>;
     /** ms epoch when the entry was created. */
     startedAt: number;
 }
@@ -1893,12 +1913,6 @@ interface PackBundleOptions {
     excludes?: string[];
     /** Optional path to the compiled /init. Default: ../microvm/test-fixtures/init relative to this file. */
     initPath?: string;
-    /**
-     * Optional host path to the compiled fuse-agent binary. When set,
-     * the binary is injected at `/fuse-agent` (mode 0755) inside the
-     * initramfs so /init can fork it per live-share mount. See #78.
-     */
-    fuseAgentPath?: string;
     /**
      * Optional path to the compiled /exec-agent. Default: same dir as
      * /init under packages/microvm/test-fixtures/. Used to override the
@@ -1924,8 +1938,6 @@ interface PackTinyBundleOptions {
     mountGuest?: string;
     /** Optional override for the compiled /init. Default: ../microvm/test-fixtures/init relative to this file. */
     initPath?: string;
-    /** Optional path to the compiled fuse-agent; staged at /fuse-agent when set. */
-    fuseAgentPath?: string;
 }
 /**
  * Build the tiny initramfs used by every user-facing boot() (#119).
@@ -1940,7 +1952,6 @@ interface PackTinyBundleOptions {
  *                                    blk slots 5+6, not in the cpio.
  *   /dev/console                     char node 5,1 — kernel needs it
  *                                    before /init re-opens the console
- *   /fuse-agent                      optional, only when liveMounts
  *   /tmp                             sticky 1777
  *
  * No /lib/modules tree, no kmod, no /modules/*.ko, no Debian userland.
@@ -2025,8 +2036,6 @@ declare const ErrorCode: {
     readonly FILES_AGENT_UNAVAILABLE: "FILES_AGENT_UNAVAILABLE";
     readonly MOUNT_PATH_INVALID: "MOUNT_PATH_INVALID";
     readonly MOUNT_PATH_ESCAPE: "MOUNT_PATH_ESCAPE";
-    readonly MOUNT_SERVER_BIN_MISSING: "MOUNT_SERVER_BIN_MISSING";
-    readonly MOUNT_SERVER_SPAWN_FAILED: "MOUNT_SERVER_SPAWN_FAILED";
     readonly SECRETS_VALUE_INVALID: "SECRETS_VALUE_INVALID";
     readonly SECRETS_AGENT_UNAVAILABLE: "SECRETS_AGENT_UNAVAILABLE";
     readonly WINSIZE_AGENT_UNAVAILABLE: "WINSIZE_AGENT_UNAVAILABLE";
@@ -2224,4 +2233,4 @@ interface BalloonCounters {
  */
 declare function readBalloonStats(path: string): BalloonCounters | null;
 
-export { type AttachOptions, type BalloonCounters, BootError, type BootOptions, CacheError, type CheckForkBackpressureOptions, type ChunkLogEvent, DEFAULT_FREE_MEMORY_THRESHOLD, type EnsureMountDiskImageOptions, type EnsureMountDiskImageResult, type EnsureMountDiskUpperOptions, type EnsureMountDiskUpperResult, type EnsureRootfsImageOptions, ErrorCode, ExecError, FilesError, type ForkOptions, type GcResult, GvproxyError, type ImageConfig, type LogEvent, MachinenError, type MachinenErrorOptions, type MemoryStats, MkinitramfsError, MountError, type OnLog, type OnOutputListener, type PackBundleOptions, type PackMinimalOptions, type PackRootfsOptions, type PackTinyBundleOptions, type PackWorkspaceOptions, ParseError, type PhaseLogEvent, type PidStatus, ProvisionError, type ProvisionOptions, type ProvisionResult, type PtyBootOptions, type PtyVmHandle, type RegistryEntry, RegistryError, type RestoreOptions, type RssTarget, type RunGcOptions, STATS_FILE_SIZE, type SandboxEntry, SandboxError, Sandboxes, SecretsError, SnapshotError, type SnapshotMeta, type SnapshotOptions, type SnapshotResult, Supervisor, type SupervisorOptions, type VmHandle, VsockExec, type VsockExecOptions, type VsockExecPtyHandle, type VsockExecPtyOptions, type VsockExecPtyResult, type VsockExecResult, VsockFiles, type VsockFilesOptions, VsockSecrets, type VsockSecretsOptions, VsockWinsize, type VsockWinsizeOptions, WinsizeError, type WriteFileOptions, _internal, attach, autoSizeMemoryMib, boot, bootPty, bootSnapshotPath, buildMachinenConfig, buildWriteFileCmd, buildWriteFileCmds, checkForkBackpressure, detachedLogRoot, ensureMountDiskImage, ensureMountDiskUpper, ensureRootfsImage, formatMachinenError, isMachinenError, list, markMountDiskImageClean, markRootfsImageClean, measureFirstByte, packBundle as mkinitramfsBundle, cli as mkinitramfsCli, packMinimal as mkinitramfsMinimal, packRootfs as mkinitramfsRootfs, packTinyBundle as mkinitramfsTinyBundle, packWorkspace as mkinitramfsWorkspace, mountdiskImgCacheDir, provision, readBalloonStats, readHostFreeBytes, readHostRssBytes, readHostRssBytesMulti, readHostTotalBytes, registryRoot, resolveBaseDtb, resolveBaseKernel, resolveBaseRootfs, resolveMke2fs, resolveMksquashfs, resolveVmmBinary, restore, rootfsImgCacheDir, runGc, validatePid, warmImageConfigCache, writeBootSnapshot };
+export { type AttachOptions, type BalloonCounters, BootError, type BootOptions, CacheError, type CheckForkBackpressureOptions, type ChunkLogEvent, DEFAULT_FREE_MEMORY_THRESHOLD, type EnsureMountDiskImageOptions, type EnsureMountDiskImageResult, type EnsureMountDiskUpperOptions, type EnsureMountDiskUpperResult, type EnsureRootfsImageOptions, ErrorCode, ExecError, FilesError, type ForkOptions, type GcResult, GvproxyError, type ImageConfig, type LogEvent, MachinenError, type MachinenErrorOptions, type MemoryStats, MkinitramfsError, MountError, type OnLog, type OnOutputListener, type PackBundleOptions, type PackMinimalOptions, type PackRootfsOptions, type PackTinyBundleOptions, type PackWorkspaceOptions, ParseError, type PhaseLogEvent, type PidStatus, ProvisionError, type ProvisionOptions, type ProvisionResult, type PtyBootOptions, type PtyVmHandle, type RegistryEntry, RegistryError, type RestoreOptions, type RssTarget, type RunGcOptions, STATS_FILE_SIZE, type SandboxEntry, SandboxError, Sandboxes, SecretsError, type SnapshotEngine, SnapshotError, type SnapshotMeta, type SnapshotOptions, type SnapshotResult, Supervisor, type SupervisorOptions, type VmHandle, VsockExec, type VsockExecOptions, type VsockExecPtyHandle, type VsockExecPtyOptions, type VsockExecPtyResult, type VsockExecResult, VsockFiles, type VsockFilesOptions, VsockSecrets, type VsockSecretsOptions, VsockWinsize, type VsockWinsizeOptions, WinsizeError, type WriteFileOptions, _internal, attach, autoSizeMemoryMib, boot, bootPty, bootSnapshotPath, buildMachinenConfig, buildWriteFileCmd, buildWriteFileCmds, checkForkBackpressure, detachedLogRoot, ensureMountDiskImage, ensureMountDiskUpper, ensureRootfsImage, formatMachinenError, isMachinenError, list, markMountDiskImageClean, markRootfsImageClean, measureFirstByte, packBundle as mkinitramfsBundle, cli as mkinitramfsCli, packMinimal as mkinitramfsMinimal, packRootfs as mkinitramfsRootfs, packTinyBundle as mkinitramfsTinyBundle, packWorkspace as mkinitramfsWorkspace, mountdiskImgCacheDir, provision, readBalloonStats, readHostFreeBytes, readHostRssBytes, readHostRssBytesMulti, readHostTotalBytes, registryRoot, resolveBaseDtb, resolveBaseKernel, resolveBaseRootfs, resolveMke2fs, resolveMksquashfs, resolveVmmBinary, restore, rootfsImgCacheDir, runGc, validatePid, warmImageConfigCache, writeBootSnapshot };