Set the supported volume and device contract #1
Labels
No labels
needs-info
needs-triage
ready-for-agent
ready-for-human
wayfinder:grilling
wayfinder:map
wayfinder:prototype
wayfinder:research
wontfix
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
phg/iodd-tool#1
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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 exact macOS, hardware, FAT32/exFAT geometry, and volume eligibility contract should the first specification promise, and how should unsupported targets be presented?
Use the user's initial platform/model/drive-selection answers and the source-backed access/compatibility findings. Define eligible external fixed/removable volumes, internal-disk exclusion, read-only versus writable targets, logical sector sizes, cluster sizes, large-file bounds, multi-partition devices, TexFAT/unsupported variants, and malformed-volume behavior. Distinguish “can analyze,” “can mutate,” and “can create an IODD-eligible image.” Specify observable rejection reasons and target identity rules without copying historical BSD device paths.
Consult grilling and domain-modeling. Resolve with the user after the prerequisite research; unsupported hardware behavior must be explicit in the specification.
Blocked by
None. The prerequisite IODD and macOS access research is complete in the retained planning records.
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.
Resolution — supported volume and device contract
Confirmed by phg on 12 October 2026 through six support-policy choices and the final shared-understanding check. This decision specifies the supported-volume boundary for the later implementation and preserves planning-only authorization.
Platform and discovery
Filesystem and geometry scope
The first specification targets the complete published base-format geometry range, rather than permanently restricting support to 512-byte sectors. Implementation and qualification can proceed in stages; an unimplemented or unqualified operation must be unavailable with a reason instead of masquerading as supported.
NoFatChainallocation.These are format targets conditional on coherent remaining geometry. FAT32 identification uses computed cluster count, not the boot label or a generic macOS
msdosclassification. Larger FAT32 clusters have consumer interoperability caveats; they are not automatically malformed. Microsoft FAT specification, 2005, pp. 8–11, Microsoft formatter allocation sizes, Microsoft exFAT specification.Recognize TexFAT, unsupported filesystem revisions, and other FAT counts as distinct unsupported variants. Disable mutations and limit diagnostics to structures whose semantics and bounds are understood. Two FAT32 copies do not indicate TexFAT. Do not treat an unknown revision as ordinary supported exFAT or declare it corrupt solely because it is newer.
Device logical block bytes, physical block bytes, filesystem sector bytes, host cluster bytes, and the VHD's 512-byte guest sectors are separate quantities. The logical-block target includes 512/1024/2048/4096-byte devices, including 512n, 512e, and 4Kn configurations. Record actual geometry; use checked byte conversions and bounds. A device/filesystem-sector mismatch requires a proven mapping and supported macOS integration before mutation, otherwise report unsupported geometry. Physical-block reporting and alignment must be handled by the eventual I/O contract; neither cluster size nor a reported physical block size proves atomic or durable writes. Apple geometry controls.
Disk layouts and selected-volume bounds
Support validated GPT, MBR primary and extended/logical partitions, and positively identified partitionless volumes. A missing or unknown partition map is not sufficient evidence of a partitionless volume. Resolve the selected volume's origin and byte range independently of filesystem bootstrapping hints; validate references, checksums where applicable, overlaps, and extended-chain loops. Conflicting, damaged, or ambiguous layout metadata permits bounded diagnostics only. No host formatting or partition-table repair is included. UEFI partition-table format, UEFI partition discovery, Microsoft partitionless-layout definition.
An operation targets the selected volume's validated range. Access to the whole device does not authorize modifying another partition or its partition table. The engine decision must establish isolation across sibling volumes and device aliases.
Independent operation availability
Analyze: supported readable volumes, including read-only volumes, are eligible for full analysis when complete, consistent coverage can be established. Analyze requests only the access it needs. Damaged or changing volumes may yield explicitly partial diagnostics: identify verified coverage and failures; withhold metrics or conclusions that depend on unverified ownership or allocation. In particular, an incomplete scan does not establish a clean volume, exact free-space totals, a largest free run, or image eligibility. If even bounded interpretation is unsafe, stop analysis and explain why.
Defrag and Compact: additionally require writable access, supported and qualified engine/macOS behavior for the actual geometry and operation, a validated consistent volume/layout, unambiguous current target identity, and the access/isolation/preparation conditions established by the mutation contract. Dirty, damaged, incomplete, or recovery-required states do not become writable just because some file rows can be displayed. No silent filesystem repair or clearing unresolved error state is included.
Create fixed VHD: has the same host-volume write gates, plus representable accepted capacity, legal complete host-file length, allocation/workspace availability, and independent format/complete-file extent verification. A creation success certifies its agreed format/allocation/initialization properties; it does not certify IODD attachment or bootability.
Unknown IODD model, firmware, or attachment qualification does not independently block ordinary filesystem operations once their own requirements pass. This does not waive macOS/engine qualification or safe IODD preparation. Hardware virtual-drive detachment, authorization, isolation, and recovery mechanics remain questions for Choose the filesystem engine and recoverable mutation contract.
Capacity and arithmetic invariants
Target identity and attachment lifecycle
Bind analysis, previews, and operations to the live attachment generation and selected volume. Combine available device/volume/partition identifiers, parent-device association, partition origin/length, geometry, and filesystem fingerprints; validate the acquired descriptor against fresh evidence. Labels, mount paths, historical BSD paths, and any single clonable UUID are insufficient by themselves. A missing optional identifier is not automatically fatal if the remaining evidence establishes an unambiguous current target. Apple disk-description keys.
Disappearance, replacement, or conflicting identity invalidates snapshots and plans. Reconnection establishes a new attachment generation and requires fresh identity/geometry/consistency checks; queued writes must never automatically inherit a reused path or device name. Ambiguous matching remains blocked. Explicit recovery is a separate action governed by the engine/recovery decision; this ticket does not select its journal schema or replay algorithm.
IODD support and evidence
Use named original-mini, ST300, ST400, and MINI PRO image-capable profiles. Older or future models do not inherit a promise solely through their names or age. LK100 can be an ordinary external-volume target but lacks the relevant image-emulation capability. Preserve unknown firmware and model-specific source conflicts rather than inventing an installed version. IODD model comparison, Original mini reference.
Report measured allocation, fixed-VHD validity, guest initialization, documented IODD requirements, actual hardware qualification, and bootability separately. For researched image profiles, assess ISO allocation against at most 24 extents and the complete VHD against one extent, including its footer. Qualify observations by actual model, firmware, layout, geometry, and image capacity. A valid host filesystem or untested 4Kn combination does not establish IODD acceptance. No unknown or merely documented combination may be presented as hardware-verified compatible.
Observable rejection and diagnostic reasons
Preserve specific reasons: unsupported filesystem/revision/variant; unsupported or unqualified operation/geometry; unresolved external location; unreadable versus read-only versus authorization denied; busy/unavailable access; dirty/damaged/incomplete metadata; recovery required; ambiguous layout/identity or changed attachment; out-of-range/unrepresentable arithmetic; file-length limit; insufficient total space versus insufficient contiguous allocation/workspace; and unassessed, documented, incompatible, or hardware-qualified IODD evidence. Show the relevant measured condition and available next action. These are semantics, not a selected error enum, helper protocol, or final UI layout.
Qualification and remaining decisions
The geometry envelope supplies 32 FAT32 and 62 ordinary-exFAT sector/cluster pairs for finite parser/image-backed coverage. Independent allocation/content oracles, actual macOS integration outcomes, and operation-specific mutation/fault cases must support claimed capabilities. This decision does not claim that any physical-media mutation or IODD geometry row has already been qualified. Exact release gates and hardware trials remain for Set validation gates and the implementation handoff.
The current FatFs documentation advertises exFAT clusters only through 16 MB; an unchanged component adoption must not silently narrow the agreed 32 MiB format envelope. Resolve that constraint when choosing the engine. FatFs limits.
All newly precise work fits existing engine, VHD workflow, analysis/compaction, prototype, and validation decisions; no additional decision ticket is required by this resolution. TexFAT/additional-revision mutation support, internal disks, and host repair/formatting are outside this first-version contract. Performance and recovery presentation still depend on the remaining decisions.
Research and context pointers
docs/research/supported-volume-geometry.md; original isolated branchresearch/supported-volume-geometry, commit5cc59dc8e8ea85e077d9dc08434c327a8f694eb9, delegated worker/root/supported_volume_geometry, worktree../fat-defrag-native-wayfinder-research/supported-volume-geometry. The research branch is published; the report link is pinned to its evidence commit.docs/research/iodd-compatibility.md,docs/research/macos-volume-access.md, anddocs/research/fixed-vhd-format.md. Primary sources above remain publicly reviewable; the retained repository assets preserve detailed provenance.