dsh-prime-memory 0.26.5 → 0.26.9

package/dist/stats.js

@@ -26,7 +26,7 @@ import { RECEIPTS_QUERY_LIMIT_MAX, dimensionOf, toReceiptView } from './store/re
 import { getTraceStore } from './store/trace.js';
 import { resolveConflictPair, listConflictPairs } from './conflict-service.js';
 import { sourceAnchorLabels } from './pipeline/anchors.js';
-import { readSupersedeMarker } from './store/supersede.js';
+import { readSupersedeMarker, withSupersedeMarker, isRetired } from './store/supersede.js';
 import { isSnapshotName } from './store/l1-snapshot.js';
 import { WING_CATALOG, WING_FALLBACK } from './types.js';
 import { isRoomSlug } from './metadata-validators.js';
@@ -525,7 +525,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
             let retired = false;
             let announced = false;
             // 退场**前**的记录快照（带 workspaceId/name）——失效联动要靠它算落点，
-            // 而 `retire` 只改 `valid_to`，不会动这两列，所以取在退场前后等价，取在前更直白。
+            // 而 `retire` 只写 marker，不会动这两列，所以取在退场前后等价，取在前更直白。
             let rec;
             if (p.score === -1) {
                 rec = stores.l1.getByIds([id])[0];
@@ -547,9 +547,11 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 // （面板无消费方），磁盘凭证的对账走 mem-reconcile。
                 if (retired && rec !== undefined && cfg.memExport?.enabled === true && stores.mdLedger !== undefined) {
                     void disableProjectionFile({
-                        // 传退场**后**的快照：渲染出的 frontmatter 才带 `retired: true`，
-                        // 凭证自己就能说清它为什么存在。
-                        record: { ...rec, validTo: Date.parse(retiredAt) || Date.now() },
+                        // 传退场**后**的快照：门1 解耦后 md 层按 marker 判退场，这里补上同样形状的
+                        // 取代标记，渲染出的 frontmatter 才带 `retired: true`——凭证自己就能说清它为什么存在。
+                        record: withSupersedeMarker(rec.metadata, { at: retiredAt, reason: 'obsolete' }) === rec.metadata
+                            ? rec
+                            : { ...rec, metadata: withSupersedeMarker(rec.metadata, { at: retiredAt, reason: 'obsolete' }) },
                         cfgRoot: cfg.memExport.root,
                         dataDir: deps.dataDir,
                         ledger: stores.mdLedger,
@@ -1342,6 +1344,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     toolRoom: true, toolGraph: true, toolRuminate: true, toolConflict: true, toolMutate: true, toolSkills: true,
                     reasoningEffort: '', distillProvider: '', distillModel: '', distillChain: [],
                     distillBudgets: { extract: 0, dedup: 0, l2: 0, l3: 0, graph: 0 }, distillMaxInputChars: 0,
+                    distillTimeoutMs: 0,
                     distillLayerChains: { l1: [], l2: [], l3: [] },
                     distillMode: '', directBaseURL: '', directApiKey: '',
                     embedRemoteBaseURL: '', embedRemoteApiKey: '', embedRemoteModel: '', embedRemoteDimensions: 0,
@@ -1352,6 +1355,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     redistillEnabled: live?.get()?.redistillEnabled === true,
                     mdSyncEnabled: live?.get()?.mdSyncEnabled === true,
                     memportEnabled: live?.get()?.memportEnabled === true,
+                    validityTiering: live?.get()?.validityTiering === true,
                     mdExportMaxRecords: live?.get()?.mdExportMaxRecords ?? 0,
                     backfillConcurrency: live?.get()?.backfillConcurrency ?? 0,
                 }),
@@ -1383,6 +1387,12 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     fallback: cfg.llm.maxInputChars,
                     effective: s && s.distillMaxInputChars > 0 ? s.distillMaxInputChars : cfg.llm.maxInputChars,
                 },
+                // R10 蒸馏超时(ms)：current 是运行时覆盖(0 = 跟随配置)，fallback 是静态 llm.timeoutMs
+                timeoutBudget: {
+                    current: s?.distillTimeoutMs ?? 0,
+                    fallback: cfg.llm.timeoutMs,
+                    effective: s && s.distillTimeoutMs > 0 ? s.distillTimeoutMs : cfg.llm.timeoutMs,
+                },
             };
             return resp;
         }
@@ -1465,14 +1475,22 @@ export async function handleEndpoint(endpoint, payload, deps) {
                 }
                 clean.distillBudgets = budgets;
             }
