@deepseek-ai/dsh-session-projection-cache 0.1.2-alpha.3 → 0.1.2-alpha.5

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: c5e438a2ededef00a1faa456e9913492a603b51d
-README.zh.md: eab0b81af618558e6f1e5e6bc0c40da3fcc38884
+README.md: 9fd9766d75ab3f9a460b2802ac59810839f21ae4
+README.zh.md: 98725d9ce76ab44821adf3d43e3807932cf6b675

package/README.md

@@ -58,11 +58,13 @@ Three mandatory points always write: session creation persists the seed-derived
 
 ### 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.
+`cachedSnapshot(meta, inheritedEventCount)` 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. An unseeded listing knows that its cut is zero; a seeded header-only listing does not know the numeric cut and must skip this fast path until an authoritative body read supplies it. `coldSnapshot(meta, inheritedEventCount, events)` accepts the exact cut with a complete ordered log, skips the checkpointed prefix while folding, and refreshes the record without reading persistence 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.
+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 complete lifecycle identity (`createdAt`, `cwd`, `isSeeded`, and `inheritedEventCount`), so a row initialized under one fork cut cannot seed another. The JSON backend stores each record at `<root>/session_projcache/sessions/<id>.json` in an owner-only directory tree.
+
+Upgrades never cost the boot or the listing: records stamped with a version in the spec's `compatibleVersions` stay readable (their absent lineage fields decode as the unseeded lineage — exact for unseeded sessions, while a seeded caller fails the identity match and refolds cold), and a stored record that still fails schema validation is moved aside as `<id>.json.bak.<stamp>` under the domain's `invalidRecords: 'backup-and-skip'` policy, logged with its cause, and rebuilt by the next checkpoint.
 
 -----
 
@@ -88,7 +90,7 @@ The cache stores one version-stamped document per session in the `session_projca
 |---|---|
 | [`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) |
+| — | No runtime invariant companion is published; 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 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. |
 
 </details>
 
@@ -126,6 +128,7 @@ These limits define where the cache needs operational care. They are current pac
 - **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.
 - **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.
+- **Every schema or domain-version change must prove its upgrade story** — a change to the stored record schema or the domain version lands in the same PR with an archived fixture of the previously shipped on-disk format under `tests/fixtures/` and test cases in `tests/fixtures.spec.ts` proving the chosen disposition: read-compat recovery (`compatibleVersions`), current-version rewrite, or backup-and-skip salvage. A bump whose old records are simply discarded still proves that the discard neither fails the boot nor poisons the tree.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -58,11 +58,13 @@ kind: "package-reference"
 
 ### 读取缓存值
 
-`cachedSnapshot(meta)` 以零 I/O 从存储域的内存表同步提供客户端值。它只接受身份匹配的记录以及版本和 schema 均匹配的 key，再按所服务行的最低水位返回 `{ asOfSeq, values }` 切面。对于未知 id、无关生命周期、缺失或外来的记录文档，或没有可用行的情况，它返回 `undefined`。`coldSnapshot(meta, events)` 接受完整有序日志，在折叠时跳过已检查点化的前缀，并在自身不读取持久化层的情况下刷新记录。
+`cachedSnapshot(meta, inheritedEventCount)` 以零 I/O 从存储域的内存表同步提供客户端值。它只接受身份匹配的记录以及版本和 schema 均匹配的 key，再按所服务行的最低水位返回 `{ asOfSeq, values }` 切面。未 seeded 的列表知道切点为零；仅 header 的 seeded 列表不知道数字切点，必须跳过该快速路径，直到权威正文读取提供它。`coldSnapshot(meta, inheritedEventCount, events)` 接受精确切点与完整有序日志，在折叠时跳过已检查点化的前缀，并在自身不读取持久化层的情况下刷新记录。
 
 ### 缓存保证什么
 
-日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与会话 header 身份（`createdAt`、`cwd`），因此畸形、陈旧或无关的记录都会读作不存在。JSON 后端把每条记录存于仅所有者可访问的 `<root>/session_projcache/sessions/<id>.json` 目录树中。
+日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与完整生命周期身份（`createdAt`、`cwd`、`isSeeded` 和 `inheritedEventCount`），因此在一个 fork 切点下初始化的行不能播种另一个切点。JSON 后端把每条记录存于仅所有者可访问的 `<root>/session_projcache/sessions/<id>.json` 目录树中。
+
+升级绝不拖垮启动或列表：版本戳落在 spec `compatibleVersions` 集合内的记录保持可读（缺失的 lineage 字段解码为 unseeded lineage——对非 fork 会话精确无误，seeded 调用方则通不过身份比对、回落冷折叠），而仍然通不过 schema 校验的存量记录会按域的 `invalidRecords: 'backup-and-skip'` 策略移出为 `<id>.json.bak.<时间戳>`、连同原因写入日志，并由下一次检查点重建。
 
 -----
 
