NODEDC_1C/docs/ARCH/11 - architecture_turnaround/05 - assistantService_extraction_map.md

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

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
• 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
• assistantService.ts:4412
• 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

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.