@modusensus/dsh-mneme 0.9.3 → 0.9.5

package/lib/provenance-http.js

@@ -0,0 +1,126 @@
+// 记忆级溯源读出口的 HTTP 口径 —— 唯一实现。
+//
+// 为什么要单独一个模块：这张脸有两个入口——宿主内的面板路由（src/api.js 的
+// /api/dsh-mneme/memory/provenance）与 Bearer 数据面（src/api-standalone.js 的
+// /memory/provenance）。两者底下是同一份 service（provenanceFor + distillRecordsFor），
+// 差别只在鉴权与路径。历史上（#509 第一版）它们是整段复制的，于是「改一边忘一边」
+// 在结构上就可能发生——#411 已经为 reclaim / share 各踩过一次，本模块照那次的结论办。
+//
+// 口径（错误码、两种「空」的区分、窗口形状）现在只写在这里，两个入口都调它。
+// 真要再写第二份，test/provenance-http.test.js 的静态锁会直接转红。
+//
+// 这里只做协议层的事：解析 id、判开关、组装窗口、区分「用户关了」「没接线」与
+// 「没有来源」。一行数据都不改——读取在 src/store.js，透传在 src/service.js。
+//
+// 状态码阶梯（自前而后，先匹配的先回）：
+//   401 未鉴权      ——两个壳各自的门（api.js 的 register 包装 / standalone 的
+//                     isAuthorized），在本模块之前，不在这里重复。
+//   400 缺 id       ——语法畸形，与服务端状态无关，所以排在功能开关之前；与
+//                     reclaim 的 invalid-json 同档（reclaim-http.js:30-33 立的是
+//                     「503 要赢过**字段校验**的 400」，缺 id 不是字段校验而是请求
+//                     本身不成立，所以不适用那条）。判断在壳里
+//                     （parseProvenanceQuery），走到本模块时 id 一定非空。
+//                     ⚠ 将来要加**语义类** 400（如 limit 越界、id 格式不合法），
+//                     必须挪到接线检查之后——那条 reclaim 口径正是为它立的。
+//   409 功能关了    ——distillRecords.enabled !== true。回的是「端点的属性」，
+//                     与 src/api.js:525 的 profileExtractEnabled 同构：用户关了
+//                     某功能 = 409，装配坏了 = 503，两者必须是可区分的答案
+//                     （src/index.js:589-591 的设计原话）。
+//   503 装配没接线  ——service 上没有 provenanceFor / distillRecordsFor。
+//   读（200 / 500）
+// 刻意不用 404：本端点永远不就「这条记忆是否存在」作断言（缺 id 是 400、未知 id
+// 是 200 + 空 windows），404 在本仓另有稳定含义——未知路由与资源不存在
+// （src/api-standalone.js:506/515、src/api.js:1367/1445）。把「功能关了」塞进
+// 404，调用方会在状态码这个唯一被代理 / 监控 / 重试逻辑读取的通道上，把它读成
+// 「这条记忆不存在」。
+
+/**
+ * 「溯源能力没接线」的错误码。headless / 旧装配下 service 上没有 provenanceFor 或
+ * distillRecordsFor，那是装配坏了，不是「这条记忆没有来源」——两种空必须分开读数，
+ * 否则调用方看到一个空 windows 会以为拿到了答案。
+ */
+export const PROVENANCE_UNAVAILABLE = "provenance-unavailable";
+
+/**
+ * 「用户把蒸馏原文留存关掉了」的错误码。distillRecords.enabled 既是写侧的总闸
+ * （src/summarize.js:988）也是本读出口的总闸（#509 评审整改）：关着时盘上可能
+ * 还有历史原文（保留期裁剪与写入同在 src/index.js:270 一道门里），但本端点不再
+ * 把它们读出去。与 api.js:525 的 "disabled" 分开：那个面只有一个功能开关，本仓
+ * 数据面上会有多个，特定码才让调用方分得清是哪一个被关。
+ */
+export const DISTILL_RECORDS_DISABLED = "distill-records-disabled";
+
+/**
+ * 读侧唯一的开关判据，**与写侧 src/summarize.js:988 逐字同源**。
+ *
+ * 为什么不放在两个壳里各算一次：那句话已经是本仓第 3、第 4 份拷贝了
+ * （summarize.js:988、index.js:270），而 #411 的结论就是「两张皮整段复制必然
+ * 漂移」——读写两道门一旦漂移，就会出现「以为关了却还能读出去」或「开着却读不到」
+ * 这两种都更难排查的状态。壳只转发 config，判据只在这里出现一次。
+ *
+ * fail-closed：config 缺失（null / undefined）、distillRecords 组缺失、值不是
+ * 严格的 true（"true" 字符串 / 1 / undefined）一律算关。这个端点返回的是蒸馏
+ * 窗口的逐字会话原文，判不出来时必须往「不读」那一侧倒。
+ *
+ * @param {object|null|undefined} config 启动期冻结的装配后 cfg（宿主 index.js:597
+ *   的 createApi 第 8 参 / index.js:621 的 createStandaloneApi config / daemon
+ *   serve.js 的最小 cfg）。
+ * @returns {boolean}
+ */
+export function isDistillRecordsEnabled(config) {
+  return config?.distillRecords?.enabled === true;
+}
+
+/** 溯源读取失败的 warn 文案。两个入口共用，日志里不会出现两种拼法。 */
+export function provenanceWarnMessage(error) {
+  return `[dsh-mneme] memory provenance read failed: ${String(error)}`;
+}
+
+/**
+ * 解析 ?id。空 / 缺失 → 400；其余原样交给 service（id 不存在时返回空 windows，
+ * 那是有效答案，不是错误——读端点不替调用方判断记忆是否存在）。
+ *
+ * @returns {{ok: true, id: string} | {ok: false, status: 400, error: string}}
+ */
+export function parseProvenanceQuery(raw) {
+  const id = typeof raw === "string" ? raw.trim() : "";
+  if (!id) return { ok: false, status: 400, error: "missing-id" };
+  return { ok: true, id };
+}
+
+/**
+ * 组装答复：一个链接一个窗口（区间 + 区间内原文行，按 seq 升序）。
+ *
+ * 顺序敏感（阶梯全貌见文件头）：409 功能关了 → 503 装配没接线 → 读。
+ * 503 要赢过空结果——装配没接线时报「这条记忆没有来源」是误导，与 reclaimReply 的
+ * maintenance-unavailable 同构；而 409 要赢过 503——「用户关了」比「装配坏了」更
+ * 具体，把前者报成后者会让人去查一个没坏的部署。
+ *
+ * @param {{service: object, id: string, config?: object|null, warn?: Function}} args
+ *   config 缺省即关（fail-closed），见 isDistillRecordsEnabled。
+ * @returns {{status: number, body: object}}
+ */
+export function provenanceReply({ service, id, config = null, warn = null }) {
+  if (!isDistillRecordsEnabled(config)) {
+    return { status: 409, body: { error: DISTILL_RECORDS_DISABLED } };
+  }
+  if (typeof service?.provenanceFor !== "function" || typeof service?.distillRecordsFor !== "function") {
+    return { status: 503, body: { error: PROVENANCE_UNAVAILABLE } };
+  }
+  try {
+    const links = service.provenanceFor(id);
+    const windows = links.map((link) => ({
+      session_id: link.session_id,
+      seq_start: link.seq_start,
+      seq_end: link.seq_end,
+      created_at: link.created_at,
+      // 到期裁剪后区间可能变空：链接刻意保留并指向空区间（clearDistillRecords 的
+      // 语义），面板据此显示「原文已过期」而非「没有来源」。
+      records: service.distillRecordsFor(link.session_id, link.seq_start, link.seq_end)
+    }));
+    return { status: 200, body: { memoryId: id, windows } };
+  } catch (error) {
+    warn?.(provenanceWarnMessage(error));
+    return { status: 500, body: { error: "internal" } };
+  }
+}

