unrip/PROOF.md

# Implementation Proof: settlement-aware strategy and inventory-skew controls

Status: open
Opened: 2026-04-10

## Target outcome
The strategy should stop behaving like a one-dimensional edge filter and start making inventory-aware choices that are explainable from durable data.

For each live BTC/EURe quote the operator must be able to answer:
- whether the quote was attractive on raw reference edge
- whether trading that side improves or worsens the current inventory skew
- whether the threshold used for that quote was the base threshold or an inventory-adjusted threshold
- whether recent settlement outcomes support or weaken confidence in submitting more quotes on that side
- why the strategy withheld, approved, or size-limited the quote

## Why this is the next architecture test
The previous turn made submission, not-fill, and settlement-attributed completion visible. It proved that the repo can now distinguish accepted quote responses from actual asset movement.

The next false path is strategy behavior that ignores that truth:
- a quote may clear the raw 1.49% edge but move inventory further away from the preferred BTC/EURe mix
- the opposite side may be blocked by inventory, stale price, or poor recent fill evidence
- portfolio-vs-hold movement is still not realized trade PnL and must not be used as if it were
- simply lowering the edge threshold further would be risk widening without proof

This turn is successful only if strategy decisions become reproducible from explicit edge, inventory-skew, and settlement-outcome inputs.

## Scope
- [I015] Benchmark-aware strategy thresholds and inventory-skewed fees: compare live inventory against deposit-time hold and target BTC/EURe mix before quoting away preferred inventory.
- Active venue and pair only: NEAR Intents BTC/EURe.
- Preserve the approved base edge threshold of `1.49%` unless the user explicitly approves a different value.
- Preserve the current max notional unless the user explicitly approves a different value.
- Use existing durable portfolio metrics, inventory snapshots, reference prices, decisions, commands, execution results, and quote outcome attributions.

## Assumptions
- The current BTC/EURe inventory mix has a preferred target or policy that can be encoded with repo-owned config.
- The first inventory policy can be simple and explicit, for example target BTC value percentage plus a tolerance band.
- Quote outcome records are good enough to compute side-level recent submission, not-fill, and completion counts, while remaining honest about heuristic settlement attribution.
- Benchmark comparisons can guide strategy but are not realized PnL.

## Turn-shaping rules
- Do not lower `STRATEGY_GROSS_THRESHOLD_PCT` below `1.49` in this turn without explicit user approval.
- Do not increase `STRATEGY_MAX_NOTIONAL_EURE` in this turn without explicit user approval.
- Do not add live funds or move funds.
- Do not claim inventory-skew benefit as realized profit.
- Do not hide a base-threshold pass behind a generic rejection; expose the decisive strategy reason.
- If recent outcome confidence is used, show the window and counts behind it.

## Non-goals
- No new venue integration.
- No new treasury fee ledger.
- No generalized optimizer or ML strategy.
- No broad backtesting workbench.
- No tax, accounting, or realized net PnL claims.
- No automatic funding, withdrawal, or treasury rebalancing.

## Required operator behavior

### Strategy threshold truth
Every recent strategy decision must expose:
- base threshold
- effective threshold
- inventory adjustment, if any
- outcome-confidence adjustment, if any
- final decisive reason

### Inventory-skew truth
For every quote decision the dashboard must show:
- current BTC and EURe spendable value
- target BTC/EURe value mix or configured policy
- current skew versus target
- whether the proposed trade moves inventory toward or away from target

### Outcome-confidence truth
If recent quote outcomes influence approval or threshold:
- submitted-only rows must not count as completed
- not-filled rows must be separate from strategy rejections and executor blocks
- heuristic completed rows must be counted as heuristic, not venue-terminal fills

## Semantic invariants
The implementation and tests must enforce at least:
- `submitted` outcome evidence cannot improve fill-confidence as if completed
- inventory-skew improvement is not realized PnL
- base edge and effective edge must both be visible when they differ
- insufficient inventory remains distinct from inventory-skew rejection
- strategy rejection remains distinct from executor blocking
- no threshold lower than `1.49%` is deployed without explicit approval

## Definition of done
- Strategy decisions include explicit inventory-skew inputs and effective threshold fields.
- The strategy can approve, reject, or size-limit a quote based on inventory direction with a decisive reason.
- Dashboard lifecycle or strategy rows show raw edge, effective threshold, skew direction, and decisive reason.
- Recent outcome counts are available to the strategy or dashboard without treating submission-only rows as fills.
- Regression tests cover inventory-skew direction, threshold adjustment, and the negative semantic invariants.
- The result is deployed through the repo workflow and validated against live service state and dashboard bootstrap data.

## Validation evidence required
- Automated tests for strategy decisions that pass raw edge but fail inventory-skew policy.
- Automated tests for strategy decisions where inventory improvement lowers friction or preserves the base threshold without lowering below `1.49%`.
- Automated tests proving submitted-only outcomes do not improve completion confidence.
- Live dashboard or `/state` evidence showing strategy decisions with base threshold, effective threshold, inventory skew, and decisive reason.
- Live evidence that strategy and executor remain armed after deployment if they were armed before rollout.

## Failure conditions
- The strategy still emits only `actionable` or `insufficient_inventory` without inventory-policy evidence.
- The dashboard cannot explain why a raw-edge quote was withheld by inventory policy.
- A submitted quote is treated as a completed or successful trade in any strategy confidence calculation.
- Benchmark or inventory-skew deltas are labeled as realized PnL.
- The deployed threshold is lower than `1.49%` without explicit user approval.

## Current real before this turn
- Live quote, decision, command, submission result, and quote outcome attribution records are durable.
- The dashboard separates submitted, rejected, blocked, not-filled, and completed rows.
- One historical quote is linked to a heuristic settled inventory delta.
- Recent submitted-only rows are visible without claiming asset movement.
- Portfolio-vs-simple-hold comparison is cash-flow adjusted and explicitly not realized PnL.

## Deliberately not built by this proof
- Full fee and cost attribution.
- Venue-native terminal fill ingestion.
- Automatic inventory rebalancing outside quote-response execution.
- Broader research/backtest UI.