refactor(runtime): derive Session transcripts from RuntimeEvents

[Astro-Han]

The problem in one picture

Imagine recording the same conversation in two notebooks. While the conversation is happening, we read notebook A. As soon as it finishes, we switch to notebook B.

Even if both notebooks are meant to say the same thing, they are written separately. A crash, retry, or reconnect can catch them at different points.

That is the current transcript architecture:

flowchart LR
    subgraph Today["Today: one conversation, two ledgers"]
        direction TB
        Run1["Runtime execution"] --> Events1["RuntimeEvent"]
        Run1 --> Messages1["StoredMessage"]
        Events1 --> Active["Active transcript"]
        Messages1 --> Completed["Completed pages"]
    end

    subgraph Target["Target: one ledger, many views"]
        direction TB
        Run2["Runtime execution"] --> Events2["RuntimeEvent"]
        Events2 --> Projection["Bounded transcript projection"]
        Notes["UI notes"] --> Projection
        WorkHub["WorkHub facts"] --> Projection
        Projection --> View["StoredMessage view"]
    end

Loading

RuntimeEvent records what happened. StoredMessage describes how transcript data is presented. They should not both be durable authorities for the same ordinary execution fact.

What happens today

Ordinary runtime conversation facts are persisted through two paths:

• RuntimeEvent records the execution timeline.
• AiSdkTurn, ToolRuntime, and AgentRun also persist equivalent StoredMessage conversation records.

Those writes do not share one commit order. The read path then switches authority at the turn boundary:

• while a root turn is active, its transcript overlay is projected from RuntimeEvent;
• after the turn becomes terminal, completed pages are read from persisted StoredMessage records.

The same conversation can therefore be reconstructed from different durable representations before and after completion. Recovery, reconnect, pagination, and migration all depend on those representations remaining equivalent even when their writes settle in different orders.

The architectural rule

RuntimeEvent is the single durable semantic authority for ordinary Session execution facts.

Everything else has one clear role:

• Transcript pages are bounded read projections over the RuntimeEvent timeline. A page must not require loading the full Session.
• SessionEvent remains live transport for active clients; it is not a second storage authority.
• StoredMessage remains a presentation and protocol DTO. It is not being deleted; normal runtime execution simply stops persisting it as an equivalent second ledger.
• UI-only notes and WorkHub coordination keep their own legitimate semantic authorities. They are composed with the runtime projection at the transcript read boundary instead of being forced into RuntimeEvent.

What changes

1. Normal execution writes each ordinary user, assistant, tool, usage, and turn-state fact to the RuntimeEvent authority.
2. Active overlays and completed transcript pages use the same bounded projection over that authority.
3. The projection supplies stable item identities and paging cursors across terminalization, reconnect, and restart.
4. UI-only and WorkHub facts join the transcript at the read boundary.
5. Direct normal-runtime persistence of equivalent StoredMessage records is removed from AiSdkTurn, ToolRuntime, and AgentRun.

What does not change

• StoredMessage remains the client-facing presentation/protocol shape.
• SessionEvent remains the live transport shape.
• UI-only notes and WorkHub coordination keep their separate authorities.
• Provider model-history replay, compaction, and recap remain under refactor(runtime): establish model history boundaries #4779.
• This issue does not introduce byte-exact provider request replay.

Compatibility and cutover

• Supported imported Sessions must follow one forward path: migrate or backfill once, or fail at an explicit compatibility boundary.
• Unmarked 0.1.x data does not need to be supported.
• Any wire or paging semantic change updates the Runtime Host compatibility epoch.
• Transitional import, comparison, or repair code has one direction. Obsolete paths are removed after cutover rather than becoming permanent parallel authorities.

Acceptance criteria

• Active overlays and completed transcript pages derive ordinary execution facts from the same RuntimeEvent authority.
• Direct normal-runtime persistence of equivalent StoredMessage conversation records is removed.
• Paging remains bounded and item identities and cursors remain stable across turn completion, reconnect, and process restart.
• Recovery tests prove that supported transcript projections can be rebuilt from durable facts.
• Imported Session handling has an explicit one-way migration/backfill or rejection boundary.
• Transitional comparison and repair paths are removed after cutover.
• Wire or paging semantic changes update the Runtime Host compatibility epoch.

