Strategic-Reserve Flow Marketplace — turn static critical-mineral stockpiles into clearable flow rights, allocated by shock-weighted priority, with a hash-chained clearing ledger.
National strategic reserves of critical minerals sit as static stockpiles —
capital frozen as inventory — while buyers who need a flow of material during a
supply shock have no shared, priced way to draw on them. ReserveFlow turns stock
into flow (lens L25), pools holders into one per-mineral capacity book (L19),
and clears buyer requests against that capacity — strategic buyers preempting
as the declared shock level rises.
Indicative clearing allocation and evidence trail — not a real commodity exchange, custody system, or settlement venue.
pip install -e . # or: PYTHONPATH=src python -m reserveflow ...Stdlib only (dependencies = []), Python ≥ 3.10.
# 1) write a sample offer/request book (under a shock)
reserveflow sample -o examples/book_sample.json
# 2) clear it -> JSON report (fill outcomes + cleared-by-mineral + fees + ledger head)
reserveflow run -i examples/book_sample.json
# 3) full report + markdown clearing view
reserveflow run -i examples/book_sample.json --full -o examples/book_report.json
reserveflow run -i examples/book_sample.json --markdown -o examples/clearing_report.md
# 4) verify the clearing ledger has not been tampered with
reserveflow verify-ledger -i examples/book_report.jsonOffers (reserve holdings posted as flow capacity) are aggregated into a per-mineral capacity book. Requests clear in priority order; capacity is never over-allocated:
| Condition | Outcome |
|---|---|
| request received all requested units | FILLED |
| capacity ran out mid-request | PARTIAL |
| no capacity remained | UNFILLED |
Priority: at shock_level 0 the market is calm — requests clear first-come
(deterministic FIFO). When a shock is declared (shock_level > 0) class priority
activates: strategic > industrial > commercial, with strategic boosted
further as the shock deepens. Reference fees per mineral
(reserveflow.models.MINERAL_TABLE): lithium 0.12, cobalt 0.15, rare_earth 0.20,
nickel 0.08, copper 0.05, generic 0.10 per cleared unit.
L25 StockToFlow + L19 Aggregation applied to insight INS-L10-003 (supply
security as a tradable instrument). Pipeline: heterogeneous offers/requests →
adapters (canonical flow) → clearing engine (FILLED/PARTIAL/UNFILLED) →
hash-chained ledger → audit/markdown report. Deterministic given input
timestamps. See .pgf/DESIGN-ReserveFlow.md.
PYTHONPATH=src python -m pytest -qCovers shock-priority ordering, partial-fill capacity limits, no-over-allocation, fee scaling, adapter normalization, determinism, and ledger tamper detection.
MIT © 2025-2026 sadpig70