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

Define analysis, defrag, and compaction success criteria #4

New issue
Closed
opened 2026-10-11 19:10:04 +00:00 by phg · 4 comments
phg commented 2026-10-11 19:10:04 +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

How should the native app preserve the original analysis/defrag/compaction workflow while reporting truthful IODD compatibility and free-space outcomes?

Separate “fragmented” from “incompatible with the selected IODD profile”: an ISO with two extents can be fragmented yet eligible, while a fragmented VHD is ineligible under the supplied policy. Decide which files appear, how Defrag All selects/prioritizes work, and whether a profile changes eligibility or merely annotations. Define full extent counts/ranges, hidden/system/long-path coverage, anomalies, scan completeness, map aggregation, file selection, stale-snapshot handling, and post-operation rescans.

For Compact, preserve small-file compaction capability but choose an explicit objective: largest-free-run growth, a requested VHD-sized free run, or another measurable goal. Decide the 1 MiB parity threshold, user controls, work caps, no-benefit results, and previews/confirmation. Do not promise every allocation problem can be solved without temporary space or moving large files. Define per-file success/skip/failure/recovery outcomes and the relationship between cancel and the already chosen safe transaction boundaries.

Resolve these product policies with the user after the relevant source/engine decisions.

Blocked by

Record ownership

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

## Parent [IODD Tool specification](https://git.s1q.dev/phg/iodd-tool/issues/7) ## Context The confirmed scope is a native Swift app for macOS 15+ on Apple Silicon, all external FAT32/exFAT disks including fixed media, and IODD mini/newer image-capable devices. Fixed VHD creation requires a valid container and verified complete-file contiguous allocation. Current work is planning and ticket publication only; implementation is a later effort. The public volume-operation API against disposable images is the confirmed main testing boundary. Type: grilling Mode: HITL ## Question How should the native app preserve the original analysis/defrag/compaction workflow while reporting truthful IODD compatibility and free-space outcomes? Separate “fragmented” from “incompatible with the selected IODD profile”: an ISO with two extents can be fragmented yet eligible, while a fragmented VHD is ineligible under the supplied policy. Decide which files appear, how Defrag All selects/prioritizes work, and whether a profile changes eligibility or merely annotations. Define full extent counts/ranges, hidden/system/long-path coverage, anomalies, scan completeness, map aggregation, file selection, stale-snapshot handling, and post-operation rescans. For Compact, preserve small-file compaction capability but choose an explicit objective: largest-free-run growth, a requested VHD-sized free run, or another measurable goal. Decide the 1 MiB parity threshold, user controls, work caps, no-benefit results, and previews/confirmation. Do not promise every allocation problem can be solved without temporary space or moving large files. Define per-file success/skip/failure/recovery outcomes and the relationship between cancel and the already chosen safe transaction boundaries. Resolve these product policies with the user after the relevant source/engine decisions. ## Blocked by - [Set the supported volume and device contract](https://git.s1q.dev/phg/iodd-tool/issues/1) - [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2) ## Record ownership This Forgejo issue governs the live implementation prerequisite. The original local planning question and its history are retained; the implementation publication index links both records. This HITL decision remains open until the user resolves it. Publication does not resolve the original decision or approve production disk writes.
phg self-assigned this 2026-10-12 12:50:35 +00:00
phg commented 2026-10-12 12:54:59 +00:00
Author
Owner
Copy link

Interview checkpoint — candidate scope, compaction goal, and previews

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

  • Analysis offers an all-file inventory with a default fragmented-files filter. Defrag All targets every movable fragmented regular file, including supported hidden/system files. The selected IODD profile adds separately qualified eligibility annotations; it does not silently change the candidate set. Provide an explicit filter for images failing the profile's allocation rule.
  • Compact aims to grow the largest free run by default and accepts an optional target free run from a failed VHD creation preview. Such a target includes the complete file's footer and cluster rounding. Completion does not promise that the target was reached.
  • Defrag File, Defrag All, and Compact each require review of the operation preview and acknowledgement of a current backup. The preview identifies files, planned movement, space/workspace requirements, skips, and work limits. A materially changed plan requires a new preview.

The reference check confirms the original small-file threshold is inclusive logical size <= 1 MiB and the cap is 100 successful moves. These are evidence, not yet accepted native policies. Ordering, controls, analysis presentation, measurable outcomes, and the final shared-understanding check remain open. This checkpoint neither resolves the ticket nor authorizes implementation or disk writes.

## Interview checkpoint — candidate scope, compaction goal, and previews phg agreed to all three recommendations in the first interview round on 12 October 2026: - Analysis offers an all-file inventory with a default fragmented-files filter. Defrag All targets every movable fragmented regular file, including supported hidden/system files. The selected IODD profile adds separately qualified eligibility annotations; it does not silently change the candidate set. Provide an explicit filter for images failing the profile's allocation rule. - Compact aims to grow the largest free run by default and accepts an optional target free run from a failed VHD creation preview. Such a target includes the complete file's footer and cluster rounding. Completion does not promise that the target was reached. - Defrag File, Defrag All, and Compact each require review of the operation preview and acknowledgement of a current backup. The preview identifies files, planned movement, space/workspace requirements, skips, and work limits. A materially changed plan requires a new preview. The reference check confirms the original small-file threshold is inclusive logical size <= 1 MiB and the cap is 100 successful moves. These are evidence, not yet accepted native policies. Ordering, controls, analysis presentation, measurable outcomes, and the final shared-understanding check remain open. This checkpoint neither resolves the ticket nor authorizes implementation or disk writes.
phg commented 2026-10-12 13:48:53 +00:00
Author
Owner
Copy link

Interview checkpoint — ordering, small-file controls, work limits, and staging

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

  • Defrag All operates on the full-volume candidate set regardless of display filters, in descending allocated size with a stable pathname tie-break. Predictable lack of a separate complete-file destination run is a per-file skip; continue after such non-mutating skips and offer Compact separately. Actual I/O, verification, ownership, journal, persistence, or identity failures halt the batch under the accepted engine contract.
  • Compact defaults to nonempty regular files with inclusive logical size <= 1 MiB, including already contiguous and supported hidden/system files. The user may explicitly raise or lower the maximum file size and review the resulting plan. Directories remain pinned. Show actual cluster-rounded allocation independently of logical size.
  • Compact defaults to at most 100 successfully committed file moves, with a configurable move limit and optional cap on the sum of allocated bytes relocated. Preview estimated copy/readback work; stop at transaction boundaries. Another operation requires fresh analysis/preview. Reaching a work cap is a limited-work result, not proof of achieving the objective.
  • Compact may use staging moves without immediate free-run improvement, but a bounded plan must predict a final largest free run greater than the starting value, and every committed prefix must preserve at least the starting largest-run size. Decline plans with no predicted benefit; stop when an optional target is reached. Report actual before/after sizes, including safely cancelled work that moved files but produced no free-run improvement.

All seven interview choices so far are agreed. Analysis presentation and observable result semantics, followed by the final shared-understanding check, remain. This checkpoint does not resolve the ticket or authorize implementation or physical-media writes.

## Interview checkpoint — ordering, small-file controls, work limits, and staging phg agreed to all four recommendations in the second interview round on 12 October 2026: - Defrag All operates on the full-volume candidate set regardless of display filters, in descending allocated size with a stable pathname tie-break. Predictable lack of a separate complete-file destination run is a per-file skip; continue after such non-mutating skips and offer Compact separately. Actual I/O, verification, ownership, journal, persistence, or identity failures halt the batch under the accepted engine contract. - Compact defaults to nonempty regular files with inclusive logical size <= 1 MiB, including already contiguous and supported hidden/system files. The user may explicitly raise or lower the maximum file size and review the resulting plan. Directories remain pinned. Show actual cluster-rounded allocation independently of logical size. - Compact defaults to at most 100 successfully committed file moves, with a configurable move limit and optional cap on the sum of allocated bytes relocated. Preview estimated copy/readback work; stop at transaction boundaries. Another operation requires fresh analysis/preview. Reaching a work cap is a limited-work result, not proof of achieving the objective. - Compact may use staging moves without immediate free-run improvement, but a bounded plan must predict a final largest free run greater than the starting value, and every committed prefix must preserve at least the starting largest-run size. Decline plans with no predicted benefit; stop when an optional target is reached. Report actual before/after sizes, including safely cancelled work that moved files but produced no free-run improvement. All seven interview choices so far are agreed. Analysis presentation and observable result semantics, followed by the final shared-understanding check, remain. This checkpoint does not resolve the ticket or authorize implementation or physical-media writes.
phg commented 2026-10-12 14:06:12 +00:00
Author
Owner
Copy link

