sage-mem 2.1.21 → 2.1.22

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.21`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `2.1.22`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.1.21`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.22`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/client.js

@@ -61,6 +61,148 @@ window.__ModuleLoader__.load({
 			return "rgba(" + ((n >> 16) & 255) + "," + ((n >> 8) & 255) + "," + (n & 255) + "," + a.toFixed(3) + ")";
 		}
 
+		// ── 陈旧宿主（2.1.22 / issue #10）────────────────────────────────
+		//
+		// `@deepseek-ai/dsh-typert-loader` 把每个包的 TYPERT manifest **按包名缓存、
+		// 进程内不失效**（它的头注原文：Package verdicts and imported manifests are
+		// cached per package name and never expire）。于是「开着 DSH 装上新版 sage-mem」
+		// 之后，宿主进程里仍然是升级前的 strict descriptor（2.1.1 的 writeFile 只有
+		// name/content 两个 wire 字段），而浏览器这边是从磁盘现取的新客户端分片 ——
+		// 第三参 opts 会在宿主**执行之前**被网关挡掉：
+		//
+		//   gateway/arguments-invalid: args fields do not match the descriptor:
+		//   unexpected "opts"
+		//
+		// 真正要清掉的是宿主进程里那份旧 manifest（彻底退出 DSH，含托盘常驻进程；
+		// 只关窗口不够）。但用户不该被卡在这里：写操作按旧协议降级重试。
+
+		/**
+		 * 只认「旧 strict descriptor 不认第三参」这一种结构化失败。
+		 *
+		 * ⚠️ 两种形态都要认（2026-11-01 真机抓到）：网关的失败既可能被**拒绝**（reject），
+		 * 也可能作为 remote 的**返回值** `{ok:false, error}` 回来 —— 后者是 api-gateway
+		 * 的 RemoteResult 语义，sage-mem 面板的其它写路径也一直在读 `r.ok === false`。
+		 * 只判 rejection 的话，真实环境里这条降级根本不会触发（第一版就踩了）。
+		 *
+		 * 判据同时看 code 与文案：同一个 `gateway/arguments-invalid` 也可能是在拒别的
+		 * 字段，甚至别的调用方传错参数 —— 那些都必须原样抛出，不能拿兼容降级去吞。
+		 * @returns 出问题的那个 error 对象，或 null。
+		 */
+		function staleHostWriteCause(value) {
+			const candidate = value && value.ok === false && value.error ? value.error : value;
+			if (!candidate) return null;
+			const code = typeof candidate.code === "string" ? candidate.code : "";
+			const message = String(candidate.message || candidate);
+			if (code !== "gateway/arguments-invalid" && !/gateway\/arguments-invalid/.test(message)) return null;
+			return /unexpected\s+["']?opts["']?/i.test(message) ? candidate : null;
+		}
+
+		/** 布尔版判据（面板/测试可读）。 */
+		function isStaleHostWriteError(value) {
+			return staleHostWriteCause(value) !== null;
+		}
+
+		/**
+		 * 只认「文件不存在」这一种读失败（宿主 readFile / readRaw 的 ENOENT 文案）。
+		 *
+		 * 陈旧宿主降级里的 create 探针必须用它：读失败也可能是权限 / IO 错误，
+		 * 那种情况下**不能**把目标当成「不存在」去覆盖写（2.1.10 / Q10 的教训）。
+		 */
+		function isNotFoundError(error) {
+			return /ENOENT|no such file|not exist/i.test(String((error && error.message) || error));
+		}
+
+		/**
+		 * 「目标是否已存在」探针（陈旧宿主创建降级用）。
+		 *
+		 * ⚠️ 两种返回形态都要认（2026-11-01 真机抓到）：宿主方法抛出的错误经 api-gateway
+		 * 可能变成**返回值** `{ok:false, error}`（RemoteResult 语义），也可能仍是 rejection。
+		 * 只处理 rejection 会把「文件不存在」误判成「已存在」—— 那会让新建永远报撞名。
+		 *
+		 * @returns Promise<boolean>：true=已存在；false=明确的 not-found；
+		 *          其它读失败（权限 / IO / 网关）抛出来，由调用方决定不降级。
+		 */
+		function probeRemoteExists(remote, method, arg) {
+			const call = new Promise(function (resolve) {
+				const fn = remote && remote[method];
+				if (typeof fn !== "function") throw new Error("sage-mem: host has no " + method);
+				resolve(fn.call(remote, arg));
+			});
+			const classify = function (error) {
+				if (isNotFoundError(error)) return false;
+				throw error;
+			};
+			return call.then(function (result) {
+				if (result && result.ok === false && result.error) return classify(result.error);
+				return true;
+			}, classify);
+		}
+
+		/**
+		 * 写调用 + 陈旧宿主降级。
+		 *
+		 * @param remote  宿主 remote 代理
+		 * @param method  写方法名（writeFile / writeRaw / writeArchived）
+		 * @param args    位置参数（不含 opts）
+		 * @param opts    写协议第三参；undefined 表示旧调用方，直接按旧协议写
+		 * @param probeExists 仅 create 语义用：探测目标是否已存在的函数（Promise<boolean>）。
+		 *       陈旧宿主没有 create 语义，**没有探针就不降级** —— 宁可这次写失败，也不拿走
+		 *       条件覆盖写去顶创建。
+		 * @returns Promise<{result, degraded}>；degraded=true 表示这次按旧协议写入，
+		 *          expectedRevision 的版本校验没有生效，界面必须把这件事告诉用户。
+		 */
+		function writeWithFallback(remote, method, args, opts, probeExists) {
+			function send(extraOpts) {
+				return new Promise(function (resolve) {
+					const fn = remote && remote[method];
+					if (typeof fn !== "function") throw new Error("sage-mem: host has no " + method);
+					// ⚠️ 第三个**位置参数**必须保留（哪怕值是 undefined）：客户端 remote 代理按
+					// 客户端描述符校验位置参数个数（三个写方法都声明了 3 个），少传一个会当场报
+					// 「client api: memory/writeFile expected 3 argument(s), got 2」—— 降级根本没
+					// 走到网关。undefined 在 JSON 里自然缺席，宿主旧接口只看到 name/content，
+					// 正好就是旧协议（2026-11-01 真机抓到）。
+					resolve(fn.apply(remote, args.concat([extraOpts])));
+				});
+			}
+			function degraded(result) { return { result: result, degraded: true }; }
+			/** 降级重试；返回 null 表示「这次不该降级」，由调用方把原始失败原样交出去。 */
+			function recover() {
+				if (opts && opts.create === true) {
+					// 降级不是无条件的：旧宿主没有 create 语义，先探一次存在性。
+					if (typeof probeExists !== "function") return null;
+					return Promise.resolve().then(probeExists).then(function (exists) {
+						if (exists) {
+							return degraded({
+								ok: false,
+								code: "already_exists",
+								error: t("error.staleHostExists", { file: String(args[0]) }),
+							});
+						}
+						return send(undefined).then(degraded);
+					});
+				}
+				return send(undefined).then(degraded);
+			}
+			if (opts === undefined) {
+				return send(undefined).then(function (result) { return { result: result, degraded: false }; });
+			}
+			function onStale(original) {
+				const recovered = recover();
+				if (recovered === null) throw staleHostWriteCause(original) || original;
+				return recovered;
+			}
+			return send(opts).then(
+				function (result) {
+					if (!isStaleHostWriteError(result)) return { result: result, degraded: false };
+					return onStale(result);
+				},
+				function (error) {
+					if (!isStaleHostWriteError(error)) throw error;
+					return onStale(error);
+				},
+			);
+		}
+
 		// ── 类型词表（唯一定义） ──
 		// 文件列表的排序 / 筛选 / 徽章、星图的 kind 标签与配色，全部从这里取。
 		const TYPE_ORDER = ["user", "feedback", "project", "reference"];
@@ -3888,11 +4030,13 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"error.saveRejected": "保存被拒绝",
 			"error.skeletonFailed": "建立索引骨架失败",
 			"error.openDirFailed": "打开记忆目录失败",
+			"error.staleHostExists": "同名文件已经存在：{file} —— 宿主还停在升级前的 sage-mem（旧写协议没有 create 语义），已拒绝，没有覆盖它",
 			"notice.indexExists": "MEMORY.md 已经存在，没有改动它。",
 			"notice.indexCreated": "已建立 MEMORY.md 索引骨架。",
 			"notice.updated": "已更新 {file}",
 			"notice.saved": "已保存 {file}",
 			"notice.rawNew": "已新建 {file}",
+			"notice.staleHostWrite": "已按旧协议写入 {file} —— 宿主仍停着升级前的 sage-mem（DSH 没有完全退出），本次未做版本校验；彻底退出 DSH（含托盘）后重开即可恢复",
 			"notice.deleted": "已删除 {file}",
 			"notice.archived": "已归档 {file} —— 它现在在「已归档」视图里，随时可以恢复",
 			"notice.batchPartial": "已归档 {done} 条，{failed} 条没成功：{files}",
@@ -4369,11 +4513,13 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			"error.saveRejected": "Save rejected",
 			"error.skeletonFailed": "Failed to create the index skeleton",
 			"error.openDirFailed": "Failed to open the memory directory",
+			"error.staleHostExists": "A file with this name already exists: {file} — the host is still on the pre-upgrade sage-mem (the old write protocol has no create semantics), so it was refused and nothing was overwritten",
 			"notice.indexExists": "MEMORY.md already exists; it was left unchanged.",
 			"notice.indexCreated": "MEMORY.md index skeleton created.",
 			"notice.updated": "Updated {file}",
 			"notice.saved": "Saved {file}",
 			"notice.rawNew": "Created {file}",
+			"notice.staleHostWrite": "Wrote {file} with the legacy protocol — the host still runs the pre-upgrade sage-mem (DSH did not fully exit), so this write skipped the version check; fully quit DSH (including the tray) and reopen to restore",
 			"notice.deleted": "Deleted {file}",
 			"notice.archived": "Archived {file} — it is now under the Archived view and can be restored at any time",
 			"notice.batchPartial": "Archived {done}, {failed} failed: {files}",
@@ -6129,12 +6275,18 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				// 服务端负责「全新安装、memory 目录还不存在」时先建父目录；
 				// 已有索引 → 明确回 already_exists（逐字节不动）。绝不再「先读一次、读失败就当
 				// 可以覆盖」—— 读失败也可能是权限错误，而那正是会顶掉一份真索引的路。
-				remote.writeRaw("MEMORY.md", INDEX_SKELETON, { create: true }).then(function (res) {
-					const out = unwrap(res);
+				// 2.1.22（issue #10）：陈旧宿主没有 create 语义，降级前先探一次存在性。
+				// 探针只认「明确的 not-found」；读失败（权限 / IO）一律不降级 —— 否则会把一份
+				// 读不到的真索引当成「不存在」顶掉（2.1.10 / Q10 的教训）。
+				const probeIndexExists = function () {
+					return probeRemoteExists(remote, "readRaw", "MEMORY.md");
+				};
+				writeWithFallback(remote, "writeRaw", ["MEMORY.md", INDEX_SKELETON], { create: true }, probeIndexExists).then(function (out) {
+					const res = unwrap(out.result);
 					setBusy(false);
-					if (out && out.code === "already_exists") { setNotice(t("notice.indexExists")); return; }
-					if (out && out.ok === false) { setError(out.error || t("error.skeletonFailed")); return; }
-					setNotice(t("notice.indexCreated"));
+					if (res && res.code === "already_exists") { setNotice(t("notice.indexExists")); return; }
+					if (res && res.ok === false) { setError(res.error || t("error.skeletonFailed")); return; }
+					setNotice(out.degraded ? t("notice.staleHostWrite", { file: "MEMORY.md" }) : t("notice.indexCreated"));
 					load();
 				}).catch(function (e) {
 					setBusy(false);
@@ -6225,17 +6377,26 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				}
 				// 2.1.2（Q02）：编辑已有文件时交回读到的 revision（盘上变了 → 宿主拒绝）；
 				// 新建走 createIfAbsent —— 撞上同名文件是**明确报已存在**，绝不覆盖入口。
+				const wasEditing = Boolean(editingFile);
 				const writeOpts = editingFile
 					? (formRevision ? { expectedRevision: formRevision } : undefined)
 					: { create: true };
-				remote.writeFile(safeName, content, writeOpts)
-					.then(function (r) {
+				// 2.1.22（issue #10）：宿主若还停在升级前的旧 manifest，先按旧协议降级一次；
+				// 新建语义在旧宿主上没有对应参数，降级前必须探存在性（绝不覆盖已有文件）。
+				const probeTarget = wasEditing ? null : function () {
+					return probeRemoteExists(remote, "readFile", safeName);
+				};
+				writeWithFallback(remote, "writeFile", [safeName, content], writeOpts, probeTarget)
+					.then(function (out) {
 						// host 侧对保留名 / 非字符串内容 / 超限一律返回 { ok: false, error }，不再抛异常。
 						// 冲突看**结构化 code**（stale_revision / already_exists），不解析文案：
 						// 编辑框不关、草稿原地保留，由用户看过最新内容后自己决定重新应用 —— 绝不自动重试覆盖。
+						const r = out.result;
 						if (r && r.ok === false) { setError(r.error || t("error.writeRejected")); return; }
 						closeForm();
-						setNotice(t(editingFile ? "notice.updated" : "notice.saved", { file: safeName }));
+						setNotice(out.degraded
+							? t("notice.staleHostWrite", { file: safeName })
+							: t(wasEditing ? "notice.updated" : "notice.saved", { file: safeName }));
 						load();
 					})
 					.catch(function (e) { setError(String((e && e.message) || e)); })
@@ -6394,12 +6555,16 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				// 原样交回：不 trim、不补 frontmatter、不做任何「智能」处理。
 				// 2.1.2（Q02）：带上读到的 revision；归档件在别处被改过 → 宿主回 stale_revision，
 				// 编辑框与文本原地保留（不自动重试覆盖）。
+				// 2.1.22（issue #10）：陈旧宿主按旧协议降级（没有 create 语义，这里本来也没有）。
 				const writeOpts = archRevision ? { expectedRevision: archRevision } : undefined;
-				remote.writeArchived(file, archText, writeOpts)
-					.then(function (r) {
+				writeWithFallback(remote, "writeArchived", [file, archText], writeOpts)
+					.then(function (out) {
+						const r = out.result;
 						if (r && r.ok === false) { setError(r.error || t("error.saveRejected")); return; }
 						setArchEdit(null);
-						setNotice(t("notice.saved", { file: file }));
+						setNotice(out.degraded
+							? t("notice.staleHostWrite", { file: file })
+							: t("notice.saved", { file: file }));
 						load();
 					})
 					.catch(function (e) { setError(String((e && e.message) || e)); })
@@ -6752,13 +6917,21 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				// 原样交回：不 trim、不补 frontmatter、不做任何「智能」处理。
 				// 2.1.2（Q02）：新建走 createIfAbsent（撞名明确失败、不覆盖）；编辑带读到的 revision
 				// （盘上变了 → stale_revision，文本原地保留，绝不自动重试覆盖）。
+				// 2.1.22（issue #10）：陈旧宿主按旧协议降级；新建语义要先探存在性，绝不覆盖。
+				const wasNew = Boolean(rawIsNew);
 				const writeOpts = rawIsNew
 					? { create: true }
 					: (rawRevision ? { expectedRevision: rawRevision } : undefined);
-				remote.writeRaw(name, rawText, writeOpts)
-					.then(function (r) {
+				const probeRaw = wasNew ? function () {
+					return probeRemoteExists(remote, "readRaw", name);
+				} : null;
+				writeWithFallback(remote, "writeRaw", [name, rawText], writeOpts, probeRaw)
+					.then(function (out) {
+						const r = out.result;
 						if (r && r.ok === false) { setError(r.error || t("error.saveRejected")); return; }
-						setNotice(t(rawIsNew ? "notice.rawNew" : "notice.saved", { file: name }));
+						setNotice(out.degraded
+							? t("notice.staleHostWrite", { file: name })
+							: t(wasNew ? "notice.rawNew" : "notice.saved", { file: name }));
 						setRawIsNew(false);
 						// 保存成功后把版本换成刚写下的那一版，连续保存不用重读
 						if (r && typeof r.revision === "string") setRawRevision(r.revision);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "2.1.21",
+  "version": "2.1.22",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",