NODEDC_1C/docs/ADDRESS/address_query/runtime_integration_plan.md

Runtime Integration Plan (question_mode=address_query)

Дата: 2026-03-29

1) Цель интеграции

Добавить отдельный runtime-контур для быстрых адресных запросов к 1С через MCP, не ломая существующий Stage 4 deep-analysis path.

2) As-Is (подтверждено кодом)

Текущий assistant pipeline:

1. normalizer -> route summary
2. execution plan по deep-routes
3. assistantDataLayer.executeRouteRuntime(...)
4. admissibility / eligibility guards
5. answer composer

Ключевые точки в текущем коде:

• llm_normalizer/backend/src/services/assistantService.ts
• llm_normalizer/backend/src/services/routeHintAdapter.ts
• llm_normalizer/backend/src/services/assistantDataLayer.ts
• llm_normalizer/backend/src/services/assistantRuntimeGuards.ts
• llm_normalizer/backend/src/services/answerComposer.ts

3) To-Be: Separate Address Lane

Новый high-level flow:

1. Входящий вопрос.
2. Mode-classifier: address_query | deep_analysis | unsupported.
3. Если address_query:

• resolve address_intent;
• extract+validate filters;
• select recipe;
• execute MCP (live-first);
• normalize result schema;
• return factual answer.

4. Если не address_query: текущий deep path без изменений.

4) Встраивание по слоям

4.1 Normalizer / Routing Layer

Изменения:

• добавить question_mode и address_intent в normalizer contract;
• в routeHintAdapter добавить address-query rule set до deep route discipline.

Рекомендуемые файлы:

• llm_normalizer/backend/src/types/normalizer.ts
• llm_normalizer/backend/src/services/routeHintAdapter.ts

4.2 Assistant Service Orchestration

Изменения:

• в AssistantService.processMessage(...) добавить раннюю развилку по question_mode;
• для address_query запускать отдельный pipeline (без claim-bound deep-chain).

Рекомендуемый новый сервис:

• llm_normalizer/backend/src/services/addressQueryService.ts

4.3 Intent + Filter Extraction

Новые компоненты:

• addressIntentResolver.ts
• addressFilterExtractor.ts
• addressFilterValidator.ts

Выход контракта:

• detected_mode
• detected_intent
• required_filters
• resolved_filters
• missing_filters

4.4 Recipe Selection + MCP Execution

Новые компоненты:

• addressRecipeCatalog.ts (статический whitelist recipes)
• addressRecipeSelector.ts
• addressMcpExecutor.ts

Правила:

• только whitelist recipe_id;
• live-first; snapshot только explicit fallback;
• hard limit на строки и fixed sorting profile.

4.5 Result Materialization + Answer Composer

Новые компоненты:

• addressResultMaterializer.ts
• addressAnswerComposer.ts

Режимы ответа:

• FACTUAL_LIST
• FACTUAL_SUMMARY
• LIMITED_WITH_REASON

4.6 Debug/Trace Contract

Минимальный debug блок для address lane:

• detected_mode
• detected_intent
• extracted_filters
• selected_recipe
• mcp_call_status
• rows_fetched
• rows_matched
• response_type

5) Fallback Rules

• Если mode=address_query, но missing_required_filters -> LIMITED_WITH_REASON (без silent fallback в deep).
• Если mode=address_query, но intent не поддержан -> LIMITED_WITH_REASON или controlled handoff в deep-path с явной пометкой.
• Если live недоступен -> LIMITED_WITH_REASON: live_unavailable.

5.1) Compound factual scope (M2.1 real status)

• COMPOUND_FACTUAL_QUERY is currently detection-only.
• Runtime does not execute multi-intent decomposition yet.
• Current behavior for compound prompts:
  • one selected intent;
  • one selected recipe;
  • one factual/limited output block.
• Multi-step decomposition (subquery planning -> per-subquery execution -> stitched composer) is planned for V1.1.

6) Safety Guardrails

• Никакого free-form query generation от LLM.
• Query только через recipe whitelist.
• Все параметры проходят типовую и value-валидацию.
• Account anchors — только validated account tokens (исключая date/amount pollution).
• Read-only MCP profile для address lane.

7) Minimal Implementation Queue

1. M0: контракты (question_mode, address_intent, filter schema, recipe schema).
2. M1: classifier + resolver + validator (без MCP execution).
3. M2: MCP executor + 5 P0 recipe.
4. M3: factual composer + debug payload + basic tests.
5. M4: live rerun pack в docs/ADDRESS/runs/....

7.1) Sprint B priority order (adapted to current reality)

1. documents_by_counterparty
2. bank_operations_by_counterparty
3. documents_forming_balance
4. documents_by_contract
5. bank_operations_by_contract

Rationale:

• start from anchors with higher resolver stability (counterparty first);
• unlock early positive evidence before contract-heavy variants;
• keep contract scenarios behind anchor-resolution hardening.

8) Out of Scope for V1

• Новый proof engine.
• Расширение доменов beyond P0 address intents.
• Полный redesign deep-stage routing.
• Автоматический свободный доступ к произвольным сущностям 1С.

9) Expected Acceptance (V1)

• Deep-analysis path не деградировал.
• Address intents из P0 стабильно маршрутизируются в MCP/live-first lane.
• Factual-ответы по P0 сценариям возвращаются в предсказуемом формате.
• false_factual_rate = 0.