@modusensus/dsh-mneme 0.9.1 → 0.9.2

package/src/dream/sleep.js

@@ -21,7 +21,7 @@ import { randomUUID, createHash } from "node:crypto";
 import { validateDecisions, applyDecisions, ACTIONS } from "./decisions.js";
 import { findPotentialConflicts, cosineSimilarity } from "./clustering.js";
 import { scopeKeyOf } from "../scope.js";
-import { buildReceipt, describeStreamFailure, resolveDreamEffort, withEffortFallback, maintainIndexAfterDream } from "../dream.js";
+import { buildReceipt, describeStreamFailure, resolveDreamEffort, withEffortFallback, withMaxTokensFallback, maintainIndexAfterDream } from "../dream.js";
 import { computeHeat } from "../heat.js";
 
 // Issue #126 review（Copilot）：默认档（sleepActionSet="conflict"）允许的动作 = 全局
@@ -172,6 +172,22 @@ function makeSummary(m) {
   return text.length <= SUMMARY_MAX ? text : `${text.slice(0, SUMMARY_MAX)}…`;
 }
 
+// issue #471 政策轴：被按下的作用域也不参与睡眠整理。与 dream.js 的 withoutPaused
+// 同源（那里记着「判定只许有一份实现」的理由），但这里是**单独一处**而不是复用：
+// 两个模块各被独立装配（runSleep / runDream 各自接 service），任何一个被换进只
+// 实现了一半 service 的夹具时都该各自降级，而不是因为对方模块没装而双双失效。
+//
+// 睡眠侧比日间加固侧更要紧：这几个相位不只读——phaseDemotion 会 setArchived 与
+// demoteToSummary（真改归档面），phasePatterns 会 mint 出 type=pattern 的新行
+// （凭空给被按下的作用域生出衍生记忆）。只挡日间那几处读入口的话，闸门开着而每
+// 6 小时一次的睡眠照样动手，那等于「按下」只是让它在白天看不见。
+//
+// service 上取不到 filterPaused 时（老装配、测试夹具）原样返回，与改动前一致。
+function withoutPaused(service, rows) {
+  if (typeof service?.filterPaused !== "function") return rows;
+  return service.filterPaused(rows);
+}
+
 // ---------------------------------------------------------------- phases
 
 /**
@@ -189,7 +205,7 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
   }
   const strictness = config.sleepConflictStrictness ?? "normal";
   const threshold = CONFLICT_THRESHOLDS[strictness] ?? CONFLICT_THRESHOLDS.normal;
-  const memories = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document");
+  const memories = withoutPaused(service, service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document"));
   if (memories.length < 2) return { status: "skipped", reason: "too few memories" };
   if (signal?.aborted) return { status: "aborted", reason: "user activity" };
 
@@ -313,7 +329,7 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
   // actionSet 已在候选构造前解析（跨类型候选需要它），这里只按档位选 prompt：
   // 默认档保持只有 conflict/keep 的窄 prompt，"full" 才开放六分支。
   const conflictPrompt = actionSet === "full" ? STR.prompts.conflictFull[language] : STR.prompts.conflict[language];
-  const runConflict = (withEffort) => {
+  const runConflict = (withEffort, tokens) => {
     conflictStreamFailure = "";
     return auditedSleepLlm(ctx, service, config, logger, {
       triggerSource: "sleep",
@@ -331,7 +347,7 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
     provider: route.provider,
     model: route.model,
     purpose: "sleep-conflict",
-    maxTokens: config.sleepMaxTokens ?? 2048,
+    maxTokens: tokens,
     ...(withEffort && sleepEffort ? { reasoningEffort: sleepEffort } : {}),
     messages: [
       { role: "system", content: [{ type: "text", text: conflictPrompt }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -339,7 +355,9 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
     ]
   }, reportUsage, (reason) => { conflictStreamFailure = describeStreamFailure(reason); }));
   };
-  const text = await withEffortFallback(ctx, sleepEffort, () => runConflict(true), () => runConflict(false), () => conflictStreamFailure);
+  // Issue #478：睡眠侧同样接 max_tokens 降级——面板 hint 已承诺「超上限同样自动降级」，
+  // 只挂 dream 三个点会让 sleepMaxTokens 的 131072 上限继续原样发。
+  const text = await withMaxTokensFallback(ctx, config.sleepMaxTokens ?? 2048, (tokens) => withEffortFallback(ctx, sleepEffort, () => runConflict(true, tokens), () => runConflict(false, tokens), () => conflictStreamFailure), () => conflictStreamFailure);
   if (text === undefined) {
     if (conflictStreamFailure) ctx.logger?.warn?.(`dsh-mneme sleep: conflict stream aborted or errored (${conflictStreamFailure})`);
     return { status: "failed", error: "llm failed" };
@@ -423,7 +441,10 @@ function phaseDemotion(service, config, logger, runId, signal = null) {
   const compressCut = Date.now() - compressDays * 86400000;
   const demoted = [];
   const archived = [];
-  for (const m of service.all()) {
+  // 政策轴在这里尤其要紧：下面两行会真改归档面（setArchived / demoteToSummary）。
+  // 把过滤放在循环之外、而不是在循环体里 continue：一旦将来有人在循环体里加
+  // 副作用（现已有），漏掉那条 continue 就是静默改到被按下的行。
+  for (const m of withoutPaused(service, service.all())) {
     if (signal?.aborted) break;
     if (m.archived || m.forgotten) continue;
     const ref = m.last_accessed_at ?? m.created_at;
@@ -472,9 +493,11 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
   const limit = config.sleepPatternMinMemories ?? 100;
   // #230：document 在查询层排除（excludeTypes）而不是截断后过滤——LIMIT 200
   // 先生效的话，指针行一多就会把普通记忆挤出扫描窗，池子饿到门槛以下。
-  const memories = service
+  // 政策轴同理必须排在 `.slice(0, limit)` **之前**，否则被按下的行照样占掉
+  // sleepPatternMinMemories 的名额，而它们既不会被扫、也不该挤掉别人（#471）。
+  const memories = withoutPaused(service, service
     .list({ limit: 200, includeForgotten: false, excludeTypes: ["document"] })
-    .filter((m) => !m.archived && m.type !== "summary" && m.type !== "pattern")
+    .filter((m) => !m.archived && m.type !== "summary" && m.type !== "pattern"))
     .sort((a, b) => (a.updated_at < b.updated_at ? 1 : -1))
     .slice(0, limit);
   if (memories.length === 0) return { status: "skipped", reason: "no memories to scan" };
@@ -485,7 +508,7 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
   const maxPatterns = config.sleepMaxPatternPerRun ?? 3;
   const sleepEffort = await resolveDreamEffort(ctx, route, config.sleepReasoningEffort, logger);
   let patternStreamFailure = "";
-  const runPattern = (withEffort) => {
+  const runPattern = (withEffort, tokens) => {
     patternStreamFailure = "";
     return auditedSleepLlm(ctx, service, config, logger, {
       triggerSource: "sleep",
@@ -500,7 +523,7 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
     provider: route.provider,
     model: route.model,
     purpose: "sleep-pattern",
-    maxTokens: config.sleepMaxTokens ?? 2048,
+    maxTokens: tokens,
     ...(withEffort && sleepEffort ? { reasoningEffort: sleepEffort } : {}),
     messages: [
       { role: "system", content: [{ type: "text", text: STR.prompts.pattern[language].replace("N", String(maxPatterns)) }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -508,7 +531,7 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
     ]
   }, reportUsage, (reason) => { patternStreamFailure = describeStreamFailure(reason); }));
   };
-  const text = await withEffortFallback(ctx, sleepEffort, () => runPattern(true), () => runPattern(false), () => patternStreamFailure);
+  const text = await withMaxTokensFallback(ctx, config.sleepMaxTokens ?? 2048, (tokens) => withEffortFallback(ctx, sleepEffort, () => runPattern(true, tokens), () => runPattern(false, tokens), () => patternStreamFailure), () => patternStreamFailure);
   if (text === undefined) {
     if (patternStreamFailure) ctx.logger?.warn?.(`dsh-mneme sleep: pattern stream aborted or errored (${patternStreamFailure})`);
     return { status: "failed", error: "llm failed" };
@@ -563,7 +586,7 @@ function phaseRelations(service, config, logger, runId, signal = null) {
   if (entities.length < 2) return { status: "skipped", reason: "too few entities" };
   const orphans = entities.filter((e) => (service.getRelations(e.id) ?? []).length === 0);
   if (orphans.length === 0) return { status: "skipped", reason: "no orphan entities" };
-  const memories = service.all().filter((m) => !m.archived && !m.forgotten);
+  const memories = withoutPaused(service, service.all().filter((m) => !m.archived && !m.forgotten));
   const seen = new Set();
   const related = [];
   const MAX_RELATIONS_PER_ORPHAN = 3;

package/src/dream.js

@@ -10,7 +10,7 @@ import { scopeKeyOf } from "./scope.js";
 import { isInPeakWindow, nextOffPeakAt } from "./peak-hours.js";
 import { createHash, randomUUID } from "node:crypto";
 import { STR, langOf } from "./lang.js";
-export { validateDecisions, applyDecisions, withEffortFallback, describeStreamFailure, resolveDreamEffort, resolveRoute };
+export { validateDecisions, applyDecisions, withEffortFallback, withMaxTokensFallback, parseMaxTokensCap, describeStreamFailure, resolveDreamEffort, resolveRoute };
 
 // Extract the first JSON array from LLM output, tolerating markdown fences,
 // leading/trailing prose, and common wrapper noise. Returns an array or null.
@@ -57,10 +57,24 @@ function totalChars(memories) {
 // 两处若各写一份过滤条件，重启播种读到的基线就会和运行期判定口径漂移（一个把
 // document 算进去、一个不算），阈值随之失真，且这种漂移只会在重启后才显形。
 function activeStoreSize(service) {
-  const memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+  const memories = withoutPaused(service, service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document"));
   return { count: memories.length, chars: totalChars(memories) };
 }
 
+// issue #471 政策轴：被按下的作用域不参与巩固，也就不该再撑着阈值把它自己触发起来。
+// 三个读入口（本函数、generateNarratives 的 inputs、runDream 的 memories）各自的附加
+// 条件不同——有的排 forgotten、有的不排——但「政策轴这一层」对三处是一样的，故收成
+// 一个助手而不是各写一遍过滤，理由与 activeStoreSize 开头记着的口径漂移同源：两处
+// 各写一份过滤条件，漂移只会在重启后才显形。
+//
+// 走 service.filterPaused 而不是自己读状态表：判定只许有一份实现（见
+// src/scope-state.js 的模块注释）。service 上取不到这个函数时（老装配、测试夹具）
+// 原样返回，行为与改动前一致。
+function withoutPaused(service, rows) {
+  if (typeof service?.filterPaused !== "function") return rows;
+  return service.filterPaused(rows);
+}
+
 // 基线的唯一合法形状：两个非负整数；其余（缺字段、负数、非整数、整个对象缺失）
 // 一律视为「没有基线」→ 调用方退回 {0,0}。播种值来自持久化列，可能是老库的 NULL
 // 或手工改坏的库，判定必须比调用点更严格，而不是相信数据库里存的一定合法。
@@ -399,6 +413,60 @@ async function withEffortFallback(ctx, effort, attempt, fallback, getStreamError
   }
 }
 
+// Issue #478：max_tokens 超服务商硬上限的拒收判别式与上限提取的单一来源。
+// 实测失败样例（dream_runs 180 连败）："max_tokens 不能超过 65536"——131072 的
+// 默认值原样发出，网关 400 直接拒，推理还没开始。与 EFFORT_REJECT_RE 同款思路：
+// 各处手写会漂移，导出供测试与其它调用点复用。
+export const MAX_TOKENS_REJECT_RE = /max[\s_-]*tokens?/i;
+
+/**
+ * 从拒收报错里提取服务商声明的 max_tokens 上限。只认「显式给数」的说法
+ * （不能超过 / at most / maximum value is / <= 65536 …），认不出就返回 null
+ * ——宁可不降级重试，也不能把报错里那个被拒的请求值（131072）误当上限。
+ * @returns {number|null}
+ */
+function parseMaxTokensCap(message) {
+  const m = String(message ?? "").match(
+    /(?:不能超过|不得超过|超出上限|至多|最多(?:只能|仅)?|at\s+most|no\s+more\s+than|maximum(?:\s+value)?(?:\s+is)?|max(?:\.)?(?:\s+value)?(?:\s+is)?|less\s+than\s+or\s+equal\s+to|<=?)\s*[:：]?\s*(\d{2,10})/i
+  );
+  const cap = m ? Number(m[1]) : null;
+  return cap && Number.isFinite(cap) && cap > 0 ? cap : null;
+}
+
+/**
+ * Issue #478：max_tokens 被服务商 400 拒收时，按报错里的上限自动降级重试一次。
+ * 与 withEffortFallback 同构：stream 路径的结果折叠成 undefined、真实原因在
+ * getStreamError() 里；throw 路径直接看 message。命中拒收且提取到比当前值小的
+ * 上限才重试（attempt 接收 tokens 值），否则原样返回/抛出。单次重试，与
+ * effort 的先例一致——重试后若仍被拒（同上限再报），cap >= tokens 的守卫让
+ * 它自然终止，不会循环。
+ */
+async function withMaxTokensFallback(ctx, maxTokens, attempt, getStreamError) {
+  const retry = (tokens, reason) => {
+    ctx.logger?.warn?.(`dsh-mneme dream: max_tokens ${maxTokens} rejected by provider (${reason}); retrying with ${tokens}`);
+    return attempt(tokens);
+  };
+  try {
+    const result = await attempt(maxTokens);
+    if (result === undefined) {
+      const reason = String(getStreamError?.() ?? "");
+      if (MAX_TOKENS_REJECT_RE.test(reason)) {
+        const cap = parseMaxTokensCap(reason);
+        if (cap && cap < maxTokens) return retry(cap, reason);
+      }
+    }
+    return result;
+  } catch (error) {
+    // AbortError 直接放行（取消意图绝不能被降级重试吞掉，与 effort 同款守卫）。
+    if (error?.name === "AbortError") throw error;
+    const message = String(error?.message ?? error);
+    if (!MAX_TOKENS_REJECT_RE.test(message)) throw error;
+    const cap = parseMaxTokensCap(message);
+    if (!cap || cap >= maxTokens) throw error;
+    return retry(cap, message);
+  }
+}
+
 /** 向量索引同步（总览与叙述条共用）：fail-safe，失败只 warn 不反噬主流程。 */
 async function reEmbedMemory(semantic, memory, logger) {
   if (!semantic?.embedder || !semantic?.vectorIndex || !memory) return;
@@ -418,7 +486,7 @@ async function reEmbedMemory(semantic, memory, logger) {
  * 任何失败降级为 0 条，绝不反噬 dream 主流程。
  */
 async function generateNarratives({ ctx, service, config, route, language, effort, semantic, logger }) {
-  const inputs = service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document");
+  const inputs = withoutPaused(service, service.all().filter((m) => !m.archived && !m.forgotten && m.type !== "summary" && m.type !== "document"));
   const clusters = clusterByTag(inputs, { minCluster: config.dreamNarrativeMinCluster ?? 3 });
   if (!clusters.length) return 0;
 
@@ -427,7 +495,7 @@ async function generateNarratives({ ctx, service, config, route, language, effor
       [`# ${tag}`, ...members.map((m) => `- id=${m.id} | title=${m.title} | ${m.content}`)].join("\n"))
     .join("\n\n");
   let streamFailure = "";
-  const runNarratives = (withEffort) => {
+  const runNarratives = (withEffort, tokens) => {
     streamFailure = "";
     return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
@@ -439,7 +507,7 @@ async function generateNarratives({ ctx, service, config, route, language, effor
       provider: route.provider,
       model: route.model,
       purpose: "compaction",
-      maxTokens: config.dreamMaxTokens ?? 2048,
+      maxTokens: tokens,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
         { role: "system", content: [{ type: "text", text: STR.prompts.narrative[language] }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -447,7 +515,7 @@ async function generateNarratives({ ctx, service, config, route, language, effor
       ]
     }, reportUsage, (reason) => { streamFailure = describeStreamFailure(reason); }));
   };
-  const text = await withEffortFallback(ctx, effort, () => runNarratives(true), () => runNarratives(false), () => streamFailure);
+  const text = await withMaxTokensFallback(ctx, config.dreamMaxTokens ?? 2048, (tokens) => withEffortFallback(ctx, effort, () => runNarratives(true, tokens), () => runNarratives(false, tokens), () => streamFailure), () => streamFailure);
 
   const entries = extractJsonArray(text);
   if (!Array.isArray(entries)) return 0;
@@ -946,7 +1014,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
   async function runDream(ctx, service, config) {
     const language = langOf(config);
     const logger = ctx.logger;
-    let memories = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+    let memories = withoutPaused(service, service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document"));
     if (memories.length === 0) return { ok: true, applied: 0, skipped: true, summary: false };
     // Issue #89：开跑时刻既喂给审计行（created_at），也是调度器闸门的时间基准。
     const dreamStartedAt = Date.now();
@@ -1127,7 +1195,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     const effort = await resolveDreamEffort(ctx, route, config.dreamReasoningEffort, logger);
     let decisions = null;
     let streamFailure = "";
-    const runConsolidation = (withEffort) => {
+    const runConsolidation = (withEffort, tokens) => {
       streamFailure = "";
       return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
@@ -1143,7 +1211,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       provider: route.provider,
       model: route.model,
       purpose: "compaction",
-      maxTokens: config.dreamMaxTokens ?? 4096,
+      maxTokens: tokens,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
         { role: "system", content: [{ type: "text", text: consolidationPrompt }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -1155,7 +1223,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       // Bug8: the consolidation call is audited (tokens/time/status). A throw
       // re-propagates to the catch below; an aborted stream returns undefined
       // and is treated as a failed run after the check below.
-      decisionText = await withEffortFallback(ctx, effort, () => runConsolidation(true), () => runConsolidation(false), () => streamFailure);
+      decisionText = await withMaxTokensFallback(ctx, config.dreamMaxTokens ?? 4096, (tokens) => withEffortFallback(ctx, effort, () => runConsolidation(true, tokens), () => runConsolidation(false, tokens), () => streamFailure), () => streamFailure);
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: consolidation llm call failed: ${String(error)}`);
       return finish({ ok: false, error: "llm failed", summary: false });
@@ -1368,7 +1436,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // a failed run; summary:false marks a run that produced no summary.
     let summaryText;
     let summaryStreamFailure = "";
-    const runSummary = (withEffort) => {
+    const runSummary = (withEffort, tokens) => {
       summaryStreamFailure = "";
       // Issue #258：总览阶段可用 dreamSummaryProvider/dreamSummaryModel 走独立路由
       //（默认空 = 沿用 dream 路由）；输入侧有 dreamSummaryMaxInputs 硬上限，
@@ -1386,7 +1454,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
       provider: summaryRoute.provider,
       model: summaryRoute.model,
       purpose: "compaction",
-      maxTokens: config.dreamMaxTokens ?? 2048,
+      maxTokens: tokens,
       ...(withEffort && effort ? { reasoningEffort: effort } : {}),
       messages: [
         { role: "system", content: [{ type: "text", text: STR.prompts.dreamSummary[language] }], source: { kind: "plugin:dsh-mneme", plugin: "dsh-mneme" } },
@@ -1404,7 +1472,11 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // 渐进恶化。倒序排序与 consolidate 窗口同款（updated_at desc, id tiebreak），
     // 保留最新的；0 = 关闭上限（回归全库行为，调用方自担 ctx）。
     // #230：document 指针行不进总览（与 dream/sleep 五个候选池的同款排除）。
-    const summaryAll = service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document");
+    // issue #471：这一处尤其不能漏——总览落库时是**无作用域**的 summary 行
+    // （saveWithDedupe 不带 agent_scope/workspace_scope），所以被按下作用域的内容
+    // 一旦进了总览，注入侧按作用域过滤就再也拦不住它：内容已经洗成了全局行。
+    // 别的入口漏了只是「那一条漏过去」，这里漏了是「洗一遍之后一直漏」。
+    const summaryAll = withoutPaused(service, service.all().filter((m) => !m.archived && m.type !== "summary" && m.type !== "document"));
     const summaryMaxInputs = Number.isInteger(config.dreamSummaryMaxInputs) ? config.dreamSummaryMaxInputs : 0;
     const summaryInputs = summaryMaxInputs > 0 && summaryAll.length > summaryMaxInputs
       ? [...summaryAll]
@@ -1425,7 +1497,7 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     );
     try {
       // Bug8: the summary call is audited too (operation dream_summarize).
-      summaryText = await withEffortFallback(ctx, effort, () => runSummary(true), () => runSummary(false), () => summaryStreamFailure);
+      summaryText = await withMaxTokensFallback(ctx, config.dreamMaxTokens ?? 2048, (tokens) => withEffortFallback(ctx, effort, () => runSummary(true, tokens), () => runSummary(false, tokens), () => summaryStreamFailure), () => summaryStreamFailure);
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: summary llm call failed: ${String(error)}`);
       return finish({ ok: false, error: "llm failed", applied, decisions: auditDecisions, outcome, frozen: frozenCount, summary: false });

package/src/embedding.js

@@ -31,10 +31,32 @@ function embeddingsUrl(baseUrl) {
  * Call the embeddings API for one text. Resolves to a Float64 array, or null
  * when the provider is not configured, the call fails, or the response is
  * unusable. Never throws: failures degrade to keyword search.
+ *
+ * The plain null return cannot tell the caller WHY — "model not loaded",
+ * "endpoint 404", "timeout" and "input rejected" all look identical, so the
+ * receipt ledger used to flatten them into one
+ * `embedding-request-returned-no-vector`. Use `embedTextDetailed` when the
+ * reason matters; this wrapper keeps the old contract for existing callers.
  */
-export async function embedText({ baseUrl, apiKey, model }, text) {
+export async function embedText(cfg, text) {
+  const out = await embedTextDetailed(cfg, text);
+  return out.vector;
+}
+
+/**
+ * Same call, but the failure mode is distinguishable: returns
+ * { vector: number[]|null, reason: null|string } where reason is one of
+ *   config-incomplete | request-failed:<err> | http-<status> |
+ *   response-not-json | response-no-vector | empty-text
+ * Never throws. `reason: null` means success.
+ */
+export async function embedTextDetailed({ baseUrl, apiKey, model }, text) {
   const url = embeddingsUrl(baseUrl);
-  if (!url || !apiKey || !model || !text) return null;
+  if (!url || !apiKey || !model || !text) {
+    // 空输入不是端点故障：区分开，否则「text 为空」会被误报成网络问题。
+    const missing = !url ? "baseUrl" : !apiKey ? "apiKey" : !model ? "model" : "text";
+    return { vector: null, reason: `config-incomplete:${missing}` };
+  }
   let res;
   try {
     res = await fetch(url, {
@@ -46,18 +68,33 @@ export async function embedText({ baseUrl, apiKey, model }, text) {
       body: JSON.stringify({ model, input: String(text).slice(0, 8000) }),
       signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
     });
-  } catch {
-    return null;
+  } catch (error) {
+    // 超时是 AbortSignal 抛的 TimeoutError；网络层错误（DNS/拒连）是 TypeError。
+    // 两者都走 request-failed，但带上类型，日志里能分清「慢」和「不通」。
+    const kind = error?.name === "TimeoutError" || error?.name === "AbortError" ? "timeout" : "network";
+    return { vector: null, reason: `request-failed:${kind}:${String(error?.message ?? error).slice(0, 200)}` };
+  }
+  if (!res.ok) {
+    // 状态码本身就是最有用的诊断：401/403 是钥匙、404 是路径、429 是限流、
+    // 5xx 是服务端。文本截断且不含请求体，日志安全。
+    let detail = "";
+    try {
+      const t = await res.text();
+      detail = String(t).slice(0, 200);
+    } catch { /* body unreadable, status alone is already informative */ }
+    return { vector: null, reason: `http-${res.status}${detail ? `:${detail}` : ""}` };
   }
-  if (!res.ok) return null;
   let body;
   try {
     body = await res.json();
   } catch {
-    return null;
+    return { vector: null, reason: "response-not-json" };
   }
   const vec = body?.data?.[0]?.embedding;
-  return Array.isArray(vec) && vec.length ? Array.from(vec) : null;
+  if (!Array.isArray(vec) || !vec.length) {
+    return { vector: null, reason: "response-no-vector" };
+  }
+  return { vector: Array.from(vec), reason: null };
 }
 
 /**
@@ -145,24 +182,17 @@ export function createEmbedder({ store, settings, logger, vectorIndex }) {
       return entry;
     }
     const text = [title, content].filter(Boolean).join("\n");
-    let vector = null;
-    try {
-      vector = await embedText(cfg, text);
-    } catch (error) {
-      const entry = { status: "failed", id, at, reason: String(error) };
-      ledger.record(entry);
-      logger?.warn?.(`[dsh-mneme] embed memory ${id} failed: ${String(error)}`);
-      return entry;
-    }
-    if (!vector) {
-      // embedText swallows the HTTP detail (404 / timeout / malformed body all
-      // resolve to null). The receipt still has to say "no vector", which is
-      // exactly the fact the write path never used to report.
-      const entry = { status: "failed", id, at, reason: "embedding-request-returned-no-vector" };
+    const detailed = await embedTextDetailed(cfg, text);
+    if (detailed.reason) {
+      // 回执带上可区分的失败模式（http-404 / request-failed:timeout /
+      // config-incomplete:model / response-no-vector ...），不再把「模型没配」
+      // 「请求挂了」「响应没有向量」压成同一个词。状态页与日志按 reason 分诊。
+      const entry = { status: "failed", id, at, reason: detailed.reason };
       ledger.record(entry);
-      logger?.warn?.(`[dsh-mneme] embed memory ${id} produced no vector`);
+      logger?.warn?.(`[dsh-mneme] embed memory ${id} failed: ${detailed.reason}`);
       return entry;
     }
+    const vector = detailed.vector;
     const model = modelHashOf(cfg.model);
     store.setEmbedding(id, vector, model);
     _dimension = vector.length;