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
12. 12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md
13. 13 - pre_multidomain_readiness_audit_2026-04-18.md
14. 14 - semantic_dialog_authority_recovery_plan_2026-04-19.md
15. 15 - mcp_bounded_autonomy_reset_plan_2026-04-21.md
16. 16 - data_need_graph_and_open_world_mcp_plan_2026-04-22.md
17. 17 - post_f_semantic_integrity_hardening_2026-04-23.md
18. 18 - post_f_code_documentation_sync_2026-04-24.md
19. 19 - inventory_stock_open_world_breadth_proof_2026-05-01.md
20. 20 - planner_autonomy_consolidation_2026-05-01.md

Current Status Snapshot (2026-05-01)

This package is no longer planning-only.

It now documents a turnaround that is already operational in code, already materially past the acute regression breakpoint, and already moved through the bounded MCP autonomy build-out into the next semantic hardening layer:

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

• the reset toward MCP-first bounded autonomy is now formalized;

• Big Block A/B/C of that reset are now closed in runtime code and replay-backed;

• Big Block D/E/F are now also materially closed in runtime code and replay-backed:

  • Question -> Data Need Graph
  • dynamic schema traversal and primitive search
  • multi-hop evidence loop with bounded clarification recovery

• the current architecture mainline is now Post-F Semantic Integrity Hardening:

  • protect grounded subject integrity against stale scope contamination
  • protect exact and planner-selected pivots from metadata/discovery drift
  • keep temporal continuity and repeated lane switches semantically stable
  • recover already-supported questions that still look broken to a human user

• the Post-F module is now operationally closed as a hardening slice:

  • code fix commit: 739e8b8 Post-F: закрыть ручные провалы НДС, выручки и item-flow
  • runtime artifact tail commit: 837e1fe Post-F: сохранить хвосты ручных runtime-прогонов
  • live map sync: 18 - post_f_code_documentation_sync_2026-04-24.md

• the next bounded breadth slice is now replay-backed under Post-F gates:

  • inventory stock/provenance/sale-trace pack: inventory_stock_open_world_breadth_rerun_semantic_integrity_20260501_fix5, accepted
  • live map sync: 19 - inventory_stock_open_world_breadth_proof_2026-05-01.md

• Planner Autonomy Consolidation has started:

  • MCP catalog now carries reusable chain templates in addition to primitive contracts;
  • planner route-fabric selection has started moving from local recipe branches toward catalog-instantiated chains;
  • value-flow, value-flow comparison, value-flow ranking, lifecycle, metadata, movement, document, and entity fallback branches now expose catalog-template instantiation reason codes in planner output;
  • explicit document/movement data-need now scores over ambiguous carried metadata surfaces without forcing neutral follow-ups into a lane;
  • live map sync: 20 - planner_autonomy_consolidation_2026-05-01.md

Current honest status:

• turnaround implementation progress: ~99%
• exit-from-danger-zone readiness: ~97%
• pre-multidomain readiness: ~90%
• bounded-autonomy foundation readiness: ~89%
• open-world bounded-autonomy readiness: ~82%
• Post-F semantic integrity module progress: ~99% operationally closed, with remaining risk now treated as next-slice discovery rather than an open blocker inside the closed slice
• active inventory-stock breadth slice progress: 100% for the declared scenario pack, not for arbitrary inventory questions
• graph snapshot after latest rebuild: 5911 nodes, 12830 edges, 138 communities
• current breakpoint:
  • the validated hot paths are no longer structurally broken;
  • flagship continuity collapse is no longer the primary risk;
  • the main remaining risk is no longer "A/B/C or D/E/F do not exist", but "already-supported semantic chains can still be contaminated by stale scope, legacy focus state, or wrong post-pivot arbitration";
  • pure wording polish remains secondary debt, but semantic integrity and explicit-subject protection are now first-class blockers;
  • the practical product risk is no longer only "the route collapsed", but "the user can still occasionally see a semantically wrong answer on a question that the architecture should already support".
• main remaining architectural pressure:
  • open-world breadth is still narrower than the intended arbitrary 1C blast radius
  • planner-selected chains are now real, but still not broad enough to cover unfamiliar 1C asks without additional primitive/search growth
  • semantic integrity can still fail on stale carryover, repeated pivots, and mixed scope contamination if those seams are not replay-hardened
  • central domain-intent pressure inside resolveAddressIntent()
  • replay breadth is still below the future open-world autonomy surface

Latest live proof now includes:

