@modusensus/dsh-mneme 0.7.18 → 0.7.21

package/src/dream/sleep.js

@@ -17,7 +17,8 @@
 import { randomUUID, createHash } from "node:crypto";
 import { validateDecisions, applyDecisions } from "./decisions.js";
 import { findPotentialConflicts } from "./clustering.js";
-import { buildReceipt, withEffortFallback } from "../dream.js";
+import { buildReceipt, describeStreamFailure, withEffortFallback } from "../dream.js";
+import { computeHeat } from "../heat.js";
 
 const SUMMARY_MAX = 120;
 // Conflict similarity threshold per strictness level (v0.4.0):
@@ -60,12 +61,17 @@ function parseJsonArray(text) {
 }
 
 /** Same stream consumption contract as dream.js. */
-async function streamText(ctx, options) {
+async function streamText(ctx, options, onStreamError) {
   if (!ctx?.llm?.stream) return undefined;
   let text = "";
   for await (const chunk of ctx.llm.stream(options)) {
     if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
     if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
+      // Same rc.1 error-as-finish-chunk behavior as dream.js — surface the
+      // cause instead of discarding it.
+      if (typeof onStreamError === "function") {
+        try { onStreamError(chunk.reason); } catch { /* diagnostics only */ }
+      }
       return undefined;
     }
   }
@@ -185,7 +191,10 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
     `候选冲突：\nid=${p.a.id} | type=${p.a.type} | title=${p.a.title}\n${p.a.content}\n---\nid=${p.b.id} | type=${p.b.type} | title=${p.b.title}\n${p.b.content}\n（相似度 ${p.similarity.toFixed(2)}）`
   ).join("\n\n");
   const sleepEffort = config.sleepReasoningEffort && config.sleepReasoningEffort !== "none" ? config.sleepReasoningEffort : null;
-  const runConflict = (withEffort) => streamText(ctx, {
+  let conflictStreamFailure = "";
+  const runConflict = (withEffort) => {
+    conflictStreamFailure = "";
+    return streamText(ctx, {
     provider: route.provider,
     model: route.model,
     purpose: "sleep-conflict",
@@ -195,9 +204,13 @@ async function phaseConflicts(ctx, service, config, logger, runId, semantic = nu
       { role: "system", content: [{ type: "text", text: CONFLICT_PROMPT }] },
       { role: "user", content: [{ type: "text", text: listText }] }
     ]
-  });
-  const text = await withEffortFallback(ctx, sleepEffort, () => runConflict(true), () => runConflict(false));
-  if (text === undefined) return { status: "failed", error: "llm failed" };
+  }, (reason) => { conflictStreamFailure = describeStreamFailure(reason); });
+  };
+  const text = await withEffortFallback(ctx, sleepEffort, () => runConflict(true), () => runConflict(false), () => conflictStreamFailure);
+  if (text === undefined) {
+    if (conflictStreamFailure) ctx.logger?.warn?.(`dsh-mneme sleep: conflict stream aborted or errored (${conflictStreamFailure})`);
+    return { status: "failed", error: "llm failed" };
+  }
   const decisions = parseJsonArray(text);
   if (!decisions) return { status: "failed", error: "invalid decisions json" };
   // validateDecisions 要求每个 snapshot id 恰好被 claim 一次。v0.4.4 起它本身