-            // 输入预算(字符):0 = 跟随静态配置;正值须落在静态 schema 同款范围(1000~100 万)
+            // 输入预算(字符):0 = 跟随静态配置;正值须落在静态 schema 同款范围(1000~256k)
             if (patch.distillMaxInputChars !== undefined) {
                 const n = Number(patch.distillMaxInputChars);
-                if (!Number.isInteger(n) || n < 0 || n > 1_000_000 || (n > 0 && n < 1000)) {
-                    throw new Error('distillMaxInputChars 须为 0 或 1000~1000000 的整数(0 = 跟随配置)');
+                if (!Number.isInteger(n) || n < 0 || n > 256_000 || (n > 0 && n < 1000)) {
+                    throw new Error('distillMaxInputChars 须为 0 或 1000~256000 的整数(0 = 跟随配置)');
                 }
                 clean.distillMaxInputChars = n;
             }
+            // R10 蒸馏超时(ms)：0 = 跟随静态配置；正值 1000~600000（与 live schema 同上限）
+            if (patch.distillTimeoutMs !== undefined) {
+                const n = Number(patch.distillTimeoutMs);
+                if (!Number.isInteger(n) || n < 0 || n > 600_000 || (n > 0 && n < 1000)) {
+                    throw new Error('distillTimeoutMs 须为 0 或 1000~600000 的整数(0 = 跟随配置)');
+                }
+                clean.distillTimeoutMs = n;
+            }
             // 蒸馏通道运行时覆盖(direct 解耦):mode 白名单;endpoint 可回显;apiKey 属机密——
             // 写入后存 settings,但不回读到 UI、不落本条日志(下方日志先剔除后记录)
             if (patch.distillMode !== undefined) {
@@ -1750,7 +1768,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     ...(Array.isArray(r.metadata?.dsh_keywords) ? { keywords: r.metadata.dsh_keywords.filter((k) => typeof k === 'string' && k !== '') } : {}),
                     ...(Array.isArray(r.metadata?.dsh_usage_scenario) ? { usageScenario: r.metadata.dsh_usage_scenario } : {}),
                     filePath,
-                    retired: r.validTo !== undefined,
+                    // 退场判据与库侧同源（门1:marker 单源，valid_to 只是现实有效期）。
+                    retired: isRetired(r),
                 };
             });
             return { items };
@@ -1828,8 +1847,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
             let targets;
             if (explicit.length > 0) {
                 // 显式 id 也要**复核**是否真的处于已退场态:防止调用方用一个 id 列表
-                // 把活动记忆绕过软删直接物理抹掉(那等于给了一条硬删后门)。
-                targets = explicit.filter((id) => stores.l1.getByIds([id]).some((r) => r.validTo !== undefined));
+                // 把活动记忆绕过软删直接物理抹掉(那等于给了一条硬删后门)。判据 marker 单源(门1)。
+                targets = explicit.filter((id) => stores.l1.getByIds([id]).some((r) => isRetired(r)));
             }
             else {
                 targets = [];
@@ -1847,7 +1866,8 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     id: r.id,
                     name: r.name ?? '',
                     type: r.type,
-                    retiredAt: r.validTo === undefined ? '' : new Date(r.validTo).toISOString(),
+                    // 退场时刻:marker.at 优先;旧版 retire 写的 valid_to 作回退(存量行兼容)。
+                    retiredAt: readSupersedeMarker(r.metadata)?.at ?? (r.validTo === undefined ? '' : new Date(r.validTo).toISOString()),
                 }));
                 const resp = {
                     dryRun: true,
@@ -1893,7 +1913,7 @@ export async function handleEndpoint(endpoint, payload, deps) {
                     id: x.id,
                     name: x.name ?? '',
                     type: x.type,
-                    retiredAt: x.validTo === undefined ? '' : new Date(x.validTo).toISOString(),
+                    retiredAt: readSupersedeMarker(x.metadata)?.at ?? (x.validTo === undefined ? '' : new Date(x.validTo).toISOString()),
                 })),
             };
             return resp;
