phg/iodd-tool
0
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Packages Wiki Activity Actions

Define fixed VHD creation and allocation failure behavior #3

New issue
Closed
opened 2026-10-11 19:10:03 +00:00 by phg · 3 comments
phg commented 2026-10-11 19:10:03 +00:00
Owner
Copy link

Parent

IODD Tool specification

Context

The confirmed scope is a native Swift app for macOS 15+ on Apple Silicon, all external FAT32/exFAT disks including fixed media, and IODD mini/newer image-capable devices. Fixed VHD creation requires a valid container and verified complete-file contiguous allocation. Current work is planning and ticket publication only; implementation is a later effort. The public volume-operation API against disposable images is the confirmed main testing boundary.

Type: grilling
Mode: HITL

Question

What should a user-sized fixed VHD creation operation accept, produce, and report, including enough total space but no sufficiently large free run?

Decide virtual capacity versus host file size in the UI, decimal/binary units, alignment/rounding, filesystem/device limits, filename/destination, overwrite behavior, zero-filled/uninitialized versus partitioned/formatted guest contents, and footer validation. Require contiguous host allocation for the complete VHD and an independent final extent check.

Choose failure behavior when a VHD fits total free space but not the largest free run: refuse with a useful explanation, offer a separately previewed compaction operation, or another evidence-backed workflow. Decide whether existing data may ever be moved as part of Create, and what explicit user intent is required. Define estimates, progress/cancellation, partial-file publication/cleanup, retry, recovery, and final remount/verification outcomes using the chosen transaction contract.

Resolve with the user using concrete size/allocation examples. A structurally valid but internally unpartitioned VHD is distinct from an image containing a ready-to-use guest filesystem.

Blocked by

Record ownership

This Forgejo issue governs the live implementation prerequisite. The original local planning question and its history are retained; the implementation publication index links both records. This HITL decision remains open until the user resolves it. Publication does not resolve the original decision or approve production disk writes.

## Parent [IODD Tool specification](https://git.s1q.dev/phg/iodd-tool/issues/7) ## Context The confirmed scope is a native Swift app for macOS 15+ on Apple Silicon, all external FAT32/exFAT disks including fixed media, and IODD mini/newer image-capable devices. Fixed VHD creation requires a valid container and verified complete-file contiguous allocation. Current work is planning and ticket publication only; implementation is a later effort. The public volume-operation API against disposable images is the confirmed main testing boundary. Type: grilling Mode: HITL ## Question What should a user-sized fixed VHD creation operation accept, produce, and report, including enough total space but no sufficiently large free run? Decide virtual capacity versus host file size in the UI, decimal/binary units, alignment/rounding, filesystem/device limits, filename/destination, overwrite behavior, zero-filled/uninitialized versus partitioned/formatted guest contents, and footer validation. Require contiguous host allocation for the complete VHD and an independent final extent check. Choose failure behavior when a VHD fits total free space but not the largest free run: refuse with a useful explanation, offer a separately previewed compaction operation, or another evidence-backed workflow. Decide whether existing data may ever be moved as part of Create, and what explicit user intent is required. Define estimates, progress/cancellation, partial-file publication/cleanup, retry, recovery, and final remount/verification outcomes using the chosen transaction contract. Resolve with the user using concrete size/allocation examples. A structurally valid but internally unpartitioned VHD is distinct from an image containing a ready-to-use guest filesystem. ## Blocked by - [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2) ## Record ownership This Forgejo issue governs the live implementation prerequisite. The original local planning question and its history are retained; the implementation publication index links both records. This HITL decision remains open until the user resolves it. Publication does not resolve the original decision or approve production disk writes.
phg self-assigned this 2026-10-12 11:11:30 +00:00
phg commented 2026-10-12 11:36:44 +00:00
Author
Owner
Copy link

Interview checkpoint — capacity entry, guest contents, free-run failure, and destination

