# Address Runtime Contracts V1 (M2.3b)

Дата: 2026-03-29

## Runtime Policy

- Runtime lane is `data-agnostic`: no hardcoded counterparties/contracts/accounts from one concrete base.
- Acceptance lane is `data-aware`: positive cases are curated after exploratory live pass.
- Address lane remains MCP/live-first, whitelist-only, read-only.

## Input Contract

- `question_mode`: `address_query | deep_analysis | unsupported`
- `address_intent`: nullable enum
- `resolved_filters`: object
- `missing_filters`: string[]

## Debug Contract

- `detected_mode`
- `query_shape`
- `detected_intent`
- `runtime_readiness`
- `is_compound_query`
- `subqueries_count`
- `resolved_entities`
- `resolved_filters`
- `missing_filters`
- `selected_recipe_ids`
- `selected_recipe`
- `account_scope_mode`
- `account_scope_fallback_applied`
- resolver block:
  - `anchor_type`
  - `anchor_value_raw`
  - `anchor_value_resolved`
  - `resolver_confidence`
  - `ambiguity_count`
- MCP/evidence flow block:
  - `mcp_call_status`
  - `rows_fetched`
  - `raw_rows_received`
  - `rows_after_account_scope`
  - `rows_materialized`
  - `rows_after_recipe_filter`
  - `rows_matched`
  - `raw_row_keys_sample`
  - `materialization_drop_reason`
- `response_type`
- `limited_reason_category`
- `fallback_reason`

## Output Contract

### FACTUAL_LIST

- short summary
- rows[]
- totals

### FACTUAL_SUMMARY

- aggregate summary
- top rows
- optional drilldown hints

### LIMITED_WITH_REASON

- explicit reason code
- missing filters / data availability note

## Limited Reason Taxonomy

- `empty_match` - live-запрос выполнен, но по фильтру нет строк.
- `missing_anchor` - не хватает обязательного якоря (контрагент/договор/счет/период).
- `recipe_visibility_gap` - текущий recipe не материализует нужную аналитику.
- `execution_error` - ошибка MCP/инфраструктуры/feature-flag.
- `unsupported` - вопрос не покрыт address-intent V1.

## Runtime Readiness Status

- `LIVE_QUERYABLE`
- `LIVE_QUERYABLE_WITH_LIMITS`
- `REQUIRES_SPECIALIZED_RECIPE`
- `DEEP_ONLY`
- `UNKNOWN`

## MCP Stage Status Taxonomy (M2.3a)

- `skipped`
- `error`
- `no_raw_rows`
- `raw_rows_received_but_not_materialized`
- `materialized_but_not_matched`
- `matched_non_empty`

## Materialization Drop Reasons (M2.3a)

- `none`
- `dropped_by_account_scope_filter`
- `missing_period_and_registrator_fields`
- `missing_period_field`
- `missing_registrator_field`
- `unknown_row_shape`

## Account Scope Strategy (M2.3b)

- `strict` - account scope is mandatory and applied as a hard filter.
- `preferred` - account scope is applied first; if it yields zero rows while raw rows exist, runtime falls back to raw rows and continues matching.

## Compound Query Note

- `COMPOUND_FACTUAL_QUERY` currently remains detection-only.
- Multi-intent decomposition execution is planned for next increment.

## Guardrails

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