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

Set validation gates and the implementation handoff #6

New issue
Closed
opened 2026-10-11 19:10:06 +00:00 by phg · 3 comments
phg commented 2026-10-11 19:10:06 +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 evidence and staged implementation plan are sufficient to enable disk writes and call the eventual native app complete?

Agree on independent FAT32/exFAT fixture manifests and checkers, fixed VHD conformance/extent verification, hash and metadata preservation, geometry/name/large-file cases, fault injection at data/metadata/flush boundaries, idempotent recovery, service/identity failures, and success versus repair-required criteria. Define disposable hardware and actual IODD model/firmware trials, including attach/boot behavior where appropriate; do not assume the existing TEST disk can be overwritten.

Specify release/development toolchain, signing/helper-registration/notarization prerequisites, installation/update/uninstall behavior, and which deliverables can proceed before credentials or hardware are available. Choose practical performance expectations only when the target devices and likely image sizes are known.

Use the resolved Define analysis, defrag, and compaction success criteria for independent snapshot/extent/map and compaction-outcome oracles, including inclusive threshold boundaries, logical versus allocated byte budgets, work-cap boundaries, committed-prefix largest-run preservation, no-benefit and already-met-target results, and partial/stale analysis. Decide geometry-dependent analysis resource/responsiveness expectations, compaction planner search/resource budgets and safe-stop responsiveness, and whether any additional public module seams are required before the staged handoff. Bound the planner without presenting failure to find a beneficial plan as proof that improvement is impossible; choose measured performance targets only with suitable device/geometry evidence.

Produce the linked implementation-ready specification and staged handoff from the resolved ticket answers. Reconcile every in-scope fog item and remaining dependency. The destination is clear only when no required product or correctness decision remains; writing production code is outside this ticket.

Blocked by

Prior clarification

The user confirmed the public volume-operation API against disposable FAT32/exFAT images as the main test boundary, with independent file/extent/recovery checks and thin supplemental UI/device-integration checks. The complete validation/release/handoff decision was confirmed by phg on 13 October 2026; its authoritative answer is the resolution comment on this ticket.

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 was resolved through the user's seven interview answers and final shared-understanding confirmation. The original proposed hardware/performance requirements are superseded by the resolution comment; this body retains the original question as history.

## 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 evidence and staged implementation plan are sufficient to enable disk writes and call the eventual native app complete? Agree on independent FAT32/exFAT fixture manifests and checkers, fixed VHD conformance/extent verification, hash and metadata preservation, geometry/name/large-file cases, fault injection at data/metadata/flush boundaries, idempotent recovery, service/identity failures, and success versus repair-required criteria. Define disposable hardware and actual IODD model/firmware trials, including attach/boot behavior where appropriate; do not assume the existing TEST disk can be overwritten. Specify release/development toolchain, signing/helper-registration/notarization prerequisites, installation/update/uninstall behavior, and which deliverables can proceed before credentials or hardware are available. Choose practical performance expectations only when the target devices and likely image sizes are known. Use the resolved [Define analysis, defrag, and compaction success criteria](https://git.s1q.dev/phg/iodd-tool/issues/4) for independent snapshot/extent/map and compaction-outcome oracles, including inclusive threshold boundaries, logical versus allocated byte budgets, work-cap boundaries, committed-prefix largest-run preservation, no-benefit and already-met-target results, and partial/stale analysis. Decide geometry-dependent analysis resource/responsiveness expectations, compaction planner search/resource budgets and safe-stop responsiveness, and whether any additional public module seams are required before the staged handoff. Bound the planner without presenting failure to find a beneficial plan as proof that improvement is impossible; choose measured performance targets only with suitable device/geometry evidence. Produce the linked implementation-ready specification and staged handoff from the resolved ticket answers. Reconcile every in-scope fog item and remaining dependency. The destination is clear only when no required product or correctness decision remains; writing production code is outside this ticket. ## Blocked by - [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2) - [Define fixed VHD creation and allocation failure behavior](https://git.s1q.dev/phg/iodd-tool/issues/3) - [Define analysis, defrag, and compaction success criteria](https://git.s1q.dev/phg/iodd-tool/issues/4) - [Validate the native analysis and VHD creation workflows](https://git.s1q.dev/phg/iodd-tool/issues/5) ## Prior clarification The user confirmed the public volume-operation API against disposable FAT32/exFAT images as the main test boundary, with independent file/extent/recovery checks and thin supplemental UI/device-integration checks. The complete validation/release/handoff decision was confirmed by phg on 13 October 2026; its authoritative answer is the resolution comment on this ticket. ## 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 was resolved through the user's seven interview answers and final shared-understanding confirmation. The original proposed hardware/performance requirements are superseded by the resolution comment; this body retains the original question as history.
phg commented 2026-10-12 10:07:20 +00:00
Author
Owner
Copy link

