[DBSP] New Recursion API Proposal - #6727

This is a genuinely nicer API than what it subsumes. The arity-from-shape trick (recursive_var calls in init determine the arity) removes the footgun that recursive_dynamic has today, the builder chain is honest about which knobs are optional, and the type-state on Reporting vs NoReport keeps the return shape of finish unambiguous. The reachability tests exercise the three shapes (single, Vec, tuple) against the same fixture as the old APIs, and the bound + reset regression test (with_bound_counter_resets_across_transactions) is the right shape. Nice work.

I want to answer the four open questions in the PR body up front, and leave the rest inline.

1. Deprecate recursive and recursive_dynamic? Yes, once this lands. Attach #[deprecated(note = "use ChildCircuit::recursion")] and let them coexist for one release so downstream callers can migrate, then remove. Two APIs for the same thing is worse than either alone; having both indefinitely will train people to reach for whichever they see first.

2. Remove mark_distinct from the public API? Yes. A public method that silently misbehaves under sharding is a correctness trap — future users will find it, use it, hit the wrong answer in production, and spend a day tracing it. Either fix the sharding interaction or remove the entry point (deprecate + private module). Do not leave broken API in the public surface.

3. Move run to the Circuit trait / offer builder-composed iterate_* variants? Not in this PR. The current shape is coherent and covers the cases users actually have. The four-knob matrix (_with_bound, _with_report, _with_consensus, _until_fixedpoint) is a classic second-system trap — you would be designing for hypothetical users of iterate who don't yet exist. Ship this as-is; wait for a real second use case before generalising. If it turns out you want the general form, it's an additive extension.

4. Naming and docs. Overall solid — the doc examples are well-chosen and the RecursionBuilder rustdoc explains the mental model. A few specific things below. The one non-cosmetic worry is the # Safety heading on Consensus: rustdoc reserves that section for unsafe items, and Consensus is safe Rust with logical invariants. Rename to # Invariants or fold into prose.

None of these block; posting as COMMENT because the PR is explicitly an RFC and I want the four answers on the record. Once the naming/marker questions are settled I'll do a proper line-by-line pass.

One meta point: the commit history is going to need a git rebase -i before this merges — the "Prototype…" tip on top of #6653's history means the same "Reset iterate_* APIs…" commit needs to survive the squash cleanly. Standard hygiene, same as last time.

Rebase + AI-feedback pass looks good. Walking my earlier eight nits against the current tip:

1. Consensus # Safety heading — resolved upstream via #6653 (now merged in through rebase). ✓
2. RecursionReport::converged() -> Option<u64> naming — split into converged() -> bool, truncated() -> bool, and converged_iterations() -> Option<u64>. Reads correctly at call sites now. ✓
3. RecursiveVar::stream() unused pub method — dropped. ✓
4. Reporting slot allocated under NoReport — genuinely fixed by pushing the recorder into the ReportMode type-state: NoReport::record is a no-op, NoReport::build_report returns None, and only Reporting owns the Rc<Cell<RecursionReport>>. Zero-alloc in the default path. ✓
5. with_bound(0) corner — solved at the type level with NonZeroU64, which is nicer than any runtime assertion. ✓
6. Tuple report is_none() walk — replaced with a direct call on the first element. ✓
7. Counter-reset comment — now cites the regression test by name (with_bound_counter_resets_across_transactions) and adds a debug_assert! on the stop invariant. ✓ (tiny nit below)
8. is_fixedpoint vs check_fixedpoint — resolved via #6653. ✓
9. Sealed markers — NoReport/Reporting are now unconstructible outside the module (private fields) and gated by a sealed::Sealed supertrait on ReportMode. Exactly right. ✓

Deferred item — deprecation of recursive/recursive_dynamic — is explicitly punted to the maintainers, which is fine; that was a soft direction question, not a blocker.

One micro-nit, non-blocking:

• debug_assert!(stop == true); — clippy's bool_comparison will grumble; prefer debug_assert!(stop); (or debug_assert!(stop, "iteration.set(0) must only fire on the last epoch iteration") to preserve intent).

Otherwise the design and implementation are in good shape. Nice cleanup.

Reviewed by mythical-fred (an AI persona) at tip a3e1e8c. My reviews are advisory input for humans, not authoritative approval.

LGTM — the three new benchmarks exercise RecursionBuilder across all three shapes (single var in acyclic, tuple in graph coloring, single var + Min in cyclic), assert cross-variant agreement against the existing recursive/iterate implementations, and the debug_assert!(stop) clippy nit is fixed.