# G-060 QEMU-based cross-platform test matrix (arm's-length integration, GPL-safe posture)

Status: proposed
Scope: build/test orchestration config and scripts (location to be settled with the buildsuites toml work - see G-005/buildsuites direction), goals/G-060-qemu-test-matrix.md (workflow + license posture), src/tests/ (any guest-driving hooks)
Goal: comprehensive cross-platform verification (linux variants, FreeBSD/NetBSD/OpenBSD, arm architectures) is achievable from a single dev machine by driving QEMU guests as strictly external tooling - punkshell invokes qemu as a separate process with declarative per-guest config, and nothing in punkshell or its artifact repos bundles, links against, derives from or otherwise couples to QEMU (GPLv2) - so the project's BSD licensing posture is unaffected and QEMU remains a swappable convenience: the guest-driving contract is push-based artifact staging and result collection (the same pattern G-059 establishes for WSL - guests never share a working tree with the host) and must be satisfiable by real hardware, WSL or another hypervisor.
Acceptance: a documented, repeatable workflow provisions at least one non-Windows QEMU guest (e.g FreeBSD x86_64) that fetches a punkbin runtime and runs the source-tree suite inside the guest, driven from the Windows dev machine with results collected back; the guest-driving interface is hypervisor-agnostic (documented contract; QEMU is one provider); the license posture is recorded in the detail file (external-process invocation only, no QEMU binaries or derived code committed to punkshell or punkbin, guest OS images not redistributed by the project - fetched/built per machine); suite runs on machines without QEMU are unaffected.

## Context

punkshell targets Windows primarily with Linux, macOS and FreeBSD as secondary targets,
and punkbin carries (or will carry) runtimes for linux-x86_64/linux-arm/macosx/freebsd
and more. Real verification on those platforms currently requires real machines. QEMU
can provide the matrix from one dev box - but QEMU is GPLv2, and punkshell is BSD: the
integration must be shaped so no licensing entanglement is possible.

## License posture (the point of the "arm's-length" framing)

- QEMU is invoked strictly as an EXTERNAL PROCESS - the same relationship a shell has
  to any tool it execs. No linking, no derived code, no embedding.
- No QEMU binaries are committed to punkshell or punkbin; each machine installs QEMU
  from its own distribution channel. (punkbin's binary policy is for punk runtimes and
  build tools we produce/pin - not third-party GPL hypervisors.)
- Guest OS images are not redistributed by the project - fetched or built per machine
  from upstream (BSDs/linux have their own licenses and trademark rules; staying out of
  image distribution avoids that entire surface).
- Nothing in punkshell's runtime or module code may depend on QEMU's presence; only
  optional test-orchestration tooling knows it exists, and even that through a
  hypervisor-agnostic contract (below). If QEMU disappeared, the contract remains.

## Approach

### Guest-driving contract (hypervisor-agnostic)

The punkshell-owned artifact is a small contract, not a QEMU integration:
- provision: bring up a named guest from declarative per-guest config (platform, arch,
  how to boot, how to reach it - ssh being the obvious transport)
- stage: push artifacts (runtimes, test fixtures, or a source snapshot/clone) into the
  guest's native filesystem - push-based staging and result collection, the same
  pattern [[G-059]] establishes for WSL; guests never share a working tree with the
  host (the DrvFs/VCS-recalculation lesson generalizes: no host checkout is ever
  operated on from a guest)
- run: execute a command in the guest (e.g fetch a punkbin runtime, run
  src/tests/runtests.tcl from a native clone)
- collect: bring results back to the host
QEMU is one provider of this contract; real hardware, WSL (G-059) or another hypervisor
must be able to satisfy it identically. Config lives with the buildsuites-era toml
direction rather than a new ad-hoc location.

### Sequencing

- G-059 (WSL) first proves the staging/run/collect pattern cheaply on linux.
- First QEMU guest target: FreeBSD x86_64 (a declared secondary target with no WSL
  equivalent, and punkbin already anticipates freebsd folders).
- Guest provisioning recipes (image fetch, first-boot setup, ssh keys) documented per
  guest in the detail/config - repeatable, not artisanal.

## Notes

- Related: [[G-005]] (zig builds - the same guests could eventually host build
  verification for non-Windows artifacts), [[G-006]] (punkbin retrieval inside guests
  exercises runtime.cmd's unix payload for real), [[G-059]] (contract sibling).
- Performance expectations should stay modest (emulated arm will be slow); the matrix
  is for correctness verification, not speed benchmarking.
- Archived-goal references in this file: G-059 achieved 2026-07-11 (goals/archive/G-059-wsl-test-driving.md).