@@ -88,7 +90,7 @@ kind: "package-reference"
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：`SessionProjectionCache` 服务、写后监听器、缓存读取 |
 | [`src/spec.ts`](src/spec.ts) | `session_projcache` 域 spec 与记录身份类型 |
-| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；正确性在写入与读取路径强制） |
+| — | 不发布运行时不变式伴生入口；正确性在写入与读取路径强制。 |
 
 </details>
 
@@ -126,6 +128,7 @@ kind: "package-reference"
 - **无淘汰或保留接口**——记录按会话持续累积；清理已存储检查点属于带外维护，与会话持久化采用相同策略。
 - **间隔节流采用按会话的粗粒度控制**——一次无脏数据的写入完成后，计时器在首个脏事件到达时启动；持续但低于条数阈值的事件流每间隔写入一次，而非滑动窗口。
 - **缓存侧不做冷重折叠**——缓存只服务并刷新自己的记录，从不读取会话日志，因为它不依赖持久化层；需要保证冷快照的消费方自行从日志重新折叠。
+- **每次 schema 或域版本变更都必须论证升级路径**——改动存储记录 schema 或域版本时，同一 PR 必须在 `tests/fixtures/` 下归档此前已发布的磁盘格式样本，并在 `tests/fixtures.spec.ts` 中用测试论证所选的处置方式：读兼容恢复（`compatibleVersions`）、当前版本重写，或 backup-and-skip 抢救。即便选择直接丢弃旧记录的 bump，也要证明丢弃既不炸启动、也不污染缓存树。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -1,6 +1,7 @@
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
+import { SessionLogOffset, SessionSeq } 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
@@ -25,7 +26,7 @@ import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 */
 const checkpointRow = z$1.object({
 	ver: z$1.number().int().nonnegative(),
-	seq: z$1.number().int().gte(-1),
+	seq: z$1.number().int().gte(-1).transform((value) => value === -1 ? -1 : SessionSeq(value)),
 	val: z$1.json()
 });
 /**
@@ -36,10 +37,19 @@ const checkpointRow = z$1.object({
 * 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.
+*
+* The lineage fields are optional because records admitted through
+* `compatibleVersions` predate them. The reader (`identityMatches`)
+* interprets their absence as the unseeded lineage — exact for an unseeded
+* session, while a seeded expectation fails the match and the record is
+* discarded to a cold rebuild. Current-version writes always store both
+* fields.
 */
 const checkpointIdentity = z$1.object({
 	createdAt: z$1.number().int().nonnegative(),
-	cwd: z$1.string().optional()
+	cwd: z$1.string().optional(),
+	isSeeded: z$1.boolean().optional(),
+	inheritedEventCount: z$1.number().int().nonnegative().transform(SessionLogOffset).optional()
 });
 /**
 * One session's stored record: the log identity it was folded from plus its
@@ -56,11 +66,27 @@ const checkpointRecord = z$1.object({
 * 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.
+* instead of rejecting the whole medium. The `compatibleVersions` entries
+* are declared because those records differ from the current version only
+* by the absent optional lineage fields, so upgraded homes keep serving
+* their cached listing projections instead of dropping every title until
+* each session is reopened; the per-record version map lives in the
+* read-compat Agent Note
+* (.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md).
+* The per-row `ver` guard and the identity match still discard anything the
+* current fold semantics cannot vouch for.
+*
+* `invalidRecords: 'backup-and-skip'`: a stored record that fails the schema
+* anyway is disposable derived data, so it must never cost the boot — the
+* domain layer moves the document aside as `<key>.json.bak.<stamp>`, logs
+* the concrete validation failure, and serves the session as uncached (a
+* cold read rebuilds and rewrites it).
 */
 const projectionCacheDomainSpec = defineDomain({
 	name: "session_projcache",
-	version: 4,
+	version: 5,
+	compatibleVersions: [3, 4],
+	invalidRecords: "backup-and-skip",
 	layout: "per-record",
 	tables: { sessions: domainTable(checkpointRecord) }
 });
