# 05 - AssistantService Extraction Map

## Purpose

This document maps the current architectural overload of `assistantService.ts` and identifies what should stop living there over time.

The goal is not to empty the file arbitrarily.

The goal is to turn it from a god-service into a thinner coordinator.

## Current Situation

`assistantService.ts` is currently the largest and most overloaded module in the assistant runtime.

Approximate size:

- `6243` lines

It currently mixes concerns from:

- living route selection;
- follow-up carryover;
- continuation contracts;
- mode boundaries;
- meta-followup logic;
- memory recap detection;
- provider-aware predecompose orchestration;
- chat/data-scope/address boundary policy.

## Extraction Principle

`assistantService` should remain the top-level coordinator.

It should stop being the main owner of:

- policy logic;
- transition semantics;
- boundary semantics;
- meta semantics.

## Extraction Targets

### 1. Living Route Policy

Current owner:

- `resolveAssistantOrchestrationDecision()`

Current location:

- [assistantService.ts:4248](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:4248)

Target owner:

- `assistantRoutePolicyRuntimeAdapter`

Expected artifact:

- explicit living-route decision contract

Done when:

- route policy can be reviewed without reading the full coordinator;
- top-level mode decisions are data-driven or contract-driven enough to be testable as a separate unit.

### 2. Carryover And Transition Policy

Current owner:

- `resolveAddressFollowupCarryoverContext()`
- `buildAddressDialogContinuationContractV2()`

Current location:

- [assistantService.ts:2828](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:2828)
- [assistantService.ts:3111](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:3111)

Target owner:

- `assistantTransitionRuntimeAdapter`
- `assistantContinuationContractBuilder`

Expected artifact:

- explicit transition classes with state inputs and carryover depth

Done when:

- follow-up continuation is understood in terms of transitions, not just heuristic carryover.

### 3. Meta Follow-Up Policy

Current owner:

- meta and evaluative follow-up detection inside route decision logic

Target owner:

- `assistantMetaFollowupPolicy`

Expected artifact:

- meta question class registry
- legal source answer object types

Done when:

- meta questions no longer depend on implicit branches buried inside living route logic.

### 4. Data-Scope And Boundary Policy

Current owner:

- `assistant_data_scope_query_detected` branches

Current references:

- [assistantService.ts:3974](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:3974)
- [assistantService.ts:4412](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:4412)
- [assistantService.ts:6052](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:6052)

Target owner:

- `assistantBoundaryPolicy`

Expected artifact:

- explicit boundary mode contract:
  - `data_scope`
  - `operational_boundary`
  - `capability_contract`
  - `non_domain_chat`

Done when:

- emotional or colloquial user messages cannot accidentally trigger data-scope selection through hidden shared logic.

### 5. Memory Recap Policy

Current owner:

- route decision + living chat cooperation

Related consumer:

- [assistantLivingChatRuntimeAdapter.ts:255](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantLivingChatRuntimeAdapter.ts:255)

Target owner:

- `assistantMemoryRecapPolicy`

Expected artifact:

- truthful recap contract over grounded prior answer objects

Done when:

- memory recap logic becomes a named subsystem with its own truth rules.

### 6. Provider-Aware Orchestration Glue

Current owner:

- coordinator-level logic that adapts to `openai` vs `local`

Target owner:

- `assistantProviderExecutionPolicy`

Expected artifact:

- provider/runtime compatibility layer for orchestration expectations

Done when:

- provider quirks no longer leak into business routing logic.

## What Should Stay In AssistantService

After extraction, `assistantService` should still own:

- high-level request coordination;
- dependency wiring;
- stage invocation order;
- final turn assembly and persistence orchestration.

It should not be removed as an architectural object.

It should become thinner.

## Proposed Extraction Order

1. extract route decision contract
2. extract transition/carryover policy
3. extract boundary/data-scope policy
4. extract meta and memory recap policy
5. isolate provider-aware orchestration glue

This order is chosen because route and transition pressure are currently the main source of runtime fragility.

## Non-Goals

- do not split the file mechanically just to reduce line count;
- do not create many tiny helpers with no architectural ownership;
- do not move exact execution logic out of its proper lane.

## Done Criteria

This extraction plan is complete only when:

- the remaining `assistantService` can be described as a coordinator;
- major policy categories have explicit owners outside `assistantService`;
- scenario regressions can point to policy subsystems instead of a single god-service.