feat: M3 — 伏笔账本 + 节奏引擎 + 大纲（含并发记账 bugfix）

- 伏笔账本：纯函数状态机(OPEN/PARTIAL/CLOSED/OVERDUE) + ForeshadowLedger repo；验收后到期扫描(BackgroundTask 自建 session 置 OVERDUE)；登记/状态变更端点
- 节奏 + 三审齐：foreshadow-analyst + pace-checker 并入 LangGraph 并行审(REVIEW_SPECS)，collect 分列落 chapter_reviews(conflicts/foreshadow_sug/pace)，review SSE 加 foreshadow/pace 事件
- 大纲：outliner Agent 产 OutlineResult(含 foreshadow_windows)，POST /outline 逐章 upsert outline 表；GET /foreshadow?status= 看板
- 前端：伏笔四泳道看板(OVERDUE 琥珀) + 大纲编辑器(窗口徽标) + 节奏节拍图(▁▃▅) + 审稿页消费 foreshadow/pace SSE
- bugfix(T3.8)：并行三审共用请求 session 记账触发 'Session is already flushing' → foreshadow/pace 静默丢失；SqlAlchemyLedgerSink.record 改 add-only(靠端点/事务 commit)，加并发回归测试
- M3 E2E：真实 DB + mock 网关零 token 走通 埋设→进展→验收后扫描 OVERDUE→看板 + 大纲含窗口 + 三审齐 SSE/留痕；E2E 暴露并钉住上述 bug
- 门禁绿：mypy 111 / pytest 228(0 xfailed) / alembic 无漂移；前端 gen:api/lint/tsc/vitest 69/build

apps/api/ww_api/services/accept_service.py

@@ -114,9 +114,11 @@ async def run_accept_transaction(
         )
         review_id = updated.id
 
-    # 步骤 3（占位）：人物 latest_state / 伏笔状态更新——M3 才正式接伏笔表，
-    # 这里按 §5.5 步骤 3 留占位，不引入 M3 表逻辑（避免越界写未就绪的状态机）。
-    # TODO(M3): 按裁决应用 latest_state 变更 + 伏笔登记/到期扫描（§6.2）。
+    # 步骤 3：伏笔到期扫描——验收提交**后**经端点登记的 BackgroundTask 跑（M3-b/d，
+    # `services/foreshadow_scan.run_overdue_scan`：current_ch > expected_close_to 且未 CLOSED
+    # → 置 OVERDUE，确定性纯函数非 AI，不变量 #3）。放在事务外/提交后是因为它是验收**结果**
+    # 的副作用、且自建独立 session（请求 session 此时已关闭）。
+    # 人物 latest_state 更新仍留后续（M4+）：本事务只落晋升 + digest + 裁决留痕。
 
     await session.commit()  # type: ignore[attr-defined]  # AsyncSession.commit()（fake 同形）
 

apps/api/ww_api/services/foreshadow_scan.py