phg agreed to all four recommendations in the first interview round on 12 October 2026:

  • Capacity entry uses explicitly binary MiB/GiB units and permits exact fractional values. Reject capacities that are not an integral multiple of 512 bytes, with a suggested correction requiring user acceptance. Do not silently round or change the requested capacity. Show virtual capacity, complete host file length including the 512-byte footer, and cluster-rounded allocation separately.
  • Create a fully zero-filled, unpartitioned guest disk with a valid fixed VHD footer, and verify all guest bytes. Explain that the disk still requires initialization through its attached virtual disk. Guest partitioning/formatting is outside this creation feature.
  • When enough total free space exists but no adequate free run exists, refuse creation with required allocation and available largest-run sizes. Offer a separate compaction preview, then require fresh analysis/preview and a creation retry if sufficient space becomes available. Create never moves existing files; compaction does not promise that a sufficient run will result. Example: 100 GiB total free, 40 GiB largest run, and a requested 64 GiB virtual capacity cannot currently satisfy creation.
  • The user chooses a folder on the selected host volume and a filename ending in .vhd. Creation never replaces an existing file. A collision requires another name or explicit removal outside Create.

These are agreed interview choices, not the final resolution. Capacity bounds/defaults, estimates/progress, detailed allocation examples, outcome/retry presentation, and the final shared-understanding check remain. The engine/recovery prerequisite continues to govern publication, commit, cleanup, and interruption. Planning-only scope is unchanged.

## Interview checkpoint — capacity entry, guest contents, free-run failure, and destination phg agreed to all four recommendations in the first interview round on 12 October 2026: - Capacity entry uses explicitly binary MiB/GiB units and permits exact fractional values. Reject capacities that are not an integral multiple of 512 bytes, with a suggested correction requiring user acceptance. Do not silently round or change the requested capacity. Show virtual capacity, complete host file length including the 512-byte footer, and cluster-rounded allocation separately. - Create a fully zero-filled, unpartitioned guest disk with a valid fixed VHD footer, and verify all guest bytes. Explain that the disk still requires initialization through its attached virtual disk. Guest partitioning/formatting is outside this creation feature. - When enough total free space exists but no adequate free run exists, refuse creation with required allocation and available largest-run sizes. Offer a separate compaction preview, then require fresh analysis/preview and a creation retry if sufficient space becomes available. Create never moves existing files; compaction does not promise that a sufficient run will result. Example: 100 GiB total free, 40 GiB largest run, and a requested 64 GiB virtual capacity cannot currently satisfy creation. - The user chooses a folder on the selected host volume and a filename ending in .vhd. Creation never replaces an existing file. A collision requires another name or explicit removal outside Create. These are agreed interview choices, not the final resolution. Capacity bounds/defaults, estimates/progress, detailed allocation examples, outcome/retry presentation, and the final shared-understanding check remain. The engine/recovery prerequisite continues to govern publication, commit, cleanup, and interruption. Planning-only scope is unchanged.
phg commented 2026-10-12 12:00:39 +00:00
Author
Owner
Copy link

Interview checkpoint — capacity bounds, progress, and interrupted creation

phg agreed to all three recommendations in the second interview round on 12 October 2026:

  • Default virtual capacity is 1 GiB. The product minimum is 16 MiB and the interoperability ceiling is 2040 GiB; apply lower host-filesystem or established device limits. The minimum is a product policy, and this range is not a proven IODD capacity envelope. FAT32 cannot store an exactly 4 GiB virtual-capacity fixed VHD; its maximum 512-byte-aligned capacity under the file-length limit is 4 GiB minus 1 KiB. Available space is a separate preflight condition.
  • Progress uses Preparing, Writing zeros, Verifying, Publishing, and Final checks. Report processed bytes during writing and verification; estimate remaining time only after measuring throughput. A 32 GiB virtual disk entails approximately 32 GiB written and 32 GiB read back, plus footer/metadata work. Cancellation cleanup displays Stopping safely. Report completion only after verification and commit.
  • Do not retain a resumable partial image. Before commit, cancellation rolls back publication/allocation; after commit, preserve the verified VHD and complete cleanup. Failed cleanup requires recovery before another mutation. Retry uses a fresh analysis and preview. Report remount failure separately from the durable VHD result. Completion identifies the file and accepted capacity, confirms format and complete-file contiguity, and explains that the guest disk still needs initialization.

