@deepseek-ai/dsh-session-query-sqlite 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-query/session-query-sqlite/README.md
-README.md: 1db3999186beebc10a6a3c6874122fa65f2787a3
-README.zh.md: f6ef419293ab0df3a3edfd171cc60bc62ee4bcb0
+README.md: 81518cb5c902583f91ef3194e7c9311f49ffe229
+README.zh.md: b8a7e268d5d1771d75f8a4fb6cae2e2d33e38169

package/README.md

@@ -49,7 +49,8 @@ Choose it when you want full-text recall over prior sessions with ranking and pa
 | `maxLimit` | `100` | Largest accepted request page size |
 | `snippetChars` | `240` | Maximum snippet length in Unicode code points |
 | `readWindowMax` | `50` | Maximum `before`/`after` raw events for the inherited `readEvent()` |
-| `persistedInspectConcurrency` | `4` | Concurrent persisted-log inspections for inherited batch reads |
+| `persistedReadConcurrency` | `4` | Concurrent persisted-log reads for inherited batch reads |
+| `preparedSessionCacheSize` | `5` | Cold prepared-Session observations the inherited `observeSession` reader retains for reuse |
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-session-query-sqlite) is the exhaustive source for every accepted field and its JSDoc.
 
@@ -84,11 +85,11 @@ This section explains the design decisions behind the backend and points at the
 The backend is built on one separation and three commitments:
 
 - **Derived index, never the source store.** The FTS rows live in a dedicated disposable database; the session-persistence database is never opened here.
-- **Live-preferred observation.** One serialized state machine compares persistence snapshot revisions, inspects only new or changed logs, and reconciles in one transaction, so a search reflects the newest stable state.
+- **Live-preferred observation.** One serialized state machine compares persistence snapshot revisions, reads only new or changed logs through short-lived read handles, and reconciles in one transaction, so a search reflects the newest stable state.
 - **Generation-bound cursors.** Every corpus change bumps a generation; cursors carry the generation they were created under and fail stale rather than returning a shifted page.
 - **Literal phrases as data.** Caller query text is quoted into one FTS5 phrase so query syntax stays inert, and reserved highlight markers are stripped from documents before indexing.
 
-The design history lives in the [SQLite FTS5 session search note](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md) and the [unified service decision](../../../.agents/notes/archived/architecture/2026-07-23-unified-session-query-service.md).
+The design history lives in the [SQLite FTS5 session search note](../../../.agents/notes/archived/feature/2026-07-10-sqlite-session-query-provider.md) and the [unified service decision](../../../.agents/notes/archived/architecture/2026-07-23-unified-session-query-service.md).
 
 ### Source map
 
@@ -101,7 +102,7 @@ The design history lives in the [SQLite FTS5 session search note](../../../.agen
 
 ### Index lifecycle
 
-Persisted FTS rows live in a dedicated derived database and survive restarts; live sessions use connection-local TEMP tables that shadow the durable base for the same session and reveal it again when the live owner detaches. Both tables retain the exact inherited cut in numeric `seed_length`; reconstructed headers expose only `isSeeded`, while the cut participates in live fingerprints and persisted source revisions. Each search runs one serialized observation: list persistence snapshots, compare per-session revisions with the indexed rows, inspect only new or changed logs, extract semantic documents, and commit the reconciliation in one transaction before running the query. Repeated queries and unchanged reopens inspect nothing; switching stores or observing new, changed, deleted, or externally repaired sources reconciles on the next stable observation. Source or transaction failure commits nothing and the next search retries.
+Persisted FTS rows live in a dedicated derived database and survive restarts; live sessions use connection-local TEMP tables that shadow the durable base for the same session and reveal it again when the live owner detaches. Both tables retain the exact inherited cut in numeric `seed_length`; reconstructed headers expose only `isSeeded`, while the cut participates in live fingerprints and persisted source revisions. Each search runs one serialized observation: list persistence snapshots, compare per-session revisions with the indexed rows, read only new or changed logs through a read handle (balancing an interrupted final turn in memory, never writing back), extract semantic documents, and commit the reconciliation in one transaction before running the query. Repeated queries and unchanged reopens read nothing; switching stores or observing new, changed, deleted, or externally repaired sources reconciles on the next stable observation. Source or transaction failure commits nothing and the next search retries.
 
 ### Schema ownership
 
@@ -119,7 +120,7 @@ Read these pages when the package-level contract is not enough. They move from t
 - [Session Query subsystem reference](../../../docs/subsystems/session-query.md) — the full type-level contract this backend implements.
 - [dsh-session-query](../session-query/README.md) — the service definition: exact reads, filters, and traces this backend inherits.
 - [dsh-tool-session-query](../tool-session-query/README.md) — the model-facing consumer that calls these search methods.
-- [SQLite FTS5 session search](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.md) — search semantics, reconciliation, and the tokenizer decision.
+- [SQLite FTS5 session search](../../../.agents/notes/archived/feature/2026-07-10-sqlite-session-query-provider.md) — search semantics, reconciliation, and the tokenizer decision.
 - [JSONL session persistence](../../session/session-persistence-jsonl/README.md) — the authoritative Session store this disposable index observes; keep its root separate from this package's database path.
 
 -----

package/README.zh.md

@@ -49,7 +49,8 @@ kind: "package-reference"
 | `maxLimit` | `100` | 接受的最大请求分页大小 |
 | `snippetChars` | `240` | 按 Unicode 码点计算的最大 snippet 长度 |
 | `readWindowMax` | `50` | 继承的 `readEvent()` 的 `before`/`after` 原始事件数上限 |
-| `persistedInspectConcurrency` | `4` | 继承批量读取的并发持久化日志检查数 |
+| `persistedReadConcurrency` | `4` | 继承批量读取的并发持久化日志读取数 |
+| `preparedSessionCacheSize` | `5` | 继承的 `observeSession` 读取器为复用保留的冷 prepared-Session 观察数 |
 
 生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-session-query-sqlite)是每个受支持字段及其 JSDoc 的穷尽式真源。
 
