dsh-prime-memory 0.26.5 → 0.26.9

package/dist/store/local-embedding.d.ts

@@ -2,7 +2,7 @@ import type { MemoryLogger } from '../types.js';
 import type { CatalogEntry } from './model-catalog.js';
 import type { EmbedCallOptions, EmbeddingProviderInfo, EmbeddingService } from './embedding.js';
 type LocalState = 'idle' | 'loading' | 'ready' | 'failed' | 'terminated';
-/** worker 启动参数(workerData;构造后不可变)。 */
+/** 推理侧启动参数(worker 经 workerData / 子进程经 env DSH_EMBED_CFG;构造后不可变)。 */
 export interface EmbedWorkerData {
     runtimeDir: string;
     modelDir: string;
@@ -49,11 +49,15 @@ export interface EmbedWorkerChannel {
     setOnCrash(cb: (error: string) => void): void;
 }
 export interface LocalEmbeddingOptions {
-    /** 数据目录 runtime/(worker 据此 createRequire 加载 transformers)。 */
+    /** 数据目录 runtime/(推理侧据此 createRequire 加载 transformers)。 */
     runtimeDir: string;
-    /** worker 资产路径(默认 dist/embedding-worker.cjs;测试可显式指定)。 */
+    /** 子进程资产路径(默认 dist/embedding-child.cjs;测试可显式指定)。 */
+    childPath?: string;
+    /** 旧 worker 资产路径(仅 useWorker=true 时生效;默认 dist/embedding-worker.cjs)。 */
     workerPath?: string;
-    /** 通道注入缝(测试用;缺省 spawn 真实 worker)。 */
+    /** 回滚逃生门:true 切回 worker_threads 通道(fix #11 前的旧路径)。 */
+    useWorker?: boolean;
+    /** 通道注入缝(测试用;缺省起真实子进程通道)。 */
     channel?: EmbedWorkerChannel;
     logger?: MemoryLogger;
     maxInputChars?: number;
@@ -77,7 +81,7 @@ export declare class LocalEmbeddingService implements EmbeddingService {
     waitForReady(): Promise<void>;
     embed(text: string, callOpts?: EmbedCallOptions): Promise<Float32Array>;
     embedBatch(texts: string[], callOpts?: EmbedCallOptions): Promise<Float32Array[]>;
-    /** 释放 worker 线程与模型(嵌入源切走/关闭时调用;幂等)。terminated 后不可
+    /** 释放推理子进程与模型(嵌入源切走/关闭时调用;幂等)。terminated 后不可
      *  再复用——防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻(内存泄漏)。 */
     close(): void;
     /** 内层钳制(仅缩短):超时放弃等待(迟到回复由通道按 id 丢弃),调用方降级。 */

package/dist/store/local-embedding.js

@@ -1,25 +1,35 @@
 /**
- * 本地嵌入服务(worker 线程化版):transformers.js 的模型加载与 ONNX 推理全部在
- * worker_threads 子线程执行(resources/embedding-worker.cjs),本类只是主线程侧的
- * 协议代理——onnxruntime-node 的 run/loadModel 是主线程同步调用,留在宿主事件循环
- * 会冻结整个 dsh 页面(0.8.6 修复的真实事故)。
+ * 本地嵌入服务(子进程隔离版,fix #11):transformers.js 的模型加载与 ONNX 推理
+ * 全部在 fork 出的独立子进程执行(resources/embedding-child.cjs),本类只是主线程侧
+ * 的协议代理——双重隔离:① onnxruntime-node 的 run/loadModel 是同步调用,留在宿主
+ * 事件循环会冻结整个 dsh 页面(0.8.6 修复的真实事故);② 插件 runtime 的 sharp/libvips
+ * 与宿主 Electron 的 sharp/libvips 同进程加载会撞 libvips-42.dll 名字(OS LoadLibrary
+ * 层冲突)——worker_thread 与主线程同进程,撞名前提仍在(issue #11);子进程自带独立
+ * DLL 表,冲突物理消失。
  *
- * - 懒加载:首次嵌入/warmup 才让 worker 加载模型,close()=terminate 释放线程与
+ * - 懒加载:首次嵌入/warmup 才让子进程加载模型,close()=kill 释放进程与
  *   模型(嵌入源切走/关闭时调用),terminated 后不可复用;
- * - 模型从数据目录 models/<id>/ 本地加载(worker 侧 env.allowRemoteModels=false);
+ * - 模型从数据目录 models/<id>/ 本地加载(子进程侧 env.allowRemoteModels=false);
  * - channel 可注入(测试缝):用假通道验证协议与状态机,不触真模型;
- * - callOpts.timeoutMs 经 Promise.race 钳制(迟到回复按 id 丢弃——推理在
- *   worker 线程无法真正取消,但主线程可以停止等待并降级 FTS);
+ * - useWorker=true 切回旧 worker_threads 通道(回滚逃生门;若宿主侧 DLL 冲突
+ *   将来被根治,可一行切回获得 transfer 零拷贝的微弱性能优势);
+ * - callOpts.timeoutMs 经 Promise.race 钉制(迟到回复按 id 丢弃——推理在
+ *   子进程无法真正取消,但主线程可以停止等待并降级 FTS);
  * - 池化方式来自模型目录(BGE 系 CLS / Gemma 系 MEAN),normalize 交给
  *   pipeline 内建 L2 归一(与远程路径的 sanitizeAndNormalize 语义一致)。
  */
+import { fork, spawn } from 'node:child_process';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { Worker } from 'node:worker_threads';
-/** 默认 worker 资产路径:dist/store/ → dist/embedding-worker.cjs(构建期拷入)。 */
+/** 默认 worker 资产路径(旧通道,useWorker 逃生门):dist/store/ → dist/embedding-worker.cjs(构建期拷入)。 */
 function defaultWorkerPath() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'embedding-worker.cjs');
 }
+/** 默认子进程资产路径(fix #11 主通道):dist/store/ → dist/embedding-child.cjs(构建期拷入)。 */
+function defaultChildPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'embedding-child.cjs');
+}
 /** 真实通道:spawn worker_threads + 自增 id 配对 + 崩溃兜底拒绝。 */
 class RealWorkerChannel {
     worker;
@@ -86,6 +96,113 @@ class RealWorkerChannel {
         }
     }
 }
