NODEDC_1C/docs/ARCH/11 - architecture_turnaround

11 - Architecture Turnaround Package

Purpose

This folder is the execution-oriented continuation of the baseline note:

• 11 - unified_project_architecture_and_reference_update_plan_2026-04-15.md

That baseline note answers:

• what the project is today;
• where the main architectural fragility sits;
• what direction is safe.

This package answers the next question:

• how the team should design the architectural turnaround without breaking the current exact-data baseline.

Package Contents

1. 01 - project_architecture_baseline_map.md
2. 02 - state_and_transition_contracts.md
3. 03 - capability_contract_spec.md
4. 04 - coverage_evidence_truth_gate.md
5. 05 - assistantService_extraction_map.md
6. 06 - phase_acceptance_matrix.md
7. 07 - external_reference_appendix.md
8. 08 - current_status_audit_2026-04-17.md
9. 09 - pre_expansion_cut_2026-04-17.md
10. 10 - regression_breakpoint_analysis_2026-04-17.md
11. 11 - continuity_stabilization_plan_2026-04-17.md

Current Status Snapshot (2026-04-17)

This package is no longer planning-only.

It now documents a turnaround that is already operational in code but still inside a pre-expansion stabilization breakpoint:

• route, transition, boundary, meta, memory, and provider policy owners exist as separate modules;
• exact-lane truth and coverage/evidence contracts exist as explicit runtime artifacts;
• scenario acceptance writes machine-readable scenario_acceptance_matrix.json and pack_state.json;
• AGENT semantic packs and source catalogs already exist for mixed domain/meta validation.

Current honest status:

• turnaround implementation progress: ~88%
• pre-expansion readiness: ~62%
• graph snapshot after latest rebuild: 5312 nodes, 11408 edges, 136 communities
• current breakpoint:
  • mixed saved-session runtime still fails on continuity-critical edges;
  • clarification can outrank restored business context;
  • recap and user-facing packaging can remain smoother than the actual grounded thread.
• main remaining architectural pressure:
  • no single authoritative continuity contract for live mixed sessions
  • residual coordinator/legacy pressure inside assistantService.ts
  • central domain-intent pressure inside resolveAddressIntent()
  • remaining answer-semantics pressure inside composeStage.ts

For the detailed audit, current percentages, and remaining debt, read:

• 08 - current_status_audit_2026-04-17.md
• 09 - pre_expansion_cut_2026-04-17.md
• 10 - regression_breakpoint_analysis_2026-04-17.md
• 11 - continuity_stabilization_plan_2026-04-17.md

Architectural Objects Of Planning

This package makes five objects explicit:

1. state model
2. transition model
3. capability contract model
4. coverage / evidence / truth gate
5. assistantService extraction plan

These are the objects that should now drive refactoring discussions.

How To Use The Package

Read in this order:

1. baseline note in docs/ARCH/11 - unified_project_architecture_and_reference_update_plan_2026-04-15.md
2. 01 - project_architecture_baseline_map.md
3. 02 - state_and_transition_contracts.md
4. 03 - capability_contract_spec.md
5. 04 - coverage_evidence_truth_gate.md
6. 05 - assistantService_extraction_map.md
7. 06 - phase_acceptance_matrix.md
8. 07 - external_reference_appendix.md
9. 08 - current_status_audit_2026-04-17.md
10. 09 - pre_expansion_cut_2026-04-17.md
11. 10 - regression_breakpoint_analysis_2026-04-17.md
12. 11 - continuity_stabilization_plan_2026-04-17.md

Planning Rules

• Do not treat this package as a rewrite plan.
• Do not dissolve AddressQueryService into generic chat logic.
• Do not move state back into transcript-only memory.
• Do not let answer wording substitute for policy/runtime fixes.
• Use scenario-based acceptance as the primary gate for all phases.

Expected Outcome

When this package is fully operational, the project should stop being described as:

• "a big custom assistant service with many heuristics"

and start being described as:

• "a stateful exact-data assistant with explicit transition contracts and isolated truth gating."

As of 2026-04-17, the project is already materially closer to the target description, but mixed-session continuity is still not governed by one runtime authority.

The biggest remaining blockers are:

• split continuity ownership across route / transition / recap / coordinator glue;
• clarification precedence still too strong in mixed sessions;
• residual assistantService overload;
• central intent pressure in resolveAddressIntent();
• remaining answer-semantics pressure in composeStage.ts.