@@ -143,18 +169,27 @@ var SessionProjectionCache = class extends Service {
 	* 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 inheritedEventCount - exact inherited prefix length that completes
+	* the checkpoint identity.
 	* @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, keys) {
-		const record = this.recordFor(meta.id, identityOf(meta));
+	cachedSnapshot(meta, inheritedEventCount, keys) {
+		const record = this.recordFor(meta.id, identityOf(meta, inheritedEventCount));
 		if (record === void 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;
+		let asOfSeq;
+		for (const key of servedKeys) {
+			const row = record.rows[key];
+			if (row !== void 0 && (asOfSeq === void 0 || row.seq < asOfSeq)) asOfSeq = row.seq;
+		}
+		/* v8 ignore next -- A nonempty checkpoint view contains a stored row for every returned key. */
+		if (asOfSeq === void 0) return void 0;
 		return {
-			asOfSeq: Math.min(...servedKeys.map((key) => record.rows[key].seq)),
+			asOfSeq,
 			values
 		};
 	}
@@ -164,17 +199,16 @@ var SessionProjectionCache = class extends Service {
 	* 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);
+	hydratePrepared(session, events) {
+		const record = this.recordFor(session.id, identityOf(session.header, session.inheritedEventCount));
+		if (record === void 0) return this.ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0));
 		try {
-			return this.ctx.sessionProjections.hydrate(session, record.rows, events, 0);
+			return this.ctx.sessionProjections.hydrate(session, record.rows, events, SessionLogOffset(0));
 		} catch {
-			return this.ctx.sessionProjections.hydrate(session, {}, events, 0);
+			return this.ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0));
 		}
 	}
 	/**
@@ -190,7 +224,7 @@ var SessionProjectionCache = class extends Service {
 		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);
+		await this.put(session.id, identityOf(session.header, session.inheritedEventCount), rows);
 	}
 	/**
 	* Cold-read one session's projections from its complete log. Each unit is
@@ -201,12 +235,14 @@ var SessionProjectionCache = class extends Service {
 	* 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 inheritedEventCount - exact inherited prefix length for projection initialization and identity.
 	* @param events - the session's complete log, in seq order.
 	* @returns the projection cut at the log end.
 	*/
