flare-kernel 0.2.0__tar.gz → 0.2.2__tar.gz

{flare_kernel-0.2.0 → flare_kernel-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flare-kernel
-Version: 0.2.0
+Version: 0.2.2
 Summary: FLARE kernel runtime package
 License: Proprietary
 Classifier: Development Status :: 3 - Alpha
@@ -22,6 +22,11 @@ Requires-Dist: qdrant-client<2,>=1.9
 
 通用编排与执行内核。
 
+边界文档：
+
+1. `packages/flare-kernel/docs/KERNEL-BOUNDARY.md`
+2. `docs/contracts/agent-contract-v1.md`
+
 职责：
 
 1. Decision 路由与策略入口。

{flare_kernel-0.2.0 → flare_kernel-0.2.2}/README.md

@@ -2,6 +2,11 @@
 
 通用编排与执行内核。
 
+边界文档：
+
+1. `packages/flare-kernel/docs/KERNEL-BOUNDARY.md`
+2. `docs/contracts/agent-contract-v1.md`
+
 职责：
 
 1. Decision 路由与策略入口。

{flare_kernel-0.2.0 → flare_kernel-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "flare-kernel"
-version = "0.2.0"
+version = "0.2.2"
 description = "FLARE kernel runtime package"
 readme = "README.md"
 requires-python = ">=3.11"

{flare_kernel-0.2.0 → flare_kernel-0.2.2}/src/flare_kernel/contracts/kernel_contract.py

@@ -4,14 +4,48 @@ from __future__ import annotations
 
 from typing import Any, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
+
+
+class IntakeFieldValue(BaseModel):
+    kind: Literal["single_choice", "multi_choice", "free_text", "number", "range", "candidate_ref"]
+    value: Any = None
+    display_value: str | None = None
+    values: list[Any] | None = None
+    text: str | None = None
+    number: float | int | None = None
+    min: float | int | None = None
+    max: float | int | None = None
+    unit: str | None = None
+    currency: str | None = None
+    candidate_id: str | None = None
+
+    @model_validator(mode="after")
+    def validate_shape(self) -> "IntakeFieldValue":
+        if self.kind == "single_choice" and self.value in (None, ""):
+            raise ValueError("single_choice requires value")
+        if self.kind == "multi_choice" and not isinstance(self.values, list):
+            raise ValueError("multi_choice requires values[]")
+        if self.kind == "free_text" and not str(self.text or "").strip():
+            raise ValueError("free_text requires text")
+        if self.kind == "number" and self.number is None:
+            raise ValueError("number requires number")
+        if self.kind == "range" and (self.min is None or self.max is None):
+            raise ValueError("range requires min and max")
+        if self.kind == "candidate_ref" and not str(self.candidate_id or "").strip():
+            raise ValueError("candidate_ref requires candidate_id")
+        return self
 
 
 class KernelRequest(BaseModel):
+    contract_version: str = "flare.v1"
+    client_request_id: str | None = None
     tenant_id: str = "default"
     instance_id: str = "default"
     domain_pack_version: str = "v1"
-    session_id: str = "default"
+    session_id: str | None = None
+    last_turn_id: str | None = None
+    command: str | None = None
     intent: str = "default"
     intent_override: str | None = None
     mode: str | None = None
@@ -30,6 +64,9 @@ class KernelRequest(BaseModel):
     action_status: str | None = None
     action_reason: str | None = None
     trace_id: str | None = None
+    question_id: str | None = None
+    field_key: str | None = None
+    field_value: IntakeFieldValue | None = None
 
 
 class KernelResponse(BaseModel):
@@ -71,6 +108,9 @@ class KnowledgeIngestResponse(BaseModel):
     chunk_count: int
     status: Literal["stored", "partial", "failed"]
     details: dict[str, Any] = Field(default_factory=dict)
+    source_id: str | None = None
+    error_code: str | None = None
+    error_message: str | None = None
 
 
 class KnowledgeSearchRequest(BaseModel):

flare_kernel-0.2.2/src/flare_kernel/router/__init__.py

@@ -0,0 +1,45 @@
+"""Kernel routers.
+
+This package keeps ``kernel_router`` as the public entrypoint and also provides
+legacy module-name compatibility for recently grouped router modules.
+"""
+
+from __future__ import annotations
+
+import importlib
+import sys
+
+from flare_kernel.router.kernel import router as kernel_router
+
+__all__ = ["kernel_router"]
+
+
+def _resolve_legacy_group(module_name: str) -> str | None:
+    if module_name.startswith("canonical_state_"):
+        return "canonical"
+    if module_name.startswith("orchestration_"):
+        return "orchestration"
+    if module_name.startswith("streaming_"):
+        return "streaming"
+    if module_name.startswith("intake_"):
+        return "intake"
+    if module_name == "session_intent" or module_name.startswith("session_intent_"):
+        return "intent"
+    if module_name.startswith("intent_"):
+        return "intent"
+    if module_name.startswith("retrieval_"):
+        return "retrieval"
+    return None
+
+
+def __getattr__(name: str):
+    """Resolve legacy ``flare_kernel.router.<module>`` access to grouped modules."""
+    group = _resolve_legacy_group(name)
+    if not group:
+        raise AttributeError(f"module 'flare_kernel.router' has no attribute {name!r}")
+
+    target = f"flare_kernel.router.{group}.{name}"
+    module = importlib.import_module(target)
+    # Register alias so direct imports by the legacy module path also resolve.
+    sys.modules.setdefault(f"flare_kernel.router.{name}", module)
+    return module

flare_kernel-0.2.2/src/flare_kernel/router/action_payload.py

@@ -0,0 +1,148 @@
+"""Action target mode and payload shaping helpers."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable
+
+from flare_kernel.contracts import KernelRequest
+
+_LEGACY_SOURCING_BASE_FIELDS_ENV = "FLARE_COMPAT_ENABLE_LEGACY_SOURCING_BASE_FIELDS"
+_LEGACY_SOURCING_BASE_FIELDS = ("category", "region")
+
+
+def resolve_action_target_mode(req: KernelRequest) -> str:
+    target_mode = req.target_mode
+    if isinstance(target_mode, str):
+        normalized = target_mode.strip()
+        if normalized in {"requirement_canvas", "intelligent_sourcing", "plan_mode"}:
+            return normalized
+
+    action_key = req.action_key if isinstance(req.action_key, str) else ""
+    if action_key == "handoff_to_sourcing":
+        return "intelligent_sourcing"
+    if action_key == "handoff_to_domain_flow":
+        return "intelligent_sourcing"
+    if action_key == "continue_collection":
+        return "requirement_canvas"
+    if action_key == "confirm_plan":
+        return "plan_mode"
+    if action_key == "confirm_sourcing":
+        return "intelligent_sourcing"
+    if action_key == "confirm_domain_flow":
+        return "intelligent_sourcing"
+
+    return req.intent if isinstance(req.intent, str) and req.intent.strip() else "default"
+
+
+def _normalize_key(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip().lower().replace("-", "_").replace(" ", "_")
+
+
+def _extract_value(raw_value: Any) -> Any:
+    if isinstance(raw_value, dict):
+        for candidate in ("value", "content", "text"):
+            candidate_value = raw_value.get(candidate)
+            if candidate_value not in (None, "", [], {}):
+                return candidate_value
+    return raw_value
+
+
+def _legacy_sourcing_base_fields_enabled() -> bool:
+    raw = os.getenv(_LEGACY_SOURCING_BASE_FIELDS_ENV)
+    if raw is None:
+        return False
+    value = raw.strip().lower()
+    return value not in {"0", "false", "off", "no"}
+
+
+def _resolve_sourcing_base_field_keys(payload: dict[str, Any]) -> tuple[str, ...]:
+    explicit = payload.get("sourcing_base_field_keys")
+    if isinstance(explicit, list):
+        normalized = [str(item).strip() for item in explicit if str(item).strip()]
+        if normalized:
+            return tuple(dict.fromkeys(normalized))
+    if _legacy_sourcing_base_fields_enabled():
+        return _LEGACY_SOURCING_BASE_FIELDS
+    return ()
+
+
+def collect_sourcing_base_fields_from_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    base_field_keys = _resolve_sourcing_base_field_keys(payload)
+    if not base_field_keys:
+        return {}
+
+    raw_base_fields = payload.get("base_fields")
+    if isinstance(raw_base_fields, dict):
+        return dict(raw_base_fields)
+
+    base_fields: dict[str, Any] = {}
+    raw_fields = payload.get("fields")
+
+    if isinstance(raw_fields, dict):
+        for key in base_field_keys:
+            if key not in raw_fields:
+                continue
+            value = _extract_value(raw_fields.get(key))
+            if value not in (None, "", [], {}):
+                base_fields[key] = value
+    elif isinstance(raw_fields, list):
+        for raw_item in raw_fields:
+            if not isinstance(raw_item, dict):
+                continue
+            field_key = ""
+            for candidate in ("field_key", "name", "id", "key", "label"):
+                candidate_value = raw_item.get(candidate)
+                if isinstance(candidate_value, str) and candidate_value.strip():
+                    field_key = candidate_value.strip()
+                    break
+            normalized_key = _normalize_key(field_key)
+            if normalized_key not in set(base_field_keys):
+                continue
+            value = _extract_value(raw_item.get("value", raw_item.get("content", raw_item.get("text"))))
+            if value not in (None, "", [], {}):
+                base_fields[normalized_key] = value
+
+    for key in base_field_keys:
+        if key in base_fields:
+            continue
+        value = payload.get(key)
+        if value not in (None, "", [], {}):
+            base_fields[key] = value
+
+    return base_fields
+
+
+def build_action_payload(
+    req: KernelRequest,
+    target_mode: str,
+    *,
+    collect_sourcing_base_fields: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    payload = dict(req.payload) if isinstance(req.payload, dict) else {}
+    payload["function_type"] = target_mode
+    payload["target_mode"] = target_mode
+    if isinstance(req.action_key, str) and req.action_key.strip():
+        payload["action_key"] = req.action_key.strip()
+    if isinstance(req.action_status, str) and req.action_status.strip():
+        payload["action_status"] = req.action_status.strip()
+    if isinstance(req.action_reason, str) and req.action_reason.strip():
+        payload["action_reason"] = req.action_reason.strip()
+    if isinstance(req.action_key, str) and req.action_key.strip() == "confirm_sourcing":
+        payload["sourcing_confirmed"] = True
+    if isinstance(req.retrieval_config, dict) and req.retrieval_config:
+        payload["retrieval_config"] = dict(req.retrieval_config)
+    if isinstance(req.canvas_config, dict) and req.canvas_config:
+        payload["canvas_config"] = dict(req.canvas_config)
+    if isinstance(req.plan_config, dict) and req.plan_config:
+        payload["plan_config"] = dict(req.plan_config)
+
+    if target_mode == "intelligent_sourcing":
+        collect_fn = collect_sourcing_base_fields or collect_sourcing_base_fields_from_payload
+        base_fields = collect_fn(payload)
+        if base_fields:
+            payload["base_fields"] = base_fields
+
+    return payload

flare_kernel-0.2.2/src/flare_kernel/router/canonical/__init__.py

@@ -0,0 +1 @@
+"""Router canonical module group."""

flare_kernel-0.2.2/src/flare_kernel/router/canonical/canonical_state_analysis.py

@@ -0,0 +1,53 @@
+"""Analysis/retrieval projection helpers for canonical state."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def apply_analysis_and_retrieval_projection(
+    *,
+    canonical: dict[str, Any],
+    command: str,
+    can_generate: bool,
+    assistant_text: str,
+    normalized_retrieved_knowledge: list[dict[str, Any]],
+) -> None:
+    if command == "generate_analysis" and can_generate and assistant_text:
+        canonical["analysis"]["sections"].append({"id": "analysis", "title": "需求分析", "content": assistant_text})
+    if command == "generate_analysis" and normalized_retrieved_knowledge:
+        evidence_rows = normalized_retrieved_knowledge[:3]
+        evidence_titles = [str(item.get("title") or item.get("candidate_value") or item.get("snippet") or "证据") for item in evidence_rows]
+        evidence_summary = f"检索到 {len(normalized_retrieved_knowledge)} 条证据"
+        if evidence_titles:
+            evidence_summary = f"{evidence_summary}，重点参考：{'；'.join(evidence_titles[:3])}"
+        canonical["analysis"]["sections"].append(
+            {
+                "id": "evidence",
+                "title": "检索证据",
+                "content": evidence_summary,
+            }
+        )
+    if not normalized_retrieved_knowledge:
+        return
+    comparison_rows: list[dict[str, Any]] = []
+    for item in normalized_retrieved_knowledge[:3]:
+        comparison_rows.append(
+            {
+                "record_id": item.get("record_id"),
+                "chunk_id": item.get("chunk_id"),
+                "title": str(item.get("title") or item.get("candidate_value") or "证据条目"),
+                "source": str(item.get("source") or item.get("source_type") or "local"),
+                "score": item.get("score"),
+                "snippet": str(item.get("snippet") or item.get("content") or "")[:220],
+                "matched_field": str(item.get("matched_field") or ""),
+                "candidate_value": str(item.get("candidate_value") or ""),
+                "confidence": item.get("confidence"),
+                "why_relevant": str(item.get("why_relevant") or ""),
+            }
+        )
+    canonical["capabilities"]["field_retrieval"]["comparison_rows"] = comparison_rows
+    canonical["capabilities"]["field_retrieval"]["recommendation_summary"] = (
+        f"已检索到 {len(normalized_retrieved_knowledge)} 条候选证据，优先查看 "
+        + "；".join(str(item.get("title") or item.get("candidate_value") or "证据条目") for item in comparison_rows)
+    )

flare_kernel-0.2.2/src/flare_kernel/router/canonical/canonical_state_builder.py

@@ -0,0 +1,82 @@
+"""Canonical state projection builder for router responses."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from flare_kernel.contracts import KernelRequest
+from flare_kernel.router.canonical.canonical_state_context import (
+    resolve_canonical_state_context,
+)
+from flare_kernel.router.canonical.canonical_state_payload import (
+    build_canonical_payload,
+)
+from flare_kernel.router.canonical.canonical_state_projection import (
+    apply_analysis_and_retrieval_projection,
+    normalize_retrieved_knowledge,
+)
+
+
+def build_canonical_state(
+    *,
+    req: KernelRequest,
+    command: str,
+    resolved_intent: str,
+    resolved_mode: str,
+    mode_source: str,
+    orchestration_status: dict[str, Any],
+    runtime_snapshot: dict[str, Any],
+    assistant_text: str,
+    provider_status: str,
+    structured_retrieved_knowledge: list[dict[str, Any]] | None = None,
+    map_external_mode_fn: Callable[[str], str],
+    resolve_session_intent_stage_fn: Callable[..., str],
+    coerce_intent_escalation_policy_fn: Callable[[Any], dict[str, Any]],
+    normalize_stage_status_fn: Callable[..., tuple[str, str]],
+    build_confirmed_fields_schema_fn: Callable[[dict[str, Any], dict[str, Any]], dict[str, Any]],
+    build_missing_fields_schema_fn: Callable[[list[str]], dict[str, Any]],
+    is_field_entity_confirmed_fn: Callable[[Any], bool],
+    extract_user_message_fn: Callable[[dict[str, Any] | None], str],
+    normalize_intake_session_id_fn: Callable[[Any], str],
+    resolve_trace_id_fn: Callable[[str | None], str],
+    safe_session_id_fn: Callable[[Any], str],
+) -> dict[str, Any]:
+    _ = runtime_snapshot
+    normalized_retrieved_knowledge = normalize_retrieved_knowledge(structured_retrieved_knowledge)
+    canonical_context = resolve_canonical_state_context(
+        req=req,
+        command=command,
+        resolved_intent=resolved_intent,
+        resolved_mode=resolved_mode,
+        mode_source=mode_source,
+        orchestration_status=orchestration_status,
+        assistant_text=assistant_text,
+        map_external_mode_fn=map_external_mode_fn,
+        resolve_session_intent_stage_fn=resolve_session_intent_stage_fn,
+        coerce_intent_escalation_policy_fn=coerce_intent_escalation_policy_fn,
+        normalize_stage_status_fn=normalize_stage_status_fn,
+        is_field_entity_confirmed_fn=is_field_entity_confirmed_fn,
+        extract_user_message_fn=extract_user_message_fn,
+        normalize_intake_session_id_fn=normalize_intake_session_id_fn,
+    )
+    canonical = build_canonical_payload(
+        req=req,
+        command=command,
+        mode_source=mode_source,
+        orchestration_status=orchestration_status,
+        assistant_text=assistant_text,
+        provider_status=provider_status,
+        canonical_context=canonical_context,
+        build_confirmed_fields_schema_fn=build_confirmed_fields_schema_fn,
+        build_missing_fields_schema_fn=build_missing_fields_schema_fn,
+        resolve_trace_id_fn=resolve_trace_id_fn,
+        safe_session_id_fn=safe_session_id_fn,
+    )
+    apply_analysis_and_retrieval_projection(
+        canonical=canonical,
+        command=command,
+        can_generate=bool(canonical_context.get("can_generate")),
+        assistant_text=assistant_text,
+        normalized_retrieved_knowledge=normalized_retrieved_knowledge,
+    )
+    return canonical

flare_kernel-0.2.2/src/flare_kernel/router/canonical/canonical_state_checkpoint.py

@@ -0,0 +1,102 @@
+"""Checkpoint projection helpers for canonical state."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def build_checkpoint_projection(
+    *,
+    orchestration_status: dict[str, Any],
+    intake_session_id: str,
+    status_key: str,
+    current_question: dict[str, Any] | None,
+    fields: dict[str, str],
+    required_missing: list[str],
+    session_id: str,
+    activated_mode: str,
+) -> dict[str, Any]:
+    raw_checkpoint = (
+        orchestration_status.get("checkpoint")
+        if isinstance(orchestration_status.get("checkpoint"), dict)
+        else {}
+    )
+    try:
+        checkpoint_version = int(raw_checkpoint.get("version") or 1)
+    except (TypeError, ValueError):
+        checkpoint_version = 1
+    checkpoint = {
+        "checkpoint_id": str(raw_checkpoint.get("checkpoint_id") or "").strip(),
+        "intake_session_id": str(raw_checkpoint.get("intake_session_id") or intake_session_id or "").strip(),
+        "checkpoint_type": str(raw_checkpoint.get("checkpoint_type") or "").strip(),
+        "checkpoint_state": str(raw_checkpoint.get("checkpoint_state") or "").strip(),
+        "current_stage": str(raw_checkpoint.get("current_stage") or "").strip(),
+        "question_key": str(raw_checkpoint.get("question_key") or "").strip(),
+        "ready_for_submit": bool(raw_checkpoint.get("ready_for_submit")),
+        "decision_point_active": bool(raw_checkpoint.get("decision_point_active")),
+        "updated_at": str(raw_checkpoint.get("updated_at") or "").strip(),
+        "waiting_user": bool(
+            orchestration_status.get("checkpoint_waiting_user") is True
+            or str(raw_checkpoint.get("checkpoint_state") or "").strip().lower() == "waiting_user"
+        ),
+        "workflow_id": str(raw_checkpoint.get("workflow_id") or "").strip(),
+        "session_id": str(raw_checkpoint.get("session_id") or session_id or "").strip(),
+        "mode": str(raw_checkpoint.get("mode") or activated_mode or "").strip(),
+        "status": str(raw_checkpoint.get("status") or "").strip(),
+        "active_checkpoint_id": str(raw_checkpoint.get("active_checkpoint_id") or raw_checkpoint.get("checkpoint_id") or "").strip(),
+        "version": max(1, checkpoint_version),
+        "checkpoints": (
+            [item for item in raw_checkpoint.get("checkpoints") if isinstance(item, dict)]
+            if isinstance(raw_checkpoint.get("checkpoints"), list)
+            else []
+        ),
+    }
+    if not checkpoint["workflow_id"] and checkpoint["intake_session_id"]:
+        checkpoint["workflow_id"] = f"wf_{checkpoint['intake_session_id']}"
+    if not checkpoint["status"]:
+        if status_key == "ready_for_submit":
+            checkpoint["status"] = "succeeded"
+        elif status_key in {"collecting", "blocked"}:
+            checkpoint["status"] = "waiting_user"
+        else:
+            checkpoint["status"] = "queued"
+    if not checkpoint["checkpoints"] and checkpoint["checkpoint_id"]:
+        current_question_text = ""
+        current_question_field = ""
+        if isinstance(current_question, dict):
+            current_question_text = str(current_question.get("question_text") or "").strip()
+            current_question_field = str(current_question.get("field_key") or "").strip()
+        checkpoint["checkpoints"] = [
+            {
+                "checkpoint_id": checkpoint["checkpoint_id"],
+                "seq": 1,
+                "title": "需求梳理",
+                "stage": "clarification" if status_key in {"collecting", "blocked"} else "intake",
+                "status": checkpoint["status"],
+                "question": (
+                    {
+                        "question_id": f"question::{current_question_field}" if current_question_field else "",
+                        "text": current_question_text,
+                        "target_fields": [current_question_field] if current_question_field else [],
+                    }
+                    if current_question_text or current_question_field
+                    else None
+                ),
+                "confirmed_fields": [
+                    {
+                        "field_key": field_key,
+                        "display_value": field_value,
+                        "confidence": 0.85,
+                    }
+                    for field_key, field_value in fields.items()
+                ],
+                "missing_fields": [
+                    {"field_key": field_key, "reason": "required_missing", "blocks": True}
+                    for field_key in required_missing
+                ],
+                "child_tasks": [],
+            }
+        ]
+    if not checkpoint["checkpoint_id"]:
+        return {}
+    return checkpoint

