Kastell — 双历史个人 Agent 应用

这份文件同时是「项目说明书」和「施工图」。建议分三种用法：

• 建立心智模型（一次通读）：读 §1–§6。读完你应该能用三句话解释这个项目：一个 store 同时保存观察日志和规范消息；pi 运行时可替换，数据库才是持久状态的权威；任何操作提交成功后才算成功，对不确定的执行结果不作推断。
• 逐章实现（边写边看）：按 §7 的 01 → 02a → … → 08a 顺序推进。每一章给出「产出物 / 核心概念 / 规则与取舍 / 完成判定 / 常见坑」。示例代码不抄进文档，需要时回原教程。
• 验收与防漂移：§8 是 M1 的验收清单；§9 是永远成立的硬规则；§10/§11 写清楚「不做什么」和「不承诺什么」——这两个清单同样重要，它们防止项目膨胀。

终点长什么样

Terminal A                                Terminal B
kastell-host                              kastell note / prompt / log --follow / timeline
     │                                          │
     ├────────── HTTP/JSON on loopback ─────────┘
     │                (127.0.0.1:8787)
     │
     ├── ONE SwiftData writer ──► persisted journal + canonical message timeline
     │        (@ModelActor, 一个 ModelContext, 一次 save)
     │
     └── AgentManager
           ├── PiRuntime(A) ── Commander ── pi --mode rpc --no-session
           └── PiRuntime(B) ── Commander ── pi --mode rpc --no-session

三句话理解整个设计

1. 一个 store，两个历史。同一个 SwiftData store 里既存 journal（host 收到并成功提交的限额内原始事件），也存 timeline（按固定策略保存的规范消息）。两者由同一个 writer、同一个 save 边界维护，不需要后台投影任务。
2. pi 运行时可替换，数据库是持久状态的权威。进程崩溃、host 重启都不丢已提交的历史。重启后历史可读，但新进程默认从空白上下文开始——这是明确的产品边界，不是缺陷。
3. 提交先于成功，证据优于猜测。收到成功回执 = 已提交入库，不等于模型执行成功；发出去没等到响应 = 不确定，绝不盲目重发；解释不了的数据保留原始记录并显式报错，不编造"看起来合理"的消息。

M1 的定义

走完 a-track 全部 8 章之后你得到的东西，就是 M1：

中途可用点：04a。 到这里 notes 能落 journal、两个历史都能读；timeline 为空是正确状态。05a/06a 才把真实 prompt 和 pi 消息接进来。

初始限额与配置（沿用教程，调整前先评估）

三层协议必须分开

Client ── HTTP requests/responses ──► Host
                                        │
                                        ├── application operations ──► HistoryStore
                                        │
                                        └── pi JSONL ──► Commander ──► child process

• 公开 API 说应用语言：create agent、start、submit prompt、append note、read log。绝不提供 POST /rpc 之类的"任意 JSON 转发给 pi"路由。
• pi 的私有协议可以随时变，不该让每个客户端都理解 process ID、扩展对话框、RPC 队列。
• Commander.writeLine 只证明传输层成功，不证明任何应用层操作成功。host 负责三层之间的翻译。

每个资源只有一个 owner

注意 Swift 的任务语义：Task { } 创建的是非结构化任务，必须明确由谁持有、取消并等待其清理完成；actor 不会自动监督自己创建的任务。资源归属最终要落实到“谁持有、谁取消、谁等待结束”。

模块边界由编译器强制

KastellCLI ────────────────────────────────► KastellProtocol
KastellHost ──► KastellRuntime ──► Commander
     │               │
     └───────────────► KastellStore ────────► KastellProtocol

• 没有任何 target 依赖 host 可执行文件；CLI 不能意外调用 store，因为没 import 那个模块。
• KastellProtocol 不 import Vapor / SwiftData / Commander——它是纯 DTO 层。
• 这是架构约束，不是命名约定。多模块的价值就在于此。

整套系统只信任两类东西：UUID 身份和数据库分配的整数顺序。时间戳只用于展示，不是排序依据。

身份表

两个计数器，两条流

journal 和 timeline 各自只有一个全局计数器，跨所有 agent；它们顺序不同、互不通用：

Journal:   J1 client.note
           J2 prompt.requested ─────────────► T1 user
           J3 pi.agent_start
           J4 pi.message_end(user) ────────► 链接到 T1，不新增
           J5 pi.message_update
           J6 pi.message_end(assistant) ───► T2 assistant
           J7 pi.agent_settled
           J8 prompt.settled

Timeline:  T1 user        (sourceJournalSequence = 2)
           T2 assistant   (sourceJournalSequence = 6)

• 每写一条 journal 行 → journalHead + 1；只有产生新的规范消息才 timelineHead + 1。
• sourceJournalSequence：从规范行指向"创建它的那条 journal 事件"。
• JournalEvent.canonicalMessageID：从 journal 行指向已有或新建的规范消息；多个观察可以链到同一条消息（如 user echo）。
• mutation receipt 里的 sequence 永远是 journal 位置，即使这次 admission 同时创建了 timeline 行。
• 计数器在同一次 save 里随行分配，并防 Int64.max 溢出。不许用 fetchCount + 1、不许用 Date、不许用进程内自增（重启会重复）。

客户端游标长这样

HistoryCursor {
  storeID: 1111...,
  stream:  "timeline",     ← 关键：journal 和 timeline 不能共用裸数字
  after:   12,
  agentID: 5555... ?       ← 可选的过滤条件也属于游标身份的一部分
}

它读作"在这个 store 里、对这个过滤条件、timeline 位置 12 之后"。log 与 timeline 用不同的 cursor 文件（如 /tmp/kastell-journal-cursor.json、/tmp/kastell-timeline-cursor.json）。服务端无法猜出一个裸数字来自哪个命令——journal 的 10 可能刚好落在 timeline 范围内，静默跳过消息。所以客户端本地校验 + 服务端范围/store 校验，缺一不可。

幂等靠 identity key，不靠文本

