"""本章注入透明（B0）的响应 schema（C 扩 / ARCH §3.4、§5.3）。

snake_case；前端经 OpenAPI 生成 TS 类型消费。改字段 → 前端必须 `pnpm gen:api`。
读取无 LLM、无 commit——仅回放 assemble() 的确定性 SelectionTrace（不变量 #6）。
"""

from __future__ import annotations

import uuid

from pydantic import BaseModel, Field


class InjectionEntity(BaseModel):
    """一个被注入本章上下文的实体 + 入选理由（喂给透明面板的徽标）。"""

    kind: str = Field(description="character / world_entity")
    name: str
    reasons: list[str] = Field(
        default_factory=list,
        description="explicit_beat / main_character / recent_digest / foreshadow_window",
    )


class InjectionResponse(BaseModel):
    """GET /projects/:id/chapters/:no/injection：本章确定性注入留痕。"""

    project_id: uuid.UUID
    chapter_no: int
    selected: list[InjectionEntity] = Field(default_factory=list)
    recent_n: int = Field(description="近况摘要回看章数（确定性选择的默认参数）")