104 lines
3.3 KiB
Markdown
104 lines
3.3 KiB
Markdown
# 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)
|
|
|
|
## 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.
|