NODEDC_1C/docs/ADDRESS/address_query/runtime_integration_plan.md

Runtime Integration Plan (question_mode=address_query)

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

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)

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

• open_contracts_confirmed_as_of_date
• list_open_contracts (diagnostic heuristic)
• 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
• Для open_contracts_confirmed_as_of_date silent degrade в list_open_contracts запрещен; при недоступности exact-ответа допускается только LIMITED_WITH_REASON.

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