• 重放同一身份：先 fetch 比较（action、agent、原始输入），一致就返回原来的 eventID/sequence/canonical 链，什么都不新建；不一致就报错。
• 永远不用文本 hash 合并消息——两条合法消息完全可能内容相同。相同文本 + 新 operationID = 真正的新 prompt/note。
• 重复摄入不重新执行生命周期转换（比如不再次标记 accepted）。

这是 a-track 的核心决定：两个历史都真实持久化。journal 保留原始证据，timeline 保存每个逻辑消息的一份规范表示。两者职责不同，但由同一套代码维护映射，并在同一次 save 中提交。

投影策略（V1 全部规则）

user 消息的三条性质

• 规范 user 消息代表已提交的意图：即使 pi 后来拒绝、或 host 丢失，它也留在 timeline。
• 用户行存在 ≠ 执行成功。它的内容永远不变，也不会被改成 accepted/rejected/interrupted——那些状态属于 operation 资源和 journal。
• timeline 不是"可发给模型的上下文列表"。是否送历史、送多少，是将来显式渲染器的决定。

为什么用 message_end，而不是 get_entries？

• pi 文档把 message_end.message 定义为权威的完整消息；单次同步投影最简单，两个视图立即对齐。
• a-track 的 live 摄入没有稳定的 pi session-entry ID 来协调 get_messages/get_entries/agent_end.messages 多来源；也不能用文本匹配去重（合法消息可能相同）。
• SessionArchive 用的是稳定 get_entries receipt——那对 checkpoint/import/resume 是合理设计，但不能混用：一个 generation 只允许一种 canonical ingestion 策略。

"canonical" 不是什么（防止自我误解）

• 不是"只有最后一个成功的回答"。
• 不是 provider 认可的当前上下文快照。
• 不是 pi 原生 session 树的精确复制。
• 不是"内容去重后的消息集合"。

pi 自动重试后，两次完成的 assistant 观察都是各自独立的事件、各自的 provenance，都留在 timeline；turn_end / agent_end 里的副本不会多加行；同一个数据库摄入用旧 wire 身份重试不会加行。这是三种不同意义的"retry"，设计分别处理。

结构

                 HistoryStore (@ModelActor)
                           │
               ONE ModelContext / ONE save
                           │
           ┌───────────────┴────────────────┐
           │                                │
     JournalEvent                     TimelineMessage
     观察到了什么                      逻辑消息各一份
           └──────── provenance links ──────┘
        （操作状态模型 HistoryAgent / HistoryGeneration / HistoryOperation
          也在同一个 store 里）

实现纪律（概念层面必须记住的）

• 一个 @ModelActor，一个 ModelContext，autosaveEnabled = false。
• commit 模式：body() → save() → 成功返回 / 失败 rollback 并 rethrow。body 内不允许 await，不允许夹带无关的 pending 改动。
• 辅助函数（insertJournal / insertTimeline 之类）绝不自己 save，否则原子边界被拆散。
• rollback 会一起撤销 journal、timeline、计数器和操作状态；回滚后要重新 fetch，不要沿用旧的内存假设。
• 不要写成 "save raw event → await → save canonical message"。
• HostLease：本地单 host 租约。第二个 host 应得到友好的 "store already open" 错误——防止两个终端误开；这不是分布式锁、也不是多用户系统。
• 模型 internal，只对外返回 Sendable 的 DTO 快照；不要编码活的 @Model 直接进 HTTP。SwiftData 的 context/container 不是安全边界，协作代码必须自觉只有一个 writer。
• 不要用 @Attribute(.unique) 表达"拒绝重复事件"：先 fetch 身份、比较、返回原结果或抛错。永远不要插入冲突的新模型然后指望 SwiftData 帮你保住 append-only 语义。
• 引用用普通 UUID/sequence 属性，不用复杂 relationship 图；SwiftData 不校验外键，由 store 检查关联是否属于同一 agent/generation/operation/message。

限额与读取规则

• 限额（§1 表）在摄入时就检查；无法满足上限的 raw/canonical 行宁可拒绝存储也不要存成让轮询永远卡住的数据。
• 读取用 keyset 分页：sequence > after + 排序 + fetchLimit；agent 过滤就是再加一个 predicate。绝不 fetch 整个 journal 再在读取时推导 timeline。
• 短页（少于 limit）不是历史结束；客户端持续请求直到空页。空页的含义是"以当前视角暂时没有更多"，不是"流永远结束"。
• nextAfter = 本页最后一条被包含的行；空页则等于传入的 after。永远不跳过一条行去塞更小的行。
• cursor 校验：after ≥ 0、limit 1…100、after ≤ 所选流自己的 head；store 身份不符 → 409。
• 页的大小限制按实际编码后字节算（含转义），只包含能装下的前缀。

投影失败：唯一的窄例外

如果一条在限额内的原始记录语义上无法解释（比如消息包无效、违反 V1 策略），流程是：

1. 保留 raw journal 记录（无效 JSON 就存一个有界 wrapper：原文 + parse error）。
2. 追加 host 事件 history.projection_failed，写明相关 journal sequence、原因、generation、已知 operation。
3. 设置 HistoryGeneration.projectionError，标记该 generation/agent stopping，并在同一次 save 里为未决工作持久化"中断"评估。不创建猜测性的 timeline 行。
4. 返回 projectionFailure，controller 停止正常操作。

之后该 generation 进入 journal-only draining：继续读、继续存原始记录，但不会再产生 canonical 消息，也不会因为又收到一个 response 就恢复 accepted。这是 fail-closed 的窄路径，不是通用 schema 演进机制。

02a 提供两份可直接使用的源码：Models.swift（6 个模型 + V1 schema + migration plan）和 Values.swift（公共 DTO，全部 Codable, Sendable，带显式 public init）。把前者复制进 MVP/Sources/KastellStore/，后者复制进 MVP/Sources/KastellProtocol/HistoryValues.swift；它们替代 01 里的 LogRow/NoteInput 等草图，不要两套并存。

V1 的冻结规则

