# 会话持久化 [English](persistence.md) | 中文 事件日志的**持久性 seam**。[session.md](session.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.md)中逐项列举。 该 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上定义 locate/create/append、可复用的 Session 准备流程、逻辑 load/inspect、物理后缀读取，以及轻量的 list/snapshot 观察——**没有平行的持久化事件类型**——以及两个实现同一约定的可互换后端。见 [session-persistence Agent Note](../../.agents/notes/implemented/architecture/2026-06-14-session-persistence.md)。 ## flush 检查点 `session/event` 是一个*同步*通知；持久化插件会将事件复制到逐会话控制器，而不阻塞生产方。第一个待处理事件会开启固定批处理窗口，后续事件会加入但不会重置截止时间。窗口到期后会启动一个持久化批次；该次写入期间接纳的事件会获得自己的截止时间，并形成后续批次。`session/flush` 会取消等待并排空至完全停稳，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。后台写入被拒绝时会保留对应事件并暂停自动重试；新事件会开启新的固定窗口，而显式 flush 会立即重试，并通过 `agent/error` 和 logger 报告失败，绝不会把失败记录成已关闭轮次之后的会话事件。dispose（资源释放）会执行同样的最终排空。配置的最大值只限制有意的批处理等待，不限制事件循环调度或后端完成持久化的延迟（[决策](../../.agents/notes/implemented/architecture/2026-08-08-bounded-session-persistence-write-batching.md)）。 ## 崩溃恢复保留被中断的轮次 后端重新加载一个在轮次中途崩溃的日志时，会发现一个已打开的 `turn/start` 却没有 `turn/end`。它**不会**截断日志：在长周期任务中，单个轮次可能非常庞大（许多步骤、大量工具输出），而这些事件在崩溃前已被持久追加。后端改为用一个合成的 `turn/end { reason: { kind: 'interrupted' } }` 关闭这个遗留轮次，在不改变其前后任何独立事件的情况下配平被中断的执行。`interrupted` 是唯一一个不由循环发出的 `TurnEndReason`（见 [session.md](session.md#why-a-turn-ended-turnendreasonmap)）。 修复仅适用于冷会话。对于活跃 id，`SessionPersistence.load(id)` 会等待权威内存快照完成持久化，并且只在日志平衡时返回；若活跃轮次仍未闭合，则拒绝操作，而不是添加合成的中断边界。HMR 会接管活跃前缀，而不会关闭其中正在进行的轮次。 `SessionPersistence.inspect(id)` 会构造一个不可变的逻辑 Session，但不发布它，也不写入恢复内容。冷检查会在内存中配平中断的轮次，同时保持撕裂的物理尾部不变；检查已经实时存在的 Session 则借用其当前不可变快照，因此可能包含打开的 turn。使用协调器的实现会在有界 LRU 中保留这个精确的冷未发布 Session，因此重复历史读取与后续 `prepare(id)` 可复用同一次读取、解压、验证、冻结及 Session 构造。`prepare(id)` 会预留该 Session、提交待处理修复并返回可 dispose 的发布句柄；`load(id)` 使用相同机制提交修复，但不会发布 Session。该生命周期由 [Session 准备阶段决策](../../.agents/notes/implemented/architecture/2026-08-05-session-preparation.md)定义。 ## `SessionLocation`——可选的逐会话产物目标 `SessionPersistence.locate(meta)` 会同步解析一个归后端所有的独立产物，而不会读取、创建或 flush 它。JSONL 返回其项目/会话目录内 transcript（文本记录）的绝对路径；SQLite 因各会话共享一个数据库而返回 `undefined`。因此，返回的路径可能指向尚不存在、或还不包含当前尚未 flush 的轮次；它是位置提示，不是授权或新鲜度保证。 ```ts type-equiv /** * A backend-resolved, per-session local artifact location. The path is an * absolute target path and can name an artifact that has not materialized yet. * Consumers must treat it as a location hint, never as an authorization token. */ interface SessionLocation { /** Backend-specific artifact kind, for example `jsonl`. */ readonly kind: string /** Absolute path to this session's backend-owned artifact. */ readonly path: string } ``` ## `SessionHeader`：日志旁的元数据 每个会话的元数据与事件日志**分开**存储：格式版本、cwd、血统与 seed 边界是存储层关注点而非对话事件，因此不进入 `SessionEventMap`，也不会到达 `deriveMessages()`。header 通过 `session.header` 附加到 `Session` 上。 源码：[`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts) ```ts type-equiv /** * Immutable validated storage metadata, kept outside the conversation event log. */ interface SessionHeader { /** * On-disk format version, stamped from {@link SESSION_FORMAT_VERSION} when the * session is created. A persistence backend rejects any other version on load * (no migration — see the constant). */ readonly version: number /** The session's id (mirrors the {@link Session}'s id). */ readonly id: SessionId /** Non-negative safe-integer Unix epoch milliseconds when the session was created. */ readonly createdAt: number /** Absolute working directory the session was created in (if any). */ readonly cwd?: string /** The session this one was forked from (seed lineage), if any. */ readonly parentSession?: SessionId /** * How many leading events were inherited through a seed. Persisting this * boundary lets resume and replay distinguish parent history from child work. */ readonly seedLength?: number /** * Coarse product classification for a session created as a subagent child. * This is presentation metadata, not proof that the child is continuable. */ readonly origin?: 'subagent' /** * Delegation depth: absent (zero) for a top-level session, parent depth + 1 * for a subagent child. Persisted so a recursion budget survives restart and * resume — a runtime-only depth would reset a resumed child to top-level. */ readonly delegationDepth?: number /** * Id of the agent preset this session's agent was composed from, when the * deployment composes per session. Durable because the preset decides the * session's tools and prompt: a resume that restored a different composition * would replay history the model can no longer act on. */ readonly agentPreset?: string } ``` ## 格式拒绝：本构建无法可靠读取的日志 后端用 `SessionFormatUnsupportedError` 拒绝无法可靠解读的日志，它与 `SessionPersistenceCorruptionError` 区分，因为数据没有损坏。header 的 `version` 比 `SESSION_FORMAT_VERSION` 新时，消息说明方向（"由更新的 harness 写入，请升级 harness 后打开"）；比它旧时说明本构建没有升级路径。经过 legacy 形状归一化后，本构建生成词汇表（`KNOWN_SESSION_EVENT_TYPES`，由 `gen-persistence-catalog` 生成）之外的事件类型同样被拒绝，除非该事件的信封带 `ignorable: true`：静默跳过一个不认识的必需事件可能改变日志其余部分的解读方式。后端为每个会话保留独立文件时，消息附上原始日志路径，被拒绝的文本仍然可读。JSONL 后端直接从原始 header 行拒绝外来版本，先于当前 header 形状校验和任何事件行解码，因此结构完全不同的未来格式仍会报告升级方向，绝不会报"损坏"；SQLite 则先由自己的 `SCHEMA_VERSION` pragma 把关整个文件的结构。设计理由与推迟建设的升级器链见 [session-log 版本机制 Agent Note](../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)。 ## `CreateSessionOptions`：seed 与元数据 通过 store 创建 `Session` 时会接收 `seed`（初始回放或 fork 历史）与 `meta`（store 折叠进 `SessionHeader` 的存储层字段）。store 填充 `version`/`id` 并为 `createdAt` 提供默认值；调用方可以提供已校验的绝对 `cwd`、`parentSession` 谱系、`seedLength` 种子边界、可选的粗粒度 `origin`、`delegationDepth`、该 agent 所依据组装的 `agentPreset` 以及已有的 `createdAt`。`origin: 'subagent'` 让产品导航能够隐藏重复的 child 行；它不证明描述符有效，也不证明 child 可以恢复。 ```ts type-equiv /** * Options for creating a {@link Session} via the store. `seed` replays/forks * an existing event log; `meta` carries the caller-supplied storage fields the * store folds into a {@link SessionHeader}. */ interface CreateSessionOptions { /** Initial replay or fork history supplied at construction. */ readonly seed?: readonly SessionEvent[] /** * Storage metadata read once before publication. `seedLength` is explicit * because a resumed seed contains the full stored log, not only its inherited prefix. */ readonly meta?: { readonly cwd?: string readonly parentSession?: SessionId readonly createdAt?: number readonly seedLength?: number readonly origin?: 'subagent' readonly delegationDepth?: number readonly agentPreset?: string } } ``` 因此，回放/fork 的调用方式为 `ctx.sessions.create(id, { seed: seedEvents })`；将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。 ## `SessionRawArtifact`——逐字存储工件文本 后端为单个会话自持的工件文本，与其持久化写入的字节逐字一致（按物理编码解码）。`readRaw` 返回它而不从解析后事件重建，因此后端特定的序列化（chunk 打包、键序、换行）得以保留；没有每会话工件的后端（如 SQLite）继承 `undefined` 默认。 ```ts type-equiv /** A backend's own raw artifact text for one session, verbatim. */ interface SessionRawArtifact { /** The session header parsed from the artifact's own first line. */ readonly meta: SessionHeader /** The artifact's base filename on disk, without any physical encoding suffix. */ readonly filename: string /** The artifact's full text content, decoded from the backend's physical encoding. */ readonly content: string } ``` ## 准备与恢复所有权 `SessionStore.prepare()` 接收普通创建选项，或通过 `RestoredSessionOptions` 转移所有权的新鲜持久化对象图。恢复分支会直接验证并冻结转移来的 header 与事件，因此调用方不得保留可变别名。`SessionPreparation` 随后持有该精确的未发布 Session，直至发布或回滚；dispose 是同步且幂等的。持久化检查只暴露 `SessionInspection`，即从同一个已准备 Session 借用的不可变逻辑视图。 ```ts type-equiv /** * Fresh storage values transferred to {@link SessionStore.prepare} without a * second serialization copy. Callers retain no mutable aliases. */ interface RestoredSessionOptions { /** Fresh detached storage events to validate and freeze in place. */ readonly seed: SessionEvent[] /** Fresh detached storage metadata to validate and freeze in place. */ readonly meta: SessionHeader /** Select the persistence ownership-transfer path. */ readonly seedSource: 'persistence' } ``` ```ts type-equiv /** Inputs accepted while constructing an unpublished Session. */ type PrepareSessionOptions = | (CreateSessionOptions & { readonly seedSource?: undefined }) | RestoredSessionOptions ``` ```ts type-equiv /** Options for a preparation whose provider retains unpublished state. */ interface SessionPreparationOptions { /** Release provider-owned state when the Session was not published. */ readonly release?: () => void } ``` ```ts public-api /** * One exact unpublished Session and the provider state that keeps it usable. * Disposal is synchronous and idempotent. Providers decide whether release * returns the Session to a cache or discards it; publication may consume that * state before disposal, making the callback a no-op. */ declare class SessionPreparation implements Disposable { /** The exact Session to use for setup and publication. */ readonly session: Session; /** * Wrap an unpublished Session in one preparation lifetime. * @param session - exact unpublished Session. * @param options - optional provider release behavior. * @returns a preparation disposed after publication or rollback. */ static create(session: Session, options?: SessionPreparationOptions): SessionPreparation; /** Release provider state once when this preparation leaves its caller. */ [Symbol.dispose](): void; } ``` ```ts type-equiv /** Immutable logical session prepared from persistence or a live owner. */ interface SessionInspection { /** Validated immutable session metadata. */ readonly meta: SessionHeader /** Validated contiguous logical event log. */ readonly events: readonly SessionEvent[] } ``` ## 轻量源修订号 派生状态的消费方会在加载完整事件日志之前比较一个低开销的不透明修订号。其表示由持久化后端拥有，并随 append 或会修改数据的 load 修复以事务方式改变；调用方仅比较修订号是否相等。 ```ts type-equiv /** * Backend-owned token that identifies both one storage source and one revision * of a persisted session log. */ type SessionPersistenceRevision = Branded<'SessionPersistenceRevision'> ``` ```ts type-equiv /** Lightweight immutable source identity returned without loading a full log. */ interface SessionPersistenceSnapshot { /** Detached metadata for one materialized session. */ header: SessionHeader /** Opaque source-qualified token that changes whenever this stored log changes. */ revision: SessionPersistenceRevision } ``` ## 后端 两者都实现同一个抽象 `SessionPersistence`（在 `SessionEvent` 上执行 locate/create/append/prepare/load/inspect/readFrom/list/listSnapshots，观察方法可选支持取消），并通过共享的 `runPersistenceContract` 套件： - **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——每个会话一份仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；支持崩溃安全的原子写入、被中断轮次的恢复以及读取/回放路径。 - **[dsh-session-persistence-sqlite](../../packages/session/session-persistence-sqlite)**：基于 `node:sqlite`，每个 `SessionEvent` 一行。行字段 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` 与事件 1:1 映射（包含可选的 surface 元数据），因此没有需要保持同步的并行持久化 schema。 ## Cordis API Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md). ### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam) Durable append-only session storage. Implementations preserve contiguous, losslessly JSON-serializable events; append resolves only after durability, and load balances a complete interrupted tail without rewriting committed events. ```ts cordis-catalog /** * Resolve this backend's independent local artifact for a session without * reading, creating, flushing, or otherwise materializing it. Backends such * as SQLite that do not own one artifact per session return `undefined`. * @param meta - the immutable session header whose artifact is requested. * @returns the backend-specific absolute location, when one exists. */ abstract locate(meta: SessionHeader): SessionLocation | undefined /** * Read a session's backend-owned artifact text verbatim — the exact durable * bytes the backend wrote (decoded from its physical encoding, e.g. a * decompressed JSONL). The returned `content` is the raw text, not a * reconstruction from parsed events, so it preserves backend-specific * serialization (chunk packing, key order, line breaks). Backends without a * per-session artifact (SQLite) inherit the `undefined` default. * @param _id - the persisted session to read (unused by the default: no * per-session artifact). * @param signal - optional cancellation for backend read work. * @returns the raw artifact plus its parsed header, or `undefined` when the * session is absent or the backend owns no per-session artifact. */ readRaw(_id: SessionId, signal?: AbortSignal): Promise /** * Register a new session's metadata. A backend MAY defer the physical write * until the first {@link append} (lazy materialization), in which case a * created-but-never-appended session is absent from {@link list} * — abandoned sessions leave nothing behind. * @param meta - the immutable header (id, version, cwd, lineage) to record. */ abstract create(meta: SessionHeader): Promise /** * Durably persist a batch of events. Honors the append-only and contiguous- * seq contracts: the first event's `seq` MUST equal the stored next-seq * (after `load` has durably closed any interrupted turn). Rejects non-JSON- * serializable `event.data` with an error naming the offending event type. * @param id - the session the batch belongs to. * @param events - the contiguous batch to persist, in seq order. */ abstract append(id: SessionId, events: readonly SessionEvent[]): Promise /** * Prepare the exact unpublished Session used by resume. Implementations may * reuse object graphs retained by an earlier {@link inspect} after confirming * their durable revision is still current; disposal releases an unpublished * reservation. Revision retries require the durable log to remain unchanged * for one read/check round trip; continuous external writers may delay completion. * @param id - persisted session to prepare. * @param signal - optional cancellation for preparation work. * @returns one owned unpublished Session preparation. */ async prepare(id: SessionId, signal?: AbortSignal): Promise /** * Load an immutable balanced logical view and commit any required cold * recovery. A complete interrupted final turn is preserved and durably * closed with missing tool errors plus any open step and turn boundaries; * only a torn final record is discarded. Unknown versions and corruption in * the committed prefix reject. Implementations MUST NOT crash-repair an * identity still bound to a live Session: a balanced live log may return as a * durable snapshot, while an open live turn rejects. Returned values may be * shared with immutable live or prepared state and must not be mutated. * Revision-based implementations may wait for one stable read/check round trip. * @param id - the persisted session to reload. * @returns the header and a log ending on a balanced `turn/end`. */ abstract load(id: SessionId): Promise /** * Inspect an immutable logical session without committing recovery or * publishing it. A cold complete interrupted turn receives synthetic closers * in memory and a torn physical tail remains untouched. An already-live * Session instead yields its current immutable snapshot, which may contain an * open turn and its `session/end-seed` boundary. Coordinator-backed * implementations retain the exact cold unpublished Session for bounded * reuse by a later {@link prepare}. A stale ready source is reloaded; a source * already committing or reserved for resume remains exclusive, and inspection * may borrow its immutable view. Callers borrow only the immutable header and * log. Continuous external writers may delay revision convergence. * @param id - the persisted session to inspect. * @param signal - optional cancellation for queued and backend read work. * @returns the validated header and current logical event log. */ abstract inspect(id: SessionId, signal?: AbortSignal): Promise /** * Read the stored events from `fromSeq` onward — the read-from-seq * primitive for read models that resume from a watermark (e.g. a persisted * projection cache folding only the tail past its checkpoint). Unlike * {@link inspect}, it is a detached physical suffix read: no preparation * cache, torn-tail truncation, synthetic closers, or coordinator-state * publication. Only events from the valid contiguous stored prefix are * returned, so a torn fragment never reaches the caller. `fromSeq` at or * beyond the stored prefix returns an empty event list (never an error). * Backends whose medium can seek by seq * (SQLite) read only the suffix; sequential media (JSONL, both encodings) * still parse the whole artifact and skip forward — the primitive bounds * what is RETURNED and refolded, not every backend's physical read. * @param id - the persisted session to read. * @param fromSeq - first event seq to include; a non-negative safe integer. * @param signal - optional cancellation for queued and backend read work. * @returns the header and the stored events with `seq >= fromSeq`. */ abstract readFrom(id: SessionId, fromSeq: number, signal?: AbortSignal): Promise<{ meta: SessionHeader; events: SessionEvent[] }> /** * Lightweight listing from metadata, without a full-log parse. * @param signal - optional cancellation for backend listing work. * @returns one header per materialized session. */ abstract list(signal?: AbortSignal): Promise /** * List materialized sessions with cheap per-log change tokens. * * Repeated observations of an unchanged log return the same revision. A * successful mutating {@link load} repair changes the next listed revision. * Revisions also distinguish independently backed stores so backend-local * counters cannot compare equal across different persistence sources. * @param signal - optional cancellation for backend snapshot-listing work. * @returns one header and opaque revision per materialized session without loading full logs. */ abstract listSnapshots(signal?: AbortSignal): Promise ``` Types: [SessionEvent](session.md) · [SessionId](core.md) Source: [`packages/session/session-persistence/src/index.ts:84`](../../packages/session/session-persistence/src/index.ts)