[Emmazlee]

Overview

This PR adds an on-chain exact-share selling path (sell_shares / quote_sell_shares) backed by a pool-favoring integer square root, so clients no longer have to invert the constant-product curve off-chain to sell an exact number of shares or fully close a position. The Python model and frontend integration docs are updated to mirror and document the new arithmetic.

Related Issue

Changes

🧮 Exact-share selling math

• [MODIFY] oracledesk-stellar/model/fpmm_model.py
  • Adds calc_sell_shares mirroring the Rust math::calc_sell_shares bit-for-bit: computes the discriminant with the same b = r_sold + shares_in + r_other / D = b^2 - 4*r_other*shares_in formulation, uses math.isqrt for the seed, and applies the same pool-favoring correction loop (not isqrt alone) so results match Rust exactly.
  • Adds _check_sell_shares_known_values, _check_sell_shares_k_non_decreasing, and _check_sell_shares_never_beats_calc_sell and wires them into run_all() so the model validates the new function against pinned fixtures, the k-never-decreases invariant, and the "never pays more than calc_sell charges for the same shares" property.

📚 Docs

• [MODIFY] oracledesk-stellar/docs/frontend-integration.md
  • Rewrites "Selling an exact share count" around sell_shares(trader, market_id, outcome, shares_in, min_collateral_out) and quote_sell_shares, replacing the three-step off-chain workaround (read reserves → invert curve → pad max_shares_in).
  • Documents the "Sell all" flow (shares_in == held) that leaves no dust in DataKey::Position.
  • Fixes the broken agents/core/src/fpmm.ts path to agents/core/fpmm.ts.

Verification Results

python3 model/fpmm_model.py
✅ _check_sell_shares_known_values passed
✅ _check_sell_shares_k_non_decreasing passed
✅ _check_sell_shares_never_beats_calc_sell passed

Acceptance Criteria	Status
calc_sell_shares mirrored in Python with the same correction loop	✅ model/fpmm_model.py
Python model checks k never decreases and never beats calc_sell	✅ _check_sell_shares_k_non_decreasing, _check_sell_shares_never_beats_calc_sell
Known-value fixtures shared with Rust/TS	✅ _check_sell_shares_known_values
docs/frontend-integration.md documents sell_shares	✅ Rewritten section
Wrong agents/core/src/fpmm.ts path fixed	✅ Corrected to agents/core/fpmm.ts

Notes

This PR covers the Python mirror and the frontend docs from the issue. The Rust math::isqrt / calc_sell_shares, the MarketCore::sell_shares / quote_sell_shares entrypoints, the TypeScript mirror in agents/core/fpmm.ts, the regenerated bindings, and the refreshed vendored market_core.wasm copies are tracked separately and are not part of this change set.

Closes #2

[Emmazlee]

this PR is ready for another review. I resolved the merge conflicts with the develop branch (pushed 0612726).
Files changed: oracledesk-stellar/agents/core/fpmm.test.ts, oracledesk-stellar/agents/core/fpmm.ts, oracledesk-stellar/contracts/market-core/src/math.rs, oracledesk-stellar/docs/frontend-integration.md, oracledesk-stellar/model/fpmm_model.py, oracledesk-stellar/packages/bindings/market-core/src/index.ts