Why this is separate from #4779

#4779 establishes the provider-history boundary: what model history is replayed, compacted, and summarized for the next provider request.

This issue changes durable transcript storage and paging. It has different failure modes, compatibility concerns, and recovery tests. Folding it into #4779 would make two authority migrations share one review surface without making either safer.

Out of scope

• Provider model-history replay, compaction, or recap boundaries tracked by refactor(runtime): establish model history boundaries #4779.
• Byte-exact provider request capture or counterfactual replay tracked by fix(runtime): RuntimeEvent ledger is recovery-grade (WAL), not source-of-truth — write-path truncation blocks counterfactual replay #615.
• Removing StoredMessage as a presentation/protocol type.
• Moving WorkHub coordination facts or UI-only notes into RuntimeEvent.

[Astro-Han]

@zhiiw @likun666661 @xxhZs

[zhiiw]

English

A concrete implementation could keep the existing public StoredMessage shape while moving all ordinary execution semantics behind a single RuntimeEvent-backed transcript service.

Canonical write path

AiSdkTurn, ToolRuntime, and AgentRun should stop calling appendMessage / appendMessages for ordinary runtime conversation records. They should emit canonical RuntimeEvents through one store-owned commit boundary instead.

That boundary should validate the event, assign its immutable Session-level order, append it, and update any rebuildable lookup indexes in one storage transaction. A corresponding SessionEvent should only be published after the RuntimeEvent commit succeeds. If persistence fails, the fact must not be exposed as successfully accepted.

The same rule should cover terminalization. The terminal RuntimeEvent is the semantic terminal fact; the AgentRun terminal header is operational state and should either be committed with it or be repairable from it after a crash.

Stable order and item identity

Per-run eventSeq is not enough for Session transcript paging because one Session can contain multiple runs. The store therefore needs an immutable, monotonically increasing Session-level ordinal. The existing Session RuntimeEvent ordinal machinery can be used or extended for this purpose; timestamps should remain metadata rather than define canonical order.

Every RuntimeEvent that contributes to a visible transcript row also needs a stable semantic item key. Existing identities such as providerEventId, storedMessageId during import, tool-use ids, and turn ids should be normalized into that key. A new explicit reference is only needed for event shapes that do not already have an unambiguous identity. Reading must not invent a new id for canonical data.

All chunks or revisions of one active assistant item reuse the same key, so terminalization updates the same projected item rather than replacing it with a differently identified StoredMessage.

Bounded projection

RuntimeEventReadModel should expose an item-oriented, bounded read API rather than requiring all Session events:

readTranscriptPage({
  sessionId,
  throughOrdinal,
  direction,
  position,
  maxItems,
  maxBytes,
}): Promise<TranscriptProjectionPage>

The implementation first locates at most maxItems semantic item keys, then loads only the RuntimeEvents required to reduce those items into StoredMessage DTOs. A rebuildable index from Session ordinal to item key/event range can make this efficient, but it must contain no independent conversation semantics and must never be used as recovery authority. It should carry a projection version/high-water mark and be rebuildable entirely from RuntimeEvents.

The cursor should be based on the immutable snapshot watermark and item position, for example:

{
  version,
  sessionId,
  throughOrdinal,
  direction,
  sortOrdinal,
  itemKey,
  byteOffset,
}

Appending later events cannot renumber older items. Reconnect and restart may open a newer watermark, but previously projected item identities remain unchanged.

Active and completed transcripts

The active and completed paths should call the same item reducer. Opening a subscription can use the usual snapshot-plus-tail sequence:

1. capture RuntimeEvent high-water mark H;
2. start buffering committed events after H;
3. return pages projected from events through H;
4. deliver the buffered and subsequent updates as SessionEvents.

This removes the authority switch without requiring SessionEvent to become durable storage. The protocol may retain separate durable/overlay presentation concepts if useful, but both must be projections of RuntimeEvents rather than different ledgers. If their paging semantics change, the Runtime Host compatibility epoch must change with them.

Projection gaps should be explicit failures. Once a Session is marked as RuntimeEvent-backed, a hard projection diagnostic must not silently fall back to persisted StoredMessages.

Other transcript contributors