All seven interview choices are agreed. The final shared-understanding check remains pending, including the footer-crossing example and metadata/workspace budget inherited from the engine contract. This checkpoint does not close the ticket or authorize implementation or physical-media writes.

## Interview checkpoint — capacity bounds, progress, and interrupted creation phg agreed to all three recommendations in the second interview round on 12 October 2026: - Default virtual capacity is 1 GiB. The product minimum is 16 MiB and the interoperability ceiling is 2040 GiB; apply lower host-filesystem or established device limits. The minimum is a product policy, and this range is not a proven IODD capacity envelope. FAT32 cannot store an exactly 4 GiB virtual-capacity fixed VHD; its maximum 512-byte-aligned capacity under the file-length limit is 4 GiB minus 1 KiB. Available space is a separate preflight condition. - Progress uses Preparing, Writing zeros, Verifying, Publishing, and Final checks. Report processed bytes during writing and verification; estimate remaining time only after measuring throughput. A 32 GiB virtual disk entails approximately 32 GiB written and 32 GiB read back, plus footer/metadata work. Cancellation cleanup displays Stopping safely. Report completion only after verification and commit. - Do not retain a resumable partial image. Before commit, cancellation rolls back publication/allocation; after commit, preserve the verified VHD and complete cleanup. Failed cleanup requires recovery before another mutation. Retry uses a fresh analysis and preview. Report remount failure separately from the durable VHD result. Completion identifies the file and accepted capacity, confirms format and complete-file contiguity, and explains that the guest disk still needs initialization. All seven interview choices are agreed. The final shared-understanding check remains pending, including the footer-crossing example and metadata/workspace budget inherited from the engine contract. This checkpoint does not close the ticket or authorize implementation or physical-media writes.
phg commented 2026-10-12 12:15:44 +00:00
Author
Owner
Copy link

Resolution — fixed VHD creation and allocation failure behavior

Confirmed by phg on 12 October 2026 through seven agreed interview choices and the final shared-understanding check. This hosted resolution is the authoritative creation contract; maps and retained local records link here rather than duplicating it.

Current scope remains planning and specification only. The later implementation follows the supported envelope in Set the supported volume and device contract and the ownership, journal, commit, recovery, and remount contract in Choose the filesystem engine and recoverable mutation contract.

Capacity entry and limits

  • The requested value is virtual capacity, excluding the footer. Offer explicitly binary MiB and GiB: 1 MiB = 1,048,576 bytes and 1 GiB = 1,073,741,824 bytes. Accept fractional values only when their exact value converts to an integral multiple of 512 bytes; use exact decimal/integer arithmetic rather than floating-point rounding. Reject invalid, nonpositive, overflowing, below-minimum, above-limit, or nonaligned requests before target mutation.
  • Do not silently adjust capacity for host clusters, CHS geometry, a default that does not fit, or current free space. For misalignment, show a valid suggested correction that requires explicit user acceptance and a renewed preview. Unit conversion must preserve the requested bytes.
  • Default virtual capacity is 1 GiB. The product minimum is 16 MiB. The selected interoperability ceiling is 2040 GiB = 2,190,433,320,960 bytes. The minimum is a product policy and the ceiling is an interoperability policy; neither is a proven universal IODD capacity limit. Apply lower host-filesystem, checked-addressability, or established model/firmware limits where relevant, and report the limiting reason. Unqualified IODD behavior remains explicitly unqualified, independently of otherwise eligible host-volume creation.
  • FAT32's maximum file length includes the footer. The greatest permitted 512-byte-aligned virtual capacity under that length rule is 4,294,966,272 bytes, or 4 GiB minus 1 KiB; its complete file length is 4,294,966,784 bytes. Exactly 4 GiB virtual capacity is rejected. exFAT does not remove the selected VHD interoperability ceiling or the other validated operation limits.
  • Distinguish the allowable capacity range from current allocation feasibility. A size within the range still requires sufficient total space, one sufficient free run, all metadata workspace, journal capacity, and a current eligible target.

