refactor(settlement): extract a settlement module and harden fill-persistence tests

[gregorydemay]

Follow-up work on the merged per-fill persistence (#179), kept separate so #179 stayed lean and approved. Two parts:

Settlement module extraction (pure refactor — no behavior or Candid change).
The settlement pipeline that was scattered across the order and state modules is pulled into a dedicated top-level settlement module, and the free settle step plus the order-status merge that was inlined in the matching path are replaced by a single type constructed directly from the matcher's output. The intent is that the flow reads off the types: match result → settled consequences (balance operations, order-record updates, lean persisted fill records) → replayed trades. Behavior and the on-wire (stable-memory) schema are unchanged — the schema-stability golden test is untouched.

Fill-persistence regression guards (the non-blocking suggestions from #179's review):

• fee/notional parity: every persisted trade leg's fee and notional must equal the balance operation produced from the same settlement, so a later edit can't let the settle-time recompute drift from the match-time transfers.
• match-time fee-rate snapshot: changing the book's fee rates between matching and settling must not move a persisted leg's fee — it reflects the rate snapshotted at match time.
• bytes-per-fill accounting: pins the store's stable footprint per fill as a tracked constant (canbench's stable_memory_increase reads 0 because the memory manager pre-allocates buckets, so this direct encoded-size assertion pins the growth those buckets absorb).

The guards are test-only; the refactor is behavior-preserving.

Spec: docs/src/development/specs/DEFI-2901-persist-fills.md

📚 Follow-up on #179 (merged to main).

[github-actions]

canbench 🏋 (dir: canister) f773625 2026-07-01 20:04:57 UTC

✅ canister/canbench_results.yml is up to date
📦 canbench_results_benchmark.csv available in artifacts

---------------------------------------------------

Summary:
  instructions:
    status:   No significant changes 👍
    counts:   [total 14 | regressed 0 | improved 0 | new 0 | unchanged 14]
    change:   [max +83.58K | p75 0 | median 0 | p25 -187.61K | min -564.99K]
    change %: [max +0.09% | p75 0.00% | median 0.00% | p25 -0.02% | min -0.16%]

  heap_increase:
    status:   No significant changes 👍
    counts:   [total 14 | regressed 0 | improved 0 | new 0 | unchanged 14]
    change:   [max 0 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max 0.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

  stable_memory_increase:
    status:   No significant changes 👍
    counts:   [total 14 | regressed 0 | improved 0 | new 0 | unchanged 14]
    change:   [max 0 | p75 0 | median 0 | p25 0 | min 0]
    change %: [max 0.00% | p75 0.00% | median 0.00% | p25 0.00% | min 0.00%]

---------------------------------------------------
CSV results saved to canbench_results.csv

[Copilot]

Pull request overview

Adds regression guards around fill persistence invariants (fee/notional parity, match-time fee-rate snapshots, and per-fill stable footprint), while also refactoring settlement-related types/logic into a dedicated settlement module.

Changes:

• Adds new proptests/unit tests to ensure persisted TradeRecord legs match the balance ops emitted from the same settlement and remain pinned to match-time fee rates.
• Pins the encoded stable-memory byte footprint per persisted fill via a deterministic encoded-size assertion.
• Refactors settlement computation and FillEvent type location into a new canister::settlement module and updates call sites/imports.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
canister/src/test_fixtures/mod.rs	Updates arbitrary fixture imports to use settlement::FillEvent.
canister/src/test_fixtures/event.rs	Updates fixture helpers to use settlement::FillEvent.
canister/src/state/tests.rs	Moves/extends invariant tests; adds new persistence invariants and fee-rate snapshot test (currently contains a compile-breaking duplicate import).
canister/src/state/snapshot/tests.rs	Updates snapshot tests to reference settlement::FillEvent.
canister/src/state/mod.rs	Refactors matching settlement construction to use MatchSettlement; adds cfg(test) fee-rate setter for tests.
canister/src/state/event/mod.rs	Updates event model to use settlement::FillEvent.
canister/src/settlement/tests.rs	New focused tests for fill settlement leg reconstruction + settlement shape proptest (moved from order/tests.rs and state/tests.rs).
canister/src/settlement/mod.rs	New settlement module containing MatchSettlement, FillSettlement, FillEvent, and RemovedOrderSettlement.
canister/src/order/trades/tests.rs	Adds encoded-size “bytes per fill” invariant test.
canister/src/order/trades/mod.rs	Adds cfg(test) helper to expose encoded-size accounting for a leg.
canister/src/order/tests.rs	Removes settled_fill tests (moved to settlement/tests.rs).
canister/src/order/mod.rs	Stops re-exporting fill/settlement types from order::fill.
canister/src/order/fill.rs	Removes settlement-related types from order::fill, leaving core fill identity/types.
canister/src/order/book.rs	Adds cfg(test) set_fee_rates to support fee-rate snapshot testing.
canister/src/main.rs	Updates event mapping to accept settlement::FillEvent.
canister/src/lib.rs	Exposes new settlement module from the canister library crate.
canister/src/history/mod.rs	Adds cfg(test) helper to compute encoded size of a primary + by-user index entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.