dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/subsystems/persistence.zh.md

@@ -1,418 +0,0 @@
-# 会话持久化
-
-[English](persistence.md) | 中文
-
-事件日志的**持久性 seam**。[session.md](session.zh.md) 描述了内存中的 `Session`：仅追加的 `SessionEvent` 日志即为真源。本页描述如何使该日志持久化：抽象的 `SessionPersistence` 服务、它的提供方模型与随产品交付的 JSONL 后端、flush 检查点、崩溃恢复，以及随日志一同存储的元数据头。日志承载的事件词汇在生成的[持久化日志事件目录](../persistence-catalog.zh.md)中逐项列举。
-
-该 seam 是一个[能力 seam](../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.zh.md)：一个抽象服务（[dsh-session-persistence](../../packages/session/session-persistence)，`ctx.sessionPersistence`）在现有 `SessionEvent` 上暴露 `create`/`open`/`stat`/`list`——**没有平行的持久化事件类型**——其中 `create` 与 `open` 返回逐会话的 `SessionHandle`（`read`/`append`/`flush`/`close`），它承载全部日志访问与单写者所有权。仓库随产品交付 [dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl) 作为其 provider；仓库外 provider 可以实现同一服务约定。见[基于句柄的持久化 Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)与 [session-persistence reference](../../packages/session/session-persistence/README.zh.md)。
-
-## `SessionHandle`——通向已存储会话的一条打开通道
-
-每一次日志读写都经由句柄流动，绝不经由按 id 寻址的服务方法：句柄是跨进程写租约把守的唯一入口。读取会返回调用方独占的外层 slice，以及由生产者建立的 event value 别名状态。一种句柄类型同时服务两种访问——在 `read` 句柄上执行修改是运行时的 `SessionReadOnlyError`，而非类型层面的拆分——而进程内单写者所有权使得在已有活跃持有者时第二次 `open(id, 'write')` 以 `SessionAlreadyOwnedError` 拒绝。
-
-```ts type-equiv
-/** One persistence event slice returned by {@link SessionHandle.read}. */
-interface SessionHandleReadResult {
-  /**
-   * Whether event values are exclusively owned or shared only after deep
-   * freezing. Slicing preserves the producer's state even when no events remain.
-   */
-  readonly eventState: SessionSeedEventState
-  /** Event values in a caller-owned outer array. */
-  readonly events: readonly SessionEvent[]
-}
-```
-
-```ts type-equiv
-/**
- * One open channel onto a stored session. A handle is single-owner state, not
- * a shared service: `read` never backtracks below what this handle already
- * observed, a `write` handle reads its own successful appends, and `close()`
- * is the one teardown (idempotent, uncancellable; `Symbol.asyncDispose`
- * delegates to it). Every operation on a closed handle rejects with
- * `SessionHandleClosedError`.
- *
- * Freshness across handles: once an `append` or `flush` resolves on a write
- * handle, every read STARTED afterwards on the same backend instance — on any
- * handle, or through `stat`/`list` — observes at least that prefix.
- * Reads concurrent with a mutation carry no ordering promise beyond the valid
- * contiguous prefix.
- */
-interface SessionHandle extends AsyncDisposable {
-  /** The stored session this handle addresses. */
-  readonly id: SessionId
-  /** The immutable stored header, fixed at `create`/`open`. */
-  readonly header: SessionHeader
-  /**
-   * Exact fork-inherited prefix length stored with the log; `0` when
-   * `header.isSeeded` is false. Storage metadata paired with the header for
-   * every body read, never part of the replayable event log.
-   */
-  readonly inheritedEventCount: SessionLogOffset
-  /** Whether this handle may mutate the log. */
-  readonly access: SessionAccess
-
-  /**
-   * Read a slice of the valid contiguous logical log. The slice is a legal log
-   * prefix segment: a torn physical tail is never returned, and repeated reads
-   * on this handle never observe an older state than a prior read.
-   * @param offset - first logical event seq to include; defaults to `0`.
-   * @param length - maximum number of events to return; defaults to the rest
-   *   of the log. An offset at or past the end returns an empty list.
-   * @param options - optional cancellation.
-   * @returns the caller-owned outer slice plus the ownership state of its event values.
-   */
-  read(offset?: number, length?: number, options?: SessionHandleReadOptions): Promise<SessionHandleReadResult>
-
-  /**
-   * Append a contiguous batch continuing the current logical end. The first
-   * event's `seq` MUST equal the stored next-seq; committed events are never
-   * rewritten. Persistence is best-effort: on resolution the batch is
-   * accepted, ordered, and visible to reads on this backend instance, but
-   * only a resolved {@link flush} promises it survives a crash — a backend
-   * may buffer or batch physical writes behind append. Rejects with
-   * `SessionReadOnlyError` on a read handle and `SessionOwnershipLostError`
-   * when write ownership is gone.
-   * @param events - the contiguous batch, in seq order.
-   * @param options - optional cancellation observed before the write starts.
-   */
-  append(events: readonly SessionEvent[], options?: SessionHandleAppendOptions): Promise<void>
-
-  /**
-   * The durability barrier — the one operation that promises storage: on
-   * resolution every acknowledged append is durable and the session is
-   * materialized for other processes; an empty created session becomes
-   * durably listable here. Callers that must survive a crash flush; a backend
-   * whose `append` already persists on resolution treats this as
-   * materialize-if-needed. Rejects with `SessionReadOnlyError` on a read
-   * handle.
-   * @param options - optional cancellation observed before the barrier starts.
-   */
-  flush(options?: SessionHandleFlushOptions): Promise<void>
-
-  /**
-   * Release the handle: a read handle frees local resources; a write handle
-   * completes pending durability and releases write ownership. Idempotent,
-   * asynchronous, and deliberately not cancellable.
-   */
-  close(): Promise<void>
-}
-```
-
-已创建的会话自 `create` 完成之刻起即可在本进程内被观察到，而后端可以把物理实体化（纯粹的优化）推迟到第一次 `append` 或 `flush`；其他进程只能看到已实体化的会话，一个在崩溃前从未实体化的会话等于从未存在。
-
-## flush 检查点
-
-`session/event` 是一个*同步*通知；挂载的后端按会话 id 把它路由进活跃写句柄的有界 write-behind 窗口，而不阻塞生产方（后端一次性安装这些监听器，因为持久化已保证每个 id 只有一个活跃写句柄）。第一个待处理事件会开启固定的内部批处理窗口，后续事件会加入但不会重置其截止时间。窗口到期后会通过该会话的写句柄启动一次持久化 `append`；该次写入期间接纳的事件会获得自己的截止时间，并形成后续批次。`session/flush` 会取消等待并排空至完全停稳，因此循环仍将其用作在领取下一个普通轮次之前的顺序与错误观察检查点。后台写入被拒绝时会按序保留对应事件、暂停自动路径，并通过 logger 报告；下一次显式 flush 会重试，并向其调用方响亮地拒绝。`session/disposed` 会执行同样的最终排空并关闭句柄，而 `close()` 本身会经由仍然打开的存储排空已路由的缓冲，因此后端 teardown 的关闭清扫不丢任何数据。该窗口只限制有意的批处理等待，不限制事件循环调度或后端完成持久化的延迟。
-
-## 崩溃恢复保留被中断的轮次
-
-一个在轮次中途崩溃的日志以打开的 `turn/start` 而无 `turn/end` 结束。持久化**不会**截断或修复它：在长周期任务中，单个轮次可能非常庞大（许多步骤、大量工具输出），而这些事件在崩溃前已被持久追加。它返回物理上有效的连续日志；只有撕裂物理尾部——属于一次从未完成的 append——中不完整的碎片会被丢弃：从中恢复的完整记录（JSONL 后端会部分解码撕裂的 Zstandard 帧）由写路径在句柄的第一次新 append 之前持久重写。修复是读方的职责：resume（agent-loop）通过其写句柄读取已存储的日志，计算 `interruptedTurnClosers`——缺失的工具错误、任何未闭合的 `step/end`，以及一个合成的 `turn/end { reason: { kind: 'interrupted' } }`——并在发布 Session 之前把它们作为普通批次通过同一句柄追加。`interrupted` 是唯一一个不由循环发出的 `TurnEndReason`（见 [session.md](session.zh.md#why-a-turn-ended-turnendreasonmap)）。
-
-因此修复只在写所有权之下写入：活跃会话的写句柄由其生命周期所有者持有，故并发的 `open(id, 'write')` 会以 `SessionAlreadyOwnedError` 拒绝，而不是让修复与活跃轮次竞速。只读观察方（session-query）仅在内存中用同样的闭合事件配平被中断的冷日志，不回写任何内容。
-
-只读观察即 `open(id, 'read')`：句柄提供经过验证的连续前缀切片，绝不返回撕裂尾部，且同一句柄上的重复读取绝不会观察到比先前读取更旧的状态。持久化侧不存在已准备 Session 缓存：session-query 拥有自己的冷读缓存，按 `stat().revision` 变更令牌为每个 id 缓存一个已配平的冷 Session，仅在令牌变化时重新读取。该生命周期由[基于句柄的持久化 Agent Note](../../.agents/notes/implemented/architecture/2026-08-27-handle-based-session-persistence.zh.md)定义；已归档的 [Session 准备阶段记录](../../.agents/notes/archived/architecture/2026-08-05-session-preparation.md)记载了发布边界 `SessionPreparation` 最初的决策。
-
-## `SessionLocation`——拒绝诊断的产物目标
-
-`SessionLocation` 不是面向消费者的查询：日志访问走会话句柄的 `read`。它仅作为拒绝诊断存在，使 `SessionFormatUnsupportedError` 能指出本构建拒绝解读的原始日志。JSONL 提供其项目/会话目录内 transcript（文本记录）的绝对路径；没有逐会话工件的后端则不提供。
-
-```ts type-equiv
-/**
- * A backend-resolved, per-session local artifact location. Carried only by
- * refusal diagnostics ({@link SessionFormatUnsupportedError}) so a user can
- * find the raw log a build refused to interpret; it is not a consumer-facing
- * query — log access goes through a session handle's `read`.
- */
-interface SessionLocation {
-  /** Backend-specific artifact kind, for example `jsonl`. */
-  readonly kind: string
-  /** Absolute path to this session's backend-owned artifact. */
-  readonly path: string
-}
-```
-
-<a id="sessionheader--metadata-beside-the-log"></a>
-
-## `SessionHeader`：日志旁的元数据
-
-每个会话的元数据与事件日志**分开**存储：header 携带格式版本、cwd 与 `isSeeded` 谱系 bit，含正文的存储值则在其旁边单独携带精确 inherited cut。二者都不进入 `SessionEventMap`，也不会到达 `deriveMessages()`。logical header 通过 `session.header` 附加，Session 则以 `inheritedEventCount` 暴露其 cut。
-
-源码：[`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 {
-  /**
-   * Current logical format version, stamped from {@link SESSION_FORMAT_VERSION}.
-   * Historical physical headers are translated before entering this interface.
-   */
-  readonly version: typeof SESSION_FORMAT_VERSION
-  /** 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
-  /**
-   * Whether this Session contains a fork-inherited event prefix. The exact prefix
-   * length is Session state rather than ordinary header metadata.
-   */
-  readonly isSeeded: boolean
-  /**
-   * 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` 区分，因为数据没有损坏。`stat` 与 `list` 会对最高规范 generation 分类，并在不读取或改变正文的前提下转换受支持的历史 header。历史 `open` 会共享每个 Session 唯一的一次 migration preparation，再返回当前逻辑值，并保持每个源路径、字节与 inode 不变。JSONL provider 直接从该内存结果返回读句柄而不发布；写 open 则在持有单写者 claim 与文件 lease 时复用 preparation、排他发布最终 current generation，随后才返回可写句柄。即使仍有较旧的可读 generation，最高的未来 generation 仍会导致拒绝。当前格式恢复会保留已安装扩展和带 `ignorable: true` 的未知事件；历史 v0/v1/v2 迁移则会拒绝未知类型，即使它带有 ignorable 标记。后端为每个会话保留独立文件时，消息附上选定的原始日志路径。仓库外后端必须在自己的物理格式入口提供等价的仅当前句柄值与方向感知拒绝。[已发布格式迁移决策](../../.agents/notes/implemented/architecture/2026-08-31-released-session-format-migrations.zh.md)负责迁移链与不可变发布规则。
-
-## `CreateSessionOptions`：seed 与元数据
-
-通过 store 创建 `Session` 时会接收 `seed`（初始回放或 fork 历史）、可选的精确 `inheritedEventCount` 与 `meta`（store 整合进 `SessionHeader` 的存储层字段）。store 填充 `version`/`id` 并为 `createdAt` 提供默认值；调用方可以提供已校验的绝对 `cwd`、`parentSession` 谱系、`isSeeded` 谱系标记、可选的粗粒度 `origin`、`delegationDepth`、用于组装该 agent（智能体）的 `agentPreset` 以及已有的 `createdAt`。seeded 创建必须显式提供与 inherited prefix 完全相等的 seed 和精确 cut；constructor 会先在该 cut 追加 child-owned tagged end-seed marker，setup 再添加 child-owned event。`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[]
-  /**
-   * Exact fork-inherited prefix length when `meta.isSeeded` is true. The
-   * constructor appends the child-owned tagged marker at the cut unless
-   * the seed already includes it followed by child-owned fork closers.
-   */
-  readonly inheritedEventCount?: SessionLogOffset
-  /**
-   * Storage metadata read once before publication. `isSeeded` marks fork
-   * lineage; supplying replay history alone does not make it inherited.
-   */
-  readonly meta?: {
-    readonly cwd?: string
-    readonly parentSession?: SessionId
-    readonly createdAt?: number
-    readonly isSeeded?: boolean
-    readonly origin?: 'subagent'
-    readonly delegationDepth?: number
-    readonly agentPreset?: string
-  }
-}
-```
-
-因此，回放/fork 的调用方式为 `ctx.agents.create({ sessionId, seed, meta })`——fork 还会随 `meta.isSeeded: true` 提供 `inheritedEventCount`，且只有经 agent-loop 发布的会话才会持久化，且循环会在发布之前通过新会话的写句柄存储 seed；将一个*持久化*会话恢复为活跃 agent 的调用方式为 `ctx.agents.resume({ resumeSessionId })`。
-
-## 准备与恢复所有权
-
-`SessionStore.prepare()` 接收普通创建选项，或通过 `RestoredSessionOptions` 接收可直接接管的 seed。它的 `eventState` 表明 event value 是独占对象，还是只有深度冻结后的共享对象；生产者负责建立该状态，slice 不会根据结果长度推断其他状态。恢复流程会校验并直接接管这些值，不再复制或冻结。`SessionPreparation` 随后持有该精确的未发布 Session，直至发布或回滚；dispose 是同步且幂等的。agent-loop 的 resume 通过该会话的写句柄读取这份结果，并在准备之前追加独占的 `interruptedTurnClosers`。
-
-```ts type-equiv
-/**
- * Aliasing state of an adoptable Session seed. `shared-frozen` permits deeply
- * frozen aliases plus independently owned unfrozen values in the same seed.
- */
-type SessionSeedEventState = 'detached' | 'shared-frozen'
-```
-
-```ts type-equiv
-/**
- * Adoptable storage values transferred to {@link SessionStore.prepare}
- * without another copy or freeze pass.
- */
-interface RestoredSessionOptions {
-  /** Events that are independently owned or already deeply frozen. */
-  readonly seed: SessionEvent[]
-  /** Independently owned storage metadata to validate and freeze in place. */
-  readonly meta: SessionHeader
-  /** Exact number of fork-inherited leading events decoded from storage. */
-  readonly inheritedEventCount: SessionLogOffset
-  /** Aliasing state carried from the operation that produced the seed. */
-  readonly eventState: SessionSeedEventState
-}
-```
-
-```ts type-equiv
-/** Inputs accepted while constructing an unpublished Session. */
-type PrepareSessionOptions =
-  | (CreateSessionOptions & { readonly eventState?: 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;
-}
-```
-
-## 轻量源修订号
-
-派生读取模型的消费方会在加载完整事件日志之前比较一个低开销的不透明修订号。该修订号是来自 `stat`/`list` 的逐后端实例变更令牌：修订号相等可视为日志未变；不相等则不作任何承诺，且写所有权的变动绝不会改变修订号。session-query 以它为键管理冷读缓存；该令牌在 open、read 或 resume 中不起任何作用。
-
-```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 stored-session observation returned by {@link SessionPersistence.stat}
- * and {@link SessionPersistence.list} without reading the full event log.
- */
-interface SessionPersistenceSnapshot {
-  /** Detached metadata for one stored session. */
-  readonly header: SessionHeader
-  /** Header-only format classification; absent without versioned artifact metadata. */
-  readonly formatStatus?: 'current' | 'migration-required'
-  /** Opaque change token; see {@link SessionPersistence.stat}. */
-  readonly revision: SessionPersistenceRevision
-  /** Logical event count, when the backend can provide it cheaply from metadata; otherwise absent. */
-  readonly eventCount?: number
-  /** Physical artifact byte size, when the backend can provide it cheaply (JSONL); otherwise absent. */
-  readonly sizeBytes?: number
-}
-```
-
-可选的 `eventCount`/`sizeBytes` 字段仍是供明确需要它们的 consumer 使用的低成本 backend observation。Session 列表不借助这两个字段打开冷日志，只读取 header 与经过 identity 校验的 projection cache hint，因此 cache 或 Session format 升级不会把启动变成 body scan。
-
-## 后端
-
-随产品交付的 provider 实现抽象 `SessionPersistence` 约定（`create`/`open`/`stat`/`list`，逐会话 `SessionHandle` 承载 `read`/`append`/`flush`/`close`，全程可选支持取消），并通过共享的持久化契约套件：
-
-- **[dsh-session-persistence-jsonl](../../packages/session/session-persistence-jsonl)**——逐会话仅追加的逻辑 JSONL 日志，默认存储为带 checksum 的连续 Zstandard frame，也可配置为原始行；具备崩溃安全的原子实体化、逐批 `fsync` 的 append，以及在第一次新 append 之前截断撕裂尾部。`stat`/`list` 携带 `sizeBytes` 与尽力而为的、由 `fs.stat` 派生的修订号。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## 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`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxsessionpersistence--sessionpersistence-abstract-seam"></a>
-
-### `ctx.sessionPersistence` — `SessionPersistence` (abstract seam)
-
-Durable append-only session storage addressed through per-session handles.
-
-Storage semantics shared by every backend: events are contiguous from seq 0 and never rewritten; a torn physical tail is never returned to a reader and is truncated by the write path before its first append; reads validate current-format records only and refuse unknown vocabulary fail-closed. `append` persists best-effort; `flush` — per handle or service-wide — is the durability barrier.
-
-Visibility: a created session is observable through `stat`/`list`/`open` in this process from the moment `create` resolves, even while a backend defers physical materialization (a pure optimization); other processes see the session only once it materializes, and a session that never materialized before a crash never existed. `SessionHandle.flush` forces materialization.
-
-Freshness: once an `append` or `flush` resolves, reads started afterwards on this backend instance observe at least that prefix.
-
-```ts cordis-catalog
-/**
- * Create a new stored session and take its write ownership.
- * @param header - the immutable header (id, version, cwd, lineage) to store.
- * @param options - optional cancellation.
- * @returns a `write` handle owned by the caller; close it to release ownership.
- * @throws {SessionAlreadyExistsError} when the id already exists.
- */
-abstract create(header: SessionHeader, options?: SessionPersistenceCreateOptions): Promise<SessionHandle>
-
-/**
- * Open an existing stored session.
- *
- * `read` never takes ownership and works while another handle (or process)
- * holds write ownership. `write` atomically claims single-writer ownership;
- * an existing active owner rejects.
- * @param id - the stored session to open.
- * @param access - `read` or `write`.
- * @param options - optional cancellation.
- * @returns the open handle.
- * @throws {SessionPersistenceNotFoundError} when the session does not exist.
- * @throws {SessionAlreadyOwnedError} for `write` when ownership is taken.
- */
-abstract open(id: SessionId, access: SessionAccess, options?: SessionPersistenceOpenOptions): Promise<SessionHandle>
-
-/**
- * Flush every active write handle owned by this service instance in one
- * durability barrier: each handle's routed live events drain durably and
- * its session materializes, exactly as that handle's own
- * `SessionHandle.flush` would. Read handles buffer nothing and are
- * untouched. A handle closed concurrently counts as flushed — close itself
- * drains durably.
- * @returns resolution once every write handle active at the call has flushed.
- * @throws {AggregateError} naming each session whose flush failed; the
- *   remaining handles still flush.
- */
-abstract flush(): Promise<void>
-
-/**
- * Observe one stored session without reading its event log or taking
- * ownership.
- *
- * The snapshot's `revision` is an opaque change token comparable only
- * against revisions from the same service instance and session id: equal
- * revisions may be treated as an unchanged log; unequal revisions promise
- * nothing. Write-ownership churn does not change a revision. It exists for
- * derived read-model caches keyed off `stat`/`list`; it plays no part in
- * open, read, or resume.
- * @param id - the stored session to observe.
- * @param options - optional cancellation.
- * @returns the snapshot, or `undefined` when the session does not exist.
- */
-abstract stat(id: SessionId, options?: SessionPersistenceStatOptions): Promise<SessionPersistenceSnapshot | undefined>
-
-/**
- * List every stored session visible to this process, in no promised order.
- * @param options - optional cancellation.
- * @returns one snapshot per stored session.
- */
-abstract list(options?: SessionPersistenceListOptions): Promise<readonly SessionPersistenceSnapshot[]>
-```
-
-Types: [SessionId](core.zh.md)
-
-Source: [`packages/session/session-persistence/src/index.ts`](../../packages/session/session-persistence/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/plan.i18n.yaml

@@ -1,22 +0,0 @@
-# Bilingual-pair consistency record for plan.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/plan.md
-/plan-mode:
-  en: 234f6e4c49714997
-  zh: add95d36252b572d
-/plan-mode/logged-state-and-recovery:
-  en: dd1e8ba31e6fd535
-  zh: a22dbccc60c73bc9
-/plan-mode/pending-selections-and-the-pre-step-append:
-  en: 8d7e5b7824921ed5
-  zh: 910fad43593f29f4
-/plan-mode/configuration:
-  en: ee04468005fae8e1
-  zh: 1347d554102951f2
-/plan-mode/the-exit-tool-and-the-plan-command:
-  en: b5bbc440552d7ade
-  zh: 17fb1cfed1bc48ef
-/plan-mode/the-service:
-  en: 07c3eec12e0dc75c
-  zh: 183d73f6672e2c5a

package/references/official-docs/docs/subsystems/plan.md

@@ -1,87 +0,0 @@
-# Plan Mode
-
-English | [中文](plan.zh.md)
-
-Plan mode is logged per-agent collaboration state owned by [dsh-plan-mode](../../packages/plan/plan-mode) (`ctx.planMode`, `PlanModeController`): while active, a deployment-owned guidance section is included in each model request. Plan mode is **soft guidance**. [Sandbox mode](sandbox.md) and [approval policy](approval.md) enforce restrictions independently; neither reads or writes plan state, so deployments configure them separately. The package is optional, and the agent loop does not depend on it. It contributes the `plan:policy` prompt section and registers the `exit_plan_mode` tool and `/plan` command. The [design reference](../../packages/plan/plan-mode/README.md) owns the rationale; the [package README](../../packages/plan/plan-mode/README.md) owns the model-experience and limitation detail.
-
-Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
-
-## Logged state and recovery
-
-`plan/mode` (`{ active: boolean }`) is a log-only, whole-value-replace [session event](session.md): durable and replayable, never in the model transcript. The optionally registered `plan` unit folds committed mode, command settlement, and the mode recorded at the latest request header. `ctx.planMode` reads that state through `stateOf()`; the first dependent access fails if the registry, `plan` key, or `turnBoundary` key is absent. Clients receive only `{ active, pending }`; resume, fork, and compaction recover both from the log. The complete event declaration is in the [persistence log event catalog](../persistence-catalog.md).
-
-## Pending selections and the pre-step append
-
-Because every session event is turn-enclosed, a user selection remains pending until the next accepted in-turn pre-step appends it before request derivation, in whichever turn that occurs. A selection never forces continuation, so one made after a turn's final accepted pre-step is appended in a later turn. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }`: the logged state used to assemble the current step plus the selected state waiting to be appended.
-
-The only append point while an agent is running is a prepended `agent/pre-step` listener. It observes every proposed request step, including turn 1 step 1 and request-recovery retries, calls downstream listeners first, and appends only after they accept the step. Prompt admission happens before a turn and cannot append `plan/mode`, so a selection made at the prompt is appended by the first accepted in-turn pre-step of the turn it starts. An append failure cannot block the turn, and the selection remains pending for a later accepted in-turn pre-step. An appended user selection also records one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A selection made after a turn's final accepted pre-step remains process-local and is lost if the process exits before another accepted in-turn pre-step ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
-
-## Configuration
-
-```ts type-equiv
-/** Deployment-owned plan guidance. */
-interface PlanModeConfig {
-  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
-  section: string
-}
-```
-
-A missing, blank, or non-string `section` and any unknown key fail at plugin load rather than being ignored. While plan mode is active, the exact `section` text renders as the `plan:policy` [system-prompt section](system-prompt.md) at order 50; inactive plan mode contributes no text.
-
-## The exit tool and the `/plan` command
-
-[`exit_plan_mode`](../tool-catalog.md#deepseek-aidsh-plan-mode) stays registered while plan mode is inactive, so entering or leaving plan mode changes only the prompt section, never the request tool catalog; execution outside plan mode fails. In plan mode it requires a complete markdown plan starting with a `#` heading and presents it for review through the [user-questions seam](user-questions.md). Approval returns `{ approved: true }` and records a silent (non-narrated) pending exit that is appended at the next accepted in-turn pre-step. Plan guidance therefore remains active for the rest of the assistant's current tool batch, and the tool result itself reports the transition. Keep-planning is a failed call carrying the user's feedback, so the model revises and presents again. A dismissed review returns `{ approved: false }` and concludes the turn, so plan mode stays active until the user's next message. A missing interaction channel and a service reload during review also fail the call rather than silently leaving plan mode.
-
-When [`ctx.commands`](commands.md) is composed, the plugin registers `/plan [off|message]`: bare `/plan` selects plan mode, any other non-empty message selects it and then submits the text through `agent.steer()` so it becomes the next step's ordinary logged user message under plan guidance, and the exact argument `off` selects inactive, which also cancels a pending entry before it is appended and becomes visible to a request.
-
-## The service
-
-`ctx.planMode` owns the logged plan state, applies and narrates selected state at step start, and owns the `plan:policy` section, the `/plan` command, and the stable exit tool; `get`/`set` signatures are in the generated [service catalog](#ctxplanmode--planmodecontroller).
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## 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`) — the language sides differ only in locale-specific paired document paths. 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).
-
-<a id="ctxplanmode--planmodecontroller"></a>
-
-### `ctx.planMode` — `PlanModeController`
-
-`ctx.planMode`: owns logged plan state, applies and narrates selected state at step start, the `plan:policy` section, the `/plan` command, and the stable exit tool. Client carriers expose the projection's cropped `{ active, pending }` view.
-
-```ts cordis-catalog
-/**
- * Read the logged plan state and any selected state awaiting the next
- * accepted in-turn pre-step.
- *
- * @param agent The agent to read.
- * @returns Current logged state plus a pending selection, when present.
- */
-get(agent: Agent): { active: boolean; pending?: boolean }
-
-/**
- * Select whether plan mode should be active. Between turns the method
- * appends the change immediately because no in-turn pre-step will run until
- * another prompt starts a turn. The open-turn fold is the idle signal:
- * agent status stays `running` through post-turn checkpointing, when no
- * further in-turn pre-step runs. During an open turn the selection remains
- * pending until the next accepted in-turn pre-step. Repeated selection of
- * the current or already-pending state is a no-op.
- *
- * @param agent The agent to switch.
- * @param active Whether plan mode should be active.
- * @returns what happened: `committed` (logged now), `queued` (awaiting the
- * next accepted in-turn pre-step), `cancelled` (an opposite pending selection
- * was cleared; the logged state already matches), or `noop` (already in that
- * state).
- */
-set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
-```
-
-Types: [Agent](core.md)
-
-Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/plan.zh.md

@@ -1,87 +0,0 @@
-# 计划模式
-
-[English](plan.md) | 中文
-
-计划模式是 [dsh-plan-mode](../../packages/plan/plan-mode) 拥有的、记录到日志的逐 agent（智能体）协作状态（`ctx.planMode`，`PlanModeController`）：激活期间，每个模型请求都会包含一段部署持有的指引。计划模式是**软性指引**。[沙箱模式](sandbox.zh.md)与[审批策略](approval.zh.md)分别强制限制；两者都不读写计划状态，因此部署需要分别配置它们。该包是可选项，agent loop（智能体循环）不依赖它。它贡献 `plan:policy` 提示词段落，并注册 `exit_plan_mode` 工具和 `/plan` 命令。[设计说明](../../packages/plan/plan-mode/README.zh.md)负责决策依据；[包 README](../../packages/plan/plan-mode/README.zh.md)负责模型体验与限制细节。
-
-源码：[`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
-
-## 已记录状态与恢复
-
-`plan/mode`（`{ active: boolean }`）是仅记日志、整值替换的[会话事件](session.zh.md)：持久且可回放，绝不进入模型 transcript（文本记录）。可选注册的 `plan` 单元折叠已提交模式、命令结算结果和最近一次请求头记录的模式。`ctx.planMode` 通过 `stateOf()` 读取该状态；注册表、`plan` key 或 `turnBoundary` key 缺失时，第一次依赖它们的访问会失败。客户端只接收 `{ active, pending }`；恢复、fork 与压缩（compaction）都能从日志恢复两者。完整事件声明见[持久化日志事件目录](../persistence-catalog.zh.md)。
-
-## 待生效选择与 pre-step 追加
-
-由于每个会话事件都位于轮次之内，用户选择会保持待生效状态，直到下一个被接受的轮内 pre-step 在派生请求之前追加该选择，无论该 pre-step 位于哪个轮次。选择不会强制续行，因此在某轮最后一个被接受的 pre-step 之后作出的选择会在之后的轮次追加。`set(agent, active)` 记录待生效选择（目标值与已记录或已在等待的状态相同时不做任何事），`get(agent)` 返回 `{ active: boolean; pending?: boolean }`：用于组装当前步骤的已记录状态，以及等待追加的已选状态。
-
-agent 运行时，唯一的追加点是前置（prepend）注册的 `agent/pre-step` 监听器。它会观察每个候选请求步骤，包括第 1 轮第 1 步和请求恢复重试；它先调用下游监听器，只在下游接受该步骤后追加。提示词准入发生在轮次开启之前，无法追加 `plan/mode`，因此在提示词处作出的选择由它开启的轮次内第一个被接受的 pre-step 追加。追加失败不能阻塞轮次，且该选择会继续等待之后被接受的轮内 pre-step。追加用户选择时还会记录一条插件来源的 `user/message` 通知，但仅当最后记录的请求头描述的是另一种状态时才记录，因此模型恰好在上下文变化时收到通知，且绝不重复。在某轮最后一个被接受的 pre-step 之后作出的选择只存在于进程内；如果进程在另一个被接受的轮内 pre-step 之前退出，该选择会丢失（[README 限制](../../packages/plan/plan-mode/README.zh.md#known-limitations-and-deferred-work)）。
-
-## 配置
-
-```ts type-equiv
-/** Deployment-owned plan guidance. */
-interface PlanModeConfig {
-  /** Guidance rendered as the `plan:policy` prompt section while plan mode is active. */
-  section: string
-}
-```
-
-`section` 缺失、为空白或不是字符串，以及任何未知键，都会在插件加载时失败，而不是被忽略。计划模式激活期间，确切的 `section` 文本以 order 50 渲染为 `plan:policy` [系统提示词段落](system-prompt.zh.md)；未激活的计划模式不贡献任何文本。
-
-## 退出工具与 `/plan` 命令
-
-[`exit_plan_mode`](../tool-catalog.zh.md#deepseek-aidsh-plan-mode) 在计划模式未激活时仍保持注册，因此进入或离开计划模式只改变提示词段落，绝不改变请求的工具目录；在计划模式之外执行会失败。在计划模式中，它要求一份以 `#` 标题开头的完整 markdown 计划，并通过[用户交互 seam](user-questions.zh.md) 呈交评审。批准返回 `{ approved: true }`，并记录一个静默（不叙述）的待生效退出，由下一个被接受的轮内 pre-step 追加。因此，计划指引在 assistant 当前这批工具调用的剩余部分继续生效，而工具结果本身会报告这次转换。「继续规划」则是一次携带用户反馈的失败调用，模型据此修订并再次呈交。放弃评审返回 `{ approved: false }` 并结束当前轮次，计划模式保持激活，直到用户发出下一条消息。评审期间交互通道缺失或服务重载同样使调用失败，而不是静默离开计划模式。
-
-当 [`ctx.commands`](commands.zh.md) 被组合时，插件注册 `/plan [off|message]`：单独的 `/plan` 选择计划模式；任何其他非空消息先选择计划模式，再通过 `agent.steer()` 提交该文本，使其在计划指引下成为下一步骤的普通已记录用户消息；确切参数 `off` 选择未激活，这还会在待生效条目被追加并对请求可见之前将其取消。
-
-## 服务
-
-`ctx.planMode` 拥有已记录的计划状态，在步骤开始时应用并叙述选中的状态，还拥有 `plan:policy` 段落、`/plan` 命令和稳定注册的退出工具；`get`/`set` 签名见生成的[服务目录](#ctxplanmode--planmodecontroller)。
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## 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`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxplanmode--planmodecontroller"></a>
-
-### `ctx.planMode` — `PlanModeController`
-
-`ctx.planMode`: owns logged plan state, applies and narrates selected state at step start, the `plan:policy` section, the `/plan` command, and the stable exit tool. Client carriers expose the projection's cropped `{ active, pending }` view.
-
-```ts cordis-catalog
-/**
- * Read the logged plan state and any selected state awaiting the next
- * accepted in-turn pre-step.
- *
- * @param agent The agent to read.
- * @returns Current logged state plus a pending selection, when present.
- */
-get(agent: Agent): { active: boolean; pending?: boolean }
-
-/**
- * Select whether plan mode should be active. Between turns the method
- * appends the change immediately because no in-turn pre-step will run until
- * another prompt starts a turn. The open-turn fold is the idle signal:
- * agent status stays `running` through post-turn checkpointing, when no
- * further in-turn pre-step runs. During an open turn the selection remains
- * pending until the next accepted in-turn pre-step. Repeated selection of
- * the current or already-pending state is a no-op.
- *
- * @param agent The agent to switch.
- * @param active Whether plan mode should be active.
- * @returns what happened: `committed` (logged now), `queued` (awaiting the
- * next accepted in-turn pre-step), `cancelled` (an opposite pending selection
- * was cleared; the logged state already matches), or `noop` (already in that
- * state).
- */
-set(agent: Agent, active: boolean): 'committed' | 'queued' | 'cancelled' | 'noop'
-```
-
-Types: [Agent](core.zh.md)
-
-Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/src/index.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/product-telemetry.i18n.yaml

@@ -1,10 +0,0 @@
-# Bilingual-pair consistency record for product-telemetry.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/product-telemetry.md
-/product-telemetry:
-  en: 419a470ec1cce036
-  zh: 91e69fb502318e45
-/product-telemetry/record-types:
-  en: bf5eadedbc896f5a
-  zh: 158fce1609a85d6d