foxhunt/docs/plans/2026-03-01-deferred-stubs-design.md

# Deferred Stubs Implementation — Design

**Date**: 2026-03-01
**Branch**: `feature/deferred-stubs`
**Scope**: 3 deferred stubs from 2026-02-24 audit

## Context

The stub audit (2026-02-24) identified 18 findings. 8 were fixed with real implementations,
3 with honest errors, 3 acceptable, and 4 deferred. Of those 4:

- WS streams (stream_model_metrics, stream_signal_strength) — **already fixed** (verified 2026-03-01, both publish real data via tokio channels)
- Feature importance — **correctly stubbed** (no feasible path without SHAP/external lib)

That leaves **3 real deferred items** to implement:

| Stub | Location | Current Behavior |
|------|----------|------------------|
| Retrain Model | `trading_service/enhanced_ml.rs:1018` | `Status::unavailable` |
| Portfolio Positions | `risk-data/src/var.rs:641` | Returns empty `Vec<PortfolioPosition>` |
| ML Confidence | `trading_agent_service/autonomous_scaling.rs:665` | Liquidity heuristic `score * 0.9 + 0.1` |

## Area 1: Retrain Model — Fine-Tune via gRPC

### Problem

`retrain_model()` returns `Status::unavailable("not yet wired to ml_training_service")`.
The ml_training_service has `StartTraining` RPC but no fine-tune mode.

### Design

1. **Proto change**: Add `TrainingMode` enum (`FULL`, `FINE_TUNE`) and fields to
   `StartTrainingRequest` in `services/ml_training_service/proto/ml_training.proto`:
   - `TrainingMode mode` — selects full vs fine-tune
   - `string resume_checkpoint_path` — path to last checkpoint
   - `uint32 max_epochs` — fine-tune uses fewer epochs (default 10)

2. **trading_service client**: Add `MlTrainingServiceClient` to `EnhancedMLServiceImpl`
   via `OnceCell` lazy initialization. Endpoint configured via env var
   `ML_TRAINING_SERVICE_URL` (default `http://ml-training-service:50052`).

3. **retrain_model() handler**:
   - Look up `RuntimeModelInfo` for the requested model_name
   - Map model_name → `CommonModelType` enum
   - Build `StartTrainingRequest` with mode=FINE_TUNE, checkpoint path, max_epochs=10
   - Call `client.start_training(request).await`
   - Return `RetrainModelResponse { job_id, status: "started" }`

4. **ml_training_service handler**: In `start_training()`:
   - If mode=FINE_TUNE: load checkpoint, train on recent 1-month data window, 10 epochs
   - If mode=FULL: existing behavior (walk-forward, full training)

### Risk

Low-Medium. Proto change is additive (backward compatible). The fine-tune code path
in ml_training_service builds on existing training infrastructure.

## Area 2: Portfolio Positions — Broker + DB Fallback

### Problem

`get_portfolio_positions()` in `risk-data/src/var.rs` returns an empty Vec,
causing VaR calculations to fail with "No positions found for portfolio".

### Design

1. **PositionProvider trait** in `crates/risk-data/src/position_provider.rs`:
   ```rust
   #[async_trait]
   pub trait PositionProvider: Send + Sync {
       async fn get_positions(&self, portfolio_id: &str)
           -> RiskDataResult<Vec<PortfolioPosition>>;
   }
   ```

2. **DatabasePositionProvider**: Queries `portfolio_positions` table via SQLX.
   Schema: `(id, portfolio_id, symbol, quantity, avg_entry_price, current_price,
   side, updated_at)`. Uses existing SQLX offline mode.

3. **BrokerPositionProvider**: Calls broker_gateway_service gRPC `GetPositions` RPC.
   Falls back gracefully if broker is unreachable.

4. **Fallback chain** in `get_portfolio_positions()`:
   - Try broker (live positions, most accurate)
   - Try DB (cached positions from fill events)
   - Return error if both fail

5. **Position sync**: Trading engine's fill handler writes/updates positions in DB
   on each fill event. This keeps the DB cache fresh even when broker is offline.

6. **SQL migration**: Add `portfolio_positions` table via SQLX migration.

### Risk

Medium. Requires DB schema change and new SQLX queries. The broker_gateway is
Phase 2 (FIX routing MVP), so broker path may not work immediately — DB path
is the primary functional path.

## Area 3: ML Confidence — Ensemble RPC

### Problem

`compute_tier_allocations()` in `autonomous_scaling.rs` uses a liquidity-based
heuristic for ML confidence instead of calling the ensemble service.

### Design

1. **Add optional gRPC client**: `Option<MlServiceClient>` on the autonomous
   scaling service struct. Initialized from env var `ML_SERVICE_URL`.

2. **Call GetEnsembleVote**: Per instrument in `compute_tier_allocations()`:
   - Build `EnsembleRequest { model_name: "all", symbol: Some(instrument.symbol) }`
   - Call `client.get_ensemble_vote(request).await`
   - Extract confidence from response

3. **Fallback**: On RPC failure, use existing heuristic `liquidity_score * 0.9 + 0.1`

4. **Caching**: Cache ensemble responses for 5 seconds per symbol to avoid
   excessive RPC calls during allocation computation.

### Risk

Low. The fallback is already tested and functional. This is purely additive.

## Execution Order

1. **Retrain Model** (smallest scope, unblocks model lifecycle)
2. **ML Confidence** (low complexity, improves trading accuracy)
3. **Portfolio Positions** (largest scope, requires DB migration)

## Verification

After each area:
- `SQLX_OFFLINE=true cargo check --workspace`
- `SQLX_OFFLINE=true cargo clippy -p <affected_crates> --lib -- -D warnings`
- `SQLX_OFFLINE=true cargo test -p <affected_crates> --lib`