• 提供的 V1 声明是新 schema：不是从原 SQL journal 或 SessionArchive 的迁移；不要修改已发布的 V1 定义，要变就引入真正的下一个 schema/migration。
• 不要操作 SwiftData 底层的 SQLite 表、不要改 pragma、不要单独拷贝 WAL/main 文件作为备份策略。
• 需要转换真实数据时：写显式 import（保留 provenance）并给新的 store 身份，而不是重命名文件。
• 数据变得重要之前，用关闭状态的 store 目录做一致备份（包含所有 sidecar 文件）。

02a 结束时这个 actor 要提供的领域方法

open(url:) / identity()
appendNote(NoteInput) -> MutationReceipt
journal(after:limit:agentID:expectedStoreID:) -> JournalPage
timeline(after:limit:agentID:expectedStoreID:) -> TimelinePage
message(UUID) -> TimelineRow?          # 持久 provenance 查询
operation(UUID) -> OperationSnapshot?

createAgent / beginGeneration / markReady
admitPrompt / markAttempted
ingestPiRecord                          # journal + canonical 选择 + 证据
finishPrompt / interruptGeneration / abandon
requestAbort / requestStop / retireGeneration

这些是后续章节逐步补全的方法清单；02a 本身只要求先实现 notes 和 reads。方法名的要点是：没有公共的"任意插入"接口。客户端不能往 timeline 塞伪造的 assistant 消息；只有被接纳的 user 意图和可信的运行时摄入路径能创建那些行。

每章按同一模板展开：目标 / 产出物 / 核心概念 / 规则与取舍 / 完成判定 / 常见坑。已经在前文讲透的概念这里只给结论，不重复论证。

kastell log      [--after N] [--agent UUID] [--follow] [--cursor-file PATH] [--json]
kastell timeline [--after N] [--agent UUID] [--follow] [--cursor-file PATH] [--json]
kastell message  UUID
kastell note / prompt / agent / operation / ...   ← 沿用原章节的请求形状

reserve prompt slot
  → store.admitPrompt      （intent + canonical user + operation/busy 一次 save）
  → install response/settlement observation
  → store.markAttempted    （attempted 生命周期 + phase 一次 save）
  → Commander.writeLine(text: encoded single-record prompt)

IngestResult {
  journalSequence, eventID,
  canonicalMessageID?, timelineSequence?,
  wasReplay, projectionFailure?
}

ingestPiRecord(agent, generation, stream, ordinal, raw, ownership hint):
  1 查已有身份 → 若已保存：比较后返回 replay
  2 校验新 generation 的 ownership 与允许的捕获状态
  3 校验下一个 stream ordinal 与 payload 限额
  4 解析路由字段，同时完整保留 raw payload
  5 用 host 持有的 runtime/request registry 校验 operation 关联
  6 分类：journal-only / user echo / 新 canonical 消息 / 协议故障
  7 commit（内部无 await）:
      J = 下一个 journal sequence；插入 raw JournalEvent
      若为新 canonical：分配 T 与 message UUID；插入 TimelineMessage
        （sourceJournalSequence = J）；journal.canonicalMessageID 指向它
      若为 user echo：journal.canonicalMessageID 指到 operation.userMessageID；
        记录 userEchoJournalSequence；不插 TimelineMessage、不加 timelineHead
      把已识别的 response/settlement 证据应用到 operation 字段
      推进该 generation 的 stream head
      一次 save
  8 返回不可变 IngestResult

Host / AgentManager
  slots[A] → PiRuntime A ─┐
  slots[B] → PiRuntime B ─┼──► ONE HistoryStore model actor
  slots[C] → PiRuntime C ─┘      ├── journalHead / timelineHead
                                 ├── JournalEvent / TimelineMessage
                                 └── agent / generation / operation records

manager 看到 idle
await store.admitPrompt(...)     ← 挂起期间其他请求/关闭可以进来
manager 标记 busy                 ← 已经太晚了

J#20 A prompt.requested        → T#1 A user
J#21 B prompt.requested        → T#2 B user
J#22 A pi.message_end(user)    → 链接 T#1，无新行
J#23 B pi.message_end(user)    → 链接 T#2，无新行
J#24 A pi.message_update       → 无 timeline 行
J#25 B pi.message_end(assistant)→ T#3 B assistant
J#26 A pi.message_end(assistant)→ T#4 A assistant

open history.store，取得单 host lease
加载持久 storeID 与 journal/timeline heads
生成新的 hostID
reconcile 旧的非终局 generations/operations
append host.started
创建空的 live runtime registry
打开 client admission

MVP/Sources/
  KastellProtocol/
    HistoryValues.swift      # 提供的双历史 DTO
    Requests.swift           # agent/prompt/control 输入
    Responses.swift          # operation/agent/problem/health DTO
  KastellStore/
    Models.swift             # 提供的 SwiftData V1 schema
    HostLease.swift          # 单本地 host 租约
    HistoryStore.swift       # open、save/rollback、identity、有界读取
    HistoryMutations.swift   # notes、admission、生命周期转换
    PiIngestion.swift        # raw 捕获 + canonical 选择，一次 save
  KastellRuntime/
    PiRuntime.swift          # child/readers/当前 operation 所有权
    RPCInbox.swift           # 私有路由/waiter helper
    AgentManager.swift       # reservations、slots、shutdown barrier
  KastellHost/
    HostMain.swift           # composition root + lifecycle
    HostConfiguration.swift  # host-only 路径/端口/profile 配置
    Routes.swift             # journal/timeline 端点 + 命令
  KastellCLI/
    ClientMain.swift / HostClient.swift
    HistoryCommands.swift    # 独立的 typed cursors 与 renderers

教程不另设测试规划路线，而以终端会话验证正常工作流。请实际执行以下场景，并保留命令、关键输出和相关 ID；自动化测试可作为补充。A 组在 04a 结束时可完成，B、C 组需要 05a–07a，D 组用于最终使用验收。

A. 边界与首个往返（01–04a）

