@modusensus/dsh-mneme 0.9.4 → 0.10.0

package/docs/SLEEP.md

@@ -42,6 +42,9 @@ flowchart TD
 | `sleepModeEnabled` | `false` | 全局开关（Opt-in），开启后激活调度器 |
 | `sleepIdleMinutes` | `5` | 连续无操作触发睡眠的阈值（分钟） |
 | `sleepMinIntervalHours` | `8` | 两次 Sleep Run 的最小时间间隔（小时） |
+| `sleepFailureBackoff` | `false` | 连续失败退避（#529，opt-in）：有效间隔 = `sleepMinIntervalHours` × 2^连败数，成功清零，封顶 `max(sleepMinIntervalHours, 24h)`（配得比 24h 大就按配的算——退避只放大间隔，不压缩用户自己设的基数）。判据看整轮 `status === "failed"`——`noop`（通路正常、只是没活干）不算失败，否则在自己工作良好的库里也会越退越长 |
+| `sleepConflictMaxPairs` | `12` | **单批**送审的冲突对上限（0 = 不限，回退旧行为） |
+| `sleepConflictMaxPairsPerRun` | `60` | **单轮**最多送审多少对（0 = 不限）。与上一条分工：一个管批次大小、一个管整轮总量 |
 | `sleepConflictStrictness` | `'normal'` | 冲突消解严格度：`'gentle'`(0.92) / `'normal'`(0.85) / `'aggressive'`(0.75) |
 | `sleepArchiveDays` | `30` | 进入冷存储/摘要降级的天数阈值 |
 | `sleepCompressDays` | `90` | 进入完全归档（Archive）的天数阈值 |
@@ -54,18 +57,27 @@ flowchart TD
 | `sleepMaxTokens` | `8192` | 冲突消解与模式发现阶段的 LLM 输出预算上限（token，#257：原硬编码 2048——`sleepActionSet: full` 实测 24 对需约 7000，截断即整轮裁决失败）。流式计费按实际用量，调大不增加成本 |
 
 ## 四阶段详解
-每个阶段独立包裹 `try/catch`，任一阶段失败仅跳过该阶段，不阻塞后续流程。
+每个阶段独立包裹 `try/catch`，任一阶段失败仅跳过该阶段，不阻塞后续流程。四个相位读取的记忆行池都先剔掉 `source='imported'` 的外来行（`src/dream/sleep.js`）——外来行不经本方蒸馏与召回，时间分层与冲突判据在它身上系统性失真，我方对它的原文和归档面没有处置权，所以下文「输入」一栏里的「全量」一律读作「本方活跃行」，契约见 [SHARE.md](SHARE.md)。
 
 ### 1. `conflict_resolution`（冲突消解）
 - **目标**：清理向量空间中的重复、矛盾或过时记忆。
 - **输入**：全量/增量记忆向量索引、`sleepConflictStrictness` 阈值。
 - **算法**：
