Initial import NDC_1C

docs/assistant_orchestration_spec.md

@@ -0,0 +1,80 @@
+# 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.