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

IODD Tool specification #7

New issue
Closed
opened 2026-10-11 19:10:21 +00:00 by phg · 1 comment
phg commented 2026-10-11 19:10:21 +00:00
Owner
Copy link

IODD Tool specification

Status: complete — implementation-ready specification
Labels: ready-for-agent, wayfinder:map
Scope: planning and specification only
Updated: 13 October 2026

Destination

An implementation-ready specification for a native macOS Swift app, IODD Tool, that preserves the useful FAT Defrag GUI functionality and creates valid fixed-size VHD files with verified contiguous host allocation for IODD devices. The map is complete when product, filesystem, recovery, platform and validation decisions are settled; implementation is a later effort.

Notes

  • Interface presentation follows Apple’s macOS Human Interface Guidelines and the accepted operation contracts, as approved in Validate the native analysis and VHD creation workflows. Use native controls appropriate to the running macOS version while retaining the agreed macOS 15 minimum.
  • This issue is the hosted wayfinder map and specification index. The retained local map and original specification preserve their history; detailed answers live in the hosted decision tickets' resolution comments.
  • Planning and specification only. No production implementation, helper installation or physical-disk trials are authorized by this map or its ready-for-agent label.
  • Consult wayfinder, grilling and domain-modeling when working a decision; use research or prototype for their corresponding ticket types. Claim a child before work; HITL decisions require live user feedback. Use the configured Forgejo tracker conventions in docs/agents/issue-tracker.md.
  • The confirmed primary test boundary is the public volume-operation API against disposable FAT32/exFAT images, with independent output oracles and thin supplemental UI/device checks.
  • All wayfinder decisions are resolved. The remaining open implementation tickets belong to the later build effort; their existing dependency graph and the accepted handoff determine order.

Problem Statement

An IODD user needs to inspect and fix fragmentation on external storage from a native macOS application. The existing FAT Defrag GUI offers analysis, file defragmentation, and small-file compaction, but its non-native interface and documented allocation, display, cancellation, and recovery defects make a direct visual rewrite insufficient.

The user owns an IODD mini and wants support for that device and newer IODD devices. An ISO may satisfy documented IODD allocation requirements while still being fragmented; a VHD must be contiguous. Users need to understand this distinction and know whether a file actually satisfies the selected device's requirements.

The user also needs the relevant VHD Tool++ creation functionality on macOS: choose a size and create a valid fixed-size VHD in a single contiguous host allocation. Enough total free space does not establish that a sufficiently large free run exists. A blank reservation, a sparse image, a valid but fragmented VHD, or an image whose footer falls in another extent does not satisfy this request.

Solution

Specify IODD Tool, a native Swift application for macOS 15 and later on Apple Silicon. It discovers all external FAT32/exFAT host volumes, including devices reported as fixed media, and preserves the useful original Analyze, Defrag File, Defrag All, Compact, statistics, allocation map, selection, progress, and cancellation workflow.

Add fixed-size VHD creation with an explicit virtual capacity, file-format validation, and verification that the complete resulting host file occupies one extent. Present total free space, the largest free run, host-file overhead, and device eligibility as separate properties. Define correct failure and recovery behavior before enabling writes.

This document indexes the conversation, completed research and resolved decisions. The product, workflow, software-validation and distribution contracts are accepted, and the implementation handoff is complete. The user has authorized planning and specification only for this effort.

User Stories

  1. As a Mac user, I want a native Swift application on macOS 15+ and Apple Silicon, so that I can prepare my IODD storage using familiar macOS controls.
  2. As an IODD user, I want support for my IODD mini and newer image-capable models, so that I can use the utility with my current and future devices.
  3. As a user, I want external FAT32 and exFAT volumes listed, so that I can select compatible host storage.
  4. As a USB SSD user, I want external disks reported as fixed media included, so that device classification does not hide my storage.
  5. As a user, I want the device, volume label, filesystem, and capacity visible before selection, so that I can distinguish similar drives.
  6. As a user, I want refresh and device insertion/removal updates, so that the available targets reflect connected storage.
  7. As a user, I want each partition treated as a distinct host volume, so that I can operate on the intended partition.
  8. As a user, I want unsupported or read-only targets explained, so that I understand which operations are available.
  9. As a user, I want the active operation bound to the selected volume's current identity, so that replacement devices cannot receive stale work.
  10. As a user, I want target changes during an active operation handled coherently, so that displayed results always describe the volume being processed.
  11. As a user, I want Analyze to produce a consistent allocation snapshot, so that statistics, file rows, and the allocation map agree.
  12. As a user, I want total, used, and free capacity plus sector and cluster geometry, so that I understand my host volume.
  13. As a user, I want the largest free run shown separately from total free space, so that I can assess contiguous allocation capacity.
  14. As a user, I want fragmented-file counts and actual per-file extent counts, so that the app describes measured fragmentation accurately.
  15. As a user, I want file paths and logical sizes in a native table, so that I can identify the files that need attention.
  16. As a user, I want supported hidden files, nested paths, and Unicode names included, so that analysis does not silently omit relevant files.
  17. As a user, I want incomplete scans and allocation anomalies reported, so that an empty file list does not imply an unverified clean volume.
  18. As a user, I want an allocation map that represents the full volume, so that I can understand the distribution of allocated and free space.
  19. As a user, I want selecting a file to highlight its complete extent ranges, so that large files receive the same accurate coverage as small files.
  20. As a keyboard or assistive-technology user, I want accessible tables, controls, and a textual map summary, so that the workflow is usable without interpreting colored cells.
  21. As an IODD user, I want fragmentation distinguished from IODD eligibility, so that a permitted fragmented ISO is not confused with an unusable image.
  22. As an IODD user, I want the selected model and known firmware reflected in compatibility results, so that constraints are attributed to the right device.
  23. As an IODD user, I want ISO allocation assessed against the documented 24-piece allowance, so that I know when defragmentation is needed for allocation eligibility.
  24. As an IODD user, I want a VHD's complete host allocation checked for one extent, so that a fragmented footer cannot be overlooked.
  25. As an IODD user, I want fixed VHD format validity checked independently of allocation, so that a contiguous invalid image is not called usable.
  26. As an IODD user, I want unknown or untested compatibility conditions stated, so that a documented rule is not mistaken for hardware qualification.
  27. As an IODD user, I want image validity, guest initialization, and bootability distinguished, so that a newly created uninitialized VHD has an understandable result.
  28. As an IODD user, I want relevant path, browser, and virtual-drive preparation requirements explained, so that the device can find and attach the resulting image.
  29. As a user, I want Defrag File for a selected fragmented file, so that I can fix that file without processing an entire volume.
  30. As a user, I want Defrag All to process its declared eligible set, so that I can address multiple fragmented files in one operation.
  31. As a user, I want already contiguous and empty files handled explicitly, so that the app avoids unnecessary movement.
  32. As a user, I want operation previews showing intended work, required free runs, and skip reasons, so that I understand the requested changes.
  33. As a user, I want original file contents and relevant metadata preserved during movement, so that defragmentation does not alter my data.
  34. As a user, I want lack of sufficient contiguous destination space explained, so that I can choose a useful next action.
  35. As a user, I want small-file Compact functionality, so that I can consolidate free space as in the original GUI.
  36. As a user, I want Compact to state its objective and measured before/after outcome, so that completion does not imply an unachieved free-space improvement.
  37. As a user, I want compaction thresholds and work limits disclosed, so that partial packing is not presented as an unlimited optimization.
  38. As a user, I want consistent previews and backup confirmation for existing-file mutations, so that Compact receives the same deliberate treatment as Defrag.
  39. As a user, I want successful, skipped, failed, and recovery-required files identified individually, so that partial success is understandable.
  40. As a user, I want a fresh analysis after completed or safely cancelled work, so that the displayed state reflects actual allocation.
  41. As an IODD user, I want to create a fixed-size VHD at a destination I choose, so that I can prepare a virtual disk directly on the device's host volume.
  42. As an IODD user, I want to enter the desired virtual capacity using clearly identified units, so that the created disk has the size I intended.
  43. As an IODD user, I want any capacity adjustment disclosed before creation, so that alignment or geometry does not silently change my request.
  44. As an IODD user, I want virtual capacity, complete host file length, and cluster-rounded space consumption shown separately, so that footer and allocation overhead are visible.
  45. As an IODD user, I want capacity checked against host filesystem and qualified device limits, so that impossible requests fail before allocation begins.
  46. As an IODD user, I want creation to account for the full VHD including its footer, so that the required free run is calculated correctly.
  47. As an IODD user, I want a structurally valid fixed VHD rather than merely a blank reserved file, so that the result is a virtual disk image.
  48. As an IODD user, I want defined initial guest contents, so that the created image has a predictable initialization state.
  49. As an IODD user, I want existing destination files protected by an explicit overwrite policy, so that creating a VHD does not unexpectedly replace data.
  50. As an IODD user, I want creation success reported only after format and complete-file extent verification, so that a fragmented result is never silently accepted.
  51. As an IODD user, I want enough total space but insufficient contiguous space reported distinctly, so that I understand why a large VHD cannot currently be created.
  52. As an IODD user, I want any prerequisite compaction or existing-file movement presented explicitly, so that Create does not conceal changes to unrelated files.
  53. As an IODD user, I want failed or cancelled creation to have a defined partial-file and allocation outcome, so that incomplete images do not masquerade as successful results.
  54. As an IODD user, I want guidance for attaching the new image and initializing its guest disk, so that I can continue using it without confusing the guest disk with host storage.
  55. As a user, I want disk access authorization explained in the context of the selected operation, so that access approval has a clear purpose.
  56. As a user, I want a busy volume to report why it cannot be acquired, so that I can close the competing application and retry.
  57. As an IODD user, I want preparation guidance for detaching active hardware virtual drives, so that image movement is not attempted while the device is using those images.
  58. As a user, I want meaningful operation progress and current-file status, so that I can understand long-running work.
  59. As a user, I want Stop to reach a defined safe transaction boundary, so that cancellation preserves a recoverable volume.
  60. As a user, I want cancelled-before-change distinguished from partially completed work, so that I know what happened to my files.
  61. As a user, I want unplugging or reconnecting a device handled without further stale writes, so that changing hardware cannot redirect an operation.
  62. As a user, I want interrupted work discovered before another mutation begins, so that recovery evidence is not overwritten by a new task.
  63. As a user, I want an understandable recovery result, so that I know whether I can resume work or need additional help.
  64. As a user, I want recovery requirements to identify the correct volume and necessary local evidence, so that another similarly named device is not modified.
  65. As a user, I want remount failure reported separately from the file operation's result, so that I understand why the volume is still unavailable in Finder.
  66. As a user, I want durability limitations communicated accurately, so that successful host I/O is not presented as an untested power-loss guarantee.
  67. As a user, I want native About, menus, keyboard navigation, and system appearance, so that the app behaves like a macOS utility.
  68. As a maintainer, I want externally observable correctness tests using independent filesystem and VHD oracles, so that the writer is not its own sole correctness authority.
  69. As a maintainer, I want independent software correctness and fault validation using disposable images and virtual volumes, so that acceptance is reproducible without physical-device trials.
  70. As a maintainer, I want baseline/current-stable macOS software evidence and documented IODD profile constraints recorded separately from unmeasured hardware behavior, so that support claims match the evidence.
  71. As a user, I want the signed/notarized app available as a direct download and a Homebrew cask, so that I can choose my installation and update path.
  72. As a user, I want updates and uninstall to preserve recovery evidence and respect active operations, so that interrupted work remains recoverable.

