@deepseek-ai/dsh-session-projection-cache 0.1.2-alpha.4 → 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: 51b9d86724af96304cf09a5c7c1b61b7394d336a
-README.zh.md: bb84b67bdde678884fd4f2be1b14b2161da8c2a0
+README.md: 9fd9766d75ab3f9a460b2802ac59810839f21ae4
+README.zh.md: 98725d9ce76ab44821adf3d43e3807932cf6b675

package/README.md

@@ -64,6 +64,8 @@ Three mandatory points always write: session creation persists the seed-derived
 
 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.
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -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

@@ -64,6 +64,8 @@ kind: "package-reference"
 
 日志领先，缓存跟随：实时检查点先把会话的缓冲事件持久化，然后才保存缓存记录。因此崩溃可能让缓存落后于日志，但绝不会让缓存领先。读取和写入共享存储域内一致的内存状态；逐单元写入链只在持久化成功后修改内存。每个带版本戳的记录必须匹配实时单元 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.<时间戳>`、连同原因写入日志，并由下一次检查点重建。
+
 -----
 
 <a id="understand-the-implementation"></a>
@@ -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

@@ -37,12 +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(),
-	isSeeded: z$1.boolean(),
-	inheritedEventCount: z$1.number().int().nonnegative().transform(SessionLogOffset)
+	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
@@ -59,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: 5,
+	compatibleVersions: [3, 4],
+	invalidRecords: "backup-and-skip",
 	layout: "per-record",
 	tables: { sessions: domainTable(checkpointRecord) }
 });
@@ -305,9 +328,15 @@ function identityOf(header, inheritedEventCount) {
 		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 && stored.isSeeded === expected.isSeeded && stored.inheritedEventCount === expected.inheritedEventCount;
+	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/spec.d.ts

@@ -33,12 +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.ZodBoolean;
-    inheritedEventCount: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionLogOffset, number>>;
+    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>;
@@ -52,8 +59,8 @@ export declare const checkpointRecord: z.ZodObject<{
     identity: z.ZodObject<{
         createdAt: z.ZodNumber;
         cwd: z.ZodOptional<z.ZodString>;
-        isSeeded: z.ZodBoolean;
-        inheritedEventCount: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionLogOffset, number>>;
+        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;
@@ -68,19 +75,35 @@ 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;
-                isSeeded: boolean;
-                inheritedEventCount: SessionLogOffset;
                 cwd?: string | undefined;
+                isSeeded?: boolean | undefined;
+                inheritedEventCount?: SessionLogOffset | undefined;
             };
             rows: Record<string, {
                 ver: number;

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