NODEDC_1C/docs/ARCH/10 - current_assistant_architecture_2026-04-15.md

# 10 - Текущая архитектура ассистента на 2026-04-15

## 1. Назначение документа

Этот документ фиксирует не историческую эволюцию, а текущий рабочий архитектурный срез ассистента в проекте `NDC_1C`.

Цель документа:
- зафиксировать, какие архитектурные блоки реально участвуют в runtime сейчас;
- отделить текущий работающий контур от ранних проектных отчетов и аудитов;
- дать опорную карту для дальнейшего bounded hardening без разрушения baseline.

Документ не заменяет ранние отчеты в `docs/ARCH`, а накладывается на них как актуальный operational snapshot.

## 2. Как читать `docs/ARCH` после этого обновления

Исторические документы сохраняют свою роль:
- `1-4` — bootstrap, ранний pipeline, MVP и GUI/manual слой;
- `5` — ранний отчет по assistant mode;
- `6` — интегральный статус проекта и Stage 4 на конец марта;
- `7-9` — архитектурные аудиты, gap-регистры, source-to-proof и relation разведка.

Текущий документ нужен для другого:
- не объяснить, как проект развивался;
- а зафиксировать, как именно устроен ассистент сейчас на уровне runtime, state, orchestration и capability routing.

## 3. Executive Summary

На текущем этапе ассистент представляет собой не один monolithic pipeline, а связку из пяти рабочих слоев:

1. `Assistant / living router` — решает, идти ли в address/data lane, в data-scope lane или в обычный chat.
2. `Address orchestration runtime` — собирает predecompose, carryover, continuation contract и orchestration decision.
3. `Address exact execution lane` — выполняет exact-capability routes через `AddressQueryService`.
4. `Session memory + navigation state` — хранит `investigation_state`, `address_navigation_state`, `result_sets`, `focus_object`, `organization/date scope`.
5. `Answer/debug contract layer` — формирует ответ, debug payload, continuation contract и данные для GUI/debug drawer.

Ключевая особенность текущей архитектуры:
- разговорный слой уже не является единственным носителем контекста;
- контекст все больше держится в структурированном session/navigation state;
- exact-capability routes уже существуют как отдельный runtime-контур, а не как побочный продукт общего chat-flow.

## 4. Graphify-срез по кодовой базе

По `graphify-out/GRAPH_REPORT.md` на `2026-04-15`:
- корпус: `473 files`;
- граф: `4865 nodes`, `10622 edges`, `132 communities`;
- среди god nodes находятся:
  - `resolveAddressIntent()`;
  - `composeFactualReply()`;
  - `resolveAssistantOrchestrationDecision()`.

Архитектурно самые важные community:
- `Community 2` — orchestration и `AssistantService`;
- `Community 6` — exact capability/runtime execution, включая `AddressQueryService`;
- `Community 14` — domain cards, domain purity, source gating;
- `Community 17` — navigation state, `focus_object`, `result_sets`, session carryover;
- `Community 20` — address orchestration runtime adapter и follow-up message policy.

Это подтверждает, что текущая система уже раскладывается на отдельные runtime-блоки, а не живет в одном промптовом центре принятия решений.

## 5. Текущая карта runtime

### 5.1 Верхний уровень

Текущий поток запроса выглядит так:

`GUI/API -> AssistantService -> orchestration decision -> address runtime adapter -> AddressQueryService -> compose/debug/session persistence`

На этом уровне уже зафиксированы три разных режима:
- `address_data`;
- `assistant_data_scope`;
- `chat`.

Ключевая точка маршрутизации — `resolveAssistantOrchestrationDecision()` в `llm_normalizer/backend/src/services/assistantService.ts`.

### 5.2 Session memory

Сессионная память не ограничивается простым хранением истории сообщений.

Текущий session store:
- `AssistantSessionStore`;
- `investigation_state`;
- `address_navigation_state`.

Это означает, что архитектурно ассистент уже работает не только на transcript memory, но и на явном структурированном state.

## 6. Orchestration слой

### 6.1 Главный orchestration узел

`AssistantService` является текущим orchestration-ядром ассистента.