-  1. 向量检索 `findPotentialConflicts` 获取高相似度对。
-  2. LLM 仲裁：基于严格度阈值生成 `keep/merge/discard` 决策。
-  3. `validateDecisions`：严格校验决策合法性，缺省策略为 `keep`。
-  4. `applyDecisions`：批量执行状态变更。
-- **输出**：冲突消解报告（决策明细）。
+  1. 向量检索 `findPotentialConflicts` 获取高相似度对；`sleepActionSet: "full"` 时再补一遍跨类型对。
+  2. **已裁决对先压掉**：`differentiated_pairs` 账本里记着「这一对判过"互补、两条都留"」，两侧正文的 `content_hash` 与记账时一致就不再送模型（任一侧被改写则重新进候选）。这一轮被压掉几对记在 `phase.suppressed`，与「一对都没检测到」（`no conflicts found`）分开报。
+  3. **台账预筛**（#529）：查 `conflict_reviewed`，把「已经判过、且两侧 `updated_at` 都不晚于 `judged_at`」的对从候选池里剔掉——它们上一轮已有结论，两侧都没动就没必要再问一遍。任一字段更新即重新入池（与 `conflict_pending` 复核项 4 同一条宽松代理）。两条边界：跨 scope 对**不筛**（它们本来就要停车进人工队列，不能被机器台账吞掉），`conflictFreezeEnabled` 档**不筛**（那一档只停车不送 LLM）。
+  4. **去重**：每条记忆至多参与一对，相似度高者优先。**必须排在 3 之后**——先占位再去掉，一个已审的对会把它那一端记忆的配对名额占住，而它真正的对手（另一条没审过的记忆）因此进不了这一轮。被台账挡下的对数记在 `phase.ledgerSkipped`。
+  5. **每轮总量上限**（`sleepConflictMaxPairsPerRun`，默认 60）：没进这一轮的对留在下一轮，既不丢也不记账。
+  6. **分批**（`sleepConflictMaxPairs`，默认 12）：每批单独一次 LLM 往返、单独 `validateDecisions` + `applyDecisions`。某批撞上下文或输出坏掉只让**这一批**失败并计入 `degraded`，其余批照常落地；只有一批都没成功才整轮 `failed`。
+  7. LLM 仲裁：基于严格度阈值生成决策（默认档 `keep/merge/conflict/create/archive/update`，full 档另开 `supersede/differentiate`）。
+  8. `validateDecisions`：严格校验决策合法性，缺省策略为 `keep`。**`reflectionUpdateMaxPerRun` 是整轮上限，不是每批上限**——额度由分批循环持有，每批只领剩余额度，校验通过后按本批通过校验的 `update` 数扣减；额度耗尽的那批若还含 `update` 会被校验器整单拒绝（记 `failed`），其余批照常继续。
+  9. `applyDecisions`：批量执行状态变更。
+  10. **台账记账**：本批**全部送审对**都写一行 `conflict_reviewed`（不只记被裁决成冲突的那几对，判 `keep` 的正是下一轮重复送审的元凶），`outcome` 取两端里非 `keep` 的那一侧。记账是幂等 upsert，按 `(memory_a, memory_b)` 排序归一化。两个防"假已审"的细节：`judged_at` 取**发送本批之前**的时刻（不是落地之后——LLM 往返期间若一侧被外部改动，它的 `updated_at` 会晚于 `judged_at`，下一轮自然重新入池；按落地时刻封盘等于用陈旧结论锁死这一对），且取 `max(墙钟, 本批两侧最新的 updated_at)`——`updated_at` 用的是 store 的**单调时钟**（`src/store.js` 的 `nowIso` 在同一毫秒内的连续写入上逐次 +1ms），它可能领先墙钟几毫秒，两列不同源的话 `alreadyJudged` 会把「刚判过」读成「判过之后又被改过」，判 `keep` 的死循环原样复活；本批 `failures` / `conflicts`（CAS 冲突）/ `skipped` 里出现过的 id，其所在对**不记账**——没落地的裁决记成已审，会让这一对从此不再送审，沉默地永久压制一个真实冲突。
+- **`differentiate` 不改正文**（#533）：`#126` 曾把同一段差异注记**同时**追加到两侧，指望注记进 embedding 后下一轮不再判重复。离线复现证伪了这个假设——两侧共享同一段后缀会让两条向量**同向靠拢**（余弦 0.876 → 0.960 只用 5 轮，注记截到 0 字照样往上爬），于是同一对每轮又被判成重复、又追加一段（实测单条堆到 19 段，正文 150 字膨胀到 2200+）。现在只落 `differentiated_pairs` 账本（配对 + 两侧当时的 `content_hash` + 模型给的 `distinctions`），正文一个字节都不动。存量库里仍带旧注记块的行按「已裁决」处理，升级不清账。
+- **输出**：冲突消解报告（决策明细 + `pairs` / `batches` / `ledgerSkipped` / `perRunSkipped`）。**失败轮同样带 `pairs` 与 `batches`**——此前只有成功路径带，85 条失败审计行连"送了多少对"都查不到。批间被用户活动打断时报 `aborted`（不是 `noop`：`noop` 的语义是"看过、没冲突"，而没送出去的批根本没看过），整轮 `deriveStatus` 也沿用同一个词，不再折回 `noop`。
 - **验收**：无合法记忆被误删；仲裁结果符合配置的严格度阈值；决策可回滚。
+- **为什么要有预算（#529 的现场）**：整池相似对一次拼进一个 prompt，实测单请求 **163,054** 输入 token（服务端 `--ctx-size` 163,840，占 99.5%），撞墙后按冷却重排，送进去的还是同一份输入，于是连续 **23 轮** `llm failed`；而 `keep` 当时是彻底的 no-op（不留痕），同一对每个冷却周期都被重新问一遍。三处一起改之后单请求降到 806–2,011 token、连续失败 23 轮 → 0 轮。
+- **台账为什么不复用 `conflict_pending`**：那张表是**人工**待裁决队列，面板徽标数就是 `countConflictPending()`（`resolved_at IS NULL` 的行数）。机器每判一对写一行会把这个数字淹掉，人就再也看不出"有哪些待我裁决"。两张表分工：`conflict_pending` = 人要看，`conflict_reviewed` = 机器记账，零界面。
 
 ### 2. `archival_demotion`（归档降级）
 - **目标**：按时间衰减对记忆进行分层压缩，释放热存储压力。
@@ -110,7 +122,9 @@ flowchart TD
 
 ## 调度器与可中断机制
 - **`noteWrite()` 心跳重置**：每次用户写入/读取记忆时触发。必须先 `clearTimeout` 清除旧计时器，再重新设置 Idle Timer，彻底杜绝 Stale Timer 导致的误触发。
