@x1a0f3n9/dsh-session-query 0.1.5-rc.5 → 0.1.7-rc.2

package/README.i18n.yaml

@@ -1,6 +1,67 @@
-# 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:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-query/session-query/README.md
-README.md: 5971903ef06035e73e6db57d3f437eec7a2aa8d9
-README.zh.md: e389975f436501093785e931c246d75279e2a0b6
+/:
+  en: 3d1caf01d90c7f34
+  zh: 4fa615b905574d83
+/x1a0f3n9-dsh-session-query:
+  en: daacbb8bb998f749
+  zh: ec12cadcba79cf24
+/x1a0f3n9-dsh-session-query/summary:
+  en: 25e9ed4d6de7c4ac
+  zh: 8b57631f7207b959
+/x1a0f3n9-dsh-session-query/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/x1a0f3n9-dsh-session-query/use-this-package:
+  en: 61b01acfa7afadb6
+  zh: f0df61147f689421
+/x1a0f3n9-dsh-session-query/use-this-package/what-you-can-do:
+  en: 742b1358d97e56cc
+  zh: 00d75ce6e5769559
+/x1a0f3n9-dsh-session-query/use-this-package/filters:
+  en: 1b95403461947ca1
+  zh: cffa21b03df9f0ad
+/x1a0f3n9-dsh-session-query/use-this-package/configuration:
+  en: bec9cedaa219e297
+  zh: e9cd16c0589fab4d
+/x1a0f3n9-dsh-session-query/use-this-package/failures-and-recovery:
+  en: fe410eb1234c1c45
+  zh: d2a1be75eb841be0
+/x1a0f3n9-dsh-session-query/understand-the-implementation:
+  en: 6a18034f1ccc247a
+  zh: aecd49a7b846f913
+/x1a0f3n9-dsh-session-query/understand-the-implementation/design-philosophy:
+  en: b34fb0d209192ff4
+  zh: 455bdb024d04f16a
+/x1a0f3n9-dsh-session-query/understand-the-implementation/source-map:
+  en: 7c546162fa3f75d4
+  zh: c6910bc53ae0ff71
+/x1a0f3n9-dsh-session-query/understand-the-implementation/corpus-resolution:
+  en: efa560c55a869c71
+  zh: 451eb107825856ac
+/x1a0f3n9-dsh-session-query/understand-the-implementation/observation-cache:
+  en: abe122deb81566e5
+  zh: 4c4f327f2ee1144e
+/x1a0f3n9-dsh-session-query/understand-the-implementation/reads-and-traces:
+  en: 48922e284adddd1b
+  zh: 9956dcc57e027d77
+/x1a0f3n9-dsh-session-query/further-exploration:
+  en: 40a0579a433d568e
+  zh: c34ff46da6cbd3e5
+/x1a0f3n9-dsh-session-query/model-experience:
+  en: dff12da8d1e64e66
+  zh: e054b0d54e29f899
+/x1a0f3n9-dsh-session-query/model-experience/kv-cache-effect:
+  en: ca75c51c89c2c9b0
+  zh: f57cc48a1b5cbfa9
+/x1a0f3n9-dsh-session-query/known-limitations-and-deferred-work:
+  en: e70a64614189c09c
+  zh: 88d2a6634385c501
+/x1a0f3n9-dsh-session-query/known-limitations-and-deferred-work/dev-note:
+  en: d2f0d68fe29fb750
+  zh: 323d21ee73a9e3f6
+/x1a0f3n9-dsh-session-query/known-limitations-and-deferred-work/dev-note/future-extractor-and-search-provider-registries:
+  en: 605a72e65297c6cf
+  zh: 87aa75ec62eccbde

package/README.md

@@ -62,7 +62,7 @@ The inherited knobs are set through the mounted backend's config:
 
 ### Failures and recovery
 
-Failures are typed with a stable `SessionQueryError.code`. The ones you will meet: `SESSION_QUERY_SESSION_NOT_FOUND` when an id is absent; `SESSION_QUERY_SOURCE_CONFLICT` when live and persisted observations of one session disagree on immutable headers; `SESSION_QUERY_PERSISTENCE_FAILED` when mounted persistence is unreadable; `SESSION_QUERY_CORRUPT_SESSION` when a durable record fails Session validation; and `SESSION_QUERY_INVALID_SURFACE` when a loaded log breaks the surface contract. Reads targeting a known live session never consult persistence, so a failing backend cannot make current in-memory history unreadable.
+Failures are typed with a stable `SessionQueryError.code`. The ones you will meet: `SESSION_QUERY_SESSION_NOT_FOUND` when an id is absent; `SESSION_QUERY_SOURCE_CONFLICT` when live and persisted observations of one session disagree on immutable headers; `SESSION_QUERY_PERSISTENCE_FAILED` when mounted persistence is unreadable; `SESSION_QUERY_CORRUPT_SESSION` when a durable record fails Session validation or a live or prepared observation fails projection computation; and `SESSION_QUERY_INVALID_SURFACE` when a loaded log breaks the surface contract. Projection failures retain the original error as `cause`. Reads targeting a known live session never consult persistence, so a failing backend cannot make current in-memory history unreadable.
 
 -----
 

