Initial import NDC_1C

llm_normalizer/backend/src/config.ts

@@ -0,0 +1,65 @@
+import path from "path";
+
+export const BACKEND_ROOT = path.resolve(__dirname, "..");
+export const MODULE_ROOT = path.resolve(BACKEND_ROOT, "..");
+
+function toBooleanFlag(value: string | undefined, defaultValue: boolean): boolean {
+  if (!value || value.trim() === "") {
+    return defaultValue;
+  }
+  const lowered = value.trim().toLowerCase();
+  return !(lowered === "0" || lowered === "false" || lowered === "off" || lowered === "no");
+}
+
+export const PORT = Number(process.env.PORT ?? 8787);
+export const TIMEZONE = process.env.TZ_FALLBACK ?? "Europe/Moscow";
+export const DEFAULT_OPENAI_BASE_URL = process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+export const DEFAULT_MODEL = process.env.OPENAI_MODEL ?? "gpt-4o-mini";
+export const DEFAULT_TEMPERATURE = Number(process.env.OPENAI_TEMPERATURE ?? 0);
+export const DEFAULT_MAX_OUTPUT_TOKENS = Number(process.env.OPENAI_MAX_OUTPUT_TOKENS ?? 700);
+export const DEFAULT_PROMPT_VERSION = process.env.DEFAULT_PROMPT_VERSION ?? "normalizer_v2_0_2";
+export const FEATURE_ASSISTANT_INVESTIGATION_STATE_V1 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_INVESTIGATION_STATE_V1,
+  true
+);
+export const FEATURE_ASSISTANT_CONTRACTS_V11 = toBooleanFlag(process.env.FEATURE_ASSISTANT_CONTRACTS_V11, true);
+export const FEATURE_ASSISTANT_STATE_FOLLOWUP_BINDING_V1 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_STATE_FOLLOWUP_BINDING_V1,
+  true
+);
+export const FEATURE_ASSISTANT_EVIDENCE_ENRICHMENT_V1 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_EVIDENCE_ENRICHMENT_V1,
+  true
+);
+export const FEATURE_ASSISTANT_BROAD_GUARD_V1 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_BROAD_GUARD_V1,
+  true
+);
+export const FEATURE_ASSISTANT_MIN_EVIDENCE_GATE_V1 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_MIN_EVIDENCE_GATE_V1,
+  true
+);
+export const FEATURE_ASSISTANT_ANTI_GENERIC_RANKING_GUARD_V1 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_ANTI_GENERIC_RANKING_GUARD_V1,
+  true
+);
+export const FEATURE_ASSISTANT_ANSWER_POLICY_V11 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_ANSWER_POLICY_V11,
+  false
+);
+export const FEATURE_ASSISTANT_ACCOUNTANT_EVAL_V1 = toBooleanFlag(
+  process.env.FEATURE_ASSISTANT_ACCOUNTANT_EVAL_V1,
+  true
+);
+
+export const DATA_DIR = process.env.DATA_DIR ?? path.resolve(MODULE_ROOT, "data");
+export const TRACES_DIR = path.resolve(DATA_DIR, "traces");
+export const PRESETS_DIR = path.resolve(DATA_DIR, "presets");
+export const EVAL_CASES_DIR = path.resolve(DATA_DIR, "eval_cases");
+export const ASSISTANT_SESSIONS_DIR = path.resolve(DATA_DIR, "assistant_sessions");
+
+export const PROMPTS_DIR = path.resolve(MODULE_ROOT, "prompts");
+export const REPORTS_DIR = path.resolve(MODULE_ROOT, "reports");
+export const EVAL_DATASETS_DIR = path.resolve(MODULE_ROOT, "eval_cases");
+export const SCHEMAS_DIR = path.resolve(BACKEND_ROOT, "src", "schemas");
+export const ARCH_EXPORT_2020_DIR = path.resolve(MODULE_ROOT, "..", "docs", "ARCH", "2020экспорт");

llm_normalizer/backend/src/prompts/developer/default.txt

@@ -0,0 +1,23 @@
+Классификация intent_class:
+- heavy_analytical: общий агрегированный риск-срез, рейтинг, приоритизация.
+- cross_entity: связки между документами/проводками/оплатами/договорами/контрагентами.
+- drilldown_explain: точечное объяснение причин по объекту или малому набору объектов.
+- rule_based_account_control: контрольные правила по счетам (ОС, 97, 10 и т.п.).
+- anomaly_probe: поиск нетипичных паттернов.
+- period_close_risk: фокус на предзакрытии периода.
+- ambiguous_human_query: широкая человеческая формулировка без точного scope.
+- simple_factual: простой факт без сложной аналитики.
+
+Правила route_hint:
+- live_mcp_drilldown: если точечный object trace.
+- hybrid_store_plus_live: если cross_entity + causal explain.
+- batch_refresh_then_store: если full-period heavy aggregate/ranking без готовой агрегации.
+- store_feature_risk: если тренд/аномалии/контроли, когда точечный runtime не обязателен.
+- store_canonical: простые факты и легкие запросы при достаточном контексте.
+
+Правила requires:
+- needs_cross_entity_join=true для связок между разными сущностями.
+- needs_causal_chain=true для формулировок "почему", "чем подтверждается", "разложи цепочку".
+- needs_exact_object_trace=true для конкретного документа/проводки/строки/номера/ref.
+- needs_period_cut=true если вопрос про конец периода или периодную сверку.
+- needs_evidence=true если требуется подтверждение документами/движениями/проводками.

llm_normalizer/backend/src/prompts/domain/default.txt

@@ -0,0 +1,11 @@
+Домен бухгалтерии:
+- ключевые счета: 01, 02, 10, 41, 51, 60, 62, 68.02, 90, 97;
+- сущности: контрагент, договор, реализация, поступление, оплата, проводка, регистр;
+- типовые паттерны: "не бьется", "хвост", "акт сверки", "закрывающие", "реализация без оплаты";
+- товарные аномалии: "продажа раньше прихода", "подозрительный остаток";
+- ОС: "амортизационная группа", "срок амортизации", "карточка ОС";
+- банк: "выписка", "движение по 51", "разрыв цепочки документ-проводка";
+- периодная аналитика: предзакрытие, риск-срез, приоритизация ручных проверок.
+
+Если присутствуют одновременно риск-слова и document/payment/posting chain,
+не понижать сценарий до чистого risk-route автоматически.

llm_normalizer/backend/src/prompts/fewshot/default.txt

@@ -0,0 +1,36 @@
+Q: По каким покупателям у нас отгрузки без оплаты на конец июня, свяжи с реализациями, договорами и проводками.
+Expected:
+{
+  "intent_class": "cross_entity",
+  "requires": {
+    "needs_cross_entity_join": true,
+    "needs_causal_chain": true,
+    "needs_exact_object_trace": false
+  },
+  "expected_output_shape": "reconciliation_report",
+  "route_hint": "hybrid_store_plus_live"
+}
+
+Q: Сделай рейтинг самых рисковых счетов перед закрытием июня.
+Expected:
+{
+  "intent_class": "heavy_analytical",
+  "requires": {
+    "needs_ranking": true,
+    "needs_period_cut": true
+  },
+  "expected_output_shape": "ranked_list",
+  "route_hint": "batch_refresh_then_store"
+}
+
+Q: Покажи документ №123 и проводку по нему, нужна точная строка.
+Expected:
+{
+  "intent_class": "drilldown_explain",
+  "requires": {
+    "needs_exact_object_trace": true,
+    "needs_runtime_truth": true
+  },
+  "expected_output_shape": "evidence_chain",
+  "route_hint": "live_mcp_drilldown"
+}

llm_normalizer/backend/src/prompts/system/default.txt

@@ -0,0 +1,11 @@
+Ты semantic-normalizer для бухгалтерского ассистента NDC.
+Твоя роль: только нормализация запроса пользователя в строгий JSON-контракт.
+
+Жесткие правила:
+1) Не давай бухгалтерский ответ по сути вопроса.
+2) Возвращай только JSON без markdown и пояснений.
+3) JSON обязан соответствовать переданной schema normalized_query_v1.
+4) Если период не указан, не выдумывай его; отмечай ambiguity.
+5) Для цепочек документов/проводок/оплат поднимай causal и cross-entity признаки.
+6) Для точечного object trace (номер/строка/ref) поднимай needs_exact_object_trace=true.
+7) Используй терминологию NDC.

llm_normalizer/backend/src/routes/accountingAgent.ts

@@ -0,0 +1,164 @@
+import { Router } from "express";
+import type { AppServices } from "../serverContext";
+import { ApiError, created, ok } from "../utils/http";
+
+const PREFIX = "/api/accounting-agent/v1";
+
+export function buildAccountingAgentRouter(services: AppServices): Router {
+  const router = Router();
+  const runtime = services.runtimeAdapter;
+
+  router.post(`${PREFIX}/runs/start`, (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const run = runtime.startRun({
+        sessionId: body.sessionId ? String(body.sessionId) : undefined,
+        initiator: body.initiator ? String(body.initiator) : "operator",
+        source: body.source ? String(body.source) : "gui",
+        metadata: (body.metadata ?? {}) as Record<string, unknown>,
+        idempotencyKey: body.idempotencyKey ? String(body.idempotencyKey) : undefined
+      });
+      created(res, {
+        ok: true,
+        sessionId: run.sessionId,
+        runId: run.runId,
+        status: run.status,
+        run
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post(`${PREFIX}/runs/finish`, (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const status = String(body.status ?? "DONE") as "DONE" | "ERROR" | "CANCELLED";
+      if (!["DONE", "ERROR", "CANCELLED"].includes(status)) {
+        throw new ApiError("INVALID_STATUS", `Invalid finish status: ${status}`, 400);
+      }
+      const run = runtime.finishRun({
+        runId: String(body.runId ?? ""),
+        status,
+        source: body.source ? String(body.source) : "gui",
+        reason: body.reason ? String(body.reason) : undefined,
+        metadata: (body.metadata ?? {}) as Record<string, unknown>,
+        idempotencyKey: body.idempotencyKey ? String(body.idempotencyKey) : undefined
+      });
+      ok(res, {
+        ok: true,
+        run
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.get(`${PREFIX}/runs`, (_req, res) => {
+    ok(res, {
+      ok: true,
+      items: runtime.listRuns()
+    });
+  });
+
+  router.get(`${PREFIX}/runs/:runId`, (req, res, next) => {
+    try {
+      const run = runtime.getRun(String(req.params.runId));
+      if (!run) {
+        throw new ApiError("RUN_NOT_FOUND", `Run not found: ${req.params.runId}`, 404);
+      }
+      ok(res, {
+        ok: true,
+        run
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post(`${PREFIX}/tasks/enqueue`, (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const task = runtime.enqueueTask({
+        runId: String(body.runId ?? ""),
+        payload: (body.payload ?? {}) as Record<string, unknown>,
+        source: body.source ? String(body.source) : "gui",
+        idempotencyKey: body.idempotencyKey ? String(body.idempotencyKey) : undefined
+      });
+      created(res, {
+        ok: true,
+        task
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post(`${PREFIX}/tasks/claim`, (_req, res) => {
+    const task = runtime.claimTask();
+    ok(res, {
+      ok: true,
+      task
+    });
+  });
+
+  router.post(`${PREFIX}/tasks/:taskId/complete`, (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const task = runtime.completeTask({
+        taskId: String(req.params.taskId),
+        result: (body.result ?? {}) as Record<string, unknown>,
+        source: body.source ? String(body.source) : "worker",
+        idempotencyKey: body.idempotencyKey ? String(body.idempotencyKey) : undefined
+      });
+      ok(res, {
+        ok: true,
+        task
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.post(`${PREFIX}/tasks/:taskId/error`, (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const task = runtime.failTask({
+        taskId: String(req.params.taskId),
+        error: {
+          code: String(body.code ?? "TASK_ERROR"),
+          message: String(body.message ?? "Task failed"),
+          details: body.details
+        },
+        source: body.source ? String(body.source) : "worker",
+        idempotencyKey: body.idempotencyKey ? String(body.idempotencyKey) : undefined
+      });
+      ok(res, {
+        ok: true,
+        task
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.get(`${PREFIX}/results`, (_req, res) => {
+    ok(res, {
+      ok: true,
+      items: runtime.getResults()
+    });
+  });
+
+  router.get(`${PREFIX}/trace/run/:runId`, (req, res) => {
+    ok(res, {
+      ok: true,
+      items: runtime.getRunTrace(String(req.params.runId))
+    });
+  });
+
+  router.get(`${PREFIX}/health`, (_req, res) => {
+    ok(res, runtime.health());
+  });
+
+  return router;
+}

llm_normalizer/backend/src/routes/assistant.ts

@@ -0,0 +1,52 @@
+import { Router } from "express";
+import type { AppServices } from "../serverContext";
+import type { AssistantMessageRequestPayload } from "../types/assistant";
+import { ApiError, ok } from "../utils/http";
+
+export function buildAssistantRouter(services: AppServices): Router {
+  const router = Router();
+
+  router.post("/api/assistant/message", async (req, res, next) => {
+    try {
+      const payload = (req.body ?? {}) as Partial<AssistantMessageRequestPayload>;
+      const userMessageSource =
+        typeof payload.user_message === "string"
+          ? payload.user_message
+          : typeof payload.message === "string"
+            ? payload.message
+            : "";
+      const userMessage = userMessageSource.trim();
+      if (!userMessage) {
+        throw new ApiError("INVALID_ASSISTANT_MESSAGE", "Field `user_message` or `message` is required.", 400);
+      }
+
+      const response = await services.assistantService.handleMessage({
+        ...payload,
+        user_message: userMessage,
+        message: userMessage,
+        mode: typeof payload.mode === "string" ? payload.mode : "assistant"
+      });
+      ok(res, response);
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  router.get("/api/assistant/session/:session_id", (req, res, next) => {
+    try {
+      const sessionId = String(req.params.session_id ?? "");
+      const session = services.assistantService.getSession(sessionId);
+      if (!session) {
+        throw new ApiError("ASSISTANT_SESSION_NOT_FOUND", `Session not found: ${sessionId}`, 404);
+      }
+      ok(res, {
+        ok: true,
+        session
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}

llm_normalizer/backend/src/routes/eval.ts

@@ -0,0 +1,38 @@
+import { Router } from "express";
+import type { AppServices } from "../serverContext";
+import { ok } from "../utils/http";
+import type { EvalRunMode, NormalizeRequestPayload } from "../types/normalizer";
+import type { EvalTarget } from "../types/assistantEval";
+
+export function buildEvalRouter(services: AppServices): Router {
+  const router = Router();
+
+  router.post("/api/eval/run", async (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const report = await services.evalService.run({
+        normalizeConfig: (body.normalizeConfig ?? {}) as Omit<NormalizeRequestPayload, "userQuestion" | "context">,
+        caseIds: Array.isArray(body.caseIds) ? (body.caseIds as string[]) : undefined,
+        useMock: Boolean(body.useMock),
+        mode: (body.mode as EvalRunMode | undefined) ?? "standard",
+        caseSetFile: typeof body.caseSetFile === "string" ? body.caseSetFile : undefined,
+        rawQuestions: typeof body.rawQuestions === "string" ? body.rawQuestions : undefined,
+        evalTarget: (body.eval_target as EvalTarget | undefined) ?? "normalizer",
+        compareWithReportFile:
+          typeof body.compare_with_report_file === "string"
+            ? body.compare_with_report_file
+            : typeof body.comparisonBaselineReportFile === "string"
+              ? body.comparisonBaselineReportFile
+              : undefined
+      });
+      ok(res, {
+        ok: true,
+        report
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}

llm_normalizer/backend/src/routes/history.ts

@@ -0,0 +1,32 @@
+import { Router } from "express";
+import { getTrace, listTraces } from "../services/traceLogger";
+import { ApiError, ok } from "../utils/http";
+
+export function buildHistoryRouter(): Router {
+  const router = Router();
+
+  router.get("/api/history", (_req, res) => {
+    ok(res, {
+      ok: true,
+      items: listTraces(200)
+    });
+  });
+
+  router.get("/api/history/:trace_id", (req, res, next) => {
+    try {
+      const traceId = String(req.params.trace_id);
+      const trace = getTrace(traceId);
+      if (!trace) {
+        throw new ApiError("TRACE_NOT_FOUND", `Trace not found: ${traceId}`, 404);
+      }
+      ok(res, {
+        ok: true,
+        trace
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}

llm_normalizer/backend/src/routes/normalize.ts

@@ -0,0 +1,20 @@
+import { Router } from "express";
+import { ok } from "../utils/http";
+import type { AppServices } from "../serverContext";
+import type { NormalizeRequestPayload } from "../types/normalizer";
+
+export function buildNormalizeRouter(services: AppServices): Router {
+  const router = Router();
+
+  router.post("/api/normalize", async (req, res, next) => {
+    try {
+      const payload = req.body as NormalizeRequestPayload;
+      const result = await services.normalizerService.normalize(payload);
+      ok(res, result);
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}

llm_normalizer/backend/src/routes/presets.ts

@@ -0,0 +1,50 @@
+import { Router } from "express";
+import { nanoid } from "nanoid";
+import { DEFAULT_PROMPT_VERSION } from "../config";
+import { listBuiltinPromptPresets } from "../services/promptBuilder";
+import { listPresets, savePreset } from "../services/traceLogger";
+import type { PromptPreset } from "../types/preset";
+import { created, ok } from "../utils/http";
+
+export function buildPresetsRouter(): Router {
+  const router = Router();
+
+  router.get("/api/presets", (_req, res) => {
+    const stored = listPresets();
+    const builtin = listBuiltinPromptPresets();
+    const combined = [...builtin, ...stored];
+    ok(res, {
+      ok: true,
+      default_prompt_version: DEFAULT_PROMPT_VERSION,
+      presets: combined
+    });
+  });
+
+  router.post("/api/presets/save", (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Partial<PromptPreset>;
+      const now = new Date().toISOString();
+      const preset: PromptPreset = {
+        id: body.id ?? `preset-${nanoid(8)}`,
+        name: body.name ?? "Пользовательский пресет",
+        createdAt: body.createdAt ?? now,
+        updatedAt: now,
+        prompt_version: body.prompt_version ?? DEFAULT_PROMPT_VERSION,
+        systemPrompt: body.systemPrompt ?? "",
+        developerPrompt: body.developerPrompt ?? "",
+        domainPrompt: body.domainPrompt ?? "",
+        schemaNotes: body.schemaNotes ?? "",
+        fewShotExamples: body.fewShotExamples ?? ""
+      };
+      savePreset(preset);
+      created(res, {
+        ok: true,
+        preset
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}

llm_normalizer/backend/src/routes/testConnection.ts

@@ -0,0 +1,28 @@
+import { Router } from "express";
+import { DEFAULT_MODEL, DEFAULT_OPENAI_BASE_URL } from "../config";
+import { OpenAIResponsesClient } from "../services/openaiResponsesClient";
+import { ok } from "../utils/http";
+
+export function buildTestConnectionRouter(client: OpenAIResponsesClient): Router {
+  const router = Router();
+
+  router.post("/api/openai/test-connection", async (req, res, next) => {
+    try {
+      const body = (req.body ?? {}) as Record<string, unknown>;
+      const result = await client.testConnection({
+        apiKey: String(body.apiKey ?? process.env.OPENAI_API_KEY ?? ""),
+        model: String(body.model ?? DEFAULT_MODEL),
+        baseUrl: String(body.baseUrl ?? DEFAULT_OPENAI_BASE_URL)
+      });
+      ok(res, {
+        ok: true,
+        model: result.model,
+        timestamp: new Date().toISOString()
+      });
+    } catch (error) {
+      next(error);
+    }
+  });
+
+  return router;
+}

llm_normalizer/backend/src/runtime/inMemoryRuntimeAdapter.ts

@@ -0,0 +1,263 @@
+import { nanoid } from "nanoid";
+import type { RuntimeAdapter } from "./runtimeAdapter";
+import type { RunRecord, TaskRecord, TraceEvent } from "../types/accountingAgent";
+import { ApiError } from "../utils/http";
+
+export class InMemoryRuntimeAdapter implements RuntimeAdapter {
+  private runs: RunRecord[] = [];
+  private tasks: TaskRecord[] = [];
+  private traces: TraceEvent[] = [];
+  private idempotencyCache = new Map<string, unknown>();
+
+  private now(): string {
+    return new Date().toISOString();
+  }
+
+  private cacheKey(action: string, key?: string): string | null {
+    if (!key || !key.trim()) return null;
+    return `${action}:${key.trim()}`;
+  }
+
+  private readIdempotency<T>(action: string, idempotencyKey?: string): T | null {
+    const cache = this.cacheKey(action, idempotencyKey);
+    if (!cache) return null;
+    return (this.idempotencyCache.get(cache) as T | undefined) ?? null;
+  }
+
+  private writeIdempotency(action: string, idempotencyKey: string | undefined, value: unknown): void {
+    const cache = this.cacheKey(action, idempotencyKey);
+    if (!cache) return;
+    this.idempotencyCache.set(cache, value);
+  }
+
+  private pushEvent(input: {
+    runId: string;
+    sessionId: string;
+    taskId?: string | null;
+    level?: "info" | "warn" | "error";
+    eventType: string;
+    payload?: Record<string, unknown>;
+  }): void {
+    this.traces.push({
+      timestamp: this.now(),
+      level: input.level ?? "info",
+      service: "llm_normalizer_backend",
+      sessionId: input.sessionId,
+      runId: input.runId,
+      taskId: input.taskId ?? null,
+      eventType: input.eventType,
+      payload: input.payload
+    });
+  }
+
+  public startRun(input: {
+    sessionId?: string;
+    initiator?: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+  }): RunRecord {
+    const cached = this.readIdempotency<RunRecord>("startRun", input.idempotencyKey);
+    if (cached) return cached;
+
+    const record: RunRecord = {
+      sessionId: input.sessionId ?? `session_${nanoid(8)}`,
+      runId: `run_${nanoid(10)}`,
+      status: "RUNNING",
+      initiator: input.initiator ?? "operator",
+      source: input.source ?? "gui",
+      createdAt: this.now(),
+      updatedAt: this.now(),
+      metadata: input.metadata ?? {}
+    };
+    this.runs.unshift(record);
+    this.pushEvent({
+      runId: record.runId,
+      sessionId: record.sessionId,
+      eventType: "RUN_STARTED",
+      payload: record.metadata as Record<string, unknown>
+    });
+    this.writeIdempotency("startRun", input.idempotencyKey, record);
+    return record;
+  }
+
+  public finishRun(input: {
+    runId: string;
+    status: "DONE" | "ERROR" | "CANCELLED";
+    source?: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+  }): RunRecord {
+    const cached = this.readIdempotency<RunRecord>("finishRun", input.idempotencyKey);
+    if (cached) return cached;
+
+    const record = this.runs.find((item) => item.runId === input.runId);
+    if (!record) {
+      throw new ApiError("RUN_NOT_FOUND", `Run not found: ${input.runId}`, 404);
+    }
+    record.status = input.status;
+    record.updatedAt = this.now();
+    record.source = input.source ?? record.source;
+    record.metadata = {
+      ...(record.metadata ?? {}),
+      ...(input.metadata ?? {}),
+      reason: input.reason ?? null
+    };
+    this.pushEvent({
+      runId: record.runId,
+      sessionId: record.sessionId,
+      eventType: `RUN_FINISHED_${input.status}`,
+      level: input.status === "ERROR" ? "error" : "info",
+      payload: { reason: input.reason ?? null }
+    });
+    this.writeIdempotency("finishRun", input.idempotencyKey, record);
+    return record;
+  }
+
+  public listRuns(): RunRecord[] {
+    return [...this.runs];
+  }
+
+  public getRun(runId: string): RunRecord | null {
+    return this.runs.find((item) => item.runId === runId) ?? null;
+  }
+
+  public enqueueTask(input: {
+    runId: string;
+    payload: Record<string, unknown>;
+    source?: string;
+    idempotencyKey?: string;
+  }): TaskRecord {
+    const cached = this.readIdempotency<TaskRecord>("enqueueTask", input.idempotencyKey);
+    if (cached) return cached;
+
+    const run = this.getRun(input.runId);
+    if (!run) {
+      throw new ApiError("RUN_NOT_FOUND", `Run not found: ${input.runId}`, 404);
+    }
+
+    const task: TaskRecord = {
+      taskId: `task_${nanoid(10)}`,
+      runId: run.runId,
+      status: "QUEUED",
+      payload: input.payload,
+      source: input.source ?? "gui",
+      createdAt: this.now(),
+      updatedAt: this.now()
+    };
+    this.tasks.unshift(task);
+    this.pushEvent({
+      runId: run.runId,
+      sessionId: run.sessionId,
+      taskId: task.taskId,
+      eventType: "TASK_ENQUEUED",
+      payload: task.payload
+    });
+    this.writeIdempotency("enqueueTask", input.idempotencyKey, task);
+    return task;
+  }
+
+  public claimTask(): TaskRecord | null {
+    const task = this.tasks.find((item) => item.status === "QUEUED");
+    if (!task) {
+      return null;
+    }
+    task.status = "RUNNING";
+    task.updatedAt = this.now();
+    const run = this.getRun(task.runId);
+    if (run) {
+      this.pushEvent({
+        runId: run.runId,
+        sessionId: run.sessionId,
+        taskId: task.taskId,
+        eventType: "TASK_CLAIMED"
+      });
+    }
+    return task;
+  }
+
+  public completeTask(input: {
+    taskId: string;
+    result: Record<string, unknown>;
+    source?: string;
+    idempotencyKey?: string;
+  }): TaskRecord {
+    const cached = this.readIdempotency<TaskRecord>("completeTask", input.idempotencyKey);
+    if (cached) return cached;
+
+    const task = this.tasks.find((item) => item.taskId === input.taskId);
+    if (!task) {
+      throw new ApiError("TASK_NOT_FOUND", `Task not found: ${input.taskId}`, 404);
+    }
+    task.status = "DONE";
+    task.updatedAt = this.now();
+    task.result = input.result;
+    task.source = input.source ?? task.source;
+
+    const run = this.getRun(task.runId);
+    if (run) {
+      this.pushEvent({
+        runId: run.runId,
+        sessionId: run.sessionId,
+        taskId: task.taskId,
+        eventType: "TASK_DONE",
+        payload: input.result
+      });
+    }
+    this.writeIdempotency("completeTask", input.idempotencyKey, task);
+    return task;
+  }
+
+  public failTask(input: {
+    taskId: string;
+    error: { code: string; message: string; details?: unknown };
+    source?: string;
+    idempotencyKey?: string;
+  }): TaskRecord {
+    const cached = this.readIdempotency<TaskRecord>("failTask", input.idempotencyKey);
+    if (cached) return cached;
+
+    const task = this.tasks.find((item) => item.taskId === input.taskId);
+    if (!task) {
+      throw new ApiError("TASK_NOT_FOUND", `Task not found: ${input.taskId}`, 404);
+    }
+    task.status = "ERROR";
+    task.updatedAt = this.now();
+    task.error = input.error;
+    task.source = input.source ?? task.source;
+
+    const run = this.getRun(task.runId);
+    if (run) {
+      this.pushEvent({
+        runId: run.runId,
+        sessionId: run.sessionId,
+        taskId: task.taskId,
+        eventType: "TASK_ERROR",
+        level: "error",
+        payload: {
+          errorCode: input.error.code,
+          errorMessage: input.error.message
+        }
+      });
+    }
+    this.writeIdempotency("failTask", input.idempotencyKey, task);
+    return task;
+  }
+
+  public getResults(): TaskRecord[] {
+    return this.tasks.filter((item) => item.status === "DONE" || item.status === "ERROR");
+  }
+
+  public getRunTrace(runId: string): TraceEvent[] {
+    return this.traces.filter((item) => item.runId === runId);
+  }
+
+  public health(): { ok: boolean; queueDepth: number; runsTotal: number } {
+    return {
+      ok: true,
+      queueDepth: this.tasks.filter((item) => item.status === "QUEUED").length,
+      runsTotal: this.runs.length
+    };
+  }
+}

llm_normalizer/backend/src/runtime/runtimeAdapter.ts

@@ -0,0 +1,43 @@
+import type { RunRecord, TaskRecord, TraceEvent } from "../types/accountingAgent";
+
+export interface RuntimeAdapter {
+  startRun(input: {
+    sessionId?: string;
+    initiator?: string;
+    source?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+  }): RunRecord;
+  finishRun(input: {
+    runId: string;
+    status: "DONE" | "ERROR" | "CANCELLED";
+    source?: string;
+    reason?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+  }): RunRecord;
+  listRuns(): RunRecord[];
+  getRun(runId: string): RunRecord | null;
+  enqueueTask(input: {
+    runId: string;
+    payload: Record<string, unknown>;
+    source?: string;
+    idempotencyKey?: string;
+  }): TaskRecord;
+  claimTask(): TaskRecord | null;
+  completeTask(input: {
+    taskId: string;
+    result: Record<string, unknown>;
+    source?: string;
+    idempotencyKey?: string;
+  }): TaskRecord;
+  failTask(input: {
+    taskId: string;
+    error: { code: string; message: string; details?: unknown };
+    source?: string;
+    idempotencyKey?: string;
+  }): TaskRecord;
+  getResults(): TaskRecord[];
+  getRunTrace(runId: string): TraceEvent[];
+  health(): { ok: boolean; queueDepth: number; runsTotal: number };
+}

llm_normalizer/backend/src/schemas/normalized_query_v1.json

@@ -0,0 +1,177 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "normalized_query_v1",
+  "title": "Normalized Query V1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "user_question_raw",
+    "normalized_question",
+    "intent_class",
+    "business_problem_type",
+    "domain_entities",
+    "accounts_mentioned",
+    "documents_mentioned",
+    "registers_mentioned",
+    "period_scope",
+    "requires",
+    "expected_output_shape",
+    "route_hint",
+    "ambiguities",
+    "confidence"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "normalized_query_v1"
+    },
+    "user_question_raw": {
+      "type": "string",
+      "minLength": 1
+    },
+    "normalized_question": {
+      "type": "string",
+      "minLength": 1
+    },
+    "intent_class": {
+      "type": "string",
+      "enum": [
+        "heavy_analytical",
+        "cross_entity",
+        "drilldown_explain",
+        "rule_based_account_control",
+        "anomaly_probe",
+        "period_close_risk",
+        "ambiguous_human_query",
+        "simple_factual"
+      ]
+    },
+    "business_problem_type": {
+      "type": "string",
+      "minLength": 1
+    },
+    "domain_entities": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "accounts_mentioned": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "documents_mentioned": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "registers_mentioned": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "period_scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "value", "confidence"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["explicit", "inferred", "missing"]
+        },
+        "value": {
+          "type": ["string", "null"]
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["high", "medium", "low"]
+        }
+      }
+    },
+    "requires": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "needs_cross_entity_join",
+        "needs_causal_chain",
+        "needs_exact_object_trace",
+        "needs_ranking",
+        "needs_anomaly_summary",
+        "needs_runtime_truth",
+        "needs_period_cut",
+        "needs_evidence"
+      ],
+      "properties": {
+        "needs_cross_entity_join": { "type": "boolean" },
+        "needs_causal_chain": { "type": "boolean" },
+        "needs_exact_object_trace": { "type": "boolean" },
+        "needs_ranking": { "type": "boolean" },
+        "needs_anomaly_summary": { "type": "boolean" },
+        "needs_runtime_truth": { "type": "boolean" },
+        "needs_period_cut": { "type": "boolean" },
+        "needs_evidence": { "type": "boolean" }
+      }
+    },
+    "expected_output_shape": {
+      "type": "string",
+      "enum": [
+        "ranked_list",
+        "evidence_chain",
+        "anomaly_summary",
+        "point_answer",
+        "reconciliation_report",
+        "prioritized_review_list"
+      ]
+    },
+    "route_hint": {
+      "type": "string",
+      "enum": [
+        "store_canonical",
+        "store_feature_risk",
+        "hybrid_store_plus_live",
+        "live_mcp_drilldown",
+        "batch_refresh_then_store"
+      ]
+    },
+    "ambiguities": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["field", "reason", "severity"],
+        "properties": {
+          "field": { "type": "string" },
+          "reason": { "type": "string" },
+          "severity": {
+            "type": "string",
+            "enum": ["low", "medium", "high"]
+          }
+        }
+      }
+    },
+    "confidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["overall", "intent_class", "route_hint"],
+      "properties": {
+        "overall": {
+          "type": "string",
+          "enum": ["high", "medium", "low"]
+        },
+        "intent_class": {
+          "type": "string",
+          "enum": ["high", "medium", "low"]
+        },
+        "route_hint": {
+          "type": "string",
+          "enum": ["high", "medium", "low"]
+        }
+      }
+    }
+  }
+}

llm_normalizer/backend/src/schemas/normalized_query_v2.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "normalized_query_v2",
+  "title": "Normalized Query V2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "user_message_raw",
+    "message_in_scope",
+    "scope_confidence",
+    "contains_multiple_tasks",
+    "fragments",
+    "discarded_fragments",
+    "global_notes"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "normalized_query_v2"
+    },
+    "user_message_raw": {
+      "type": "string",
+      "minLength": 1
+    },
+    "message_in_scope": {
+      "type": "boolean"
+    },
+    "scope_confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"]
+    },
+    "contains_multiple_tasks": {
+      "type": "boolean"
+    },
+    "fragments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "fragment_id",
+          "raw_fragment_text",
+          "normalized_fragment_text",
+          "domain_relevance",
+          "business_scope",
+          "entity_hints",
+          "account_hints",
+          "document_hints",
+          "register_hints",
+          "time_scope",
+          "flags",
+          "candidate_labels",
+          "confidence"
+        ],
+        "properties": {
+          "fragment_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "raw_fragment_text": {
+            "type": "string",
+            "minLength": 1
+          },
+          "normalized_fragment_text": {
+            "type": "string",
+            "minLength": 1
+          },
+          "domain_relevance": {
+            "type": "string",
+            "enum": ["in_scope", "out_of_scope", "unclear"]
+          },
+          "business_scope": {
+            "type": "string",
+            "enum": ["company_specific_accounting", "generic_accounting", "offtopic", "unclear"]
+          },
+          "entity_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "account_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "document_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "register_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "time_scope": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["type", "value", "confidence"],
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": ["explicit", "inferred", "missing"]
+              },
+              "value": {
+                "type": ["string", "null"]
+              },
+              "confidence": {
+                "type": "string",
+                "enum": ["high", "medium", "low"]
+              }
+            }
+          },
+          "flags": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "has_multi_entity_scope",
+              "asks_for_chain_explanation",
+              "asks_for_ranking_or_top",
+              "asks_for_period_summary",
+              "asks_for_rule_check",
+              "asks_for_anomaly_scan",
+              "asks_for_exact_object_trace",
+              "asks_for_evidence",
+              "mentions_period_close_context"
+            ],
+            "properties": {
+              "has_multi_entity_scope": { "type": "boolean" },
+              "asks_for_chain_explanation": { "type": "boolean" },
+              "asks_for_ranking_or_top": { "type": "boolean" },
+              "asks_for_period_summary": { "type": "boolean" },
+              "asks_for_rule_check": { "type": "boolean" },
+              "asks_for_anomaly_scan": { "type": "boolean" },
+              "asks_for_exact_object_trace": { "type": "boolean" },
+              "asks_for_evidence": { "type": "boolean" },
+              "mentions_period_close_context": { "type": "boolean" }
+            }
+          },
+          "candidate_labels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "heavy_analytical",
+                "cross_entity",
+                "drilldown_explain",
+                "rule_based_account_control",
+                "anomaly_probe",
+                "period_close_risk",
+                "ambiguous_human_query",
+                "simple_factual"
+              ]
+            }
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          }
+        }
+      }
+    },
+    "discarded_fragments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["raw_fragment_text", "reason"],
+        "properties": {
+          "raw_fragment_text": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "global_notes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["needs_clarification", "clarification_reason"],
+      "properties": {
+        "needs_clarification": {
+          "type": "boolean"
+        },
+        "clarification_reason": {
+          "type": ["string", "null"]
+        }
+      }
+    }
+  }
+}

llm_normalizer/backend/src/schemas/normalized_query_v2_0_1.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "normalized_query_v2_0_1",
+  "title": "Normalized Query V2.0.1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "user_message_raw",
+    "message_in_scope",
+    "scope_confidence",
+    "contains_multiple_tasks",
+    "fragments",
+    "discarded_fragments",
+    "global_notes"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "normalized_query_v2_0_1"
+    },
+    "user_message_raw": {
+      "type": "string",
+      "minLength": 1
+    },
+    "message_in_scope": {
+      "type": "boolean"
+    },
+    "scope_confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"]
+    },
+    "contains_multiple_tasks": {
+      "type": "boolean"
+    },
+    "fragments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "fragment_id",
+          "raw_fragment_text",
+          "normalized_fragment_text",
+          "domain_relevance",
+          "business_scope",
+          "entity_hints",
+          "account_hints",
+          "document_hints",
+          "register_hints",
+          "time_scope",
+          "flags",
+          "candidate_labels",
+          "confidence",
+          "execution_readiness",
+          "clarification_reason",
+          "soft_assumption_used"
+        ],
+        "properties": {
+          "fragment_id": { "type": "string", "minLength": 1 },
+          "raw_fragment_text": { "type": "string", "minLength": 1 },
+          "normalized_fragment_text": { "type": "string", "minLength": 1 },
+          "domain_relevance": {
+            "type": "string",
+            "enum": ["in_scope", "out_of_scope", "unclear"]
+          },
+          "business_scope": {
+            "type": "string",
+            "enum": ["company_specific_accounting", "generic_accounting", "offtopic", "unclear"]
+          },
+          "entity_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "account_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "document_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "register_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "time_scope": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["type", "value", "confidence"],
+            "properties": {
+              "type": { "type": "string", "enum": ["explicit", "inferred", "missing"] },
+              "value": { "type": ["string", "null"] },
+              "confidence": { "type": "string", "enum": ["high", "medium", "low"] }
+            }
+          },
+          "flags": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "has_multi_entity_scope",
+              "asks_for_chain_explanation",
+              "asks_for_ranking_or_top",
+              "asks_for_period_summary",
+              "asks_for_rule_check",
+              "asks_for_anomaly_scan",
+              "asks_for_exact_object_trace",
+              "asks_for_evidence",
+              "mentions_period_close_context"
+            ],
+            "properties": {
+              "has_multi_entity_scope": { "type": "boolean" },
+              "asks_for_chain_explanation": { "type": "boolean" },
+              "asks_for_ranking_or_top": { "type": "boolean" },
+              "asks_for_period_summary": { "type": "boolean" },
+              "asks_for_rule_check": { "type": "boolean" },
+              "asks_for_anomaly_scan": { "type": "boolean" },
+              "asks_for_exact_object_trace": { "type": "boolean" },
+              "asks_for_evidence": { "type": "boolean" },
+              "mentions_period_close_context": { "type": "boolean" }
+            }
+          },
+          "candidate_labels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "heavy_analytical",
+                "cross_entity",
+                "drilldown_explain",
+                "rule_based_account_control",
+                "anomaly_probe",
+                "period_close_risk",
+                "ambiguous_human_query",
+                "simple_factual"
+              ]
+            }
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          },
+          "execution_readiness": {
+            "type": "string",
+            "enum": ["executable", "executable_with_soft_assumptions", "needs_clarification"]
+          },
+          "clarification_reason": {
+            "type": ["string", "null"]
+          },
+          "soft_assumption_used": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["period_from_session_context", "company_scope_defaulted", "problem_scan_mode_enabled"]
+            }
+          }
+        }
+      }
+    },
+    "discarded_fragments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["raw_fragment_text", "reason"],
+        "properties": {
+          "raw_fragment_text": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "global_notes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["needs_clarification", "clarification_reason"],
+      "properties": {
+        "needs_clarification": { "type": "boolean" },
+        "clarification_reason": { "type": ["string", "null"] }
+      }
+    }
+  }
+}
+

llm_normalizer/backend/src/schemas/normalized_query_v2_0_2.json

@@ -0,0 +1,192 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "normalized_query_v2_0_2",
+  "title": "Normalized Query V2.0.2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "user_message_raw",
+    "message_in_scope",
+    "scope_confidence",
+    "contains_multiple_tasks",
+    "fragments",
+    "discarded_fragments",
+    "global_notes"
+  ],
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "normalized_query_v2_0_2"
+    },
+    "user_message_raw": {
+      "type": "string",
+      "minLength": 1
+    },
+    "message_in_scope": {
+      "type": "boolean"
+    },
+    "scope_confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"]
+    },
+    "contains_multiple_tasks": {
+      "type": "boolean"
+    },
+    "fragments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "fragment_id",
+          "raw_fragment_text",
+          "normalized_fragment_text",
+          "domain_relevance",
+          "business_scope",
+          "entity_hints",
+          "account_hints",
+          "document_hints",
+          "register_hints",
+          "time_scope",
+          "flags",
+          "candidate_labels",
+          "confidence",
+          "execution_readiness",
+          "clarification_reason",
+          "soft_assumption_used",
+          "route_status",
+          "no_route_reason"
+        ],
+        "properties": {
+          "fragment_id": { "type": "string", "minLength": 1 },
+          "raw_fragment_text": { "type": "string", "minLength": 1 },
+          "normalized_fragment_text": { "type": "string", "minLength": 1 },
+          "domain_relevance": {
+            "type": "string",
+            "enum": ["in_scope", "out_of_scope", "unclear"]
+          },
+          "business_scope": {
+            "type": "string",
+            "enum": ["company_specific_accounting", "generic_accounting", "offtopic", "unclear"]
+          },
+          "entity_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "account_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "document_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "register_hints": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "time_scope": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["type", "value", "confidence"],
+            "properties": {
+              "type": { "type": "string", "enum": ["explicit", "inferred", "missing"] },
+              "value": { "type": ["string", "null"] },
+              "confidence": { "type": "string", "enum": ["high", "medium", "low"] }
+            }
+          },
+          "flags": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "has_multi_entity_scope",
+              "asks_for_chain_explanation",
+              "asks_for_ranking_or_top",
+              "asks_for_period_summary",
+              "asks_for_rule_check",
+              "asks_for_anomaly_scan",
+              "asks_for_exact_object_trace",
+              "asks_for_evidence",
+              "mentions_period_close_context"
+            ],
+            "properties": {
+              "has_multi_entity_scope": { "type": "boolean" },
+              "asks_for_chain_explanation": { "type": "boolean" },
+              "asks_for_ranking_or_top": { "type": "boolean" },
+              "asks_for_period_summary": { "type": "boolean" },
+              "asks_for_rule_check": { "type": "boolean" },
+              "asks_for_anomaly_scan": { "type": "boolean" },
+              "asks_for_exact_object_trace": { "type": "boolean" },
+              "asks_for_evidence": { "type": "boolean" },
+              "mentions_period_close_context": { "type": "boolean" }
+            }
+          },
+          "candidate_labels": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": [
+                "heavy_analytical",
+                "cross_entity",
+                "drilldown_explain",
+                "rule_based_account_control",
+                "anomaly_probe",
+                "period_close_risk",
+                "ambiguous_human_query",
+                "simple_factual"
+              ]
+            }
+          },
+          "confidence": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          },
+          "execution_readiness": {
+            "type": "string",
+            "enum": ["executable", "executable_with_soft_assumptions", "needs_clarification", "no_route"]
+          },
+          "clarification_reason": {
+            "type": ["string", "null"]
+          },
+          "soft_assumption_used": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "enum": ["period_from_session_context", "company_scope_defaulted", "problem_scan_mode_enabled"]
+            }
+          },
+          "route_status": {
+            "type": "string",
+            "enum": ["routed", "no_route"]
+          },
+          "no_route_reason": {
+            "type": ["string", "null"],
+            "enum": ["out_of_scope", "insufficient_specificity", "missing_mapping", "unsupported_fragment_type", null]
+          }
+        }
+      }
+    },
+    "discarded_fragments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["raw_fragment_text", "reason"],
+        "properties": {
+          "raw_fragment_text": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "global_notes": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["needs_clarification", "clarification_reason"],
+      "properties": {
+        "needs_clarification": { "type": "boolean" },
+        "clarification_reason": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

llm_normalizer/backend/src/server.ts

@@ -0,0 +1,80 @@
+import "dotenv/config";
+import cors from "cors";
+import express from "express";
+import { PORT, PRESETS_DIR, TRACES_DIR, EVAL_CASES_DIR, REPORTS_DIR, TIMEZONE, ASSISTANT_SESSIONS_DIR } from "./config";
+import { buildAccountingAgentRouter } from "./routes/accountingAgent";
+import { buildAssistantRouter } from "./routes/assistant";
+import { buildEvalRouter } from "./routes/eval";
+import { buildHistoryRouter } from "./routes/history";
+import { buildNormalizeRouter } from "./routes/normalize";
+import { buildPresetsRouter } from "./routes/presets";
+import { buildTestConnectionRouter } from "./routes/testConnection";
+import { InMemoryRuntimeAdapter } from "./runtime/inMemoryRuntimeAdapter";
+import { AssistantService } from "./services/assistantService";
+import { AssistantSessionStore } from "./services/assistantSessionStore";
+import { EvalService } from "./services/evalService";
+import { NormalizerService } from "./services/normalizerService";
+import { OpenAIResponsesClient } from "./services/openaiResponsesClient";
+import type { AppServices } from "./serverContext";
+import { ensureDir } from "./utils/files";
+import { errorMiddleware, ok } from "./utils/http";
+import { logJson } from "./utils/log";
+
+export function createApp(): express.Express {
+  ensureDir(TRACES_DIR);
+  ensureDir(PRESETS_DIR);
+  ensureDir(EVAL_CASES_DIR);
+  ensureDir(REPORTS_DIR);
+  ensureDir(ASSISTANT_SESSIONS_DIR);
+
+  const app = express();
+  app.use(cors());
+  app.use(express.json({ type: ["application/json", "application/*+json"], limit: "2mb" }));
+
+  const openaiClient = new OpenAIResponsesClient();
+  const normalizerService = new NormalizerService(openaiClient);
+  const evalService = new EvalService(normalizerService);
+  const assistantSessionStore = new AssistantSessionStore();
+  const assistantService = new AssistantService(normalizerService, assistantSessionStore);
+  const runtimeAdapter = new InMemoryRuntimeAdapter();
+
+  const services: AppServices = {
+    normalizerService,
+    evalService,
+    assistantService,
+    runtimeAdapter
+  };
+
+  app.get("/api/health", (_req, res) => {
+    ok(res, {
+      ok: true,
+      service: "llm-normalizer-backend",
+      status: "RUNNING",
+      timezone: TIMEZONE,
+      now: new Date().toISOString()
+    });
+  });
+
+  app.use(buildTestConnectionRouter(openaiClient));
+  app.use(buildNormalizeRouter(services));
+  app.use(buildEvalRouter(services));
+  app.use(buildAssistantRouter(services));
+  app.use(buildHistoryRouter());
+  app.use(buildPresetsRouter());
+  app.use(buildAccountingAgentRouter(services));
+  app.use(errorMiddleware);
+
+  return app;
+}
+
+if (require.main === module) {
+  const app = createApp();
+  app.listen(PORT, () => {
+    logJson({
+      timestamp: new Date().toISOString(),
+      level: "info",
+      service: "llm_normalizer_backend",
+      message: `Backend started on http://localhost:${PORT}`
+    });
+  });
+}

llm_normalizer/backend/src/serverContext.ts

@@ -0,0 +1,11 @@
+import { EvalService } from "./services/evalService";
+import { NormalizerService } from "./services/normalizerService";
+import { AssistantService } from "./services/assistantService";
+import type { RuntimeAdapter } from "./runtime/runtimeAdapter";
+
+export interface AppServices {
+  normalizerService: NormalizerService;
+  evalService: EvalService;
+  assistantService: AssistantService;
+  runtimeAdapter: RuntimeAdapter;
+}

llm_normalizer/backend/src/services/answerComposer.ts

@@ -0,0 +1,879 @@
+import type {
+  AssistantFallbackType,
+  AssistantReplyType,
+  AnswerGroundingCheck,
+  AssistantRequirement,
+  RequirementCoverageReport,
+  UnifiedRetrievalResult
+} from "../types/assistant";
+import type { RouteHintSummary } from "../types/normalizer";
+import type { AnswerStructureV11, EvidenceConfidence, EvidenceItem, EvidenceLimitationReasonCode } from "../types/stage1Contracts";
+
+interface ComposeAnswerInput {
+  userMessage: string;
+  routeSummary: RouteHintSummary | null;
+  retrievalResults: UnifiedRetrievalResult[];
+  requirements: AssistantRequirement[];
+  coverageReport: RequirementCoverageReport;
+  groundingCheck: AnswerGroundingCheck;
+  enableAnswerPolicyV11?: boolean;
+}
+
+interface ComposeAnswerOutput {
+  assistant_reply: string;
+  fallback_type: AssistantFallbackType;
+  reply_type: AssistantReplyType;
+  answer_structure_v11?: AnswerStructureV11;
+}
+
+function fallbackFromSummary(routeSummary: RouteHintSummary | null): AssistantFallbackType {
+  if (!routeSummary || routeSummary.mode !== "deterministic_v2") {
+    return "none";
+  }
+  return routeSummary.fallback.type as AssistantFallbackType;
+}
+
+function uniqueStrings(values: string[], limit = 6): string[] {
+  return Array.from(new Set(values.map((item) => item.trim()).filter(Boolean))).slice(0, limit);
+}
+
+function formatList(items: string[]): string {
+  if (items.length === 0) {
+    return "";
+  }
+  return items.map((item) => `- ${item}`).join("\n");
+}
+
+function extractTopFacts(results: UnifiedRetrievalResult[]): string[] {
+  const lines: string[] = [];
+  for (const result of results.filter((item) => item.status === "ok").slice(0, 3)) {
+    if (result.result_type === "chain") {
+      const top = result.items.slice(0, 3).map((item) => {
+        const counterparty = String(item.counterparty_id ?? "не указан");
+        const operations = String(item.operations_count ?? "0");
+        const docs = String(item.document_refs_count ?? "0");
+        return `Контрагент ${counterparty}: операций ${operations}, документов в связке ${docs}.`;
+      });
+      lines.push(...top);
+      continue;
+    }
+    if (result.result_type === "ranking") {
+      const top = result.items
+        .slice(0, 5)
+        .map((item) => `${item.rank ?? "•"}. ${String(item.entity ?? "Сущность")} — ${String(item.records_count ?? 0)}.`);
+      lines.push(...top);
+      continue;
+    }
+    if (result.result_type === "list") {
+      const top = result.items.slice(0, 5).map((item) => {
+        if (item.risk_score !== undefined) {
+          return `${String(item.source_entity ?? "Запись")} (${String(item.source_id ?? "")}) — риск ${String(item.risk_score)}.`;
+        }
+        return `${String(item.source_entity ?? "Запись")} (${String(item.source_id ?? "")}).`;
+      });
+      lines.push(...top);
+      continue;
+    }
+    const top = result.items
+      .slice(0, 3)
+      .map((item) => `${String(item.source_entity ?? "Запись")} (${String(item.source_id ?? "")}).`);
+    lines.push(...top);
+  }
+  return lines;
+}
+
+function extractWhyIncluded(results: UnifiedRetrievalResult[]): string[] {
+  return uniqueStrings(results.flatMap((item) => item.why_included));
+}
+
+function extractSelectionReasons(results: UnifiedRetrievalResult[]): string[] {
+  return uniqueStrings(results.flatMap((item) => item.selection_reason));
+}
+
+function extractRiskFactors(results: UnifiedRetrievalResult[]): string[] {
+  return uniqueStrings(results.flatMap((item) => item.risk_factors));
+}
+
+function extractBusinessInterpretation(results: UnifiedRetrievalResult[]): string[] {
+  return uniqueStrings(results.flatMap((item) => item.business_interpretation));
+}
+
+function extractLimitations(results: UnifiedRetrievalResult[]): string[] {
+  return uniqueStrings(results.flatMap((item) => item.limitations));
+}
+
+function summaryValue(result: UnifiedRetrievalResult, key: string): unknown {
+  const summary = result.summary ?? {};
+  return Object.prototype.hasOwnProperty.call(summary, key) ? summary[key] : undefined;
+}
+
+function summaryBoolean(result: UnifiedRetrievalResult, key: string): boolean {
+  return summaryValue(result, key) === true;
+}
+
+function summaryString(result: UnifiedRetrievalResult, key: string): string | null {
+  const value = summaryValue(result, key);
+  return typeof value === "string" ? value : null;
+}
+
+function suggestNextStep(requirements: AssistantRequirement[], coverage: RequirementCoverageReport): string[] {
+  const next: string[] = [];
+  if (coverage.clarification_needed_for.length > 0) {
+    next.push("Уточните период, счет, документ или контрагента для требований: " + coverage.clarification_needed_for.join(", ") + ".");
+  }
+  if (coverage.requirements_uncovered.length > 0) {
+    next.push("Проверьте непокрытые требования: " + coverage.requirements_uncovered.join(", ") + ".");
+  }
+  if (coverage.out_of_scope_requirements.length > 0) {
+    next.push("Часть запроса вне текущего учетного контура: " + coverage.out_of_scope_requirements.join(", ") + ".");
+  }
+  if (next.length === 0 && requirements.length > 0) {
+    next.push("Следующим шагом можно открыть технический разбор и углубить проверку по выбранным объектам.");
+  }
+  return next;
+}
+
+interface PolicySignals {
+  broad_query_detected: boolean;
+  broad_result_flag: boolean;
+  minimum_evidence_failed: boolean;
+  degraded_to: "partial" | "clarification" | null;
+  narrowing_strength: "weak" | "medium" | "strong" | null;
+}
+
+type PolicyMode =
+  | "focused_grounded"
+  | "broad_partial"
+  | "clarification_required"
+  | "out_of_scope"
+  | "route_mismatch"
+  | "empty"
+  | "no_grounded"
+  | "backend_error";
+
+interface PolicyDecision {
+  mode: PolicyMode;
+  fallback_type: AssistantFallbackType;
+  reply_type: AssistantReplyType;
+}
+
+interface MissingAnchors {
+  period: boolean;
+  account: boolean;
+  documentOrObject: boolean;
+  counterparty: boolean;
+  anomalyType: boolean;
+}
+
+function flattenEvidence(results: UnifiedRetrievalResult[]): EvidenceItem[] {
+  return results.flatMap((item) => item.evidence);
+}
+
+function buildClaimEvidenceLinks(results: UnifiedRetrievalResult[]): NonNullable<AnswerStructureV11["evidence_block"]["claim_evidence_links"]> {
+  const byClaim = new Map<string, string[]>();
+  for (const evidence of flattenEvidence(results)) {
+    const claimRef = String(evidence.claim_ref ?? "").trim();
+    const evidenceId = String(evidence.evidence_id ?? "").trim();
+    if (!claimRef || !evidenceId) {
+      continue;
+    }
+    const current = byClaim.get(claimRef) ?? [];
+    current.push(evidenceId);
+    byClaim.set(claimRef, current);
+  }
+  return Array.from(byClaim.entries())
+    .slice(0, 10)
+    .map(([claim_ref, evidenceIds]) => ({
+      claim_ref,
+      evidence_ids: uniqueStrings(evidenceIds, 10)
+    }));
+}
+
+function aggregatePolicySignals(results: UnifiedRetrievalResult[]): PolicySignals {
+  const broad_query_detected = results.some((item) => summaryBoolean(item, "broad_query_detected"));
+  const broad_result_flag = results.some((item) => summaryBoolean(item, "broad_result_flag"));
+  const minimum_evidence_failed = results.some((item) => summaryBoolean(item, "minimum_evidence_failed"));
+
+  let degraded_to: PolicySignals["degraded_to"] = null;
+  for (const result of results) {
+    const degraded = summaryString(result, "degraded_to");
+    if (degraded === "clarification") {
+      degraded_to = "clarification";
+      break;
+    }
+    if (degraded === "partial") {
+      degraded_to = "partial";
+    }
+  }
+
+  const narrowingOrder: Record<"weak" | "medium" | "strong", number> = {
+    weak: 0,
+    medium: 1,
+    strong: 2
+  };
+  let narrowing_strength: PolicySignals["narrowing_strength"] = null;
+  for (const result of results) {
+    const value = summaryString(result, "narrowing_strength");
+    if (value !== "weak" && value !== "medium" && value !== "strong") {
+      continue;
+    }
+    if (!narrowing_strength || narrowingOrder[value] < narrowingOrder[narrowing_strength]) {
+      narrowing_strength = value;
+    }
+  }
+
+  return {
+    broad_query_detected,
+    broad_result_flag,
+    minimum_evidence_failed,
+    degraded_to,
+    narrowing_strength
+  };
+}
+
+function confidenceToScore(value: EvidenceConfidence): number {
+  if (value === "high") return 3;
+  if (value === "medium") return 2;
+  return 1;
+}
+
+function aggregateConfidence(results: UnifiedRetrievalResult[], evidenceItems: EvidenceItem[]): EvidenceConfidence {
+  const scores: number[] = [];
+  for (const evidence of evidenceItems) {
+    scores.push(confidenceToScore(evidence.confidence));
+  }
+  for (const result of results) {
+    if (result.status === "error") {
+      continue;
+    }
+    scores.push(confidenceToScore(result.confidence));
+  }
+  if (scores.length === 0) {
+    return "low";
+  }
+  const average = scores.reduce((acc, item) => acc + item, 0) / scores.length;
+  if (average >= 2.6) return "high";
+  if (average >= 1.8) return "medium";
+  return "low";
+}
+
+function collectLimitationReasonCodes(evidenceItems: EvidenceItem[]): EvidenceLimitationReasonCode[] {
+  const codes = evidenceItems
+    .map((item) => item.limitation?.reason_code ?? null)
+    .filter((item): item is EvidenceLimitationReasonCode => Boolean(item));
+  return uniqueStrings(codes, 8) as EvidenceLimitationReasonCode[];
+}
+
+function limitationReasonToText(code: EvidenceLimitationReasonCode): string {
+  if (code === "snapshot_only") return "Evidence is snapshot-only and may lag source-of-record.";
+  if (code === "heuristic_inference") return "Part of the conclusion relies on heuristic inference.";
+  if (code === "missing_mechanism") return "Mechanism is unresolved for part of the evidence.";
+  if (code === "weak_source_mapping") return "Source mapping is weak for part of the evidence.";
+  if (code === "insufficient_detail") return "Evidence lacks detail for a strong factual claim.";
+  return "Some evidence limitations remain unresolved.";
+}
+
+function detectMissingAnchors(userMessage: string): MissingAnchors {
+  const lower = String(userMessage ?? "").toLowerCase();
+  const hasPeriod = /\b20\d{2}(?:[-./](?:0[1-9]|1[0-2]))?\b/.test(lower);
+  const hasAccount = /(?:\bсчет\b|\baccount\b|\bschet\b|\b\d{2}(?:\.\d{2})?\b)/i.test(lower);
+  const hasDocumentOrObject = /(?:документ|invoice|guid|object|obj|#\d+|\bid\b|\bref\b|dokument|doc)/i.test(lower);
+  const hasCounterparty = /(?:контрагент|supplier|buyer|customer|kontragent|postavsh|pokupatel)/i.test(lower);
+  const hasAnomalyType = /(?:аномал|risk|отклон|разрыв|mismatch|duplicate|tail|цепочк|anomali|hvost)/i.test(lower);
+
+  return {
+    period: !hasPeriod,
+    account: !hasAccount,
+    documentOrObject: !hasDocumentOrObject,
+    counterparty: !hasCounterparty,
+    anomalyType: !hasAnomalyType
+  };
+}
+
+function buildClarificationQuestions(input: {
+  mode: PolicyMode;
+  missingAnchors: MissingAnchors;
+  coverageReport: RequirementCoverageReport;
+  policySignals: PolicySignals;
+}): string[] {
+  const questions: string[] = [];
+  const shouldAsk = input.mode === "clarification_required" || input.coverageReport.clarification_needed_for.length > 0;
+  if (!shouldAsk) {
+    return questions;
+  }
+
+  if (input.missingAnchors.period) {
+    questions.push("Уточните период проверки (например, 2020-06).");
+  }
+  if (input.missingAnchors.account) {
+    questions.push("Уточните счет или группу счетов (например, 19, 60, 62).");
+  }
+  if (input.missingAnchors.documentOrObject) {
+    questions.push("Укажите документ/GUID/конкретный объект для трассировки.");
+  }
+  if (input.missingAnchors.counterparty) {
+    questions.push("Укажите контрагента или группу контрагентов.");
+  }
+  if (input.policySignals.broad_query_detected && input.missingAnchors.anomalyType) {
+    questions.push("Уточните тип отклонения: разрыв цепочки, неверный документ или аномальный риск.");
+  }
+  if (input.coverageReport.clarification_needed_for.length > 0) {
+    questions.push(`Закройте уточнения для требований: ${input.coverageReport.clarification_needed_for.join(", ")}.`);
+  }
+
+  return uniqueStrings(questions, 6);
+}
+
+function buildRecommendedActions(input: {
+  mode: PolicyMode;
+  coverageReport: RequirementCoverageReport;
+  policySignals: PolicySignals;
+  limitationReasonCodes: EvidenceLimitationReasonCode[];
+  sourceRefs: string[];
+}): string[] {
+  const actions: string[] = [];
+  if (input.mode === "focused_grounded") {
+    actions.push("Проверьте 1-2 ключевые записи по source_ref и зафиксируйте итог в рабочем файле проверки.");
+  }
+  if (input.mode === "broad_partial") {
+    actions.push("Сузьте запрос до периода + счета или периода + документа и повторите проверку.");
+  }
+  if (input.mode === "clarification_required") {
+    actions.push("Дайте недостающие якоря (период/счет/объект), иначе сильный factual вывод невозможен.");
+  }
+  if (input.coverageReport.requirements_uncovered.length > 0) {
+    actions.push(`Закройте непокрытые требования: ${input.coverageReport.requirements_uncovered.join(", ")}.`);
+  }
+  if (input.coverageReport.requirements_partially_covered.length > 0) {
+    actions.push(`Доуточните частично покрытые требования: ${input.coverageReport.requirements_partially_covered.join(", ")}.`);
+  }
+  if (input.policySignals.broad_query_detected && input.policySignals.narrowing_strength !== "strong") {
+    actions.push("Добавьте более узкий контекст: тип отклонения, группу документов и бизнес-участок.");
+  }
+  if (input.limitationReasonCodes.includes("snapshot_only")) {
+    actions.push("Сверьте критичные выводы с live source-of-record в 1C.");
+  }
+  if (input.limitationReasonCodes.includes("weak_source_mapping")) {
+    actions.push("Проверьте source mapping для связей document/register по указанным ref.");
+  }
+  if (input.sourceRefs.length > 0) {
+    actions.push(`Начните проверку с source_ref: ${input.sourceRefs.slice(0, 2).join(", ")}.`);
+  }
+
+  return uniqueStrings(actions, 6);
+}
+
+function firstMeaningfulFact(results: UnifiedRetrievalResult[]): string | null {
+  const facts = extractTopFacts(results);
+  return facts.length > 0 ? facts[0] : null;
+}
+
+function buildPolicyDecision(input: {
+  fallbackType: AssistantFallbackType;
+  coverageReport: RequirementCoverageReport;
+  groundingCheck: AnswerGroundingCheck;
+  okResults: UnifiedRetrievalResult[];
+  partialResults: UnifiedRetrievalResult[];
+  emptyResults: UnifiedRetrievalResult[];
+  errorResults: UnifiedRetrievalResult[];
+  hasSupport: boolean;
+  focusedStrong: boolean;
+  policySignals: PolicySignals;
+}): PolicyDecision {
+  const hasCoverageGaps =
+    input.coverageReport.requirements_uncovered.length > 0 ||
+    input.coverageReport.requirements_partially_covered.length > 0 ||
+    input.coverageReport.clarification_needed_for.length > 0 ||
+    input.coverageReport.out_of_scope_requirements.length > 0;
+
+  if (input.fallbackType === "out_of_scope" && input.coverageReport.requirements_covered === 0) {
+    return {
+      mode: "out_of_scope",
+      fallback_type: "out_of_scope",
+      reply_type: "out_of_scope"
+    };
+  }
+
+  if (input.groundingCheck.status === "route_mismatch_blocked") {
+    return {
+      mode: "route_mismatch",
+      fallback_type: "partial",
+      reply_type: "route_mismatch_blocked"
+    };
+  }
+
+  if (
+    (input.policySignals.degraded_to === "clarification" && input.policySignals.minimum_evidence_failed) ||
+    (input.fallbackType === "clarification" && !input.hasSupport) ||
+    (input.groundingCheck.status === "no_grounded_answer" && !input.hasSupport)
+  ) {
+    return {
+      mode: "clarification_required",
+      fallback_type: "clarification",
+      reply_type: "clarification_required"
+    };
+  }
+
+  if (input.errorResults.length > 0 && input.okResults.length === 0 && input.partialResults.length === 0) {
+    return {
+      mode: "backend_error",
+      fallback_type: input.fallbackType,
+      reply_type: "backend_error"
+    };
+  }
+
+  if (input.okResults.length === 0 && input.partialResults.length === 0 && input.emptyResults.length > 0) {
+    return {
+      mode: "empty",
+      fallback_type: input.fallbackType,
+      reply_type: "empty_but_valid"
+    };
+  }
+
+  if (input.groundingCheck.status === "no_grounded_answer" && input.okResults.length === 0 && input.partialResults.length === 0) {
+    return {
+      mode: "no_grounded",
+      fallback_type: input.fallbackType,
+      reply_type: "no_grounded_answer"
+    };
+  }
+
+  if (
+    input.focusedStrong &&
+    !input.policySignals.broad_query_detected &&
+    !input.policySignals.minimum_evidence_failed &&
+    !hasCoverageGaps
+  ) {
+    return {
+      mode: "focused_grounded",
+      fallback_type: "none",
+      reply_type: "factual_with_explanation"
+    };
+  }
+
+  if (
+    input.okResults.length > 0 ||
+    input.partialResults.length > 0 ||
+    hasCoverageGaps ||
+    input.policySignals.minimum_evidence_failed ||
+    input.policySignals.broad_result_flag ||
+    input.groundingCheck.status === "partial"
+  ) {
+    return {
+      mode: "broad_partial",
+      fallback_type: "partial",
+      reply_type: "partial_coverage"
+    };
+  }
+
+  return {
+    mode: "backend_error",
+    fallback_type: "unknown",
+    reply_type: "backend_error"
+  };
+}
+
+function buildAnswerSummary(mode: PolicyMode): string {
+  if (mode === "focused_grounded") return "Сформирован прямой ответ на основе подтвержденной опоры.";
+  if (mode === "broad_partial") return "Вывод ограничен: есть частичная опора, но не полный coverage.";
+  if (mode === "clarification_required") return "Нужны уточнения: без сужения strong factual вывод ненадежен.";
+  if (mode === "out_of_scope") return "Запрос вне доступного учетного контура.";
+  if (mode === "route_mismatch") return "Результат маршрута не совпал с предметом вопроса.";
+  if (mode === "empty") return "В текущем срезе данных релевантные записи не обнаружены.";
+  if (mode === "no_grounded") return "Недостаточно опоры для обоснованного ответа.";
+  return "Не удалось собрать обоснованный ответ по текущему запросу.";
+}
+
+function buildDirectAnswer(input: {
+  mode: PolicyMode;
+  retrievalResults: UnifiedRetrievalResult[];
+  policySignals: PolicySignals;
+}): string {
+  const topFact = firstMeaningfulFact(input.retrievalResults);
+  if (input.mode === "focused_grounded") {
+    return topFact ?? "Подтвержденный результат получен; можно продолжать предметную проверку без деградации.";
+  }
+  if (input.mode === "broad_partial") {
+    if (topFact) {
+      return `Доступен ограниченный подтвержденный фрагмент: ${topFact}`;
+    }
+    return "Есть только ограниченная опора; вывод дан в частичном режиме без ложной точности.";
+  }
+  if (input.mode === "clarification_required") {
+    return "Текущий запрос слишком широкий или недоопределен; надежный factual вывод пока невозможен.";
+  }
+  if (input.mode === "out_of_scope") {
+    return "Могу отвечать только в пределах данных доступного учетного контура.";
+  }
+  if (input.mode === "route_mismatch") {
+    return "Предмет результата не совпал с предметом вопроса; требуется уточнение фокуса.";
+  }
+  if (input.mode === "empty") {
+    return "В текущем срезе данных проблемные записи по заданному условию не найдены.";
+  }
+  if (input.mode === "no_grounded") {
+    return "Недостаточно подтвержденной опоры для ответа в требуемой точности.";
+  }
+  if (input.policySignals.minimum_evidence_failed) {
+    return "Маршрут отработал, но минимальная evidence-опора не пройдена.";
+  }
+  return "Не удалось сформировать обоснованный ответ; нужно уточнение запроса.";
+}
+
+function renderPolicyReply(structure: AnswerStructureV11): string {
+  const mechanismLines: string[] = [`status=${structure.mechanism_block.status}`];
+  if (structure.mechanism_block.mechanism_notes.length > 0) {
+    mechanismLines.push(...structure.mechanism_block.mechanism_notes.map((item) => `note: ${item}`));
+  }
+  if (structure.mechanism_block.limitation_reason_codes.length > 0) {
+    mechanismLines.push(`limitation_codes: ${structure.mechanism_block.limitation_reason_codes.join(", ")}`);
+  }
+  if (structure.mechanism_block.status === "unresolved" && structure.mechanism_block.mechanism_notes.length === 0) {
+    mechanismLines.push("mechanism_note is intentionally omitted due to weak or missing mechanism evidence");
+  }
+
+  const evidenceLines: string[] = [
+    `coverage=${structure.evidence_block.coverage_note}`,
+    `evidence_ids=${structure.evidence_block.evidence_ids.length > 0 ? structure.evidence_block.evidence_ids.join(", ") : "none"}`
+  ];
+  if (Array.isArray(structure.evidence_block.source_refs) && structure.evidence_block.source_refs.length > 0) {
+    evidenceLines.push(`source_refs=${structure.evidence_block.source_refs.join(", ")}`);
+  }
+  if (Array.isArray(structure.evidence_block.claim_evidence_links) && structure.evidence_block.claim_evidence_links.length > 0) {
+    const compactLinks = structure.evidence_block.claim_evidence_links
+      .slice(0, 4)
+      .map((item) => `${item.claim_ref}:${item.evidence_ids.join("|")}`);
+    evidenceLines.push(`claim_evidence_links=${compactLinks.join("; ")}`);
+  }
+
+  const uncertaintyLines = [
+    ...structure.uncertainty_block.open_uncertainties.map((item) => `open: ${item}`),
+    ...structure.uncertainty_block.limitations.map((item) => `limit: ${item}`)
+  ];
+  if (uncertaintyLines.length === 0) {
+    uncertaintyLines.push("No material uncertainty detected in current scoped answer.");
+  }
+
+  const nextStepLines = [
+    ...structure.next_step_block.recommended_actions.map((item) => `action: ${item}`),
+    ...structure.next_step_block.clarification_questions.map((item) => `clarify: ${item}`)
+  ];
+  if (nextStepLines.length === 0) {
+    nextStepLines.push("No additional action is required for this scoped answer.");
+  }
+
+  return [
+    `Answer summary: ${structure.answer_summary}`,
+    `Direct answer:\n${structure.direct_answer}`,
+    `Mechanism block:\n${formatList(mechanismLines)}`,
+    `Evidence block:\n${formatList(evidenceLines)}`,
+    `Uncertainty block:\n${formatList(uncertaintyLines)}`,
+    `Next step block:\n${formatList(nextStepLines)}`
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function composeAssistantAnswerV11(input: ComposeAnswerInput): ComposeAnswerOutput {
+  const fallbackType = fallbackFromSummary(input.routeSummary);
+  const okResults = input.retrievalResults.filter((item) => item.status === "ok");
+  const partialResults = input.retrievalResults.filter((item) => item.status === "partial");
+  const emptyResults = input.retrievalResults.filter((item) => item.status === "empty");
+  const errorResults = input.retrievalResults.filter((item) => item.status === "error");
+  const evidenceItems = flattenEvidence(input.retrievalResults);
+  const policySignals = aggregatePolicySignals(input.retrievalResults);
+  const limitationReasonCodes = collectLimitationReasonCodes(evidenceItems);
+  const sourceRefs = uniqueStrings(
+    evidenceItems
+      .map((item) => item.source_ref?.canonical_ref)
+      .filter((item): item is string => typeof item === "string" && item.trim().length > 0),
+    8
+  );
+  const mechanismNotes = uniqueStrings(
+    evidenceItems
+      .map((item) => item.mechanism_note)
+      .filter((item): item is string => typeof item === "string" && item.trim().length > 0),
+    6
+  );
+  const claimEvidenceLinks = buildClaimEvidenceLinks(input.retrievalResults);
+  const aggregateEvidenceConfidence = aggregateConfidence(input.retrievalResults, evidenceItems);
+  const hasSupport =
+    okResults.length > 0 ||
+    partialResults.length > 0 ||
+    evidenceItems.length > 0 ||
+    input.retrievalResults.some((item) => item.items.length > 0);
+  const hasCoverageGaps =
+    input.coverageReport.requirements_uncovered.length > 0 ||
+    input.coverageReport.requirements_partially_covered.length > 0 ||
+    input.coverageReport.clarification_needed_for.length > 0 ||
+    input.coverageReport.out_of_scope_requirements.length > 0;
+  const hasCriticalEvidenceLimitation =
+    limitationReasonCodes.includes("weak_source_mapping") ||
+    limitationReasonCodes.includes("insufficient_detail");
+  const hasNonLowRouteConfidence = input.retrievalResults.some(
+    (item) => item.status === "ok" && item.confidence !== "low"
+  );
+  const focusedStrong =
+    okResults.length > 0 &&
+    input.groundingCheck.status === "grounded" &&
+    !hasCoverageGaps &&
+    !policySignals.broad_query_detected &&
+    !policySignals.broad_result_flag &&
+    !policySignals.minimum_evidence_failed &&
+    !hasCriticalEvidenceLimitation &&
+    (aggregateEvidenceConfidence !== "low" || hasNonLowRouteConfidence);
+
+  const decision = buildPolicyDecision({
+    fallbackType,
+    coverageReport: input.coverageReport,
+    groundingCheck: input.groundingCheck,
+    okResults,
+    partialResults,
+    emptyResults,
+    errorResults,
+    hasSupport,
+    focusedStrong,
+    policySignals
+  });
+
+  const missingAnchors = detectMissingAnchors(input.userMessage);
+  const clarificationQuestions = buildClarificationQuestions({
+    mode: decision.mode,
+    missingAnchors,
+    coverageReport: input.coverageReport,
+    policySignals
+  });
+  const recommendedActions = buildRecommendedActions({
+    mode: decision.mode,
+    coverageReport: input.coverageReport,
+    policySignals,
+    limitationReasonCodes,
+    sourceRefs
+  });
+
+  const limitations = uniqueStrings(
+    [
+      ...limitationReasonCodes.map((code) => limitationReasonToText(code)),
+      ...extractLimitations(input.retrievalResults),
+      ...input.groundingCheck.reasons,
+      ...(policySignals.minimum_evidence_failed ? ["Minimum evidence gate failed for current scope."] : []),
+      ...(policySignals.broad_query_detected && policySignals.narrowing_strength === "weak"
+        ? ["Broad query remains weakly narrowed; precision is intentionally limited."]
+        : [])
+    ],
+    10
+  );
+  const openUncertainties = uniqueStrings(
+    [
+      ...input.groundingCheck.missing_requirements,
+      ...(decision.mode === "clarification_required" && missingAnchors.period ? ["missing_anchor:period"] : []),
+      ...(decision.mode === "clarification_required" && missingAnchors.account ? ["missing_anchor:account"] : []),
+      ...(decision.mode === "clarification_required" && missingAnchors.documentOrObject ? ["missing_anchor:document_or_object"] : []),
+      ...(decision.mode === "clarification_required" && missingAnchors.counterparty ? ["missing_anchor:counterparty"] : [])
+    ],
+    8
+  );
+
+  const mechanismStatus: AnswerStructureV11["mechanism_block"]["status"] =
+    mechanismNotes.length === 0
+      ? "unresolved"
+      : limitationReasonCodes.includes("missing_mechanism") || limitationReasonCodes.includes("heuristic_inference")
+        ? "limited"
+        : "grounded";
+
+  const answerStructure: AnswerStructureV11 = {
+    schema_version: "answer_structure_v1_1",
+    answer_summary: buildAnswerSummary(decision.mode),
+    direct_answer: buildDirectAnswer({
+      mode: decision.mode,
+      retrievalResults: input.retrievalResults,
+      policySignals
+    }),
+    mechanism_block: {
+      status: mechanismStatus,
+      mechanism_notes: mechanismNotes,
+      limitation_reason_codes: limitationReasonCodes
+    },
+    evidence_block: {
+      evidence_ids: uniqueStrings(evidenceItems.map((item) => item.evidence_id), 10),
+      source_refs: sourceRefs,
+      mechanism_notes: mechanismNotes,
+      coverage_note:
+        input.coverageReport.requirements_total > 0 &&
+        input.coverageReport.requirements_total === input.coverageReport.requirements_covered &&
+        input.coverageReport.requirements_uncovered.length === 0 &&
+        input.coverageReport.requirements_partially_covered.length === 0
+          ? "coverage_full_or_near_full"
+          : "coverage_partial_or_limited",
+      ...(claimEvidenceLinks.length > 0
+        ? {
+            claim_evidence_links: claimEvidenceLinks
+          }
+        : {})
+    },
+    uncertainty_block: {
+      open_uncertainties: openUncertainties,
+      limitations
+    },
+    next_step_block: {
+      recommended_actions: recommendedActions,
+      clarification_questions: clarificationQuestions
+    }
+  };
+
+  return {
+    assistant_reply: renderPolicyReply(answerStructure),
+    fallback_type: decision.fallback_type,
+    reply_type: decision.reply_type,
+    answer_structure_v11: answerStructure
+  };
+}
+
+function composeExplainableAnswer(input: ComposeAnswerInput, scopeLabel: "full" | "partial"): string {
+  const facts = extractTopFacts(input.retrievalResults);
+  const whyIncluded = extractWhyIncluded(input.retrievalResults);
+  const selectionReasons = extractSelectionReasons(input.retrievalResults);
+  const riskFactors = extractRiskFactors(input.retrievalResults);
+  const interpretation = extractBusinessInterpretation(input.retrievalResults);
+  const limitations = uniqueStrings([...extractLimitations(input.retrievalResults), ...input.groundingCheck.reasons]);
+  const nextSteps = suggestNextStep(input.requirements, input.coverageReport);
+
+  const lead =
+    scopeLabel === "full"
+      ? "Итог: запрос обработан по предмету, найденные объекты подтверждены данными контура."
+      : "Итог: запрос обработан частично, ниже подтвержденная часть и ограничения.";
+
+  return [
+    lead,
+    facts.length > 0 ? "Подтвержденные результаты:\n" + formatList(facts) : "",
+    whyIncluded.length > 0 ? "Почему это попало в ответ:\n" + formatList(whyIncluded) : "",
+    selectionReasons.length > 0 ? "Основание отбора:\n" + formatList(selectionReasons) : "",
+    riskFactors.length > 0 ? "Подтверждающие признаки:\n" + formatList(riskFactors) : "",
+    interpretation.length > 0 ? "Практический смысл:\n" + formatList(interpretation) : "",
+    limitations.length > 0 ? "Ограничения:\n" + formatList(limitations) : "",
+    nextSteps.length > 0 ? "Что проверить дальше:\n" + formatList(nextSteps) : ""
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export function composeAssistantAnswer(input: ComposeAnswerInput): ComposeAnswerOutput {
+  if (input.enableAnswerPolicyV11) {
+    return composeAssistantAnswerV11(input);
+  }
+
+  const fallbackType = fallbackFromSummary(input.routeSummary);
+  const okResults = input.retrievalResults.filter((item) => item.status === "ok");
+  const partialResults = input.retrievalResults.filter((item) => item.status === "partial");
+  const emptyResults = input.retrievalResults.filter((item) => item.status === "empty");
+  const errorResults = input.retrievalResults.filter((item) => item.status === "error");
+  const hasBroadMinimumEvidenceSignal = input.retrievalResults.some(
+    (item) => summaryBoolean(item, "broad_guard_applied") && summaryBoolean(item, "minimum_evidence_failed")
+  );
+  const hasBroadClarificationSignal = input.retrievalResults.some(
+    (item) =>
+      summaryBoolean(item, "broad_guard_applied") &&
+      summaryBoolean(item, "minimum_evidence_failed") &&
+      summaryString(item, "degraded_to") === "clarification"
+  );
+
+  if (fallbackType === "out_of_scope" && input.coverageReport.requirements_covered === 0) {
+    return {
+      assistant_reply:
+        "Я могу отвечать только по данным вашей учетной базы. Этот запрос выходит за рамки доступного контура.",
+      fallback_type: "out_of_scope",
+      reply_type: "out_of_scope"
+    };
+  }
+
+  if (input.groundingCheck.status === "route_mismatch_blocked") {
+    return {
+      assistant_reply: [
+        "Не отправляю финальный ответ, потому что предмет результата не совпал с предметом вопроса.",
+        "Уточните формулировку (например, нужный счет/участок учета), и я выполню повторный проход."
+      ].join("\n\n"),
+      fallback_type: "partial",
+      reply_type: "route_mismatch_blocked"
+    };
+  }
+
+  if (input.groundingCheck.status === "no_grounded_answer" && okResults.length === 0 && !hasBroadMinimumEvidenceSignal) {
+    return {
+      assistant_reply:
+        "Пока не удалось собрать предметно подтвержденный ответ по вашему вопросу. Нужны дополнительные уточнения по периоду или объекту проверки.",
+      fallback_type: fallbackType,
+      reply_type: "no_grounded_answer"
+    };
+  }
+
+  if (hasBroadClarificationSignal && okResults.length === 0 && partialResults.length === 0) {
+    return {
+      assistant_reply:
+        "Запрос слишком широкий для надежного вывода по текущей опоре. Уточните период, участок учета или объект проверки, после чего я дам предметный результат.",
+      fallback_type: "clarification",
+      reply_type: "clarification_required"
+    };
+  }
+
+  if (fallbackType === "clarification" && okResults.length === 0 && partialResults.length === 0) {
+    return {
+      assistant_reply: "Уточните, пожалуйста, период, счет, документ или контрагента, чтобы закрыть все части вопроса корректно.",
+      fallback_type: "clarification",
+      reply_type: "clarification_required"
+    };
+  }
+
+  if (errorResults.length > 0 && okResults.length === 0 && partialResults.length === 0) {
+    return {
+      assistant_reply: "Не удалось получить данные из контура. Попробуйте повторить запрос или уточнить формулировку.",
+      fallback_type: fallbackType,
+      reply_type: "backend_error"
+    };
+  }
+
+  if (partialResults.length > 0 && okResults.length === 0) {
+    return {
+      assistant_reply: composeExplainableAnswer(input, "partial"),
+      fallback_type: "partial",
+      reply_type: "partial_coverage"
+    };
+  }
+
+  if (okResults.length === 0 && partialResults.length === 0 && emptyResults.length > 0) {
+    return {
+      assistant_reply: "По заданному условию в текущем срезе данных явных проблемных записей не найдено.",
+      fallback_type: fallbackType,
+      reply_type: "empty_but_valid"
+    };
+  }
+
+  const hasPartialCoverage =
+    input.coverageReport.requirements_uncovered.length > 0 ||
+    input.coverageReport.requirements_partially_covered.length > 0 ||
+    input.coverageReport.clarification_needed_for.length > 0 ||
+    input.coverageReport.out_of_scope_requirements.length > 0 ||
+    input.groundingCheck.status === "partial" ||
+    errorResults.length > 0;
+
+  if (okResults.length > 0 && hasPartialCoverage) {
+    return {
+      assistant_reply: composeExplainableAnswer(input, "partial"),
+      fallback_type: "partial",
+      reply_type: "partial_coverage"
+    };
+  }
+
+  if (okResults.length > 0) {
+    return {
+      assistant_reply: composeExplainableAnswer(input, "full"),
+      fallback_type: "none",
+      reply_type: "factual_with_explanation"
+    };
+  }
+
+  return {
+    assistant_reply: "По текущему запросу не удалось построить обоснованный ответ. Уточните формулировку и попробуйте снова.",
+    fallback_type: "unknown",
+    reply_type: "backend_error"
+  };
+}

llm_normalizer/backend/src/services/assistantSessionLogger.ts

@@ -0,0 +1,261 @@
+import path from "path";
+import { ASSISTANT_SESSIONS_DIR } from "../config";
+import type { AssistantConversationItem, AssistantReplyType, AssistantSessionState } from "../types/assistant";
+import { ensureDir, writeJsonFile } from "../utils/files";
+
+interface AssistantTurnLogRecord {
+  turn_id: string;
+  started_at: string | null;
+  completed_at: string | null;
+  human_block: string;
+  human_readable: {
+    question_raw: string;
+    question_understood: string;
+    decomposition: string[];
+    answer: string;
+    reply_type: AssistantReplyType | null;
+  };
+  technical_json: {
+    trace_id: string | null;
+    user_message: AssistantConversationItem;
+    assistant_message: AssistantConversationItem;
+    debug: AssistantConversationItem["debug"];
+  };
+}
+
+interface AssistantSessionLogRecord {
+  schema_version: "assistant_session_log_v1";
+  session_id: string;
+  started_at: string;
+  updated_at: string;
+  counters: {
+    total_messages: number;
+    user_messages: number;
+    assistant_messages: number;
+  };
+  trace_ids: string[];
+  reply_types: AssistantReplyType[];
+  investigation_state: AssistantSessionState["investigation_state"];
+  turns: AssistantTurnLogRecord[];
+  conversation: AssistantConversationItem[];
+  last_assistant: {
+    message_id: string | null;
+    reply_type: AssistantReplyType | null;
+    trace_id: string | null;
+    created_at: string | null;
+  };
+}
+
+function unique(values: Array<string | null>): string[] {
+  return Array.from(new Set(values.filter((item): item is string => typeof item === "string" && item.length > 0)));
+}
+
+function toObject(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function toStringOrNull(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+function extractFragments(assistantItem: AssistantConversationItem): Array<Record<string, unknown>> {
+  if (!assistantItem.debug || !Array.isArray(assistantItem.debug.fragments)) {
+    return [];
+  }
+  return assistantItem.debug.fragments
+    .map((item) => toObject(item))
+    .filter((item): item is Record<string, unknown> => item !== null);
+}
+
+function extractNormalizedQuestion(userText: string, assistantItem: AssistantConversationItem): string {
+  const normalized = toObject(assistantItem.debug?.normalized);
+  if (normalized) {
+    const fromUserMessageRaw = toStringOrNull(normalized.user_message_raw);
+    if (fromUserMessageRaw) return fromUserMessageRaw;
+    const fromUserQuestionRaw = toStringOrNull(normalized.user_question_raw);
+    if (fromUserQuestionRaw) return fromUserQuestionRaw;
+    const fromNormalizedQuestion = toStringOrNull(normalized.normalized_question);
+    if (fromNormalizedQuestion) return fromNormalizedQuestion;
+  }
+
+  const fragments = extractFragments(assistantItem);
+  if (fragments.length > 0) {
+    const joined = fragments
+      .map((fragment) => toStringOrNull(fragment.normalized_fragment_text) ?? toStringOrNull(fragment.raw_fragment_text))
+      .filter((item): item is string => Boolean(item))
+      .join(" | ");
+    if (joined) {
+      return joined;
+    }
+  }
+
+  return userText;
+}
+
+function buildRouteLookup(assistantItem: AssistantConversationItem): Map<string, Record<string, unknown>> {
+  const output = new Map<string, Record<string, unknown>>();
+  if (!assistantItem.debug || !Array.isArray(assistantItem.debug.routes)) {
+    return output;
+  }
+  for (const route of assistantItem.debug.routes) {
+    const routeObject = toObject(route);
+    if (!routeObject) continue;
+    const fragmentId = toStringOrNull(routeObject.fragment_id);
+    if (!fragmentId) continue;
+    output.set(fragmentId, routeObject);
+  }
+  return output;
+}
+
+function buildDecompositionLines(assistantItem: AssistantConversationItem): string[] {
+  const fragments = extractFragments(assistantItem);
+  if (fragments.length === 0) {
+    return ["Фрагменты декомпозиции не выделены."];
+  }
+
+  const routeLookup = buildRouteLookup(assistantItem);
+
+  return fragments.map((fragment, index) => {
+    const fragmentId = toStringOrNull(fragment.fragment_id) ?? `F${index + 1}`;
+    const fragmentText =
+      toStringOrNull(fragment.normalized_fragment_text) ??
+      toStringOrNull(fragment.raw_fragment_text) ??
+      "текст фрагмента отсутствует";
+    const executionReadiness = toStringOrNull(fragment.execution_readiness);
+    const routeStatus = toStringOrNull(fragment.route_status);
+
+    const routeObject = routeLookup.get(fragmentId);
+    const route = toStringOrNull(routeObject?.route);
+    const noRouteReason =
+      toStringOrNull(fragment.no_route_reason) ?? toStringOrNull(routeObject?.no_route_reason);
+
+    const parts = [`${fragmentId}: ${fragmentText}`];
+    if (executionReadiness) parts.push(`execution_readiness=${executionReadiness}`);
+    if (routeStatus) parts.push(`route_status=${routeStatus}`);
+    if (route) parts.push(`route=${route}`);
+    if (noRouteReason) parts.push(`no_route_reason=${noRouteReason}`);
+
+    return parts.join("; ");
+  });
+}
+
+function toHumanBlock(input: {
+  questionRaw: string;
+  questionUnderstood: string;
+  decomposition: string[];
+  answer: string;
+}): string {
+  const lines: string[] = [];
+  lines.push(`Вопрос: ${input.questionRaw}`);
+  lines.push(`Понято как: ${input.questionUnderstood}`);
+  lines.push("Декомпозиция:");
+  lines.push(...input.decomposition.map((item) => `- ${item}`));
+  lines.push(`Ответ: ${input.answer}`);
+  return lines.join("\n");
+}
+
+function buildTurns(items: AssistantConversationItem[]): AssistantTurnLogRecord[] {
+  const turns: AssistantTurnLogRecord[] = [];
+  const pendingUsers: AssistantConversationItem[] = [];
+
+  for (const item of items) {
+    if (item.role === "user") {
+      pendingUsers.push(item);
+      continue;
+    }
+
+    const pairedUser = pendingUsers.shift();
+    if (!pairedUser) {
+      continue;
+    }
+
+    const questionRaw = pairedUser.text;
+    const questionUnderstood = extractNormalizedQuestion(questionRaw, item);
+    const decomposition = buildDecompositionLines(item);
+    const answer = item.text;
+
+    turns.push({
+      turn_id: `turn-${turns.length + 1}`,
+      started_at: pairedUser.created_at ?? null,
+      completed_at: item.created_at ?? null,
+      human_block: toHumanBlock({
+        questionRaw,
+        questionUnderstood,
+        decomposition,
+        answer
+      }),
+      human_readable: {
+        question_raw: questionRaw,
+        question_understood: questionUnderstood,
+        decomposition,
+        answer,
+        reply_type: item.reply_type
+      },
+      technical_json: {
+        trace_id: item.trace_id,
+        user_message: pairedUser,
+        assistant_message: item,
+        debug: item.debug
+      }
+    });
+  }
+
+  return turns;
+}
+
+export class AssistantSessionLogger {
+  constructor(private readonly rootDir: string = ASSISTANT_SESSIONS_DIR) {}
+
+  public persistSession(session: AssistantSessionState): void {
+    ensureDir(this.rootDir);
+    const filePath = path.resolve(this.rootDir, `${session.session_id}.json`);
+
+    const startedAt = session.items[0]?.created_at ?? session.updated_at;
+    const userMessages = session.items.filter((item) => item.role === "user").length;
+    const assistantMessages = session.items.filter((item) => item.role === "assistant").length;
+    const assistantItems = session.items.filter((item) => item.role === "assistant");
+    const lastAssistant = assistantItems.length > 0 ? assistantItems[assistantItems.length - 1] : null;
+
+    const traceIds = unique(session.items.map((item) => item.trace_id));
+    const replyTypes = Array.from(
+      new Set(
+        session.items
+          .map((item) => item.reply_type)
+          .filter((item): item is AssistantReplyType => typeof item === "string" && item.length > 0)
+      )
+    );
+    const turns = buildTurns(session.items);
+
+    const record: AssistantSessionLogRecord = {
+      schema_version: "assistant_session_log_v1",
+      session_id: session.session_id,
+      started_at: startedAt,
+      updated_at: session.updated_at,
+      counters: {
+        total_messages: session.items.length,
+        user_messages: userMessages,
+        assistant_messages: assistantMessages
+      },
+      trace_ids: traceIds,
+      reply_types: replyTypes,
+      investigation_state: session.investigation_state,
+      turns,
+      conversation: session.items,
+      last_assistant: {
+        message_id: lastAssistant?.message_id ?? null,
+        reply_type: lastAssistant?.reply_type ?? null,
+        trace_id: lastAssistant?.trace_id ?? null,
+        created_at: lastAssistant?.created_at ?? null
+      }
+    };
+
+    writeJsonFile(filePath, record);
+  }
+}

llm_normalizer/backend/src/services/assistantSessionStore.ts

@@ -0,0 +1,98 @@
+import { nanoid } from "nanoid";
+import type { AssistantConversationItem, AssistantSessionState } from "../types/assistant";
+import type { InvestigationState } from "../types/stage1Contracts";
+import { FEATURE_ASSISTANT_INVESTIGATION_STATE_V1 } from "../config";
+import { cloneInvestigationState, createEmptyInvestigationState } from "./investigationState";
+
+const MAX_ITEMS_PER_SESSION = 200;
+
+function cloneItem(item: AssistantConversationItem): AssistantConversationItem {
+  return {
+    ...item,
+    debug: item.debug ? { ...item.debug } : null
+  };
+}
+
+function cloneSession(state: AssistantSessionState): AssistantSessionState {
+  return {
+    session_id: state.session_id,
+    updated_at: state.updated_at,
+    items: state.items.map(cloneItem),
+    investigation_state: cloneInvestigationState(state.investigation_state)
+  };
+}
+
+function normalizeSessionShape(state: AssistantSessionState): AssistantSessionState {
+  const legacy = state as AssistantSessionState & {
+    investigation_state?: InvestigationState | null;
+    items?: AssistantConversationItem[];
+    updated_at?: string;
+  };
+  const normalizedItems = Array.isArray(legacy.items) ? legacy.items : [];
+  const investigationState =
+    FEATURE_ASSISTANT_INVESTIGATION_STATE_V1
+      ? legacy.investigation_state ?? createEmptyInvestigationState(state.session_id)
+      : legacy.investigation_state ?? null;
+
+  state.items = normalizedItems;
+  state.updated_at = typeof legacy.updated_at === "string" && legacy.updated_at.trim() ? legacy.updated_at : new Date().toISOString();
+  state.investigation_state = investigationState;
+  return state;
+}
+
+export class AssistantSessionStore {
+  private readonly sessions = new Map<string, AssistantSessionState>();
+
+  public ensureSession(sessionId?: string): AssistantSessionState {
+    const resolvedId = (sessionId ?? "").trim() || `asst-${nanoid(10)}`;
+    const existing = this.sessions.get(resolvedId);
+    if (existing) {
+      return cloneSession(normalizeSessionShape(existing));
+    }
+    const created: AssistantSessionState = {
+      session_id: resolvedId,
+      updated_at: new Date().toISOString(),
+      items: [],
+      investigation_state: FEATURE_ASSISTANT_INVESTIGATION_STATE_V1 ? createEmptyInvestigationState(resolvedId) : null
+    };
+    this.sessions.set(resolvedId, created);
+    return cloneSession(created);
+  }
+
+  public appendItem(sessionId: string, item: AssistantConversationItem): AssistantConversationItem {
+    const session = this.ensureMutableSession(sessionId);
+    session.items.push(item);
+    if (session.items.length > MAX_ITEMS_PER_SESSION) {
+      session.items = session.items.slice(session.items.length - MAX_ITEMS_PER_SESSION);
+    }
+    session.updated_at = new Date().toISOString();
+    return cloneItem(item);
+  }
+
+  public getSession(sessionId: string): AssistantSessionState | null {
+    const found = this.sessions.get(sessionId);
+    return found ? cloneSession(normalizeSessionShape(found)) : null;
+  }
+
+  public setInvestigationState(sessionId: string, state: InvestigationState | null): InvestigationState | null {
+    const session = this.ensureMutableSession(sessionId);
+    session.investigation_state = cloneInvestigationState(state);
+    session.updated_at = new Date().toISOString();
+    return cloneInvestigationState(session.investigation_state);
+  }
+
+  private ensureMutableSession(sessionId: string): AssistantSessionState {
+    const existing = this.sessions.get(sessionId);
+    if (existing) {
+      return normalizeSessionShape(existing);
+    }
+    const created: AssistantSessionState = {
+      session_id: sessionId,
+      updated_at: new Date().toISOString(),
+      items: [],
+      investigation_state: FEATURE_ASSISTANT_INVESTIGATION_STATE_V1 ? createEmptyInvestigationState(sessionId) : null
+    };
+    this.sessions.set(sessionId, created);
+    return created;
+  }
+}

llm_normalizer/backend/src/services/investigationState.ts

@@ -0,0 +1,199 @@
+import type {
+  AssistantRequirement,
+  RequirementCoverageReport,
+  UnifiedRetrievalResult
+} from "../types/assistant";
+import type { RouteHintSummary } from "../types/normalizer";
+import type {
+  InvestigationLastAnswerMode,
+  InvestigationNarrowingStatus,
+  InvestigationState
+} from "../types/stage1Contracts";
+import {
+  INVESTIGATION_MAX_EVIDENCE_REFS,
+  INVESTIGATION_MAX_PRIMARY_ACCOUNTS,
+  INVESTIGATION_MAX_REQUIREMENT_LINKS,
+  INVESTIGATION_MAX_UNCERTAINTIES,
+  INVESTIGATION_STATE_SCHEMA_VERSION
+} from "../types/stage1Contracts";
+
+interface UpdateInvestigationStateInput {
+  previous: InvestigationState;
+  timestamp: string;
+  questionId: string;
+  userMessage: string;
+  routeSummary: RouteHintSummary | null;
+  requirements: AssistantRequirement[];
+  coverageReport: RequirementCoverageReport;
+  retrievalResults: UnifiedRetrievalResult[];
+  replyType: InvestigationLastAnswerMode;
+}
+
+function uniqueStrings(values: string[]): string[] {
+  return Array.from(new Set(values.map((item) => item.trim()).filter(Boolean)));
+}
+
+function capStrings(values: string[], max: number): string[] {
+  return uniqueStrings(values).slice(0, max);
+}
+
+function detectAccounts(text: string): string[] {
+  return capStrings(text.match(/\b\d{2}(?:\.\d{2})?\b/g) ?? [], INVESTIGATION_MAX_PRIMARY_ACCOUNTS);
+}
+
+function detectPeriod(text: string): string | null {
+  const monthly = text.match(/\b(20\d{2})[-/.](0[1-9]|1[0-2])\b/);
+  if (monthly) return `${monthly[1]}-${monthly[2]}`;
+  const yearly = text.match(/\b(20\d{2})\b/);
+  if (yearly) return yearly[1];
+  return null;
+}
+
+function deriveDomain(routeSummary: RouteHintSummary | null): string | null {
+  if (!routeSummary) return null;
+  if (routeSummary.mode === "legacy_v1") {
+    return routeSummary.route_hint;
+  }
+  const routes = routeSummary.decisions.map((item) => item.route).filter((route) => route !== "no_route");
+  const uniqueRoutes = uniqueStrings(routes);
+  if (uniqueRoutes.length === 0) {
+    return "no_route";
+  }
+  return uniqueRoutes.join(",");
+}
+
+function deriveNarrowingStatus(
+  routeSummary: RouteHintSummary | null,
+  coverageReport: RequirementCoverageReport
+): InvestigationNarrowingStatus {
+  if (!routeSummary) {
+    return "unknown";
+  }
+
+  if (routeSummary.mode === "legacy_v1") {
+    return "not_needed";
+  }
+
+  if (routeSummary.fallback.type === "clarification" || coverageReport.clarification_needed_for.length > 0) {
+    return "needs_clarification";
+  }
+
+  const hasNoRoute = routeSummary.decisions.some((item) => item.route === "no_route");
+  if (hasNoRoute) {
+    return "broad_guarded";
+  }
+
+  return routeSummary.decisions.length > 1 ? "applied" : "not_needed";
+}
+
+function deriveQueryModeHint(routeSummary: RouteHintSummary | null): InvestigationState["query_mode_hint"] {
+  if (!routeSummary) {
+    return "investigation_candidate";
+  }
+  if (routeSummary.mode === "legacy_v1") {
+    return "direct_answer";
+  }
+  return routeSummary.fallback.type === "none" ? "direct_answer" : "investigation_candidate";
+}
+
+function collectEvidenceRefs(retrievalResults: UnifiedRetrievalResult[]): string[] {
+  const refs = retrievalResults.flatMap((result) => result.evidence.map((item) => item.evidence_id));
+  return capStrings(refs, INVESTIGATION_MAX_EVIDENCE_REFS);
+}
+
+function collectOpenUncertainties(
+  coverageReport: RequirementCoverageReport,
+  retrievalResults: UnifiedRetrievalResult[]
+): string[] {
+  const requirementNotes = [
+    ...coverageReport.requirements_uncovered.map((item) => `uncovered:${item}`),
+    ...coverageReport.requirements_partially_covered.map((item) => `partial:${item}`),
+    ...coverageReport.clarification_needed_for.map((item) => `clarify:${item}`),
+    ...coverageReport.out_of_scope_requirements.map((item) => `out_of_scope:${item}`)
+  ];
+  const limitationNotes = retrievalResults.flatMap((result) => result.limitations).slice(0, 6);
+  return capStrings([...requirementNotes, ...limitationNotes], INVESTIGATION_MAX_UNCERTAINTIES);
+}
+
+export function cloneInvestigationState(state: InvestigationState | null): InvestigationState | null {
+  if (!state) return null;
+  return {
+    ...state,
+    focus: {
+      ...state.focus,
+      primary_accounts: [...state.focus.primary_accounts]
+    },
+    evidence_refs: [...state.evidence_refs],
+    open_uncertainties: [...state.open_uncertainties],
+    followup_context: state.followup_context
+      ? {
+          ...state.followup_context,
+          referenced_requirement_ids: [...state.followup_context.referenced_requirement_ids]
+        }
+      : null
+  };
+}
+
+export function createEmptyInvestigationState(sessionId: string, timestamp = new Date().toISOString()): InvestigationState {
+  return {
+    schema_version: INVESTIGATION_STATE_SCHEMA_VERSION,
+    session_id: sessionId,
+    status: "idle",
+    turn_index: 0,
+    updated_at: timestamp,
+    question_id: null,
+    focus: {
+      domain: null,
+      period: null,
+      primary_accounts: [],
+      active_query_subject: null
+    },
+    narrowing_status: "unknown",
+    evidence_refs: [],
+    open_uncertainties: [],
+    last_answer_mode: null,
+    followup_context: null,
+    query_mode_hint: "direct_answer"
+  };
+}
+
+export function updateInvestigationState(input: UpdateInvestigationStateInput): InvestigationState {
+  const previous = input.previous;
+  const focusFromMessage = capStrings(detectAccounts(input.userMessage), INVESTIGATION_MAX_PRIMARY_ACCOUNTS);
+  const requirementIds = capStrings(
+    input.requirements.map((item) => item.requirement_id),
+    INVESTIGATION_MAX_REQUIREMENT_LINKS
+  );
+  const mainRequirement = input.requirements[0]?.requirement_text ?? input.userMessage;
+
+  return {
+    schema_version: INVESTIGATION_STATE_SCHEMA_VERSION,
+    session_id: previous.session_id,
+    status: "active",
+    turn_index: previous.turn_index + 1,
+    updated_at: input.timestamp,
+    question_id: input.questionId,
+    focus: {
+      domain: deriveDomain(input.routeSummary) ?? previous.focus.domain,
+      period: detectPeriod(input.userMessage) ?? previous.focus.period,
+      primary_accounts: capStrings(
+        [...focusFromMessage, ...previous.focus.primary_accounts],
+        INVESTIGATION_MAX_PRIMARY_ACCOUNTS
+      ),
+      active_query_subject: mainRequirement.slice(0, 180)
+    },
+    narrowing_status: deriveNarrowingStatus(input.routeSummary, input.coverageReport),
+    evidence_refs: capStrings(
+      [...collectEvidenceRefs(input.retrievalResults), ...previous.evidence_refs],
+      INVESTIGATION_MAX_EVIDENCE_REFS
+    ),
+    open_uncertainties: collectOpenUncertainties(input.coverageReport, input.retrievalResults),
+    last_answer_mode: input.replyType,
+    followup_context: {
+      previous_question_id: previous.question_id,
+      last_user_message: input.userMessage.slice(0, 240),
+      referenced_requirement_ids: requirementIds
+    },
+    query_mode_hint: deriveQueryModeHint(input.routeSummary)
+  };
+}

llm_normalizer/backend/src/services/openaiResponsesClient.ts

@@ -0,0 +1,213 @@
+import fs from "fs";
+import path from "path";
+import { DEFAULT_OPENAI_BASE_URL, SCHEMAS_DIR } from "../config";
+import { ApiError } from "../utils/http";
+
+export interface OpenAIRequestConfig {
+  apiKey: string;
+  model: string;
+  baseUrl?: string;
+  temperature?: number;
+  maxOutputTokens?: number;
+}
+
+export interface OpenAIResponseEnvelope {
+  raw: unknown;
+  outputText: string;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+  };
+}
+
+function extractUsage(raw: Record<string, unknown>): {
+  input_tokens: number;
+  output_tokens: number;
+  total_tokens: number;
+} {
+  const usage = (raw.usage ?? {}) as Record<string, unknown>;
+  const input = Number(usage.input_tokens ?? usage.prompt_tokens ?? 0);
+  const output = Number(usage.output_tokens ?? usage.completion_tokens ?? 0);
+  const total = Number(usage.total_tokens ?? input + output);
+  return {
+    input_tokens: Number.isFinite(input) ? input : 0,
+    output_tokens: Number.isFinite(output) ? output : 0,
+    total_tokens: Number.isFinite(total) ? total : 0
+  };
+}
+
+function extractOutputText(raw: Record<string, unknown>): string {
+  if (typeof raw.output_text === "string" && raw.output_text.trim().length > 0) {
+    return raw.output_text;
+  }
+
+  const output = raw.output;
+  if (Array.isArray(output)) {
+    for (const item of output) {
+      if (!item || typeof item !== "object") {
+        continue;
+      }
+      const content = (item as Record<string, unknown>).content;
+      if (!Array.isArray(content)) {
+        continue;
+      }
+      for (const c of content) {
+        if (!c || typeof c !== "object") {
+          continue;
+        }
+        const block = c as Record<string, unknown>;
+        if (typeof block.text === "string" && block.text.trim()) {
+          return block.text;
+        }
+      }
+    }
+  }
+
+  const response = raw.response;
+  if (response && typeof response === "object") {
+    const nested = response as Record<string, unknown>;
+    if (typeof nested.output_text === "string" && nested.output_text.trim().length > 0) {
+      return nested.output_text;
+    }
+  }
+
+  throw new ApiError("OPENAI_OUTPUT_PARSE_FAILED", "Не удалось извлечь output_text из Responses API ответа.", 502, raw);
+}
+
+function loadSchemaForTransport(schemaVersion: "v1" | "v2" | "v2_0_1" | "v2_0_2"): Record<string, unknown> {
+  const schemaFile =
+    schemaVersion === "v1"
+      ? "normalized_query_v1.json"
+      : schemaVersion === "v2_0_1"
+        ? "normalized_query_v2_0_1.json"
+        : schemaVersion === "v2_0_2"
+          ? "normalized_query_v2_0_2.json"
+        : "normalized_query_v2.json";
+  const schemaPath = path.resolve(SCHEMAS_DIR, schemaFile);
+  return JSON.parse(fs.readFileSync(schemaPath, "utf-8")) as Record<string, unknown>;
+}
+
+export class OpenAIResponsesClient {
+  public async testConnection(config: OpenAIRequestConfig): Promise<{ ok: boolean; model: string }> {
+    const payload = {
+      model: config.model,
+      input: [
+        {
+          role: "user",
+          content: [{ type: "input_text", text: "ping" }]
+        }
+      ],
+      max_output_tokens: 16
+    };
+    await this.post(config, payload);
+    return { ok: true, model: config.model };
+  }
+
+  public async normalize(
+    config: OpenAIRequestConfig,
+    prompt: {
+      systemPrompt: string;
+      developerPrompt: string;
+      domainPrompt: string;
+      userQuestion: string;
+      schemaVersion: "v1" | "v2" | "v2_0_1" | "v2_0_2";
+      controlledRetryInstruction?: string;
+    }
+  ): Promise<OpenAIResponseEnvelope> {
+    const schema = loadSchemaForTransport(prompt.schemaVersion);
+    const schemaName =
+      prompt.schemaVersion === "v1"
+        ? "normalized_query_v1"
+        : prompt.schemaVersion === "v2_0_1"
+          ? "normalized_query_v2_0_1"
+          : prompt.schemaVersion === "v2_0_2"
+            ? "normalized_query_v2_0_2"
+          : "normalized_query_v2";
+
+    const developerPrompt = prompt.controlledRetryInstruction
+      ? `${prompt.developerPrompt}\n\n${prompt.controlledRetryInstruction}`
+      : prompt.developerPrompt;
+
+    const payload = {
+      model: config.model,
+      temperature: config.temperature ?? 0,
+      max_output_tokens: config.maxOutputTokens ?? 700,
+      input: [
+        {
+          role: "system",
+          content: [{ type: "input_text", text: prompt.systemPrompt }]
+        },
+        {
+          role: "developer",
+          content: [{ type: "input_text", text: developerPrompt }]
+        },
+        {
+          role: "user",
+          content: [
+            {
+              type: "input_text",
+              text: `${prompt.domainPrompt}\n\nПользовательский вопрос:\n${prompt.userQuestion}`
+            }
+          ]
+        }
+      ],
+      text: {
+        format: {
+          type: "json_schema",
+          name: schemaName,
+          strict: true,
+          schema
+        }
+      }
+    };
+
+    const raw = await this.post(config, payload);
+    const outputText = extractOutputText(raw);
+    return {
+      raw,
+      outputText,
+      usage: extractUsage(raw)
+    };
+  }
+
+  private async post(config: OpenAIRequestConfig, payload: Record<string, unknown>): Promise<Record<string, unknown>> {
+    if (!config.apiKey || config.apiKey.trim().length < 10) {
+      throw new ApiError("OPENAI_API_KEY_MISSING", "API ключ OpenAI не задан или слишком короткий.", 400);
+    }
+
+    const url = `${(config.baseUrl ?? DEFAULT_OPENAI_BASE_URL).replace(/\/$/, "")}/responses`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${config.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(payload)
+    });
+
+    const text = await response.text();
+    let data: Record<string, unknown>;
+    try {
+      data = JSON.parse(text) as Record<string, unknown>;
+    } catch {
+      throw new ApiError("OPENAI_NON_JSON_RESPONSE", "OpenAI вернул не-JSON ответ.", 502, { status: response.status, body: text.slice(0, 500) });
+    }
+
+    if (!response.ok) {
+      const errorObj = (data.error ?? {}) as Record<string, unknown>;
+      throw new ApiError(
+        "OPENAI_REQUEST_FAILED",
+        String(errorObj.message ?? `OpenAI request failed with status ${response.status}`),
+        response.status,
+        {
+          status: response.status,
+          type: errorObj.type ?? null,
+          code: errorObj.code ?? null
+        }
+      );
+    }
+
+    return data;
+  }
+}

llm_normalizer/backend/src/services/promptBuilder.ts

@@ -0,0 +1,212 @@
+import fs from "fs";
+import path from "path";
+import { DEFAULT_PROMPT_VERSION, PROMPTS_DIR } from "../config";
+import type { PromptBundle, PromptPreset, PromptVersion } from "../types/preset";
+
+function readPromptFile(relativePath: string): string {
+  const filePath = path.resolve(PROMPTS_DIR, relativePath);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Prompt file not found: ${filePath}`);
+  }
+  return fs.readFileSync(filePath, "utf-8").trim();
+}
+
+interface BuiltinPromptPresetDefinition {
+  id: string;
+  name: string;
+  promptVersion: PromptVersion;
+  schemaNotes: string;
+  files: {
+    system: string;
+    developer: string;
+    domain: string;
+    fewshot: string;
+  };
+}
+
+const BUILTIN_PROMPT_PRESETS: Record<PromptVersion, BuiltinPromptPresetDefinition> = {
+  normalizer_v1: {
+    id: "default-normalizer-v1",
+    name: "Стандартный пресет NDC v1",
+    promptVersion: "normalizer_v1",
+    schemaNotes: "Используется схема normalized_query_v1. Строго соблюдать enum/required поля.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "default.txt"),
+      domain: path.join("domain", "default.txt"),
+      fewshot: path.join("fewshot", "default.txt")
+    }
+  },
+  normalizer_v1_1: {
+    id: "default-normalizer-v1_1",
+    name: "Стандартный пресет NDC v1.1",
+    promptVersion: "normalizer_v1_1",
+    schemaNotes:
+      "v1.1: усиленная taxonomy intent/route и confidence policy. Используется схема normalized_query_v1 без дополнительных полей.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "normalizer_v1_1.txt"),
+      domain: path.join("domain", "normalizer_domain_v1_1.txt"),
+      fewshot: path.join("fewshot", "normalizer_fewshot_v1_1.txt")
+    }
+  },
+  normalizer_v1_1_1: {
+    id: "default-normalizer-v1_1_1",
+    name: "Стандартный пресет NDC v1.1.1",
+    promptVersion: "normalizer_v1_1_1",
+    schemaNotes:
+      "v1.1.1: surgical patch для period_close_risk, exact drilldown requires и anomaly route escalation. Схема normalized_query_v1 без изменений.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "normalizer_v1_1_1.txt"),
+      domain: path.join("domain", "normalizer_domain_v1_1.txt"),
+      fewshot: path.join("fewshot", "normalizer_fewshot_v1_1_1.txt")
+    }
+  },
+  normalizer_v1_1_2: {
+    id: "default-normalizer-v1_1_2",
+    name: "Стандартный пресет NDC v1.1.2",
+    promptVersion: "normalizer_v1_1_2",
+    schemaNotes:
+      "v1.1.2: точечный patch границы heavy_analytical vs period_close_risk + confidence guard на boundary кейсах. Схема normalized_query_v1 без изменений.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "normalizer_v1_1_2.txt"),
+      domain: path.join("domain", "normalizer_domain_v1_1.txt"),
+      fewshot: path.join("fewshot", "normalizer_fewshot_v1_1_2.txt")
+    }
+  },
+  normalizer_v1_1_2_1: {
+    id: "default-normalizer-v1_1_2_1",
+    name: "Стандартный пресет NDC v1.1.2.1",
+    promptVersion: "normalizer_v1_1_2_1",
+    schemaNotes:
+      "v1.1.2.1: stable prompt baseline v1.1.2 + accounting-review phrasing anchors for 30-case validation pack. Схема normalized_query_v1 без изменений.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "normalizer_v1_1_2_1.txt"),
+      domain: path.join("domain", "normalizer_domain_v1_1.txt"),
+      fewshot: path.join("fewshot", "normalizer_fewshot_v1_1_2_1.txt")
+    }
+  },
+  normalizer_v2: {
+    id: "default-normalizer-v2",
+    name: "Стандартный пресет NDC v2",
+    promptVersion: "normalizer_v2",
+    schemaNotes:
+      "v2: decomposition-first pre-router. LLM returns fragments + scope + flags; deterministic routing happens in code. Схема normalized_query_v2.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "normalizer_v2.txt"),
+      domain: path.join("domain", "normalizer_domain_v1_1.txt"),
+      fewshot: path.join("fewshot", "normalizer_v2.txt")
+    }
+  },
+  normalizer_v2_0_1: {
+    id: "default-normalizer-v2_0_1",
+    name: "Стандартный пресет NDC v2.0.1",
+    promptVersion: "normalizer_v2_0_1",
+    schemaNotes:
+      "v2.0.1: clarification-threshold policy. Вопросы в контуре и с понятным route должны исполняться без лишних уточнений. Схема normalized_query_v2_0_1.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "normalizer_v2_0_1.txt"),
+      domain: path.join("domain", "normalizer_domain_v1_1.txt"),
+      fewshot: path.join("fewshot", "normalizer_v2_0_1.txt")
+    }
+  },
+  normalizer_v2_0_2: {
+    id: "default-normalizer-v2_0_2",
+    name: "Стандартный пресет NDC v2.0.2",
+    promptVersion: "normalizer_v2_0_2",
+    schemaNotes:
+      "v2.0.2: execution-state hardening + explicit route_status/no_route_reason. Схема normalized_query_v2_0_2.",
+    files: {
+      system: path.join("system", "default.txt"),
+      developer: path.join("developer", "normalizer_v2_0_2.txt"),
+      domain: path.join("domain", "normalizer_domain_v1_1.txt"),
+      fewshot: path.join("fewshot", "normalizer_v2_0_2.txt")
+    }
+  }
+};
+
+function isPromptVersion(value: string | undefined): value is PromptVersion {
+  return (
+    value === "normalizer_v1" ||
+    value === "normalizer_v1_1" ||
+    value === "normalizer_v1_1_1" ||
+    value === "normalizer_v1_1_2" ||
+    value === "normalizer_v1_1_2_1" ||
+    value === "normalizer_v2" ||
+    value === "normalizer_v2_0_1" ||
+    value === "normalizer_v2_0_2"
+  );
+}
+
+function resolvePromptVersion(requested?: string): PromptVersion {
+  if (isPromptVersion(requested)) {
+    return requested;
+  }
+  if (isPromptVersion(DEFAULT_PROMPT_VERSION)) {
+    return DEFAULT_PROMPT_VERSION;
+  }
+  return "normalizer_v2_0_2";
+}
+
+function loadBuiltinPreset(promptVersion: PromptVersion): PromptPreset {
+  const now = new Date().toISOString();
+  const definition = BUILTIN_PROMPT_PRESETS[promptVersion];
+  return {
+    id: definition.id,
+    name: definition.name,
+    createdAt: now,
+    updatedAt: now,
+    prompt_version: definition.promptVersion,
+    systemPrompt: readPromptFile(definition.files.system),
+    developerPrompt: readPromptFile(definition.files.developer),
+    domainPrompt: readPromptFile(definition.files.domain),
+    schemaNotes: definition.schemaNotes,
+    fewShotExamples: readPromptFile(definition.files.fewshot)
+  };
+}
+
+export function listBuiltinPromptPresets(): PromptPreset[] {
+  return (Object.keys(BUILTIN_PROMPT_PRESETS) as PromptVersion[]).map((version) => loadBuiltinPreset(version));
+}
+
+export function loadDefaultPrompts(promptVersion?: string): PromptPreset {
+  return loadBuiltinPreset(resolvePromptVersion(promptVersion));
+}
+
+export function buildPromptBundle(input: {
+  promptVersion?: string;
+  systemPrompt?: string;
+  developerPrompt?: string;
+  domainPrompt?: string;
+  schemaNotes?: string;
+  fewShotExamples?: string;
+}): PromptBundle {
+  const selectedPromptVersion = resolvePromptVersion(input.promptVersion);
+  const defaults = loadDefaultPrompts(selectedPromptVersion);
+  const systemPrompt = (input.systemPrompt ?? defaults.systemPrompt).trim();
+  const developerPrompt = (input.developerPrompt ?? defaults.developerPrompt).trim();
+  const domainPrompt = (input.domainPrompt ?? defaults.domainPrompt).trim();
+  const schemaNotes = (input.schemaNotes ?? defaults.schemaNotes ?? "").trim();
+  const fewShotExamples = (input.fewShotExamples ?? defaults.fewShotExamples ?? "").trim();
+  const prompt_version = (input.promptVersion ?? defaults.prompt_version).trim() || selectedPromptVersion;
+
+  const sections = [developerPrompt, `Schema notes:\n${schemaNotes}`];
+  if (fewShotExamples) {
+    sections.push(`Few-shot examples:\n${fewShotExamples}`);
+  }
+
+  return {
+    prompt_version,
+    systemPrompt,
+    developerPrompt,
+    domainPrompt,
+    schemaNotes,
+    fewShotExamples,
+    combinedDeveloperPrompt: sections.join("\n\n")
+  };
+}

llm_normalizer/backend/src/services/retrievalResultNormalizer.ts

@@ -0,0 +1,479 @@
+import type {
+  RetrievalConfidence,
+  RetrievalResultStatus,
+  RetrievalResultType,
+  UnifiedRetrievalResult
+} from "../types/assistant";
+import { FEATURE_ASSISTANT_EVIDENCE_ENRICHMENT_V1 } from "../config";
+import { EVIDENCE_SOURCE_REF_SCHEMA_VERSION } from "../types/stage1Contracts";
+import type {
+  EvidenceConfidence,
+  EvidenceItem,
+  EvidenceLimitationReasonCode,
+  EvidenceKind,
+  EvidencePointer,
+  EvidenceSourceRef
+} from "../types/stage1Contracts";
+
+interface RawRetrievalResult {
+  status?: string;
+  result_type?: string;
+  items?: unknown;
+  summary?: unknown;
+  evidence?: unknown;
+  why_included?: unknown;
+  selection_reason?: unknown;
+  risk_factors?: unknown;
+  business_interpretation?: unknown;
+  confidence?: unknown;
+  limitations?: unknown;
+  errors?: unknown;
+}
+
+function toObject(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function toStringOrNull(value: unknown): string | null {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function toNumberOrNull(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  return null;
+}
+
+function normalizeStatus(value: string | undefined): RetrievalResultStatus {
+  if (value === "ok" || value === "empty" || value === "partial" || value === "error") {
+    return value;
+  }
+  return "error";
+}
+
+function normalizeResultType(value: string | undefined): RetrievalResultType {
+  if (value === "list" || value === "summary" || value === "object" || value === "chain" || value === "ranking") {
+    return value;
+  }
+  return "summary";
+}
+
+function normalizeObjectArray(value: unknown): Array<Record<string, unknown>> {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((item) => (item && typeof item === "object" ? (item as Record<string, unknown>) : null))
+    .filter((item): item is Record<string, unknown> => item !== null);
+}
+
+function normalizeSummary(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  return value as Record<string, unknown>;
+}
+
+function normalizeErrors(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((item) => String(item));
+}
+
+function normalizeStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((item) => String(item));
+}
+
+function normalizeConfidence(value: unknown): RetrievalConfidence {
+  if (value === "high" || value === "medium" || value === "low") {
+    return value;
+  }
+  return "medium";
+}
+
+function parseEvidenceConfidence(value: unknown): EvidenceConfidence | null {
+  if (value === "high" || value === "medium" || value === "low") {
+    return value;
+  }
+  return null;
+}
+
+function normalizeEvidenceNamespace(value: unknown): EvidencePointer["source"]["namespace"] {
+  const normalized = toStringOrNull(value)?.toLowerCase();
+  if (!normalized) return "unknown";
+  if (normalized === "snapshot_2020" || normalized === "snapshot") return "snapshot_2020";
+  if (normalized === "assistant_derived" || normalized === "derived") return "assistant_derived";
+  return "unknown";
+}
+
+function inferEvidenceKind(item: Record<string, unknown>): EvidenceKind {
+  if (item.mechanism_of_failure !== undefined || item.failed_expected_edge !== undefined || item.expected_next_step !== undefined) {
+    return "mechanism_link";
+  }
+  if (item.risk_score !== undefined || item.zero_guid_values !== undefined || item.unknown_link_count !== undefined) {
+    return "anomaly_signal";
+  }
+  if (item.records_count !== undefined || item.operations_count !== undefined || item.document_refs_count !== undefined) {
+    return "aggregation";
+  }
+  if (item.limitation !== undefined || item.is_snapshot_limited !== undefined) {
+    return "limitation_note";
+  }
+  return "factual_anchor";
+}
+
+function inferMechanismNoteLegacy(kind: EvidenceKind, item: Record<string, unknown>): string {
+  const explicit = toStringOrNull(item.mechanism_note);
+  if (explicit) {
+    return explicit;
+  }
+  if (kind === "mechanism_link") {
+    const failure = toStringOrNull(item.mechanism_of_failure);
+    if (failure) return failure;
+    return "Mechanism link inferred from retrieval evidence.";
+  }
+  if (kind === "anomaly_signal") {
+    return "Anomaly signal inferred from risk-oriented fields.";
+  }
+  if (kind === "aggregation") {
+    return "Aggregated evidence item.";
+  }
+  if (kind === "limitation_note") {
+    return "Evidence includes explicit limitation hints.";
+  }
+  return "Factual evidence anchor.";
+}
+
+interface MechanismNoteResolution {
+  note: string | null;
+  reliable: boolean;
+}
+
+function resolveMechanismNote(kind: EvidenceKind, item: Record<string, unknown>): MechanismNoteResolution {
+  const explicit = toStringOrNull(item.mechanism_note);
+  if (explicit) {
+    return {
+      note: explicit,
+      reliable: true
+    };
+  }
+
+  if (kind === "mechanism_link") {
+    const failure = toStringOrNull(item.mechanism_of_failure);
+    if (failure) {
+      return {
+        note: failure,
+        reliable: true
+      };
+    }
+    const failedEdge = toStringOrNull(item.failed_expected_edge);
+    const expectedNext = toStringOrNull(item.expected_next_step);
+    const composed = [failedEdge ? `failed_edge=${failedEdge}` : null, expectedNext ? `expected_next_step=${expectedNext}` : null]
+      .filter((part): part is string => Boolean(part))
+      .join("; ");
+    if (composed) {
+      return {
+        note: composed,
+        reliable: true
+      };
+    }
+  }
+
+  if (!FEATURE_ASSISTANT_EVIDENCE_ENRICHMENT_V1) {
+    return {
+      note: inferMechanismNoteLegacy(kind, item),
+      reliable: false
+    };
+  }
+
+  return {
+    note: null,
+    reliable: false
+  };
+}
+
+function normalizeEvidenceSourceType(value: unknown, record: Record<string, unknown>): EvidenceItem["source_type"] {
+  const normalized = toStringOrNull(value);
+  if (normalized === "retrieval_item" || normalized === "retrieval_summary" || normalized === "derived") {
+    return normalized;
+  }
+  if (record.records_count !== undefined || record.operations_count !== undefined || record.document_refs_count !== undefined) {
+    return "retrieval_summary";
+  }
+  return "retrieval_item";
+}
+
+function readPointer(record: Record<string, unknown>): Record<string, unknown> {
+  const pointer = toObject(record.pointer);
+  return pointer ?? {};
+}
+
+interface NormalizedPointerResult {
+  pointer: EvidencePointer;
+  fallback_source_namespace: boolean;
+  fallback_source_entity: boolean;
+  fallback_source_id: boolean;
+}
+
+function normalizeEvidencePointer(
+  fragmentId: string,
+  route: string,
+  record: Record<string, unknown>,
+  index: number
+): NormalizedPointerResult {
+  const pointer = readPointer(record);
+  const source = toObject(pointer.source);
+  const locator = toObject(pointer.locator);
+
+  const sourceEntityCandidate = toStringOrNull(source?.entity) ?? toStringOrNull(record.source_entity);
+  const sourceEntity = sourceEntityCandidate ?? "unknown_entity";
+  const sourceIdCandidate = toStringOrNull(source?.id) ?? toStringOrNull(record.source_id);
+  const sourceId = sourceIdCandidate ?? `${route}:${fragmentId}:${index + 1}`;
+  const period = toStringOrNull(source?.period) ?? toStringOrNull(record.period);
+  const namespace = normalizeEvidenceNamespace(source?.namespace ?? record.source_namespace);
+
+  return {
+    pointer: {
+      fragment_id: toStringOrNull(pointer.fragment_id) ?? fragmentId,
+      route: toStringOrNull(pointer.route) ?? route,
+      source: {
+        namespace,
+        entity: sourceEntity,
+        id: sourceId,
+        period
+      },
+      locator: {
+        field_path: toStringOrNull(locator?.field_path) ?? toStringOrNull(record.field_path),
+        item_index: toNumberOrNull(locator?.item_index) ?? index
+      }
+    },
+    fallback_source_namespace: namespace === "unknown",
+    fallback_source_entity: sourceEntityCandidate === null,
+    fallback_source_id: sourceIdCandidate === null
+  };
+}
+
+function canonicalizeSourceRefPart(value: string | null): string {
+  return encodeURIComponent((value ?? "none").trim().toLowerCase());
+}
+
+function buildSourceRef(pointer: EvidencePointer): EvidenceSourceRef {
+  return {
+    schema_version: EVIDENCE_SOURCE_REF_SCHEMA_VERSION,
+    namespace: pointer.source.namespace,
+    entity: pointer.source.entity,
+    id: pointer.source.id,
+    period: pointer.source.period,
+    canonical_ref: [
+      EVIDENCE_SOURCE_REF_SCHEMA_VERSION,
+      canonicalizeSourceRefPart(pointer.source.namespace),
+      canonicalizeSourceRefPart(pointer.source.entity),
+      canonicalizeSourceRefPart(pointer.source.id),
+      canonicalizeSourceRefPart(pointer.source.period)
+    ].join("|")
+  };
+}
+
+function toBoolean(value: unknown): boolean {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return value !== 0;
+  if (typeof value === "string") {
+    const lowered = value.trim().toLowerCase();
+    return lowered === "true" || lowered === "1" || lowered === "yes";
+  }
+  return false;
+}
+
+function limitationCodeFromText(text: string): EvidenceLimitationReasonCode {
+  const lower = text.toLowerCase();
+  if (/(snapshot|read-only|read only)/i.test(lower)) {
+    return "snapshot_only";
+  }
+  if (/heuristic/i.test(lower)) {
+    return "heuristic_inference";
+  }
+  if (/mechanism/i.test(lower)) {
+    return "missing_mechanism";
+  }
+  if (/(guid|detail|specific)/i.test(lower)) {
+    return "insufficient_detail";
+  }
+  return "unknown";
+}
+
+interface LimitationResolutionInput {
+  record: Record<string, unknown>;
+  sourceType: EvidenceItem["source_type"];
+  evidenceKind: EvidenceKind;
+  mechanismReliable: boolean;
+  mechanismExpected: boolean;
+  pointerWeak: boolean;
+}
+
+function resolveEvidenceLimitation(input: LimitationResolutionInput): EvidenceItem["limitation"] {
+  const explicitLimitation = toStringOrNull(input.record.limitation);
+  if (explicitLimitation) {
+    return {
+      reason_code: limitationCodeFromText(explicitLimitation),
+      note: explicitLimitation
+    };
+  }
+  if (toBoolean(input.record.is_snapshot_limited)) {
+    return {
+      reason_code: "snapshot_only",
+      note: null
+    };
+  }
+  if (!FEATURE_ASSISTANT_EVIDENCE_ENRICHMENT_V1) {
+    return null;
+  }
+  if (input.mechanismExpected && !input.mechanismReliable) {
+    return {
+      reason_code: "missing_mechanism",
+      note: null
+    };
+  }
+  if (input.pointerWeak) {
+    return {
+      reason_code: "weak_source_mapping",
+      note: null
+    };
+  }
+  if (input.sourceType === "derived") {
+    return {
+      reason_code: "heuristic_inference",
+      note: null
+    };
+  }
+  if (input.evidenceKind === "limitation_note") {
+    return {
+      reason_code: "unknown",
+      note: null
+    };
+  }
+  return null;
+}
+
+function downgradeConfidence(value: EvidenceConfidence): EvidenceConfidence {
+  if (value === "high") return "medium";
+  if (value === "medium") return "low";
+  return "low";
+}
+
+interface ConfidenceResolutionInput {
+  explicitConfidence: EvidenceConfidence | null;
+  sourceType: EvidenceItem["source_type"];
+  mechanismReliable: boolean;
+  mechanismExpected: boolean;
+  limitation: EvidenceItem["limitation"];
+  pointerWeak: boolean;
+}
+
+function resolveEvidenceConfidence(input: ConfidenceResolutionInput): EvidenceConfidence {
+  if (!FEATURE_ASSISTANT_EVIDENCE_ENRICHMENT_V1) {
+    return input.explicitConfidence ?? "medium";
+  }
+
+  let confidence: EvidenceConfidence = input.explicitConfidence ?? (input.sourceType === "retrieval_item" ? "medium" : "low");
+
+  if (input.limitation?.reason_code === "missing_mechanism" || input.limitation?.reason_code === "weak_source_mapping") {
+    confidence = downgradeConfidence(confidence);
+  }
+  if (input.sourceType === "derived" && !input.explicitConfidence) {
+    confidence = "low";
+  }
+  if (input.mechanismExpected && !input.mechanismReliable) {
+    confidence = "low";
+  }
+  if (input.pointerWeak) {
+    confidence = "low";
+  }
+
+  return confidence;
+}
+
+function normalizeEvidenceItems(
+  fragmentId: string,
+  requirementIds: string[],
+  route: string,
+  value: unknown
+): EvidenceItem[] {
+  const records = normalizeObjectArray(value);
+  return records.map((record, index) => {
+    const evidenceId = toStringOrNull(record.evidence_id) ?? `ev-${fragmentId}-${index + 1}`;
+    const claimRef =
+      toStringOrNull(record.claim_ref) ??
+      (requirementIds[0] ? `requirement:${requirementIds[0]}` : `fragment:${fragmentId}`);
+    const evidenceKind = inferEvidenceKind(record);
+    const sourceType = normalizeEvidenceSourceType(record.source_type, record);
+    const pointerResult = normalizeEvidencePointer(fragmentId, route, record, index);
+    const mechanism = resolveMechanismNote(evidenceKind, record);
+    const mechanismExpected = evidenceKind === "mechanism_link" || evidenceKind === "anomaly_signal" || evidenceKind === "aggregation";
+    const pointerWeak =
+      pointerResult.fallback_source_namespace || pointerResult.fallback_source_entity || pointerResult.fallback_source_id;
+    const limitation = resolveEvidenceLimitation({
+      record,
+      sourceType,
+      evidenceKind,
+      mechanismReliable: mechanism.reliable,
+      mechanismExpected,
+      pointerWeak
+    });
+    const confidence = resolveEvidenceConfidence({
+      explicitConfidence: parseEvidenceConfidence(record.confidence),
+      sourceType,
+      mechanismReliable: mechanism.reliable,
+      mechanismExpected,
+      limitation,
+      pointerWeak
+    });
+
+    return {
+      evidence_id: evidenceId,
+      claim_ref: claimRef,
+      source_type: sourceType,
+      source_ref: buildSourceRef(pointerResult.pointer),
+      pointer: pointerResult.pointer,
+      evidence_kind: evidenceKind,
+      mechanism_note: mechanism.note,
+      confidence,
+      limitation,
+      payload: record
+    };
+  });
+}
+
+export function normalizeRetrievalResult(
+  fragmentId: string,
+  requirementIds: string[],
+  route: string,
+  raw: RawRetrievalResult
+): UnifiedRetrievalResult {
+  return {
+    fragment_id: fragmentId,
+    requirement_ids: requirementIds,
+    route,
+    status: normalizeStatus(raw.status),
+    result_type: normalizeResultType(raw.result_type),
+    items: normalizeObjectArray(raw.items),
+    summary: normalizeSummary(raw.summary),
+    evidence: normalizeEvidenceItems(fragmentId, requirementIds, route, raw.evidence),
+    why_included: normalizeStringArray(raw.why_included),
+    selection_reason: normalizeStringArray(raw.selection_reason),
+    risk_factors: normalizeStringArray(raw.risk_factors),
+    business_interpretation: normalizeStringArray(raw.business_interpretation),
+    confidence: normalizeConfidence(raw.confidence),
+    limitations: normalizeStringArray(raw.limitations),
+    errors: normalizeErrors(raw.errors)
+  };
+}

llm_normalizer/backend/src/services/routeHintAdapter.ts

@@ -0,0 +1,335 @@
+import type {
+  NoRouteReason,
+  NormalizedPayload,
+  NormalizedQueryV1,
+  NormalizedQueryV2,
+  NormalizedQueryV2_0_1,
+  NormalizedQueryV2_0_2,
+  RouteDecisionV2,
+  RouteHintSummary,
+  RouteHintSummaryV1,
+  RouteHintSummaryV2,
+  RouteStatus,
+  SoftAssumption
+} from "../types/normalizer";
+
+function toRouteHintSummaryV1(normalized: NormalizedQueryV1): RouteHintSummaryV1 {
+  return {
+    mode: "legacy_v1",
+    intent_class: normalized.intent_class,
+    route_hint: normalized.route_hint,
+    confidence: normalized.confidence.route_hint,
+    decision_flags: {
+      needs_cross_entity_join: normalized.requires.needs_cross_entity_join,
+      needs_causal_chain: normalized.requires.needs_causal_chain,
+      needs_exact_object_trace: normalized.requires.needs_exact_object_trace,
+      needs_ranking: normalized.requires.needs_ranking,
+      needs_anomaly_summary: normalized.requires.needs_anomaly_summary,
+      needs_runtime_truth: normalized.requires.needs_runtime_truth,
+      needs_period_cut: normalized.requires.needs_period_cut,
+      needs_evidence: normalized.requires.needs_evidence
+    },
+    period_scope: normalized.period_scope,
+    entities: {
+      domain_entities: normalized.domain_entities,
+      accounts_mentioned: normalized.accounts_mentioned,
+      documents_mentioned: normalized.documents_mentioned,
+      registers_mentioned: normalized.registers_mentioned
+    }
+  };
+}
+
+type V2Family = NormalizedQueryV2 | NormalizedQueryV2_0_1 | NormalizedQueryV2_0_2;
+type V2FamilyFragment = V2Family["fragments"][number];
+
+function reasonForNoRoute(noRouteReason: NoRouteReason | null | undefined): string {
+  if (noRouteReason === "out_of_scope") {
+    return "Fragment is out-of-scope for company-specific accounting contour.";
+  }
+  if (noRouteReason === "missing_mapping") {
+    return "Fragment is in-scope but route mapping is currently missing.";
+  }
+  if (noRouteReason === "unsupported_fragment_type") {
+    return "Fragment type is not supported by the current deterministic route map.";
+  }
+  return "Fragment requires clarification or is too underspecified for safe routing.";
+}
+
+function explicitRouteStatus(fragment: V2FamilyFragment): RouteStatus | null {
+  return "route_status" in fragment ? fragment.route_status : null;
+}
+
+function explicitNoRouteReason(fragment: V2FamilyFragment): NoRouteReason | null {
+  return "no_route_reason" in fragment ? fragment.no_route_reason : null;
+}
+
+function executionReadiness(fragment: V2FamilyFragment): RouteDecisionV2["execution_readiness"] {
+  return "execution_readiness" in fragment ? fragment.execution_readiness : null;
+}
+
+function clarificationReason(fragment: V2FamilyFragment): string | null {
+  return "clarification_reason" in fragment ? fragment.clarification_reason : null;
+}
+
+function softAssumptions(fragment: V2FamilyFragment): SoftAssumption[] {
+  return "soft_assumption_used" in fragment ? fragment.soft_assumption_used : [];
+}
+
+function buildNoRouteDecision(fragment: V2FamilyFragment, noRouteReason: NoRouteReason | null): RouteDecisionV2 {
+  return {
+    fragment_id: fragment.fragment_id,
+    domain_relevance: fragment.domain_relevance,
+    business_scope: fragment.business_scope,
+    candidate_labels: fragment.candidate_labels,
+    decision_flags: fragment.flags,
+    execution_readiness: executionReadiness(fragment),
+    clarification_reason: clarificationReason(fragment),
+    soft_assumption_used: softAssumptions(fragment),
+    route_status: "no_route",
+    no_route_reason: noRouteReason ?? "insufficient_specificity",
+    route: "no_route",
+    reason: reasonForNoRoute(noRouteReason)
+  };
+}
+
+function decideRouteForFragment(fragment: V2FamilyFragment): RouteDecisionV2 {
+  const status = explicitRouteStatus(fragment);
+  const noRouteReason = explicitNoRouteReason(fragment);
+  const readiness = executionReadiness(fragment);
+  const clarification = clarificationReason(fragment);
+  const soft = softAssumptions(fragment);
+
+  if (status === "no_route") {
+    return buildNoRouteDecision(fragment, noRouteReason);
+  }
+
+  if (readiness === "needs_clarification" || readiness === "no_route") {
+    return buildNoRouteDecision(fragment, noRouteReason ?? "insufficient_specificity");
+  }
+
+  if (fragment.domain_relevance !== "in_scope") {
+    return buildNoRouteDecision(fragment, "out_of_scope");
+  }
+
+  if (fragment.flags.asks_for_exact_object_trace) {
+    return {
+      fragment_id: fragment.fragment_id,
+      domain_relevance: fragment.domain_relevance,
+      business_scope: fragment.business_scope,
+      candidate_labels: fragment.candidate_labels,
+      decision_flags: fragment.flags,
+      execution_readiness: readiness,
+      clarification_reason: clarification,
+      soft_assumption_used: soft,
+      route_status: "routed",
+      no_route_reason: null,
+      route: "live_mcp_drilldown",
+      reason: "Exact object trace requested."
+    };
+  }
+
+  if (fragment.flags.asks_for_ranking_or_top || fragment.flags.asks_for_period_summary) {
+    return {
+      fragment_id: fragment.fragment_id,
+      domain_relevance: fragment.domain_relevance,
+      business_scope: fragment.business_scope,
+      candidate_labels: fragment.candidate_labels,
+      decision_flags: fragment.flags,
+      execution_readiness: readiness,
+      clarification_reason: clarification,
+      soft_assumption_used: soft,
+      route_status: "routed",
+      no_route_reason: null,
+      route: "batch_refresh_then_store",
+      reason: "Ranking/summary semantics require batch analytical route."
+    };
+  }
+
+  if (fragment.flags.has_multi_entity_scope && fragment.flags.asks_for_chain_explanation) {
+    return {
+      fragment_id: fragment.fragment_id,
+      domain_relevance: fragment.domain_relevance,
+      business_scope: fragment.business_scope,
+      candidate_labels: fragment.candidate_labels,
+      decision_flags: fragment.flags,
+      execution_readiness: readiness,
+      clarification_reason: clarification,
+      soft_assumption_used: soft,
+      route_status: "routed",
+      no_route_reason: null,
+      route: "hybrid_store_plus_live",
+      reason: "Multi-entity causal chain requested."
+    };
+  }
+
+  if (fragment.flags.asks_for_rule_check && !fragment.flags.asks_for_chain_explanation) {
+    return {
+      fragment_id: fragment.fragment_id,
+      domain_relevance: fragment.domain_relevance,
+      business_scope: fragment.business_scope,
+      candidate_labels: fragment.candidate_labels,
+      decision_flags: fragment.flags,
+      execution_readiness: readiness,
+      clarification_reason: clarification,
+      soft_assumption_used: soft,
+      route_status: "routed",
+      no_route_reason: null,
+      route: "store_feature_risk",
+      reason: "Rule-control check without causal decomposition."
+    };
+  }
+
+  if (
+    fragment.flags.asks_for_anomaly_scan &&
+    !fragment.flags.asks_for_ranking_or_top &&
+    !(fragment.flags.has_multi_entity_scope && fragment.flags.asks_for_chain_explanation)
+  ) {
+    return {
+      fragment_id: fragment.fragment_id,
+      domain_relevance: fragment.domain_relevance,
+      business_scope: fragment.business_scope,
+      candidate_labels: fragment.candidate_labels,
+      decision_flags: fragment.flags,
+      execution_readiness: readiness,
+      clarification_reason: clarification,
+      soft_assumption_used: soft,
+      route_status: "routed",
+      no_route_reason: null,
+      route: "store_feature_risk",
+      reason: "Anomaly scan without heavy ranking or causal chain."
+    };
+  }
+
+  if (status === "routed") {
+    return {
+      fragment_id: fragment.fragment_id,
+      domain_relevance: fragment.domain_relevance,
+      business_scope: fragment.business_scope,
+      candidate_labels: fragment.candidate_labels,
+      decision_flags: fragment.flags,
+      execution_readiness: readiness,
+      clarification_reason: clarification,
+      soft_assumption_used: soft,
+      route_status: "routed",
+      no_route_reason: null,
+      route: "store_canonical",
+      reason: "Routed fragment without deep analytical or causal signals."
+    };
+  }
+
+  return buildNoRouteDecision(fragment, "missing_mapping");
+}
+
+function fallbackMessageFor(type: RouteHintSummaryV2["fallback"]["type"]): string | null {
+  if (type === "out_of_scope") {
+    return "Я работаю только с данными и бухгалтерским контуром текущей компании. Запрос вне доступной предметной области.";
+  }
+  if (type === "clarification") {
+    return "Могу проверить это в контуре компании, но нужно уточнить период, документ, счет или участок учета.";
+  }
+  if (type === "partial") {
+    return "Обработаю только часть запроса, которая относится к данным компании. Остальное выходит за пределы доступного контура.";
+  }
+  return null;
+}
+
+export function simulateDeterministicRouting(normalized: V2Family): RouteHintSummaryV2 {
+  const decisions = normalized.fragments.map((fragment) => decideRouteForFragment(fragment));
+  const inScopeCount = decisions.filter((item) => item.domain_relevance === "in_scope").length;
+  const outOfScopeCount = decisions.filter((item) => item.domain_relevance === "out_of_scope").length;
+  const routedInScopeCount = decisions.filter((item) => item.domain_relevance === "in_scope" && item.route !== "no_route").length;
+  const clarificationInScopeCount = decisions.filter(
+    (item) => item.domain_relevance === "in_scope" && item.execution_readiness === "needs_clarification"
+  ).length;
+  const noRouteInScopeCount = decisions.filter((item) => item.domain_relevance === "in_scope" && item.route === "no_route").length;
+
+  let fallbackType: RouteHintSummaryV2["fallback"]["type"] = "none";
+  if (!normalized.message_in_scope || inScopeCount === 0) {
+    fallbackType = "out_of_scope";
+  } else if (routedInScopeCount === 0 && clarificationInScopeCount > 0) {
+    fallbackType = "clarification";
+  } else if (routedInScopeCount === 0 && noRouteInScopeCount > 0) {
+    fallbackType = "clarification";
+  } else if ((inScopeCount > 0 && outOfScopeCount > 0) || (routedInScopeCount > 0 && noRouteInScopeCount > 0)) {
+    fallbackType = "partial";
+  }
+
+  return {
+    mode: "deterministic_v2",
+    message_in_scope: normalized.message_in_scope,
+    scope_confidence: normalized.scope_confidence,
+    planner: {
+      total_fragments: normalized.fragments.length,
+      in_scope_fragments: inScopeCount,
+      out_of_scope_fragments: outOfScopeCount,
+      discarded_fragments: normalized.discarded_fragments.length,
+      contains_multiple_tasks: normalized.contains_multiple_tasks
+    },
+    decisions,
+    fallback: {
+      type: fallbackType,
+      message: fallbackMessageFor(fallbackType)
+    }
+  };
+}
+
+export function toRouteHintSummary(normalized: NormalizedPayload): RouteHintSummary {
+  if (
+    normalized.schema_version === "normalized_query_v2" ||
+    normalized.schema_version === "normalized_query_v2_0_1" ||
+    normalized.schema_version === "normalized_query_v2_0_2"
+  ) {
+    return simulateDeterministicRouting(normalized);
+  }
+  return toRouteHintSummaryV1(normalized);
+}
+
+export function toRouterInput(normalized: NormalizedPayload): Record<string, unknown> {
+  if (
+    normalized.schema_version === "normalized_query_v2" ||
+    normalized.schema_version === "normalized_query_v2_0_1" ||
+    normalized.schema_version === "normalized_query_v2_0_2"
+  ) {
+    return {
+      mode: "deterministic_v2",
+      message_in_scope: normalized.message_in_scope,
+      scope_confidence: normalized.scope_confidence,
+      contains_multiple_tasks: normalized.contains_multiple_tasks,
+      fragments: normalized.fragments.map((fragment) => ({
+        fragment_id: fragment.fragment_id,
+        domain_relevance: fragment.domain_relevance,
+        business_scope: fragment.business_scope,
+        execution_readiness: "execution_readiness" in fragment ? fragment.execution_readiness : null,
+        clarification_reason: "clarification_reason" in fragment ? fragment.clarification_reason : null,
+        soft_assumption_used: "soft_assumption_used" in fragment ? fragment.soft_assumption_used : [],
+        route_status: "route_status" in fragment ? fragment.route_status : null,
+        no_route_reason: "no_route_reason" in fragment ? fragment.no_route_reason : null,
+        flags: fragment.flags,
+        candidate_labels: fragment.candidate_labels,
+        confidence: fragment.confidence
+      }))
+    };
+  }
+
+  return {
+    mode: "legacy_v1",
+    intent_class: normalized.intent_class,
+    decision_flags: {
+      needs_cross_entity_join: normalized.requires.needs_cross_entity_join,
+      needs_causal_chain: normalized.requires.needs_causal_chain,
+      needs_exact_object_trace: normalized.requires.needs_exact_object_trace,
+      needs_ranking: normalized.requires.needs_ranking,
+      needs_anomaly_summary: normalized.requires.needs_anomaly_summary,
+      needs_runtime_truth: normalized.requires.needs_runtime_truth
+    },
+    route_hint: normalized.route_hint,
+    confidence: normalized.confidence.overall,
+    entities: {
+      domain_entities: normalized.domain_entities,
+      accounts_mentioned: normalized.accounts_mentioned,
+      documents_mentioned: normalized.documents_mentioned,
+      registers_mentioned: normalized.registers_mentioned
+    },
+    period_scope: normalized.period_scope
+  };
+}

llm_normalizer/backend/src/services/schemaValidator.ts

@@ -0,0 +1,59 @@
+import fs from "fs";
+import path from "path";
+import Ajv2020, { type ErrorObject, type ValidateFunction } from "ajv/dist/2020";
+import { SCHEMAS_DIR } from "../config";
+import type { NormalizedPayload, ValidationResult } from "../types/normalizer";
+
+type SchemaVersion = "v1" | "v2" | "v2_0_1" | "v2_0_2";
+
+const validators = new Map<SchemaVersion, ValidateFunction>();
+
+function schemaPath(version: SchemaVersion): string {
+  if (version === "v1") {
+    return path.resolve(SCHEMAS_DIR, "normalized_query_v1.json");
+  }
+  if (version === "v2_0_1") {
+    return path.resolve(SCHEMAS_DIR, "normalized_query_v2_0_1.json");
+  }
+  if (version === "v2_0_2") {
+    return path.resolve(SCHEMAS_DIR, "normalized_query_v2_0_2.json");
+  }
+  return path.resolve(SCHEMAS_DIR, "normalized_query_v2.json");
+}
+
+function loadValidator(version: SchemaVersion): ValidateFunction {
+  const cached = validators.get(version);
+  if (cached) {
+    return cached;
+  }
+  const raw = fs.readFileSync(schemaPath(version), "utf-8");
+  const schema = JSON.parse(raw);
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  const compiled = ajv.compile(schema);
+  validators.set(version, compiled);
+  return compiled;
+}
+
+function normalizeAjvErrors(errors: ErrorObject[] | null | undefined): string[] {
+  if (!errors || errors.length === 0) {
+    return [];
+  }
+  return errors.map((item) => `${item.instancePath || "/"} ${item.message ?? "validation error"}`.trim());
+}
+
+export function validateNormalized(payload: unknown, schemaVersion: SchemaVersion = "v1"): ValidationResult {
+  const check = loadValidator(schemaVersion);
+  const passed = check(payload);
+  return {
+    passed: Boolean(passed),
+    errors: passed ? [] : normalizeAjvErrors(check.errors)
+  };
+}
+
+export function assertNormalized(payload: unknown, schemaVersion: SchemaVersion = "v1"): NormalizedPayload {
+  const validation = validateNormalized(payload, schemaVersion);
+  if (!validation.passed) {
+    throw new Error(`Invalid normalized JSON: ${validation.errors.join("; ")}`);
+  }
+  return payload as NormalizedPayload;
+}

llm_normalizer/backend/src/services/traceLogger.ts

@@ -0,0 +1,125 @@
+import fs from "fs";
+import path from "path";
+import { EVAL_CASES_DIR, PRESETS_DIR, TRACES_DIR } from "../config";
+import { ensureDir, writeJsonFile } from "../utils/files";
+import type { PromptPreset } from "../types/preset";
+
+export interface TraceRecord {
+  trace_id: string;
+  timestamp: string;
+  model: string;
+  prompt_version: string;
+  schema_version: string;
+  case_id?: string;
+  user_question_raw: string;
+  context: Record<string, unknown>;
+  request_payload_redacted: Record<string, unknown>;
+  raw_model_response: unknown;
+  parsed_normalized_json: unknown;
+  validation_result: {
+    passed: boolean;
+    errors: string[];
+  };
+  route_hint_summary?: unknown;
+  route_hint: string | null;
+  confidence: string | null;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+  };
+  latency_ms: number;
+  expected_route?: string;
+  eval_label?: string;
+  eval_mode?: string;
+  request_count_for_case: number;
+}
+
+export interface HistoryListItem {
+  trace_id: string;
+  timestamp: string;
+  model: string;
+  question_short: string;
+  confidence: string | null;
+  validation_passed: boolean;
+  route_hint: string | null;
+  save_status: "saved";
+}
+
+function redactSecrets(payload: Record<string, unknown>): Record<string, unknown> {
+  const output = { ...payload };
+  delete output.apiKey;
+  return output;
+}
+
+export function saveTrace(record: TraceRecord): void {
+  ensureDir(TRACES_DIR);
+  const target = path.resolve(TRACES_DIR, `${record.trace_id}.json`);
+  writeJsonFile(target, record);
+}
+
+export function listTraces(limit = 100): HistoryListItem[] {
+  ensureDir(TRACES_DIR);
+  const files = fs
+    .readdirSync(TRACES_DIR)
+    .filter((item) => item.endsWith(".json"))
+    .sort((a, b) => {
+      const pa = path.resolve(TRACES_DIR, a);
+      const pb = path.resolve(TRACES_DIR, b);
+      return fs.statSync(pb).mtimeMs - fs.statSync(pa).mtimeMs;
+    })
+    .slice(0, limit);
+
+  return files.map((fileName) => {
+    const raw = fs.readFileSync(path.resolve(TRACES_DIR, fileName), "utf-8");
+    const item = JSON.parse(raw) as TraceRecord;
+    return {
+      trace_id: item.trace_id,
+      timestamp: item.timestamp,
+      model: item.model,
+      question_short: item.user_question_raw.slice(0, 110),
+      confidence: item.confidence,
+      validation_passed: item.validation_result.passed,
+      route_hint: item.route_hint,
+      save_status: "saved"
+    };
+  });
+}
+
+export function getTrace(traceId: string): TraceRecord | null {
+  ensureDir(TRACES_DIR);
+  const target = path.resolve(TRACES_DIR, `${traceId}.json`);
+  if (!fs.existsSync(target)) {
+    return null;
+  }
+  const raw = fs.readFileSync(target, "utf-8");
+  return JSON.parse(raw) as TraceRecord;
+}
+
+export function savePreset(preset: PromptPreset): void {
+  ensureDir(PRESETS_DIR);
+  writeJsonFile(path.resolve(PRESETS_DIR, `${preset.id}.json`), preset);
+}
+
+export function listPresets(): PromptPreset[] {
+  ensureDir(PRESETS_DIR);
+  return fs
+    .readdirSync(PRESETS_DIR)
+    .filter((item) => item.endsWith(".json"))
+    .map((fileName) => {
+      const raw = fs.readFileSync(path.resolve(PRESETS_DIR, fileName), "utf-8");
+      return JSON.parse(raw) as PromptPreset;
+    })
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+export function saveEvalCase(casePayload: Record<string, unknown>): string {
+  ensureDir(EVAL_CASES_DIR);
+  const id = String(casePayload.case_id ?? `NQ-${Date.now()}`);
+  writeJsonFile(path.resolve(EVAL_CASES_DIR, `${id}.json`), casePayload);
+  return id;
+}
+
+export function redactRequestPayload(payload: Record<string, unknown>): Record<string, unknown> {
+  return redactSecrets(payload);
+}

llm_normalizer/backend/src/types/accountingAgent.ts

@@ -0,0 +1,39 @@
+export type AgentStatus = "NONE" | "QUEUED" | "RUNNING" | "DONE" | "ERROR" | "STALE" | "CANCELLED";
+
+export interface RunRecord {
+  sessionId: string;
+  runId: string;
+  status: AgentStatus;
+  initiator: string;
+  source: string;
+  createdAt: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface TaskRecord {
+  taskId: string;
+  runId: string;
+  status: AgentStatus;
+  payload: Record<string, unknown>;
+  result?: Record<string, unknown>;
+  error?: {
+    code: string;
+    message: string;
+    details?: unknown;
+  };
+  source: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TraceEvent {
+  timestamp: string;
+  level: "info" | "warn" | "error";
+  service: string;
+  sessionId: string;
+  runId: string;
+  taskId: string | null;
+  eventType: string;
+  payload?: Record<string, unknown>;
+}

llm_normalizer/backend/src/types/assistant.ts

@@ -0,0 +1,147 @@
+import type { NormalizeRequestPayload, NormalizeResponsePayload, RouteHintSummary } from "./normalizer";
+import type { AnswerStructureV11, EvidenceItem, InvestigationState } from "./stage1Contracts";
+
+export type AssistantFallbackType = "none" | "out_of_scope" | "clarification" | "partial" | "unknown";
+export type AssistantReplyType =
+  | "factual"
+  | "factual_with_explanation"
+  | "partial_coverage"
+  | "clarification_required"
+  | "out_of_scope"
+  | "empty_but_valid"
+  | "no_grounded_answer"
+  | "route_mismatch_blocked"
+  | "backend_error";
+export type RetrievalResultStatus = "ok" | "empty" | "partial" | "error";
+export type RetrievalResultType = "list" | "summary" | "object" | "chain" | "ranking";
+export type RetrievalConfidence = "high" | "medium" | "low";
+
+export interface AssistantRequirement {
+  requirement_id: string;
+  source_fragment_id: string | null;
+  requirement_text: string;
+  subject_tokens: string[];
+  status: "covered" | "partially_covered" | "uncovered" | "clarification_needed" | "out_of_scope";
+  route: string | null;
+}
+
+export interface RequirementCoverageReport {
+  requirements_total: number;
+  requirements_covered: number;
+  requirements_uncovered: string[];
+  requirements_partially_covered: string[];
+  clarification_needed_for: string[];
+  out_of_scope_requirements: string[];
+}
+
+export interface AnswerGroundingCheck {
+  status: "grounded" | "partial" | "no_grounded_answer" | "route_mismatch_blocked";
+  route_subject_match: boolean;
+  missing_requirements: string[];
+  reasons: string[];
+  why_included_summary: string[];
+  selection_reason_summary: string[];
+}
+
+export interface FollowupStateUsageDebug {
+  applied: true;
+  reason: string;
+  state_turn_index: number;
+  context_patch: {
+    period_hint_from_state: boolean;
+    expected_route_from_state: boolean;
+    business_context_from_state: boolean;
+    question_augmented: boolean;
+  };
+}
+
+export interface AssistantMessageRequestPayload {
+  session_id?: string;
+  user_message?: string;
+  message?: string;
+  mode?: "assistant" | string;
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  temperature?: number;
+  maxOutputTokens?: number;
+  promptVersion?: string;
+  systemPrompt?: string;
+  developerPrompt?: string;
+  domainPrompt?: string;
+  fewShotExamples?: string;
+  context?: NormalizeRequestPayload["context"];
+  useMock?: boolean;
+}
+
+export interface UnifiedRetrievalResult {
+  fragment_id: string;
+  requirement_ids: string[];
+  route: string;
+  status: RetrievalResultStatus;
+  result_type: RetrievalResultType;
+  items: Array<Record<string, unknown>>;
+  summary: Record<string, unknown>;
+  evidence: EvidenceItem[];
+  why_included: string[];
+  selection_reason: string[];
+  risk_factors: string[];
+  business_interpretation: string[];
+  confidence: RetrievalConfidence;
+  limitations: string[];
+  errors: string[];
+}
+
+export interface AssistantDebugPayload {
+  trace_id: string;
+  prompt_version: string;
+  schema_version: string;
+  fallback_type: AssistantFallbackType;
+  route_summary: RouteHintSummary | null;
+  fragments: unknown[];
+  requirements_extracted: AssistantRequirement[];
+  coverage_report: RequirementCoverageReport;
+  routes: Array<Record<string, unknown>>;
+  retrieval_status: Array<{
+    fragment_id: string;
+    requirement_ids: string[];
+    route: string;
+    status: RetrievalResultStatus;
+    result_type: RetrievalResultType;
+  }>;
+  retrieval_results: UnifiedRetrievalResult[];
+  answer_grounding_check: AnswerGroundingCheck;
+  dropped_intent_segments: string[];
+  followup_state_usage?: FollowupStateUsageDebug;
+  answer_structure_v11: AnswerStructureV11 | null;
+  investigation_state_snapshot: InvestigationState | null;
+  normalized: NormalizeResponsePayload["normalized"];
+}
+
+export interface AssistantConversationItem {
+  message_id: string;
+  session_id: string;
+  role: "user" | "assistant";
+  text: string;
+  reply_type: AssistantReplyType | null;
+  created_at: string;
+  trace_id: string | null;
+  debug: AssistantDebugPayload | null;
+}
+
+export interface AssistantSessionState {
+  session_id: string;
+  updated_at: string;
+  items: AssistantConversationItem[];
+  investigation_state: InvestigationState | null;
+}
+
+export interface AssistantMessageResponsePayload {
+  ok: true;
+  session_id: string;
+  assistant_reply: string;
+  reply_type: AssistantReplyType;
+  conversation_item: AssistantConversationItem;
+  debug: AssistantDebugPayload;
+  conversation: AssistantConversationItem[];
+}

llm_normalizer/backend/src/types/assistantEval.ts

@@ -0,0 +1,31 @@
+import type { AssistantEvalBroadnessLevel, AssistantEvalQuestionType } from "./stage1Contracts";
+
+export type EvalTarget = "normalizer" | "assistant_stage1";
+
+export interface AssistantStage1SuiteCaseTurn {
+  user_message: string;
+}
+
+export interface AssistantStage1ExpectedHints {
+  expected_reply_type?: string;
+  expected_degraded_to?: "partial" | "clarification" | null;
+}
+
+export interface AssistantStage1SuiteCase {
+  case_id: string;
+  scenario_tag: string;
+  question_type: AssistantEvalQuestionType;
+  broadness_level: AssistantEvalBroadnessLevel;
+  turns: AssistantStage1SuiteCaseTurn[];
+  expected_hints?: AssistantStage1ExpectedHints;
+  notes?: string[];
+}
+
+export interface AssistantStage1SuiteFile {
+  suite_id: string;
+  suite_version: string;
+  schema_version?: string;
+  scenario_count: number;
+  case_ids: string[];
+  cases: AssistantStage1SuiteCase[];
+}

llm_normalizer/backend/src/types/normalizer.ts

@@ -0,0 +1,284 @@
+export type ConfidenceLevel = "high" | "medium" | "low";
+
+export type IntentClass =
+  | "heavy_analytical"
+  | "cross_entity"
+  | "drilldown_explain"
+  | "rule_based_account_control"
+  | "anomaly_probe"
+  | "period_close_risk"
+  | "ambiguous_human_query"
+  | "simple_factual";
+
+export type RouteHint =
+  | "store_canonical"
+  | "store_feature_risk"
+  | "hybrid_store_plus_live"
+  | "live_mcp_drilldown"
+  | "batch_refresh_then_store";
+
+export type DeterministicRouteHint = RouteHint | "no_route";
+
+export type PromptVersion =
+  | "normalizer_v1"
+  | "normalizer_v1_1"
+  | "normalizer_v1_1_1"
+  | "normalizer_v1_1_2"
+  | "normalizer_v1_1_2_1"
+  | "normalizer_v2"
+  | "normalizer_v2_0_1"
+  | "normalizer_v2_0_2";
+
+export type EvalRunMode = "standard" | "single-pass-strict";
+
+export interface NormalizedQueryV1 {
+  schema_version: "normalized_query_v1";
+  user_question_raw: string;
+  normalized_question: string;
+  intent_class: IntentClass;
+  business_problem_type: string;
+  domain_entities: string[];
+  accounts_mentioned: string[];
+  documents_mentioned: string[];
+  registers_mentioned: string[];
+  period_scope: {
+    type: "explicit" | "inferred" | "missing";
+    value: string | null;
+    confidence: ConfidenceLevel;
+  };
+  requires: {
+    needs_cross_entity_join: boolean;
+    needs_causal_chain: boolean;
+    needs_exact_object_trace: boolean;
+    needs_ranking: boolean;
+    needs_anomaly_summary: boolean;
+    needs_runtime_truth: boolean;
+    needs_period_cut: boolean;
+    needs_evidence: boolean;
+  };
+  expected_output_shape:
+    | "ranked_list"
+    | "evidence_chain"
+    | "anomaly_summary"
+    | "point_answer"
+    | "reconciliation_report"
+    | "prioritized_review_list";
+  route_hint: RouteHint;
+  ambiguities: Array<{
+    field: string;
+    reason: string;
+    severity: "low" | "medium" | "high";
+  }>;
+  confidence: {
+    overall: ConfidenceLevel;
+    intent_class: ConfidenceLevel;
+    route_hint: ConfidenceLevel;
+  };
+}
+
+export type V2DomainRelevance = "in_scope" | "out_of_scope" | "unclear";
+export type V2BusinessScope = "company_specific_accounting" | "generic_accounting" | "offtopic" | "unclear";
+export type ExecutionReadiness = "executable" | "executable_with_soft_assumptions" | "needs_clarification" | "no_route";
+export type SoftAssumption =
+  | "period_from_session_context"
+  | "company_scope_defaulted"
+  | "problem_scan_mode_enabled";
+export type RouteStatus = "routed" | "no_route";
+export type NoRouteReason = "out_of_scope" | "insufficient_specificity" | "missing_mapping" | "unsupported_fragment_type";
+
+export interface NormalizedFragmentV2 {
+  fragment_id: string;
+  raw_fragment_text: string;
+  normalized_fragment_text: string;
+  domain_relevance: V2DomainRelevance;
+  business_scope: V2BusinessScope;
+  entity_hints: string[];
+  account_hints: string[];
+  document_hints: string[];
+  register_hints: string[];
+  time_scope: {
+    type: "explicit" | "inferred" | "missing";
+    value: string | null;
+    confidence: ConfidenceLevel;
+  };
+  flags: {
+    has_multi_entity_scope: boolean;
+    asks_for_chain_explanation: boolean;
+    asks_for_ranking_or_top: boolean;
+    asks_for_period_summary: boolean;
+    asks_for_rule_check: boolean;
+    asks_for_anomaly_scan: boolean;
+    asks_for_exact_object_trace: boolean;
+    asks_for_evidence: boolean;
+    mentions_period_close_context: boolean;
+  };
+  candidate_labels: IntentClass[];
+  confidence: ConfidenceLevel;
+}
+
+export interface NormalizedFragmentV2_0_1 extends NormalizedFragmentV2 {
+  execution_readiness: ExecutionReadiness;
+  clarification_reason: string | null;
+  soft_assumption_used: SoftAssumption[];
+}
+
+export interface NormalizedFragmentV2_0_2 extends NormalizedFragmentV2_0_1 {
+  route_status: RouteStatus;
+  no_route_reason: NoRouteReason | null;
+}
+
+export interface DiscardedFragmentV2 {
+  raw_fragment_text: string;
+  reason: string;
+}
+
+export interface NormalizedQueryV2 {
+  schema_version: "normalized_query_v2";
+  user_message_raw: string;
+  message_in_scope: boolean;
+  scope_confidence: ConfidenceLevel;
+  contains_multiple_tasks: boolean;
+  fragments: NormalizedFragmentV2[];
+  discarded_fragments: DiscardedFragmentV2[];
+  global_notes: {
+    needs_clarification: boolean;
+    clarification_reason: string | null;
+  };
+}
+
+export interface NormalizedQueryV2_0_1 {
+  schema_version: "normalized_query_v2_0_1";
+  user_message_raw: string;
+  message_in_scope: boolean;
+  scope_confidence: ConfidenceLevel;
+  contains_multiple_tasks: boolean;
+  fragments: NormalizedFragmentV2_0_1[];
+  discarded_fragments: DiscardedFragmentV2[];
+  global_notes: {
+    needs_clarification: boolean;
+    clarification_reason: string | null;
+  };
+}
+
+export interface NormalizedQueryV2_0_2 {
+  schema_version: "normalized_query_v2_0_2";
+  user_message_raw: string;
+  message_in_scope: boolean;
+  scope_confidence: ConfidenceLevel;
+  contains_multiple_tasks: boolean;
+  fragments: NormalizedFragmentV2_0_2[];
+  discarded_fragments: DiscardedFragmentV2[];
+  global_notes: {
+    needs_clarification: boolean;
+    clarification_reason: string | null;
+  };
+}
+
+export interface RouteHintSummaryV1 {
+  mode: "legacy_v1";
+  intent_class: IntentClass;
+  route_hint: RouteHint;
+  confidence: ConfidenceLevel;
+  decision_flags: {
+    needs_cross_entity_join: boolean;
+    needs_causal_chain: boolean;
+    needs_exact_object_trace: boolean;
+    needs_ranking: boolean;
+    needs_anomaly_summary: boolean;
+    needs_runtime_truth: boolean;
+    needs_period_cut: boolean;
+    needs_evidence: boolean;
+  };
+  period_scope: NormalizedQueryV1["period_scope"];
+  entities: {
+    domain_entities: string[];
+    accounts_mentioned: string[];
+    documents_mentioned: string[];
+    registers_mentioned: string[];
+  };
+}
+
+export interface RouteDecisionV2 {
+  fragment_id: string;
+  domain_relevance: V2DomainRelevance;
+  business_scope: V2BusinessScope;
+  candidate_labels: IntentClass[];
+  decision_flags: NormalizedFragmentV2["flags"];
+  execution_readiness?: ExecutionReadiness | null;
+  clarification_reason?: string | null;
+  soft_assumption_used?: SoftAssumption[];
+  route_status?: RouteStatus | null;
+  no_route_reason?: NoRouteReason | null;
+  route: DeterministicRouteHint;
+  reason: string;
+}
+
+export interface RouteHintSummaryV2 {
+  mode: "deterministic_v2";
+  message_in_scope: boolean;
+  scope_confidence: ConfidenceLevel;
+  planner: {
+    total_fragments: number;
+    in_scope_fragments: number;
+    out_of_scope_fragments: number;
+    discarded_fragments: number;
+    contains_multiple_tasks: boolean;
+  };
+  decisions: RouteDecisionV2[];
+  fallback: {
+    type: "none" | "out_of_scope" | "clarification" | "partial";
+    message: string | null;
+  };
+}
+
+export type RouteHintSummary = RouteHintSummaryV1 | RouteHintSummaryV2;
+export type NormalizedPayload = NormalizedQueryV1 | NormalizedQueryV2 | NormalizedQueryV2_0_1 | NormalizedQueryV2_0_2;
+
+export interface NormalizeRequestPayload {
+  apiKey?: string;
+  model?: string;
+  baseUrl?: string;
+  temperature?: number;
+  maxOutputTokens?: number;
+  promptVersion?: PromptVersion | string;
+  systemPrompt?: string;
+  developerPrompt?: string;
+  domainPrompt?: string;
+  schemaVersion?: string;
+  userQuestion: string;
+  context?: {
+    period_hint?: string;
+    business_context?: string;
+    expected_route?: RouteHint;
+    eval_label?: string;
+    case_id?: string;
+    eval_mode?: EvalRunMode;
+  };
+  fewShotExamples?: string;
+  saveAsTestCase?: boolean;
+  useMock?: boolean;
+  retryPolicy?: "default" | "single-pass-strict";
+}
+
+export interface ValidationResult {
+  passed: boolean;
+  errors: string[];
+}
+
+export interface NormalizeResponsePayload {
+  trace_id: string;
+  ok: boolean;
+  normalized: NormalizedPayload | null;
+  route_hint_summary: RouteHintSummary | null;
+  raw_model_output: unknown;
+  validation: ValidationResult;
+  usage: {
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+  };
+  latency_ms: number;
+  prompt_version: string;
+  schema_version: string;
+  request_count_for_case: number;
+}

llm_normalizer/backend/src/types/preset.ts

@@ -0,0 +1,32 @@
+export type PromptVersion =
+  | "normalizer_v1"
+  | "normalizer_v1_1"
+  | "normalizer_v1_1_1"
+  | "normalizer_v1_1_2"
+  | "normalizer_v1_1_2_1"
+  | "normalizer_v2"
+  | "normalizer_v2_0_1"
+  | "normalizer_v2_0_2";
+
+export interface PromptPreset {
+  id: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+  prompt_version: PromptVersion | string;
+  systemPrompt: string;
+  developerPrompt: string;
+  domainPrompt: string;
+  schemaNotes?: string;
+  fewShotExamples?: string;
+}
+
+export interface PromptBundle {
+  prompt_version: PromptVersion | string;
+  systemPrompt: string;
+  developerPrompt: string;
+  domainPrompt: string;
+  schemaNotes: string;
+  fewShotExamples: string;
+  combinedDeveloperPrompt: string;
+}

llm_normalizer/backend/src/types/stage1Contracts.ts

@@ -0,0 +1,216 @@
+export const INVESTIGATION_STATE_SCHEMA_VERSION = "investigation_state_v1" as const;
+export const ANSWER_STRUCTURE_SCHEMA_VERSION = "answer_structure_v1_1" as const;
+export const ASSISTANT_EVAL_RECORD_SCHEMA_VERSION = "assistant_eval_record_v0_1" as const;
+export const EVIDENCE_SOURCE_REF_SCHEMA_VERSION = "evidence_source_ref_v1" as const;
+
+export const INVESTIGATION_MAX_EVIDENCE_REFS = 24;
+export const INVESTIGATION_MAX_UNCERTAINTIES = 12;
+export const INVESTIGATION_MAX_PRIMARY_ACCOUNTS = 8;
+export const INVESTIGATION_MAX_REQUIREMENT_LINKS = 8;
+
+export type InvestigationNarrowingStatus = "unknown" | "not_needed" | "applied" | "needs_clarification" | "broad_guarded";
+export type InvestigationQueryModeHint = "direct_answer" | "investigation_candidate";
+export type InvestigationLastAnswerMode =
+  | "factual"
+  | "factual_with_explanation"
+  | "partial_coverage"
+  | "clarification_required"
+  | "out_of_scope"
+  | "empty_but_valid"
+  | "no_grounded_answer"
+  | "route_mismatch_blocked"
+  | "backend_error"
+  | null;
+
+export interface InvestigationStateFocus {
+  domain: string | null;
+  period: string | null;
+  primary_accounts: string[];
+  active_query_subject: string | null;
+}
+
+export interface InvestigationFollowupContext {
+  previous_question_id: string | null;
+  last_user_message: string;
+  referenced_requirement_ids: string[];
+}
+
+export interface InvestigationState {
+  schema_version: typeof INVESTIGATION_STATE_SCHEMA_VERSION;
+  session_id: string;
+  status: "idle" | "active";
+  turn_index: number;
+  updated_at: string;
+  question_id: string | null;
+  focus: InvestigationStateFocus;
+  narrowing_status: InvestigationNarrowingStatus;
+  evidence_refs: string[];
+  open_uncertainties: string[];
+  last_answer_mode: InvestigationLastAnswerMode;
+  followup_context: InvestigationFollowupContext | null;
+  query_mode_hint: InvestigationQueryModeHint;
+}
+
+export type EvidenceSourceNamespace = "snapshot_2020" | "assistant_derived" | "unknown";
+
+export interface EvidencePointer {
+  fragment_id: string;
+  route: string;
+  source: {
+    namespace: EvidenceSourceNamespace;
+    entity: string;
+    id: string;
+    period: string | null;
+  };
+  locator: {
+    field_path: string | null;
+    item_index: number | null;
+  };
+}
+
+export interface EvidenceSourceRef {
+  schema_version: typeof EVIDENCE_SOURCE_REF_SCHEMA_VERSION;
+  namespace: EvidenceSourceNamespace;
+  entity: string;
+  id: string;
+  period: string | null;
+  canonical_ref: string;
+}
+
+export type EvidenceKind = "factual_anchor" | "aggregation" | "anomaly_signal" | "mechanism_link" | "limitation_note";
+export type EvidenceConfidence = "high" | "medium" | "low";
+export type EvidenceLimitationReasonCode =
+  | "snapshot_only"
+  | "heuristic_inference"
+  | "missing_mechanism"
+  | "weak_source_mapping"
+  | "insufficient_detail"
+  | "unknown";
+
+export interface EvidenceLimitation {
+  reason_code: EvidenceLimitationReasonCode;
+  note: string | null;
+}
+
+export interface EvidenceItem {
+  evidence_id: string;
+  claim_ref: string;
+  source_type: "retrieval_item" | "retrieval_summary" | "derived";
+  source_ref: EvidenceSourceRef;
+  pointer: EvidencePointer;
+  evidence_kind: EvidenceKind;
+  mechanism_note: string | null;
+  confidence: EvidenceConfidence;
+  limitation: EvidenceLimitation | null;
+  payload: Record<string, unknown>;
+}
+
+export interface AnswerStructureV11 {
+  schema_version: typeof ANSWER_STRUCTURE_SCHEMA_VERSION;
+  answer_summary: string;
+  direct_answer: string;
+  mechanism_block: {
+    status: "grounded" | "limited" | "unresolved";
+    mechanism_notes: string[];
+    limitation_reason_codes: EvidenceLimitationReasonCode[];
+  };
+  evidence_block: {
+    evidence_ids: string[];
+    source_refs?: string[];
+    mechanism_notes: string[];
+    coverage_note: string;
+    claim_evidence_links?: Array<{
+      claim_ref: string;
+      evidence_ids: string[];
+    }>;
+  };
+  uncertainty_block: {
+    open_uncertainties: string[];
+    limitations: string[];
+  };
+  next_step_block: {
+    recommended_actions: string[];
+    clarification_questions: string[];
+  };
+}
+
+export type AssistantEvalQuestionType = "direct" | "broad" | "followup" | "multi_intent" | "clarification" | "out_of_scope";
+export type AssistantEvalBroadnessLevel = "low" | "medium" | "high";
+export type AssistantEvalNarrowingResult = "not_required" | "applied" | "clarification_requested" | "failed";
+
+export interface AssistantEvalMetricVector {
+  retrieval_differentiation_rate: number | null;
+  generic_explanation_rate: number | null;
+  accountant_actionability_score: number | null;
+  false_confidence_rate: number | null;
+  broad_answer_rate: number | null;
+  mechanism_specificity_score: number | null;
+  followup_context_retention_score: number | null;
+}
+
+export interface AssistantEvalRecord {
+  schema_version: typeof ASSISTANT_EVAL_RECORD_SCHEMA_VERSION;
+  created_at: string;
+  case_id: string;
+  scenario_tag?: string;
+  session_id: string | null;
+  trace_id: string | null;
+  question_type: AssistantEvalQuestionType;
+  broadness_level: AssistantEvalBroadnessLevel;
+  narrowing_result: AssistantEvalNarrowingResult;
+  evidence_quality_score: number | null;
+  genericness_score: number | null;
+  accountant_usefulness_score: number | null;
+  accountant_metrics: AssistantEvalMetricVector;
+  raw_signals?: Record<string, unknown>;
+  metric_subscores?: Partial<Record<keyof AssistantEvalMetricVector, number | null>>;
+  limitations?: string[];
+  notes: string[];
+}
+
+export type AccountantMetricName = keyof AssistantEvalMetricVector;
+export type AccountantMetricRubricScore = 0 | 1 | 2 | 3 | 4 | 5;
+
+export interface AccountantMetricRubricBand {
+  score: AccountantMetricRubricScore;
+  label: string;
+  description: string;
+}
+
+export const ACCOUNTANT_SCORING_RUBRIC_V01: Record<AccountantMetricName, AccountantMetricRubricBand[]> = {
+  retrieval_differentiation_rate: [
+    { score: 0, label: "No Differentiation", description: "Ответы почти одинаковые для разных кейсов." },
+    { score: 3, label: "Partial Differentiation", description: "Различия есть, но по механизмам недостаточно стабильны." },
+    { score: 5, label: "Strong Differentiation", description: "Ответы устойчиво различаются по предмету и механизму." }
+  ],
+  generic_explanation_rate: [
+    { score: 0, label: "Mostly Generic", description: "Преобладают общие объяснения без локальной опоры." },
+    { score: 3, label: "Mixed", description: "Есть и предметные, и общие блоки объяснения." },
+    { score: 5, label: "Mostly Specific", description: "Объяснение в основном case-specific и операбельно." }
+  ],
+  accountant_actionability_score: [
+    { score: 0, label: "Not Actionable", description: "Бухгалтер не получает понятного следующего шага." },
+    { score: 3, label: "Partially Actionable", description: "Следующий шаг есть, но недостаточно конкретен." },
+    { score: 5, label: "Actionable", description: "Есть конкретные проверяемые действия и приоритет." }
+  ],
+  false_confidence_rate: [
+    { score: 0, label: "High False Confidence", description: "Часто дается уверенный тон при слабой опоре." },
+    { score: 3, label: "Moderate False Confidence", description: "Периодически встречается избыточная уверенность." },
+    { score: 5, label: "Low False Confidence", description: "Неопределенность обозначается честно и вовремя." }
+  ],
+  broad_answer_rate: [
+    { score: 0, label: "Broad by Default", description: "Часто даются широкие ответы без controlled narrowing." },
+    { score: 3, label: "Partially Controlled", description: "Broad-ответы периодически сужаются, но не всегда." },
+    { score: 5, label: "Controlled", description: "Broad-ответы редки и сопровождаются корректным сужением." }
+  ],
+  mechanism_specificity_score: [
+    { score: 0, label: "No Mechanism", description: "Есть только лейблы без механики поломки." },
+    { score: 3, label: "Partial Mechanism", description: "Механизм описан частично, без полной связки." },
+    { score: 5, label: "Mechanism-Aware", description: "Механизм поломки и опорные объекты связаны явно." }
+  ],
+  followup_context_retention_score: [
+    { score: 0, label: "Context Lost", description: "Follow-up теряет фокус текущего разбора." },
+    { score: 3, label: "Context Partial", description: "Фокус удерживается частично, с дрейфом." },
+    { score: 5, label: "Context Retained", description: "Follow-up устойчиво держит предмет и ограничения." }
+  ]
+};

llm_normalizer/backend/src/utils/files.ts

@@ -0,0 +1,20 @@
+import fs from "fs";
+
+export function ensureDir(path: string): void {
+  if (!fs.existsSync(path)) {
+    fs.mkdirSync(path, { recursive: true });
+  }
+}
+
+export function readJsonFile<T>(path: string, fallback: T): T {
+  try {
+    const raw = fs.readFileSync(path, "utf-8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeJsonFile(path: string, value: unknown): void {
+  fs.writeFileSync(path, JSON.stringify(value, null, 2), "utf-8");
+}

llm_normalizer/backend/src/utils/http.ts

@@ -0,0 +1,46 @@
+import type { NextFunction, Request, Response } from "express";
+
+export class ApiError extends Error {
+  public readonly code: string;
+  public readonly status: number;
+  public readonly details?: unknown;
+
+  constructor(code: string, message: string, status = 400, details?: unknown) {
+    super(message);
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+}
+
+export function ok<T>(res: Response, payload: T): Response<T> {
+  return res.status(200).json(payload);
+}
+
+export function created<T>(res: Response, payload: T): Response<T> {
+  return res.status(201).json(payload);
+}
+
+export function errorMiddleware(err: unknown, _req: Request, res: Response, _next: NextFunction): void {
+  if (err instanceof ApiError) {
+    res.status(err.status).json({
+      ok: false,
+      error: {
+        code: err.code,
+        message: err.message,
+        details: err.details ?? null
+      }
+    });
+    return;
+  }
+
+  const fallback = err instanceof Error ? err.message : "Unknown error";
+  res.status(500).json({
+    ok: false,
+    error: {
+      code: "INTERNAL_ERROR",
+      message: fallback,
+      details: null
+    }
+  });
+}

llm_normalizer/backend/src/utils/log.ts

@@ -0,0 +1,41 @@
+export interface JsonLogEntry {
+  timestamp: string;
+  level: "info" | "warn" | "error";
+  service: string;
+  message: string;
+  sessionId?: string;
+  runId?: string;
+  taskId?: string;
+  eventType?: string;
+  details?: unknown;
+}
+
+const REDACT_KEYS = new Set(["apiKey", "authorization", "Authorization", "openai_api_key", "OPENAI_API_KEY"]);
+
+function redactObject(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(redactObject);
+  }
+  if (value !== null && typeof value === "object") {
+    const source = value as Record<string, unknown>;
+    const out: Record<string, unknown> = {};
+    for (const [key, field] of Object.entries(source)) {
+      if (REDACT_KEYS.has(key)) {
+        out[key] = "***REDACTED***";
+      } else {
+        out[key] = redactObject(field);
+      }
+    }
+    return out;
+  }
+  return value;
+}
+
+export function logJson(entry: JsonLogEntry): void {
+  const safe = {
+    ...entry,
+    details: redactObject(entry.details)
+  };
+  // Structured JSON logs for diagnostics/trace aggregation.
+  process.stdout.write(JSON.stringify(safe) + "\n");
+}