@@ -0,0 +1,90 @@
+"""验收后伏笔到期扫描（M3-b/d；ARCH §6.2, §7.4，不变量 #3）。
+
+接 §5.5 验收事务后的 `TODO(M3)` 占位：验收**提交成功后**触发一次伏笔到期扫描，把
+`current_ch > expected_close_to AND status≠CLOSED` 的伏笔确定性置 `OVERDUE`（M3-d 纯
+函数，非 Agent；不变量 #3：状态变更是确定性扫描而非 AI 静默写库）。
+
+挂载方式（端点）：FastAPI `BackgroundTasks` 在 accept 端点登记 `run_overdue_scan`。
+BackgroundTask 在请求-response 发回、请求 session 关闭**之后**才跑——故本函数**自建新
+session**（不复用请求 session）并自己 `commit()`。
+
+**持久性局限（§7.4）**：BackgroundTasks 在 API 进程内跑，进程重启/崩溃会丢失未跑完的
+任务——原型可接受，这里把触发/完成/失败都记结构化日志便于查错；**不引入 `jobs` 表**
+（那是 M4/T4.1 的工作，本任务不越界）。
+
+可测性：扫描逻辑抽成纯 async 函数 `run_overdue_scan(session_factory, ...)`，端点用
+BackgroundTasks 调它；单测直接 `await` 它（注入 fake session 工厂）断言行被置 OVERDUE，
+**绝不真起不可控后台线程**。
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol
+
+import structlog
+from sqlalchemy.ext.asyncio import AsyncSession
+from ww_core.domain import ForeshadowLedgerView, SqlForeshadowLedgerRepo
+
+log = structlog.get_logger(__name__)
+
+# 新建独立 session 的工厂：调用得到一个 async 上下文管理器（`async with` → AsyncSession）。
+SessionFactory = Callable[[], AbstractAsyncContextManager[AsyncSession]]
+
+
+class OverdueScanRepo(Protocol):
+    """到期扫描对账本 repo 的最小依赖（仅 `scan_overdue`）。"""
+
+    async def scan_overdue(
+        self, project_id: uuid.UUID, *, current_chapter: int
+    ) -> list[ForeshadowLedgerView]: ...
+
+
+# repo 工厂：从新 session 造账本 repo。默认建 SQL 实现；测试注入 fake（避免真连 DB）。
+RepoFactory = Callable[[AsyncSession], OverdueScanRepo]
+
+
+def _default_repo_factory(session: AsyncSession) -> OverdueScanRepo:
+    return SqlForeshadowLedgerRepo(session)
+
+
+async def run_overdue_scan(
+    session_factory: SessionFactory,
+    *,
+    project_id: uuid.UUID,
+    chapter_no: int,
+    request_id: str | None = None,
+    repo_factory: RepoFactory = _default_repo_factory,
+) -> int:
+    """验收后伏笔到期扫描：新建 session → `scan_overdue` 置 OVERDUE → `commit()`。
+
+    返回被置 OVERDUE 的伏笔条数（供日志/测试断言）。任何异常被捕获并记错误日志后
+    吞掉——后台任务失败不应冒泡崩进程，也不影响已成功的验收事务（§7.4 局限可接受）。
+    `repo_factory` 是可注入缝：默认建 SQL 账本 repo，测试注 fake（直接 await、不联网）。
+    """
+    try:
+        async with session_factory() as session:
+            repo = repo_factory(session)
+            changed = await repo.scan_overdue(project_id, current_chapter=chapter_no)
+            if changed:
+                await session.commit()
+            log.info(
+                "foreshadow_overdue_scan",
+                project_id=str(project_id),
+                chapter_no=chapter_no,
+                request_id=request_id,
+                overdue_count=len(changed),
+                overdue_codes=[v.code for v in changed],
+            )
+            return len(changed)
+    except Exception as exc:  # noqa: BLE001 — 后台任务边界：记错误、不冒泡崩进程（§7.4）。
+        log.error(
+            "foreshadow_overdue_scan_failed",
+            project_id=str(project_id),
+            chapter_no=chapter_no,
+            request_id=request_id,
+            error=str(exc),
+        )
+        return 0

apps/api/ww_api/services/outline_context.py

@@ -0,0 +1,87 @@
+"""大纲生成的注入上下文组装（确定性序列化文本；ARCH §5.4 outliner reads / §6.2）。
+
+把 projects 设定 + 已登记伏笔 + 人物 + 世界观确定性序列化成纯文本喂给 outliner——
+**无时间戳/无 UUID**（缓存前缀稳定，不变量 #9），逐项排序保证同输入同输出（可单测）。
+outliner 据此排出分章节拍 + 伏笔回收窗口（关联本章与伏笔，§6.2）。
+
+注：reads=["projects","foreshadow","characters","world_entities"]（C6 outliner_spec），
+本组装恰好覆盖这四源，不读 digest/outline（排大纲是从设定生成、非续写既有章）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ww_core.domain import ForeshadowLedgerView, ProjectView
+from ww_core.domain.repositories import CharacterView, WorldEntityView
+
+
+def _project_block(project: ProjectView) -> str:
+    lines = [f"标题：{project.title}"]
+    if project.genre:
+        lines.append(f"类型：{project.genre}")
+    if project.logline:
+        lines.append(f"一句话简介：{project.logline}")
+    if project.premise:
+        lines.append(f"前提：{project.premise}")
+    if project.theme:
+        lines.append(f"主题：{project.theme}")
+    if project.selling_points:
+        lines.append("卖点：" + "、".join(project.selling_points))
+    if project.structure:
+        lines.append(f"结构：{project.structure}")
+    return "【作品设定】\n" + "\n".join(lines)
+
+
+def _foreshadow_block(foreshadow: Sequence[ForeshadowLedgerView]) -> str:
+    if not foreshadow:
+        return "【已登记伏笔】\n（无）"
+    rows = sorted(foreshadow, key=lambda f: f.code)
+    lines = []
+    for f in rows:
+        window = ""
+        if f.expected_close_from is not None or f.expected_close_to is not None:
+            lo = f.expected_close_from if f.expected_close_from is not None else "?"
+            hi = f.expected_close_to if f.expected_close_to is not None else "?"
+            window = f"（回收窗口 {lo}-{hi}）"
+        plant = f"埋设第{f.planted_at}章 " if f.planted_at is not None else ""
+        lines.append(f"- [{f.code}] {f.title} {plant}{window}".rstrip())
+    return "【已登记伏笔】\n" + "\n".join(lines)
+
+
+def _characters_block(characters: Sequence[CharacterView]) -> str:
+    if not characters:
+        return "【人物】\n（无）"
+    rows = sorted(characters, key=lambda c: c.name)
+    lines = []
+    for c in rows:
+        role = f"（{c.role}）" if c.role else ""
+        motive = f" 动机：{c.motive}" if c.motive else ""
+        lines.append(f"- {c.name}{role}{motive}".rstrip())
+    return "【人物】\n" + "\n".join(lines)
+
+
+def _world_block(entities: Sequence[WorldEntityView]) -> str:
+    if not entities:
+        return "【世界观】\n（无）"
+    rows = sorted(entities, key=lambda e: (e.type, e.name))
+    lines = [f"- [{e.type}] {e.name}" for e in rows]
+    return "【世界观】\n" + "\n".join(lines)
+
+
+def build_outline_context(
+    *,
+    project: ProjectView,
+    foreshadow: Sequence[ForeshadowLedgerView],
+    characters: Sequence[CharacterView],
+    world_entities: Sequence[WorldEntityView],
+) -> str:
+    """组装 outliner 注入上下文（确定性文本，纯函数）。"""
+    return "\n\n".join(
+        [
+            _project_block(project),
+            _foreshadow_block(foreshadow),
+            _characters_block(characters),
+            _world_block(world_entities),
+        ]
+    )

