unrip/IMPLEMENTATION.md

Implementation Turn: quote lifecycle truth and execution explanation

Status: open Opened: 2026-04-09

Goal

Replace ambiguous quote and decision wording with a truthful per-quote lifecycle that tells the operator exactly why a quote was filtered, rejected, blocked, submitted, failed, not filled, or completed.

Selected backlog items

• [I021] Quote lifecycle truth and execution explanation: replace ambiguous dashboard verdicts with a per-quote state machine that shows exactly why a quote was filtered, rejected, blocked, submitted, not filled, or executed, with durable reason codes and operator-facing traceability.

Design rules

• Treat quote lifecycle as product truth, not UI decoration.
• Strategy verdict is not the final operator answer.
• Prefer one explicit lifecycle derivation path shared by backend and dashboard over ad hoc page-specific wording.
• Do not invent downstream certainty where durable evidence is absent.
• Remove Actionable completely from operator-facing copy.

Problem statement for this turn

The current dashboard still forces operators to infer too much:

• Actionable does not say whether a command was emitted or submitted
• the Strategy page mixes strategy and execution truth
• executor-rejected rows are not clearly distinguishable from strategy-rejected rows
• quote ids are truncated and awkward to use during debugging

The repo already stores enough of the real lifecycle to do better:

• quote id
• decision id
• emitted command id
• execution result status and result code

The turn therefore needs to improve:

• lifecycle derivation
• durable reason mapping
• recent-row rendering
• trace affordances

Lifecycle model for this turn

Implement one repo-owned lifecycle derivation for recent rows, using durable evidence in this order:

1. Quote observed
2. Strategy evaluated
3. Command emitted or not emitted
4. Executor result observed or absent
5. Venue downstream outcome when available

The first mandatory states are:

• Filtered
• Rejected
• Blocked
• Submitted
• Failed
• Awaiting outcome
• Completed

Suggested meanings:

• Filtered quote never entered the active trade path or was excluded before strategy decision
• Rejected strategy evaluated the quote and decided not to trade
• Blocked strategy approved or emitted a command, but execution did not proceed due to control state or another repo-owned gate
• Submitted executor accepted the command and successfully submitted a quote response
• Failed execution submission failed technically
• Awaiting outcome submitted to venue, but no later durable terminal venue outcome exists yet
• Completed durable evidence shows the trade completed successfully

Do not show states we cannot support yet for a given row.

Reason-code model

For each lifecycle state, map durable payload fields to a small operator reason taxonomy.

Examples:

• strategy reason codes:
  • unsupported_pair
  • below_edge_threshold
  • inventory_unavailable
  • stale_reference_price
• executor reason codes:
  • executor_disarmed
  • executor_paused
  • submission_failed
  • quote_response_ok
• downstream outcome reasons if available:
  • expired
  • not_filled
  • completed

If the exact reason is missing:

• expose reason_unknown
• keep the row truthful instead of synthesizing an explanation

Backend changes

1. Add a lifecycle derivation helper

Create or extend a backend module that derives quote lifecycle from:

• recent trade decisions
• recent execution results
• successful trade records
• any available quote-status or venue result surfaces

It should emit a normalized row object with:

• quote_id
• decision_id
• command_id
• pair
• direction
• lifecycle_state
• lifecycle_label
• reason_code
• reason_text
• timestamps for the latest known stage
• stage details for tooltips or drilldown

2. Join decision and execution truth explicitly

The backend should no longer leave the frontend to infer execution from isolated tables.

For each recent quote/decision row:

• attach the matching execution result by command_id, decision_id, or quote_id
• attach successful-trade or later terminal evidence where available
• expose whether the row is strategy-only, strategy-plus-command, or strategy-plus-execution

3. Preserve operator drilldown identifiers

Ensure the bootstrap payload exposes:

• full quote id
• full decision id
• full command id

Avoid requiring the frontend to reconstruct or guess identifiers from formatted strings.

Dashboard changes

4. Remove forbidden language

Remove Actionable from:

• Strategy page tables
• any lifecycle badge or verdict cell
• any supporting labels or legends

Replace it with explicit state labels driven by lifecycle derivation.

5. Make recent rows self-explanatory

For each row, render:

• primary lifecycle state
• secondary reason text
• quote id with copy action
• command id if emitted
• timestamps

The operator should be able to scan rows and answer:

• why no trade happened
• whether the system tried to trade
• whether failure was strategic, operational, or downstream

6. Add trace affordances

At minimum:

• copy button for quote id
• avoid over-truncating ids without recovery path
• show linked ids in a dedicated trace column or expanded detail panel

If the row layout gets crowded, prefer an expandable detail tray over hiding identifiers.

Page-level application

Strategy page

This page should become the primary recent quote-decision-execution lifecycle surface.

It should show:

• the latest recent rows for the active pair
• lifecycle state rather than strategy-only verdict
• explicit explanation text

If a strategy-only summary remains, it must be visually separate from per-quote lifecycle truth.

Related quote surfaces

Inspect quote and system surfaces for similar ambiguity and align the wording if they expose the same concepts.

Do not let one page say Submitted while another page still says Actionable for the same row.

Data and state edge cases

• Strategy decision exists, no command emitted: render as Rejected with strategy reason
• Command emitted, no execution result yet: render as Blocked or Awaiting executor only if that distinction is durably supportable; otherwise use a truthful pending label
• Execution result executor_disarmed: render as Blocked with reason executor disarmed
• Execution result submission_failed: render as Failed
• Execution result submitted: render as Submitted or Awaiting outcome
• Successful trade summary exists but no explicit per-quote completion event: only promote to Completed where the durable linkage is real

Concrete implementation order

Phase 1. Define lifecycle derivation

• inspect current durable decision and execution payloads
• write the normalized lifecycle state mapping
• define forbidden and allowed operator labels

Phase 2. Implement backend aggregation

• derive unified recent lifecycle rows
• expose full identifiers and reason codes
• keep old consumers working until the frontend is switched

Phase 3. Update Strategy page rendering

• replace verdict column with lifecycle state
• add reason text
• add quote-id copy affordance
• surface command id and execution state where relevant

Phase 4. Tighten wording and consistency

• remove Actionable
• align supporting labels
• ensure blocked vs rejected vs submitted are clearly distinct

Phase 5. Validate with live recent rows

• verify a row rejected due to executor disarmed renders as blocked with reason
• verify a submitted row renders as submitted
• verify quote ids can be copied and used for tracing

Test plan

• unit tests for lifecycle derivation from:
  • strategy-rejected rows
  • executor-disarmed rows
  • submission-failed rows
  • submitted rows
• dashboard bootstrap tests for:
  • forbidden Actionable removal
  • explicit lifecycle labels
  • reason text rendering
  • identifier exposure
• frontend component tests if needed for copy affordance or row rendering logic

No lifecycle ambiguity fix is complete without a regression test proving the old ambiguous wording cannot return.

Validation checklist against the proof

• Actionable no longer appears
• strategy approval is visibly distinct from execution submission
• recent blocked rows explain why they did not trade
• recent submitted rows show that they were submitted
• quote ids are directly usable from the dashboard

Failure modes to plan for

• the backend joins rows incorrectly and attributes the wrong execution result
• the UI uses softer wording than the backend lifecycle state
• older rows lack enough evidence and the UI pretends certainty
• ids are still truncated without a copy or expand path