dsh-prime-memory 0.22.1 → 0.24.0

package/dist/metadata-validators.js

@@ -10,6 +10,7 @@
  * 历史上 Wing 侧零校验,非法值先入库、再由下游剥离,形成无谓的写入-剥离循环。
  */
 import { WING_CATALOG, WING_FALLBACK } from './types.js';
+import { isCognitiveHall, COG_HALL_METADATA_KEY } from './cognitive-hall.js';
 /** Wing 词表(8 域 + general 兜底):与 relabel 机械校验、提示词候选集同源。 */
 const WING_ID_SET = new Set([
     ...WING_CATALOG.map((w) => w.id),
@@ -66,3 +67,47 @@ export function normTags(v, max = 3) {
     return out;
 }
 export { isCognitiveHall, COGNITIVE_HALLS } from './cognitive-hall.js';
+/** usageScenario 单条最大长度(“何时该浮现”的短语，非 slug，故不校 isTag 字符集)。 */
+const USAGE_SCENARIO_MAX_CHARS = 60;
+/**
+ * usageScenario 归一 + 去重 + 上限。**所有写回点必须过这里**。
+ *
+ * 与 normTags 的区别：usageScenario 是自然语言短语（如“修改 profile 配置时”），
+ * 不是 slug，所以不做字符集校验，只做 trim/去重/长度钳制/上限。
+ * 非数组或空→ `[]`（缺字段中性，不抛——防单条抽取失败波及整切片重试）。
+ */
+export function normUsageScenario(v, max = 3) {
+    if (!Array.isArray(v) || max <= 0)
+        return [];
+    const out = [];
+    for (const raw of v) {
+        if (typeof raw !== 'string')
+            continue;
+        const t = raw.trim();
+        if (!t || out.includes(t))
+            continue;
+        out.push(t.slice(0, USAGE_SCENARIO_MAX_CHARS));
+        if (out.length >= max)
+            break;
+    }
+    return out;
+}
+/**
+ * 读 **Wing（生活域）**。⚠️ 磁盘键是 `metadata.hall`——历史别名，存的其实是 **wing 值**。
+ * 只认词表内的合法 wing（8 角 + general），否则 undefined。
+ *
+ * 用它取代裸读 `metadata.hall`：从入口上把“wing 轴”与“认知 hall 轴”分开，
+ * 防止把认知 hall 值（facts/events/…）误当 wing 读——两轴不串。
+ */
+export function readWing(metadata) {
+    const v = metadata?.hall;
+    return typeof v === 'string' && isWingId(v) ? v : undefined;
+}
+/**
+ * 读 **认知 hall（大类）**。磁盘键 `metadata.cogHall`，与 wing 的磁盘键 `hall` 正交。
+ * 只认五个枚举值，否则 undefined（wing 值不当认知 hall 读）。
+ */
+export function readCognitiveHall(metadata) {
+    const v = metadata?.[COG_HALL_METADATA_KEY];
+    return isCognitiveHall(v) ? v : undefined;
+}

package/dist/pipeline/l1.d.ts

@@ -2,7 +2,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { MemoryConfig } from '../config.js';
 import type { L1Store } from '../store/l1.js';
 import type { MemoryState } from '../store/state.js';
-import type { ConversationAnchor, ConversationMessage, ExtractMode, MemoryFamily, MemoryLogger, MemoryRecord } from '../types.js';
+import type { ConversationAnchor, ConversationMessage, ExtractedMemory, ExtractMode, MemoryFamily, MemoryLogger, MemoryRecord, MemoryScope } from '../types.js';
 export interface ExtractionResult {
     stored: number;
     skipped: boolean;
@@ -15,6 +15,42 @@ export interface ExtractionResult {
 }
 /** 分族 checkpoint 桶(活引用,改动由调用方 save 落盘)。 */
 export type FamilyStates = Record<MemoryFamily, MemoryState>;
+/** 抽取产出 + 管线补上的五个字段(与 Step 1 的 `extracted` 元素同形)。 */
+export type PendingMemory = ExtractedMemory & {
+    record_id: string;
+    scene_name: string;
+    family: MemoryFamily;
+    /** §E 归属:write 侧已按 `resolveRecordScope` 算好,`toStoreRecord` 原样带出 */
+    scope: MemoryScope;
+    workspaceId: string;
+    /** 治理归属(ADR-0015 T1.9/T1.10):进管线时一次算定(I-21),写时随 store 行落盘。 */
+    repoKeyName: string;
+    repoKeyOwner: string;
+    applicability: string;
+};
+/**
+ * 合并时的检索轴并集（P0-c）。
+ *
+ * 此前合并产物只带新记忆的 metadata，targets 的 tags/hall/cogHall/使用场景全丢——
+ * 一次合并就把这条记忆从它原来的 Room/Wing 里摘出去，而面板上看不出任何异常（F2）。
+ * 这里只并**检索轴**：派生评价（maturity/usage/rating）与内容层字段不在其列。
+ *
+ * 单值轴（hall/cogHall）两侧互斥时**保留新记忆侧并留痕**，不拼成 `"a,b"`——那会
+ * 造出一个不存在的域（与 `isWingId` 的值域约束相冲）。
+ *
+ * @param self - 新记忆自己的 metadata（可为 undefined）。
+ * @param targets - 被合并掉的旧记录们的 metadata。
+ * @returns 并集后的 metadata 与若干条“丢了什么”的留痕文案。
+ */
+export declare function mergeAxes(self: Record<string, unknown> | undefined, targets: ReadonlyArray<Record<string, unknown> | undefined>): {
+    metadata: Record<string, unknown>;
+    notes: string[];
+};
+/**
+ * 导出仅供用例：`title → name` 这一跳是本计划的风隙（模型给的名字能不能落成合法身份名），
+ * 而驱动整条 LLM 管线会把断言埋进抽取/去重两段的噪声里。与 `mergeAxes` 同一先例。
+ */
+export declare function toStoreRecord(m: PendingMemory, now: number, ts: number, anchorMap?: ReadonlyMap<string, ConversationAnchor>): MemoryRecord;
 /**
  * 按字符预算把消息切成多块(保持顺序,单条超预算独占一块,由 callLLM 兜底截断)。
  * 每条消息按 content 长度 + 64 字符脚手架开销(id/时间戳行)计。
@@ -32,4 +68,10 @@ workspaceId?: string,
  * **缺省时行为与改动前逐字一致**——传入的 `pending` 消息若不带锚点(老数据、
  * 未启用捕获侧打戳),`resolveSourceAnchors` 一律返回 undefined,不写 metadata 键。
  */
-anchorMap?: ReadonlyMap<string, ConversationAnchor>): Promise<ExtractionResult>;
+anchorMap?: ReadonlyMap<string, ConversationAnchor>, 
+/**
+ * 合并后的**派生数据搬运钩子**（P0-d）：旧 id → 新 id。使用史与人工标注存在
+ * 另两个 sidecar 里，而 merge 每次新铸 id——不搬就等于每次合并把这条记忆的
+ * `used`/人工打分清零，它会被当成“没用过”而沉底。缺省不搬（行为与改动前一致）。
+ */
+mergeRekey?: (oldId: string, newId: string) => void): Promise<ExtractionResult>;

package/dist/pipeline/l1.js

@@ -12,10 +12,13 @@ import { callLLM, parseJsonLogged, resolveLayerTokens } from '../llm.js';
 import { buildReceipts, newRunId, persistReceiptsSafely } from '../store/receipts.js';
 import { buildConflictPair, conflictRejectId, DEFER_MAX, normalizeClaimKey, normalizeConflictType, occupiesConflictQuota, pendingHardTotal, validateConflictPair, } from '../store/conflicts.js';
 import { formatExtractionPrompt, getExtractMemoriesSystemPrompt } from '../prompts/l1-extraction.js';
+import { normTags, normUsageScenario, readCognitiveHall, readWing } from '../metadata-validators.js';
+import { acceptTitle } from '../util/md-name.js';
 import { formatBatchConflictPrompt, getConflictDetectionSystemPrompt } from '../prompts/l1-dedup.js';
 import { resolveSourceAnchors, withSourceAnchors } from './anchors.js';
 import { familyForType, normPersistence, normScope, resolveRecordFamily, resolveRecordScope, WING_FALLBACK } from '../types.js';
 import { normApplicability, resolveRepoScope } from '../repo-scope.js';
+import { routeWorkspace } from '../workspace-route.js';
 /** 解析 ISO/epoch 时间证据,非法或非正值一律 undefined——不猜测。 */
 function parseTimeEvidence(raw) {
     const t = typeof raw === 'string' ? Date.parse(raw) : typeof raw === 'number' ? raw : Number.NaN;
@@ -58,7 +61,97 @@ function mergeTemporal(self, targets) {
  * 第 4 个参数是 R7 的锚点映射(`L0 消息 id → 会话坐标`)。**传 undefined 时
  * 行为与改动前逐字一致**——老调用方与没有锚点的会话走这条分支。
  */
-function toStoreRecord(m, now, ts, anchorMap) {
+/**
+ * 把抽取侧的 `metadata.usageScenario` 归一到命名空间保留键 `dsh_usage_scenario`
+ *（与 dsh_source_anchors 同范式）。**无该键时原样返回**——功能关时 LLM 不产出该键，
+ * 记录 metadata 与改动前逐字一致（零漂移）。只随新蒸馏写，不回填存量。
+ */
+function withUsageScenario(meta) {
+    if (!meta || !('usageScenario' in meta))
+        return meta;
+    const out = { ...meta };
+    out.dsh_usage_scenario = normUsageScenario(out.usageScenario);
+    delete out.usageScenario;
+    return out;
+}
+/** 把“可能是数组的 metadata 值”读成字符串数组（不是数组就当空，不猜）。 */
+function asStrings(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === 'string' && x.length > 0) : [];
+}
+/**
+ * 合并时的检索轴并集（P0-c）。
+ *
+ * 此前合并产物只带新记忆的 metadata，targets 的 tags/hall/cogHall/使用场景全丢——
+ * 一次合并就把这条记忆从它原来的 Room/Wing 里摘出去，而面板上看不出任何异常（F2）。
+ * 这里只并**检索轴**：派生评价（maturity/usage/rating）与内容层字段不在其列。
+ *
+ * 单值轴（hall/cogHall）两侧互斥时**保留新记忆侧并留痕**，不拼成 `"a,b"`——那会
+ * 造出一个不存在的域（与 `isWingId` 的值域约束相冲）。
+ *
+ * @param self - 新记忆自己的 metadata（可为 undefined）。
+ * @param targets - 被合并掉的旧记录们的 metadata。
+ * @returns 并集后的 metadata 与若干条“丢了什么”的留痕文案。
+ */
+export function mergeAxes(self, targets) {
+    const out = { ...(self ?? {}) };
+    const notes = [];
+    const list = targets.filter((m) => m !== undefined);
+    // tags 是 Room 的构成单元（自生长分类）：并集去重后**仍过 normTags**，
+    // 长度与字符纪律不因合并而放宽。
+    const tags = normTags([...asStrings(out.tags), ...list.flatMap((m) => asStrings(m.tags))], 6);
+    if (tags.length > 0)
+        out.tags = tags;
+    // 使用场景：同样并集，但维持≤ 3 的既有上限（多了会灌 prompt）。
+    const sc = normUsageScenario([...asStrings(out.dsh_usage_scenario), ...list.flatMap((m) => asStrings(m.dsh_usage_scenario))]);
+    if (sc.length > 0)
+        out.dsh_usage_scenario = sc;
+    // Room 待评审状态要跟着走，否则合并把“待评审”洗成“未标注”、下轮反刍重新入队。
+    const cands = normTags([...asStrings(out.roomCandidates), ...list.flatMap((m) => asStrings(m.roomCandidates))], 6);
+    if (cands.length > 0)
+        out.roomCandidates = cands;
+    if (out.roomReview === undefined) {
+        const review = list.find((m) => typeof m.roomReview === 'string' && m.roomReview.length > 0)?.roomReview;
+        if (review !== undefined)
+            out.roomReview = review;
+    }
+    // 单值轴：新记忆已打标则不抢；没打标且目标侧只一个结论才继承，互斥则留痕不猜。
+    const wingMine = readWing(out);
+    if (wingMine === undefined) {
+        const theirs = [...new Set(list.map((m) => readWing(m)).filter((v) => v !== undefined))];
+        if (theirs.length === 1)
+            out.hall = theirs[0];
+        else if (theirs.length > 1)
+            notes.push(`hall 目标侧互斥(${theirs.join('|')})，不猜`);
+    }
+    else {
+        const theirs = new Set(list.map((m) => readWing(m)).filter((v) => v !== undefined));
+        theirs.delete(wingMine);
+        if (theirs.size > 0)
+            notes.push(`hall 保留新记忆侧 ${wingMine}，目标侧 ${[...theirs].join('|')} 被舍`);
+    }
+    const cogMine = readCognitiveHall(out);
+    if (cogMine === undefined) {
+        // 认知 hall 的值是固定枚举（不是 string），故用 Set 收集而不是 `v is string` 谓词。
+        const seen = new Set();
+        for (const m of list) {
+            const v = readCognitiveHall(m);
+            if (v !== undefined)
+                seen.add(v);
+        }
+        if (seen.size === 1)
+            out.cogHall = [...seen][0];
+    }
+    return { metadata: out, notes };
+}
+/**
+ * 导出仅供用例：`title → name` 这一跳是本计划的风隙（模型给的名字能不能落成合法身份名），
+ * 而驱动整条 LLM 管线会把断言埋进抽取/去重两段的噪声里。与 `mergeAxes` 同一先例。
+ */
+export function toStoreRecord(m, now, ts, anchorMap) {
+    // 名称蒸馏（Phase 3）：模型当场给的 title 只是**名字候选**，必须过同一个形状闸；
+    // 过不了就**不写键**，交给 `L1Store.assignMissingNames`——判据只留一份，
+    // 不在这里养第二套“看起来差不多”的名字清洗。
+    const titled = m.title === undefined ? undefined : acceptTitle(m.title);
     return {
         id: m.record_id,
         content: m.content,
@@ -72,7 +165,7 @@ function toStoreRecord(m, now, ts, anchorMap) {
         source_message_ids: m.source_message_ids ?? [],
         // R7:锚点与 source_message_ids 同源解析;解析不到就**不写键**(不是空数组),
         // 使无锚点记录与改动前的 metadata 逐字一致。
-        metadata: withSourceAnchors(m.metadata, anchorMap === undefined ? undefined : resolveSourceAnchors(m.source_message_ids, anchorMap)),
+        metadata: withSourceAnchors(withUsageScenario(m.metadata), anchorMap === undefined ? undefined : resolveSourceAnchors(m.source_message_ids, anchorMap)),
         family: m.family,
         scope: m.scope,
         workspaceId: m.workspaceId,
@@ -82,6 +175,10 @@ function toStoreRecord(m, now, ts, anchorMap) {
         ...(m.repoKeyName ? { repoKeyName: m.repoKeyName } : {}),
         ...(m.repoKeyOwner ? { repoKeyOwner: m.repoKeyOwner } : {}),
         ...(m.applicability ? { applicability: m.applicability } : {}),
+        ...(titled === undefined ? {} : { name: titled }),
+        // 文件身份键不在这里分：**起名只有一个真源**（`L1Store.assignMissingNames`）。
+        // 以前这里自己分一份、库里再分一份，两套判据迟早漂移，而漂移的后果是同一个基底
+        // 洗出两个名字（文件跳名）或两个记录抢一个名字（整条写不进去）。
         ...temporalOf(m.metadata),
     };
 }
@@ -124,7 +221,13 @@ workspaceId,
  * **缺省时行为与改动前逐字一致**——传入的 `pending` 消息若不带锚点(老数据、
  * 未启用捕获侧打戳),`resolveSourceAnchors` 一律返回 undefined,不写 metadata 键。
  */
-anchorMap) {
+anchorMap, 
+/**
+ * 合并后的**派生数据搬运钩子**（P0-d）：旧 id → 新 id。使用史与人工标注存在
+ * 另两个 sidecar 里，而 merge 每次新铸 id——不搬就等于每次合并把这条记忆的
+ * `used`/人工打分清零，它会被当成“没用过”而沉底。缺省不搬（行为与改动前一致）。
+ */
+mergeRekey) {
     if (!cfg.extract.enabled)
         return { stored: 0, skipped: true, sceneName: chainHead(states, mode), newRecords: [] };
     // 触发阈值(渐进爬坡 + 按会话切片计数)由 runner 判定(trigger.ts);
@@ -195,7 +298,14 @@ anchorMap) {
             halls,
         });
         const raw = await callLLM(ctx, cfg, {
-            system: getExtractMemoriesSystemPrompt(mode),
+            system: getExtractMemoriesSystemPrompt(mode, {
+                usageScenario: cfg.usageScenario?.enabled === true,
+                narrative: cfg.narrativeTemplates?.enabled === true,
+                // 名称蒸馏（Phase 3）：示例段只在总开关开着时付（它与 title 是两层成本，
+                // 分开开关才能 A/B）。关着时这份 opts 产出的提示与改动前逐字相同。
+                title: cfg.naming?.enabled === true,
+                fewShot: cfg.naming?.enabled === true && cfg.naming.fewShot === true,
+            }),
             user: userPrompt,
             maxTokens: resolveLayerTokens(cfg, 'extract'),
             layer: 'l1-extract',
@@ -213,14 +323,29 @@ anchorMap) {
                 if (!m || typeof m.content !== 'string' || !m.content.trim())
                     continue;
                 const family = resolveRecordFamily(forcedFamily, m.family, m.type ?? '');
+                // 内容路由（`cfg.workspaceSource`，默认开）：按内容谈到哪个项目定归属。
+                // 不走「来源会话反查」：session_id 恒为 default、锚点仅 7.3% 能定位到会话树，
+                // 而内容自己说它属于哪个项目——不受这些缺失影响。见 `src/workspace-route.ts`。
+                const routed = cfg.workspaceSource?.enabled === true
+                    ? routeWorkspace(`${m.content}\n${scene.scene_name}`, cfg.workspaceSource.routes)
+                    : undefined;
                 extracted.push({
                     ...m,
+                    // 开关关着时**不把 title 带进管线**：旧记录形状逐字不变（不新增键、不参与任何判据）。
+                    ...(cfg.naming?.enabled === true && m.title !== undefined && m.title !== null
+                        ? { title: m.title }
+                        : {}),
                     record_id: newId('mem'),
                     scene_name: scene.scene_name,
                     family,
                     // §E 归属在**进管线时**一次算定,下游(store / conflict / update / merge 各分支)
                     // 一律复用它——四个分支各算一次是漏判的温床。
                     ...resolveRecordScope(scopeMode, family, workspaceId),
+                    // 路由值只覆盖 `workspaceId`、**不动 `scope`**：`resolveRecordScope` 规则③ 在
+                    // cfg.scope='global' 时故意把归属清成 ''(零漂移保证)，这里在其后补一个事实列。
+                    // 可见性判据 `isScopeVisible` 先看 scope，global 即全可见 → 今天一行行为不变；
+                    // 将来启用 workspace 围栏时这列已经是现成的正确依据。
+                    ...(routed === undefined ? {} : { workspaceId: routed }),
                     // 治理归属(ADR-0015 T1.9/T1.10):repoKey 一次算定;applicability 由抽取
                     // prompt 显式产出、经归一收窄——**绝不从 family 推导**(P0-7 四象限),
                     // 未声明/非法 = ''(不围栏)。
@@ -246,7 +371,7 @@ anchorMap) {
         conflictFreeze: cfg.conflictFreeze.enabled,
     });
     const dedupRaw = await callLLM(ctx, cfg, {
-        system: getConflictDetectionSystemPrompt(mode, { conflictFreeze: cfg.conflictFreeze.enabled }),
+        system: getConflictDetectionSystemPrompt(mode, { conflictFreeze: cfg.conflictFreeze.enabled, title: cfg.naming?.enabled === true }),
         user: dedupPrompt,
         maxTokens: resolveLayerTokens(cfg, 'dedup'),
         layer: 'l1-dedup',
@@ -446,11 +571,39 @@ anchorMap) {
             .map((t) => Date.parse(t))
             .filter((t) => !Number.isNaN(t))
             .concat([now]);
+        const targetRecords = targets
+            .map((id) => byId.get(id))
+            .filter((r) => r !== undefined);
+        const mergedContent = decision.merged_content && decision.merged_content.trim()
+            ? decision.merged_content
+            : m.content;
+        // 合并产物的身份与检索轴必须从 targets 继承（P0-c）。此前这里只带新记忆的
+        // metadata：`ext_key` 被写成空 ⇒ 幂等保护随合并消失（而它是“文件↔库”的唯一锚）；
+        // `name` 同理 ⇒ 文件身份随合并漂移；tags/hall/使用场景全丢 ⇒ 一次合并就把这条
+        // 记忆从它原来的 Room/Wing 摘出去，且全程无日志（F2）。
+        const inheritedName = targetRecords.find((r) => typeof r.name === 'string' && r.name.length > 0)?.name;
+        const inheritedExtKey = targetRecords.find((r) => typeof r.extKey === 'string' && r.extKey.length > 0)?.extKey;
+        const axes = mergeAxes(m.metadata, targetRecords.map((r) => r.metadata));
+        // 名字优先继承（保持文件身份连续）；没得继承就留空，由写库前的起名器按**合并后的正文**分。
+        // 继承来的名字如果已被库里另一条占着（典型：本轮正要退场的那条旧记录），
+        // `assignMissingNames` 会把它重命到一个带后缀的变体——不能直接写，写了就是撞唯一索引、
+        // 整条合并产物丢进不了检索库。
+        const mergedName = inheritedName;
+        // 丢东西必须说话：静默合并是这一整期要结的账。
+        for (const note of axes.notes) {
+            logger.info(`[memory] merge 轴冲突(${m.record_id} ← ${targets.join(',')}): ${note}`);
+        }
+        logger.info(`[memory] merge 传播身份(${m.record_id} ← ${targets.length} 条): `
+            + `name=${mergedName ?? '(本轮没继承到，由起名器分配)'} extKey=${inheritedExtKey ?? '(无)'} `
+            + `tags=${Array.isArray(axes.metadata.tags) ? axes.metadata.tags.length : 0}`);
+        // 名字优先级：继承旧身份（保持文件连续）> 模型当场给的 merged_title > 交给起名器。
+        // 顺序反了会让每次合并都把新语义挂在旧名字上，而旧名字描述的正是被合并掉的那批内容。
+        const mergedTitle = mergedName === undefined || mergedName.length === 0
+            ? acceptTitle(decision.merged_title)
+            : mergedName;
         added.push({
             id: m.record_id,
-            content: decision.merged_content && decision.merged_content.trim()
-                ? decision.merged_content
-                : m.content,
+            content: mergedContent,
             type: decision.merged_type || m.type,
             priority: Number(decision.merged_priority) || Number(m.priority) || 60,
             scene_name: m.scene_name,
@@ -462,8 +615,19 @@ anchorMap) {
             // R7:合并/更新产出的记录同样带锚点——否则"合并一次就丢坐标",
             // 而合并恰恰是长会话里最常发生的动作。无映射时传空表 →
             // resolveSourceAnchors 返回 undefined → 不写 metadata 键(零漂移)。
-            metadata: withSourceAnchors(m.metadata, resolveSourceAnchors(m.source_message_ids, anchorMap ?? new Map())),
+            metadata: withSourceAnchors(axes.metadata, resolveSourceAnchors(m.source_message_ids, anchorMap ?? new Map())),
             family: m.family,
+            // 身份两键：从 targets 继承（没得继承且开关开着才现分）。
+            ...(inheritedExtKey === undefined ? {} : { extKey: inheritedExtKey }),
+            ...(mergedTitle === undefined || mergedTitle.length === 0 ? {} : { name: mergedTitle }),
+            // 归属五字段必须带上：这里此前**一个都没写**，等于每次合并都把 scope/
+            // workspaceId/repoKey/applicability 打回默认——cfg.scope='global' 时看不出来，
+            // 一旦启用围栏，一条记忆归过哪个项目就在合并后静默丢了。
+            scope: m.scope,
+            workspaceId: m.workspaceId,
+            repoKeyName: m.repoKeyName,
+            repoKeyOwner: m.repoKeyOwner,
+            applicability: m.applicability,
             // 合并的有效期取并集:起 = 两侧最早;止 = 任一侧未闭合则仍未闭合(undefined)。
             ...mergeTemporal(temporalOf(m.metadata), targets.map((id) => byId.get(id)).filter((r) => r !== undefined)),
         });
@@ -482,6 +646,10 @@ anchorMap) {
         }
         for (const [newId, ids] of byNewRecord) {
             store.retire(ids, { at: retiredAt, reason: 'superseded', by: newId });
+            // 旧行退场后它的派生数据不能留在死 id 上：按“每个被合并者 → 新行”搬一次。
+            if (mergeRekey !== undefined)
+                for (const oldId of ids)
+                    mergeRekey(oldId, newId);
         }
     }
     // §C 自动裁决的执行面:LLM 的 loser 从检索面退场(winner 存活),同为**软删**。

package/dist/pipeline/md-sync.d.ts

@@ -0,0 +1,65 @@
+/**
+ * P2 反向同步：md 投射文件 → 索引（文件是人编辑的那一侧）。
+ *
+ * 与导出侧（`memory-md-export.ts`）共用同一份落点计算（`targetFor`）、同一个库侧指纹
+ * 算法（`recordDigest`）和同一本账本，所以两侧看到的世界一致；写文件这条路**直接复用**
+ * `exportRecords`（传单条记录），不另写一套落盘逻辑——两套写盘迟早漂移。
+ *
+ * 判定一律走**三方**：账本里存着上次投射时的库侧指纹与文件侧指纹，"谁变了"才是可判定的。
+ * 四象限（spec P2 裁决表）：
+ * - 只有文件变 → 回灌入库，然后把文件重写成规范渲染（正文仍是人写的那段，frontmatter 归一）。
+ *   这一步同时消掉写回环：库和文件都回到账本记着的那个状态，下一轮判 `same`。
+ * - 只有库变 → 重写文件。
+ * - **两边都变 → 什么都不做**，只在报告里挂账。人不裁决机器不许动；两侧保持原样、账本也不动，
+ *   所以下次对账还会报同样的 `both`（挂账是持久的，不会悄悄过期）。
+ * - 都没变 → 跳过，不刷 mtime。
+ *
+ * 另有一条独立通道：`.memory.md.disable` 后缀 = 人在文件侧手工判过时 → 退场对应记录
+ * （写 valid_to，不进任何检索通路）。这是 `recall-feedback -1` 的文件侧对偶。
+ *
+ * 两条边界：
+ * - 没有账本、也认不出记录的文件 = 人新建的，**不入库**。导入一条新记忆必须过写入内核
+ *   的判据面（归一/长度/预算/去重），在这里手搓一条等于绕过那些不变量。只计数。
+ * - 遍历范围 = 从记录算出的落点根 ∪ 账本里记过的根。所以"没有任何记录指向的全新 workspace"
+ *   不在本轮范围内——它还没有投射根，等它的第一条记忆落进去才可见。
+ *
+ * 另有一条遍历防护（P2 缺口 task_3.7）：投射根下的"链接"在 win32 上不止 symlink 一种形状，
+ * junction（目录联接，reparse point）也算，而 `Dirent.isSymbolicLink()` 对它的判定随 Node 版本
+ * 与文件系统漂移。所以进任何子目录前再加一道 `realpath` 判据：解析出的真实路径必须仍在该投射根
+ * 内，界外的一律不进并计入 `skippedLinks`。⚠️ 这个 realpath **只服务划界**——不参与账本键，也不
+ * 参与落点计算（那边刻意不做 realpath，理由见 `store/memory-md.ts::targetFor` 的注释）。两处不一致
+ * 是有意的，不是 bug。
+ */
+import type { MdLedgerStore } from '../store/memory-md-ledger.js';
+import type { MdSyncReport } from '../store/memory-md-types.js';
+import type { L1Store } from '../store/l1.js';
+import type { MemoryLogger } from '../types.js';
+export interface MdSyncDeps {
+    store: L1Store;
+    ledger: MdLedgerStore;
+    /** `cfg.memExport.root`（空 = 默认单根）；与导出侧同一个值。 */
+    cfgRoot: string | undefined;
+    dataDir: string;
+    maxFiles: number;
+    timeBudgetMs: number;
+    logger?: MemoryLogger;
+    /** 注入时钟（测试用）。 */
+    now?: () => number;
+}
+/**
+ * 越界判据：`resolved` 必须就是根，或者是根的子目录。
+ *
+ * 前缀比较带 `sep`：少了那个分隔符，兄弟目录 `<root>2` 会被判成界内（经典越界陷阱）。
+ * 两侧都出自 `realpath`，同一卷上大小写与 8.3 短名都已归一，所以这里做**严格字符串**比较；
+ * win32 上再折叠大小写只会放松判据（把真越界说成合法），不做。
+ * 导出只为把判据本身钉成用例：造不出链接的机器上，判据仍要有测试可跑。
+ */
+export declare function isWithinRoot(rootReal: string, resolved: string): boolean;
+/**
+ * 反向同步一轮。
+ *
+ * @param deps - 见 `MdSyncDeps`。
+ * @returns 同步报告（含挂账样本、剩余量、以及遍历防护拦下的条目数 `skippedLinks`）。
+ *   任何单条失败只计数并留痕，绝不抛挂整轮。
+ */
+export declare function syncFromFiles(deps: MdSyncDeps): Promise<MdSyncReport>;