@deepseek-ai/dsh-session-projection-cache 0.1.1-rc.2 → 0.1.2-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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 packages/session/session-projection-cache/README.md
-README.md: 33908578a5127f2b6bb78ed7467833aaaa2cf085
-README.zh.md: 0ca410f91562360d85faadf4cf64cb61ac467482
+README.md: c5e438a2ededef00a1faa456e9913492a603b51d
+README.zh.md: eab0b81af618558e6f1e5e6bc0c40da3fcc38884

package/README.md

@@ -1,42 +1,41 @@
+---
+description: "The persisted session-projection cache for deployments and maintainers choosing, configuring, or debugging durable checkpoints, zero-I/O list reads, and accelerated cold projection folds."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-session-projection-cache
 
 English | [中文](README.zh.md)
 
-The persisted projection cache (`ctx.sessionProjectionCache`): durable checkpoints of every projection unit's state, one record per session on the domain data form (`session_projcache` domain — the shipped json backend lands it beside `workspace.json` under the configured storage root). Design authority: the [session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) (persisted projection cache section).
-
-A stored row `(key → {ver, seq, val})` is a fold shortcut, never an authority: possibly stale (`seq` says exactly how stale) but never wrong. Consequences the implementation commits to:
+## Summary
 
-- **Every background write is fail-soft.** A failed durable write logs a warning and keeps the cache stale; the next write or cold read self-heals. A crash between writes costs a longer tail replay, never a wrong value.
-- **A `ver` mismatch against the live unit's `stateVersion` discards, never migrates.** A unit bump invalidates its rows at read time; the key refolds from the log.
-- **A row must pass the live unit's `stateSchema`.** A malformed row is omitted from the zero-I/O view and rejected by restore so the cold-read ladder refolds it from the log.
-- **Whole-record writes.** Each write replaces the session's full checkpoint (the registry cut is always complete), snapshotted through the lossless-JSON boundary — a unit state violating the plain-JSON contract fails loud.
-- **Records are bound to a log lifecycle, not just an id.** Each record stores the header identity (`createdAt`, `cwd`) it was folded from; every read validates it (the live or stored header is the witness) before accepting a row, so a deleted-then-recreated id or a persistence store swapped under a surviving cache discards the unrelated record instead of seeding phantom values.
-- **The log leads, the cache follows.** A live checkpoint flushes the session's buffered events durably BEFORE the cache row lands, so a crash can leave the cache behind the log (a longer tail replay) but never ahead of it.
+`dsh-session-projection-cache` persists the state checkpoints of every registered projection unit (`ctx.sessionProjectionCache`) as one versioned document per session in the `session_projcache` storage domain's `per-record` layout. The shipped JSON backend stores each record at `<root>/session_projcache/sessions/<id>.json`, and the cache never reads the session-persistence layer. A stored row is a fold shortcut, never an authority: it may be stale — its `seq` says exactly how stale — but never wrong. Three mandatory checkpoints (session creation, `turn/end`, and session disposal) plus configurable count and interval throttles keep the cache fresh. Choose it when list views need synchronous cached values or cold projection folds should skip an already-checkpointed prefix.
 
-## Write policy
+## Table of Contents
 
-Two mandatory points, throttled in between:
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
 
-| Trigger | Nature |
-|---|---|
-| `turn/end` | Mandatory — the turn-final value is what cold reads want. |
-| Session disposal (detach) | Mandatory — the live-to-cold moment; after it the cold ladder serves this session. |
-| `writeEveryEvents` committed events | Config throttle (count). |
-| `writeIntervalMs` since the first dirty event | Config throttle (interval). |
+-----
 
-Both `Config` fields are required (no defaults): flush cadence is a deployment choice with no universally correct value, stated in cordis.yml.
+<a id="use-this-package"></a>
+## Use this package
 
-## Listing read (`cachedSnapshot(meta)`)
+Mount this package beside the projection registry and the storage stack when clients should list projection values for cold sessions without loading their logs. Without it, consumers must obtain the log before they can reconstruct cold projection values.
 
-The zero-I/O rung: client values viewed straight from the identity-matching stored record (version- and state-schema-matching keys only), returned as a `{asOfSeq, values}` cut — `asOfSeq` is the lowest served-row watermark, so a client seeding its per-session value store under higher-seq-wins can never let a stale list block overwrite a newer push frame. Host-only rows are never returned. `undefined` when no usable client row exists (unknown id, unrelated lifecycle, or no usable rows); the api-proxy list carrier turns that into an absent column.
+### When to choose it
 
-## Cold read (`coldSnapshot(id, signal?)`)
+Choose it when a deployment restarts sessions and needs durable projection values for history lists, statistics, or goal snapshots. Skip it when projections serve only live sessions, or when the extra storage writes cost more than the saved projection work.
 
-The read ladder, zero full-log load on the happy path: cached rows → `sessionProjections.restoreFloor` (anchored one event below the lowest usable watermark) → persistence `readFrom(id, floor)` → `sessionProjections.restore` → fail-soft write-back of the refreshed rows. The anchor makes a shrunk log (crash-repair truncation) provable: an overreaching row triggers exactly one full re-read from seq 0 instead of serving a ghost value. No registered units serve `{asOfSeq: -1, values: {}}` without touching persistence; a session with no persisted log rejects with the seam's `not found`.
+### Minimal configuration
 
-`write(session)` is the synchronous-cut checkpoint both mandatory points use; carriers may call it directly (not fail-soft — the fail-soft wrappers own containment).
+Both throttle fields are required — flush cadence is a deployment choice with no universally correct value:
 
-## Composition
+The cache opens its domain through the storage stack, so base mounts `storage`, `storage-json` (root `dshHomePath('storages')`), and `storage-domain` (`backend: json`) before it:
 
 ```yaml
 - id: session-projection-cache
@@ -46,11 +45,72 @@ The read ladder, zero full-log load on the happy path: cached rows → `sessionP
     writeIntervalMs: 5000
 ```
 
-Injects `storageDomain`, `sessionProjections`, `sessionPersistence`, `sessions`. Without this row the projection system runs live-only (watermark cache; cold reads fall back to full log loads wherever a carrier implements them).
+| Field | Default | Meaning |
+|---|---|---|
+| `writeEveryEvents` | required | Committed events per session that force a durable checkpoint write between mandatory points |
+| `writeIntervalMs` | required | Longest time a dirty checkpoint may stay unwritten between mandatory points |
+
+The plugin injects `storageDomain`, `sessionProjections`, and `sessions`. The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-session-projection-cache) is the exhaustive source for every accepted field and its JSDoc.
+
+### How checkpoints are written
+
+Three mandatory points always write: session creation persists the seed-derived cut, `turn/end` persists the value that listing reads want, and session disposal persists the final live cut. Between them, the configured count and interval throttles write as events accumulate. Every write atomically replaces the session's complete record through the domain write chain; a failure logs a warning and keeps the cache stale, and the next write self-heals.
+
+### Reading cached values
+
+`cachedSnapshot(meta)` synchronously serves client values from the storage domain's in-memory tables with zero I/O. It accepts only an identity-matching record and version- and schema-matching keys, then returns a `{ asOfSeq, values }` cut at the lowest served-row watermark. It returns `undefined` for an unknown id, unrelated lifecycle, absent or foreign record document, or no usable rows. `coldSnapshot(meta, events)` accepts a complete ordered log, skips the checkpointed prefix while folding, and refreshes the record without reading the persistence layer itself.
+
+### What the cache guarantees
+
+The log leads and the cache follows: a live checkpoint flushes the session's buffered events durably before the cache row lands, so a crash can leave the cache behind the log but never ahead of it. Reads and writes share the storage domain's coherent in-memory state; the per-unit write chain mutates memory only after durability. Each version-stamped record must match the live unit schema and session header identity (`createdAt`, `cwd`), so malformed, stale, or unrelated records read as absent. The JSON backend stores each record at `<root>/session_projcache/sessions/<id>.json` in an owner-only directory tree.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the cache's durability and storage ownership; the observable behavior is covered in [Use this package](#use-this-package).
+
+### Design concept
+
+The cache is a fold shortcut over the projection registry's checkpoint face, stored in a `per-record` domain data table. It commits to six consequences: reads never bypass the domain write chain; every background write is fail-soft; a `ver` mismatch discards rather than migrates a row; a record must pass the live unit's `stateSchema`; writes replace one complete session record through the lossless-JSON boundary; and the log leads, the cache follows.
+
+### Read and write ownership
 
+The cache stores one version-stamped document per session in the `session_projcache` domain. It does not depend on a session-persistence backend, call `locate`, or inspect per-session directories. A malformed or stale record reads as absent, and consumers that require a cold value own any log refold.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `SessionProjectionCache` service, write-behind listeners, cache reads |
+| [`src/spec.ts`](src/spec.ts) | The `session_projcache` domain spec and record identity types |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; correctness is enforced at the write and read paths) |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the cache to the registry it checkpoints and the storage domain that holds its records.
+
+- [Session projections subsystem](../../../docs/subsystems/session-projection.md) — the projection unit contract and drive semantics this cache checkpoints.
+- [Session projection registry](../session-projection/README.md) — the `ctx.sessionProjections` service whose checkpoints this cache persists.
+- [Storage subsystem](../../../docs/subsystems/storage.md) — the domain routing and backend behavior that store cache records.
+- [Session package map](../README.md) — adjacent persistence, title, and telemetry packages.
+- [Session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md) — the persisted projection cache design rationale.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-None, as the cache only persists and restores host-side read models of already-logged session state and touches no prompt, message, schema, stream, or tool result.
+None, as the persisted cache accelerates host-side reads of projection state and registers nothing model-facing.
 
 #### KV Cache effect
 
@@ -58,6 +118,21 @@ None; the cache never assembles or sends provider requests.
 
 ## Known Limitations and Deferred Work
 
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define where the cache needs operational care. They are current package constraints, not a task backlog.
+
 - **No eviction or retention surface** — records accumulate per session; pruning stored checkpoints is out-of-band maintenance, same stance as session persistence itself.
 - **Interval throttle is per-session coarse** — the timer arms at the first dirty event after a clean write; a steady sub-threshold trickle writes once per interval, not a sliding window.
-- **`coldSnapshot` reads are not deduplicated** — two concurrent cold reads of one session each run the ladder; last write-back wins (rows are equivalent), acceptable for listing-scale call rates.
+- **No cache-side cold refold** — the cache serves and refreshes its rows but never reads the session log (it does not depend on the persistence layer); a consumer that needs a guaranteed cold snapshot refolds from the log itself.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,42 +1,41 @@
+---
+description: "面向部署方与维护者的持久会话投影缓存说明，用于选择、配置或排查持久检查点、零 I/O 列表读取与加速的冷投影折叠。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-session-projection-cache
 
 [English](README.md) | 中文
 
-持久投影缓存（`ctx.sessionProjectionCache`）：把每个投影单元的状态保存为检查点，基于域数据形态（domain data form）每会话一条记录（`session_projcache` 域——出厂 JSON 后端将其落在配置的存储根目录下、`workspace.json` 旁边）。设计权威：[session-projection RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md)（persisted projection cache 一节）。
-
-一条存储行 `(key → {ver, seq, val})` 是折叠捷径，绝不是权威：可能陈旧（`seq` 精确说明陈旧到哪），但绝不会错。实现据此承诺：
+## 概述
 
-- **每次后台写入都 fail-soft。** 持久写失败只记一条警告并保持缓存陈旧；下一次写入或冷读自愈。两次写之间崩溃的代价是更长的尾部回放，绝不是错误的值。
-- **`ver` 与当前运行单元的 `stateVersion` 不匹配即丢弃，绝不迁移。** 单元递增版本会在读取时使其行失效；该 key 从日志重新折叠。
-- **存储行必须通过当前单元的 `stateSchema`。** 畸形行从零 I/O view 中省略，并被 restore 拒绝，使冷读阶梯从日志重新折叠。
-- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 约定的单元状态会显式失败并报错。
-- **记录绑定到日志生命周期，而不只是 id。** 每条记录存储其折叠来源的 header 身份（`createdAt`、`cwd`）；每次读取先以活 header 或存储 header 为证验证它，再接受任何行——被删后重建的 id、或缓存幸存而持久化存储被换掉时，无关记录被整体丢弃，绝不播种幻影值。
-- **日志领先，缓存跟随。** 活会话检查点先把缓冲事件持久 flush，缓存行才落地，因此崩溃只会让缓存落后于日志（更长的尾部回放），绝不领先于它。
+`dsh-session-projection-cache` 将每个已注册投影单元的状态检查点（`ctx.sessionProjectionCache`）存为 `session_projcache` 存储域 `per-record` 布局下的逐会话版本化文档。随附 JSON 后端将每条记录存于 `<root>/session_projcache/sessions/<id>.json`，缓存绝不读取会话持久化层。存储行是折叠捷径，绝不是权威：它可能陈旧——`seq` 精确说明陈旧到哪——但绝不会错。三个必写点（会话创建、`turn/end` 与会话释放）加上可配置的条数与间隔节流让缓存保持新鲜。当列表视图需要同步缓存值，或冷投影折叠应跳过已检查点化的前缀时，选择本包。
 
-## 写策略
+## 目录
 
-两个必写点，其间节流：
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
 
-| 触发 | 性质 |
-|---|---|
-| `turn/end` | 必写——冷读要的正是轮次终值。 |
-| 会话释放（detach） | 必写——live 转 cold 的时刻；此后冷读阶梯接管该会话。 |
-| 累计 `writeEveryEvents` 个已提交事件 | 配置节流（条数）。 |
-| 距首个脏事件 `writeIntervalMs` 毫秒 | 配置节流（间隔）。 |
+-----
 
-两个 `Config` 字段均必填（无默认值）：写入节奏是部署选择，没有普适正确值，由 cordis.yml 明示。
+<a id="use-this-package"></a>
+## 使用本包
 
-## 列表读（`cachedSnapshot(meta)`）
+当客户端应在不加载日志的情况下列出冷会话投影值时，把本包与投影注册表及存储栈一起挂载。没有它时，消费方必须先取得日志，才能重建冷投影值。
 
-零 I/O 一档：从身份匹配的存储记录直接 view 客户端值（仅版本与 state schema 均匹配的 key），以 `{asOfSeq, values}` 切面返回——`asOfSeq` 取所服务行的最低水位，客户端在 higher-seq-wins 规则下播种值存储时，陈旧列表块永远压不过更新的推送帧。host-only 行永不返回。无可用客户端行（未知 id、无关生命周期、无可用行）时返回 `undefined`；api-proxy 列表载体将其转为列缺席。
+### 何时选择
 
-## 冷读（`coldSnapshot(id, signal?)`）
+当部署会重启会话，并需要为历史列表、统计信息或 goal 快照提供持久投影值时，选择本包。当投影只服务实时会话，或额外存储写入的成本高于所节省的投影工作时，跳过本包。
 
-读取阶梯，正常路径无需加载全量日志：缓存行 → `sessionProjections.restoreFloor`（锚定在最低可用水位之前一个事件的位置）→ 持久化 `readFrom(id, floor)` → `sessionProjections.restore` → 刷新行的 fail-soft 写回。这个锚使缩短的日志（崩溃修复截断）可被证明：越界的行恰好触发一次从 seq 0 的全量重读，而不是把幽灵值当现值服务。无已注册单元时直接服务 `{asOfSeq: -1, values: {}}`，不触碰持久化；无持久日志的会话以 seam 的 `not found` 拒绝。
+### 最小配置
 
-`write(session)` 是两个必写点共用的同步切面检查点；载体可以直接调用（非 fail-soft——由 fail-soft 包装层负责遏制）。
+两个节流字段均必填——写入节奏是部署选择，没有普适正确值：
 
-## 组合
+缓存通过存储栈打开自己的域，因此 base 先挂 `storage`、`storage-json`（根 `dshHomePath('storages')`）与 `storage-domain`（`backend: json`）：
 
 ```yaml
 - id: session-projection-cache
