# Assistant Orchestration Spec (Layer 7)

Date: 2026-03-23  
Status: architecture-ready, partial runtime implementation

## 1. Objective

Route user questions to the correct execution path:

- live read-only bridge (point drill-down)
- canonical/feature/risk stores (fast analytical answer)
- refresh/feature/risk jobs (if cached context is stale or missing)

## 2. Routing modes

### Mode A: Live Drill-down

Use when user asks for a specific object/fact:

- one document
- one posting
- one account entry chain

Path:

`Assistant -> runtime bridge tools -> user answer`

### Mode B: Cached Analytics

Use when answer is already represented in stores:

- features
- anomalies
- risk patterns

Path:

`Assistant -> /features/* + /risk/* + canonical store -> user answer`

### Mode C: Recompute Then Answer

Use when data freshness is not acceptable or context missing:

1. trigger refresh (`/refresh/run`)
2. trigger features (`/features/run`)
3. trigger risk (`/risk/run`)
4. return updated answer

## 3. Current API surface used by orchestrator

- `POST /refresh/run`
- `GET /refresh/runs`
- `GET /store/stats`
- `POST /features/run`
- `GET /features/stats`
- `GET /features/anomalies`
- `POST /risk/run`
- `GET /risk/patterns`
- `GET /risk/stats`

## 4. Freshness policy (MVP)

1. If `stale_refresh` signal exists, trigger Mode C.
2. If no feature run exists, trigger Mode C.
3. If no risk run exists, trigger Mode C.
4. Otherwise use Mode B with optional Mode A drill-down evidence.

## 5. Response shape (recommended)

Assistant output should include:

1. direct answer
2. evidence source (`live`, `canonical`, `feature`, `risk`)
3. freshness markers (timestamps/run ids)
4. optional next action (`rerun refresh/features/risk`)

## 6. Safety rule

Orchestrator never sends write commands to 1C.
All runtime access is read-only by policy.