[btorressz]

Summary

Implements HyperAMM Phase 5 directly on top of the accepted Phase 4.1 foundation.

Inventory architecture

• Adds normalized InventoryState plus pure deterministic InventoryPolicy.
• PAPER inventory is the signed sum of economic fills only; resting/cancelled/rejected orders do not create position.
• TESTNET inventory is authoritative Hyperliquid account state via Info.user_state(account_address) / assetPositions[].position.szi.
• Missing, stale, malformed, reconciliation-uncertain, or UNKNOWN TESTNET exposure fails closed instead of defaulting inventory to zero.
• Decisions bind to an inventory version checked by final execution authority.

Quoting

• Keeps market fair value and strategy reservation price separate.
• Uses r = clamp((position-target)/soft_limit, -1, 1).
• Reservation shift is -r * max_inventory_price_skew_bps.
• Long inventory shifts reservation down; short inventory shifts it up.
• Bounded side-size multipliers apply to AMM-derived excess above the existing base_order_size floor, preserving the Phase 4.1 baseline and curve profile.
• Neutral inventory preserves the executable Phase 4.1 ladder.
• Tick normalization, sorting, no-cross constraints, max-order-size, quote-distance, and aggregate-notional risk remain downstream authority.

Hard limits

• Long hard limit suppresses inventory-increasing BIDs; inventory-reducing ASKs may continue.
• Short hard limit suppresses inventory-increasing ASKs; inventory-reducing BIDs may continue.
• Existing KEEP / CREATE / REPLACE / CANCEL reconciliation cancels newly forbidden resting quotes.
• Hard-limit safety remains active even when ordinary price/size skew is disabled.

Runtime, API, and terminal

• PAPER fills and TESTNET venue/account refreshes wake the existing serialized strategy loop for prompt requoting.
• GET /api/v1/positions exposes normalized inventory and computed skew state.
• Position observability remains available during a transient market-price startup gap; market-derived reservation fields remain null rather than fabricated.
• /ws/terminal includes inventory, ratio, reservation, price skew, multipliers, hard-limit state, source, freshness, and version.
• React terminal adds Inventory & Skew metrics/gauge, grouped controls, and quote neutral/final explainability.

Tests and documentation

• Adds focused Phase 5 math, composition, fill, hard-limit, fail-closed, runtime/version, TESTNET normalization, and positions API coverage.
• Adds docs/INVENTORY_SKEW.md; updates README, architecture, AMM math, and roadmap.
• Adds .github/workflows/phase5-acceptance.yml using Python 3.12 and Node 24.

Acceptance — final head 0403b777c02f109d8163d2dfdf60a14f7dc2dbec

• pytest: 105 passed, 1 warning in 1.87s
• FastAPI startup: PASS
• GET /api/v1/health: HTTP 200
  • {"status":"ok","app":"HyperAMM","market_connection":"CONNECTED","stale":false,"mode":"DEMO","simulated":true}
• npm run typecheck: PASS — tsc -b --pretty false
• npm run build: PASS — tsc -b && vite build, Vite production build completed in 2.08s
• git diff --check origin/main...HEAD: PASS, no output
• Phase 5 CSS syntax warning found during an earlier validation pass was corrected; the final build has no Phase 5 CSS syntax error.
• Live signed Hyperliquid TESTNET order/fill validation: not exercised because no explicit credentials were provided. Offline normalization and fail-closed acceptance remain covered.

Acceptance result

Phase 5 passes the requested offline acceptance gate. Phase 6 remains unstarted and can begin after this PR is merged.

Scope boundary

No Phase 6 volatility/book-imbalance logic, Phase 7 perp/funding adaptation, Phase 8 oracle/risk-firewall expansion, AI/LLM agents, optimization solvers, or mainnet execution is included.