@@ -84,11 +85,11 @@ kind: "package-reference"
 本后端建立在一个分离与三项承诺之上：
 
 - **派生索引，绝不动源存储。** FTS 行存放在专用可丢弃数据库中；这里的代码从不打开 session-persistence 数据库。
-- **实时优先的观察。** 一个串行化状态机比较持久化快照修订，只检查新增或已更改日志，并在一个事务中对账，因此搜索反映最新的稳定状态。
+- **实时优先的观察。** 一个串行化状态机比较持久化快照修订，只通过短生命周期读取 handle 读取新增或已更改日志，并在一个事务中对账，因此搜索反映最新的稳定状态。
 - **世代绑定的游标。** 每次语料库变化都会递增世代；游标携带其创建时的世代，宁可陈旧失败也不返回偏移后的页面。
 - **字面短语即数据。** 调用方查询文本被引成一个 FTS5 短语，查询语法保持惰性；保留高亮标记在索引前从文档中剥离。
 
-设计历史记录在 [SQLite FTS5 会话搜索笔记](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md)与[统一服务决策](../../../.agents/notes/archived/architecture/2026-07-23-unified-session-query-service.md)中。
+设计历史记录在 [SQLite FTS5 会话搜索笔记](../../../.agents/notes/archived/feature/2026-07-10-sqlite-session-query-provider.md)与[统一服务决策](../../../.agents/notes/archived/architecture/2026-07-23-unified-session-query-service.md)中。
 
 ### 源码地图
 
@@ -101,7 +102,7 @@ kind: "package-reference"
 
 ### 索引生命周期
 
-持久化 FTS 行存放在专用派生数据库中并跨重启保留；实时会话使用连接本地 TEMP 表，遮蔽同一会话的持久化基库，并在实时所有者脱离后再次显示基库。两类表都在数字 `seed_length` 中保留精确继承切点；重建的 header 只公开 `isSeeded`，而切点参与实时 fingerprint 与持久来源修订。每次搜索执行一次串行化观察：列出持久化快照、把逐会话修订与已索引行比较、只检查新增或已更改日志、提取语义文档，并在运行查询前于一个事务中提交对账。重复查询与不变的重新打开不会检查任何内容；切换存储或观察到新增、已更改、已删除或经外部修复的来源时，会在下次稳定观察时对账。来源或事务失败不提交任何内容，下一次搜索重试。
+持久化 FTS 行存放在专用派生数据库中并跨重启保留；实时会话使用连接本地 TEMP 表，遮蔽同一会话的持久化基库，并在实时所有者脱离后再次显示基库。两类表都在数字 `seed_length` 中保留精确继承切点；重建的 header 只公开 `isSeeded`，而切点参与实时 fingerprint 与持久来源修订。每次搜索执行一次串行化观察：列出持久化快照、把逐会话修订与已索引行比较、只通过读取 handle 读取新增或已更改日志（在内存中补齐被中断的末尾轮次，从不写回）、提取语义文档，并在运行查询前于一个事务中提交对账。重复查询与不变的重新打开不读取任何内容；切换存储或观察到新增、已更改、已删除或经外部修复的来源时，会在下次稳定观察时对账。来源或事务失败不提交任何内容，下一次搜索重试。
 
 ### Schema 归属
 
