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 |
Not started | 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 |