dsh-plugin-guide 0.1.0

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

@@ -0,0 +1,186 @@
+# 仅限 Session 内的 Schedule
+
+[English](schedule.md) | 中文
+
+Schedule 拥有持久提醒；这些提醒会作为普通的后续对话轮次返回原 live Session。[持久 Schedule Agent Note](../../.agents/notes/implemented/feature/2026-08-05-durable-web-schedule.md) 负责持久化与生命周期决策，[对话式交付](../../.agents/notes/implemented/simplification/2026-08-09-conversational-schedule-delivery.md) 负责无回执边界，[显式时区边界](../../.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md) 负责浏览器本地解释，[有界固定速率 Schedule](../../.agents/notes/implemented/simplification/2026-08-09-bounded-fixed-rate-schedule.md) 负责重复调度。本页记录 [`packages/schedule/schedule/src/types.ts`](../../packages/schedule/schedule/src/types.ts) 中的持久数据形状和面向模型的数据形状；[包 README](../../packages/schedule/schedule/README.md) 负责组合、工具行为与确切的提醒 framing。
+
+## 持久记录
+
+`ScheduleId` 是[品牌化 id](core.md#branded-ids)，在单个 Session 内唯一且绝不复用。版本 1 支持正的安全整数 `after_seconds` 延时、显式的绝对 `at` 目标，或至少五分钟的安全整数 `every_seconds` 间隔。创建操作会将每个初始目标规范化为使用四位年份的 RFC 3339 UTC `scheduledAt`；`after` 记录会保留提交的延时，`at` 记录只存储结果时点，`every` 记录则保留固定间隔和下一个目标。
+
+```ts type-equiv
+/** Durable one-shot reminder created from a positive delay. */
+interface AfterScheduleRecord {
+  /** Session-local stable identity. */
+  readonly id: ScheduleId
+  /** Rule discriminator for a delayed one-shot reminder. */
+  readonly kind: 'after'
+  /** Trimmed reminder content supplied at creation. */
+  readonly prompt: string
+  /** Positive safe-integer delay accepted at creation. */
+  readonly afterSeconds: number
+  /** Four-digit-year RFC 3339 UTC target. */
+  readonly scheduledAt: string
+}
+```
+
+```ts type-equiv
+/** Durable one-shot reminder created from an absolute instant. */
+interface AtScheduleRecord {
+  /** Session-local stable identity. */
+  readonly id: ScheduleId
+  /** Rule discriminator for an absolute one-shot reminder. */
+  readonly kind: 'at'
+  /** Trimmed reminder content supplied at creation. */
+  readonly prompt: string
+  /** Four-digit-year RFC 3339 UTC target. */
+  readonly scheduledAt: string
+}
+```
+
+```ts type-equiv
+/** Durable fixed-rate reminder whose next target remains creation-anchor-aligned. */
+interface EveryScheduleRecord {
+  /** Session-local stable identity. */
+  readonly id: ScheduleId
+  /** Rule discriminator for a fixed-rate recurring reminder. */
+  readonly kind: 'every'
+  /** Trimmed reminder content supplied at creation. */
+  readonly prompt: string
+  /** Fixed safe-integer interval, never below five minutes. */
+  readonly everySeconds: number
+  /** Earliest anchor-aligned occurrence not yet dispatched. */
+  readonly scheduledAt: string
+}
+```
+
+```ts type-equiv
+/** One-shot record variants that terminate on an id-only dispatch. */
+type OneShotScheduleRecord = AfterScheduleRecord | AtScheduleRecord
+```
+
+```ts type-equiv
+/** The v1 durable reminder record union. */
+type ScheduleRecord = OneShotScheduleRecord | EveryScheduleRecord
+```
+
+## 绝对时间输入
+
+`at` 选择器可以是严格且带偏移量的 RFC 3339 字符串，也可以是精确的本地日历对象。本地形式让这种解释在工具边界保持显式：
+
+```ts type-equiv
+/** Structured local-calendar input accepted by `schedule_create`. */
+interface LocalAtInput {
+  /** Four-digit ISO calendar date. */
+  readonly date: string
+  /** Local wall-clock time with optional one-to-three digit milliseconds. */
+  readonly time: string
+  /** Explicit UTC or IANA Area/Location zone. */
+  readonly time_zone: string
+}
+```
+
+```ts type-equiv
+/** Absolute selector accepted by `schedule_create`. */
+type AtInput = string | LocalAtInput
+```
+
+官方 Web overlay 会为每条提示词采样浏览器的 IANA 时区。当 open turn 只有一个无歧义的浏览器时区时，Time-context 会告诉模型按该请求本地时区解释未明确限定时区的自然语言日期和时间；provenance 混合或缺失时，则告诉模型询问用户。该指引不是持久 Session 默认值：模型仍必须在字符串形式中传入偏移量，或在本地形式中传入 `time_zone`；Schedule 绝不会读取浏览器、Session、进程或模型上下文。
+
+Schedule 会拒绝无效偏移量与时区、不带偏移量的字符串、非未来目标，以及落在夏令时缺口内的本地时间。遇到夏令时重叠时，会选择第一次出现的较早时点。创建成功后只存储规范化后的 UTC `scheduledAt`，因此回放绝不依赖环境时区状态。
+
+## 固定速率输入与补偿
+
+`every_seconds` 是每条记录单独拥有且至少为 300 秒的间隔，以创建时间为锚点。它只提供固定速率重复调度：协议不包含日历规则或 Cron 表达式、重复调度时区、共享冷却时间或跨记录准入门禁。
+
+如果一个 Session 在多个目标到期期间处于 cold 或 busy 状态，一条 Every 记录只会贡献其中最新的一次到期触发。dispatch 会直接将记录推进到 dispatch 判断时刻之后第一个与创建锚点对齐的目标，而不会枚举、持久化或回放错过的间隔。如果下一个目标无法落在四位数年份的 UTC 范围内，最后一次 dispatch 将终结该记录。
+
+当多条彼此不同的 Every 记录均已到期，且没有一次性提醒到期时，每条记录都会向同一个 follow-up 批次贡献一次触发，并按目标时间和创建顺序排列。每条 Every 记录的状态互相独立，但该获准批次中的所有 dispatch 都使用同一个判断时刻。批处理限制模型轮次数量；五分钟下限限制每条记录的 timer 频率。
+
+## 持久变更与回放
+
+版本 1 的 `schedule/change` 会话事件是 Schedule 唯一的持久权威。create 保存完整记录，delete 是终结性且仅含 id 的转换。一次性提醒的 dispatch 同样是终结性且仅含 id。Every dispatch 携带用于选择最新到期触发的墙钟判断时刻，通常推进活动记录而不终结它。dispatch 表示 follow-up 已同步入队，而不表示模型答复成功或用户已读取答复。
+
+```ts type-equiv
+/** Creates one durable reminder record. */
+interface ScheduleCreateChange {
+  readonly version: 1
+  readonly operation: 'create'
+  readonly schedule: ScheduleRecord
+}
+```
+
+```ts type-equiv
+/** Deletes one currently active reminder. */
+interface ScheduleDeleteChange {
+  readonly version: 1
+  readonly operation: 'delete'
+  readonly id: ScheduleId
+}
+```
+
+```ts type-equiv
+/** Records that one active one-shot reminder entered the durable dispatch history. */
+interface OneShotScheduleDispatchChange {
+  readonly version: 1
+  readonly operation: 'dispatch'
+  readonly id: ScheduleId
+}
+```
+
+```ts type-equiv
+/** Records one fixed-rate decision and advances directly past missed occurrences. */
+interface EveryScheduleDispatchChange {
+  readonly version: 1
+  readonly operation: 'dispatch'
+  readonly id: ScheduleId
+  /** Wall-clock decision time used to select the latest due occurrence. */
+  readonly acceptedAt: string
+}
+```
+
+```ts type-equiv
+/** Durable dispatch shapes supported by the current rule set. */
+type ScheduleDispatchChange = OneShotScheduleDispatchChange | EveryScheduleDispatchChange
+```
+
+```ts type-equiv
+/** Strict version-1 durable Schedule mutation union. */
+type ScheduleChange = ScheduleCreateChange | ScheduleDeleteChange | ScheduleDispatchChange
+```
+
+严格 decoder 与 fold 会拒绝未知版本、额外字段、复用 id、不匹配的一次性提醒或 Every dispatch 形状，以及针对非活动记录的 delete 或 dispatch 转换。普通 Session 折叠完整事件流。fork 只折叠 `SessionHeader.seedLength` 位置及其后的事件，因此保留历史，但不会接管父 Session 的活动提醒。`schedule/change` 声明和源码位置也编入[持久化目录](../persistence-catalog.md#schedulechange--log-only)。
+
+## 活动视图与管理
+
+工具值将持久记录与根据当前墙钟派生的交付状态组合起来。`session-local` 表示原 Session 必须处于 live 状态：不存在外部通知渠道或 cold Session scheduler。
+
+```ts type-equiv
+/** Current delivery timing derived from the durable record and wall clock. */
+type ScheduleState = 'scheduled' | 'overdue'
+```
+
+```ts type-equiv
+/** Fixed v1 delivery boundary: the original session must be live. */
+type ScheduleDeliveryMode = 'session-local'
+```
+
+```ts type-equiv
+/** Complete model-facing view of one active reminder. */
+type ScheduleView = ScheduleRecord & {
+  /** Whether the target remains in the future. */
+  readonly state: ScheduleState
+  /** Reminder delivery never leaves the owning session. */
+  readonly deliveryMode: ScheduleDeliveryMode
+}
+```
+
+生成的[工具目录](../tool-catalog.md#deepseek-aidsh-schedule)负责 `schedule_create`、`schedule_list` 和 `schedule_delete` 的参数与结果 schema。一条 Agent-scoped 队列将管理调用与到期工作串行化。每次读取或判断都会先等待共享的 Session 持久化 barrier；create 与实际执行的 delete 在追加后还会再次等待。barrier 失败会报告 `persistence_uncertain`，而不是猜测 eager write 是否已提交。其他稳定错误代码是 `invalid_prompt`、`invalid_selector`、`invalid_rule`、`invalid_time_zone`、`not_future`、`time_out_of_range`、`frequency_too_high`、`corrupt_schedule_log` 和 `internal_error`。
+
+## Live 交付
+
+进程内 owner 根据持久 fold 派生最早的 timer，并在每次有界等待后重新读取墙钟。cold Session 不执行任何工作；重新打开后会重建 timer，并使已经过去的目标进入 overdue 状态。到期的一次性提醒享有优先级，每次只进入一个后续轮次。当没有一次性提醒到期时，所有 overdue 的 Every 记录会组成上述单个批次。
+
+到期工作会先等待 Agent 完全 idle 并认领 maintenance phase，再重新折叠状态、采样本次判断、将一个 `followup()` 排入队列，并追加对应的 dispatch 变更。它绝不会调用 `steer()`，也绝不会中断当前轮次。
+
+获得准入的一次性提醒或固定速率批次会启动一个普通的后续轮次，且只通过普通对话 transcript（文本记录）出现；Schedule 不提供独立的持久 Web 回执或浏览器渲染器。如果 framing 构造或同步队列准入失败，则不会记录 dispatch，提醒仍保持活动。队列准入后、持久 dispatch 前的狭窄崩溃窗口可能使提醒内容在恢复后重复，因此该边界提供的是尽力而为的至少一次交付，而非恰好一次交付。

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

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/subsystems/scope.md
+scope.md: c425217de224839d719da213e33f58bd2e6bf002
+scope.zh.md: 546226a23f8218d2f1b50ce970c6cc11d9626e27

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

@@ -0,0 +1,59 @@
+# Scoped Registration
+
+English | [中文](scope.zh.md)
+
+The [scope package](../../packages/core/scope) supplies the identity, carrier, and scoped-layer vocabulary that makes one registration context mean both per-agent visibility and shared lifetime ownership. It is a library primitive rather than a Cordis service; the [agent-scope runtime-design Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer) owns the lifecycle rationale, the [shared-storage Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md) owns the registry-layer decision, and the package [README](../../packages/core/scope/README.md) owns the callable API and filtering semantics.
+
+Sources: [`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts) and [`packages/core/scope/src/store.ts`](../../packages/core/scope/src/store.ts).
+
+## Identity and dispatch carrier
+
+`ScopeKey` is an opaque object identity. The shipped loop uses the live `Agent` object as its own key, but the primitive never inspects the object.
+
+```ts type-equiv
+/** An opaque, identity-compared scope key. */
+type ScopeKey = object
+```
+
+`Scoped<T>` is the compile-time brand on the opaque routing receiver returned by `scopeTarget(base, key)`. Scope-filtered event declarations require this carrier as their `this` type, while the real event subject remains an explicit argument.
+
+```ts type-equiv
+/**
+ * A routing-only event receiver built by {@link scopeTarget}. The type
+ * parameter records the subject type for dispatch checking; the carrier does
+ * not expose the subject's properties. Event payloads carry the real subject.
+ */
+type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
+```
+
+## Owned registration context
+
+`Scope` pairs the tagged registration context with two teardown paths. `rawDispose` preserves the exact Cordis disposer identity needed by an ordered composite effect; `dispose()` is the public shared quiescence boundary for direct and racing callers.
+
+```ts type-equiv
+/** A minted registration scope and its quiescent disposal boundaries. */
+interface Scope {
+  /** Context through which scope-owned registrations are made. */
+  ctx: Context
+  /** Exact Cordis disposer, used when nesting this scope in an ordered composite effect. */
+  rawDispose: () => Promise<void> | void
+  /** Dispose every scope-owned registration; racing calls await the same completion. */
+  dispose(): Promise<void>
+}
+```
+
+## Scoped registry layer
+
+`ScopeLayer` represents one registry's complete contribution at the global or exact-scope level. A concrete layer may aggregate multiple named and anonymous tables; whole-layer emptiness lets `ScopedLayers` reclaim scoped state without discarding a sibling table.
+
+```ts type-equiv
+/** One scope's aggregate contribution to a registry. */
+interface ScopeLayer {
+  /** Whether every table in this layer is empty. */
+  isEmpty(): boolean
+}
+```
+
+`ScopedLayers<L>` owns the eager global layer and lazily created exact-scope layers. Reads do not create layers: `peek(undefined)` means no overlay, while `merge()` materializes insertion-ordered global named entries followed by scoped shadows. Registrations use one context for both visibility and Cordis effect ownership, collect one synchronous undo before optional notification, return Cordis's exact disposer, and reclaim a scoped layer only when its complete `ScopeLayer` is empty.
+
+`NamedEntries<V>` supplies insertion-ordered lookup and live iteration with caller-owned duplicate errors. `AnonymousEntries<V>` gives every append a unique identity so equal values remain independent. Iteration stays live within one nonempty table generation; draining the table detaches existing iterators from later insertions. Both return idempotent exact-entry undos; the shared `EntryValues` implementation interface is not public.

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

@@ -0,0 +1,59 @@
+# 作用域注册
+
+[English](scope.md) | 中文
+
+[scope 包](../../packages/core/scope)提供身份、载体与作用域层词汇，使同一注册上下文同时表达每个 agent（智能体）的可见性和共享生命周期所有权。它是库原语，而不是 Cordis 服务；生命周期设计理由由 [agent-scope 运行时设计 Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md#scope-routing-one-opaque-key-selects-one-layer)规定，注册表层决策由[共享存储 Agent Note](../../.agents/notes/implemented/architecture/2026-07-12-scoped-layers-store.md)规定，可调用 API 与过滤语义则由包 [README](../../packages/core/scope/README.md)规定。
+
+源码：[`packages/core/scope/src/index.ts`](../../packages/core/scope/src/index.ts) 与 [`packages/core/scope/src/store.ts`](../../packages/core/scope/src/store.ts)。
+
+## 身份标识与分发载体
+
+`ScopeKey` 是一个不透明的对象身份标识。已交付的 agent loop（智能体循环）使用活跃的 `Agent` 对象作为自身的 key，但该原语从不检视该对象。
+
+```ts type-equiv
+/** An opaque, identity-compared scope key. */
+type ScopeKey = object
+```
+
+`Scoped<T>` 是编译期品牌标记，标注在 `scopeTarget(base, key)` 返回的不透明路由接收器上。作用域过滤的事件声明要求以此载体作为 `this` 类型，而真正的事件主体仍作为显式参数传入。
+
+```ts type-equiv
+/**
+ * A routing-only event receiver built by {@link scopeTarget}. The type
+ * parameter records the subject type for dispatch checking; the carrier does
+ * not expose the subject's properties. Event payloads carry the real subject.
+ */
+type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
+```
+
+## 拥有所有权的注册上下文
+
+`Scope` 将带标签的注册上下文与两个拆卸接口配对。`rawDispose` 保留有序复合 effect 所需的 Cordis disposer 的确切身份；`dispose()` 是面向直接调用方和竞态调用方的公共完全停稳边界。
+
+```ts type-equiv
+/** A minted registration scope and its quiescent disposal boundaries. */
+interface Scope {
+  /** Context through which scope-owned registrations are made. */
+  ctx: Context
+  /** Exact Cordis disposer, used when nesting this scope in an ordered composite effect. */
+  rawDispose: () => Promise<void> | void
+  /** Dispose every scope-owned registration; racing calls await the same completion. */
+  dispose(): Promise<void>
+}
+```
+
+## 带作用域的注册表层
+
+`ScopeLayer` 表示一个注册表在全局或确切作用域层级的完整贡献。具体 layer 可以聚合多个具名与匿名 table；整个 layer 为空时，`ScopedLayers` 可以回收带作用域状态，而不会丢弃兄弟 table。
+
+```ts type-equiv
+/** One scope's aggregate contribution to a registry. */
+interface ScopeLayer {
+  /** Whether every table in this layer is empty. */
+  isEmpty(): boolean
+}
+```
+
+`ScopedLayers<L>` 拥有立即创建的全局 layer，以及惰性创建的确切作用域 layer。读取不会创建 layer：`peek(undefined)` 表示不存在作用域覆盖层，而 `merge()` 会依次物化按插入顺序排列的全局具名条目和带作用域的遮蔽项。注册使用同一个上下文表示可见性与 Cordis effect 所有权，在可选通知前取得一个同步撤销函数，返回 Cordis 的原始 disposer，并且只在带作用域 layer 的完整 `ScopeLayer` 为空时回收它。
+
+`NamedEntries<V>` 提供按插入顺序的查找和动态迭代，重复项错误由调用方处理。`AnonymousEntries<V>` 为每次 append 分配唯一标识，因此值相等的条目仍彼此独立。在同一轮非空 table 生命周期内，迭代器可以观察后续变化；table 被清空后，现有迭代器不会再观察后续插入。两者都返回幂等、精确对应相应条目的撤销函数；共享实现接口 `EntryValues` 不对外公开。

package/references/official-docs/docs/subsystems/session-projection.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/subsystems/session-projection.md
+session-projection.md: 281e7630eed6480de07a66bf7050798c83396f77
+session-projection.zh.md: bc1448e8baa0f38b3a9ffed1c6005e8905c93bcd

package/references/official-docs/docs/subsystems/session-projection.md

@@ -0,0 +1,262 @@
+# Session Projections
+
+English | [中文](session-projection.zh.md)
+
+The session-projection seam — a [capability seam](../capability-seams.md) through which domain host plugins serve whole current values of log-derived per-session state to client carriers: the Service Definition and registry ([dsh-session-projection](../../packages/session/session-projection), `ctx.sessionProjections`), domain contributors (each registering one pure unit), and carriers ([dsh-host-apiproxy](../../packages/host/apiproxy)'s history tail page and `session/projection` push frame). It is one optional capability, not part of the agent-loop spine. The framework drives, the domain computes: the registry subscribes to `session/event` once and folds every committed event through every unit; domains hold no subscriptions and clients never fold domain events — they receive finished values. Design authority: the [session-projection RFC](../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md); drive/cache/feed contracts: the [package README](../../packages/session/session-projection/README.md).
+
+Source: [`packages/session/session-projection/src/index.ts`](../../packages/session/session-projection/src/index.ts)
+
+## The unit
+
+`SessionProjectionMap` is the merge-extensible type table for the whole chain (host unit, wire block, client hook); values are wire-JSON whole values, and rendering belongs to the slot system, never this layer. A domain contributes one `ProjectionDefinition` per key:
+
+```ts type-equiv
+/**
+ * One domain's state-driven computation unit: three pure synchronous
+ * functions plus declarations — never an opaque getter. The framework drives
+ * `apply` on every committed session event; the domain holds no
+ * subscriptions and owns only the mathematics. All three functions MUST be
+ * synchronous (an async unit would tear the carriers' consistency cut) and
+ * `state` MUST be plain JSON (the persisted-cache precondition).
+ */
+interface ProjectionDefinition<K extends keyof SessionProjectionMap, S> {
+  /** The projection key this unit owns (its `SessionProjectionMap` entry). */
+  key: K
+  /** Validates the wire payload (`view` output) before it leaves the host. */
+  schema: ZodType<SessionProjectionMap[K]>
+  /**
+   * State for the empty log.
+   * @returns the initial state.
+   */
+  init(): S
+  /**
+   * Pure transition: previous state + one committed event → next state. A
+   * unit uninterested in an event MUST return the same state reference — an
+   * unchanged reference (`Object.is`) produces zero downstream work.
+   * @param state - the state covering all prior events.
+   * @param event - the next committed session event.
+   * @returns the next state (same reference when the event is not the unit's).
+   */
+  apply(state: S, event: SessionEvent): S
+  /**
+   * State → wire payload (the read-side projection).
+   * @param state - the current state.
+   * @returns the whole current value for this unit's key.
+   */
+  view(state: S): SessionProjectionMap[K]
+  /**
+   * Persisted-cache invalidation version: bump whenever the serialized state fields or the
+   * fold semantics change, so persisted `(sessionId, key, ver, seq, val)`
+   * rows from an older unit are discarded instead of being forward-applied
+   * into garbage. Non-negative integer.
+   */
+  stateVersion: number
+}
+```
+
+The whole-value event rule is load-bearing: a state-carrying log event carries the complete post-change state, never a bare delta — it keeps every transition trivially cheap and every served value self-describing (last-wins for consumers).
+
+## The snapshot and the change feed
+
+```ts type-equiv
+/**
+ * One consistent read cut over every registered unit for one session.
+ * `asOfSeq` is the shared watermark — the seq of the last event every value
+ * reflects (`-1` for an empty log, mirroring `session/subscribed.lastSeq`).
+ */
+interface ProjectionSnapshot {
+  /** Seq of the last event the values reflect; -1 for an empty log. */
+  asOfSeq: number
+  /** Whole current value per registered key. */
+  values: Partial<SessionProjectionMap>
+}
+```
+
+```ts type-equiv
+/**
+ * Change-feed listener: one unit's value changed for one session. `value` is
+ * the schema-validated `view` output; `seq` is the unit's watermark at
+ * emission (the seq of the event that caused the change).
+ */
+type ProjectionChangeListener = (
+  session: Session,
+  key: Extract<keyof SessionProjectionMap, string>,
+  value: unknown,
+  seq: number,
+) => void
+```
+
+`snapshot(session)` is fully synchronous: a carrier reads it in the same tick as its page slice, so `asOfSeq` covers both reads at one sequence number. Every value passes its unit's schema before return; an accidentally async `view` returns a Promise, which schema validation rejects. The change feed fires once per unit whose state *reference* changed for each committed event; `apply` must return the same reference when its state did not change.
+
+## The registry: `ctx.sessionProjections`
+
+`SessionProjectionRegistry` ([signatures](#ctxsessionprojections--sessionprojectionregistry)) owns the drive: one `session/event` subscription, eager `apply` over every registered unit, and per-session per-unit watermark cells. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect whose disposer rides the calling fiber: an unloaded domain plugin's key (with its cached cells) disappears from subsequent drives and snapshots, and clients read that as capability absence; duplicate keys throw. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected.
+
+<!-- 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`) — 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).
+
+<a id="ctxsessionprojectioncache--sessionprojectioncache"></a>
+
+### `ctx.sessionProjectionCache` — `SessionProjectionCache`
+
+The persisted projection cache service. Opens the `session_projcache` domain at init, checkpoints live sessions on a throttled write-behind (count/interval triggers from Config) plus two mandatory points — `turn/end` and session disposal (the live-to-cold moment) — and serves the cold-read ladder: cached row, persistence `readFrom` tail, registry `restore`, durable write-back. Every durable write is fail-soft: failures log a warning and the cache self-heals on the next write or cold read.
+
+```ts cordis-catalog
+/**
+ * The zero-I/O listing read: whole values viewed straight from the stored
+ * rows (version-matching keys only), each cut carried with its watermark
+ * so a client value store can seed under its higher-seq-wins rule — as
+ * stale as the last durable checkpoint but never wrong, and never from an
+ * unrelated log (the caller's header is the identity witness). Fresher
+ * paths (the history tail baseline, {@link coldSnapshot}) supersede these
+ * values whenever a session is actually opened.
+ * @param meta - the listed session's header (identity witness; no log read).
+ * @returns the cut (`asOfSeq` = lowest served-row watermark), or
+ *   `undefined` when no usable row exists for this lifecycle.
+ */
+cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined
+
+/**
+ * Durably checkpoint one live session NOW (both mandatory points call
+ * this; tests and carriers may too). The registry cut is snapshotted at
+ * this boundary (states are live references), then the whole record is
+ * replaced. NOT fail-soft — callers on the fail-soft paths contain it.
+ * @param session - the live session to checkpoint.
+ * @returns resolution after durability and event emission.
+ */
+async write(session: Session): Promise<void>
+
+/**
+ * Cold-read one persisted session's projections with zero full-log load:
+ * cached rows + a persistence `readFrom` tail from the registry's restore
+ * floor, refolded by the registry and written back (fail-soft) so the next
+ * cold read starts closer. A cache row invalidated by a shrunk log
+ * (crash-repair truncation) triggers one full re-read from seq 0 — the
+ * ladder's slow rung, still no crash. Rejects when the session has no
+ * persisted log (`not found` from the persistence seam).
+ * @param id - the persisted session to read.
+ * @param signal - optional cancellation for the persistence reads.
+ * @returns the snapshot cut at the stored log end.
+ */
+async coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>
+```
+
+Types: [Session](session.md) · [SessionHeader](persistence.md) · [SessionId](core.md)
+
+Source: [`packages/session/session-projection-cache/src/index.ts:71`](../../packages/session/session-projection-cache/src/index.ts)
+
+<a id="ctxsessionprojections--sessionprojectionregistry"></a>
+
+### `ctx.sessionProjections` — `SessionProjectionRegistry`
+
+`ctx.sessionProjections`: the projection unit table and its drive. The service subscribes to `session/event` once; every committed event passes every registered unit's `apply` (eager drive), and a changed state reference notifies the change feed with the schema-validated view. Cells build lazily — a unit registered after events flowed, or a session older than the registry, folds `init` over the in-memory log on first touch (event or read). Registration is an effect (disposer rides the calling fiber): an unloaded domain plugin's key disappears from snapshots and clients read it as capability absence. Domain plugins register under `ctx.inject(['sessionProjections'], …)` so headless assemblies without the registry stay unaffected. Registrants sharing a key share one unit and are counted: the same tool package mounted in N agent presets registers N times, and the key survives until the last one unloads.
+
+```ts cordis-catalog
+/**
+ * Register one domain's unit. The registration is an effect on the calling
+ * context's fiber: disposing the fiber (or calling the returned disposer)
+ * removes the key — and the unit's cached cells — from subsequent drives
+ * and snapshots.
+ * @param definition - key, state schema, pure unit functions, and stateVersion.
+ * @returns the exact disposer that unregisters this unit.
+ */
+register<K extends keyof SessionProjectionMap, S>(definition: ProjectionDefinition<K, S>): () => void
+
+/**
+ * Subscribe to the change feed. The registration is an effect on the
+ * calling context's fiber.
+ * @param listener - called once per unit whose state reference changed, per committed event.
+ * @returns the exact disposer that unsubscribes.
+ */
+onChanged(listener: ProjectionChangeListener): () => void
+
+/**
+ * One consistent cut over every registered unit for one session, read from
+ * the watermark cache (missing cells fold lazily over the in-memory log).
+ * Fully synchronous — every value and `asOfSeq` reflect the same log
+ * position. Each value passes its unit's schema before leaving.
+ * @param session - the session whose projection values are read.
+ * @returns the snapshot; `values` is empty when no unit is registered.
+ */
+snapshot(session: Session): ProjectionSnapshot
+
+/**
+ * State-level checkpoint of every registered unit for one session, read
+ * from the watermark cache (missing cells fold lazily over the in-memory
+ * log). This is the write side of the persisted projection cache: the
+ * returned rows are the `(key → {ver, seq, val})` part of the durable
+ * `(sessionId, key, ver, seq, val)`
+ * rows. Every `val` is a DETACHED structured clone — never the live
+ * cell reference: the watermark cache is this registry's authoritative
+ * mutable state, and a caller reaching the live reference could corrupt
+ * every subsequent snapshot and frame through it (plain JSON by the unit
+ * contract, so the clone is total).
+ * @param session - the session whose unit states are checkpointed.
+ * @returns one row per registered key; empty when no unit is registered.
+ */
+checkpoint(session: Session): ProjectionCheckpoint
+
+/**
+ * The stored seq a {@link restore} tail read over `checkpoint` must start
+ * at: one event BELOW the lowest usable watermark (a row is usable when
+ * its `ver` matches the live unit's `stateVersion`; an absent or mismatched row
+ * pulls the floor to `0` — that key must refold the full log). The
+ * one-below anchor is load-bearing: the tail then proves how far the
+ * stored log still extends, so {@link restore} can detect a log that
+ * shrank below a row's watermark (crash-repair truncation) instead of
+ * serving the stale row as current — an empty tail read from the anchor
+ * yields an end below every watermark and the restore rejects for a full
+ * re-read.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns the seq to hand the persistence `readFrom`, or `undefined`
+ *   when no unit is registered (no read needed — {@link restore} would
+ *   serve empty values regardless).
+ */
+restoreFloor(checkpoint: ProjectionCheckpoint): number | undefined
+
+/**
+ * View a checkpoint's rows without any log read: for every registered
+ * unit whose row's `ver` matches, serve the schema-validated
+ * `view` of the stored state; mismatched or absent rows leave their key
+ * absent (a cold or listing consumer treats it as not-yet-available and a
+ * fuller read path refolds it). The zero-I/O rung of the read ladder —
+ * values are as stale as their rows, never wrong.
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @returns whole values per key with a usable row; empty when none.
+ */
+viewCheckpoint(checkpoint: ProjectionCheckpoint): Partial<SessionProjectionMap>
+
+/**
+ * Cold read: fold every registered unit over a stored log suffix, seeding
+ * each from its checkpoint row when usable — the one read recipe (cached
+ * state + forward tail replay + `view`) applied without a live `Session`.
+ * Call with the events returned by a persistence
+ * `readFrom(id, restoreFloor(checkpoint))` and that same floor as
+ * `baseSeq`; the floor's one-below anchor makes the supplied end honest,
+ * so a shrunk log is detected here. A row is usable iff its
+ * `ver` matches the live unit's `stateVersion`, it does not predate `baseSeq`
+ * (`seq >= baseSeq - 1`), and it does not claim events past the
+ * supplied end (`seq <= endSeq`); an unusable row is discarded
+ * and its key refolds from `init` — which is only sound over the full
+ * log, so a discarded row with `baseSeq > 0` throws (the caller re-reads
+ * from seq 0, e.g. after a crash-repair truncation shrank the log below
+ * a row's watermark).
+ * @param checkpoint - persisted rows for one session (possibly stale or empty).
+ * @param events - the stored events with `seq >= baseSeq`, in seq order.
+ * @param baseSeq - the seq `events` starts at (its first event's seq when non-empty).
+ * @returns the snapshot cut at the supplied log end (`asOfSeq` is the last
+ *   supplied event's seq, `baseSeq - 1` for an empty tail) plus the
+ *   refreshed checkpoint rows at that cut, ready for a durable write-back.
+ */
+restore(checkpoint: ProjectionCheckpoint, events: readonly SessionEvent[], baseSeq: number): { snapshot: ProjectionSnapshot; checkpoint: ProjectionCheckpoint }
+```
+
+Types: [Session](session.md) · [SessionEvent](session.md)
+
+Source: [`packages/session/session-projection/src/index.ts:171`](../../packages/session/session-projection/src/index.ts)
+<!-- END GENERATED cordis-surface -->