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.