• swift build --package-path MVP 通过；模块依赖符合 §2；CLI 仅依赖 Protocol 与 Foundation，不依赖 Store 或 Runtime。
• 同时只有一个 host 能打开 store；第二个得到友好错误。
• note：只出现在 journal；timeline 空；同 operationID 重试返回原 receipt；不同内容同 ID 冲突。
• GET /v1/log / GET /v1/timeline 各自校验自己的 head；storeID 不符 409；畸形 cursor 400。
• log 与 timeline 的 cursor 文件互不干扰；错误 cursor 被本地拒绝。
• 短页不会让 CLI 提前停止；Ctrl+C 不影响 host 中工作。

B. 单 agent 摄入（05a）

• admission 后立刻有一条 canonical user 行，operation 为 prepared→attempted。
• user echo：journal 增加、timeline 计数不变、链到原 user UUID。
• assistant message_end：raw 行与 canonical 行一起 commit（同一 save 的结果）；未完整/未知消息不会被猜进 timeline。
• 重复摄入同一 raw 记录 → replay，无新行、无重复状态转换。
• 语义无效记录 → raw + history.projection_failed + generation stopping；此后只有 journal-only drain。
• accepted 和 settled 的证据各自独立落盘；settlement 无终局 assistant → interrupted，而不是假回答。

C. 多 agent 与恢复（06a–07a）

• 两个 agent 交错运行；journal 与 timeline 顺序不按 agent 分组，provenance 能解释对应关系。
• busy agent 的 prompt 被拒绝（明确错误），不进队列。
• 客户端断开不取消已接纳工作；同一 operation 重试返回原 receipt。
• abort 只作用于 admission 时 pinned 的 prompt，不误伤后续工作。
• 正常 stop 后重启：两个历史可读、游标继续、storeID 不变、hostID 变。
• 未完成工作显示 interrupted；abandon 记录决定、保留所有消息、不重放。
• 启动过程没有 journal 重放，也没有 timeline 重建。

D. 六个日常里程碑（08a，最终使用验收）

1. note 只进 journal。
2. prompt → 一条 canonical user 行。
3. user echo → timeline 计数不变。
4. 完成回答 → raw 证据 + 一条 canonical 回答。
5. stop/reopen → 同样的行与 provenance。
6. 两个 agent 交错 → 规则依旧成立。

教程把它们散落在各章；这里集中。实现任何新功能前先问：会不会破坏其中一条？

1. Commit before success（提交先于成功）。成功的 note/operation receipt 指一个已提交的数据库事务，不是内存队列里的待办项。
2. One journal order（唯一 journal 顺序）。sequence 由数据库 writer 分配，永不来自时间戳或 agent 本地计数器。
3. No mutation of facts（事实不可变）。修正与生命周期变化都 append 新事件；操作表可以与事件在同一次 save 里原子更新，但历史行不改不删。
4. One active prompt per generation（每个 generation 同时最多一个 prompt）。在任何可能让第二个 prompt 进入的 await 之前先 reserve busy 状态。SwiftData 不消除 actor reentrancy。
5. No blind resend（不盲发）。尝试写入管道但没有 pi 响应 = 不确定，不等于 pi 什么都没做。绝不自动重发。
6. Journal + canonical 同一次 save。没有后台 projector、没有最终一致性窗口；投影失败是显式的窄例外，且那之后只 drain 不投影。
7. 只有两条路径能创建 timeline 行：被接纳的 user 意图、可信运行时摄入的非 user message_end。客户端不能插入任意消息。
8. 重放看身份，不看文本。同 identity 返回原结果；相同文本 + 新 operationID = 新动作；绝不 hash 文本合并。
9. reader 纪律。只有一个 stdout reader；它绝不 await 只有自己能读的 RPC 响应；response 在 raw 证据保存前不能交给 waiter。
10. 关闭有序。停 admission → join handoff → generation 保持可捕获地 stopping → reap child → join readers/tasks → 存最终状态 → 释放 store/lease。重启后 fresh context，不自动重放。

这些不是"以后做"的路线图，而是 M1 故意不做的清单。每一条都可以在需要时单独重新决策。

• "All messages" 有精确定义：host 收到并成功提交的、限额内的完整记录（含 tool 与 error 消息）。不是"模型说过的一切"。
• 没有持久确认协议：RAM-only 的 pi 进程在崩溃时可能丢弃未被接收/未提交的尾部；M1 暴露这个限制，不承诺无损捕获、不承诺 exactly-once 执行。
• live ordinal 是 host 观察身份，不是 pi 原生 entry ID：无法识别以全新 ordinal 到达的任意重传；也不能把 live 流与 get_entries 历史按内容做身份协调。
• timeline 不是 pi session 树的精确副本；faulted generation 存在 journal-only 尾巴——那条 timeline 不能被声称完整。
• 两个独立 GET 不构成同一快照；user 行不会随 operation 状态变化而更新。
• 客户端崩溃可能重复输出已渲染的行（先打印后存 cursor 的代价），但不应跳过任何行。
• 单 host lease 不是分布式锁，不提供多用户保护。
• append-only 是应用契约，不是防篡改存储：SwiftData 的 var 属性、unique attribute、底层表都可被写入；靠"一个协作 writer + 私有 mutation API + 无 delete/update 路由"约束。
• save 失败无法被记录在同一块盘上（如磁盘满）；此时回滚全部并走 host 失败路径。
• 超限记录无法完整保留（>1 MiB）：只在可能时记录有界的 size/error 评估。
• 历史可见 ≠ 新进程记得：fresh generation 上下文为空；语义续接是显式后续功能，且需要新的 echo 校验设计。
• 流程重试 ≠ store 摄入重试 ≠ pi 自动重试——三种 retry 语义不同，设计分别处理（见 §7/07a）。

Journal

观察日志。客户端意图、host 生命周期、host 从 pi 收到并成功提交的限额内 stdout/stderr 记录的 append-only 全局序列；允许同一逻辑消息出现多次。

Timeline

规范消息集合。每个 admitted user 意图、每个合格的非 user message_end 各一行；跨 agent 的独立全局序列。

Canonical

"逻辑上一条消息一行"，不是"全局一份字节"。timeline 行是物化的规范表示；payload 与 journal 有意重复。

Projection（投影）

