SILVER
/
NODEDC_1C
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

ГЛОБАЛЬНЫЙ РЕФАКТОРИНГ АРХИТЕКТУРЫ - Рефакторинг этапов 2.89 - 2.92 и 2.93 - 2.96 - Ужесточение deep-turn финализацию/response контракт debug до строго AssistantDebugPayload / Вынен общий контракт followup-usage и helper / Протянут typed followupUsage по deep-turn цепочке и убрал inline-cast проверки applied

This commit is contained in:
dctouch 2026-04-11 11:07:56 +03:00
parent 966be04af9
commit 360b59d7c5
17 changed files with 95 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/TECH/1CLLMARCH-FACT.md
View File

@ -1974,7 +1974,58 @@ Validation:
- `assistantDeepTurnResponseAttemptRuntimeAdapter.test.ts`
- `assistantDeepTurnAttemptRuntimeAdapter.test.ts`
Status: **In progress (Phase 2.1 + 2.2 + 2.3 + 2.4 + 2.5 + 2.6 + 2.7 + 2.8 + 2.9 + 2.10 + 2.11 + 2.12 + 2.13 + 2.14 + 2.15 + 2.16 + 2.17 + 2.18 + 2.19 + 2.20 + 2.21 + 2.22 + 2.23 + 2.24 + 2.25 + 2.26 + 2.27 + 2.28 + 2.29 + 2.30 + 2.31 + 2.32 + 2.33 + 2.34 + 2.35 + 2.36 + 2.37 + 2.38 + 2.39 + 2.40 + 2.41 + 2.42 + 2.43 + 2.44 + 2.45 + 2.46 + 2.47 + 2.48 + 2.49 + 2.50 + 2.51 + 2.52 + 2.53 + 2.54 + 2.55 + 2.56 + 2.57 + 2.58 + 2.59 + 2.60 + 2.61 + 2.62 + 2.63 + 2.64 + 2.65 + 2.66 + 2.67 + 2.68 + 2.69 + 2.70 + 2.71 + 2.72 + 2.73 + 2.74 + 2.75 + 2.76 + 2.77 + 2.78 + 2.79 + 2.80 + 2.81 + 2.82 + 2.83 + 2.84 + 2.85 + 2.86 + 2.87 + 2.88 completed)**
Implemented in current pass (Phase 2.89 + 2.90 + 2.91 + 2.92):
1. Hardened deep-turn response envelope contract:
- `assistantDeepTurnResponseBuilder.ts`
- removed weak `debug` union (`AssistantDebugPayload | Record<string, unknown>`);
- response builder now accepts and propagates `AssistantDebugPayload` strictly.
2. Hardened deep-turn finalize runtime contract:
- `assistantDeepTurnFinalizeRuntimeAdapter.ts`
- aligned finalize input to strict `AssistantDebugPayload` for `debug`.
3. Preserved behavior:
- no runtime logic changes; only stricter contract enforcement for debug payload type at finalize/response boundary.
Validation:
1. `npm run build` passed.
2. Targeted deep finalize/response pack passed:
- `assistantDeepTurnResponseBuilder.test.ts`
- `assistantDeepTurnFinalizeRuntimeAdapter.test.ts`
- `assistantDeepTurnResponseAttemptRuntimeAdapter.test.ts`
- `assistantDeepTurnAttemptRuntimeAdapter.test.ts`
Implemented in current pass (Phase 2.93 + 2.94 + 2.95 + 2.96):
1. Introduced shared followup-usage contract and helper:
- `assistantFollowupUsage.ts`
- added:
- `AssistantFollowupUsage`
- `isAssistantFollowupApplied(...)`
2. Replaced weak `unknown` followup usage contracts across deep-turn chain:
- `assistantDeepTurnNormalizationRuntimeAdapter.ts`
- `assistantDeepTurnAnalysisAttemptRuntimeAdapter.ts`
- `assistantDeepTurnContextRuntimeAdapter.ts`
- `assistantDeepTurnCompositionRuntimeAdapter.ts`
- `assistantDeepTurnAttemptInputBuilder.ts`
- `assistantDeepTurnResponseAttemptRuntimeAdapter.ts`
- `assistantDeepTurnInputBuilder.ts`
- `assistantDeepTurnPackagingRuntimeAdapter.ts`
- `assistantDeepTurnPackaging.ts`
3. Removed inline followup casts:
- switched `Boolean((... as { applied?: unknown })?.applied)` style checks to shared helper usage.
4. Preserved behavior:
- no logic changes, only contract normalization and reuse of a single applied-check helper.
Validation:
1. `npm run build` passed.
2. Targeted deep followup chain pack passed:
- `assistantDeepTurnNormalizationRuntimeAdapter.test.ts`
- `assistantDeepTurnContextRuntimeAdapter.test.ts`
- `assistantDeepTurnCompositionRuntimeAdapter.test.ts`
- `assistantDeepTurnAttemptInputBuilder.test.ts`
- `assistantDeepTurnResponseAttemptRuntimeAdapter.test.ts`
- `assistantDeepTurnPackagingRuntimeAdapter.test.ts`
- `assistantDeepTurnPackaging.test.ts`
Status: **In progress (Phase 2.1 + 2.2 + 2.3 + 2.4 + 2.5 + 2.6 + 2.7 + 2.8 + 2.9 + 2.10 + 2.11 + 2.12 + 2.13 + 2.14 + 2.15 + 2.16 + 2.17 + 2.18 + 2.19 + 2.20 + 2.21 + 2.22 + 2.23 + 2.24 + 2.25 + 2.26 + 2.27 + 2.28 + 2.29 + 2.30 + 2.31 + 2.32 + 2.33 + 2.34 + 2.35 + 2.36 + 2.37 + 2.38 + 2.39 + 2.40 + 2.41 + 2.42 + 2.43 + 2.44 + 2.45 + 2.46 + 2.47 + 2.48 + 2.49 + 2.50 + 2.51 + 2.52 + 2.53 + 2.54 + 2.55 + 2.56 + 2.57 + 2.58 + 2.59 + 2.60 + 2.61 + 2.62 + 2.63 + 2.64 + 2.65 + 2.66 + 2.67 + 2.68 + 2.69 + 2.70 + 2.71 + 2.72 + 2.73 + 2.74 + 2.75 + 2.76 + 2.77 + 2.78 + 2.79 + 2.80 + 2.81 + 2.82 + 2.83 + 2.84 + 2.85 + 2.86 + 2.87 + 2.88 + 2.89 + 2.90 + 2.91 + 2.92 + 2.93 + 2.94 + 2.95 + 2.96 completed)**
## Stage 3 (P2): Hybrid Semantic Layer (LLM + Deterministic Guards)