Set the supported volume and device contract is now resolved and closed. Use its authoritative resolution comment for scope and capability semantics.

The geometry evidence makes the sector/cluster fixture worklist precise, together with ordinary variant, selected-layout, byte-unit, and address-boundary cases. Define qualification through the already agreed public volume-operation API, distinguishing image/engine correctness, actual macOS integration, and IODD hardware observations. No physical-media mutation or IODD geometry row was qualified by this planning session. Release gates and trial authorization remain unresolved here.

[Set the supported volume and device contract](https://git.s1q.dev/phg/iodd-tool/issues/1) is now resolved and closed. Use its authoritative resolution comment for scope and capability semantics. The [geometry evidence](https://git.s1q.dev/phg/iodd-tool/src/commit/5cc59dc8e8ea85e077d9dc08434c327a8f694eb9/docs/research/supported-volume-geometry.md) makes the sector/cluster fixture worklist precise, together with ordinary variant, selected-layout, byte-unit, and address-boundary cases. Define qualification through the already agreed public volume-operation API, distinguishing image/engine correctness, actual macOS integration, and IODD hardware observations. No physical-media mutation or IODD geometry row was qualified by this planning session. Release gates and trial authorization remain unresolved here.
phg self-assigned this 2026-10-13 07:30:10 +00:00
phg commented 2026-10-13 07:58:22 +00:00
Author
Owner
Copy link

Interview checkpoint — software-only validation and distribution

phg answered the first interview round on 13 October 2026:

  • Validation: software validation only. Use disposable virtual FAT32/exFAT volumes when a device-like target is needed. Physical-media trials, IODD attachment/boot trials and hardware power-loss tests are not validation or release prerequisites for this effort. Do not use or overwrite the existing TEST disk.
  • IODD coverage: the first release does not wait for physical testing of every targeted IODD model, nor for a mini qualification trial. Keep documented model/firmware requirements separate from hardware observations; software results do not establish unperformed hardware qualification.
  • Distribution: deliver a Developer ID signed, notarized downloadable app and a Homebrew tap. Exact package, cask and lifecycle choices remain to be made concrete.
  • Performance: no performance commitments or benchmark-derived release targets. The eventual drives are unknown and IODD devices are storage enclosures with additional functionality. Preserve the accepted correctness, work-limit and cancellation contracts without throughput, elapsed-time, stop-latency or device-speed promises.

These answers supersede this ticket's proposed hardware-trial and performance-target requirements and the corresponding earlier handoff recommendations. The ordinary authopen worker remains the accepted design; daemon registration is not a prerequisite.

The independent software oracle/fault matrix, virtual macOS integration coverage, release/update/uninstall contract and complete staged handoff still need a shared-understanding check. This is a checkpoint, not the resolution; current scope remains planning and specification only.

## Interview checkpoint — software-only validation and distribution phg answered the first interview round on 13 October 2026: - **Validation:** software validation only. Use disposable virtual FAT32/exFAT volumes when a device-like target is needed. Physical-media trials, IODD attachment/boot trials and hardware power-loss tests are not validation or release prerequisites for this effort. Do not use or overwrite the existing TEST disk. - **IODD coverage:** the first release does not wait for physical testing of every targeted IODD model, nor for a mini qualification trial. Keep documented model/firmware requirements separate from hardware observations; software results do not establish unperformed hardware qualification. - **Distribution:** deliver a Developer ID signed, notarized downloadable app and a Homebrew tap. Exact package, cask and lifecycle choices remain to be made concrete. - **Performance:** no performance commitments or benchmark-derived release targets. The eventual drives are unknown and IODD devices are storage enclosures with additional functionality. Preserve the accepted correctness, work-limit and cancellation contracts without throughput, elapsed-time, stop-latency or device-speed promises. These answers supersede this ticket's proposed hardware-trial and performance-target requirements and the corresponding earlier handoff recommendations. The ordinary authopen worker remains the accepted design; daemon registration is not a prerequisite. The independent software oracle/fault matrix, virtual macOS integration coverage, release/update/uninstall contract and complete staged handoff still need a shared-understanding check. This is a checkpoint, not the resolution; current scope remains planning and specification only.
phg commented 2026-10-13 08:29:08 +00:00
Author
Owner
Copy link

Resolution — software validation and implementation handoff

Confirmed by phg on 13 October 2026: the first four answers selected software-only validation, no wait for IODD hardware qualification, a signed/notarized download plus a Homebrew tap, and no performance commitments. phg then agreed to the independent software correctness gate, virtual macOS integration gate, and complete distribution/lifecycle contract, confirming the final shared understanding.

This is the authoritative validation and staged-handoff decision. It completes the planning route; it neither implements the app nor claims any test has already passed. The accepted supported-volume, engine/recovery, creation, analysis/compaction, and native-workflow contracts remain governed by their respective resolved tickets.

Validation scope and main boundary

  • Validate software only. Use disposable FAT32/exFAT disk images and attached virtual volumes whenever a device-like target is needed. Physical-media read/write trials, IODD attachment/boot trials and hardware power-loss tests are outside this validation effort and are not release prerequisites. Existing physical disks, including TEST, are not fixtures.
  • Keep the public volume-operation API as the main boundary for analyze, preview, execute, cancel and recover. Independent tests inspect the resulting storage and observable outcomes, rather than asserting private parser/planner/journal phases. No additional public module seam is required for the handoff; a controllable storage/fault adapter belongs below that boundary.
  • Use a distinct, explicitly admitted fixture identity for images and virtual attachments. Preserve production discovery of all eligible external FAT32/exFAT media, including fixed media; do not globally classify disk images or devices with unknown location as external. Test production discovery decisions with controlled device descriptions and the native access lifecycle with validated disposable attachments.
  • Retain all runtime identity, bounds, ownership, authorization, isolation, checked synchronization, preparation, backup/preview and recovery gates. Removing hardware trials does not permit an unsupported synchronization or exclusivity operation to return fabricated success.
  • IODD profiles retain documented model/firmware constraints and separate format, allocation, guest initialization and eligibility results. No model, including mini, must undergo a physical trial before release. Do not label unperformed hardware qualification, firmware attachment, bootability or physical power-loss behavior as measured software evidence.

Independent fixture and oracle gate

Each implementation slice owns its applicable tests and records reproducible fixture identity, manifest, operation/settings, software versions, expected results, actual independent results and any fault schedule/seed.

  • Establish independently specified manifests and independently implemented FAT32/exFAT allocation/ownership readers or capable non-repairing checkers. Include original content hashes, paths/names, attributes/timestamps, logical and allocated lengths, complete extents, free runs, pinned ownership and selected-volume/sibling bounds. Do not reuse writer placement bookkeeping as the oracle.
  • Cover the agreed geometry envelope: all 32 FAT32 and 62 ordinary-exFAT sector/cluster pairs, consistent volume sizes, supported revisions/allocation forms, one/two FAT32 FATs and active/mirrored modes, validated MBR/GPT/partitionless and supported extended-partition layouts. Keep device logical/physical blocks, filesystem sectors, host clusters, partition origins and 512-byte VHD guest sectors distinct. Include alignment and checked-address/overflow boundaries.
  • Coherent sparse backing images and synthetic address/arithmetic fixtures may avoid materializing enormous media. A synthetic boundary fixture proves the declared arithmetic case, not native mount support; a sparse backing container must not substitute for a VHD's required fully initialized guest contents or complete host-volume allocation.
  • Exercise hidden/system/read-only files, empty files, nested/long/Unicode names, large ranges, FAT32 reserved bits/FSInfo, exFAT bitmap and chained/NoFatChain states, ValidDataLength zeros, complete spanning entry sets/checksums and preserved unrelated fields. Malformed/unsupported geometry, loops, cross-links, missing coverage and conflicting layouts must produce the accepted diagnostic/refusal result without mutation.
  • Compare complete snapshots, actual extent counts, largest runs, statistics and full map/selection coverage against manifests. Partial/cancelled scans withhold unsupported global claims; stale snapshots/plans and attachment replacement cannot authorize work.
  • Independently verify fixed VHD footer/type/checksum/fields/capacity/exact EOF, all guest zeros and one complete-file extent including footer clusters. Test the 16 MiB minimum, 1 GiB default, selected 2040 GiB ceiling, FAT32 aligned limit and one sector beyond, exact binary-unit conversion, footer/cluster overhead, collision, insufficient total/run/workspace and create-only publication rules. QEMU or another independent consumer supplements the independent footer/allocation oracles; a sparse research fixture alone is insufficient.
  • For defrag and batches, independently check hashes, preserved metadata/identity, complete contiguous allocation, untouched files/regions and truthful success/skip/error/Stop outcomes. Verify largest-first batch order, full-volume selection independent of display filters and halt-on-actual-failure behavior.
  • For Compact, verify the inclusive logical-size threshold, logical versus allocated byte accounting, move/byte limits, feasible disjoint destinations, staging plans, no-benefit/already-met-target outcomes and optional target status. Independently confirm that every committed prefix preserves the starting largest free run, and that final reported benefit matches actual allocation. Bounded-search exhaustion is not proof that improvement is impossible.

Fault and recovery gate

  • Deterministically inject short/failing reads/writes, failed or unsupported synchronization, lost/reordered/torn writes and process/host interruption at every meaningful data, allocation, directory, dirty-state, journal/registry and persistence boundary, including both sides of the durable commit decision. Include cancellation and UI/worker disconnection.
  • Check pre-commit rollback and post-commit forward completion, retained source allocation until verified commit, creation publication/cleanup and earlier committed batch outcomes. Interrupt recovery itself and repeat it to verify idempotence through the public recover operation.
  • Exercise truncated/corrupt/unsupported journals, missing required evidence, invalid imported offsets, wrong/reused/cloned target identities, attachment-generation changes and conflicting external metadata/content changes. Refuse ambiguous replay, retain evidence and prevent a later mutation from overwriting it.
  • A passing normal-operation or successful-recovery case has independently consistent allocation/content and no repair-dependent result. Run filesystem checkers without repair on preserved test outputs; do not conceal a failure by repairing the fixture before assessment.
  • A deliberately injected fault may correctly produce safe refusal or recovery-required state. That test passes only when its specified expected outcome, preserved evidence, bounds and prohibition of further writes are verified. False success, false clean state, corruption outside the declared fault model or repair-dependent claimed success fails the gate.
  • Keep journal and target persistence domains explicit. These tests validate software under the declared modeled I/O contract; they do not establish actual controller power-loss durability.

Virtual macOS and UI gate

  • Run the native app/ordinary worker on Apple Silicon macOS 15 and current stable macOS; macOS VMs and disposable attached images are acceptable. Record exact OS builds, toolchain and virtual geometry. Build/typecheck success alone does not replace baseline runtime integration.
  • Verify authopen descriptor transfer, read-only versus read/write authority, denial/cancellation and standard-user authorization; authenticate worker/UI peers. No permanent daemon or SMAppService registration is required by the accepted ordinary-worker design.
  • Exercise whole/slice/raw/block aliases, sibling volumes, competing access, busy ordinary unmount, worker-owned claims/interlocks, UI disconnection, worker death, descriptor close, identity replacement and restoration of prior mounts. Test unsupported/failed cache synchronization and exclusivity through controlled adapters when the virtual driver cannot generate them; record actual-native versus simulated coverage.
  • Keep the thin accepted UI checks for selection, accessible full allocation map/table, capacity entry, preview/backup/preparation, stale events, progress/Stop, recovery and separate remount outcomes. Simulate IODD preparation/known-active-drive states without performing hardware trials.

Toolchain, distribution and lifecycle

  • Pin a supported stable Xcode/Swift release and exact build in the later implementation repository/CI, with an arm64 app and macOS 15 deployment minimum. Do not require beta/RC tooling. The available command-line Swift installation can support image-based work; full Xcode selection and actual baseline runtime checks remain later implementation prerequisites. Apple toolchain matrix.
  • Publish one versioned immutable DMG containing the app and bundled ordinary worker, with appropriate Developer ID component signatures, hardened runtime, secure timestamps, successful notarization and stapled tickets. Verify the final download's signatures/Gatekeeper and clean-user installation on the supported software environments. Release credentials/enrollment block signing/distribution, not core image implementation. Developer ID distribution, notarization requirements.
  • Provide a Forgejo-hosted Homebrew tap with a cask for the same final DMG, exact version/URL/SHA-256, arm64 restriction and macOS 15 minimum. Document explicit Git-URL tap setup and the fully qualified cask installation/upgrade commands. Compute the digest after final signing/stapling. No App Store or in-app updater is required for v1. Homebrew taps, Cask Cookbook.
  • Support manual app replacement and brew upgrade --cask. Update/reinstall/uninstall must wait for verified safe worker completion or refuse while an operation remains active; quitting the GUI alone is insufficient because the worker owns the operation. Do not forcibly terminate it or replace an active worker. Preserve journal-version rejection and all recovery evidence across versions.
  • Preserve authoritative journals, recovery registry and exported recovery bundles across ordinary uninstall, reinstall/upgrade and Homebrew --zap. Optional preference/cache cleanup must use narrow paths that exclude recovery evidence; never delete its parent support directory as generic cleanup. Verify both distribution paths and lifecycle/refusal outcomes on disposable software environments. Homebrew uninstall/zap behavior.

Performance and resource behavior

There are no throughput, elapsed-time, stop-latency, device-speed, benchmark or geometry-dependent performance commitments or release gates. Actual hard drives are unknown; IODD enclosures do not determine their speed. Retain the already accepted finite work limits, bounded compaction search, checked resource handling, cancellation at safe boundaries, nonblocking native presentation and truthful progress/estimates as software behavior. Concrete private implementation limits are documented implementation choices, not new device performance promises.

Staged implementation handoff

  1. Analyze a FAT32 image and Analyze an exFAT image establish the independently checked corpus and public operation boundary. The allocation-map, IODD-profile and creation-preview slices build on that foundation according to their existing dependencies.
  2. Image-backed FAT32/exFAT VHD creation, single-file defrag, Defrag All and Compact implement their accepted transaction contracts with the applicable independent and fault tests in each slice. Recover interrupted operations in the app joins creation, batches and compaction and verifies the aggregate recovery gate.
  3. Discover and analyze external host volumes qualifies the native access lifecycle using virtual volumes and controlled discovery/failure inputs. The external creation, defrag and compaction slices then integrate their software-tested engines. Enabling their write path requires passing the applicable software correctness/recovery/access evidence, not merely this decision's closed state. Their tests use virtual targets only.
  4. Qualify and package the native app joins the native workflow and external-operation implementations, reruns the required software acceptance suite on baseline/current-stable macOS, and produces the DMG, Homebrew cask and lifecycle evidence when credentials are available.

The existing implementation graph owns all this work; no new decision ticket is needed. The hosted specification indexes the resolved contracts; implementation tickets retain the detailed build work and its prerequisites. The retained local specification is the original publication snapshot, and local map/records point to the authoritative hosted answers.

All planning decisions are settled. Planning/specification remains the current authorized work; application implementation and release publication belong to the later effort. This session performed tracker/document reconciliation only, with no application tests, image mounts, physical-device access, helper installation or release publication.

## Resolution — software validation and implementation handoff Confirmed by phg on 13 October 2026: the first four answers selected software-only validation, no wait for IODD hardware qualification, a signed/notarized download plus a Homebrew tap, and no performance commitments. phg then agreed to the independent software correctness gate, virtual macOS integration gate, and complete distribution/lifecycle contract, confirming the final shared understanding. This is the authoritative validation and staged-handoff decision. It completes the planning route; it neither implements the app nor claims any test has already passed. The accepted supported-volume, engine/recovery, creation, analysis/compaction, and native-workflow contracts remain governed by their respective resolved tickets. ### Validation scope and main boundary - Validate software only. Use disposable FAT32/exFAT disk images and attached virtual volumes whenever a device-like target is needed. Physical-media read/write trials, IODD attachment/boot trials and hardware power-loss tests are outside this validation effort and are not release prerequisites. Existing physical disks, including TEST, are not fixtures. - Keep the public volume-operation API as the main boundary for analyze, preview, execute, cancel and recover. Independent tests inspect the resulting storage and observable outcomes, rather than asserting private parser/planner/journal phases. No additional public module seam is required for the handoff; a controllable storage/fault adapter belongs below that boundary. - Use a distinct, explicitly admitted fixture identity for images and virtual attachments. Preserve production discovery of all eligible external FAT32/exFAT media, including fixed media; do not globally classify disk images or devices with unknown location as external. Test production discovery decisions with controlled device descriptions and the native access lifecycle with validated disposable attachments. - Retain all runtime identity, bounds, ownership, authorization, isolation, checked synchronization, preparation, backup/preview and recovery gates. Removing hardware trials does not permit an unsupported synchronization or exclusivity operation to return fabricated success. - IODD profiles retain documented model/firmware constraints and separate format, allocation, guest initialization and eligibility results. No model, including mini, must undergo a physical trial before release. Do not label unperformed hardware qualification, firmware attachment, bootability or physical power-loss behavior as measured software evidence. ### Independent fixture and oracle gate Each implementation slice owns its applicable tests and records reproducible fixture identity, manifest, operation/settings, software versions, expected results, actual independent results and any fault schedule/seed. - Establish independently specified manifests and independently implemented FAT32/exFAT allocation/ownership readers or capable non-repairing checkers. Include original content hashes, paths/names, attributes/timestamps, logical and allocated lengths, complete extents, free runs, pinned ownership and selected-volume/sibling bounds. Do not reuse writer placement bookkeeping as the oracle. - Cover the agreed geometry envelope: all 32 FAT32 and 62 ordinary-exFAT sector/cluster pairs, consistent volume sizes, supported revisions/allocation forms, one/two FAT32 FATs and active/mirrored modes, validated MBR/GPT/partitionless and supported extended-partition layouts. Keep device logical/physical blocks, filesystem sectors, host clusters, partition origins and 512-byte VHD guest sectors distinct. Include alignment and checked-address/overflow boundaries. - Coherent sparse backing images and synthetic address/arithmetic fixtures may avoid materializing enormous media. A synthetic boundary fixture proves the declared arithmetic case, not native mount support; a sparse backing container must not substitute for a VHD's required fully initialized guest contents or complete host-volume allocation. - Exercise hidden/system/read-only files, empty files, nested/long/Unicode names, large ranges, FAT32 reserved bits/FSInfo, exFAT bitmap and chained/NoFatChain states, ValidDataLength zeros, complete spanning entry sets/checksums and preserved unrelated fields. Malformed/unsupported geometry, loops, cross-links, missing coverage and conflicting layouts must produce the accepted diagnostic/refusal result without mutation. - Compare complete snapshots, actual extent counts, largest runs, statistics and full map/selection coverage against manifests. Partial/cancelled scans withhold unsupported global claims; stale snapshots/plans and attachment replacement cannot authorize work. - Independently verify fixed VHD footer/type/checksum/fields/capacity/exact EOF, all guest zeros and one complete-file extent including footer clusters. Test the 16 MiB minimum, 1 GiB default, selected 2040 GiB ceiling, FAT32 aligned limit and one sector beyond, exact binary-unit conversion, footer/cluster overhead, collision, insufficient total/run/workspace and create-only publication rules. QEMU or another independent consumer supplements the independent footer/allocation oracles; a sparse research fixture alone is insufficient. - For defrag and batches, independently check hashes, preserved metadata/identity, complete contiguous allocation, untouched files/regions and truthful success/skip/error/Stop outcomes. Verify largest-first batch order, full-volume selection independent of display filters and halt-on-actual-failure behavior. - For Compact, verify the inclusive logical-size threshold, logical versus allocated byte accounting, move/byte limits, feasible disjoint destinations, staging plans, no-benefit/already-met-target outcomes and optional target status. Independently confirm that every committed prefix preserves the starting largest free run, and that final reported benefit matches actual allocation. Bounded-search exhaustion is not proof that improvement is impossible. ### Fault and recovery gate - Deterministically inject short/failing reads/writes, failed or unsupported synchronization, lost/reordered/torn writes and process/host interruption at every meaningful data, allocation, directory, dirty-state, journal/registry and persistence boundary, including both sides of the durable commit decision. Include cancellation and UI/worker disconnection. - Check pre-commit rollback and post-commit forward completion, retained source allocation until verified commit, creation publication/cleanup and earlier committed batch outcomes. Interrupt recovery itself and repeat it to verify idempotence through the public recover operation. - Exercise truncated/corrupt/unsupported journals, missing required evidence, invalid imported offsets, wrong/reused/cloned target identities, attachment-generation changes and conflicting external metadata/content changes. Refuse ambiguous replay, retain evidence and prevent a later mutation from overwriting it. - A passing normal-operation or successful-recovery case has independently consistent allocation/content and no repair-dependent result. Run filesystem checkers without repair on preserved test outputs; do not conceal a failure by repairing the fixture before assessment. - A deliberately injected fault may correctly produce safe refusal or recovery-required state. That test passes only when its specified expected outcome, preserved evidence, bounds and prohibition of further writes are verified. False success, false clean state, corruption outside the declared fault model or repair-dependent claimed success fails the gate. - Keep journal and target persistence domains explicit. These tests validate software under the declared modeled I/O contract; they do not establish actual controller power-loss durability. ### Virtual macOS and UI gate - Run the native app/ordinary worker on Apple Silicon macOS 15 and current stable macOS; macOS VMs and disposable attached images are acceptable. Record exact OS builds, toolchain and virtual geometry. Build/typecheck success alone does not replace baseline runtime integration. - Verify authopen descriptor transfer, read-only versus read/write authority, denial/cancellation and standard-user authorization; authenticate worker/UI peers. No permanent daemon or SMAppService registration is required by the accepted ordinary-worker design. - Exercise whole/slice/raw/block aliases, sibling volumes, competing access, busy ordinary unmount, worker-owned claims/interlocks, UI disconnection, worker death, descriptor close, identity replacement and restoration of prior mounts. Test unsupported/failed cache synchronization and exclusivity through controlled adapters when the virtual driver cannot generate them; record actual-native versus simulated coverage. - Keep the thin accepted UI checks for selection, accessible full allocation map/table, capacity entry, preview/backup/preparation, stale events, progress/Stop, recovery and separate remount outcomes. Simulate IODD preparation/known-active-drive states without performing hardware trials. ### Toolchain, distribution and lifecycle - Pin a supported stable Xcode/Swift release and exact build in the later implementation repository/CI, with an arm64 app and macOS 15 deployment minimum. Do not require beta/RC tooling. The available command-line Swift installation can support image-based work; full Xcode selection and actual baseline runtime checks remain later implementation prerequisites. [Apple toolchain matrix](https://developer.apple.com/xcode/system-requirements). - Publish one versioned immutable DMG containing the app and bundled ordinary worker, with appropriate Developer ID component signatures, hardened runtime, secure timestamps, successful notarization and stapled tickets. Verify the final download's signatures/Gatekeeper and clean-user installation on the supported software environments. Release credentials/enrollment block signing/distribution, not core image implementation. [Developer ID distribution](https://developer.apple.com/developer-id/), [notarization requirements](https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution). - Provide a Forgejo-hosted Homebrew tap with a cask for the same final DMG, exact version/URL/SHA-256, arm64 restriction and macOS 15 minimum. Document explicit Git-URL tap setup and the fully qualified cask installation/upgrade commands. Compute the digest after final signing/stapling. No App Store or in-app updater is required for v1. [Homebrew taps](https://docs.brew.sh/Taps), [Cask Cookbook](https://docs.brew.sh/Cask-Cookbook). - Support manual app replacement and brew upgrade --cask. Update/reinstall/uninstall must wait for verified safe worker completion or refuse while an operation remains active; quitting the GUI alone is insufficient because the worker owns the operation. Do not forcibly terminate it or replace an active worker. Preserve journal-version rejection and all recovery evidence across versions. - Preserve authoritative journals, recovery registry and exported recovery bundles across ordinary uninstall, reinstall/upgrade and Homebrew --zap. Optional preference/cache cleanup must use narrow paths that exclude recovery evidence; never delete its parent support directory as generic cleanup. Verify both distribution paths and lifecycle/refusal outcomes on disposable software environments. [Homebrew uninstall/zap behavior](https://docs.brew.sh/Cask-Cookbook#stanza-uninstall). ### Performance and resource behavior There are no throughput, elapsed-time, stop-latency, device-speed, benchmark or geometry-dependent performance commitments or release gates. Actual hard drives are unknown; IODD enclosures do not determine their speed. Retain the already accepted finite work limits, bounded compaction search, checked resource handling, cancellation at safe boundaries, nonblocking native presentation and truthful progress/estimates as software behavior. Concrete private implementation limits are documented implementation choices, not new device performance promises. ### Staged implementation handoff 1. [Analyze a FAT32 image](https://git.s1q.dev/phg/iodd-tool/issues/8) and [Analyze an exFAT image](https://git.s1q.dev/phg/iodd-tool/issues/9) establish the independently checked corpus and public operation boundary. The allocation-map, IODD-profile and creation-preview slices build on that foundation according to their existing dependencies. 2. Image-backed FAT32/exFAT VHD creation, single-file defrag, Defrag All and Compact implement their accepted transaction contracts with the applicable independent and fault tests in each slice. [Recover interrupted operations in the app](https://git.s1q.dev/phg/iodd-tool/issues/19) joins creation, batches and compaction and verifies the aggregate recovery gate. 3. [Discover and analyze external host volumes](https://git.s1q.dev/phg/iodd-tool/issues/20) qualifies the native access lifecycle using virtual volumes and controlled discovery/failure inputs. The external creation, defrag and compaction slices then integrate their software-tested engines. Enabling their write path requires passing the applicable software correctness/recovery/access evidence, not merely this decision's closed state. Their tests use virtual targets only. 4. [Qualify and package the native app](https://git.s1q.dev/phg/iodd-tool/issues/24) joins the native workflow and external-operation implementations, reruns the required software acceptance suite on baseline/current-stable macOS, and produces the DMG, Homebrew cask and lifecycle evidence when credentials are available. The existing implementation graph owns all this work; no new decision ticket is needed. The hosted specification indexes the resolved contracts; implementation tickets retain the detailed build work and its prerequisites. The retained local specification is the original publication snapshot, and local map/records point to the authoritative hosted answers. All planning decisions are settled. Planning/specification remains the current authorized work; application implementation and release publication belong to the later effort. This session performed tracker/document reconciliation only, with no application tests, image mounts, physical-device access, helper installation or release publication.
phg closed this issue 2026-10-13 08:29:09 +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#6
No description provided.