NODEDC_1C/docs/TECH/ARCH_LAYER_FOUNDATION.md

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.