从 journal 观察决定"是否产生 canonical 行"的固定策略（§4 表格）。原子发生在每次摄入的同一个 save 内，不是后台任务。

Provenance（来源链）

timeline 行 ↔ journal 事件 ↔ operation 的双向可追踪链接（sourceJournalSequence、canonicalMessageID）。

Admission（接纳）

prompt 正式进入系统的持久化时刻：intent + canonical user + operation + busy 一次 save，发生在任何 RPC 字节发出之前。

Attempted / Accepted / Settled

prompt 的三个持久里程碑：已尝试写入（不确定的前沿）、pi 已确认接受、会话级 settlement 已观察。三者在不同 save 中独立落盘。

Receipt（回执）

{storeID, operationID, sequence}；确认客户端动作已提交。sequence 永远是 journal 位置。重试返回原回执。

Operation

一次客户端意图的持久记录（note/prompt/abort/review…），带 phase、消息绑定、outcome；连接意图、运行时归属与执行结果。

Generation

一次 pi 进程/上下文化身。它不证明进程活着，是数据库用来比较的 fencing token；每个 generation 有自己的 stdout/stderr ordinal 头。

Agent

命名的逻辑 worker，跨 stop/start 存活；不是 PID。

Cursor（游标）

"在这个 store、这条 stream、这个过滤条件下，位置 N 之后"：{storeID, stream, after, agentID}。两条流不能共用裸数字。

Wire ordinal

某 generation 某条 OS 管道上收到的第几条完整记录，从 1 开始；作为收到的原始行的持久身份的一部分。

Keyset pagination

用 sequence > after + 排序 + fetchLimit 取下一页，而不是 offset；配合"直到空页"的客户端循环。

Owner（所有者）

每个资源恰好一个；负责 retain、cancel、await 清理。Swift 的 actor 不会自动成为所创建 task 的 supervisor。

Reservation（预留）

在 await 之前抢先登记的临时占用（如 prompt slot），防止 actor reentrancy 让第二个请求进入；提交后只有"仍是当前"的 reservation 才被释放。

HostLease

单机单 host 的租约文件；防止两个终端误开同一个 store。不是分布式锁。

Journal-only draining

projection fault 之后的模式：继续读存原始记录，但不再产生 canonical 行、不恢复投影；故障显式可见。

Fresh context

重启后显式启动空白 pi 上下文；历史可读但不自动成为 prompt 内容。语义续接是后续显式功能。

教程阅读顺序（a-track）

Tutorials/01-MVPBoundaries → 02a-SwiftDataHistory → 03a-SwiftDataHostAPI → 04a-JournalTimelineCLI → 05a-PiJournalTimeline → 06a-SwiftDataMultiAgent → 07a-SwiftDataRecovery → 08a-DualHistoryDesignReview。

原 SQL 线（02–08）保留作对照；03-HostAPI/API.md 的写接口形状在 a-track 继续有效。

工作区里可复用的资产

pi 协议注意事项（以本地安装包为准）

• 参考版本：本地 pi 0.85.1 的 rpc.md、session-format.md、settings.md；若上游 tag/新版本不同，以你安装包的 docs/ 为权威。
• 本课程用 agent_settled（会话级完成边界），不是 agent_end。
• message_end.message = 权威的完整消息；message_end 不是持久 pi entry 身份，也不保证 tools 成功。
• 发送 prompt 用 JSONEncoder 输出单条记录；绝不把用户文本插进 JSON 字符串，绝不自己拼 LF。

环境

• macOS 26+、Swift 6 language mode、Swift 6.0 tools；SwiftData 宏与示例需要完整 Xcode：export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer。
• 数据库固定在 MVP/.state/history.store；MVP/.gitignore 排除 .build/、.swiftpm/、.state/；凭据与运行日志不进仓库。

一句话结尾

先做小、做对、做得能解释：一个 host、一个 writer、两个历史、多个 agent、一个诚实的 CLI。剩下的复杂度，等真实使用提出要求再说。

↑ 回到开头

这一章不是教程内容，也不改变任何设计。它是通读 01 + 02a–08a（并对照原轨道）之后，我认为最值得补上的东西：教程给你的是设计；而落地时最容易出错的，是各章之间的接缝，以及那些“看起来都对、就是不对”的时刻。教程本身仍是权威，下面是我个人的笔记，你可以把它当成一份可修改的 checklist。

B1 · 接缝处的十个决定

这些是两个章交界、契约只被“勾勒”而没有写死的地方。它们不需要现在回答“对错”，但需要你明确选一个，并且写下来——哪怕只是一行注释。我做实现的习惯是给每个决定写三行：背景 / 决定 / 后果。

1. 区分运行时归属与持久状态校验。
   • 教程事实：runtime 在发送前装好 active operation（05a）；store 校验显式传入的关联（02a）；manager 负责调度（06a）。
   • 我的建议：runtime/controller 持有当前进程与请求的关联；store 依据持久化的 active 指针、generation 归属和 operation 状态，校验调用者传入的 (agent, generation, operation) 三元组。两者职责互补：runtime 不能绕过数据库校验，数据库中的 busy 指针也不能证明进程仍在执行。
2. 把两套状态机的转换表写下来。
   • 分别列出合法转换，而不是串成一条通用状态链。note 可直接为 recorded；prompt 的主要路径是 prepared → attempted → accepted → settled，另有拒绝与中断分支；interrupted → abandoned 需要显式 review。agent 的 idle/busy 是调度状态，应与 generation 的 starting/running/stopping 分开说明。
   • 写一张“事件 × 当前状态 → 新状态 / 是否允许 / 同时写什么”的表，作为唯一参考；代码里做一个 isAllowed(transition) 之类的校验。特别写死：settled 只表示“结束”不表示“成功”；settled 之后不接受 accepted 回退；interrupted 优先于 idle；busy 指针只能由已定义的 admission、完成、拒绝或中断事务更新，不由无关回调修改。
