Plans index¶
This page summarises every planning document in chronological order. Master plans decompose work into numbered phases, each with its own detailed plan file. Standalone plans track issues, follow-ups, or design decisions that do not require phased execution.
New plans should follow the structure in PLAN-TEMPLATE.md at the repo
root. For pre-push audits of our own work see PUSH-TEMPLATE.md (also
at the repo root).
Master plans¶
| Date | Plan | Intent | Status | Phases |
|---|---|---|---|---|
| 2026-05-08 | Distro matrix CI | Run instar's full functional test suite against installed .deb/.rpm packages on a representative matrix of Linux distributions in the GitHub merge queue, with qemu-img differential coverage |
Drafted, not started | (phases not yet written; design blocks pending) |
| 2026-05-09 | Release v0.2.0 | Cut the v0.2.0 tag and publish signed GitHub Release artifacts (tarball, .deb, .rpm) for x86_64 Linux | Complete (tagged 2026-05-09) | (no phase files; sequential gates) |
| 2026-05-10 | First public release of instar | Cargo.toml metadata, release workflow, .deb/.rpm packaging, and signing for instar's public releases (umbrella plan; v0.2.0 execution lives in PLAN-release-v0.2.md) |
In progress (phases 1-4 complete through v0.2.0; phase 5 audit mostly done; phase 6 coverage fuzzing in progress) | (phases inline) |
| 2026-05-10 | Security audit | Sweep instar for security weaknesses across the host VMM, KVM guest, call-table boundary, and format parsers, including coverage-guided fuzzing | In progress (phases 1a-5 done; phase 6 coverage fuzzing in progress) | (phases inline) |
| 2026-05-10 | Coverage-guided fuzzing | Stand up coverage-guided fuzzing across the format parsers and run sustained campaigns | In progress (steps 1-5 infrastructure merged; extended runs not yet complete) | (phases inline) |
| 2026-05-10 | Fuzz autofix workflow | Workflow that triages fuzzer-discovered crashes and proposes minimal fixes | In progress (workflow scaffolding merged; not yet exercised end-to-end) | (phases inline) |
| 2026-05-10 | Convert follow-ups | Track the deferred work from the (now-removed) convert master plan: extra qemu-img subcommands (create / map / measure / resize / snapshot / rebase / commit) and check --repair wiring |
Complete — phase 1 (all seven subcommands shipped; snapshot closed the roster) and phase 2 (check --repair, promoted to PLAN-check-repair.md, all 11 phases landed) both done |
1: subcommand parity, 2: check --repair |
| 2026-05-10 | instar measure subcommand |
Implement the measure subcommand (qemu-img parity for raw and qcow2 outputs; instar extensions for vmdk / vhd / vhdx) with cross-version baselines, integration tests, coverage-guided fuzzing, and differential fuzzing |
Complete (phases 1-10) | 1: calculators, 2: allocation scanners, 3: guest op, 4: host CLI, 5: target options, 6: baselines, 7: integration tests, 8: coverage fuzz, 9: differential fuzz, 10: docs |
| 2026-05-16 | instar create subcommand |
Implement the create subcommand (qemu-img parity for raw / qcow2 / vmdk monolithicSparse / vhd / vhdx outputs, with backing-file support, preallocation modes, cross-version info-equivalence baselines, integration tests, coverage-guided fuzzing, and differential fuzzing) |
Complete (phases 1-11) | 1: emitters, 2: guest op, 3: host CLI, 4: target options, 5: backing file, 6: preallocation, 7: baselines, 8: integration tests, 9: coverage fuzz, 10: differential fuzz, 11: docs |
| 2026-05-20 | instar resize subcommand |
Implement the resize subcommand (qemu-img parity for raw / qcow2 / vmdk monolithicSparse / vhd dynamic+fixed / vhdx dynamic, including --shrink for raw and qcow2, --preallocation modes, the [+-]SIZE syntax, a new read_output_sector call-table primitive, cross-version info-equivalence baselines, integration tests, coverage-guided fuzzing, and differential fuzzing) |
Complete (phases 1-13) | 1: skeleton, 2: qcow2 grow, 3: qcow2 shrink, 4: vhd, 5: vhdx, 6: vmdk, 7: guest op, 8: host CLI, 9: preallocation, 10: baselines, 11: integration tests, 12: fuzz, 13: docs |
| 2026-05-30 | instar rebase and instar commit subcommands |
Implement rebase (change backing-file references; both -u unsafe metadata-only mode and the default safe data-aware mode) and commit (merge overlay clusters into backing file) for qcow2 and vmdk monolithicSparse, with cross-version baselines, integration tests, coverage-guided fuzzing, and differential fuzzing. Reuses the read_output_sector call-table primitive from resize; no ABI extension required. |
Complete (phases 1-12) | 1: ABI, 2: rebase planners, 3: rebase guest, 4: rebase host, 5: rebase tests, 6: commit planners, 7: commit guest, 8: commit host, 9: commit tests, 10: fuzz, 11: diff fuzz, 12: docs |
| 2026-05-25 | resize followup-01: targeted refcount pre-pass | Lift the qcow2 grow image-size ceiling (~128 GiB at default cluster) by replacing the guest's "stage every refcount block" pre-pass with a targeted pre-pass that stages only the specific blocks the chosen grow flavour will modify. New public compute_qcow2_grow_query planner helper computes the action + required-block set; guest pre-pass dispatches on it. Bound is now "what the filesystem can hold" instead of per-cluster-size. Shrink retains its older stage-all pre-pass (separate followup). |
Complete (steps 01a-01e) | 01a: planner helper, 01b: guest pre-pass, 01c: large-image integration tests, 01d: fuzz clamp relaxation, 01e: docs |
| 2026-05-27 | Fuzzing bug backlog | Triage and fix the 44 open security-audit GitHub issues filed by coverage-guided fuzzing and differential fuzzing. Five root-cause fix phases: plan_vmdk capacity overflow, qcow2 scan_allocation out-of-bounds L2 entries, measure-calculator sum overflow, vhd/vhdx/vmdk allocated_bytes clamp, differential-fuzz external-timeout reclassification. |
Complete (phases 1-5) | 01: plan_vmdk, 02: qcow2 OOB L2, 03: measure calc overflow, 04: vhd/vhdx/vmdk clamp, 05: diff-fuzz timeouts |
| 2026-06-03 | instar map subcommand |
Implement the map subcommand (qemu-img parity for raw / qcow2 / vmdk / vhd / vhdx single-image sources, streaming per-extent emission over the guest serial channel, cross-version baselines, integration tests, coverage-guided fuzzing, and differential fuzzing). Backing-chain depth composition deferred to a follow-up. |
Complete (phases 1-9) | 1: extent iterators, 2: guest op, 3: host CLI, 4: output formatting, 5: baselines, 6: integration tests, 7: coverage fuzz, 8: differential fuzz, 9: docs |
| 2026-06-08 | instar snapshot subcommand |
Implement the snapshot subcommand (qcow2-only, mirroring qemu-img snapshot's -l/-c/-a/-d modes). List mode emits qemu-img-compatible human and JSON output; mutating modes manipulate the snapshot table, L1 copies, refcounts, and COPIED flags entirely inside the KVM guest using the existing write_input_sector primitive. Cross-version list baselines, integration tests with qemu-img check / info / compare post-op assertions, coverage-guided fuzzing of parse and refcount mutators, and differential fuzzing of random -c/-d/-a chains against qemu-img. Closes out the convert-followups subcommand roster. |
Complete (phases 1-14) | 1: ABI, 2: list planner, 3: list guest, 4: list host, 5: refcount mutators, 6: create, 7: delete, 8: apply, 9: mutate host, 10: baselines, 11: integration tests, 12: coverage fuzz, 13: differential fuzz, 14: docs |
| 2026-06-13 | June 2026 fuzzer bug backlog | Triage and fix the 10 open bug GitHub issues outstanding after the May 2026 backlog drain. Three root-cause fix phases: Fixed-VHD virtual_size overflow in plan_vhd (7 fuzz_create_emitters issues), unchecked VHDX resize sequence-number increment (2 fuzz_resize_planners issues), and qcow2 resize --shrink sub-byte refcount corruption (1 hand-filed snapshot-audit issue). |
Complete (phases 1-3: bbfdfc9, 514c52a, a54cef8) |
01: fixed-vhd overflow, 02: vhdx resize seqnum, 03: qcow2 shrink sub-byte refcount |
| 2026-06-13 | instar check --repair for QCOW2 |
Wire CheckConfig::FLAG_REPAIR (reserved but dead since the original check op) to real QCOW2 repair logic, mirroring qemu-img check -r leaks/-r all. Settles the repair safety model (tiered safe-vs-lossy repair, dry-run-by-default, in-place mutation with no mandatory backup, crash-safe write ordering guarded by the corrupt header bit, refuse-rather-than-guess) and implements leak reclamation + refcount/COPIED rebuild inside the KVM guest, reusing the src/crates/snapshot/ refcount mutators. Corrupt-fixture baselines, integration tests with post-op qemu-img check/info/compare, coverage and differential fuzzing. Promoted from convert-followups phase 2. |
Complete (all 11 phases landed) | 1: ABI + crate, 2: leak planner, 3: refcount planner, 4: guest (leaks tier), 5: guest (all tier), 6: host CLI, 7: baselines, 8: integration tests, 9: coverage fuzz, 10: differential fuzz, 11: docs |
| 2026-06-15 | instar amend subcommand |
Implement the amend subcommand (qcow2-only, mirroring qemu-img amend -o). v1 scope is the two header-only options that change no cluster/refcount data: compat=0.10\|1.1 (qcow2 v2⇔v3 version transition, with v3-only-feature downgrade blockers, refcount-width constraints, and header-extension relocation) and lazy_refcounts=on\|off (the v3 compatible-feature bit). Reuses the resize/rebase in-place-mutation idiom; new src/crates/amend/ planner crate and src/operations/amend/ guest op. Cross-version info-equivalence baselines, integration tests with post-op info/check/compare, coverage and differential fuzzing. refcount_bits, external data file, encryption, and backing-file amend deferred. Picks up the qemu-img amend sibling deferred from convert-followups. |
Complete (phases 1-9) | 1: ABI, 2: qcow2 planner, 3: guest, 4: host CLI, 5: rust tests, 6: integration tests, 7: baselines, 8: fuzz, 9: docs |
| 2026-06-21 | instar dd subcommand |
Implement the dd subcommand to upstream qemu-img dd parity (no PVE/downstream extensions). dd is convert with a windowed input: name=value operands (bs/count/skip/if/of) plus -f/-O (default output raw), a dense (non-sparse) copy, and faithful quirk replication (count shrinks-only, skip subtracts after count, skip-past-EOF ⇒ empty-but-exit-0, bs=0 rejected, short final block). Reuses convert's format writers and the run_convert lifecycle. New host name=value operand parser, guest input-windowing path, cross-version baselines, integration tests over a 14-row cross-validation matrix vs real qemu-img dd, coverage and differential fuzzing. First of the three remaining in-scope subcommands (dd, then bitmap, then bench). |
Complete | 1: ABI, 2: host operands, 3: guest raw, 4: guest formats, 5: rust tests, 6: integration tests, 7: baselines, 8: coverage fuzz, 9: differential fuzz, 10: docs |