apps/api/ww_api/services/project_deps.py

@@ -16,13 +16,15 @@ from openai import AsyncOpenAI
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from ww_config import get_settings
+from ww_core.domain import ForeshadowLedgerRepo, SqlForeshadowLedgerRepo
 from ww_core.domain.chapter_repo import ChapterRepo, SqlChapterRepo
 from ww_core.domain.digest_repo import DigestAppendRepo, SqlDigestAppendRepo
+from ww_core.domain.outline_write_repo import OutlineWriteRepo, SqlOutlineWriteRepo
 from ww_core.domain.project_repo import ProjectRepo, SqlProjectRepo
 from ww_core.domain.repositories import MemoryRepos
 from ww_core.domain.review_repo import ReviewRepo, SqlReviewRepo
 from ww_core.memory.sql_repositories import sql_memory_repos
-from ww_db import get_session
+from ww_db import get_session, get_sessionmaker
 from ww_db.models import User
 from ww_llm_gateway import (
     Gateway,
@@ -42,6 +44,7 @@ from ww_api.services.credentials import (
     CredentialStore,
     SqlCredentialStore,
 )
+from ww_api.services.foreshadow_scan import SessionFactory
 from ww_api.services.provider_deps import _PROVIDER_BASE_URLS
 
 # 单用户 stub 的占位邮箱（多租户化时由真实主体替换）。
@@ -95,6 +98,30 @@ def get_digest_append_repo(
     return SqlDigestAppendRepo(session)
 
 
+def get_foreshadow_repo(
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> ForeshadowLedgerRepo:
+    """伏笔账本写侧 repo（登记/状态变更端点；只 flush，端点提交）。测试经 override 注 fake。"""
+    return SqlForeshadowLedgerRepo(session)
+
+
+def get_outline_write_repo(
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> OutlineWriteRepo:
+    """大纲写侧 repo（大纲生成端点逐章 upsert；只 flush，端点提交）。测试经 override 注 fake。"""
+    return SqlOutlineWriteRepo(session)
+
+
+def get_session_factory() -> SessionFactory:
+    """验收后到期扫描的**独立 session 工厂**缝。
+
+    BackgroundTask 在请求 session 关闭后才跑，必须自建 session（不复用 `get_session`）。
+    返回的工厂 `()` → `async with` 得一个新 `AsyncSession`。测试经 `app.dependency_overrides`
+    注入 fake 工厂（避免真起后台线程/真连 DB）。
+    """
+    return get_sessionmaker()
+
+
 async def build_gateway_for_tier(
     session: AsyncSession, store: CredentialStore, tier: Tier
 ) -> Gateway:
@@ -160,3 +187,11 @@ async def get_digest_gateway(
     """验收终稿 digest 提炼（light 档位）的可注入网关缝。测试经 override 注 mock。"""
     store = SqlCredentialStore(session)
     return await build_gateway_for_tier(session, store, "light")
+
+
+async def get_outline_gateway(
+    session: Annotated[AsyncSession, Depends(get_session)],
+) -> Gateway:
+    """大纲生成（analyst 档位）的可注入网关缝。测试经 override 注 mock（产 OutlineResult）。"""
+    store = SqlCredentialStore(session)
+    return await build_gateway_for_tier(session, store, "analyst")