package/README.zh.md

@@ -62,7 +62,7 @@ kind: "package-reference"
 
 ### 失败与恢复
 
-失败带有稳定的 `SessionQueryError.code` 类型。你会遇到的包括：id 不存在时 `SESSION_QUERY_SESSION_NOT_FOUND`；同一会话的实时与持久化观察在不可变 header 上不一致时 `SESSION_QUERY_SOURCE_CONFLICT`；已挂载持久化不可读时 `SESSION_QUERY_PERSISTENCE_FAILED`；持久化记录未通过 Session 校验时 `SESSION_QUERY_CORRUPT_SESSION`；加载的日志破坏表层约定时 `SESSION_QUERY_INVALID_SURFACE`。针对已知实时会话的读取从不查询持久化，因此后端故障不会让当前内存历史变得不可读。
+失败带有稳定的 `SessionQueryError.code` 类型。你会遇到的包括：id 不存在时 `SESSION_QUERY_SESSION_NOT_FOUND`；同一会话的实时与持久化观察在不可变 header 上不一致时 `SESSION_QUERY_SOURCE_CONFLICT`；已挂载持久化不可读时 `SESSION_QUERY_PERSISTENCE_FAILED`；持久化记录未通过 Session 校验，或实时或 prepared 观察的投影计算失败时 `SESSION_QUERY_CORRUPT_SESSION`；加载的日志破坏表层约定时 `SESSION_QUERY_INVALID_SURFACE`。投影失败会将原始错误保留为 `cause`。针对已知实时会话的读取从不查询持久化，因此后端故障不会让当前内存历史变得不可读。
 
 -----
 

package/lib/index.js

@@ -1,3 +1,4 @@
+import { currentSessionMessageProjections } from "@x1a0f3n9/dsh-session-format-catalog/message-projections";
 import { Service } from "@deepseek-ai/cordis";
 import { Session, SessionLogOffset, SessionSeq, foldSurface, interruptedTurnClosers, isSurfaceEvent, snapshotSessionEvent } from "@x1a0f3n9/dsh-session";
 import { foldSessionTitle } from "@x1a0f3n9/dsh-session-title";
