NODEDC_1C/llm_normalizer/backend/src/services/assistantMcpDiscoveryResponsePolicy.ts

import {
  buildAssistantMcpDiscoveryResponseCandidate,
  type AssistantMcpDiscoveryResponseCandidateContract,
  type AssistantMcpDiscoveryResponseCandidateStatus
} from "./assistantMcpDiscoveryResponseCandidate";
import type { AssistantMcpDiscoveryRuntimeEntryPointContract } from "./assistantMcpDiscoveryRuntimeEntryPoint";

export const ASSISTANT_MCP_DISCOVERY_RESPONSE_POLICY_SCHEMA_VERSION =
  "assistant_mcp_discovery_response_policy_v1" as const;

export type AssistantMcpDiscoveryResponsePolicyDecision = "apply_candidate" | "keep_current_reply";

export interface ApplyAssistantMcpDiscoveryResponsePolicyInput {
  currentReply: string;
  currentReplySource?: string | null;
  currentReplyType?: string | null;
  livingChatSource?: string | null;
  modeDecisionReason?: string | null;
  addressRuntimeMeta?: Record<string, unknown> | null;
  entryPoint?: unknown;
}

export interface AssistantMcpDiscoveryResponsePolicyResult {
  schema_version: typeof ASSISTANT_MCP_DISCOVERY_RESPONSE_POLICY_SCHEMA_VERSION;
  policy_owner: "assistantMcpDiscoveryResponsePolicy";
  decision: AssistantMcpDiscoveryResponsePolicyDecision;
  applied: boolean;
  reply_text: string;
  reply_source: string;
  candidate: AssistantMcpDiscoveryResponseCandidateContract;
  reason_codes: string[];
}

const ALLOWED_CANDIDATE_STATUSES = new Set<AssistantMcpDiscoveryResponseCandidateStatus>([
  "ready_for_guarded_use",
  "checked_sources_only_candidate",
  "clarification_candidate"
]);

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 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: string): void {
  const normalized = normalizeReasonCode(value);
  if (normalized && !target.includes(normalized)) {
    target.push(normalized);
  }
}

function hasInternalMechanics(value: string): boolean {
  const text = value.toLowerCase();
  return (
    text.includes("mcp fetch failed") ||
    text.includes("this operation was aborted") ||
    text.includes("entity-resolution") ||
    text.includes("could not continue") ||
    text.includes("checked catalog search step") ||
    text.includes("query_documents") ||
    text.includes("query_movements") ||
    text.includes("primitive") ||
    text.includes("pilot_") ||
    text.includes("runtime_") ||
    text.includes("planner_") ||
    text.includes("catalog_") ||
    text.includes("select ")
  );
}

function isMcpDiscoveryEntryPointContract(value: unknown): value is AssistantMcpDiscoveryRuntimeEntryPointContract {
  const record = toRecordObject(value);
  return (
    record?.schema_version === "assistant_mcp_discovery_runtime_entry_point_v1" &&
    record?.policy_owner === "assistantMcpDiscoveryRuntimeEntryPoint"
  );
}

function resolveEntryPoint(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput
): AssistantMcpDiscoveryRuntimeEntryPointContract | null {
  if (isMcpDiscoveryEntryPointContract(input.entryPoint)) {
    return input.entryPoint;
  }
  const runtimeMetaEntryPoint =
    input.addressRuntimeMeta?.mcpDiscoveryRuntimeEntryPoint ??
    input.addressRuntimeMeta?.assistantMcpDiscoveryRuntimeEntryPoint ??
    input.addressRuntimeMeta?.assistant_mcp_discovery_entry_point_v1;
  return isMcpDiscoveryEntryPointContract(runtimeMetaEntryPoint) ? runtimeMetaEntryPoint : null;
}

function isUnsupportedCurrentTurnBoundary(input: ApplyAssistantMcpDiscoveryResponsePolicyInput): boolean {
  return (
    input.modeDecisionReason === "unsupported_current_turn_meaning_boundary" ||
    input.livingChatSource === "deterministic_unsupported_current_turn_boundary" ||
    input.currentReplySource === "deterministic_unsupported_current_turn_boundary"
  );
}

function isDeterministicBroadBusinessEvaluationReply(input: ApplyAssistantMcpDiscoveryResponsePolicyInput): boolean {
  return (
    input.livingChatSource === "deterministic_broad_business_evaluation_contract" ||
    input.currentReplySource === "deterministic_broad_business_evaluation_contract"
  );
}

function isDiscoveryReadyChatCandidate(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  const turnInput = toRecordObject(entryPoint?.turn_input);
  return (
    entryPoint?.entry_status === "bridge_executed" &&
    entryPoint.discovery_attempted === true &&
    turnInput?.should_run_discovery === true &&
    (input.livingChatSource === "llm_chat" || input.currentReplySource === "llm_chat")
  );
}

function isDiscoveryReadyDeepCandidate(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  const turnInput = toRecordObject(entryPoint?.turn_input);
  const source = String(input.currentReplySource ?? input.livingChatSource ?? "").trim().toLowerCase();
  return (
    entryPoint?.entry_status === "bridge_executed" &&
    entryPoint.discovery_attempted === true &&
    turnInput?.should_run_discovery === true &&
    (source === "deep_analysis" || source === "partial_coverage" || source === "normalizer_v2_0_2")
  );
}

function isDiscoveryReadyAddressCandidate(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  const turnInput = toRecordObject(entryPoint?.turn_input);
  const source = String(input.currentReplySource ?? input.livingChatSource ?? "").trim().toLowerCase();
  return (
    entryPoint?.entry_status === "bridge_executed" &&
    entryPoint.discovery_attempted === true &&
    turnInput?.should_run_discovery === true &&
    (source === "address_lane" || source === "address_exact" || source === "address_query_runtime_v1")
  );
}

function isDetectedIntentAlignedWithTurnMeaning(
  detectedIntent: string | null,
  turnMeaning: Record<string, unknown> | null
): boolean {
  const normalizedIntent = String(detectedIntent ?? "").trim().toLowerCase();
  if (!normalizedIntent) {
    return false;
  }
  const askedDomain = String(toNonEmptyString(turnMeaning?.asked_domain_family) ?? "").trim().toLowerCase();
  const askedAction = String(toNonEmptyString(turnMeaning?.asked_action_family) ?? "").trim().toLowerCase();

  if (normalizedIntent === "counterparty_activity_lifecycle") {
    return (
      askedDomain === "counterparty_lifecycle" ||
      askedAction === "activity_duration" ||
      askedAction === "age_or_activity_duration"
    );
  }
  if (normalizedIntent === "supplier_payouts_profile") {
    return (askedDomain === "counterparty_value" || askedDomain === "counterparty") && askedAction === "payout";
  }
  if (normalizedIntent === "customer_revenue_and_payments") {
    return (
      (askedDomain === "counterparty_value" || askedDomain === "counterparty") &&
      (askedAction === "turnover" || askedAction === "counterparty_value_or_turnover")
    );
  }
  if (normalizedIntent === "receivables_confirmed_as_of_date") {
    return askedDomain === "receivables" || askedAction === "confirmed_snapshot";
  }
  if (normalizedIntent === "payables_confirmed_as_of_date") {
    return askedDomain === "payables" || askedAction === "confirmed_snapshot";
  }
  if (normalizedIntent === "vat_liability_confirmed_for_tax_period") {
    return askedDomain === "vat" && askedAction === "confirmed_tax_period";
  }
  if (normalizedIntent === "vat_payable_confirmed_as_of_date") {
    return askedDomain === "vat" && askedAction === "confirmed_snapshot";
  }
  if (normalizedIntent === "vat_payable_forecast") {
    return askedDomain === "vat" && askedAction === "forecast";
  }
  if (normalizedIntent === "list_documents_by_counterparty") {
    return askedAction === "list_documents" || askedDomain === "counterparty_documents" || askedDomain === "counterparty";
  }
  if (normalizedIntent === "inventory_on_hand_as_of_date" || normalizedIntent === "inventory_aging_by_purchase_date") {
    return askedDomain === "inventory" && askedAction === "confirmed_snapshot";
  }
  if (
    normalizedIntent === "inventory_purchase_provenance_for_item" ||
    normalizedIntent === "inventory_purchase_documents_for_item" ||
    normalizedIntent === "inventory_sale_trace_for_item" ||
    normalizedIntent === "inventory_profitability_for_item" ||
    normalizedIntent === "inventory_purchase_to_sale_chain"
  ) {
    return askedDomain === "inventory";
  }
  return false;
}

