# ARCH Layer Foundation (Safe Multi-Layer Evolution)

## Purpose

This foundation prepares the assistant runtime for independent evolution of:

1. `compute` layer (deterministic financial routes),
2. `navigation` layer (result-set and drilldown state),
3. `conversational` layer (language, formatting, clarification UX).

The goal is to make fixes in one layer without accidental regressions in the others.

## Implemented Building Blocks

### 1) Capability Route Policy (`compute` boundary)

Files:

- `llm_normalizer/backend/src/services/addressCapabilityPolicy.ts`
- `llm_normalizer/backend/src/config.ts` (new per-capability flags)
- `llm_normalizer/backend/src/services/addressQueryService.ts` (guard integration)

What it gives:

- explicit capability identity per intent (`capability_id`),
- explicit layer classification (`compute` / `navigation` / `conversational`),
- route-mode marker (`exact` / `heuristic`),
- hard guard by feature flags (route can be disabled safely),
- shadow-route planning hook for controlled rollout.

### 2) Address Navigation State (`navigation` boundary)

Files:

- `llm_normalizer/backend/src/types/addressNavigation.ts`
- `llm_normalizer/backend/src/services/addressNavigationState.ts`
- `llm_normalizer/backend/src/services/assistantSessionStore.ts`
- `llm_normalizer/backend/src/services/assistantSessionLogger.ts`

What it gives:

- first-class `session_context` with:
  - `active_result_set_id`,
  - `active_focus_object`,
  - `last_confirmed_route`,
  - date/org scope carryover,
- persisted `result_sets` with entity refs parsed from assistant lists,
- persisted `navigation_history` (`open` / `drilldown` / `refine`),
- backward-compatible session normalization.

### 3) Runtime Traceability (`cross-layer safety`)

Files:

- `llm_normalizer/backend/src/types/addressQuery.ts`
- `llm_normalizer/backend/src/types/assistant.ts`
- `llm_normalizer/backend/src/services/addressQueryService.ts`
- `llm_normalizer/backend/src/services/assistantService.ts`

What it gives in debug payload:

- `capability_id`,
- `capability_layer`,
- `capability_route_mode`,
- `capability_route_enabled`,
- `capability_route_reason`,
- `shadow_route_intent`,
- `shadow_route_selected_recipe`,
- `shadow_route_status`.

This makes route regressions observable and testable.

## Guard-Rail Flags

New flags in `config.ts`:

- `FEATURE_ASSISTANT_ADDRESS_NAVIGATION_STATE_V1`
- `FEATURE_ASSISTANT_CAPABILITY_ROUTE_GUARD_V1`
- `FEATURE_ASSISTANT_ROUTE_ADDRESS_GENERIC_V1`
- `FEATURE_ASSISTANT_ROUTE_DRILLDOWN_V1`
- `FEATURE_ASSISTANT_ROUTE_BALANCE_EXACT_V1`
- `FEATURE_ASSISTANT_ROUTE_PAYABLES_CONFIRMED_V1`
- `FEATURE_ASSISTANT_ROUTE_PAYABLES_HEURISTIC_V1`
- `FEATURE_ASSISTANT_ROUTE_RECEIVABLES_HEURISTIC_V1`
- `FEATURE_ASSISTANT_ROUTE_SHADOW_PAYABLES_EXACT_V1`

## Validation Coverage Added

Tests:

- `llm_normalizer/backend/tests/addressCapabilityPolicy.test.ts`
- `llm_normalizer/backend/tests/addressNavigationState.test.ts`
- `llm_normalizer/backend/tests/sessionBackwardCompat.test.ts` (extended)
- `llm_normalizer/backend/tests/addressRouteBaseline.test.ts`

Route baseline contract:

- `docs/TECH/address_route_baseline_v1.json`
- loader: `llm_normalizer/backend/src/services/addressRouteBaseline.ts`

This baseline freezes capability mapping for key intents and acts as anti-regression control when routing evolves.

Route expectation contract (level 2):

- `docs/TECH/address_route_expectations_v1.json`
- loader/evaluator: `llm_normalizer/backend/src/services/addressRouteExpectations.ts`

This second-level baseline freezes expected `intent -> selected_recipe/result_mode` semantics and provides runtime audit with optional hard guard.

## Why This Is a Foundation, Not a Patch

This change does not only tune one scenario. It introduces stable contracts:

- capability contracts for compute routing,
- persistent navigation model for multi-step dialog chains,
- explicit debug semantics to separate route decisions from answer wording.

This is the base for parallel development across layers with lower regression risk.