unrip/PROOF.md

# 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