Interview checkpoint — analysis, stale results, outcomes, and read-only attributes

phg agreed to all four remaining recommendations on 12 October 2026:

  • One verified snapshot supplies statistics, inventory, real extent counts, complete ranges and the full data-cluster map. Mixed cells show free/allocated/unknown proportions and exact textual detail. Account for pinned directory/system allocation and highlight every selected extent intersection without display coverage caps.
  • Keep verified partial findings from cancelled/incomplete analysis explicitly labelled with coverage; withhold global metrics and eligibility conclusions needing missing evidence and disable mutations. Earlier complete results are historical/stale. After safe mutation or Stop obtain a fresh full snapshot. Preserve selection only through revalidated identity; recovery-required states remain blocked.
  • Keep per-file verified success, skips, failures, cancellation, recovery-required and not-started outcomes alongside the measured overall result. Defrag success requires complete-file contiguity and preserved contents/metadata. Compact reports actual free-run change and target status separately from successful moves; capped/cancelled work can have no benefit. No-change and remount outcomes are explicit and separate.
  • A regular file's FAT32/exFAT read-only attribute alone does not prevent relocation when ordinary write gates pass. Preserve its contents, identity and read-only attribute. A read-only host volume remains mutation-ineligible; unsupported metadata retains the engine's rejection rules.

All eleven interview choices are agreed. Only the final shared-understanding check remains before publishing the combined resolution, closing this decision and updating its map/context pointers. Planning-only scope is unchanged.

## Interview checkpoint — analysis, stale results, outcomes, and read-only attributes phg agreed to all four remaining recommendations on 12 October 2026: - One verified snapshot supplies statistics, inventory, real extent counts, complete ranges and the full data-cluster map. Mixed cells show free/allocated/unknown proportions and exact textual detail. Account for pinned directory/system allocation and highlight every selected extent intersection without display coverage caps. - Keep verified partial findings from cancelled/incomplete analysis explicitly labelled with coverage; withhold global metrics and eligibility conclusions needing missing evidence and disable mutations. Earlier complete results are historical/stale. After safe mutation or Stop obtain a fresh full snapshot. Preserve selection only through revalidated identity; recovery-required states remain blocked. - Keep per-file verified success, skips, failures, cancellation, recovery-required and not-started outcomes alongside the measured overall result. Defrag success requires complete-file contiguity and preserved contents/metadata. Compact reports actual free-run change and target status separately from successful moves; capped/cancelled work can have no benefit. No-change and remount outcomes are explicit and separate. - A regular file's FAT32/exFAT read-only attribute alone does not prevent relocation when ordinary write gates pass. Preserve its contents, identity and read-only attribute. A read-only host volume remains mutation-ineligible; unsupported metadata retains the engine's rejection rules. All eleven interview choices are agreed. Only the final shared-understanding check remains before publishing the combined resolution, closing this decision and updating its map/context pointers. Planning-only scope is unchanged.
phg commented 2026-10-12 14:11:05 +00:00
Author
Owner
Copy link

Resolution — analysis, defrag, and compaction success criteria

Confirmed by phg on 12 October 2026 through eleven agreed interview choices and the final shared-understanding check. This hosted resolution is the authoritative product contract; the map and retained local indexes link here.

Current scope remains planning and specification only. The supported volume envelope and IODD evidence rules remain Set the supported volume and device contract; the offline worker, ownership, verification, journal, cancellation, and recovery rules remain Choose the filesystem engine and recoverable mutation contract. No production implementation or physical-media writes are authorized here.