function readDiscoveryTurnMeaning(
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): Record<string, unknown> | null {
  const turnInput = toRecordObject(entryPoint?.turn_input);
  return toRecordObject(turnInput?.turn_meaning_ref);
}

function readDiscoveryDataNeedGraph(
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): Record<string, unknown> | null {
  const turnInput = toRecordObject(entryPoint?.turn_input);
  return toRecordObject(turnInput?.data_need_graph);
}

function isMetadataDiscoveryTurn(
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  const turnMeaning = readDiscoveryTurnMeaning(entryPoint);
  const graph = readDiscoveryDataNeedGraph(entryPoint);
  const bridge = toRecordObject(entryPoint?.bridge);
  const pilot = toRecordObject(bridge?.pilot);
  const reasonCodes = Array.isArray(entryPoint?.reason_codes) ? entryPoint.reason_codes : [];
  return Boolean(
    toNonEmptyString(turnMeaning?.asked_domain_family) === "metadata" ||
      toNonEmptyString(turnMeaning?.unsupported_but_understood_family) === "1c_metadata_surface" ||
      toNonEmptyString(graph?.business_fact_family) === "schema_surface" ||
      toNonEmptyString(pilot?.pilot_scope) === "metadata_inspection_v1" ||
      reasonCodes.some((reason) => toNonEmptyString(reason) === "mcp_discovery_metadata_signal_detected")
  );
}

function isInventoryExactAddressIntent(intent: string | null): boolean {
  return /^(?:inventory_purchase_provenance_for_item|inventory_purchase_documents_for_item|inventory_sale_trace_for_item|inventory_profitability_for_item|inventory_purchase_to_sale_chain|inventory_aging_by_purchase_date|inventory_on_hand_as_of_date)$/u.test(
    String(intent ?? "")
  );
}

function hasMetadataDiscoveryPriority(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (!isMetadataDiscoveryTurn(entryPoint)) {
    return false;
  }
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  return !isInventoryExactAddressIntent(detectedIntent);
}

function isOpenScopeValueFlowWithoutSubject(
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  const graph = readDiscoveryDataNeedGraph(entryPoint);
  const businessFactFamily = toNonEmptyString(graph?.business_fact_family);
  const subjectCandidates = Array.isArray(graph?.subject_candidates) ? graph.subject_candidates : [];
  const reasonCodes = Array.isArray(graph?.reason_codes) ? graph.reason_codes : [];
  return (
    businessFactFamily === "value_flow" &&
    subjectCandidates.length === 0 &&
    reasonCodes.some((reason) => toNonEmptyString(reason) === "data_need_graph_open_scope_total_without_subject")
  );
}

function needsOpenScopeValueFlowOrganizationClarification(
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  const graph = readDiscoveryDataNeedGraph(entryPoint);
  const businessFactFamily = toNonEmptyString(graph?.business_fact_family);
  const subjectCandidates = Array.isArray(graph?.subject_candidates) ? graph.subject_candidates : [];
  const clarificationGaps = Array.isArray(graph?.clarification_gaps) ? graph.clarification_gaps : [];
  return (
    businessFactFamily === "value_flow" &&
    subjectCandidates.length === 0 &&
    clarificationGaps.some((gap) => toNonEmptyString(gap) === "organization")
  );
}

function isOpenScopeValueFlowRanking(
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  const graph = readDiscoveryDataNeedGraph(entryPoint);
  const businessFactFamily = toNonEmptyString(graph?.business_fact_family);
  const subjectCandidates = Array.isArray(graph?.subject_candidates) ? graph.subject_candidates : [];
  return businessFactFamily === "value_flow" && subjectCandidates.length === 0 && Boolean(toNonEmptyString(graph?.ranking_need));
}

function readTruthAnswerShape(input: ApplyAssistantMcpDiscoveryResponsePolicyInput): Record<string, unknown> | null {
  const directShape = toRecordObject(input.addressRuntimeMeta?.answer_shape_contract);
  if (directShape) {
    return directShape;
  }
  const truthAnswerPolicy = toRecordObject(input.addressRuntimeMeta?.assistant_truth_answer_policy_v1);
  return toRecordObject(truthAnswerPolicy?.answer_shape);
}

function hasEffectivelyFactualAddressReply(input: ApplyAssistantMcpDiscoveryResponsePolicyInput): boolean {
  if (toNonEmptyString(input.currentReplyType) === "factual") {
    return true;
  }
  const truthAnswerShape = readTruthAnswerShape(input);
  return toNonEmptyString(truthAnswerShape?.reply_type) === "factual";
}

