@modusensus/dsh-mneme 0.8.15 → 0.9.0

package/lib/summarize.js

@@ -4,6 +4,8 @@ import { STR, langOf } from "./lang.js";
 // 重试一次不带 effort 字段）与 describeStreamFailure（流失败原因归一）——
 // 三条链路同一降级语义，不另造第二份实现。
 import { withEffortFallback, describeStreamFailure, EFFORT_REJECT_RE } from "./dream.js";
+// v0.9.0（M.O. 项目记忆）：蒸馏写入复用工具路径那把作用域解析器，见 createSummarizer。
+import { createScopeResolver } from "./scope.js";
 
 // 编码记忆蒸馏 prompt（codingRetrospect 开启时启用）：在通用记忆之外，额外提取
 // 三类编码专属记忆，专治重复踩坑 / 遗忘被否决方案 / 丢失工程约束。字段仍沿用
@@ -225,6 +227,83 @@ function eventSeq(event) {
 
 const SUBAGENT_MESSAGE_KINDS = new Set(["agent-message", "subagent-settled"]);
 
+// 兼容严格形状 [{type:"text",text}] 与宽松形状 ["字符串", ...]（lib-smoke 用例
+// 直接传字符串数组）。只取公开文本块；reasoning 私有推理块不进蒸馏上下文。
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => (typeof block === "string" ? block : (block && block.type === "text" && typeof block.text === "string" ? block.text : "")))
+    .filter((s) => s)
+    .join("\n");
+}
+
+/**
+ * Issue #399：公开会话正文的**单一隐私谓词**。
+ *
+ * 渲染（喂给 LLM 的转录）与落盘（distill_records 原始记录）必须走同一份判定，
+ * 各写一遍必然漂移——而漂移方向是「存下来的比 LLM 看过的更多」，也就是把从未
+ * 交给模型的内容留在盘上，是最糟的那个方向。所以这里只回答一个问题：这个事件
+ * 里有没有**可公开的会话正文**，是什么角色、什么原文；裁剪与格式化交给调用方。
+ *
+ * 返回 `[]` 表示不含可公开正文，包含三种情形：
+ * - 机器注入内容（AGENTS.md、skill 正文、文件变更通知）：source.kind 不是
+ *   user / agent-message / subagent-settled，整个事件被挡在门外；
+ * - 私有推理（assistant 的 reasoning 块）：textOf 只认 `type:"text"` 块，
+ *   思考链在两条路径上都到不了；
+ * - 工具调用与结果、code 输出：它们是**渲染专属**内容（codingRetrospect 需要
+ *   模型看见工具报错才能沉淀踩坑根因），但 #399 明确不落盘（已知边界 3），
+ *   因此由 collectMessages 的渲染分支单独处理，不进这个函数。
+ *
+ * @returns {Array<{role: "user"|"assistant"|"agent", text: string, key?: string}>}
+ *   text 是**未截断**原文；key 仅子会话消息用于跨事件去重。
+ */
+function publicTranscriptParts(event) {
+  const data = event?.data ?? {};
+  const kind = data?.source?.kind;
+  const parts = [];
+  const pushAgentMessage = (message) => {
+    const messageKind = message?.source?.kind;
+    if (!SUBAGENT_MESSAGE_KINDS.has(messageKind)) return;
+    const text = textOf(message?.content);
+    if (!text.trim()) return;
+    parts.push({
+      role: "agent",
+      text,
+      // 同一条子会话消息可能同时出现在 user/message 与 agent/inbox/spliced
+      // 里（投递路径重叠），按 id（无 id 时按内容）去重，否则转录会重复。
+      key: typeof message?.id === "string" && message.id
+        ? `id:${message.id}`
+        : `content:${messageKind}:${text}`
+    });
+  };
+  switch (event?.type) {
+    case "user/message": {
+      if (kind !== undefined && kind !== "user" && !SUBAGENT_MESSAGE_KINDS.has(kind)) break;
+      const text = textOf(data?.content);
+      if (!text.trim()) break;
+      if (SUBAGENT_MESSAGE_KINDS.has(kind)) pushAgentMessage(data);
+      else parts.push({ role: "user", text });
+      break;
+    }
+    case "agent/inbox/spliced": {
+      const inserted = Array.isArray(data?.inserted) ? data.inserted : [];
+      for (const message of inserted) pushAgentMessage(message);
+      break;
+    }
+    case "assistant/message": {
+      const blocks = Array.isArray(data?.message?.content) ? data.message.content : [];
+      const text = textOf(blocks);
+      // 私有推理块（reasoning）刻意不采集：蒸馏记忆不得沉淀模型私有思考链。
+      if (text.trim()) parts.push({ role: "assistant", text });
+      break;
+    }
+    default:
+      break;
+  }
+  return parts;
+}
+
 // DSH 0.1.2-rc.1 起 Session 改用 snapshotEvents()，兼容旧版 .events。
 // snapshotEvents 的范围参数按 seq 传入；再做一次事件级过滤，是为了兼容
 // 旧实现忽略参数、或把边界解释为闭区间的情况，同时避免用数组下标充当游标。
