Bounded session persistence write batching
为会话持久化写入批处理设定上界
One agent step can emit several durable events in a short interval: request metadata, one Assistant settlement, tool lifecycles, plugin facts, and execution boundaries. Scheduling a provider append as soon as an idle queue receives one event can therefore produce many small durable appends. Each JSONL append creates and syncs a Zstandard frame or raw suffix. Assistant stream embedding reduces one high-volume event fa
English
Problem
One agent step can emit several durable events in a short interval: request metadata, one Assistant settlement, tool lifecycles, plugin facts, and execution boundaries. Scheduling a provider append as soon as an idle queue receives one event can therefore produce many small durable appends. Each JSONL append creates and syncs a Zstandard frame or raw suffix.
Assistant stream embedding reduces one high-volume event family, but write cadence remains a provider-neutral lifecycle concern for every other burst and for historical generations. The batching decision does not change event semantics or storage encoding.
Quantified baseline
Released-v1 repository fixtures established the original logical volume. Decoding the packed goal-multi-turn-actions generation yielded 2,098 events, including 2,017 chunks (96.1%); unpacked chunk lines occupied 332,647 of 379,225 event bytes, while the packed file used 89,176 bytes and 182 rows. The packed permission-policy-context generation yielded 813 events, including 746 chunks (91.8%); unpacked chunk lines occupied 118,935 of 184,821 event bytes, while the packed file used 84,917 bytes and 123 rows. These deterministic historical measurements explain why v2 embeds streams, but they are not a production workload distribution or a current-format size claim.
JSONL writes one Zstandard frame and fsync per durable append batch. Runtime files do not record former append boundaries, so fixture row counts cannot honestly be presented as fsync counts.
The scheduling bound is deterministic. With an immediately resolving sink, the former immediate controller could issue one append for each event arriving after the previous append completed. A controller test admits 20 events 10 ms apart: the 200 ms fixed window hands all 20 to one append. This is a 20-to-1 reduction for that cadence, not a universal ratio. Sparse events, mandatory flushes, slow prior writes, and different arrival rates produce different batch sizes.
Decision
The fixed window is the JSONL provider's constant LIVE_WRITE_BATCH_MAX_DELAY_MS (200 ms), an internal scheduling policy rather than configuration: the backend's own session listeners route live events by id into the active write handle's buffer, so batching never crosses the package boundary (handle note).
Each active write handle owns its buffer directly. A routed event lands in the handle's pending array, and the first event of an idle buffer arms one fixed timer. Later events join that batch without resetting the deadline: this is bounded coalescing, not debounce. When the deadline expires, a single-flight drain persists the pending prefix through the handle's mutation chain, which already serializes it against explicit appends. Events admitted during a drain pass coalesce into the next chained batch, in order.
The window bounds only the controller's intentional batching wait. Event-loop scheduling, initialization, an earlier serialized operation, and backend I/O can delay durable completion, so the option is not a hard fsync or crash-loss SLA.
session/flush cancels any remaining wait and becomes a shared quiescence barrier. It drains the active attempt and every event admitted while the barrier is running before it resolves. Session retirement (session/disposed), the handle's close, and backend teardown's close sweep use that same barrier, so lifecycle teardown never waits for the batching timer. The checkpoint policy continues to place mandatory barriers before model requests and top-level tool side effects.
Every admitted event remains durable in its original order and representation. The controller copies each event on admission; batching removes or rewrites no sequence, timestamp, surface metadata, embedded Assistant stream, or storage record. JSONL can therefore encode more events in one append frame without changing the Session format.
A failed background drain retains its complete batch in order ahead of newer pending events, reports the failure once, and pauses the automatic timer. The next explicit drain — a session/flush barrier, service-level flush(), or close — retries immediately and surfaces a repeated failure to its caller. This avoids a timer-driven failure loop while preserving the existing recoverable flush boundary.
This decision supersedes only the immediate scheduling cadence in Collapse live persistence into one flush controller. That note remains authoritative for one buffer owner per live Session, retained failed batches, retirement, and quiescent disposal. The coordinator and the separate write-behind controller that first hosted this behavior are deleted; the buffer, timer, and drain live on the provider's handle, and the handle-based seam owns the storage boundary they write through.
Alternatives considered
Use one settlement per Assistant attempt instead of batching writes. The v2 Assistant stream decision provides that no-information-loss event model and reduces Assistant event cardinality. It does not replace bounded batching for other adjacent events, historical-generation publication, or providers with the same append interface.
Write only at semantic checkpoints. Rejected: it maximizes batching but makes the ordinary crash-loss window depend on a separately mounted policy. Bounded background writes preserve progress between checkpoints while mandatory flushes keep their stronger ordering contract.
Debounce from the latest event. Rejected: a continuously streaming response could postpone its first write indefinitely. A fixed window from the first pending event provides a real upper bound on intentional coalescing wait.
A shared provider-neutral controller component. Rejected after one iteration shipped it: the handle's mutation chain already serializes writes, so a separate controller duplicated that ordering machinery. Each provider implements the buffer on its own handle, and the shared live-write contract suite pins the equivalent observable behavior for any provider.
Verification
The shared live-write contract suite (runLiveWritePathContract) uses a fake clock to prove the fixed, non-resetting 200 ms window; the session/flush barrier and its loud failure surfacing; ordered failure retention with exactly-once recovery; the service-level flush() sweep with per-session failure aggregation; and the disposed/close/teardown drains. The JSONL suite retains its storage-format, recovery, and shared persistence-contract coverage.
Consequences
High-frequency event bursts normally produce fewer durable append operations while preserving the exact admitted event sequence. The reduction depends on arrival rate and backend latency: a burst inside one 200 ms window becomes one batch, while mandatory flushes and sparse events can still produce small batches.
This decision does not cap pending event count or bytes behind a slow provider, and it does not reduce the decoded logical log. A demonstrated memory bound or logical-retention policy would require its own failure and replay contract rather than another hidden timer rule.
An admitted event can remain only in memory during the fixed window, and then while scheduling or backend work is outstanding. Explicit durability boundaries remain unchanged and bypass the wait.
The handle gives the timer, active drain, pending prefix, retry pause, and barrier one owner; the backend's listeners own routing and lifecycle-driven drains. Batching itself never changes SESSION_FORMAT_VERSION.
中文
问题
一个 agent 步骤可以在短时间内发出多个持久事件：请求元数据、一个 Assistant settlement、工具生命周期、插件事实与执行边界。只要空闲队列收到一个事件就立即调度 provider 追加，仍可能产生大量小规模的持久化追加。每次 JSONL 追加都会创建并同步一个 Zstandard 帧或原始格式后缀。
Assistant stream 嵌入会减少一个高频事件 family，但对于其他事件突发与历史 generation，写入节奏仍是 provider-neutral 生命周期问题。批处理决策不会改变事件语义或存储编码。
量化基线
已发布 v1 仓库 fixture 建立了原始逻辑数据量。解码 packed goal-multi-turn-actions generation 得到 2,098 个事件，其中 2,017 个是 chunk（96.1%）；解包的 chunk 行占 379,225 个事件字节中的 332,647 字节，而 packed 文件使用 89,176 字节与 182 行。packed permission-policy-context generation 得到 813 个事件，其中 746 个是 chunk（91.8%）；解包的 chunk 行占 184,821 个事件字节中的 118,935 字节，而 packed 文件使用 84,917 字节与 123 行。这些确定性历史测量解释了 v2 为何嵌入 stream，但不代表生产工作负载分布或当前格式大小。
JSONL 每个持久化追加批次会写入一个 Zstandard 帧并执行一次 fsync。运行时文件不记录原有追加边界，因此不能把 fixture 的存储行数当作 fsync 次数。
调度上界是确定的。当写入端会立即完成每次操作时，原来的即时控制器可能对每个在前一次追加完成后到达的事件分别发起一次追加。一个控制器测试以 10 ms 的间隔接纳 20 个事件：200 ms 固定窗口会把全部 20 个事件交给一次追加。对于这种到达节奏，追加次数从 20 次降至 1 次，但这不是普遍比例。稀疏事件、强制 flush、较慢的前序写入和不同到达速率都会产生不同的批次大小。
决策
固定窗口是 JSONL provider 的常量 LIVE_WRITE_BATCH_MAX_DELAY_MS（200 ms），它是内部调度策略而非配置：后端自己的会话监听器按 id 把实时事件路由进活跃写句柄的缓冲，因此批处理绝不跨越包边界（句柄 Note）。
每个活跃写句柄直接拥有自己的缓冲。被路由的事件落入句柄的待处理数组，空闲缓冲收到的第一个事件会启动一个固定计时器。后续事件加入该批次但不会重置截止时间：这属于有界合并，而不是防抖。截止时间到达后，一次 single-flight 排空会把待处理前缀经由句柄的修改链持久化，该链本就将其与显式 append 串行化。排空进行期间接纳的事件会按顺序合并进下一个链上的批次。
该窗口只限制控制器为批处理而主动等待的时间。事件循环调度、初始化、此前的串行化操作和后端 I/O 都可能延后持久化完成时间，因此该选项并不对 fsync 完成时间或崩溃数据丢失提供硬性 SLA。
session/flush 会取消剩余等待，并充当共享的完全停稳屏障。它会在完成前等待活跃写入尝试，并排空屏障运行期间接纳的每个事件。会话退役（session/disposed）、句柄的 close 与后端 teardown 的关闭清扫共用该屏障，因此生命周期 teardown 绝不会等待批处理计时器。检查点策略仍会在模型请求与顶层工具副作用之前设置强制屏障。
每个已接纳事件仍会按原有顺序和表示持久化。控制器会在接纳时复制每个事件；批处理不会删除或改写任何序号、时间戳、surface 元数据、嵌入式 Assistant stream 或存储记录。因此，JSONL 可以在一个追加 frame 中编码更多事件，而无需改变 Session 格式。
后台排空失败后，其完整批次会按顺序保留在所有较新的待处理事件之前，该失败被报告一次，自动计时器随之暂停。下一次显式排空——session/flush 屏障、服务级 flush() 或 close——会立即重试，如果故障再次发生，则会向调用方暴露该故障。这可以避免计时器驱动的失败循环，同时保留现有可恢复的 flush 边界。
本决策仅取代将实时持久化归并到单个刷新控制器中的即时调度节奏。对于每个活跃会话使用一个缓冲所有者、保留失败批次、退役和完全停稳的 dispose，原 Agent Note 仍是权威记录。最初承载该行为的协调器与独立的 write-behind 控制器均已删除；缓冲、计时器和排空落在 provider 的句柄上，它们写入所经过的存储边界由基于句柄的 seam 定义。
备选方案
使用每个 Assistant attempt 一个 settlement 代替批处理写入。 v2 Assistant stream 决策提供该无信息损失事件模型，并减少 Assistant 事件基数。它不能替代其他相邻事件、历史 generation 发布或使用同一 append 接口的 provider 所需的有界批处理。
仅在语义检查点写入。 不采纳：此方案会最大化批处理，却让普通的崩溃丢失窗口取决于另行挂载的策略。有界后台写入会在检查点之间持久化进度，而强制 flush 继续提供更强的顺序约定。
按最新事件重置防抖窗口。 不采纳：持续不断的流式响应可能无限期推迟首次写入。由第一个待处理事件启动的固定窗口，为主动合并等待提供了真正的上界。
共享的 provider 无关控制器组件。 曾在一次迭代中交付，随后不采纳：句柄的修改链本就串行化写入，独立控制器重复了这套排序机制。每个 provider 在自己的句柄上实现该缓冲，共享的实时写入约定测试套件为任何 provider 钉住等价的可观察行为。
验证
共享的实时写入约定测试套件（runLiveWritePathContract）使用假时钟证明固定且不会重置的 200 ms 窗口、session/flush 屏障及其失败的响亮暴露、有序保留失败批次并恰好恢复一次、带逐会话失败聚合的服务级 flush() 清扫，以及 disposed/close/teardown 的排空。JSONL 测试套件继续覆盖存储格式、恢复和共享持久化约定。
后果
高频事件突发通常会减少持久化追加操作，同时保持已接纳事件序列完全不变。减少幅度取决于事件到达速率和后端延迟：位于同一 200 ms 窗口内的突发事件会成为一个批次，而强制 flush 与稀疏事件仍可能产生小批次。
本决策不会限制因 provider 缓慢而积压的待处理事件数量或字节数，也不会减少解码后的逻辑日志。若要建立经过验证的内存上界或逻辑保留策略，就必须为其另行定义失败与回放约定，而不是再引入一条隐式计时器规则。
接纳后的事件在固定窗口内可能只存在于内存中，此后在等待调度或后端工作完成期间也可能如此。显式持久性边界保持不变，并会绕过等待。
句柄统一负责计时器、活跃排空、待处理前缀、重试暂停和屏障；后端的监听器负责路由和生命周期驱动的排空。批处理本身绝不改变 SESSION_FORMAT_VERSION。