feat(ffi): resumable external-signer finalize — retain the paid attempt on a partial store

[Nic-dorman]

Why

External-signer uploads had a "pay once, maybe upload once" footgun (#201). finalize_upload* handed the PreparedUpload to ant-core by value; if chunk storage fell short after the wallet had paid, the paid proofs were dropped and the payment was stranded — a re-prepare collects new quotes with different quote hashes that can never match the paid tx map. The FFI docs said so honestly ("NOT retryable after payment") as a stopgap.

ant-core now has a resumable finalize (WithAutonomi/ant-client#172, in the ant-cli-v0.3.6 tag ant-ffi already pins): a store shortfall comes back as FinalizeOutcome::Partial carrying a FinalizeResume handle that owns the paid proofs and the still-unstored chunks. This PR wires the FFI onto it.

What

• session module (new). The session map now holds either a PreparedUpload or the FinalizeResume handle a partial finalize returned, under the same upload_id. It is generic over the two payloads — neither can be constructed outside ant-core — so the state machine has offline unit tests with stand-ins. payment_kind() returns Option so an unknown future variant of ant-core's #[non_exhaustive] enums is refused rather than mis-routed.
• Finalize, both paths. Wave → finalize_upload_resumable_with_progress; merkle → finalize_upload_merkle_multi_resumable_with_progress with the one batch this surface supports (multi-batch prepares are already refused). A session in resume state routes to finalize_resume_with_progress and ignores the tx map / winner hash.
• Outcome handling. Complete converts as before. Partial re-inserts the resume handle under the same upload_id and returns the existing ClientError::PartialUpload (counts + spend) with a reason telling the caller to call the same finalize again. Other errors propagate; they are payment-side and consume the session as before.
• Lossless pre-check. A wave tx map that is well-formed but missing the receipt for a paid quote is refused before ant-core can consume the prepared upload (previously a PaymentError that lost the session).
• Adjacent surface. payment_transactions rejects a resume-state session as already paid; cancel_upload also abandons a retained partial attempt (dropping the handle frees the chunks).
• No FFI signature change. Python / Node / C# / Kotlin / Swift pick this up unchanged; only doc strings differ. Node wrapper cargo checks clean against it.
• Docs. finalize_upload*, cancel_upload, the PartialUpload variant, and docs/mobile-external-signer.md now describe the resumable contract, including ant-core's guidance to bound the retry loop and treat a non-shrinking chunks_failed as stuck (with a Swift loop example).

Tests

• session unit tests: prepared → partial retains a resume entry under the same id; resume → complete removes it; wrong-method finalize on either state is lossless; cancel drops both; payment_transactions on a resume state is refused; an unroutable shape is refused without removal.
• devnet_tests::devnet_external_signer_wave_round_trip (#[ignore], gated on ANT_FFI_DEVNET_MANIFEST): real prepare → wrong-method + incomplete-map refusals leave the session intact → pay the quotes with the devnet wallet exactly as an external signer would → finalize completes through the new path → repeat finalize is "unknown" → bytes round-trip by data map.
• cargo fmt --check, cargo clippy --all-targets --all-features --locked -D warnings, cargo test --locked → 23 passed, 1 ignored.

Not covered live: a forced mid-finalize store shortfall is not reproducible on a healthy devnet, so the Partial → retained → resume → Complete transition is proven by the offline session tests only; the ant-core side of that transition has its own unit coverage upstream.

Notes

• No ant-core pin bump: ant-cli-v0.3.6 already carries the resumable API.
• The C# Generated/ dir is gitignored; regenerating locally confirms the new doc strings flow through.
• Version stays 0.0.9; the bump across crate / node / python / csproj belongs to the release PR.

Closes #201

🤖 Generated with Claude Code

[Nic-dorman]

Live devnet run (dev2, ant-devnet --preset small --enable-evm, ant-node v0.18.1 / ant-core ant-cli-v0.3.6):

ANT_FFI_DEVNET_MANIFEST=~/.ant-dev/devnet-manifest.json cargo test -p ant-ffi --locked -- --ignored devnet
test devnet_tests::devnet_external_signer_wave_round_trip ... ok
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 23 filtered out; finished in 26.05s

Covers, against a real prepared session: wrong-method finalize and incomplete tx map both refused without consuming the session → payment_transactions still works → quotes paid by the devnet wallet as an external signer → finalize_upload completes through the resumable path → repeat finalize is "unknown" (session removed on Complete) → bytes round-trip by data map. Offline suite on the same box: 23 passed, 1 ignored.

[dirvine]

APPROVE — no blockers. Reviewed the full diff at head a31125e, verified against the pinned ant-core (ant-cli-v0.3.6 at dbc01ce), and ran the test suite. This closes #201 correctly.

Verified

• The FFI now uses ant-core's resumable finalisation. A store shortfall returns FinalizeOutcome::Partial; paid proofs and unstored chunks are retained as a FinalizeResume handle under the same upload_id; a repeat finalisation uses the same on-chain payment without re-preparing or re-signing.
• check_tx_hashes_complete validates the wave transaction map before consuming the session, so invalid input is lossless.
• Re-checked the previously outstanding edge case: its zero-amount exemption exactly mirrors ant-core's build_paid_chunks. Both require a transaction hash only when !amount.is_zero() (client.rs:1555; ant-core batch.rs:299-307).
• Invalid merkle winner input is decoded before take, so malformed input does not consume the prepared upload.
• Wrong-method and wrong-shape routing failures remove nothing; payment_transactions correctly refuses already-paid resume state.

Tests

cargo test -p ant-ffi --locked passed: 23 passed, 1 ignored (devnet-gated). CI is green across the current matrix.

The session unit tests cover prepared → partial → resume → complete, wrong-method losslessness in both states, cancellation in both states, and refusal of unroutable shapes without removal. The healthy-devnet test cannot naturally force the Partial → resume → Complete leg; that path is covered by the offline session tests and ant-core's upstream coverage.

Non-blocking follow-ups

• A stuck partial retains paid chunk bodies in memory (wave) or the spill directory (merkle) until finalisation succeeds or cancel_upload is called. This is documented, but bounded caching remains worthwhile for long-lived mobile clients.
• peek and take use separate lock acquisitions. Concurrent finalisation of the same ID can give the losing caller a benign unknown error, but take remains atomic and there is no double-payment risk.