ummaya 0.2.3 → 0.2.5

package/src/ummaya/evidence/tool_layer.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ummaya.evidence.models import RouteTraceRecord
+from ummaya.evidence.tool_layer_models import ToolLayerEvidenceEvent
+
+
+@dataclass(frozen=True, slots=True)
+class ToolLayerEvidenceJoinError(ValueError):
+    """Raised when a tool-layer artifact cannot be joined to route evidence."""
+
+    event_id: str
+
+    def __str__(self) -> str:
+        return f"tool-layer event does not join to route evidence: {self.event_id}"
+
+
+def build_tool_layer_events(
+    route_trace_records: tuple[RouteTraceRecord, ...],
+    *,
+    observed_events: tuple[ToolLayerEvidenceEvent, ...] = (),
+) -> tuple[ToolLayerEvidenceEvent, ...]:
+    """Return validated tool-layer artifacts without synthesizing sample events."""
+
+    if not observed_events:
+        return ()
+
+    route_keys = {
+        (record.scenario_id, record.trace_id, record.correlation_id)
+        for record in route_trace_records
+        if record.trace_kind == "scenario_route"
+    }
+    for event in observed_events:
+        event_key = (event.scenario_id, event.trace_id, event.correlation_id)
+        if event_key not in route_keys:
+            raise ToolLayerEvidenceJoinError(event_id=event.event_id)
+    return observed_events