@@ -119,7 +120,7 @@ kind: "package-reference"
 - [会话查询子系统参考](../../../docs/subsystems/session-query.zh.md)——本后端实现的完整类型级约定。
 - [dsh-session-query](../session-query/README.zh.md)——服务定义：本后端继承的精确读取、过滤与追踪。
 - [dsh-tool-session-query](../tool-session-query/README.zh.md)——调用这些搜索方法的面向模型消费方。
-- [SQLite FTS5 会话搜索](../../../.agents/notes/implemented/feature/2026-07-10-sqlite-session-query-provider.zh.md)——搜索语义、对账与 tokenizer 决策。
+- [SQLite FTS5 会话搜索](../../../.agents/notes/archived/feature/2026-07-10-sqlite-session-query-provider.md)——搜索语义、对账与 tokenizer 决策。
 - [JSONL 会话持久化](../../session/session-persistence-jsonl/README.zh.md)——本可丢弃索引观察的权威 Session store；其 root 必须与本包的数据库路径分开。
 
 -----

package/lib/index.js

@@ -1,8 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
+import { SESSION_FORMAT_VERSION, SessionSeq } from "@deepseek-ai/dsh-session";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { SessionSeq } from "@deepseek-ai/dsh-session";
-import SessionQueryEngine, { SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY, SESSION_QUERY_READ_WINDOW_MAX, SessionQueryError, SessionSearchCursor, assertSessionHeadersCompatible, buildSessionEventSearchDocuments, materializeSessionEventResultFilters, materializeSessionResultFilters } from "@deepseek-ai/dsh-session-query";
+import SessionQueryEngine, { SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY, SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE, SESSION_QUERY_READ_WINDOW_MAX, SessionQueryError, SessionSearchCursor, assertSessionHeadersCompatible, buildSessionEventSearchDocuments, materializeSessionEventResultFilters, materializeSessionResultFilters, readColdSessionLog } from "@deepseek-ai/dsh-session-query";
 import { mkdir, open } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 //#region lib/types/schema.js
@@ -492,7 +492,8 @@ var SqliteSessionQueryEngine = class extends SessionQueryEngine {
 		maxLimit: z.number().step(1).min(1).max(SQLITE_MAX_PAGE_LIMIT).default(100),
 		snippetChars: z.number().step(1).min(1).default(240),
 		readWindowMax: z.number().step(1).min(0).default(SESSION_QUERY_READ_WINDOW_MAX),
-		persistedInspectConcurrency: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY)
+		persistedReadConcurrency: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY),
+		preparedSessionCacheSize: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE)
 	});
 	/** Validated and defaulted backend configuration. */
 	config;