UI-only notes and WorkHub facts should stay in their own authorities. Each source can expose bounded contributions with a stable namespaced item id and ordering key. The transcript service captures a watermark for each source and performs a bounded merge at the read boundary. Nothing needs to be copied into RuntimeEvent solely for rendering.

Catalog previews, unread state, turn summaries, and search data may remain materialized projections for performance. They should record their projection version and RuntimeEvent high-water mark, be rebuildable, and never participate in recovery decisions.

Cutover

New Sessions should use the RuntimeEvent transcript authority from creation. A supported existing/imported Session should follow one staged path:

1. mark it as preparing;
2. translate supported StoredMessages to RuntimeEvents while preserving their item identities;
3. commit the events and rebuildable indexes;
4. project them back to StoredMessages and validate the supported visible facts;
5. atomically mark the Session as RuntimeEvent-backed;
6. stop consulting the legacy message ledger for that Session.

If a record cannot be translated safely, preparation should fail at that compatibility boundary instead of producing a mixed-authority Session.

After cutover, remove ordinary runtime message persistence from AiSdkTurn, ToolRuntime, and AgentRun. Any remaining StoredMessage writes must belong to a separately named non-runtime authority, not the normal execution path.

Recovery behavior to prove

The projection should be rebuilt and compared after process termination at least at these boundaries:

• after the user RuntimeEvent commit;
• during assistant streaming;
• after a tool call and before its result;
• after a tool result and before live publication;
• after the terminal RuntimeEvent and before the AgentRun header update;
• while paging from an older snapshot;
• during imported-Session preparation.

After reopening, item ids, order, visible content, turn state, and cursor continuation must be derived from the committed facts alone.

The storage contract should be the same on Linux, macOS, and Windows: the same SQLite transaction, uniqueness, ordering, and durable-commit guarantees, with no platform-specific StoredMessage or JSONL fallback.

The resulting ownership would be:

RuntimeEventStore    ordinary execution facts and canonical order
TranscriptProjector RuntimeEvent -> StoredMessage conversion
TranscriptService   bounded paging and multi-source composition
SessionEvent        live delivery only
StoredMessage       client-facing DTO only

---

中文版本

中文

一种具体的实现方式，是保留现有公开的 StoredMessage 数据结构，同时把所有普通执行语义统一放到一个由 RuntimeEvent 支撑的会话记录服务之后。

规范写入路径

AiSdkTurn、ToolRuntime 和 AgentRun 应停止为普通 Runtime 对话记录调用 appendMessage / appendMessages，改为通过一个由存储层拥有的提交边界写入规范 RuntimeEvent。

该边界应在同一个存储事务中完成事件校验、分配不可变的 Session 级顺序、追加事件，以及更新所有可重建的查询索引。只有 RuntimeEvent 提交成功后，才能发布对应的 SessionEvent。如果持久化失败，就不能对外表示该事实已被成功接受。

终止过程也应遵循同一规则。终止 RuntimeEvent 是具有语义权威的终止事实；AgentRun 的终止 Header 属于运行状态，应与终止事件一同提交，或者能够在崩溃后根据终止事件修复。

稳定顺序与条目身份

单个 Run 内的 eventSeq 不足以支持 Session 会话分页，因为一个 Session 可能包含多个 Run。因此，存储层需要维护一个不可变、单调递增的 Session 级序号。可以使用或扩展现有的 Session RuntimeEvent ordinal 机制；时间戳只应作为元数据，不能定义规范顺序。

每个会生成可见会话记录的 RuntimeEvent，还需要一个稳定的语义条目键。现有的 providerEventId、导入时的 storedMessageId、工具调用 ID 和 Turn ID 等身份，应统一映射为这个条目键。只有无法从现有字段获得无歧义身份的事件类型，才需要新增明确的引用字段。规范数据的读取过程不能临时创造新的 ID。

同一个活跃助手条目的所有分片或修订都复用相同的键。因此，Turn 终止时更新的是同一个投影条目，而不是用另一个具有不同身份的 StoredMessage 替换它。

有界投影

RuntimeEventReadModel 应提供以条目为单位的有界读取接口，而不是要求读取一个 Session 的全部事件：

readTranscriptPage({
  sessionId,
  throughOrdinal,
  direction,
  position,
  maxItems,
  maxBytes,
}): Promise<TranscriptProjectionPage>

