# Query Recipes V1 (Address Query)

Дата: 2026-04-13  
Контур: `question_mode=address_query` (live-first, whitelist only)

## 1) Safe Access Contract

Каноническая цепочка исполнения:

`intent -> filters -> recipe -> MCP -> materialization -> factual/limited`

Ограничения:

- LLM не генерирует свободные SQL/1C-запросы.
- Runtime выбирает только `recipe_id` из статического каталога.
- Если фильтры/якоря невалидны или не подтверждены, возвращается `LIMITED_WITH_REASON`.

## 2) Entity Families (runtime focus)

- `ACCOUNTING_REGISTER` (`РегистрБухгалтерии.Хозрасчетный`)
- `DOCUMENT` (`СписаниеСРасчетногоСчета`, `ПоступлениеНаРасчетныйСчет`, документные строки)
- `DOCUMENT_JOURNAL`
- `NSI_CATALOG` (договоры, контрагенты)
- `CHART_OF_ACCOUNTS`

## 3) Filter Catalog (runtime)

| filter | type | required_when (runtime) | notes |
|---|---|---|---|
| `period_from` | date (`YYYY-MM-DD`) | периодные выборки | начало окна |
| `period_to` | date (`YYYY-MM-DD`) | периодные выборки | конец окна |
| `as_of_date` | date (`YYYY-MM-DD`) | balance/drilldown/open-items | для account intents defaulted если не задан |
| `organization` | string | optional | passthrough-filter |
| `counterparty` | string | by-counterparty intents | допускается heuristic extraction |
| `contract` | string | by-contract intents | допускается heuristic extraction |
| `account` | string (`60`, `62.01`, ...) | account intents | strict token normalization |
| `document_type` | string | optional (пока ограниченно используется) | runtime V1 не строит отдельный by-type intent |
| `document_ref` | string | optional | point lookup |
| `status` | string | optional | reserved |
| `limit` | int | optional | extractor default: `20` |
| `sort` | enum | optional | `period_desc` / `period_asc` |

## 4) Runtime Recipe Catalog (actual)

| recipe_id | intent | purpose | required_filters | optional_filters | query_template | account_scope_mode |
|---|---|---|---|---|---|---|
| `address_period_coverage_profile_v1` | `period_coverage_profile` | профиль покрытия периодов + топ год/месяц активности | - | `period_from`, `period_to`, `organization`, `limit` | `period_profile` | `preferred` |
| `address_document_type_and_account_section_profile_v1` | `document_type_and_account_section_profile` | профиль типов документов + заполненность разделов учета | - | `period_from`, `period_to`, `organization`, `limit` | `document_section_profile` | `preferred` |
| `address_movements_payables_v1` | `list_payables_counterparties` | movement-срез по обязательствам | - | `as_of_date`, `counterparty`, `contract`, `limit` | `movements` | `preferred` |
| `address_movements_receivables_v1` | `list_receivables_counterparties` | movement-срез по требованиям | - | `as_of_date`, `counterparty`, `contract`, `limit` | `movements` | `preferred` |
| `address_open_contracts_confirmed_as_of_date_v1` | `open_contracts_confirmed_as_of_date` | подтвержденный срез открытых договоров на дату | `as_of_date` | `period_from`, `period_to`, `organization`, `counterparty`, `contract`, `limit`, `sort` | `open_contracts_confirmed_as_of_balance_profile` | `strict` |
| `address_open_contracts_candidates_v1` | `list_open_contracts` | диагностические кандидаты незакрытых договоров | - | `as_of_date`, `organization`, `limit` | `movements` | `preferred` |
| `address_open_items_by_party_or_contract_v1` | `open_items_by_counterparty_or_contract` | открытые позиции по party/contract | - (`service guard`: нужен `counterparty OR contract`) | `as_of_date`, `counterparty`, `contract`, `limit` | `movements` | `preferred` |
| `address_documents_by_counterparty_v1` | `list_documents_by_counterparty` | документы по контрагенту | `counterparty` | `period_from`, `period_to`, `as_of_date`, `organization`, `limit`, `sort` | `bank_docs` | `preferred` |
| `address_bank_operations_by_counterparty_v1` | `bank_operations_by_counterparty` | банковские операции по контрагенту | `counterparty` | `period_from`, `period_to`, `as_of_date`, `organization`, `limit`, `sort` | `bank_docs` | `preferred` |
| `address_documents_by_contract_v1` | `list_documents_by_contract` | документы по договору | `contract` | `period_from`, `period_to`, `as_of_date`, `organization`, `counterparty`, `limit`, `sort` | `movements` | `preferred` |
| `address_bank_operations_by_contract_v1` | `bank_operations_by_contract` | банковские операции по договору | `contract` | `period_from`, `period_to`, `as_of_date`, `organization`, `counterparty`, `limit`, `sort` | `movements` | `preferred` |
| `address_documents_forming_balance_v1` | `documents_forming_balance` | drilldown документов, формирующих остаток | `account`, `as_of_date` | `organization`, `counterparty`, `contract`, `period_from`, `period_to`, `limit`, `sort` | `movements` | `strict` |
| `address_movements_account_snapshot_v1` | `account_balance_snapshot` | snapshot движений по счету | `account` (`as_of_date` defaulted in extractor) | `as_of_date`, `period_from`, `period_to`, `limit` | `movements` | `strict` |

## 5) Limit and Scope Policy (actual)

- Базовый max limit: `200`.
- Расширенный max limit (`1000`) для:
  - `period_coverage_profile`;
  - `document_type_and_account_section_profile`;
  - `documents/bank by counterparty|contract`;
  - `open_items_by_counterparty_or_contract`;
  - `list_open_contracts`;
  - `open_contracts_confirmed_as_of_date`.
- Для all-time запросов `documents/bank by *` runtime поднимает limit до max.
- Для account intents при явном `account` limit поднимается до `200`.

## 6) Stage Status Taxonomy (runtime)

- `skipped`
- `error`
- `no_raw_rows`
- `raw_rows_received_but_not_materialized`
- `materialized_but_not_anchor_matched`
- `materialized_but_filtered_out_by_recipe`
- `matched_non_empty`

Legacy совместимость:

- `mcp_call_status_legacy=materialized_but_not_matched` для двух split-статусов materialized-*.

## 7) Runtime Fallback Behaviors (actual)

- При `list_documents_by_contract` и пустом документном отборе, но с anchor rows:
  - fallback на банковские строки по договору или на anchor rows.
- Для `documents/bank by *` при пустом заданном периоде:
  - auto-broaden периода до доступных данных (`period_window_auto_broadened_to_available_data`).
- Для `documents/bank by *` при anchor mismatch:
  - factual fallback на ближайшие строки (`anchor_not_matched_fallback_rows`) вместо silent empty.
- Для `open_contracts_confirmed_as_of_date`:
  - exact недоступность должна заканчиваться `LIMITED_WITH_REASON`;
  - `list_open_contracts` допустим только как отдельный diagnostic capability, не как silent fallback.

## 8) Result Modes

- `FACTUAL_LIST`
- `FACTUAL_SUMMARY`
- `LIMITED_WITH_REASON`

Фактическая реализация `composeStage` сейчас отдает:

- `FACTUAL_SUMMARY` для `account_balance_snapshot`, `period_coverage_profile`, `document_type_and_account_section_profile`;
- для остальных factual intents — `FACTUAL_LIST`.

## 9) Guardrails

- whitelist recipes only
- read-only MCP
- no free-form query generation
- no silent source substitution