function readStateTransitionReasonCodes(input: ApplyAssistantMcpDiscoveryResponsePolicyInput): string[] {
  const directTransition = toRecordObject(input.addressRuntimeMeta?.assistant_state_transition_v1);
  const fallbackTransition = toRecordObject(input.addressRuntimeMeta?.state_transition_contract);
  const stateTransition = directTransition ?? fallbackTransition;
  if (!stateTransition || !Array.isArray(stateTransition.reason_codes)) {
    return [];
  }
  return stateTransition.reason_codes
    .map((item) => toNonEmptyString(item))
    .filter((item): item is string => Boolean(item));
}

function hasFullConfirmedTruth(input: ApplyAssistantMcpDiscoveryResponsePolicyInput): boolean {
  const truthGateStatus = toNonEmptyString(input.addressRuntimeMeta?.truth_gate_contract_status);
  if (truthGateStatus === "full_confirmed") {
    return true;
  }
  const truthAnswerPolicy = toRecordObject(input.addressRuntimeMeta?.assistant_truth_answer_policy_v1);
  const truthGate = toRecordObject(truthAnswerPolicy?.truth_gate);
  const sourceTruthGateStatus = toNonEmptyString(truthGate?.source_truth_gate_status);
  const coverageStatus = toNonEmptyString(truthGate?.coverage_status);
  const groundingStatus = toNonEmptyString(truthGate?.grounding_status);
  return sourceTruthGateStatus === "full_confirmed" || (coverageStatus === "full" && groundingStatus === "grounded");
}

function readStringArray(value: unknown): string[] {
  return Array.isArray(value)
    ? value.map((item) => toNonEmptyString(item)).filter((item): item is string => Boolean(item))
    : [];
}

function hasValueFlowActionConflictWithDiscoveryTurnMeaning(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  const turnMeaning = readDiscoveryTurnMeaning(entryPoint);
  const askedDomain = toNonEmptyString(turnMeaning?.asked_domain_family);
  const askedAction = toNonEmptyString(turnMeaning?.asked_action_family);
  if (askedDomain !== "counterparty_value") {
    return false;
  }
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  if (askedAction === "payout") {
    return detectedIntent !== "supplier_payouts_profile";
  }
  if (askedAction === "net_value_flow") {
    return true;
  }
  return false;
}

function hasEvidenceLaneConflictWithDiscoveryTurnMeaning(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  const turnMeaning = readDiscoveryTurnMeaning(entryPoint);
  const askedDomain = toNonEmptyString(turnMeaning?.asked_domain_family);
  const askedAction = toNonEmptyString(turnMeaning?.asked_action_family);
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  if (!detectedIntent) {
    return false;
  }
  const asksForMovements = askedDomain === "movements" || askedAction === "list_movements";
  const asksForDocuments = askedDomain === "documents" || askedAction === "list_documents";
  const detectedDocumentsLane =
    detectedIntent === "list_documents_by_counterparty" || detectedIntent === "list_documents_by_contract";
  const detectedCashLane =
    detectedIntent === "bank_operations_by_counterparty" || detectedIntent === "bank_operations_by_contract";
  return (asksForMovements && detectedDocumentsLane) || (asksForDocuments && detectedCashLane);
}

function hasExactMatchedFactualAddressReply(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (hasOpenScopeValueFlowDiscoveryPriority(input, entryPoint)) {
    return false;
  }
  if (hasMetadataDiscoveryPriority(input, entryPoint)) {
    return false;
  }
  if (hasValueFlowActionConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    return false;
  }
  if (hasEvidenceLaneConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    return false;
  }
  if (hasSemanticConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
    if (!(isMetadataDiscoveryTurn(entryPoint) && isInventoryExactAddressIntent(detectedIntent))) {
      return false;
    }
  }
  const mcpCallStatus = toNonEmptyString(input.addressRuntimeMeta?.mcp_call_status);
  const truthMode = toNonEmptyString(input.addressRuntimeMeta?.truth_mode);
  const selectedRecipe = toNonEmptyString(input.addressRuntimeMeta?.selected_recipe);
  const bindingStatus = toNonEmptyString(input.addressRuntimeMeta?.capability_binding_status);
  const bindingViolations = readStringArray(input.addressRuntimeMeta?.capability_binding_violations);
  return Boolean(
    mcpCallStatus === "matched_non_empty" &&
      truthMode === "confirmed" &&
      selectedRecipe?.startsWith("address_") &&
      (bindingStatus === "bound" || bindingStatus === "bound_with_limits") &&
      bindingViolations.length === 0
  );
}

