Defragment a file on a FAT32 image #15

New issue

Closed

opened 2026-10-11 19:10:44 +00:00 by phg · 1 comment

phg commented

2026-10-11 19:10:44 +00:00

Owner

Parent

IODD Tool specification

What to build

Select one fragmented file, review its relocation preview, confirm, and move it to one free run on a FAT32 image with a verified final result.

Acceptance criteria

A selected file has a preview showing intended movement, required destination run, eligibility/skip reasons, and the agreed confirmation.
Execution preserves contents and relevant metadata while producing one complete extent and an independently verified fresh analysis.
Empty/already-contiguous files, inadequate contiguous space, stale identities, and allocation anomalies have explicit outcomes.
FAT32 reserved bits, mirrored/active FATs, FSInfo, and exact directory-entry persistence are correct under independent fixtures.
The original live allocation is retained until the new ownership is durable and recoverable under the approved protocol.
Progress and cancellation reach the chosen safe boundary; ambiguous failures preserve evidence and prohibit another mutation.
Fault injection across each meaningful write/flush boundary verifies content/ownership and idempotent recovery through the operation API.
Independent hashes, metadata manifests, allocation ownership, and untouched regions validate success and safe failure.

Blocked by

Validation contract

Completion requires the applicable independently checked software evidence in Set validation gates and the implementation handoff. A closed policy decision does not establish that implementation tests have passed. Use disposable images/virtual volumes and controlled faults; no hardware-trial or performance gate applies.

Scope

This ticket belongs to the later implementation effort. All planning decisions are resolved; current work covers tracker and documentation updates. The parent specification indexes the authoritative product and software-validation contracts. Forgejo governs live updates; retained local files record the handoff.

## Parent [IODD Tool specification](https://git.s1q.dev/phg/iodd-tool/issues/7) ## What to build Select one fragmented file, review its relocation preview, confirm, and move it to one free run on a FAT32 image with a verified final result. ## Acceptance criteria - [ ] A selected file has a preview showing intended movement, required destination run, eligibility/skip reasons, and the agreed confirmation. - [ ] Execution preserves contents and relevant metadata while producing one complete extent and an independently verified fresh analysis. - [ ] Empty/already-contiguous files, inadequate contiguous space, stale identities, and allocation anomalies have explicit outcomes. - [ ] FAT32 reserved bits, mirrored/active FATs, FSInfo, and exact directory-entry persistence are correct under independent fixtures. - [ ] The original live allocation is retained until the new ownership is durable and recoverable under the approved protocol. - [ ] Progress and cancellation reach the chosen safe boundary; ambiguous failures preserve evidence and prohibit another mutation. - [ ] Fault injection across each meaningful write/flush boundary verifies content/ownership and idempotent recovery through the operation API. - [ ] Independent hashes, metadata manifests, allocation ownership, and untouched regions validate success and safe failure. ## Blocked by - [Analyze a FAT32 image](https://git.s1q.dev/phg/iodd-tool/issues/8) - [Define analysis, defrag, and compaction success criteria](https://git.s1q.dev/phg/iodd-tool/issues/4) ## Validation contract Completion requires the applicable independently checked software evidence in [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6). A closed policy decision does not establish that implementation tests have passed. Use disposable images/virtual volumes and controlled faults; no hardware-trial or performance gate applies. ## Scope This ticket belongs to the later implementation effort. All planning decisions are resolved; current work covers tracker and documentation updates. The parent specification indexes the authoritative product and software-validation contracts. Forgejo governs live updates; retained local files record the handoff.

phg added the

ready-for-agent

label

2026-10-11 19:10:45 +00:00

phg referenced this issue

2026-10-11 19:10:45 +00:00

Defragment a file on an exFAT image #16

phg self-assigned this

2026-10-13 10:33:34 +00:00

phg referenced this issue from a commit

2026-10-13 15:43:17 +00:00

Merge ticket #15: defragment FAT32 images with recoverable mutation

phg commented

2026-10-13 15:45:26 +00:00

Author

Owner

Resolution — FAT32 image defragmentation and shared recovery foundation implemented

Implemented on implement/iodd-tool-spec-7, implementation c605d71, integration merge 950e500.