@@ -46,18 +45,94 @@
     writeIntervalMs: 5000
 ```
 
-注入 `storageDomain`、`sessionProjections`、`sessionPersistence`、`sessions`。没有这一行时，投影系统只跑 live（水位缓存；冷读在实现了它的载体处退回全量日志加载）。
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `writeEveryEvents` | 必填 | 在各必写点之间强制一次持久检查点写入的每会话已提交事件数 |
+| `writeIntervalMs` | 必填 | 各必写点之间脏检查点最长可保持未写入的时间 |
+
+本插件注入 `storageDomain`、`sessionProjections` 与 `sessions`。生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-session-projection-cache)是每个受支持字段及其 JSDoc 的穷尽式真源。
+
+### 检查点如何写入
+
+三个必写点总是写入：会话创建保存由种子派生的切面，`turn/end` 保存列表读取所需的轮次终值，会话释放保存最终实时切面。其间，配置的条数与间隔节流随事件累积写入。每次写入通过领域写入链以原子方式替换该会话的完整记录；失败会记录警告并让缓存保持陈旧，后续写入会自行修复。
+
+### 读取缓存值
+
+`cachedSnapshot(meta)` 以零 I/O 从存储域的内存表同步提供客户端值。它只接受身份匹配的记录以及版本和 schema 均匹配的 key，再按所服务行的最低水位返回 `{ asOfSeq, values }` 切面。对于未知 id、无关生命周期、缺失或外来的记录文档，或没有可用行的情况，它返回 `undefined`。`coldSnapshot(meta, events)` 接受完整有序日志，在折叠时跳过已检查点化的前缀，并在自身不读取持久化层的情况下刷新记录。
+
+### 缓存保证什么
+
+日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与会话 header 身份（`createdAt`、`cwd`），因此畸形、陈旧或无关的记录都会读作不存在。JSON 后端把每条记录存于仅所有者可访问的 `<root>/session_projcache/sessions/<id>.json` 目录树中。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节说明缓存的持久性与存储所有权；可观察行为已在[使用本包](#use-this-package)中说明。
+
+### 设计理念
+
+缓存是投影注册表检查点接口上的折叠捷径，存于 `per-record` 领域数据表中。它带来六项后果：读取绝不绕过领域写入链；每次后台写入都 fail-soft；`ver` 不匹配时丢弃而不迁移记录；记录必须通过实时单元的 `stateSchema`；写入通过无损 JSON 边界替换一份完整会话记录；日志领先，缓存跟随。
+
+### 读写所有权
 
+缓存在 `session_projcache` 领域中为每个会话保存一份带版本戳的文档。它不依赖会话持久化后端，不调用 `locate`，也不检查逐会话目录。畸形或陈旧的记录读作不存在；需要冷值的消费方负责提供日志以重新折叠。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`SessionProjectionCache` 服务、写后监听器、缓存读取 |
+| [`src/spec.ts`](src/spec.ts) | `session_projcache` 域 spec 与记录身份类型 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；正确性在写入与读取路径强制） |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从缓存逐步进入它检查点化的注册表与保存其记录的存储域。
+
+- [会话投影子系统](../../../docs/subsystems/session-projection.zh.md)——本缓存检查点化的投影单元约定与驱动语义。
+- [会话投影注册表](../session-projection/README.zh.md)——本缓存持久化其检查点的 `ctx.sessionProjections` 服务。
+- [存储子系统](../../../docs/subsystems/storage.zh.md)——保存缓存记录的领域路由与后端行为。
+- [会话包映射](../README.zh.md)——相邻的持久化、标题与遥测包。
+- [会话投影 RFC](../../../.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.zh.md)——持久投影缓存的设计理由。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-无，因为缓存只持久化并恢复 host 侧的、由已写入日志的会话状态派生的读模型，不触碰任何提示词、消息、schema、流或工具结果。
+无，因为持久缓存只加速主机侧的投影状态读取，不注册任何模型可见内容。
 
 #### KV Cache 影响
 
 无；缓存从不组装或发送提供方请求。
 
-## 已知局限与延后工作
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明缓存何时需要运维注意。它们是当前包约束，不是任务积压。
+
+- **无淘汰或保留接口**——记录按会话持续累积；清理已存储检查点属于带外维护，与会话持久化采用相同策略。
+- **间隔节流采用按会话的粗粒度控制**——一次无脏数据的写入完成后，计时器在首个脏事件到达时启动；持续但低于条数阈值的事件流每间隔写入一次，而非滑动窗口。
+- **缓存侧不做冷重折叠**——缓存只服务并刷新自己的记录，从不读取会话日志，因为它不依赖持久化层；需要保证冷快照的消费方自行从日志重新折叠。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
 
-- **不提供淘汰或保留接口**：记录会按会话持续累积；清理已存储的检查点属于带外维护，与会话持久化采用相同策略。
-- **间隔节流采用按会话的粗粒度控制**：一次无脏数据的写入完成后，计时器会在首个脏事件到达时启动；对于持续但未达到条数阈值的事件流，系统每个间隔写入一次，而不采用滑动窗口。
-- **`coldSnapshot` 读取不去重**——同一会话的两个并发冷读各跑一遍阶梯；写回最后者胜（行等价），对列表级调用频率可接受。
+</details>

package/lib/index.js

@@ -1,17 +1,18 @@
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { snapshotJsonValue } from "@deepseek-ai/dsh-session";
+import { snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
 import { z as z$1 } from "zod";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 //#region lib/types/spec.js
 /**
-* The session-projcache domain declaration: one `sessions` table keyed by
+* The projection-cache domain declaration: one `sessions` table keyed by
 * {@link SessionId}, each record the full projection checkpoint for one
-* session (`key → {ver, seq, val}` rows). The spec object
-* is the single source of the domain's identity, version, and record schema;
-* the storage-domain routing decides the medium (the shipped composition's
-* json backend lands it at `<root>/session_projcache.json`, beside
-* `workspace.json`).
+* session (`key → {ver, seq, val}` rows). The spec object is the single
+* source of the domain's identity, version, layout, and record schema; the
+* storage-domain routing decides the medium (the shipped composition's json
+* backend stores the domain `per-record`: one document per session under
+* `<root>/session_projcache/sessions/`, so a checkpoint write rewrites one
+* session's document instead of the whole unit).
 * @module @deepseek-ai/dsh-session-projection-cache/src/spec
 */
 /**
@@ -32,9 +33,9 @@ const checkpointRow = z$1.object({
 * that distinguish one session lifecycle from another under the same id. A
 * session id names a slot, not a lifecycle — a deleted-then-recreated id, or
 * a persistence root swapped under a surviving cache, would otherwise let an
-* old row pass every watermark check and seed state folded from an unrelated
-* log. Reads validate this against the live header (listing) or the stored
-* header (cold read) before accepting any row.
+* old record pass every watermark check and seed state folded from an
+* unrelated log. Reads validate this against the live header (listing) or
+* the stored header (cold read) before accepting any record.
 */
 const checkpointIdentity = z$1.object({
 	createdAt: z$1.number().int().nonnegative(),
@@ -51,27 +52,34 @@ const checkpointRecord = z$1.object({
 	rows: z$1.record(z$1.string(), checkpointRow)
 });
 /**
-* The session-projcache domain spec. Version bumps discard the whole medium
-* (cache semantics: a stale or unreadable cache costs a longer tail replay,
-* never a wrong value).
+* The session-projcache domain spec. The `per-record` layout scopes version
+* bumps per session: after a bump, a stale session document is discarded on
+* open (cache semantics — a stale or unreadable cache costs a longer tail
+* replay, never a wrong value) while the rest of the domain stays usable,
+* instead of rejecting the whole medium.
 */
 const projectionCacheDomainSpec = defineDomain({
 	name: "session_projcache",
-	version: 3,
+	version: 4,
+	layout: "per-record",
 	tables: { sessions: domainTable(checkpointRecord) }
 });
 //#endregion
 //#region lib/types/index.js
 /**
 * Persisted projection cache (`ctx.sessionProjectionCache`): durable
-* checkpoints of every client-visible or explicitly persisted projection unit's state, one record per
-* session on the domain data form (`session_projcache` domain — the shipped
-* json backend lands it beside `workspace.json`). The cache is a fold
-* shortcut, never an authority: a row is possibly stale (its `seq`
-* says how stale) but never wrong, so every write path is fail-soft (a lost
-* write costs a longer tail replay on the next cold read) and a
-* `ver` mismatch discards the row instead of migrating it. Design
-* authority: the session-projection RFC
+* checkpoints of every projection unit's state, one record per session on
+* the `session_projcache` domain (`per-record` layout — the shipped json
+* backend stores one document per session under its root). Reads and writes
+* share ONE coherent state: the domain's in-memory tables serve every read
+* synchronously, and each write lands on the domain's write chain (durability
+* first, then memory), so a read can never observe a disk write the memory
+* has not applied, or a memory value the disk does not hold. The cache is a
+* fold shortcut, never an authority: a row
+* is possibly stale (its `seq` says how stale) but never wrong, so every
+* write path is fail-soft (a lost write costs a longer tail replay on the
+* next cold read) and a `ver` mismatch discards the row instead of migrating
+* it. Design authority: the session-projection RFC
 * (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
 * @module @deepseek-ai/dsh-session-projection-cache
 */
@@ -82,18 +90,17 @@ const Config = z.object({
 /**
 * The persisted projection cache service. Opens the `session_projcache`
 * domain at init, checkpoints live sessions on a throttled write-behind
-* (count/interval triggers from {@link 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.
+* (count/interval triggers from {@link Config}) plus three mandatory points —
+* session creation, `turn/end`, and session disposal (the live-to-cold
+* moment) — and serves the
+* cached rows for a session header. Every durable write is fail-soft:
+* failures log a warning and the cache self-heals on the next write.
 */
 var SessionProjectionCache = class extends Service {
 	config;
 	static inject = [
 		"storageDomain",
 		"sessionProjections",
-		"sessionPersistence",
 		"sessions"
 	];
 	static Config = Config;
@@ -115,7 +122,9 @@ var SessionProjectionCache = class extends Service {
 	* identity matches `expected`. A session id names a slot, not a lifecycle:
 	* a recreated id or a persistence store swapped under a surviving cache
 	* must not let an old record seed state folded from an unrelated log.
-	* Synchronous from the domain's in-memory state.
+	* Synchronous from the domain's in-memory state — the same state every
+	* write mutated, so a read can never go around the write chain to the
+	* medium.
 	* @param id - the session whose record is read.
 	* @param expected - the log identity the caller holds (live or stored header).
 	* @returns the identity-matching record, or `undefined` (absent or unrelated).
@@ -127,32 +136,53 @@ var SessionProjectionCache = class extends Service {
 	}
 	/**
 	* 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
+	* 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.
+	* paths (the history tail baseline) supersede these values whenever a
+	* session is actually opened.
 	* @param meta - the listed session's header (identity witness; no log read).
+	* @param keys - optional projection keys required by the caller's audience.
 	* @returns the cut (`asOfSeq` = lowest served-row watermark), or
 	*   `undefined` when no usable row exists for this lifecycle.
 	*/
-	cachedSnapshot(meta) {
+	cachedSnapshot(meta, keys) {
 		const record = this.recordFor(meta.id, identityOf(meta));
 		if (record === void 0) return void 0;
-		const values = this.ctx.sessionProjections.viewCheckpoint(record.rows);
-		const keys = Object.keys(values);
-		if (keys.length === 0) return void 0;
+		const values = this.ctx.sessionProjections.viewCheckpoint(record.rows, keys);
+		const servedKeys = Object.keys(values);
+		if (servedKeys.length === 0) return void 0;
 		return {
-			asOfSeq: Math.min(...keys.map((key) => record.rows[key].seq)),
+			asOfSeq: Math.min(...servedKeys.map((key) => record.rows[key].seq)),
 			values
 		};
 	}
 	/**
-	* Durably checkpoint one live session NOW (both mandatory points call
+	* Hydrate projection cells for an already-prepared Session without another
+	* persistence read. The cache seeds matching rows; the supplied exact log
+	* advances every unit to the observation cut. No checkpoint is written
+	* because the logical observation may contain recovery events not yet durable.
+	* @param session - exact unpublished Session retained by persistence.
+	* @param meta - observed lifecycle header.
+	* @param events - exact logical event prefix represented by the observation.
+	* @returns all projection values at the event cut.
+	*/
+	hydratePrepared(session, meta, events) {
+		const record = this.recordFor(meta.id, identityOf(meta));
+		if (record === void 0) return this.ctx.sessionProjections.hydrate(session, {}, events, 0);
+		try {
+			return this.ctx.sessionProjections.hydrate(session, record.rows, events, 0);
+		} catch {
+			return this.ctx.sessionProjections.hydrate(session, {}, events, 0);
+		}
+	}
+	/**
+	* Durably checkpoint one live session NOW (all 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.
+	* this boundary (states are live references), then the session's record is
+	* replaced on the domain's write chain. 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.
 	*/
@@ -163,37 +193,22 @@ var SessionProjectionCache = class extends Service {
 		await this.put(session.id, identityOf(session.header), rows);
 	}
 	/**
-	* 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.
+	* Cold-read one session's projections from its complete log. Each unit is
+	* seeded from the identity-checked cached rows — the registry skips `apply`
+	* for the already-folded prefix (events at or below the row's `seq`) — and
+	* the refreshed checkpoint is written back (fail-soft, fire-and-forget), so
+	* the first cold read creates the cache row and later ones seed from it.
+	* The caller supplies the complete log in seq order: this service never
+	* consults the persistence layer.
+	* @param meta - the stored session header (identity witness).
+	* @param events - the session's complete log, in seq order.
+	* @returns the projection cut at the log end.
 	*/
-	async coldSnapshot(id, signal) {
-		const record = this.requireTable().get(id);
-		const cached = record?.rows ?? {};
-		const floor = this.ctx.sessionProjections.restoreFloor(cached);
-		const persistence = this.ctx.sessionPersistence;
-		if (floor === void 0) return {
-			asOfSeq: (await persistence.readFrom(id, 0, signal)).events.at(-1)?.seq ?? -1,
-			values: {}
-		};
-		let restored;
-		const tail = await persistence.readFrom(id, floor, signal);
-		const related = record === void 0 || identityMatches(record.identity, identityOf(tail.meta));
-		try {
-			if (!related) throw new Error("unrelated log identity");
-			restored = this.ctx.sessionProjections.restore(cached, tail.events, floor);
-		} catch {
-			const whole = await persistence.readFrom(id, 0, signal);
-			restored = this.ctx.sessionProjections.restore({}, whole.events, 0);
-		}
-		await this.putSoft(id, identityOf(tail.meta), restored.checkpoint, "cold-read write-back");
+	coldSnapshot(meta, events) {
+		const restored = this.ctx.sessionProjections.restore(this.recordFor(meta.id, identityOf(meta))?.rows ?? {}, events, 0, meta);
+		this.put(meta.id, identityOf(meta), restored.checkpoint).catch((error) => {
+			this.ctx.logger.warn(`session projection cache: cold-read write-back for "${meta.id}" failed (cache stays stale): ${String(error)}`);
+		});
 		return restored.snapshot;
 	}
 	installWritePath() {
@@ -216,6 +231,9 @@ var SessionProjectionCache = class extends Service {
 				this.flushSoft(session, "interval");
 			}, this.config.writeIntervalMs);
 		});
+		this.ctx.on("session/created", (session) => {
+			this.flushSoft(session, "create");
+		});
 		this.ctx.on("session/disposed", (session) => {
 			this.flushSoft(session, "detach");
 			this.markClean(session);
@@ -229,7 +247,7 @@ var SessionProjectionCache = class extends Service {
 	/**
 	* One fail-soft durable checkpoint. Every caller has work by construction:
 	* the throttle triggers only fire dirty (markClean clears the timer with
-	* the counter) and the two mandatory points write unconditionally.
+	* the counter) and the mandatory points write unconditionally.
 	*/
 	async flushSoft(session, trigger) {
 		try {
@@ -257,14 +275,6 @@ var SessionProjectionCache = class extends Service {
 			rows: detached
 		});
 	}
-	/** Fail-soft {@link put}: cache writes must never fail their caller's read or event path. */
-	async putSoft(id, identity, rows, what) {
-		try {
-			await this.put(id, identity, rows);
-		} catch (error) {
-			this.ctx.logger.warn(`session projection cache: ${what} for "${id}" failed (cache stays stale): ${String(error)}`);
-		}
-	}
 	requireTable() {
 		/* v8 ignore next -- Service.init assigns the table before the service becomes injectable */
 		if (this.table === void 0) throw new Error("session projection cache is not initialized");

package/lib/invariant.js

@@ -13,8 +13,8 @@ const inject = ["invariants"];
 * the registry fold at its `seq` watermark) is only checkable by re-running the
 * fold over the persisted log — duplicating the implementation rather than
 * detecting drift — and its staleness is by design (fail-soft writes). The
-* durable boundary is already schema-validated by the storage-domain layer
-* on every reopen, and the read ladder's version/watermark guards are proven
+* durable boundary is schema-validated by the cache's own zod parse on every
+* read, and the read ladder's version/watermark guards are proven
 * by the package spec.
 */
 const install = () => {};

package/lib/types/index.d.ts

@@ -1,20 +1,24 @@
 /**
  * Persisted projection cache (`ctx.sessionProjectionCache`): durable
- * checkpoints of every client-visible or explicitly persisted projection unit's state, one record per
- * session on the domain data form (`session_projcache` domain — the shipped
- * json backend lands it beside `workspace.json`). The cache is a fold
- * shortcut, never an authority: a row is possibly stale (its `seq`
- * says how stale) but never wrong, so every write path is fail-soft (a lost
- * write costs a longer tail replay on the next cold read) and a
- * `ver` mismatch discards the row instead of migrating it. Design
- * authority: the session-projection RFC
+ * checkpoints of every projection unit's state, one record per session on
+ * the `session_projcache` domain (`per-record` layout — the shipped json
+ * backend stores one document per session under its root). Reads and writes
+ * share ONE coherent state: the domain's in-memory tables serve every read
+ * synchronously, and each write lands on the domain's write chain (durability
+ * first, then memory), so a read can never observe a disk write the memory
+ * has not applied, or a memory value the disk does not hold. The cache is a
+ * fold shortcut, never an authority: a row
+ * is possibly stale (its `seq` says how stale) but never wrong, so every
+ * write path is fail-soft (a lost write costs a longer tail replay on the
+ * next cold read) and a `ver` mismatch discards the row instead of migrating
+ * it. Design authority: the session-projection RFC
  * (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
  * @module @deepseek-ai/dsh-session-projection-cache
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
-import type { Session, SessionHeader, SessionId } from '@deepseek-ai/dsh-session';
-import type { ProjectionSnapshot } from '@deepseek-ai/dsh-session-projection';
+import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session';
+import type { ProjectionSnapshot, SessionProjectionMap } from '@deepseek-ai/dsh-session-projection';
 export { checkpointIdentity, checkpointRecord, checkpointRow, projectionCacheDomainSpec } from './spec.ts';
 export type { CheckpointIdentity, CheckpointRecord } from './spec.ts';
 declare module '@deepseek-ai/cordis' {
@@ -25,8 +29,9 @@ declare module '@deepseek-ai/cordis' {
 /**
  * Plugin config. Both throttle triggers are deployment choices with no
  * universally correct value, so the composition states them explicitly
- * (cordis.yml); the two mandatory write points (`turn/end` and session
- * disposal) are policy, not tunables, and always fire.
+ * (cordis.yml); the three mandatory write points (session creation,
+ * `turn/end`, and session disposal) are policy, not tunables, and always
+ * fire.
  */
 export interface Config {
     /** Committed events per session that force a durable checkpoint write between mandatory points. */
@@ -38,11 +43,11 @@ export declare const Config: z<Config>;
 /**
  * The persisted projection cache service. Opens the `session_projcache`
  * domain at init, checkpoints live sessions on a throttled write-behind
- * (count/interval triggers from {@link 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.
+ * (count/interval triggers from {@link Config}) plus three mandatory points —
+ * session creation, `turn/end`, and session disposal (the live-to-cold
+ * moment) — and serves the
+ * cached rows for a session header. Every durable write is fail-soft:
+ * failures log a warning and the cache self-heals on the next write.
  */
 export declare class SessionProjectionCache extends Service {
     config: Config;
@@ -58,7 +63,9 @@ export declare class SessionProjectionCache extends Service {
      * identity matches `expected`. A session id names a slot, not a lifecycle:
      * a recreated id or a persistence store swapped under a surviving cache
      * must not let an old record seed state folded from an unrelated log.
-     * Synchronous from the domain's in-memory state.
+     * Synchronous from the domain's in-memory state — the same state every
+     * write mutated, so a read can never go around the write chain to the
+     * medium.
      * @param id - the session whose record is read.
      * @param expected - the log identity the caller holds (live or stored header).
      * @returns the identity-matching record, or `undefined` (absent or unrelated).
@@ -66,52 +73,63 @@ export declare class SessionProjectionCache extends Service {
     private recordFor;
     /**
      * 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
+     * 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.
+     * paths (the history tail baseline) supersede these values whenever a
+     * session is actually opened.
      * @param meta - the listed session's header (identity witness; no log read).
+     * @param keys - optional projection keys required by the caller's audience.
      * @returns the cut (`asOfSeq` = lowest served-row watermark), or
      *   `undefined` when no usable row exists for this lifecycle.
      */
-    cachedSnapshot(meta: SessionHeader): ProjectionSnapshot | undefined;
+    cachedSnapshot(meta: SessionHeader, keys?: readonly Extract<keyof SessionProjectionMap, string>[]): ProjectionSnapshot | undefined;
     /**
-     * Durably checkpoint one live session NOW (both mandatory points call
+     * Hydrate projection cells for an already-prepared Session without another
+     * persistence read. The cache seeds matching rows; the supplied exact log
+     * advances every unit to the observation cut. No checkpoint is written
+     * because the logical observation may contain recovery events not yet durable.
+     * @param session - exact unpublished Session retained by persistence.
+     * @param meta - observed lifecycle header.
+     * @param events - exact logical event prefix represented by the observation.
+     * @returns all projection values at the event cut.
+     */
+    hydratePrepared(session: Session, meta: SessionHeader, events: readonly SessionEvent[]): ProjectionSnapshot;
+    /**
+     * Durably checkpoint one live session NOW (all 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.
+     * this boundary (states are live references), then the session's record is
+     * replaced on the domain's write chain. 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.
      */
     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.
+     * Cold-read one session's projections from its complete log. Each unit is
+     * seeded from the identity-checked cached rows — the registry skips `apply`
+     * for the already-folded prefix (events at or below the row's `seq`) — and
+     * the refreshed checkpoint is written back (fail-soft, fire-and-forget), so
+     * the first cold read creates the cache row and later ones seed from it.
+     * The caller supplies the complete log in seq order: this service never
+     * consults the persistence layer.
+     * @param meta - the stored session header (identity witness).
+     * @param events - the session's complete log, in seq order.
+     * @returns the projection cut at the log end.
      */
-    coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<ProjectionSnapshot>;
+    coldSnapshot(meta: SessionHeader, events: readonly SessionEvent[]): ProjectionSnapshot;
     private installWritePath;
     /**
      * One fail-soft durable checkpoint. Every caller has work by construction:
      * the throttle triggers only fire dirty (markClean clears the timer with
-     * the counter) and the two mandatory points write unconditionally.
+     * the counter) and the mandatory points write unconditionally.
      */
     private flushSoft;
     /** Reset one session's dirty bookkeeping (its checkpoint is being written). */
     private markClean;
     /** Replace one session's stored record with its log identity and a detached snapshot of `rows`. */
     private put;
-    /** Fail-soft {@link put}: cache writes must never fail their caller's read or event path. */
-    private putSoft;
     private requireTable;
 }
 export default SessionProjectionCache;

package/lib/types/spec.d.ts

@@ -1,15 +1,16 @@
 /**
- * The session-projcache domain declaration: one `sessions` table keyed by
+ * The projection-cache domain declaration: one `sessions` table keyed by
  * {@link SessionId}, each record the full projection checkpoint for one
- * session (`key → {ver, seq, val}` rows). The spec object
- * is the single source of the domain's identity, version, and record schema;
- * the storage-domain routing decides the medium (the shipped composition's
- * json backend lands it at `<root>/session_projcache.json`, beside
- * `workspace.json`).
+ * session (`key → {ver, seq, val}` rows). The spec object is the single
+ * source of the domain's identity, version, layout, and record schema; the
+ * storage-domain routing decides the medium (the shipped composition's json
+ * backend stores the domain `per-record`: one document per session under
+ * `<root>/session_projcache/sessions/`, so a checkpoint write rewrites one
+ * session's document instead of the whole unit).
  * @module @deepseek-ai/dsh-session-projection-cache/src/spec
  */
 import { z } from 'zod';
-import { SessionId } from '@deepseek-ai/dsh-session';
+import type { SessionId } from '@deepseek-ai/dsh-session';
 /**
  * One persisted checkpoint row (the RFC's `(sessionId, key, ver, seq, val)`
  * minus the two record keys). `val` is the unit's internal state — plain
@@ -28,9 +29,9 @@ export declare const checkpointRow: z.ZodObject<{
  * that distinguish one session lifecycle from another under the same id. A
  * session id names a slot, not a lifecycle — a deleted-then-recreated id, or
  * a persistence root swapped under a surviving cache, would otherwise let an
- * old row pass every watermark check and seed state folded from an unrelated
- * log. Reads validate this against the live header (listing) or the stored
- * header (cold read) before accepting any row.
+ * old record pass every watermark check and seed state folded from an
+ * unrelated log. Reads validate this against the live header (listing) or
+ * the stored header (cold read) before accepting any record.
  */
 export declare const checkpointIdentity: z.ZodObject<{
     createdAt: z.ZodNumber;
@@ -58,13 +59,16 @@ export declare const checkpointRecord: z.ZodObject<{
 /** One stored per-session checkpoint record, inferred from {@link checkpointRecord}. */
 export type CheckpointRecord = z.infer<typeof checkpointRecord>;
 /**
- * The session-projcache domain spec. Version bumps discard the whole medium
- * (cache semantics: a stale or unreadable cache costs a longer tail replay,
- * never a wrong value).
+ * The session-projcache domain spec. The `per-record` layout scopes version
+ * bumps per session: after a bump, a stale session document is discarded on
+ * open (cache semantics — a stale or unreadable cache costs a longer tail
+ * replay, never a wrong value) while the rest of the domain stays usable,
+ * instead of rejecting the whole medium.
  */
 export declare const projectionCacheDomainSpec: {
     name: string;
     version: number;
+    layout: "per-record";
     tables: {
         sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<SessionId, {
             identity: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-projection-cache",
-  "description": "Persisted projection cache (ctx.sessionProjectionCache): durable per-session projection checkpoints over the domain data form, throttled write-behind, and the cold-read ladder (cache row + persistence tail replay)",
-  "version": "0.1.1-rc.2",
+  "description": "Persisted projection cache (ctx.sessionProjectionCache): durable per-session checkpoint records on the session_projcache storage domain (per-record layout), throttled write-behind, and the cached listing read",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -33,23 +33,23 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-storage": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-storage-json": "^0.1.2-alpha.2"
   }
 }