19v6-03 · 存储形态与生命周期
本篇是 doc/19-v6 文档集的存储篇:四表 + 两键(PG 四表 + Redis 的
runlive/runepoch)、生命周期、真源划分、多副本。 2026-10-20 起draft已移除(doc/38)。端点契约见19v6-01;概念表见 index(19-运行引擎架构-v6.md)。
三搬两留一消失(2026-10-07 D1 落库)
| 结构 | 原形态(Redis 六键) | 现形态 | 介质 |
|---|---|---|---|
session |
tk:session:{id} STRING |
sessions 表 |
PG |
model_history |
tk:mh:{session} LIST |
run_model_messages 表 |
PG |
runlog |
tk:runlog:{session} LIST |
runlog_entries 表 |
PG |
runlive |
tk:runlive:{run} LIST |
留 Redis | Redis |
draft |
tk:draft:{run} STRING |
已移除(doc/38) | — |
runepoch |
doc/30 起新增,不在当初六键里 | 留 Redis tk:runepoch:{run} STRING |
Redis |
live(闸) |
tk:live:{session} STRING + 租约 |
消失——闸 = runs 表活行上的部分唯一索引 |
PG |
- 一次搬完,不走过渡双写;四个 API 的线上字节零变化(A4-1 baseline 原样重跑判据)。
- 留 Redis 的理由(2026-10-20 起,doc/38):
runlive与runepoch是临时态——TTL 到即清、过期不影响历史正确性(真源划分见下)。 定稿正文在 turn 里,EndRun把它写入 runlog,不再在 Redis 存全文。AppendFrame(唯一的帧写口,2026-10-21 起)每次只问runepoch是否等于本执行者的令牌。 - Redis 临时键只剩这两类,
tk:前缀纪律不变(tk:runlive:{runId}/tk:runepoch:{runId}): reset 用SCAN MATCH tk:*对未来新增的键天然免疫,也是连错实例时的误伤防线。 - 不复活
Store接口(A4-3 已裁单实现):唯一实现内部跨两存储——PG 管永久状态,Redis 管临时态。
四表(PG)
sessions—— 会话登记:id(s_<ULID>,主键)、title(展示字段,非契约;初值 = 首条用户消息 按 rune 截断,重复投递不重写)、created_at。存在即已登记(懒建于 POST 事务内);永久状态。runs—— run = 闸 + 状态 + 租约(执行单元本身),不存消息文本:id(r_<ULID>)、session_id、status(running / complete / error;stopped后续 loop)、lease_until(活行租约,终态置 NULL)、created_at、finished_at。- 闸本体 = 部分唯一索引
one_live_run_per_session:UNIQUE (session_id) WHERE status = 'running'; - 活行读 / 死行清扫走索引
(session_id, status, lease_until)。 - 租户并发闸(doc/43):
AcquireRun事务内先pg_advisory_xact_lock(<tenant id 哈希>), 再数该租户的活 run(runs JOIN sessions,口径status='running' AND lease_until > now()), 超tenants.max_concurrent_runs就拒(429113001)。数与放行同一笔事务、期间持一把 所有副本共享的锁——这是会话闸之上的第二道闸(会话闸管「一场会话」,租户闸管「一个租户」)。 - 一 run 的消息有多条,见下——
runs只留闸 / 状态 / 租约。
- 闸本体 = 部分唯一索引
run_model_messages—— run 内的模型侧消息序列(model_history的落库形态):id(msg_<ULID>行级主键,与契约字段messageId是两回事)、session_id(冗余列:消息不跨 run/session 移动)、run_id、seq(run 内序号,从 1 起;0 = compact 摘要行)、role、text、compacted(默认 false)、created_at。- 自然键
UNIQUE (run_id, seq);模型输入的热查询走部分索引(session_id) WHERE compacted = false。 - 消息按行设计:一条消息一行,种类由
role列的取值承载、不编码进列结构——本步只产生 user(POST 投递)/ assistant(定稿),agent 形态的多轮 ReAct 与 HITL 人工插入都是后续 seq 行 (role是 TEXT 不是 ENUM,扩展零迁移);结构化附加字段(tool_calls 等)随对应 loop 加列。 compacted是 compact 的落点(原文行保留作审计、不进模型输入;可见内容由 seq=0 摘要行替代)—— compact 压本表、不动 runlog;触发形态与摘要行规格已定于 19v6-07(§1 触发者 = worker 发送前 自测、无定时器;§2 摘要行 role=user、挂点 = 本事件最后折入的 run、二级压缩不单做)。
- 自然键
runlog_entries—— 历史真源:id(rl_<ULID>)、session_id、seq(session 内序号 = runlogOffset 的列形态;列名避用offset——PG 保留字;契约词汇runlogOffset/nextOffset不变)、run_id、role(本步 user / assistant)、message_id(仅 user 行;客户端生成、服务端零读路径)、text、created_at。- 自然键
UNIQUE (session_id, seq):seq 分配(事务内MAX(seq)+1,唯一约束兜底)、高水位(MAX(seq))、 收口按run_id匹配半截气泡,全走它。 - 只增不删:「seq N 恒指同一条消息」是客户端对齐游标只前进的地基——任何失败路径都不删行; 「run 没跑成」的形状一律走 error 结局(留 user 行、无 assistant 行)。
- 自然键
零 JSONB、零外键、全表代理主键(2026-10-07 裁):消息、摘要都是行 / 列,无键序问题; 引用完整性归应用层(写入路径只有 engine 一处、且被闸串行化);代理主键供未来行级引用。
闸的落库形态(kill -9 在 DB 形态下的答案)
- 闸 = 部分唯一索引:
AcquireRun事务INSERT runs(status='running'),冲突即 409—— 「插入失败本身就是闸」的字面落地(AGENTS.md「闸放数据库不放进程」);放闸 = 终态那笔UPDATE status, 没有独立解锁动作。多副本同投一个空会话:唯一索引只放行一笔、另一笔 409。 - 出生即带租约:
INSERT同笔写lease_until = now() + lease(-lease-ttl,dev 30s)—— A7-2 的「出生窗口」在 DB 形态天然闭合(不存在「先建后补租约」两步)。 - watchdog 续约(只在生成期间;链路 = 抢闸成功 → 每
-lease-renew续一次 → endRun 前先停 watchdog,wg.Wait()保证续约全部退出):- PG 半是 CAS 本体:
UPDATE runs SET lease_until = now() + lease WHERE id=$run AND session_id=$s AND status='running' AND lease_until > now()——影响 0 行 = 本 run 判死、停止续约; - Redis 半:
tk:runlive/tk:runepoch两键 PEXPIRE 刷回 lease(PG 说活才刷)。 lease_until > now()那半是「过期不可复活」:A7 的 Redis CAS(闸键蒸发即 no-op)逐字同义。
- PG 半是 CAS 本体:
- 读侧即回收:
GET /api/sessions/{id}的liveRunId按status='running' AND lease_until > now()判活—— lease 已过的死行当场不再算活,不等清扫;清扫只为放行新 run(新 POST 时把死行翻error+finished_at+lease_until=NULL,唯一索引随之放行新 INSERT)。 - kill -9 全链:无人续约 → 两键 TTL 到期蒸发(frames
gone)→liveRunId因 lease 判空 → 再 POST 得 202 不是 409(死行被清扫翻error)。会话不再永久锁死;闸的「放」由终态UPDATE/ 租约判死两路达成,没有独立的解锁动作。
生命周期
- POST 事务(跨两存储;PG 事务持有跨 Redis 写):BEGIN → 懒建
sessions(首条消息截断写title) → 清扫死行 →INSERT runs('running'、出生即带lease_until)→INSERT run_model_messages(seq=1, role=user) →INSERT runlog_entries(seq=MAX+1, role=user)→ Redis 建tk:runlive压start帧 + 建tk:runepoch(出生值 1) (两键出生即带同租约)→ 全成才 COMMIT。Redis 写失败 → ROLLBACK → 500 零痕迹(与 409 同形「什么都不写」); 409 =runsINSERT 唯一冲突 → 整笔回滚零痕迹(runlog 永不删行,只靠不写来保零痕迹)。 - 生成中:每 delta →
tk:runliveRPUSH 一帧;写口先读tk:runepoch,和本执行者的 epoch 比对,缺失或不等就拒收(accepted=false)。watchdog 按上面的链路续约。 - run 结束(
endRun(sessionId, runId, status);watchdog 严格先停):同一笔 PG 事务「放闸 + 定稿」——UPDATE runs落终态(守卫status='running' AND lease_until > now();影响 0 行 = 空转、不 INSERT) 与 complete 的INSERT run_model_messages(seq=2, assistant,文本 = turn 里 root assistant 的累计pending[""])+INSERT runlog_entries(assistant)同事务——「model_history与闸同事务」就此是事务边界,不存在「闸已放、历史还没那行」的窗口。 commit 后 Redis 半:压terminal帧 +EXPIRE 300s(覆盖租约残值)+ 删runepoch;失败不补偿—— run 已定稿在权威(PG),runlive 到 TTL 走gone,客户端从 log 拿全文(B1 冗余收口兜住)。 error结局:放闸;「这一轮已产出的内容」照常落库(失败留痕,2026-10-22)——runlog 有已说出的 assistant 行与工具行、run_model_messages同样落这些行(缺结果的调用由 worker 侧配平补一条「没拿到结果」 的合成行,否则下一枪的 provider 会因 tool_calls 缺配对结果而 400)。「失败且无产出」那一档(还没说出 话就失败)仍是一行不写——与 2026-10-22 之前同形。stopped与error同待遇(都是「这一轮做了一半」)。 (模型上下文保留这次失败的尝试,重投时看得到)。- 进程死亡(
kill -9/ 崩溃):无人续约 →lease_until到点:① 读侧立即回收(liveRunId不再报活); ② 两键 TTL 蒸发(framesgone,客户端走 19v6-02 收口);③ 死行由下次 POST 的清扫翻error(形状 = error 结局:留 user 行、无 assistant 行;不翻也不影响读侧,清扫只为放行新 run)。 这场 run 不进历史;runlog/run_model_messages的既有行不受影响。
真源划分
runlog 记「产出了什么」(历史展示只读它);run_model_messages 记「模型现在该看到什么」(worker 组装输入的唯一来源,compact 压它、不动 runlog);runlive 是「正在生成的临时态」,TTL 到即清——清掉后那条回复的权威在 runlog,runlive 过期不影响历史正确性。 root 终稿 = turn 里 root assistant 文本的累计(pending[""]),EndRun 写入 runlog,不从 Redis 读正文。
- 历史展示(
GET /api/sessions/{id}/log)只读runlog_entries,按seq排; - 模型输入(worker)读
run_model_messages:WHERE session_id=$s AND compacted=false ORDER BY run_id, seq——单表、双列过滤、无 JOIN(run_id的 ULID 字典序即 run 时序)。 - 两表是同一对话的两个投影,别拿
run_model_messages组历史展示:compact 后展示会塌 (compacted 原文行 + seq=0 摘要行泄进聊天)、tool 观测会泄进界面。
「一条记录 / 一帧」= DB 的一行 row,不是文本的一行 line。
text里的\n原样保留,客户端按 markdown 渲染,排版不受影响。
多副本
全部状态在 PG 与 Redis 共享存储:客户端轮询打到任意副本从共享存储读;执行 run 的 worker 往 Redis 的 runlive 与 runepoch 写。 闸 = 部分唯一索引——跨副本天然成立;租约判定共用一个时钟(SQL now()),不依赖进程本地时间。 删掉 SSE 后不再有「持有长连接的副本 = 执行副本」的亲和问题。
reset(dev 端点)两半都清:PG TRUNCATE 四表 + Redis SCAN MATCH tk:* + UNLINK(返回 Redis 删除键数)。 runs 必须同清——它是闸的落点,漏清则幽灵 running 行永久残留(清扫只在新 POST 时按 session_id 触发, 旧 session 已 404,再没人替它扫)。