flare-kernel 0.2.11__tar.gz → 0.2.12__tar.gz

{flare_kernel-0.2.11 → flare_kernel-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flare-kernel
-Version: 0.2.11
+Version: 0.2.12
 Summary: FLARE kernel runtime package
 License: Proprietary
 Classifier: Development Status :: 3 - Alpha
@@ -60,7 +60,8 @@ kernel 现已输出 mode/context 运行时占位事件与字段。
 1. kernel 支持从 domain-pack 读取品牌配置：
    `branding/instance-branding.json`
 2. 读取方式：
-   - 仅通过环境变量 `FLARE_DOMAIN_PACK_ROOT` 显式指定
+   - 优先通过环境变量 `FLARE_DOMAIN_PACK_ROOT` 显式指定
+   - 本地仓库运行时可回退到仓库根目录下的 `domain-packs/`
 3. 注入位置：
    - `POST /kernel/run` 响应 `result.instance_profile`
    - `POST /kernel/stream` SSE 事件 `instance_profile`

{flare_kernel-0.2.11 → flare_kernel-0.2.12}/README.md

@@ -38,7 +38,8 @@ kernel 现已输出 mode/context 运行时占位事件与字段。
 1. kernel 支持从 domain-pack 读取品牌配置：
    `branding/instance-branding.json`
 2. 读取方式：
-   - 仅通过环境变量 `FLARE_DOMAIN_PACK_ROOT` 显式指定
+   - 优先通过环境变量 `FLARE_DOMAIN_PACK_ROOT` 显式指定
+   - 本地仓库运行时可回退到仓库根目录下的 `domain-packs/`
 3. 注入位置：
    - `POST /kernel/run` 响应 `result.instance_profile`
    - `POST /kernel/stream` SSE 事件 `instance_profile`

{flare_kernel-0.2.11 → flare_kernel-0.2.12}/pyproject.toml

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

flare_kernel-0.2.12/src/flare_kernel/project_record_memory_store.py

@@ -0,0 +1,47 @@
+"""In-memory Project record storage for local runs without SQL DSN."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any
+
+_PROJECT_RECORDS: dict[str, dict[str, Any]] = {}
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def _normalize_text(value: Any) -> str:
+    return " ".join(str(value or "").split()).strip()
+
+
+def list_project_records() -> list[dict[str, Any]]:
+    return [
+        dict(record)
+        for record in sorted(
+            _PROJECT_RECORDS.values(),
+            key=lambda item: str(item.get("updated_at") or ""),
+            reverse=True,
+        )
+    ]
+
+
+def get_project_record(*, project_id: str) -> dict[str, Any] | None:
+    record = _PROJECT_RECORDS.get(_normalize_text(project_id))
+    return dict(record) if record else None
+
+
+def upsert_project_record(*, project_id: str, project_name: str | None, status: str | None) -> dict[str, Any]:
+    resolved_project_id = _normalize_text(project_id)
+    now = _now_iso()
+    existing = dict(_PROJECT_RECORDS.get(resolved_project_id) or {})
+    record = {
+        "project_id": resolved_project_id,
+        "project_name": _normalize_text(project_name) or _normalize_text(existing.get("project_name")) or resolved_project_id,
+        "status": _normalize_text(status) or _normalize_text(existing.get("status")) or "active",
+        "created_at": _normalize_text(existing.get("created_at")) or now,
+        "updated_at": now,
+    }
+    _PROJECT_RECORDS[resolved_project_id] = record
+    return dict(record)

{flare_kernel-0.2.11 → flare_kernel-0.2.12}/src/flare_kernel/project_store.py

@@ -2,9 +2,15 @@
 
 from __future__ import annotations
 
+import os
 from datetime import UTC, datetime
 from typing import Any
 
+from flare_kernel.project_record_memory_store import (
+    get_project_record,
+    list_project_records,
+    upsert_project_record,
+)
 from flare_kernel.runtime.infrastructure.database import build_sqlalchemy_engine
 from flare_kernel.session_store import list_sessions
 from flare_kernel.user_store import get_current_user_id
@@ -33,6 +39,10 @@ def _normalize_text(value: Any) -> str:
     return " ".join(str(value or "").split()).strip()
 
 
+def _use_in_memory_project_store() -> bool:
+    return not str(os.getenv("FLARE_POSTGRES_DSN") or "").strip()
+
+
 def _ensure_project_table(conn: Any, text_fn: Any) -> None:
     """Create the durable Project table when it does not exist.
 
@@ -111,6 +121,9 @@ def list_projects() -> list[dict[str, Any]]:
         Project view dictionaries sorted by persisted updated_at descending.
     """
 
+    if _use_in_memory_project_store():
+        return [_build_project_view(row) for row in list_project_records()]
+
     from sqlalchemy import text
 
     with _project_engine().begin() as conn:
@@ -144,6 +157,10 @@ def get_project(*, project_id: str) -> dict[str, Any] | None:
     if not resolved_project_id:
         return None
 
+    if _use_in_memory_project_store():
+        record = get_project_record(project_id=resolved_project_id)
+        return _build_project_view(record) if record else None
+
     from sqlalchemy import text
 
     with _project_engine().begin() as conn:
@@ -183,6 +200,10 @@ def upsert_project(*, project_id: str, project_name: str | None, status: str | N
     if not resolved_project_id:
         raise ValueError("project_id is required")
 
+    if _use_in_memory_project_store():
+        record = upsert_project_record(project_id=resolved_project_id, project_name=project_name, status=status)
+        return _build_project_view(record)
+
     now = _now_iso()
     next_project_name = _normalize_text(project_name)
     next_status = _normalize_text(status)

flare_kernel-0.2.12/src/flare_kernel/router/canonical/mode_projection.py

@@ -0,0 +1,47 @@
+"""Frontend-facing mode projection rules.
+
+This module owns round-end mode reset projection. It does not decide workflow
+state; it only maps canonical workflow state to composer-facing mode state.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+_ROUND_SCOPED_MODE_SOURCES = {"manual_hint", "current_hint"}
+_ROUND_SCOPED_COMMANDS = {
+    "activate_requirement_intake",
+    "submit_intake_answer",
+    "implement",
+    "apply",
+}
+
+
+def _clean_text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def resolve_round_end_mode_projection(
+    *,
+    activated_mode: str,
+    suggested_mode: Any,
+    mode_source: str,
+    command: str,
+    intake_session_completed: bool,
+) -> dict[str, Any]:
+    """Return frontend-facing mode projection for a completed round.
+
+    Manual mode hints and command activations are round-scoped. The workflow can
+    still expose stage/status/question separately, but composer active mode must
+    return to auto so the frontend does not persist manual mode locally.
+    """
+
+    reset_to_auto = bool(intake_session_completed) or _clean_text(mode_source) in _ROUND_SCOPED_MODE_SOURCES
+    if not reset_to_auto:
+        reset_to_auto = _clean_text(command).lower() in _ROUND_SCOPED_COMMANDS
+    if reset_to_auto:
+        return {"activated_mode": "auto", "suggested_mode": None}
+    return {"activated_mode": _clean_text(activated_mode) or "auto", "suggested_mode": suggested_mode}
+
+
+__all__ = ["resolve_round_end_mode_projection"]

{flare_kernel-0.2.11 → flare_kernel-0.2.12}/src/flare_kernel/router/canonical/payload.py

@@ -18,6 +18,7 @@ from flare_kernel.router.canonical.contract_support import (
 )
 from flare_kernel.router.canonical.composer_ui import build_composer_ui_projection
 from flare_kernel.router.canonical.context_authority import build_context_authority_projection
+from flare_kernel.router.canonical.mode_projection import resolve_round_end_mode_projection
 from flare_kernel.router.canonical.projection import resolve_canonical_next_actions
 from flare_kernel.router.canonical.track_actions import build_track_next_actions
 from flare_kernel.router.intake.status.projection import (
@@ -40,8 +41,11 @@ def _resolve_analysis_title(*, command: str, can_generate: bool, orchestration_s
         return ""
     analysis_route = orchestration_status.get("analysis_route")
     if isinstance(analysis_route, dict):
+        route_title = str(analysis_route.get("title") or analysis_route.get("display_title") or "").strip()
+        if route_title:
+            return route_title
         if str(analysis_route.get("analysis_type") or "").strip().lower() == "sourcing":
-            return "寻源分析"
+            return "候选分析"
     return "需求分析"
 
 
@@ -115,8 +119,15 @@ def build_canonical_payload(
     module_prompt_registry = coerce_action_list(authoritative_runtime_payload.get("module_prompt_registry"))
     current_question = authoritative_current_question
     next_actions = authoritative_next_actions
-    projected_activated_mode = "auto" if intake_session_completed else activated_mode
-    projected_suggested_mode = None if intake_session_completed else canonical_context.get("suggested_mode")
+    mode_projection = resolve_round_end_mode_projection(
+        activated_mode=activated_mode,
+        suggested_mode=canonical_context.get("suggested_mode"),
+        mode_source=mode_source,
+        command=command,
+        intake_session_completed=intake_session_completed,
+    )
+    projected_activated_mode = mode_projection["activated_mode"]
+    projected_suggested_mode = mode_projection["suggested_mode"]
     composer_ui = build_composer_ui_projection(
         activated_mode=projected_activated_mode,
         mode_source=mode_source,
@@ -211,7 +222,7 @@ def build_canonical_payload(
             "mode": {
                 "suggested": projected_suggested_mode,
                 "activated": projected_activated_mode,
-                "is_activation_explicit": explicit_activation and projected_activated_mode != "auto",
+                "is_activation_explicit": explicit_activation,
                 "activation_source": mode_source if explicit_activation else "none",
             },
             "stage": stage_key,

flare_kernel-0.2.12/src/flare_kernel/router/completion/capability_boundary.py

@@ -0,0 +1,165 @@
+"""Capability-boundary completion helpers.
+
+This module projects backend-owned module prompt registry entries into
+customer-visible capability boundary text. It does not decide workflow state or
+embed domain-specific capabilities; supported interactions come from payload
+contracts such as ``module_prompt_registry``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from flare_kernel.runtime.llm.llm_provider import LLMCompletion
+
+_CAPABILITY_INQUIRY_TERMS = (
+    "支持哪些交互",
+    "支持什么交互",
+    "有哪些交互",
+    "能怎么交互",
+    "可以怎么交互",
+    "支持哪些功能",
+    "有什么功能",
+    "你能做什么",
+    "你会做什么",
+)
+
+_INTERACTION_REQUEST_TERMS = ("功能", "交互", "模式", "工具", "按钮", "插件", "入口")
+_INTERACTION_ACTION_TERMS = ("开启", "打开", "进入", "启动", "使用", "调用", "执行")
+_SUPPORTED_TRIGGER_LIMIT = 16
+_SUPPORTED_INTERACTION_LIMIT = 6
+
+
+def _clean_text(value: Any) -> str:
+    return " ".join(str(value or "").split()).strip()
+
+
+def _as_list(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _contains_any(text: str, terms: tuple[str, ...] | list[str]) -> bool:
+    return any(term for term in terms if term and term in text)
+
+
+def _module_entries(payload: dict[str, Any]) -> list[dict[str, Any]]:
+    entries = payload.get("module_prompt_registry")
+    return [item for item in entries if isinstance(item, dict)] if isinstance(entries, list) else []
+
+
+def _interaction_label(entry: dict[str, Any]) -> str:
+    return _clean_text(entry.get("action_text") or entry.get("label") or entry.get("module_key"))
+
+
+def build_supported_interactions(payload: dict[str, Any]) -> list[dict[str, str]]:
+    """Return customer-visible supported interactions from backend registry."""
+
+    interactions: list[dict[str, str]] = []
+    seen: set[str] = set()
+    for entry in _module_entries(payload):
+        label = _interaction_label(entry)
+        if not label or label in seen:
+            continue
+        seen.add(label)
+        interactions.append(
+            {
+                "label": label,
+                "reason": _clean_text(entry.get("reason")),
+                "module_key": _clean_text(entry.get("module_key") or entry.get("key")),
+            }
+        )
+        if len(interactions) >= _SUPPORTED_INTERACTION_LIMIT:
+            break
+    return interactions
+
+
+def _supported_trigger_terms(payload: dict[str, Any]) -> list[str]:
+    terms: list[str] = []
+    for entry in _module_entries(payload):
+        for value in (
+            _interaction_label(entry),
+            _clean_text(entry.get("label")),
+            _clean_text(entry.get("module_key") or entry.get("key")),
+        ):
+            if value and value not in terms:
+                terms.append(value)
+        for keyword in _as_list(entry.get("trigger_keywords")):
+            text = _clean_text(keyword)
+            if text and text not in terms:
+                terms.append(text)
+        if len(terms) >= _SUPPORTED_TRIGGER_LIMIT:
+            break
+    return terms[:_SUPPORTED_TRIGGER_LIMIT]
+
+
+def _is_capability_inquiry(message: str) -> bool:
+    text = _clean_text(message)
+    return _contains_any(text, _CAPABILITY_INQUIRY_TERMS)
+
+
+def _is_unknown_interaction_request(message: str, payload: dict[str, Any]) -> bool:
+    text = _clean_text(message)
+    if not text or _is_capability_inquiry(text):
+        return False
+    if _contains_any(text, _supported_trigger_terms(payload)):
+        return False
+    has_interaction_noun = _contains_any(text, _INTERACTION_REQUEST_TERMS)
+    has_action_verb = _contains_any(text, _INTERACTION_ACTION_TERMS)
+    return bool(has_interaction_noun and has_action_verb)
+
+
+def _format_supported_interactions(interactions: list[dict[str, str]]) -> str:
+    if not interactions:
+        return "目前可支持已配置的交互方式；当前配置暂未返回可展示的能力清单。"
+    lines = ["目前支持的交互方式："]
+    for item in interactions:
+        reason = item.get("reason") or "可基于当前任务上下文继续推进。"
+        lines.append(f"- {item['label']}：{reason}")
+    return "\n".join(lines)
+
+
+def build_capability_overview_message(payload: dict[str, Any]) -> str:
+    return _format_supported_interactions(build_supported_interactions(payload))
+
+
+def build_unknown_interaction_message(payload: dict[str, Any]) -> str:
+    supported = _format_supported_interactions(build_supported_interactions(payload))
+    return (
+        "这个交互方式目前还没有开发到，暂时不能直接完成。\n"
+        f"{supported}\n"
+        "您可以换成上面任一交互方式继续，我会按当前任务上下文接着处理。"
+    )
+
+
+def resolve_capability_boundary_completion(
+    *,
+    message: str,
+    payload: dict[str, Any],
+) -> LLMCompletion | None:
+    """Return a deterministic boundary response when the turn is about app capabilities."""
+
+    if _is_capability_inquiry(message):
+        return LLMCompletion(
+            provider="kernel_guardrail",
+            model="capability_boundary",
+            content=build_capability_overview_message(payload),
+            status="guardrail",
+            details={"reason": "supported_interactions_inquiry"},
+        )
+    if _is_unknown_interaction_request(message, payload):
+        return LLMCompletion(
+            provider="kernel_guardrail",
+            model="capability_boundary",
+            content=build_unknown_interaction_message(payload),
+            status="guardrail",
+            details={"reason": "unknown_interaction_request"},
+        )
+    return None
+
+
+__all__ = [
+    "build_capability_overview_message",
+    "build_supported_interactions",
+    "build_unknown_interaction_message",
+    "resolve_capability_boundary_completion",
+]

{flare_kernel-0.2.11 → flare_kernel-0.2.12}/src/flare_kernel/router/completion/guided.py

@@ -6,17 +6,25 @@ from dataclasses import dataclass
 from typing import Any
 
 from flare_kernel.contracts import KernelRequest
+from flare_kernel.router.completion.intake_summary_submission import (
+    is_requirement_summary_submission,
+)
+from flare_kernel.router.turn_act import classify_turn_act
 from flare_kernel.runtime.llm.llm_provider import LLMCompletion
 
 _REQUIREMENT_INTAKE_COMMAND_SCORES = {
-    "": {"main_chain": 1.0, "patch_only": 0.0},
-    "send_message": {"main_chain": 1.0, "patch_only": 0.0},
-    "submit_intake_answer": {"main_chain": 0.0, "patch_only": 1.0},
-    "activate_requirement_intake": {"main_chain": 0.0, "patch_only": 1.0},
+    "": {"main_chain": 0.0, "patch_only": 1.0, "phase_floor": 0.0},
+    "send_message": {"main_chain": 0.0, "patch_only": 1.0, "phase_floor": 0.0},
+    "submit_intake_answer": {"main_chain": 0.0, "patch_only": 1.0, "phase_floor": 0.0},
+    "continue_collection": {"main_chain": 0.0, "patch_only": 1.0, "phase_floor": 0.0},
+    "activate_requirement_intake": {"main_chain": 0.0, "patch_only": 1.0, "phase_floor": 1.0},
+    "apply": {"main_chain": 0.0, "patch_only": 1.0, "phase_floor": 1.0},
+    "implement": {"main_chain": 0.0, "patch_only": 1.0, "phase_floor": 1.0},
 }
-_DEFAULT_REQUIREMENT_INTAKE_COMMAND_SCORE = {"main_chain": 1.0, "patch_only": 0.0}
+_DEFAULT_REQUIREMENT_INTAKE_COMMAND_SCORE = {"main_chain": 1.0, "patch_only": 0.0, "phase_floor": 0.0}
 _PATCH_ONLY_COMPLETION_MODES = frozenset({"patch_only", "state_patch_only"})
 _MAIN_CHAIN_COMPLETION_MODES = frozenset({"main_chain", "llm", "generate"})
+_MAIN_CHAIN_TURN_KINDS = frozenset({"clarification_question", "patch_request", "mixed"})
 
 
 @dataclass(frozen=True)
@@ -140,11 +148,39 @@ def _resolve_requirement_intake_guided_decision(
     payload_decision = _payload_patch_decision(payload)
     if payload_decision is not None:
         return payload_decision
+    if is_requirement_summary_submission(payload):
+        return _GuidedCompletionDecision(
+            action="main_chain",
+            main_chain_score=1.0,
+            patch_only_score=0.0,
+            phase_score=1.0,
+            policy_reason="requirement_summary_submission",
+        )
+    if command in {"", "send_message"} and _is_collecting_question_phase(orchestration_status):
+        turn_act = classify_turn_act(
+            message=str(payload.get("message") or ""),
+            current_question=orchestration_status.get("current_question")
+            if isinstance(orchestration_status.get("current_question"), dict)
+            else None,
+            field_definitions=payload.get("field_definitions"),
+        )
+        turn_kind = str(turn_act.get("turn_kind") or "").strip()
+        if turn_kind in _MAIN_CHAIN_TURN_KINDS:
+            return _GuidedCompletionDecision(
+                action="main_chain",
+                main_chain_score=1.0,
+                patch_only_score=0.0,
+                phase_score=1.0,
+                policy_reason=f"orc15_{turn_kind}",
+            )
     command_scores = _REQUIREMENT_INTAKE_COMMAND_SCORES.get(
         command,
         _DEFAULT_REQUIREMENT_INTAKE_COMMAND_SCORE,
     )
-    phase_score = float(_is_collecting_question_phase(orchestration_status))
+    phase_score = max(
+        float(_is_collecting_question_phase(orchestration_status)),
+        float(command_scores.get("phase_floor") or 0.0),
+    )
     patch_only_score = phase_score * float(command_scores["patch_only"])
     main_chain_score = float(command_scores["main_chain"])
     action = "patch_only" if patch_only_score > main_chain_score else "main_chain"

flare_kernel-0.2.12/src/flare_kernel/router/completion/intake_commit_contract.py

@@ -0,0 +1,46 @@
+"""Requirement-intake commit projection for non-stream run results.
+
+DOC HELPER — run result intake context writeback boundary.
+This helper exposes the same context patch carried by stream completion events.
+It only frames an already-canonical context patch on the response result.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from flare_kernel.runtime.context.intake_application import build_context_patch_from_intake_commit
+
+
+def _merge_context_patches(existing: Any, incoming: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(existing) if isinstance(existing, dict) else {}
+    for key, value in incoming.items():
+        if isinstance(value, list):
+            current = merged.get(key) if isinstance(merged.get(key), list) else []
+            merged[key] = [*current, *value]
+        elif isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = {**merged[key], **value}
+        else:
+            merged[key] = value
+    return merged
+
+
+def attach_intake_commit_context_contract(
+    *,
+    result: dict[str, Any],
+    runtime_snapshot: dict[str, Any],
+    orchestration_status: dict[str, Any],
+    command: str,
+) -> dict[str, Any]:
+    context_patch = build_context_patch_from_intake_commit(
+        runtime_snapshot=runtime_snapshot,
+        orchestration_status=orchestration_status,
+        command=command,
+    )
+    if not context_patch:
+        return result
+    result["context_patch"] = _merge_context_patches(result.get("context_patch"), context_patch)
+    return result
+
+
+__all__ = ["attach_intake_commit_context_contract"]

flare_kernel-0.2.12/src/flare_kernel/router/completion/intake_summary_content.py

@@ -0,0 +1,147 @@
+"""Resolve requirement-intake Canvas summary content.
+
+The Canvas prompt review surface must not reuse the main assistant reply as the
+reviewable prompt. This module resolves backend-owned scope content from
+canonical intake/runtime state only.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _clean_text(value: Any) -> str:
+    return str(value or "").strip()
+
+
+def _coerce_mapping(value: Any) -> dict[str, Any]:
+    return value if isinstance(value, dict) else {}
+
+
+def _mode_event_payloads(runtime_snapshot: dict[str, Any]) -> list[dict[str, Any]]:
+    mode_events = runtime_snapshot.get("mode_events")
+    if not isinstance(mode_events, list):
+        return []
+    payloads: list[dict[str, Any]] = []
+    for event in mode_events:
+        if not isinstance(event, dict):
+            continue
+        payload = event.get("payload")
+        if isinstance(payload, dict):
+            payloads.append(payload)
+    return payloads
+
+
+def _explicit_summary_content(runtime_snapshot: dict[str, Any]) -> str:
+    payload = _coerce_mapping(runtime_snapshot.get("payload"))
+    content = _clean_text(payload.get("requirement_summary_content"))
+    if content:
+        return content
+    summary = _coerce_mapping(payload.get("requirement_summary"))
+    content = _clean_text(summary.get("content"))
+    if content:
+        return content
+    content = _clean_text(payload.get("canvas_content"))
+    if content:
+        return content
+    for event_payload in reversed(_mode_event_payloads(runtime_snapshot)):
+        summary = _coerce_mapping(event_payload.get("requirement_summary"))
+        content = _clean_text(summary.get("content"))
+        if content:
+            return content
+        canvas_state = _coerce_mapping(event_payload.get("canvas_state"))
+        summary = _coerce_mapping(canvas_state.get("requirement_summary"))
+        content = _clean_text(summary.get("content"))
+        if content:
+            return content
+        content = _clean_text(event_payload.get("canvas_content"))
+        if content:
+            return content
+    return ""
+
+
+def _understanding_scope_content(runtime_snapshot: dict[str, Any]) -> str:
+    for event_payload in reversed(_mode_event_payloads(runtime_snapshot)):
+        understanding = _coerce_mapping(event_payload.get("intake_understanding"))
+        context = _coerce_mapping(understanding.get("understood_context"))
+        for value in (
+            context.get("context_phrase"),
+            understanding.get("raw_user_goal"),
+            event_payload.get("message_excerpt"),
+        ):
+            content = _clean_text(value)
+            if content:
+                return content
+    return ""
+
+
+def _payload_message_scope_content(runtime_snapshot: dict[str, Any]) -> str:
+    payload = _coerce_mapping(runtime_snapshot.get("payload"))
+    return _clean_text(payload.get("message"))
+
+
+def _row_text(row: dict[str, Any]) -> str:
+    label = _clean_text(row.get("label") or row.get("field_key") or row.get("key"))
+    value = _clean_text(row.get("value") or row.get("field_value") or row.get("display_value"))
+    if not label:
+        return value
+    if not value:
+        return label
+    return f"{label}：{value}"
+
+
+def _field_scope_content(runtime_snapshot: dict[str, Any]) -> str:
+    for event_payload in reversed(_mode_event_payloads(runtime_snapshot)):
+        canvas_state = _coerce_mapping(event_payload.get("canvas_state"))
+        collected = canvas_state.get("collected")
+        if not isinstance(collected, list):
+            continue
+        lines: list[str] = []
+        for row in collected:
+            if not isinstance(row, dict):
+                continue
+            text = _row_text(row)
+            if text:
+                lines.append(text)
+        if lines:
+            return "\n".join(lines)
+    return ""
+
+
+def resolve_requirement_summary_content(
+    *,
+    runtime_snapshot: dict[str, Any],
+) -> str:
+    """Resolve canonical prompt/scope content for requirement-intake fallback."""
+
+    if _clean_text(runtime_snapshot.get("mode_key")) != "requirement_intake":
+        return ""
+    return (
+        _explicit_summary_content(runtime_snapshot)
+        or _understanding_scope_content(runtime_snapshot)
+        or _field_scope_content(runtime_snapshot)
+        or _payload_message_scope_content(runtime_snapshot)
+    )
+
+
+def resolve_reviewable_requirement_summary_content(
+    *,
+    runtime_snapshot: dict[str, Any],
+    content_text: str,
+) -> str:
+    """Resolve the user-reviewable requirement summary text.
+
+    The model-authored main-chain summary is the preferred review surface when
+    present. Canonical scope remains the fallback for patch-only or empty model
+    turns, so field state can still be rendered without inventing content.
+    """
+
+    return _clean_text(content_text) or resolve_requirement_summary_content(
+        runtime_snapshot=runtime_snapshot,
+    )
+
+
+__all__ = [
+    "resolve_requirement_summary_content",
+    "resolve_reviewable_requirement_summary_content",
+]