From 7be037e2252ce053958eccf7423dc4c840520a37 Mon Sep 17 00:00:00 2001 From: dctouch Date: Fri, 17 Apr 2026 14:20:27 +0300 Subject: [PATCH] =?UTF-8?q?=D0=90=D0=A0=D0=A7=20=D0=90=D0=9F11=20-=20?= =?UTF-8?q?=D0=90=D0=BA=D1=82=D1=83=D0=B0=D0=BB=D0=B8=D0=B7=D0=B8=D1=80?= =?UTF-8?q?=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC?= =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8E=20turnaround=2011=20?= =?UTF-8?q?=D0=BF=D0=BE=20=D1=82=D0=B5=D0=BA=D1=83=D1=89=D0=B5=D0=BC=D1=83?= =?UTF-8?q?=20=D0=B0=D1=80=D1=85=D0=B8=D1=82=D0=B5=D0=BA=D1=82=D1=83=D1=80?= =?UTF-8?q?=D0=BD=D0=BE=D0=BC=D1=83=20=D0=B0=D1=83=D0=B4=D0=B8=D1=82=D1=83?= =?UTF-8?q?=20=D0=B8=20graphify?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../04 - coverage_evidence_truth_gate.md | 43 ++- .../05 - assistantService_extraction_map.md | 32 +- .../06 - phase_acceptance_matrix.md | 33 ++ .../08 - current_status_audit_2026-04-17.md | 300 ++++++++++++++++++ .../11 - architecture_turnaround/README.md | 34 ++ 5 files changed, 431 insertions(+), 11 deletions(-) create mode 100644 docs/ARCH/11 - architecture_turnaround/08 - current_status_audit_2026-04-17.md diff --git a/docs/ARCH/11 - architecture_turnaround/04 - coverage_evidence_truth_gate.md b/docs/ARCH/11 - architecture_turnaround/04 - coverage_evidence_truth_gate.md index f5e92da..2b1e69c 100644 --- a/docs/ARCH/11 - architecture_turnaround/04 - coverage_evidence_truth_gate.md +++ b/docs/ARCH/11 - architecture_turnaround/04 - coverage_evidence_truth_gate.md @@ -32,15 +32,28 @@ Answer policy must not own the truth gate. ## Current Code Owners -The gate already exists in code in fragmented form: +The gate is no longer only a fragmented idea. -- [assistantCoverageGrounding.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantCoverageGrounding.ts:1) -- [assistantClaimBoundEvidence.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantClaimBoundEvidence.ts:1) -- [assistantDataLayer.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantDataLayer.ts:622) -- [addressQueryService.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressQueryService.ts:2806) -- [answerComposer.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/answerComposer.ts:22) +The current explicit owners are: -The architectural problem is not absence, but insufficient naming and isolation. +- [addressTruthGatePolicy.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressTruthGatePolicy.ts:1) +- [addressCoverageEvidencePolicy.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressCoverageEvidencePolicy.ts:1) +- [assistantRuntimeContractResolver.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantRuntimeContractResolver.ts:256) +- [assistantTruthAnswerPolicyRuntimeAdapter.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/assistantTruthAnswerPolicyRuntimeAdapter.ts:127) + +These contracts are currently named: + +- `address_truth_gate_v1` +- `address_coverage_evidence_v1` + +Residual gate-related pressure still exists in: + +- [addressQueryService.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/addressQueryService.ts:3082) +- [composeStage.ts](/x:/1C/NDC_1C/llm_normalizer/backend/src/services/address_runtime/composeStage.ts:2684) + +The current architectural problem is no longer absence. + +It is incomplete end-to-end isolation of truth semantics from final answer shaping. ## Gate Inputs @@ -194,3 +207,19 @@ This layer is considered architecturally established only when: - its outputs are explicit inputs to answer shaping; - carryover policy depends on gate output rather than hidden heuristics; - scenario acceptance can fail specifically on gate behavior, not only on final wording. + +## Honest Current Status (2026-04-17) + +This layer is `mostly established`, but not complete. + +What is already true: + +- exact-lane truth and coverage/evidence contracts are explicit and machine-readable; +- runtime adapters consume those contracts directly; +- scenario acceptance can already fail on truth/coverage invariants. + +What is still not fully true: + +- user-facing blocked/limited semantics are still partly coupled to final packaging branches; +- `composeFactualReply()` still carries too much architectural weight; +- not every business contour is equally mature in explicit truth/coverage signaling. diff --git a/docs/ARCH/11 - architecture_turnaround/05 - assistantService_extraction_map.md b/docs/ARCH/11 - architecture_turnaround/05 - assistantService_extraction_map.md index f098c4d..203391c 100644 --- a/docs/ARCH/11 - architecture_turnaround/05 - assistantService_extraction_map.md +++ b/docs/ARCH/11 - architecture_turnaround/05 - assistantService_extraction_map.md @@ -14,7 +14,7 @@ The goal is to turn it from a god-service into a thinner coordinator. Approximate size: -- `6243` lines +- `5770` lines It currently mixes concerns from: @@ -52,7 +52,7 @@ Current location: Target owner: -- `assistantRoutePolicyRuntimeAdapter` +- `assistantRoutePolicy` Expected artifact: @@ -77,8 +77,7 @@ Current location: Target owner: -- `assistantTransitionRuntimeAdapter` -- `assistantContinuationContractBuilder` +- `assistantTransitionPolicy` Expected artifact: @@ -198,6 +197,31 @@ It should become thinner. 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:4725): + +- provider owner near `4725` +- meta and memory owners near `4738-4743` +- route owner near `4748` +- transition owner near `4785` +- boundary owner near `5439` + +What is already true: + +- route, transition, boundary, meta, memory, and provider policies have explicit external owners; +- runtime already delegates important decisions to those owners. + +What is still not fully true: + +- 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; diff --git a/docs/ARCH/11 - architecture_turnaround/06 - phase_acceptance_matrix.md b/docs/ARCH/11 - architecture_turnaround/06 - phase_acceptance_matrix.md index c0ea46f..a56b76e 100644 --- a/docs/ARCH/11 - architecture_turnaround/06 - phase_acceptance_matrix.md +++ b/docs/ARCH/11 - architecture_turnaround/06 - phase_acceptance_matrix.md @@ -12,6 +12,39 @@ Each phase must specify: - `non-goals` - `acceptance signals` +## Current Execution Snapshot (2026-04-17) + +Current honest estimate of overall turnaround completion: `~85%` + +Current phase status: + +- `Phase 0` - `100%` +- `Phase 1` - `100%` +- `Phase 2` - `92%` +- `Phase 3` - `86%` +- `Phase 4` - `84%` +- `Phase 5` - `76%` +- `Phase 6` - `80%` +- `Phase 7` - `90%` + +This estimate is supported by: + +- graph snapshot: `5228 nodes`, `11338 edges`, `133 communities` +- explicit truth/coverage contracts in code +- extracted policy owners in code +- machine-readable scenario acceptance artifacts +- mixed AGENT semantic source catalogs and accepted packs + +Main remaining blockers: + +- `assistantService.ts` is still too large +- `resolveAddressIntent()` remains a high-pressure god node +- `composeFactualReply()` remains a high-pressure god node + +For the full audit, see: + +- [08 - current_status_audit_2026-04-17.md](./08%20-%20current_status_audit_2026-04-17.md) + ## Phase 0. Shared Baseline Goal: diff --git a/docs/ARCH/11 - architecture_turnaround/08 - current_status_audit_2026-04-17.md b/docs/ARCH/11 - architecture_turnaround/08 - current_status_audit_2026-04-17.md new file mode 100644 index 0000000..8522a8b --- /dev/null +++ b/docs/ARCH/11 - architecture_turnaround/08 - current_status_audit_2026-04-17.md @@ -0,0 +1,300 @@ +# 08 - Current Status Audit (2026-04-17) + +## Purpose + +This note is the honest execution snapshot for the turnaround package after the latest architecture passes, graph rebuild, and semantic acceptance work. + +It is not a replacement for the phase documents. + +It is the current-state audit that answers: + +- what is already real in code; +- what still remains architectural debt; +- how far the turnaround has actually progressed. + +## Audit Basis + +This snapshot is based on: + +- `graphify-out/GRAPH_REPORT.md` rebuilt on `2026-04-17` +- current owner modules in `llm_normalizer/backend/src/services/` +- current scenario acceptance scripts under `scripts/` +- current AGENT semantic source catalog under `docs/orchestration/` + +## Graph Snapshot + +Latest graph rebuild: + +- `5228 nodes` +- `11338 edges` +- `133 communities` + +Most relevant current god nodes for turnaround `11`: + +1. `resolveAddressIntent()` +2. `ChannelRegistry` +3. `composeFactualReply()` +4. `CanonicalStore` +5. `compactWhitespace()` + +The relevant conclusion is not that every god node is part of turnaround `11`. + +The relevant conclusion is: + +- `resolveAddressIntent()` remains the main unresolved domain-intent concentration point; +- `composeFactualReply()` remains the main unresolved answer-shaping concentration point; +- `assistantService` still appears as a large coordinator-heavy community rather than a thin shell. + +## What Is Already Real In Code + +### 1. Policy owners are no longer hypothetical + +The following owner modules exist and are live architectural objects: + +- `assistantRoutePolicy.ts` +- `assistantTransitionPolicy.ts` +- `assistantBoundaryPolicy.ts` +- `assistantMetaFollowupPolicy.ts` +- `assistantMemoryRecapPolicy.ts` +- `assistantProviderExecutionPolicy.ts` + +`assistantService.ts` wires these owners in active runtime paths around: + +- provider policy creation near line `4725` +- route/meta/memory policy creation near lines `4738-4783` +- transition policy creation near line `4785` +- boundary policy creation near line `5439` + +### 2. Truth and coverage/evidence are explicit contracts + +The exact lane now exposes explicit machine-readable contracts: + +- `address_truth_gate_v1` +- `address_coverage_evidence_v1` + +Primary current owners: + +- `addressTruthGatePolicy.ts` +- `addressCoverageEvidencePolicy.ts` +- `assistantRuntimeContractResolver.ts` +- `assistantTruthAnswerPolicyRuntimeAdapter.ts` + +This means exact-lane answers are no longer judged only by final text or hidden heuristics. + +### 3. Scenario acceptance is now a real gate artifact + +The truth harness now writes: + +- `scenario_acceptance_matrix.json` +- `scenario_acceptance_matrix.md` +- `pack_state.json` +- `final_status.md` + +Primary current owners: + +- `domain_truth_harness.py` +- `scenario_acceptance_policy.py` + +This is the main reason the project is no longer relying on unit tests alone for architecture verification. + +### 4. Mixed AGENT semantic source material already exists + +Current source catalog snapshot: + +- `truth_harness_steps_total = 58` +- `saved_session_questions_total = 81` + +The source catalog already covers mixed reusable tags such as: + +- `inventory_root` +- `selected_object` +- `selected_object_supplier` +- `counterparty_documents` +- `counterparty_shipment_fallback` +- `settlements_account_60` +- `settlements_receivables` +- `vat` +- `meta_smalltalk` +- `meta_scope` +- `meta_capability` +- `meta_historical_capability` +- `meta_memory` +- `same_date_pivot` +- `same_date_restore` + +This is enough to build targeted semantic packs that are not single-domain toy scripts. + +## Honest Phase Status + +Estimated overall turnaround completion: `~85%` + +### Phase 0. Shared Baseline + +Status: `100%` + +Reason: + +- architecture vocabulary is stable; +- planning discussions already use the package and current owner names. + +### Phase 1. Formal Layer Separation + +Status: `100%` + +Reason: + +- subsystem boundaries are explicit enough in planning and in code ownership; +- `canonical_layer`, `llm_normalizer/backend`, and domain loop/orchestration assets are no longer treated as one blob. + +### Phase 2. State And Transition Contracts + +Status: `92%` + +Reason: + +- root, selected-object, same-date, and carryover classes are materially operational; +- transition policy is extracted; +- scenario acceptance now evaluates continuity explicitly. + +Remaining debt: + +- legacy transition helpers still physically exist inside `assistantService.ts`; +- not every follow-up family is represented as equally clean first-class transition taxonomy. + +### Phase 3. Capability Contracts + +Status: `86%` + +Reason: + +- critical inventory/address capabilities are materially contract-driven; +- selected-object and root capability behavior is much more explicit than before. + +Remaining debt: + +- `resolveAddressIntent()` is still too central; +- some business contours outside the most exercised inventory/address scenarios remain less explicit. + +### Phase 4. Coverage / Evidence / Truth Gate Isolation + +Status: `84%` + +Reason: + +- explicit truth and coverage/evidence contracts exist; +- answer policy reads those contracts rather than rebuilding verdicts blindly from raw rows. + +Remaining debt: + +- `composeFactualReply()` is still a major concentration point; +- humanized blocked/limited semantics are not yet fully separated from final packaging logic across all paths. + +### Phase 5. AssistantService Extraction + +Status: `76%` + +Reason: + +- major policy categories have real owners outside the coordinator. + +Remaining debt: + +- `assistantService.ts` is still about `5770` lines; +- runtime uses extracted owners, but legacy bodies and fallback branches still live in the coordinator file; +- code review still sometimes requires reading `assistantService` together with extracted owners. + +### Phase 6. Provider / Runtime Axis Hardening + +Status: `80%` + +Reason: + +- provider/runtime behavior is now an explicit policy concern; +- local/openai semantics are materially less entangled with business routing. + +Remaining debt: + +- compatibility is stronger than before, but not yet the final universal execution contract for every contour and acceptance pack. + +### Phase 7. Scenario Acceptance As Primary Gate + +Status: `90%` + +Reason: + +- acceptance writes first-class artifacts; +- AGENT source catalog and mixed packs exist; +- meta-space, domain-space, and cross-domain interruptions are already represented. + +Remaining debt: + +- semantic replay remains intentionally tool-driven and script-driven rather than promoted to a mandatory UI-first loop; +- coverage breadth should continue to grow as new domain slices are hardened. + +## What Has Improved Relative To The Original State + +Compared with the pre-turnaround baseline, the system is now materially better in the following ways: + +- long mixed conversations are more stable; +- selected-object continuity is no longer treated as optional polish; +- temporal honesty is now evaluated as an explicit invariant; +- factual-negative answers can remain truthful instead of collapsing into generic technical refusals; +- meta questions and memory recap are no longer purely incidental side effects of route logic; +- architecture regressions can now be localized to route, transition, truth gate, coverage/evidence, boundary, or meta/memory layers. + +## What Still Remains The Main Architectural Debt + +### 1. `assistantService.ts` is still too large + +The extracted owners are real, but the coordinator has not yet been fully reduced to a thin orchestration shell. + +### 2. `resolveAddressIntent()` is still too central + +Intent resolution remains one of the most connected business nodes in the graph. + +This means capability and contour growth still concentrate pressure there. + +### 3. `composeFactualReply()` is still too central + +Truth contracts are now explicit, but final answer-shaping still retains too much architecture weight. + +This is the main remaining reason why user-facing humanization and limitation semantics are not completely isolated yet. + +### 4. Coverage breadth is stronger, but still selective + +The project is now strong on: + +- inventory root +- selected-object provenance/documents +- counterparty document and shipment-fallback cases +- key settlement and VAT follow-ups +- meta/memory/context integrity + +But not every business family has reached the same contract maturity. + +## Recommended Next Work + +The next honest architecture slice should be: + +1. continue reducing `assistantService.ts` to a thinner coordinator; +2. isolate answer-shaping semantics further away from `composeFactualReply()`; +3. keep extending AGENT packs with mixed business + meta + interruption patterns instead of single-family smoke tests; +4. keep using scenario acceptance as the main sign-off rather than unit-test green status alone. + +## Bottom Line + +Turnaround `11` is no longer a proposal. + +It is an operational architecture program that is already mostly implemented in the critical path. + +The current state is best described as: + +- `architecturally real` +- `operationally useful` +- `not yet fully cleaned up` + +The remaining work is now mostly about: + +- removing residual concentration points; +- tightening the last humanized answer-policy seams; +- and broadening acceptance coverage without regressing the hard-won exact-data behavior. diff --git a/docs/ARCH/11 - architecture_turnaround/README.md b/docs/ARCH/11 - architecture_turnaround/README.md index 1468660..82699fa 100644 --- a/docs/ARCH/11 - architecture_turnaround/README.md +++ b/docs/ARCH/11 - architecture_turnaround/README.md @@ -25,6 +25,31 @@ This package answers the next question: 5. [05 - assistantService_extraction_map.md](./05%20-%20assistantService_extraction_map.md) 6. [06 - phase_acceptance_matrix.md](./06%20-%20phase_acceptance_matrix.md) 7. [07 - external_reference_appendix.md](./07%20-%20external_reference_appendix.md) +8. [08 - current_status_audit_2026-04-17.md](./08%20-%20current_status_audit_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 partially operational in code: + +- 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: + +- estimated overall completion: `~85%` +- graph snapshot after latest rebuild: `5228 nodes`, `11338 edges`, `133 communities` +- main remaining architectural pressure: + - `resolveAddressIntent()` + - `composeFactualReply()` + - residual coordinator/legacy pressure inside `assistantService.ts` + +For the detailed audit, current percentages, and remaining debt, read: + +- [08 - current_status_audit_2026-04-17.md](./08%20-%20current_status_audit_2026-04-17.md) ## Architectural Objects Of Planning @@ -50,6 +75,7 @@ Read in this order: 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` ## Planning Rules @@ -68,3 +94,11 @@ When this package is fully operational, the project should stop being described 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 not fully there yet. + +The biggest remaining blockers are: + +- residual `assistantService` overload; +- central answer-shaping pressure in `composeFactualReply()`; +- central intent pressure in `resolveAddressIntent()`.