-- **`maybeSchedule()` 准入控制**：串行检查 `sleepModeEnabled` → 空闲时长 `>= sleepIdleMinutes` → 距上次运行 `>= sleepMinIntervalHours` → 状态非 `running/disposed`。任一不满足则放弃调度。
+- **`maybeSchedule()` 准入控制**：串行检查 `sleepModeEnabled` → 空闲时长 `>= sleepIdleMinutes` → 距上次运行 `>= 有效最小间隔` → 状态非 `running/disposed`。任一不满足则放弃调度。
+  - **有效最小间隔**（#529）：`sleepFailureBackoff` 关（默认）时逐字节等于 `sleepMinIntervalHours`；开启时按连续失败次数指数推迟，封顶 `max(sleepMinIntervalHours, 24h)`——不是硬 24h：基数允许配到 168 小时，那时封顶跟着基数走，退避只能放宽间隔、不会把用户设的基数压小。`armNextWindow()` 排下一次闹钟用的是同一个函数——两处口径必须一致，否则退避期闹钟会在基数到点响、被 `shouldRun` 否掉、再重排一次，白转一轮。
+  - 退避**不是**按"同一份输入又失败"判的：`runSleep` 里那个 `snapshotHash` 是跑完之后对 `phases` 结果算的摘要哈希，不是输入快照，拿它当判据会把"同样的输入"认成"不同的结果"。改用连续失败计数，与 `autoDream` 的失败退避（#292）同构。
 - **`service.enqueue` 串行队列**：所有 Sleep Run 必须进入全局串行队列执行，与 `autoDream` 严格互斥，避免并发写入冲突与资源争抢。
 - **`AbortController` 可中断**：调度器持有 AbortController 实例。一旦检测到用户活动（`noteWrite` 或显式交互），立即调用 `abort()` 中断当前 `runSleep` 的执行上下文，保证实时性优先。
 

package/docs/STORAGE.md

@@ -31,12 +31,13 @@ dsh-mneme reclaim --json                        # 原始 JSON，给脚本用
 |---|---|---|
 | `dream_runs.input`（窗口外） | 置空 | 它是当时的记忆库快照，可由记忆库重建 |
 | `dream_runs` 的骨架 / `decisions` / `outcome` / `receipt` | 不动 | 不可重建：拆了就回放不了那次裁决 |
+| `dream_runs.raw_output` | 不动 | 失败轮的诊断摘要（#534）：收到文本但解析或校验失败时留下的原文头尾，只在那一次调用里存在过，日志滚掉就再也拿不回来。**它不参与回放**——删了不会让保留的决策放不出来，只是丢掉「模型当时到底吐了什么」这条证据；无正文的流错误本来就是 `NULL` |
 | `memories.embedding`（`archived = 1`） | 置空 | 检索恒带 `archived = 0`，按定义不可达 |
 | `memories` 的行 | 一条不删 | 本入口止体积不止条数；条数与重复归 #254 与整理动作面 |
 | 活跃行的向量 | 不动 | 检索正在用 |
 | `distill_records`（窗口外，#399） | 删行 | 蒸馏原文留存是 opt-in 旁路索引；到期即弃。**`memory_provenance` 链接保留**指向空区间（面板显示「来源已过期」），记忆与链接都不删——原文本就是「回查用」的，保留期到了就该走 |
 
-`distill_records` 只在 `distillRecords.enabled=true` 时才有行（默认关，连收集都不做），所以对大多数库这一项恒为 0。
+`distill_records` 只在 `distillRecords.enabled=true` 时才会有行（默认关，连收集都不做），所以对大多数库这一项恒为 0。**曾经开过再关的库有行**：关掉开关只是不再写、也不再经 HTTP 读出去，已留的行一直躺在库里，直到 `dsh-mneme reclaim`（不读这个键）或重新开启后的启动裁剪（见 [蒸馏原文留存](DISTILL.md)）。
 
 取消归档时（`memory_archive` 还原）服务端会重新排队嵌入，所以被回收的向量能拿回来。
 

package/lib/api-standalone.js

@@ -15,10 +15,13 @@
 // the operator's explicit responsibility (documented in README).
 import { createServer } from "node:http";
 import { randomBytes, timingSafeEqual } from "node:crypto";
+import { homedir } from "node:os";
 import { TYPES } from "./store.js";
 import { bootstrapFromDirectory } from "./bootstrap.js";
 import { PACKAGE_VERSION } from "./version-check.js";
 import { parseReclaimJson, readReclaimFields, reclaimReply, RECLAIM_UNAVAILABLE } from "./reclaim-http.js";
+import { parseShareBody, shareReply, parseReceiveBody, receiveReply, parseUndoBody, undoReply } from "./share-http.js";
+import { parseProvenanceSelector, provenanceReply } from "./provenance-http.js";
 
 const DEFAULT_PORT = 8790;
 const DEFAULT_HOST = "127.0.0.1";
