Plan turn: execution outcome truth and settled attribution
All checks were successful
deploy / deploy (push) Successful in 31s
All checks were successful
deploy / deploy (push) Successful in 31s
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.
This commit is contained in:
philipp
parent
bd72e355b1
commit
208be20a1c
4 changed files with 309 additions and 8 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
139
PROOF.md
139
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
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue