# ТЗ Этап 4  
## Accounting Ontology Graph Core для Assistant Mode

## 0. Смысл этапа

Этот этап не является попыткой «нарисовать онтологию бухгалтерии» как красивую абстракцию.  
Его задача — ввести **рабочее графовое ядро бухгалтерской предметной области**, которое станет общим причинно-следственным слоем для:

- retrieval;
- lifecycle resolution;
- problem unit assembly;
- cross-branch analysis;
- investigation mode следующего этапа;
- future live verification bridge.

На предыдущих этапах система уже должна получить:

- усиленный текущий контур Assistant Mode;
- `investigation_state` baseline;
- mechanism-aware evidence pack;
- accountant-facing eval layer;
- problem-centric retrieval unit;
- lifecycle formalization по ключевым доменам.

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

Чтобы перейти к следующему уровню reasoning, системе нужен **единый causal representation layer**, в котором:

- документ существует не сам по себе;
- проводка существует не сама по себе;
- контрагент не является главным контейнером смысла;
- lifecycle не живёт отдельно от связей;
- проблема существует как узел или подграф, а не как случайная выдача рядом лежащих сущностей.

Именно это и является предметом Этапа 4.

---

## 1. От чего идём: целевая способность системы

Если смотреть от конечной цели назад, то после Этапа 4 бухгалтерский ассистент должен приобрести следующую новую способность:

**работать не только с сущностями, problem units и lifecycle defects, а с типизированным графом бухгалтерской реальности, по которому можно проходить причинные маршруты, находить отсутствующие/конфликтующие связи и поднимать соседние ветки как архитектурно нормальную операцию.**

Это означает, что система должна уметь:

1. представлять бухгалтерские объекты как типизированные графовые узлы;
2. представлять связи между ними как типизированные рёбра, а не как общую “связанность”; 
3. поддерживать причинные маршруты между документами, проводками, расчётами, налоговыми следствиями, lifecycle-переходами и влиянием на период;
4. использовать этот граф в runtime, а не только в документации;
5. улучшать retrieval, lifecycle reasoning и problem assembly именно за счёт graph layer.

---

## 2. Что не устраивает в текущем состоянии

По итогам предыдущих этапов у системы уже есть:

- нормализованные бухгалтерские сущности;
- semantic retrieval profile;
- problem-centric retrieval;
- lifecycle модели;
- evidence packs;
- answer policy;
- базовый investigation state.

Но даже в таком состоянии у неё остаются архитектурные ограничения:

### 2.1. Связи между сущностями ещё слишком локальны
Даже если retrieval находит правильную проблему, соседние сущности часто поднимаются:

- по фильтрам;
- по локальным relation patterns;
- по heuristics;
- по эвристическим rule bundles.

Это означает, что cross-domain traversal всё ещё слишком зависит от частных сценариев.

### 2.2. Нет единого пространства причинности
Сейчас причина и следствие часто живут в разных местах:

- проблема определяется в retrieval;
- lifecycle — в отдельном resolution слое;
- соседняя ветка подтягивается по дополнительным правилам;
- answer layer уже потом пытается из этого собрать narrative.

Без общего graph core такие reasoning-цепочки остаются хрупкими.

### 2.3. Missing/conflicting links ещё не являются first-class runtime objects
Пока разрыв связи зачастую определяется как:

- эвристика;
- дефект lifecycle;
- conflict label;
- absence of expected evidence.

Но система ещё не мыслит это как **типизированный дефект графа**:

- missing edge;
- invalid edge;
- conflicting edge;
- weakly supported edge;
- obsolete edge.

### 2.4. Investigation traversal ещё не имеет архитектурной базы
Следующий этап должен будет ввести полноценный investigation engine. Но без graph core этот движок будет вынужден жить на ad hoc secondary retrieval, а не на нормальном traversal.

---

## 3. Главная архитектурная цель этапа

К концу Этапа 4 система должна перейти из состояния:

**problem-centric assistant with lifecycle-aware reasoning**

в состояние:

**graph-backed accounting assistant, в котором retrieval, lifecycle и problem assembly опираются на единое causal representation бухгалтерских сущностей и связей.**

---

## 4. Что сохраняем, а что меняем

### 4.1. Что сохраняем
На этом этапе не ломаем уже построенные слои:

- `investigation_state` baseline;
- `semantic_retrieval_profile`;
- broad-query guard;
- mechanism-aware evidence pack;
- problem unit layer;
- lifecycle registry и lifecycle resolver;
- accountant-facing eval harness;
- answer contract предыдущих этапов.

Graph core должен встроиться **под** эти слои и усилить их, а не заменить весь контур с нуля.

### 4.2. Что меняем принципиально
На этом этапе меняем:

1. модель внутренних сущностей;
2. модель связей;
3. runtime-слой, который формирует causal representation;
4. retrieval execution для graph-eligible queries;
5. problem assembly, чтобы он использовал graph connectivity;
6. lifecycle reasoning, чтобы он использовал graph-backed transitions;
7. eval layer, чтобы она умела доказывать ценность graph layer.

### 4.3. От чего отказываемся
На этом этапе нужно осознанно отказаться от следующих паттернов:

- retrieval “по соседству” без явной модели связей;
- implicit relation semantics, зашитой в случайные правила;
- ad hoc cross-branch checks без graph traversal;
- формальной онтологии, которая не участвует в runtime;
- мысли о том, что graph = просто JSON-структура для объяснения.

---

## 5. Главные сущности этапа

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

---

## 5.1. Сущность №1 — `AccountingGraphNode`

### Почему нужна
Система не может делать устойчивый traversal, пока объекты учёта существуют только как плоские normalized items.

Нужен единый типизированный контейнер для сущности в graph layer.

### Что это такое
`AccountingGraphNode` — это базовая графовая сущность, представляющая конкретный бухгалтерский объект или агрегированную аналитическую единицу.

### Базовые поля
- `node_id`
- `node_type`
- `source_type`
- `source_id`
- `domain`
- `subdomain`
- `attributes`
- `period_scope`
- `organization_scope`
- `confidence`
- `provenance`
- `temporal_markers`
- `lifecycle_binding`
- `graph_status`

### Какие типы узлов должны быть поддержаны

#### Документные узлы
- `BankStatementDocument`
- `PaymentOrderDocument`
- `ReceiptDocument`
- `SalesDocument`
- `InvoiceDocument`
- `AdjustmentDocument`
- `DeferredExpenseDocument`
- `AssetAcceptanceDocument`
- `AssetCommissioningDocument`
- `DepreciationDocument`
- `PeriodCloseOperation`
- `ManualOperationDocument`

#### Учётные узлы
- `Posting`
- `RegisterMovement`
- `Account`
- `Subaccount`
- `TaxEntry`
- `VATPosition`
- `DeferredExpensePosition`
- `AssetCard`
- `SettlementPosition`
- `ReceivablePosition`
- `PayablePosition`

#### Бизнес-узлы
- `Counterparty`
- `Contract`
- `Organization`
- `Department`
- `Project`
- `Warehouse`
- `Nomenclature`
- `AssetObject`

#### Аналитические узлы
- `ProblemUnit`
- `LifecycleStateNode`
- `PeriodRiskNode`
- `InvestigationFocusNode`

### Зачем это нужно бухгалтерски
В 1С одна и та же проблема часто размазана по разным слоям:

- документ;
- проводка;
- регистр;
- расчётная позиция;
- контрагент;
- договор;
- период;
- налоговое следствие.

Пока эти объекты не приведены к единому узловому представлению, система не может делать нормальный causal traversal.

---

## 5.2. Сущность №2 — `AccountingGraphEdge`

### Почему нужна
Graph без typed edges — это не рабочая причинная модель, а просто связанный список объектов.

### Что это такое
`AccountingGraphEdge` — типизированная связь между двумя graph nodes с чётким смыслом, confidence и provenance.

### Базовые поля
- `edge_id`
- `edge_type`
- `from_node_id`
- `to_node_id`
- `direction`
- `attributes`
- `confidence`
- `provenance`
- `is_expected`
- `is_observed`
- `is_conflicting`
- `is_missing_marker`
- `temporal_markers`

### Базовые классы рёбер

#### Документно-учётные связи
- `creates_posting`
- `affects_register`
- `references_document`
- `based_on_document`
- `generated_from`
- `belongs_to_period`

#### Расчётные связи
- `settles`
- `partially_settles`
- `linked_to_payment`
- `linked_to_receivable`
- `linked_to_payable`
- `linked_to_contract`

#### Lifecycle-связи
- `advances_to_state`
- `expected_next_state`
- `conflicts_with_state`
- `closes`
- `writes_off`
- `commissions`
- `depreciates`

#### Cross-domain связи
- `affects_vat`
- `affects_period_close`
- `depends_on_branch`
- `conflicts_with_branch`
- `requires_neighbor_check`

#### Проблемно-аналитические связи
- `evidence_for_problem`
- `part_of_problem_cluster`
- `supports_hypothesis`
- `contradicts_hypothesis`

### Зачем это нужно бухгалтерски
Для бухгалтера важно не только наличие объектов, а смысл связи между ними:

- документ создал проводку;
- платёж должен закрывать обязательство;
- РБП должно перейти в списание;
- ввод ОС должен вести к амортизации;
- счёт-фактура должна вести к налоговому следствию;
- один контур влияет на закрытие другого.

Именно эти причинные связи и должны стать first-class runtime objects.

---

## 5.3. Сущность №3 — `GraphSchemaRegistry`

### Почему нужна
Если node/edge типы живут в коде фрагментами, система быстро превратится в набор несогласованных graph rules.

### Что это такое
Единый реестр graph schema, где определяются:

- допустимые node types;
- допустимые edge types;
- обязательные атрибуты;
- domain bindings;
- lifecycle bindings;
- expected graph patterns;
- graph validation rules.

### Что он должен содержать
Для каждого node type:
- required attributes;
- optional attributes;
- provenance sources;
- domain membership;
- period semantics;
- lifecycle compatibility.

Для каждого edge type:
- допустимые типы from/to;
- допустимость направлений;
- допустимость по домену;
- допустимость по lifecycle;
- confidence policy;
- missing-edge semantics.

### Зачем это нужно
Чтобы graph оставался управляемой архитектурной системой, а не хаотичным набором типов и связей.

---

## 5.4. Сущность №4 — `GraphBuilder`

### Почему нужна
Graph schema без runtime-построения — это формальная документация, а не архитектурный слой.

### Что это такое
`GraphBuilder` — runtime-компонент, который из normalized accounting entities, lifecycle outputs и relation evidence строит graph core.

### Что он принимает на вход
- normalized documents;
- postings;
- register movements;
- domain-specific entities;
- lifecycle resolution outputs;
- problem assembly signals;
- source provenance metadata.

### Что он делает
1. создаёт graph nodes;
2. создаёт typed edges;
3. маркирует expected vs observed relations;
4. создаёт missing/conflicting edge markers;
5. формирует graph layer для retrieval/problem assembly/investigation;
6. присваивает confidence и provenance.

### Что важно
GraphBuilder не должен быть чисто offline-процедурой “раз в день”.  
На этапе 4 допускается snapshot-based build, но он должен быть встроен в рабочий assistant runtime как доступный слой.

---

## 5.5. Сущность №5 — `GraphTraversalPolicy`

### Почему нужна
Наличие graph само по себе не означает, что система умеет им пользоваться.

### Что это такое
Политика traversal по graph layer для разных классов задач.

### Какие типы traversal должны быть поддержаны

#### Upstream traversal
От проблемы назад к причинам.

#### Downstream traversal
От объекта вперёд к последствиям.

#### Cross-domain traversal
Из одного домена в другой:
- банк → расчёты;
- документ → НДС;
- объект → период;
- документ → lifecycle state;
- issue → affected branches.

#### Period-impact traversal
Поиск того, как локальная проблема влияет на закрытие периода.

#### Neighbor-branch traversal
Переход в соседнюю ветку учёта для усиления доказательной базы.

### Что важно
Traversal не должен быть свободным «гулянием по графу». Нужны жёсткие policies:

- allowed traversal depth;
- allowed edge families;
- purpose-specific traversal;
- stop criteria;
- evidence sufficiency rules.

---

## 5.6. Сущность №6 — `GraphBackedProblemAssembly`

### Почему нужна
Problem unit layer второго этапа не должен оставаться чисто эвристическим, если мы уже строим graph core.

### Что это такое
Слой problem assembly, который использует graph connectivity и graph defects как основу для формирования problem units.

### Что меняется по сравнению с этапом 2
Раньше problem unit собирался в основном из:

- retrieval entities;
- relation patterns;
- lifecycle defects;
- evidence pack fields.

Теперь problem unit должен собираться также из:

- graph-connected nodes;
- missing edges;
- conflicting edges;
- weakly supported paths;
- graph neighborhoods;
- branch crossings.

### Что это даёт
- более чёткое отделение одной проблемы от другой;
- более сильное объяснение broken chain;
- better cross-branch inconsistency detection;
- better duplicate collapse;
- better evidence completeness.

---

## 5.7. Сущность №7 — `GraphBackedLifecycleBinding`

### Почему нужна
Lifecycle formalization из этапа 3 должна опираться на graph, а не существовать как отдельная state machine поверх плоских данных.

### Что это такое
Связь lifecycle registry/runtime с graph core.

### Что должно происходить
- lifecycle state node должен быть связан с domain object;
- expected transitions должны отображаться через expected edges;
- observed transitions должны отображаться через observed edges;
- missing transition = missing expected edge;
- invalid transition = conflicting edge pattern.

### Что это даст
Lifecycle становится не только временной логикой, но и логикой структурных переходов в графе.

---

## 5.8. Сущность №8 — `GraphProvenanceLayer`

### Почему нужна
В бухгалтерии нельзя строить reasoning по графу без ясного понимания, откуда взялась каждая связь.

### Что это такое
Слой provenance для nodes и edges.

### Что должен хранить
- источник (snapshot / live / inferred / derived);
- origin entity ids;
- confidence source;
- timestamp / period;
- inference path;
- lifecycle dependence;
- conflict flags.

### Зачем это нужно
Иначе graph будет выглядеть умно, но не будет доказуемым и пригодным для бухгалтерского ассистента.

---

## 5.9. Сущность №9 — `GraphValidationLayer`

### Почему нужна
Самый большой риск этапа — построить formal graph, который runtime почти не улучшает.

### Что это такое
Слой валидации graph core по двум осям:

1. structural validity;
2. product value validity.

### Structural validity
- корректность node/edge типов;
- корректность доменных связей;
- корректность confidence/provenance;
- отсутствие невалидных типов связей;
- отсутствие циклов там, где они запрещены.

### Product value validity
- улучшил ли graph causal retrieval;
- улучшил ли graph cross-branch reasoning;
- улучшил ли graph problem unit precision;
- улучшил ли graph lifecycle explanation;
- улучшил ли graph answer usefulness.

---

## 6. Домены этапа 4

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

### 6.1. Банк / расчёты / 51–60
Узлы:
- выписка;
- платёжное поручение;
- проводка;
- settlement position;
- payable position;
- counterparty;
- contract.

Связи:
- payment ↔ statement;
- statement ↔ posting;
- payment ↔ settlement;
- settlement ↔ contract;
- settlement ↔ payable closure.

### 6.2. Покупатели / 62
Узлы:
- реализация;
- оплата;
- receivable position;
- contract;
- tax entry.

Связи:
- sales ↔ posting;
- payment ↔ receivable;
- receivable ↔ contract;
- sales ↔ VAT effect.

### 6.3. РБП / 97
Узлы:
- deferred expense document;
- deferred expense position;
- writeoff movement;
- period;
- supporting basis.

Связи:
- basis ↔ deferred expense;
- deferred expense ↔ writeoff;
- writeoff ↔ period;
- deferred expense ↔ lifecycle state.

### 6.4. ОС / 08–01–02
Узлы:
- asset acceptance document;
- asset commissioning document;
- asset card;
- depreciation movement;
- asset object.

Связи:
- acceptance ↔ asset card;
- commissioning ↔ asset object;
- asset object ↔ depreciation;
- capitalized value ↔ commissioned asset.

### 6.5. НДС / 19–68
Узлы:
- invoice;
- tax entry;
- VAT position;
- source document;
- period.

Связи:
- source document ↔ invoice;
- invoice ↔ VAT position;
- VAT position ↔ tax entry;
- VAT position ↔ period.

### 6.6. Закрытие периода
Узлы:
- period close operation;
- affected problem unit;
- affected domain object;
- period risk node.

Связи:
- domain object ↔ period close;
- problem unit ↔ period risk;
- unresolved chain ↔ close blocker.

---

## 7. Что именно меняется по цепи выполнения

---

## 7.1. Вход данных

### Сейчас
Система получает normalized accounting entities из snapshot/assistant data layer.

### Что меняем
После normalized entity layer вводится graph construction layer.

### Новый фрагмент контура
`Normalized entities → GraphBuilder → Graph core → retrieval / lifecycle / problem assembly / answer`

### Цель
Сделать graph не параллельной документацией, а рабочим промежуточным слоем.

---

## 7.2. Retrieval planning

### Сейчас
Retrieval planning строится на semantic profile и domain-specific filters.

### Что меняем
Добавляем `graph_eligibility` и `graph_traversal_policy` в retrieval plan.

### Что должно появиться
- для causal queries;
- для cross-branch queries;
- для period-impact queries;
- для neighbor-check-worthy problem units.

Retrieval planner должен уметь решать:
- нужен ли graph traversal;
- какой traversal type нужен;
- какая глубина допустима;
- какие edge families допустимы.

---

## 7.3. Retrieval execution

### Сейчас
Execution основан на semantic narrowing + problem-centric extraction.

### Что меняем
В graph-eligible режимах retrieval должен использовать:
- node lookup;
- typed edge traversal;
- missing/conflicting edge detection;
- graph neighborhood assembly.

### Что важно
Graph-backed retrieval не заменяет фильтры. Он расширяет их там, где нужен causal traversal.

---

## 7.4. Lifecycle reasoning

### Сейчас
Lifecycle работает по domain state models и evidence.

### Что меняем
Lifecycle resolver должен использовать graph edges для:
- проверки ожидаемых переходов;
- проверки observed transitions;
- маркировки missing/invalid transitions;
- cross-branch consistency.

---

## 7.5. Problem assembly

### Сейчас
Problem units собираются по evidence и relation patterns.

### Что меняем
Assembler должен использовать graph connectivity как первичный или равноправный признак assembly.

### Что это значит practically
Если есть broken chain, то assembler должен видеть:
- какие узлы входят в цепочку;
- какая связь отсутствует;
- какая связь конфликтует;
- какие соседние узлы усиливают проблему.

---

## 7.6. Answer synthesis

### Сейчас
Answer layer строит narrative по problem units и lifecycle-enriched evidence.

### Что меняем
Composer должен уметь включать graph-backed explanation fragments:
- между какими сущностями найден разрыв;
- какая ожидаемая связь отсутствует;
- какая ветка противоречит другой;
- как проблема проходит по causal path.

### Цель
Сделать explanation не просто case-specific, а структурно причинным.

---

## 8. Как не уткнуться в главный риск этапа

Пользователь специально просил отдельно раскрыть, как не скатиться в формальный этап. Это критично.

### Главный риск
Сделать онтологию как формальную схему, которую можно красиво показать, но которая почти не влияет на runtime.

### Как это обычно выглядит
- список узлов описан;
- список рёбер описан;
- graph builder формально есть;
- maybe есть storage;
- но retrieval почти не поменялся;
- problem assembly почти не поменялся;
- answer quality почти не выросло.

### Как этого избежать

#### 1. Graph должен иметь runtime-critical use cases
С первого релиза этапа graph должен использоваться хотя бы в:
- broken chain detection;
- cross-branch inconsistency checks;
- period-impact traversal;
- problem unit assembly.

#### 2. Нужно сразу доказать value, а не только correctness
Нужны before/after сценарии, где graph реально улучшает:
- causal answers;
- neighboring branch discovery;
- distinction between one problem and another;
- explanation clarity.

#### 3. Нельзя строить graph “вообще”
Graph schema должен строиться под уже существующие бухгалтерские домены и problem classes.

#### 4. Нельзя делать слабые edge types
“related_to” не подходит как основной тип связи.  
Нужны typed edges с бухгалтерским смыслом.

#### 5. Нельзя оставлять provenance опциональным
Без provenance graph быстро превратится в недоказуемую inference-конструкцию.

#### 6. Нельзя считать этап успешным, если graph не вошёл в retrieval/problem assembly/lifecycle
Документация и storage сами по себе не считаются результатом.

---

## 9. Что должно быть переписано, а что только усилено

### Полностью переписывать на этапе 4 не надо
- весь assistant loop;
- normalizer;
- базовый routing engine;
- answer contract с нуля;
- lifecycle registry с нуля;
- problem unit layer с нуля.

### Существенно переделываем
- internal representation layer;
- relation semantics;
- graph-eligible retrieval execution;
- graph-backed problem assembly;
- lifecycle-to-graph binding;
- eval harness для graph value.

### Частично усиливаем
- evidence pack;
- traversal hints в retrieval profile;
- answer composer;
- investigation state integration.

### Оставляем на следующий этап
- полноценный investigation orchestrator;
- full branch automation;
- live verification bridge как core path;
- full enterprise graph beyond accounting core.

---

## 10. Архитектурные артефакты этапа

К концу этапа должны появиться следующие артефакты:

1. `AccountingGraphNode` schema
2. `AccountingGraphEdge` schema
3. `GraphSchemaRegistry`
4. `GraphBuilder` runtime spec
5. `GraphTraversalPolicy` spec
6. `GraphBackedProblemAssembly` spec
7. `GraphBackedLifecycleBinding` spec
8. `GraphProvenanceLayer` spec
9. `GraphValidationLayer` spec
10. domain graph definitions for selected accounting domains
11. graph-backed benchmark suite
12. graph value proof scenarios

---

## 11. Критерии приёмки этапа

Этап считается выполненным только при одновременном выполнении следующих условий.

### 11.1. По graph core
- есть рабочая node/edge schema;
- graph builder формирует runtime-usable graph;
- nodes и edges имеют provenance и confidence;
- graph покрывает agreed accounting domains.

### 11.2. По retrieval
- graph-eligible queries реально используют graph traversal;
- broken chain detection улучшается за счёт graph;
- cross-branch checks перестают быть чисто эвристическими;
- period-impact traversal использует graph relationships.

### 11.3. По problem assembly
- problem units собираются по graph connectivity, а не только по filter proximity;
- duplicate collapse quality улучшается;
- distinction between separate vs shared problem clusters становится лучше.

### 11.4. По lifecycle
- lifecycle resolver использует graph-backed transitions;
- missing/invalid transitions определяются через graph semantics;
- lifecycle explanation становится структурно точнее.

### 11.5. По answer usefulness
- ответы лучше объясняют, между чем и чем разрыв;
- ответы лучше показывают путь проблемы по связанным сущностям;
- ответы лучше поднимают соседние контуры и влияние на период.

### 11.6. По продуктовой ценности
- есть канонические сценарии before/after;
- доказано, что graph layer улучшает не только внутреннюю красоту, но и user-facing полезность.

---

## 12. Что не считается результатом этапа

Этап не считается выполненным, если произошло только что-то из этого:

- появилась formal ontology documentation;
- появилась graph storage representation;
- появились node/edge definitions, но runtime их почти не использует;
- graph builder есть, но retrieval/problem assembly почти не изменились;
- answers не стали заметно более причинными;
- graph оказался просто ещё одним способом сериализации старых entities.

---

## 13. Практический идеальный результат этапа

После завершения Этапа 4 система ещё не должна быть финальным бухгалтерским copilot.  
Но она уже должна перестать быть:

- набором локальных retrieval и lifecycle правил;
- системой, которая тянет соседние сущности в основном по эвристике;
- assistant’ом, который знает problem units, но не имеет общего пространства связей.

И должна стать:

- graph-backed accounting assistant;
- системой, в которой causal traversal является нормальной архитектурной операцией;
- системой, где retrieval, lifecycle и problem assembly живут в одном пространстве типизированных связей;
- базой для Investigation Engine следующего этапа.

---

## 14. Короткое управленческое резюме этапа

**Этап 4 не строит “красивую онтологию”.  
Он строит рабочее графовое ядро бухгалтерских сущностей и связей, чтобы retrieval, lifecycle reasoning и problem assembly опирались на единое causal representation.  
Только после этого становится рационально строить полноценный investigation engine как следующий взрослый архитектурный слой.**
