NODEDC_1C/docs/ARCH/11 - architecture_turnaround/02 - state_and_transition_contracts.md

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.