sync(engine): Wave 11a-ii-B — permissionless_progress dispatcher (minimal port, recovery deferred)

[dcccrypto]

Summary

Wave 11a-ii-B ports the engine-side permissionless-progress entry point + request/outcome types so the wrapper KeeperCrank port (Wave 7c) can land. Recovery branches (active-close continuation / account-B dispatch / 5-reason global recovery loop) are intentionally deferred to a follow-up wave — they require porting an additional ~1500 LOC of helpers beyond the scope of this PR.

The wrapper's only behavioral dependence on the outcome is matches!(outcome, Cranked(_)) for post-crank fee logic, so stubbing recovery is safe: recovery-eligible markets surface a stable RecoveryRequired error instead of being terminally recovered in-engine.

Types added (toly:engine refs in parens)

• RecoveryReason enum (270-302) — 7 variants
• PermissionlessProgressOutcome enum (950-958) — 6 variants
• KeeperCrankRequest struct (1036-1050)
• PermissionlessProgressRequest struct (1057-1073)

Functions added

• force_close_resolved_cursor_with_fee_not_atomic (toly:9731-9774): bounded resolved-close cursor progress; advances rr_cursor_position across missing slots, reconciles the first materialized account in the window via the existing force_close_resolved_with_fee_not_atomic.
• force_close_resolved_cursor_not_atomic (toly:9719-9724): zero-fee convenience delegate.
• keeper_crank_with_request_not_atomic (toly:8848-9069 at the request-shape level): thin adapter around fork's existing positional-arg keeper_crank_not_atomic. The two toly-only request fields not consumed by the fork's keeper (max_candidate_inspections, rr_scan_limit) are forwarded structurally but ignored.
• permissionless_progress_not_atomic (toly:8754-8845 at the dispatcher level):
  • Resolved → force_close_resolved_cursor_with_fee
  • Live → keeper_crank_with_request
  • active_close_present != 0 → RecoveryRequired (defense-in-depth, dead code on this branch since Wave 11a-ii-A setters have no production caller yet)
  • Otherwise → Unauthorized

The recovery middle 3 branches (toly:8787-8829) are deferred.

Kani harnesses (342 → 346, +4)

• proof_permissionless_progress_resolved_routes_to_resolved_close
• proof_permissionless_progress_rejects_when_active_close_present
• proof_force_close_resolved_cursor_rejects_live_market
• proof_force_close_resolved_cursor_rejects_zero_scan_limit

Risk on this branch

Wave 7c (wrapper KeeperCrank port) can now call `engine.permissionless_progress_not_atomic(PermissionlessProgressRequest {...})` and match on `PermissionlessProgressOutcome::Cranked(_)` exactly as toly's wrapper does.

Deferred to a future wave (KL-FORK-ENGINE-B-TRACKING-1 / KL-FORK-ENGINE-BANKRUPT-CLOSE-1)

• `try_permissionless_account_b_dispatch` / `_b_progress`
• `try_permissionless_global_recovery` (5 reasons)
• `permissionless_recovery_resolve_p_last_not_atomic` + account-B variant
• `validate_permissionless_p_last_recovery_reason` + account-B variant
• `bounded_price_step_cap_abs` / `_toward_raw_target` / `bounded_accrual_slot_for_now` / `plan_accrual_segment`
• `resolve_counter_or_epoch_overflow_recovery_not_atomic`
• `exposed_market_has_oi`
• `begin_terminal_epoch_exhaustion_reset`
• Integration of Wave 11a-ii-A setters into trade / accrue / resolve / fee-sync hot paths

Test plan

• `cargo build --release` — clean
• `scripts/verify-engine-preservation.sh` — silent
• `scripts/verify-engine-deferred-absent.sh` — silent
• `cargo test --release --features test` — 49 + 3 + 283 tests pass
• Kani harnesses on CI (346 total, was 342 — never decreases)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Introduced permissionless progress API enabling cursor-based position closure with fee flexibility and configurable scan parameters for optimal recovery outcomes.

• Tests

  • Added proof-based test coverage validating correct routing for permissionless progress operations, error conditions, and market state guards.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4037e0c2-fd01-4eef-85ad-e026ece2c29e

📥 Commits

Reviewing files that changed from the base of the PR and between 69ce830 and e7cacee.

📒 Files selected for processing (2)

• src/percolator.rs
• tests/proofs_invariants.rs

---

📝 Walkthrough

Walkthrough

Adds a permissionless progress dispatcher and cursor-based resolved-account closure APIs. Introduces RecoveryReason and PermissionlessProgressOutcome enums, KeeperCrankRequest and PermissionlessProgressRequest request structs, and four public methods for cursor-based force-close, keeper-crank adaptation, and top-level routing. Includes four Kani proofs validating dispatcher behavior.

Changes

Wave 11a-ii-B Permissionless Progress API

Layer / File(s)	Summary
Request/Response Types src/percolator.rs	RecoveryReason and PermissionlessProgressOutcome enums define dispatcher failure categories and outcomes. KeeperCrankRequest<'a> and PermissionlessProgressRequest<'a> package keeper-crank and permissionless-progress inputs as structured request objects.
Cursor-Based Resolved Closure src/percolator.rs	force_close_resolved_cursor_with_fee_not_atomic validates resolved mode, iterates from rr_cursor_position up to scan_limit with wraparound, closes the first used account via force_close_resolved_with_fee_not_atomic, advances the cursor, and returns ProgressOnly if no accounts are found.
Zero-Fee Convenience Wrapper src/percolator.rs	force_close_resolved_cursor_not_atomic wraps force_close_resolved_cursor_with_fee_not_atomic with zero fee rate.
Keeper Crank Request Adapter src/percolator.rs	keeper_crank_with_request_not_atomic destructures KeeperCrankRequest and forwards to keeper_crank_not_atomic, delegating to internal cap logic.
Top-Level Dispatcher src/percolator.rs	permissionless_progress_not_atomic routes to resolved cursor closure in Resolved mode, rejects with RecoveryRequired if active_close_present != 0 in Live mode, and otherwise calls keeper crank via the request adapter, returning Cranked(...) on success.
Proof Suites tests/proofs_invariants.rs	Four Kani proofs verify dispatcher routing: Resolved mode routes to ResolvedClose outcome; Live mode with active close rejects as RecoveryRequired; force_close_resolved_cursor rejects Live markets as Unauthorized; zero scan limit on Resolved markets rejects as Overflow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• dcccrypto/percolator#91: Extends percolator API with cursored/permissionless dispatchers that build on force_close_resolved_with_fee_not_atomic.
• dcccrypto/percolator#82: Introduces upstream ResolvePermissionless instruction and extensive proof suites that overlap with permissionless resolution surface.
• dcccrypto/percolator#90: Modifies force-close and market resolution code paths that the main PR extends with cursor-based dispatch.

Poem

🐰 A cursor hops through resolved accounts,
Closing each with steadfast grace,
While keeper cranks and progress mounts—
Permissionless paths find their place!
✨🔄

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/eng-permissionless-progress-wave11a-ii-B

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}