• address_truth_harness_phase24_metadata_lane_choice_loop_live_rerun14 accepted
• address_truth_harness_phase32_planner_selected_chain_end_to_end_live_rerun2 accepted 6/6
• address_truth_harness_phase42_catalog_metadata_drilldown_live_rerun2 accepted
• address_truth_harness_phase45_multi_hop_open_total_clarification_loop_live_rerun2 accepted
• address_truth_harness_phase67_svk_grounded_counterparty_integrity_live_rerun_vatfix accepted
• address_truth_harness_phase68_referential_document_followup_integrity_live_rerun1 accepted
• address_truth_harness_phase69_document_to_payments_pronoun_pivot_live_rerun3 accepted
• address_truth_harness_phase72_document_to_contracts_year_switch_live_rerun3 accepted
• address_truth_harness_phase80_payments_to_contracts_to_documents_all_time_live_rerun1 accepted
• address_truth_harness_phase82_human_mixed_integrity_status_dialog_post_m23_rerun_documents_scope_bidirectional accepted 19/19
• address_truth_harness_phase82_human_mixed_integrity_status_dialog_post_f_account_injection_guard_clean_scope accepted 19/19, with the Жуковке 51 numeric counterparty suffix kept as counterparty scope instead of leaking as account 51
• address_truth_harness_post_f_cross_stage_canary_agent_20260424_live7 accepted 24/24, proving a saved cross-stage AGENT canary across VAT metadata, metadata-scoped organization/document pivots, numeric counterparty suffixes, open-organization value-flow clarification, ranked value-flow year switches, and SVK grounded reset; the saved autorun is AGENT | Post-F cross-stage semantic integrity canary (gen-ag04241406-abe4d8)
• address_truth_harness_post_f_manual_failures_20260424_live3 accepted 11/11, proving the manual failure slice from assistant-stage1-9liEOh-7JP: VAT purchase-date, VAT February 2017, highest-value customer, and Chepurnov item-flow after stale inventory context; the saved autorun is AGENT | Post-F ручные провалы VAT revenue item-flow live3 (gen-ag04241710-bdb248)
• address_truth_harness_phase11_manual_followup_meta_quality_live_rerun_vatfix accepted 10/10
• address_truth_harness_phase20_continuity_stabilization_live_rerun_vatfix accepted 6/6
• addressQueryRuntimeM23.test.ts full semantic/runtime slice accepted 403/403 after Post-F VAT/date-basis, scope-recovery, open value-flow organization clarification, document-vs-bank arbitration, and reply-shape hardening
• inventory_stock_open_world_breadth_rerun_semantic_integrity_20260501_fix5 accepted all declared inventory stock scenarios: root snapshots, selected-item supplier provenance, supplier overlap, stock aging/unresolved supplier-link, sale trace, and purchase-to-sale chain
• address_truth_harness_phase66_human_org_open_scope_dialog_planner_template_rerun2 accepted 7/7, proving catalog-instantiated value-flow still preserves open-organization clarification, year switches, and guarded candidate arbitration
• address_truth_harness_phase52_metadata_movement_full_recovery_planner_metadata_scoring_rerun2 accepted 4/4, proving metadata-born movement continuation keeps lane choice, organization, and period recovery intact
• address_truth_harness_phase54_metadata_document_full_recovery_planner_metadata_scoring_rerun2 accepted 4/4, proving metadata-born document continuation keeps lane choice, organization, and period recovery intact
• MCP planner/catalog consolidation slice accepted locally: assistantMcpCatalogIndex.test.ts + assistantMcpDiscoveryPlanner.test.ts passed 47/47, full MCP-discovery slice passed 227/227 with 9 skipped

Current architectural reading:

• the system is already materially past the dangerous regression breakpoint;
• it is now safe for continued architecture hardening and controlled domain-by-domain enablement under replay gates;
• it is materially closer to pre-multidomain stability, but still not safe to declare broad low-risk expansion over arbitrary unfamiliar 1C questions.
• the practical next target is no longer Post-F rescue itself; it is broader open-world bounded autonomy over 1C evidence while preserving the Post-F semantic-integrity invariants as regression gates.
• from this point onward, readiness must be judged not only by route truth and replay pass rate, but also by whether already-supported questions stay semantically correct through stale memory, pivots, clarifications, and mixed scope resets.

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
• 12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md
• 13 - pre_multidomain_readiness_audit_2026-04-18.md
• 14 - semantic_dialog_authority_recovery_plan_2026-04-19.md
• 15 - mcp_bounded_autonomy_reset_plan_2026-04-21.md
• 16 - data_need_graph_and_open_world_mcp_plan_2026-04-22.md
• 17 - post_f_semantic_integrity_hardening_2026-04-23.md
• 19 - inventory_stock_open_world_breadth_proof_2026-05-01.md
• 20 - planner_autonomy_consolidation_2026-05-01.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
13. 12 - manual_run_system_analysis_3NilqwT1G2_2026-04-18.md
14. 13 - pre_multidomain_readiness_audit_2026-04-18.md
15. 14 - semantic_dialog_authority_recovery_plan_2026-04-19.md
16. 15 - mcp_bounded_autonomy_reset_plan_2026-04-21.md
17. 16 - data_need_graph_and_open_world_mcp_plan_2026-04-22.md
18. 17 - post_f_semantic_integrity_hardening_2026-04-23.md
19. 18 - post_f_code_documentation_sync_2026-04-24.md
20. 19 - inventory_stock_open_world_breadth_proof_2026-05-01.md
21. 20 - planner_autonomy_consolidation_2026-05-01.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-24, the project is already materially closer to the target description and is no longer in the same acute collapse state. The remaining blocker is no longer the original continuity failure itself, no longer the A/B/C or D/E/F build-out, and no longer the first Post-F rescue slice. The active blocker is now the combination of:

• unfinished convergence from reviewed bounded MCP chains toward broader open-world autonomy;
• continued use of Post-F semantic integrity invariants as regression gates while that breadth grows.

The biggest remaining blockers are:

• broader open-world primitive search is still narrower than the future arbitrary 1C blast radius;
• dynamic schema traversal is still not broad enough for many unfamiliar 1C asks outside the repaired families;
• new stale-scope or post-pivot seams may still appear in future breadth work and must be treated as regression-gated semantic defects, not as wording polish;
• residual assistantService overload;
• central intent pressure in resolveAddressIntent();
• semantic robustness gaps may still appear where already-supported questions meet new wording, typo pressure, short follow-up retargets, or human-answer mismatch.