@michengai/dsh-archive-manager 0.1.19 → 0.1.21

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 Published release notes are retained below; new versions are added without removing earlier entries.
 
+## 0.1.21 — 2026-08-31
+
+- Preserved the projection-cache `put()` Promise contract when a tombstone suppresses a deleted Session write, so DSH `v0.1.2-alpha.2` cold-read write-back remains fail-soft instead of throwing a synchronous `TypeError`.
+- Added direct `put(...).catch(...)` regression coverage for alpha.2 while retaining the `putSoft` path used by DSH `v0.1.1-rc.2`, and clarified the separate safe cache domain and migration behavior.
+
+Published package: [`@michengai/dsh-archive-manager@0.1.21`](https://www.npmjs.com/package/@michengai/dsh-archive-manager/v/0.1.21).
+
+## 0.1.20 — 2026-08-31
+
+- Kept IM and other non-filesystem-safe Session ids unchanged while persisting projection checkpoints under fixed-length safe keys, preventing DSH `v0.1.2-alpha.2` from using colons as Windows filenames.
+- Added resumable, add-only cache import from the DSH `v0.1.1-rc.2` whole-file format and from clean alpha per-record profiles, so existing users retain cached projections across either upgrade path.
+- Rebuild missing archived-session projections from the retained transcript on demand and refresh the client list, so legacy archive markers remain fully visible whether their old cache row exists or not.
+
+Published package: [`@michengai/dsh-archive-manager@0.1.20`](https://www.npmjs.com/package/@michengai/dsh-archive-manager/v/0.1.20).
+
 ## 0.1.19 — 2026-08-30
 
 - Fixed the workspace-row **+** action on DSH `v0.1.2-alpha.1` by resolving the `uiWorkspace` service when the action runs, removing its dependency on plugin load order and avoiding the removed legacy `startSession` API.

package/CHANGELOG.zh-CN.md

@@ -4,6 +4,21 @@
 
 以下发布说明会持续保留；新增版本时不再删除较早记录。
 
+## 0.1.21 — 2026-08-31
+
+- 墓碑拦截已删除会话的投影缓存写入时仍保持 `put()` 的 Promise 契约，使 DSH `v0.1.2-alpha.2` 冷读写回继续按 fail-soft 方式处理，而不会同步抛出 `TypeError`。
+- 补充 alpha.2 直接调用 `put(...).catch(...)` 的回归测试，同时保留 DSH `v0.1.1-rc.2` 使用的 `putSoft` 路径覆盖，并澄清独立安全缓存域与迁移行为。
+
+已发布包：[`@michengai/dsh-archive-manager@0.1.21`](https://www.npmjs.com/package/@michengai/dsh-archive-manager/v/0.1.21)。
+
+## 0.1.20 — 2026-08-31
+
+- 保持 IM 等不适合作文件名的会话 ID 不变，将投影检查点改用固定长度安全键落盘，避免 DSH `v0.1.2-alpha.2` 在 Windows 上把冒号直接用作文件名。
+- 支持从 DSH `v0.1.1-rc.2` 单文件缓存和干净的 alpha 分记录缓存断点续迁、只补缺失项，老用户沿任一升级路径都能保留已有投影缓存。
+- 归档标记仍在但旧缓存行缺失时，按需从保留的会话原文重建投影并刷新客户端列表；无论老归档是否带缓存，都能完整显示。
+
+已发布包：[`@michengai/dsh-archive-manager@0.1.20`](https://www.npmjs.com/package/@michengai/dsh-archive-manager/v/0.1.20)。
+
 ## 0.1.19 — 2026-08-30
 
 - 修复 DSH `v0.1.2-alpha.1` 中工作区行 **+** 操作：在操作执行时再获取 `uiWorkspace` 服务，避免受插件加载顺序影响，也不再落入已移除的旧版 `startSession` API。

package/lib/client.js

@@ -74,6 +74,7 @@ window.__ModuleLoader__.load({
 			parse(value) {
 				if (typeof value !== "object" || value === null || Array.isArray(value) || !Array.isArray(value.items)) throw new TypeError("result.items must be an array");
 				if (value.items.some((item) => typeof item !== "object" || item === null || typeof item.sessionId !== "string" || typeof item.createdAt !== "number" || !Number.isFinite(item.createdAt))) throw new TypeError("items must contain sessionId/createdAt objects");
+				if (value.repairedSessionIds !== void 0 && (!Array.isArray(value.repairedSessionIds) || value.repairedSessionIds.some((id) => typeof id !== "string"))) throw new TypeError("repairedSessionIds must be a string array");
 				return value;
 			}
 		};
@@ -3512,6 +3513,13 @@ window.__ModuleLoader__.load({
 				if (registry === void 0) throw new Error("archive-manager remote service is unavailable");
 				const result = await registry.archivedSessionMetadata();
 				if (!result.ok) throw new Error(result.error.message);
+				if (result.value.repairedSessionIds?.length > 0 && typeof ctx.sessions.refresh === "function") {
+					try {
+						await ctx.sessions.refresh();
+					} catch (error) {
+						console.warn("archive-manager: repaired archived projections but session list refresh failed:", error);
+					}
+				}
 				return result.value;
 			};
 			const browserInjected = () => ({

package/lib/projcache.js

@@ -1,20 +1,161 @@
-import { SessionProjectionCache } from "@deepseek-ai/dsh-session-projection-cache";
+import { createHash } from "node:crypto";
+import { Service } from "@deepseek-ai/cordis";
+import {
+	SessionProjectionCache,
+	checkpointIdentity,
+	checkpointRecord,
+	projectionCacheDomainSpec
+} from "@deepseek-ai/dsh-session-projection-cache";
+import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { trackTombstone } from "./tombstone.js";
+
+/**
+ * Archive Manager owns a separate cache domain so DSH alpha.2 never asks the
+ * JSON backend to turn a logical IM id such as `im:qq:dm:...` into a Windows
+ * filename. The public Session id remains unchanged; only the storage key is
+ * a fixed-length SHA-256 token and the original id is carried in the value.
+ *
+ * On rc.2 the runtime has no per-record layout, so the same domain remains a
+ * single JSON file. After that user upgrades to alpha.2, every already-safe
+ * hashed key can be migrated by the official backend without hitting the
+ * legacy colon bug.
+ */
+const storedCheckpointRecord = checkpointRecord.extend({
+	sessionId: checkpointIdentity.shape.cwd.unwrap()
+});
+const safeDomainInput = {
+	name: "session_projcache_archive_manager",
+	version: 1,
+	tables: { sessions: domainTable(storedCheckpointRecord) },
+	...(projectionCacheDomainSpec.layout === "per-record" ? { layout: "per-record" } : {})
+};
+const safeProjectionCacheDomainSpec = defineDomain(safeDomainInput);
+
+/** The last official whole-file cache format used by DSH rc.2. */
+const legacyProjectionCacheDomainSpec = defineDomain({
+	name: "session_projcache",
+	version: 3,
+	tables: { sessions: domainTable(checkpointRecord) }
+});
+
+function projectionCacheStorageKey(sessionId) {
+	return `session_${createHash("sha256").update(sessionId, "utf8").digest("base64url")}`;
+}
+
+function unwrapStoredCheckpoint(stored) {
+	return { identity: stored.identity, rows: stored.rows };
+}
+
+/** Map the Session-id table contract onto path-safe physical keys. */
+class SafeSessionTable {
+	constructor(table) {
+		this.table = table;
+	}
+	get size() {
+		return [...this.keys()].length;
+	}
+	get(sessionId) {
+		const stored = this.table.get(projectionCacheStorageKey(sessionId));
+		if (stored === void 0 || stored.sessionId !== sessionId) return void 0;
+		return unwrapStoredCheckpoint(stored);
+	}
+	has(sessionId) {
+		return this.get(sessionId) !== void 0;
+	}
+	*entries() {
+		for (const [key, stored] of this.table.entries()) {
+			if (projectionCacheStorageKey(stored.sessionId) !== key) continue;
+			yield [stored.sessionId, unwrapStoredCheckpoint(stored)];
+		}
+	}
+	*keys() {
+		for (const [sessionId] of this.entries()) yield sessionId;
+	}
+	*values() {
+		for (const [, value] of this.entries()) yield value;
+	}
+	async put(sessionId, record) {
+		const key = projectionCacheStorageKey(sessionId);
+		const existing = this.table.get(key);
+		if (existing !== void 0 && existing.sessionId !== sessionId) {
+			throw new Error(`projection-cache storage-key collision for "${sessionId}"`);
+		}
+		await this.table.put(key, { sessionId, identity: record.identity, rows: record.rows });
+	}
+	async delete(sessionId) {
+		const key = projectionCacheStorageKey(sessionId);
+		const existing = this.table.get(key);
+		if (existing === void 0 || existing.sessionId !== sessionId) return false;
+		return this.table.delete(key);
+	}
+}
+
+async function readSourceRecords(ctx, spec, label) {
+	let domain;
+	try {
+		domain = await ctx.storageDomain.open(spec);
+		return { opened: true, records: [...domain.table("sessions").entries()] };
+	} catch (error) {
+		ctx.logger.warn(`archive-manager projcache: ${label} cache import skipped: ${String(error)}`);
+		return { opened: false, records: [] };
+	} finally {
+		try {
+			await domain?.close();
+		} catch (error) {
+			ctx.logger.warn(`archive-manager projcache: ${label} cache close failed: ${String(error)}`);
+		}
+	}
+}
+
+async function importMissingRecords(ctx, target, records, label) {
+	let imported = 0;
+	for (const [sessionId, record] of records) {
+		if (target.has(sessionId)) continue;
+		try {
+			await target.put(sessionId, record);
+			imported += 1;
+		} catch (error) {
+			ctx.logger.warn(`archive-manager projcache: ${label} row "${sessionId}" import failed: ${String(error)}`);
+		}
+	}
+	return imported;
+}
+
+/**
+ * Seed the compatibility domain without opening alpha.2's unsafe per-record
+ * source while the v3 whole-file cache contains rows. An empty v3 source may
+ * fall through to the current source; source-open failures stay fail-soft.
+ * Imports are add-only: a newer compatibility-domain checkpoint always wins,
+ * and a partially completed import resumes on the next startup.
+ */
+async function importPreviousProjectionCache(ctx, target) {
+	const legacy = await readSourceRecords(ctx, legacyProjectionCacheDomainSpec, "legacy v3");
+	if (!legacy.opened) return 0;
+	if (legacy.records.length > 0) return importMissingRecords(ctx, target, legacy.records, "legacy v3");
+	const sameSpec = projectionCacheDomainSpec.version === legacyProjectionCacheDomainSpec.version
+		&& projectionCacheDomainSpec.layout === legacyProjectionCacheDomainSpec.layout;
+	if (sameSpec) return 0;
+	const current = await readSourceRecords(ctx, projectionCacheDomainSpec, "current");
+	if (!current.opened) return 0;
+	return importMissingRecords(ctx, target, current.records, "current");
+}
 //#region lib/types/index.js
 /**
  * dsh-archive-manager projcache 半边。
  *
- * `ArchiveProjectionCache` 继承上游 `SessionProjectionCache`
- * （服务名 `sessionProjectionCache`，同域、同 fail-soft 写路径），
- * 为归档管理的 `deleteSession` 增加三处守护：
+ * `ArchiveProjectionCache` 继承上游 `SessionProjectionCache`，保留服务名
+ * `sessionProjectionCache` 与 fail-soft 写路径，但使用独立、路径安全的
+ * `session_projcache_archive_manager` 兼容域，为归档管理的
+ * `deleteSession` 增加三处守护：
  *
- * - `delete(id)` - 永久移除一个会话的缓存投影行
- *   （`session_projcache` 域上的 `table.delete`），写入前先登记墓碑。
+ * - `delete(id)` - 永久移除兼容域中该会话经 SHA-256 映射的缓存投影行，
+ *   写入前先登记墓碑。
  * - `whenIdle()` - 全部在途公开写入落定后 resolve。
  * - 墓碑挡住已删除会话的写入：迟到的写入要么被直接拦截，要么在
  *   落定后补删自己的残留行，不会复活已删除的缓存条目。守护覆盖
- *   `write()`（dispose 写后路径）与 `putSoft()`（`coldSnapshot` 的
- *   冷读写回路径），两条落盘路径都纳入 `whenIdle` 跟踪。
+ *   `write()`（dispose 写后路径）与 `put()`（rc.2 的 `putSoft` 最终调用
+ *   它，alpha.2 的 `coldSnapshot` 则直接调用它），两代落盘路径都纳入
+ *   `whenIdle` 跟踪。
  *
  * 默认导出是 Service 子类（与上游 `@deepseek-ai/dsh-session-projection-cache`
  * 包同形），profile 补丁可直接替换 `session-projection-cache` 服务行，
@@ -31,6 +172,18 @@ var ArchiveProjectionCache = class extends SessionProjectionCache {
 	constructor(ctx, config) {
 		super(ctx, config);
 	}
+	/**
+	 * Replace the official cache domain with the path-safe compatibility
+	 * domain, then preserve the upstream listener/write implementation.
+	 */
+	async [Service.init]() {
+		const domain = await this.ctx.storageDomain.open(safeProjectionCacheDomainSpec);
+		this.ctx.effect(() => () => domain.close(), "sessionProjectionCache.domainClose");
+		const table = new SafeSessionTable(domain.table("sessions"));
+		this.table = table;
+		await importPreviousProjectionCache(this.ctx, table);
+		this.installWritePath();
+	}
 	/** 跟踪公开写入路径，避免依赖上游私有 `flushSoft` 的实现细节。 */
 	write(session) {
 		const task = this.writeCore(session);
@@ -47,22 +200,29 @@ var ArchiveProjectionCache = class extends SessionProjectionCache {
 		if (this.deletedSessionIds.has(session.id)) await this.requireTable().delete(session.id);
 	}
 	/**
-	 * 冷读写回路径（上游 `coldSnapshot` 经 `putSoft` 落盘）与 `write` 同守：
-	 * 已删除直接放弃；删除落在写回进行中则在其落定后补删残留行。
-	 * 同样纳入 `whenIdle` 跟踪。
+	 * 守住所有底层写入。rc.2 的冷读经 `putSoft -> put`，alpha.2 则
+	 * 直接经 `put`；把墓碑与 whenIdle 跟踪放在这里可同时兼容两代实现。
 	 */
-	async putSoft(id, identity, rows, what) {
-		if (this.deletedSessionIds.has(id)) return;
-		const task = this.putSoftCore(id, identity, rows, what);
+	put(id, identity, rows) {
+		// alpha.2 coldSnapshot unconditionally chains `.catch()` onto put().
+		// A blocked write must therefore preserve the upstream Promise contract.
+		if (this.deletedSessionIds.has(id)) return Promise.resolve();
+		const task = this.putCore(id, identity, rows);
 		this.writeTail = Promise.allSettled([this.writeTail, task]).then(() => void 0);
 		return task;
 	}
-	async putSoftCore(id, identity, rows, what) {
-		await super.putSoft(id, identity, rows, what);
+	async putCore(id, identity, rows) {
+		await super.put(id, identity, rows);
+		if (this.deletedSessionIds.has(id)) await this.requireTable().delete(id);
+	}
+	/** rc.2 公开的 fail-soft 辅助在 alpha.2 已移除；保留同形兼容入口。 */
+	async putSoft(id, identity, rows, what) {
+		const upstream = SessionProjectionCache.prototype.putSoft;
+		if (typeof upstream === "function") return upstream.call(this, id, identity, rows, what);
 		try {
-			if (this.deletedSessionIds.has(id)) await this.requireTable().delete(id);
+			await this.put(id, identity, rows);
 		} catch (error) {
-			this.ctx.logger.warn(`archive-manager projcache: cold-read write-back cleanup for "${id}" failed: ${String(error)}`);
+			this.ctx.logger.warn(`session projection cache: ${what} for "${id}" failed (cache stays stale): ${String(error)}`);
 		}
 	}
 	/**
@@ -89,4 +249,12 @@ var ArchiveProjectionCache = class extends SessionProjectionCache {
 	}
 };
 //#endregion
-export { ArchiveProjectionCache, ArchiveProjectionCache as default };
+export {
+	ArchiveProjectionCache,
+	ArchiveProjectionCache as default,
+	SafeSessionTable,
+	importPreviousProjectionCache,
+	legacyProjectionCacheDomainSpec,
+	projectionCacheStorageKey,
+	safeProjectionCacheDomainSpec
+};

package/lib/workspace.js

@@ -109,6 +109,7 @@ const archivedSessionMetadataSchema = {
 	parse(value) {
 		if (typeof value !== "object" || value === null || Array.isArray(value) || !Array.isArray(value.items)) throw new TypeError("result.items must be an array");
 		if (value.items.some((item) => typeof item !== "object" || item === null || typeof item.sessionId !== "string" || typeof item.createdAt !== "number" || !Number.isFinite(item.createdAt))) throw new TypeError("items must contain sessionId/createdAt objects");
+		if (value.repairedSessionIds !== void 0 && (!Array.isArray(value.repairedSessionIds) || value.repairedSessionIds.some((id) => typeof id !== "string"))) throw new TypeError("repairedSessionIds must be a string array");
 		return value;
 	}
 };
@@ -250,18 +251,47 @@ var ArchiveWorkspaceRegistry = class extends WorkspaceRegistry {
 		markRemoteMethod(this, "archivedSessionMetadata");
 		registerHostRemote(this.ctx);
 	}
-	/** 归档设置页创建时间排序所需的最小元数据；列表摘要本身只暴露 updatedAt。 */
+	/**
+	* 归档设置页创建时间排序所需的最小元数据。老用户可能仍有会话原文和
+	* 归档标记、却没有投影缓存；这里按需从完整日志重建一次，再通知客户端
+	* 刷新会话列表。已有缓存不读原文，新老 DSH 的缓存布局都走同一 put。
+	*/
 	async archivedSessionMetadata() {
 		const items = [];
+		const repairedSessionIds = [];
 		for (const sessionId of [...new Set(this.requireState().archivedSessionIds)]) {
 			try {
 				const header = await this.readSessionHeader(sessionId);
+				if (await this.repairArchivedProjection(header)) repairedSessionIds.push(sessionId);
 				if (typeof header.createdAt === "number" && Number.isFinite(header.createdAt)) items.push({ sessionId, createdAt: header.createdAt });
 			} catch (error) {
 				this.ctx.logger.warn(`archive-manager: could not read creation time for archived session "${sessionId}": ${String(error)}`);
 			}
 		}
-		return { items };
+		return { items, ...repairedSessionIds.length === 0 ? {} : { repairedSessionIds } };
+	}
+	/** 从会话原文补齐缺失的派生缓存；任何失败都只降级为原有无摘要列表。 */
+	async repairArchivedProjection(header) {
+		const cache = this.ctx.get("sessionProjectionCache");
+		const persistence = this.ctx.get("sessionPersistence");
+		const projections = this.ctx.get("sessionProjections");
+		if (cache === void 0 || typeof cache.cachedSnapshot !== "function" || typeof cache.put !== "function") return false;
+		if (persistence === void 0 || typeof persistence.readFrom !== "function" || projections === void 0 || typeof projections.restore !== "function") return false;
+		try {
+			if (cache.cachedSnapshot(header) !== void 0) return false;
+			const stored = await persistence.readFrom(header.id, 0);
+			const meta = stored.meta ?? header;
+			const restored = projections.restore({}, stored.events, 0, meta);
+			if (restored === void 0 || typeof restored !== "object" || restored.checkpoint === void 0) return false;
+			await cache.put(header.id, {
+				createdAt: meta.createdAt,
+				...meta.cwd === void 0 ? {} : { cwd: meta.cwd }
+			}, restored.checkpoint);
+			return true;
+		} catch (error) {
+			this.ctx.logger.warn(`archive-manager: projection repair for archived session "${header.id}" failed: ${String(error)}`);
+			return false;
+		}
 	}
 	/**
 	* 把一个会话移出注册表全局归档集合，恢复其正常可见性（其记账位从未

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michengai/dsh-archive-manager",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "NPM-installable DSH Web plugin for managing archived sessions.",
   "type": "module",
   "packageManager": "pnpm@11.21.0",
@@ -42,6 +42,7 @@
     "@deepseek-ai/dsh-client-ui-workspace": ">=0.1.0-rc.5 <0.2.0",
     "@deepseek-ai/dsh-session": ">=0.1.0-rc.5 <0.2.0",
     "@deepseek-ai/dsh-session-projection-cache": ">=0.1.0-rc.5 <0.2.0",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.0-rc.5 <0.2.0",
     "@deepseek-ai/dsh-spill-local": ">=0.1.0-rc.5 <0.2.0",
     "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.5 <0.2.0",
     "@deepseek-ai/dsh-typert-registry": ">=0.1.0-rc.5 <0.2.0",
@@ -59,6 +60,7 @@
     "@deepseek-ai/dsh-client-ui-slots": "0.1.0-rc.6",
     "@deepseek-ai/dsh-client-web-react": "0.1.0-rc.6",
     "@deepseek-ai/dsh-session-projection-cache": "0.1.0-rc.6",
+    "@deepseek-ai/dsh-storage-domain": "0.1.0-rc.6",
     "@deepseek-ai/dsh-spill-local": "0.1.0-rc.6",
     "@deepseek-ai/dsh-typert-protocol": "0.1.0-rc.6",
     "@deepseek-ai/dsh-typert-registry": "0.1.0-rc.6",