+/**
+ * 真实子进程通道(fix #11 默认):fork 独立进程隔离 sharp/libvips DLL 冲突。
+ * 与 RealWorkerChannel 同协议语义,差异仅在传输层:
+ * - 配置经 env DSH_EMBED_CFG(JSON 字符串,fork env 只收标量);
+ * - 向量经 number[][] 序列化回传(IPC JSON 通道不支持 TypedArray;512d×32 条
+ *   ≈64KB,<5ms,不构成瓶颈),主线程侧收到后重建 Float32Array;
+ * - 终止 Windows 走 taskkill /T /F(同 runtime-installer 模式,防只杀包装进程),
+ *   其余 SIGTERM + 3s 强杀钉底。
+ */
+class RealChildChannel {
+    child;
+    pending = new Map();
+    nextId = 1;
+    terminated = false;
+    crashed;
+    crashCb;
+    constructor(childPath, cfg) {
+        this.child = fork(childPath, [], {
+            // execPath 显式沿用当前二进制:宿主 Electron 自带 Node runtime,打包后 PATH 里没有 node
+            execPath: process.execPath,
+            env: { ...process.env, DSH_EMBED_CFG: JSON.stringify(cfg) },
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+        });
+        this.child.on('message', (msg) => {
+            if (msg && msg.type === 'fatal') {
+                this.failAll(`本地嵌入子进程致命错误: ${msg.error ?? '未知'}`);
+                return;
+            }
+            const id = msg.id;
+            if (typeof id !== 'number')
+                return;
+            const entry = this.pending.get(id);
+            if (!entry)
+                return; // 迟到回复(调用方已超时放弃)
+            this.pending.delete(id);
+            // 子进程侧 vectors 是 number[][](IPC JSON 序列化),本侧重建 Float32Array 保持协议类型不变
+            const reply = msg;
+            if (reply.ok && reply.type === 'embedded') {
+                reply.vectors = reply.vectors.map((v) => new Float32Array(v));
+            }
+            entry.resolve(reply);
+        });
+        // error(fork 启动失败等)与 exit(含 fatal 后自杀、OOM 被杀)都钉底拒绝
+        this.child.on('error', (err) => this.failAll(`本地嵌入子进程错误: ${err.message}`));
+        this.child.on('exit', (code) => {
+            if (!this.terminated)
+                this.failAll(`本地嵌入子进程退出(code=${code})`);
+        });
+    }
+    request(call) {
+        // 已释放/已崩溃的通道快速拒绝——send 到死进程是静默无回应,调用方会挂到超时
+        if (this.terminated)
+            return Promise.reject(new Error('嵌入子进程已释放'));
+        if (this.crashed)
+            return Promise.reject(new Error(this.crashed));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            // 递送失败(通道已关/子进程已死)走 send 回调拒绝,不留挂死的 pending
+            this.child.send({ ...call, id }, (err) => {
+                if (!err)
+                    return;
+                const entry = this.pending.get(id);
+                if (entry) {
+                    this.pending.delete(id);
+                    entry.reject(new Error(`嵌入子进程 IPC 发送失败: ${err.message}`));
+                }
+            });
+        });
+    }
+    terminate() {
+        if (this.terminated)
+            return;
+        this.terminated = true;
+        this.failAll('嵌入子进程已释放');
+        if (process.platform === 'win32' && this.child.pid !== undefined) {
+            // 同 runtime-installer 的 taskkill 模式:Windows 上 child.kill() 信号语义弱,
+            // /T 按进程树杀防孤儿;taskkill 自身启动失败回退裸 kill
+            const tk = spawn('taskkill', ['/pid', String(this.child.pid), '/T', '/F'], { windowsHide: true });
+            tk.on('error', () => this.child.kill());
+        }
+        else {
+            this.child.kill('SIGTERM');
+            // 钉底:子进程卡在同步 native 调用时收不到 SIGTERM → 3s 后强杀;自然退出则撤销定时器
+            const force = setTimeout(() => {
+                if (this.child.exitCode === null && this.child.signalCode === null)
+                    this.child.kill('SIGKILL');
+            }, 3000);
+            this.child.once('exit', () => clearTimeout(force));
+        }
+    }
+    setOnCrash(cb) {
+        this.crashCb = cb;
+        // 构造与回调注册之间发生的崩溃(fork 即失败等)不丢通知
+        if (this.crashed)
+            cb(this.crashed);
+    }
+    failAll(error) {
+        for (const [, entry] of this.pending)
+            entry.reject(new Error(error));
+        this.pending.clear();
+        if (!this.terminated && !this.crashed) {
+            this.crashed = error;
+            this.crashCb?.(error);
+        }
+    }
+}
 export class LocalEmbeddingService {
     state = 'idle';
     loadError = null;
@@ -96,15 +213,18 @@ export class LocalEmbeddingService {
         this.entry = entry;
         this.logger = opts.logger;
         const maxInputChars = opts.maxInputChars && opts.maxInputChars > 0 ? opts.maxInputChars : 5000;
+        const cfgObj = {
+            runtimeDir: opts.runtimeDir,
+            modelDir,
+            pooling: entry.pooling,
+            dtype: 'q8',
+            maxInputChars,
+        };
         this.channel =
             opts.channel ??
-                new RealWorkerChannel(opts.workerPath ?? defaultWorkerPath(), {
-                    runtimeDir: opts.runtimeDir,
-                    modelDir,
-                    pooling: entry.pooling,
-                    dtype: 'q8',
-                    maxInputChars,
-                });
+                (opts.useWorker
+                    ? new RealWorkerChannel(opts.workerPath ?? defaultWorkerPath(), cfgObj)
+                    : new RealChildChannel(opts.childPath ?? defaultChildPath(), cfgObj));
         // 崩溃不自愈(换源/重启恢复):拒绝语义沿 EmbedHelper 降级链走 FTS
         this.channel.setOnCrash((error) => {
             if (this.state === 'terminated')
@@ -186,7 +306,7 @@ export class LocalEmbeddingService {
         }
         return reply.vectors;
     }
-    /** 释放 worker 线程与模型(嵌入源切走/关闭时调用;幂等)。terminated 后不可
+    /** 释放推理子进程与模型(嵌入源切走/关闭时调用;幂等)。terminated 后不可
      *  再复用——防止插件卸载/切走后残留的重嵌循环把模型重新加载常驻(内存泄漏)。 */
     close() {
         this.state = 'terminated';

package/dist/store/memory-md-disable.d.ts

@@ -12,8 +12,9 @@ export type DisableOutcome = 'renamed' | 'created' | 'already' | 'no-workspace'
 export { isRetiredRecord };
 export interface DisableDeps {
     /**
-     * 刚被退场的那条记录。调用方应传**退场后**的快照（带 `validTo`），这样渲染出的
-     * frontmatter 自然包含 `retired: true`——凭证自己就说清了它为什么存在。
+     * 刚被退场的那条记录。调用方应传**退场后**的快照（带 `dsh_superseded` 标记，
+     * 门1 解耦后 md 层按 marker 判退场），这样渲染出的 frontmatter 自然包含
+     * `retired: true`——凭证自己就说清了它为什么存在。
      */
     record: MemoryRecord;
     /** `cfg.memExport.root`（只管无 workspace 那批，这里用不到但落点函数要它）。 */

package/dist/store/memory-md.d.ts

@@ -63,14 +63,14 @@ export type MdRecordInput = Pick<MemoryRecord, 'id' | 'content' | 'type' | 'prio
  */
 export declare function targetFor(r: MdRecordInput, cfgRoot: string | undefined, dataDir: string, logger?: MemoryLogger): MdTarget;
 /**
- * 退场判据：与库侧同口径（`sqlite.ts` 的“`valid_to` 非空即退场”，与
- * `retiredL1Count`/`listRetiredL1` 一致）。
+ * 退场判据：与库侧同口径（门1 解耦后**只认 marker**，与 `supersede.isRetired`/
+ * `retiredL1Sql` 一致；valid_to 回归现实有效期，不再拿它判退场）。
  *
  * 为什么住在本文件：导出（要不要把文件放回非退场路径）与失效联动（后缀该不该带）
  * 两侧都得用同一个判据，否则“列表说它退了、文件却没后缀”会回来。放 `memory-md-disable.ts`
  * 会让 `memory-md-export.ts` 反向 import 它形成循环（那边已经 import 这边）。
  */
-export declare function isRetiredRecord(r: Pick<MemoryRecord, 'validTo'>): boolean;
+export declare function isRetiredRecord(r: Pick<MemoryRecord, 'metadata'>): boolean;
 /**
  * 投射文件的失效路径：`x.memory.md` → `x.memory.md.disable`。
  * 已带后缀的原样返回（幂等靠这个性质，而不是靠调用方记住判重）。

package/dist/store/memory-md.js

@@ -21,6 +21,7 @@ import { memoryTypeDirs, UNCLASSIFIED_DIR } from '../memory-types.js';
 import { deriveName } from '../util/md-name.js';
 import { normalizeContentMd } from '../util/md-normalize.js';
 import { sanitizeFilename } from './scenes.js';
+import { readSupersedeMarker } from './supersede.js';
 /**
  * 允许当目录名的 type 值（pm-name-distill task_1.3：由词表单一真源派生，不再手抄）。
  *
@@ -127,15 +128,15 @@ function warnMissingWorkspace(logger, ws) {
     logger.warn(`[memory] workspace 目录不存在，该条投射落点退回单根: ${ws}`);
 }
 /**
- * 退场判据：与库侧同口径（`sqlite.ts` 的“`valid_to` 非空即退场”，与
- * `retiredL1Count`/`listRetiredL1` 一致）。
+ * 退场判据：与库侧同口径（门1 解耦后**只认 marker**，与 `supersede.isRetired`/
+ * `retiredL1Sql` 一致；valid_to 回归现实有效期，不再拿它判退场）。
  *
  * 为什么住在本文件：导出（要不要把文件放回非退场路径）与失效联动（后缀该不该带）
  * 两侧都得用同一个判据，否则“列表说它退了、文件却没后缀”会回来。放 `memory-md-disable.ts`
  * 会让 `memory-md-export.ts` 反向 import 它形成循环（那边已经 import 这边）。
  */
 export function isRetiredRecord(r) {
-    return typeof r.validTo === 'number' && r.validTo > 0;
+    return readSupersedeMarker(r.metadata) !== undefined;
 }
 /**
  * 投射文件的失效路径：`x.memory.md` → `x.memory.md.disable`。
@@ -230,7 +231,8 @@ export function renderRecord(r) {
     // 「换了 id、正文没动」也误报被改。
     lines.push(fmLine('hash', contentHash(r.content)));
     // 退场标记只在真退场时写：不留 `retired: false` 这种噪声键（键集越稳，人越不容易改错）。
-    if (r.validTo !== undefined)
+    // 判据走本文件的 `isRetiredRecord`（门1 解耦后只认 marker，与库侧同口径）。
+    if (isRetiredRecord(r))
         lines.push(fmLine('retired', true));
     lines.push('---', '');
     // 正文过一道版式归一（P4.2）：无结构存量文本出口就是标准形状。归一是**幂等**的，

package/dist/store/route-health.d.ts

@@ -0,0 +1,38 @@
+/** 单条路由健康记录。 */
+export interface RouteHealthEntry {
+    /** 退避后实测跑通的最小块长(字符)；0 = 未学到。 */
+    lastGoodChunkChars: number;
+    /** 该路由延迟 EMA(ms)；0 = 未记。R5 自适应可据此调初值。 */
+    latencyEmaMs: number;
+    /** 最近一次记录时刻(ISO)。 */
+    updatedAt: string;
+}
+/** 学习值默认过期(ms)：超此龄视为陈旧、读侧应重探（换模型/网关不至于被历史最小值锁死）。 */
+export declare const ROUTE_HEALTH_STALE_MS: number;
+export declare function routeHealthPathFor(dataDir: string): string;
+export declare class RouteHealthStore {
+    private readonly file;
+    private routes;
+    private dirty;
+    constructor(file: string);
+    /** 读盘 fail-open：缺/坏/未知版本 → 空表、不抛。 */
+    load(): Promise<void>;
+    /** 该路由已学到、且未过期的跑通块长；0 = 无可用学习值（未学到或已陈旧）。 */
+    lastGoodChunkChars(provider: string, model: string, now?: number, staleMs?: number): number;
+    /** 该路由延迟 EMA(ms)；0 = 未记。 */
+    latencyEma(provider: string, model: string): number;
+    /**
+     * 记一次「跑通」的块长：只降不升（更小块长才覆盖 lastGood），并更新延迟 EMA。
+     * @param chunkChars 本次成功的块长(字符)
+     * @param latencyMs  本次成功调用耗时(可选，用于 EMA)
+     */
+    recordGood(provider: string, model: string, chunkChars: number, latencyMs?: number): void;
+    /** 清除学习值：传 provider+model 清单条，否则清全部（面板「重置学习值」一键）。 */
+    reset(provider?: string, model?: string): void;
+    /** 全量快照（面板回显用）。 */
+    snapshot(): Array<{
+        key: string;
+    } & RouteHealthEntry>;
+    /** 有变更才落盘；失败由调用方兜底（不抛穿蒸馏）。@returns 是否写了盘 */
+    save(): Promise<boolean>;
+}

package/dist/store/route-health.js

@@ -0,0 +1,115 @@
+/**
+ * 蒸馏路由健康学习(R9)：按 `provider/model` 记「自适应退避后实测跑通的最小块长」，
+ * 跨进程留存，令下次 perChunk 初值直接取跑通过的值、不必每进程重付退避风暴；
+ * 面板可回显「实测最小可用块长 / 最后退避长度」。
+ *
+ * 运行时学习值、非磁盘契约：
+ * - 读 **fail-open**（缺文件/损坏/未知版本 → 空表起步，绝不抛、不阻蒸馏——学习值丢了最多少一次优化）；
+ * - 写走 `atomicWriteJson`（原子 + 覆盖保护）；
+ * - **只降不升**：更小的跑通块长才覆盖 lastGood（换 provider/过期由读侧决定重探，见 R5 接线）。
+ *
+ * 本模块 Phase 1 仅落地存储与纯逻辑，尚未接线到 runExtraction（接线在 Phase 4 R5/R9）。
+ */
+import * as path from 'node:path';
+import { atomicWriteJson, readJsonStrict } from '../util/io.js';
+import { ROUTE_HEALTH_FILE_VERSION } from './file-versions.js';
+function keyOf(provider, model) {
+    return `${provider}/${model}`;
+}
+/** 学习值默认过期(ms)：超此龄视为陈旧、读侧应重探（换模型/网关不至于被历史最小值锁死）。 */
+export const ROUTE_HEALTH_STALE_MS = 7 * 24 * 60 * 60_000;
+export function routeHealthPathFor(dataDir) {
+    return path.join(dataDir, 'distill-route-health.json');
+}
+export class RouteHealthStore {
+    file;
+    routes = new Map();
+    dirty = false;
+    constructor(file) {
+        this.file = file;
+    }
+    /** 读盘 fail-open：缺/坏/未知版本 → 空表、不抛。 */
+    async load() {
+        const r = await readJsonStrict(this.file, { expectedVersion: ROUTE_HEALTH_FILE_VERSION });
+        this.routes = new Map();
+        if (!r.ok)
+            return; // missing / corrupt / unreadable / unknown_version 一律空起步
+        const raw = r.value?.routes;
+        if (!raw || typeof raw !== 'object')
+            return;
+        for (const [k, v] of Object.entries(raw)) {
+            if (!v || typeof v !== 'object')
+                continue;
+            const e = v;
+            if (typeof e.lastGoodChunkChars !== 'number' || !Number.isFinite(e.lastGoodChunkChars))
+                continue;
+            this.routes.set(k, {
+                lastGoodChunkChars: Math.max(0, Math.floor(e.lastGoodChunkChars)),
+                latencyEmaMs: typeof e.latencyEmaMs === 'number' && Number.isFinite(e.latencyEmaMs) ? e.latencyEmaMs : 0,
+                updatedAt: typeof e.updatedAt === 'string' ? e.updatedAt : '',
+            });
+        }
+    }
+    /** 该路由已学到、且未过期的跑通块长；0 = 无可用学习值（未学到或已陈旧）。 */
+    lastGoodChunkChars(provider, model, now = Date.now(), staleMs = ROUTE_HEALTH_STALE_MS) {
+        const e = this.routes.get(keyOf(provider, model));
+        if (!e || e.lastGoodChunkChars <= 0)
+            return 0;
+        const t = Date.parse(e.updatedAt);
+        if (Number.isFinite(t) && now - t > staleMs)
+            return 0; // 陈旧 → 交读侧重探
+        return e.lastGoodChunkChars;
+    }
+    /** 该路由延迟 EMA(ms)；0 = 未记。 */
+    latencyEma(provider, model) {
+        return this.routes.get(keyOf(provider, model))?.latencyEmaMs ?? 0;
+    }
+    /**
+     * 记一次「跑通」的块长：只降不升（更小块长才覆盖 lastGood），并更新延迟 EMA。
+     * @param chunkChars 本次成功的块长(字符)
+     * @param latencyMs  本次成功调用耗时(可选，用于 EMA)
+     */
+    recordGood(provider, model, chunkChars, latencyMs) {
+        if (!(chunkChars > 0) || !Number.isFinite(chunkChars))
+            return;
+        const k = keyOf(provider, model);
+        const cur = this.routes.get(k);
+        const next = {
+            lastGoodChunkChars: cur && cur.lastGoodChunkChars > 0
+                ? Math.min(cur.lastGoodChunkChars, Math.floor(chunkChars))
+                : Math.floor(chunkChars),
+            latencyEmaMs: latencyMs !== undefined && Number.isFinite(latencyMs) && latencyMs >= 0
+                ? cur && cur.latencyEmaMs > 0
+                    ? cur.latencyEmaMs * 0.7 + latencyMs * 0.3
+                    : latencyMs
+                : (cur?.latencyEmaMs ?? 0),
+            updatedAt: new Date().toISOString(),
+        };
+        this.routes.set(k, next);
+        this.dirty = true;
+    }
+    /** 清除学习值：传 provider+model 清单条，否则清全部（面板「重置学习值」一键）。 */
+    reset(provider, model) {
+        if (provider && model)
+            this.routes.delete(keyOf(provider, model));
+        else
+            this.routes.clear();
+        this.dirty = true;
+    }
+    /** 全量快照（面板回显用）。 */
+    snapshot() {
+        return [...this.routes.entries()].map(([key, v]) => ({ key, ...v }));
+    }
+    /** 有变更才落盘；失败由调用方兜底（不抛穿蒸馏）。@returns 是否写了盘 */
+    async save() {
+        if (!this.dirty)
+            return false;
+        const routes = {};
+        for (const [k, v] of this.routes)
+            routes[k] = v;
+        const payload = { version: ROUTE_HEALTH_FILE_VERSION, routes };
+        await atomicWriteJson(this.file, payload);
+        this.dirty = false;
+        return true;
+    }
+}

package/dist/store/runtime-installer.d.ts

@@ -36,8 +36,20 @@ export declare class RuntimeInstaller {
     private pkgJsonPath;
     /** 已就位版本(读 package.json;未安装返回 null)。 */
     installedVersion(): Promise<string | null>;
-    /** 是否就绪(版本精确匹配目标)。 */
+    /** 是否就绪(版本精确匹配目标 + sharp 平台原生件就位)。 */
     isReady(): Promise<boolean>;
+    /**
+     * 当前平台的 sharp 原生件候选路径(测试注入缝与单测共用):
+     * 绑定 .node 在 @img/sharp-<os>-<arch>/lib/,libvips 在 @img/sharp-libvips-<os>-<arch>/lib/。
+     * linux 有 glibc/musl 双候选;libvips 库文件名含版本串(仅 win 的 libvips-42.dll 稳定),
+     * 故统一按 lib 目录内存在 libvips* 文件判定,不钉文件名。
+     */
+    sharpNativeCandidates(): Array<{
+        binding: string;
+        libvipsDir: string;
+    }>;
+    /** 任一候选同时具备绑定 .node 与 libvips 库文件 → true(ENOENT/读取失败均计缺失)。 */
+    private sharpNativePresent;
     /**
      * 确保运行时就位:版本匹配直接就绪;否则安装(忙时并 await 同一次任务)。
      * 返回是否就绪(失败/取消返回 false 并在 progress.error 说明原因)。

package/dist/store/runtime-installer.js

@@ -102,9 +102,47 @@ export class RuntimeInstaller {
             return null;
         }
     }
-    /** 是否就绪(版本精确匹配目标)。 */
+    /** 是否就绪(版本精确匹配目标 + sharp 平台原生件就位)。 */
     async isReady() {
-        return (await this.installedVersion()) === this.target;
+        if ((await this.installedVersion()) !== this.target)
+            return false;
+        // fix #11 辅助检测:--ignore-scripts 安装半坏(平台原生包缺失/被剪)时,
+        // transformers 顶层 require('sharp') 必炸——判存在性,缺失报未就绪触发重装。
+        if (!(await this.sharpNativePresent())) {
+            this.logger?.warn('[memory] 运行时 sharp 平台原生件缺失(半装状态),isReady=false 触发重装');
+            return false;
+        }
+        return true;
+    }
+    /**
+     * 当前平台的 sharp 原生件候选路径(测试注入缝与单测共用):
+     * 绑定 .node 在 @img/sharp-<os>-<arch>/lib/,libvips 在 @img/sharp-libvips-<os>-<arch>/lib/。
+     * linux 有 glibc/musl 双候选;libvips 库文件名含版本串(仅 win 的 libvips-42.dll 稳定),
+     * 故统一按 lib 目录内存在 libvips* 文件判定,不钉文件名。
+     */
+    sharpNativeCandidates() {
+        const arch = process.arch; // x64 | arm64
+        const osKeys = process.platform === 'linux' ? ['linux', 'linuxmusl'] : process.platform === 'darwin' ? ['darwin'] : ['win32'];
+        const img = path.join(this.runtimeDir, 'node_modules', '@img');
+        return osKeys.map((k) => ({
+            binding: path.join(img, `sharp-${k}-${arch}`, 'lib', `sharp-${k}-${arch}.node`),
+            libvipsDir: path.join(img, `sharp-libvips-${k}-${arch}`, 'lib'),
+        }));
+    }
+    /** 任一候选同时具备绑定 .node 与 libvips 库文件 → true(ENOENT/读取失败均计缺失)。 */
+    async sharpNativePresent() {
+        for (const c of this.sharpNativeCandidates()) {
+            try {
+                await fs.access(c.binding);
+                const files = await fs.readdir(c.libvipsDir);
+                if (files.some((f) => f.startsWith('libvips')))
+                    return true;
+            }
+            catch {
+                /* 本候选不命中,试下一个 */
+            }
+        }
+        return false;
     }
     /**
      * 确保运行时就位:版本匹配直接就绪;否则安装(忙时并 await 同一次任务)。

package/dist/store/sqlite.d.ts

@@ -168,20 +168,22 @@ export declare class MemoryDb {
      * **软删**(记忆退场):保留主表行,撤出检索面。
      *
      * 与 `deleteL1Batch` 的差别**只有一处**:不动 `l1_records` 行本身。
-     * `valid_to` 闭合 + `metadata_json` 写取代标记 → 记录仍能被 `listL1` 列出、
-     * 能被 `clearRetireMarker` + upsert 恢复;而 FTS 与向量行照旧删除,于是检索面
-     * (含去重候选召回)自然看不到它 —— **检索 SQL 一行都不用改**,活动记录零漂移
-     * 因此是构造性的,不是比对出来的。
+     * `metadata_json` 写取代标记 → 记录仍能被 `listL1` 列出、能被 `clearRetireMarker`
+     * + upsert 恢复;而 FTS 与向量行照旧删除,于是检索面(含去重候选召回)自然看不到它。
+     *
+     * 门1 解耦(expiry-tiering R1/task_2.3):退场**只写 marker，不再闭合 valid_to**——
+     * valid_to 回归纯现实有效期，退场与否由 marker 单源回答（`isRetired`）。
      *
      * 顺序刻意如此:先打标记(可逆的那一半),再撤检索面,且整体在一个事务里。
      * 反过来先撤索引而打标记失败,记录会落在"检索不到、也没被标记"的状态 ——
      * 既查不出来也恢复不了,是最坏的一种中间态。
      *
-     * **幂等**:已退场(`valid_to` 非空或已有标记)的 id 不再重复写标记,
+     * **幂等**:已退场(带 marker)的 id 不再重复写标记,
      * 保留首次退场的原因与时刻(「谁先取代了它」不该被后一次调用改写)。
      *
-     * **不调** `graphStore.markSourcesDeleted`:那是"来源已物理消失"的传播,
-     * 而软删的记录仍活在主表里 —— 图谱侧的退役语义另计(见计划 findings R-a)。
+     * **不调** `graphStore.markSourcesDeleted`(那是"来源已物理消失"的传播,软删行一直在),
+     * 而是调 `markSourcesRetired`(计划 R9 对偶刀):按"来源是否全部退场态"重算清扫,
+     * 全退场的 active/disputed 节点·边标 archived 墓碑(派生投影由当前事实重算,非事件改写)。
      */
     retireL1Batch(ids: string[], info: SupersedeInfo): number;
     /**
@@ -193,12 +195,14 @@ export declare class MemoryDb {
      * 清掉退场标记(恢复的**前半**)。返回清完标记的记录,供调用方 re-upsert 以重建
      * FTS/向量 —— 那条路径(`upsertL1InTx`)已存在,不在这里重复实现。
      *
-     * 只清 `valid_to` 与标记键,**不碰内容**:恢复不该修改记忆本身。
-     * 返回的 `validTo` 显式置 `undefined`(而非留着旧 epoch),否则 upsert 会
-     * 用 `toIso(旧值)` 把 `valid_to` 又写回去,恢复静默失败。
+     * 门1 解耦(task_2.3 的对偶面):只剥 marker,**不碰 valid_to**——
+     * 行若本就带着真实历史有效期(导入/抽取写入),恢复不该把它抹掉;
+     * 旧版 retire 写进 valid_to 的退场时刻对新行只影响 classify 落到
+     * historical/expired_suspect(仍可检可注入,带标注),由 validity-backfill 逐步纠偏。
+     * 返回的 `validTo` 保持原值——upsert 照原样写回,不会静默改列。
      */
     clearRetireMarker(ids: string[]): MemoryRecord[];
-    /** 已退场记录列表(面板用):`valid_to` 非空即已退场。失败返回空。 */
+    /** 已退场记录列表(面板用):与 `retiredL1Sql()` 同判据(marker 单源)。失败返回空。 */
     listRetiredL1(opts: {
         limit: number;
         offset: number;
@@ -530,7 +534,15 @@ export declare class MemoryDb {
      * 返回扫描行数;存储降级返回 0。
      */
     scanL1Metadata(cb: (recordId: string, metadata: Record<string, unknown> | null) => void): number;
-    /** retired 行计数(退场判定与 listRetiredL1 同口径:valid_to 非空)。失败返回 0。 */
+    /**
+     * 反向取代链查询(task_4.4,门3):"谁被这条记录取代了"——扫 metadata_json 里
+     * 取代标记的 `by` 指向本 id 的行。百~千量级全扫可接受(与 `retiredL1Sql` 同属
+     * LIKE 面);超过阈值时留 warn——真到万级该建索引，不在本计划面里预先造。
+     * **只回退场行**："被取代者"正是带 marker 的旧行(活跃行若 by 指过来是脏数据)；
+     * 模式含闭合引号(`"by":"<id>"`),不会前缀误配更长 id。
+     */
+    findSupersededTargets(newId: string): string[];
+    /** retired 行计数(退场判定与 listRetiredL1 同口径:`retiredL1Sql` marker 单源)。失败返回 0。 */
     retiredL1Count(): number;
     /**
      * Room 计数(**标签自生长分类**):展开 `metadata.tags` 聚合,1 个 slug tag = 1 个 Room。