@deepseek-ai/dsh-session-projection-cache 0.1.2-alpha.5 → 0.1.3-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: 9fd9766d75ab3f9a460b2802ac59810839f21ae4
-README.zh.md: 98725d9ce76ab44821adf3d43e3807932cf6b675
+README.md: ba90e838763787d28e5b6e278d868504fc672c5f
+README.zh.md: 8b3fe4148d408af75194212e4787a7cdb9030507

package/README.md

@@ -58,13 +58,13 @@ Three mandatory points always write: session creation persists the seed-derived
 
 ### Reading cached values
 
-`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.
+`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. `cachedPredecessorTitle(meta, inheritedEventCount)` is the narrower listing-only exception: a structurally admitted predecessor record whose lifecycle matches may expose only a current-version-compatible `title` row. The title is a possibly stale fact from a durable prefix, not a fold seed; it carries the sentinel `asOfSeq: -1` because a cardinality-changing Session migration can invalidate the predecessor row's numeric sequence. All other predecessor rows remain unavailable. An unseeded listing knows that its cut is zero; a seeded header-only listing does not know the numeric cut and skips both fast paths 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 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.
+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 (`formatVersion`, `createdAt`, `cwd`, `isSeeded`, and `inheritedEventCount`), so a row folded from another Session format generation or fork cut cannot seed the caller. 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.
+Upgrades never cost the boot or expose an unproven fold. Records stamped with a version in the spec's `compatibleVersions` remain structurally readable for a current checkpoint rewrite, but a missing or older `formatVersion` never matches a current Session and therefore cannot seed hydration. A lifecycle-matching predecessor title remains available only through the listing hint above because title text is invariant across the adjacent Session-format edges and its row still passes the current projection `stateVersion` and schema. Once the format matches, absent lineage fields decode as the unseeded lineage — exact for unseeded sessions, while a seeded caller fails the identity match and refolds cold. 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.
 
 -----
 

package/README.zh.md

@@ -58,13 +58,13 @@ kind: "package-reference"
 
 ### 读取缓存值
 
-`cachedSnapshot(meta, inheritedEventCount)` 以零 I/O 从存储域的内存表同步提供客户端值。它只接受身份匹配的记录以及版本和 schema 均匹配的 key，再按所服务行的最低水位返回 `{ asOfSeq, values }` 切面。未 seeded 的列表知道切点为零；仅 header 的 seeded 列表不知道数字切点，必须跳过该快速路径，直到权威正文读取提供它。`coldSnapshot(meta, inheritedEventCount, events)` 接受精确切点与完整有序日志，在折叠时跳过已检查点化的前缀，并在自身不读取持久化层的情况下刷新记录。
+`cachedSnapshot(meta, inheritedEventCount)` 以零 I/O 从存储域的内存表同步提供客户端值。它只接受身份匹配的记录以及版本和 schema 均匹配的 key，再按所服务行的最低水位返回 `{ asOfSeq, values }` 切面。`cachedPredecessorTitle(meta, inheritedEventCount)` 是更窄的列表专用例外：生命周期匹配且已通过结构准入的 predecessor record 只能公开与当前版本兼容的 `title` row。该 title 是 durable prefix 中可能过时的事实，而不是 fold seed；它携带 sentinel `asOfSeq: -1`，因为改变事件数量的 Session 迁移会使 predecessor row 的数字序号失效。其他 predecessor row 仍不可用。未 seeded 的列表知道切点为零；仅 header 的 seeded 列表不知道数字切点，因此两条快速路径都要跳过，直到权威正文读取提供它。`coldSnapshot(meta, inheritedEventCount, events)` 接受精确切点与完整有序日志，在折叠时跳过已检查点化的前缀，并在自身不读取持久化层的情况下刷新记录。
 
 ### 缓存保证什么
 
-日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与完整生命周期身份（`createdAt`、`cwd`、`isSeeded` 和 `inheritedEventCount`），因此在一个 fork 切点下初始化的行不能播种另一个切点。JSON 后端把每条记录存于仅所有者可访问的 `<root>/session_projcache/sessions/<id>.json` 目录树中。
+日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 schema 与完整生命周期身份（`formatVersion`、`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.<时间戳>`、连同原因写入日志，并由下一次检查点重建。
+升级绝不拖垮启动，也不会暴露未经证明的折叠结果。版本戳落在 spec `compatibleVersions` 集合内的记录仍可被结构化读取并等待当前检查点重写，但缺失或更旧的 `formatVersion` 绝不匹配当前 Session，因此不能作为 hydrate seed。生命周期匹配的 predecessor title 只能通过上述列表 hint 读取，因为 title 文本在相邻 Session format edge 之间保持不变，并且该 row 仍须通过当前 projection `stateVersion` 与 schema。格式匹配后，缺失的 lineage 字段解码为 unseeded lineage——对非 fork 会话精确无误，seeded 调用方则通不过身份比对、回落冷折叠。仍然通不过 schema 校验的存量记录会按域的 `invalidRecords: 'backup-and-skip'` 策略移出为 `<id>.json.bak.<时间戳>`、连同原因写入日志，并由下一次检查点重建。
 
 -----
 