The public preview/confirm/execute/Stop workflow moves complete FAT32 file allocation into the exact reviewed free run, verifies contents before publication, preserves source allocation until the checked durable commit, and updates required FAT copies, entry location and valid FSInfo hints. The reusable bounded journal driver owns full physical-unit before/after images, checked internal persistence, discovery registry, source-free creation support, logged rollback/forward replay and exact durable retirement. Recovery refuses foreign/corrupt/unsupported/ambiguous evidence and regenerates allowed writes from verified original metadata. Complete-but-unretired evidence remains actionable and preserved. Physical-unit-aware preview avoids shared pinned boundaries; stale-unit previews refuse before writes. Regular-image writes validate admitted length and bounds; owned open-description locks are explicitly released.

Validation: final production/test implementation8ad5ae5 passed83 tests in545.429s on Xcode27.0/27A266a, including1018 initial/replay/transfer fault cases, all32 FAT32 geometry pairs, imported geometry/authority corruption, completion retirement, directory persistence, external truncation and a deterministic inherited-descriptor regression. Evidence-only c605d71 and integration950e500 have identical verified Sources/Tests trees. Integration focused checks, arm64 release, minimumOS15 and plist checks pass. Native owned-image workflow passed explicit preparation+backup+review+Confirm, exact7–9 destination and fresh completed inventory; independent allocated/logical hashes, untouched-region SHA and nonrepairing fsck pass. Earlier exact9a22 public core also passed on actual guestmacOS15.7.7/24G720; that historical scope is recorded separately.

Reproducible validation, complete logs and native screenshot. Qualification covers disposable regular images/internal recovery storage. Raw-device authentication/exclusion/remount and signed/notarized release gates remain their later tickets. Existing default recovery evidence is preserved.

## Resolution — FAT32 image defragmentation and shared recovery foundation implemented Implemented on [implement/iodd-tool-spec-7](https://git.s1q.dev/phg/iodd-tool/src/branch/implement/iodd-tool-spec-7), implementation [c605d71](https://git.s1q.dev/phg/iodd-tool/commit/c605d71fae7e10529576ddef6e9b5616b5e6c8f1), integration merge [950e500](https://git.s1q.dev/phg/iodd-tool/commit/950e50048e6d8ba0e110517a637c12fe1e3116e0). The public preview/confirm/execute/Stop workflow moves complete FAT32 file allocation into the exact reviewed free run, verifies contents before publication, preserves source allocation until the checked durable commit, and updates required FAT copies, entry location and valid FSInfo hints. The reusable bounded journal driver owns full physical-unit before/after images, checked internal persistence, discovery registry, source-free creation support, logged rollback/forward replay and exact durable retirement. Recovery refuses foreign/corrupt/unsupported/ambiguous evidence and regenerates allowed writes from verified original metadata. Complete-but-unretired evidence remains actionable and preserved. Physical-unit-aware preview avoids shared pinned boundaries; stale-unit previews refuse before writes. Regular-image writes validate admitted length and bounds; owned open-description locks are explicitly released. Validation: final production/test implementation8ad5ae5 passed83 tests in545.429s on Xcode27.0/27A266a, including1018 initial/replay/transfer fault cases, all32 FAT32 geometry pairs, imported geometry/authority corruption, completion retirement, directory persistence, external truncation and a deterministic inherited-descriptor regression. Evidence-only c605d71 and integration950e500 have identical verified Sources/Tests trees. Integration focused checks, arm64 release, minimumOS15 and plist checks pass. Native owned-image workflow passed explicit preparation+backup+review+Confirm, exact7–9 destination and fresh completed inventory; independent allocated/logical hashes, untouched-region SHA and nonrepairing fsck pass. Earlier exact9a22 public core also passed on actual guestmacOS15.7.7/24G720; that historical scope is recorded separately. [Reproducible validation, complete logs and native screenshot](https://git.s1q.dev/phg/iodd-tool/src/commit/950e50048e6d8ba0e110517a637c12fe1e3116e0/docs/validation/fat32-defragmentation.md). Qualification covers disposable regular images/internal recovery storage. Raw-device authentication/exclusion/remount and signed/notarized release gates remain their later tickets. Existing default recovery evidence is preserved.

phg closed this issue

2026-10-13 15:45:26 +00:00

phg referenced this issue

2026-10-13 15:45:55 +00:00

IODD Tool specification #7