Preview and allocation arithmetic

For accepted virtual capacity C and host cluster size K, use checked arithmetic:

L = C + 512                         # exact complete host file length
Q = ceil(L / K)                     # quotient/remainder, avoiding overflow
A = Q * K                          # cluster-rounded allocation
  • Show virtual capacity C, exact host file length L, cluster-rounded allocation A, total free space, the actual largest free run, and additional metadata/workspace requirements separately. Label their units clearly; exact byte values must be inspectable.
  • Reserve Q consecutive free clusters for the complete image, including the footer. Budget supported directory growth and other target metadata allocation separately; preserve an adequate image run when planning those allocations. The authoritative recovery journal is on the Mac's internal storage and has its own required-space check. Do not equate total free space or payload-only allocation with complete-file contiguity.
  • Bind the selected directory, collision checks, size, allocation and workspace plan to the fresh target snapshot and attachment generation. Revalidate under the engine's offline exclusive access before execution. A stale or materially changed plan requires fresh analysis and a new preview; do not silently substitute a different destination, smaller capacity, or prerequisite movement.

Concrete boundary examples agreed during the interview:

  • At K = 32 KiB, C = 1 GiB gives L = 1,073,742,336 bytes and Q = 32,769 clusters. A = 1,073,774,592 bytes, or 1 GiB plus 32 KiB. A run of exactly 1 GiB is too short because the footer needs another cluster. Directory growth and transaction workspace are additional, not included in A.
  • With 100 GiB total free and a largest free run of 40 GiB, a 64 GiB virtual-capacity VHD cannot currently be created contiguously, even though its total allocation would fit.
  • Exactly 4 GiB virtual capacity on FAT32 fails the file-length rule before allocation. The calculated aligned boundary above satisfies only that rule, not a promise of available allocation or IODD qualification.
  • 1.5 GiB is exact and sector aligned; 1.1 GiB is not an integral 512-byte capacity and must be rejected or explicitly corrected by the user.

Destination and guest contents

  • The user chooses an existing supported directory on the selected host volume and a filename ending in .vhd. Validate destination/name rules against that filesystem and its actual collision semantics. Do not introduce an app-mandated _ISO folder; model-specific browsing/path eligibility is a separate annotation and qualification concern.
  • Creation is create-only. Never replace, truncate, or delete an existing destination, and never silently pick a different filename. A collision requires the user to choose another name or explicitly remove the existing file outside Create. Recheck the destination immediately before publication.
  • Initialize every guest byte in [0, C) to zero. No unchecked quick-create mode, sparse substitute, or stale free-cluster contents can satisfy this contract. Stream complete readback and validate all guest bytes as part of verification.
  • The guest disk is unpartitioned and unformatted. Guest partitioning/formatting is outside this creation feature; creation does not promise an installed operating system or bootability. Explain that subsequent initialization targets the attached virtual disk, independently of the FAT32/exFAT host volume.

Fixed format and independent final verification

  • Write the standard new fixed VHD profile from Fixed VHD creation format and size contract: exactly C guest bytes followed immediately by a 512-byte footer at offset C, with no logical trailing padding, leading backup footer, dynamic header, or block allocation table.
  • Use the fixed type, cookie, required feature/version fields, full-width unused data offset, equal new-image original/current capacities, documented CHS calculation, valid checksum, fresh disk UUID, app-owned creator identity, creation timestamp, and required saved-state/reserved values. CHS calculation must not replace the accepted virtual capacity with a rounded geometry capacity.
  • Before linking the image into the directory, initialize and verify the complete image. After tentative publication and before commit, verify the live directory metadata, exact EOF, declared capacity, complete allocation ownership and single extent, including every footer-bearing cluster. A separate verifier reads fresh storage; it does not accept the writer's placement bookkeeping as proof.
  • Footer/container validity, complete guest-zero initialization, and complete-file contiguous allocation are separate required results. A reservation success, correct file length, valid checksum, or a contiguous payload with a separate footer extent cannot substitute for all three.
  • Implementation validation uses independently implemented footer/VHD readers and FAT32/exFAT allocation/content oracles through the agreed public volume-operation API. These checks do not prove firmware acceptance, hardware-reported capacity, or physical power-loss durability; those require later qualification.