@@ -30,6 +33,46 @@ const MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
 const MAX_PAGE_LIMIT = 1000;
 const MAX_SEARCH_TOP_K = 200;
 
+/**
+ * /context 降级原因枚举（#383，issue #508 评审后定稿）——**日志读数**的唯一真源。
+ * 它不进响应体：响应只多 `tier` 一个键，具体原因走 daemon stderr 那行 warn。
+ *
+ * 成例是「修法不同就分开」，于是六值互不吞并：
+ *   embed-unavailable  embedder 对象在，上面没有 embedSingle / embed → 修适配器
+ *   embed-empty        接口返回了，但向量是空数组 / 非数组 → 修接口
+ *   embed-timeout      接口挂起，被 embedTimeoutMs 护栏按缺失处理 → 修端点响应
+ *   embed-error        接口抛错（HTTP 4xx/5xx、网络、解析失败……）→ 查端点
+ *   embed-dimension    接口成功了，但库里没有一条维度相符的活跃向量 → 重建索引
+ *   no-embedder        压根没装配 embedder（daemon `--embed off` / lightMode /
+ *                      宿主未装配）→ 把嵌入装上或开起来。这是**预期态，不是故障**
+ * 最后一个是 #508 Minor 的修正：此前这条路不写 diag.reason，靠日志行的兜底表达式
+ * 临时拼一个值出来，结果那个值不在任何文档声明的枚举里，按枚举解析日志的运维程序
+ * 会整条漏掉。现在它在决策点赋值，与其余五值并列同源。
+ *
+ * 不并进 embed-unavailable 是有意的：那两个读数今天共用「语义路没通」的结果，但
+ * 主体与动作都不同——一个是适配器坏了（异常），一个是语义路没开（设计内常态，
+ * src/index.js 的 lightMode 注释与 src/serve.js 的 `embedder ?? semantic?.embedder
+ * ?? null` 都明写它）。并过去会让按 embed-unavailable 告警的面板对每个轻量模式
+ * 安装报警。用词则与宿主面 /api/dsh-mneme/semantic 的 reason 对齐（src/api.js），
+ * 同一个物理条件在两个面叫同一个名字，运维 grep 时不会分裂。
+ *
+ * **两套同名枚举的分界**：src/api.js 那套是 `no-embedder / not-configured /
+ * initializing / null`，免鉴权状态面板消费，test/api.test.js 锁着。两套同名不同源，
+ * 这里只借词、不改那边；清扫文档时不要顺手统一（会打红那条测试）。
+ *
+ * 这一个常量同时是代码写入方、两份文档（README 外部 API 段 / docs/DAEMON.md §2）与
+ * 契约测试的同一来源：新增降级路径必须在这里加值并同步那两处，否则
+ * test/standalone-api.test.js 的枚举契约测试会红。
+ */
+export const CONTEXT_DEGRADE_REASONS = Object.freeze([
+  "embed-unavailable",
+  "embed-empty",
+  "embed-timeout",
+  "embed-error",
+  "embed-dimension",
+  "no-embedder"
+]);
+
 /**
  * Listen with automatic EADDRINUSE recovery. Tries the configured port, then
  * the next MAX_PORT_ATTEMPTS-1 ports, and finally falls back to port 0 so the
@@ -226,16 +269,29 @@ async function handlePutBody(res, service, logger, id, text) {
  * /context 的查询嵌入：best-effort，embedder 接口宽容与 searchMemories 同款
  * （embedSingle 优先，兼容 embed-only 的 OpenAI 兼容客户端，issue #10）。
  * 调用方负责 catch——嵌入失败降级规则档，绝不因此 500。
+ *
+ * `diag`（optional，issue #383）：拿不到向量时把原因写进去，供 daemon 侧日志枚举
+ * 降级原因。枚举是上面那个 CONTEXT_DEGRADE_REASONS（六值，互不吞并），本函数只负
+ * 责其中两个「没拿到向量」的值：无可用接口 → embed-unavailable，空/非数组 →
+ * embed-empty。其余由超时护栏、查询嵌入 .catch 与维度判据写入。不传则行为与既往
+ * 逐字节一致。
  */
