# Runtime Integration Plan (question_mode=address_query)

Дата среза: 2026-04-02

## 1) Цель

Поддерживать отдельный runtime-контур для быстрых address-запросов через MCP,
без деградации deep-analysis path.

## 2) Фактический статус интеграции

Address lane уже встроен в `AssistantService` и включен feature-флагами по умолчанию:

- `FEATURE_ASSISTANT_ADDRESS_QUERY_V1=true`
- `FEATURE_ASSISTANT_ADDRESS_QUERY_LLM_PREDECOMPOSE_V1=true`
- `FEATURE_ASSISTANT_ADDRESS_QUERY_LIVE_V1=true`

Ключевая оркестрация:

- `assistantService.ts`:
  - L0 pre-decompose (LLM + deterministic fallback)
  - tool-gate решение (`run_address_lane` / `skip_address_lane`)
  - follow-up carryover context (сигнал берется из raw user message и pre-decompose effective message)
  - вызов `addressQueryService.tryHandle(...)`

## 3) Canonical Runtime Flow (actual)

1. User message.
2. L0 layer:
   - message sanitization/cleanup;
   - optional LLM pre-decompose (`normalizer_v2_0_2`);
   - deterministic fallback rules;
   - tool-gate decision.
3. `addressQueryService`:
   - `decomposeStage` (mode/shape/intent/filters + follow-up merge)
   - `resolveStage` (primary anchor + refinement from rows)
   - `execute` (recipe select -> MCP query -> materialization/scope/filter)
   - `compose` (FACTUAL_* или LIMITED_WITH_REASON)
4. Unified debug payload в `AssistantService`.
5. Если lane не обработал запрос - возврат в основной deep path.

## 4) Реализованные компоненты

- `src/services/address_runtime/decomposeStage.ts`
- `src/services/address_runtime/resolveStage.ts`
- `src/services/address_runtime/composeStage.ts`
- `src/services/addressIntentResolver.ts`
- `src/services/addressFilterExtractor.ts`
- `src/services/addressRecipeCatalog.ts`
- `src/services/addressMcpClient.ts`
- `src/services/addressQueryService.ts`

## 5) Intent Coverage (runtime)

Реализовано:

- `list_open_contracts`
- `list_payables_counterparties`
- `list_receivables_counterparties`
- `account_balance_snapshot`
- `open_items_by_counterparty_or_contract`
- `list_documents_by_counterparty`
- `bank_operations_by_counterparty`
- `list_documents_by_contract`
- `bank_operations_by_contract`
- `documents_forming_balance`

Не реализовано (V1):

- `account_turnover_snapshot`
- `list_documents_by_type`

## 6) Execution and Debug Guarantees

- whitelist recipes only
- read-only MCP
- no free-form query generation
- explicit stage statuses:
  - `no_raw_rows`
  - `raw_rows_received_but_not_materialized`
  - `materialized_but_not_anchor_matched`
  - `materialized_but_filtered_out_by_recipe`
  - `matched_non_empty`
- legacy compatibility field:
  - `mcp_call_status_legacy`

## 7) Runtime Fallbacks (actual)

- Missing required filters -> `LIMITED_WITH_REASON` (`missing_anchor`)
- Recipe missing -> `LIMITED_WITH_REASON` (`recipe_visibility_gap`)
- MCP error / lane disabled -> `LIMITED_WITH_REASON` (`execution_error`)
- Period auto-broaden for by-counterparty/by-contract docs+bank intents
- Anchor mismatch fallback для document/bank intents
- Contract-docs recovery path через bank-like rows

## 8) Compound Scope

- `COMPOUND_FACTUAL_QUERY` сейчас detection-only.
- Multi-intent decomposition execution не выполняется в runtime V1.

## 9) Known Gaps for Step-4

- введены шаблоны (`domain_card_template_v1.md`, `domain_acceptance_question_set_template_v1.md`), но domain-specific cards/sets для новых доменов еще не заведены;
- P1 intents (`turnover`, `documents_by_type`) в runtime отсутствуют;
- CI pipeline интеграция nightly еще не подключена (локальный nightly через Task Scheduler уже работает).

## 10) Acceptance Baseline (must keep)

- stress pack: `102/102` (run `2026-04-02_Address_Slang_Live_Stress_2026-04-02_12-57-27`)
- follow-up pack: `25/25` (run `2026-04-02_Address_Followup_Context_Chains_2026-04-02_19-15-Run5`)
- `strict_policy=route`
- `false_factual_rate=0`