实现首先定位不超过 maxItems 个语义条目键，然后只加载把这些条目归约为 StoredMessage DTO 所必需的 RuntimeEvents。可以通过一个从 Session ordinal 映射到条目键和事件范围的可重建索引提高效率，但该索引不能保存独立的对话语义，也不能成为恢复权威。它应记录投影版本和高水位，并能完全从 RuntimeEvents 重建。

游标应基于不可变的快照高水位和条目位置，例如：

{
  version,
  sessionId,
  throughOrdinal,
  direction,
  sortOrdinal,
  itemKey,
  byteOffset,
}

后续追加的事件不能重新编号已有条目。重新连接或重启时可以打开更新的高水位，但之前投影出的条目身份必须保持不变。

活跃与已完成会话记录

活跃路径和完成路径应调用同一个条目归约器。建立订阅时可以采用“快照加后续事件”的流程：

1. 获取 RuntimeEvent 高水位 H；
2. 开始缓存 H 之后提交的事件；
3. 返回由截至 H 的事件投影得到的分页；
4. 通过 SessionEvent 发送缓存的事件和后续更新。

这样可以消除权威来源切换，同时不要求 SessionEvent 成为持久化存储。如果有展示需要，协议仍可以保留 durable/overlay 两个概念，但二者必须都是 RuntimeEvents 的投影，不能代表两本不同的账。如果分页语义发生变化，Runtime Host compatibility epoch 也必须同步更新。

投影缺口必须表现为明确失败。一旦 Session 被标记为由 RuntimeEvent 支撑，严重的投影诊断就不能静默回退到持久化的 StoredMessages。

其他会话数据来源

仅供 UI 使用的备注和 WorkHub 事实应继续保留各自的权威来源。每种来源可以通过稳定、带命名空间的条目 ID 和排序键提供有界的数据贡献。会话服务为每个来源记录高水位，并在读取边界执行有界合并。不需要仅为渲染目的把这些事实复制到 RuntimeEvent。

为提高查询性能，目录预览、未读状态、Turn 摘要和搜索数据可以继续作为物化投影存在。它们应记录投影版本和 RuntimeEvent 高水位，能够被重建，并且不能参与恢复决策。

正式切换

新建 Session 从创建开始就应使用 RuntimeEvent 会话权威。受支持的已有或导入 Session 应只经过一条分阶段路径：

1. 将 Session 标记为 preparing；
2. 在保留条目身份的情况下，把受支持的 StoredMessages 转换成 RuntimeEvents；
3. 提交生成的事件和可重建索引；
4. 将事件重新投影为 StoredMessages，并验证受支持的可见事实；
5. 原子地把 Session 标记为由 RuntimeEvent 支撑；
6. 此后不再为该 Session 查询旧消息账本。

如果某条记录无法被安全转换，准备过程应在兼容性边界明确失败，而不能生成一个同时使用两套权威来源的 Session。

切换完成后，应删除 AiSdkTurn、ToolRuntime 和 AgentRun 对普通 Runtime 消息的持久化。任何剩余的 StoredMessage 写入都必须属于一个具有独立名称的非 Runtime 权威来源，而不是普通执行路径。

需要证明的恢复行为

至少应在以下边界终止进程，然后重建并比较投影：

• 用户 RuntimeEvent 提交后；
• 助手流式输出过程中；
• 工具调用产生后、结果产生前；
• 工具结果提交后、实时事件发布前；
• 终止 RuntimeEvent 提交后、AgentRun Header 更新前；
• 正在从旧快照分页时；
• 导入 Session 的准备过程中。

重新打开后，条目 ID、顺序、可见内容、Turn 状态和游标续读位置，都必须只由已经提交的事实推导出来。

Linux、macOS 和 Windows 应遵循相同的存储契约：使用相同的 SQLite 事务、唯一性约束、排序和持久化提交保证，不提供特定平台的 StoredMessage 或 JSONL 回退路径。

最终的职责划分为：

RuntimeEventStore    负责普通执行事实和规范顺序
TranscriptProjector  负责 RuntimeEvent -> StoredMessage 转换
TranscriptService    负责有界分页和多来源组合
SessionEvent         只负责实时传输
StoredMessage        只作为面向客户端的 DTO