@deepseek-ai/dsh-session-projection-cache 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.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 packages/session/session-projection-cache/README.md
+README.md: 5d4ad07fab6648acdb40c6aa86d32cc78b4c016e
+README.zh.md: 9dfcd645097cc8390812be3aef82b9535fa953eb

package/README.md

@@ -0,0 +1,62 @@
+# @deepseek-ai/dsh-session-projection-cache
+
+English | [中文](README.zh.md)
+
+The persisted projection cache (`ctx.sessionProjectionCache`): durable checkpoints of every registered 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:
+
+- **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.
+- **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.
+
+## Write policy
+
+Two mandatory points, throttled in between:
+
+| 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.
+
+## Listing read (`cachedSnapshot(meta)`)
+
+The zero-I/O rung: whole values viewed straight from the identity-matching stored record (version-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. `undefined` when no usable record exists (unknown id, unrelated lifecycle, or no version-matching rows); the api-proxy list carrier turns that into an absent column.
+
+## Cold read (`coldSnapshot(id, signal?)`)
+
+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`.
+
+`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).
+
+## Composition
+
+```yaml
+- id: session-projection-cache
+  name: '@deepseek-ai/dsh-session-projection-cache'
+  config:
+    writeEveryEvents: 200
+    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).
+
+## 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.
+
+#### KV Cache effect
+
+None; the cache never assembles or sends provider requests.
+
+## Known Limitations and Deferred Work
+
+- **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.

package/README.zh.md

@@ -0,0 +1,62 @@
+# @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.md)（persisted projection cache 一节）。
+
+一条存储行 `(key → {ver, seq, val})` 是折叠捷径，绝不是权威：可能陈旧（`seq` 精确说明陈旧到哪），但绝不会错。实现据此承诺：
+
+- **每次后台写入都 fail-soft。** 持久写失败只记一条警告并保持缓存陈旧；下一次写入或冷读自愈。两次写之间崩溃的代价是更长的尾部回放，绝不是错误的值。
+- **`ver` 与活单元 `stateVersion` 不匹配即丢弃，绝不迁移。** 单元递增版本会在读取时使其行失效；该 key 从日志重新折叠。
+- **整记录写入。** 每次写入替换该会话的完整检查点（注册表切面始终是完整的），并经无损 JSON 边界快照——违反纯 JSON 约定的单元状态会大声失败。
+- **记录绑定到日志生命周期，而不只是 id。** 每条记录存储其折叠来源的 header 身份（`createdAt`、`cwd`）；每次读取先以活 header 或存储 header 为证验证它，再接受任何行——被删后重建的 id、或缓存幸存而持久化存储被换掉时，无关记录被整体丢弃，绝不播种幻影值。
+- **日志领先，缓存跟随。** 活会话检查点先把缓冲事件持久 flush，缓存行才落地，因此崩溃只会让缓存落后于日志（更长的尾部回放），绝不领先于它。
+
+## 写策略
+
+两个必写点，其间节流：
+
+| 触发 | 性质 |
+|---|---|
+| `turn/end` | 必写——冷读要的正是轮次终值。 |
+| 会话销毁（detach） | 必写——live 转 cold 的时刻；此后冷读阶梯接管该会话。 |
+| 累计 `writeEveryEvents` 个已提交事件 | 配置节流（条数）。 |
+| 距首个脏事件 `writeIntervalMs` 毫秒 | 配置节流（间隔）。 |
+
+两个 `Config` 字段均必填（无默认值）：写入节奏是部署选择，没有普适正确值，由 cordis.yml 明示。
+
+## 列表读（`cachedSnapshot(meta)`）
+
+零 I/O 一档：从身份匹配的存储记录直接 view 全量值（仅版本匹配的 key），以 `{asOfSeq, values}` 切面返回——`asOfSeq` 取所服务行的最低水位，客户端在 higher-seq-wins 规则下播种值存储时，陈旧列表块永远压不过更新的推送帧。无可用记录（未知 id、无关生命周期、无版本匹配行）时返回 `undefined`；api-proxy 列表载体将其转为列缺席。
+
+## 冷读（`coldSnapshot(id, signal?)`）
+
+读取阶梯，正常路径无需加载全量日志：缓存行 → `sessionProjections.restoreFloor`（锚定在最低可用水位之前一个事件的位置）→ 持久化 `readFrom(id, floor)` → `sessionProjections.restore` → 刷新行的 fail-soft 写回。这个锚使缩短的日志（崩溃修复截断）可被证明：越界的行恰好触发一次从 seq 0 的全量重读，而不是把幽灵值当现值服务。无已注册单元时直接服务 `{asOfSeq: -1, values: {}}`，不触碰持久化；无持久日志的会话以 seam 的 `not found` 拒绝。
+
+`write(session)` 是两个必写点共用的同步切面检查点；载体可以直接调用（非 fail-soft——由 fail-soft 包装层负责遏制）。
+
+## 组合
+
+```yaml
+- id: session-projection-cache
+  name: '@deepseek-ai/dsh-session-projection-cache'
+  config:
+    writeEveryEvents: 200
+    writeIntervalMs: 5000
+```
+
+注入 `storageDomain`、`sessionProjections`、`sessionPersistence`、`sessions`。没有这一行时，投影系统只跑 live（水位缓存；冷读在实现了它的载体处退回全量日志加载）。
+
+## 模型体验
+
+无，因为缓存只持久化并恢复 host 侧的、由已写入日志的会话状态派生的读模型，不触碰任何提示词、消息、schema、流或工具结果。
+
+#### KV Cache 影响
+
+无；缓存从不组装或发送提供方请求。
+
+## 已知局限与延后工作
+
+- **没有淘汰或保留面**——记录按会话累积；清理存储的检查点是带外维护，与会话持久化本身同一立场。
+- **间隔节流按会话粗粒度**——计时器在一次干净写入后的首个脏事件时武装；持续的低于阈值的涓流每个间隔写一次，不是滑动窗口。
+- **`coldSnapshot` 读取不去重**——同一会话的两个并发冷读各跑一遍阶梯；写回最后者胜（行等价），对列表级调用频率可接受。

package/lib/index.js

@@ -0,0 +1,286 @@
+import { Service } from "@deepseek-ai/cordis";
+import z from "@deepseek-ai/schemastery";
+import { snapshotJsonValue } from "@deepseek-ai/dsh-session";
+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
+* {@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`).
+* @module @deepseek-ai/dsh-session-projection-cache/src/spec
+*/
+/**
+* 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
+* JSON by the unit contract; `z.json()` enforces that at the durable
+* boundary. A row is never wrong, only possibly stale: `seq` says exactly
+* how stale, and a `ver` mismatch against the live unit's `stateVersion`
+* discards it at read time (never a migration).
+*/
+const checkpointRow = z$1.object({
+	ver: z$1.number().int().nonnegative(),
+	seq: z$1.number().int().gte(-1),
+	val: z$1.json()
+});
+/**
+* The stored-log identity a record is bound to: the immutable header fields
+* 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.
+*/
+const checkpointIdentity = z$1.object({
+	createdAt: z$1.number().int().nonnegative(),
+	cwd: z$1.string().optional()
+});
+/**
+* One session's stored record: the log identity it was folded from plus its
+* checkpoint rows keyed by projection key. The whole record is replaced on
+* every write (whole-value discipline — the registry checkpoint is always
+* the complete per-session cut).
+*/
+const checkpointRecord = z$1.object({
+	identity: checkpointIdentity,
+	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).
+*/
+const projectionCacheDomainSpec = defineDomain({
+	name: "session_projcache",
+	version: 3,
+	tables: { sessions: domainTable(checkpointRecord) }
+});
+//#endregion
+//#region lib/types/index.js
+/**
+* Persisted projection cache (`ctx.sessionProjectionCache`): durable
+* checkpoints of every registered 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
+* (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
+* @module @deepseek-ai/dsh-session-projection-cache
+*/
+const Config = z.object({
+	writeEveryEvents: z.natural().min(1).required(),
+	writeIntervalMs: z.natural().min(1).required()
+});
+/**
+* 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.
+*/
+var SessionProjectionCache = class extends Service {
+	config;
+	static inject = [
+		"storageDomain",
+		"sessionProjections",
+		"sessionPersistence",
+		"sessions"
+	];
+	static Config = Config;
+	table;
+	dirty = /* @__PURE__ */ new Map();
+	constructor(ctx, config) {
+		super(ctx, "sessionProjectionCache");
+		this.config = config;
+	}
+	/** Open the domain and install the write-behind listeners. */
+	async [Service.init]() {
+		const domain = await this.ctx.storageDomain.open(projectionCacheDomainSpec);
+		this.ctx.effect(() => () => domain.close(), "sessionProjectionCache.domainClose");
+		this.table = domain.table("sessions");
+		this.installWritePath();
+	}
+	/**
+	* The stored record for one session, accepted only when its bound log
+	* 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.
+	* @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).
+	*/
+	recordFor(id, expected) {
+		const record = this.requireTable().get(id);
+		if (record === void 0) return void 0;
+		return identityMatches(record.identity, expected) ? record : void 0;
+	}
+	/**
+	* 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) {
+		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;
+		return {
+			asOfSeq: Math.min(...keys.map((key) => record.rows[key].seq)),
+			values
+		};
+	}
+	/**
+	* 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) {
+		const rows = this.ctx.sessionProjections.checkpoint(session);
+		this.markClean(session);
+		if (this.ctx.sessions.get(session.id) === session) await this.ctx.sessions.flush(session);
+		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.
+	*/
+	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");
+		return restored.snapshot;
+	}
+	installWritePath() {
+		this.ctx.on("session/event", (session, event) => {
+			if (event.type === "turn/end") {
+				this.flushSoft(session, "turn/end");
+				return;
+			}
+			const state = this.dirty.get(session) ?? {
+				pending: 0,
+				timer: void 0
+			};
+			this.dirty.set(session, state);
+			state.pending += 1;
+			if (state.pending >= this.config.writeEveryEvents) {
+				this.flushSoft(session, "count threshold");
+				return;
+			}
+			state.timer ??= setTimeout(() => {
+				this.flushSoft(session, "interval");
+			}, this.config.writeIntervalMs);
+		});
+		this.ctx.on("session/disposed", (session) => {
+			this.flushSoft(session, "detach");
+			this.markClean(session);
+			this.dirty.delete(session);
+		});
+		this.ctx.effect(() => () => {
+			for (const state of this.dirty.values()) if (state.timer !== void 0) clearTimeout(state.timer);
+			this.dirty.clear();
+		}, "sessionProjectionCache.timers");
+	}
+	/**
+	* 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.
+	*/
+	async flushSoft(session, trigger) {
+		try {
+			await this.write(session);
+		} catch (error) {
+			this.ctx.logger.warn(`session projection cache: ${trigger} write for "${session.id}" failed (cache stays stale): ${String(error)}`);
+		}
+	}
+	/** Reset one session's dirty bookkeeping (its checkpoint is being written). */
+	markClean(session) {
+		const state = this.dirty.get(session);
+		if (state === void 0) return;
+		state.pending = 0;
+		if (state.timer !== void 0) {
+			clearTimeout(state.timer);
+			state.timer = void 0;
+		}
+	}
+	/** Replace one session's stored record with its log identity and a detached snapshot of `rows`. */
+	async put(id, identity, rows) {
+		const detached = snapshotJsonValue(rows);
+		if (detached === void 0) throw new TypeError("projection checkpoint is not losslessly JSON-serializable (a unit state violates the plain-JSON contract)");
+		await this.requireTable().put(id, {
+			identity,
+			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");
+		return this.table;
+	}
+};
+/** Project a header onto the identity fields a record is bound to. */
+function identityOf(header) {
+	return {
+		createdAt: header.createdAt,
+		...header.cwd === void 0 ? {} : { cwd: header.cwd }
+	};
+}
+/** Whether a stored record's bound identity names the caller's lifecycle. */
+function identityMatches(stored, expected) {
+	return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd;
+}
+//#endregion
+export { Config, SessionProjectionCache, SessionProjectionCache as default, checkpointIdentity, checkpointRecord, checkpointRow, projectionCacheDomainSpec };

package/lib/invariant.js

@@ -0,0 +1,28 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-session-projection-cache`.
+* @module @deepseek-ai/dsh-session-projection-cache/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-session-projection-cache";
+/** Cordis companion plugin name. */
+const name = "session-projection-cache-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: the cache's correctness relation (a stored row equals
+* 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
+* by the package spec.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Persisted projection cache (`ctx.sessionProjectionCache`): durable
+ * checkpoints of every registered 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
+ * (.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';
+export { checkpointIdentity, checkpointRecord, checkpointRow, projectionCacheDomainSpec } from './spec.ts';
+export type { CheckpointIdentity, CheckpointRecord } from './spec.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        sessionProjectionCache: SessionProjectionCache;
+    }
+}
+/**
+ * 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.
+ */
+export interface Config {
+    /** Committed events per session that force a durable checkpoint write between mandatory points. */
+    writeEveryEvents: number;
+    /** Longest time (milliseconds) a dirty checkpoint may stay unwritten between mandatory points. */
+    writeIntervalMs: number;
+}
+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.
+ */
+export declare class SessionProjectionCache extends Service {
+    config: Config;
+    static inject: string[];
+    static Config: z<Config>;
+    private table?;
+    private readonly dirty;
+    constructor(ctx: Context, config: Config);
+    /** Open the domain and install the write-behind listeners. */
+    protected [Service.init](): Promise<void>;
+    /**
+     * The stored record for one session, accepted only when its bound log
+     * 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.
+     * @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).
+     */
+    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
+     * 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.
+     */
+    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.
+     */
+    coldSnapshot(id: SessionId, signal?: AbortSignal): Promise<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.
+     */
+    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;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-projection-cache`.
+ * @module @deepseek-ai/dsh-session-projection-cache/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "session-projection-cache-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/spec.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The session-projcache 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`).
+ * @module @deepseek-ai/dsh-session-projection-cache/src/spec
+ */
+import { z } from 'zod';
+import { 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
+ * JSON by the unit contract; `z.json()` enforces that at the durable
+ * boundary. A row is never wrong, only possibly stale: `seq` says exactly
+ * how stale, and a `ver` mismatch against the live unit's `stateVersion`
+ * discards it at read time (never a migration).
+ */
+export declare const checkpointRow: z.ZodObject<{
+    ver: z.ZodNumber;
+    seq: z.ZodNumber;
+    val: z.ZodJSONSchema;
+}, z.core.$strip>;
+/**
+ * The stored-log identity a record is bound to: the immutable header fields
+ * 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.
+ */
+export declare const checkpointIdentity: z.ZodObject<{
+    createdAt: z.ZodNumber;
+    cwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** The identity fields a record is bound to, inferred from {@link checkpointIdentity}. */
+export type CheckpointIdentity = z.infer<typeof checkpointIdentity>;
+/**
+ * One session's stored record: the log identity it was folded from plus its
+ * checkpoint rows keyed by projection key. The whole record is replaced on
+ * every write (whole-value discipline — the registry checkpoint is always
+ * the complete per-session cut).
+ */
+export declare const checkpointRecord: z.ZodObject<{
+    identity: z.ZodObject<{
+        createdAt: z.ZodNumber;
+        cwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    rows: z.ZodRecord<z.ZodString, z.ZodObject<{
+        ver: z.ZodNumber;
+        seq: z.ZodNumber;
+        val: z.ZodJSONSchema;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** 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).
+ */
+export declare const projectionCacheDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<SessionId, {
+            identity: {
+                createdAt: number;
+                cwd?: string | undefined;
+            };
+            rows: Record<string, {
+                ver: number;
+                seq: number;
+                val: z.core.util.JSONType;
+            }>;
+        }>;
+    };
+};
+//# sourceMappingURL=spec.d.ts.map

package/package.json

@@ -0,0 +1,55 @@
+{
+  "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.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/session/session-projection-cache"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.0.1-rc.1"
+  }
+}