Analysis and coverage

  • Full Analyze uses the accepted read-only offline engine and produces one consistent, target-bound verified snapshot. Derive geometry, data-cluster capacity, used/free totals, largest free run, file counts, fragmentation counts, file rows, and map summaries from that same snapshot. Distinguish logical file sizes from actual cluster-rounded allocations; do not substitute cached free-space hints for verified ownership.
  • Inventory all supported regular files, including nonfragmented and empty files, nested or leading-dot directories, hidden/system/read-only attributes, Unicode names, and long paths. Do not reproduce the reference's 512-byte path cutoff or silently omit a subtree. Report regular-file and nonempty-file counts with clear semantics rather than conflating them with directory entries.
  • Show actual extent counts and complete extent ranges with inspectable cluster coordinates and selected-volume-relative byte ranges. Cover each file's complete allocation, including footer-bearing clusters. Empty files are not one-extent defrag successes; expose any allocation they actually own. Virtualize or paginate presentation when needed without truncating measured coverage.
  • Account for directories and filesystem-owned allocations as understood pinned ownership. Unknown allocation is never free space. Loops, cross-links, out-of-bounds references, inconsistent ownership, invalid supported metadata, missing directory coverage, or unsupported allocation semantics are explicit anomalies governed by the engine contract; no silent repair is included.
  • Cancelled, failed, or incomplete analysis may retain verified partial findings with declared coverage and causes. Withhold global metrics and eligibility conclusions that depend on missing coverage, and disable mutation. Locally verified observations must not be labelled exact global totals, the volume's largest free run, or proof of a clean volume.
  • Earlier complete results may remain visible only as historical/as-analyzed results and, when invalidated, clearly stale. Removal, attachment replacement, identity conflict, changed metadata, or failed revalidation invalidates plans. Before mutation obtain the engine's fresh exclusive-access scan and validate all plan preconditions; materially changed work needs a renewed preview. Preserve file selection across refresh only when its actual identity is revalidated, not merely its path.

File list, map, and IODD annotations

  • Offer an all-file inventory with a default fragmented-files filter. Filtering changes presentation; it does not silently change Defrag All's full-volume candidate set. Provide an explicit filter for images failing the selected profile's allocation rule, and preserve unknown/unassessed results as such.
  • IODD profiles add evidence-qualified annotations. Keep measured fragmentation, image/container validity, guest initialization, documented model/firmware allocation requirements, hardware qualification, and bootability separate. Changing a profile does not authorize or suppress ordinary filesystem work.
  • A two-extent ISO is fragmented and remains a Defrag All candidate even when it passes the profile's documented allocation rule. Apply the researched allowance of at most 24 extents only to its stated profile/evidence scope. A VHD requires one complete-file extent, including its footer; allocation alone does not establish format validity or hardware acceptance.
  • The allocation map covers the complete data-cluster range and accounts for free, allocated, and unknown coverage, with directory/system/pinned ownership available in detail. Mixed cells show proportions and exact counts rather than allowing one fragmented or allocated cluster to imply that the entire cell has that state.
  • Fragmentation and selected-file highlights represent every applicable extent intersection, including partial-cell coverage, without the reference's 4,096/8,192-cluster caps. Provide exact textual ranges, cell summaries, and accessible non-color descriptions. Final visual layout and interaction are for the existing workflow prototype decision.

Defrag File and Defrag All

  • Defrag File operates on the revalidated selected regular file. Defrag All considers every movable fragmented regular file on the selected host volume, including supported hidden/system/read-only files, regardless of display filters or IODD annotations. Known pinned/unmovable files remain explainable skips; unsupported or unknown ownership still blocks the volume under the engine contract.
  • A regular file's read-only attribute alone does not pin it. Relocation must preserve that attribute, all other supported metadata, logical contents and directory identity. A read-only host volume remains mutation-ineligible.
  • Order Defrag All by descending allocated byte size with a stable pathname tie-break. Freeze and disclose the candidate set/order in the preview; do not add newly discovered files or change substantive work silently. Track allocation changes from earlier verified transactions under the engine contract.
  • Each defrag requires a separate wholly free run sufficient for the complete source allocation while retaining its original allocation until verified commit. Neither aggregate free space nor a smaller partial placement satisfies defrag. Report insufficient destination space as a predictable non-mutating skip and continue to the remaining candidates; offer Compact as a separate reviewed operation.
  • Empty or already contiguous files are explicit no-change/skipped outcomes. A moved file succeeds only after contents and preserved metadata are verified and its complete resulting allocation is one extent, followed by the accepted commit/cleanup checks.
  • Continue only after predictable non-mutating preflight skips. Unexpected ownership or allocation changes invalidate work; they are not ordinary insufficient-space skips. Halt on actual I/O, content/metadata verification, ownership, identity, journal, or persistence failure, including when rollback succeeds. Do not reproduce the reference's continue-after-error behavior.

