unrip/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