unrip/IMPLEMENTATION.md

# Implementation Turn: pre-credit funding visibility and operator alerts

Status: open
Opened: 2026-04-02

## Goal
Make the already-live BTC/EURe loop operationally understandable between external funding and spendable credit, and make critical stale or failed states queryable as durable alert records instead of transient logs.

## Selected backlog items
- [O003] Alerts for stale reference prices, stale inventory state, stuck funding actions, and failed executor submissions.
- [O004] Pre-credit funding visibility for slow chains: watch configured deposit addresses at chain level, track inbound transfers through mempool and on-chain confirmation before bridge credit, persist that state separately from spendable inventory, and alert operators when funding is seen, delayed, or stuck.

## Design rule
Keep the already-proven execution and inventory truth path intact:
- verifier and bridge credit remain the only spendable truth
- pre-credit visibility is additive observability
- alerts are additive operability

## Event backbone
Retain Kafka as the backbone. Add only the minimal new topics required:

- `ops.funding_observation`
- `ops.alert`

These topics are append-only evidence streams, not control planes.

## Durable store
Extend PostgreSQL with new append-only families:
- `funding_observations`
- `ops_alerts`

If a current-state materialization is needed, derive it from append-only records or keep it as a clearly named snapshot table. Do not replace the append-only record.

## Service changes

### 1. `liquidity-manager`
Extend the existing treasury owner instead of inventing a broad new funding stack.

New responsibilities:
- retain active funding handles by chain and asset
- poll configured chain observers for those handles
- emit `ops.funding_observation`
- correlate chain observations with bridge `recent_deposits`
- expose latest observations and credit-correlation state through `/state`

Expected state shape additions:
- `funding_observations_by_handle`
- `latest_funding_observation_at`
- `uncredited_funding_total_by_asset`
- `credit_correlation`

Control additions:
- `POST /refresh-funding-observations`
- optional `POST /pause-funding-observer`
- optional `POST /resume-funding-observer`

Important implementation constraints:
- do not change withdrawal behavior
- do not reuse spendable inventory fields for pre-credit state
- keep BTC and EURe observation records in one shared schema

### 2. `inventory-sync`
Keep current spendable accounting intact.

Possible additions:
- read the latest funding observations
- expose a separate `pre_credit_inbound` or `funding_visibility` field in `/state`

Hard rule:
- `spendable`, `pending_inbound`, and strategy-facing credited truth must not become looser

### 3. `history-writer`
Consume and persist the new topics:
- `ops.funding_observation`
- `ops.alert`

Expose through `/state`:
- latest funding-observation write time
- latest alert write time
- counts or offsets for the new topics

Add query-friendly indexes for:
- `tx_hash`
- `funding_handle`
- `alert_code`
- `ingested_at`

### 4. `ops-sentinel` or equivalent alert evaluator
Add one small service only if needed to keep alert logic separate and testable.

Responsibilities:
- consume:
  - `ref.market_price`
  - `state.intent_inventory`
  - `ops.liquidity_action`
  - `ops.funding_observation`
  - `exec.trade_result`
- evaluate policy windows for stale and stuck conditions
- emit `ops.alert` raise/clear transitions
- expose current alert state

Preferred alert model:
- stable `alert_code`
- `status`: `raised` or `cleared`
- `severity`
- `reason`
- `first_raised_at`
- `last_evaluated_at`
- correlation IDs when available

Minimal alert set for this turn:
- `reference_price_stale`
- `inventory_snapshot_stale`
- `funding_seen_unconfirmed`
- `funding_confirmed_credit_pending`
- `funding_stuck`
- `executor_submission_failed`

Do not add Slack, email, or paging integrations in this turn unless required to prove the path. Durable alert records plus HTTP state are sufficient.

## Chain observer plan

### BTC
Must be the first-class proof path.

Implementation expectations:
- configurable observer endpoint
- look up the configured BTC deposit address
- detect:
  - mempool appearance when available
  - confirmation count
  - credited transition once bridge/verifier catches up

Assumption to keep explicit in code:
- a chain observer can disappear or lag independently of the bridge

### Gnosis / EURe
Nice-to-have within the same schema, but BTC is the proof-critical path.

If included this turn:
- watch the configured deposit address for EURe token transfers
- represent observation state in the same event model

## Record shapes

### `ops.funding_observation`
Required fields:
- `funding_observation_id`
- `account_id`
- `asset_id`
- `chain`
- `funding_handle`
- `source`
- `tx_hash`
- `status`
- `amount`
- `confirmations`
- `first_seen_at`
- `last_seen_at`
- `credited_at` when known
- `bridge_deposit_tx_hash` when correlated

### `ops.alert`
Required fields:
- `alert_event_id`
- `alert_code`
- `status`
- `severity`
- `reason`
- `service_scope`
- `pair` when relevant
- `asset_id` when relevant
- `tx_hash` when relevant
- `raised_at`
- `cleared_at`
- `details`

## Control surface expectations

### `liquidity-manager`
Must expose:
- active deposit handles
- latest pre-credit funding observations
- latest credit correlation
- whether the funding observer is healthy or paused

### alert evaluator
Must expose:
- current active alerts
- latest cleared alerts
- per-alert evaluation timestamps
- pause state

### `history-writer`
Must expose the new topic offsets and write status for funding observations and alerts.

## Tests
Required automated coverage:
- BTC funding observation remains non-spendable before credit
- alert transitions raise then clear on recovered stale state
- funding observation correlates to a later credited deposit without losing the original tx hash
- executor failure produces an alert event

If a meaningful automated test cannot be written for a subpath, stop and record why instead of hand-waving.

## Validation plan
- Safe induced stale-price alert:
  - pause `market-reference-ingest`
  - wait past freshness window
  - observe `reference_price_stale`
  - resume and observe clear
- Safe induced stale-inventory alert:
  - pause `inventory-sync`
  - wait past freshness window
  - observe `inventory_snapshot_stale`
  - resume and observe clear
- Funding visibility proof:
  - use a real deposit address
  - observe pre-credit chain state before bridge credit where timing allows
  - later observe credit correlation
- Executor failure alert proof:
  - use a controlled non-destructive failure mode such as temporary relay endpoint override in a safe environment or a replayable failure fixture
  - verify `executor_submission_failed`

## Out of scope on purpose
- No new trading strategy
- No historical backtest engine
- No broad observability stack
- No polished dashboard frontend
- No automated treasury refills

## Still fake at turn open
- Pre-credit funding visibility is still missing from the live cluster.
- Alert state is still mostly implicit in service logs and manual inspection.
- There is no durable operator-facing record yet for "funds are on the way but not spendable."