Compact candidates, goal, and work limits

  • Compact consolidates free space rather than merely reducing individual extent counts. Its default objective is growth of the largest free run. An optional target free run is a requested minimum contiguous host allocation; when carried from VHD creation it includes the complete file, footer, and cluster rounding from Define fixed VHD creation and allocation failure behavior. Metadata/workspace budgets remain separate.
  • If the existing largest run already meets a requested target, report target already met with no movement. Create never silently runs Compact. After separately requested Compact, creation still requires fresh analysis, renewed preview, and an explicit retry.
  • Default candidates are nonempty regular files with inclusive logical size <= 1 MiB (1,048,576 bytes), including already contiguous and supported hidden/system/read-only files. The user may explicitly lower or raise the maximum file size and review the resulting plan. Do not silently include larger files to rescue a failed target. Directories and understood non-movable structures remain pinned.
  • Logical size and allocation are separate: a qualifying file can occupy a 32 MiB exFAT cluster. Show actual allocations and destination/workspace requirements. Relocation uses the existing disjoint-destination transaction; there is no in-place cycle, directory relocation, external temporary-copy mode, or guarantee that every layout can be improved.
  • Default to at most 100 successfully committed file moves per operation. Permit a configurable finite positive move limit and an optional cap on the sum of allocated bytes relocated. State the chosen threshold and caps before execution, alongside estimated logical copy/readback work. Do not equate allocated bytes with elapsed time or promise a fixed duration.
  • Construct a bounded plan within the declared candidate, space, and work limits. A planned sequence must predict a final largest free run strictly greater than its starting value. Staging moves may leave that metric unchanged, but every committed prefix must preserve at least the starting largest-run size. This permits useful multi-move sequences without accepting a smaller largest run on safe cancellation.
  • Check benefit under complete allocation simulation and current ownership, not a separate approximate dry-run algorithm. Each move's complete destination and retained source must be feasible. Planner search/resource budgets and measured performance expectations belong in the existing validation/handoff decision; no globally optimal packing algorithm is promised.
  • Decline movement when no beneficial plan is found within the declared bounds. State the limiting reason, including candidate/pinned-layout restrictions, workspace, work cap, or bounded search; this does not prove that improvement is mathematically impossible. Raising a threshold or cap is an explicit new operation with fresh analysis/preview.
  • Stop when the optional target is reached, the reviewed plan ends, a work limit is reached, the user requests Stop, or an engine failure halts work. Do not automatically exceed limits, start a second batch, or adopt another goal. Every successfully moved file must still satisfy the accepted content, metadata, allocation, and transaction verification contract.
  • Measure the resulting largest run independently. Report before/after sizes, moved-file count and allocated bytes, observed content work, target status, and stop/limiting reason. Successful file moves are distinct from achieved free-space benefit. A safely cancelled staging prefix may have moved files yet produced zero largest-run growth; label that outcome accurately.

Previews, outcomes, cancellation, and freshness

  • Defrag File, Defrag All, and Compact each require a reviewed operation preview and acknowledgement of a current backup. Identify the target, candidate files/order, known skips/pinned files, predicted movement/benefit, complete destination and metadata/journal workspace requirements, Compact settings/caps, and relevant qualification limits. Acknowledgement is per operation; material changes require renewed review.
  • Retain per-file verified success, skip with reason, failure, cancellation, recovery-required state, and not-started outcomes, with a separate overall operation result. Distinguish rejection/no change, all requested work verified, partial/limited work, safe cancellation, failed but conclusively rolled back work, and recovery required. Preserve phase/cause and earlier committed outcomes.
  • Defrag success means the verified contiguous file; Compact's operation result means its measured free-space objective and target status. Neither a completed progress bar nor 100 successful moves implies that every file was processed or that a target free run exists. Explicit no-change results cover already satisfied targets and no beneficial plan found.
  • Stop/UI disconnection follows the accepted commit boundary: before commit, roll back the current transaction; after commit, finish source release/verification then start no further transaction. Display Stopping safely during cleanup. Earlier committed files remain completed. Failed cleanup or uncertain consistency leaves recovery required; never discard unresolved evidence to proceed.
  • After successful work or safe cancellation, and after a conclusively safe failure where the device remains available, perform the engine's fresh full allocation/consistency analysis before presenting a current final state and releasing/restoring access. If full verification cannot finish, present partial/stale diagnostics and the required blocked/recovery state rather than a fabricated clean result.
  • Remount status is separate from durable file and free-space outcomes. A verified move or achieved free run can coexist with remount failure. Reconnection, uncertain target state, or unresolved recovery requires the already accepted identity, isolation, and explicit recovery workflow.

