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

АРЧ АП11 - Добавить capability runtime binding для assistant contracts

Browse Source
This commit is contained in:
dctouch
2026-04-15 23:41:57 +03:00
parent 5f628f427f
commit 1c928a5d68
12 changed files with 937 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
llm_normalizer/backend/src/services/assistantAddressLaneResponseRuntimeAdapter.ts
+7 -2
View File
@@ -7,6 +7,7 @@ import {
type AddressLlmPreDecomposeMetaLogInput,
type FinalizeAssistantAddressTurnInput
} from "./assistantAddressTurnFinalizeRuntimeAdapter";
import { attachAssistantCapabilityRuntimeBinding } from "./assistantCapabilityRuntimeBindingAdapter";
import { attachAssistantRuntimeContractShadow } from "./assistantRuntimeContractResolver";
import { attachAssistantStateTransition } from "./assistantStateTransitionRuntimeAdapter";
import { attachAssistantTruthAnswerPolicy } from "./assistantTruthAnswerPolicyRuntimeAdapter";
@@ -261,6 +262,10 @@ export function runAssistantAddressLaneResponseRuntime<ResponseType = AssistantM
addressRuntimeMeta: input.llmPreDecomposeMeta,
replyType: normalizeAddressReplyType(input.addressLane.reply_type)
});
const debugWithCapabilityBinding = attachAssistantCapabilityRuntimeBinding(debugWithStateTransition, {
addressRuntimeMeta: input.llmPreDecomposeMeta,
replyType: normalizeAddressReplyType(input.addressLane.reply_type)
});
const finalization = finalizeAddressTurnSafe({
sessionId: input.sessionId,
userMessage: input.userMessage,
@@ -268,7 +273,7 @@ export function runAssistantAddressLaneResponseRuntime<ResponseType = AssistantM
assistantReply: safeAddressReply,
replyType: normalizeAddressReplyType(input.addressLane.reply_type),
addressLaneDebug: normalizeAddressLaneDebug(input.addressLane.debug),
debug: debugWithStateTransition,
debug: debugWithCapabilityBinding,
carryoverMeta: normalizeCarryoverMeta(input.carryoverMeta),
llmPreDecomposeMeta: normalizeLlmPreDecomposeMeta(input.llmPreDecomposeMeta),
appendItem: input.appendItem,
@@ -281,6 +286,6 @@ export function runAssistantAddressLaneResponseRuntime<ResponseType = AssistantM
return {
response: finalization.response as ResponseType,
debug: debugWithStateTransition
debug: debugWithCapabilityBinding
};
}
llm_normalizer/backend/src/services/assistantCapabilityRuntimeBindingAdapter.ts
+394
View File
@@ -0,0 +1,394 @@
import {
ASSISTANT_CAPABILITY_RUNTIME_BINDING_SCHEMA_VERSION,
type AssistantCapabilityBindingAction,
type AssistantCapabilityBindingStatus,
type AssistantCapabilityBindingViolation,
type AssistantCapabilityRuntimeBindingContract,
type AssistantRuntimeContractShadowDecision,
type AssistantRuntimeLane,
type AssistantStateTransitionRuntimeContract,
type AssistantTruthAnswerPolicyRuntimeContract
} from "../types/assistantRuntimeContracts";
import { getAssistantCapabilityContract } from "./assistantRuntimeContractRegistry";
import { resolveAssistantRuntimeContractShadow } from "./assistantRuntimeContractResolver";
import { resolveAssistantStateTransitionRuntime } from "./assistantStateTransitionRuntimeAdapter";
import { resolveAssistantTruthAnswerPolicyRuntime } from "./assistantTruthAnswerPolicyRuntimeAdapter";
export interface ResolveAssistantCapabilityRuntimeBindingInput {
addressDebug?: Record<string, unknown> | null;
addressRuntimeMeta?: Record<string, unknown> | null;
groundingStatus?: unknown;
coverageReport?: Record<string, unknown> | null;
replyType?: unknown;
runtimeContractShadow?: AssistantRuntimeContractShadowDecision | null;
truthAnswerPolicy?: AssistantTruthAnswerPolicyRuntimeContract | null;
stateTransition?: AssistantStateTransitionRuntimeContract | null;
}
export interface AssistantCapabilityRuntimeBindingFields {
assistant_capability_binding_v1: AssistantCapabilityRuntimeBindingContract;
capability_binding_contract: AssistantCapabilityRuntimeBindingContract;
capability_binding_status: AssistantCapabilityBindingStatus;
capability_binding_action: AssistantCapabilityBindingAction;
capability_binding_violations: AssistantCapabilityBindingViolation[];
}
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 toStringList(value: unknown): string[] {
if (!Array.isArray(value)) {
return [];
}
return value
.map((item) => toNonEmptyString(item))
.filter((item): item is string => Boolean(item));
}
function uniqueStrings(values: string[]): string[] {
return Array.from(new Set(values.filter((item) => item.trim().length > 0)));
}
function addViolation(target: AssistantCapabilityBindingViolation[], violation: AssistantCapabilityBindingViolation): void {
if (!target.includes(violation)) {
target.push(violation);
}
}
function resolveShadow(
input: ResolveAssistantCapabilityRuntimeBindingInput,
debug: Record<string, unknown>
): AssistantRuntimeContractShadowDecision {
return (
input.runtimeContractShadow ??
(toRecordObject(debug.assistant_runtime_contract_v1) as AssistantRuntimeContractShadowDecision | null) ??
resolveAssistantRuntimeContractShadow({
addressDebug: debug,
addressRuntimeMeta: input.addressRuntimeMeta,
groundingStatus: input.groundingStatus
})
);
}
function resolveTruthPolicy(
input: ResolveAssistantCapabilityRuntimeBindingInput,
debug: Record<string, unknown>
): AssistantTruthAnswerPolicyRuntimeContract {
return (
input.truthAnswerPolicy ??
(toRecordObject(debug.assistant_truth_answer_policy_v1) as AssistantTruthAnswerPolicyRuntimeContract | null) ??
resolveAssistantTruthAnswerPolicyRuntime({
addressDebug: debug,
addressRuntimeMeta: input.addressRuntimeMeta,
groundingStatus: input.groundingStatus,
coverageReport: input.coverageReport,
replyType: input.replyType
})
);
}
function resolveStateTransition(
input: ResolveAssistantCapabilityRuntimeBindingInput,
debug: Record<string, unknown>
): AssistantStateTransitionRuntimeContract {
return (
input.stateTransition ??
(toRecordObject(debug.assistant_state_transition_v1) as AssistantStateTransitionRuntimeContract | null) ??
resolveAssistantStateTransitionRuntime({
addressDebug: debug,
addressRuntimeMeta: input.addressRuntimeMeta,
groundingStatus: input.groundingStatus,
coverageReport: input.coverageReport,
replyType: input.replyType,
runtimeContractShadow: input.runtimeContractShadow,
truthAnswerPolicy: input.truthAnswerPolicy
})
);
}
function hasValue(value: unknown): boolean {
return toNonEmptyString(value) !== null;
}
function collectProvidedAnchors(debug: Record<string, unknown>): string[] {
const anchors: string[] = [];
const filters = toRecordObject(debug.extracted_filters);
const semanticFrame = toRecordObject(debug.semantic_frame);
const rootFrame = toRecordObject(debug.address_root_frame_context);
const anchorType = toNonEmptyString(debug.anchor_type);
const anchorValue = toNonEmptyString(debug.anchor_value_resolved) ?? toNonEmptyString(debug.anchor_value_raw);
if (filters) {
for (const [key, value] of Object.entries(filters)) {
if (hasValue(value)) {
anchors.push(key);
}
}
}
if (anchorType && anchorType !== "unknown" && anchorValue) {
anchors.push(anchorType);
}
if (semanticFrame) {
const anchorKind = toNonEmptyString(semanticFrame.anchor_kind);
const anchorValueFromFrame = toNonEmptyString(semanticFrame.anchor_value);
if (anchorKind && anchorKind !== "none" && (anchorValueFromFrame || semanticFrame.selected_object_scope_detected === true)) {
anchors.push(anchorKind);
}
if (semanticFrame.selected_object_scope_detected === true) {
anchors.push("selected_object");
}
}
if (toNonEmptyString(rootFrame?.current_frame_kind)?.includes("drilldown")) {
anchors.push("selected_object");
}
return uniqueStrings(anchors);
}
function anchorSatisfied(requiredAnchor: string, providedAnchors: string[], debug: Record<string, unknown>): boolean {
const filters = toRecordObject(debug.extracted_filters);
if (providedAnchors.includes(requiredAnchor)) {
return true;
}
if (requiredAnchor === "item") {
return (
providedAnchors.includes("selected_object") ||
providedAnchors.includes("anchor_item") ||
hasValue(filters?.item) ||
toNonEmptyString(debug.anchor_type) === "item"
);
}
if (requiredAnchor === "supplier") {
return providedAnchors.includes("counterparty") || hasValue(filters?.supplier) || hasValue(filters?.counterparty);
}
return false;
}
function runtimeLaneObserved(debug: Record<string, unknown>): AssistantRuntimeLane | "unknown" {
const capabilityRouteMode = toNonEmptyString(debug.capability_route_mode);
const capabilityLayer = toNonEmptyString(debug.capability_layer);
const detectedMode = toNonEmptyString(debug.detected_mode);
if (capabilityRouteMode === "exact" && (capabilityLayer === "compute" || detectedMode === "address_query")) {
return "address_exact";
}
if (detectedMode === "assistant_data_scope") {
return "assistant_data_scope";
}
if (capabilityLayer === "conversational") {
return "chat";
}
return "unknown";
}
function focusObjectBindingStatus(input: {
requiresFocusObject: boolean;
providedAnchors: string[];
missingAnchors: string[];
}): AssistantCapabilityRuntimeBindingContract["focus_object_binding_status"] {
if (!input.requiresFocusObject) {
return "not_required";
}
if (input.providedAnchors.includes("selected_object")) {
return "bound";
}
if (!input.missingAnchors.includes("item") && input.providedAnchors.includes("item")) {
return "inferred_from_anchor";
}
return "missing";
}
function truthFallbackAllowed(
contractTruthFallbacks: string[],
truthMode: AssistantTruthAnswerPolicyRuntimeContract["truth_gate"]["truth_mode"]
): boolean {
return truthMode === "confirmed" || contractTruthFallbacks.includes(truthMode);
}
function bindingStatusFor(input: {
hasCapabilityId: boolean;
hasContract: boolean;
violations: AssistantCapabilityBindingViolation[];
truthMode: AssistantTruthAnswerPolicyRuntimeContract["truth_gate"]["truth_mode"];
}): AssistantCapabilityBindingStatus {
if (!input.hasCapabilityId) {
return "not_applicable";
}
if (!input.hasContract) {
return "contract_missing";
}
if (
input.violations.includes("transition_not_supported_by_capability") ||
input.violations.includes("required_anchor_missing") ||
input.violations.includes("focus_object_required_but_unbound") ||
input.violations.includes("runtime_lane_mismatch")
) {
return "blocked";
}
if (input.violations.length > 0 || input.truthMode !== "confirmed") {
return "bound_with_limits";
}
return "bound";
}
function bindingActionFor(status: AssistantCapabilityBindingStatus, missingAnchors: string[]): AssistantCapabilityBindingAction {
if (status === "not_applicable" || status === "contract_missing") {
return "observe_only";
}
if (status === "blocked" && missingAnchors.length > 0) {
return "clarify";
}
if (status === "blocked") {
return "block";
}
if (status === "bound_with_limits") {
return "limit";
}
return "allow";
}
export function resolveAssistantCapabilityRuntimeBinding(
input: ResolveAssistantCapabilityRuntimeBindingInput
): AssistantCapabilityRuntimeBindingContract {
const debug = toRecordObject(input.addressDebug) ?? {};
const shadow = resolveShadow(input, debug);
const truthPolicy = resolveTruthPolicy(input, debug);
const stateTransition = resolveStateTransition(input, debug);
const capabilityId =
shadow.capability_contract_id ??
toNonEmptyString(debug.capability_contract_id) ??
toNonEmptyString(debug.capability_id) ??
truthPolicy.answer_shape.capability_contract_id;
const capabilityContract = capabilityId ? getAssistantCapabilityContract(capabilityId) : null;
const violations: AssistantCapabilityBindingViolation[] = [];
if (capabilityId && !capabilityContract) {
addViolation(violations, "capability_contract_missing");
}
const transitionAllowed =
capabilityContract && stateTransition.transition_id
? capabilityContract.supported_transition_classes.includes(stateTransition.transition_id)
: capabilityContract
? null
: false;
if (capabilityContract && stateTransition.transition_id && !transitionAllowed) {
addViolation(violations, "transition_not_supported_by_capability");
}
const providedAnchors = collectProvidedAnchors(debug);
const requiredAnchors = capabilityContract?.required_anchors ?? [];
const missingAnchors = requiredAnchors.filter((anchor) => !anchorSatisfied(anchor, providedAnchors, debug));
if (missingAnchors.length > 0) {
addViolation(violations, "required_anchor_missing");
}
const focusStatus = focusObjectBindingStatus({
requiresFocusObject: capabilityContract?.requires_focus_object ?? false,
providedAnchors,
missingAnchors
});
if (capabilityContract?.requires_focus_object && focusStatus === "missing") {
addViolation(violations, "focus_object_required_but_unbound");
}
const observedLane = runtimeLaneObserved(debug);
const laneMatches = !capabilityContract || observedLane === "unknown" || capabilityContract.runtime_lane === observedLane;
if (capabilityContract && !laneMatches) {
addViolation(violations, "runtime_lane_mismatch");
}
const truthAllowed = capabilityContract
? truthFallbackAllowed(capabilityContract.truth_mode_fallbacks, truthPolicy.truth_gate.truth_mode)
: null;
if (truthAllowed === false) {
addViolation(violations, "truth_fallback_not_declared");
}
const answerShapeCompatible =
capabilityContract && truthPolicy.answer_shape.capability_contract_id
? truthPolicy.answer_shape.capability_contract_id === capabilityContract.capability_id
: capabilityContract
? null
: false;
if (answerShapeCompatible === false && capabilityContract) {
addViolation(violations, "answer_shape_capability_mismatch");
}
const status = bindingStatusFor({
hasCapabilityId: Boolean(capabilityId),
hasContract: Boolean(capabilityContract),
violations,
truthMode: truthPolicy.truth_gate.truth_mode
});
const action = bindingActionFor(status, missingAnchors);
return {
schema_version: ASSISTANT_CAPABILITY_RUNTIME_BINDING_SCHEMA_VERSION,
binding_owner: "assistantCapabilityRuntimeBindingAdapter",
capability_id: capabilityId,
capability_contract_id: capabilityContract?.capability_id ?? null,
binding_status: status,
binding_action: action,
runtime_lane_expected: capabilityContract?.runtime_lane ?? null,
runtime_lane_observed: observedLane,
execution_adapter: capabilityContract?.execution_adapter ?? null,
transition_id: stateTransition.transition_id,
transition_allowed: transitionAllowed,
required_anchors: requiredAnchors,
provided_anchors: providedAnchors,
missing_anchors: missingAnchors,
requires_focus_object: capabilityContract?.requires_focus_object ?? false,
focus_object_binding_status: focusStatus,
result_shape: capabilityContract?.result_shape ?? null,
answer_object_shape: capabilityContract?.answer_object_shape ?? null,
truth_gate_behavior: capabilityContract?.coverage_gate_behavior ?? null,
truth_fallback_allowed: truthAllowed,
answer_shape_compatible: answerShapeCompatible,
violations,
reason_codes: uniqueStrings([
`binding_status_${status}`,
`binding_action_${action}`,
...violations,
...stateTransition.reason_codes,
...truthPolicy.truth_gate.reason_codes,
...shadow.capability_contract_reason
]).slice(0, 48)
};
}
export function buildAssistantCapabilityRuntimeBindingFields(
input: ResolveAssistantCapabilityRuntimeBindingInput
): AssistantCapabilityRuntimeBindingFields {
const binding = resolveAssistantCapabilityRuntimeBinding(input);
return {
assistant_capability_binding_v1: binding,
capability_binding_contract: binding,
capability_binding_status: binding.binding_status,
capability_binding_action: binding.binding_action,
capability_binding_violations: binding.violations
};
}
export function attachAssistantCapabilityRuntimeBinding<T extends Record<string, unknown>>(
debugPayload: T,
input: Omit<ResolveAssistantCapabilityRuntimeBindingInput, "addressDebug">
): T & AssistantCapabilityRuntimeBindingFields {
return {
...debugPayload,
...buildAssistantCapabilityRuntimeBindingFields({
...input,
addressDebug: debugPayload
})
};
}
llm_normalizer/backend/src/services/assistantDebugPayloadAssembler.ts
+8 -1
View File
@@ -23,6 +23,7 @@ import type {
GroundedAnswerEligibilityAudit,
TemporalGuardAudit
} from "./assistantRuntimeGuards";
import { attachAssistantCapabilityRuntimeBinding } from "./assistantCapabilityRuntimeBindingAdapter";
import { attachAssistantRuntimeContractShadow } from "./assistantRuntimeContractResolver";
import { attachAssistantStateTransition } from "./assistantStateTransitionRuntimeAdapter";
import { attachAssistantTruthAnswerPolicy } from "./assistantTruthAnswerPolicyRuntimeAdapter";
@@ -186,7 +187,13 @@ export function buildDeepAnalysisDebugPayload(input: DeepAnalysisDebugPayloadInp
coverageReport: input.coverageReport as unknown as Record<string, unknown>,
replyType: "deep_analysis"
});
return attachAssistantStateTransition(debugWithTruthAnswerPolicy, {
const debugWithStateTransition = attachAssistantStateTransition(debugWithTruthAnswerPolicy, {
addressRuntimeMeta: input.addressRuntimeMetaForDeep as unknown as Record<string, unknown> | null | undefined,
groundingStatus: input.groundingCheck.status,
coverageReport: input.coverageReport as unknown as Record<string, unknown>,
replyType: "deep_analysis"
});
return attachAssistantCapabilityRuntimeBinding(debugWithStateTransition, {
addressRuntimeMeta: input.addressRuntimeMetaForDeep as unknown as Record<string, unknown> | null | undefined,
groundingStatus: input.groundingCheck.status,
coverageReport: input.coverageReport as unknown as Record<string, unknown>,
llm_normalizer/backend/src/types/assistant.ts
+9
View File
@@ -19,6 +19,10 @@ import type { AccountingGraphBuildResult } from "./stage4Graph";
import type { AddressNavigationState } from "./addressNavigation";
import type {
AssistantAnswerShapeKind,
AssistantCapabilityBindingAction,
AssistantCapabilityBindingStatus,
AssistantCapabilityBindingViolation,
AssistantCapabilityRuntimeBindingContract,
AssistantRuntimeContractShadowDecision,
AssistantStateTransitionApplicationStatus,
AssistantStateTransitionRuntimeContract,
@@ -470,6 +474,11 @@ export interface AssistantDebugPayload {
state_transition_id?: AssistantTransitionClassId | null;
state_transition_status?: AssistantStateTransitionApplicationStatus;
effective_carryover_depth?: AssistantStateTransitionRuntimeContract["effective_carryover_depth"];
assistant_capability_binding_v1?: AssistantCapabilityRuntimeBindingContract;
capability_binding_contract?: AssistantCapabilityRuntimeBindingContract;
capability_binding_status?: AssistantCapabilityBindingStatus;
capability_binding_action?: AssistantCapabilityBindingAction;
capability_binding_violations?: AssistantCapabilityBindingViolation[];
execution_lane?: "address_query" | "deep_analysis";
llm_decomposition_applied?: boolean;
llm_decomposition_attempted?: boolean;
llm_normalizer/backend/src/types/assistantRuntimeContracts.ts
+37
View File
@@ -3,6 +3,7 @@ import type { AddressIntent } from "./addressQuery";
export const ASSISTANT_RUNTIME_CONTRACTS_SCHEMA_VERSION = "assistant_runtime_contracts_v1" as const;
export const ASSISTANT_TRUTH_ANSWER_POLICY_RUNTIME_SCHEMA_VERSION = "assistant_truth_answer_policy_runtime_v1" as const;
export const ASSISTANT_STATE_TRANSITION_RUNTIME_SCHEMA_VERSION = "assistant_state_transition_runtime_v1" as const;
export const ASSISTANT_CAPABILITY_RUNTIME_BINDING_SCHEMA_VERSION = "assistant_capability_runtime_binding_v1" as const;
export type AssistantLivingMode = "address_data" | "assistant_data_scope" | "chat" | "meta_followup" | "clarification";
export type AssistantFrameStatus = "active" | "suspended" | "closed" | "blocked";
@@ -39,6 +40,16 @@ export type AssistantAnswerShapeKind =
export type AssistantAnswerShapeReplyType = "factual" | "partial_coverage" | "deep_analysis" | "unknown";
export type AssistantStateTransitionApplicationStatus = "applied" | "clarification_required" | "blocked" | "unresolved";
export type AssistantStateFrameAction = "create" | "update" | "preserve" | "reuse" | "clear" | "block" | "none";
export type AssistantCapabilityBindingStatus = "bound" | "bound_with_limits" | "blocked" | "contract_missing" | "not_applicable";
export type AssistantCapabilityBindingAction = "allow" | "limit" | "clarify" | "block" | "observe_only";
export type AssistantCapabilityBindingViolation =
| "capability_contract_missing"
| "transition_not_supported_by_capability"
| "required_anchor_missing"
| "focus_object_required_but_unbound"
| "runtime_lane_mismatch"
| "truth_fallback_not_declared"
| "answer_shape_capability_mismatch";
export interface AssistantDateScopeState {
as_of_date: string | null;
@@ -144,6 +155,32 @@ export interface AssistantStateTransitionRuntimeContract {
reason_codes: string[];
}
export interface AssistantCapabilityRuntimeBindingContract {
schema_version: typeof ASSISTANT_CAPABILITY_RUNTIME_BINDING_SCHEMA_VERSION;
binding_owner: "assistantCapabilityRuntimeBindingAdapter";
capability_id: string | null;
capability_contract_id: string | null;
binding_status: AssistantCapabilityBindingStatus;
binding_action: AssistantCapabilityBindingAction;
runtime_lane_expected: AssistantRuntimeLane | null;
runtime_lane_observed: AssistantRuntimeLane | "unknown";
execution_adapter: string | null;
transition_id: AssistantTransitionClassId | null;
transition_allowed: boolean | null;
required_anchors: string[];
provided_anchors: string[];
missing_anchors: string[];
requires_focus_object: boolean;
focus_object_binding_status: "bound" | "inferred_from_anchor" | "missing" | "not_required";
result_shape: string | null;
answer_object_shape: string | null;
truth_gate_behavior: AssistantCoverageGateBehavior | null;
truth_fallback_allowed: boolean | null;
answer_shape_compatible: boolean | null;
violations: AssistantCapabilityBindingViolation[];
reason_codes: string[];
}
export interface AssistantSessionAggregateState {
schema_version: typeof ASSISTANT_RUNTIME_CONTRACTS_SCHEMA_VERSION;
living_mode_state: {