@@ -242,10 +255,22 @@ function phaseDemotion(service, config, logger, runId, signal = null) {
   for (const m of service.all()) {
     if (signal?.aborted) break;
     if (m.archived || m.forgotten) continue;
-    const ref = m.last_accessed_at ?? m.updated_at ?? m.created_at;
+    const ref = m.last_accessed_at ?? m.created_at;
     if (!ref) continue;
     const t = new Date(ref).getTime();
     if (Number.isNaN(t)) continue;
+    // v0.7.0 热联合判定（仅 heatEnabled 时启用；默认关则退回纯时间分层，
+    // 与 v0.7.12 行为一致）：时间窗之外再加两道保护闸——热度低于
+    // sleepHeatThreshold 且 importance<5 才允许降级。λ=0 的免疫类型 heat 恒
+    // 1.0 天然豁免（preference/pattern/summary 永不因 sleep 降级）；importance
+    // ≥5 的紧要记忆无论多冷都保留。`冷但重要` 与 `热但低值` 均不满足条件。
+    const heatOn = config.heatEnabled !== false;
+    if (heatOn) {
+      const heat = computeHeat(m, Date.now(), config);
+      const heatProtected = heat >= (config.sleepHeatThreshold ?? 0.05);
+      const important = (m.importance ?? 0) >= 5;
+      if (heatProtected || important) continue;
+    }
     if (t < compressCut) {
       service.setArchived(m.id, true);
       archived.push(m.id);
@@ -285,7 +310,10 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
     .join("\n");
   const maxPatterns = config.sleepMaxPatternPerRun ?? 3;
   const sleepEffort = config.sleepReasoningEffort && config.sleepReasoningEffort !== "none" ? config.sleepReasoningEffort : null;
-  const runPattern = (withEffort) => streamText(ctx, {
+  let patternStreamFailure = "";
+  const runPattern = (withEffort) => {
+    patternStreamFailure = "";
+    return streamText(ctx, {
     provider: route.provider,
     model: route.model,
     purpose: "sleep-pattern",
@@ -295,9 +323,13 @@ async function phasePatterns(ctx, service, config, logger, runId, signal = null)
       { role: "system", content: [{ type: "text", text: PATTERN_PROMPT.replace("N", String(maxPatterns)) }] },
       { role: "user", content: [{ type: "text", text: listText }] }
     ]
-  });
-  const text = await withEffortFallback(ctx, sleepEffort, () => runPattern(true), () => runPattern(false));
-  if (text === undefined) return { status: "failed", error: "llm failed" };
+  }, (reason) => { patternStreamFailure = describeStreamFailure(reason); });
+  };
+  const text = await withEffortFallback(ctx, sleepEffort, () => runPattern(true), () => runPattern(false), () => patternStreamFailure);
+  if (text === undefined) {
+    if (patternStreamFailure) ctx.logger?.warn?.(`dsh-mneme sleep: pattern stream aborted or errored (${patternStreamFailure})`);
+    return { status: "failed", error: "llm failed" };
+  }
   const decisions = parseJsonArray(text);
   if (!decisions || decisions.length === 0) return { status: "skipped", reason: "no patterns found" };
   // Evidence ids are provenance refs; an LLM-fabricated id would mint a dead

package/src/dream.js

@@ -1,7 +1,7 @@
 import { validateDecisions, applyDecisions } from "./dream/decisions.js";
 import { clusterMemories, findPotentialConflicts } from "./dream/clustering.js";
 import { createHash, randomUUID } from "node:crypto";
-export { validateDecisions, applyDecisions, withEffortFallback };
+export { validateDecisions, applyDecisions, withEffortFallback, describeStreamFailure };
 
 
 // Extract the first JSON array from LLM output, tolerating markdown fences,
@@ -238,18 +238,34 @@ function buildRecordReceipts({ runId, committed, snapshot, policyEpoch }) {
  * surfaces as undefined. The caller decides how to treat an empty result.
  * `onUsage` (optional, Bug8) receives any usage chunk for token accounting.
  */
-async function streamText(ctx, options, onUsage) {
+async function streamText(ctx, options, onUsage, onStreamError) {
   let text = "";
   for await (const chunk of ctx.llm.stream(options)) {
     if (chunk.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
     if (chunk.type === "usage" && typeof onUsage === "function") onUsage(chunk);
     if (chunk.type === "finish" && (chunk.reason?.kind === "error" || chunk.reason?.kind === "aborted")) {
+      // dsh-llm rc.1 turns adapter-stage failures (unknown provider route,
+      // UNSUPPORTED_REASONING_EFFORT from resolveCallWithInfo, …) into a
+      // terminal finish chunk instead of a throw — the cause rides in
+      // chunk.reason.failure {message, code}. Surface it, never swallow it.
+      if (typeof onStreamError === "function") {
+        try { onStreamError(chunk.reason); } catch { /* diagnostics only */ }
+      }
       return undefined;
     }
   }
   return text;
 }
 
+/** One-line human-readable cause from a finish-chunk failure reason. */
+function describeStreamFailure(reason) {
+  const failure = reason?.failure ?? reason ?? {};
+  const code = failure.code ? String(failure.code) : "";
+  const message = String(failure.message ?? failure.error ?? "");
+  if (code && message) return message.includes(code) ? message : `${code}: ${message}`;
+  return code || message;
+}
+
 /**
  * Bug8: wrap a background LLM call so its token/time/status are recorded in the
  * llm_audit_logs table. Best-effort bookkeeping: a failure to WRITE the audit
@@ -279,9 +295,12 @@ async function runAuditedLlm(ctx, service, config, spec, body) {
     });
     if (result === undefined) {
       // stream aborted/errored: the caller treats undefined as a failed run;
-      // record it as error here so the audit shows the truth.
+      // record it as error here so the audit shows the truth. spec.streamError
+      // (a getter) lets the caller attach the finish-chunk cause so the audit
+      // row names it instead of a bare "aborted".
       status = "error";
-      errorMessage = errorMessage ?? "llm stream aborted or errored";
+      const streamErr = typeof spec.streamError === "function" ? String(spec.streamError() ?? "") : "";
+      errorMessage = errorMessage ?? (streamErr ? `llm stream aborted or errored (${streamErr})` : "llm stream aborted or errored");
     } else if (typeof spec.auditError === "function") {
       // A stream that returned text but yields nothing usable is still a
       // failed call — record it as error, not the default success, so the
@@ -328,10 +347,22 @@ async function runAuditedLlm(ctx, service, config, spec, body) {
  * accepted → reasoning capped; rejected → provider default (old behavior),
  * logged so the rejection is observable.
  */
-async function withEffortFallback(ctx, effort, attempt, fallback) {
+async function withEffortFallback(ctx, effort, attempt, fallback, getStreamError) {
   if (!effort || effort === "none") return attempt();
   try {
-    return await attempt();
+    const result = await attempt();
+    if (result === undefined) {
+      // dsh-llm rc.1 streams a provider effort-rejection as a terminal error
+      // finish chunk (adapterStream catches everything, never throws) — match
+      // on the chunk's failure reason here or the retry below is dead code
+      // for the stream path.
+      const reason = String(getStreamError?.() ?? "");
+      if (/reasoning[\s_]*effort|UNSUPPORTED_REASONING_EFFORT/i.test(reason)) {
+        ctx.logger?.warn?.(`dsh-mneme dream: reasoningEffort "${effort}" rejected via stream (${reason}); retrying without it`);
+        return fallback();
+      }
+    }
+    return result;
   } catch (error) {
     const message = String(error?.message ?? error);
     // matches both "reasoning effort" (natural language) and the bare
@@ -630,11 +661,15 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // 记 audit error 并在日志带原始输出前 300 字节，便于定位"推理吞预算返回空体"。
     const effort = config.dreamReasoningEffort && config.dreamReasoningEffort !== "none" ? config.dreamReasoningEffort : null;
     let decisions = null;
-    const runConsolidation = (withEffort) => runAuditedLlm(ctx, service, config, {
+    let streamFailure = "";
+    const runConsolidation = (withEffort) => {
+      streamFailure = "";
+      return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
       operationType: "dream_consolidate",
       modelId: `${route.provider}:${route.model}`,
       relatedMemoryIds: [...snapshot.keys()],
+      streamError: () => streamFailure,
       auditError: (text) => {
         decisions = extractJsonArray(text);
         return Array.isArray(decisions) ? null : "no json array in llm output";
@@ -649,18 +684,19 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         { role: "system", content: [{ type: "text", text: consolidationPrompt }] },
         { role: "user", content: [{ type: "text", text: listText }] }
       ]
-    }, reportUsage));
+    }, reportUsage, (reason) => { streamFailure = describeStreamFailure(reason); }));
+    };
     try {
       // 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));
+      decisionText = await withEffortFallback(ctx, effort, () => runConsolidation(true), () => runConsolidation(false), () => streamFailure);
     } catch (error) {
       logger?.warn?.(`dsh-mneme dream: consolidation llm call failed: ${String(error)}`);
       return finish({ ok: false, error: "llm failed", summary: false });
     }
     if (decisionText === undefined) {
-      logger?.warn?.("dsh-mneme dream: consolidation llm stream aborted or errored");
+      logger?.warn?.(`dsh-mneme dream: consolidation llm stream aborted or errored${streamFailure ? ` (${streamFailure})` : ""}`);
       return finish({ ok: false, error: "llm failed", summary: false });
     }
     if (!Array.isArray(decisions)) {
@@ -782,11 +818,15 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
     // Summary generation (second LLM call). A throwing stream is reported as
     // a failed run; summary:false marks a run that produced no summary.
     let summaryText;
-    const runSummary = (withEffort) => runAuditedLlm(ctx, service, config, {
+    let summaryStreamFailure = "";
+    const runSummary = (withEffort) => {
+      summaryStreamFailure = "";
+      return runAuditedLlm(ctx, service, config, {
       triggerSource: "autoDream",
       operationType: "dream_summarize",
       modelId: `${route.provider}:${route.model}`,
-      relatedMemoryIds: []
+      relatedMemoryIds: [],
+      streamError: () => summaryStreamFailure
     }, (reportUsage) => streamText(ctx, {
       provider: route.provider,
       model: route.model,
@@ -797,10 +837,11 @@ export function createDreamScheduler({ onRun, thresholdCount = 10, thresholdChar
         { role: "system", content: [{ type: "text", text: SUMMARY_PROMPT }] },
         { role: "user", content: [{ type: "text", text: service.all().filter((m) => !m.archived && m.type !== "summary").map((m) => `- ${m.title}: ${m.content}`).join("\n") }] }
       ]
-    }, reportUsage));
+    }, reportUsage, (reason) => { summaryStreamFailure = describeStreamFailure(reason); }));
+    };
     try {
       // Bug8: the summary call is audited too (operation dream_summarize).
-      summaryText = await withEffortFallback(ctx, effort, () => runSummary(true), () => runSummary(false));
+      summaryText = await withEffortFallback(ctx, effort, () => runSummary(true), () => runSummary(false), () => 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/heat.js

@@ -0,0 +1,136 @@
+// dsh-mneme/src/heat.js
+// 热度（heat）纯函数模块：基于类遗忘曲线计算 memory 的当前热度。
+// 零数据库依赖，不引入任何外部依赖。
+
+/**
+ * 默认的 per-type 衰减因子 λ。
+ * λ = 0 表示该类型免疫热度衰减，热度恒为 1.0。
+ */
+export const TYPE_DECAY_DEFAULTS = Object.freeze({
+  preference: 0,    // 免疫：用户画像需长期保持
+  pattern: 0,       // 免疫：发现型稳定规律
+  summary: 0,       // 免疫：已是压缩产物
+  project: 0.0008,  // 慢衰减
+  decision: 0.002,  // 中速衰减
+  history: 0.006,   // 较快（会话摘要不断被合并）
+});
+
+const HOUR_MS = 3600000;
+const DEFAULT_ALPHA = 1.2;
+const DEFAULT_LAMBDA = 0.002;
+
+/**
+ * 将可能的日期值统一转成毫秒时间戳。
+ * 支持 Date、number、ISO 字符串；无法解析时返回 NaN。
+ */
+function toTimestamp(value) {
+  if (value === null || value === undefined) return NaN;
+
+  if (value instanceof Date) {
+    return Number.isFinite(value.getTime()) ? value.getTime() : NaN;
+  }
+
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? value : NaN;
+  }
+
+  if (typeof value === 'string') {
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : NaN;
+  }
+
+  return NaN;
+}
+
+/**
+ * 获取用于计算热度的参考时间点 ref。
+ * 优先取 last_accessed_at；缺失时退到 created_at。
+ * 绝不 fallback 到 updated_at。
+ */
+function getRef(memory) {
+  if (!memory || typeof memory !== 'object') return NaN;
+  return toTimestamp(memory.last_accessed_at ?? memory.created_at);
+}
+
+/**
+ * 解析并校验配置，提供安全的 alpha 与衰减表。
+ */
+function resolveConfig(config) {
+  const safe = config && typeof config === 'object' ? config : {};
+
+  let alpha = safe.heatGlobalAlpha ?? DEFAULT_ALPHA;
+  if (!Number.isFinite(alpha) || alpha <= 0) {
+    alpha = DEFAULT_ALPHA;
+  }
+
+  const decayMap = safe.heatTypeDecay ?? TYPE_DECAY_DEFAULTS;
+
+  return { alpha, decayMap };
+}
+
+/**
+ * 构建热度信号对象，便于调试与后续扩展。
+ *
+ * @param {object} memory - memory 记录
+ * @param {object} config - 插件配置
+ * @param {number} [now=Date.now()] - 当前毫秒时间戳
+ * @returns {{ type, ref, lambda, alpha, deltaHours }}
+ */
+export function buildHeatSignals(memory, config, now = Date.now()) {
+  const nowMs = Number.isFinite(now) ? now : Date.now();
+  const ref = getRef(memory);
+  const { alpha, decayMap } = resolveConfig(config);
+
+  const type = memory?.type;
+
+  // 取对应类型的 λ，未知类型走默认
+  let lambda = decayMap[type];
+  if (!Number.isFinite(lambda)) {
+    lambda = DEFAULT_LAMBDA;
+  }
+  // λ < 0 视为非法，回退到默认；λ === 0 保留为免疫
+  if (lambda < 0) {
+    lambda = DEFAULT_LAMBDA;
+  }
+
+  let deltaHours;
+  if (!Number.isFinite(ref)) {
+    deltaHours = NaN;
+  } else if (nowMs < ref) {
+    deltaHours = 0;
+  } else {
+    deltaHours = (nowMs - ref) / HOUR_MS;
+  }
+
+  return { type, ref, lambda, alpha, deltaHours };
+}
+
+/**
+ * 计算 memory 的热度 H ∈ [0, 1]。
+ *
+ * 公式：H = 1 / (1 + λ · ΔtHours)^α
+ *
+ * @param {object} memory - memory 记录
+ * @param {number} [now=Date.now()] - 当前毫秒时间戳
+ * @param {object} [config={}] - 插件配置
+ * @returns {number} 热度值
+ */
+export function computeHeat(memory, now = Date.now(), config = {}) {
+  const signals = buildHeatSignals(memory, config, now);
+  const { alpha, lambda, deltaHours, ref } = signals;
+
+  // 无有效参考时间、或未来时间，热度视为满格
+  if (!Number.isFinite(ref) || deltaHours <= 0) {
+    return 1.0;
+  }
+
+  // λ = 0 的类型免疫，热度恒满
+  if (lambda === 0) {
+    return 1.0;
+  }
+
+  const heat = 1 / Math.pow(1 + lambda * deltaHours, alpha);
+
+  // 防止浮点误差越界
+  return Math.min(1, Math.max(0, heat));
+}

package/src/service.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { TYPE_FILE } from "./mirror.js";
+import { computeHeat } from "./heat.js";
 import { evaluateMemoryQuality } from "./quality-filter.js";
 import { createBM25Index } from "./search/bm25.js";
 import { adaptiveThreshold } from "./search/adaptive.js";
@@ -398,14 +399,15 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   }
 
   /**
-   * Sleep touch (v0.4.0): when sleep is enabled, any memory surfaced by recall
-   * or auto-injection gets its last_accessed_at bumped, so the "unrecalled N
-   * days → demote/archive" tiering counts real access. Best-effort and gated on
-   * config.sleepModeEnabled — when sleep is off this is a complete no-op (no
-   * writes on the hot recall path). A touch failure must never break search/inject.
+   * Recall touch (v0.4.0 sleep; v0.7.0 heat gating): any memory surfaced by
+   * recall or auto-injection gets its last_accessed_at bumped, so the "unrecalled
+   * N days → demote/archive" tiering counts real access — and the heat clock
+   * resets (heat ref = last_accessed_at). Best-effort and gated on
+   * config.heatEnabled — when heat is off this is a complete no-op (no writes
+   * on the hot recall path). A touch failure must never break search/inject.
    */
   function touchRecalled(memories) {
-    if (config?.sleepModeEnabled !== true || !Array.isArray(memories) || memories.length === 0) return;
+    if (config?.heatEnabled === false || !Array.isArray(memories) || memories.length === 0) return;
     for (const m of memories) {
       if (!m?.id) continue;
       try {
@@ -415,7 +417,7 @@ export function createService({ store, mirror, config, onWrite, logger }) {
   }
 
   async function searchMemories(query, options = {}) {
-    const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = false } = options;
+    const { mode = "auto", topK = 20, threshold, useRerank = true, recordRecall = options.recordRecall ?? (config?.recallRecordDefault ?? true) } = options;
     const q = String(query ?? "").trim();
     if (!q) return [];
 
@@ -1506,6 +1508,21 @@ export function createService({ store, mirror, config, onWrite, logger }) {
     saveRelation: (r) => store.saveRelation(r),
     listEntities: (o) => store.listEntities(o),
     getRelations: (id) => store.getRelations(id),
+    // v0.7.0 实体热投影：实体热 = 关联记忆 heat 聚合（取 max）。无关联记忆
+    // 或 heatEnabled=false 时返回 null；前端据此决定图谱节点大小/明暗。
+    entityHeat: (entityId) => {
+      if (config.heatEnabled === false) return null;
+      const rels = store.getRelations(entityId) ?? [];
+      let max = -Infinity;
+      for (const rel of rels) {
+        if (!rel.memory_id) continue;
+        const mem = store.getById(rel.memory_id);
+        if (!mem) continue;
+        const h = computeHeat(mem, Date.now(), config);
+        if (h > max) max = h;
+      }
+      return max === -Infinity ? null : max;
+    },
     saveAttr: (r) => store.saveAttr(r),
     createEntity: (r) => store.createEntity(r),
     findEntityByName: (n) => store.findEntityByName(n),

package/src/settings.js

@@ -47,6 +47,7 @@ const FEATURE_FLAG_BOOLEANS = [
   "codingRetrospect",
   "autoDream",
   "sleepModeEnabled",
+  "heatEnabled",
   "hybridInject",
   "selectiveInjectEnabled",
   "searchSemanticDedup",

package/test/api.test.js

@@ -527,10 +527,10 @@ test("GET /api/dsh-mneme/features returns empty overrides and effective config d
   assert.equal(res.statusCode, 200);
   const data = JSON.parse(res.body);
   assert.deepEqual(data.overrides, {});
-  // effective 覆盖全部 30 个白名单键，未覆盖时取 bundle 配置的解析默认值；
-  // dreamProvider/dreamModel 无 schema 默认值（Config({}) 解析为 undefined），
-  // 不编造给前端 → 30 - 2 = 28
-  assert.equal(Object.keys(data.effective).length, 28);
+  // effective 覆盖全部 31 个白名单键（含 v0.7.20 新增的 heatEnabled），未覆盖时
+  // 取 bundle 配置的解析默认值；dreamProvider/dreamModel 无 schema 默认值
+  // （Config({}) 解析为 undefined），不编造给前端 → 31 - 2 = 29
+  assert.equal(Object.keys(data.effective).length, 29);
   assert.equal(data.effective.autoInject, true);
   assert.equal(data.effective.codingRetrospect, false);
   assert.equal(data.effective.distillMaxChars, 24000);
@@ -903,7 +903,9 @@ test("GET /api/dsh-mneme/dream-status returns runs and pending conflict ids", as
   assert.equal(data.runs.length, 2);
   assert.equal(data.runs[0].created_at, "2026-01-02T00:00:00.000Z", "created_at DESC");
   assert.deepEqual(data.lastRun, data.runs[0]);
-  assert.deepEqual(Object.keys(data.lastRun).sort(), ["created_at", "error", "model", "provider", "status"]);
+  assert.deepEqual(Object.keys(data.lastRun).sort(), ["created_at", "demotion", "error", "model", "provider", "run_type", "status"]);
+  assert.equal(data.lastRun.run_type, "auto", "default run_type is auto");
+  assert.equal(data.lastRun.demotion, null, "no demotion info for non-sleep runs");
   assert.equal(data.runs[0].error, "boom");
   assert.equal(data.runs[1].provider, "ollama");
   assert.equal(data.pendingConflicts, 1);
@@ -1049,3 +1051,29 @@ test("GET /api/dsh-mneme/list?deposited=only lists dream-touched memories (recei
   assert.deepEqual(bothData.items.map((m) => m.title), ["被巩固"]);
   assert.equal(bothData.total, 1);
 });
+
+test("GET /api/dsh-mneme/list projects per-memory heat only when heatEnabled=true", async () => {
+  // 默认（heatEnabled=false）：heat 字段整体缺省——前端徽章据此自动隐藏
+  const off = setup();
+  off.service.saveWithDedupe({ type: "preference", title: "免疫型", content: "immune" });
+  const r0 = new FakeRes();
+  await off.routes.find((r) => r.path === "/api/dsh-mneme/list").handler(req("/api/dsh-mneme/list"), r0);
+  const d0 = JSON.parse(r0.body);
+  assert.equal(d0.total, 1);
+  assert.equal("heat" in d0.items[0], false, "heat must be absent from the wire DTO when the flag is off");
+
+  // heatEnabled=true：逐条投影。λ=0 免疫类型（preference）恒 1.0；其余落在
+  // [0,1] 区间（新建记忆 Δt≈0 接近满格，衰减数学由 heat.test.js 看门）。
+  const on = setup(null, "", { heatEnabled: true });
+  on.service.saveWithDedupe({ type: "preference", title: "免疫型", content: "immune" });
+  on.service.saveWithDedupe({ type: "history", title: "会话历史", content: "recent" });
+  const r1 = new FakeRes();
+  await on.routes.find((r) => r.path === "/api/dsh-mneme/list").handler(req("/api/dsh-mneme/list"), r1);
+  const d1 = JSON.parse(r1.body);
+  assert.equal(d1.total, 2);
+  const byTitle = Object.fromEntries(d1.items.map((m) => [m.title, m.heat]));
+  assert.equal(byTitle["免疫型"], 1, "λ=0 immune types stay at full heat");
+  for (const v of Object.values(byTitle)) {
+    assert.ok(typeof v === "number" && v >= 0 && v <= 1, "heat values stay within [0,1]");
+  }
+});

package/test/client.test.js

@@ -223,18 +223,16 @@ test("importance renders as star glyphs, not raw text stars", () => {
 // external-plugin-guide §2.2): 'betterSidebar' IS declared in inject (DSH's
 // runtime gates ctx property access on the inject declaration — probing
 // without declaring fails the whole loader entry, verified in the field) and
-// marked as an optional peer dependency, so when it is absent the service
-// resolves to undefined and registration skips gracefully. Registration
-// probes at runtime inside a named ctx.effect (scope cleanup on HMR/disable)
-// with a bounded retry for service-provision ordering.
-test("better-sidebar tab declares optional inject, probes, and skips gracefully", () => {
+// better-sidebar 软集成（issue #88 修正）：模块级 inject 声明 betterSidebar
+// 是硬等待——未安装 bs 的环境整个 entry pending（"1 entry did not activate"，
+// Failed to load plugins）。正确模式（dsh-server-deck 同款）：外层入口零
+// inject 立即激活（独立模式保底），tab 注册挂在内层动态子插件
+// ctx.plugin({ inject: ['betterSidebar'] }) 由 cordis 原生等待服务——bs 未装
+// 时该内层 fiber 永远 INACTIVE，静默无害。
+test("better-sidebar tab mounts via an inner sub-plugin, standalone mode intact", () => {
   assert.ok(
-    /const inject = \["slots", "locale", "betterSidebar"\];/.test(clientSource),
-    "module inject must declare betterSidebar — DSH gates ctx property access on it"
-  );
-  assert.ok(
-    /const bs = ctx\.betterSidebar;[\s\S]{0,60}typeof bs\.registerTab === "function"/.test(clientSource),
-    "the tab registration must still probe ctx.betterSidebar at runtime (undefined when absent)"
+    /const reg = bsCtx\.betterSidebar;[\s\S]{0,60}typeof reg\.registerTab !== "function"/.test(clientSource),
+    "the inner apply must still guard the service shape before registering"
   );
   assert.ok(
     /id: "dsh-mneme:memory"/.test(clientSource),
@@ -252,9 +250,20 @@ test("better-sidebar tab declares optional inject, probes, and skips gracefully"
     clientSource.includes('"dsh-mneme: better-sidebar tab"'),
     "the registration effect must carry a named label for scope cleanup"
   );
+  // issue #88：模块级 inject 声明 betterSidebar 是硬等待——未安装 bs 的环境
+  // 整个 entry pending（"1 entry did not activate"）。tab 注册必须挂在内层
+  // 动态子插件（dsh-server-deck 同款模式），外层入口零 inject 立即激活。
+  assert.ok(
+    /const inject = \["slots", "locale"\]/.test(clientSource),
+    "the module inject must not declare betterSidebar (hard-wait regression)"
+  );
   assert.ok(
-    /if \(\+\+tries <= 10\) timer = setTimeout\(attempt, 1000\);/.test(clientSource),
-    "the service probe must retry with a bound (10 × 1s), not loop forever"
+    /ctx\.plugin\?\.\(\{[\s\S]*?inject: \["betterSidebar"\][\s\S]*?apply: \(bsCtx\) =>/.test(clientSource),
+    "the tab registration must live in an inner dynamic sub-plugin waiting on cordis"
+  );
+  assert.ok(
+    /if \(\+\+tries <= 10\) timer = setTimeout\(attempt, 1000\);/.test(clientSource) === false,
+    "the old 10×1s probe must go — cordis waits for the inner inject natively"
   );
 });
 
@@ -409,3 +418,51 @@ test("explorer chrome aligns with the host design system", () => {
     "pill chips belong to the drawer era and must stay gone"
   );
 });
+
+// heat 阶段二：/list 仅在 heatEnabled=true 时下发逐条 heat，前端徽章三档
+// 配色且自门控（字段缺省自动隐藏）——卡片页脚、抽屉 meta、状态分布卡共用
+// 同一数据源，前端不感知开关状态。
+test("heat badges render from the /list projection and self-hide when off", () => {
+  assert.ok(
+    /const HeatBadge = \(\{ value, size = 12 \}\) =>/.test(clientSource),
+    "the heat badge component must exist"
+  );
+  assert.ok(
+    clientSource.includes("flame:"),
+    "the Lucide flame glyph must back the badge"
+  );
+  assert.ok(
+    /h\(HeatBadge, \{ value: m\.heat \}\)/.test(clientSource),
+    "the card foot must render the heat badge"
+  );
+  assert.ok(
+    clientSource.includes('t("memory.explorer.heat")'),
+    "the drawer must show a localized heat meta row"
+  );
+  assert.ok(
+    clientSource.includes("function HeatStatusCard"),
+    "the status grid must include the heat distribution card"
+  );
+  assert.ok(
+    clientSource.includes('typeof items[0].heat !== "number"'),
+    "the distribution card must self-hide when /list omits heat"
+  );
+  assert.ok(
+    /\.mneme-heat--hot\{/.test(clientSource),
+    "the three-tier heat colors must be styled"
+  );
+  // order=heat 的前端补口：热度是运行时投影无存储序，SQL 排不了——页内
+  // 对已加载条目降序，时间树保持 chrono；chip 自门控（heat 缺省不出现）。
+  assert.ok(
+    /const heatAvailable = visible\.some\(\(m\) => typeof m\.heat === "number"\);/.test(clientSource),
+    "the heat-sort chip must self-gate on the /list heat field"
+  );
+  assert.ok(
+    /const gridItems = heatSort[\s\S]{0,80}\(b\.heat \?\? 0\) - \(a\.heat \?\? 0\)/.test(clientSource),
+    "the cards grid must sort loaded items by heat in-page"
+  );
+  assert.ok(
+    clientSource.includes("if (!heatSort) switchViewMode(\"cards\")"),
+    "toggling heat sort must land on the cards view (sort does not apply to the month tree)"
+  );
+});