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:

• 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

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
• 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
• 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

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:

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