@@ -2351,7 +2371,8 @@ export function agingWeightOf(updatedAtMs, halfLifeDays, now = Date.now()) {
     return Math.max(0.5, Math.pow(0.5, ageDays / halfLifeDays));
 }
 export function hitToUiRecord(r, extra) {
-    const retired = r.validTo !== undefined;
+    // 退场判据 marker 单源(门1 解耦,与 `isRetired`/`retiredL1Sql` 同口径)。
+    const retired = isRetired(r);
     const mark = retired ? readSupersedeMarker(r.metadata) : undefined;
     return {
         id: r.id,

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

@@ -63,8 +63,10 @@ export interface InitialEmbedding {
 export declare function remoteCeiling(cfg: MemoryConfig): boolean;
 export declare function resolveInitialEmbedding(cfg: MemoryConfig, sourceStore: EmbeddingSourceStore, downloader: ModelDownloadQueue, makeLocal: (modelId: string) => LocalEmbeddingService | null, logger?: MemoryLogger): Promise<InitialEmbedding>;
 /** 本地服务构造工厂(index.ts 的初始解析与 Manager 共用一份实现,防漂移)。
- *  推理在 worker 线程(见 local-embedding.ts);此处只传 runtime 目录与模型目录。 */
-export declare function makeLocalServiceFactory(installer: RuntimeInstaller, downloader: ModelDownloadQueue, logger?: MemoryLogger, maxInputChars?: number): (modelId: string) => LocalEmbeddingService | null;
+ *  推理在 fork 子进程(见 local-embedding.ts,fix #11);此处只传 runtime 目录与模型目录。 */
+export declare function makeLocalServiceFactory(installer: RuntimeInstaller, downloader: ModelDownloadQueue, logger?: MemoryLogger, maxInputChars?: number, 
+/** 测试注入缝:子进程资产路径(源码态下 dist 产物不存在,显式指向 resources 源文件)。 */
+childPath?: string): (modelId: string) => LocalEmbeddingService | null;
 export interface EmbeddingManagerDeps {
     dataDir: string;
     cfg: MemoryConfig;

package/dist/store/embedding-source.js

@@ -153,14 +153,17 @@ export async function resolveInitialEmbedding(cfg, sourceStore, downloader, make
     return { svc, dims: cfg.embedding.dimensions, providerInfo: svc.getProviderInfo() };
 }
 /** 本地服务构造工厂(index.ts 的初始解析与 Manager 共用一份实现,防漂移)。
- *  推理在 worker 线程(见 local-embedding.ts);此处只传 runtime 目录与模型目录。 */
-export function makeLocalServiceFactory(installer, downloader, logger, maxInputChars) {
+ *  推理在 fork 子进程(见 local-embedding.ts,fix #11);此处只传 runtime 目录与模型目录。 */
+export function makeLocalServiceFactory(installer, downloader, logger, maxInputChars, 
+/** 测试注入缝:子进程资产路径(源码态下 dist 产物不存在,显式指向 resources 源文件)。 */
+childPath) {
     return (modelId) => {
         const entry = catalogById(modelId);
         if (!entry)
             return null;
         return new LocalEmbeddingService(entry, downloader.modelsDir(entry.id), {
             runtimeDir: installer.runtimeDir,
+            childPath,
             logger,
             maxInputChars,
         });

package/dist/store/file-versions.d.ts

@@ -29,3 +29,5 @@ export declare const PENDING_FILE_VERSION = 1;
 export declare const RECONCILE_STATE_FILE_VERSION = 1;
 /** `mem-md-ledger.json`（md 投射指纹账本，N9；派生态，删了可重建）。*/
 export declare const MEM_MD_LEDGER_FILE_VERSION = 1;
+/** `distill-route-health.json`（蒸馏路由健康学习值，R9；运行时派生，删了可重学）。*/
+export declare const ROUTE_HEALTH_FILE_VERSION = 1;

package/dist/store/file-versions.js

@@ -29,3 +29,5 @@ export const PENDING_FILE_VERSION = 1;
 export const RECONCILE_STATE_FILE_VERSION = 1;
 /** `mem-md-ledger.json`（md 投射指纹账本，N9；派生态，删了可重建）。*/
 export const MEM_MD_LEDGER_FILE_VERSION = 1;
+/** `distill-route-health.json`（蒸馏路由健康学习值，R9；运行时派生，删了可重学）。*/
+export const ROUTE_HEALTH_FILE_VERSION = 1;

package/dist/store/graph-store.d.ts

@@ -139,6 +139,54 @@ export declare class GraphStore {
      * 记录跳过。返回实际新建的 job 数。
      */
     queueGraphProjection(recordIds: readonly string[], priority: number): number;
+    /**
+     * 入队的详细形态(与 `queueGraphProjection` 同一实现,只是把新建 job id 也交出来):
+     * `memory_reproject` 工具面需要 `{queued, jobIds}` 回报,而既有调用方只数 created——
+     * 两个返回形状共享一份去重/分片逻辑,不漂移。
+     */
+    private queueGraphProjectionDetailed;
+    /**
+     * 强制重投(计划 expiry-tiering R10 冻结契约 · 先行刀):
+     * 抹掉 `graph_projected_records` 里这些记录的"已按当前版本投过"凭证,再按
+     * 新蒸馏优先级入队——绕开 `projector_version` 的永久跳过,让"改了 L1 → 图谱跟随"
+     * 有一条不依赖重启/周期 sweep 的纠正通道。
+     *
+     * **不动在途 `graph_job_records` 映射**(与上游 task_7.5 字面的一处刻意偏差,
+     * 理由记入写面计划 findings):claim 在认领时才现读 L1 记录,在途 job 天然投的是
+     * **改后**内容;若把映射一并删掉,同一次调用稍后再来一次就会绕过 PK 去重,
+     * 堆出内容重叠的双 job——保留映射才是"重复调用不堆重 job"的构造性保证。
+     *
+     * 幂等:在途有 job → blocked 集吸收,`created=0`;job 已完成 → 凭证刚被
+     * `complete` 写回,本方法再删再投,是合法的新重投而非堆积。
+     */
+    forceReprojectRecord(recordIds: readonly string[]): {
+        queued: number;
+        jobIds: string[];
+    };
+    /**
+     * 确定性边提案落库面(graph-write-plane R4 兜底支路):把"工具传入的显式边提案"
+     * 当作一次确定性投影输入,经 `applyGraphProjection` **纯函数**校验后在同一事务内
+     * 写回——不是裸 UPDATE graph_edges:validSources 硬校验、同 (from,relation) 换目标
+     * 闭旧边的确定性支路、来源并集封顶,全部复用既有守门代码(R5 不变量由它保证)。
+     *
+     * 提案形态:两端节点按现有 name/type 重提(消歧合并会命中现有节点,不新铸实体),
+     * 边 (from → to, relation) 携调用方给的 sourceRecordIds。claim 同款现读 L1:
+     * allowedRecordIds = 命中的来源记录集,未命中的 id 会被纯函数整条拒掉(返回
+     * ok:false, reason='dropped')——工具面传的"非现存 L1"在这里撞上硬校验,而非静默落库。
+     */
+    applyRelationProposal(opts: {
+        fromNodeId: string;
+        toNodeId: string;
+        relation: string;
+        sourceRecordIds: readonly string[];
+        now?: string;
+    }): {
+        ok: boolean;
+        reason?: string;
+        closedEdgeIds: string[];
+        edgeIds: string[];
+        touchedNodeIds: string[];
+    };
     /**
      * 记录被物理删除后，把两张**索引表**里指向它的行一并抹掉。
      *
@@ -164,8 +212,11 @@ export declare class GraphStore {
      * 校验)→ 写回 touched 行 → job 置 completed + 登记已投影记录 + 放掉 mapping。
      * job 非 running 态(已完成/已 dead/已回收)一律幂等 no-op;任何一步抛错整体
      * 回滚,不留半写。
+     *
+     * 返回 touched 节点中 active/disputed 的那批(写面向量收尾的输入,G-vec 缺陷修):
+     * 调用方只关心"哪些节点刚被写活",向量补算失败不回滚投影——返回值不参与控制流。
      */
-    complete(jobId: string, result: GraphProjectionResult, opts?: CompleteOptions): void;
+    complete(jobId: string, result: GraphProjectionResult, opts?: CompleteOptions): GraphNode[];
     /**
      * 投影失败收尾:attempts 已在 claim 时 +1——根据错误分类选不同封顶:
      * - 永久错误(校验/解析):attempts >= GRAPH_JOB_MAX_ATTEMPTS(3) → dead
@@ -191,6 +242,25 @@ export declare class GraphStore {
      * 之后;按 L1 存活集判定(而非本次删除集合),跨多次删除与历史孤儿一并收敛。
      */
     markSourcesDeleted(deletedIds: readonly string[]): void;
+    /**
+     * 退场传播(计划 expiry-tiering R9 冻结契约 · 先行刀):软删/取代后的图谱
+     * 来源活性重算清扫。
+     *
+     * 与 `markSourcesDeleted` 的分野:那边判"来源 row 是否还活着",对软删(主表行
+     * 一直在)结构性失效;这边判"来源是否全部处于**退场态**"——即
+     * `classifyValidity` ∈ {superseded, retired}。退场判据单源在 validity 层,
+     * 本方不再自写一份 valid_to/marker 比较(写面计划约束 §4)。
+     *
+     * 重算式 sweep(不是逐条事件改写):每次按当前 L1 全量判定候选节点/边,
+     * 双向收敛——
+     * - active/disputed 且来源全部退场(含 row 消失)→ `archived` 墓碑(保留行,
+     *   expand 可见,与物理删传播同落库形态);
+     * - archived 且来源全部复活(row 存在且非退场态)→ 回 `active`(restore 的回药;
+     *   被物理删清空来源的永不满 足此条,不会误复活)。
+     *
+     * `changedIds` 只作早退与诊断日志的口径,不参与判定(判定面 = 全图来源集)。
+     */
+    markSourcesRetired(changedIds: readonly string[]): void;
     /**
      * §C 矛盾冻结:把图谱的 `disputed` 状态**同步**到给定冲突集。
      *

package/dist/store/graph-store.js

@@ -21,8 +21,10 @@ import { randomBytes } from 'node:crypto';
 import { applyGraphProjection } from '../graph/apply.js';
 import { expandHitRecordIds, searchGraphNodes } from '../graph/search.js';
 import { buildFullView, buildGraphPreview } from '../graph/preview.js';
-import { GRAPH_JOB_BACKOFF_BASE_MS, GRAPH_JOB_BATCH, GRAPH_JOB_MAX_ATTEMPTS, GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS, GRAPH_PRIORITY_BACKFILL, GRAPH_PROJECTOR_VERSION, GRAPH_VEC_SEED_CAP, } from '../graph/types.js';
+import { GRAPH_JOB_BACKOFF_BASE_MS, GRAPH_JOB_BATCH, GRAPH_JOB_MAX_ATTEMPTS, GRAPH_JOB_TRANSIENT_MAX_ATTEMPTS, GRAPH_PRIORITY_BACKFILL, GRAPH_PRIORITY_NEW, GRAPH_PROJECTOR_VERSION, GRAPH_VEC_SEED_CAP, } from '../graph/types.js';
 import { normPersistence } from '../types.js';
+import { classifyValidity, isExitedState, validToSourceOf } from './validity.js';
+import { readSupersedeMarker } from './supersede.js';
 import { isZeroVector, vecToBuffer } from './vec-utils.js';
 const TAG = '[memory][graph]';
 /** 坏 JSON 容忍解析:图谱表列损坏只损失该行派生信息,不抛。 */
@@ -565,8 +567,16 @@ export class GraphStore {
      * 记录跳过。返回实际新建的 job 数。
      */
     queueGraphProjection(recordIds, priority) {
+        return this.queueGraphProjectionDetailed(recordIds, priority).created;
+    }
+    /**
+     * 入队的详细形态(与 `queueGraphProjection` 同一实现,只是把新建 job id 也交出来):
+     * `memory_reproject` 工具面需要 `{queued, jobIds}` 回报,而既有调用方只数 created——
+     * 两个返回形状共享一份去重/分片逻辑,不漂移。
+     */
+    queueGraphProjectionDetailed(recordIds, priority) {
         if (!this.db || recordIds.length === 0)
-            return 0;
+            return { created: 0, jobIds: [] };
         try {
             const db = this.db;
             const ids = [...new Set(recordIds)];
@@ -585,10 +595,10 @@ export class GraphStore {
             }
             const fresh = ids.filter((id) => !blocked.has(id));
             if (fresh.length === 0)
-                return 0;
+                return { created: 0, jobIds: [] };
             const now = new Date().toISOString();
             return this.tx(() => {
-                let created = 0;
+                const jobIds = [];
                 for (let i = 0; i < fresh.length; i += GRAPH_JOB_BATCH) {
                     const batch = fresh.slice(i, i + GRAPH_JOB_BATCH);
                     const jobId = this.newJobId();
@@ -597,14 +607,121 @@ export class GraphStore {
                     for (const id of batch) {
                         db.prepare('INSERT OR REPLACE INTO graph_job_records (record_id, job_id) VALUES (?, ?)').run(id, jobId);
                     }
-                    created++;
+                    jobIds.push(jobId);
                 }
-                return created;
+                return { created: jobIds.length, jobIds };
             });
         }
         catch (err) {
             this.logger?.warn(`${TAG} 投影入队失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
-            return 0;
+            return { created: 0, jobIds: [] };
+        }
+    }
+    /**
+     * 强制重投(计划 expiry-tiering R10 冻结契约 · 先行刀):
+     * 抹掉 `graph_projected_records` 里这些记录的"已按当前版本投过"凭证,再按
+     * 新蒸馏优先级入队——绕开 `projector_version` 的永久跳过,让"改了 L1 → 图谱跟随"
+     * 有一条不依赖重启/周期 sweep 的纠正通道。
+     *
+     * **不动在途 `graph_job_records` 映射**(与上游 task_7.5 字面的一处刻意偏差,
+     * 理由记入写面计划 findings):claim 在认领时才现读 L1 记录,在途 job 天然投的是
+     * **改后**内容;若把映射一并删掉,同一次调用稍后再来一次就会绕过 PK 去重,
+     * 堆出内容重叠的双 job——保留映射才是"重复调用不堆重 job"的构造性保证。
+     *
+     * 幂等:在途有 job → blocked 集吸收,`created=0`;job 已完成 → 凭证刚被
+     * `complete` 写回,本方法再删再投,是合法的新重投而非堆积。
+     */
+    forceReprojectRecord(recordIds) {
+        if (!this.db || recordIds.length === 0)
+            return { queued: 0, jobIds: [] };
+        const ids = [...new Set(recordIds)];
+        try {
+            this.tx(() => {
+                for (const chunk of chunkOf(ids)) {
+                    const ph = chunk.map(() => '?').join(',');
+                    this.db.prepare(`DELETE FROM graph_projected_records WHERE record_id IN (${ph})`).run(...chunk);
+                }
+            });
+            const r = this.queueGraphProjectionDetailed(ids, GRAPH_PRIORITY_NEW);
+            return { queued: r.created, jobIds: r.jobIds };
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 强制重投入队失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+            return { queued: 0, jobIds: [] };
+        }
+    }
+    /**
+     * 确定性边提案落库面(graph-write-plane R4 兜底支路):把"工具传入的显式边提案"
+     * 当作一次确定性投影输入,经 `applyGraphProjection` **纯函数**校验后在同一事务内
+     * 写回——不是裸 UPDATE graph_edges:validSources 硬校验、同 (from,relation) 换目标
+     * 闭旧边的确定性支路、来源并集封顶,全部复用既有守门代码(R5 不变量由它保证)。
+     *
+     * 提案形态:两端节点按现有 name/type 重提(消歧合并会命中现有节点,不新铸实体),
+     * 边 (from → to, relation) 携调用方给的 sourceRecordIds。claim 同款现读 L1:
+     * allowedRecordIds = 命中的来源记录集,未命中的 id 会被纯函数整条拒掉(返回
+     * ok:false, reason='dropped')——工具面传的"非现存 L1"在这里撞上硬校验,而非静默落库。
+     */
+    applyRelationProposal(opts) {
+        const fail = (reason) => ({ ok: false, reason, closedEdgeIds: [], edgeIds: [], touchedNodeIds: [] });
+        if (!this.db)
+            return fail('graph-not-ready');
+        const relation = String(opts.relation ?? '').trim();
+        const sourceIds = [...new Set((opts.sourceRecordIds ?? []).map((s) => String(s).trim()).filter((s) => s.length > 0))];
+        if (!opts.fromNodeId || !opts.toNodeId || opts.fromNodeId === opts.toNodeId)
+            return fail('bad-nodes');
+        if (!relation || sourceIds.length === 0)
+            return fail('empty-relation-or-sources');
+        try {
+            return this.tx(() => {
+                const { nodes, edges } = this.loadGraphInTx();
+                const from = nodes.find((n) => n.id === opts.fromNodeId);
+                const to = nodes.find((n) => n.id === opts.toNodeId);
+                if (!from || !to)
+                    return fail('nodes-not-found');
+                const records = this.loadRecordsInTx(sourceIds);
+                if (records.length === 0)
+                    return fail('sources-not-in-l1');
+                const now = opts.now ?? new Date().toISOString();
+                const idFactory = (prefix) => `${prefix}_${Date.now()}_${randomBytes(3).toString('hex')}`;
+                const result = {
+                    reason: 'tool-explicit-proposal',
+                    nodes: [
+                        { ref: 'from', name: from.name, type: from.type, sourceRecordIds: sourceIds, status: 'active' },
+                        { ref: 'to', name: to.name, type: to.type, sourceRecordIds: sourceIds, status: 'active' },
+                    ],
+                    edges: [{ fromRef: 'from', toRef: 'to', relation, sourceRecordIds: sourceIds, status: 'active' }],
+                };
+                const statusBefore = new Map(edges.map((e) => [e.id, e.status]));
+                const outcome = applyGraphProjection({
+                    nodes,
+                    edges,
+                    records,
+                    result,
+                    allowedRecordIds: new Set(records.map((r) => r.id)),
+                    now,
+                    idFactory,
+                });
+                if (outcome.edgeIds.length === 0)
+                    return fail('proposal-dropped-by-validator');
+                const touchedNodes = nodes.filter((n) => outcome.nodeIds.includes(n.id));
+                const touchedEdges = edges.filter((e) => outcome.edgeIds.includes(e.id));
+                this.upsertTouchedInTx(touchedNodes, touchedEdges);
+                const closedEdgeIds = touchedEdges
+                    .filter((e) => e.status === 'superseded' && statusBefore.get(e.id) !== 'superseded')
+                    .map((e) => e.id);
+                const newEdgeIds = touchedEdges.filter((e) => e.status === 'active' && e.relation === relation).map((e) => e.id);
+                this.logger?.info(`${TAG} 确定性边提案落库:${newEdgeIds.length} 边 active,${closedEdgeIds.length} 旧边 superseded(来源 ${sourceIds.length} 条,校验丢弃 ${outcome.dropped} 项)`);
+                return {
+                    ok: true,
+                    closedEdgeIds,
+                    edgeIds: newEdgeIds,
+                    touchedNodeIds: touchedNodes.map((n) => n.id),
+                };
+            }, true);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 确定性边提案失败(整体回滚): ${err instanceof Error ? err.message : String(err)}`);
+            return fail('tx-error');
         }
     }
     /**
@@ -692,10 +809,14 @@ export class GraphStore {
      * 校验)→ 写回 touched 行 → job 置 completed + 登记已投影记录 + 放掉 mapping。
      * job 非 running 态(已完成/已 dead/已回收)一律幂等 no-op;任何一步抛错整体
      * 回滚,不留半写。
+     *
+     * 返回 touched 节点中 active/disputed 的那批(写面向量收尾的输入,G-vec 缺陷修):
+     * 调用方只关心"哪些节点刚被写活",向量补算失败不回滚投影——返回值不参与控制流。
      */
     complete(jobId, result, opts) {
         if (!this.db)
-            return;
+            return [];
+        let touchedVecNodes = [];
         try {
             const db = this.db;
             const now = opts?.now ?? new Date().toISOString();
@@ -721,6 +842,9 @@ export class GraphStore {
                 const touchedNodes = nodes.filter((n) => outcome.nodeIds.includes(n.id));
                 const touchedEdges = edges.filter((e) => outcome.edgeIds.includes(e.id));
                 this.upsertTouchedInTx(touchedNodes, touchedEdges);
+                // 写面收尾的输入(只递交落库后的 active/disputed 节点):墓碑不需要向量,
+                // 读侧 searchNodesByVector 本就按状态闸过滤陈旧向量行。
+                touchedVecNodes = touchedNodes.filter((n) => n.status === 'active' || n.status === 'disputed');
                 db.prepare(`UPDATE graph_projection_jobs SET status = 'completed', error = NULL, updated_time = ? WHERE job_id = ?`).run(now, jobId);
                 for (const id of wanted) {
                     db.prepare('INSERT OR REPLACE INTO graph_projected_records (record_id, projector_version) VALUES (?, ?)').run(id, GRAPH_PROJECTOR_VERSION);
@@ -736,6 +860,7 @@ export class GraphStore {
             // 提交失败:job 仍在 running 态,下次启动 recoverRunning 回收重投
             this.logger?.warn(`${TAG} 投影提交失败(待启动回收重投): ${err instanceof Error ? err.message : String(err)}`);
         }
+        return touchedVecNodes;
     }
     /**
      * 投影失败收尾:attempts 已在 claim 时 +1——根据错误分类选不同封顶:
@@ -874,6 +999,94 @@ export class GraphStore {
             this.logger?.warn(`${TAG} 删除传播失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    /**
+     * 退场传播(计划 expiry-tiering R9 冻结契约 · 先行刀):软删/取代后的图谱
+     * 来源活性重算清扫。
+     *
+     * 与 `markSourcesDeleted` 的分野:那边判"来源 row 是否还活着",对软删(主表行
+     * 一直在)结构性失效;这边判"来源是否全部处于**退场态**"——即
+     * `classifyValidity` ∈ {superseded, retired}。退场判据单源在 validity 层,
+     * 本方不再自写一份 valid_to/marker 比较(写面计划约束 §4)。
+     *
+     * 重算式 sweep(不是逐条事件改写):每次按当前 L1 全量判定候选节点/边,
+     * 双向收敛——
+     * - active/disputed 且来源全部退场(含 row 消失)→ `archived` 墓碑(保留行,
+     *   expand 可见,与物理删传播同落库形态);
+     * - archived 且来源全部复活(row 存在且非退场态)→ 回 `active`(restore 的回药;
+     *   被物理删清空来源的永不满 足此条,不会误复活)。
+     *
+     * `changedIds` 只作早退与诊断日志的口径,不参与判定(判定面 = 全图来源集)。
+     */
+    markSourcesRetired(changedIds) {
+        if (!this.db || changedIds.length === 0)
+            return;
+        try {
+            const { nodes, edges } = this.loadGraph();
+            const sourceIds = new Set();
+            for (const n of nodes)
+                for (const id of n.sourceRecordIds)
+                    sourceIds.add(id);
+            for (const e of edges)
+                for (const id of e.sourceRecordIds)
+                    sourceIds.add(id);
+            if (sourceIds.size === 0)
+                return;
+            // 现读 L1 行(含已退场软删行——主表行一直在,差别在 marker);
+            // 列形状按 l1SelectCols 同款容缺(独立测试夹具/旧库可能没有时间增强列)。
+            const now = Date.now();
+            const byId = new Map();
+            for (const chunk of chunkOf([...sourceIds])) {
+                const ph = chunk.map(() => '?').join(',');
+                for (const r of this.db
+                    .prepare(`SELECT ${l1SelectCols(this.db)} FROM l1_records WHERE record_id IN (${ph})`)
+                    .all(...chunk)) {
+                    byId.set(String(r.record_id), rowToRecord(r));
+                }
+            }
+            /** 单条来源是否处于退场态:row 消失也算(与物理删传播同口径,宁保守勿复活)。 */
+            const exited = (id) => {
+                const rec = byId.get(id);
+                if (!rec)
+                    return true;
+                const state = classifyValidity({
+                    marker: readSupersedeMarker(rec.metadata),
+                    persistence: rec.persistence,
+                    validTo: rec.validTo,
+                    validToSource: validToSourceOf(rec.metadata),
+                    now,
+                });
+                return isExitedState(state);
+            };
+            const allExited = (ids) => ids.length > 0 && ids.every(exited);
+            const allRevived = (ids) => ids.length > 0 && ids.every((id) => byId.has(id) && !exited(id));
+            const toArchive = nodes.filter((n) => (n.status === 'active' || n.status === 'disputed') && allExited(n.sourceRecordIds));
+            const toArchiveEdges = edges.filter((e) => (e.status === 'active' || e.status === 'disputed') && allExited(e.sourceRecordIds));
+            const toRevive = nodes.filter((n) => n.status === 'archived' && allRevived(n.sourceRecordIds));
+            const toReviveEdges = edges.filter((e) => e.status === 'archived' && allRevived(e.sourceRecordIds));
+            if (toArchive.length === 0 && toArchiveEdges.length === 0 && toRevive.length === 0 && toReviveEdges.length === 0)
+                return;
+            const nowIso = new Date(now).toISOString();
+            this.tx(() => {
+                for (const n of toArchive) {
+                    this.db.prepare(`UPDATE graph_nodes SET status = 'archived', updated_time = ? WHERE node_id = ?`).run(nowIso, n.id);
+                }
+                for (const e of toArchiveEdges) {
+                    this.db.prepare(`UPDATE graph_edges SET status = 'archived', updated_time = ? WHERE edge_id = ?`).run(nowIso, e.id);
+                }
+                for (const n of toRevive) {
+                    this.db.prepare(`UPDATE graph_nodes SET status = 'active', updated_time = ? WHERE node_id = ?`).run(nowIso, n.id);
+                }
+                for (const e of toReviveEdges) {
+                    this.db.prepare(`UPDATE graph_edges SET status = 'active', updated_time = ? WHERE edge_id = ?`).run(nowIso, e.id);
+                }
+            });
+            this.logger?.info(`${TAG} 退场传播(重算清扫):${toArchive.length + toArchiveEdges.length} 项标 archived,` +
+                `${toRevive.length + toReviveEdges.length} 项复活(触发记录 ${changedIds.length} 条)`);
+        }
+        catch (err) {
+            this.logger?.warn(`${TAG} 退场传播失败(忽略): ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /**
      * §C 矛盾冻结:把图谱的 `disputed` 状态**同步**到给定冲突集。
      *

package/dist/store/l1.d.ts

@@ -252,6 +252,11 @@ export declare class L1Store {
     };
     /** 按 id 精确取记录(去重决策的版本号查询用,避免全表扫描)。 */
     getByIds(ids: string[]): MemoryRecord[];
+    /**
+     * 反向取代链(task_4.4,门3):返回"被 newId 取代"的退场记录 id。
+     * 走 MemoryDb 的 LIKE 全扫缝(百~千量级;阈值告警在那边)。
+     */
+    findSupersededTargets(newId: string): string[];
     /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
     findIdByExtKey(extKey: string): string | undefined;
     /**

package/dist/store/l1.js

@@ -10,6 +10,7 @@ import { existsSync, mkdirSync, promises as fs, writeFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { familyForType, isScopeVisible } from '../types.js';
 import { isRetired } from './supersede.js';
+import { stampValidity } from './validity.js';
 import { exportThenPurge, readSnapshotManifest, readSnapshotRecords, restoreL1Snapshot, selectSnapshotTargets, snapshotDirFor, listSnapshots as listSnapshotsIn } from './l1-snapshot.js';
 import { EmbedHelper, NoopEmbeddingService } from './embedding.js';
 import { appendJsonl, dayKey, ensureDir, readJsonl } from '../util/io.js';
@@ -392,6 +393,13 @@ export class L1Store {
     getByIds(ids) {
         return this.db.getL1ByIds(ids);
     }
+    /**
+     * 反向取代链(task_4.4,门3):返回"被 newId 取代"的退场记录 id。
+     * 走 MemoryDb 的 LIKE 全扫缝(百~千量级;阈值告警在那边)。
+     */
+    findSupersededTargets(newId) {
+        return this.db.findSupersededTargets(newId);
+    }
     /** 外部导入幂等 pre-check(轨3-P0):ext_key 命中已存在记录则返回其 id,否则 undefined。 */
     findIdByExtKey(extKey) {
         return this.db.findRecordIdByExtKey(extKey);
@@ -473,9 +481,14 @@ export class L1Store {
     async appendNew(records) {
         if (records.length === 0)
             return;
+        // 写侧标注汇流口(task_3.2):所有新写路径(pipeline / memory_add / import / memport /
+        // 重建保留…)都经这里，统一盖 dsh_validity 快照;源头盖过的行(pipeline 带 evidence、
+        // 工具带 llm_inferred)保留其 validToSource，未盖过的补 'unknown'(fail-open)。
+        const stampNow = Date.now();
         for (const r of records) {
             if (!r.family)
                 r.family = familyForType(r.type);
+            stampValidity(r, stampNow);
         }
         // 起名必须在**追加事实源之前**：名字是文件身份键，进了 JSONL 才能跟记录一起重生。
         // 这批还没进库，所以只算名字不落库（persist=false），由下面的 upsert 一并写。
@@ -506,7 +519,9 @@ export class L1Store {
     async upsert(record) {
         if (!record.family)
             record.family = familyForType(record.type);
-        // merge 分支会继承胜方的 name；两边都没名字时在这里补上，别让新铸的行继续带空名。
+        // 写侧标注汇流口(与 appendNew 同口径):merge 分支会继承胜方的 name；
+        // 两边都没名字时在这里补上，别让新铸的行继续带空名。
+        stampValidity(record, Date.now());
         this.assignMissingNames([record], { persist: false });
         const vec = (await this.helper.batch([record.content]))[0];
         if (!this.db.upsertL1(record, vec)) {
@@ -584,8 +599,9 @@ export class L1Store {
         // **只清理确实处于退场态的记录**。这道复核必须在删除发生的地方(而不是调用方):
         // 否则任何调用方传一个 id 列表就能绕过软删、把活动记忆直接物理抹掉——
         // 那等于给"先导出后清理"留了一条硬删后门。
+        // 门1 解耦:判据与全仓同为 marker 单源 `isRetired`(不再拿 valid_to 当退场凭据)。
         const known = new Map(this.db.getL1ByIds(ids).map((r) => [r.id, r]));
-        const retiredIds = ids.filter((id) => known.get(id)?.validTo !== undefined);
+        const retiredIds = ids.filter((id) => { const r = known.get(id); return r !== undefined && isRetired(r); });
         return exportThenPurge(this.db, this.dataDir, retiredIds, reason, this.logger, new Date(), opts);
     }
     // ───────────────────────────────────────────────────────────────────────────