3
llm_normalizer/backend/dist/services/assistantDeepTurnAttemptInputBuilder.js vendored
View File

@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
exports.buildAssistantDeepTurnNormalizationRuntimeInput = buildAssistantDeepTurnNormalizationRuntimeInput;
exports.buildAssistantDeepTurnAnalysisAttemptRuntimeInput = buildAssistantDeepTurnAnalysisAttemptRuntimeInput;
exports.buildAssistantDeepTurnResponseAttemptRuntimeInput = buildAssistantDeepTurnResponseAttemptRuntimeInput;
const assistantFollowupUsage_1 = require("./assistantFollowupUsage");
function buildAssistantDeepTurnNormalizationRuntimeInput(input) {
return {
userMessage: input.userMessage,
@ -60,7 +61,7 @@ function buildAssistantDeepTurnResponseAttemptRuntimeInput(input) {
deepTurnAnalysisRuntime: input.deepTurnAnalysisRuntime,
runtimeAnalysisContext: input.runtimeAnalysisContext,
followupStateUsage: input.normalizationRuntime.followupBinding.usage,
followupApplied: Boolean(input.normalizationRuntime.followupBinding.usage?.applied),
followupApplied: (0, assistantFollowupUsage_1.isAssistantFollowupApplied)(input.normalizationRuntime.followupBinding.usage),
previousInvestigationState: input.sessionInvestigationState,
addressRuntimeMetaForDeep: input.addressRuntimeMetaForDeep,
extractDroppedIntentSegments: input.extractDroppedIntentSegments,

3
llm_normalizer/backend/dist/services/assistantDeepTurnCompositionRuntimeAdapter.js vendored
View File

@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
exports.buildAssistantDeepTurnComposition = buildAssistantDeepTurnComposition;
const questionTypeResolver_1 = require("./questionTypeResolver");
const answerComposer_1 = require("./answerComposer");
const assistantFollowupUsage_1 = require("./assistantFollowupUsage");
function toStringArray(value) {
if (!Array.isArray(value)) {
return [];
@ -30,7 +31,7 @@ function normalizeCompanyAnchorSet(value) {
function buildAssistantDeepTurnComposition(input) {
const resolveQuestionTypeSafe = input.resolveQuestionTypeFn ?? questionTypeResolver_1.resolveQuestionType;
const composeAssistantAnswerSafe = input.composeAssistantAnswerFn ?? answerComposer_1.composeAssistantAnswer;
const followupApplied = Boolean(input.followupUsage?.applied);
const followupApplied = (0, assistantFollowupUsage_1.isAssistantFollowupApplied)(input.followupUsage);
const focusDomainHint = followupApplied
? input.investigationState?.followup_context?.active_domain ?? input.investigationState?.focus.domain ?? null
: null;

3
llm_normalizer/backend/dist/services/assistantDeepTurnContextRuntimeAdapter.js vendored
View File

@ -1,6 +1,7 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.buildAssistantDeepTurnRuntimeContext = buildAssistantDeepTurnRuntimeContext;
const assistantFollowupUsage_1 = require("./assistantFollowupUsage");
const KNOWN_P0_DOMAINS = new Set([
"settlements_60_62",
"vat_document_register_book",
@ -53,7 +54,7 @@ function buildAssistantDeepTurnRuntimeContext(input) {
focusDomainHint: focusDomainForGuards,
userMessage: input.userMessage,
companyAnchors,
followupApplied: Boolean(input.followupUsage?.applied)
followupApplied: (0, assistantFollowupUsage_1.isAssistantFollowupApplied)(input.followupUsage)
});
const resolvedRouteSummary = businessScopeResolution.route_summary_resolved;
const liveTemporalHint = toAnalysisContext(input.runtimeAnalysisContext);

6
llm_normalizer/backend/dist/services/assistantFollowupUsage.js vendored Normal file
View File

@ -0,0 +1,6 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.isAssistantFollowupApplied = isAssistantFollowupApplied;
function isAssistantFollowupApplied(usage) {
return Boolean(usage?.applied);
}

3
llm_normalizer/backend/src/services/assistantDeepTurnAnalysisAttemptRuntimeAdapter.ts
View File

@ -35,6 +35,7 @@ import {
} from "./assistantDeepTurnCompositionRuntimeAdapter";
import type { NormalizeResponsePayload, RouteHintSummary } from "../types/normalizer";
import type { InvestigationStateWithProblemUnits } from "../types/stage2ProblemUnits";
import type { AssistantFollowupUsage } from "./assistantFollowupUsage";
import { buildAssistantDeepTurnAnalysisRuntimeInput } from "./assistantDeepTurnAnalysisAttemptInputBuilder";
interface RuntimeAnalysisContextLike {
@ -50,7 +51,7 @@ export interface RunAssistantDeepTurnAnalysisAttemptRuntimeInput {
normalizedPayload: NormalizeResponsePayload["normalized"];
routeSummary: RouteHintSummary | null;
runtimeAnalysisContext: RuntimeAnalysisContextLike;
followupUsage: unknown | null | undefined;
followupUsage: AssistantFollowupUsage | null | undefined;
investigationState: InvestigationStateWithProblemUnits | null | undefined;
featureAnswerPolicyV11: boolean;
featureProblemCentricAnswerV1: boolean;

5
llm_normalizer/backend/src/services/assistantDeepTurnAttemptInputBuilder.ts
View File

@ -5,6 +5,7 @@ import type {
import type { RunAssistantDeepTurnAnalysisAttemptRuntimeInput } from "./assistantDeepTurnAnalysisAttemptRuntimeAdapter";
import type { RunAssistantDeepTurnAnalysisRuntimeOutput } from "./assistantDeepTurnAnalysisRuntimeAdapter";
import type { RunAssistantDeepTurnResponseAttemptRuntimeInput } from "./assistantDeepTurnResponseAttemptRuntimeAdapter";
import { isAssistantFollowupApplied } from "./assistantFollowupUsage";
export interface BuildAssistantDeepTurnNormalizationRuntimeInputInput {
userMessage: string;
@ -134,9 +135,7 @@ export function buildAssistantDeepTurnResponseAttemptRuntimeInput<ResponseType =
deepTurnAnalysisRuntime: input.deepTurnAnalysisRuntime,
runtimeAnalysisContext: input.runtimeAnalysisContext,
followupStateUsage: input.normalizationRuntime.followupBinding.usage,
followupApplied: Boolean(
(input.normalizationRuntime.followupBinding.usage as { applied?: unknown } | null)?.applied
),
followupApplied: isAssistantFollowupApplied(input.normalizationRuntime.followupBinding.usage),
previousInvestigationState: input.sessionInvestigationState,
addressRuntimeMetaForDeep: input.addressRuntimeMetaForDeep,
extractDroppedIntentSegments: input.extractDroppedIntentSegments,

5
llm_normalizer/backend/src/services/assistantDeepTurnCompositionRuntimeAdapter.ts
View File

@ -5,6 +5,7 @@ import type { QuestionTypeClass } from "./questionTypeResolver";
import { resolveQuestionType } from "./questionTypeResolver";
import { composeAssistantAnswer } from "./answerComposer";
import type { CompanyAnchorSet } from "./companyAnchorResolver";
import { isAssistantFollowupApplied, type AssistantFollowupUsage } from "./assistantFollowupUsage";
export interface BuildAssistantDeepTurnCompositionInput {
userMessage: string;
@ -13,7 +14,7 @@ export interface BuildAssistantDeepTurnCompositionInput {
requirements: AssistantRequirement[];
coverageReport: RequirementCoverageReport;
groundingCheck: AnswerGroundingCheck;
followupUsage: unknown | null | undefined;
followupUsage: AssistantFollowupUsage | null | undefined;
investigationState: InvestigationStateWithProblemUnits | null | undefined;
companyAnchors: unknown;
normalizedPayload: NormalizeResponsePayload["normalized"];
@ -65,7 +66,7 @@ export function buildAssistantDeepTurnComposition(
const resolveQuestionTypeSafe = input.resolveQuestionTypeFn ?? resolveQuestionType;
const composeAssistantAnswerSafe = input.composeAssistantAnswerFn ?? composeAssistantAnswer;
const followupApplied = Boolean((input.followupUsage as { applied?: unknown } | null)?.applied);
const followupApplied = isAssistantFollowupApplied(input.followupUsage);
const focusDomainHint = followupApplied
? input.investigationState?.followup_context?.active_domain ?? input.investigationState?.focus.domain ?? null
: null;

5
llm_normalizer/backend/src/services/assistantDeepTurnContextRuntimeAdapter.ts
View File

@ -1,6 +1,7 @@
import type { NormalizeResponsePayload, RouteHintSummary } from "../types/normalizer";
import type { ClaimBoundAnchorAudit } from "./assistantClaimBoundEvidence";
import type { AssistantLiveTemporalHint } from "./assistantDeepTurnRetrievalRuntimeAdapter";
import { isAssistantFollowupApplied, type AssistantFollowupUsage } from "./assistantFollowupUsage";
import type { DomainPolarityGuardAudit, TemporalGuardAudit } from "./assistantRuntimeGuards";
const KNOWN_P0_DOMAINS = new Set([
@ -35,7 +36,7 @@ export interface BuildAssistantDeepTurnRuntimeContextInput {
period_to: string | null;
source: string | null;
};
followupUsage: unknown | null | undefined;
followupUsage: AssistantFollowupUsage | null | undefined;
resolveCompanyAnchors: (userMessage: string) => unknown;
resolveBusinessScopeAlignment: (input: {
userMessage: string;
@ -138,7 +139,7 @@ export function buildAssistantDeepTurnRuntimeContext(
focusDomainHint: focusDomainForGuards,
userMessage: input.userMessage,
companyAnchors,
followupApplied: Boolean((input.followupUsage as { applied?: unknown } | null)?.applied)
followupApplied: isAssistantFollowupApplied(input.followupUsage)
});
const resolvedRouteSummary = businessScopeResolution.route_summary_resolved;
const liveTemporalHint = toAnalysisContext(input.runtimeAnalysisContext);

2
llm_normalizer/backend/src/services/assistantDeepTurnFinalizeRuntimeAdapter.ts
View File

@ -8,7 +8,7 @@ export interface FinalizeAssistantDeepTurnInput {
assistantReply: string;
replyType: AssistantReplyType;
assistantItem: AssistantConversationItem;
debug: AssistantDebugPayload | Record<string, unknown>;
debug: AssistantDebugPayload;
deepAnalysisLogDetails: Record<string, unknown>;
appendItem: Parameters<typeof commitAssistantTurnAndLog>[0]["appendItem"];
getSession: Parameters<typeof commitAssistantTurnAndLog>[0]["getSession"];

3
llm_normalizer/backend/src/services/assistantDeepTurnInputBuilder.ts
View File

@ -2,6 +2,7 @@ import type { AssistantReplyType, AssistantRequirement, AnswerGroundingCheck, Re
import type { NormalizeResponsePayload, RouteHintSummary } from "../types/normalizer";
import type { AnswerStructureV11 } from "../types/stage1Contracts";
import type { AssistantDeepTurnPackagingInput } from "./assistantDeepTurnPackaging";
import type { AssistantFollowupUsage } from "./assistantFollowupUsage";
export interface AssistantDeepTurnInputBuilderArgs {
sessionId: string;
@ -64,7 +65,7 @@ export interface AssistantDeepTurnInputBuilderArgs {
rbpLiveRouteAudit: unknown | null;
faLiveRouteAudit: unknown | null;
groundedAnswerEligibilityGuard: Record<string, unknown>;
followupStateUsage?: unknown;
followupStateUsage?: AssistantFollowupUsage | null;
composition: {
reply_type: AssistantReplyType;
fallback_type: unknown;

3
llm_normalizer/backend/src/services/assistantDeepTurnNormalizationRuntimeAdapter.ts
View File

@ -1,10 +1,11 @@
import type { AssistantMessageRequestPayload } from "../types/assistant";
import type { NormalizeRequestPayload, NormalizeResponsePayload } from "../types/normalizer";
import type { AssistantFollowupUsage } from "./assistantFollowupUsage";
export interface AssistantDeepTurnFollowupBinding {
normalizedQuestion: string;
mergedContext: NormalizeRequestPayload["context"] | undefined;
usage: unknown | null;
usage: AssistantFollowupUsage | null;
}
export interface BuildAssistantDeepTurnNormalizationRuntimeInput {

3
llm_normalizer/backend/src/services/assistantDeepTurnPackaging.ts
View File

@ -17,6 +17,7 @@ import { assembleAssistantContractsBundleV1, type AssistantContractsBundleV1 } f
import { buildDeepAnswerArtifacts, buildAssistantConversationItem, type DeepAnswerArtifacts } from "./assistantDeepResponseAssembler";
import { buildDeepAnalysisDebugPayload } from "./assistantDebugPayloadAssembler";
import { buildDeepAnalysisProcessedLogDetails } from "./assistantMessageLogAssembler";
import type { AssistantFollowupUsage } from "./assistantFollowupUsage";
export interface AssistantDeepTurnPackagingInput {
sessionId: string;
@ -79,7 +80,7 @@ export interface AssistantDeepTurnPackagingInput {
rbpLiveRouteAudit: unknown | null;
faLiveRouteAudit: unknown | null;
groundedAnswerEligibilityGuard: Record<string, unknown>;
followupStateUsage: unknown | null;
followupStateUsage: AssistantFollowupUsage | null;
composition: {
reply_type: AssistantReplyType;
fallback_type: unknown;

3
llm_normalizer/backend/src/services/assistantDeepTurnPackagingRuntimeAdapter.ts
View File

@ -12,6 +12,7 @@ import type { InvestigationStateWithProblemUnits } from "../types/stage2ProblemU
import type { AssistantDeepTurnInputBuilderArgs } from "./assistantDeepTurnInputBuilder";
import { buildAssistantDeepTurnPackagingInput } from "./assistantDeepTurnInputBuilder";
import { assembleAssistantDeepTurnPackaging } from "./assistantDeepTurnPackaging";
import type { AssistantFollowupUsage } from "./assistantFollowupUsage";
import type {
AssistantAnalysisContextForContract,
AssistantRuntimeAnalysisContextForPrePackaging
@ -59,7 +60,7 @@ export interface AssistantDeepTurnPackagingRuntimeInput {
rbpLiveRouteAudit: unknown | null;
faLiveRouteAudit: unknown | null;
groundedAnswerEligibilityGuard: Record<string, unknown>;
followupStateUsage?: unknown;
followupStateUsage?: AssistantFollowupUsage | null;
followupApplied: boolean;
composition: AssistantDeepTurnCompositionForPackaging;
featureContractsV11: boolean;

3
llm_normalizer/backend/src/services/assistantDeepTurnResponseAttemptRuntimeAdapter.ts
View File

@ -2,6 +2,7 @@ import type { AssistantDebugPayload, AssistantMessageResponsePayload } from "../
import type { NormalizeResponsePayload } from "../types/normalizer";
import type { InvestigationStateWithProblemUnits } from "../types/stage2ProblemUnits";
import type { RunAssistantDeepTurnAnalysisRuntimeOutput } from "./assistantDeepTurnAnalysisRuntimeAdapter";
import type { AssistantFollowupUsage } from "./assistantFollowupUsage";
import {
runAssistantDeepTurnResponseRuntime,
type RunAssistantDeepTurnResponseRuntimeInput,
@ -27,7 +28,7 @@ export interface RunAssistantDeepTurnResponseAttemptRuntimeInput<
normalizedQuestion: string;
deepTurnAnalysisRuntime: RunAssistantDeepTurnAnalysisRuntimeOutput;
runtimeAnalysisContext: unknown;
followupStateUsage: unknown;
followupStateUsage: AssistantFollowupUsage | null;
followupApplied: boolean;
previousInvestigationState: InvestigationStateWithProblemUnits | null | undefined;
addressRuntimeMetaForDeep: unknown;

4
llm_normalizer/backend/src/services/assistantDeepTurnResponseBuilder.ts
View File

@ -10,7 +10,7 @@ export interface BuildAssistantDeepTurnSuccessResponseInput {
assistantReply: string;
replyType: AssistantReplyType;
conversationItem: AssistantConversationItem;
debug: AssistantDebugPayload | Record<string, unknown>;
debug: AssistantDebugPayload;
conversation: AssistantConversationItem[];
}
@ -23,7 +23,7 @@ export function buildAssistantDeepTurnSuccessResponse(
assistant_reply: input.assistantReply,
reply_type: input.replyType,
conversation_item: input.conversationItem,
debug: input.debug as AssistantDebugPayload,
debug: input.debug,
conversation: input.conversation
};
}

8
llm_normalizer/backend/src/services/assistantFollowupUsage.ts Normal file
View File

@ -0,0 +1,8 @@
export interface AssistantFollowupUsage {
applied?: unknown;
[key: string]: unknown;
}
export function isAssistantFollowupApplied(usage: AssistantFollowupUsage | null | undefined): boolean {
return Boolean(usage?.applied);
}