Add multi-base chain modelling, fix price-band-aware demand/supply, tranche-split sell tool

- puga/network.py + tools/network.py: model a multi-base chain (e.g. mine LST at one base,
  ship it, consume it at another). Simulates each base independently, nets a transferred
  material's producer-surplus against consumer-need, charges real freight only on what's
  moved, cm_free for a founding covered by a Core Module Kit. Worked example in plans/chains/.
- puga/saturation.py: real price-band filtering. FIO's order_book NarrowPriceBandLow/High and
  WidePriceBandLow/High match APEX's own displayed Price Band exactly (verified live) - an
  order outside it is a stale artifact, not just uncompetitive. Added in_band() and
  effective_demand(); effective_supply() gained the same hard band filter alongside its
  existing soft vwap-proximity filter (renamed that param mult to free up `band`). Wired into
  tools/scan.py stage 2 in place of the raw, unfiltered demand figure. Was flagged as an
  unimplemented refinement in saturation-design.md since the original design review.
- tools/sell.py: self-contained tranche split (aggressive tranche capped at a volume quantile,
  median normally or 80th pct with --tight when a payment is imminent and stockout risk
  outweighs margin; patient tranche priced under the next competitor tier). Instant-bid
  comparison moved behind --show-bid (off by default).
- Docs and roadmap updated accordingly.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

docs/saturation-design.md

@@ -48,3 +48,24 @@ Later refinements (not built): supply-feedback fixpoint (our N raises supply), d
 
 ## Addendum: effective supply (implemented)
 Stage 1 of `tools/scan.py` uses flow + demand only; stage 2 (shortlist) fetches the ask book and counts only standing sell orders priced <= 1.25 x vwap7 (`saturation.effective_supply`). Reason: DEC at AI1 showed 2,013 units 'queue' of which 1,501 sat at 50,000 (1.5x vwap), which made the raw queue penalty call the market saturated (N=0.38) when the effective queue gives about 1.7.
+
+
+## Addendum: real price-band filtering (implemented 2026-09-25)
+Verified live: FIO's order_book `NarrowPriceBandLow/High` and `WidePriceBandLow/High` fields match
+APEX's own displayed "Price Band" exactly (BHP.AI1: 663.00 - 16,575.00 both narrow and wide at the
+time). This is the exchange's actual tradeable range (dev log #191: unrated companies +/-25%, rated
++/-75% of a 3-day average, though observed bounds here are wider than that 2019 formula predicts -
+the live numbers win per source-of-truth rules). An order outside this band isn't just
+uncompetitive, it's a stale artifact that cannot be freshly placed and will never fill (e.g. a
+leftover 334 AIC bid on BHP.AI1 when the floor is 663 - only 19 of 1,060 standing "demand" units
+were like this, so the raw demand figure was mostly fine here, but the filter is a hard correctness
+fix, not a heuristic).
+- `saturation.in_band(price, (lo, hi))`: the band test.
+- `saturation.effective_demand(bids, band)`: hard-filters demand to in-band bids. Now used in
+  `tools/scan.py` stage 2 (`demand_of()`) in place of the raw, unfiltered `Quote.demand`.
+- `effective_supply()` gained the same hard band pre-filter (`band=` param) alongside its existing
+  soft `mult x vwap` "active competition" filter - these are different concepts: band = literally
+  invalid/stale, mult x vwap = valid but not realistically competing right now (e.g. OCK's far top
+  tier). Renamed the old positional `band` (vwap multiplier) param to `mult` to free up the name.
+- `p_patient()` already accepted `wide_high` as a price ceiling; `scan.py` wasn't passing it before,
+  now does via `band_of(t)[1]`.