-	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) => {
+	coldSnapshot(meta, inheritedEventCount, events) {
+		const identity = identityOf(meta, inheritedEventCount);
+		const restored = this.ctx.sessionProjections.restore(this.recordFor(meta.id, identity)?.rows ?? {}, events, SessionLogOffset(0), meta, inheritedEventCount);
+		this.put(meta.id, identity, 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;
@@ -282,15 +318,25 @@ var SessionProjectionCache = class extends Service {
 	}
 };
 /** Project a header onto the identity fields a record is bound to. */
-function identityOf(header) {
+function identityOf(header, inheritedEventCount) {
+	const cut = SessionLogOffset(inheritedEventCount);
+	if (!header.isSeeded && cut !== 0) throw new Error("unseeded projection-cache identity inherited event count must be 0");
 	return {
 		createdAt: header.createdAt,
-		...header.cwd === void 0 ? {} : { cwd: header.cwd }
+		...header.cwd === void 0 ? {} : { cwd: header.cwd },
+		isSeeded: header.isSeeded,
+		inheritedEventCount: cut
 	};
 }
-/** Whether a stored record's bound identity names the caller's lifecycle. */
+/**
+* Whether a stored record's bound identity names the caller's lifecycle.
+* Absent lineage fields (records admitted via `compatibleVersions` predate
+* them) read as the unseeded lineage: exact for an unseeded caller, and a
+* seeded caller's expectation then fails the match, discarding the record to
+* a cold rebuild.
+*/
 function identityMatches(stored, expected) {
-	return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd;
+	return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd && (stored.isSeeded ?? false) === expected.isSeeded && (stored.inheritedEventCount ?? 0) === expected.inheritedEventCount;
 }
 //#endregion
 export { Config, SessionProjectionCache, SessionProjectionCache as default, checkpointIdentity, checkpointRecord, checkpointRow, projectionCacheDomainSpec };

package/lib/types/index.d.ts

@@ -17,6 +17,7 @@
  */
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { SessionLogOffset } from '@deepseek-ai/dsh-session';
 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';
@@ -80,22 +81,23 @@ export declare class SessionProjectionCache extends Service {
      * 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 inheritedEventCount - exact inherited prefix length that completes
+     * the checkpoint identity.
      * @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, keys?: readonly Extract<keyof SessionProjectionMap, string>[]): ProjectionSnapshot | undefined;
+    cachedSnapshot(meta: SessionHeader, inheritedEventCount: SessionLogOffset, keys?: readonly Extract<keyof SessionProjectionMap, string>[]): ProjectionSnapshot | undefined;
     /**
      * 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;
+    hydratePrepared(session: Session, 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
@@ -115,10 +117,11 @@ export declare class SessionProjectionCache extends Service {
      * 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 inheritedEventCount - exact inherited prefix length for projection initialization and identity.
      * @param events - the session's complete log, in seq order.
      * @returns the projection cut at the log end.
      */
-    coldSnapshot(meta: SessionHeader, events: readonly SessionEvent[]): ProjectionSnapshot;
+    coldSnapshot(meta: SessionHeader, inheritedEventCount: SessionLogOffset, events: readonly SessionEvent[]): ProjectionSnapshot;
     private installWritePath;
     /**
      * One fail-soft durable checkpoint. Every caller has work by construction:

package/lib/types/spec.d.ts

@@ -10,6 +10,7 @@
  * @module @deepseek-ai/dsh-session-projection-cache/src/spec
  */
 import { z } from 'zod';
+import { SessionLogOffset, SessionSeq } 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)`
@@ -21,7 +22,7 @@ import type { SessionId } from '@deepseek-ai/dsh-session';
  */
 export declare const checkpointRow: z.ZodObject<{
     ver: z.ZodNumber;
-    seq: z.ZodNumber;
+    seq: z.ZodPipe<z.ZodNumber, z.ZodTransform<-1 | SessionSeq, number>>;
     val: z.ZodJSONSchema;
 }, z.core.$strip>;
 /**
@@ -32,10 +33,19 @@ export declare const checkpointRow: z.ZodObject<{
  * 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.
+ *
+ * The lineage fields are optional because records admitted through
+ * `compatibleVersions` predate them. The reader (`identityMatches`)
+ * interprets their absence as the unseeded lineage — exact for an unseeded
+ * session, while a seeded expectation fails the match and the record is
+ * discarded to a cold rebuild. Current-version writes always store both
+ * fields.
  */
 export declare const checkpointIdentity: z.ZodObject<{
     createdAt: z.ZodNumber;
     cwd: z.ZodOptional<z.ZodString>;
+    isSeeded: z.ZodOptional<z.ZodBoolean>;
+    inheritedEventCount: z.ZodOptional<z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionLogOffset, number>>>;
 }, z.core.$strip>;
 /** The identity fields a record is bound to, inferred from {@link checkpointIdentity}. */
 export type CheckpointIdentity = z.infer<typeof checkpointIdentity>;
@@ -49,10 +59,12 @@ export declare const checkpointRecord: z.ZodObject<{
     identity: z.ZodObject<{
         createdAt: z.ZodNumber;
         cwd: z.ZodOptional<z.ZodString>;
+        isSeeded: z.ZodOptional<z.ZodBoolean>;
+        inheritedEventCount: z.ZodOptional<z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionLogOffset, number>>>;
     }, z.core.$strip>;
     rows: z.ZodRecord<z.ZodString, z.ZodObject<{
         ver: z.ZodNumber;
-        seq: z.ZodNumber;
+        seq: z.ZodPipe<z.ZodNumber, z.ZodTransform<-1 | SessionSeq, number>>;
         val: z.ZodJSONSchema;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -63,21 +75,39 @@ export type CheckpointRecord = z.infer<typeof checkpointRecord>;
  * 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.
+ * instead of rejecting the whole medium. The `compatibleVersions` entries
+ * are declared because those records differ from the current version only
+ * by the absent optional lineage fields, so upgraded homes keep serving
+ * their cached listing projections instead of dropping every title until
+ * each session is reopened; the per-record version map lives in the
+ * read-compat Agent Note
+ * (.agents/notes/implemented/architecture/2026-09-02-projcache-cross-version-read-compat.md).
+ * The per-row `ver` guard and the identity match still discard anything the
+ * current fold semantics cannot vouch for.
+ *
+ * `invalidRecords: 'backup-and-skip'`: a stored record that fails the schema
+ * anyway is disposable derived data, so it must never cost the boot — the
+ * domain layer moves the document aside as `<key>.json.bak.<stamp>`, logs
+ * the concrete validation failure, and serves the session as uncached (a
+ * cold read rebuilds and rewrites it).
  */
 export declare const projectionCacheDomainSpec: {
     name: string;
     version: number;
+    compatibleVersions: number[];
+    invalidRecords: "backup-and-skip";
     layout: "per-record";
     tables: {
         sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<SessionId, {
             identity: {
                 createdAt: number;
                 cwd?: string | undefined;
+                isSeeded?: boolean | undefined;
+                inheritedEventCount?: SessionLogOffset | undefined;
             };
             rows: Record<string, {
                 ver: number;
-                seq: number;
+                seq: -1 | SessionSeq;
                 val: z.core.util.JSONType;
             }>;
         }>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-projection-cache",
   "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.3",
+  "version": "0.1.2-alpha.5",
   "publishConfig": {
     "access": "public"
   },
@@ -18,38 +18,31 @@
       "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": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.3"
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.5",
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.3"
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.5"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.3",
-    "@deepseek-ai/dsh-storage-json": "^0.1.2-alpha.3"
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-storage": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-storage-json": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.5"
   }
 }

package/lib/invariant.js

@@ -1,28 +0,0 @@
-//#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 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 = () => {};
-/**
-* 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/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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