@@ -253,16 +332,6 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
   const events = snapshotSessionEvents(session, afterSeq, throughSeq);
   const lines = [];
   const seenSubagentMessages = new Set();
-  // 兼容严格形状 [{type:"text",text}] 与宽松形状 ["字符串", ...]（lib-smoke 用例
-  // 直接传字符串数组）。只取公开文本块；reasoning 私有推理块不进蒸馏上下文。
-  const textOf = (content) => {
-    if (typeof content === "string") return content;
-    if (!Array.isArray(content)) return "";
-    return content
-      .map((block) => (typeof block === "string" ? block : (block && block.type === "text" && typeof block.text === "string" ? block.text : "")))
-      .filter((s) => s)
-      .join("\n");
-  };
   const trim = (s, n) => (typeof s === "string" && s.length > n ? `${s.slice(0, n)}…` : s);
   const trimTranscript = (s, n) => {
     if (typeof s !== "string" || s.length <= n) return s;
@@ -283,29 +352,22 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
   };
   for (const event of events) {
     const data = event?.data ?? {};
-    const kind = data?.source?.kind;
-    switch (event.type) {
-      case "user/message": {
-        if (kind !== undefined && kind !== "user" && !SUBAGENT_MESSAGE_KINDS.has(kind)) break;
-        const text = textOf(data?.content);
-        if (!text.trim()) break;
-        if (SUBAGENT_MESSAGE_KINDS.has(kind)) appendSubagentMessage(data);
-        else lines.push(STR.transcriptUser[language](text));
-        break;
-      }
-      case "agent/inbox/spliced": {
-        const inserted = Array.isArray(data?.inserted) ? data.inserted : [];
-        for (const message of inserted) appendSubagentMessage(message);
-        break;
-      }
-      case "assistant/message": {
-        const msg = data?.message;
-        const blocks = Array.isArray(msg?.content) ? msg.content : [];
-        const text = textOf(blocks);
-        if (text.trim()) lines.push(STR.transcriptAssistant[language](text));
-        // 私有推理块（reasoning）刻意不采集：蒸馏记忆不得沉淀模型私有思考链。
-        break;
+    // #399：用户提示 / 助手公开正文 / 子会话交付三种可公开内容由共享谓词产出，
+    // 渲染与落盘因此不可能对「什么算公开」产生分歧（见 publicTranscriptParts）。
+    for (const part of publicTranscriptParts(event)) {
+      if (part.role === "agent") {
+        if (part.key && seenSubagentMessages.has(part.key)) continue;
+        if (part.key) seenSubagentMessages.add(part.key);
+        lines.push(STR.transcriptAgent[language](part.text));
+      } else if (part.role === "user") {
+        lines.push(STR.transcriptUser[language](part.text));
+      } else {
+        lines.push(STR.transcriptAssistant[language](part.text));
       }
+    }
+    // 渲染专属内容：工具调用/结果与 code 输出进 LLM 转录（codingRetrospect 靠
+    // 它们沉淀踩坑根因），但不进 distill_records——#399 已知边界 3 明说不覆盖。
+    switch (event.type) {
       case "tool/call": {
         const args = typeof data.arguments === "string"
           ? data.arguments
@@ -351,6 +413,56 @@ function collectMessages(session, maxChars = 8000, language = "zh", afterSeq, th
   };
 }
 
+/**
+ * Issue #399：把当前蒸馏窗口里**可公开的会话正文**收集成待落盘记录。
+ *
+ * 与 collectMessages 共用 publicTranscriptParts，但**不截断**：留存的意义就是
+ * 整段原文（超长用户提示在记录里必须全文，而喂给 LLM 的转录仍受 distillMaxChars
+ * 约束）——两条路径在裁剪上的差异是设计的一部分，测试锁 3 显式覆盖。
+ *
+ * 只收有 seq 的事件：distill_records 的主键是 (session_id, seq)，seq 也是溯源
+ * 区间与幂等的唯一依据；没有 seq 就无法表达「这条记录属于哪个窗口」。
+ */
+function collectTranscriptRecords(session, afterSeq, throughSeq, distilledAt) {
+  const events = snapshotSessionEvents(session, afterSeq, throughSeq);
+  const records = [];
+  const seenKeys = new Set();
+  // 窗口的 seq 区间取窗口内**全部**事件的 min/max（不只是公开正文那些）：这是
+  // LLM 实际看到的那个窗口，溯源链接要回答的是「这条记忆出自哪个窗口」。
+  let seqStart;
+  let seqEnd;
+  for (const event of events) {
+    const seq = eventSeq(event);
+    if (seq !== undefined) {
+      if (seqStart === undefined || seq < seqStart) seqStart = seq;
+      if (seqEnd === undefined || seq > seqEnd) seqEnd = seq;
+    }
+    if (seq === undefined) continue;
+    const parts = [];
+    for (const part of publicTranscriptParts(event)) {
+      if (part.key) {
+        if (seenKeys.has(part.key)) continue;
+        seenKeys.add(part.key);
+      }
+      parts.push(part);
+    }
+    if (!parts.length) continue;
+    // 主键是 (session_id, seq)：一个事件一行。agent/inbox/spliced 一次可投递多条
+    // 子会话消息（同 seq、同 role），各自成行会被 INSERT OR IGNORE 静默丢掉后几条；
+    // 按事件合并成一行才是这套主键的真实语义（角色同事件内不会混：user/message 与
+    // assistant/message 各只产出一条公开 part）。
+    records.push({
+      sessionId: session.id,
+      seq,
+      role: parts[0].role,
+      text: parts.map((part) => part.text).join("\n"),
+      windowId: `session:${session.id}:${seq}`,
+      distilledAt
+    });
+  }
+  return { records, seqStart, seqEnd };
+}
+
 // ── 智能调速器（429 保护）─────────────────────────────────────────────
 // 对话一多时 turn/end 会批量触发蒸馏，多个 LLM 请求"一拥而上"正是 429 的
 // 来源。这里借鉴机场安检的思路：所有蒸馏调用进同一个全局串行队列，按间隔
@@ -401,6 +513,16 @@ export function createSummarizer(ctx, service, config, deps = {}) {
   const setTimer = typeof deps.setTimeoutFn === "function" ? deps.setTimeoutFn : setTimeout;
   const clearTimer = typeof deps.clearTimeoutFn === "function" ? deps.clearTimeoutFn : clearTimeout;
 
+  // v0.9.0（M.O. 项目记忆）：蒸馏写入也要盖作用域章。此前只有 memory_save 那条工具
+  // 路径盖章（tools.js 的 memory_save 里 resolveSessionScope 到 workspaceLabel 那一段，
+  // 2026-10-13 在 :173-193），而机器提炼是写入量的绝大多数——于是「项目记忆」
+  // 在库里根本不存在（全库带 scope 的行不足 3%，且带 scope 的全部来自工具路径）。
+  // 这里不另造口径：同一把解析器（scope.js 的 createScopeResolver，2026-10-13 在 :24）、同一把闸门
+  // （config.scopeEnabled === true）、同一对列（*_scope + *_scope_source='auto'），
+  // 与工具路径逐字对齐。解析器的入参形状是「工具 exec」（内部读 exec.agent.session），
+  // 蒸馏路径手里直接有会话对象，所以包一层壳喂进去——不改解析器的公共契约。
+  const resolveSessionScope = createScopeResolver({ ctx, config, logger: ctx.logger });
+
   const inFlight = new Map();
   // Issue #127：per-session 上一次实际开跑时刻（最小间隔闸门用）。与 inFlight
   // 同生命周期，dispose 时一并清空。
@@ -574,23 +696,28 @@ export function createSummarizer(ctx, service, config, deps = {}) {
       // 判定纯规则（字符数），无模型参与；被挡下的窗口照常消费游标，否则每个
       // turn/end 都会重新评估同一段短文本。skip 原因进审计，作为后续按真实负载
       // 决定下一级规则的依据。
+      //
+      // 字符数改为无条件计算并写进审计 metadata：它是「下一级预判该不该开、阈值
+      // 该给多少」的唯一依据，而原先开关一关就一个数都不留（维护者本机 1240 条
+      // summarize_compress 成功行的 metadata 里窗口字符数为 0 条），验收 4「默认配置
+      // 下调用量可量化下降」因此无法对账。本改动只加计量，不动任何跳过决策——
+      // summarizeMinWindowChars 仍为 0 时行为逐字节不变。
+      const distillChars = messages.reduce(
+        (total, message) => total + (Array.isArray(message.content) ? message.content : [])
+          .reduce((n, part) => n + (typeof part?.text === "string" ? part.text.length : 0), 0),
+        0
+      );
       const minWindowChars = config.summarizeMinWindowChars ?? 0;
-      if (minWindowChars > 0) {
-        const distillChars = messages.reduce(
-          (total, message) => total + (Array.isArray(message.content) ? message.content : [])
-            .reduce((n, part) => n + (typeof part?.text === "string" ? part.text.length : 0), 0),
-          0
-        );
-        if (distillChars < minWindowChars) {
-          commitCursor(session.id, nextSeq);
-          writeAudit({
-            timestamp: new Date().toISOString(),
-            model_id: route ? `${route.provider}:${route.model}` : "unknown",
-            status: "skipped",
-            error_message: "window-too-small"
-          });
-          return;
-        }
+      if (minWindowChars > 0 && distillChars < minWindowChars) {
+        commitCursor(session.id, nextSeq);
+        writeAudit({
+          timestamp: new Date().toISOString(),
+          model_id: route ? `${route.provider}:${route.model}` : "unknown",
+          status: "skipped",
+          error_message: "window-too-small",
+          metadata: { distillChars, minWindowChars }
+        });
+        return;
       }
       // 只有真正准备发起一次 LLM 蒸馏时才占用最小间隔与 run 预算；失败路径仍按
       // 原语义占用（调用确实发生过），aborted 则由 finally 回滚。
@@ -758,6 +885,13 @@ export function createSummarizer(ctx, service, config, deps = {}) {
       const dedupeMode = config.summarizeDedupeMode ?? "off";
       let deduped = 0;
       let dedupeMaxSim = 0;
+      // v0.9.0（M.O. 项目记忆）：一次窗口解析一次——同一蒸馏窗口里所有条目同属一个
+      // 工作区、一个 agent 身份，逐条解析是白花钱。解析不到就落 NULL（NULL = 未标注 =
+      // 全局可见），且解析器绝不抛错（scope.js 的硬约束：记忆写入不该被作用域拖挂）。
+      // 闸门与 tools.js 的 autoStamping（2026-10-13 在 :180）同一把：关着就一个字段都不加，老行为不变。
+      const writeScope = config?.scopeEnabled === true
+        ? resolveSessionScope({ agent: { session } })
+        : null;
       const writes = [];
       for (const entry of entries) {
         // Provenance: the summarizer runs on a real session (turn/end hook), so
@@ -787,7 +921,57 @@ export function createSummarizer(ctx, service, config, deps = {}) {
         }
         writes.push({ entry, source, dup });
       }
-      if (writes.length) {
+      // #399：蒸馏窗口的原始公开记录 + 记忆级溯源链接，与记忆写入同事务落盘。
+      // 凭证与它的派生记忆必须同生共死：记忆写了而记录没写，溯源就断在「不知道
+      // 出自哪段原文」；记录写了而记忆没写，盘上留一份没有索引的原文。默认关
+      // （enabled !== true）时连收集都不做，一次 SQL 都不发（测试锁 5）。
+      const distilledAt = new Date(now()).toISOString();
+      const transcript = config?.distillRecords?.enabled === true
+        && typeof service.saveDistillRecords === "function"
+        ? collectTranscriptRecords(session, previousSeq, triggerSeq, distilledAt)
+        : null;
+      const writeWindow = () => {
+        const savedIds = [];
+        for (const { entry, source, dup } of writes) {
+          const outcome = service.saveWithDedupe({
+            ...entry,
+            source,
+            // 合并进既有行时不盖章，但这件事由 saveWithDedupe 的合并分支自己保证
+            // （它只认 explicit 来源升级，从不采纳这里传的 auto 字段）——调用方不能
+            // 靠「省略字段」来表达这个意图，因为省略会反向把合并也挡掉：
+            // findSessionDuplicate 只按 type+source+时间窗找候选，不看 scope；找到
+            // 候选后由 saveWithDedupe 的 scopeMatches 门决定并或不并。这里一省略，
+            // 新条目的 scope 就是 null，与已盖过章的候选不等，门必拒 → 回落新建，
+            // 而那一行同样是新行、同样该带章，却没有章可带。实测两轮蒸馏正是如此：
+            // 第二轮命中第一轮、门拒后新建，留下同题两行一行 auto 一行 NULL——
+            // 作用域隔离没做成，重复倒留下了。传字段、让合并分支按自己的口径处理，
+            // 才是「不重贴」与「新行必贴」两个要求的唯一相容解。
+            ...(writeScope ? { agent_scope: writeScope.agent_scope, agent_scope_source: "auto" } : {}),
+            ...(writeScope ? { workspace_scope: writeScope.workspace_scope, workspace_scope_source: "auto" } : {}),
+            ...(dup ? { _mergeInto: dup.memory.id } : {})
+          });
+          // created 与 merged 两条成功分支都返回 memory（含 id）；merged 时 id 是
+          // 被并入的既有记忆——本次窗口的原文确实贡献了它，链接它是诚实的。
+          if (outcome?.memory?.id) savedIds.push(outcome.memory.id);
+        }
+        if (transcript && transcript.records.length) {
+          service.saveDistillRecords(transcript.records);
+          if (transcript.seqStart !== undefined && transcript.seqEnd !== undefined
+            && typeof service.saveMemoryProvenance === "function") {
+            for (const memoryId of savedIds) {
+              service.saveMemoryProvenance({
+                memoryId,
+                sessionId: session.id,
+                seqStart: transcript.seqStart,
+                seqEnd: transcript.seqEnd,
+                createdAt: distilledAt
+              });
+            }
+          }
+        }
+        persistCursor(session.id, nextSeq);
+      };
+      if (writes.length || (transcript && transcript.records.length)) {
         // 查询去重目标可以异步执行，但记忆写入必须在同一个事务中完成。
         // 否则第 N 条写入失败时，前 N-1 条会残留，而重试同一 seq 窗口会重复
         // 追加它们。createService 始终提供 transaction；缺失时直接失败并保留
@@ -795,22 +979,17 @@ export function createSummarizer(ctx, service, config, deps = {}) {
         if (typeof service.transaction !== "function") {
           throw new Error("dsh-mneme: atomic summarization writes require service.transaction");
         }
-        service.transaction(() => {
-          for (const { entry, source, dup } of writes) {
-            service.saveWithDedupe({
-              ...entry,
-              source,
-              ...(dup ? { _mergeInto: dup.memory.id } : {})
-            });
-          }
-          persistCursor(session.id, nextSeq);
-        });
+        service.transaction(writeWindow);
       } else {
         // 空数组是合法成功：没有记忆写入，但本次事件窗口仍然应被持久消费。
         persistCursor(session.id, nextSeq);
       }
-      if (audit && (capped > 0 || deduped > 0 || parsedResult.salvaged)) {
+      // Issue #239 定标：窗口字符数无条件随成功行落进 metadata。原先只有
+      // capped / deduped / salvaged 其中一项发生时才建 metadata，默认档位下
+      // 一条都不留——下一级预判规则的阈值就无从定标。
+      if (audit) {
         audit.metadata = {
+          distillChars,
           parsed: parsed.length,
           ...(parsedResult.salvaged ? { json_salvaged: true } : {}),
           ...(capped > 0 ? { capped } : {}),

package/lib/tools.js

@@ -7,6 +7,7 @@ import { matchesPlatform } from "./runtime/closure.js";
 import { verifyPayload } from "./runtime/verify.js";
 import { TOOL_GUIDE, CONTINUITY_TOOL_RULE } from "./guide.js";
 import { injectChildEnabled } from "./config.js";
+import { lastUserQuery } from "./inject.js";
 
 const TEXT_OUTPUT = (text) => [{ type: "text", text }];
 // Per-registry tool-name registry: guards against duplicate registration on
@@ -381,6 +382,14 @@ export function createTools(ctx, service, config, embedder) {
         render: (_args, value) => TEXT_OUTPUT(`Updated memory ${value.memory.id}: ${value.memory.title}`)
       },
       async execute(args) {
+        // v0.9.0：失败表的 query 是「当时到底想干什么」唯一的落点，而 service
+        // 层看不到会话（它只认 ctx.query，见 src/service.js 的 saveFailure 注释）。
+        // 工具层是唯一同时握着改写动作与本轮会话的入口：没给 reason 就退回当轮用户
+        // 原话，取法与注入侧共用同一份实现（src/inject.js 的 lastUserQuery），不复制
+        // 第二份。两边都取不到时仍然写 NULL——空串会假装「有意图」，NULL 才说实话。
+        const exec = arguments[1];
+        const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+        const query = reason || lastUserQuery(exec) || undefined;
         const memory = service.update(args.id, {
           title: args.title,
           content: args.content,
@@ -389,10 +398,10 @@ export function createTools(ctx, service, config, embedder) {
           importance: args.importance,
           // 复核项 4（#170）：strictScope 下他 scope 的行按「不存在」处理（与 get 对齐），
           // 展开恒为 undefined，仅承担写入前校验。
-          ...(assertVisibleForTool(args.id, arguments[1])),
+          ...(assertVisibleForTool(args.id, exec)),
           ...(args.agent_scope !== undefined ? { agent_scope: args.agent_scope } : {}),
           ...(args.workspace_scope !== undefined ? { workspace_scope: args.workspace_scope } : {})
-        }, { query: args.reason });
+        }, { query });
         return { memory: { id: memory.id, title: memory.title, content: memory.content } };
       }
     }),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@modusensus/dsh-mneme",
   "description": "Cross-session memory plugin for DeepSeek Harness with autoDream consolidation: SQLite store, Markdown mirrors, 9 model tools, automatic injection, session summarization, user profile/rules, custom slash commands, vector (semantic) search, and a Web GUI panel",
-  "version": "0.8.15",
+  "version": "0.9.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/scripts/publish-gate.mjs

@@ -0,0 +1,197 @@
+// 发布闸门：publish 步之后**必须**确认这个版本真的能被 registry 看见，看不见就整轮失败。
+//
+// 为什么需要它：原先这一步是
+//   echo "Published: $(npm view "@modusensus/dsh-mneme@${V}" version)"
+// 命令替换里的失败**不会**让 `set -e` 退出。v0.8.16 那次日志白纸黑字写着
+// `npm error code E404 / 404 No match found for version 0.8.16`，step 与 job 却都是绿的。
+// 也就是说「真发不出去」（token 失效、权限不足、npm 侧拒绝）与「发出去了」在 CI 上是同一种
+// 颜色，只有人翻日志才看得出来 —— 闸门的意义恰恰是没人翻日志的时候。
+//
+// 为什么是轮询而不是一次性查询：registry 有传播延迟，v0.8.16 实测 publish 到可见约 4.5 分钟
+// （11:15:52Z → 11:20:22Z）。一次性查询只有两种结局：忽略失败（就是现在的假绿），或者拿传播
+// 延迟当发布失败（假红）。幂等跳过那条路径（版本已存在）**首次探测即通过**，所以只有真发新版
+// 才付等待成本。
+//
+// 为什么探测走 registry 公开 HTTP 面而不是 `npm view`：不依赖 .npmrc 里的 token、不依赖 npm CLI
+// 的 E404 语义，而且能把「还没传播」与「网络异常」分开报出来 —— 两种都重试，但日志里要能区分，
+// 否则排障时又得靠猜。
+//
+// 与 scripts/changelog-prep.mjs 同一个理由：逻辑收在可注入的模块里才测得到（probe/sleep/now 全
+// 可注入，单测零网络零等待），入口只负责读参数与决定退出码。
+
+import { pathToFileURL } from "node:url";
+
+export const PACKAGE_NAME = "@modusensus/dsh-mneme";
+export const REGISTRY_ORIGIN = "https://registry.npmjs.org";
+
+/** 默认 10 分钟：实测传播 ~4.5 分钟，留一倍余量；超时=发布失败，宁可红也不许假绿。 */
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/** 默认 15 秒：一次发布最多 40 次探测，日志行数与 registry 负载都可接受。 */
+export const DEFAULT_INTERVAL_MS = 15 * 1000;
+/** 单次探测的 HTTP 超时：挂死的请求必须自己失败，不能吃掉整段预算。 */
+export const DEFAULT_PROBE_TIMEOUT_MS = 15 * 1000;
+
+/**
+ * 单版本的 registry URL。scoped 包名必须整体 encodeURIComponent（`@scope/name` → `%40scope%2Fname`）：
+ * 直接拼裸 `/` 会被当成路径分隔符，registry 回 404 —— 那正是「闸门自己造成的假红」。
+ */
+export function versionUrl(name, version, origin = REGISTRY_ORIGIN) {
+  return `${origin.replace(/\/+$/, "")}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`;
+}
+
+/**
+ * 探测一次「该版本是否已在 registry 上」。
+ *
+ * 永不抛错：任何异常都折成 `{ok:false, reason, detail}`，让上层的重试与超时逻辑保持单一形状。
+ * `reason` 取值：`missing`(404，多半是还没传播) / `network`(请求本身失败) / `http`(非 2xx/404) /
+ * `bad-json` / `mismatch`(200 但版本号对不上)。
+ *
+ * @param {string} version 如 "0.8.16"
+ * @param {{name?: string, origin?: string, fetchImpl?: typeof fetch, timeoutMs?: number}} [options]
+ * @returns {Promise<{ok: true, version: string, tarball: string} | {ok: false, reason: string, detail: string}>}
+ */
+export async function probeVersion(version, {
+  name = PACKAGE_NAME,
+  origin = REGISTRY_ORIGIN,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = DEFAULT_PROBE_TIMEOUT_MS
+} = {}) {
+  const url = versionUrl(name, version, origin);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers: { accept: "application/json" },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  } catch (error) {
+    return { ok: false, reason: "network", detail: `请求失败：${error?.message ?? error}（${url}）` };
+  }
+  if (response.status === 404) {
+    return { ok: false, reason: "missing", detail: `HTTP 404，registry 上还看不到（${url}）` };
+  }
+  if (!response.ok) {
+    return { ok: false, reason: "http", detail: `HTTP ${response.status}（${url}）` };
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (error) {
+    return { ok: false, reason: "bad-json", detail: `响应不是 JSON：${error?.message ?? error}` };
+  }
+  if (body?.version !== version) {
+    return { ok: false, reason: "mismatch", detail: `registry 返回的版本是 ${body?.version ?? "(缺失)"}` };
+  }
+  return { ok: true, version, tarball: body?.dist?.tarball ?? "" };
+}
+
+/**
+ * 轮询到版本可见为止；超时即 `{ok:false, reason:"timeout"}`。
+ *
+ * 契约（单测锁的就是这条）：**看不见就绝不返回 ok:true**。任何把超时折叠成成功、或者把
+ * 「探测失败」当成「跳过校验」的改法，都等于退回 v0.8.16 那种假绿。
+ *
+ * @param {string} version
+ * @param {{name?: string, origin?: string, timeoutMs?: number, intervalMs?: number,
+ *          now?: () => number, sleep?: (ms: number) => Promise<void>,
+ *          probe?: () => Promise<{ok: boolean, detail?: string}>, log?: (line: string) => void}} [options]
+ */
+export async function waitForPublished(version, {
+  name = PACKAGE_NAME,
+  origin = REGISTRY_ORIGIN,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  now = () => Date.now(),
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  probe = () => probeVersion(version, { name, origin }),
+  log = () => {}
+} = {}) {
+  const startedAt = now();
+  let attempts = 0;
+  let lastError = "";
+  for (;;) {
+    attempts += 1;
+    const result = await probe();
+    // 探测成功即算通过，**不再回头比期限**：预算是「等多久才放弃」，不是「多久之后就算没发布」。
+    // 单次探测自带 HTTP 超时（默认 15 秒），所以晚到的成功最多超出预算十几秒；而版本真的在
+    // registry 上就等于发布成功，因为晚到几秒把它判红才是假红——这个闸门存在的理由正是消灭
+    // 假绿，不该顺手制造另一种失真。反过来，探测失败仍严格按预算收口（见下）。
+    if (result?.ok) {
+      return { ok: true, version, attempts, waitedMs: now() - startedAt, tarball: result.tarball ?? "" };
+    }
+    lastError = result?.detail ?? "未知原因";
+    const waitedMs = now() - startedAt;
+    log(`第 ${attempts} 次探测（已等 ${Math.round(waitedMs / 1000)}s）：${lastError}`);
+    if (waitedMs >= timeoutMs) {
+      return { ok: false, reason: "timeout", attempts, waitedMs, lastError };
+    }
+    // 只睡到预算耗尽为止：最后一次探测落在超时点上，不额外多睡一整轮。
+    await sleep(Math.min(intervalMs, timeoutMs - waitedMs));
+  }
+}
+
+/**
+ * 入口参数：位置参数是版本号，另可覆盖 `--timeout-ms` / `--interval-ms`（排障与手动跑用）。
+ * 缺版本号如实回报 `missing-version`，由入口打印用法并退出 1。
+ */
+export function parseArgs(argv = []) {
+  const out = { version: "", timeoutMs: DEFAULT_TIMEOUT_MS, intervalMs: DEFAULT_INTERVAL_MS };
+  const positional = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--timeout-ms" || arg === "--interval-ms") {
+      const key = arg === "--timeout-ms" ? "timeoutMs" : "intervalMs";
+      const value = Number(argv[i + 1]);
+      if (!Number.isFinite(value) || value <= 0) return { ok: false, reason: `${arg} 需要一个正数` };
+      out[key] = value;
+      i += 1;
+      continue;
+    }
+    positional.push(arg);
+  }
+  if (positional.length !== 1) return { ok: false, reason: "missing-version" };
+  out.version = positional[0];
+  return { ok: true, ...out };
+}
+
+/** 入口：CI 与手动都用它；失败一律 `process.exit(1)`，绝不吞掉。 */
+export async function main(argv = process.argv.slice(2), {
+  log = console.log,
+  error = console.error,
+  wait = waitForPublished
+} = {}) {
+  const parsed = parseArgs(argv);
+  if (!parsed.ok) {
+    error(`用法：node scripts/publish-gate.mjs <版本号> [--timeout-ms 600000] [--interval-ms 15000]`);
+    error(`参数有误：${parsed.reason}`);
+    return 1;
+  }
+  log(`等待 ${PACKAGE_NAME}@${parsed.version} 在 registry 上可见（最多 ${parsed.timeoutMs / 1000}s）…`);
+  const result = await wait(parsed.version, {
+    timeoutMs: parsed.timeoutMs,
+    intervalMs: parsed.intervalMs,
+    log
+  });
+  if (!result.ok) {
+    error(
+      `发布闸门未通过：${PACKAGE_NAME}@${parsed.version} 在 ${Math.round(result.waitedMs / 1000)}s 内` +
+      `（${result.attempts} 次探测）始终看不到 —— 最后一次：${result.lastError}`
+    );
+    error(`publish 步很可能失败了（token 失效 / 权限不足 / npm 侧拒绝），请翻上面 publish 步的日志。`);
+    return 1;
+  }
+  const waitedSec = Math.round(result.waitedMs / 1000);
+  log(`✓ ${PACKAGE_NAME}@${result.version} 已在 registry 上可见（第 ${result.attempts} 次探测，等了 ${waitedSec}s）`);
+  if (result.tarball) log(`  tarball: ${result.tarball}`);
+  return 0;
+}
+
+// import 即执行会让单测没法只 import 纯函数（changelog-prep.mjs 的同一教训），故用主模块判别。
+// 比较用 pathToFileURL：手拼 `file://${argv[1]}` 在本机（Windows 盘符 + 非 ASCII 路径）拼不出合法 URL，
+// 判别会恒假 —— 那样的失败是静默的：脚本什么也不做，还退出 0。
+//
+// 用 `process.exitCode` 而不是 `process.exit()`：刚做完 HTTP 请求就硬退，会在 Windows 上撞到
+// libuv 的 `Assertion failed: !(handle->flags & UV_HANDLE_CLOSING)`（实测 0.8.16 成功路径复现），
+// 退出码变成 0xC0000409 而不是 0 —— 一个把成功报成崩溃的退出路径，正好与本次要修的假绿同类。
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  process.exitCode = await main();
+}