supermachine-kernel 0.1.0

# supermachine-kernel

Pre-built Linux kernel image and in-VM `init-oci` shim for the
[supermachine](https://crates.io/crates/supermachine) microVM
runtime.

This is a **data crate**. No public functions worth calling on
their own; depend on it alongside `supermachine` so the runtime
finds its kernel + init shim.

## Quick start

```toml
[dependencies]
supermachine        = "=0.1"
supermachine-kernel = "=0.1"
```

Pin both to the same version with `=` — the snapshot format is
keyed to the kernel build, and a partial `cargo update` would
invalidate previously baked snapshots.

```rust
// Stage the bundled assets into a writable scratch dir, then
// point supermachine at them.
let scratch = std::env::temp_dir().join("supermachine-assets");
std::fs::create_dir_all(&scratch)?;
supermachine_kernel::extract_kernel_to(&scratch.join("kernel"))?;
supermachine_kernel::extract_init_oci_to(&scratch.join("init-oci"))?;

let assets = supermachine::AssetPaths::from_dir(&scratch);
let vm = supermachine::Vm::start(
    &supermachine::Image::from_snapshot("path/to/snapshot")?,
    &supermachine::VmConfig::new().with_assets(assets),
)?;
```

For `.app`-bundle distribution, do the extraction in a `build.rs`
so the bundle is self-contained — no first-run download.

## What this ships

| Asset | Size | Purpose |
| --- | ---: | --- |
| `KERNEL_BYTES` | ~29 MiB | aarch64 Linux `Image` with the AF_TSI patch series. Loaded into guest RAM at VM start. |
| `INIT_OCI_BYTES` | ~1.6 MiB | Statically-linked aarch64-musl PID 1. Mounts overlayfs, /proc, /dev; exec's the OCI image entrypoint. Only needed for fresh bakes; snapshot restore doesn't use it. |

The bytes ship inside the published `.crate` as **xz-compressed
payloads** (`kernel.xz` ≈ 7 MiB, `init-oci.xz` ≈ 330 KiB). cargo's
outer gzip on the tarball adds essentially nothing on already-xz
data, so the final `.crate` is ~7.3 MiB — comfortably under
crates.io's 10 MiB cap. No network, no separate install step:
`cargo add supermachine-kernel` and `build.rs` decompresses the
payloads into `OUT_DIR` at first build.

`build.rs` resolves the assets in this order:

1. `SUPERMACHINE_KERNEL_PATH` / `SUPERMACHINE_INIT_OCI_PATH` env
   vars — point at uncompressed files. Use this for a custom
   kernel build.
2. The bundled `kernel.xz` / `init-oci.xz` next to `Cargo.toml`.
   Decompressed via `xz -d` (universally available on macOS 11+
   and every mainstream Linux distro). This is the default path.

Decompression runs once at first `cargo build` (~50–100 ms);
subsequent builds use cargo's incremental cache. If `xz` is
missing on the build host: `brew install xz`,
`apt install xz-utils`, or `dnf install xz`.

## API

- [`KERNEL_BYTES`] / [`KERNEL_LEN`]
- [`INIT_OCI_BYTES`] / [`INIT_OCI_LEN`]
- [`extract_kernel_to`] / [`extract_kernel_to_with_parents`]
- [`extract_init_oci_to`] / [`extract_init_oci_to_with_parents`]

See the rustdoc for usage notes.

## License

This crate is a combined work under three licenses (see the
`NOTICE` file shipped in this crate for full attribution + the
GPL §3(b) source-availability offer):

- **Apache-2.0** — our build glue (`build.rs`, `src/lib.rs`).
  See [`LICENSE-APACHE`](./LICENSE-APACHE).
- **GPL-2.0-only** — the bundled Linux kernel image
  (`kernel.xz`). See [`LICENSE-GPL-2.0`](./LICENSE-GPL-2.0).
  Source available on request per GPL-2.0 §3(b) — see
  [`NOTICE`](./NOTICE) for the written offer (email
  `domas@supercorp.ai` with the crate version received).
- **MIT** — musl libc statically linked into the bundled
  `init-oci` binary (`init-oci.xz`). See
  [`LICENSE-MIT`](./LICENSE-MIT).

SPDX expression: `Apache-2.0 AND GPL-2.0-only AND MIT`.

Redistributing this crate requires satisfying each license on
its respective component. Most redistributors are fine: the
kernel runs as guest data, not as linked host code.