NODEDC_1C/docs/ARCH/11 - architecture_turnaround/09 - pre_expansion_cut_2026-04-17.md

09 - Pre-Expansion Cut (2026-04-17)

Purpose

This note freezes the practical cutoff for turnaround 11 before mass domain expansion.

The goal is not architectural perfection.

The goal is to separate:

• what must be closed before large-scale domain growth;
• what can be consciously deferred without putting expansion quality at risk.

Current Read

As of 2026-04-17, the architecture is no longer in the "foundations are unstable" state.

The system already has:

• extracted route / transition / boundary / meta / memory owners;
• explicit truth and coverage/evidence contracts;
• scenario acceptance artifacts;
• live AGENT semantic replay practice;
• materially stronger selected-object and temporal continuity than in the baseline state.

The remaining problem is different now:

• the project is in a hybrid extracted state;
• quality risk is concentrated in a small number of central pressure points;
• these pressure points will amplify regressions once many new domains are added.

Must Close Before Mass Domain Expansion

1. One continuity authority for live mixed sessions

Why it matters:

• the same capability family can pass in a narrow scenario and fail in a nearby mixed scenario;
• current runtime continuity is still split across route policy, transition policy, memory recap policy, navigation state, and coordinator glue;
• domain expansion on top of split continuity ownership will multiply regressions faster than route extraction can contain them.

What "done enough" means:

• one governing session continuity contract resolves active root frame, selected object, organization scope, date scope, clarification state, and recap source;
• route, recap, and clarification decisions read the same continuity object instead of reconstructing state independently;
• selected-object, same-date, and cross-domain root pivots stop drifting across different owners.

Current status:

• the underlying contract vocabulary already exists across runtime contract registries and state-transition adapters;
• owner modules are real, but continuity state is still not yet governed from one place.

2. Clarification precedence must stop outranking continuity

Why it matters:

• current regressions often appear as repeated company clarification even after a nearby business answer already succeeded;
• this is not a pure intent failure, it is clarification winning too often when continuity confidence was lost;
• if this precedence remains unstable, new domains will feel scripted even when the route exists.

What "done enough" means:

• clarification becomes the last meaningful step, not the default escape hatch;
• restored business continuity outranks template clarification whenever the active frame is sufficient;
• repeated clarification no longer breaks selected-object or same-date follow-ups.

Current status:

• company clarification already has explicit owner seams;
• mixed live replay still shows clarification outranking restored business context.

3. Intent concentration in resolveAddressIntent()

Why it matters:

• this is still the main domain-intent concentration point in the graph;
• new domain slices will increase route collisions and accidental cross-triggering;
• follow-up-heavy contours will become harder to reason about if raw signal families stay mixed in one resolver body.

What "done enough" means:

• the most stressed signal families are delegated to dedicated owners;
• inventory, counterparty/documents, and high-risk settlement families are no longer all encoded inline in one body;
• targeted regression packs exist for each extracted family.

Current status:

• inventory signal-family is now delegated to addressInventoryIntentSignals.ts;
• counterparty / documents / contracts / open-items signal-family is now also delegated to addressCounterpartyIntentSignals.ts;
• the central resolver now delegates these hot families through owner modules instead of carrying them only as inline branches.

4. Answer semantics pressure in composeFactualReplyBody()

Why it matters:

• this still controls too much user-facing behavior;
• technical leakage, limitation phrasing, and answer-shape instability can spread into new domains quickly;
• every new domain added on top of a still-heavy compose body increases presentation inconsistency risk.

What "done enough" means:

• the hottest answer families are routed through dedicated builders/presentation owners;
• blocked / limited / humanized fallback semantics are explicit for the most important contours;
• user-facing replies no longer expose internal route/capability/debug jargon on critical business paths.

Current status:

• inventory factual replies already live in address_runtime/inventoryReplyBuilders.ts;
• counterparty analytics / lifecycle / value / contract-value factual replies now also live in address_runtime/counterpartyAnalyticsReplyBuilders.ts;
• composeStage.ts is materially smaller than before, but blocked / limited semantics still need one more hardening pass on the hottest contours.

5. Business-first quality guard on hot contours

Why it matters:

• mass expansion will multiply edge cases faster than humans can manually spot them;
• if hot contours still leak technical junk or weak follow-up logic, the problem will scale with every new domain.

What "done enough" means:

• AGENT semantic runs continue to validate mixed business chains;
• core hot contours are checked for direct-answer usefulness, selected-object continuity, temporal honesty, and no technical leakage;
• enablement gaps are treated as contour-extension work, not dismissed as "unsupported".

Can Be Deferred After Expansion Starts

1. Full assistantService.ts beautification

This still matters, but it is no longer the primary pre-expansion blocker.

As long as runtime-critical policy ownership is already externalized, some coordinator-local legacy bodies can remain temporarily.

2. Full elimination of every residual helper duplicate

If ownership has already moved and regression coverage exists, residual historical helper bodies are cleanup work, not expansion blockers.

They should be removed during later hardening passes, but they do not all need to be gone before domain growth begins.

3. Long-tail micro-polish in reply tone

Minor phrasing improvements can be postponed if:

• the business answer is already truthful;
• no technical internals leak to the user;
• answer shape remains useful and stable.

4. UI-first acceptance ergonomics

The current script-driven acceptance loop is good enough for pre-expansion gating.

Promoting every replay step into a more polished UI loop can happen later.

Recommended Final Turnaround Sequence

Pass 1

• finish the first authoritative continuity contract and wire it into route / recap / clarification hot paths;
• prove that mixed replay stops losing active frame authority;
• treat this as the main pre-expansion hardening track.

Pass 2

• subordinate clarification to restored business continuity and remove repeated template escapes;
• harden recap truthfulness so it can only summarize verified session facts;
• confirm with AGENT replay that user-facing answers stay business-first.

Pass 3

• continue extracting the highest-risk signal families out of resolveAddressIntent();
• reduce remaining answer-semantics pressure in composeFactualReplyBody() and composeStage.ts;
• confirm with AGENT replay that technical scaffolding no longer leaks into the user-facing answer.

Practical Exit Condition

Turnaround 11 can be considered "ready for domain expansion" when:

• one continuity authority governs mixed live sessions;
• clarification no longer wins against valid restored business context;
• the main route-collision pressure in resolveAddressIntent() is materially reduced;
• the hottest user-facing answer families are protected from technical leakage;
• AGENT replay confirms stable business usefulness on the core mixed chains;
• remaining debt is mostly cleanup debt, not architecture debt that can multiply regressions during expansion.