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

АРЧ АП11 - Вынести coverage evidence contract для exact lane и завершить phase 4 агентным прогоном

Browse Source
This commit is contained in:
dctouch
2026-04-17 11:14:10 +03:00
parent 1484c2375f
commit b3572d9d11
16 changed files with 1357 additions and 375 deletions
Download Patch File Download Diff File Expand all files Collapse all files
llm_normalizer/backend/src/services/addressCoverageEvidencePolicy.ts
+391
View File
@@ -0,0 +1,391 @@
import type { AssistantCoverageStatus } from "../types/assistantRuntimeContracts";
import type {
AddressAsOfDateBasis,
AddressCoverageEvidenceBasis,
AddressEvidenceStrength,
AddressFilterSet,
AddressIntent,
AddressResponseType,
AddressResultMode,
AddressSemanticFrame
} from "../types/addressQuery";
export const ADDRESS_COVERAGE_EVIDENCE_SCHEMA_VERSION = "address_coverage_evidence_v1" as const;
export interface AddressCoverageEvidenceContract {
schema_version: typeof ADDRESS_COVERAGE_EVIDENCE_SCHEMA_VERSION;
policy_owner: "addressCoverageEvidencePolicy";
requested_result_mode: AddressResultMode | null;
result_mode: AddressResultMode | null;
evidence_strength: AddressEvidenceStrength | null;
balance_confirmed: boolean | null;
as_of_date_basis: AddressAsOfDateBasis | null;
coverage_status: AssistantCoverageStatus;
evidence_basis: AddressCoverageEvidenceBasis;
reason_codes: string[];
}
export interface ResolveAddressCoverageEvidenceInput {
intent: AddressIntent;
selectedRecipe: string | null;
filters: AddressFilterSet;
semanticFrame?: AddressSemanticFrame | null;
responseType: AddressResponseType;
rowsMatched: number;
overrideResultMode?: AddressResultMode | null;
overrideEvidenceStrength?: AddressEvidenceStrength | null;
overrideBalanceConfirmed?: boolean | null;
}
function toRecordObject(value: unknown): Record<string, unknown> | null {
if (!value || typeof value !== "object" || Array.isArray(value)) {
return null;
}
return value as Record<string, unknown>;
}
function toNonEmptyString(value: unknown): string | null {
if (value === null || value === undefined) {
return null;
}
const text = String(value).trim();
return text.length > 0 ? text : null;
}
function normalizeIsoDateHint(value: unknown): string | null {
if (typeof value !== "string") {
return null;
}
const trimmed = value.trim();
if (!trimmed) {
return null;
}
const match = trimmed.match(/^(\d{4})-(\d{2})-(\d{2})(?:T.*)?$/);
if (!match) {
return null;
}
const year = Number(match[1]);
const month = Number(match[2]);
const day = Number(match[3]);
if (!Number.isFinite(year) || !Number.isFinite(month) || !Number.isFinite(day)) {
return null;
}
const candidate = new Date(Date.UTC(year, month - 1, day));
if (
candidate.getUTCFullYear() !== year ||
candidate.getUTCMonth() + 1 !== month ||
candidate.getUTCDate() !== day
) {
return null;
}
return `${match[1]}-${match[2]}-${match[3]}`;
}
function normalizeReasonCode(value: string): string | null {
const normalized = value
.trim()
.replace(/[^\p{L}\p{N}_.:-]+/gu, "_")
.replace(/^_+|_+$/g, "")
.toLowerCase();
return normalized.length > 0 ? normalized.slice(0, 120) : null;
}
function pushReason(target: string[], value: unknown): void {
const text = toNonEmptyString(value);
if (!text) {
return;
}
const normalized = normalizeReasonCode(text);
if (normalized && !target.includes(normalized)) {
target.push(normalized);
}
}
function isResultMode(value: string | null): value is AddressResultMode {
return value === "heuristic_candidates" || value === "confirmed_balance";
}
function isEvidenceStrength(value: string | null): value is AddressEvidenceStrength {
return value === "weak" || value === "medium" || value === "strong";
}
function isCoverageStatus(value: string | null): value is AssistantCoverageStatus {
return value === "full" || value === "partial" || value === "blocked";
}
function isAsOfDateBasis(value: string | null): value is AddressAsOfDateBasis {
return (
value === "period_end" ||
value === "explicit_as_of_date" ||
value === "period_range" ||
value === "implicit_current_snapshot"
);
}
function isEvidenceBasis(value: string | null): value is AddressCoverageEvidenceBasis {
return (
value === "matched_rows" ||
value === "exact_negative" ||
value === "limited_response" ||
value === "heuristic_candidates" ||
value === "unknown"
);
}
export function isHeuristicCandidatesIntent(intent: AddressIntent): boolean {
return (
intent === "list_receivables_counterparties" ||
intent === "list_payables_counterparties" ||
intent === "list_open_contracts" ||
intent === "open_items_by_counterparty_or_contract"
);
}
export function isConfirmedBalanceIntent(intent: AddressIntent): boolean {
return (
intent === "account_balance_snapshot" ||
intent === "documents_forming_balance" ||
intent === "inventory_on_hand_as_of_date" ||
intent === "inventory_purchase_provenance_for_item" ||
intent === "inventory_purchase_documents_for_item" ||
intent === "inventory_sale_trace_for_item" ||
intent === "inventory_purchase_to_sale_chain" ||
intent === "open_contracts_confirmed_as_of_date" ||
intent === "payables_confirmed_as_of_date" ||
intent === "receivables_confirmed_as_of_date" ||
intent === "vat_payable_confirmed_as_of_date" ||
intent === "vat_liability_confirmed_for_tax_period"
);
}
export function resolveAddressAsOfDateBasis(
filters: AddressFilterSet,
semanticFrame?: AddressSemanticFrame | null
): AddressAsOfDateBasis | null {
if (semanticFrame?.date_basis_hint) {
return semanticFrame.date_basis_hint;
}
const asOfDate = normalizeIsoDateHint(filters.as_of_date);
if (asOfDate) {
return "explicit_as_of_date";
}
const periodFrom = normalizeIsoDateHint(filters.period_from);
const periodTo = normalizeIsoDateHint(filters.period_to);
if (periodFrom && periodTo) {
return "period_range";
}
if (!periodFrom && periodTo) {
return "period_end";
}
if (periodFrom) {
return "period_range";
}
return null;
}
function deriveAddressEvidenceStrength(input: {
intent: AddressIntent;
selectedRecipe: string | null;
responseType: AddressResponseType;
rowsMatched: number;
}): AddressEvidenceStrength | null {
if (isHeuristicCandidatesIntent(input.intent)) {
if (input.rowsMatched <= 0 || input.responseType === "LIMITED_WITH_REASON") {
return "weak";
}
if (input.selectedRecipe === "address_open_items_by_party_or_contract_v1") {
return "medium";
}
return "weak";
}
if (isConfirmedBalanceIntent(input.intent)) {
if (input.rowsMatched > 0) {
return "strong";
}
return input.responseType === "LIMITED_WITH_REASON" ? "weak" : "medium";
}
return null;
}
export function resolveAddressRequestedResultMode(
intent: AddressIntent,
filters: AddressFilterSet,
semanticFrame?: AddressSemanticFrame | null
): AddressResultMode | null {
if (isConfirmedBalanceIntent(intent)) {
return "confirmed_balance";
}
if (intent === "list_open_contracts") {
return "heuristic_candidates";
}
if (isHeuristicCandidatesIntent(intent)) {
const asOfDateBasis = resolveAddressAsOfDateBasis(filters, semanticFrame);
if (
asOfDateBasis === "explicit_as_of_date" ||
asOfDateBasis === "period_end" ||
asOfDateBasis === "period_range" ||
asOfDateBasis === "implicit_current_snapshot"
) {
return "confirmed_balance";
}
return "heuristic_candidates";
}
return null;
}
function balanceConfirmedFrom(input: {
intent: AddressIntent;
responseType: AddressResponseType;
}): boolean | null {
if (isHeuristicCandidatesIntent(input.intent)) {
return false;
}
if (isConfirmedBalanceIntent(input.intent)) {
return input.responseType !== "LIMITED_WITH_REASON";
}
return null;
}
function coverageStatusFrom(input: {
resultMode: AddressResultMode | null;
balanceConfirmed: boolean | null;
responseType: AddressResponseType;
rowsMatched: number;
}): AssistantCoverageStatus {
if (input.responseType === "LIMITED_WITH_REASON") {
return input.resultMode === "heuristic_candidates" ? "partial" : "blocked";
}
if (input.balanceConfirmed === false) {
return "partial";
}
if (input.rowsMatched > 0) {
return "full";
}
if (input.resultMode === "heuristic_candidates") {
return "partial";
}
if (input.resultMode === "confirmed_balance" && input.balanceConfirmed === true) {
return "full";
}
return "blocked";
}
function evidenceBasisFrom(input: {
resultMode: AddressResultMode | null;
responseType: AddressResponseType;
rowsMatched: number;
balanceConfirmed: boolean | null;
}): AddressCoverageEvidenceBasis {
if (input.responseType === "LIMITED_WITH_REASON") {
return "limited_response";
}
if (input.resultMode === "heuristic_candidates" || input.balanceConfirmed === false) {
return "heuristic_candidates";
}
if (input.rowsMatched > 0) {
return "matched_rows";
}
if (input.resultMode === "confirmed_balance") {
return "exact_negative";
}
return "unknown";
}
export function resolveAddressCoverageEvidence(
input: ResolveAddressCoverageEvidenceInput
): AddressCoverageEvidenceContract {
const requestedResultMode = resolveAddressRequestedResultMode(input.intent, input.filters, input.semanticFrame);
const resultMode = input.overrideResultMode ?? requestedResultMode;
const evidenceStrength =
input.overrideEvidenceStrength ?? deriveAddressEvidenceStrength(input);
const balanceConfirmed =
input.overrideBalanceConfirmed ?? balanceConfirmedFrom(input);
const asOfDateBasis = resolveAddressAsOfDateBasis(input.filters, input.semanticFrame);
const coverageStatus = coverageStatusFrom({
resultMode,
balanceConfirmed,
responseType: input.responseType,
rowsMatched: input.rowsMatched
});
const evidenceBasis = evidenceBasisFrom({
resultMode,
responseType: input.responseType,
rowsMatched: input.rowsMatched,
balanceConfirmed
});
const reasonCodes: string[] = [];
pushReason(reasonCodes, `coverage_status_${coverageStatus}`);
pushReason(reasonCodes, resultMode ? `result_mode_${resultMode}` : "result_mode_unknown");
pushReason(reasonCodes, evidenceStrength ? `evidence_strength_${evidenceStrength}` : "evidence_strength_none");
pushReason(reasonCodes, `evidence_basis_${evidenceBasis}`);
pushReason(reasonCodes, balanceConfirmed === true ? "balance_confirmed_true" : balanceConfirmed === false ? "balance_confirmed_false" : "balance_confirmed_unknown");
pushReason(reasonCodes, asOfDateBasis ? `as_of_date_basis_${asOfDateBasis}` : "as_of_date_basis_none");
return {
schema_version: ADDRESS_COVERAGE_EVIDENCE_SCHEMA_VERSION,
policy_owner: "addressCoverageEvidencePolicy",
requested_result_mode: requestedResultMode,
result_mode: resultMode,
evidence_strength: evidenceStrength,
balance_confirmed: balanceConfirmed,
as_of_date_basis: asOfDateBasis,
coverage_status: coverageStatus,
evidence_basis: evidenceBasis,
reason_codes: reasonCodes.slice(0, 24)
};
}
export function attachAddressCoverageEvidence<T extends Record<string, unknown>>(
debugPayload: T,
input: ResolveAddressCoverageEvidenceInput
): T & { address_coverage_evidence_v1: AddressCoverageEvidenceContract } {
return {
...debugPayload,
address_coverage_evidence_v1: resolveAddressCoverageEvidence(input)
};
}
export function toAddressCoverageEvidenceContract(value: unknown): AddressCoverageEvidenceContract | null {
const record = toRecordObject(value);
if (!record) {
return null;
}
const requestedResultMode = toNonEmptyString(record.requested_result_mode);
const resultMode = toNonEmptyString(record.result_mode);
const evidenceStrength = toNonEmptyString(record.evidence_strength);
const asOfDateBasis = toNonEmptyString(record.as_of_date_basis);
const coverageStatus = toNonEmptyString(record.coverage_status);
const evidenceBasis = toNonEmptyString(record.evidence_basis);
const balanceConfirmed = typeof record.balance_confirmed === "boolean" ? record.balance_confirmed : null;
if (!isCoverageStatus(coverageStatus) || !isEvidenceBasis(evidenceBasis)) {
return null;
}
if (requestedResultMode !== null && !isResultMode(requestedResultMode)) {
return null;
}
if (resultMode !== null && !isResultMode(resultMode)) {
return null;
}
if (evidenceStrength !== null && !isEvidenceStrength(evidenceStrength)) {
return null;
}
if (asOfDateBasis !== null && !isAsOfDateBasis(asOfDateBasis)) {
return null;
}
return {
schema_version: ADDRESS_COVERAGE_EVIDENCE_SCHEMA_VERSION,
policy_owner: "addressCoverageEvidencePolicy",
requested_result_mode: requestedResultMode,
result_mode: resultMode,
evidence_strength: evidenceStrength,
balance_confirmed: balanceConfirmed,
as_of_date_basis: asOfDateBasis,
coverage_status: coverageStatus,
evidence_basis: evidenceBasis,
reason_codes: Array.isArray(record.reason_codes)
? record.reason_codes
.map((item) => toNonEmptyString(item))
.filter((item): item is string => Boolean(item))
.slice(0, 24)
: []
};
}
llm_normalizer/backend/src/services/addressQueryService.ts
+122 -223
View File
@@ -14,8 +14,6 @@ import type {
AddressCapabilityLayer,
AddressCapabilityRouteMode,
AddressShadowRouteStatus,
AddressAsOfDateBasis,
AddressEvidenceStrength,
AddressExecutionResult,
AddressFilterSet,
AddressIntent,
@@ -64,6 +62,13 @@ import {
normalizeOrganizationScopeValue,
resolveOrganizationSelectionFromMessage
} from "./assistantOrganizationMatcher";
import {
attachAddressCoverageEvidence,
isConfirmedBalanceIntent,
isHeuristicCandidatesIntent,
resolveAddressRequestedResultMode,
resolveAddressCoverageEvidence
} from "./addressCoverageEvidencePolicy";
import { attachAddressTruthGate } from "./addressTruthGatePolicy";
import { OpenAIResponsesClient, type OpenAIRequestConfig } from "./openaiResponsesClient";
import { readJsonFile } from "../utils/files";
@@ -1802,168 +1807,10 @@ function collectOrganizationCandidatesFromRows(rows: NormalizedAddressRow[]): st
return mergeKnownOrganizations(rows.map((row) => row.organization).filter((value): value is string => Boolean(value)));
}
function isHeuristicCandidatesIntent(intent: AddressIntent): boolean {
return (
intent === "list_receivables_counterparties" ||
intent === "list_payables_counterparties" ||
intent === "list_open_contracts" ||
intent === "open_items_by_counterparty_or_contract"
);
}
function isConfirmedBalanceIntent(intent: AddressIntent): boolean {
return (
intent === "account_balance_snapshot" ||
intent === "documents_forming_balance" ||
intent === "inventory_on_hand_as_of_date" ||
intent === "inventory_purchase_provenance_for_item" ||
intent === "inventory_purchase_documents_for_item" ||
intent === "inventory_sale_trace_for_item" ||
intent === "inventory_purchase_to_sale_chain" ||
intent === "open_contracts_confirmed_as_of_date" ||
intent === "payables_confirmed_as_of_date" ||
intent === "receivables_confirmed_as_of_date" ||
intent === "vat_payable_confirmed_as_of_date" ||
intent === "vat_liability_confirmed_for_tax_period"
);
}
function resolveAsOfDateBasis(filters: AddressFilterSet, semanticFrame?: AddressSemanticFrame | null): AddressAsOfDateBasis | null {
if (semanticFrame?.date_basis_hint) {
return semanticFrame.date_basis_hint;
}
const asOfDate = normalizeAnalysisDateHint(filters.as_of_date);
if (asOfDate) {
return "explicit_as_of_date";
}
const periodFrom = normalizeAnalysisDateHint(filters.period_from);
const periodTo = normalizeAnalysisDateHint(filters.period_to);
if (periodFrom && periodTo) {
return "period_range";
}
if (!periodFrom && periodTo) {
return "period_end";
}
if (periodFrom) {
return "period_range";
}
return null;
}
function deriveAddressEvidenceStrength(input: {
intent: AddressIntent;
selectedRecipe: string | null;
responseType: AddressResponseType;
rowsMatched: number;
}): AddressEvidenceStrength | undefined {
if (isHeuristicCandidatesIntent(input.intent)) {
if (input.rowsMatched <= 0 || input.responseType === "LIMITED_WITH_REASON") {
return "weak";
}
if (input.selectedRecipe === "address_open_items_by_party_or_contract_v1") {
return "medium";
}
return "weak";
}
if (isConfirmedBalanceIntent(input.intent)) {
if (input.rowsMatched > 0) {
return "strong";
}
return input.responseType === "LIMITED_WITH_REASON" ? "weak" : "medium";
}
return undefined;
}
function resolveRequestedResultMode(
intent: AddressIntent,
filters: AddressFilterSet,
semanticFrame?: AddressSemanticFrame | null
): AddressResultMode | undefined {
if (isConfirmedBalanceIntent(intent)) {
return "confirmed_balance";
}
if (intent === "list_open_contracts") {
return "heuristic_candidates";
}
if (isHeuristicCandidatesIntent(intent)) {
const asOfDateBasis = resolveAsOfDateBasis(filters, semanticFrame);
if (
asOfDateBasis === "explicit_as_of_date" ||
asOfDateBasis === "period_end" ||
asOfDateBasis === "period_range" ||
asOfDateBasis === "implicit_current_snapshot"
) {
return "confirmed_balance";
}
return "heuristic_candidates";
}
return undefined;
}
function deriveAddressResultSemantics(input: {
intent: AddressIntent;
selectedRecipe: string | null;
filters: AddressFilterSet;
semanticFrame?: AddressSemanticFrame | null;
responseType: AddressResponseType;
rowsMatched: number;
}): {
requested_result_mode?: AddressResultMode;
result_mode?: AddressResultMode;
evidence_strength?: AddressEvidenceStrength;
balance_confirmed?: boolean;
as_of_date_basis?: AddressAsOfDateBasis | null;
} {
const asOfDateBasis = resolveAsOfDateBasis(input.filters, input.semanticFrame);
const requestedResultMode = resolveRequestedResultMode(input.intent, input.filters, input.semanticFrame);
if (isHeuristicCandidatesIntent(input.intent)) {
return {
requested_result_mode: requestedResultMode,
result_mode: "heuristic_candidates",
evidence_strength: deriveAddressEvidenceStrength(input),
balance_confirmed: false,
as_of_date_basis: asOfDateBasis
};
}
if (isConfirmedBalanceIntent(input.intent)) {
const balanceConfirmed = input.responseType !== "LIMITED_WITH_REASON";
return {
requested_result_mode: requestedResultMode,
result_mode: "confirmed_balance",
evidence_strength: deriveAddressEvidenceStrength(input),
balance_confirmed: balanceConfirmed,
as_of_date_basis: asOfDateBasis ?? "period_end"
};
}
if (requestedResultMode) {
return {
requested_result_mode: requestedResultMode
};
}
return {};
}
type AddressResultSemantics = ReturnType<typeof deriveAddressResultSemantics>;
function mergeAddressResultSemantics(
base: AddressResultSemantics,
override: ComposeReplySemantics | undefined
): AddressResultSemantics {
if (!override) {
return base;
}
return {
...base,
...(override.result_mode ? { result_mode: override.result_mode } : {}),
...(override.evidence_strength ? { evidence_strength: override.evidence_strength } : {}),
...(typeof override.balance_confirmed === "boolean" ? { balance_confirmed: override.balance_confirmed } : {})
};
}
function withConfirmedBalanceFallbackReason(
reasons: string[],
requestedResultMode: AddressResultMode | undefined,
semantics: ComposeReplySemantics | undefined,
semantics: { result_mode?: AddressResultMode | null } | undefined,
baseResultMode?: AddressResultMode
): string[] {
if (requestedResultMode !== "confirmed_balance") {
@@ -3120,7 +2967,7 @@ function buildLimitedExecutionResult(input: {
semanticFrame?: AddressSemanticFrame | null;
}): AddressExecutionResult {
const accountScopeAudit = input.accountScopeAudit ?? buildDefaultAccountScopeAudit(input.filters);
const resultSemantics = deriveAddressResultSemantics({
const coverageEvidence = resolveAddressCoverageEvidence({
intent: input.intent.intent,
selectedRecipe: input.selectedRecipe,
filters: input.filters,
@@ -3128,12 +2975,11 @@ function buildLimitedExecutionResult(input: {
responseType: "LIMITED_WITH_REASON",
rowsMatched: input.rowsMatched
});
const requestedResultMode = resolveRequestedResultMode(input.intent.intent, input.filters, input.semanticFrame);
const reasonsWithConfirmedFallback = withConfirmedBalanceFallbackReason(
input.reasons,
requestedResultMode,
coverageEvidence.requested_result_mode ?? undefined,
undefined,
resultSemantics.result_mode
coverageEvidence.result_mode ?? undefined
);
const exactLimitedReason =
input.intent.intent === "inventory_on_hand_as_of_date"
@@ -3156,11 +3002,12 @@ function buildLimitedExecutionResult(input: {
buildRouteExpectationAudit({
intent: input.intent.intent,
selectedRecipe: input.selectedRecipe,
requestedResultMode: requestedResultMode,
resultMode: resultSemantics.result_mode
requestedResultMode: coverageEvidence.requested_result_mode ?? undefined,
resultMode: coverageEvidence.result_mode ?? undefined
});
const runtimeReadiness = runtimeReadinessForLimitedCategory(input.category);
const debugPayload = attachAddressTruthGate(
attachAddressCoverageEvidence(
{
detected_mode: input.mode.mode,
detected_mode_confidence: input.mode.confidence,
@@ -3212,10 +3059,23 @@ function buildLimitedExecutionResult(input: {
route_expectation_expected_selected_recipes: routeExpectationAudit.expectedSelectedRecipes,
route_expectation_expected_requested_result_modes: routeExpectationAudit.expectedRequestedResultModes,
route_expectation_expected_result_modes: routeExpectationAudit.expectedResultModes,
...resultSemantics,
requested_result_mode: coverageEvidence.requested_result_mode ?? undefined,
result_mode: coverageEvidence.result_mode ?? undefined,
evidence_strength: coverageEvidence.evidence_strength ?? undefined,
balance_confirmed:
typeof coverageEvidence.balance_confirmed === "boolean" ? coverageEvidence.balance_confirmed : undefined,
as_of_date_basis: coverageEvidence.as_of_date_basis ?? undefined,
limitations: input.limitations,
reasons
},
{
intent: input.intent.intent,
selectedRecipe: input.selectedRecipe,
filters: input.filters,
semanticFrame: input.semanticFrame ?? null,
responseType: "LIMITED_WITH_REASON",
rowsMatched: input.rowsMatched
}),
{
intent: input.intent.intent,
filters: input.filters,
@@ -3364,12 +3224,13 @@ export class AddressQueryService {
capabilityAudit: buildCapabilityAudit(intent.intent),
shadowRouteAudit: buildShadowRouteAudit({
intent: intent.intent,
requestedResultMode: resolveRequestedResultMode(intent.intent, filters.extracted_filters, semanticFrame),
requestedResultMode: resolveAddressRequestedResultMode(intent.intent, filters.extracted_filters, semanticFrame) ?? undefined,
filters: filters.extracted_filters
})
});
}
const requestedResultMode = resolveRequestedResultMode(intent.intent, filters.extracted_filters, semanticFrame);
const requestedResultMode =
resolveAddressRequestedResultMode(intent.intent, filters.extracted_filters, semanticFrame) ?? undefined;
const confirmedBalancePayablesIntent =
(intent.intent === "list_payables_counterparties" || intent.intent === "payables_confirmed_as_of_date") &&
requestedResultMode === "confirmed_balance";
@@ -4098,31 +3959,29 @@ export class AddressQueryService {
extraLimitations: string[] = []
): AddressExecutionResult => {
const responseType: AddressResponseType = "FACTUAL_SUMMARY";
const semantics = mergeAddressResultSemantics(
deriveAddressResultSemantics({
intent: intent.intent,
selectedRecipe: effectiveRecipeId,
filters: filters.extracted_filters,
semanticFrame,
responseType,
rowsMatched: 0
}),
undefined
);
const coverageEvidence = resolveAddressCoverageEvidence({
intent: intent.intent,
selectedRecipe: effectiveRecipeId,
filters: filters.extracted_filters,
semanticFrame,
responseType,
rowsMatched: 0
});
const factualNoRowsLimitations = [...filters.warnings, ...extraLimitations];
const factualNoRowsReasons = withConfirmedBalanceFallbackReason(
[...baseReasons, noRowsReason],
requestedResultMode,
undefined,
semantics.result_mode
coverageEvidence.result_mode ?? undefined
);
const routeExpectationAudit = buildRouteExpectationAudit({
intent: routeExpectationIntent,
selectedRecipe: effectiveRecipeId,
requestedResultMode,
resultMode: semantics.result_mode
resultMode: coverageEvidence.result_mode ?? undefined
});
const debugPayload = attachAddressTruthGate(
attachAddressCoverageEvidence(
{
detected_mode: mode.mode,
detected_mode_confidence: mode.confidence,
@@ -4165,7 +4024,12 @@ export class AddressQueryService {
route_expectation_expected_selected_recipes: routeExpectationAudit.expectedSelectedRecipes,
route_expectation_expected_requested_result_modes: routeExpectationAudit.expectedRequestedResultModes,
route_expectation_expected_result_modes: routeExpectationAudit.expectedResultModes,
...semantics,
requested_result_mode: coverageEvidence.requested_result_mode ?? undefined,
result_mode: coverageEvidence.result_mode ?? undefined,
evidence_strength: coverageEvidence.evidence_strength ?? undefined,
balance_confirmed:
typeof coverageEvidence.balance_confirmed === "boolean" ? coverageEvidence.balance_confirmed : undefined,
as_of_date_basis: coverageEvidence.as_of_date_basis ?? undefined,
limitations: factualNoRowsLimitations,
reasons: factualNoRowsReasons,
...(capabilityAudit
@@ -4185,6 +4049,14 @@ export class AddressQueryService {
}
: {})
},
{
intent: intent.intent,
selectedRecipe: effectiveRecipeId,
filters: filters.extracted_filters,
semanticFrame,
responseType,
rowsMatched: 0
}),
{
intent: intent.intent,
filters: filters.extracted_filters,
@@ -4245,26 +4117,30 @@ export class AddressQueryService {
truthGateStatusHint?: AssistantTruthGateContractStatus | null;
extractedFilters?: AddressFilterSet;
}): AddressExecutionResult => {
const resultSemantics = mergeAddressResultSemantics(
deriveAddressResultSemantics({
intent: intent.intent,
selectedRecipe: input.selectedRecipe,
filters: input.extractedFilters ?? filters.extracted_filters,
semanticFrame: input.semanticFrame ?? semanticFrame,
responseType: input.responseType,
rowsMatched: input.rowsMatched
}),
input.responseSemantics
);
const coverageEvidence = resolveAddressCoverageEvidence({
intent: intent.intent,
selectedRecipe: input.selectedRecipe,
filters: input.extractedFilters ?? filters.extracted_filters,
semanticFrame: input.semanticFrame ?? semanticFrame,
responseType: input.responseType,
rowsMatched: input.rowsMatched,
overrideResultMode: input.responseSemantics?.result_mode ?? null,
overrideEvidenceStrength: input.responseSemantics?.evidence_strength ?? null,
overrideBalanceConfirmed:
typeof input.responseSemantics?.balance_confirmed === "boolean"
? input.responseSemantics.balance_confirmed
: null
});
const routeExpectationAudit =
input.routeExpectationAudit ??
buildRouteExpectationAudit({
intent: routeExpectationIntent,
selectedRecipe: input.selectedRecipe,
requestedResultMode,
resultMode: resultSemantics.result_mode
resultMode: coverageEvidence.result_mode ?? undefined
});
const debugPayload = attachAddressTruthGate(
attachAddressCoverageEvidence(
{
detected_mode: mode.mode,
detected_mode_confidence: mode.confidence,
@@ -4308,7 +4184,12 @@ export class AddressQueryService {
route_expectation_expected_requested_result_modes: routeExpectationAudit.expectedRequestedResultModes,
route_expectation_expected_result_modes: routeExpectationAudit.expectedResultModes,
semantic_frame: input.semanticFrame ?? semanticFrame,
...resultSemantics,
requested_result_mode: coverageEvidence.requested_result_mode ?? undefined,
result_mode: coverageEvidence.result_mode ?? undefined,
evidence_strength: coverageEvidence.evidence_strength ?? undefined,
balance_confirmed:
typeof coverageEvidence.balance_confirmed === "boolean" ? coverageEvidence.balance_confirmed : undefined,
as_of_date_basis: coverageEvidence.as_of_date_basis ?? undefined,
limitations: input.limitations,
reasons: input.reasons,
...(input.capabilityAudit
@@ -4328,6 +4209,20 @@ export class AddressQueryService {
}
: {})
},
{
intent: intent.intent,
selectedRecipe: input.selectedRecipe,
filters: input.extractedFilters ?? filters.extracted_filters,
semanticFrame: input.semanticFrame ?? semanticFrame,
responseType: input.responseType,
rowsMatched: input.rowsMatched,
overrideResultMode: input.responseSemantics?.result_mode ?? null,
overrideEvidenceStrength: input.responseSemantics?.evidence_strength ?? null,
overrideBalanceConfirmed:
typeof input.responseSemantics?.balance_confirmed === "boolean"
? input.responseSemantics.balance_confirmed
: null
}),
{
intent: intent.intent,
filters: input.extractedFilters ?? filters.extracted_filters,
@@ -4645,22 +4540,25 @@ export class AddressQueryService {
"period_window_auto_broadened_to_available_data"
];
const broadenedReasons = [...baseReasons, ...broadenedAdjustments, "period_window_auto_broadened_to_available_data"];
const broadenedResultSemantics = mergeAddressResultSemantics(
deriveAddressResultSemantics({
intent: intent.intent,
selectedRecipe: broadenedSelection.selected_recipe.recipe_id,
filters: filters.extracted_filters,
semanticFrame,
responseType: broadenedFactual.responseType,
rowsMatched: broadenedFilteredRows.length
}),
broadenedFactual.semantics
);
const broadenedCoverageEvidence = resolveAddressCoverageEvidence({
intent: intent.intent,
selectedRecipe: broadenedSelection.selected_recipe.recipe_id,
filters: filters.extracted_filters,
semanticFrame,
responseType: broadenedFactual.responseType,
rowsMatched: broadenedFilteredRows.length,
overrideResultMode: broadenedFactual.semantics?.result_mode ?? null,
overrideEvidenceStrength: broadenedFactual.semantics?.evidence_strength ?? null,
overrideBalanceConfirmed:
typeof broadenedFactual.semantics?.balance_confirmed === "boolean"
? broadenedFactual.semantics.balance_confirmed
: null
});
const broadenedRouteExpectationAudit = buildRouteExpectationAudit({
intent: routeExpectationIntent,
selectedRecipe: broadenedSelection.selected_recipe.recipe_id,
requestedResultMode,
resultMode: broadenedResultSemantics.result_mode
resultMode: broadenedCoverageEvidence.result_mode ?? undefined
});
return buildFactualExecutionResult({
replyText: injectNoticeAfterLeadLine(broadenedFactual.text, broadenedPrefix),
@@ -5085,22 +4983,23 @@ export class AddressQueryService {
: []
: [];
const factualLimitations = [...filters.warnings, ...vatProbeLimitations];
const factualResultSemantics = mergeAddressResultSemantics(
deriveAddressResultSemantics({
intent: composeIntent,
selectedRecipe: effectiveRecipeId,
filters: filters.extracted_filters,
semanticFrame,
responseType: factual.responseType,
rowsMatched: filteredRows.length
}),
factual.semantics
);
const factualCoverageEvidence = resolveAddressCoverageEvidence({
intent: composeIntent,
selectedRecipe: effectiveRecipeId,
filters: filters.extracted_filters,
semanticFrame,
responseType: factual.responseType,
rowsMatched: filteredRows.length,
overrideResultMode: factual.semantics?.result_mode ?? null,
overrideEvidenceStrength: factual.semantics?.evidence_strength ?? null,
overrideBalanceConfirmed:
typeof factual.semantics?.balance_confirmed === "boolean" ? factual.semantics.balance_confirmed : null
});
const finalRouteExpectationAudit = buildRouteExpectationAudit({
intent: routeExpectationIntent,
selectedRecipe: effectiveRecipeId,
requestedResultMode,
resultMode: factualResultSemantics.result_mode
resultMode: factualCoverageEvidence.result_mode ?? undefined
});
if (finalRouteExpectationAudit.status === "mismatch" && FEATURE_ASSISTANT_ROUTE_EXPECTATION_HARD_GUARD_V1) {
return finalizeLimitedResult({
@@ -5142,7 +5041,7 @@ export class AddressQueryService {
(intent.intent === "vat_payable_confirmed_as_of_date" && composeIntent === "vat_payable_confirmed_as_of_date") ||
(intent.intent === "vat_liability_confirmed_for_tax_period" &&
composeIntent === "vat_liability_confirmed_for_tax_period");
if (exactConfirmedIntent && factualResultSemantics.balance_confirmed !== true) {
if (exactConfirmedIntent && factualCoverageEvidence.balance_confirmed !== true) {
const exactModeName =
intent.intent === "payables_confirmed_as_of_date"
? "payables"
@@ -5218,7 +5117,7 @@ export class AddressQueryService {
reasonsWithRouteExpectation,
requestedResultMode,
factual.semantics,
factualResultSemantics.result_mode
factualCoverageEvidence.result_mode ?? undefined
),
routeExpectationAudit: finalRouteExpectationAudit,
capabilityAudit,
llm_normalizer/backend/src/services/assistantTruthAnswerPolicyRuntimeAdapter.ts
+14 -1
View File
@@ -11,6 +11,7 @@ import {
type AssistantTruthGateContractStatus,
type AssistantTruthMode
} from "../types/assistantRuntimeContracts";
import { toAddressCoverageEvidenceContract } from "./addressCoverageEvidencePolicy";
import { toAddressTruthGateContract } from "./addressTruthGatePolicy";
import { resolveAssistantRuntimeContractShadow } from "./assistantRuntimeContractResolver";
@@ -123,6 +124,7 @@ function coverageStatusFrom(
truthGateStatus: AssistantTruthGateContractStatus,
groundingStatus: AssistantGroundingStatus
): AssistantCoverageStatus {
const explicitCoverageEvidence = toAddressCoverageEvidenceContract(debug.address_coverage_evidence_v1);
if (truthGateStatus === "full_confirmed") {
return "full";
}
@@ -135,6 +137,9 @@ function coverageStatusFrom(
if (toStringList(debug.missing_required_filters).length > 0 || groundingStatus === "route_mismatch_blocked" || groundingStatus === "no_grounded_answer") {
return "blocked";
}
if (explicitCoverageEvidence) {
return explicitCoverageEvidence.coverage_status;
}
const coverageReport = toRecordObject(input.coverageReport) ?? toRecordObject(debug.coverage_report);
if (coverageReport) {
@@ -186,6 +191,10 @@ function evidenceGradeFrom(
groundingStatus: AssistantGroundingStatus,
truthGateStatus: AssistantTruthGateContractStatus
): AssistantEvidenceGrade {
const explicitCoverageEvidence = toAddressCoverageEvidenceContract(debug.address_coverage_evidence_v1);
if (explicitCoverageEvidence?.evidence_strength && isEvidenceGrade(explicitCoverageEvidence.evidence_strength)) {
return explicitCoverageEvidence.evidence_strength;
}
const explicit = toNonEmptyString(debug.evidence_strength);
if (isEvidenceGrade(explicit)) {
return explicit;
@@ -230,11 +239,13 @@ function collectReasonCodes(input: {
truthMode: AssistantTruthMode;
truthGateStatus: AssistantTruthGateContractStatus;
explicitGateReasonCodes: string[];
explicitCoverageReasonCodes: string[];
}): string[] {
const reasons: string[] = [];
pushReason(reasons, `truth_gate_${input.truthGateStatus}`);
pushReason(reasons, `truth_mode_${input.truthMode}`);
input.explicitGateReasonCodes.forEach((item) => pushReason(reasons, item));
input.explicitCoverageReasonCodes.forEach((item) => pushReason(reasons, item));
input.shadow.transition_contract_reason.forEach((item) => pushReason(reasons, item));
input.shadow.capability_contract_reason.forEach((item) => pushReason(reasons, item));
toStringList(input.debug.missing_required_filters).forEach((item) => pushReason(reasons, `missing_filter_${item}`));
@@ -318,6 +329,7 @@ export function resolveAssistantTruthAnswerPolicyRuntime(
): AssistantTruthAnswerPolicyRuntimeContract {
const debug = toRecordObject(input.addressDebug) ?? {};
const explicitAddressTruthGate = toAddressTruthGateContract(debug.address_truth_gate_v1);
const explicitCoverageEvidence = toAddressCoverageEvidenceContract(debug.address_coverage_evidence_v1);
const shadow = resolveAssistantRuntimeContractShadow({
addressDebug: debug,
addressRuntimeMeta: input.addressRuntimeMeta,
@@ -340,7 +352,8 @@ export function resolveAssistantTruthAnswerPolicyRuntime(
shadow,
truthMode,
truthGateStatus,
explicitGateReasonCodes: explicitAddressTruthGate?.reason_codes ?? []
explicitGateReasonCodes: explicitAddressTruthGate?.reason_codes ?? [],
explicitCoverageReasonCodes: explicitCoverageEvidence?.reason_codes ?? []
});
const shape = answerShapeFrom({
coverageStatus,
llm_normalizer/backend/src/types/addressQuery.ts
+19
View File
@@ -1,6 +1,7 @@
export type AddressQuestionMode = "address_query" | "deep_analysis" | "unsupported";
import type {
AssistantCoverageStatus,
AssistantCarryoverDepth,
AssistantTruthGateContractStatus
} from "./assistantRuntimeContracts";
@@ -102,6 +103,12 @@ export type AddressRuntimeReadiness =
| "REQUIRES_SPECIALIZED_RECIPE"
| "DEEP_ONLY"
| "UNKNOWN";
export type AddressCoverageEvidenceBasis =
| "matched_rows"
| "exact_negative"
| "limited_response"
| "heuristic_candidates"
| "unknown";
export type AddressMcpCallStatus =
| "skipped"
@@ -266,6 +273,18 @@ export interface AddressExecutionDebug {
| "rows_remaining_after_scope_filter";
runtime_readiness: AddressRuntimeReadiness;
limited_reason_category: AddressLimitedReasonCategory | null;
address_coverage_evidence_v1?: {
schema_version: "address_coverage_evidence_v1";
policy_owner: "addressCoverageEvidencePolicy";
requested_result_mode: AddressResultMode | null;
result_mode: AddressResultMode | null;
evidence_strength: AddressEvidenceStrength | null;
balance_confirmed: boolean | null;
as_of_date_basis: AddressAsOfDateBasis | null;
coverage_status: AssistantCoverageStatus;
evidence_basis: AddressCoverageEvidenceBasis;
reason_codes: string[];
} | null;
address_truth_gate_v1?: {
schema_version: "address_truth_gate_v1";
policy_owner: "addressTruthGatePolicy";