Decisions so far

  • Set the supported volume and device contract: Full base-format geometry and validated layouts; read-only/partial diagnostics; separate volume-operation eligibility and IODD qualification. The authoritative answer is the ticket's resolution comment.

  • Choose the filesystem engine and recoverable mutation contract: Swift offline worker, device-wide isolation, internal journal, verified per-file commits, and conditional recovery. The authoritative answer is the ticket's resolution comment.

  • Define fixed VHD creation and allocation failure behavior: Exact binary capacity, verified zeroed guest disk, create-only destination, separate compaction, and recoverable creation outcomes. The authoritative answer is the ticket's resolution comment.

  • Define analysis, defrag, and compaction success criteria: Complete verified snapshots, separate profile annotations, largest-first Defrag All, and bounded compaction with measured free-run outcomes. The authoritative answer is the ticket's resolution comment.

  • Validate the native analysis and VHD creation workflows: User accepted the macOS HIG redesign and all five workflow presentation decisions. The authoritative answer and prototype evidence are in the ticket's resolution comment.

  • Set validation gates and the implementation handoff: Independent software/fault gates, virtual macOS integration, no hardware or performance gates, and a signed/notarized DMG plus Homebrew cask and staged handoff. The authoritative answer is the ticket's resolution comment.

  • Name the project IODD Tool: IODD Tool branding and iodd-tool repository identity, with historical evidence preserved.

  • Analyze a FAT32 image: Native image analysis and independent 32-geometry corpus implemented; full-Xcode integration tests/build pass on implement/iodd-tool-spec-7, merge 766c42c.

  • Inspect the complete allocation map: Full-volume exact map/selection/accessible ranges implemented and independently verified on FAT32 and exFAT;37 integrated tests and native keyboard/stale checks pass, final checked commit cd50bd8.

  • Analyze an exFAT image: All62 ordinary exFAT geometry pairs and complete allocation/entry-set/VDL analysis independently verified; native checker qualification remains explicit, integrated native table/map smoke passes.

  • Assess IODD image eligibility: Named documented profiles, ISO24-piece allowance and separate fixed-VHD complete-allocation/container checks implemented;49 integration tests, QEMU/oracles and native FAT32/exFAT selection/firmware/stale checks pass at 904dd22.

  • Preview fixed VHD creation: Exact binary capacity, footer-inclusive allocation, directory/collision semantics, conservative recovery workspace and stale/no-write preview implemented;61 integration tests and native unit/correction/collision checks pass, merge a133e4d.

  • FAT32 file defragmentation and shared recovery implemented: exact reviewed whole-file relocation, physical-unit-safe reservations, bounded checksummed journal/registry/retirement, idempotent logged rollback/forward recovery and conservative imported-evidence refusal. Final83tests/1018faultcases, all32geometries, native explicit-consent image workflow and independent content/untouched/fsck checks pass; integration950e500. Raw-device and signed-release gates remain later tickets.

  • Contiguous FAT32 VHD creation implemented: exact create-only reviewed full allocation, complete zero guest/fixed footer verification, logged spanning entries/directory growth, source-free rollback/forward recovery and physical-unit-safe reservations. Final105tests/all32geometries/1010creationfaultcases plus nativeCreate/Stop and independent footer/content/extent/QEMU/fsck checks pass; integration2b1dbcb. exFAT/nativeexternal/signedrelease gates remain separate.

  • Implementation #16: Defragment a file on an exFAT image is resolved on integration a4ec902. The shared journal now verifies complete exFAT allocation, bitmap/FAT/entry publication and bounded replay; final 124-test suite, all62 software geometry pairs, controlled faults, native image workflows and exact-source macOS15 probe pass. Native checker evidence retains21 passes/45 explicit driver refusals; raw access and release gates remain separate.

  • Implementation #14: Create a contiguous VHD on an exFAT image is resolved on integration fef4131. Full zero guest/footer/contiguous allocation, bitmap/entry publication, separate directory growth and bounded source-free recovery pass143tests/all62software geometry pairs/1008fault cases, native Create/Stop and exact-source pristine15 creation. Native checker scope is17passes/45software-only geometries; external access and final release gates remain separate.

  • Implementation #20: Discover and analyze external host volumes is resolved on integration f424fb8. Signed ordinary-worker discovery, selected-range read-only analysis, whole/sibling exclusion and truthful lifecycle outcomes pass 158 tests and actual standard-user macOS 15/current checks. Final combined signed scans preserve independent six-file/VDL/range and full offline hashes. Native writes, physical/cache durability and final distribution gates remain separate.

  • Implementation #17: Run Defrag All with accurate outcomes is resolved on integration cbc9aef. Full-volume frozen review/order, verified file transactions, predictable skips, failure/recovery halts, safe Stop and truthful retained final results pass 166 integrated tests and native FAT32/exFAT/large-file checks. Shared FAT32 allocation-slack and postcommit Stop regressions are corrected. Image-only scope; later raw-write/recovery/release gates remain pending.

  • Implementation #18: Compact small files with measured outcomes is resolved on integration 6f6a9b3. Reviewed bounded FAT32/exFAT compaction includes contiguous files, finite caps, strict final benefit and preserved committed-prefix free space. Full 182-test combined suite, fresh 26-test/79-case integration checks, native two-file completion and actual Copying/Stop pass independent complete allocation/content/free-run checks. Scoped image qualification and explicit limited/unverified outcomes are retained; later recovery/raw-write/distribution gates remain pending.