Insufficient space and prerequisite compaction

  • Preflight distinguishes invalid capacity/format limits, insufficient total space or metadata/journal workspace, enough total space but no sufficient free run, destination collision, stale preview, and volume/access ineligibility. A failed preflight does not begin a creation transaction.
  • When the run is too small, refuse and explain the required complete allocation, current largest run, and total free space. Offer a separate compaction preview where that operation is eligible. The user explicitly requests and reviews compaction under its own preservation, backup-confirmation, progress and transaction policy; Create never moves existing files or bundles compaction into itself.
  • Compaction makes no advance promise of producing the required run. After it, obtain fresh analysis and a renewed creation preview; retry only when all prerequisites pass and the user requests Create again. A different capacity or destination is another explicit user choice.
  • The detailed compaction objective and work limits remain governed by Define analysis, defrag, and compaction success criteria.

Progress and time estimates

  • Present Preparing, Writing zeros, Verifying, Publishing, and Final checks. Report processed/total bytes for writing and full verification, and phase-specific status for metadata work. Keep the phase visible so a completed write pass is not mistaken for a completed operation.
  • Estimate remaining time only after measured throughput is available; update estimates as phases change and account for the remaining verification pass. Before measurements, show an unavailable estimate rather than an invented duration. A 32 GiB disk requires approximately 32 GiB written and 32 GiB read back, plus footer and metadata work; no fixed speed or completion-time promise is implied.
  • Stop displays Stopping safely while the worker reaches the permitted transaction boundary and verifies cleanup. Do not report completion merely because writing or a progress bar reaches its end. Final success follows all required checks, the durable commit and safe completion requirements inherited from the engine contract.

Publication, cancellation, recovery, and retry

  • Use the existing journalled creation transaction: establish recovery evidence and allocation ownership; initialize and verify the image before directory linking; verify tentative live publication; persist the commit decision; finish metadata accounting, final consistency verification and safe clean-state restoration. No resumable partial-image feature is included.
  • Before commit, Stop/UI disconnection rolls back tentative publication and releases only allocation owned by this creation. A conclusively verified rollback leaves no created VHD and restores the owned space. Do not retain an incomplete .vhd as a successful or resumable output.
  • After commit, preserve the verified VHD and finish cleanup even if Stop arrives. Report that the file was created, rather than implying cancellation removed committed output. An I/O, journal, persistence, ownership, verification, or cleanup failure halts the operation; an uncertain resulting state requires recovery and retained evidence.
  • Process/host interruption follows the engine's durable recovery direction: uncommitted creation rolls back; committed creation finishes forward. A crash during metadata publication can leave a tentative entry until recovery, and a foreign OS is not persistently quarantined. Do not promise universal partial-file invisibility after a crash or delete ambiguous allocation without validated evidence.
  • Device removal/replacement invalidates pending work. Reconnection does not automatically resume creation. Reestablish identity, preparation and exclusive access; perform explicit recovery when needed before another mutation. Retry requires fresh analysis and preview, not a stale plan or an unchecked partial image.

Completion and remount outcomes

  • A successful result identifies the chosen file and accepted virtual capacity, confirms fixed-format validity, zeroed uninitialized guest contents and complete-file contiguous allocation, and explains the next guest-initialization step. Keep format/allocation results, IODD qualification, guest initialization and bootability distinct.
  • Distinguish rejection before change, cancelled with verified rollback, committed verified output, failure with verified rollback, and recovery required. Retain the phase, cause and durable file outcome; failed cleanup cannot be presented as a volume ready for normal use.
  • Run the fresh final consistency/allocation checks required by the engine. Restore only the previously mounted volumes after safe verification and correct identity. Report remount failure separately from the durable file result: a verified created VHD can coexist with an unavailable Finder volume. Recovery-required storage remains offline while the live worker can enforce that state.

Remaining route and evidence