flare_kernel-0.2.2/src/flare_kernel/router/canonical/canonical_state_context.py

@@ -0,0 +1,88 @@
+"""Facade for canonical state context assembly.
+
+This module keeps the public entrypoint stable while delegating the work into
+three readable stages:
+1. normalize the incoming context inputs
+2. derive session-scoped context material
+3. assemble the canonical output consumed by the state builder
+
+The contract assumption is that each helper is pure with respect to the input
+payloads it receives; this facade only wires the stage outputs together.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from flare_kernel.contracts import KernelRequest
+from flare_kernel.router.canonical.canonical_state_context_analysis import (
+    build_canonical_state_context_output,
+)
+from flare_kernel.router.canonical.canonical_state_context_inputs import (
+    resolve_canonical_state_context_inputs,
+)
+from flare_kernel.router.canonical.canonical_state_context_session import (
+    resolve_canonical_state_context_session,
+)
+
+
+def resolve_canonical_state_context(
+    *,
+    req: KernelRequest,
+    command: str,
+    resolved_intent: str,
+    resolved_mode: str,
+    mode_source: str,
+    orchestration_status: dict[str, Any],
+    assistant_text: str,
+    map_external_mode_fn: Callable[[str], str],
+    resolve_session_intent_stage_fn: Callable[..., str],
+    coerce_intent_escalation_policy_fn: Callable[[Any], dict[str, Any]],
+    normalize_stage_status_fn: Callable[..., tuple[str, str]],
+    is_field_entity_confirmed_fn: Callable[[Any], bool],
+    extract_user_message_fn: Callable[[dict[str, Any] | None], str],
+    normalize_intake_session_id_fn: Callable[[Any], str],
+) -> dict[str, Any]:
+    """Resolve the canonical context used by the canonical state builder.
+
+    The function is intentionally thin: it does not infer policy, only
+    sequences the normalization, session resolution, and output assembly
+    stages so downstream callers can treat the result as a canonical snapshot.
+    """
+    # Stage 1: normalize the raw request and orchestration inputs into a
+    # compact context bundle that subsequent helpers can consume consistently.
+    context_inputs = resolve_canonical_state_context_inputs(
+        resolved_intent=resolved_intent,
+        resolved_mode=resolved_mode,
+        orchestration_status=orchestration_status,
+        map_external_mode_fn=map_external_mode_fn,
+        is_field_entity_confirmed_fn=is_field_entity_confirmed_fn,
+    )
+    # Stage 2: resolve the session-scoped fields that depend on the normalized
+    # context and request/session metadata.
+    context_session = resolve_canonical_state_context_session(
+        req=req,
+        command=command,
+        resolved_intent=resolved_intent,
+        mode_source=mode_source,
+        orchestration_status=orchestration_status,
+        assistant_text=assistant_text,
+        context_inputs=context_inputs,
+        map_external_mode_fn=map_external_mode_fn,
+        resolve_session_intent_stage_fn=resolve_session_intent_stage_fn,
+        coerce_intent_escalation_policy_fn=coerce_intent_escalation_policy_fn,
+        normalize_stage_status_fn=normalize_stage_status_fn,
+        extract_user_message_fn=extract_user_message_fn,
+        normalize_intake_session_id_fn=normalize_intake_session_id_fn,
+    )
+    # Stage 3: assemble the final canonical payload that the state builder
+    # consumes without having to re-run any normalization logic.
+    return build_canonical_state_context_output(
+        req=req,
+        command=command,
+        orchestration_status=orchestration_status,
+        assistant_text=assistant_text,
+        context_inputs=context_inputs,
+        context_session=context_session,
+        map_external_mode_fn=map_external_mode_fn,
+    )