Он отвечает за:
- выбор living mode;
- resolution follow-up context;
- построение continuation contracts;
- связывание session memory с runtime execution;
- routing между address lane, data-scope и chat.

На текущем этапе это уже не просто “controller”, а фактический координатор между state, semantics и runtime.

### 6.2 Address orchestration runtime

Для address/data контура вынесен отдельный adapter:
- `assistantAddressOrchestrationRuntimeAdapter.ts`

Он выполняет:
- LLM predecompose или fallback predecompose;
- нормализацию `effectiveMessage`;
- resolution carryover context через `resolveAddressFollowupCarryoverContext()`;
- защиту от неудачных канонизаций через `shouldPreferRawFollowupMessage()`;
- построение `dialogContinuationContract`;
- формирование `addressRuntimeMeta`.

Это важное отличие текущей архитектуры от ранних отчетов:
- predecompose;
- carryover;
- continuation contract;
- orchestration decision

теперь собраны в отдельный runtime-блок, а не размазаны по нескольким ad hoc helper-ам.

## 7. Session state и navigation state

### 7.1 Что реально хранится

`addressNavigationState.ts` фиксирует текущую модель навигационного состояния.

Текущий `session_context` включает:
- `active_result_set_id`;
- `active_focus_object`;
- `last_confirmed_route`;
- `date_scope`:
  - `as_of_date`;
  - `period_from`;
  - `period_to`;
- `organization_scope`.

Отдельно хранятся:
- `result_sets[]`;
- `navigation_history[]`.

### 7.2 Что это значит архитектурно

Текущий диалоговый контекст больше не должен держаться только “в голове модели”.

У системы уже есть структурированные сущности:
- результат ответа как `result_set`;
- выбранный объект как `focus_object`;
- подтвержденный маршрут как `last_confirmed_route`;
- текущий root scope как `organization/date scope`.

Это база для устойчивых drilldown-сценариев.

### 7.3 Как state эволюционирует

`evolveAddressNavigationStateWithAssistantItem()` делает следующее:
- вынимает из assistant reply `detected_intent`, `selected_recipe`, `extracted_filters`;
- строит `result_set_id`;
- при наличии — строит `focus_object`;
- пишет navigation event;
- обновляет active result/focus/route/date/org scope.

Важно:
- `active_focus_object` не затирается автоматически при отсутствии нового focus;
- `organization_scope` и `date_scope` также тянутся как долговременный session context.

## 8. Follow-up и continuation semantics

### 8.1 Carryover контекст

`resolveAddressFollowupCarryoverContext()` сейчас является центральным узлом follow-up логики.

Он собирает carryover из:
- предыдущего address reply;
- navigation state;
- organization clarification state;
- implicit continuation signal;
- selected object / displayed entities;
- inventory root frame.

### 8.2 Root frame и drilldown frame

В текущей реализации уже присутствует различие между:
- `inventory_root`;
- `inventory_drilldown`;
- `generic`.

То есть архитектура уже ушла от полностью плоского carryover.

Фактически в runtime уже живут два уровня:
- root context:
  - организация;
  - дата/период;
  - root intent;
- object/drilldown context:
  - item/counterparty/contract/focus object;
  - drilldown intent.

### 8.3 Root-only carryover

Отдельно введен режим `carry_root_context` / `root_context_only`.

Он используется в тех местах, где нужно:
- сохранить организацию и temporal scope;
- но не тянуть старый object-level intent в новый доменный вопрос.

Архитектурно это важный шаг: система уже умеет не только продолжать предыдущий вопрос, но и ограничивать глубину carryover.

### 8.4 Continuation contract

`buildAddressDialogContinuationContractV2()` сейчас формирует отдельный machine-readable контракт продолжения.

Он хранит:
- `decision`;
- `decision_reasons`;
- `previous_intent`;
- `target_intent`;
- `intent_selection_mode`;
- `anchor_type`;
- `anchor_value`;
- `implicit_continuation_signal`.

Это уже полноценный runtime artifact, а не побочный debug-комментарий.

## 9. Exact capability runtime

### 9.1 Role of `AddressQueryService`

`AddressQueryService` — текущий exact execution engine для address/data маршрутов.

Основной поток внутри `tryHandle()`:
- `runAddressDecomposeStage()`;
- pre-execution grounding;
- organization clarification / scope resolution;
- requested result mode resolution;
- capability route decision;
- recipe selection;
- exact MCP query execution;
- materialization;
- scoped filtering;
- future/temporal guards;
- limited/factual reply building.

### 9.2 Что изменилось относительно ранних отчетов

Текущий address runtime уже не является “одним generic execute_query на удачу”.

Сейчас в нем есть:
- capability route guard;
- route expectation audit;
- organization clarification path;
- intent-specific filter layer;
- lifecycle detachment semantics;
- historical/broadened retry layers;
- exact/limited result policy.

То есть ранняя картина из `ARCH/5` уже устарела: exact-capability execution есть и он занимает отдельный крупный слой runtime.

### 9.3 Capability policy

`addressCapabilityPolicy.ts` фиксирует точные capability routes.

На текущем этапе в policy явно присутствуют, в частности:
- inventory:
  - `inventory_on_hand_as_of_date`;
  - `inventory_purchase_provenance_for_item`;
  - `inventory_purchase_documents_for_item`;
  - `inventory_supplier_stock_overlap_as_of_date`;
  - `inventory_sale_trace_for_item`;
  - `inventory_purchase_to_sale_chain`;
  - `inventory_aging_by_purchase_date`;
- VAT:
  - `vat_payable_confirmed_as_of_date`;
  - `vat_liability_confirmed_for_tax_period`.

Это важно зафиксировать отдельно:
- capability layer уже живет как explicit policy map;
- она не должна снова расползаться в “общую умность”.

## 10. Data/domain слой

### 10.1 Domain purity

`assistantDataLayer.ts` продолжает играть роль доменного ограничителя и source gate.

В нем присутствуют:
- `domain_scope`;
- `forbidden_cross_domain_leakage`;
- source gating;
- graph traversal profiles;
- live MCP call planning;
- domain card based filtering.

### 10.2 Почему это важно для текущей архитектуры

Даже если текущая задача решается в address exact lane, система уже опирается на более широкий доменный слой:
- domain cards;
- source purity;
- graph-aware retrieval planning;
- forbidden cross-domain leakage rules.

Следовательно, любые новые hardening-решения нельзя строить как локальные regex-патчи в inventory/VAT ветках, если они конфликтуют с domain purity моделями.

## 11. Data source модель

Текущий runtime работает как минимум с двумя типами источников:
- live MCP / `execute_query` и каталожные резолверы;
- snapshot/canonical/risk материалы, участвующие в более широком assistant/data контуре.

Для address exact lane центральным остается live execution, но:
- orchestration уже знает про data-scope и domain routes;
- в проекте сохраняется split между lightweight live path и более широкими доказательными/аналитическими слоями.

## 12. Debug, contracts и observability

Текущая архитектура сильно опирается на machine-readable debug artifacts.

На runtime-уровне зафиксированы:
- `technical_debug_payload_json`;
- `addressRuntimeMeta`;
- `orchestrationContract`;
- `dialogContinuationContract`;
- `route_expectation_*`;
- `capability_id`;
- `selected_recipe`;
- `limited_reason_category`.

Для проекта это уже не “вспомогательная телеметрия”, а часть архитектуры:
- через эти контракты GUI, аудит и domain loop понимают, что именно решила система;
- без них bounded hardening быстро превращается в непрозрачную серию случайных патчей.

## 13. Feature-flag слой

В текущем runtime существенная часть поведения завязана на feature flags.

Ключевые flags, влияющие на архитектуру:
- `FEATURE_ASSISTANT_ADDRESS_QUERY_V1`;
- `FEATURE_ASSISTANT_ADDRESS_QUERY_LIVE_V1`;
- `FEATURE_ASSISTANT_CAPABILITY_ROUTE_GUARD_V1`;
- `FEATURE_ASSISTANT_ROUTE_EXPECTATION_AUDIT_V1`;
- `FEATURE_ASSISTANT_ROUTE_EXPECTATION_HARD_GUARD_V1`;
- `FEATURE_ASSISTANT_INVESTIGATION_STATE_V1`;
- `FEATURE_ASSISTANT_ADDRESS_NAVIGATION_STATE_V1`;
- `FEATURE_ASSISTANT_LIVING_CHAT_ROUTER_V1`;
- `FEATURE_ASSISTANT_STATE_FOLLOWUP_BINDING_V1`;
- `FEATURE_ASSISTANT_CONTRACTS_V11`;
- `FEATURE_ASSISTANT_ANSWER_POLICY_V11`.

Архитектурно это значит:
- текущая система уже modularized;
- но operational profile зависит от конфигурации flags, а не только от кода.

## 14. Что устарело в ранних архитектурных документах

### 14.1 Что больше нельзя считать точным описанием текущего состояния

Ранние документы `ARCH/5` и частично `ARCH/6_global_report` полезны как история, но не как точный snapshot текущего runtime.

Устаревшими в них являются, в частности, представления о том, что:
- assistant mode в основном сводится к answer composer + session memory;
- retrieval plan еще в основном stubbed;
- routing и follow-up существуют как легкая надстройка поверх ответа.

На текущем этапе это уже не так:
- continuation contracts существуют;
- navigation state существует;
- exact capability runtime существует;
- route expectation / capability guard / organization clarification существуют;
- root/drilldown carryover уже встроен в orchestrator.

### 14.2 Как использовать старые документы теперь

Старые отчеты полезны:
- как описание этапов развития;
- как baseline для исторического сравнения;
- как объяснение происхождения guardrails и audit criteria.

Но для описания того, “как работает ассистент сейчас”, опорным должен считаться уже этот документ.

## 15. Текущие архитектурные инварианты

На момент `2026-04-15` безопасно считать архитектурными инвариантами следующее:

1. Exact business routes должны жить как explicit capability/runtime paths, а не как heuristic chat imitation.
2. Follow-up continuity должна опираться не только на transcript, но и на structured state.
3. `focus_object`, `result_set`, `organization_scope`, `date_scope` являются частью архитектуры, а не UX-деталью.
4. Root context и drilldown context нельзя больше считать одной плоской переменной “контекст разговора”.
5. Machine-readable debug/contracts обязательны для объяснимости и bounded hardening.
6. Domain purity и forbidden cross-domain leakage уже являются встроенными guardrails и должны учитываться при любом расширении.

## 16. Текущие ограничения

Несмотря на значительный сдвиг архитектуры, текущая система еще не должна описываться как полностью закрытая production architecture.

Остаются ограничения:
- часть follow-up semantics еще зависит от LLM predecompose и quality canonicalization;
- часть object-level continuity еще удерживается комбинацией transcript + navigation state, а не единым frame engine;
- не все capability routes одинаково зрелые по depth и proof closure;
- hardening по meta-follow-up, pivot semantics и field admissibility еще остается отдельным слоем работы.

## 17. Практический итог

Текущий ассистент уже нельзя описывать как “чат над 1С”.

Более точная формулировка:

`структурированный orchestration runtime + session/navigation state + exact address capability engine + domain/data guardrails`

Именно в этой рамке должны приниматься следующие решения:
- не через новый общий rewrite;
- не через промптовую переумность;
- а через bounded усиление уже существующих архитектурных блоков.

## 18. Связанные документы

Исторический baseline:
- `docs/ARCH/5 - assistant_mode_architecture_report_2026-03-24.md`
- `docs/ARCH/6 - project_and_stage4_full_report_2026-03-28.md`
- `docs/ARCH/6_global_report/Assistant_Mode_GLOBAL_STATUS_2026-03-24.md`

Аудит и gap-анализ:
- `docs/ARCH/7 - аудит архитектуры на 4 этапе/7 - assistant_runtime_ground_truth_audit_2026-03-28.md`
- `docs/ARCH/8_audit_artifacts/8 - аудит source_to_proof_по_3_контрольным_вопросам_2026-03-29.md`
- `docs/ARCH/9_audit_artifacts/9 - разведка_структуры_1с_и_связей_через_mcp_по_3_контрольным_вопросам_2026-03-29.md`
- `docs/ARCH/9_audit_artifacts/9F - current_runtime_vs_required_runtime.md`

Следующий operational документ:
- `docs/ARCH/10A - current_assistant_hardening_plan_2026-04-15.md`