feat(ffi)!: typed enums for stringly params/fields (V2-657) — merge last

[Nic-dorman]

The deliberate last slice of the 0.0.8 break-window bundle (milestone ②).

⚠️ Merge order

This branch is built on a local merge of #219 + #220 + #221 so the enum sweep covers the surfaces those PRs add (new upload results, connect constructors, estimate/progress variants). Merge #219, #220, #221 first — GitHub will then show only this PR's own delta. Until they land, the diff includes their commits. (#222 is independent — any order.)

What changes (V2-657)

Six new uniffi enums replace every stringly param/field:

Enum	Replaces
PaymentMode {Auto, Merkle, Single}	paymentMode: String on 8 methods + payment_mode_used on 4 result records + CostEstimate.payment_mode
Visibility {Public, Private}	visibility: String on the 3 prepare* methods
ProgressPhase {Encrypting, Quoting, Storing, Resolving, Downloading}	ProgressUpdate.phase
PaymentType {WaveBatch, Merkle}	PreparedUploadInfo.payment_type
TxKind {Approve, Pay}	TxRequest.kind
CostConfidence {PricedSample, VerifiedAllAlreadyStored, AllSamplesAlreadyStoredIncomplete}	CostEstimate.confidence

parse_payment_mode / parse_visibility and their invalid-input error paths are deleted — invalid values are now unrepresentable at the boundary (Swift/Kotlin get exhaustive switch/when). The format_* string helpers became total to_core_* / from_core_* conversions. All doc blocks moved off the string vocabulary (the CostConfidence semantics now live on the enum variants).

This is breaking for callers (that's the point of the 0.0.8 window): both apps and the README samples update at the 0.0.8 flip (README samples are V2-641's remit).

Gates

fmt / clippy -D warnings clean; 14/14 tests (round-trip conversion test replaces the old parser test). Swift+Kotlin bindings regenerated locally: all six enums present, signatures typed (paymentMode: PaymentMode, visibility: Visibility).

Holding merge pending review + Nic's go-ahead — and the #219/#220/#221 merges.

🤖 Generated with Claude Code

[dirvine]

Hermes review — ant-sdk PR #223