function hasOpenScopeValueFlowDiscoveryPriority(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  return Boolean(
    isOpenScopeValueFlowRanking(entryPoint) ||
      needsOpenScopeValueFlowOrganizationClarification(entryPoint) ||
      (detectedIntent === "customer_revenue_and_payments" && isOpenScopeValueFlowWithoutSubject(entryPoint))
  );
}

function hasRuntimeAdjustedExactReply(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (hasMetadataDiscoveryPriority(input, entryPoint)) {
    return false;
  }
  if (hasEvidenceLaneConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    return false;
  }
  if (!hasFullConfirmedTruth(input)) {
    return false;
  }
  const truthAnswerShape = readTruthAnswerShape(input);
  const capabilityContractId = toNonEmptyString(truthAnswerShape?.capability_contract_id);
  if (!capabilityContractId) {
    return false;
  }
  return readStateTransitionReasonCodes(input).some(
    (reason) => /^intent_adjusted_to_.+_followup_context$/i.test(reason)
  );
}

function hasRuntimeMatchedExactReply(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (hasMetadataDiscoveryPriority(input, entryPoint)) {
    return false;
  }
  if (hasEvidenceLaneConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    return false;
  }
  if (!hasFullConfirmedTruth(input)) {
    return false;
  }
  const reasonCodes = readStateTransitionReasonCodes(input);
  return (
    reasonCodes.some((reason) => reason === "route_expectation_matched") &&
    reasonCodes.some((reason) => /(?:confirmed_balance_exact|exact_.+_intent|vat_period_inspection_bridge_signal_detected)/iu.test(reason))
  );
}

function hasAlignedFactualAddressReply(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (hasMetadataDiscoveryPriority(input, entryPoint)) {
    return false;
  }
  if (hasSemanticConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    return false;
  }
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  return isDetectedIntentAlignedWithTurnMeaning(detectedIntent, readDiscoveryTurnMeaning(entryPoint));
}

function hasSemanticConflictWithDiscoveryTurnMeaning(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (hasRuntimeAdjustedExactReply(input, entryPoint)) {
    return false;
  }
  if (hasRuntimeMatchedExactReply(input, entryPoint)) {
    return false;
  }
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  const turnMeaning = readDiscoveryTurnMeaning(entryPoint);
  const askedDomain = toNonEmptyString(turnMeaning?.asked_domain_family);
  const askedAction = toNonEmptyString(turnMeaning?.asked_action_family);
  const unsupportedFamily = toNonEmptyString(turnMeaning?.unsupported_but_understood_family);
  if (!detectedIntent || (!askedDomain && !askedAction && !unsupportedFamily)) {
    return false;
  }
  if (isOpenScopeValueFlowRanking(entryPoint)) {
    return true;
  }
  if (needsOpenScopeValueFlowOrganizationClarification(entryPoint)) {
    return true;
  }
  if (hasMetadataDiscoveryPriority(input, entryPoint)) {
    return true;
  }
  if (
    detectedIntent === "customer_revenue_and_payments" &&
    isOpenScopeValueFlowWithoutSubject(entryPoint)
  ) {
    return true;
  }
  return !isDetectedIntentAlignedWithTurnMeaning(detectedIntent, turnMeaning);
}

function hasMatchedFactualAddressContinuationTarget(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (hasSemanticConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    return false;
  }
  if (hasMetadataDiscoveryPriority(input, entryPoint)) {
    return false;
  }
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  const dialogContinuationContract =
    toRecordObject(input.addressRuntimeMeta?.dialogContinuationContract) ??
    toRecordObject(input.addressRuntimeMeta?.dialog_continuation_contract_v2);
  const targetIntent = toNonEmptyString(dialogContinuationContract?.target_intent);
  return Boolean(detectedIntent && targetIntent && detectedIntent === targetIntent);
}

