ARCHIVE.md

@@ -13,7 +13,6 @@ Legacy note:
 - 2026-04-08: `cow-protocol-intent-based-venue-integration` closed with status `paused`. The CoW venue integration turn is paused after cluster investigation showed a real NEAR Intents ingest outage exposed a larger observability gap: the dashboard did not escalate stale quote flow or disconnected websocket clients, so runtime health and alerting need to be strengthened before adding a second venue.
 - 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.
 ## Research Turns
 
 ## Planning Events
@@ -28,4 +27,3 @@ Legacy note:
 - 2026-04-08: opened implementation turn `runtime-health-sentinel-alert-routing-and-anomaly-detection` from backlog items I020.
 - 2026-04-08: opened implementation turn `quote-lifecycle-truth-and-execution-explanation` from backlog items I021.
 - 2026-04-09: opened implementation turn `execution-outcome-truth-and-settled-attribution` from backlog items I017, I018.
-- 2026-04-10: opened implementation turn `settlement-aware-strategy-and-inventory-skew-controls` from backlog items I015.

BACKLOG.md

@@ -20,6 +20,7 @@ Rules:
 - [I012] Quotes and execution analytics workbench: live quote tape, quote count and volume windows, size-bucket distributions, oracle-deviation views, per-quote decision and execution trace, and matched-only filters.
 - [I013] Benchmark and PnL analytics: compare trade PnL versus mark-to-market, all-BTC hold, all-EURe hold, passive 50/50 hold, and hindsight trade quality against later benchmarks.
 
+- [I015] (soon) 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
 - [I016] (soon) Treasury cashflow and fee ledger: durably record deposits, withdrawals, bridge or network costs, and other non-trade cashflows so dashboard profit can move from mark-to-market to true net PnL. tags=pnl,fees,treasury
 ## Research Candidates
 - [R001] Compare Kraken and CoinGecko drift and freshness for the assets needed to price the active pair.

IMPLEMENTATION.md

@@ -1,142 +1,174 @@
-# Implementation Turn: settlement-aware strategy and inventory-skew controls
+# Implementation Turn: execution outcome truth and settled attribution
 
 Status: open
-Opened: 2026-04-10
+Opened: 2026-04-09
 
 ## 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.
+Make the live BTC/EURe quote path more real by durably linking submission, downstream outcome, and settled inventory attribution so the dashboard can distinguish completion from submission and show real post-trade movement where available.
 
 ## 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
+- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
+- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
 
 ## Design rules
-- Keep the approved base threshold at `1.49%`.
+- Treat downstream outcome and settlement truth as part of the same shared evidence path, not separate dashboard decoration.
-- Keep notional limits unchanged unless separately approved.
+- Preserve the current turn’s semantic boundary: submission is still non-terminal.
-- Treat inventory policy as strategy evidence, not as profitability truth.
+- Store explicit linkage and attribution records instead of recomputing ad hoc joins differently across pages.
-- Keep submitted, not-filled, and completed outcome counts semantically separate.
+- If a linkage is heuristic, store the heuristic and expose uncertainty.
-- Store enough fields on each decision to replay why the strategy approved or rejected a quote.
+- Keep the first implementation narrow to the active pair and current venue.
 
-## Problem statement
+## Problem statement for this turn
-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?
+The repository now explains why a quote was rejected, blocked, or submitted, but it still does not fully explain what happened after submission:
+- terminal outcome truth is absent or disconnected
+- recent submission tables are still quote-term oriented rather than settlement oriented
+- completed and realized labels cannot yet be proven from repo-owned durable records
+- later analytics such as markout and realized contribution have no canonical per-quote linkage record
 
-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 must therefore improve:
+- downstream outcome ingestion or linkage
+- quote-to-outcome storage
+- settlement attribution storage
+- operator rendering of completed versus submission-only rows
 
-This turn should make that policy explicit and visible.
+## Required evidence model
+Add one repo-owned quote outcome and attribution model with at least:
+- `quote_id`
+- `decision_id`
+- `command_id`
+- `execution_result_status`
+- `outcome_status`
+- `outcome_observed_at`
+- `outcome_source`
+- `attribution_status`
+- `attributed_inventory_delta`
+- `attribution_method`
+- `markout_reference_price` where implemented
+
+Suggested vocabulary:
+- outcome states:
+  - `submitted`
+  - `awaiting_outcome`
+  - `not_filled`
+  - `completed`
+- attribution states:
+  - `unattributed`
+  - `heuristic_match`
+  - `linked_settlement`
 
 ## Backend changes
 