-async function embedQueryVector(embedder, q) {
+async function embedQueryVector(embedder, q, diag) {
   const embedSingle = typeof embedder.embedSingle === "function"
     ? embedder.embedSingle.bind(embedder)
     : typeof embedder.embed === "function"
       ? embedder.embed.bind(embedder)
       : null;
-  if (!embedSingle) return undefined;
+  if (!embedSingle) {
+    if (diag) diag.reason = "embed-unavailable";
+    return undefined;
+  }
   const vector = await embedSingle(q);
-  return Array.isArray(vector) && vector.length ? vector : undefined;
+  if (!Array.isArray(vector) || !vector.length) {
+    if (diag) diag.reason = "embed-empty";
+    return undefined;
+  }
+  return vector;
 }
 
 /**
@@ -244,11 +300,17 @@ async function embedQueryVector(embedder, q) {
  * 按嵌入缺失处理，降级规则档。输掉的 embed promise 无法取消、自行结束后被丢弃，
  * 无害；挂起的主要成本是一个泄漏的挂起任务，可接受。嵌入先完成时清掉定时器
  * （CodeRabbit 同轮 Minor：别让每个请求都留一枚要等满超时的计时器）。
+ *
+ * `diag`（optional，issue #383）：超时写 `embed-timeout`，与上面几个原因同一套枚举
+ * （CONTEXT_DEGRADE_REASONS）。
  */
-function withEmbedTimeout(promise, timeoutMs) {
+function withEmbedTimeout(promise, timeoutMs, diag) {
   let timer;
   const timeout = new Promise((resolve) => {
-    timer = setTimeout(() => resolve(undefined), timeoutMs);
+    timer = setTimeout(() => {
+      if (diag) diag.reason = "embed-timeout";
+      resolve(undefined);
+    }, timeoutMs);
   });
   return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
@@ -281,6 +343,11 @@ function scopeFromSearchParams(url) {
  *   - embedTimeoutMs: /context query-embed guard (default 3000) — a hung
  *     embedder must not hold the HTTP connection; timeout degrades to the rule
  *     tier. Factory option (like strictPort), not a user config key.
+ *   - config: 缺省 `{}` 对 /memory/provenance 意味着**功能关着**——该读出口的门读
+ *     config.distillRecords.enabled（判据见 src/provenance-http.js），而它返回的是
+ *     蒸馏窗口的逐字原文，所以「不传即关」是故意的 fail-closed 方向（reclaim-http
+ *     「没接线如实报」同族）。将来新增第三个构造点忘传 config，这个端点会安静地
+ *     回 409 而不是把原文读出去——那是想要的行为，不要修成默认开。
  * Returns { server, port, host, token, ready }: `port` is the effective bound
  * port (updated to the OS-assigned one after `ready` resolves when asked to
  * bind port 0), `ready` resolves once listening and rejects if the bind fails.
@@ -414,6 +481,40 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
         return;
       }
 
+      // --- GET /memory/provenance: 记忆级溯源读出口（#399 写、#421 读）--------
+      // 与宿主内 /api/dsh-mneme/memory/provenance 同一份实现口径，就在
+      // src/provenance-http.js 里写一份（#411 的教训：两张皮整段复制必然漂移）。
+      // 一个链接一个窗口（区间 + 区间内原文行，按 seq 升序）；没有链接的记忆返回
+      // 空 windows——「不是蒸馏来的」是有效答案，不是错误。
+      //
+      // 两个读方向共一条路径（#524）：?id=<memoryId> 走方向 1（记忆 → 窗口），
+      // ?sessionId=<sid> 走方向 2（会话 → 窗口）。互斥校验在共用模块里（都缺/都给
+      // 都是 400），本壳只把三个 query 参数原样递进去——拆分与择一的判断只准写一份。
+      //
+      // 这张面本来就要 Bearer token（除 /health 外无例外），所以不涉及宿主侧那次
+      // open → token 的归类调整；daemon 与宿主共用 service，口径天然一致。
+      //
+      // distillRecords.enabled 门（#509 评审整改）：config 原样转交给共用模块，
+      // 判据只在那边算一次（isDistillRecordsEnabled，与写侧 src/summarize.js:988
+      // 同源，本文件不重写）。config 缺省 {} → 判据为假 → 409，错误码取共用模块导出的
+      // DISTILL_RECORDS_DISABLED：「不传即关」对这个返回逐字原文的端点是正确的失败
+      // 方向，别当成 bug 修掉。阶梯全貌（401 → 400 → 409 → 503 → 读）见
+      // provenance-http.js 文件头。
+      if (req.method === "GET" && pathname === "/memory/provenance") {
+        const parsed = parseProvenanceSelector({
+          memoryId: url.searchParams.get("id"),
+          sessionId: url.searchParams.get("sessionId"),
+          limit: url.searchParams.get("limit")
+        });
+        if (!parsed.ok) {
+          sendJson(res, parsed.status, { error: parsed.error });
+          return;
+        }
+        const { status, body } = provenanceReply({ service, selector: parsed.selector, config, warn: (m) => logger?.warn?.(m) });
+        sendJson(res, status, body);
+        return;
+      }
+
       // --- GET/PUT/DELETE /memories/:id --------------------------------------
       const idMatch = pathname.match(/^\/memories\/([^/]+)$/);
       if (idMatch) {
@@ -581,6 +682,84 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
         return;
       }
 
+      // --- POST /share: 分享包（spec §4）--------------------------------------
+      // 判据一条都不在这里：哪些行进包、超没超限、抛错回什么码，全在 share-http.js
+      // 那份共用实现里（#411 的口径——两张皮只许差在鉴权与路径）。本侧独有的只有
+      // 鉴权（Bearer，除 GET /health 外没有例外）与「不出 Content-Disposition」：
+      // 下面的 sendJson 连 headers 参数都没有，CLI 拿 JSON 自己落盘。
+      //
+      // GET 回 405 而不是掉到末尾的 404，与面板那侧一致。这**故意**与上面的
+      // /maintenance/reclaim（GET → 404）不同：状态码差一次就是第三处差别，而两条
+      // 路由的「两张皮」约束比这份文件里邻居的写法更硬。
+      //
+      // .catch 不是装饰：shareReply 现在自己兜得住，但这条链上 readBody 之前之后的
+      // 任何一处抛错都没人接——本文件那个同步 try/catch 在 .then 的回调里已经退栈，
+      // 漏出去就是未处理拒绝、客户端一个字节都没收到（#410）。
+      if (pathname === "/share") {
+        if (req.method !== "POST") {
+          sendJson(res, 405, { error: "method-not-allowed" });
+          return;
+        }
+        void readBody(req, res).then((text) => {
+          if (text === null) return; // readBody 已经答过 413，再写一次就是双写响应
+          const parsed = parseShareBody(text);
+          if (!parsed.ok) {
+            sendJson(res, 400, { error: parsed.error });
+            return;
+          }
+          const out = shareReply({
+            service,
+            packageVersion: PACKAGE_VERSION,
+            homeDir: homedir(),
+            options: parsed.options,
+            warn: (msg) => logger?.warn?.(msg)
+          });
+          sendJson(res, out.status, out.body);
+        }).catch(() => sendJson(res, 500, { error: "internal" }));
+        return;
+      }
+
+      // --- POST /receive + POST /receive/undo: 分享包入库与整包退出（车道 C）-----
+      // 判据一条都不在这里：包体合格不合格住在 share.js 的闸门（由 service 的
+      // importSharePack 调），错误码 → 状态的映射与 dry_run 那一格住在 src/share-http.js
+      // 这份共用实现里——#411 的口径是两张皮只许差在鉴权与路径（面板那半见
+      // /api/dsh-mneme/receive）。本面独有的只有两件事：鉴权是这里唯一的 Bearer 一道门
+      // （没有 policy 名可用，除 GET /health 外人人都要带），以及 sendJson 连 headers
+      // 参数都没有，所以不出 Content-Disposition。
+      //
+      // 非 POST 一律 405，与面板逐字同款：这**故意**与上面的 /maintenance/reclaim 不同
+      // （那边掉到末尾 404）。状态码差一次就是第三处差别，而每条 receive 都还有个面板
+      // 双胞胎，一致性比照抄本文件的邻居更硬。
+      //
+      // void + .catch，不留外层 try 兜底：本文件那个 try 在 .then 的回调里早已退栈，
+      // 回调里抛出去就是没人接的 rejection、客户端一个字节都收不到（#410）。共用层
+      // 从不抛（连 warn 自己坏都被守卫吞掉），所以这里能被走到的只剩面自己写答复那一步。
+      // readBody 超限时会自己答 413 并把 text 解析成 null：那句 return 是必需的，少了
+      // 它就是在已发出的响应上再写一次。
+      if (pathname === "/receive" || pathname === "/receive/undo") {
+        const isUndo = pathname === "/receive/undo";
+        if (req.method !== "POST") {
+          sendJson(res, 405, { error: "method-not-allowed" });
+          return;
+        }
+        void readBody(req, res).then((text) => {
+          if (text === null) return; // readBody 已经答过 413，再写一次就是双写响应
+          const parsed = isUndo ? parseUndoBody(text) : parseReceiveBody(text);
+          // 两个解析器都回 {ok:true,…}|{ok:false,error}，所以一处判断就够。别把它写成
+          // 「有 error 就 400」：那会把本面缺路径时该落的 404 与真正的坏 body 混成一种
+          // 答复，排查时看不出是哪一层没接上。
+          if (!parsed.ok) {
+            sendJson(res, 400, { error: parsed.error });
+            return;
+          }
+          const out = isUndo
+            ? undoReply({ service, packId: parsed.packId, dryRun: parsed.dryRun, warn: (msg) => logger?.warn?.(msg) })
+            : receiveReply({ service, pack: parsed.pack, dryRun: parsed.dryRun, warn: (msg) => logger?.warn?.(msg) });
+          sendJson(res, out.status, out.body);
+        }).catch(() => sendJson(res, 500, { error: "internal" }));
+        return;
+      }
+
       // --- POST /bootstrap: cold-start memories from repo files (#220) -------
       // 显式收 dir（插件没有工作区根目录概念，不猜路径）；确定性解析零 LLM；
       // 幂等骑 saveWithDedupe 的 (type, title, scope) 去重 + _overwrite 刷新。
@@ -671,16 +850,123 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
         const thresholdRaw = Number(url.searchParams.get("threshold") ?? 3);
         const threshold = Number.isFinite(thresholdRaw) ? thresholdRaw : 3;
         const scope = scopeFromSearchParams(url);
-        void Promise.resolve(q && embedder ? withEmbedTimeout(embedQueryVector(embedder, q), embedTimeoutMs) : undefined)
-          .catch(() => undefined)   // 查询嵌入失败降级规则档（与 searchMemories 同口径）
+        // #383：降级原因记账用。embedQueryVector / withEmbedTimeout 只负责「拿不到
+        // 向量时返回 undefined」，原因（无可用接口 / 空向量 / 超时 / 抛错 / 维度不符 /
+        // 没装配 embedder）在这里回收，供 daemon 侧日志枚举——响应体只多 tier 一个
+        // 键，不加第二个字段。
+        const diag = {};
+        // 记账的唯一决策点：q 非空但没装配 embedder。#508 Minor 的成因正是这条路不写
+        // reason，靠日志行的兜底表达式临时拼一个值（no-embedder），而那个值不在文档
+        // 声明的枚举里；同一表达式里还躺着第二个越界字面量 embed-failed。兜底表达式的
+        // 问题不只是越界：它把「默认值」编码在两处，且 embedder 存在时那个 embed-error
+        // 分支一次都走不到（10 种降级场景实测：只要 embedder 为真，embedQueryVector /
+        // withEmbedTimeout / 下面的 .catch 三者必居其一地写好原因），却会把未来任何新增
+        // 的未记账失败一律谎报成「接口抛错」，把运维引去查 HTTP 端点。现在默认值只有
+        // 这一个来源，日志行不再兜底。
+        if (q && !embedder) diag.reason = "no-embedder";
+        void Promise.resolve(q && embedder ? withEmbedTimeout(embedQueryVector(embedder, q, diag), embedTimeoutMs, diag) : undefined)
+          .catch((err) => { diag.reason = "embed-error"; return undefined; })   // 查询嵌入失败降级规则档（与 searchMemories 同口径）
           .then((queryVector) => {
             const pinnedStats = {};
+            // items 本身失败（injectCandidates 抛错，典型如库被关）回 500 是正当的：
+            // 没有可返回的内容。items 一旦算好，后面的档位判定与降级日志就只是诊断，
+            // 任何一步出错都不该把已经算好的 items 丢掉——所以下面每一处 logger 调用
+            // 都各自包了 try/catch（logger 来自宿主，stdout 管道断裂时 warn 自身抛错是
+            // 真实可发生的，而 `logger?.warn?.()` 只防 logger 缺失，防不了这个）。
             const items = service.injectCandidates({ query: q, maxItems, threshold, queryVector, scope, pinnedStats });
+            // #383 档位信号：嵌入降级在调用方视角原本完全静默（items 看着正常，只是
+            // 召回质量悄悄变差），外部集成方无从感知自己长期跑在降级档上。
+            // 三态 fail-closed——判不出来报 unknown，不报 full：
+            //   full     语义档，查询嵌入真的成功了且与库里的向量可比
+            //   degraded 规则档：没装配 embedder / 嵌入超时 / 不可用向量 / 抛错 /
+            //             维度不符（拿到了向量但语义召回整个不可用）
+            //   unknown  语义路未启用（空 q），或判不出来（维度探针没跑成 / 读不出
+            //             任何向量）——那不是降级，但也不能宣称 full
+            // 比 /search 的 mode 更精确：/search 把「空查询」和「向量失败」都报
+            // keyword，这里能分开（空 q 直接可观测）。
+            //
+            // 预算：判档不是免费的——q 非空且配了 embedder 时，它真的会起一次查询
+            // 嵌入（一次网络往返 + embedTimeoutMs 的超时窗口），因为档位要回答的
+            // 正是「这次嵌入成不成」。这里**没有**复用宿主 /health 那份现成数据源：
+            // standalone 的 /health 只回 {ok:true}，而 embeddingDimensionBreakdown
+            // 是 src/api.js 里的一次全表扫（每行 JSON.parse 一个向量），按请求跑会
+            // 把语义路成本翻倍，且它根本不在 standalone 的装配里。维度探针因此走
+            // service.vectorDimensionState()——存在性判据（有没有一条活跃向量与查询
+            // 同维），成本模型见 store.js 那段注释：常态一次全 id 扫描 + 解析 1 个
+            // 向量，只有要报 degraded 时才走完全表。
+            let tier = "unknown";
+            if (q && queryVector) {
+              // #508 Major：探针判据从「读一行的维度」换成存在性。LIMIT 1 拿任意一条
+              // 代表全库，在混合维度库里两个方向都错——抽到与查询不符的那条会误报
+              // degraded（明明有可比的向量），首条解析失败又会漏报成 full。现在问的是
+              // 「有没有一条活跃向量的维度等于查询维度」，与 searchVector 的行集同源。
+              //
+              // 探针失败（库被锁 / 半开 / 旧装配没有这个方法）判不出来：tier 保持
+              // unknown，不宣称 full，也不把已经算好的 items 丢掉。sentinel 不能用
+              // null / undefined——那正是「库里没有向量」的合法读数，混起来就会把一次
+              // 真实的探针故障谎报成 full（fail-open）。隔离只在调用侧：store 与 service
+              // 透传都保持抛出口，不把异常吞成某个 state。
+              let state;
+              // 判不出来时的留痕。unknown 现在有三个生产者（空 q / 探针没跑成 / 有行却
+              // 一条都读不出来），而响应体只有 tier 一个键、分不出它们，调用方对 unknown
+              // 的策略又常常是「不告警」——不留一条 warn，一次真实的判档故障就从运维面上
+              // 消失了。这条 warn **不是** diag.reason 枚举的一员（tier 不是 degraded，
+              // 没有降级原因可记），运维程序不要按降级原因枚举解析它；消息也与
+              // 「degraded to the rule tier (<reason>)」分开，因为语义路这次是真的跑了，
+              // 只是没判成，两种故障的后续动作不同。
+              let judgeFailure;
+              try {
+                state = typeof service.vectorDimensionState === "function"
+                  ? service.vectorDimensionState(queryVector.length)
+                  : undefined;
+              } catch (error) {
+                state = undefined;
+                judgeFailure = `dimension probe failed (${String(error)})`;
+              }
+              if (state?.state === "match" || state?.state === "none") {
+                // match：有维度相符的活跃向量，语义路通（通 ≠ 有命中，四道门仍可能让
+                // 语义档贡献为 0）。none：行集本身为空——没有东西可比，不是维度不符。
+                tier = "full";
+              } else if (state?.state === "mismatch") {
+                // 维度不符：searchVector 对不等长的行直接跳过（见 store.js 的
+                // distill-tx-embed-gap 注释），不抛错、只是命中为零——于是召回静默
+                // 退回 BM25/规则档，而嵌入侧一切正常。这是 issue #383 点名的那一种
+                // 「悄悄退化」，必须有自己的名字：修法是重建索引，不是查端点。
+                diag.reason = "embed-dimension";
+                tier = "degraded";
+              } else if (state?.state === "unreadable" || state?.state === "invalid") {
+                // 有行却一条都读不出来（比维度不符更严重：语义召回 100% 死亡），或查询
+                // 维度本身不是正整数。判不出来，留 unknown。
+                judgeFailure = `no comparable vector readable (${state.state})`;
+              }
+              // undefined（探针方法缺失 / 返回垃圾 / 异步漂移）同样留 unknown。
+              if (judgeFailure) {
+                try {
+                  logger?.warn?.(`dsh-mneme: /context tier left unknown: ${judgeFailure}`);
+                } catch { /* 日志通道坏了也不是把 items 丢掉的理由 */ }
+              }
+            } else if (q) {
+              tier = "degraded";
+            }
+            if (tier === "degraded") {
+              // reason 由唯一决策点（q && !embedder）+ 三个写入方（embedQueryVector /
+              // withEmbedTimeout / 查询嵌入 .catch）+ 维度判据保证必已赋值，所以这里不再
+              // 写第二份默认值——#508 之前的那份兜底表达式（`embedder ? "embed-failed" :
+              // "no-embedder"`）两个默认值互相矛盾、且都在文档枚举之外，其中 embed-error
+              // 分支在 embedder 存在时一次都走不到，却会把未来任何新增的未记账失败一律
+              // 谎报成「接口抛错」。现在只把枚举内的值写进日志：越界或漏记账都露出
+              // (undefined)，那是看得见的缺陷信号，不是一个编出来的因。
+              const reason = CONTEXT_DEGRADE_REASONS.includes(diag.reason) ? diag.reason : undefined;
+              try {
+                logger?.warn?.(`dsh-mneme: /context degraded to the rule tier (${reason})`);
+              } catch { /* 日志通道坏了也不是把 items 丢掉的理由 */ }
+            }
             sendJson(res, 200, {
               profile: (settings?.getProfile?.() ?? "").trim(),
               rules: settings?.getRules?.() ?? [],
               items: service.toApiList(items),
-              pinnedCount: pinnedStats.shown ?? 0
+              pinnedCount: pinnedStats.shown ?? 0,
+              tier
             });
           })
           .catch(() => {