fix(core): surface partial external-signer merkle uploads as PartialUpload

[Nic-dorman]

Linear issue

V2-944

Fixes #166.

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

Compatibility

• Wire: none
• Storage: none
• API: no signature or type changes. Behavioral: Client::finalize_upload_merkle(_with_progress) now returns Err(Error::PartialUpload) when chunks remain short of quorum after all retries, where it previously returned Ok with chunks_failed > 0. This matches the wave-batch finalize's existing contract and FileUploadResult::chunks_failed's own documented contract ("Always 0 for a successful upload — partial-failure information is conveyed via PartialUpload instead"). Callers that inspected chunks_failed keep working (it is now always 0 on Ok); callers that ignored it — every known one: desktop app, mobile FFI — stop reporting paid, partially stored, unretrievable files as complete.

Semver impact

• breaking
• feature
• fix

Test evidence

• 2 new unit tests on the extracted merkle_finalize_result fold: quorum shortfall → PartialUpload with correct stored/failed address sets (preflight carry-ins included in stored, no address expected for them), and full success → identical previous Ok shape with chunks_failed == 0.
• cargo test -p ant-core --lib: 432/432 pass.
• cargo clippy --all-targets --all-features -- -D warnings and cargo fmt --all -- --check clean.

New dependency

none

ADR

n/a

Mitigation / rollback

Single-commit revert restores the old semantics; a caller needing the previous behavior can match Error::PartialUpload, which carries the same counts the Ok used to (plus the failed addresses).

Notes

• The PartialUpload::spend is reported as 0 — the external signer pays on-chain out-of-band, so the spend is unknown to the library here (same as the Ok arm's storage_cost_atto: "0").
• Relationship to external-signer finalize: post-payment storage failure strands the payment (PreparedUpload consumed, not retryable) #140: this makes the failure visible; external-signer finalize: post-payment storage failure strands the payment (PreparedUpload consumed, not retryable) #140 makes it recoverable. Until then a surfaced PartialUpload after payment still cannot re-store without re-paying the missing chunks — strictly better than silent success, and re-preparing the same file skips chunks already stored.
• Downstream consumers get the fix on their next ant-core bump: the desktop app (fix: reject partial merkle uploads instead of reporting success ant-ui#212 adds its own guard meanwhile) and the mobile FFI (to_external_result currently drops chunks_failed; error propagation makes that moot).

🤖 Generated with Claude Code

[Nic-dorman]

Note on the Security Audit failure: it's pre-existing, not introduced here — this PR changes no dependencies. cargo audit fails on main's lockfile too: RUSTSEC-2026-0220 (ruint 1.18.0, "Uint shift operations: incorrect overflow flags and truncated shift amounts", advisory dated 2026-07-08, fix >=1.20.0). ruint comes in via the alloy/evmlib tree; cargo update -p ruint should clear it repo-wide as a separate chore PR.

[dirvine]

Panel review (6 seats: correctness, storage/lifecycle/concurrency, API/compatibility, tests/operations, security, and independent GLM-5.2), against head 52db38988c5384bbd0a3daf85067e72d091de418.

Verdict: no material blocker found. This is a focused and internally consistent fix: successful stores from the same pass remain reported, while quorum shortfalls now surface as Error::PartialUpload instead of an apparent success with chunks_failed > 0.

Verification performed:

• git diff --check and cargo fmt --all -- --check: clean
• cargo check -p ant-core: passed
• both focused #167 regression tests: 2 passed
• current GitHub build, unit, Clippy, format, docs, security and Merkle E2E checks: passed

The generic macOS/Ubuntu E2E jobs are still pending, so this is a review comment rather than an approval.

Relationship note: #168 contains/supersedes this change. If both are retained, merge #167 first and rebase/collapse #168; merging #168 alone includes the fix.