Archive implementation turn: settlement-aware strategy and inventory-skew controls
Proof: Preserve the completed implementation turn and record its outcome in the tracked archive. Assumptions: The archived files capture the relevant planning state for the completed turn. Still fake: Archiving does not validate the work by itself; external evidence still governs whether the result is trustworthy.
This commit is contained in:
philipp
parent
d5a7325e48
commit
52505a4257
5 changed files with 270 additions and 259 deletions
|
|
@ -14,6 +14,7 @@ Legacy note:
|
|||
- 2026-04-08: `runtime-health-sentinel-alert-routing-and-anomaly-detection` closed with status `passed`. Runtime health is now sentinel-owned, stale truth no longer renders healthy, alert delivery and safe containment exist, and deployment automation rolls all repo-owned services from push.
|
||||
- 2026-04-09: `quote-lifecycle-truth-and-execution-explanation` closed with status `passed`. Live operator surfaces now derive quote lifecycle from durable evidence, distinguish strategy rejection from executor blocking and submission, expose copyable quote traces, and no longer overclaim submission as completion or asset movement.
|
||||
- 2026-04-10: `execution-outcome-truth-and-settled-attribution` closed with status `passed`. Deployed e0dfd24, validated 1 completed heuristic settlement-attributed trade, 6 inferred not-filled outcomes, submitted-only rows without asset deltas, and stable armed strategy/executor at the approved 1.49% threshold.
|
||||
- 2026-04-12: `settlement-aware-strategy-and-inventory-skew-controls` closed with status `paused`. Paused after deploying approved 0.49 percent threshold, validating live quote intake recovery, and fixing NEAR Intents ingest reconnect-on-error; 0.49 percent submission resolved not_filled and full inventory-skew controls remain incomplete.
|
||||
## Research Turns
|
||||
|
||||
## Planning Events
|
||||
|
|
|
|||
|
|
@ -1,142 +1,5 @@
|
|||
# Implementation Turn: settlement-aware strategy and inventory-skew controls
|
||||
# Implementation Turn
|
||||
|
||||
Status: open
|
||||
Opened: 2026-04-10
|
||||
Status: idle
|
||||
|
||||
## Goal
|
||||
Use quote outcome truth, live inventory, and benchmark hold comparisons to make strategy thresholds and side selection explicit so the system trades only when evidence says the execution opportunity is worth changing inventory.
|
||||
|
||||
## Selected backlog items
|
||||
- [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. tags=strategy,inventory,pnl
|
||||
|
||||
## Design rules
|
||||
- Keep the approved base threshold at `1.49%`.
|
||||
- Keep notional limits unchanged unless separately approved.
|
||||
- Treat inventory policy as strategy evidence, not as profitability truth.
|
||||
- Keep submitted, not-filled, and completed outcome counts semantically separate.
|
||||
- Store enough fields on each decision to replay why the strategy approved or rejected a quote.
|
||||
|
||||
## Problem statement
|
||||
The current system can now say whether submitted quotes became linked asset movement, inferred not-fills, or are still submitted-only. The strategy still mostly answers a simpler question: does raw reference edge clear the threshold and is source inventory available?
|
||||
|
||||
That is not enough for a real operator workflow. A quote that clears raw edge may still sell down scarce inventory, worsen the BTC/EURe mix, or repeat a side with poor recent outcome evidence. Conversely, a quote with the same raw edge may be more desirable if it moves inventory toward target.
|
||||
|
||||
This turn should make that policy explicit and visible.
|
||||
|
||||
## Backend changes
|
||||
|
||||
### 1. Define strategy inventory policy
|
||||
- Add repo-owned config for target BTC value share and tolerance band.
|
||||
- Use current spendable BTC/EURe inventory plus latest reference price to compute current value mix.
|
||||
- For a candidate quote, compute projected post-trade mix using the proposed maker-side asset deltas.
|
||||
- Classify direction as `improves_inventory`, `within_band`, or `worsens_inventory`.
|
||||
- Keep policy disabled or neutral if required inputs are missing, with a visible reason.
|
||||
|
||||
### 2. Compute effective threshold
|
||||
- Keep `base_threshold_pct = 1.49`.
|
||||
- Add an explicit `effective_threshold_pct` to each decision.
|
||||
- If inventory direction worsens target skew, require extra edge or reject with `inventory_skew_worsens`.
|
||||
- If inventory direction improves target skew, do not lower below the approved base threshold unless the user separately approves it.
|
||||
- Store the adjustment components separately from the final threshold.
|
||||
|
||||
### 3. Add outcome-confidence inputs
|
||||
- Aggregate recent quote outcomes by side over a small explicit window.
|
||||
- Count submitted, not-filled, completed-heuristic, and completed-linked separately.
|
||||
- Do not count submitted as completion.
|
||||
- If outcome confidence affects threshold or reason, store the exact counts and window on the decision.
|
||||
|
||||
### 4. Extend durable decision payloads
|
||||
Each strategy decision should include:
|
||||
- `base_threshold_pct`
|
||||
- `effective_threshold_pct`
|
||||
- `threshold_adjustments`
|
||||
- `inventory_policy`
|
||||
- `inventory_skew_before`
|
||||
- `inventory_skew_after`
|
||||
- `inventory_direction`
|
||||
- `outcome_confidence`
|
||||
- `decision_reason`
|
||||
|
||||
### 5. Dashboard aggregation
|
||||
- Show base threshold and effective threshold on recent strategy/lifecycle rows.
|
||||
- Show inventory direction and decisive policy reason.
|
||||
- Keep quote ids copyable and full lifecycle reason visible.
|
||||
- Add a compact strategy policy panel with current target mix, current mix, and recent outcome counts.
|
||||
|
||||
## UI changes
|
||||
|
||||
### Strategy page
|
||||
- Add columns or row details for:
|
||||
- raw edge
|
||||
- base threshold
|
||||
- effective threshold
|
||||
- inventory direction
|
||||
- decisive reason
|
||||
- Keep successful-trade and lifecycle sections truthful from the previous turn.
|
||||
|
||||
### Funds page
|
||||
- Keep `Portfolio vs simple hold` separate from realized PnL.
|
||||
- If inventory target mix is shown on Funds, label it as policy context, not profit.
|
||||
|
||||
### System page
|
||||
- Surface strategy policy config and freshness only if it is directly useful for operator validation.
|
||||
|
||||
## Edge cases
|
||||
- Missing price: reject or defer with `reference_price_unavailable`.
|
||||
- Missing inventory: reject or defer with `inventory_unavailable`.
|
||||
- Candidate quote has unsupported assets: reject with `unsupported_pair`.
|
||||
- Source inventory is insufficient: keep `insufficient_inventory`, not `inventory_skew_worsens`.
|
||||
- Quote improves skew but does not clear base threshold: reject with a reason that says raw edge failed base threshold.
|
||||
- Recent outcomes are all submitted-only: outcome confidence is unknown, not good.
|
||||
- Recent movement is heuristic: count separately from linked terminal settlement.
|
||||
|
||||
## Concrete implementation order
|
||||
|
||||
### Phase 1. Model and tests
|
||||
- Add pure helper functions for inventory value mix, projected post-trade mix, direction classification, and effective threshold.
|
||||
- Add tests for improving, neutral, and worsening inventory directions.
|
||||
- Add tests that threshold never drops below `1.49`.
|
||||
|
||||
### Phase 2. Strategy integration
|
||||
- Wire helpers into `src/core/strategy.mjs` and `src/apps/strategy-engine.mjs`.
|
||||
- Extend emitted decision payloads with policy fields.
|
||||
- Preserve existing execution command shape unless size-limiting is implemented.
|
||||
|
||||
### Phase 3. Outcome-confidence integration
|
||||
- Load or derive recent outcome counts from existing quote outcome records where the strategy process can access them.
|
||||
- If direct DB access from strategy is too invasive, expose counts only on the dashboard in this turn and record that strategy-side outcome adjustment remains fake.
|
||||
- Add regression tests for submitted-only counts.
|
||||
|
||||
### Phase 4. Operator surfaces
|
||||
- Update dashboard bootstrap and Strategy page to render the new policy fields.
|
||||
- Ensure no operator-facing `Actionable` label returns.
|
||||
- Ensure no submitted-only row is described as completed or successful.
|
||||
|
||||
### Phase 5. Deploy and validate
|
||||
- Run targeted tests plus full `npm test`.
|
||||
- Build the dashboard bundle.
|
||||
- Commit with required proof body.
|
||||
- Push to `forgejo/main`.
|
||||
- Validate rollout image, strategy state, executor state, dashboard bootstrap, and at least one recent decision carrying inventory-policy fields.
|
||||
|
||||
## Test plan
|
||||
- Unit tests for inventory-skew direction.
|
||||
- Unit tests for effective threshold calculation.
|
||||
- Unit tests for missing inputs and insufficient inventory reason precedence.
|
||||
- Dashboard tests for base/effective threshold rendering.
|
||||
- Negative tests:
|
||||
- submitted-only outcome count does not improve fill confidence
|
||||
- inventory-skew comparison is not labeled realized PnL
|
||||
- threshold below `1.49` is rejected or clamped unless explicitly configured in a test-only override
|
||||
|
||||
## Validation checklist against the proof
|
||||
- Live strategy `/state` shows decisions with inventory-policy fields.
|
||||
- Dashboard Strategy page can explain a quote that passed raw edge but was withheld or size-limited by inventory policy.
|
||||
- Dashboard Strategy page can explain a quote that improves inventory and clears base threshold.
|
||||
- Executor remains armed if it was armed before deployment.
|
||||
- The repo still deploys fully from push without manual cluster reconciliation.
|
||||
|
||||
## Known fakes allowed at start of this turn
|
||||
- Realized net PnL remains unavailable without fee/cost attribution.
|
||||
- Venue-native terminal fill events remain unavailable.
|
||||
- Outcome-confidence may be dashboard-only if strategy DB access is not justified in the implementation.
|
||||
No approved implementation turn is active yet.
|
||||
|
|
|
|||
122
PROOF.md
122
PROOF.md
|
|
@ -1,121 +1,5 @@
|
|||
# Implementation Proof: settlement-aware strategy and inventory-skew controls
|
||||
# Implementation Proof
|
||||
|
||||
Status: open
|
||||
Opened: 2026-04-10
|
||||
Status: idle
|
||||
|
||||
## 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.
|
||||
No approved implementation proof is active yet.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,142 @@
|
|||
# Implementation Turn: settlement-aware strategy and inventory-skew controls
|
||||
|
||||
Status: open
|
||||
Opened: 2026-04-10
|
||||
|
||||
## Goal
|
||||
Use quote outcome truth, live inventory, and benchmark hold comparisons to make strategy thresholds and side selection explicit so the system trades only when evidence says the execution opportunity is worth changing inventory.
|
||||
|
||||
## Selected backlog items
|
||||
- [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. tags=strategy,inventory,pnl
|
||||
|
||||
## Design rules
|
||||
- Keep the approved base threshold at `1.49%`.
|
||||
- Keep notional limits unchanged unless separately approved.
|
||||
- Treat inventory policy as strategy evidence, not as profitability truth.
|
||||
- Keep submitted, not-filled, and completed outcome counts semantically separate.
|
||||
- Store enough fields on each decision to replay why the strategy approved or rejected a quote.
|
||||
|
||||
## Problem statement
|
||||
The current system can now say whether submitted quotes became linked asset movement, inferred not-fills, or are still submitted-only. The strategy still mostly answers a simpler question: does raw reference edge clear the threshold and is source inventory available?
|
||||
|
||||
That is not enough for a real operator workflow. A quote that clears raw edge may still sell down scarce inventory, worsen the BTC/EURe mix, or repeat a side with poor recent outcome evidence. Conversely, a quote with the same raw edge may be more desirable if it moves inventory toward target.
|
||||
|
||||
This turn should make that policy explicit and visible.
|
||||
|
||||
## Backend changes
|
||||
|
||||
### 1. Define strategy inventory policy
|
||||
- Add repo-owned config for target BTC value share and tolerance band.
|
||||
- Use current spendable BTC/EURe inventory plus latest reference price to compute current value mix.
|
||||
- For a candidate quote, compute projected post-trade mix using the proposed maker-side asset deltas.
|
||||
- Classify direction as `improves_inventory`, `within_band`, or `worsens_inventory`.
|
||||
- Keep policy disabled or neutral if required inputs are missing, with a visible reason.
|
||||
|
||||
### 2. Compute effective threshold
|
||||
- Keep `base_threshold_pct = 1.49`.
|
||||
- Add an explicit `effective_threshold_pct` to each decision.
|
||||
- If inventory direction worsens target skew, require extra edge or reject with `inventory_skew_worsens`.
|
||||
- If inventory direction improves target skew, do not lower below the approved base threshold unless the user separately approves it.
|
||||
- Store the adjustment components separately from the final threshold.
|
||||
|
||||
### 3. Add outcome-confidence inputs
|
||||
- Aggregate recent quote outcomes by side over a small explicit window.
|
||||
- Count submitted, not-filled, completed-heuristic, and completed-linked separately.
|
||||
- Do not count submitted as completion.
|
||||
- If outcome confidence affects threshold or reason, store the exact counts and window on the decision.
|
||||
|
||||
### 4. Extend durable decision payloads
|
||||
Each strategy decision should include:
|
||||
- `base_threshold_pct`
|
||||
- `effective_threshold_pct`
|
||||
- `threshold_adjustments`
|
||||
- `inventory_policy`
|
||||
- `inventory_skew_before`
|
||||
- `inventory_skew_after`
|
||||
- `inventory_direction`
|
||||
- `outcome_confidence`
|
||||
- `decision_reason`
|
||||
|
||||
### 5. Dashboard aggregation
|
||||
- Show base threshold and effective threshold on recent strategy/lifecycle rows.
|
||||
- Show inventory direction and decisive policy reason.
|
||||
- Keep quote ids copyable and full lifecycle reason visible.
|
||||
- Add a compact strategy policy panel with current target mix, current mix, and recent outcome counts.
|
||||
|
||||
## UI changes
|
||||
|
||||
### Strategy page
|
||||
- Add columns or row details for:
|
||||
- raw edge
|
||||
- base threshold
|
||||
- effective threshold
|
||||
- inventory direction
|
||||
- decisive reason
|
||||
- Keep successful-trade and lifecycle sections truthful from the previous turn.
|
||||
|
||||
### Funds page
|
||||
- Keep `Portfolio vs simple hold` separate from realized PnL.
|
||||
- If inventory target mix is shown on Funds, label it as policy context, not profit.
|
||||
|
||||
### System page
|
||||
- Surface strategy policy config and freshness only if it is directly useful for operator validation.
|
||||
|
||||
## Edge cases
|
||||
- Missing price: reject or defer with `reference_price_unavailable`.
|
||||
- Missing inventory: reject or defer with `inventory_unavailable`.
|
||||
- Candidate quote has unsupported assets: reject with `unsupported_pair`.
|
||||
- Source inventory is insufficient: keep `insufficient_inventory`, not `inventory_skew_worsens`.
|
||||
- Quote improves skew but does not clear base threshold: reject with a reason that says raw edge failed base threshold.
|
||||
- Recent outcomes are all submitted-only: outcome confidence is unknown, not good.
|
||||
- Recent movement is heuristic: count separately from linked terminal settlement.
|
||||
|
||||
## Concrete implementation order
|
||||
|
||||
### Phase 1. Model and tests
|
||||
- Add pure helper functions for inventory value mix, projected post-trade mix, direction classification, and effective threshold.
|
||||
- Add tests for improving, neutral, and worsening inventory directions.
|
||||
- Add tests that threshold never drops below `1.49`.
|
||||
|
||||
### Phase 2. Strategy integration
|
||||
- Wire helpers into `src/core/strategy.mjs` and `src/apps/strategy-engine.mjs`.
|
||||
- Extend emitted decision payloads with policy fields.
|
||||
- Preserve existing execution command shape unless size-limiting is implemented.
|
||||
|
||||
### Phase 3. Outcome-confidence integration
|
||||
- Load or derive recent outcome counts from existing quote outcome records where the strategy process can access them.
|
||||
- If direct DB access from strategy is too invasive, expose counts only on the dashboard in this turn and record that strategy-side outcome adjustment remains fake.
|
||||
- Add regression tests for submitted-only counts.
|
||||
|
||||
### Phase 4. Operator surfaces
|
||||
- Update dashboard bootstrap and Strategy page to render the new policy fields.
|
||||
- Ensure no operator-facing `Actionable` label returns.
|
||||
- Ensure no submitted-only row is described as completed or successful.
|
||||
|
||||
### Phase 5. Deploy and validate
|
||||
- Run targeted tests plus full `npm test`.
|
||||
- Build the dashboard bundle.
|
||||
- Commit with required proof body.
|
||||
- Push to `forgejo/main`.
|
||||
- Validate rollout image, strategy state, executor state, dashboard bootstrap, and at least one recent decision carrying inventory-policy fields.
|
||||
|
||||
## Test plan
|
||||
- Unit tests for inventory-skew direction.
|
||||
- Unit tests for effective threshold calculation.
|
||||
- Unit tests for missing inputs and insufficient inventory reason precedence.
|
||||
- Dashboard tests for base/effective threshold rendering.
|
||||
- Negative tests:
|
||||
- submitted-only outcome count does not improve fill confidence
|
||||
- inventory-skew comparison is not labeled realized PnL
|
||||
- threshold below `1.49` is rejected or clamped unless explicitly configured in a test-only override
|
||||
|
||||
## Validation checklist against the proof
|
||||
- Live strategy `/state` shows decisions with inventory-policy fields.
|
||||
- Dashboard Strategy page can explain a quote that passed raw edge but was withheld or size-limited by inventory policy.
|
||||
- Dashboard Strategy page can explain a quote that improves inventory and clears base threshold.
|
||||
- Executor remains armed if it was armed before deployment.
|
||||
- The repo still deploys fully from push without manual cluster reconciliation.
|
||||
|
||||
## Known fakes allowed at start of this turn
|
||||
- Realized net PnL remains unavailable without fee/cost attribution.
|
||||
- Venue-native terminal fill events remain unavailable.
|
||||
- Outcome-confidence may be dashboard-only if strategy DB access is not justified in the implementation.
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
# 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.
|
||||
Loading…
Add table
Reference in a new issue