# 02 - State And Transition Contracts

## Purpose

This document defines the objects that must become explicit in project design:

1. `state objects`
2. `transition classes`

The goal is to stop treating the assistant as a prompt-driven flow with ad hoc carryover and start treating it as a stateful runtime with explicit transitions.

## State Model

### 1. Assistant Session Aggregate

Top-level first-class runtime state:

`assistant_session_state`

It must aggregate:

- `living_mode_state`
- `address_navigation_state`
- `investigation_state`
- `clarification_state`
- `answer_context_state`
- `coverage_gate_state`

This aggregate is the architectural owner of cross-turn continuity.

### 2. Living Mode State

Purpose:

- remember which major runtime contour is active.

Fields:

- `living_mode`
- `mode_reason`
- `mode_source`
- `mode_entry_turn_id`

Allowed values:

- `address_data`
- `assistant_data_scope`
- `chat`
- `meta_followup`
- `clarification`

### 3. Root Frame State

Purpose:

- represent the currently active root business slice.

Fields:

- `domain_id`
- `root_route_id`
- `organization_scope`
- `date_scope`
- `root_result_set_id`
- `root_answer_object_ref`
- `frame_status`

This state survives more transitions than object state.

### 4. Selected Object Frame State

Purpose:

- represent the currently active drilldown object.

Fields:

- `focus_object_ref`
- `focus_object_kind`
- `source_result_set_id`
- `compatible_route_family`
- `provenance_bundle_ref`
- `temporal_ceiling`
- `frame_status`

This state may only survive compatible object-level transitions.

### 5. Meta Frame State

Purpose:

- support questions about the already returned answer without replaying exact execution blindly.

Fields:

- `source_answer_object_ref`
- `meta_question_kind`
- `source_gate_status`
- `meta_truth_mode`

Allowed meta classes:

- `evaluation`
- `comparison`
- `memory_recap`
- `boundary_explanation`
- `answer_interpretation`

### 6. Clarification State

Purpose:

- represent unfinished business queries that are waiting for missing anchors or disambiguation.

Fields:

- `clarification_kind`
- `missing_anchors`
- `candidate_scopes`
- `resume_target_route`
- `resume_target_frame`

### 7. Coverage Gate State

Purpose:

- capture whether the exact execution result is admissible for full, partial, or blocked downstream behavior.

Fields:

- `coverage_status`
- `evidence_grade`
- `grounding_status`
- `truth_mode`
- `carryover_eligibility`
- `reason_codes`

Allowed values:

- `coverage_status`: `full`, `partial`, `blocked`
- `truth_mode`: `confirmed`, `limited`, `clarification_required`, `unsupported`
- `carryover_eligibility`: `full`, `root_only`, `object_only`, `meta_only`, `none`

## Transition Model

The architecture must distinguish transition classes explicitly.

### T1. Root Query Entry

Trigger:

- new root business question

Inputs:

- raw user query
- living mode state

Outputs:

- new `root_frame_state`
- new `coverage_gate_state`

Must not:

- inherit stale `focus_object`

### T2. Root Follow-Up With Date Or Scope Change

Trigger:

- `а на март 2020`
- `на тот же период`
- `еще раз по этой дате`

Inputs:

- existing `root_frame_state`
- compatible temporal or organization shift

Outputs:

- updated `root_frame_state`
- new exact route execution

Must preserve:

- root domain
- organization scope if not explicitly changed

Must not:

- downgrade into `unknown` if supported root route exists

### T3. Explicit Selected Object Drilldown

Trigger:

- item selected from current result set
- UI selected-object wording
- full explicit object mention

Inputs:

- active `root_frame_state`
- selected object reference

Outputs:

- `selected_object_frame_state`

Must preserve:

- source result set
- compatible temporal ceiling

### T4. Short Action Follow-Up On Selected Object

Trigger:

- `кто поставщик`
- `где купили`
- `кому продали`
- `какие документы`

Inputs:

- active `selected_object_frame_state`
- compatible action request

Outputs:

- exact item-level capability route

Must not:

- fall into generic chat
- fall into data-scope selection
- lose selected object because the wording is short

### T5. Pronoun Or Compressed Object Follow-Up

Trigger:

- `по ней`
- `по этой позиции`
- `а эта кому ушла`

Inputs:

- active `selected_object_frame_state`
- prior compatible object route

Outputs:

- continued object drilldown

Must not:

- degrade full object anchor into vague semantic noise

### T6. Domain Pivot With Root-Only Carryover

Trigger:

- user leaves the current object drilldown but remains in compatible higher business scope

Inputs:

- `root_frame_state`
- incompatible `selected_object_frame_state`

Outputs:

- preserved root context
- dropped object context

Must preserve:

- organization/date root scope

Must not:

- replay object route into another domain

### T7. Clarification Continuation

Trigger:

- user resolves missing anchor or ambiguity

Inputs:

- active `clarification_state`

Outputs:

- resumed target route
- cleared or updated clarification state

Must not:

- forget the suspended target route

### T8. Meta Follow-Up Over Answer Object

Trigger:

- `это много или мало`
- `это мы должны или нам`
- `что из этого важнее`

Inputs:

- `answer_context_state`
- `coverage_gate_state`

Outputs:

- meta answer

Must not:

- blindly replay exact route

### T9. Memory Recap

Trigger:

- `мы это обсуждали?`
- `помнишь, о чем говорили`

Inputs:

- prior grounded answer context

Outputs:

- truthful recap

Must not:

- invent conversation memory

### T10. Unsupported Or Blocked Boundary

Trigger:

- unsupported route
- blocked evidence gate
- execution failure

Inputs:

- exact runtime outcome
- `coverage_gate_state`

Outputs:

- bounded truthful answer or clarification

Must not:

- masquerade blocked execution as confirmed factual answer

## Transition Invariants

Every transition must declare:

- `entry condition`
- `required prior state`
- `allowed carryover depth`
- `state mutations`
- `forbidden carryover`
- `expected answer mode`

## Required Artifacts

Any future implementation of these contracts should produce:

- transition table or registry;
- state schema definitions;
- transition tests;
- scenario acceptance coverage by transition class.

## Done Criteria

This document is only considered implemented in architecture when:

- every major follow-up case maps to a named transition class;
- every transition class has a declared state owner;
- every transition class has a scenario-based regression family;
- no critical follow-up behavior depends only on unnamed heuristic carryover.