Multi-extent VMDK output: twoGbMaxExtentSparse and twoGbMaxExtentFlat¶
Status: Not started¶
Prompt¶
Before responding to questions or discussion points in this document, explore the instar codebase thoroughly. Read relevant source files, understand existing patterns (VMM structure, guest operation layout, shared crate conventions, call table ABI, format parsing, test infrastructure), and ground your answers in what the code actually does today. Do not speculate about the codebase when you could read it instead. Where a question touches on external concepts (QCOW2, VMDK, VHD/VHDX, LUKS, KVM, virtio, disk image formats), research as needed to give a confident answer. Flag any uncertainty explicitly rather than guessing.
Consult ARCHITECTURE.md for the overall system structure
(host VMM, KVM guest, call table, device emulation).
Consult AGENTS.md for build commands, project conventions,
code organisation, and the security model summary. Consult
docs/ for format-specific documentation (docs/qcow2/,
docs/raw/, etc.) and docs/commentary/ for architectural
decisions and design rationale.
Plan file conventions (shared block; do not edit -- the canonical
copy lives in shakenfist/development at
templates/shared-blocks/plan-file-conventions.md):
- All planning documents live in
docs/plans/. - Detailed planning gets one plan file per phase. Phase files are
named for their master plan, sit in the same directory as it,
and append
-phase-NN-descriptivebefore the.mdextension. - The master plan tracks its phases in a table under its Execution
section.
Mergedis last, and the push audit is the last row, for the reasons given inplan-push-audit-phase:
| Phase | Plan | Status | Merged |
|---|---|---|---|
| 1. Schema migration | PLAN-thing-phase-01-schema.md | Not started | |
| 2. Public API | PLAN-thing-phase-02-api.md | Not started | |
| 3. Push audit | - | Not started |
- One commit per logical change, and at minimum one commit per phase. Unrelated changes are not batched into a single commit. Each commit is self-contained: it builds, passes tests, and has a message explaining what changed and why.
Situation¶
The 2026 technical goal VHD/VMDK writers done has one leaf left.
PLAN-differencing.md closed the differencing leaves;
PLAN-bat-population.md closed VHDX fixed output, vmdk/vpc/vhdx
preallocation (as qemu parity, a no-op) and the per-format BAT
population pattern. What remains is VMDK twoGbMaxExtent* output and
the prerequisite the goals graph calls the multi-output-device call
table. Closing both turns the whole waypoint green.
Three earlier plans deferred to that prerequisite by name and none of
them built it: PLAN-create-phase-05-backing-file.md ("Future work;
requires multi-output-device call-table support"), PLAN-resize.md
(multi-file resize, twice), and PLAN-bat-population.md, which put it
out of scope because nothing in that plan needed it -- monolithicFlat
create is host-only and the convert path that writes it already uses
one output device.
What was measured¶
Everything in this section was measured on 2026-11-16 against
24b629cb (the merge of #912), with the host's qemu-img 10.0.13
(Debian 1:10.0.13+ds-0+deb13u1). The instar binary used was
src/target/release/instar dated 2026-10-19, which predates several
merges; every instar result below is a host-side refusal or a
host-side descriptor walk, reached before any guest operation starts,
so the stale binary does not affect them. Phase 1 re-measures against
a freshly built binary anyway.
qemu-img creates both subformats:
$ qemu-img create -f vmdk -o subformat=twoGbMaxExtentSparse sp.vmdk 5G
$ ls
sp.vmdk (417 bytes) sp-s001.vmdk sp-s002.vmdk sp-s003.vmdk
$ qemu-img create -f vmdk -o subformat=twoGbMaxExtentFlat fl.vmdk 5G
$ ls
fl.vmdk (415 bytes) fl-f001.vmdk fl-f002.vmdk fl-f003.vmdk
So there is a real oracle for both. This is the question that
collapsed the preallocation leaf in PLAN-bat-population.md into a
parity no-op, and here it answers the other way.
Extent naming is <stem>-s%03d.vmdk for sparse and <stem>-f%03d.vmdk
for flat. Flat extents are the full 2 GiB in length but sparse on disk
(the 5G flat image occupies 4 KiB). The descriptor qemu wrote:
# Disk DescriptorFile
version=1
CID=4de986e1
parentCID=ffffffff
createType="twoGbMaxExtentSparse"
# Extent description
RW 4194304 SPARSE "sp-s001.vmdk"
RW 4194304 SPARSE "sp-s002.vmdk"
RW 2097152 SPARSE "sp-s003.vmdk"
# The Disk Data Base
#DDB
ddb.virtualHWVersion = "4"
ddb.geometry.cylinders = "10402"
ddb.geometry.heads = "16"
ddb.geometry.sectors = "63"
ddb.adapterType = "ide"
ddb.toolsVersion = "2147483647"
Note the ddb.* block. docs/create.md's Future work records that
instar emits none of those lines; open question 3 takes that up.
The 80-build sweep (qemu 6.0.0 to 10.2.0) confirmed the naming and
descriptor shape above for both subformats; the only difference
across builds is ddb.toolsVersion = "2147483647" appearing from
6.2.0 onward. The pin is tests/golden/qemu-create-pins.json.
The ceiling. A 40 GiB image is 20 extents, which qemu-img reads without complaint. instar refuses it:
$ instar convert -O qcow2 big-flat.vmdk out.qcow2
Error: "chain depth 21 plus output device exceeds maximum of 16 devices"
$ instar convert -O qcow2 fl.vmdk out.qcow2 # 3 extents
(succeeds)
So instar cannot read any twoGbMaxExtent* image past 15 extents --
about 30 GiB -- today. That is a shipping limitation, not a
hypothetical, and it bounds any writer built on the same device model.
Two other current refusals, both clean and both consistent with the
docs: sparse extents are refused at descriptor resolution ("extent 0
has kind Sparse; only FLAT extents are supported"), and instar map
refuses every flat source ("monolithicFlat source images are not yet
supported"). instar info walks a 20-extent flat descriptor fine and
lists /extents.0 through /extents.19, because info resolves the
descriptor on the host and never opens the extents as devices.
What the code does today¶
Source citations are to 24b629cb. Each phase re-reads the lines it
depends on, because unrelated merges move them.
The device model is already N-device capable at the virtio layer.
DeviceSet (src/vmm/src/main.rs:717) holds a Vec<ManagedDevice>,
each with an is_input flag (:690-697), assigns sequential MMIO
bases, and dispatches MMIO by address (:772-790). What is capped is
the total: MAX_CHAIN_DEPTH = 16 (:412), and add_device panics
past it (:736-750). Operations guard with an explicit error first --
:15088 is the convert guard that produced the message above -- so the
panic is not reachable through the CLI today. That guard is the
ceiling, and it counts inputs and the output together.
The call table is asymmetric. Input devices are indexed:
pub get_input_device_count: unsafe extern "C" fn() -> u32,
pub read_input_sector: unsafe extern "C" fn(u32, u64, *mut u8, usize) -> bool,
pub get_input_capacity: unsafe extern "C" fn(u32) -> u64,
pub get_input_sector_size: unsafe extern "C" fn(u32) -> usize,
(src/shared/src/lib.rs:1060-1078.) Output devices are not:
// Output device functions (single device)
pub write_output_sector: unsafe extern "C" fn(u64, *const u8, usize) -> bool,
pub get_output_capacity: unsafe extern "C" fn() -> u64,
pub get_output_sector_size: unsafe extern "C" fn() -> usize,
(:1083-1092), with read_output_sector (:1227-1234) appended later
for resize. The table is append-only by convention: several entries
carry the comment "Appended at the end of CallTable so existing
operation binaries do not need to recompile against shifted offsets to
keep working". Anything this plan adds goes at the end.
In the guest core, inputs are an array and the output is a single
cell: INPUT_DEVICES: [Option<VirtioBlock>; MAX_INPUT_DEVICES]
(src/core/src/main.rs:129-130, MAX_INPUT_DEVICES = 16 at :49)
against OUTPUT_DEVICE: SingleThreadCell<Option<VirtioBlock>>
(:135). Device init (:176-233) fills inputs from index 0, then
places the output at index active_count -- so the output's device
index already varies with chain depth -- and bounds-checks it against
MAX_INPUT_DEVICES (:211-216).
The host tells the guest about devices over serial, by name:
read_config (src/core/src/serial.rs:130-170) matches "input",
then "input1" through "input15" via parse_device_index, then
"output". Extending that to "output1".."outputN" needs no protobuf
schema change, only new device names and a wider DeviceConfig
(:72-95).
The .bss hazard. OUTPUT_DEVICE and INPUT_DEVICES are exactly
the statics that have twice forced the guest memory map to move.
OPERATION_LOAD_ADDR (src/shared/src/lib.rs:632) documents it: core's
.bss once overflowed 0x20000 and device init wrote a VirtioBlock
over the loaded operation's code at 0x20380-0x203c7, corrupting amend's
header cross-check; the flat-binary size check missed it because the
flat image excludes .bss. The address was raised to 0x22000, then to
0x30000, and scripts/check-binary-sizes.sh now measures the
.bss-inclusive ELF extent with an 85% warning threshold. Measured
today, core sits at 68 KiB of its 128 KiB budget (53%). Turning
OUTPUT_DEVICE into a 16-slot array would add roughly a second copy of
the INPUT_DEVICES region to that figure. Open question 1 turns on
this as much as on the ceiling.
Finally, the surfaces that refuse these subformats today, all of which
this plan changes or deliberately leaves: create rejects
subformat=twoGbMaxExtent* (docs/create.md:144), resize rejects
every multi-extent subformat (docs/resize.md:263-264),
format-internals.md:89 records sparse multi-extent as "detected and
rejected gracefully", and docs/check.md:58 claims check validates
multi-extent twoGbMaxExtentFlat while issue #822 says check refuses
monolithicFlat outright.
Mission and problem statement¶
Give instar a device model that can write -- and read -- a VMDK split
across an arbitrary number of extent files, and use it to emit
twoGbMaxExtentSparse and twoGbMaxExtentFlat the way qemu-img does,
at any virtual size qemu-img supports.
The goals graph calls the prerequisite "multi-output-device call
table", and the measurement above is the reason this plan does not
simply build that. Extents are capped at 2 GiB each and the device
model is capped at 16 slots, so simultaneous output devices reach
about 30 GiB and stop. qemu-img does not stop there. A design that
opens every extent at once moves instar's ceiling by one device and
leaves a parity gap that grows with image size; it would also roughly
double the virtio statics in core's .bss, the one region of the guest
memory map with a history of silently corrupting loaded operations.
Open question 1, resolved on 2026-11-16, takes sequential extent
rotation instead, which bounds the device count at one regardless of
extent count and fixes the read-side ceiling with the same mechanism.
In scope:
- A device-rotation mechanism in the call table, core and VMM, letting a guest operation write (and read) a sequence of extent files through a bounded number of device slots.
- Lifting the read-side ceiling:
twoGbMaxExtent*sources with more than 15 extents, andtwoGbMaxExtentSparsesources at all. instar create -f vmdk -o subformat=twoGbMaxExtentFlat(and--subformat), host-only, matching qemu's extent naming, descriptor and per-extent sizing.instar create -f vmdk -o subformat=twoGbMaxExtentSparse, through the guest, with a streaming per-extent grain directory and grain tables in the same shapePLAN-bat-population.mdestablished for the VHDX BAT: compute each entry from its index, stream through one bounded buffer, never hold the table in memory.instar convert -O vmdk --subformat twoGbMaxExtentSparse|Flat.instar measure -O vmdk -o subformat=twoGbMaxExtent*.- A multi-extent descriptor emitter in the crates (
no_std, panic-free), shared by create and convert. checkover instar's own multi-extent output, and a decision on whatresizedoes with one.- Extent path derivation and its safety: N files written from one CLI argument is a new blast radius for a tool whose threat model assumes hostile images.
- A structural multi-extent comparator for the tests and the
differential fuzzer, since
qemu-img infoalone cannot tell a correct extent split from a wrong one.
Out of scope:
twoGbMaxExtent*as a backing file or in a backing chain. The chain machinery addresses images by device slot, and rotation changes what a slot means mid-operation; combining the two wants its own plan.- Real preallocation of the new subformats, for the reasons
PLAN-bat-population.mdopen question 1 gives: qemu-img leaves them sparse, so allocating would be an unflagged instar-only behaviour with no oracle.fallocandfullstay accepted no-ops andmetadatastays refused. - Retrofitting
ddb.*lines onto the existing VMDK subformats. Open question 3 keeps it out and says why. instar mapon flat sources. It refuses every flat source today, not just multi-extent ones, and that refusal is older and wider than this plan.- Fixing #822 (check refuses monolithicFlat while
docs/check.mdsays it validates it). This plan's check phase must not widen that inconsistency, but closing it belongs to the issue.
Open questions¶
Each question carries the planner's recommendation and its reasoning. The operator resolved questions 1 and 2 on 2026-11-16, before phase 1's plan was written, adopting both recommendations as drafted; each question records it. Questions 3 to 6 are still open, and phase 1's measurements settle much of 4 and 5.
- Simultaneous output devices, or sequential extent rotation? Recommendation: rotation. Four reasons, in order of weight.
Parity. Measured above: 16 slots total, 2 GiB per extent, so simultaneous devices support 15 extents against qemu's 20-and-up. Rotation bounds the device count at one and has no size ceiling of its own.
The access pattern already suits it. Conversion and creation walk
the virtual disk in ascending order, and extent k owns exactly
[k*2GiB, (k+1)*2GiB). Two data extents are never live at once. A
sparse extent's grain directory and grain tables live inside that
same extent, and the streaming emitter from
PLAN-bat-population.md finalises them without a second pass.
It fixes the read side. The shipping bug is the same ceiling. One mechanism, rotated over inputs as well as outputs, closes both; an indexed-output design closes neither.
Core .bss. Rotation keeps OUTPUT_DEVICE a single cell. A
16-slot output array adds roughly another INPUT_DEVICES to the
region that has twice forced OPERATION_LOAD_ADDR to move and once
silently corrupted a loaded operation.
The cost is honest and should be weighed: rotation adds control flow
to a boundary that currently has none. A new call-table entry
("finish the current output extent and bind the next") means the
host opens, closes and fsyncs files mid-operation, and a failure
between extents leaves a partially written image the guest cannot
see. Phase 8 owns that lifecycle and its cleanup.
Alternative, if the operator prefers the simpler change: indexed output devices capped at the slot budget, with sizes above the cap refused and the divergence documented. That is less code and no new control flow, and it would still close the goals-graph node as drawn, but instar would carry a size limit qemu does not.
Resolved 2026-11-16: rotation, as recommended. The alternative stays recorded here so a later reader knows it was weighed and why it lost, not to leave the decision open. Phase 8 owns the lifecycle cost this choice accepts.
- Does lifting the read-side ceiling belong in this plan? Recommendation: yes. It is the same mechanism and the same ceiling, it is a bug users can hit today on images instar otherwise supports, and the differential fuzzer cannot check what this plan writes unless instar can read a 20-extent image back. Doing it first (phase 3) also exercises rotation on the read path, where a mistake corrupts nothing, before the write path trusts it.
Against: it widens a plan that is already large, and the read fix has value on its own. If the operator wants it split, phase 3 is the clean seam -- it would become its own small plan that this one depends on.
Resolved 2026-11-16: in this plan, as phase 3, as recommended.
- Does multi-extent output emit qemu's
ddb.*lines? Recommendation: yes for the new subformats, and do not retrofit the existing ones here. The descriptor is small, text, and compared byte-for-byte against qemu's in the pin tests; omitting six lines qemu always writes would mean either a weaker oracle or a documented divergence on brand-new output, and the geometry values are computable from the virtual size. RetrofittingmonolithicSparse,streamOptimizedandmonolithicFlatwould change the bytes of every VMDK instar has ever written, churn every VMDK baseline, and deserves its own differential-fuzz exposure. Phase 4 files the retrofit as an issue and names it in Future work.
The cost of the recommendation: instar's VMDK descriptors become
inconsistent with each other until that retrofit lands -- new
subformats carry ddb.*, old ones do not. Phase 17 documents it
explicitly rather than leaving a reader to discover it.
- How are extent paths derived, and what is refused?
Recommendation: derive strictly from the output argument's own
stem and directory (
out.vmdk->out-s001.vmdk), never from any string in an input descriptor; refuse if any target already exists; refuse a stem that would collide with the descriptor itself; and write every extent before the descriptor, so a failure never leaves a descriptor pointing at files that do not exist. Phase 1 must measure what qemu-img actually does on each of those -- particularly pre-existing targets -- because matching it matters more than any rule invented here.
Measurement (phase 1, 80 qemu builds; not a resolution): a
pre-existing file where an extent goes is not refused, in either
split subformat. On all 80 builds qemu returns rc 0 with empty
stderr and writes the image exactly as it does without the
obstruction. A second hard link kept to the file reports the
extent's length, not the original 1 MiB, so qemu truncated it in
place rather than unlinking it and creating its own file --
shrinking it for a sparse extent and growing it for a flat one,
which is the same ftruncate in both directions. Any other hard link, and any open
descriptor, follows the image. What qemu does is not by itself
what instar should do: silently truncating a file the user did not
name is a different risk calculus for a tool whose threat model
assumes hostile input. The recommendation above stands
unresolved; the decision is the operator's.
- What is the maximum extent count, and what happens past it?
The
%03dnaming implies 999 extents, about 2 TiB. Recommendation: measure qemu's real ceiling in phase 1 and match it, refusing above it with a message that names the limit and the size that would reach it, before the output file is opened -- the shapePLAN-bat-population.mdused for VHDX's 64 TiB refusal, which leaves nothing behind where qemu-img leaves an empty file.
Measurement (phase 1; not a resolution): the premise above is
false. %03d is a minimum field width, not a cap. Probed on
6.0.0, 7.2.0, 8.2.0 and 10.2.0, both split subformats: at 2000 GiB
all four builds write 1000 extents, rc 0, empty stderr, and the
thousandth descriptor line is verbatim
RW 4194304 SPARSE "image-s1000.vmdk". At 32 TiB all four write
16384 extents. At 1 PiB 10.2.0 still does not refuse; a 60 s
timeout stopped it at extent 70168 of 524288. The only refusal
anywhere near is qemu-img's generic size parser, identical on
every build: qemu-img: Invalid image size specified. Must be
between 0 and 9223372036854775807. So there is no qemu ceiling
to match. The recommendation above was written before this
measurement and its "measure and match" reasoning no longer
applies as stated. Whether instar matches qemu or imposes a
documented limit of its own is the operator's decision, still
open.
- Is flat create host-only, like monolithicFlat?
Recommendation: yes, and it should land before the ABI work.
A flat multi-extent image is N sparse files of known length plus a
text descriptor -- no format emission, nothing the guest is needed
for.
PLAN-bat-population.mdalready established host-only monolithicFlat create. That makes phase 5 a cheap, user-visible delivery that does not depend on phases 6 to 8, and it de-risks the descriptor emitter and the path rules by exercising them first.
Execution¶
Push audit phase (shared block; do not edit -- the canonical
copy lives in shakenfist/development at
templates/shared-blocks/plan-push-audit-phase.md):
- Every master plan ends with a phase that runs the repository's
PUSH-AUDIT.mdover the whole plan's work. It is the last row of the Execution table and it is not optional. The rule binds every plan that carries the phase, which is decidable from the plan file alone: a plan that is alreadyComplete,AbandonedorSupersededand does not carry the phase is not reopened to acquire one, and a plan that has the phase runs it even if it reachesCompletebefore the phase does. - That phase audits the accumulated diff of every phase in the plan against the default branch, not the diff of the last phase alone. Auditing one phase at a time would miss what the phases did to each other -- the duplicated helper that only exists once phases three and six have both landed, the doc page that phase two made wrong and phase five never revisited.
- Once the plan's phases have merged, a diff against the default
branch is empty and would read as a clean audit. The range is not
reliably derivable after the fact either: unrelated work lands on
the default branch between phases, so anything anchored on "since
the plan file appeared" is far too wide. It has to be recorded. As
each phase lands, what put it on the default branch goes into the
plan: the merge commit of its pull request, whose diff against its
first parent is the whole of what landed, or -- where the phase
landed directly -- every commit of the phase, or its
first..lastrange. A single commit is only ever enough when it is a merge commit. - Where the Execution phases are a table, that record is a
Mergedcolumn, added last so that a row which omits it still reachesStatus; where they are prose sections it is aMerged:line in the phase's own section. TheStatuscolumn keeps its single vocabulary term and nothing else (seeplan-status-vocabulary). A phase that landed in another repository records<repo> <sha> (#pr)and is audited against that repository's default branch, as part of the pull request that lands it; the plan's own push-audit phase cites that audit rather than re-running it. - Phases that landed before the plan started recording them are
reconstructed rather than left blank. Recover what you can from
gh pr list --state mergedandgit rev-list --first-parent, and say in the plan that the range was reconstructed. Do not trust a path-filteredgit logon its own: it lists the commits that touched a path without saying which arrived directly and which arrived inside a pull request, and recording a commit that came in under a merge audits one commit of that pull request rather than the pull request. A reconstructed record may be a summary table in the audit phase's own section rather than a column or a line in the Execution table, which keeps retrospective archaeology out of a table that tracks live status. Where a phase accreted over months of unrelated commits and no range is recoverable, say that instead and name the paths the audit read -- an audit that says what it could not scope is a result; one that silently audits nothing is not. - Findings land as their own pull request against the default branch, and the plan is not complete until they are resolved or explicitly declined in writing. A finding that is declined says why, in the plan, where the next reader will find it.
- Where the audit finds nothing, record that in the plan in one sentence. It is a real result, and a run of them is the evidence for making the phase conditional rather than mandatory.
- A repository with no
PUSH-AUDIT.mdstill carries the phase, and the phase says that the runbook does not exist yet and what was done instead. Silently omitting it is what let the audit go untriggered for as long as it did. What is done instead is at least the checklist below, applied to the recorded ranges: it is a floor, not a substitute for a runbook, and a plan adds the questions its own repository's blast radius raises. Each item gets a verdict, or a sentence saying why it does not apply. Do not borrow another repository's runbook instead: a runbook is written for one repository's blast radius. - Every recorded landing takes one of the forms above: a merge
commit with two parents, whose diff is read against its first
parent; every commit of a direct landing, or its
first..lastrange; a landing in another repository, whose own audit is cited; or a statement that no range is recoverable, naming the paths the audit read. - Anything the diff added that runs unattended -- cron, a timer, a scheduled workflow, a self-update -- reports its own failure somewhere a human sees, or is named as not doing so.
- No secret or token entered any repository, and no private hostname or IP address entered a repository more public than the one it came from.
- Anything the diff removed or renamed has no consumer left, checked by grep across every repository that could consume it rather than by assumption, with the greps stated.
- Where the repository publishes something -- an image, a release, a package -- a broken change fails closed: one that publishes nothing is recoverable, one that publishes something wrong is not.
The phase order is chosen so that the cheap, user-visible delivery (phase 5, host-only flat create) lands before the ABI change, and so that rotation is proved on the read path (phase 3), where a mistake cannot corrupt an output, before the write path depends on it.
| Phase | Plan | Status | Merged |
|---|---|---|---|
| 1. Pin and measure qemu's output | PLAN-multi-extent-vmdk-phase-01-pin.md | Not started | |
| 2. Fixtures and baselines | PLAN-multi-extent-vmdk-phase-02-fixtures.md | Not started | |
| 3. Read side: lift the extent ceiling | PLAN-multi-extent-vmdk-phase-03-read-ceiling.md | Not started | |
| 4. Multi-extent descriptor emitter | PLAN-multi-extent-vmdk-phase-04-descriptor.md | Not started | |
| 5. Host-only flat create | PLAN-multi-extent-vmdk-phase-05-flat-create.md | Not started | |
| 6. ABI: output rotation | PLAN-multi-extent-vmdk-phase-06-abi.md | Not started | |
| 7. Core: rotation in the guest | PLAN-multi-extent-vmdk-phase-07-core.md | Not started | |
| 8. VMM: extent lifecycle and safety | PLAN-multi-extent-vmdk-phase-08-vmm.md | Not started | |
| 9. Streaming grain tables | PLAN-multi-extent-vmdk-phase-09-grain-tables.md | Not started | |
| 10. Sparse create | PLAN-multi-extent-vmdk-phase-10-sparse-create.md | Not started | |
| 11. convert -O vmdk multi-extent | PLAN-multi-extent-vmdk-phase-11-convert.md | Not started | |
| 12. measure | PLAN-multi-extent-vmdk-phase-12-measure.md | Not started | |
| 13. check and resize | PLAN-multi-extent-vmdk-phase-13-check-resize.md | Not started | |
| 14. Baselines across the version matrix | PLAN-multi-extent-vmdk-phase-14-baselines.md | Not started | |
| 15. Integration tests | PLAN-multi-extent-vmdk-phase-15-integration.md | Not started | |
| 16. Fuzzing | PLAN-multi-extent-vmdk-phase-16-fuzz.md | Not started | |
| 17. Documentation | PLAN-multi-extent-vmdk-phase-17-docs.md | Not started | |
| 18. Push audit | - | Not started |
Phase intents¶
Each phase gets its own plan file before it is implemented; these are the one-paragraph intents the phase plans expand.
1. Pin and measure qemu's output. Establish the oracle before
writing anything. Phase 1's survey corrected this section: the
cross-version sweep already exists, built by
PLAN-bat-population-phase-01-pin.md -- tools/sweep-qemu-create.py,
tests/helpers/qemu_pins.py, tests/golden/qemu-create-pins.json and
tests/test_qemu_create_pins.py, over the 80 static builds in
instar-testdata/qemu-img-binaries/x86_64/<version>/qemu-img -- and
this phase extends it rather than starting one. It also adds the VMDK
structural parser that phases 10, 11 and 16 depend on, and makes the
pinned descriptor able to prove an extent naming scheme and ordering,
which it cannot today. Measure, per version: descriptor bytes for both
subformats; extent naming; per-extent sector counts for sizes that are
and are not multiples of 2 GiB; the ddb.* values and how geometry is
derived; the maximum extent count and the refusal past it; behaviour
when a target extent already exists; and whether any of this moved
between versions. Record every answer as a measurement with the version
that produced it. Nothing in later phases may assert a qemu-img
behaviour this phase did not measure -- sub-agents have asserted
plausible-but-wrong qemu-img capabilities repeatedly in this
repository, and the preallocation leaf in PLAN-bat-population.md
turned on exactly this kind of check.
2. Fixtures and baselines. Add twoGbMaxExtent{Sparse,Flat}
fixtures to instar-testdata with their manifest entries, including at
least one image past the current 15-extent ceiling so phase 3 has
something to prove itself against, and one whose last extent is
partial. Remember that repository takes direct commits to main, never
a merge request, and that it is git-LFS backed. Generate baselines with
--no-commit and validate the derived profile directories rather than
trusting them; they have twice been silently wrong while the raw
baselines were fine.
3. Read side: lift the extent ceiling. Implement rotation on the
input path and remove the 15-extent limit for multi-extent sources, and
add twoGbMaxExtentSparse as a readable input. This is where rotation
is designed and proved; a mistake here fails a read, not an image.
Includes the guard at src/vmm/src/main.rs:15088 and its siblings, and
DeviceSet::add_device's panic, which should become unreachable by
construction rather than by a caller remembering to check.
4. Multi-extent descriptor emitter. One no_std, panic-free
emitter in the crates that writes a multi-extent descriptor from a
geometry, used by both create and convert, carrying the ddb.*
decision from open question 3. Files the retrofit issue for the
existing subformats.
5. Host-only flat create. create -f vmdk -o
subformat=twoGbMaxExtentFlat, written entirely on the host: N sparse
extent files of the measured lengths plus the descriptor. No ABI
change, no guest involvement. Carries the path-derivation rules from
open question 4 and the extent-count refusal from question 5.
6. ABI: output rotation. The call-table change, appended at the end
of CallTable for the back-compat reason the existing entries
document, plus the serial DeviceConfig extension. Re-measure core's
.bss-inclusive extent with scripts/check-binary-sizes.sh as part of
the phase's definition of done, not afterwards.
7. Core: rotation in the guest. The guest side of rotation in
src/core/src/main.rs and serial.rs: binding, rebinding, bounds, and
what an operation sees when rotation fails. Guest operations are
no_std and panic-free; a failed rotation is an error code, never a
fault.
8. VMM: extent lifecycle and safety. The host side: opening,
fsyncing and closing extents as the guest advances, the path rules,
refusing pre-existing targets, and cleanup when an operation fails
part-way so a failure never leaves a descriptor pointing at a
half-written set. This phase owns the blast radius that open question 1
names as rotation's cost.
9. Streaming grain tables. The per-extent grain directory and grain
table emitter, in the shape PLAN-bat-population.md established for
the VHDX BAT: computed per index, streamed through one bounded buffer,
never held in memory. The cluster-size and geometry matrix matters
here -- a fixed staging buffer that only ever saw one geometry is
exactly the defect the bitmap plan's phase 7 found.
10. Sparse create. create -f vmdk -o
subformat=twoGbMaxExtentSparse through the guest, on phases 6 to 9.
11. convert -O vmdk multi-extent. Both subformats as convert targets.
12. measure. measure -O vmdk -o subformat=twoGbMaxExtent*,
against the phase 1 baselines. Note that 81 safe fixtures have no
measure baselines at any version (#845); new fixtures must not quietly
join them.
13. check and resize. check over instar's own multi-extent
output, and a decision on resize: today it refuses every multi-extent
subformat, and the honest options are to keep refusing with a better
message or to support growing by appending extents. Must not widen
822's docs/behaviour mismatch.¶
14. Baselines across the version matrix. Generate and validate
baselines for every new case across the pinned qemu versions, and check
the distro matrix: RHEL's qemu-kvm omits several drivers, so a
capability is not a version.
15. Integration tests. Python integration coverage for every new surface, including the structural comparator. Watch for the subunit attachment trap: an attachment over 4 MiB kills a stestr worker and the run still exits 0, so check "Ran: N" rather than trusting a green exit.
16. Fuzzing. Coverage targets for the emitter and the descriptor
parser, and differential-fuzz arms for both subformats with a
structural comparator -- qemu-img info cannot tell a correct extent
split from a wrong one, the same reason phase 11 of
PLAN-bat-population.md needed a VHDX structural comparator. Make sure
the new options are actually drawn: an option the picker never draws is
not coverage.
17. Documentation. docs/create.md, docs/convert.md,
docs/measure.md, docs/resize.md, docs/check.md,
docs/format-internals.md, docs/vmdk/vmdk-format.md, the CHANGELOG,
and ARCHITECTURE.md -- the last only because rotation changes the
shape of the device model, which is exactly what that file is for.
Documents the ddb.* inconsistency from open question 3 explicitly.
18. Push audit. Per the shared block above.
Agent guidance¶
Execution model¶
Sub-agent execution model (shared block; do not edit -- the
canonical copy lives in shakenfist/development at
templates/shared-blocks/subagent-execution-model.md):
All implementation work is done by sub-agents, never in the management session. The management session is reserved for planning, review, and decision-making. This keeps the management context lean and avoids drowning it in implementation diffs.
The workflow is:
- Plan at high effort in the management session.
- Spawn a sub-agent for each implementation step with the brief from the plan, at the recommended effort level and model.
- Review the sub-agent's output in the management session. Check the actual files -- the sub-agent's summary describes what it intended, not necessarily what it did.
- Fix or retry if the output is wrong. Diagnose whether the brief was insufficient (improve it) or the model was too light (upgrade it), then re-run.
- Commit once the management session is satisfied.
This applies to all steps, including high-effort ones. If a sub-agent cannot succeed even with a detailed brief and the right model, that is a signal the brief needs improving, not that the management session should do the implementation itself.
Use isolation: "worktree" for sub-agents when the change is
risky or experimental; the worktree is discarded if the output is
unsatisfactory. For safe, well-understood changes, sub-agents can
work directly in the main tree.
Planning effort¶
The ABI and rotation phases (3, 6, 7, 8) turn on design decisions at
the guest/host boundary and are planned at high effort. Phase 1 is
high effort because everything downstream rests on its measurements.
Phases 5, 10, 11 and 12 follow patterns already established by
PLAN-bat-population.md and PLAN-create.md and can be planned at
medium. Phases 14, 15 and 17 are mechanical.
Verification that is not optional¶
- Cite or measure. No phase asserts a qemu-img behaviour without either a measurement in this plan or a citation to qemu source. The management session re-runs a sample of any sub-agent's measurements.
- Never trust a single green run. The integration suite is
zero-fail on healthy testdata, but a
test_convertcluster on this host reporting "Content mismatch at offset 0" or "convert operation failed" is 16-worker contention, not a regression; replay at low concurrency with--selectbefore attributing it. - Run the consumer suites. A change to a crate can alter non-gated behaviour in the operations that link it; crate tests alone are not enough.
- Re-measure the binary sizes. Phases 6 and 7 change core's
.bss.scripts/check-binary-sizes.shis part of their definition of done. - Mutation-check the guards. Where a phase adds a test that is meant to prove a refusal or a bound, prove the test would notice its absence.
Administration and logistics¶
Success criteria¶
instar create -f vmdk -o subformat=twoGbMaxExtentSparseand...=twoGbMaxExtentFlatproduce images byte-identical to qemu-img's for every measured geometry, or divergent only where a divergence is documented and justified.instar convert -O vmdk --subformat twoGbMaxExtent*likewise.instar measurereports what qemu-img reports for both subformats.- instar reads a
twoGbMaxExtent*image with more than 15 extents, and readstwoGbMaxExtentSparsesources at all. - The size at which instar refuses a multi-extent image matches qemu-img's, and the refusal leaves nothing behind.
- A failure part-way through writing a multi-extent image never leaves a descriptor pointing at a set of extents that does not match it.
- The differential fuzzer compares multi-extent output structurally,
not just through
qemu-img info, and the new options are drawn. make testand the integration suite are zero-fail, with "Ran: N" checked rather than the exit code trusted.
Documentation index maintenance¶
This plan is registered in docs/plans/index.md and docs/plans/order.yml
when it is created, and its status there is kept in step with the
Status line above.
Future work¶
Filled in as the plan runs. Already known:
- Retrofitting
ddb.*ontomonolithicSparse,streamOptimizedandmonolithicFlatdescriptors (open question 3), which churns every existing VMDK baseline and wants its own differential-fuzz exposure. twoGbMaxExtent*as a backing file or in a backing chain, excluded from scope above.instar mapon flat sources, which is refused today for all flat sources and is wider than this plan.- Making
tests/helpers/vmdk_structure.pycheck an image against itself, rather than only against another image. It never compares an extent line's declared sector count with the sparse header's capacity or with a flat extent's file length, so an image whose descriptor and extents disagree parses cleanly and is caught only if the image it is compared against happens to be right. Raised in review on #921 and left to the phases that use the parser as an oracle (10, 11 and 16), because what counts as internally consistent is a property of the writer those phases build, and a refusal added now would be guessing at it. The same entry covers two neighbours raised in the same review: a start offset is carried through on any extent kind although onlyFLATlines are supposed to have one, and aZEROextent that carries a filename is opened and measured as though it held data. No writer produces either, so each is a rule about malformed input rather than a defect against anything that exists.
Bugs fixed during this work¶
Filled in as the plan runs. The read-side ceiling measured in the Situation needs an issue filed before phase 3 starts, so that the fix has something to close.
Back brief¶
Before implementation begins, the implementing session restates this plan's mission, the resolved open questions, and the phase it is starting, in its own words, and the operator confirms. Questions 1 and 2, which change the shape of the whole plan, were resolved on 2026-11-16; questions 3 to 6 remain open, and phase 1's plan file names which of them its measurements settle.