-### 1. Define strategy inventory policy
+### 1. Add durable outcome linkage
-- Add repo-owned config for target BTC value share and tolerance band.
+- inspect available downstream event sources, solver relay data, inventory movement evidence, and existing history tables
-- Use current spendable BTC/EURe inventory plus latest reference price to compute current value mix.
+- add a durable record or derived snapshot that links a submitted quote to later terminal outcome when possible
-- For a candidate quote, compute projected post-trade mix using the proposed maker-side asset deltas.
+- preserve source timestamps and raw evidence pointers
-- 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
+### 2. Add durable settlement attribution
-- Keep `base_threshold_pct = 1.49`.
+- link completed quote outcomes to later inventory movement for the active assets
-- Add an explicit `effective_threshold_pct` to each decision.
+- store both raw units and formatted operator values
-- If inventory direction worsens target skew, require extra edge or reject with `inventory_skew_worsens`.
+- track whether the attribution is exact or heuristic
-- If inventory direction improves target skew, do not lower below the approved base threshold unless the user separately approves it.
+- do not report net realized contribution unless costs are explicitly present
-- Store the adjustment components separately from the final threshold.
 
-### 3. Add outcome-confidence inputs
+### 3. Extend dashboard bootstrap models
-- Aggregate recent quote outcomes by side over a small explicit window.
+- expose recent quote outcome rows with terminal evidence where available
-- Count submitted, not-filled, completed-heuristic, and completed-linked separately.
+- expose settled attribution separately from submitted quote terms
-- Do not count submitted as completion.
+- ensure summary metrics count completed outcomes and submission-only rows separately
-- If outcome confidence affects threshold or reason, store the exact counts and window on the decision.
 