No new decision ticket is needed. Compaction policy belongs in Define analysis, defrag, and compaction success criteria; concrete creation/progress/recovery presentation belongs in Validate the native analysis and VHD creation workflows; exact validation/performance gates and implementation staging belong in Set validation gates and the implementation handoff. No production build or physical-media test is authorized here.

The retained format, IODD compatibility and engine/recovery research supply evidence, not universal firmware guarantees. The first two interview checkpoint comments retain the seven choices; phg then confirmed the combined contract, including the footer-crossing/workspace example, before this resolution was published. The glossary records uninitialized guest disk separately from container validity and contiguous host allocation.

## Resolution — fixed VHD creation and allocation failure behavior Confirmed by phg on 12 October 2026 through seven agreed interview choices and the final shared-understanding check. This hosted resolution is the authoritative creation contract; maps and retained local records link here rather than duplicating it. Current scope remains planning and specification only. The later implementation follows the supported envelope in [Set the supported volume and device contract](https://git.s1q.dev/phg/iodd-tool/issues/1) and the ownership, journal, commit, recovery, and remount contract in [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2). ### Capacity entry and limits - The requested value is virtual capacity, excluding the footer. Offer explicitly binary MiB and GiB: 1 MiB = 1,048,576 bytes and 1 GiB = 1,073,741,824 bytes. Accept fractional values only when their exact value converts to an integral multiple of 512 bytes; use exact decimal/integer arithmetic rather than floating-point rounding. Reject invalid, nonpositive, overflowing, below-minimum, above-limit, or nonaligned requests before target mutation. - Do not silently adjust capacity for host clusters, CHS geometry, a default that does not fit, or current free space. For misalignment, show a valid suggested correction that requires explicit user acceptance and a renewed preview. Unit conversion must preserve the requested bytes. - Default virtual capacity is 1 GiB. The product minimum is 16 MiB. The selected interoperability ceiling is 2040 GiB = 2,190,433,320,960 bytes. The minimum is a product policy and the ceiling is an interoperability policy; neither is a proven universal IODD capacity limit. Apply lower host-filesystem, checked-addressability, or established model/firmware limits where relevant, and report the limiting reason. Unqualified IODD behavior remains explicitly unqualified, independently of otherwise eligible host-volume creation. - FAT32's maximum file length includes the footer. The greatest permitted 512-byte-aligned virtual capacity under that length rule is 4,294,966,272 bytes, or 4 GiB minus 1 KiB; its complete file length is 4,294,966,784 bytes. Exactly 4 GiB virtual capacity is rejected. exFAT does not remove the selected VHD interoperability ceiling or the other validated operation limits. - Distinguish the allowable capacity range from current allocation feasibility. A size within the range still requires sufficient total space, one sufficient free run, all metadata workspace, journal capacity, and a current eligible target. ### Preview and allocation arithmetic For accepted virtual capacity C and host cluster size K, use checked arithmetic: ```text L = C + 512 # exact complete host file length Q = ceil(L / K) # quotient/remainder, avoiding overflow A = Q * K # cluster-rounded allocation ``` - Show virtual capacity C, exact host file length L, cluster-rounded allocation A, total free space, the actual largest free run, and additional metadata/workspace requirements separately. Label their units clearly; exact byte values must be inspectable. - Reserve Q consecutive free clusters for the complete image, including the footer. Budget supported directory growth and other target metadata allocation separately; preserve an adequate image run when planning those allocations. The authoritative recovery journal is on the Mac's internal storage and has its own required-space check. Do not equate total free space or payload-only allocation with complete-file contiguity. - Bind the selected directory, collision checks, size, allocation and workspace plan to the fresh target snapshot and attachment generation. Revalidate under the engine's offline exclusive access before execution. A stale or materially changed plan requires fresh analysis and a new preview; do not silently substitute a different destination, smaller capacity, or prerequisite movement. Concrete boundary examples agreed during the interview: - At K = 32 KiB, C = 1 GiB gives L = 1,073,742,336 bytes and Q = 32,769 clusters. A = 1,073,774,592 bytes, or 1 GiB plus 32 KiB. A run of exactly 1 GiB is too short because the footer needs another cluster. Directory growth and transaction workspace are additional, not included in A. - With 100 GiB total free and a largest free run of 40 GiB, a 64 GiB virtual-capacity VHD cannot currently be created contiguously, even though its total allocation would fit. - Exactly 4 GiB virtual capacity on FAT32 fails the file-length rule before allocation. The calculated aligned boundary above satisfies only that rule, not a promise of available allocation or IODD qualification. - 1.5 GiB is exact and sector aligned; 1.1 GiB is not an integral 512-byte capacity and must be rejected or explicitly corrected by the user. ### Destination and guest contents - The user chooses an existing supported directory on the selected host volume and a filename ending in .vhd. Validate destination/name rules against that filesystem and its actual collision semantics. Do not introduce an app-mandated _ISO folder; model-specific browsing/path eligibility is a separate annotation and qualification concern. - Creation is create-only. Never replace, truncate, or delete an existing destination, and never silently pick a different filename. A collision requires the user to choose another name or explicitly remove the existing file outside Create. Recheck the destination immediately before publication. - Initialize every guest byte in [0, C) to zero. No unchecked quick-create mode, sparse substitute, or stale free-cluster contents can satisfy this contract. Stream complete readback and validate all guest bytes as part of verification. - The guest disk is unpartitioned and unformatted. Guest partitioning/formatting is outside this creation feature; creation does not promise an installed operating system or bootability. Explain that subsequent initialization targets the attached virtual disk, independently of the FAT32/exFAT host volume. ### Fixed format and independent final verification - Write the standard new fixed VHD profile from [Fixed VHD creation format and size contract](https://git.s1q.dev/phg/iodd-tool/src/commit/a43b0f6ce3656874a76a0c1be52c152a66f68fd5/docs/research/fixed-vhd-format.md): exactly C guest bytes followed immediately by a 512-byte footer at offset C, with no logical trailing padding, leading backup footer, dynamic header, or block allocation table. - Use the fixed type, cookie, required feature/version fields, full-width unused data offset, equal new-image original/current capacities, documented CHS calculation, valid checksum, fresh disk UUID, app-owned creator identity, creation timestamp, and required saved-state/reserved values. CHS calculation must not replace the accepted virtual capacity with a rounded geometry capacity. - Before linking the image into the directory, initialize and verify the complete image. After tentative publication and before commit, verify the live directory metadata, exact EOF, declared capacity, complete allocation ownership and single extent, including every footer-bearing cluster. A separate verifier reads fresh storage; it does not accept the writer's placement bookkeeping as proof. - Footer/container validity, complete guest-zero initialization, and complete-file contiguous allocation are separate required results. A reservation success, correct file length, valid checksum, or a contiguous payload with a separate footer extent cannot substitute for all three. - Implementation validation uses independently implemented footer/VHD readers and FAT32/exFAT allocation/content oracles through the agreed public volume-operation API. These checks do not prove firmware acceptance, hardware-reported capacity, or physical power-loss durability; those require later qualification. ### Insufficient space and prerequisite compaction - Preflight distinguishes invalid capacity/format limits, insufficient total space or metadata/journal workspace, enough total space but no sufficient free run, destination collision, stale preview, and volume/access ineligibility. A failed preflight does not begin a creation transaction. - When the run is too small, refuse and explain the required complete allocation, current largest run, and total free space. Offer a separate compaction preview where that operation is eligible. The user explicitly requests and reviews compaction under its own preservation, backup-confirmation, progress and transaction policy; Create never moves existing files or bundles compaction into itself. - Compaction makes no advance promise of producing the required run. After it, obtain fresh analysis and a renewed creation preview; retry only when all prerequisites pass and the user requests Create again. A different capacity or destination is another explicit user choice. - The detailed compaction objective and work limits remain governed by [Define analysis, defrag, and compaction success criteria](https://git.s1q.dev/phg/iodd-tool/issues/4). ### Progress and time estimates - Present Preparing, Writing zeros, Verifying, Publishing, and Final checks. Report processed/total bytes for writing and full verification, and phase-specific status for metadata work. Keep the phase visible so a completed write pass is not mistaken for a completed operation. - Estimate remaining time only after measured throughput is available; update estimates as phases change and account for the remaining verification pass. Before measurements, show an unavailable estimate rather than an invented duration. A 32 GiB disk requires approximately 32 GiB written and 32 GiB read back, plus footer and metadata work; no fixed speed or completion-time promise is implied. - Stop displays Stopping safely while the worker reaches the permitted transaction boundary and verifies cleanup. Do not report completion merely because writing or a progress bar reaches its end. Final success follows all required checks, the durable commit and safe completion requirements inherited from the engine contract. ### Publication, cancellation, recovery, and retry - Use the existing journalled creation transaction: establish recovery evidence and allocation ownership; initialize and verify the image before directory linking; verify tentative live publication; persist the commit decision; finish metadata accounting, final consistency verification and safe clean-state restoration. No resumable partial-image feature is included. - Before commit, Stop/UI disconnection rolls back tentative publication and releases only allocation owned by this creation. A conclusively verified rollback leaves no created VHD and restores the owned space. Do not retain an incomplete .vhd as a successful or resumable output. - After commit, preserve the verified VHD and finish cleanup even if Stop arrives. Report that the file was created, rather than implying cancellation removed committed output. An I/O, journal, persistence, ownership, verification, or cleanup failure halts the operation; an uncertain resulting state requires recovery and retained evidence. - Process/host interruption follows the engine's durable recovery direction: uncommitted creation rolls back; committed creation finishes forward. A crash during metadata publication can leave a tentative entry until recovery, and a foreign OS is not persistently quarantined. Do not promise universal partial-file invisibility after a crash or delete ambiguous allocation without validated evidence. - Device removal/replacement invalidates pending work. Reconnection does not automatically resume creation. Reestablish identity, preparation and exclusive access; perform explicit recovery when needed before another mutation. Retry requires fresh analysis and preview, not a stale plan or an unchecked partial image. ### Completion and remount outcomes - A successful result identifies the chosen file and accepted virtual capacity, confirms fixed-format validity, zeroed uninitialized guest contents and complete-file contiguous allocation, and explains the next guest-initialization step. Keep format/allocation results, IODD qualification, guest initialization and bootability distinct. - Distinguish rejection before change, cancelled with verified rollback, committed verified output, failure with verified rollback, and recovery required. Retain the phase, cause and durable file outcome; failed cleanup cannot be presented as a volume ready for normal use. - Run the fresh final consistency/allocation checks required by the engine. Restore only the previously mounted volumes after safe verification and correct identity. Report remount failure separately from the durable file result: a verified created VHD can coexist with an unavailable Finder volume. Recovery-required storage remains offline while the live worker can enforce that state. ### Remaining route and evidence No new decision ticket is needed. Compaction policy belongs in [Define analysis, defrag, and compaction success criteria](https://git.s1q.dev/phg/iodd-tool/issues/4); concrete creation/progress/recovery presentation belongs in [Validate the native analysis and VHD creation workflows](https://git.s1q.dev/phg/iodd-tool/issues/5); exact validation/performance gates and implementation staging belong in [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6). No production build or physical-media test is authorized here. The retained format, IODD compatibility and engine/recovery research supply evidence, not universal firmware guarantees. The first two interview checkpoint comments retain the seven choices; phg then confirmed the combined contract, including the footer-crossing/workspace example, before this resolution was published. The glossary records uninitialized guest disk separately from container validity and contiguous host allocation.
phg closed this issue 2026-10-12 12:15:45 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
implement/iodd-tool-spec-7
prototype/native-workflow
research/engine-recovery-constraints
research/supported-volume-geometry
No results found.
Labels
Clear labels   
needs-info

   
needs-triage

   
ready-for-agent
Ready for an agent; explicit blockers and scope still apply

  
ready-for-human

   
wayfinder:grilling

   
wayfinder:map

   
wayfinder:prototype

   
wayfinder:research

   
wontfix
No labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
phg
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
phg/iodd-tool#3
No description provided.