Implementation #19 — verified recovery workflow

Recover interrupted operations in the app is implemented and resolved on integration merge 58e8cf4. Read-only matching, explicit replay, self-contained bundles and reverified per-file/aggregate history preserve unresolved evidence and distinguish unknown later outcomes/metrics. All 200 ordinary release tests pass (895.115 s), including 952 aggregate faults; six final-source native image bundle sessions and fresh 21-test/87-case merge/release checks pass. External writes #21–23 and final supported-runtime/distribution/lifecycle gates #24 remain active under the resumed full implementation effort.

Implementation #21–23 — qualified external operations enabled

  • Create a verified VHD on external storage (#21) is resolved on 381442f. Fresh target/preparation/preview, checked persistence and conservative recovery preserve evidence. Independent guest-zero/footer/EOF/complete-extent and complete surrounding-file/allocation/metadata proofs pass. Exact signed d514 mounted macOS 15 Compact → fresh Create and macOS 27 File/All exited safely. Hardware detachment, new EOF slack zeroing and physical guarantees are not inferred.
  • Defragment files on external storage (#22) is resolved on 381442f. Exact d514 standard-user macOS 27 File → fresh All preserves six files, full allocations/slack/metadata, pinned and sibling/outside bytes. Literal placements/exact-free-map oracles run with the raw descriptor held; native close 0, raw check 0, unchanged input, normal Quit and detach pass. Earlier both-filesystem macOS 15/API Stop/rollback evidence retains its timing limits.
  • Compact external storage (#23) is resolved on 381442f. Bounded policy/no-benefit/target-unmet, both-filesystem modeled-report rollback and explicit Compact → fresh Create joins pass preservation/free-run checks. Actual FAT GUI Stop and old close gaps remain unqualified; accepted public/thin-native composition requires no further matrix.

All four flags are enabled in development integration after independent review, canonical/signing checks and thin exact-artifact checks on both runtimes. Qualify and package the native app (#24) remains the frontier: supported lifecycle, final frozen both-OS suites/native UI/whole-review and notarized/stapled DMG/Homebrew distribution are still open. Earlier planning, pause, milestone and failure history is preserved.

Not yet specified

None. All required planning decisions are resolved; implementation and software validation execution are the later effort.

Implementation Decisions

The following records confirmed scope and requirements implied by it. Research constraints are identified as such; accepted operation and workflow choices are indexed by their resolved tickets. Validation gates and the staged handoff are governed by Set validation gates and the implementation handoff.

  1. Current deliverable: planning and specification only. Building or deploying the application is a later effort, even though this specification is labelled ready-for-agent.
  2. Platform: a native Swift application targeting macOS 15+ on Apple Silicon. Intel and older macOS versions are not the initial target.
  3. Host volumes: external FAT32/exFAT, including external devices classified as fixed media. Device discovery must distinguish external location from removability. Detailed geometry and volume eligibility are resolved in Set the supported volume and device contract.
  4. IODD scope: original mini and newer image-capable devices. Current research identifies ST300, ST400, and MINI PRO as relevant model profiles; newer does not itself prove image capability or compatibility. Hardware qualification remains distinct from documented support.
  5. Functional parity: preserve drive selection/refresh, Analyze, statistics, allocation map, fragmented-file selection, Defrag File, Defrag All, small-file Compact, progress, Stop, and native About/menu/accessibility behavior. The behavioral reference does not require reproducing implementation defects or unrelated embedded functions.
  6. Creation output: a valid fixed-size VHD with verified contiguous host allocation. Dynamic/differencing VHD and VHDX are outside the selected output scope. Capacity, guest contents, destination, and operation outcomes are governed by Define fixed VHD creation and allocation failure behavior.
  7. Allocation reporting: use actual extents and complete file coverage. Keep fragmentation, fixed-container validity, model-specific IODD eligibility, and bootability as separate results. The documented ISO allowance maps to at most 24 host extents for the researched profiles; VHD allocation requires one. Firmware counting and attachment remain unmeasured hardware behavior, separate from software-validation acceptance. IODD mini reference.
  8. Fixed-format constraints: for accepted virtual capacity C, use a 512-byte-aligned guest byte range followed by the standard 512-byte fixed VHD footer. Complete host file length is C + 512; cluster-rounded allocation must cover that length, including the footer, without adding logical padding after it. Validate footer type, fields, checksum, capacities, and geometry independently. These are format constraints, not newly selected UI policies. Microsoft format specification.
  9. Size constraints: use checked capacity and allocation arithmetic. FAT32's maximum host file length includes footer overhead; the greatest 512-byte-aligned virtual capacity under that limit is 4,294,966,272 bytes. This is a filesystem arithmetic bound, not a selected default, general IODD capacity limit, or promise of available free space. Metadata growth and transaction workspace need separate budgeting.
  10. Success criteria: neither file length, a valid footer, nor a successful preallocation request certifies contiguity. Final VHD success requires an independently verified single extent for the complete file and conformance to the guest initialization policy governed by Define fixed VHD creation and allocation failure behavior. A fragmented or sparse result cannot silently satisfy the requested output. Apple allocation contract.
  11. Correction baseline: complete scans and real extent counts must replace the original's omissions and display caps. Mutation correctness must address allocation ownership, checked persistence, directory updates, retained recovery evidence, safe cancellation, fresh final analysis, and remount reporting. The original's recovery mechanism is not an accepted transaction model.
  12. Engine and recovery: the accepted contract is held by Choose the filesystem engine and recoverable mutation contract. No production modules, exact Swift API types, worker protocol implementation or persisted journal implementation yet exist. The ticket governs the decisions; implementation remains a later effort.
  13. Confirmed primary test boundary: the user selected the public volume-operation API exercised against disposable FAT32/exFAT disk images, with independent verification of resulting files, extents, and recovery outcomes. Thin UI and virtual macOS integration checks supplement that main boundary; exact API signatures are implementation choices.

Testing Decisions

The authoritative independent fixture/oracle matrix, fault/recovery outcomes, virtual macOS integration, release/lifecycle prerequisites and staged implementation plan live in the resolution comment on Set validation gates and the implementation handoff. The confirmed main test boundary remains the public volume-operation API against disposable FAT32/exFAT images, supplemented by thin UI and virtual-volume integration checks.

Software validation is the release gate. Physical-media/IODD trials and performance commitments are outside this effort. The referenced contracts specify required evidence; this planning record does not claim that the eventual implementation has already passed it.

Out of Scope

  • Guest partitioning/formatting as part of Create; the new guest disk is initialized separately, as decided in Define fixed VHD creation and allocation failure behavior.
  • Production implementation, helper installation, signing, notarization and release publication during this planning/specification effort.
  • Physical-media read/write trials, IODD attachment/boot and power-loss qualification as part of implementation validation or release acceptance.
  • Performance commitments, benchmark-derived release gates and hardware-specific speed or stop-latency targets.
  • Intel support and macOS versions earlier than 15 for the initial target.
  • Host NTFS, APFS, FAT12/FAT16, and other filesystems outside the confirmed FAT32/exFAT scope.
  • Dynamic/differencing VHD, VHDX, and conversion or creation of unrelated virtual disk formats.
  • General filesystem repair, host-volume formatting/repartitioning, arbitrary sector editing, and cloning the original's manual-repair or unrelated embedded CLI functions.
  • Full VHD Tool++ parity, such as extending existing virtual disks, raw-image conversion, and other tooling beyond the requested fixed VHD creation capability.
  • Operating-system installation, bootloader provisioning, guaranteed bootability, automatic firmware upgrades, and special PIN-management workflows.
  • Copying proprietary recovered code or embedded promotional/audio assets into the replacement.
  • Disk-alone recovery, persistent foreign-OS quarantine, and directory-relocation/in-place movement algorithms are outside the first engine contract chosen in Choose the filesystem engine and recoverable mutation contract.

Further Notes

Specification maturity and triage. The specification retains its requested ready-for-agent label and is implementation-ready. All wayfinder decisions are resolved through user feedback; the map is complete. The later implementation tickets remain open. Current work remains planning and documentation, with the actual software evidence to be produced during implementation.

Logical structure. The accepted operation, worker and storage-ownership contract is held by Choose the filesystem engine and recoverable mutation contract, retaining the public volume-operation API as the primary testing boundary. The native presentation direction is held by Validate the native analysis and VHD creation workflows. Detailed module layout and exact production interfaces remain later implementation matters; this map authorizes no production build.

Resolved validation and handoff. Set validation gates and the implementation handoff holds the accepted independent software evidence, virtual macOS integration, DMG/Homebrew lifecycle contract and staged route through the existing implementation tickets. No required decision remains open.

No common maximum VHD capacity or host sector/cluster geometry matrix was proved for all IODD models. A consumer's published 2040 GiB VHD limit must not automatically become an IODD guarantee. Firmware-specific named-image features must remain separate from ordinary creation.

IODD preparation constraint. Vendor guidance prohibits moving or defragmenting a host image while its hardware virtual drive is in use. The accepted preparation/access requirements are held by Choose the filesystem engine and recoverable mutation contract. OS volume unmounting does not prove hardware LUN detachment; the accepted presentation is held by Validate the native analysis and VHD creation workflows. IODD operational evidence.

Evidence scope. The original FAT Defrag investigation observed startup and TEST discovery, not successful Analyze, mutation, or recovery. VHD Tool++ translation resources were inspected as clues, but its executable was not run or traced. Completed research establishes independently implementable format requirements and source-backed platform alternatives; it does not certify the eventual app or the user's unspecified firmware.

Source and decision provenance. Read the wayfinder map, reference baseline, and completed IODD, macOS access, and fixed VHD research. Detailed findings remain in those assets and their resolved research tickets. The glossary supplies the terms host volume, extent, free run, defragmentation, compaction, fixed-size VHD, virtual capacity, uninitialized guest disk, and IODD eligibility.

Tracker configuration. Forgejo Issues for this repository govern the hosted specification and implementation tickets. The local planning map, original specification, and retained research keep their history; the separate implementation publication index holds reciprocal hosted/local references. This hosted specification and its resolved decision comments govern the implementation-ready handoff. The retained original specification remains a historical publication snapshot; all named planning decisions are closed.

Current implementation effort

On 13 October 2026, phg invoked implement-spec for this specification, starting the software build effort on implement/iodd-tool-spec-7. The planning-only scope above records the completed prior effort. Implementation follows the existing 17-ticket graph and the accepted software-only validation gates; completed slices are recorded in Decisions so far. Physical-media trials remain outside scope.

Paused on 13 October 2026 at the user's request, “Pause when you've finished the current tickets,” after resolving the current set #17, #18 and #20. The pushed integration checkpoint is 6f6a9b3 on implement/iodd-tool-spec-7. Twelve of the seventeen implementation tickets are resolved. On resume, the first unblocked unassigned ticket is Recover interrupted operations in the app (#19); #21, #22, #23 and #24 remain pending behind their dependencies. No new frontier ticket has been claimed or started. The full-spec code review and final signed/notarized release are deferred until the remaining tickets complete. Task-owned VMs are stopped; committed worktrees, validation/recovery evidence and resume context are preserved.

Resumed at 2026-10-13T21:01:53.034022+00:00 after phg's explicit “please continue”. The completed pause checkpoint remains above as history. Recover interrupted operations in the app (#19) is now assigned to phg and started from validated integration6f6a9b3; the remaining dependency graph, full-spec review and final release gates are active again. The original checkout and prior evidence remain preserved.

Implementation continued on 15 October 2026 at pushed 381442f: 16 of 17 implementation tickets (#8–23) are resolved; #24 is assigned to phg and active. This is operation enablement, not final release or whole-review completion. Older macOS 15 and capacity-derivative VMs remain normally stopped with evidence retained; the fresh 100 GB macOS 27 VM is safely idle after exact-d514 qualification. Earlier pause/resume statements remain historical.

# IODD Tool specification Status: complete — implementation-ready specification Labels: ready-for-agent, wayfinder:map Scope: planning and specification only Updated: 13 October 2026 ## Destination An implementation-ready specification for a native macOS Swift app, **IODD Tool**, that preserves the useful FAT Defrag GUI functionality and creates valid fixed-size VHD files with verified contiguous host allocation for IODD devices. The map is complete when product, filesystem, recovery, platform and validation decisions are settled; implementation is a later effort. ## Notes - Interface presentation follows [Apple’s macOS Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines) and the accepted operation contracts, as approved in [Validate the native analysis and VHD creation workflows](https://git.s1q.dev/phg/iodd-tool/issues/5). Use native controls appropriate to the running macOS version while retaining the agreed macOS 15 minimum. - This issue is the hosted wayfinder map and specification index. The retained local map and original specification preserve their history; detailed answers live in the hosted decision tickets' resolution comments. - Planning and specification only. No production implementation, helper installation or physical-disk trials are authorized by this map or its ready-for-agent label. - Consult wayfinder, grilling and domain-modeling when working a decision; use research or prototype for their corresponding ticket types. Claim a child before work; HITL decisions require live user feedback. Use the configured Forgejo tracker conventions in docs/agents/issue-tracker.md. - The confirmed primary test boundary is the public volume-operation API against disposable FAT32/exFAT images, with independent output oracles and thin supplemental UI/device checks. - All wayfinder decisions are resolved. The remaining open implementation tickets belong to the later build effort; their existing dependency graph and the accepted handoff determine order. ## Problem Statement An IODD user needs to inspect and fix fragmentation on external storage from a native macOS application. The existing FAT Defrag GUI offers analysis, file defragmentation, and small-file compaction, but its non-native interface and documented allocation, display, cancellation, and recovery defects make a direct visual rewrite insufficient. The user owns an IODD mini and wants support for that device and newer IODD devices. An ISO may satisfy documented IODD allocation requirements while still being fragmented; a VHD must be contiguous. Users need to understand this distinction and know whether a file actually satisfies the selected device's requirements. The user also needs the relevant VHD Tool++ creation functionality on macOS: choose a size and create a valid fixed-size VHD in a single contiguous host allocation. Enough total free space does not establish that a sufficiently large free run exists. A blank reservation, a sparse image, a valid but fragmented VHD, or an image whose footer falls in another extent does not satisfy this request. ## Solution Specify **IODD Tool**, a native Swift application for macOS 15 and later on Apple Silicon. It discovers all external FAT32/exFAT host volumes, including devices reported as fixed media, and preserves the useful original Analyze, Defrag File, Defrag All, Compact, statistics, allocation map, selection, progress, and cancellation workflow. Add fixed-size VHD creation with an explicit virtual capacity, file-format validation, and verification that the complete resulting host file occupies one extent. Present total free space, the largest free run, host-file overhead, and device eligibility as separate properties. Define correct failure and recovery behavior before enabling writes. This document indexes the conversation, completed research and resolved decisions. The product, workflow, software-validation and distribution contracts are accepted, and the implementation handoff is complete. The user has authorized planning and specification only for this effort. ## User Stories 1. As a Mac user, I want a native Swift application on macOS 15+ and Apple Silicon, so that I can prepare my IODD storage using familiar macOS controls. 2. As an IODD user, I want support for my IODD mini and newer image-capable models, so that I can use the utility with my current and future devices. 3. As a user, I want external FAT32 and exFAT volumes listed, so that I can select compatible host storage. 4. As a USB SSD user, I want external disks reported as fixed media included, so that device classification does not hide my storage. 5. As a user, I want the device, volume label, filesystem, and capacity visible before selection, so that I can distinguish similar drives. 6. As a user, I want refresh and device insertion/removal updates, so that the available targets reflect connected storage. 7. As a user, I want each partition treated as a distinct host volume, so that I can operate on the intended partition. 8. As a user, I want unsupported or read-only targets explained, so that I understand which operations are available. 9. As a user, I want the active operation bound to the selected volume's current identity, so that replacement devices cannot receive stale work. 10. As a user, I want target changes during an active operation handled coherently, so that displayed results always describe the volume being processed. 11. As a user, I want Analyze to produce a consistent allocation snapshot, so that statistics, file rows, and the allocation map agree. 12. As a user, I want total, used, and free capacity plus sector and cluster geometry, so that I understand my host volume. 13. As a user, I want the largest free run shown separately from total free space, so that I can assess contiguous allocation capacity. 14. As a user, I want fragmented-file counts and actual per-file extent counts, so that the app describes measured fragmentation accurately. 15. As a user, I want file paths and logical sizes in a native table, so that I can identify the files that need attention. 16. As a user, I want supported hidden files, nested paths, and Unicode names included, so that analysis does not silently omit relevant files. 17. As a user, I want incomplete scans and allocation anomalies reported, so that an empty file list does not imply an unverified clean volume. 18. As a user, I want an allocation map that represents the full volume, so that I can understand the distribution of allocated and free space. 19. As a user, I want selecting a file to highlight its complete extent ranges, so that large files receive the same accurate coverage as small files. 20. As a keyboard or assistive-technology user, I want accessible tables, controls, and a textual map summary, so that the workflow is usable without interpreting colored cells. 21. As an IODD user, I want fragmentation distinguished from IODD eligibility, so that a permitted fragmented ISO is not confused with an unusable image. 22. As an IODD user, I want the selected model and known firmware reflected in compatibility results, so that constraints are attributed to the right device. 23. As an IODD user, I want ISO allocation assessed against the documented 24-piece allowance, so that I know when defragmentation is needed for allocation eligibility. 24. As an IODD user, I want a VHD's complete host allocation checked for one extent, so that a fragmented footer cannot be overlooked. 25. As an IODD user, I want fixed VHD format validity checked independently of allocation, so that a contiguous invalid image is not called usable. 26. As an IODD user, I want unknown or untested compatibility conditions stated, so that a documented rule is not mistaken for hardware qualification. 27. As an IODD user, I want image validity, guest initialization, and bootability distinguished, so that a newly created uninitialized VHD has an understandable result. 28. As an IODD user, I want relevant path, browser, and virtual-drive preparation requirements explained, so that the device can find and attach the resulting image. 29. As a user, I want Defrag File for a selected fragmented file, so that I can fix that file without processing an entire volume. 30. As a user, I want Defrag All to process its declared eligible set, so that I can address multiple fragmented files in one operation. 31. As a user, I want already contiguous and empty files handled explicitly, so that the app avoids unnecessary movement. 32. As a user, I want operation previews showing intended work, required free runs, and skip reasons, so that I understand the requested changes. 33. As a user, I want original file contents and relevant metadata preserved during movement, so that defragmentation does not alter my data. 34. As a user, I want lack of sufficient contiguous destination space explained, so that I can choose a useful next action. 35. As a user, I want small-file Compact functionality, so that I can consolidate free space as in the original GUI. 36. As a user, I want Compact to state its objective and measured before/after outcome, so that completion does not imply an unachieved free-space improvement. 37. As a user, I want compaction thresholds and work limits disclosed, so that partial packing is not presented as an unlimited optimization. 38. As a user, I want consistent previews and backup confirmation for existing-file mutations, so that Compact receives the same deliberate treatment as Defrag. 39. As a user, I want successful, skipped, failed, and recovery-required files identified individually, so that partial success is understandable. 40. As a user, I want a fresh analysis after completed or safely cancelled work, so that the displayed state reflects actual allocation. 41. As an IODD user, I want to create a fixed-size VHD at a destination I choose, so that I can prepare a virtual disk directly on the device's host volume. 42. As an IODD user, I want to enter the desired virtual capacity using clearly identified units, so that the created disk has the size I intended. 43. As an IODD user, I want any capacity adjustment disclosed before creation, so that alignment or geometry does not silently change my request. 44. As an IODD user, I want virtual capacity, complete host file length, and cluster-rounded space consumption shown separately, so that footer and allocation overhead are visible. 45. As an IODD user, I want capacity checked against host filesystem and qualified device limits, so that impossible requests fail before allocation begins. 46. As an IODD user, I want creation to account for the full VHD including its footer, so that the required free run is calculated correctly. 47. As an IODD user, I want a structurally valid fixed VHD rather than merely a blank reserved file, so that the result is a virtual disk image. 48. As an IODD user, I want defined initial guest contents, so that the created image has a predictable initialization state. 49. As an IODD user, I want existing destination files protected by an explicit overwrite policy, so that creating a VHD does not unexpectedly replace data. 50. As an IODD user, I want creation success reported only after format and complete-file extent verification, so that a fragmented result is never silently accepted. 51. As an IODD user, I want enough total space but insufficient contiguous space reported distinctly, so that I understand why a large VHD cannot currently be created. 52. As an IODD user, I want any prerequisite compaction or existing-file movement presented explicitly, so that Create does not conceal changes to unrelated files. 53. As an IODD user, I want failed or cancelled creation to have a defined partial-file and allocation outcome, so that incomplete images do not masquerade as successful results. 54. As an IODD user, I want guidance for attaching the new image and initializing its guest disk, so that I can continue using it without confusing the guest disk with host storage. 55. As a user, I want disk access authorization explained in the context of the selected operation, so that access approval has a clear purpose. 56. As a user, I want a busy volume to report why it cannot be acquired, so that I can close the competing application and retry. 57. As an IODD user, I want preparation guidance for detaching active hardware virtual drives, so that image movement is not attempted while the device is using those images. 58. As a user, I want meaningful operation progress and current-file status, so that I can understand long-running work. 59. As a user, I want Stop to reach a defined safe transaction boundary, so that cancellation preserves a recoverable volume. 60. As a user, I want cancelled-before-change distinguished from partially completed work, so that I know what happened to my files. 61. As a user, I want unplugging or reconnecting a device handled without further stale writes, so that changing hardware cannot redirect an operation. 62. As a user, I want interrupted work discovered before another mutation begins, so that recovery evidence is not overwritten by a new task. 63. As a user, I want an understandable recovery result, so that I know whether I can resume work or need additional help. 64. As a user, I want recovery requirements to identify the correct volume and necessary local evidence, so that another similarly named device is not modified. 65. As a user, I want remount failure reported separately from the file operation's result, so that I understand why the volume is still unavailable in Finder. 66. As a user, I want durability limitations communicated accurately, so that successful host I/O is not presented as an untested power-loss guarantee. 67. As a user, I want native About, menus, keyboard navigation, and system appearance, so that the app behaves like a macOS utility. 68. As a maintainer, I want externally observable correctness tests using independent filesystem and VHD oracles, so that the writer is not its own sole correctness authority. 69. As a maintainer, I want independent software correctness and fault validation using disposable images and virtual volumes, so that acceptance is reproducible without physical-device trials. 70. As a maintainer, I want baseline/current-stable macOS software evidence and documented IODD profile constraints recorded separately from unmeasured hardware behavior, so that support claims match the evidence. 71. As a user, I want the signed/notarized app available as a direct download and a Homebrew cask, so that I can choose my installation and update path. 72. As a user, I want updates and uninstall to preserve recovery evidence and respect active operations, so that interrupted work remains recoverable. ## Decisions so far - [Set the supported volume and device contract](https://git.s1q.dev/phg/iodd-tool/issues/1): Full base-format geometry and validated layouts; read-only/partial diagnostics; separate volume-operation eligibility and IODD qualification. The authoritative answer is the ticket's resolution comment. - [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2): Swift offline worker, device-wide isolation, internal journal, verified per-file commits, and conditional recovery. The authoritative answer is the ticket's resolution comment. - [Define fixed VHD creation and allocation failure behavior](https://git.s1q.dev/phg/iodd-tool/issues/3): Exact binary capacity, verified zeroed guest disk, create-only destination, separate compaction, and recoverable creation outcomes. The authoritative answer is the ticket's resolution comment. - [Define analysis, defrag, and compaction success criteria](https://git.s1q.dev/phg/iodd-tool/issues/4): Complete verified snapshots, separate profile annotations, largest-first Defrag All, and bounded compaction with measured free-run outcomes. The authoritative answer is the ticket's resolution comment. - [Validate the native analysis and VHD creation workflows](https://git.s1q.dev/phg/iodd-tool/issues/5): User accepted the macOS HIG redesign and all five workflow presentation decisions. The authoritative answer and prototype evidence are in the ticket's resolution comment. - [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6): Independent software/fault gates, virtual macOS integration, no hardware or performance gates, and a signed/notarized DMG plus Homebrew cask and staged handoff. The authoritative answer is the ticket's resolution comment. - [Name the project IODD Tool](https://git.s1q.dev/phg/iodd-tool/issues/25): IODD Tool branding and iodd-tool repository identity, with historical evidence preserved. - [Analyze a FAT32 image](https://git.s1q.dev/phg/iodd-tool/issues/8): Native image analysis and independent 32-geometry corpus implemented; full-Xcode integration tests/build pass on [implement/iodd-tool-spec-7](https://git.s1q.dev/phg/iodd-tool/src/branch/implement/iodd-tool-spec-7), merge `766c42c`. - [Inspect the complete allocation map](https://git.s1q.dev/phg/iodd-tool/issues/10): Full-volume exact map/selection/accessible ranges implemented and independently verified on FAT32 and exFAT;37 integrated tests and native keyboard/stale checks pass, final checked commit `cd50bd8`. - [Analyze an exFAT image](https://git.s1q.dev/phg/iodd-tool/issues/9): All62 ordinary exFAT geometry pairs and complete allocation/entry-set/VDL analysis independently verified; native checker qualification remains explicit, integrated native table/map smoke passes. - [Assess IODD image eligibility](https://git.s1q.dev/phg/iodd-tool/issues/11): Named documented profiles, ISO24-piece allowance and separate fixed-VHD complete-allocation/container checks implemented;49 integration tests, QEMU/oracles and native FAT32/exFAT selection/firmware/stale checks pass at `904dd22`. - [Preview fixed VHD creation](https://git.s1q.dev/phg/iodd-tool/issues/12): Exact binary capacity, footer-inclusive allocation, directory/collision semantics, conservative recovery workspace and stale/no-write preview implemented;61 integration tests and native unit/correction/collision checks pass, merge `a133e4d`. - [FAT32 file defragmentation and shared recovery implemented](https://git.s1q.dev/phg/iodd-tool/issues/15): exact reviewed whole-file relocation, physical-unit-safe reservations, bounded checksummed journal/registry/retirement, idempotent logged rollback/forward recovery and conservative imported-evidence refusal. Final83tests/1018faultcases, all32geometries, native explicit-consent image workflow and independent content/untouched/fsck checks pass; integration950e500. Raw-device and signed-release gates remain later tickets. - [Contiguous FAT32 VHD creation implemented](https://git.s1q.dev/phg/iodd-tool/issues/13): exact create-only reviewed full allocation, complete zero guest/fixed footer verification, logged spanning entries/directory growth, source-free rollback/forward recovery and physical-unit-safe reservations. Final105tests/all32geometries/1010creationfaultcases plus nativeCreate/Stop and independent footer/content/extent/QEMU/fsck checks pass; integration2b1dbcb. exFAT/nativeexternal/signedrelease gates remain separate. - Implementation #16: [Defragment a file on an exFAT image](https://git.s1q.dev/phg/iodd-tool/issues/16) is resolved on integration [a4ec902](https://git.s1q.dev/phg/iodd-tool/commit/a4ec902cac54efaf331b89a5c2a05e994b572851). The shared journal now verifies complete exFAT allocation, bitmap/FAT/entry publication and bounded replay; final 124-test suite, all62 software geometry pairs, controlled faults, native image workflows and exact-source macOS15 probe pass. Native checker evidence retains21 passes/45 explicit driver refusals; raw access and release gates remain separate. - Implementation #14: [Create a contiguous VHD on an exFAT image](https://git.s1q.dev/phg/iodd-tool/issues/14) is resolved on integration [fef4131](https://git.s1q.dev/phg/iodd-tool/commit/fef41316d7de887b0bb4edc3bdb5c762baa382c2). Full zero guest/footer/contiguous allocation, bitmap/entry publication, separate directory growth and bounded source-free recovery pass143tests/all62software geometry pairs/1008fault cases, native Create/Stop and exact-source pristine15 creation. Native checker scope is17passes/45software-only geometries; external access and final release gates remain separate. - Implementation #20: [Discover and analyze external host volumes](https://git.s1q.dev/phg/iodd-tool/issues/20) is resolved on integration [f424fb8](https://git.s1q.dev/phg/iodd-tool/commit/f424fb8ca806d7268e33532e398439b850ff6426). Signed ordinary-worker discovery, selected-range read-only analysis, whole/sibling exclusion and truthful lifecycle outcomes pass 158 tests and actual standard-user macOS 15/current checks. Final combined signed scans preserve independent six-file/VDL/range and full offline hashes. Native writes, physical/cache durability and final distribution gates remain separate. - Implementation #17: [Run Defrag All with accurate outcomes](https://git.s1q.dev/phg/iodd-tool/issues/17) is resolved on integration [cbc9aef](https://git.s1q.dev/phg/iodd-tool/commit/cbc9aef4cdd87e5e1e2e8799bcd8623dceb6eaf9). Full-volume frozen review/order, verified file transactions, predictable skips, failure/recovery halts, safe Stop and truthful retained final results pass 166 integrated tests and native FAT32/exFAT/large-file checks. Shared FAT32 allocation-slack and postcommit Stop regressions are corrected. Image-only scope; later raw-write/recovery/release gates remain pending. - Implementation #18: [Compact small files with measured outcomes](https://git.s1q.dev/phg/iodd-tool/issues/18) is resolved on integration [6f6a9b3](https://git.s1q.dev/phg/iodd-tool/commit/6f6a9b3c1db865751ad7dd164f18b2687a7403f0). Reviewed bounded FAT32/exFAT compaction includes contiguous files, finite caps, strict final benefit and preserved committed-prefix free space. Full 182-test combined suite, fresh 26-test/79-case integration checks, native two-file completion and actual Copying/Stop pass independent complete allocation/content/free-run checks. Scoped image qualification and explicit limited/unverified outcomes are retained; later recovery/raw-write/distribution gates remain pending. ### Implementation #19 — verified recovery workflow [Recover interrupted operations in the app](https://git.s1q.dev/phg/iodd-tool/issues/19) is implemented and resolved on integration merge [58e8cf4](https://git.s1q.dev/phg/iodd-tool/commit/58e8cf4084c79336f0b8d65901b66cac1bd663fb). Read-only matching, explicit replay, self-contained bundles and reverified per-file/aggregate history preserve unresolved evidence and distinguish unknown later outcomes/metrics. All 200 ordinary release tests pass (895.115 s), including 952 aggregate faults; six final-source native image bundle sessions and fresh 21-test/87-case merge/release checks pass. External writes #21–23 and final supported-runtime/distribution/lifecycle gates #24 remain active under the resumed full implementation effort. ### Implementation #21–23 — qualified external operations enabled - [Create a verified VHD on external storage (#21)](https://git.s1q.dev/phg/iodd-tool/issues/21) is resolved on [381442f](https://git.s1q.dev/phg/iodd-tool/commit/381442f79cd5736fceaffa15d5f1edacb1ca8842). Fresh target/preparation/preview, checked persistence and conservative recovery preserve evidence. Independent guest-zero/footer/EOF/complete-extent and complete surrounding-file/allocation/metadata proofs pass. Exact signed d514 mounted macOS 15 Compact → fresh Create and macOS 27 File/All exited safely. Hardware detachment, new EOF slack zeroing and physical guarantees are not inferred. - [Defragment files on external storage (#22)](https://git.s1q.dev/phg/iodd-tool/issues/22) is resolved on [381442f](https://git.s1q.dev/phg/iodd-tool/commit/381442f79cd5736fceaffa15d5f1edacb1ca8842). Exact d514 standard-user macOS 27 File → fresh All preserves six files, full allocations/slack/metadata, pinned and sibling/outside bytes. Literal placements/exact-free-map oracles run with the raw descriptor held; native close 0, raw check 0, unchanged input, normal Quit and detach pass. Earlier both-filesystem macOS 15/API Stop/rollback evidence retains its timing limits. - [Compact external storage (#23)](https://git.s1q.dev/phg/iodd-tool/issues/23) is resolved on [381442f](https://git.s1q.dev/phg/iodd-tool/commit/381442f79cd5736fceaffa15d5f1edacb1ca8842). Bounded policy/no-benefit/target-unmet, both-filesystem modeled-report rollback and explicit Compact → fresh Create joins pass preservation/free-run checks. Actual FAT GUI Stop and old close gaps remain unqualified; accepted public/thin-native composition requires no further matrix. All four flags are enabled in development integration after independent review, canonical/signing checks and thin exact-artifact checks on both runtimes. [Qualify and package the native app (#24)](https://git.s1q.dev/phg/iodd-tool/issues/24) remains the frontier: supported lifecycle, final frozen both-OS suites/native UI/whole-review and notarized/stapled DMG/Homebrew distribution are still open. Earlier planning, pause, milestone and failure history is preserved. ## Not yet specified None. All required planning decisions are resolved; implementation and software validation execution are the later effort. ## Implementation Decisions The following records confirmed scope and requirements implied by it. Research constraints are identified as such; accepted operation and workflow choices are indexed by their resolved tickets. Validation gates and the staged handoff are governed by [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6). 1. **Current deliverable:** planning and specification only. Building or deploying the application is a later effort, even though this specification is labelled `ready-for-agent`. 2. **Platform:** a native Swift application targeting macOS 15+ on Apple Silicon. Intel and older macOS versions are not the initial target. 3. **Host volumes:** external FAT32/exFAT, including external devices classified as fixed media. Device discovery must distinguish external location from removability. Detailed geometry and volume eligibility are resolved in [Set the supported volume and device contract](https://git.s1q.dev/phg/iodd-tool/issues/1). 4. **IODD scope:** original mini and newer image-capable devices. Current research identifies ST300, ST400, and MINI PRO as relevant model profiles; newer does not itself prove image capability or compatibility. Hardware qualification remains distinct from documented support. 5. **Functional parity:** preserve drive selection/refresh, Analyze, statistics, allocation map, fragmented-file selection, Defrag File, Defrag All, small-file Compact, progress, Stop, and native About/menu/accessibility behavior. The behavioral reference does not require reproducing implementation defects or unrelated embedded functions. 6. **Creation output:** a valid fixed-size VHD with verified contiguous host allocation. Dynamic/differencing VHD and VHDX are outside the selected output scope. Capacity, guest contents, destination, and operation outcomes are governed by [Define fixed VHD creation and allocation failure behavior](https://git.s1q.dev/phg/iodd-tool/issues/3). 7. **Allocation reporting:** use actual extents and complete file coverage. Keep fragmentation, fixed-container validity, model-specific IODD eligibility, and bootability as separate results. The documented ISO allowance maps to at most 24 host extents for the researched profiles; VHD allocation requires one. Firmware counting and attachment remain unmeasured hardware behavior, separate from software-validation acceptance. [IODD mini reference](https://help.iodd.kr/product-reference-wiki/iodd-mini). 8. **Fixed-format constraints:** for accepted virtual capacity C, use a 512-byte-aligned guest byte range followed by the standard 512-byte fixed VHD footer. Complete host file length is C + 512; cluster-rounded allocation must cover that length, including the footer, without adding logical padding after it. Validate footer type, fields, checksum, capacities, and geometry independently. These are format constraints, not newly selected UI policies. [Microsoft format specification](https://download.microsoft.com/download/f/f/e/ffef50a5-07dd-4cf8-aaa3-442c0673a029/Virtual%20Hard%20Disk%20Format%20Spec_10_18_06.doc). 9. **Size constraints:** use checked capacity and allocation arithmetic. FAT32's maximum host file length includes footer overhead; the greatest 512-byte-aligned virtual capacity under that limit is 4,294,966,272 bytes. This is a filesystem arithmetic bound, not a selected default, general IODD capacity limit, or promise of available free space. Metadata growth and transaction workspace need separate budgeting. 10. **Success criteria:** neither file length, a valid footer, nor a successful preallocation request certifies contiguity. Final VHD success requires an independently verified single extent for the complete file and conformance to the guest initialization policy governed by [Define fixed VHD creation and allocation failure behavior](https://git.s1q.dev/phg/iodd-tool/issues/3). A fragmented or sparse result cannot silently satisfy the requested output. [Apple allocation contract](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/fcntl.2.html). 11. **Correction baseline:** complete scans and real extent counts must replace the original's omissions and display caps. Mutation correctness must address allocation ownership, checked persistence, directory updates, retained recovery evidence, safe cancellation, fresh final analysis, and remount reporting. The original's recovery mechanism is not an accepted transaction model. 12. **Engine and recovery:** the accepted contract is held by [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2). No production modules, exact Swift API types, worker protocol implementation or persisted journal implementation yet exist. The ticket governs the decisions; implementation remains a later effort. 13. **Confirmed primary test boundary:** the user selected the public volume-operation API exercised against disposable FAT32/exFAT disk images, with independent verification of resulting files, extents, and recovery outcomes. Thin UI and virtual macOS integration checks supplement that main boundary; exact API signatures are implementation choices. ## Testing Decisions The authoritative independent fixture/oracle matrix, fault/recovery outcomes, virtual macOS integration, release/lifecycle prerequisites and staged implementation plan live in the resolution comment on [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6). The confirmed main test boundary remains the public volume-operation API against disposable FAT32/exFAT images, supplemented by thin UI and virtual-volume integration checks. Software validation is the release gate. Physical-media/IODD trials and performance commitments are outside this effort. The referenced contracts specify required evidence; this planning record does not claim that the eventual implementation has already passed it. ## Out of Scope - Guest partitioning/formatting as part of Create; the new guest disk is initialized separately, as decided in [Define fixed VHD creation and allocation failure behavior](https://git.s1q.dev/phg/iodd-tool/issues/3). - Production implementation, helper installation, signing, notarization and release publication during this planning/specification effort. - Physical-media read/write trials, IODD attachment/boot and power-loss qualification as part of implementation validation or release acceptance. - Performance commitments, benchmark-derived release gates and hardware-specific speed or stop-latency targets. - Intel support and macOS versions earlier than 15 for the initial target. - Host NTFS, APFS, FAT12/FAT16, and other filesystems outside the confirmed FAT32/exFAT scope. - Dynamic/differencing VHD, VHDX, and conversion or creation of unrelated virtual disk formats. - General filesystem repair, host-volume formatting/repartitioning, arbitrary sector editing, and cloning the original's manual-repair or unrelated embedded CLI functions. - Full VHD Tool++ parity, such as extending existing virtual disks, raw-image conversion, and other tooling beyond the requested fixed VHD creation capability. - Operating-system installation, bootloader provisioning, guaranteed bootability, automatic firmware upgrades, and special PIN-management workflows. - Copying proprietary recovered code or embedded promotional/audio assets into the replacement. - Disk-alone recovery, persistent foreign-OS quarantine, and directory-relocation/in-place movement algorithms are outside the first engine contract chosen in [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2). ## Further Notes **Specification maturity and triage.** The specification retains its requested `ready-for-agent` label and is implementation-ready. All wayfinder decisions are resolved through user feedback; the map is complete. The later implementation tickets remain open. Current work remains planning and documentation, with the actual software evidence to be produced during implementation. **Logical structure.** The accepted operation, worker and storage-ownership contract is held by [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2), retaining the public volume-operation API as the primary testing boundary. The native presentation direction is held by [Validate the native analysis and VHD creation workflows](https://git.s1q.dev/phg/iodd-tool/issues/5). Detailed module layout and exact production interfaces remain later implementation matters; this map authorizes no production build. **Resolved validation and handoff.** [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6) holds the accepted independent software evidence, virtual macOS integration, DMG/Homebrew lifecycle contract and staged route through the existing implementation tickets. No required decision remains open. No common maximum VHD capacity or host sector/cluster geometry matrix was proved for all IODD models. A consumer's published 2040 GiB VHD limit must not automatically become an IODD guarantee. Firmware-specific named-image features must remain separate from ordinary creation. **IODD preparation constraint.** Vendor guidance prohibits moving or defragmenting a host image while its hardware virtual drive is in use. The accepted preparation/access requirements are held by [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2). OS volume unmounting does not prove hardware LUN detachment; the accepted presentation is held by [Validate the native analysis and VHD creation workflows](https://git.s1q.dev/phg/iodd-tool/issues/5). IODD operational evidence. **Evidence scope.** The original FAT Defrag investigation observed startup and TEST discovery, not successful Analyze, mutation, or recovery. VHD Tool++ translation resources were inspected as clues, but its executable was not run or traced. Completed research establishes independently implementable format requirements and source-backed platform alternatives; it does not certify the eventual app or the user's unspecified firmware. **Source and decision provenance.** Read the wayfinder map, reference baseline, and completed IODD, macOS access, and fixed VHD research. Detailed findings remain in those assets and their resolved research tickets. The glossary supplies the terms host volume, extent, free run, defragmentation, compaction, fixed-size VHD, virtual capacity, uninitialized guest disk, and IODD eligibility. **Tracker configuration.** Forgejo Issues for this repository govern the hosted specification and implementation tickets. The local planning map, original specification, and retained research keep their history; the separate implementation publication index holds reciprocal hosted/local references. This hosted specification and its resolved decision comments govern the implementation-ready handoff. The retained original specification remains a historical publication snapshot; all named planning decisions are closed. ## Current implementation effort On 13 October 2026, phg invoked implement-spec for this specification, starting the software build effort on [implement/iodd-tool-spec-7](https://git.s1q.dev/phg/iodd-tool/src/branch/implement/iodd-tool-spec-7). The planning-only scope above records the completed prior effort. Implementation follows the existing 17-ticket graph and the accepted software-only validation gates; completed slices are recorded in Decisions so far. Physical-media trials remain outside scope. Paused on 13 October 2026 at the user's request, “Pause when you've finished the current tickets,” after resolving the current set #17, #18 and #20. The pushed integration checkpoint is [6f6a9b3](https://git.s1q.dev/phg/iodd-tool/commit/6f6a9b3c1db865751ad7dd164f18b2687a7403f0) on [implement/iodd-tool-spec-7](https://git.s1q.dev/phg/iodd-tool/src/branch/implement/iodd-tool-spec-7). Twelve of the seventeen implementation tickets are resolved. On resume, the first unblocked unassigned ticket is [Recover interrupted operations in the app (#19)](https://git.s1q.dev/phg/iodd-tool/issues/19); #21, #22, #23 and #24 remain pending behind their dependencies. No new frontier ticket has been claimed or started. The full-spec code review and final signed/notarized release are deferred until the remaining tickets complete. Task-owned VMs are stopped; committed worktrees, validation/recovery evidence and resume context are preserved. Resumed at 2026-10-13T21:01:53.034022+00:00 after phg's explicit “please continue”. The completed pause checkpoint remains above as history. [Recover interrupted operations in the app (#19)](https://git.s1q.dev/phg/iodd-tool/issues/19) is now assigned to phg and started from validated integration6f6a9b3; the remaining dependency graph, full-spec review and final release gates are active again. The original checkout and prior evidence remain preserved. Implementation continued on 15 October 2026 at pushed [381442f](https://git.s1q.dev/phg/iodd-tool/commit/381442f79cd5736fceaffa15d5f1edacb1ca8842): 16 of 17 implementation tickets (#8–23) are resolved; #24 is assigned to phg and active. This is operation enablement, not final release or whole-review completion. Older macOS 15 and capacity-derivative VMs remain normally stopped with evidence retained; the fresh 100 GB macOS 27 VM is safely idle after exact-d514 qualification. Earlier pause/resume statements remain historical.
phg commented 2026-10-13 08:37:34 +00:00
Author
Owner
Copy link

Wayfinder complete — implementation-ready specification

All six required decision tickets are resolved through the user's feedback. The destination is reached: this specification indexes the accepted product, engine/recovery, creation, analysis/compaction, native-workflow and validation contracts, with no required decision or in-scope fog remaining.

The authoritative final software-validation, distribution/lifecycle and staged implementation handoff is the resolution comment on Set validation gates and the implementation handoff.

The existing 17 implementation tickets remain open for the later build effort. Their acceptance criteria and retained records have been reconciled with the final contract. Verified the dependency graph has no cycles or missing references and that the original specification snapshot is preserved. The first unblocked implementation slice is Analyze a FAT32 image.

Closing this map records planning completion. The actual implementation and its required software evidence have not yet been produced.

## Wayfinder complete — implementation-ready specification All six required decision tickets are resolved through the user's feedback. The destination is reached: this specification indexes the accepted product, engine/recovery, creation, analysis/compaction, native-workflow and validation contracts, with no required decision or in-scope fog remaining. The authoritative final software-validation, distribution/lifecycle and staged implementation handoff is the resolution comment on [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6). The existing 17 implementation tickets remain open for the later build effort. Their acceptance criteria and retained records have been reconciled with the final contract. Verified the dependency graph has no cycles or missing references and that the original specification snapshot is preserved. The first unblocked implementation slice is [Analyze a FAT32 image](https://git.s1q.dev/phg/iodd-tool/issues/8). Closing this map records planning completion. The actual implementation and its required software evidence have not yet been produced.
phg closed this issue 2026-10-13 08:37:34 +00:00
phg changed title from Native Swift FAT Defrag and contiguous VHD creation specification to IODD Tool specification 2026-10-13 08:46:10 +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
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#7
No description provided.