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

# 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