3. reservation 复验清单要精确到字段。
   • 06a 的六步里，“revalidate”最容易被写成“大概没事”。我的复验项：(a) operation 身份与登记时一致；(b) generation 仍是当前 generation，且状态允许当前动作（新 prompt 要求 running；starting/stopping 可捕获记录，但不因此允许新 prompt）；(c) 没有未决的 control/abort/stop reservation；(d) 没有 projection fault；(e) 容量 slot 仍属于这个 reservation；(f) manager 还没有关闭 admission barrier。
   • 释放规则同样要精确：失败时只释放仍是已登记那一个的 reservation（按身份比较，不按 slot 序号），绝不能释放后来者。这个函数值得配注释和一个 debug 断言。
4. markStopping / retireGeneration / reconcileOnStartup 是三件事，不是一件事。
   • markStopping：fence 仍有效，readers 仍可写；retireGeneration：readers 已 join、禁止再 append、写最终 generation 状态；reconcileOnStartup：只发生在 boot，处理上一次遗留的孤儿。
   • 我的做法：让 retire 只有 shutdown 的 join 点能调用（把“已 join 的凭据”作为参数传递）。让“提前 retire”在类型层面就难写出来，比在 code review 里抓住它可靠得多。
5. 解析发生在哪里，原始字符串永远原样保留。
   • reader 只负责读完整行、分配 ordinal；解析/分类放到 store actor 上（或 reader 侧解析成一个只含提取字段 + 原始字符串的 Sendable enum）。
   • 无论选哪种：raw 保留 Commander 交付的原始行文本，canonical 从解析结果确定性编码。这里不承诺字节级管道归档：Commander 会处理行尾，非法 UTF-8 或超长帧可能在交付前被拒绝。不要为格式美化重写 raw，也不必为了生成 canonical 重复解析。
6. 把事件路由做成一张二维表。
   • 维度：事件类型 × 是否存在匹配的 active operation。格子里填：journal-only / 生命周期证据 / echo 绑定 / 新 canonical 行 / protocol fault。
   • 教程的规则分散在 05a/06a 各节；合成一张表贴在 ingestion 代码旁边，新增事件类型时先改表再改代码。特别注明：正常摄入时，无归属的对话 message_end 应保留原始证据并触发投影故障；已进入故障排空模式的 generation 则继续 journal-only——丢掉会让调查者永远不知道发生过什么。
7. 时间只有一个来源，而且不参与冲突判定。
   • recordedAtMS 是 host 接收时间；admission 的时间戳在首次提交时固定、重试不重生成；排序一律用 sequence。
   • 建议集中处理时间获取；确有替换需求时再注入时钟函数或协议，并在比较函数上留注释：“时间戳不用于判断两条记录是否相同”。很多“重试变成了新事件”的 bug 都是这里漏的。
8. 溢出与超限的失败姿势：fail closed。
   • 分配 sequence 或 ordinal 前检查溢出；raw/canonical 存储 JSON 分别受 1 MiB 上限约束，编码后的读取页受 8 MiB 上限约束。超限、计数器耗尽与语义投影失败要分别报告，不一律归为 projection_failed；存储不可用时转 host 失败路径。
   • 不静默回绕、不跳过、不“先存了再说”。这些分支在正常开发中永远不会跑到，正是它们值得在写的时候多想五分钟。
9. 那些数字是策略，不是语义。
   • fetchLimit = 4、8 MiB、32 KiB、1 MiB、250ms……放进一个常量文件，每个两行注释写明“为什么是这个数量级”。
   • 验收脚本不要依赖具体数值（除非你正在验收限额本身）。否则将来调参时，会有一批“测试”替你把好设计锁死。
10. projectionVersion 是兼容承诺；同时给未来的 renderer 留一扇可替换的门。
    • 承诺：同一个 storeID + stream=timeline + after，其含义不因投影策略升级而原位漂移。改策略需要新版本与明确的兼容或迁移计划；不支持的版本应显式拒绝，不能静默重解释旧行。
    • 建议现在就做的一件事：把 user-echo 校验写成一个纯函数（输入：原始意图文本/结构、收到的 echo、当前策略版本；输出：匹配/不匹配/异常）。将来加入语义续接 renderer 时，这能缩小校验逻辑的改动范围；仍需设计派生请求记录、来源追踪和恢复策略，不能认为只改一个函数就已支持续接。

B2 · 调试剧本：症状 → 最可能的违约 → 先查哪里

这张表是把 §9 的硬规则反过来用：看到症状，先假设某条不变量被破坏了，而不是先怀疑 pi 或系统。

B3 · 故障注入演习：没有测试框架的测试

教程明确说“终端会话就是正常工作流”。下面七个演习用于复现进程、存储和连接故障，补充正常路径与单元测试。请使用独立的临时 store 和可丢弃的测试进程，不在真实数据目录上演练。

1. 在四个提交边界强制终止 host。 在四个时刻分别 SIGKILL：① admit 后、attempted 前；② attempted 后、acceptance 前；③ message_end 提交后、settled 前；④ settled 后、finish 前。
   通过判据：重开后逐个对照 07a 表——①/② 用户行存在、operation interrupted、无伪造回答；③ 至少一条 canonical assistant 在，operation 可能仍非终局但被保守标 interrupted；④ 若最终 host 转换尚未提交，仍保守标为 interrupted，重试返回原 admission receipt，并通过 operation 查询中断结果；只有最终转换已提交时才保留原终局 outcome。全程不允许出现“有 receipt 却无 intent”，也不允许“timeline 有答案但 journal 无 raw”。
2. 只杀 child，不杀 host。 对 pi 子进程 kill -9。
   通过判据：等待两个 reader 消费可交付的缓冲记录并结束，显式报告读取错误；generation 与未决 operation 标 interrupted，不伪造 assistant。child/readers 清理完毕后才释放容量；是否可再次 start，仍需检查未解决工作的 review 政策。
3. store 写失败。 在可丢弃环境中使用受控故障注入，让保存步骤确定性地失败，再发 note。仅将已打开的目录改成只读未必能阻止已有文件描述符继续写入；无权限路径通常只能验证打开失败，不能代替 save/rollback 演习。
   通过判据：请求以可理解的错误失败；journal、timeline、计数器与操作状态一起提交或一起回滚，不存在“一半提交”；host 走失败路径而不是假装成功。