-### 4. Extend durable decision payloads
+### 4. Prepare markout support on the same linkage path
-Each strategy decision should include:
+- if implemented in this turn, compute later reference-price markout from the linked quote or completion timestamp
-- `base_threshold_pct`
+- store it in a way that cannot be confused with realized settlement contribution
-- `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:
+- extend lifecycle rows so submitted paths can become `Awaiting outcome`, `Not filled`, or `Completed`
-  - raw edge
+- show linked outcome reason and settlement attribution state
-  - base threshold
+- keep quote, decision, and command trace ids visible
-  - 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.
+- separate:
-- If inventory target mix is shown on Funds, label it as policy context, not profit.
+  - recent submission terms
+  - recent settled attribution
+  - completed outcome ledger
+- if no settled attribution exists yet for a completed row, say that plainly
 
-### System page
+### Summary language
-- Surface strategy policy config and freshness only if it is directly useful for operator validation.
+- introduce distinct labels for:
+  - recent submissions
+  - recent completed outcomes
+  - recent settled attributions
+- never reuse one metric for all three concepts
 
 ## Edge cases
-- Missing price: reject or defer with `reference_price_unavailable`.
+- submitted row with no later evidence:
-- Missing inventory: reject or defer with `inventory_unavailable`.
+  render as `Submitted` or `Awaiting outcome`
-- Candidate quote has unsupported assets: reject with `unsupported_pair`.
+- explicit expiry or non-fill evidence:
-- Source inventory is insufficient: keep `insufficient_inventory`, not `inventory_skew_worsens`.
+  render as `Not filled`
-- Quote improves skew but does not clear base threshold: reject with a reason that says raw edge failed base threshold.
+- completed outcome with no attributable inventory delta yet:
-- Recent outcomes are all submitted-only: outcome confidence is unknown, not good.
+  render completion truthfully, but mark attribution as missing
-- Recent movement is heuristic: count separately from linked terminal settlement.
+- inventory movement with no unambiguous quote match:
+  keep unattributed and do not silently assign
+- multiple near-simultaneous quotes in the same direction:
+  require explicit or recorded heuristic linkage before claiming settlement
 
 ## Concrete implementation order
 
-### Phase 1. Model and tests
+### Phase 1. Discover and define outcome sources
-- Add pure helper functions for inventory value mix, projected post-trade mix, direction classification, and effective threshold.
+- inspect current relay, executor, and inventory evidence
-- Add tests for improving, neutral, and worsening inventory directions.
+- document what fields can carry downstream outcome and settlement linkage
-- Add tests that threshold never drops below `1.49`.
+- define exact versus heuristic attribution rules
 
-### Phase 2. Strategy integration
+### Phase 2. Implement durable outcome and attribution records
-- Wire helpers into `src/core/strategy.mjs` and `src/apps/strategy-engine.mjs`.
+- add storage or derived records for linked outcomes
-- Extend emitted decision payloads with policy fields.
+- add storage or derived records for settlement attribution
-- Preserve existing execution command shape unless size-limiting is implemented.
+- preserve raw references and timestamps
 
-### Phase 3. Outcome-confidence integration
+### Phase 3. Update dashboard aggregation
-- Load or derive recent outcome counts from existing quote outcome records where the strategy process can access them.
+- join recent lifecycle rows to outcome and attribution records
-- 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.
+- split summary metrics and ledgers by evidence strength
-- Add regression tests for submitted-only counts.
+- keep submission-only rows clearly non-terminal
 
-### Phase 4. Operator surfaces
+### Phase 4. Validate on live data
-- Update dashboard bootstrap and Strategy page to render the new policy fields.
+- prove at least one recent row remains submission-only
-- Ensure no operator-facing `Actionable` label returns.
+- prove blocked and rejected rows remain distinct
-- Ensure no submitted-only row is described as completed or successful.
+- prove a completed or non-fill row appears only with durable linked evidence
-
+- prove settled attribution is shown only when actual linked movement exists
-### 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 outcome linkage:
-- Unit tests for effective threshold calculation.
+  - submitted with no outcome
-- Unit tests for missing inputs and insufficient inventory reason precedence.
+  - submitted with non-fill outcome
-- Dashboard tests for base/effective threshold rendering.
+  - submitted with completed outcome
-- Negative tests:
+- unit tests for attribution:
-  - submitted-only outcome count does not improve fill confidence
+  - completed with linked settlement
-  - inventory-skew comparison is not labeled realized PnL
+  - completed without settlement yet
-  - threshold below `1.49` is rejected or clamped unless explicitly configured in a test-only override
+  - ambiguous movement remains unattributed
+- negative semantic tests:
+  - submission-only rows must not render completion
+  - markout must not be labeled realized
+  - quote terms must not be labeled settled asset delta
+- dashboard bootstrap tests for:
+  - separated summary metrics
+  - completed rows carrying explicit outcome evidence
+  - unattributed rows staying plainly unattributed
 
 ## Validation checklist against the proof
-- Live strategy `/state` shows decisions with inventory-policy fields.
+- recent rows separate submitted, awaiting, not-filled, and completed where evidence exists
-- Dashboard Strategy page can explain a quote that passed raw edge but was withheld or size-limited by inventory policy.
+- completed rows show explicit outcome linkage
-- Dashboard Strategy page can explain a quote that improves inventory and clears base threshold.
+- settled attribution is visible and clearly sourced
-- Executor remains armed if it was armed before deployment.
+- submission-only rows still do not claim completion or realized movement
-- The repo still deploys fully from push without manual cluster reconciliation.
+- remaining uncertainty is named plainly
 
-## Known fakes allowed at start of this turn
+## Failure modes to plan for
-- Realized net PnL remains unavailable without fee/cost attribution.
+- linking the wrong inventory movement to a quote
-- Venue-native terminal fill events remain unavailable.
+- mistaking inventory rebalance or treasury movement for trade settlement
-- Outcome-confidence may be dashboard-only if strategy DB access is not justified in the implementation.
+- rendering completed from incomplete venue evidence
+- blending markout and realized attribution into one metric
+- introducing hidden heuristics without storing them
+
+## Truth review checklist for this turn
+For every outcome or attribution field:
+- what exact durable event or snapshot backs it
+- how is the quote linked to it
+- is the linkage exact or heuristic
+- what wording would overclaim certainty
+- what regression test prevents that overclaim from returning

PROOF.md

@@ -1,121 +1,138 @@
-# Implementation Proof: settlement-aware strategy and inventory-skew controls
+# Implementation Proof: execution outcome truth and settled attribution
 
 Status: open
-Opened: 2026-04-10
+Opened: 2026-04-09
 
 ## 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.
+This turn proves that `unrip` can move recent quote rows past submission-only evidence and into durable downstream outcome truth.
 
-For each live BTC/EURe quote the operator must be able to answer:
+For the live NEAR Intents BTC/EURe system, the operator must be able to answer:
-- whether the quote was attractive on raw reference edge
+- was the quote merely submitted
-- whether trading that side improves or worsens the current inventory skew
+- did the venue later complete or not fill it
-- whether the threshold used for that quote was the base threshold or an inventory-adjusted threshold
+- what settled inventory delta, if any, was actually observed afterward
-- whether recent settlement outcomes support or weaken confidence in submitting more quotes on that side
+- what part of the post-trade change is still inferred versus durably linked
-- why the strategy withheld, approved, or size-limited the quote
 
-## Why this is the next architecture test
+## Why this is a meaningful 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 previous turn fixed an overclaiming dashboard, but it also exposed the next hard truth gap:
+- `submitted` is now shown truthfully as non-terminal evidence
+- downstream completion and non-fill states are still mostly absent from durable repo-owned data
+- recent asset-term tables still describe submitted quote terms, not settled inventory truth
+- realized attribution is still fake because quote response success is not the same thing as completed asset movement
 
-The next false path is strategy behavior that ignores that truth:
+That means the system is now honest about the gap, but the gap still exists. This turn is where the shared history path must become more real again.
-- 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.
+## Hypothesis
+`unrip` becomes materially more trustworthy if it durably links:
+- quote
+- strategy decision
+- execute command
+- executor submission result
+- downstream venue or relay outcome where available
+- later settled inventory deltas attributable to that quote
+
+The turn passes only if the operator can distinguish submission from later outcome and can inspect a recent completed path with explicit settled attribution instead of implied completion.
 
 ## 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.
+- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
-- Active venue and pair only: NEAR Intents BTC/EURe.
+- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
-- Preserve the approved base edge threshold of `1.49%` unless the user explicitly approves a different value.
+- Focus on the active NEAR Intents BTC/EURe venue and the repo-owned path already in production.
-- Preserve the current max notional unless the user explicitly approves a different value.
+- Cover recent rows first; historical backfill is secondary unless required to prove the live path.
-- 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 venue or relay emits enough downstream identifiers or status surfaces to link at least some submitted quotes to later terminal outcomes.
-- The first inventory policy can be simple and explicit, for example target BTC value percentage plus a tolerance band.
+- Inventory snapshots and durable history can support quote-to-settlement attribution for the active pair, even if the first version uses a narrow matching heuristic.
-- Quote outcome records are good enough to compute side-level recent submission, not-fill, and completion counts, while remaining honest about heuristic settlement attribution.
+- Some rows will still remain unattributed or partially inferred; the UI and stored records must say that plainly.
-- Benchmark comparisons can guide strategy but are not realized PnL.
+- This turn should prioritize truthful linkage and settlement evidence over broad analytics polish.
 
 ## Turn-shaping rules
-- Do not lower `STRATEGY_GROSS_THRESHOLD_PCT` below `1.49` in this turn without explicit user approval.
+- `submitted` remains non-terminal evidence.
-- Do not increase `STRATEGY_MAX_NOTIONAL_EURE` in this turn without explicit user approval.
+- `completed`, `not filled`, `settled`, `realized`, and `asset delta` are forbidden unless backed by a durable linked record representing that fact.
-- Do not add live funds or move funds.
+- If settlement attribution is heuristic rather than exact, the stored attribution record and operator surface must say so explicitly.
-- Do not claim inventory-skew benefit as realized profit.
+- Do not build a broad analytics suite before the quote-to-outcome path is durably linked.
-- Do not hide a base-threshold pass behind a generic rejection; expose the decisive strategy reason.
+- Prefer one repo-owned outcome and attribution model reused by storage, dashboard, and later analytics.
-- 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 PnL accounting for all treasury cashflows.
-- No generalized optimizer or ML strategy.
+- No broad historical backfill project unless needed to prove current-path linkage.
-- No broad backtesting workbench.
+- No strategy changes beyond what is required to preserve truthful lifecycle and attribution semantics.
-- No tax, accounting, or realized net PnL claims.
-- No automatic funding, withdrawal, or treasury rebalancing.
 
 ## Required operator behavior
 
-### Strategy threshold truth
+### Outcome truth
-Every recent strategy decision must expose:
+For a recent submitted quote, the dashboard must be able to render one of:
-- base threshold
+- `Submitted`
-- effective threshold
+- `Awaiting outcome`
-- inventory adjustment, if any
+- `Not filled`
-- outcome-confidence adjustment, if any
+- `Completed`
-- final decisive reason
 
-### Inventory-skew truth
+The label must be driven by the strongest durable evidence currently stored.
-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
+### Settlement truth
-If recent quote outcomes influence approval or threshold:
+For a recent completed quote, the operator must be able to inspect:
-- submitted-only rows must not count as completed
+- quote id
-- not-filled rows must be separate from strategy rejections and executor blocks
+- decision id
-- heuristic completed rows must be counted as heuristic, not venue-terminal fills
+- command id
+- executor result id or submission timestamp
+- linked terminal outcome evidence
+- linked settled asset delta or explicitly missing settled delta
+
+### Attribution truth
+If the system reports realized contribution, it must be derived from:
+- linked settled asset movement
+- explicit attributable costs where available
+
+If costs or full settlement are missing, the system must not claim net realized truth.
+
+### Markout truth
+If markout is stored for completed or submitted rows, it must:
+- be clearly labeled as later reference-price comparison
+- remain separate from realized settlement attribution
 
 ## Semantic invariants
 The implementation and tests must enforce at least:
-- `submitted` outcome evidence cannot improve fill-confidence as if completed
+- `submitted != completed`
-- inventory-skew improvement is not realized PnL
+- `completed` requires linked terminal outcome evidence
-- base edge and effective edge must both be visible when they differ
+- settled asset delta requires linked settlement evidence, not quote terms
-- insufficient inventory remains distinct from inventory-skew rejection
+- markout is not realized PnL
-- strategy rejection remains distinct from executor blocking
+- unattributed inventory movement must not be silently assigned to a quote
-- 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.
+- A durable quote outcome link exists from submission to later outcome where available.
-- The strategy can approve, reject, or size-limit a quote based on inventory direction with a decisive reason.
+- The repo stores an explicit per-quote outcome or attribution record for the active path.
-- Dashboard lifecycle or strategy rows show raw edge, effective threshold, skew direction, and decisive reason.
+- The dashboard can show at least one recent path as `Completed` only when durable linked evidence supports it.
-- Recent outcome counts are available to the strategy or dashboard without treating submission-only rows as fills.
+- The dashboard can show non-fill or still-awaiting paths truthfully where that evidence exists.
-- Regression tests cover inventory-skew direction, threshold adjustment, and the negative semantic invariants.
+- Recent settled asset delta or explicit lack of attribution is visible per completed row.
-- The result is deployed through the repo workflow and validated against live service state and dashboard bootstrap data.
+- Submission-term tables and summaries do not overclaim settled truth.
+- Regression tests cover the negative semantic boundaries above.
 
 ## Validation evidence required
-- Automated tests for strategy decisions that pass raw edge but fail inventory-skew policy.
+- direct evidence from deployed dashboard or bootstrap payload that recent rows separate `Submitted`, `Blocked`, `Rejected`, `Not filled`, and `Completed` when the evidence exists
-- Automated tests for strategy decisions where inventory improvement lowers friction or preserves the base threshold without lowering below `1.49%`.
+- direct evidence that a completed row shows linked settled attribution rather than quote terms alone
-- Automated tests proving submitted-only outcomes do not improve completion confidence.
+- direct evidence that a submission-only row still does not claim completion or realized asset movement
-- Live dashboard or `/state` evidence showing strategy decisions with base threshold, effective threshold, inventory skew, and decisive reason.
+- automated test evidence for quote-to-outcome linkage
-- Live evidence that strategy and executor remain armed after deployment if they were armed before rollout.
+- automated test evidence for settlement attribution boundaries
 
 ## Failure conditions
-- The strategy still emits only `actionable` or `insufficient_inventory` without inventory-policy evidence.
+- the system still cannot represent downstream terminal outcome beyond submission
-- The dashboard cannot explain why a raw-edge quote was withheld by inventory policy.
+- any UI or backend surface claims completion from submission-only evidence
-- A submitted quote is treated as a completed or successful trade in any strategy confidence calculation.
+- settled asset delta is still derived from quoted terms rather than linked settlement evidence
-- Benchmark or inventory-skew deltas are labeled as realized PnL.
+- markout or later reference comparison is presented as realized PnL
-- The deployed threshold is lower than `1.49%` without explicit user approval.
+- outcome attribution silently guesses across ambiguous rows without recording uncertainty
 
 ## Current real before this turn
-- Live quote, decision, command, submission result, and quote outcome attribution records are durable.
+- quote, decision, command, and execution submission result are durable
-- The dashboard separates submitted, rejected, blocked, not-filled, and completed rows.
+- the dashboard now renders those stages truthfully
-- One historical quote is linked to a heuristic settled inventory delta.
+- submission counts and recent submission terms are constrained to submission evidence
-- 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.
+- full treasury fee ledger
-- Venue-native terminal fill ingestion.
+- generalized tax or accounting treatment
-- Automatic inventory rebalancing outside quote-response execution.
+- multi-venue settlement harmonization
-- Broader research/backtest UI.
+
+## Prevention requirements for this proof
+- For every new `Completed`, `Not filled`, or realized attribution label:
+  - what exact durable record backs it
+  - what linkage key or heuristic connects it to the quote
+  - what uncertainty remains
+  - what regression test prevents future overclaiming

archive/implementation/20260410T092923Z-execution-outcome-truth-and-settled-attribution-implementation.md

@@ -1,174 +0,0 @@
-# Implementation Turn: execution outcome truth and settled attribution
-
-Status: open
-Opened: 2026-04-09
-
-## Goal
-Make the live BTC/EURe quote path more real by durably linking submission, downstream outcome, and settled inventory attribution so the dashboard can distinguish completion from submission and show real post-trade movement where available.
-
-## Selected backlog items
-- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
-- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
-
-## Design rules
-- Treat downstream outcome and settlement truth as part of the same shared evidence path, not separate dashboard decoration.
-- Preserve the current turn’s semantic boundary: submission is still non-terminal.
-- Store explicit linkage and attribution records instead of recomputing ad hoc joins differently across pages.
-- If a linkage is heuristic, store the heuristic and expose uncertainty.
-- Keep the first implementation narrow to the active pair and current venue.
-
-## Problem statement for this turn
-The repository now explains why a quote was rejected, blocked, or submitted, but it still does not fully explain what happened after submission:
-- terminal outcome truth is absent or disconnected
-- recent submission tables are still quote-term oriented rather than settlement oriented
-- completed and realized labels cannot yet be proven from repo-owned durable records
-- later analytics such as markout and realized contribution have no canonical per-quote linkage record
-
-This turn must therefore improve:
-- downstream outcome ingestion or linkage
-- quote-to-outcome storage
-- settlement attribution storage
-- operator rendering of completed versus submission-only rows
-
-## Required evidence model
-Add one repo-owned quote outcome and attribution model with at least:
-- `quote_id`
-- `decision_id`
-- `command_id`
-- `execution_result_status`
-- `outcome_status`
-- `outcome_observed_at`
-- `outcome_source`
-- `attribution_status`
-- `attributed_inventory_delta`
-- `attribution_method`
-- `markout_reference_price` where implemented
-
-Suggested vocabulary:
-- outcome states:
-  - `submitted`
-  - `awaiting_outcome`
-  - `not_filled`
-  - `completed`
-- attribution states:
-  - `unattributed`
-  - `heuristic_match`
-  - `linked_settlement`
-
-## Backend changes
-
-### 1. Add durable outcome linkage
-- inspect available downstream event sources, solver relay data, inventory movement evidence, and existing history tables
-- add a durable record or derived snapshot that links a submitted quote to later terminal outcome when possible
-- preserve source timestamps and raw evidence pointers
-
-### 2. Add durable settlement attribution
-- link completed quote outcomes to later inventory movement for the active assets
-- store both raw units and formatted operator values
-- track whether the attribution is exact or heuristic
-- do not report net realized contribution unless costs are explicitly present
-
-### 3. Extend dashboard bootstrap models
-- expose recent quote outcome rows with terminal evidence where available
-- expose settled attribution separately from submitted quote terms
-- ensure summary metrics count completed outcomes and submission-only rows separately
-
-### 4. Prepare markout support on the same linkage path
-- if implemented in this turn, compute later reference-price markout from the linked quote or completion timestamp
-- store it in a way that cannot be confused with realized settlement contribution
-
-## UI changes
-
-### Strategy page
-- extend lifecycle rows so submitted paths can become `Awaiting outcome`, `Not filled`, or `Completed`
-- show linked outcome reason and settlement attribution state
-- keep quote, decision, and command trace ids visible
-
-### Funds page
-- separate:
-  - recent submission terms
-  - recent settled attribution
-  - completed outcome ledger
-- if no settled attribution exists yet for a completed row, say that plainly
-
-### Summary language
-- introduce distinct labels for:
-  - recent submissions
-  - recent completed outcomes
-  - recent settled attributions
-- never reuse one metric for all three concepts
-
-## Edge cases
-- submitted row with no later evidence:
-  render as `Submitted` or `Awaiting outcome`
-- explicit expiry or non-fill evidence:
-  render as `Not filled`
-- completed outcome with no attributable inventory delta yet:
-  render completion truthfully, but mark attribution as missing
-- inventory movement with no unambiguous quote match:
-  keep unattributed and do not silently assign
-- multiple near-simultaneous quotes in the same direction:
-  require explicit or recorded heuristic linkage before claiming settlement
-
-## Concrete implementation order
-
-### Phase 1. Discover and define outcome sources
-- inspect current relay, executor, and inventory evidence
-- document what fields can carry downstream outcome and settlement linkage
-- define exact versus heuristic attribution rules
-
-### Phase 2. Implement durable outcome and attribution records
-- add storage or derived records for linked outcomes
-- add storage or derived records for settlement attribution
-- preserve raw references and timestamps
-
-### Phase 3. Update dashboard aggregation
-- join recent lifecycle rows to outcome and attribution records
-- split summary metrics and ledgers by evidence strength
-- keep submission-only rows clearly non-terminal
-
-### Phase 4. Validate on live data
-- prove at least one recent row remains submission-only
-- prove blocked and rejected rows remain distinct
-- prove a completed or non-fill row appears only with durable linked evidence
-- prove settled attribution is shown only when actual linked movement exists
-
-## Test plan
-- unit tests for outcome linkage:
-  - submitted with no outcome
-  - submitted with non-fill outcome
-  - submitted with completed outcome
-- unit tests for attribution:
-  - completed with linked settlement
-  - completed without settlement yet
-  - ambiguous movement remains unattributed
-- negative semantic tests:
-  - submission-only rows must not render completion
-  - markout must not be labeled realized
-  - quote terms must not be labeled settled asset delta
-- dashboard bootstrap tests for:
-  - separated summary metrics
-  - completed rows carrying explicit outcome evidence
-  - unattributed rows staying plainly unattributed
-
-## Validation checklist against the proof
-- recent rows separate submitted, awaiting, not-filled, and completed where evidence exists
-- completed rows show explicit outcome linkage
-- settled attribution is visible and clearly sourced
-- submission-only rows still do not claim completion or realized movement
-- remaining uncertainty is named plainly
-
-## Failure modes to plan for
-- linking the wrong inventory movement to a quote
-- mistaking inventory rebalance or treasury movement for trade settlement
-- rendering completed from incomplete venue evidence
-- blending markout and realized attribution into one metric
-- introducing hidden heuristics without storing them
-
-## Truth review checklist for this turn
-For every outcome or attribution field:
-- what exact durable event or snapshot backs it
-- how is the quote linked to it
-- is the linkage exact or heuristic
-- what wording would overclaim certainty
-- what regression test prevents that overclaim from returning

archive/implementation/20260410T092923Z-execution-outcome-truth-and-settled-attribution-proof.md

@@ -1,138 +0,0 @@
-# Implementation Proof: execution outcome truth and settled attribution
-
-Status: open
-Opened: 2026-04-09
-
-## Target outcome
-This turn proves that `unrip` can move recent quote rows past submission-only evidence and into durable downstream outcome truth.
-
-For the live NEAR Intents BTC/EURe system, the operator must be able to answer:
-- was the quote merely submitted
-- did the venue later complete or not fill it
-- what settled inventory delta, if any, was actually observed afterward
-- what part of the post-trade change is still inferred versus durably linked
-
-## Why this is a meaningful architecture test
-The previous turn fixed an overclaiming dashboard, but it also exposed the next hard truth gap:
-- `submitted` is now shown truthfully as non-terminal evidence
-- downstream completion and non-fill states are still mostly absent from durable repo-owned data
-- recent asset-term tables still describe submitted quote terms, not settled inventory truth
-- realized attribution is still fake because quote response success is not the same thing as completed asset movement
-
-That means the system is now honest about the gap, but the gap still exists. This turn is where the shared history path must become more real again.
-
-## Hypothesis
-`unrip` becomes materially more trustworthy if it durably links:
-- quote
-- strategy decision
-- execute command
-- executor submission result
-- downstream venue or relay outcome where available
-- later settled inventory deltas attributable to that quote
-
-The turn passes only if the operator can distinguish submission from later outcome and can inspect a recent completed path with explicit settled attribution instead of implied completion.
-
-## Scope
-- [I017] Per-trade realized attribution: link each successful trade to actual settled inventory deltas and attributable costs so the system can report realized net contribution per trade instead of only expected edge.
-- [I018] Quote-to-outcome and markout analytics: link quote, response, decision, execution result, and settlement, then store later reference-price markouts to measure adverse selection and quote quality.
-- Focus on the active NEAR Intents BTC/EURe venue and the repo-owned path already in production.
-- Cover recent rows first; historical backfill is secondary unless required to prove the live path.
-
-## Assumptions
-- The venue or relay emits enough downstream identifiers or status surfaces to link at least some submitted quotes to later terminal outcomes.
-- Inventory snapshots and durable history can support quote-to-settlement attribution for the active pair, even if the first version uses a narrow matching heuristic.
-- Some rows will still remain unattributed or partially inferred; the UI and stored records must say that plainly.
-- This turn should prioritize truthful linkage and settlement evidence over broad analytics polish.
-
-## Turn-shaping rules
-- `submitted` remains non-terminal evidence.
-- `completed`, `not filled`, `settled`, `realized`, and `asset delta` are forbidden unless backed by a durable linked record representing that fact.
-- If settlement attribution is heuristic rather than exact, the stored attribution record and operator surface must say so explicitly.
-- Do not build a broad analytics suite before the quote-to-outcome path is durably linked.
-- Prefer one repo-owned outcome and attribution model reused by storage, dashboard, and later analytics.
-
-## Non-goals
-- No new venue integration.
-- No generalized PnL accounting for all treasury cashflows.
-- No broad historical backfill project unless needed to prove current-path linkage.
-- No strategy changes beyond what is required to preserve truthful lifecycle and attribution semantics.
-
-## Required operator behavior
-
-### Outcome truth
-For a recent submitted quote, the dashboard must be able to render one of:
-- `Submitted`
-- `Awaiting outcome`
-- `Not filled`
-- `Completed`
-
-The label must be driven by the strongest durable evidence currently stored.
-
-### Settlement truth
-For a recent completed quote, the operator must be able to inspect:
-- quote id
-- decision id
-- command id
-- executor result id or submission timestamp
-- linked terminal outcome evidence
-- linked settled asset delta or explicitly missing settled delta
-
-### Attribution truth
-If the system reports realized contribution, it must be derived from:
-- linked settled asset movement
-- explicit attributable costs where available
-
-If costs or full settlement are missing, the system must not claim net realized truth.
-
-### Markout truth
-If markout is stored for completed or submitted rows, it must:
-- be clearly labeled as later reference-price comparison
-- remain separate from realized settlement attribution
-
-## Semantic invariants
-The implementation and tests must enforce at least:
-- `submitted != completed`
-- `completed` requires linked terminal outcome evidence
-- settled asset delta requires linked settlement evidence, not quote terms
-- markout is not realized PnL
-- unattributed inventory movement must not be silently assigned to a quote
-
-## Definition of done
-- A durable quote outcome link exists from submission to later outcome where available.
-- The repo stores an explicit per-quote outcome or attribution record for the active path.
-- The dashboard can show at least one recent path as `Completed` only when durable linked evidence supports it.
-- The dashboard can show non-fill or still-awaiting paths truthfully where that evidence exists.
-- Recent settled asset delta or explicit lack of attribution is visible per completed row.
-- Submission-term tables and summaries do not overclaim settled truth.
-- Regression tests cover the negative semantic boundaries above.
-
-## Validation evidence required
-- direct evidence from deployed dashboard or bootstrap payload that recent rows separate `Submitted`, `Blocked`, `Rejected`, `Not filled`, and `Completed` when the evidence exists
-- direct evidence that a completed row shows linked settled attribution rather than quote terms alone
-- direct evidence that a submission-only row still does not claim completion or realized asset movement
-- automated test evidence for quote-to-outcome linkage
-- automated test evidence for settlement attribution boundaries
-
-## Failure conditions
-- the system still cannot represent downstream terminal outcome beyond submission
-- any UI or backend surface claims completion from submission-only evidence
-- settled asset delta is still derived from quoted terms rather than linked settlement evidence
-- markout or later reference comparison is presented as realized PnL
-- outcome attribution silently guesses across ambiguous rows without recording uncertainty
-
-## Current real before this turn
-- quote, decision, command, and execution submission result are durable
-- the dashboard now renders those stages truthfully
-- submission counts and recent submission terms are constrained to submission evidence
-
-## Deliberately not built by this proof
-- full treasury fee ledger
-- generalized tax or accounting treatment
-- multi-venue settlement harmonization
-
-## Prevention requirements for this proof
-- For every new `Completed`, `Not filled`, or realized attribution label:
-  - what exact durable record backs it
-  - what linkage key or heuristic connects it to the quote
-  - what uncertainty remains
-  - what regression test prevents future overclaiming