@@ -342,6 +343,7 @@ var SessionObservationReader = class {
 	* @param sessionId - logical Session identity.
 	* @param options - cancellation and all-or-none projection computation for this read.
 	* @returns one exact immutable observation.
+	* @throws {@link SessionQueryError} with code `SESSION_QUERY_CORRUPT_SESSION` when live or prepared projection computation fails.
 	*/
 	async read(sessionId, options = {}) {
 		const { signal, projectionMode = "all" } = options;
@@ -354,7 +356,7 @@ var SessionObservationReader = class {
 			const snapshot = await this.statSource(persistence, sessionId, signal);
 			const attachedDuringStat = this.ctx.sessions.get(sessionId);
 			if (attachedDuringStat !== void 0) return this.live(attachedDuringStat, projectionMode);
-			let entry = this.cachedEntry(persistence, sessionId, snapshot.revision);
+			let entry = this.cachedEntry(persistence.identity, sessionId, snapshot.revision);
 			if (entry === void 0) {
 				const loaded = await this.loadSource(persistence, sessionId, signal);
 				throwIfObservationAborted(signal);
@@ -374,7 +376,7 @@ var SessionObservationReader = class {
 					throw new SessionQueryError(`stored session "${sessionId}" is corrupt: ${errorMessage(error)}`, "SESSION_QUERY_CORRUPT_SESSION", { cause: error });
 				}
 				entry = {
-					persistence,
+					persistenceIdentity: persistence.identity,
 					revision: snapshot.revision,
 					session,
 					events: Object.freeze(seed),
@@ -415,9 +417,9 @@ var SessionObservationReader = class {
 		}
 	}
 	/** Return a still-valid cached entry and mark it most recently used. */
-	cachedEntry(persistence, sessionId, revision) {
+	cachedEntry(persistenceIdentity, sessionId, revision) {
 		const cached = this.cache.get(sessionId);
-		if (cached === void 0 || cached.persistence !== persistence || cached.revision !== revision) return;
+		if (cached === void 0 || cached.persistenceIdentity !== persistenceIdentity || cached.revision !== revision) return;
 		this.cache.delete(sessionId);
 		this.cache.set(sessionId, cached);
 		return cached;
@@ -473,7 +475,12 @@ var SessionObservationReader = class {
 	live(session, projectionMode) {
 		const seq = session.seq;
 		let materialized;
-		const projections = projectionMode === "none" ? void 0 : this.ctx.get("sessionProjections")?.snapshot(session);
+		let projections;
+		try {
+			projections = projectionMode === "none" ? void 0 : this.ctx.get("sessionProjections")?.snapshot(session);
+		} catch (error) {
+			throw new SessionQueryError(`failed to project session "${session.id}": ${errorMessage(error)}`, "SESSION_QUERY_CORRUPT_SESSION", { cause: error });
+		}
 		const lease = () => {
 			let disposed = false;
 			return {
@@ -571,7 +578,6 @@ function blockText(block) {
 		case "text": return [block.text];
 		case "reasoning": return [];
 		case "tool-call": return [block.name, block.arguments];
-		case "tool-result": return block.content.flatMap(blockText);
 		default: return [];
 	}
 }
@@ -623,7 +629,7 @@ function buildSessionEventSearchDocuments(sessionId, events) {
 function classifySurface(events) {
 	let folded;
 	try {
-		folded = foldSurface(events);
+		folded = foldSurface(events, currentSessionMessageProjections);
 	} catch (error) {
 		throw new SessionQueryError(
 			/* v8 ignore next -- foldSurface throws Error instances */
@@ -940,7 +946,7 @@ function traceSession(records, sessionId) {
 function analyzeEventLog(sessionId, events) {
 	let folded;
 	try {
-		folded = foldSurface(events);
+		folded = foldSurface(events, currentSessionMessageProjections);
 	} catch (error) {
 		throw new SessionQueryError(
 			/* v8 ignore next -- foldSurface throws Error instances */
@@ -1072,7 +1078,7 @@ var SessionQueryEngine = class extends Service {
 	*/
 	async readSession(sessionId) {
 		const loaded = await this._corpus.load(sessionId);
-		Session.create(sessionId, loaded.events, loaded.header, loaded.inheritedEventCount);
+		Session.create(sessionId, loaded.events, loaded.header, loaded.inheritedEventCount, currentSessionMessageProjections);
 		return {
 			session: structuredClone(loaded.header),
 			inheritedEventCount: loaded.inheritedEventCount,

package/lib/types/observation.d.ts

@@ -60,6 +60,7 @@ export declare class SessionObservationReader {
      * @param sessionId - logical Session identity.
      * @param options - cancellation and all-or-none projection computation for this read.
      * @returns one exact immutable observation.
+     * @throws {@link SessionQueryError} with code `SESSION_QUERY_CORRUPT_SESSION` when live or prepared projection computation fails.
      */
     read(sessionId: SessionId, options?: SessionObservationOptions): Promise<SessionObservation>;
     /** Observe the stored snapshot, mapping absence and backend failures to the query taxonomy. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@x1a0f3n9/dsh-session-query",
   "description": "Combined session query service contract with concrete reads, traces, and filters",
-  "version": "0.1.5-rc.5",
+  "version": "0.1.7-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,15 +27,15 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@x1a0f3n9/dsh-brand": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-title": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-tool-todo": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-persistence": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-projection": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-projection-cache": "^0.1.5-rc.5",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@x1a0f3n9/dsh-brand": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-llm": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-title": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-persistence": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-tool-todo": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-projection": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-projection-cache": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "peerDependenciesMeta": {
     "@x1a0f3n9/dsh-session-persistence": {
@@ -49,14 +49,17 @@
     }
   },
   "devDependencies": {
-    "@x1a0f3n9/dsh-brand": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-llm": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-title": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-tool-todo": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-persistence": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-projection": "^0.1.5-rc.5",
-    "@x1a0f3n9/dsh-session-projection-cache": "^0.1.5-rc.5",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@x1a0f3n9/dsh-brand": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-llm": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-title": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-tool-todo": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-persistence": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-projection": "0.1.7-rc.2",
+    "@x1a0f3n9/dsh-session-projection-cache": "0.1.7-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4"
+  },
+  "dependencies": {
+    "@x1a0f3n9/dsh-session-format-catalog": "0.1.7-rc.2"
   }
 }