function hasMatchedFactualSuggestedIntentPivotTarget(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  const detectedIntent = toNonEmptyString(input.addressRuntimeMeta?.detected_intent);
  const dialogContinuationContract =
    toRecordObject(input.addressRuntimeMeta?.dialogContinuationContract) ??
    toRecordObject(input.addressRuntimeMeta?.dialog_continuation_contract_v2);
  const targetIntent = toNonEmptyString(dialogContinuationContract?.target_intent);
  const decision = toNonEmptyString(dialogContinuationContract?.decision);
  const selectionMode = toNonEmptyString(dialogContinuationContract?.intent_selection_mode);
  const suggestedPivotSignal = dialogContinuationContract?.suggested_intent_pivot_signal === true;
  return Boolean(
    detectedIntent &&
      targetIntent &&
      detectedIntent === targetIntent &&
      (decision === "switch_to_suggested" ||
        selectionMode === "switch_to_suggested_intent" ||
        suggestedPivotSignal)
  );
}

function hasFullConfirmedFactualAddressReply(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput,
  entryPoint: AssistantMcpDiscoveryRuntimeEntryPointContract | null
): boolean {
  if (!isDiscoveryReadyAddressCandidate(input, entryPoint)) {
    return false;
  }
  if (!hasEffectivelyFactualAddressReply(input)) {
    return false;
  }
  if (hasSemanticConflictWithDiscoveryTurnMeaning(input, entryPoint)) {
    return false;
  }
  if (hasMetadataDiscoveryPriority(input, entryPoint)) {
    return false;
  }
  return hasFullConfirmedTruth(input);
}