package/lib/index.js

@@ -38,14 +38,15 @@ const checkpointRow = z$1.object({
 * 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
+* The format and lineage fields are optional because records admitted through
+* `compatibleVersions` predate them. The reader (`identityMatches`) refuses an
+* absent format generation because no current Session log can prove that
+* record's fold semantics. It interprets absent lineage as unseeded only after
+* the format generation matches. Current-version writes always store all three
 * fields.
 */
 const checkpointIdentity = z$1.object({
+	formatVersion: z$1.number().int().nonnegative().optional(),
 	createdAt: z$1.number().int().nonnegative(),
 	cwd: z$1.string().optional(),
 	isSeeded: z$1.boolean().optional(),
@@ -67,15 +68,18 @@ const checkpointRecord = z$1.object({
 * 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. 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
+* keep structurally valid predecessor records available for a later current
+* checkpoint rewrite. Records without `formatVersion` remain unusable as fold
+* shortcuts because they cannot prove which Session event semantics produced
+* their rows; the per-record version map and disposition live 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.
 *
+* A lifecycle-matching predecessor may still expose its version-compatible
+* title through the cache service's listing-only hint; this never relaxes the
+* format requirement for hydration or another fold shortcut.
+*
 * `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
@@ -84,8 +88,13 @@ const checkpointRecord = z$1.object({
 */
 const projectionCacheDomainSpec = defineDomain({
 	name: "session_projcache",
-	version: 5,
-	compatibleVersions: [3, 4],
+	version: 7,
+	compatibleVersions: [
+		3,
+		4,
+		5,
+		6
+	],
 	invalidRecords: "backup-and-skip",
 	layout: "per-record",
 	tables: { sessions: domainTable(checkpointRecord) }
@@ -109,6 +118,7 @@ const projectionCacheDomainSpec = defineDomain({
 * (.agents/notes/proposed/architecture/2026-07-27-session-projection-and-command-log.md).
 * @module @deepseek-ai/dsh-session-projection-cache
 */
+const PREDECESSOR_TITLE_KEY = "title";
 const Config = z.object({
 	writeEveryEvents: z.natural().min(1).required(),
 	writeIntervalMs: z.natural().min(1).required()
@@ -178,16 +188,46 @@ var SessionProjectionCache = class extends Service {
 	cachedSnapshot(meta, inheritedEventCount, keys) {
 		const record = this.recordFor(meta.id, identityOf(meta, inheritedEventCount));
 		if (record === void 0) return void 0;
+		return this.viewRecord(record, keys);
+	}
+	/**
+	* Read only a predecessor checkpoint's title as a zero-I/O listing hint.
+	*
+	* The authoritative Session header supplies the lifecycle identity. A cache
+	* checkpoint can lag that log but cannot lead it because writes flush the
+	* log first, so a matching predecessor title is a genuine (possibly stale)
+	* fact from this Session. The registry still requires the current title
+	* projection's row version and schema. No other predecessor projection is
+	* exposed: format normalization can change their current meaning, and the
+	* strict {@link cachedSnapshot} / hydration paths continue to reject them.
+	* @param meta - authoritative listed Session header.
+	* @param inheritedEventCount - exact inherited cut completing the lifecycle identity.
+	* @returns a title-only checkpoint view with `asOfSeq: -1`, or `undefined`
+	*   when the record is current, newer, unrelated, missing, or incompatible
+	*   with the title unit. The sentinel avoids reusing a sequence that a
+	*   cardinality-changing Session migration may have remapped.
+	*/
+	cachedPredecessorTitle(meta, inheritedEventCount) {
+		const expected = identityOf(meta, inheritedEventCount);
+		const record = this.requireTable().get(meta.id);
+		if (record === void 0 || !predecessorIdentityMatches(record.identity, expected)) return void 0;
+		const title = this.viewRecord(record, [PREDECESSOR_TITLE_KEY]);
+		return title === void 0 ? void 0 : {
+			...title,
+			asOfSeq: -1
+		};
+	}
+	/** View selected wire rows and bind them to their lowest served watermark. */
+	viewRecord(record, keys) {
 		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 firstKey = servedKeys[0];
+		let asOfSeq = record.rows[firstKey].seq;
+		for (const key of servedKeys.slice(1)) {
 			const row = record.rows[key];
-			if (row !== void 0 && (asOfSeq === void 0 || row.seq < asOfSeq)) asOfSeq = row.seq;
+			if (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,
 			values
@@ -322,6 +362,7 @@ 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 {
+		formatVersion: header.version,
 		createdAt: header.createdAt,
 		...header.cwd === void 0 ? {} : { cwd: header.cwd },
 		isSeeded: header.isSeeded,
@@ -330,12 +371,20 @@ function identityOf(header, inheritedEventCount) {
 }
 /**
 * 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.
+* An absent format generation cannot prove the fold semantics and never
+* matches. Once the format matches, absent lineage fields (records admitted
+* via `compatibleVersions` predate them) read as the unseeded lineage: exact
+* for an unseeded caller, while a seeded caller fails the match.
 */
 function identityMatches(stored, expected) {
+	return stored.formatVersion === expected.formatVersion && lifecycleIdentityMatches(stored, expected);
+}
+/** Match one predecessor cache record to the authoritative listed lifecycle. */
+function predecessorIdentityMatches(stored, expected) {
+	return (stored.formatVersion === void 0 || stored.formatVersion < expected.formatVersion) && lifecycleIdentityMatches(stored, expected);
+}
+/** Match the format-independent fields that distinguish one Session lifecycle. */
+function lifecycleIdentityMatches(stored, expected) {
 	return stored.createdAt === expected.createdAt && stored.cwd === expected.cwd && (stored.isSeeded ?? false) === expected.isSeeded && (stored.inheritedEventCount ?? 0) === expected.inheritedEventCount;
 }
 //#endregion

package/lib/types/index.d.ts

@@ -88,6 +88,26 @@ export declare class SessionProjectionCache extends Service {
      *   `undefined` when no usable row exists for this lifecycle.
      */
     cachedSnapshot(meta: SessionHeader, inheritedEventCount: SessionLogOffset, keys?: readonly Extract<keyof SessionProjectionMap, string>[]): ProjectionSnapshot | undefined;
+    /**
+     * Read only a predecessor checkpoint's title as a zero-I/O listing hint.
+     *
+     * The authoritative Session header supplies the lifecycle identity. A cache
+     * checkpoint can lag that log but cannot lead it because writes flush the
+     * log first, so a matching predecessor title is a genuine (possibly stale)
+     * fact from this Session. The registry still requires the current title
+     * projection's row version and schema. No other predecessor projection is
+     * exposed: format normalization can change their current meaning, and the
+     * strict {@link cachedSnapshot} / hydration paths continue to reject them.
+     * @param meta - authoritative listed Session header.
+     * @param inheritedEventCount - exact inherited cut completing the lifecycle identity.
+     * @returns a title-only checkpoint view with `asOfSeq: -1`, or `undefined`
+     *   when the record is current, newer, unrelated, missing, or incompatible
+     *   with the title unit. The sentinel avoids reusing a sequence that a
+     *   cardinality-changing Session migration may have remapped.
+     */
+    cachedPredecessorTitle(meta: SessionHeader, inheritedEventCount: SessionLogOffset): ProjectionSnapshot | undefined;
+    /** View selected wire rows and bind them to their lowest served watermark. */
+    private viewRecord;
     /**
      * Hydrate projection cells for an already-prepared Session without another
      * persistence read. The cache seeds matching rows; the supplied exact log

package/lib/types/spec.d.ts

@@ -34,14 +34,15 @@ export declare const checkpointRow: z.ZodObject<{
  * 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
+ * The format and lineage fields are optional because records admitted through
+ * `compatibleVersions` predate them. The reader (`identityMatches`) refuses an
+ * absent format generation because no current Session log can prove that
+ * record's fold semantics. It interprets absent lineage as unseeded only after
+ * the format generation matches. Current-version writes always store all three
  * fields.
  */
 export declare const checkpointIdentity: z.ZodObject<{
+    formatVersion: z.ZodOptional<z.ZodNumber>;
     createdAt: z.ZodNumber;
     cwd: z.ZodOptional<z.ZodString>;
     isSeeded: z.ZodOptional<z.ZodBoolean>;
@@ -57,6 +58,7 @@ export type CheckpointIdentity = z.infer<typeof checkpointIdentity>;
  */
 export declare const checkpointRecord: z.ZodObject<{
     identity: z.ZodObject<{
+        formatVersion: z.ZodOptional<z.ZodNumber>;
         createdAt: z.ZodNumber;
         cwd: z.ZodOptional<z.ZodString>;
         isSeeded: z.ZodOptional<z.ZodBoolean>;
@@ -76,15 +78,18 @@ export type CheckpointRecord = z.infer<typeof checkpointRecord>;
  * 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. 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
+ * keep structurally valid predecessor records available for a later current
+ * checkpoint rewrite. Records without `formatVersion` remain unusable as fold
+ * shortcuts because they cannot prove which Session event semantics produced
+ * their rows; the per-record version map and disposition live 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.
  *
+ * A lifecycle-matching predecessor may still expose its version-compatible
+ * title through the cache service's listing-only hint; this never relaxes the
+ * format requirement for hydration or another fold shortcut.
+ *
  * `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
@@ -101,6 +106,7 @@ export declare const projectionCacheDomainSpec: {
         sessions: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<SessionId, {
             identity: {
                 createdAt: number;
+                formatVersion?: number | undefined;
                 cwd?: string | undefined;
                 isSeeded?: boolean | undefined;
                 inheritedEventCount?: SessionLogOffset | undefined;

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.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -28,21 +28,21 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-util-values": "^0.1.3-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@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"
+    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.3-alpha.2"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@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"
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-storage": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-storage-json": "^0.1.3-alpha.2"
   }
 }