4. 超大记录。 为演习临时把 1 MiB 上限调小到容易复现的值（例如让一条 stdout 行超过几 KB），触发拒绝路径。
   通过判据：不落盘完整超限内容；在存储仍可用且评估记录满足限额时保存有界 size/error 事件，否则向 stderr 报告。generation 停止；后续轮询不卡死；错误可见。
5. 畸形 JSON 注入。 在 pi stdout 上制造一行非法 JSON（或用测试替身进程）。
   通过判据：raw wrapper + history.projection_failed + generation stopping；之后进入 journal-only drain，后续记录仍在 journal 可见。
6. 断线重试。 分别验证两件事：关闭 --follow 只停止观察；另在 mutation 请求提交后、回执接收前断开客户端，再使用原 operationID 和原输入重试。
   通过判据：host 工作不受影响；返回原来的 receipt；timeline 不新增重复消息；新客户端从头读得到完整历史。
7. 双开。 同时启动第二个 host。
   通过判据：第二个 host 得到清晰的 lease 错误并退出；第一个 host 不受影响；第二个 host 未打开写入路径、未修改历史数据（lease 文件的检查本身不等于写历史）。

B4 · 变更准入测试：加任何东西之前的十个问题

任何新功能、新事件类型、新命令，先检查下面十项风险。每项均确认“不存在该风险”后再勾选；若答案为“是”或仍不确定，先补充设计说明，不把勾选当作批准。

• 它是否引入第二个 writer、第二个 ModelContext 或第二个 store？（§5）
• 它是否会在某个 helper 内部悄悄 save()？（§5）
• 它是否在两处合法路径（admission、可信摄入）之外创建 timeline 行？（§9 规则 7）
• 它是否让 client 或 runtime 自己推导 canonical/去重策略？（04a）
• 它是否引入了不被 reservation 覆盖的 await 窗口？（§9 规则 4）
• 它是否依赖 wall-clock 排序，或让时间戳参与“是否同一条”的判定？（§3）
• 它是否会自动重放、重发或“帮忙”完成不确定的工作？（§9 规则 5、07a）
• 它是否为存储引入新的无上限 payload 类型或字段？（§5 限额）
• 它是否让恢复“更聪明”：启动时重建 timeline、自动补完 interrupted operation、自动继续对话？（07a）
• 它是否把可变状态塞进不可变历史行，或让旧行随 operation 悄悄改变？（03a、06a）

B5 · 调试自检：debug 构建里的八条断言

这些断言可检查计数器、身份与引用的一致性，但完整扫描及关联校验会随数据量增长，不应视为恒定低成本。建议放进一个 debug-only 函数，在 启动 reconcile 之后和 需要时的自检命令里调用——不要让它在生产路径上每次摄入后都跑，更不要变成后台任务。

1. journalHead == max(JournalEvent.sequence) == journal 行数，并检查 sequence 唯一且连续（空表的 max 按 0 处理；前提是从 1 连续分配且历史从未删除）。
2. timelineHead == max(TimelineMessage.sequence) == timeline 行数，同样检查唯一性、连续性与空表情况。
3. 每条 TimelineMessage.sourceJournalSequence 指向存在的 journal 行，且那条行的 canonicalMessageID == messageID。
4. 每个非空 canonicalMessageID 都指向存在的 TimelineMessage。
5. 每个 agent 最多只有一个非终局的 active prompt operation。
6. HistoryGeneration.stdoutHead/stderrHead 等于该流已存身份的最大 ordinal，且 1…head 无空洞（重放不算新 ordinal）。
7. timeline 的 agentID/operationID 都指向存在的行；operation 绑定的 userMessageID 存在且 role=user。
8. 所有 operation 的 state 在允许集合内；settled 的必须带 outcome；interrupted 的不携带伪造的终局 assistant 指针。

这些检查不能替代 B3 的故障演习——断言证明“账本自洽”，演习证明“世界变化时账本仍然诚实”。两者互补。

B6 · M1 之后的成长阶梯

下面的顺序是我个人的建议。核心原则：每一项都要连同前置条件一起批准。不满足前置条件的实现，不管多小，都只是在给未来的自己增加 B2 表格里的条目。

↑ 回到开头

前文给出实施路线，Bonus 补充模块衔接和排错方法。本章继续讨论运行时容易忽略的风险，并列出 M2 的候选方向。 这些是补充审阅建议，不是已实现能力，也不自动扩大 M1 范围。涉及新状态、错误码或命令时，应先定义契约并验证，再纳入实现。

E1 · 并发与进程管理的五个风险

Swift 6 的严格并发检查有助于发现隔离与 Sendable 使用问题，但通过编译不等于状态机正确，更不代表底层 I/O、外部进程和不安全接口已得到验证。以下五点需要在实现中单独检查。

1. 跨 await 保留未提交的 ModelContext 改动。
   风险：actor 方法在 await 处可能挂起；挂起期间，其他任务可以进入同一 actor。若共享 context 中仍有未提交改动，另一次 save 或 rollback 就可能把不属于本次操作的状态一并提交或撤销。并非每个 await 都实际挂起，但设计必须按“可能重入”处理。
   规则：属性修改、关联校验与 save() 必须处于同一个无 await 的提交边界。异步准备在边界外完成，进入后重新校验状态。
2. 管道背压与关闭顺序。
   风险：管道容量有限，不能把某个容量数值当作跨系统保证。下游停止读取后，生产方可能阻塞或等待可写；此时只等待 child 退出而不排空输出，可能无法完成关闭。
   规则：正常关闭时保留 stdout/stderr 单消费者循环，stop/reap child 后再 join readers。当前 Commander 在直接子进程退出后会做有界尾部捕获并关闭描述符，避免后代进程持有管道导致无限等待；上层应消费其可交付记录并处理终止错误，不能承诺总能等到物理 EOF 或完整捕获所有后代输出。
