"""多章工作流链状态 `ChainState`（chain-workflow 设计 §3.1）。

不变量 #5：langgraph 检查点 = state 内容，**只放控制流**——章号/计数/已验收清单/
冲突标志。草稿正文/上下文/冲突明文**不进** state（落 `chapters`/`chapter_reviews`，
resume 时从领域表重读为真相）。

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

from __future__ import annotations

import uuid
from typing import TypedDict


class ChainState(TypedDict, total=False):
    """`draft_volume` 链的控制流状态（检查点内容）。

    - `project_id` / `user_id`：定位 + 调用作用域（原型单用户 stub）。
    - `chain_key`：固定 `"draft_volume"`（本期唯一内置链）。
    - `start_chapter_no` / `last_chapter_no`：本 run 区间 [start, last]（含）。
    - `current_chapter_no`：当前处理章；初值 = start，每验收一章 +1。
    - `written`：本 run 已验收章号（进度来源；resume 后累积）。
    - `has_conflicts`：`decide` 节点写入的控制流标志（不存冲突明文，不变量 #5）。

    `total=False`：初始 invoke 只需填区间字段，`written`/`has_conflicts` 由节点逐步填。
    """

    project_id: uuid.UUID
    user_id: uuid.UUID
    chain_key: str
    start_chapter_no: int
    last_chapter_no: int
    current_chapter_no: int
    written: list[int]
    has_conflicts: bool
