@supermachine/core 0.4.25

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,407 @@
+# @supermachine/core
+
+> Run any OCI/Docker image as a hardware-isolated microVM, from Node.js / Bun / Deno. Sub-100 ms cold start, ~3 MiB RAM per idle VM, full API parity with the [`supermachine`](https://crates.io/crates/supermachine) Rust crate via napi-rs.
+
+```bash
+npm install @supermachine/core
+```
+
+**No Rust toolchain required.** The package ships a prebuilt, code-signed native addon via the `@supermachine/core-darwin-arm64` optional dependency — npm's `os` / `cpu` filter installs only on macOS Apple Silicon (the current only supported platform). At runtime you need:
+
+- macOS Apple Silicon (`arm64`)
+- Node ≥ 18.17, Bun, or Deno 2+
+- Network access on first `Image.build()` (OCI registry pull via `curl`, no Docker daemon required — same pull model as libkrun / krunvm). After bake, snapshots are local and offline-usable.
+
+For private registries, supermachine reads `~/.docker/config.json` (the same auth file Docker writes via `docker login`). You can create that file by hand if you don't have Docker installed. To force the legacy Docker-daemon-based pull path, set `SUPERMACHINE_IMAGE_SOURCE=docker`.
+
+```ts
+import { Image } from "@supermachine/core";
+
+const image = await Image.build({ ref: "alpine:latest" });
+const pool  = await image.pool({ min: 4, max: 16 });
+const vm    = await pool.acquire();
+try {
+  const { stdout, exitCode } = await vm.exec({
+    argv: ["echo", "hello from the VM"],
+    timeoutMs: 5_000,
+  });
+  console.log(stdout.toString());   // "hello from the VM\n"
+} finally {
+  await vm.release();
+}
+```
+
+---
+
+## Why microVMs
+
+Same hardware isolation as Firecracker, libkrun, or qemu — but the *acquire latency* you'd expect from a container. Designed for use cases where you'd otherwise pick between containers (fast but shared-kernel) and full VMs (isolated but slow):
+
+- **Agent runtimes** — spin up a fresh, hardware-isolated environment per agent task, run untrusted code, throw it away. ~5 ms cycle, no kernel-namespace escapes to worry about.
+- **CI / build verifiers** — compile + run untrusted code (MultiPL-E, Codeforces solutions, student submissions) without trusting the host.
+- **Per-tenant sandboxes** — run customer code per request without a fork+exec security boundary.
+- **Code execution APIs** — same as the OpenAI Code Interpreter pattern, hardware-isolated.
+
+If your bar is "fast enough fork" and you trust the workload, use containers. If your bar is "I'm running this code from an LLM and the host needs to survive", use this.
+
+---
+
+## Status
+
+**Currently supported:** macOS on Apple Silicon (`darwin-arm64`, HVF backend).
+**Roadmap:** Linux KVM (`linux-arm64-gnu`, `linux-x64-gnu`), Windows WHP.
+
+For platforms not yet supported, the package installs cleanly but emits a clear error on first call. The `optionalDependencies` mechanism means non-supported hosts don't fail `npm install`.
+
+---
+
+## Performance, measured
+
+All numbers are on Apple Silicon (M-series, 24 GiB dev box), `alpine:latest` unless noted. The numbers include the napi-rs binding overhead (~10–20 µs per `await` from libuv worker scheduling). Per-call overhead is 0.3–0.5 % vs. direct Rust embedders — the floor is set by V8 / libuv / HVF, not by the binding.
+
+| Operation | Cost | Notes |
+|---|---|---|
+| Cold bake (first run, Docker layer cache warm) | **~400 ms** | Pulls layers → squashfs → boots VM → captures snapshot |
+| Cache-hit bake | **~15 ms** | Re-running `Image.build` for an already-baked image |
+| First `acquire()` after `build()` (warm-handoff) | **~0 ms** | Bake's living worker is stashed for the first acquire |
+| `acquire()` on pre-spawned idle pool entry | **~0 ms** | Just a queue pop |
+| `acquire()` with cycle-restore | **~5 ms** | HVF-bound; restoration from in-memory snapshot |
+| `acquire()` spawn-from-disk (pool growing) | **~22 ms** | Fork + dyld + HVF setup + mmap-restore |
+| `vm.exec(["echo", "hi"])` round-trip | **~0.3 ms** | vsock RPC to the in-guest agent — no host fork |
+
+### Memory
+
+Each idle VM costs **~3 MiB host `phys_footprint`** (measured). The `memoryMib` build option is a *guest-visible ceiling*, not host commit — pages are committed lazily via CoW page-faults. Read-only state (kernel, init binaries, your image's `rustc`/`python` etc.) is shared across all VMs via the snapshot's mmap, so a pool of 50 VMs uses ~150 MiB total, not 50 × 256 MiB.
+
+**The hard limit on parallelism isn't VM count — it's concurrent active workloads.** 50 idle VMs ≈ 150 MiB; 50 simultaneous rustc compiles ≈ 15+ GiB. Size your pool against expected *active concurrency*, not problem count.
+
+---
+
+## Integration patterns
+
+### Pattern 1: One-shot exec (CI / verifier)
+
+You have generated code, want to run it in isolation, get the result, throw the VM away.
+
+```ts
+import { Image } from "@supermachine/core";
+
+const image = await Image.build({
+  ref: "python:slim",
+  memoryMib: 512,
+});
+
+const pool = await image.pool({ min: 0, max: 8, restoreOnRelease: true });
+
+async function runCandidate(source: string): Promise<{ ok: boolean; stdout: string }> {
+  const vm = await pool.acquire();
+  try {
+    const out = await vm.exec({
+      argv: ["python3", "/tmp/code.py"],
+      stageFiles: { "/tmp/code.py": Buffer.from(source) },
+      timeoutMs: 10_000,
+    });
+    return { ok: out.exitCode === 0, stdout: out.stdout.toString() };
+  } finally {
+    await vm.release();
+  }
+}
+
+const results = await Promise.all(
+  candidates.map(runCandidate),  // queues through pool of 8
+);
+```
+
+`restoreOnRelease: true` is the right default here — each candidate runs in clean state.
+
+### Pattern 2: Agent runtime (per-task isolated sandbox)
+
+```ts
+import { Image } from "@supermachine/core";
+
+const image = await Image.build({
+  ref: "python:slim",
+  memoryMib: 512,
+  // Pre-warm: import heavy libs once at bake time, snapshot the
+  // warm state. Subsequent acquires land on the post-import
+  // snapshot — saves ~200 ms of import cost per task.
+  warmupTag: "v1",                       // bump to invalidate cache
+  warmup: async (vm) => {
+    await vm.exec({
+      argv: ["python3", "-c", "import numpy, pandas, requests"],
+      timeoutMs: 60_000,
+    });
+  },
+});
+
+const pool = await image.pool({
+  min: 4,                                // warm idle pool
+  max: 32,                               // burst capacity
+  restoreOnRelease: true,                // isolate per task
+  acquireTimeoutMs: 30_000,
+});
+
+// In your request handler:
+async function handleAgentTask(taskCode: string) {
+  using vm = await pool.acquire();       // Node 20+ disposer
+  return await vm.exec({
+    argv: ["python3", "/tmp/task.py"],
+    stageFiles: { "/tmp/task.py": Buffer.from(taskCode) },
+    timeoutMs: 30_000,
+  });
+}                                        // auto-released
+```
+
+### Pattern 3: Persistent service inside the VM
+
+You want to bake an image where the snapshot includes a *running listener* (nginx, redis, your own daemon) so first restore has it serving immediately.
+
+```ts
+const image = await Image.build({
+  ref: "nginx:alpine",
+  listenerRequired: true,   // wait for workload to bind before snapshot
+  // (no warmup needed — listener-ready trigger fires when nginx is up)
+});
+```
+
+Without `listenerRequired`, the default `.build()` uses a *pre-exec* snapshot trigger for ~10× faster bake on slow-starting workloads — but the listener won't be bound at restore time. The right knob depends on whether your code talks to the workload's listener or runs its own `vm.exec` commands.
+
+### Pattern 4: Resource files baked into the snapshot
+
+Sometimes you need files inside the guest that aren't part of the OCI image — a config, a cert, a binary. `extraFiles` stages them into the snapshot's filesystem layer:
+
+```ts
+const image = await Image.build({
+  ref: "alpine:latest",
+  extraFiles: [
+    { hostPath: "./config/app.toml",    guestPath: "/etc/app.toml" },
+    { hostPath: "./certs/server.pem",   guestPath: "/etc/server.pem" },
+  ],
+});
+```
+
+Host file contents are folded into the snapshot's input-hash, so editing the host file invalidates the cache and rebakes automatically.
+
+---
+
+## Full API
+
+Auto-generated from the Rust source — see [`index.d.ts`](./index.d.ts) for the typed surface. Highlights below; runnable demos in [`examples/`](./examples/).
+
+### `Image`
+
+```ts
+class Image {
+  static build(options: BuildOptions): Promise<Image>;
+  static fromSnapshot(path: string): Promise<Image>;
+  pool(options?: PoolOptions): Promise<Pool>;
+
+  // Sync accessors — read from snapshot metadata, cached.
+  readonly snapshotPath: string;
+  readonly memoryMib: number;
+  readonly vcpus: number;
+}
+```
+
+`BuildOptions`:
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `ref` | `string` | required | OCI ref: `"alpine:latest"`, `"ghcr.io/owner/img@sha256:..."` |
+| `name` | `string` | sha-derived | Stable snapshot name |
+| `memoryMib` | `number` | 256 | Guest-visible ceiling (lazy-committed) |
+| `vcpus` | `number` | 1 | vCPUs per VM |
+| `pullPolicy` | `"always" \| "missing" \| "never"` | `"missing"` | docker-style pull policy |
+| `cmd` | `string[]` | (image CMD) | Override the image's CMD / ENTRYPOINT |
+| `env` | `Record<string, string>` | `{}` | Extra workload env vars |
+| `guestPort` | `number` | 80 | Listener port (used with `listenerRequired`) |
+| `listenerRequired` | `boolean` | `false` | Wait for workload's listener before snapshotting |
+| `extraFiles` | `ExtraFile[]` | — | Stage host files into guest at fixed paths |
+| `warmupTag` | `string` | `"default"` | Cache key for the warmup; bump to invalidate |
+| `warmup` | `(vm: WarmupVm) => Promise<void>` | — | Post-bake state pre-population |
+| `snapshotsDir` | `string` | `~/.local/supermachine-snapshots` | Where to write the snapshot |
+
+### `Pool`
+
+```ts
+class Pool {
+  acquire(): Promise<Vm>;
+  stats(): PoolStats;          // sync, ~1 µs — safe to poll
+  shutdown(): Promise<void>;
+}
+
+interface PoolStats {
+  alive: number;     // total workers (idle + checked-out)
+  inUse: number;     // checked out via acquire()
+  idle: number;
+  waiting: number;   // acquire() callers blocked on a free slot
+  min: number;
+  max: number;
+}
+```
+
+`PoolOptions`:
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `min` | `number` | 1 | Idle VMs to keep warm |
+| `max` | `number` | 1 | Maximum total VMs |
+| `acquireTimeoutMs` | `number` | 60 000 | Max wait when pool is saturated. **Pass `0` for "block forever" (batch workloads).** |
+| `idleTimeoutMs` | `number` | — | Evict idle VMs above `min` after this |
+| `restoreOnRelease` | `boolean` | `true` | Clean state per acquire (vs. dirty reuse) |
+| `memoryMib` | `number` | (image default) | Runtime memory override (no re-bake) |
+| `vcpus` | `number` | (image default) | Runtime vCPU override (no re-bake) |
+| `restoreTimeoutMs` | `number` | 30 000 | Per-worker snapshot-restore deadline |
+
+### `Vm`
+
+```ts
+class Vm {
+  // Execution
+  exec(options: ExecOptions): Promise<ExecOutput>;
+  spawn(options: ExecOptions): Promise<ExecChild>;   // streaming variant
+
+  // File I/O (4 MiB cap each direction)
+  writeFile(path: string, bytes: Buffer): Promise<void>;
+  readFile(path: string): Promise<Buffer>;
+
+  // Workload control
+  workloadSignal(signum: number): Promise<void>;     // SIGTERM/SIGHUP/etc. to PID-1
+  exposeTcp(hostPort: number, guestPort: number): Promise<TcpForwarder>;
+
+  // Mid-flight snapshot
+  snapshot(destDir: string): Promise<Image>;
+
+  // Lifecycle
+  release(): Promise<void>;
+  dispose(): Promise<void>;        // alias; Symbol.asyncDispose-friendly
+
+  // Escape hatches (raw socket paths for bring-your-own-client)
+  readonly vsockPath: string;
+  readonly execPath: string;
+}
+```
+
+`ExecOptions`:
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `argv` | `string[]` | required | argv[0] resolved via PATH inside the guest |
+| `stageFiles` | `Record<string, Buffer>` | `{}` | Files to drop into the guest before exec (mode 0o644) |
+| `stageFilesMode` | `StagedFileMode[]` | — | Same as stageFiles but with explicit per-file modes (e.g. 0o755 for scripts) |
+| `timeoutMs` | `number` | 60 000 | Hard wall-clock kill (collect-mode `exec` only) |
+| `env` | `Record<string, string>` | `{}` | Per-exec env (merged with image env) |
+| `cwd` | `string` | `/` | Working directory inside the guest |
+| `chain` | `string[]` | — | Run if first argv exits 0 (saves one round-trip) |
+| `tty` | `boolean` | `false` | Allocate a pty; stdout/stderr merge onto stdout |
+| `winsize` | `{cols, rows}` | — | Initial pty size (tty only). Resize later via `ExecChild.resize()` |
+
+`ExecOutput` (collect-mode):
+
+```ts
+interface ExecOutput {
+  stdout: Buffer;
+  stderr: Buffer;
+  exitCode: number;     // -1 if killed by signal / timeout
+}
+```
+
+### `ExecChild` (streaming, returned by `vm.spawn()`)
+
+Pull-style bidirectional I/O. Use when you want incremental input/output (LLM-style streaming, interactive REPLs, long-running daemons) instead of waiting for the whole exec to finish.
+
+```ts
+class ExecChild {
+  writeStdin(bytes: Buffer): Promise<void>;
+  closeStdin(): Promise<void>;
+  readStdout(maxBytes?: number): Promise<Buffer>;   // returns 0-length on EOF
+  readStderr(maxBytes?: number): Promise<Buffer>;
+  signal(signum: number): Promise<void>;            // e.g. 15=SIGTERM, 9=SIGKILL
+  resize(cols: number, rows: number): Promise<void>;// tty resize; no-op in pipe mode
+  wait(): Promise<ExecWaitResult>;
+}
+
+interface ExecWaitResult {
+  exitCode: number;
+  timedOut: boolean;
+  peakRssKib: number | null;
+}
+```
+
+### `TcpForwarder` (returned by `vm.exposeTcp()`)
+
+Proxies `127.0.0.1:hostPort` into the guest's vsock mux. In-flight connections survive `stop()`.
+
+```ts
+class TcpForwarder {
+  readonly localAddr: string;     // e.g. "127.0.0.1:54321"
+  stop(): Promise<void>;          // idempotent
+}
+```
+
+---
+
+## `using` syntax (Node 20+)
+
+If you have explicit-resource-management (TC39) enabled:
+
+```ts
+{
+  using vm = await pool.acquire();
+  await vm.exec({ argv: ["echo", "auto-released"] });
+}   // vm.release() runs at end of block
+```
+
+For older Node / Bun / Deno without `Symbol.asyncDispose`, use `try/finally`:
+
+```ts
+const vm = await pool.acquire();
+try {
+  await vm.exec({ argv: ["echo", "manual"] });
+} finally {
+  await vm.release();
+}
+```
+
+---
+
+## Compatibility
+
+| Runtime | Status |
+|---|---|
+| Node.js ≥ 18.17 | supported (LTS line, N-API 9) |
+| Node.js ≥ 20 | supported + `Symbol.asyncDispose` available |
+| Bun ≥ 1.0 | supported (same .node binary) |
+| Deno ≥ 2 | supported (same .node binary, `--unstable-node-api` for older) |
+| Browsers / Cloudflare Workers / Edge | not supported (no HVF available; see `@supermachine/client` roadmap) |
+
+The native binary is a single `.node` file built with napi-rs; the N-API ABI is stable so runtime upgrades don't require rebuilds.
+
+---
+
+## Troubleshooting
+
+**`hv_vm_create: 0xfae94007`** — worker binary lost its HVF entitlement (usually after a manual `cargo build` strip). The published npm binary is pre-signed; if you're running from source, run `npm run build` which re-signs.
+
+**`registry unreachable`** — Docker registry DNS failed. Check your network. Pre-pull images you depend on with `docker pull <image>` to surface this earlier.
+
+**`snapshot path not found`** — calling `Image.fromSnapshot` immediately after `Image.build` can race the bg disk save. Either wait for the file to exist or just keep the `Image` handle from `build()` instead of reloading.
+
+**Pool seems to hang under load** — likely cycle-restore-on-release contention. Set `restoreOnRelease: false` for throughput-style workloads if you don't need state isolation between acquires.
+
+**Memory grows over time** — first sample after balloon convergence (~10 s); pre-balloon RSS is misleading. Use macOS `footprint -p <pid>` for accurate per-process memory accounting (RSS double-counts shared snapshot mmap pages).
+
+---
+
+## Versioning
+
+Lockstep with the [`supermachine`](https://crates.io/crates/supermachine) Rust crate. Each release ships a matching `@supermachine/core` and platform binary (e.g. `@supermachine/core-darwin-arm64`) with the same version number. Pin in your `package.json` with an exact match if you bake snapshots and don't want the snapshot format to drift.
+
+## License
+
+Apache-2.0
+
+## Source
+
+GitHub: <https://github.com/supercorp/supermachine>
+Rust crate: <https://crates.io/crates/supermachine>

package/examples/01-hello.mjs

@@ -0,0 +1,32 @@
+// 01-hello.mjs — the minimum @supermachine/core program.
+//
+// Boots an alpine:latest microVM, runs `echo hello`, prints the
+// output. Cold bake ~400 ms; cache-hit ~15 ms + first-acquire
+// near-zero (warm handoff).
+//
+// Run:
+//   node examples/01-hello.mjs
+//
+// Requires Docker (for the OCI image pull) and macOS on Apple
+// Silicon (no Linux/Windows backends yet).
+
+import { Image } from "@supermachine/core";
+
+const img = await Image.build({
+  ref: "alpine:latest",
+  // Stable name → snapshot cached on disk, so subsequent runs
+  // skip the bake. Omit for an auto-derived sha-name.
+  name: "hello-alpine",
+});
+
+const pool = await img.pool({ min: 1, max: 1 });
+const vm = await pool.acquire();
+
+const { stdout, exitCode } = await vm.exec({
+  argv: ["echo", "hello from supermachine"],
+  timeoutMs: 5_000,
+});
+
+console.log(`exit ${exitCode}:`, stdout.toString().trim());
+
+await vm.release();