"""章节摘要**写**侧 Repository（append-only；ARCH §3.3 / §5.5 / §6.1）。

`chapter_digests` 是 append-only：每次验收从**终稿**提炼一行事实，**永不覆盖**历史
（不变量 #4：digest 从终稿提炼）。读侧（`recent`，供 assemble 注入）已在
`ww_core.memory.sql_repositories.SqlDigestRepo` / `domain.repositories.DigestRepo` 提供；
本模块只加**写**能力，不动读侧。

命名：写侧 Protocol 命名 `DigestAppendRepo`（区别于 `repositories.DigestRepo` 读侧），
共用 `DigestView`，避免同名歧义（见 memory/decisions）。
"""

from __future__ import annotations

import uuid
from typing import Any, Protocol

from sqlalchemy.ext.asyncio import AsyncSession
from ww_db.models import ChapterDigest

from ww_core.domain.repositories import DigestView


class DigestAppendRepo(Protocol):
    """摘要追加接口（append-only，按 project_id 隔离）。"""

    async def append(
        self, project_id: uuid.UUID, chapter_no: int, *, facts: dict[str, Any]
    ) -> DigestView:
        """追加一行 digest（永不覆盖既有行）；返回不可变 frozen View。"""
        ...


class SqlDigestAppendRepo:
    """SQLAlchemy 实现：始终 INSERT 新行（append-only）。

    **只 flush 不 commit**：验收事务（T2.4）把晋升+digest+裁决留痕作为单事务提交。
    """

    def __init__(self, session: AsyncSession) -> None:
        self._s = session

    async def append(
        self, project_id: uuid.UUID, chapter_no: int, *, facts: dict[str, Any]
    ) -> DigestView:
        row = ChapterDigest(
            project_id=project_id,
            chapter_no=chapter_no,
            facts=dict(facts),
        )
        self._s.add(row)
        await self._s.flush()
        await self._s.refresh(row)
        return DigestView(chapter_no=row.chapter_no, facts=dict(row.facts))
