feat(v2): principal-based fee split — fixes super under-payment (#38 3/5)

Replaces the broken fraction-of-fee math with fraction-of-principal,
direction-aware. Pre-#38: super_fee_fraction was interpreted as
`round(fee_sats * super_fraction)`, paying super ~13× below intent on
every cashout since the bitspire wire-shape landed. Post-#38: super
and operator shares are computed independently against principal
using the per-direction fractions from SuperConfig + Machine.

Per workspace CLAUDE.md "Backwards-compatibility on pre-public-launch
code" (v2-bitspire hasn't shipped to users), no compat shims:

- calculations.py: delete `split_two_stage_commission` (legacy
  fraction-of-fee). Keep `split_principal_based` as the sole split fn.
- migrations.py m009: extend to also DROP the deprecated
  `super_fee_fraction` column after backfilling its value into the
  new directional fields.
- models.py: drop `super_fee_fraction` from SuperConfig +
  UpdateSuperConfigData entirely.
- bitspire.py parse_settlement: new signature takes `super_config:
  SuperConfig` instead of `super_fee_fraction: float`. Resolves
  directional fractions from super_config + machine by tx_type, then
  computes via split_principal_based. Raises SettlementInvariantError
  on unknown tx_type.
- tasks.py: pass `super_config` through to parse_settlement; assert
  non-None (m001 inserts the singleton at install time — None is an
  impossible state).
- partial-dispense ratio path in distribution.py is unchanged — still
  uses `settlement.platform_fee_sats / settlement.fee_sats` from the
  landed row, which is the right invariant (lock at landing) and
  independent of the per-direction config.

Tests:
- Rename `test_two_stage_split.py` → `test_operator_split_legs.py`.
  Drop the legacy-function test classes. Keep TestAllocateOperatorSplitLegs
  (still-production fn) and TestPartialDispenseSplitRatio (inline ratio
  math in distribution.py).
- New `test_principal_based_fees.py`: pure-math tests for
  `split_principal_based` (six cases including a direct regression
  test pinning the pre-#38 bug at 240→3000 sats per 100k principal at
  3% super), plus parse_settlement directional dispatch tests
  (cash-in routes through cash-in fractions; cash-out through
  cash-out; unknown tx_type raises; zero-zero free-charge ATM; cross-
  direction guard).

Migration verified end-to-end via container restart: super_config
columns post-m009 = id/super_fee_wallet_id/updated_at/
super_cash_in_fee_fraction/super_cash_out_fee_fraction (no
super_fee_fraction). dca_machines + dca_settlements gained the
expected new columns. 156/156 tests green.

Refs: aiolabs/satmachineadmin#37 (parent), #38 (this layer). Closes
the load-bearing super under-payment bug standalone.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

tests/test_operator_split_legs.py

@@ -0,0 +1,150 @@
+"""
+Tests for `allocate_operator_split_legs` (operator's commission-leg
+distribution) and the partial-dispense ratio math in
+`apply_partial_dispense_and_redistribute`.
+
+Both are split-arithmetic concerns that survive the post-#38
+principal-based-math refactor:
+
+  - `allocate_operator_split_legs` slices the operator's share across
+    their commission legs by their per-leg fractions. Function-level,
+    no fee-model coupling.
+  - Partial-dispense ratio math (in distribution.py) preserves the
+    ORIGINAL platform/operator ratio recorded against a settlement at
+    land time when an operator partial-dispenses post-hoc. The ratio
+    comes from the absolute platform_fee_sats / fee_sats recorded on
+    the settlement row, NOT the current super-config fractions — the
+    contract is locked at landing.
+
+Pre-#38 tests for `split_two_stage_commission` lived here; that
+function was removed when the principal-based math landed
+(aiolabs/satmachineadmin#38).
+"""
+
+import pytest
+
+from ..calculations import allocate_operator_split_legs
+
+
+class TestAllocateOperatorSplitLegs:
+    """Operator's remaining share split into commission legs by fraction."""
+
+    def test_plan_example_50_30_20_on_70(self):
+        amounts = allocate_operator_split_legs(70, [0.5, 0.3, 0.2])
+        assert amounts == [35, 21, 14]
+
+    def test_realistic_50_30_20_on_5575(self):
+        amounts = allocate_operator_split_legs(5575, [0.5, 0.3, 0.2])
+        # Plan-scale: 5575 * (0.5, 0.3, 0.2) = (2787.5, 1672.5, 1115)
+        # Last leg absorbs rounding remainders so sum == 5575 exactly.
+        assert sum(amounts) == 5575
+        assert amounts[0] == round(5575 * 0.5)
+        assert amounts[1] == round(5575 * 0.3)
+        # Last leg absorbs the remainder.
+        assert amounts[2] == 5575 - amounts[0] - amounts[1]
+
+    def test_single_leg_full_remainder(self):
+        amounts = allocate_operator_split_legs(7965, [1.0])
+        assert amounts == [7965]
+
+    def test_zero_operator_fee_zeros_all_legs(self):
+        amounts = allocate_operator_split_legs(0, [0.5, 0.3, 0.2])
+        assert amounts == [0, 0, 0]
+
+    def test_empty_legs_list_returns_empty(self):
+        amounts = allocate_operator_split_legs(100, [])
+        assert amounts == []
+
+    def test_last_leg_absorbs_rounding_remainder(self):
+        # 100 sats split [1/3, 1/3, 1/3] — last leg absorbs the +1 remainder.
+        amounts = allocate_operator_split_legs(100, [1 / 3, 1 / 3, 1 / 3])
+        assert sum(amounts) == 100
+        assert amounts[0] == round(100 / 3)  # 33
+        assert amounts[1] == round(100 / 3)  # 33
+        # Last leg absorbs the rounding (34, not 33) so total == 100.
+        assert amounts[2] == 100 - amounts[0] - amounts[1]
+
+    @pytest.mark.parametrize(
+        "operator_fee,fractions",
+        [
+            (1, [0.5, 0.5]),
+            (7, [0.5, 0.3, 0.2]),
+            (100, [0.5, 0.5]),
+            (5575, [0.5, 0.3, 0.2]),
+            (1_000_000, [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]),
+        ],
+    )
+    def test_invariant_sum_equals_operator_fee(self, operator_fee, fractions):
+        amounts = allocate_operator_split_legs(operator_fee, fractions)
+        assert sum(amounts) == operator_fee
+        assert all(a >= 0 for a in amounts)
+
+
+class TestPartialDispenseSplitRatio:
+    """Partial-dispense recompute (closes #11 H6) must preserve the
+    ORIGINAL platform/operator ratio recorded on the settlement row at
+    land time. Super raising or lowering a global rate post-hoc must
+    NOT retroactively change an existing settlement's share split.
+
+    The math is inlined in `apply_partial_dispense_and_redistribute`
+    (distribution.py) rather than in a standalone function. These tests
+    mirror the inline math so a future refactor doesn't silently change
+    the invariant.
+    """
+
+    def _recompute(self, original_fee, original_platform_fee, new_fee):
+        """Mirror of the ratio math in apply_partial_dispense_and_redistribute."""
+        if original_fee > 0:
+            ratio = original_platform_fee / original_fee
+        else:
+            ratio = 0.0
+        new_platform = round(new_fee * ratio)
+        new_platform = max(0, min(new_platform, new_fee))
+        new_operator = new_fee - new_platform
+        return new_platform, new_operator
+
+    def test_30pct_lands_then_partial(self):
+        # Landed at platform ratio 30/100 = 0.30; new fee = 50.
+        # Original ratio preserved → new_platform = round(50 * 0.30) = 15.
+        new_platform, new_operator = self._recompute(100, 30, 50)
+        assert new_platform == 15
+        assert new_operator == 35
+        assert new_platform + new_operator == 50
+
+    def test_super_changed_rate_doesnt_affect_existing_settlement(self):
+        # Landed with platform=2390, fee=7965 (ratio ≈ 0.30). Super then
+        # bumps the global rate to 50%. Operator partial-dispenses to
+        # 50% gross → new_fee = round(7965 * 0.5) = 3982. The 30% ratio
+        # at land time MUST persist regardless of the new super rate.
+        new_platform, new_operator = self._recompute(7965, 2390, 3982)
+        # Expected with original ratio: round(3982 * 0.30006...) = 1195
+        # With (broken) current rate of 50%: would be 1991 — much higher.
+        assert 1190 <= new_platform <= 1200
+        assert new_platform + new_operator == 3982
+        # Original platform share was ~30%; preserved within rounding.
+        assert abs(new_platform / 3982 - 2390 / 7965) < 0.001
+
+    def test_zero_original_fee_yields_zero_platform(self):
+        new_platform, new_operator = self._recompute(0, 0, 0)
+        assert new_platform == 0
+        assert new_operator == 0
+
+    def test_invariant_sum_equals_new_fee(self):
+        # Random-ish parameter sweep over realistic values.
+        cases = [
+            (100, 30, 50),
+            (100, 0, 50),       # original platform_fee was 0
+            (100, 100, 50),     # original platform_fee was full fee
+            (7965, 2390, 3982),
+            (7965, 7965, 3982),
+            (1_000_000, 333_333, 250_000),
+        ]
+        for orig_comm, orig_plat, new_comm in cases:
+            new_platform, new_operator = self._recompute(
+                orig_comm, orig_plat, new_comm
+            )
+            assert new_platform + new_operator == new_comm, (
+                f"sum invariant violated: {orig_comm=} {orig_plat=} "
+                f"{new_comm=} → {new_platform=} {new_operator=}"
+            )
+            assert 0 <= new_platform <= new_comm