predict: probability-weighted inventory charge (DBU-732)

[tonylee08]

Summary

• Wires the probability-weighted inventory charge end to end: mints and closes are charged or rebated on the change in rate * D(W), where D(W) is the standard deviation of the pool's payout profile under a probability measure frozen at the market's first mint.
• The payout index stores each boundary's frozen weight and carries mass-weighted first moments per subtree, so a trade's range read is O(log n) — the weighted analog of predict: add a tick-weighted first moment to the payout tree (DBU-732) #1248's tick-weighted moment, with the frozen survival function replacing the tick coordinate, which is also what makes unbounded legs finite without a measurement window.
• Collected charges are escrowed in an isolated skew_reserve, rebates are paid only from it, and cumulative collections equal the current potential exactly; settlement releases the residual. inventory_skew_rate ships at 0 and is snapshotted per market.

D(W) = sqrt( sum q(S)*W(S)^2  -  ( sum q(S)*W(S) )^2 )

Why

This is the windowless alternative to the #1248 + #1250 pair: the same charge-on-deviation mechanism with one substitution — each settlement price counts by its frozen probability instead of equally. That substitution deletes the measurement window and everything the window owned: the fraction to size, the tenor scaling, the freeze on reference-tick landing, the mint gate behind it, and the zero-tick rounding edge. A price the market will almost certainly never reach carries almost no weight, so nothing has to be excluded.

The measure freezes from the first mint's own validated pricer, atomically with that mint. The book is empty at the freeze by construction, so every boundary the index ever creates carries a weight from one fixed surface; there is no admin step, no keeper, and no market-launch ordering constraint. Freezing is what makes the charge a state function: cycles telescope exactly and a round trip refunds to the unit, which the flow tests assert bit-for-bit through custody, across an oracle move.

Linear / Context

• DBU-732
• Alternative to predict: add a tick-weighted first moment to the payout tree (DBU-732) #1248 + predict: charge and rebate inventory skew (DBU-732) #1250 (windowed spread); measured against predict: add frozen-grid inventory impact #1252 (frozen-grid shortfall). At most one of the three designs should merge.

Key decisions

• Raw accumulators, no division in the fold. The totals carry payout * mass products at the 1e9 scale, with division deferred to the read. The earlier statistic-only commit divided inside the fold, which floored differently on open and close and ratcheted residue upward — fifty open-close cycles at a non-dividing payout/mass pair left an empty book scoring 273,861. Raw carriage makes the round trip exact by construction; a ragged-pair regression pins it.
• Freeze at first mint, not at creation or by admin step. Market creation has no pricer in hand; a separate initialization step (as in predict: add frozen-grid inventory impact #1252) creates an ordering constraint and an empty-book requirement. The first mint always has a validated pricer and an empty book, and the quote-vs-mutation consistency is structural: an unfrozen quote prices from the same live surface its mint installs.
• Escrow senior to fee revenue on the close path. A close can be charged (closing a leg of a complete set unbalances the book); the charge is the first claim on the payout and the fee is clamped against the remainder, so deep out-of-the-money closes stay closable. A close whose charge exceeds everything it releases aborts rather than under-collecting — predeploy/response-policies.md RP-29 records the trigger, blast radius, and why clamping is worse.
• Boundary weights live in the index nodes. Rotations and resummaries never evaluate a surface; a reused boundary must arrive with the weight it stores, and a mismatch aborts. Zero-rate markets pass zero weights and never read them.

Scope / Descoped

• In scope: the statistic, the index moments and range read, the frozen surface, quote/commit wiring, mint and close custody, config plumbing with bounds and their relational guards, events, docs, and unit/flow coverage.
• Descoped: any per-market admin rate path — the rate is template-snapshotted only, like the occupancy rate.

Measurement caveat

The earlier draft body leaned on rank-correlation-with-dispersion columns (0.983 / 0.951). An independent re-derivation reproduced those numbers exactly but showed the dispersion target rewards functional form: a control with the same shape and one constant volatility per cadence — no surface at all — scores 0.9948, and the target carries no per-market volatility variation for a measure to be credited with tracking. On the one metric grounded in realised loss at the single actual settlement price, this measure scores 0.4330 against 0.4488 for #1252 and 0.3918 for the windowed form. The case for this design is therefore not the dispersion columns: it is that it beats the windowed form on the clean metric while deleting the window's defect class, at a per-mint marginal of ~209 instruction units against the windowed form's ~294 (rate-zero baseline 179 against main's 175), with ~30 units attributable to the charge itself. On a rebuilt dispersion benchmark whose target varies per market, the measure's surface holds while every no-information control falls, so its rank quality survives the control that invalidated the original benchmark.

Tests

• sui move test --path packages/predict --gas-limit 100000000000 (CI-pinned toolchain): 536 passed, 0 failed, on the branch merged with current main (referral fees, config-history events, settlement fallback, and the calibrated default economics all composed and re-verified; the skew flow tests pin their own fee floor, so they are default-independent).
• New: inventory_weighted_tests (raw-unit arithmetic, ragged round trip, ratchet-free cycles, stacked drains), strike_payout_tree_weighted_sum_tests (hand-derived per-position identities, sentinel legs, rebalanced/drained books, weight-mismatch and inversion aborts), inventory_skew_flow_tests (custody end to end: charge into escrow, complete-set rebate exact, round-trip refund across an oracle move, close-side charge and drain, two half-closes draining like one full close, skew and inventory-impact escrows stacking in isolation, settlement release, zero-rate inertness, and the RP-29 abort reached via a worthless-leg close), plus config bounds, the rate/fee-floor relational guards, the skew-escrow guard's abort test, and an exact end-to-end magnitude pin: for one ATM digital the deviation is flat in the frozen mass to first order, so the scipy-derived reference up price pins the quoted charge at exactly 2,499,999 across the whole reference budget — closing the seam between the frozen surface, the mass, and the rate that relational tests alone cannot see.
• The accumulator, read, and escrow identities are additionally pinned off-chain by an exact-integer reference simulation over randomized adversarial books (interleaved partial opens/closes, flat-stretch and cliff weight profiles): committed accumulators match from-scratch recomputation bit for bit, the escrow equals the potential after every operation, and the deviation matches the exact rational standard deviation.

Risk

Ships inert (inventory_skew_rate = 0): no market charges, freezes, or evaluates a weight until an admin sets a template rate, and existing markets never change. The mechanism's custody is isolated in its own reserve with the backing invariant asserted after every cash-mutating flow.

🤖 Generated with Claude Code

[0xaslan]

can we assert this earlier, when inventory_skew_rate is being set? if this assertion is ever triggerable, then it bricks market creation, right?

[0xaslan]

should we rename to inventory_charge / inventory_rebate?