# v2.0.2 Execution State Machine

## Goal
Synchronize fragment-level states so there are no gray zones between:
- domain scope
- execution readiness
- routing
- fallback behavior

## Canonical Fragment Contract (v2.0.2)
- `execution_readiness`: `executable | executable_with_soft_assumptions | needs_clarification | no_route`
- `route_status`: `routed | no_route`
- `no_route_reason`: `out_of_scope | insufficient_specificity | missing_mapping | unsupported_fragment_type | null`

## Resolver Layer
`resolveFragmentExecutionStateV202(fragment, session_context)` runs after raw LLM output and before schema validation.

Resolver responsibilities:
1. Normalize readiness.
2. Normalize route status.
3. Set explicit no-route reason.
4. Enforce deterministic no-route guard.

## State Rules

### Rule A: out-of-scope
- Condition: `domain_relevance=out_of_scope`
- Result:
  - `execution_readiness=no_route`
  - `route_status=no_route`
  - `no_route_reason=out_of_scope`

### Rule B: insufficient specificity
- Condition: readiness policy says clarification is required
- Result:
  - `execution_readiness=needs_clarification`
  - `route_status=no_route`
  - `no_route_reason=insufficient_specificity`

### Rule C: missing mapping
- Condition: in-scope fragment cannot be mapped by deterministic route selector
- Result:
  - `execution_readiness=no_route`
  - `route_status=no_route`
  - `no_route_reason=missing_mapping`

### Rule D: routable fragment
- Condition: in-scope, not clarification-blocked, route-selectable
- Result:
  - `execution_readiness=executable | executable_with_soft_assumptions`
  - `route_status=routed`
  - `no_route_reason=null`

## Global Clarification Rule
`global_notes.needs_clarification=true` only when all in-scope fragments are clarification-blocked.

## Deterministic Routing Consistency Checks

Decision is consistent when:
- `route=no_route` -> readiness is not executable, and `no_route_reason` is present.
- `route!=no_route` -> readiness is not clarification/no_route, and `no_route_reason` is null.

This consistency is now measured in eval as:
- `execution_state_consistency_rate`

## Fallback Alignment
- `out_of_scope`: no in-scope fragments
- `clarification`: in-scope exists, but zero routable fragments due clarification
- `partial`: mix of routed and no-route fragments
- `none`: all in-scope fragments routed

## Trace Completeness Guard
For each normalization run, service now validates trace has:
- raw model output
- parsed normalized payload
- fragment execution state fields (for v2.0.1/v2.0.2)
- deterministic route decisions per fragment

Missing elements are logged as system trace-completeness errors.
