From 208be20a1c21808e3ddead5a04d3dfdd246cad7a Mon Sep 17 00:00:00 2001 From: philipp Date: Thu, 9 Apr 2026 18:09:05 +0200 Subject: [PATCH] Plan turn: execution outcome truth and settled attribution Proof: Open the next implementation turn focused on durable downstream outcome linkage and settled inventory attribution for executed quotes. Assumptions: I017 and I018 belong to one coherent proof topic for the active NEAR Intents BTC/EURe path. Still fake: Planning defines the next truth gap and validation target, but no downstream outcome or settlement attribution implementation exists yet. --- ARCHIVE.md | 1 + BACKLOG.md | 2 - IMPLEMENTATION.md | 175 +++++++++++++++++++++++++++++++++++++++++++++- PROOF.md | 139 +++++++++++++++++++++++++++++++++++- 4 files changed, 309 insertions(+), 8 deletions(-) diff --git a/ARCHIVE.md b/ARCHIVE.md index 63fcd01..76581fb 100644 --- a/ARCHIVE.md +++ b/ARCHIVE.md @@ -26,3 +26,4 @@ Legacy note: - 2026-04-07: opened implementation turn `cow-protocol-intent-based-venue-integration` from backlog items I019. - 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. diff --git a/BACKLOG.md b/BACKLOG.md index afa8280..91c2635 100644 --- a/BACKLOG.md +++ b/BACKLOG.md @@ -22,8 +22,6 @@ Rules: - [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 -- [I017] (soon) 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. tags=trades,pnl,settlement -- [I018] (later) 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. tags=quotes,analytics,markout ## Research Candidates - [R001] Compare Kraken and CoinGecko drift and freshness for the assets needed to price the active pair. - [R002] Test whether the active pair's implied rate diverges from external reference prices enough to justify execution after a simple 2% gross threshold. diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index c6b72a8..444b42c 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,5 +1,174 @@ -# Implementation Turn +# Implementation Turn: execution outcome truth and settled attribution -Status: idle +Status: open +Opened: 2026-04-09 -No approved implementation turn is active yet. +## 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 diff --git a/PROOF.md b/PROOF.md index 71baf39..79edb82 100644 --- a/PROOF.md +++ b/PROOF.md @@ -1,5 +1,138 @@ -# Implementation Proof +# Implementation Proof: execution outcome truth and settled attribution -Status: idle +Status: open +Opened: 2026-04-09 -No approved implementation proof is active yet. +## 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