package/lib/serve.js

@@ -61,6 +61,19 @@ export async function createServeRuntime({
   // documentMemoryEnabled 关掉 document 子系统(daemon 不建 documentIndex,service
   // 内部 if-guard 安全,index.js:261 的 documentIndex 仅宿主装配)。
   const cfg = { language: "zh", documentMemoryEnabled: false };
+  // #509 评审整改补的一格:GET /memory/provenance 的读门读 cfg.distillRecords.enabled
+  // (判据在 src/provenance-http.js,与写侧 src/summarize.js:988 同源)。daemon 与宿主
+  // 共用同一个 memory.db、同一份 feature_flags kv,所以这里把用户显式开关展开进 cfg
+  // ——index.js:217-233 同款展开,只取蒸馏这一组(daemon 其余键仍刻意不吃宿主 config
+  // schema)。不展开的后果:daemon 对这一面恒定回「功能关了」,哪怕用户在面板里开着、
+  // 库里明明有原文——对这个端点那是一句谎话,而「两种空必须分开读数」正是本仓纪律。
+  // 残留不对称(写进 docs/DAEMON.md 与 PR):只靠 bundle 配置打开、从没在面板点过的
+  // 用户,宿主认、daemon 不认——daemon 结构上看不到宿主的 bundle config,这是它看不见
+  // 的那一半,不是本处能补的。
+  const persistedFlags = settings.getFeatureFlags?.() ?? {};
+  if (typeof persistedFlags["distillRecords.enabled"] === "boolean") {
+    cfg.distillRecords = { ...(cfg.distillRecords ?? {}), enabled: persistedFlags["distillRecords.enabled"] };
+  }
   const mirror = createMirror(dir, langOf(cfg));
   const service = createService({ store, mirror, config: cfg, logger });
 

package/lib/service.js

@@ -7,9 +7,13 @@ import { STR, langOf } from "./lang.js";
 import { computeHeat } from "./heat.js";
 import { recallStats } from "./recall-stats.js";
 import { evaluateMemoryQuality } from "./quality-filter.js";
+// 外来行（source='imported'，导入路径落的来源）的身份判定只许有一个定义处——本文件的
+// 两处汇流口与巩固/降级那些读侧行池都调这同一个谓词，避免各处自己写字符串比较然后各自漂移。
+import { isImportedRow } from "./memory-source.js";
 import { applyDecisions } from "./dream/decisions.js";
 import { createDocumentRegistrar } from "./document.js";
 import { createOrganizer } from "./organize.js";
+import { createShareImport } from "./share-import.js";
 import { createBM25Index } from "./search/bm25.js";
 import { adaptiveThreshold } from "./search/adaptive.js";
 import { anchorSeeds, normalizePath, cascadeDepths, HOP_QUOTA } from "./graph/anchoring.js";
@@ -1368,7 +1372,31 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // dream 总览按 source 身份去重，而非本地化标题：memory.language 切换后
     // 标题变化，若仍按 (type, title) 匹配会出现两个活跃的 summary 同时注入。
     // 其余类型维持 (type, title) 匹配不变。
-    const candidates = store.list({ type: memory.type, limit: 100 });
+    //
+    // Issue #505：候选集此前是 store.list({ type, limit: 100 }) —— 那是「该类型
+    // 最重要的 100 行」（order 默认 importance），与「找出同标题的那一行」无关。
+    // 某类型里 importance 高于待写行的行数一旦超过 100，同标题行与待写行双双落在
+    // 窗口外，下面的 find 恒不命中，于是静默走创建分支：不报错、不告警，合并语义
+    // 随库增长而失效（实测 1047 行类型、importance=5 有 180 行时稳定复现）。
+    // 改为按同标题定向取（store.activeByTypeAndTitle，无窗口）。
+    //
+    // spec §5 决策 2：本机巩固不许改写别人的原文。这里不是防呆——蒸馏路径的每一次
+    // 同题命中都会 appendContent 覆盖外来行的正文与 updated_at，别人的记忆从此变成
+    // 我们两家的混杂物。把外来行剔出候选集后只会落回既有的「新建一行」分支。
+    // 谓词挂在**两个**候选集上：sourceScopedCandidates 在 dream/narrative 那两条分支
+    // 里就是候选集本身，只挂 candidates 等于给外来行留一条后门。这一处过滤留在 JS 侧
+    // 而不是下推 SQL（同 #515 的反面）：那里下推是因为外来行会吃掉 LIMIT 窗口名额，
+    // 这里 limit: null 本就无界，没有窗口可饿，而下推会多出第二份外来行判据。
+    const candidates = store.activeByTypeAndTitle(memory.type, memory.title).filter((m) => !isImportedRow(m));
+    // dream/narrative 两条分支按 source（及 tags[0]）匹配，而不是按标题：它们的
+    // 去重键本来就不含标题（语言切换后标题会变）。定向取同标题会把这两条路径
+    // 打回「永远不命中」——所以这两类仍走「该类型活跃行」的候选集，只是窗口换成
+    // 了无界且不带 importance 排序。类型内行数由 summary 的生产方（autoDream /
+    // generateNarratives）决定，量级远小于普通记忆，且这两条分支本来就要求扫全
+    // 类型才能找到同 source 的那一行——原来的 100 行窗口对它们同样是错的。
+    const sourceScopedCandidates = (memory.type === "summary" && (memory.source === "dream" || memory.source === "narrative"))
+      ? store.list({ type: memory.type, limit: null }).filter((m) => !isImportedRow(m))
+      : candidates;
     // v0.8.0 A1（issue #17）：去重键由 (type, title) 扩展为
     // (type, title, agent_scope, workspace_scope, sensitivity)——不同作用域的同
     // 标题记忆绝不互相物理合并（旧逻辑跨 agent/workspace 并行，事后无法拆分）。
@@ -1386,17 +1414,20 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // 下面这段并入逻辑（appendContent + content_history + 质量处置），不另写第二份
     // 实现。目标已被并发删除时回落到常规匹配。显式目标同样过 scope 门：跨作用域
     // 的语义相似不并入（防泄漏），回落为独立新行。
-    const explicitTarget = memory._mergeInto ? store.getById(memory._mergeInto) : undefined;
+    // 显式目标还过外来门（spec §5 决策 2）：调用方指到别人导入的原文时，这个目标
+    // 按「未命中」处理，同样落回新建一行——两条路都只有 merged/created 两种结局。
+    const explicitCandidate = memory._mergeInto ? store.getById(memory._mergeInto) : undefined;
+    const explicitTarget = explicitCandidate && !isImportedRow(explicitCandidate) ? explicitCandidate : undefined;
     const existing = explicitTarget
       ? (scopeMatches(explicitTarget) ? explicitTarget : undefined)
       : (memory.type === "summary" && memory.source === "dream")
-        ? (candidates.find((m) => m.source === "dream" && scopeMatches(m))
+        ? (sourceScopedCandidates.find((m) => m.source === "dream" && scopeMatches(m))
           ?? candidates.find((m) => scopeMatches(m) && m.title.trim() === String(memory.title).trim()))
         : (memory.type === "summary" && memory.source === "narrative")
           // 叙述条（#164）按主题键去重而非本地化标题：标题随语言变
           // （叙述：X / Narrative: X），title 匹配在语言切换后会残留同 tag 双行。
           // tag 存于 tags[0]（generateNarratives 落库），跨语言稳定 → 原地刷新。
-          ? (candidates.find((m) => m.source === "narrative" && m.tags?.[0] === memory.tags?.[0] && scopeMatches(m))
+          ? (sourceScopedCandidates.find((m) => m.source === "narrative" && m.tags?.[0] === memory.tags?.[0] && scopeMatches(m))
             ?? candidates.find((m) => scopeMatches(m) && m.title.trim() === String(memory.title).trim()))
         : candidates.find((m) => scopeMatches(m) && m.title.trim() === String(memory.title).trim());
     if (existing) {
@@ -2564,18 +2595,34 @@ export function createService({ store, mirror, config, onWrite, logger, document
     }
   });
 
+  // 车道 C 收侧的入库与整包退出（spec §5）：内聚块在 src/share-import.js，这里只做依赖
+  // 注入 + barrel 出口。注入的是本文件的 transaction 而不是 store.runAtomically——嵌入
+  // 队列由 transaction 的最外层 COMMIT 排空，换那个助手等于静默不嵌入（#372 修过两次）；
+  // 退出那侧用它则是为了 finally 里的 syncMirror + notifyWrite（删完得让其余读侧知道）。
+  const shareImport = createShareImport({ store, transaction, scheduleEmbed });
+
   return {
     saveWithDedupe,
     registerDocument,
     // agent 主动整理接口（#231）：内聚块在 src/organize.js，这里只做依赖注入 +
-    // barrel 出口。刻意不加 opt-in 开关（维护者口径：功能本体不做开关，与 #249
-    // 同批暴露时再定配置面），也不进工具列表——工具注册在 #249 那批。
+    // barrel 出口。本体不带配置键（第一批口径），暴露闸住在工具层（#231 第二批的
+    // `organizeEnabled` → `tools.js` 的 `memory_organize`）：service 侧不认识开关，
+    // 所以直连 service 的调用方（测试、内部管线）不受面板那格影响。
     organize,
     recoverMirror,
     getMirrorHealth,
     getMirrorState: () => store.getMirrorState(),
     injectCandidates,
     mergeHumanEdits,
+    // 车道 C 收侧：两张皮（面板路由 / standalone 数据面）各自的壳只认这一份实现——
+    // createApi 手里没有 store，「api 层不直接摸 store」这条纪律（见下面 embeddedCount
+    // 那组 passthrough 的注释）要求导入从 service 进，否则两皮各摸一遍 store、幂等
+    // 口径随之变成两份。
+    importSharePack: shareImport.importSharePack,
+    // 整包退出（C4）与导入同住 src/share-import.js：收侧的「进与出」共用同一份 store
+    // 注入与同一个事务口径，键名照计划里的契约留在 service 的返回表上，两张皮（C5/C6）
+    // 只认 service 这一个入口——api 层不直接摸 store 那条纪律对退出同样成立。
+    deleteSharePack: shareImport.deleteSharePack,
     toApiList,
     isVisibleInScope,
     // issue #471 政策轴：按下/松开与读取照 store 那三条件透传（纯 bookkeeping，
@@ -2598,6 +2645,9 @@ export function createService({ store, mirror, config, onWrite, logger, document
     saveDistillRecords: (records) => store.saveDistillRecords(records),
     saveMemoryProvenance: (link) => store.saveMemoryProvenance(link),
     provenanceFor: (memoryId) => store.provenanceFor(memoryId),
+    // #421 读出口：按 (session, seq 区间) 取蒸馏原文。与 provenanceFor 成对——
+    // 一个给区间、一个给区间里的原文，合起来才是「这条记忆从哪几句蒸出来的」。
+    distillRecordsFor: (sessionId, seqStart, seqEnd) => store.distillRecordsFor(sessionId, seqStart, seqEnd),
     enqueue,
     setDreamHook(fn) { dreamHook = fn; },
     setSleepHook(fn) { sleepHook = fn; },
@@ -2669,6 +2719,20 @@ export function createService({ store, mirror, config, onWrite, logger, document
     // passthrough 形状与 embeddedCount 同款，api 层不直接摸 store。
     embeddingModelBreakdown: () => store.embeddingModelBreakdown(),
     embeddingDimensionBreakdown: () => store.embeddingDimensionBreakdown(),
+    // #383：维度探针，供 /context 判「库里有没有一条活跃向量与查询同维」。注意
+    // 它**不再是**「读一行的维度」（那个判据在混合维度库里两个方向都错，见 store.js
+    // vectorDimensionState 的注释）：换成存在性判据后成本是「一次全 id 扫描 + 按匹配
+    // 短路的解析」，同维度健康库只解析 1 个向量，只有要报 degraded 时才走完全表。
+    // 与上面那个全表扫的 breakdown 仍是两件事：一个是状态页的完整分布，一个是每请求
+    // 用得起的判据。透传而非让 api 层摸 store，与同组其他条目一致；api 侧负责把探针
+    // 异常隔离成 unknown，不在这里吞。
+    vectorDimensionState: (dimension) => store.vectorDimensionState(dimension),
+    // 整包透传：store.list 的每个口径（excludeTypes / excludeImported / includeArchived…）
+    // 都从这里过去，service 侧不再枚举一遍——枚举就是第二份口径表，加一个键就要改两处，
+    // 漏改的那处静默失效。政策轴一律走这里的查询参数，不许退回调用方的 .filter：
+    // LIMIT 先生效的话，被丢掉的行照样吃掉窗口名额。前例是同文件 syncMirror 的那条注释
+    // （src/service.js:2247，document 轴改由 excludeTypes 在 LIMIT 之前排除），
+    // 同一取舍的另两次是 #230 与 #471。
     list: (o) => store.list(o),
     all: () => store.all(),
     count: (type, opts) => store.count(type, opts),

package/lib/settings.js

@@ -185,6 +185,10 @@ const FEATURE_FLAG_BOOLEANS = [
   // 在慢/轻量模型上是多余往返，面板可关（默认关=行为不变）。
   "disableMemorySearch",
   "disableMemoryArchive",
+  // Issue #231 第二批：agent 主动整理（memory_organize 工具）的暴露闸。与上面两个
+  // 反向——那两个藏默认在场的工具，本键开默认不在场的能力（默认关=工具根本不存在，
+  // 行为逐字节不变）。面板可启停=线上回滚开关。
+  "organizeEnabled",
   // 嵌套对象开关：config.js 里是 memoryQualityFilter / llmAudit 对象的 enabled
   // 子字段。kv 按点号键平铺存（"memoryQualityFilter.enabled": false），index.js
   // 合并时展开回嵌套对象，api.js 的 effective 从对象子字段取值。
@@ -229,7 +233,13 @@ const FEATURE_FLAG_BOOLEANS = [
   // LIGHT_MODE_OFF——人格段是用户自写的一小段轻量常驻文本，不引入任何重型后台
   // 路径，轻量档用户显式勾选仍然赢（同 actionPipelineEnabled 的定性）。顶层扁平
   // 键，不需要 NESTED_FLAG_PATHS 条目。
-  "personaEnabled"
+  "personaEnabled",
+  // 人格寻址口径（上一条打开时才有意义）：开 = 身份没建卡/卡被关时不注入人格，
+  // default 只兜解析不到身份的会话。默认关（历史行为，升级零变化）。
+  "personaStrictAddressing",
+  // Issue #497：画像提取草稿（POST /profile/extract）。默认关——每次调用一次 LLM 且
+  // 读上百行记忆；产物只回草稿，绝不写 user_settings。进 LIGHT_MODE_OFF（预设关）。
+  "profileExtractEnabled"
 ];
 // 整数开关的闭区间，与 config.js 里 z.natural().min().max() 对齐。
 const FEATURE_FLAG_INT_RANGES = {
@@ -247,6 +257,9 @@ const FEATURE_FLAG_INT_RANGES = {
   // Issue #239：蒸馏零 LLM 预判（窗口最小字符数）与每会话 run 预算（0 = 零行为变化）。
   summarizeMinWindowChars: [0, 100000],
   summarizeMaxRunsPerSession: [0, 1000],
+  // Issue #493：连续解析失败几次后放弃当前窗口（0 = 关）。与 config.js 的
+  // z.natural().min(0).max(10) 成对。
+  summarizeParseFailureMaxRetries: [0, 10],
   // Issue #239 第 4 项：高峰顺延上限（分钟，0 = 不设上限）。
   summarizePeakMaxDeferMinutes: [0, 1440],
   // Issue #239 第 4 项镜像到巩固：同一口径（分钟，0 = 不设上限）。
@@ -489,8 +502,9 @@ export function createSettings(db) {
     /**
      * Agent persona (name / personality / replyStyle + enabled gate), stored as
      * one JSON key. v1.2 多卡：存储形 { default, byAgent }，旧 v1 单对象读作
-     * default 兼容。getPersona 返回全量多卡形（面板用）；getPersonaFor 按 agent
-     * 身份取卡（注入用），身份缺失/无卡/卡 enabled=false 均落 default。
+     * default 兼容。getPersona 返回全量多卡形（面板与注入寻址都用它）。
+     * 寻址与兜底口径不在这里——住 src/user-settings.js 的 resolvePersonaCard，
+     * 注入与面板预览共用那一份；这里若再留一个 getPersonaFor，就是两张皮。
      */
     getPersona() {
       return parsePersonaStore(getSetting("persona") ?? "{}");
@@ -507,16 +521,6 @@ export function createSettings(db) {
       current.default = parsePersona(JSON.stringify(input));
       setSetting("persona", serializePersonaStore(current));
     },
-    /** Per-agent lookup for the injector: id card → default fallback. */
-    getPersonaFor(agentId) {
-      const store = parsePersonaStore(getSetting("persona") ?? "{}");
-      const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
-      if (id) {
-        const card = store.byAgent[id];
-        if (card && card.enabled === true) return card;
-      }
-      return store.default;
-    },
     /** Replace one byAgent card wholesale (panel save); default 不可经此改。 */
     setPersonaFor(agentId, card) {
       const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";

package/lib/share-http.js

@@ -0,0 +1,281 @@
+// 分享包在两张皮上共用的解析与答复（形状照 src/reclaim-http.js，#411）。
+// 只返回 {status, body}，绝不自己写 res —— 两侧的 sendJson 签名不同（api.js 有
+// headers 第四参、api-standalone.js 没有），把写 res 留在各侧 handler 里是唯一
+// 能让一份实现喂两张脸的做法。
+//
+// 哪些行进包、以什么原因不进，一条判据都不在这里重复：那是 src/share.js 的事。本模块
+// 只做协议层的事——读 body、把结果包成答复、给一个能落盘的文件名。
+import { buildSharePack } from "./share.js";
+
+/** 拒发时的下一步动作。它是给调用方看的，出口只许有一处措辞（同 RECLAIM_CONFIRM_HINT）。 */
+const SHARE_ERROR_HINT = "包体超过分享水位：用 --type 或 --tag 分批，别整库外发。";
+
+/**
+ * 记日志这一手，只许经这里。
+ *
+ * 「这一层从不抛」是**层的契约**，不是每个调用面的运气（C5 评审裁定）：warn 裸调时，宿主
+ * logger 自己坏掉就会从 catch 块里再抛出去，而两侧 handler 那个外层 try 在 .then 的回调里
+ * 早已退栈——现场就是「一个字节都没回」（#410）。守卫住在面上一处一个，等于每接一张新脸
+ * 都要记得再兜一次；住在层里，两侧、以及后面的 CLI（C7）拿到的都是同一个脾气。
+ *
+ * 三个构造器（shareReply / receiveReply / undoReply）都走这里，**对称本身就是要点**：
+ * 只给新加的两个上守卫、出包那侧留一处裸调，下一个读者就会照那处裸的抄。
+ * 日志环坏掉时答复照旧送出——对面拿到的仍是那一个状态码，只是少了一条日志迹。
+ */
+function warnSafely(warn, message) {
+  try {
+    warn?.(message);
+  } catch { /* 记日志是自己的事，坏了的日志不许把已经算好的答复一起带走 */ }
+}
+
+/**
+ * 解析 POST body（已由调用方读成文本）→ buildSharePack 的入参集合。
+ *
+ * 空 body 等价于 `{}`：分享的主用法就是「一个字节都不发，按整库口径打」。坏 JSON 与
+ * 发成数组/null 是两个不同的错码（前者是调用方发坏了，后者是发错了顶层形状），
+ * 与 reclaim 侧同款，出口要能分支。
+ *
+ * 只认这三个键，多余的键丢掉：面板与 CLI 各写各的选项时，静默接受一个拼错的键等于
+ * 让她以为筛过了。
+ *
+ * 这里**没有** dryRun：share 是纯读、不改库，spec §4 明确它不套 reclaim 的
+ * dry-run/confirm 纪律，干跑由 CLI 侧的 `--dry-run` 决定（它压根不发这个键）。上一版
+ * 把它「登记但不参与答复构造」留着，等于凭空多出一个没人消费的公开字段：今天发
+ * `dryRun: true` 的人拿到的是真包，而哪天要给它真语义、或把它删掉，两侧都是破坏性改动。
+ * 删掉后它和别的多余键走同一条规则——丢掉，不再是一个特例。
+ *
+ * @returns {{ok: true, options: {alias?: string, type?: unknown, tag?: unknown}}
+ *           | {ok: false, error: string}}
+ */
+export function parseShareBody(text) {
+  if (text === undefined || text === null || String(text).trim() === "") return { ok: true, options: {} };
+  let body;
+  try {
+    body = JSON.parse(String(text));
+  } catch {
+    return { ok: false, error: "invalid-json" };
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: "invalid-body" };
+  const options = {};
+  if (typeof body.alias === "string") options.alias = body.alias;
+  // type / tag 在这里只判「填没填」，不判形状。收窄口径是 share.js 的 shareFilterSet，
+  // 它钉死的是「读不懂的形状只许收窄到 0 条，不许当没填」（错的方向是少发，当场看得见）。
+  // 本层若再校验一次形状、把裸字符串或混进非字符串条目的数组丢成「没填」，就等于在 HTTP
+  // 面上把那条洞反着挖开——她以为只发了一类，实际整库进包，而 report 看不出异样。
+  if (body.type !== undefined && body.type !== null) options.type = body.type;
+  if (body.tag !== undefined && body.tag !== null) options.tag = body.tag;
+  return { ok: true, options };
+}
+
+/** 包文件名：日期 + pack_id 前 8 位。Content-Disposition 与 CLI 落盘共用这一个拼法。 */
+export function shareFilename(packId, now = () => new Date()) {
+  const stamp = now().toISOString().slice(0, 10).replace(/-/g, "");
+  return `dsh-mneme-share-${stamp}-${String(packId).slice(0, 8)}.json`;
+}
+
+/**
+ * 组包并给出答复。`service.all()` 是「全库含归档/已遗忘」的现成通道（store.js 的 all()
+ * 不带 WHERE），口径判据全在 share.js 里判，本模块不重复任何一条。
+ *
+ * filters 两个键只在填了时才挂上去：buildSharePack 的默认值兜的是 `filters` 整个参数为
+ * undefined，构造一个 `filters: null` 会直接在对端解引用时抛——没填的键就让它不存在。
+ *
+ * 413 那条绝不回 pack：这条答复存在的原因恰恰是包太大，把 memories 序列化回去等于把
+ * 刚拒绝掉的那几 MB 再发一遍。report + 量到的字节 + 水位 + 提示够出口说清「大了多少、
+ * 怎么分批」（share.js 超限时也把完整 pack 交回，本层只用它的 report）。
+ *
+ * 抛错在这里兜住并回 500，不留给调用方的 try：面板侧 handler 的形状是
+ * `try { return readBody(...).then(...) } catch`，外层 try 在 .then 的回调里已经退栈，
+ * 从这里抛出去就是一个没人接的 rejection，客户端拿到的不是 500 而是「一个字节都没回」
+ * （#410，reclaim-http.js 里 reclaimReply 那段注释记的就是这一次）。共用层兜一次，两张
+ * 皮才不会因为各自接线不同而有一种会漏。warn 可选：数据面的 logger 未必接得上，少一个
+ * 回调也不许把异常漏出去。
+ *
+ * @param {{service: {all: () => object[]}, packageVersion: string, homeDir: string,
+ *          now?: () => Date, options?: object, warn?: ((msg: string) => void)|null}} input
+ * @returns {{status: number, body: object}}
+ */
+export function shareReply({ service, packageVersion, homeDir, now = () => new Date(), options = {}, warn = null }) {
+  try {
+    const rows = typeof service?.all === "function" ? service.all() : [];
+    const filters = {};
+    if (options.type !== undefined) filters.type = options.type;
+    if (options.tag !== undefined) filters.tag = options.tag;
+    const out = buildSharePack({
+      rows, alias: options.alias, homeDir, packageVersion,
+      filters,
+      generatedAt: now().toISOString()
+    });
+    if (!out.ok) {
+      return {
+        status: 413,
+        body: { error: out.error, bytes: out.bytes, limitBytes: out.limitBytes, hint: SHARE_ERROR_HINT, report: out.pack.report }
+      };
+    }
+    return { status: 200, body: out.pack };
+  } catch (error) {
+    // 日志里留住原始文本（现场最难下手的就是「只回了 internal」那一类），对外只有一个码。
+    warnSafely(warn, `[dsh-mneme] share pack failed: ${String(error)}`);
+    return { status: 500, body: { error: "internal" } };
+  }
+}
+
+// --- 接收侧（车道 C，spec §5）--------------------------------------------------
+// 入库与整包退出同属「两张皮只许差在鉴权与路径」那条纪律（#411），所以这两组解析/答复
+// 也住在本模块，与出包侧同一个形状：只回 {status, body}，绝不写 res。
+//
+// 这里刻意**不**重跑 validateSharePack：整包闸门住在 share.js、由 service 的
+// importSharePack 自己调（src/share-import.js）。本层再判一次就是第二套口径——两份实现
+// 各自演进时最坏情况是「路由放行、service 拒」或反过来，而一个包有没有合格从此没有准信。
+// 失败靠 err.code 鸭子类型映射成状态码：ShareImportError 是刻意不从 service 再导出的
+// （类跨模块之后，instanceof 就退化成「只在同一个实例内成立」），码才是契约。
+
+/**
+ * 导入错误码 → HTTP 状态。一张表喂两张皮（数据面那半也从这儿取），码集由 share.js 的
+ * validateSharePack 定：闸门新增一格必须在这里登记。认不出的码走「500 + 日志」那一条，
+ * 绝不静默降级成 400 冒充「你的包不合格」——那会把存储故障报成对方的错。
+ */
+export const SHARE_IMPORT_ERRORS = Object.freeze({
+  "invalid-kind": 400,
+  "invalid-pack-id": 400,
+  "invalid-memories": 400,
+  "empty-pack": 400,
+  "invalid-type": 400,
+  "invalid-entry": 400,
+  "external-id-mismatch": 400,
+  "duplicate-external-id": 400
+});
+
+/**
+ * 「收侧没接线」的码（headless 或旧装配里没有那两个方法）。与 RECLAIM_UNAVAILABLE 同一
+ * 处置：字面量只许住在本模块，两张皮都从这一个导出取，否则各写一种拼法就没法按码分支。
+ */
+export const SHARE_IMPORT_UNAVAILABLE = "share-import-unavailable";
+
+/**
+ * 缺省即干跑：没有 confirm 就是预览。脾气照 readReclaimFields 的 confirm（只认真布尔），
+ * 但这一面的方向更硬——写的是**收件人的库**，所以唯一的入口就是 confirm，`dryRun` 之类
+ * 的第二个旋钮一概不认（reclaim 的 body 形状里就带 dryRun，手熟的人会顺手发来，把它读成
+ * 「要写」等于替她点头）。
+ */
+function readDryRun(body) {
+  return body?.confirm !== true;
+}
+
+/**
+ * 答复壳里唯一由本层加的一格。service 那一侧收的是 opts.dryRun、不认识 dry_run，对面读的
+ * 却是这一格，所以放在本层加：两张皮拿到的键才完全相同。
+ *
+ * `dryRun !== false` 而不是 `=== true`：认不出的值（字符串、对象、undefined）一律落回**干跑**，
+ * 与解析侧同一个失败方向；而传下去的那个布尔值与写进答复的那一格永远同一个数——「其实没写、
+ * 却说写了」和「其实写了、却说没写」都是说谎，这一格不许和实参分家。
+ */
+function withDryRun(reply, dryRun) {
+  return { ...reply, dry_run: dryRun !== false };
+}
+
+/**
+ * 解析 POST /receive 的 body（已读成文本）→ { pack, dryRun }。
+ *
+ * 三个码分开是有原因的：invalid-json（发坏了）、invalid-body（顶层就不是对象）、
+ * missing-pack（对象里没有包）——对面据此知道改哪一头，而它们全是 400。空 body 是
+ * **错**的，与出包侧相反：那边「一个字节都不发」是整库口径，这边压根没东西可写。
+ *
+ * pack 那一格只判「是不是个对象」，不判包：数组或 `{kind:"nope"}` 都往下交，由闸门整包拒
+ * （invalid-kind）。判据只许有一处。
+ *
+ * @returns {{ok: true, pack: object, dryRun: boolean} | {ok: false, error: string}}
+ */
+export function parseReceiveBody(text) {
+  if (text === undefined || text === null || String(text).trim() === "") return { ok: false, error: "invalid-body" };
+  let body;
+  try {
+    body = JSON.parse(String(text));
+  } catch {
+    return { ok: false, error: "invalid-json" };
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: "invalid-body" };
+  if (!body.pack || typeof body.pack !== "object") return { ok: false, error: "missing-pack" };
+  return { ok: true, pack: body.pack, dryRun: readDryRun(body) };
+}
+
+/**
+ * 解析 POST /receive/undo 的 body → { packId, dryRun }。顶层形状与「有没有 id」是两个错，
+ * 与 receive 侧同一口径（发坏了 / 发错了形状 / 没填）。
+ *
+ * id 在这里 trim，与 deleteSharePack 首行同一把尺；非字符串与空白一律不进删除那条路——
+ * 让空白去 service 那儿换回一个 `pack_id: ""` 的 0 删除，读数上看不出是「没填」还是
+ * 「那个包本来就没导入过」，而这两种在出口是完全不同的事。
+ *
+ * @returns {{ok: true, packId: string, dryRun: boolean} | {ok: false, error: string}}
+ */
+export function parseUndoBody(text) {
+  if (text === undefined || text === null || String(text).trim() === "") return { ok: false, error: "invalid-body" };
+  let body;
+  try {
+    body = JSON.parse(String(text));
+  } catch {
+    return { ok: false, error: "invalid-json" };
+  }
+  if (!body || typeof body !== "object" || Array.isArray(body)) return { ok: false, error: "invalid-body" };
+  const packId = typeof body.packId === "string" ? body.packId.trim() : "";
+  if (!packId) return { ok: false, error: "missing-pack-id" };
+  return { ok: true, packId, dryRun: readDryRun(body) };
+}
+
+/**
+ * 入库的答复。`pack` 原样交给 service，校验在那儿跑（见本段开头那句「判据只许有一处」）。
+ *
+ * 抛错在这儿兜住并回 500，不留给调用方的 try：两侧 handler 的形状都是
+ * `try { return readBody(...).then(...) } catch`，外层 try 在 .then 的回调里已经退栈，
+ * 从这里抛出去就是一个没人接的 rejection（#410）。warn 可选——数据面的 logger 未必接得上，
+ * 少一个回调不许把异常漏出去。
+ *
+ * @param {{service: {importSharePack?: Function}, pack: object, dryRun?: boolean,
+ *          warn?: ((msg: string) => void)|null}} input
+ * @returns {{status: number, body: object}}
+ */
+export function receiveReply({ service, pack, dryRun, warn = null }) {
+  if (typeof service?.importSharePack !== "function") {
+    return { status: 503, body: { error: SHARE_IMPORT_UNAVAILABLE } };
+  }
+  const dry = dryRun !== false;
+  try {
+    return { status: 200, body: withDryRun(service.importSharePack(pack, { dryRun: dry }), dry) };
+  } catch (error) {
+    const code = typeof error?.code === "string" ? error.code : null;
+    const status = code === null ? undefined : SHARE_IMPORT_ERRORS[code];
+    if (status) {
+      // detail 是闸门给的那一格（哪个字段、哪个坏类型），只转发不加工；没有就不造这一格。
+      const detail = typeof error.detail === "string" && error.detail ? { detail: error.detail } : {};
+      return { status, body: { error: code, ...detail } };
+    }
+    warnSafely(warn, `[dsh-mneme] share import failed: ${String(error)}`);
+    return { status: 500, body: { error: "internal" } };
+  }
+}
+
+/**
+ * 整包退出的答复。这一面**不查** SHARE_IMPORT_ERRORS：packId 的形状闸门在 parseUndoBody，
+ * service 那侧不抛带码的错（非字符串/空白它回一个 0 删除，不是异常），所以真抛出来就是
+ * 存储故障。别在这儿补第二张表——那张表只会成为 SHARE_IMPORT_ERRORS 的影子。
+ *
+ * 答复里的 pack_id 是 service 的读数而不是请求的回显（非字符串/空白那一支它回 ""），
+ * 本层不改写、不兜底；dry_run 由 withDryRun 加，与入库那侧同一格键。
+ *
+ * @param {{service: {deleteSharePack?: Function}, packId: string, dryRun?: boolean,
+ *          warn?: ((msg: string) => void)|null}} input
+ * @returns {{status: number, body: object}}
+ */
+export function undoReply({ service, packId, dryRun, warn = null }) {
+  if (typeof service?.deleteSharePack !== "function") {
+    return { status: 503, body: { error: SHARE_IMPORT_UNAVAILABLE } };
+  }
+  const dry = dryRun !== false;
+  try {
+    return { status: 200, body: withDryRun(service.deleteSharePack(packId, { dryRun: dry }), dry) };
+  } catch (error) {
+    warnSafely(warn, `[dsh-mneme] share undo failed: ${String(error)}`);
+    return { status: 500, body: { error: "internal" } };
+  }
+}