@@ -712,20 +713,21 @@ var SqliteSessionQueryEngine = class extends SessionQueryEngine {
 			let persisted = /* @__PURE__ */ new Map();
 			if (persistence !== void 0) try {
 				const canReuseIndexed = this._lastPersistenceIdentity === void 0 || this._lastPersistenceIdentity === persistenceBinding.identity;
-				const before = await persistence.listSnapshots(signal);
+				const listOptions = signal === void 0 ? void 0 : { signal };
+				const before = await persistence.list(listOptions);
 				assertNotAborted(signal);
 				persisted = materializePersistenceSnapshots(before);
 				for (const entry of persisted.values()) {
 					if (canReuseIndexed && indexed.get(entry.header.id)?.revision === entry.revision) continue;
 					if (initiallyLive.has(entry.header.id) || this.ctx.sessions.get(entry.header.id) !== void 0) continue;
 					assertNotAborted(signal);
-					const loaded = await persistence.inspect(entry.header.id, signal);
+					const loaded = await readColdSessionLog(persistence, entry.header.id, signal);
 					assertNotAborted(signal);
-					assertSessionHeadersCompatible(entry.header, loaded.meta);
-					entry.loaded = observeSession(loaded.meta, loaded.inheritedEventCount, loaded.events);
+					assertSessionHeadersCompatible(entry.header, loaded.header);
+					entry.loaded = observeSession(loaded.header, loaded.inheritedEventCount, loaded.events);
 				}
 				assertNotAborted(signal);
-				const afterSnapshots = await persistence.listSnapshots(signal);
+				const afterSnapshots = await persistence.list(listOptions);
 				assertNotAborted(signal);
 				const after = materializePersistenceSnapshots(afterSnapshots);
 				if (!samePersistenceSnapshots(persisted, after)) continue;
@@ -1034,11 +1036,11 @@ function sameSessionIds(before, after) {
 	return true;
 }
 function sameHeader(a, b) {
-	return a.version === b.version && a.id === b.id && a.createdAt === b.createdAt && a.cwd === b.cwd && a.parentSession === b.parentSession && a.isSeeded === b.isSeeded && (a.delegationDepth ?? 0) === (b.delegationDepth ?? 0) && a.agentPreset === b.agentPreset;
+	return a.id === b.id && a.createdAt === b.createdAt && a.cwd === b.cwd && a.parentSession === b.parentSession && a.isSeeded === b.isSeeded && (a.delegationDepth ?? 0) === (b.delegationDepth ?? 0) && a.agentPreset === b.agentPreset;
 }
 function rowHeader(row) {
 	return {
-		version: row.version,
+		version: SESSION_FORMAT_VERSION,
 		id: row.session_id,
 		createdAt: row.created_at,
 		...row.cwd === null ? {} : { cwd: row.cwd },
@@ -1081,7 +1083,8 @@ function resolveConfig(config) {
 		maxLimit: config.maxLimit ?? 100,
 		snippetChars: config.snippetChars ?? 240,
 		readWindowMax: config.readWindowMax ?? SESSION_QUERY_READ_WINDOW_MAX,
-		persistedInspectConcurrency: config.persistedInspectConcurrency ?? SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY
+		persistedReadConcurrency: config.persistedReadConcurrency ?? SESSION_QUERY_DEFAULT_PERSISTED_INSPECT_CONCURRENCY,
+		preparedSessionCacheSize: config.preparedSessionCacheSize ?? SESSION_QUERY_DEFAULT_PREPARED_SESSION_CACHE_SIZE
 	};
 	if (typeof resolved.path !== "string" || resolved.path.trim().length === 0) throw invalidConfig("path must not be blank");
 	if (![
@@ -1093,7 +1096,8 @@ function resolveConfig(config) {
 	assertPageLimit("maxLimit", resolved.maxLimit);
 	assertPositiveInteger("snippetChars", resolved.snippetChars);
 	if (!Number.isInteger(resolved.readWindowMax) || resolved.readWindowMax < 0) throw invalidConfig("readWindowMax must be a non-negative integer");
-	if (!Number.isSafeInteger(resolved.persistedInspectConcurrency) || resolved.persistedInspectConcurrency < 1) throw invalidConfig("persistedInspectConcurrency must be a positive safe integer");
+	if (!Number.isSafeInteger(resolved.persistedReadConcurrency) || resolved.persistedReadConcurrency < 1) throw invalidConfig("persistedReadConcurrency must be a positive safe integer");
+	if (!Number.isSafeInteger(resolved.preparedSessionCacheSize) || resolved.preparedSessionCacheSize < 1) throw invalidConfig("preparedSessionCacheSize must be a positive safe integer");
 	if (resolved.defaultLimit > resolved.maxLimit) throw invalidConfig("defaultLimit must be less than or equal to maxLimit");
 	if (![
 		"wal",

package/lib/types/index.d.ts

@@ -49,8 +49,10 @@ export interface Config extends SessionQueryConfig {
     maxLimit?: number;
     /** Maximum snippet length in Unicode code points. Defaults to 240. */
     snippetChars?: number;
-    /** Maximum concurrent persisted-log inspections in one inherited batch read. Defaults to 4. */
-    persistedInspectConcurrency?: number;
+    /** Maximum concurrent persisted-log reads in one inherited batch read. Defaults to 4. */
+    persistedReadConcurrency?: number;
+    /** Maximum cold prepared-Session observations the inherited reader retains for reuse. Defaults to 5. */
+    preparedSessionCacheSize?: number;
 }
 interface ResolvedConfig {
     path: string;
@@ -60,7 +62,8 @@ interface ResolvedConfig {
     maxLimit: number;
     snippetChars: number;
     readWindowMax: number;
-    persistedInspectConcurrency: number;
+    persistedReadConcurrency: number;
+    preparedSessionCacheSize: number;
 }
 /** Concrete SQLite owner of the combined `ctx.sessionQuery` service. */
 export declare class SqliteSessionQueryEngine extends SessionQueryEngine {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-query-sqlite",
   "description": "Concrete ctx.sessionQuery backend with SQLite FTS5 search",
-  "version": "0.1.2-alpha.5",
+  "version": "0.1.3-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,9 +27,9 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-query": "^0.1.2-alpha.5",
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.3-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "peerDependenciesMeta": {
@@ -41,12 +41,12 @@
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-session": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.2-alpha.5",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-query": "^0.1.2-alpha.5",
-    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.5",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.1.3-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-session-query": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.3-alpha.2"
   }
 }