3. 轮询重试错误地推进或重置游标。
   风险：M1 是 loopback 上的普通轮询，不是长轮询。即使在本机，请求也可能超时或连接中断；服务端完成响应不代表客户端已经成功展示。凭猜测推进游标会漏读，每次失败都重置为 0 则会重复全量读取。
   规则：成功展示非空页后推进到 nextAfter，短页也一样推进并继续读取；空页才暂停，follow 模式等待后再查。瞬时 GET 失败从最后已展示的位置有限退避重试；格式错误、顺序异常与 store 变化应显式报错。
4. 直接子进程退出，不代表整个进程树已清理。
   风险：Commander 只管理直接子进程。开启 tools 或扩展后，其派生进程可能继续运行、持有管道或占用端口；仍在运行的孤儿进程与已退出待回收的僵尸进程不是同一概念。
   规则：M1 初始关闭 tools 与扩展发现。异常退出后，先核查残留进程再启动替代实例；锁文件、旧 PID 和 generation UUID 都不足以单独证明进程归属。任何清理命令都需核对身份并明确确认，不能按进程名批量终止。进程组管理属于后续显式设计。
5. 绕过 SwiftData 检查活动数据库。
   风险：外部写入可能破坏框架维护的状态；长读事务可能阻碍 WAL 回收，但不能简单等同于所有写入都会报 busy。immutable=1 声明文件不会变化，不适用于仍在写入的活动 store，也不是通用安全只读开关。
   规则：日常检查使用 kastell log、timeline、message 与 operation。需要离线取证时，先关闭 host，备份完整 store 目录及 sidecar 文件，再在副本上分析；不把未公开的底层表结构当作应用接口。

E2 · 故障处置矩阵

故障时的原则是：停止扩大影响，保留能够确认的证据，不伪造成功。下表沿用 M1 的失败路径；超时阈值、诊断事件名和 HTTP 状态码仍需在实现时明确，不在这里追加一套未经验证的降级协议。

E3 · 展示降噪与完整存储

日常阅读不需要暴露每个协议细节，但展示简洁不能以删减持久证据为代价。应把“保存哪些消息”和“默认显示哪些内容”作为两个独立问题处理。

E4 · M2 候选能力与前置条件

先完成 M1 的实际验收，再根据使用问题选择后续能力。下列方案不是承诺交付的路线图；它们需要新的设计评审，尤其要明确哪些 M1 契约继续成立，哪些需要版本化变更。

E5 · 致实现者：让承诺与证据相称

↑ 回到开头

延续前两轮审阅的做法，本章记录我的最终判断、这次修订的重点，以及交付前仍需完成的验证。终审的目的不是再加一层架构，而是让全文的承诺、术语和行动建议彼此一致。

F1 · 审核结论与适用范围

§0–§14 是实施主线；Bonus 与 §15 是补充建议；本章说明终审边界。M2 候选能力不计入 M1 验收，也不能因写进报告就视为已经支持。

F2 · 本轮纠偏要点

1. 完整存储与简洁展示分开。合格完成消息中的 thinking、工具字段和失败信息保留在 canonical payload；CLI 可折叠，存储不能悄悄删减。完成消息不等于终局成功回答。
2. 来源链接不可改写。submitted user 的来源始终是 prompt intent；user echo 只链接回已有消息，不重写其 sourceJournalSequence。
3. 分清三类失败。语义投影失败、传输帧错误与数据库保存失败，能保留的证据不同；不能一律承诺“原文已入库并可继续排空”。保存失败也不能提前释放仍有任务持有的 slot。
4. 恢复不补写成功。settled 证据已在、最终转换未提交，重启后仍保守标 interrupted。原 admission receipt 与终局 outcome 是不同事实；重试前必须分清。
5. 收回未经支持的安全承诺。worktree 不是沙盒，内容摘要不是安全签名，append-only 不是防篡改存储；活动数据库不能用 immutable 声明绕过正常读取约束。
6. 把建议写成可执行的条件。修正短页的游标推进、限额层次、故障演习判据与自检成本；删去“绝对完整”“确定性演进”等超出证据的措辞。

F3 · iPhone 阅读与验证边界

• 排版：手机正文采用 16px 基准字号，缩小嵌套卡片留白；长标识符可换行，宽表格和等宽图各自横向滚动。保留页面缩放，并考虑安全区与减少动态效果的系统偏好。
• 导航：窄屏目录可折叠，章节锚点保留；滚动高亮不再把手机页面拉回目录。目录链接、回顶按钮和勾选标签提供便于触控的操作区域。
• 交互：验收项使用原生复选框，支持键盘与辅助技术；浏览器拒绝 localStorage 时仍能临时勾选。为避免修订后状态错配，不迁移旧版按列表序号保存的勾选记录。
• 离线：样式与脚本均内嵌，无外部字体、图片或网络依赖。Safari 与“文件”App 的预览能力不同：不执行 JavaScript 的预览保留正文、表格和原生锚点，目录折叠、进度条及勾选增强需要支持脚本的浏览器。

本轮验证：WebKit 与 Chromium 在 320、375、390、430、844、1440px 视口下通过页面宽度、锚点、目录高亮、回顶、勾选保存和键盘操作检查；另检查本地文件打开、禁用脚本、拒绝本地存储及正文放大情形，未发现脚本异常或整页横向溢出。WebKit 的 iPhone 视口模拟不等于 iPhone 真机 Safari 或“文件”App 实测，仍建议在目标手机上按下列步骤复核。

F4 · 交付前的最后一轮验收

1. 先验文档：在 iPhone 竖屏与横屏分别打开，检查页首、05a 长卡片、E2 宽表和本章；左右滑动只影响表格或代码区域，放大文字后正文仍可读。
2. 再验交互：展开目录跳到 05a 与本章，测试回顶；勾选一项并重开页面，确认当前打开方式是否支持保存。若使用文件预览，不把脚本缺失误判为正文缺失。
3. 最后验产品：执行 §8 的日常闭环与 B3 的相关故障演习，记录 storeID、operationID、J#/T# 和实际结果。未运行的项保持未勾选，失败的项保留失败证据。

↑ 回到开头