export function applyAssistantMcpDiscoveryResponsePolicy(
  input: ApplyAssistantMcpDiscoveryResponsePolicyInput
): AssistantMcpDiscoveryResponsePolicyResult {
  const currentReply = String(input.currentReply ?? "");
  const currentReplySource =
    toNonEmptyString(input.currentReplySource) ?? toNonEmptyString(input.livingChatSource) ?? "unknown";
  const entryPoint = resolveEntryPoint(input);
  const candidate = buildAssistantMcpDiscoveryResponseCandidate(entryPoint);
  const reasonCodes = [...candidate.reason_codes];
  const unsupportedBoundary = isUnsupportedCurrentTurnBoundary(input);
  const deterministicBroadBusinessEvaluationReply = isDeterministicBroadBusinessEvaluationReply(input);
  const discoveryReadyChatCandidate = isDiscoveryReadyChatCandidate(input, entryPoint);
  const discoveryReadyDeepCandidate = isDiscoveryReadyDeepCandidate(input, entryPoint);
  const discoveryReadyAddressCandidate = isDiscoveryReadyAddressCandidate(input, entryPoint);
  const alignedFactualAddressReply = hasAlignedFactualAddressReply(input, entryPoint);
  const semanticConflictWithDiscoveryTurnMeaning = hasSemanticConflictWithDiscoveryTurnMeaning(input, entryPoint);
  const matchedFactualAddressContinuationTarget = hasMatchedFactualAddressContinuationTarget(input, entryPoint);
  const matchedFactualSuggestedIntentPivotTarget = hasMatchedFactualSuggestedIntentPivotTarget(input, entryPoint);
  const fullConfirmedFactualAddressReply = hasFullConfirmedFactualAddressReply(input, entryPoint);
  const exactMatchedFactualAddressReply = hasExactMatchedFactualAddressReply(input, entryPoint);
  const runtimeAdjustedExactReply = hasRuntimeAdjustedExactReply(input, entryPoint);
  const runtimeMatchedExactReply = hasRuntimeMatchedExactReply(input, entryPoint);
  const openScopeValueFlowDiscoveryPriority = hasOpenScopeValueFlowDiscoveryPriority(input, entryPoint);
  const metadataDiscoveryPriority = hasMetadataDiscoveryPriority(input, entryPoint);
  const valueFlowActionConflictWithDiscoveryTurnMeaning = hasValueFlowActionConflictWithDiscoveryTurnMeaning(
    input,
    entryPoint
  );
  const evidenceLaneConflictWithDiscoveryTurnMeaning = hasEvidenceLaneConflictWithDiscoveryTurnMeaning(
    input,
    entryPoint
  );

  if (!entryPoint) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_no_entry_point");
  }
  if (!unsupportedBoundary) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_not_unsupported_boundary");
  }
  if (!discoveryReadyChatCandidate) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_not_discovery_ready_chat_candidate");
  }
  if (!discoveryReadyDeepCandidate) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_not_discovery_ready_deep_candidate");
  }
  if (!discoveryReadyAddressCandidate) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_not_discovery_ready_address_candidate");
  }
  if (alignedFactualAddressReply) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_keep_aligned_factual_address_reply");
  }
  if (semanticConflictWithDiscoveryTurnMeaning) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_semantic_conflict_allows_candidate_override");
  }
  if (valueFlowActionConflictWithDiscoveryTurnMeaning) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_value_flow_action_conflict_allows_candidate_override");
  }
  if (evidenceLaneConflictWithDiscoveryTurnMeaning) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_evidence_lane_conflict_allows_candidate_override");
  }
  if (openScopeValueFlowDiscoveryPriority) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_open_scope_value_flow_candidate_priority");
  }
  if (metadataDiscoveryPriority) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_metadata_candidate_priority");
  }
  if (matchedFactualAddressContinuationTarget) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_keep_factual_address_continuation_target");
  }
  if (matchedFactualSuggestedIntentPivotTarget) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_keep_factual_suggested_intent_pivot_target");
  }
  if (fullConfirmedFactualAddressReply) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_keep_full_confirmed_factual_address_reply");
  }
  if (exactMatchedFactualAddressReply) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_keep_exact_matched_factual_address_reply");
  }
  if (runtimeAdjustedExactReply) {
    pushReason(
      reasonCodes,
      "mcp_discovery_response_policy_keep_runtime_adjusted_exact_reply_over_stale_discovery_turn_meaning"
    );
  }
  if (runtimeMatchedExactReply) {
    pushReason(
      reasonCodes,
      "mcp_discovery_response_policy_keep_runtime_matched_exact_reply_over_stale_discovery_turn_meaning"
    );
  }
  if (deterministicBroadBusinessEvaluationReply && candidate.candidate_status === "clarification_candidate") {
    pushReason(
      reasonCodes,
      "mcp_discovery_response_policy_keep_broad_business_summary_over_clarification_candidate"
    );
  }
  if (!ALLOWED_CANDIDATE_STATUSES.has(candidate.candidate_status)) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_candidate_status_not_allowed");
  }
  if (!candidate.eligible_for_future_hot_runtime) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_candidate_not_eligible");
  }
  if (!toNonEmptyString(candidate.reply_text)) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_candidate_missing_reply_text");
  }
  if (candidate.reply_text && hasInternalMechanics(candidate.reply_text)) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_candidate_contains_internal_mechanics");
  }

  const canApply =
    Boolean(entryPoint) &&
    (unsupportedBoundary || discoveryReadyChatCandidate || discoveryReadyDeepCandidate || discoveryReadyAddressCandidate) &&
    !alignedFactualAddressReply &&
    !matchedFactualAddressContinuationTarget &&
    !matchedFactualSuggestedIntentPivotTarget &&
    !fullConfirmedFactualAddressReply &&
    !exactMatchedFactualAddressReply &&
    !runtimeAdjustedExactReply &&
    !runtimeMatchedExactReply &&
    !(deterministicBroadBusinessEvaluationReply && candidate.candidate_status === "clarification_candidate") &&
    ALLOWED_CANDIDATE_STATUSES.has(candidate.candidate_status) &&
    candidate.eligible_for_future_hot_runtime &&
    Boolean(toNonEmptyString(candidate.reply_text)) &&
    !hasInternalMechanics(String(candidate.reply_text ?? ""));

  if (!canApply) {
    pushReason(reasonCodes, "mcp_discovery_response_policy_kept_current_reply");
    return {
      schema_version: ASSISTANT_MCP_DISCOVERY_RESPONSE_POLICY_SCHEMA_VERSION,
      policy_owner: "assistantMcpDiscoveryResponsePolicy",
      decision: "keep_current_reply",
      applied: false,
      reply_text: currentReply,
      reply_source: currentReplySource,
      candidate,
      reason_codes: reasonCodes
    };
  }

  pushReason(reasonCodes, "mcp_discovery_response_policy_candidate_applied");
  return {
    schema_version: ASSISTANT_MCP_DISCOVERY_RESPONSE_POLICY_SCHEMA_VERSION,
    policy_owner: "assistantMcpDiscoveryResponsePolicy",
    decision: "apply_candidate",
    applied: true,
    reply_text: String(candidate.reply_text),
    reply_source: "mcp_discovery_response_candidate_guarded",
    candidate,
    reason_codes: reasonCodes
  };
}