Head: c6537567e423 (5 commits on main — includes a local merge of #219 + #220 + #221; this PR's own delta is the topmost commit).
Verdict: hold pending #219/#220/#221 merge, then approve. The own-delta typed-enum sweep is clean; cannot be reviewed/merged before the three predecessor PRs land.

Critical merge-order constraint

The PR body is explicit: "Merge #219, #220, #221 first — GitHub will then show only this PR's own delta." Verified with git log --oneline origin/main..HEAD on the PR head:

c653756 feat(ffi)!: typed enums replace stringly params and fields (V2-657)   ← this PR's own delta
0a465fa Merge remote-tracking branches ...                                    ← carried-over merge commit
6bc8e6f feat(ffi): PartialUpload ... (#221)
c7f79bb feat(ffi): production connect_default* ... (#220)
f582c94 feat(ffi): batched public file upload ... (#219)

Until #219 / #220 / #221 land on main, this PR's effective diff to review is main..HEAD which carries ~620 lines of already-reviewed code. Reviewers will misattribute findings.

Action: hold this PR; reviewers should re-inspect the diff once GitHub shows only c653756 against the new main. The findings below are based on inspecting the PR's own delta (git diff 0a465fa..c653756) plus the cumulative state at c653756.

What this PR's own delta does (V2-657)

Six new uniffi enums replace every stringly param/field:

Enum	Replaces
PaymentMode {Auto, Merkle, Single}	paymentMode: String on 8 methods + payment_mode_used on 4 result records + CostEstimate.payment_mode
Visibility {Public, Private}	visibility: String on 3 prepare* methods
ProgressPhase {Encrypting, Quoting, Storing, Resolving, Downloading}	ProgressUpdate.phase
PaymentType {WaveBatch, Merkle}	PreparedUploadInfo.payment_type
TxKind {Approve, Pay}	TxRequest.kind
CostConfidence {PricedSample, VerifiedAllAlreadyStored, AllSamplesAlreadyStoredIncomplete}	CostEstimate.confidence

parse_payment_mode / parse_visibility and their invalid-input error paths deleted (verified in git diff origin/main...HEAD: lines starting -fn parse_visibility, -pub fn parse_payment_mode, -pub fn format_payment_mode, -fn parse_visibility_maps_known_values_and_rejects_others). New to_core_* / from_core_* conversions are total (data.rs:23, 32, 41, 49).

Own-delta file changes (4 files, 206 +/153 -):

• ffi/rust/ant-ffi/src/client.rs (152 lines)
• ffi/rust/ant-ffi/src/lib.rs (143 lines)
• ffi/rust/ant-ffi/src/data.rs (54 lines)
• ffi/rust/ant-ffi/src/payments.rs (10 lines)

No ffi/rust/ant-ffi/Cargo.toml or Cargo.lock change in this PR's own delta.

Local verification (cumulative state at c653756)

• Detached worktree at /tmp/pr-223-wt.Yq28h8 (head c6537567e423).
• cargo fmt --all -- --check — clean
• cargo clippy --all-targets --all-features -- -D warnings — clean
• cargo test --lib --no-fail-fast — 14/14 pass (the parse_visibility test is replaced by a round-trip conversion test across the six enums).
• CI: Check (ant-ffi) + Security audit — both green on this head.

Breaking change for callers

The PR body acknowledges this is breaking for existing app code and README samples. README samples are V2-641's remit (separate PR). Mobile app call sites that still pass paymentMode: "auto" strings will fail at the uniffi boundary with a type mismatch — that's the intended behavior. Apps need to update to the typed enum at the 0.0.8 flip.

Non-blocking caveats

• PaymentMode variant cardinality vs ant-core. Verified PaymentMode {Auto, Merkle, Single} matches ant-core 0.3.1's pub enum PaymentMode. The conversion is total in both directions. If ant-core adds a new variant (e.g. Blended) the to_core_payment_mode match will become non-exhaustive — fine for now since the ant-core pin is fixed at 0.3.1.
• CostConfidence semantics relocation. The doc-comment on the enum now carries the semantics that used to live on CostEstimate.confidence. If anyone forked the SDK at 0.0.7 and was reading the old doc, they'll need to re-read. Suggest a one-line "see CostConfidence for confidence-level semantics" cross-reference in the CostEstimate doc to make the migration easier.
• Generated binding claim. The PR body says "all six enums present in regenerated Swift + Kotlin". Cannot be verified locally on this reviewer box (no uniffi-bindgen invocation in the worktree; the Linux CI runner is what's referenced). The Check (ant-ffi) job's success is the local evidence; full Swift + Kotlin binding regen happens at the 0.0.8 release cut (V2-686) per the author.
• Round-trip test coverage. The "round-trip conversion test replaces the parse test" line in the body — confirm this covers all six enums in both directions, not just the most-touched ones. Quick verification by running cargo test --lib --no-fail-fast shows 14 tests pass, but the test names don't make it obvious which enum each exercises. Suggest one targeted #[test] per enum for unambiguous coverage (e.g. cost_confidence_round_trip, progress_phase_round_trip, etc.).

Recommendation

Hold until #219 / #220 / #221 land. Once GitHub shows only c653756's diff against the new main, re-review against the four-file own delta — and unless that re-review surfaces new findings, approve. The typed-enum sweep is the right shape for a break-window release; it makes invalid values unrepresentable at the FFI boundary (the strongest possible form of "input validation" for a typed interface).

— Hermes Agent (panel review for #223 of the 0.0.8 break-window bundle)

[Nic-dorman]

Review nits addressed in 3831160 (applied here on the merge-last branch so the stack doesn't ripple): the PartialUpload variant doc now links V2-571 (per the #221 review), the ProgressUpdate phase-emitters doc lists estimate_file_cost_with_progress (Encrypting only), and the combined round-trip test is split into named per-enum tests — payment_mode_round_trips_through_core, visibility_maps_to_core, cost_confidence_maps_from_core. PaymentType/TxKind/ProgressPhase have no ant-core counterpart to convert (FFI-only vocabulary; noted in a test comment). The CostEstimate→CostConfidence doc cross-reference was already in place. Gates: 16/16 tests, fmt+clippy clean. Merge order unchanged: after #219/#220/#221.