Remaining route and evidence

No additional decision ticket is needed. Exact presentation and user feedback belong in Validate the native analysis and VHD creation workflows; independent analysis/compaction oracles, threshold/cap/prefix/no-benefit cases, bounded resource/responsiveness expectations, release gates and staged implementation belong in Set validation gates and the implementation handoff. The former remains the next unblocked decision after this resolution.

Reference evidence is indexed by docs/reference-baseline.md and the retained application-behavior/disk-engine reports in the neighboring rea_fatdefrag checkout. Delegated read-only worker /root/analysis_compaction_reference confirmed the inclusive logical 1 MiB threshold, 100 successful-move limit, scan-order batching, leading-dot/long-path omissions, and capped/inaccurate map/count behavior. The original mutation paths were not successfully runtime-qualified. These observations explain the corrections; recovered implementation is not the production engine.

The interview checkpoint comments retain the choices. phg confirmed the combined contract before closure. The glossary records target free run separately from total free capacity and image virtual capacity.

## Resolution — analysis, defrag, and compaction success criteria Confirmed by phg on 12 October 2026 through eleven agreed interview choices and the final shared-understanding check. This hosted resolution is the authoritative product contract; the map and retained local indexes link here. Current scope remains planning and specification only. The supported volume envelope and IODD evidence rules remain [Set the supported volume and device contract](https://git.s1q.dev/phg/iodd-tool/issues/1); the offline worker, ownership, verification, journal, cancellation, and recovery rules remain [Choose the filesystem engine and recoverable mutation contract](https://git.s1q.dev/phg/iodd-tool/issues/2). No production implementation or physical-media writes are authorized here. ### Analysis and coverage - Full Analyze uses the accepted read-only offline engine and produces one consistent, target-bound verified snapshot. Derive geometry, data-cluster capacity, used/free totals, largest free run, file counts, fragmentation counts, file rows, and map summaries from that same snapshot. Distinguish logical file sizes from actual cluster-rounded allocations; do not substitute cached free-space hints for verified ownership. - Inventory all supported regular files, including nonfragmented and empty files, nested or leading-dot directories, hidden/system/read-only attributes, Unicode names, and long paths. Do not reproduce the reference's 512-byte path cutoff or silently omit a subtree. Report regular-file and nonempty-file counts with clear semantics rather than conflating them with directory entries. - Show actual extent counts and complete extent ranges with inspectable cluster coordinates and selected-volume-relative byte ranges. Cover each file's complete allocation, including footer-bearing clusters. Empty files are not one-extent defrag successes; expose any allocation they actually own. Virtualize or paginate presentation when needed without truncating measured coverage. - Account for directories and filesystem-owned allocations as understood pinned ownership. Unknown allocation is never free space. Loops, cross-links, out-of-bounds references, inconsistent ownership, invalid supported metadata, missing directory coverage, or unsupported allocation semantics are explicit anomalies governed by the engine contract; no silent repair is included. - Cancelled, failed, or incomplete analysis may retain verified partial findings with declared coverage and causes. Withhold global metrics and eligibility conclusions that depend on missing coverage, and disable mutation. Locally verified observations must not be labelled exact global totals, the volume's largest free run, or proof of a clean volume. - Earlier complete results may remain visible only as historical/as-analyzed results and, when invalidated, clearly stale. Removal, attachment replacement, identity conflict, changed metadata, or failed revalidation invalidates plans. Before mutation obtain the engine's fresh exclusive-access scan and validate all plan preconditions; materially changed work needs a renewed preview. Preserve file selection across refresh only when its actual identity is revalidated, not merely its path. ### File list, map, and IODD annotations - Offer an all-file inventory with a default fragmented-files filter. Filtering changes presentation; it does not silently change Defrag All's full-volume candidate set. Provide an explicit filter for images failing the selected profile's allocation rule, and preserve unknown/unassessed results as such. - IODD profiles add evidence-qualified annotations. Keep measured fragmentation, image/container validity, guest initialization, documented model/firmware allocation requirements, hardware qualification, and bootability separate. Changing a profile does not authorize or suppress ordinary filesystem work. - A two-extent ISO is fragmented and remains a Defrag All candidate even when it passes the profile's documented allocation rule. Apply the researched allowance of at most 24 extents only to its stated profile/evidence scope. A VHD requires one complete-file extent, including its footer; allocation alone does not establish format validity or hardware acceptance. - The allocation map covers the complete data-cluster range and accounts for free, allocated, and unknown coverage, with directory/system/pinned ownership available in detail. Mixed cells show proportions and exact counts rather than allowing one fragmented or allocated cluster to imply that the entire cell has that state. - Fragmentation and selected-file highlights represent every applicable extent intersection, including partial-cell coverage, without the reference's 4,096/8,192-cluster caps. Provide exact textual ranges, cell summaries, and accessible non-color descriptions. Final visual layout and interaction are for the existing workflow prototype decision. ### Defrag File and Defrag All - Defrag File operates on the revalidated selected regular file. Defrag All considers every movable fragmented regular file on the selected host volume, including supported hidden/system/read-only files, regardless of display filters or IODD annotations. Known pinned/unmovable files remain explainable skips; unsupported or unknown ownership still blocks the volume under the engine contract. - A regular file's read-only attribute alone does not pin it. Relocation must preserve that attribute, all other supported metadata, logical contents and directory identity. A read-only host volume remains mutation-ineligible. - Order Defrag All by descending allocated byte size with a stable pathname tie-break. Freeze and disclose the candidate set/order in the preview; do not add newly discovered files or change substantive work silently. Track allocation changes from earlier verified transactions under the engine contract. - Each defrag requires a separate wholly free run sufficient for the complete source allocation while retaining its original allocation until verified commit. Neither aggregate free space nor a smaller partial placement satisfies defrag. Report insufficient destination space as a predictable non-mutating skip and continue to the remaining candidates; offer Compact as a separate reviewed operation. - Empty or already contiguous files are explicit no-change/skipped outcomes. A moved file succeeds only after contents and preserved metadata are verified and its complete resulting allocation is one extent, followed by the accepted commit/cleanup checks. - Continue only after predictable non-mutating preflight skips. Unexpected ownership or allocation changes invalidate work; they are not ordinary insufficient-space skips. Halt on actual I/O, content/metadata verification, ownership, identity, journal, or persistence failure, including when rollback succeeds. Do not reproduce the reference's continue-after-error behavior. ### Compact candidates, goal, and work limits - Compact consolidates free space rather than merely reducing individual extent counts. Its default objective is growth of the largest free run. An optional target free run is a requested minimum contiguous host allocation; when carried from VHD creation it includes the complete file, footer, and cluster rounding from [Define fixed VHD creation and allocation failure behavior](https://git.s1q.dev/phg/iodd-tool/issues/3). Metadata/workspace budgets remain separate. - If the existing largest run already meets a requested target, report target already met with no movement. Create never silently runs Compact. After separately requested Compact, creation still requires fresh analysis, renewed preview, and an explicit retry. - Default candidates are nonempty regular files with inclusive logical size <= 1 MiB (1,048,576 bytes), including already contiguous and supported hidden/system/read-only files. The user may explicitly lower or raise the maximum file size and review the resulting plan. Do not silently include larger files to rescue a failed target. Directories and understood non-movable structures remain pinned. - Logical size and allocation are separate: a qualifying file can occupy a 32 MiB exFAT cluster. Show actual allocations and destination/workspace requirements. Relocation uses the existing disjoint-destination transaction; there is no in-place cycle, directory relocation, external temporary-copy mode, or guarantee that every layout can be improved. - Default to at most 100 successfully committed file moves per operation. Permit a configurable finite positive move limit and an optional cap on the sum of allocated bytes relocated. State the chosen threshold and caps before execution, alongside estimated logical copy/readback work. Do not equate allocated bytes with elapsed time or promise a fixed duration. - Construct a bounded plan within the declared candidate, space, and work limits. A planned sequence must predict a final largest free run strictly greater than its starting value. Staging moves may leave that metric unchanged, but every committed prefix must preserve at least the starting largest-run size. This permits useful multi-move sequences without accepting a smaller largest run on safe cancellation. - Check benefit under complete allocation simulation and current ownership, not a separate approximate dry-run algorithm. Each move's complete destination and retained source must be feasible. Planner search/resource budgets and measured performance expectations belong in the existing validation/handoff decision; no globally optimal packing algorithm is promised. - Decline movement when no beneficial plan is found within the declared bounds. State the limiting reason, including candidate/pinned-layout restrictions, workspace, work cap, or bounded search; this does not prove that improvement is mathematically impossible. Raising a threshold or cap is an explicit new operation with fresh analysis/preview. - Stop when the optional target is reached, the reviewed plan ends, a work limit is reached, the user requests Stop, or an engine failure halts work. Do not automatically exceed limits, start a second batch, or adopt another goal. Every successfully moved file must still satisfy the accepted content, metadata, allocation, and transaction verification contract. - Measure the resulting largest run independently. Report before/after sizes, moved-file count and allocated bytes, observed content work, target status, and stop/limiting reason. Successful file moves are distinct from achieved free-space benefit. A safely cancelled staging prefix may have moved files yet produced zero largest-run growth; label that outcome accurately. ### Previews, outcomes, cancellation, and freshness - Defrag File, Defrag All, and Compact each require a reviewed operation preview and acknowledgement of a current backup. Identify the target, candidate files/order, known skips/pinned files, predicted movement/benefit, complete destination and metadata/journal workspace requirements, Compact settings/caps, and relevant qualification limits. Acknowledgement is per operation; material changes require renewed review. - Retain per-file verified success, skip with reason, failure, cancellation, recovery-required state, and not-started outcomes, with a separate overall operation result. Distinguish rejection/no change, all requested work verified, partial/limited work, safe cancellation, failed but conclusively rolled back work, and recovery required. Preserve phase/cause and earlier committed outcomes. - Defrag success means the verified contiguous file; Compact's operation result means its measured free-space objective and target status. Neither a completed progress bar nor 100 successful moves implies that every file was processed or that a target free run exists. Explicit no-change results cover already satisfied targets and no beneficial plan found. - Stop/UI disconnection follows the accepted commit boundary: before commit, roll back the current transaction; after commit, finish source release/verification then start no further transaction. Display Stopping safely during cleanup. Earlier committed files remain completed. Failed cleanup or uncertain consistency leaves recovery required; never discard unresolved evidence to proceed. - After successful work or safe cancellation, and after a conclusively safe failure where the device remains available, perform the engine's fresh full allocation/consistency analysis before presenting a current final state and releasing/restoring access. If full verification cannot finish, present partial/stale diagnostics and the required blocked/recovery state rather than a fabricated clean result. - Remount status is separate from durable file and free-space outcomes. A verified move or achieved free run can coexist with remount failure. Reconnection, uncertain target state, or unresolved recovery requires the already accepted identity, isolation, and explicit recovery workflow. ### Remaining route and evidence No additional decision ticket is needed. Exact presentation and user feedback belong in [Validate the native analysis and VHD creation workflows](https://git.s1q.dev/phg/iodd-tool/issues/5); independent analysis/compaction oracles, threshold/cap/prefix/no-benefit cases, bounded resource/responsiveness expectations, release gates and staged implementation belong in [Set validation gates and the implementation handoff](https://git.s1q.dev/phg/iodd-tool/issues/6). The former remains the next unblocked decision after this resolution. Reference evidence is indexed by docs/reference-baseline.md and the retained application-behavior/disk-engine reports in the neighboring rea_fatdefrag checkout. Delegated read-only worker /root/analysis_compaction_reference confirmed the inclusive logical 1 MiB threshold, 100 successful-move limit, scan-order batching, leading-dot/long-path omissions, and capped/inaccurate map/count behavior. The original mutation paths were not successfully runtime-qualified. These observations explain the corrections; recovered implementation is not the production engine. The interview checkpoint comments retain the choices. phg confirmed the combined contract before closure. The glossary records target free run separately from total free capacity and image virtual capacity.
phg closed this issue 2026-10-12 14:11:05 +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#4
No description provided.