"""编排器图状态（C4 / ARCH §5.2）——只存**控制流 + 组装上下文 + 累积草稿**。

不变量 #5：checkpoint 只承载控制流位置 + 组装上下文 + 已生成草稿增量 + 过程态审稿产物，
正文/审稿以领域表为权威；resume 时从 `chapters`/`chapter_reviews` 重读（M2）。
M2 加并行审 + collect；验收/interrupt 的真相源重建归 T2.4（accept 不在本图）。

`ChapterState` 用 TypedDict（LangGraph 原生状态形态），字段全 snake_case。
"""

from __future__ import annotations

import uuid
from typing import Annotated, Any, TypedDict


def merge_reviews(left: dict[str, Any], right: dict[str, Any]) -> dict[str, Any]:
    """并行审分支的 `reviews` 归并 reducer（不可变：返回新 dict）。

    四审为并行分支，同一 superstep 各写 `{spec.name: ...}`；无 reducer 时 LangGraph
    会因并发写同一键抛 `InvalidUpdateError`。本 reducer 把各分项浅合并入一个 dict。
    """
    return {**left, **right}


class ChapterState(TypedDict, total=False):
    """写章 + 审稿图的控制流状态。

    - `project_id` / `chapter_no`：定位本章（resume 时据此重读领域表）。
    - `user_id`：调用作用域（落账 owner_id；原型单用户 stub）。
    - `stable_core` / `volatile`：来自 `memory.assemble` 的中性文本
      （stable_core=缓存断点前；volatile=断点后）。write 节点据此构造 `LlmRequest`。
    - `draft`：write 节点累积的草稿正文（流式增量拼接的最终结果）。
    - `review_context`（M2）：审稿注入文本——草稿 + 近况摘要/人物卡/世界观硬规则的
      确定性拼装（复用 assemble 的 stable/volatile，无时间戳）。
    - `reviews`（M2）：collect 汇总的各审分项结果（**过程态**）。落 `chapter_reviews`
      表后真相在表；不变量 #5：checkpoint 不作审稿真相源，resume 从领域表重读。

    M2 起字段按节点逐步填充，故 `total=False`（write 阶段无 review 字段亦合法）。
    """

    project_id: uuid.UUID
    chapter_no: int
    user_id: uuid.UUID
    stable_core: str
    volatile: str
    draft: str
    review_context: str
    reviews: Annotated[dict[str, Any], merge_reviews]