package/src/ummaya/evidence/tool_layer_models.py

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Tool-layer Evidence Fabric event models."""
+
+from __future__ import annotations
+
+from typing import Literal, Self, assert_never
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic_core import PydanticCustomError
+
+ToolLayerExposureState = Literal[
+    "always-loaded",
+    "deferred-searchable",
+    "permission-gated-callable",
+    "hidden",
+    "unsupported",
+]
+ToolLayerTrustTier = Literal[0, 1, 2, 3, 4, 5]
+ToolLayerPermissionDecision = Literal[
+    "not_required",
+    "approved",
+    "denied",
+    "blocked_pending_approval",
+    "policy_preapproved",
+]
+ToolLayerResultStatus = Literal["succeeded", "failed", "blocked"]
+ToolLayerBlockedState = Literal[
+    "not_blocked",
+    "blocked_by_permission",
+    "blocked_by_policy",
+    "blocked_by_missing_source",
+    "blocked_by_unsupported",
+]
+ToolLayerRenderFrame = Literal[
+    "permission_prompt",
+    "tool_call",
+    "tool_result",
+    "blocked_state",
+]
+ToolLayerPromptInjectionState = Literal["detected", "not_detected"]
+ToolLayerSourceTrust = Literal["trusted", "untrusted"]
+ToolLayerSourceInstructionVisibility = Literal["evidence_only"]
+
+
+def _validation_error(code: str, message: str) -> PydanticCustomError:
+    return PydanticCustomError(code, message)
+
+
+class ToolLayerEvidenceEvent(BaseModel):
+    """One recovered Claude Code support-tool exposure and provenance event."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    event_id: str = Field(min_length=1)
+    scenario_id: str = Field(min_length=1)
+    trace_id: str = Field(min_length=1)
+    correlation_id: str = Field(min_length=1)
+    frame_hash: str = Field(min_length=64, max_length=64)
+    render_frame: ToolLayerRenderFrame
+    selected_tool: str = Field(min_length=1)
+    exposure_state: ToolLayerExposureState
+    trust_tier: ToolLayerTrustTier
+    permission_decision: ToolLayerPermissionDecision
+    source_url: str | None
+    source_local_handle: str | None
+    source_citation_id: str = Field(min_length=1)
+    provenance_id: str = Field(min_length=1)
+    source_trust: ToolLayerSourceTrust
+    source_prompt_injection: ToolLayerPromptInjectionState
+    source_instruction_visibility: ToolLayerSourceInstructionVisibility = "evidence_only"
+    result_status: ToolLayerResultStatus
+    result_summary: str | None
+    error_summary: str | None
+    blocked_state: ToolLayerBlockedState
+
+    @field_validator("frame_hash")
+    @classmethod
+    def _validate_frame_hash(cls, value: str) -> str:
+        if len(value) != 64 or any(ch not in "0123456789abcdef" for ch in value):
+            raise _validation_error(
+                "tool_layer_frame_hash", "frame_hash must be lowercase SHA-256 hex"
+            )
+        return value
+
+    @field_validator("source_url", "source_local_handle", "source_citation_id", "provenance_id")
+    @classmethod
+    def _reject_model_visible_leakage_keys(cls, value: str | None) -> str | None:
+        if value is not None and ("adapter_id" in value or "expected_tool" in value):
+            raise _validation_error(
+                "tool_layer_model_visible_leakage",
+                "tool-layer evidence cannot carry model-visible leakage keys",
+            )
+        return value
+
+    @field_validator("result_summary", "error_summary")
+    @classmethod
+    def _reject_empty_summary(cls, value: str | None) -> str | None:
+        if value is not None and not value.strip():
+            raise _validation_error(
+                "tool_layer_blank_summary", "tool-layer summaries cannot be blank"
+            )
+        return value
+
+    @model_validator(mode="after")
+    def _requires_source_reference(self) -> Self:
+        if self.source_url is None and self.source_local_handle is None:
+            raise _validation_error(
+                "tool_layer_missing_source",
+                "tool-layer evidence requires source_url or source_local_handle",
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _requires_status_payload(self) -> Self:
+        match self.result_status:
+            case "succeeded":
+                if self.result_summary is None:
+                    raise _validation_error(
+                        "tool_layer_missing_result_summary",
+                        "succeeded tool-layer event requires result_summary",
+                    )
+                if self.error_summary is not None:
+                    raise _validation_error(
+                        "tool_layer_unexpected_error_summary",
+                        "succeeded tool-layer event cannot carry error_summary",
+                    )
+                if self.blocked_state != "not_blocked":
+                    raise _validation_error(
+                        "tool_layer_unexpected_blocked_state",
+                        "succeeded tool-layer event must not be blocked",
+                    )
+            case "failed":
+                if self.error_summary is None:
+                    raise _validation_error(
+                        "tool_layer_failed_without_error",
+                        "failed tool-layer event requires error_summary",
+                    )
+            case "blocked":
+                if self.error_summary is None:
+                    raise _validation_error(
+                        "tool_layer_blocked_without_error",
+                        "blocked tool-layer event requires error_summary",
+                    )
+                if self.blocked_state == "not_blocked":
+                    raise _validation_error(
+                        "tool_layer_blocked_without_state",
+                        "blocked tool-layer event requires a blocked_state",
+                    )
+            case unreachable:
+                assert_never(unreachable)
+        return self

package/src/ummaya/ipc/adapter_manifest_emitter.py

@@ -47,6 +47,7 @@ import importlib
 import json
 import logging
 import os
+import re
 from datetime import UTC, datetime
 from typing import IO, Any, Literal
 
@@ -255,7 +256,7 @@ def _build_entries(  # noqa: C901, ANN401 — three-source walker, refactor defe
     except Exception:
         tools_list = []
 
-    root_primitive_tool_ids = frozenset({"locate", "find", "check", "send"})
+    root_primitive_tool_ids = frozenset({"locate", "find", "check", "send", "document"})
 
     for tool in tools_list:
         tool_id_opt: str | None = tool.id if hasattr(tool, "id") else getattr(tool, "tool_id", None)
@@ -371,24 +372,39 @@ def _verify_family_llm_description(
     """Build model-facing prose for a verify-family manifest entry."""
 
     metadata = metadata or {}
-    tool_id = str(metadata.get("tool_id") or family).strip()
     name = str(metadata.get("name_ko") or family).strip()
-    scope_rules = str(metadata.get("scope_rules") or "").strip()
+    scope_rules = _safe_verify_scope_rules(str(metadata.get("scope_rules") or "").strip())
     scope_clause = f" {scope_rules}" if scope_rules else ""
     return (
-        f"Internal check-family surface for {name} (family_hint='{family}', "
-        f"bridged adapter id '{tool_id}'). Use this only through the core check "
-        "primitive before a downstream protected find/send action needs delegated "
-        "authorization. Params must follow input_schema_json exactly: scope_list "
-        "contains '<verb>:<adapter_family>.<action>' scope strings, purpose_ko is "
-        "the Korean citizen-facing consent purpose, and purpose_en is the audit-log "
+        f"Internal check-family surface for {name} (family_hint='{family}'). "
+        "Use this only through the core check primitive before a downstream "
+        "protected find/send action needs delegated authorization. Params must "
+        "follow input_schema_json exactly: scope_list contains "
+        "'<verb>:<adapter_family>.<action>' scope strings, purpose_ko is the "
+        "Korean citizen-facing consent purpose, and purpose_en is the audit-log "
         "English purpose. The manifest entry stays source_mode='internal' because "
         "the agency citation is emitted by the verify response transparency stamp, "
-        "while the pre-call tool schema remains stable for the TUI and LLM loop."
+        "while the pre-call tool schema remains stable for the TUI and LLM loop. "
+        "Do not mention internal mock bridge identifiers in citizen-facing prose."
         f"{scope_clause}"
     )
 
 
+def _safe_verify_scope_rules(scope_rules: str) -> str:
+    if not scope_rules:
+        return ""
+    safe_sentences: list[str] = []
+    for sentence in re.split(r"(?<=[.!?])\s+", scope_rules):
+        candidate = sentence.strip()
+        if not candidate:
+            continue
+        lowered = candidate.lower()
+        if "mock_verify" in lowered or "tool_id" in lowered:
+            continue
+        safe_sentences.append(candidate)
+    return " ".join(safe_sentences)
+
+
 def _string_list(value: object) -> list[str]:
     """Return non-empty strings from a loosely typed metadata list."""
 

package/src/ummaya/ipc/document_intent_normalization.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import re
+import uuid
+from pathlib import Path
+from typing import Final
+
+_DOCUMENT_WRITE_REQUEST_RE: Final = re.compile(
+    r"(작성|수정|편집|채우|채워|입력|변경|저장|write|edit|fill|apply|save)",
+    re.IGNORECASE,
+)
+_DOCUMENT_SAVE_REQUEST_RE: Final = re.compile(
+    r"(저장|내보내|export|save)",
+    re.IGNORECASE,
+)
+_DOCUMENT_READ_ONLY_INSPECT_RE: Final = re.compile(
+    r"(구조.{0,30}빈칸.{0,30}확인|빈칸.{0,30}확인|구조.{0,30}확인|"
+    r"확인해\s*줘|검토만|inspect|read[- ]?only)",
+    re.IGNORECASE,
+)
+_DOCUMENT_MUTATION_PROHIBITION_RE: Final = re.compile(
+    r"(절대.{0,40}(?:수정|저장|작성|채우|입력|변경).{0,40}"
+    r"(?:하지\s*마|하지\s*말|금지)|"
+    r"(?:수정|저장|작성|채우|입력|변경).{0,30}(?:하지\s*마|하지\s*말)|"
+    r"(?:do not|don't).{0,40}(?:modify|save|write|edit|fill))",
+    re.IGNORECASE,
+)
+_QUESTION_FIRST_AUTHORING_RE: Final = re.compile(
+    r"(근거가\s*부족하면\s*먼저\s*질문|먼저\s*(?:확인|파악|검토|질문|물어)|"
+    r"초안을?\s*먼저|아직.{0,40}(?:쓰지\s*마|작성하지\s*마|저장하지\s*마|"
+    r"반영하지\s*마)|문서에는\s*쓰지\s*마)",
+    re.IGNORECASE,
+)
+_DOCUMENT_MUTATION_PARAM_KEYS: Final[frozenset[str]] = frozenset(
+    {
+        "approved_draft_id",
+        "destination_display_name",
+        "destination_path",
+        "dry_run",
+        "patches",
+        "styles",
+        "template_id",
+    }
+)
+_DOCUMENT_INTERNAL_USER_QUERY_KEY: Final = "__ummaya_user_query"
+_DOCUMENT_ROOT_SYNTHESIS_KEYS: Final[frozenset[str]] = frozenset(
+    {_DOCUMENT_INTERNAL_USER_QUERY_KEY}
+)
+_DOCUMENT_EXPLICIT_LOCAL_PATH_RE: Final = re.compile(
+    r"(?P<path>(?:~|/)[^\s\"'<>]+?\."
+    r"(?:hwpx|hwp|docx|pdf|xlsx|pptx|odt|ods|odp|doc|xls|ppt|csv|txt|md|json|xml|html))",
+    re.IGNORECASE,
+)
+
+
+def _normalize_document_root_call_for_user_intent(
+    fname: str,
+    args_obj: dict[str, object],
+    latest_user_utt: str,
+) -> dict[str, object]:
+    if fname != "document" or args_obj.get("tool_id") != "document":
+        return args_obj
+    params_obj = args_obj.get("params")
+    if not isinstance(params_obj, dict):
+        return args_obj
+
+    intent_text = _document_intent_text(params_obj, latest_user_utt)
+    synthesized_params = _synthesize_document_read_params(params_obj, intent_text)
+    if synthesized_params is not None:
+        return {**args_obj, "params": synthesized_params}
+
+    normalized_params = dict(params_obj)
+    normalized_params.pop(_DOCUMENT_INTERNAL_USER_QUERY_KEY, None)
+    _normalize_document_path_from_user_query(normalized_params, intent_text)
+    if _is_explicit_read_only_inspect_intent(intent_text):
+        read_only_params = _strip_mutation_params(normalized_params)
+        read_only_params["operation"] = "inspect"
+        read_only_params["instruction"] = intent_text
+        return {**args_obj, "params": read_only_params}
+
+    operation = str(params_obj.get("operation") or "").casefold()
+    changed = normalized_params != params_obj
+    if (
+        operation in {"fill", "save"}
+        and intent_text
+        and _DOCUMENT_WRITE_REQUEST_RE.search(intent_text)
+    ):
+        if _DOCUMENT_SAVE_REQUEST_RE.search(intent_text):
+            normalized_params["operation"] = "save"
+        normalized_params["instruction"] = intent_text
+        return {**args_obj, "params": normalized_params}
+    if operation not in {"inspect", "extract"}:
+        return {**args_obj, "params": normalized_params} if changed else args_obj
+    if _should_keep_read_only_for_question_first_authoring(intent_text):
+        return {**args_obj, "params": normalized_params} if changed else args_obj
+    if not intent_text or not _DOCUMENT_WRITE_REQUEST_RE.search(intent_text):
+        return {**args_obj, "params": normalized_params} if changed else args_obj
+
+    normalized_params["operation"] = (
+        "save" if _DOCUMENT_SAVE_REQUEST_RE.search(intent_text) else "fill"
+    )
+    normalized_params["instruction"] = intent_text
+    return {**args_obj, "params": normalized_params}
+
+
+def _document_intent_text(params_obj: dict[str, object], latest_user_utt: str) -> str:
+    internal_user_query = params_obj.get(_DOCUMENT_INTERNAL_USER_QUERY_KEY)
+    if isinstance(internal_user_query, str) and internal_user_query.strip():
+        return internal_user_query.strip()
+    return latest_user_utt
+
+
+def _synthesize_document_read_params(
+    params_obj: dict[str, object],
+    intent_text: str,
+) -> dict[str, object] | None:
+    if (
+        not intent_text
+        or isinstance(params_obj.get("document"), dict)
+        or set(params_obj) - _DOCUMENT_ROOT_SYNTHESIS_KEYS
+    ):
+        return None
+    local_path = _first_existing_document_path(intent_text, None)
+    if local_path is None:
+        return None
+    document_format = local_path.suffix.removeprefix(".").lower()
+    return {
+        "correlation_id": f"document-intent-{uuid.uuid4().hex}",
+        "document": {"path": str(local_path), "expected_format": document_format},
+        "operation": "inspect",
+        "instruction": intent_text,
+    }
+
+
+def _normalize_document_path_from_user_query(
+    normalized_params: dict[str, object],
+    intent_text: str,
+) -> None:
+    if not intent_text:
+        return
+    document_obj = normalized_params.get("document")
+    if not isinstance(document_obj, dict):
+        return
+    current_path = document_obj.get("path")
+    if isinstance(current_path, str) and Path(current_path).expanduser().exists():
+        return
+    expected_format = document_obj.get("expected_format")
+    expected_suffix = f".{expected_format}".lower() if isinstance(expected_format, str) else None
+    explicit_path = _first_existing_document_path(intent_text, expected_suffix)
+    if explicit_path is None:
+        return
+    normalized_params["document"] = {
+        **document_obj,
+        "path": str(explicit_path),
+    }
+
+
+def _first_existing_document_path(intent_text: str, expected_suffix: str | None) -> Path | None:
+    for match in _DOCUMENT_EXPLICIT_LOCAL_PATH_RE.finditer(intent_text):
+        candidate = Path(match.group("path").rstrip(".,;:)]}）")).expanduser()
+        if expected_suffix is not None and candidate.suffix.lower() != expected_suffix:
+            continue
+        if candidate.exists():
+            return candidate.resolve()
+    return None
+
+
+def _should_keep_read_only_for_question_first_authoring(intent_text: str) -> bool:
+    return bool(intent_text and _QUESTION_FIRST_AUTHORING_RE.search(intent_text))
+
+
+def _is_explicit_read_only_inspect_intent(intent_text: str) -> bool:
+    return bool(
+        intent_text
+        and _DOCUMENT_READ_ONLY_INSPECT_RE.search(intent_text)
+        and _DOCUMENT_MUTATION_PROHIBITION_RE.search(intent_text)
+    )
+
+
+def _strip_mutation_params(params_obj: dict[str, object]) -> dict[str, object]:
+    return {
+        key: value for key, value in params_obj.items() if key not in _DOCUMENT_MUTATION_PARAM_KEYS
+    }

package/src/ummaya/ipc/frame_schema.py

@@ -56,6 +56,7 @@ _ROLE_KIND_ALLOW_LIST: dict[str, frozenset[str]] = {
     # Spec 1978 ADR-0001 — tools-aware chat request from TUI
     "chat_request": frozenset({"tui"}),
     "assistant_chunk": frozenset({"backend", "llm"}),
+    "progress_event": frozenset({"backend"}),
     "tool_call": frozenset({"backend", "tool"}),
     "tool_result": frozenset({"backend", "tool"}),
     "coordinator_phase": frozenset({"backend"}),
@@ -385,6 +386,10 @@ class ChatRequestFrame(_BaseFrame):
         le=1.0,
         description="Nucleus sampling threshold.",
     )
+    reasoning_mode: Literal["fast", "balanced", "deep", "diagnostic", "auto"] | None = Field(
+        default=None,
+        description="K-EXAONE/FriendliAI reasoning policy for this assistant turn.",
+    )
 
     @model_validator(mode="after")
     def _v_tool_message_integrity(self) -> ChatRequestFrame:
@@ -449,6 +454,46 @@ class AssistantChunkFrame(_BaseFrame):
     done: bool = Field(description="True if this is the terminal chunk for this message_id.")
 
 
+# ---------------------------------------------------------------------------
+# Arm: progress_event  (UMMAYA query-loop painting — deterministic and safe)
+# ---------------------------------------------------------------------------
+
+
+class ProgressEventFrame(_BaseFrame):
+    """backend -> TUI: deterministic query-loop progress.
+
+    This is intentionally separate from ``AssistantChunkFrame.thinking``.
+    ``progress_event`` carries safe harness state such as analysis, tool
+    selection, tool dispatch/result, and answer synthesis. Provider reasoning
+    remains on the gated ``thinking_delta`` channel.
+    """
+
+    kind: Literal["progress_event"] = Field(
+        default="progress_event", description="Frame discriminator."
+    )
+    phase: Literal[
+        "analysis",
+        "tool_selection",
+        "tool_call",
+        "tool_result",
+        "answer_synthesis",
+    ] = Field(description="Safe query-loop phase represented by this event.")
+    message_ko: str = Field(min_length=1, description="Korean progress text for the TUI.")
+    message_en: str = Field(min_length=1, description="English fallback progress text.")
+    safe_to_persist: bool = Field(
+        default=True,
+        description="True because this channel never carries raw provider chain-of-thought.",
+    )
+    tool_id: str | None = Field(
+        default=None,
+        description="Concrete adapter/tool id when this event is tied to one.",
+    )
+    call_id: str | None = Field(
+        default=None,
+        description="Tool call id when this event is tied to a specific invocation.",
+    )
+
+
 # ---------------------------------------------------------------------------
 # Arm: tool_call  (Spec 287 baseline — arguments changed from Any to dict[str, object])
 # ---------------------------------------------------------------------------
@@ -483,7 +528,7 @@ class ToolResultEnvelope(BaseModel):
 
     model_config = ConfigDict(frozen=True, extra="allow", populate_by_name=True)
 
-    kind: Literal["find", "locate", "send", "check"] = Field(
+    kind: Literal["find", "locate", "send", "check", "document"] = Field(
         description="Primitive kind discriminator per Spec 031."
     )
 
@@ -531,7 +576,7 @@ class WorkerStatusFrame(_BaseFrame):
     role_id: str = Field(
         description="Specialist label (e.g., transport-specialist, health-specialist)."
     )
-    current_primitive: Literal["find", "locate", "send", "check"] = Field(
+    current_primitive: Literal["find", "locate", "send", "check", "document"] = Field(
         description="Primitive currently being invoked by this worker."
     )
     status: Literal["idle", "running", "waiting_permission", "error"] = Field(
@@ -554,7 +599,7 @@ class PermissionRequestFrame(_BaseFrame):
         description="ULID; round-trips in the matching permission_response frame."
     )
     worker_id: str = Field(description="Worker requesting permission.")
-    primitive_kind: Literal["find", "locate", "send", "check"] = Field(
+    primitive_kind: Literal["find", "locate", "send", "check", "document"] = Field(
         description="The primitive the worker wants to invoke."
     )
     description_ko: str = Field(description="Korean-language description shown to the citizen.")
@@ -624,7 +669,7 @@ class PermissionResponseFrame(_BaseFrame):
     # `layer: 1, tool_name: 'unknown'` (UI-C-1 spec violation: Layer 2/3
     # submits were colour-coded green like a Layer 1 verify).
     # Both fields are optional so legacy backends remain wire-compatible.
-    primitive_kind: Literal["find", "locate", "send", "check"] | None = Field(
+    primitive_kind: Literal["find", "locate", "send", "check", "document"] | None = Field(
         default=None,
         description=(
             "The primitive that was authorised. The TUI feeds this into "
@@ -1175,7 +1220,7 @@ class AdapterManifestEntry(BaseModel):
         max_length=80,
         description="Human-readable display name; bilingual permitted.",
     )
-    primitive: Literal["find", "send", "check", "locate"] = Field(
+    primitive: Literal["find", "send", "check", "locate", "document"] = Field(
         description="Primitive verb the adapter is registered under (I6).",
     )
     policy_authority_url: str | None = Field(
@@ -1436,6 +1481,7 @@ IPCFrame = Annotated[
     UserInputFrame
     | ChatRequestFrame
     | AssistantChunkFrame
+    | ProgressEventFrame
     | ToolCallFrame
     | ToolResultFrame
     | CoordinatorPhaseFrame
@@ -1505,6 +1551,7 @@ __all__ = [
     "ToolDefinition",
     "ToolDefinitionFunction",
     "AssistantChunkFrame",
+    "ProgressEventFrame",
     "ToolCallFrame",
     "ToolResultFrame",
     "ToolResultEnvelope",

package/src/ummaya/ipc/route_diagnostics.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ummaya.tools.routing import RouteDecision, RouteStopReason, SchemaProjectionLevel
+
+
+class RouteDecisionDiagnosticPayload(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    turn_index: int = Field(ge=1)
+    session_id: str = Field(min_length=1)
+    correlation_id: str = Field(min_length=1)
+    decision_id: str = Field(min_length=1)
+    query_hash: str = Field(min_length=64, max_length=64)
+    manifest_hash: str = Field(min_length=64, max_length=64)
+    backend_label: str = Field(min_length=1)
+    selected_tools: tuple[str, ...]
+    candidate_count: int = Field(ge=0)
+    effective_top_k: int = Field(ge=0)
+    schema_projection_level: SchemaProjectionLevel
+    stop_reason: RouteStopReason
+    permission_gate: bool
+    clarification_reason: (
+        Literal[
+            "missing_slots",
+            "equal_candidates",
+            "side_effect_confirmation",
+            "execution_risk_input_fault",
+        ]
+        | None
+    )
+    evidence_events: tuple[str, ...]
+
+
+def log_route_decision_diagnostic(
+    *,
+    logger: logging.Logger,
+    turn_index: int,
+    session_id: str,
+    correlation_id: str,
+    decision: RouteDecision | None,
+) -> None:
+    if decision is None:
+        return
+    clarification_reason = None if decision.clarification is None else decision.clarification.reason
+    payload = RouteDecisionDiagnosticPayload(
+        turn_index=turn_index,
+        session_id=session_id,
+        correlation_id=correlation_id,
+        decision_id=decision.decision_id,
+        query_hash=decision.query_hash,
+        manifest_hash=decision.manifest_hash,
+        backend_label=decision.backend_label,
+        selected_tools=decision.selected_tools,
+        candidate_count=len(decision.candidate_set),
+        effective_top_k=decision.effective_top_k,
+        schema_projection_level=decision.schema_projection_level,
+        stop_reason=decision.stop_reason,
+        permission_gate=decision.permission_gate,
+        clarification_reason=clarification_reason,
+        evidence_events=decision.evidence_events,
+    )
+    logger.info(
+        "[ROUTE_DECISION] payload=%s",
+        json.dumps(payload.model_dump(mode="json"), ensure_ascii=False, sort_keys=True),
+    )