# 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:

- `5050` 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.
- debug and backend-error payload assembly.

## 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:3999](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:3999)

Target owner:

- `assistantRoutePolicy`

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:2927](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:2927)
- [assistantService.ts:2930](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:2930)

Target owner:

- `assistantTransitionPolicy`

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:4284](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:4284)
- [assistantService.ts:4977](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:4977)

Target owner:

- `assistantBoundaryPolicy`
- `assistantDataScopePolicy`

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.

## Honest Current Status (2026-04-17)

This extraction is materially underway and no longer just a proposal.

Current active owner creation and wiring in [assistantService.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantService.ts:4188):

- provider owner near `4188`
- meta and memory owners near `4201-4206`
- route owner near `4211`
- transition owner near `4250`
- data-scope owner near `4284`
- boundary owner near `4977`

What is already true:

- route, transition, boundary, meta, memory, and provider policies have explicit external owners;
- data-scope probing and organization-history extraction now also have an explicit owner;
- address/backend debug payload assembly now delegates into `assistantDebugPayloadAssembler`;
- runtime already delegates important decisions to those owners.

What is still not fully true:

- some legacy helper bodies still physically remain inside `assistantService.ts`
- the coordinator is still too large to be called thin
- some reviews still require reading both extracted owners and the coordinator to understand final behavior

This means Phase 5 is substantially advanced, but not finished.

## 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.