Skip to content

Audit part-file gap and progress arithmetic against eMuleAI hardening

Workflow status is tracked in GitHub: https://github.com/emulebb/emulebb/issues/29. This local document is retained as an engineering spec/evidence record.

Closure

Closed locally on 2026-05-24.

  • app commit d743bbd (BUG-012 BUG-119: harden part-file shutdown progress) moves completed-size and percent resolution behind a defensive helper, clamps impossible total-gap counts, handles zero-size denominator cases, and avoids overflow while aggregating gap byte counts.
  • test commit 9dcb7d7 covers valid progress, oversized malformed gaps, zero-size malformed gaps, and zero-size complete files.

Validation:

  • python -m emule_workspace validate
  • python -m emule_workspace build app --variant main --config Debug --platform x64 --build-output-mode ErrorsOnly
  • python -m emule_workspace build app --variant main --config Release --platform x64 --build-output-mode ErrorsOnly
  • Debug and Release native suites: parity.

Summary

eMuleAI contains extra hardening around part-file gaps and progress arithmetic. Current eMuleBB has several independent part-file persistence and AICH fixes, but the exact invalid-gap cleanup and denominator/percentage behavior has not been matched line-for-line. This item tracks a focused parity audit and any narrow bug fixes found by tests.

eMuleAI Implementation References

Review source: eMuleAI commit 8e34bdec2b7e4fe9e4307df9d80f691804be99ed.

Current Risk

Bad or stale gap records can produce wrong completion percentages, stale download state, or edge-case instability around corrupted .part.met data. The likely failures are rare, but the affected surface is core download correctness and should be test-driven.

Intended Fix Shape

  • Build small seam tests for empty gaps, inverted ranges, duplicate/overlapping ranges, zero-size denominator cases, and large-file boundary values.
  • Compare eMuleBB behavior against community baseline and the eMuleAI hardening intent.
  • Port only the minimum cleanup/clamp logic that fixes reproducible defects.

Acceptance Criteria

  • [ ] invalid gap records cannot produce impossible completed-size or progress percentages
  • [ ] zero-size and boundary-size files do not divide by zero or overflow
  • [ ] repaired gap state is persisted safely through existing part-file save hardening
  • [ ] tests cover both valid stock data and malformed data