АРЧ АП11 - Актуализировать документацию turnaround 11 по текущему архитектурному аудиту и graphify
This commit is contained in:
parent
6223062b37
commit
7be037e225
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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()`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue