@avantf/dsh-mem 0.4.1 → 0.6.0

package/README.md

@@ -30,8 +30,10 @@ DSH（DeepSeek Harness）原生记忆插件：给 agent 一份可长期检索的
   （frontmatter 记着它属于哪篇文档）——用你自己的编辑器改，插件会在**其后任一工具调用结束时**自动把改动同步
   回索引（先一次 `stat` 判漂移、再用正文哈希裁决，只重摄入真正改过的），「知识」页的「重新摄入」是手动兜底；
   删除文档会连同这份副本一起删除，`source_uri` 指向的原文件始终不被改动。
-- **可插拔、可降级**：语义后端 / 重排 / 向量库都走内部注册表；模型、hnswlib、分词器任一缺失都自动降级
+- **可插拔、可降级**：语义后端 / 向量库都走内部注册表；模型、hnswlib、分词器任一缺失都自动降级
   （FTS + 实体 / numpy 向量库 / 正则抽取），不会因此退出。
+- **0.5.0 起不再有结果重排**：`Reranker` 接口、`rerank.*` 配置键、公开面的 `registerReranker` 与结果/统计里的
+  `rerank_*` 字段已整体移除（旧配置里的 `rerank:` 段会被当作未知键告警并忽略）；可注册的检索面只剩语义后端与向量库。
 - **两个主窗口标签页**（排在 对话 / 轨迹 之后）：**记忆**（浏览、编辑、归档恢复、反馈、矛盾裁决）与
   **知识**（文档列表，每行可查看切片 / 编辑 / 打开目录 / 重新摄入 / 删除；另有跨库查询与入库——
   URL / 本地文件 / 本地目录 / 粘贴文本共用一个输入）。
@@ -166,6 +168,22 @@ SQLite 绑定的原因：存储层用运行时自带的 `node:sqlite`，它就
   - 规则型：`只有「注销式回购」减少总股本，库存股回购不减少——比较 EPS 影响时要区分。`（当……时，应……，附条件与例外）
   - 反例（不该写成事实）：一次调查的过程叙述、数据表、命令与链接——依据属于知识库文档，记忆里只留**结论 + 位置**
     （路径 / 来源 / 名称）；敏感信息同理，只记存放位置，不记明文。
+- **自定义过提示词文件的话，升级时需手动补**：提示词**文件优先于内置正文**（文件存在且非空时内置正文完全不参与渲染）。
+  0.6.0 起内置正文多了三条行为口径，若你改过 `mem-memory-usage.md`，请把下面三行追加到你的文件末尾；没改过则无需操作：
+  ```text
+  记忆是过去的记录、不是当下指令，无关时可完全忽略。
+  同一主题用 `update` 纠正并附核实依据，不同事实新增。
+  不要把 `recall` 结果原样回记。
+  ```
+- **可选：中文时间窗检索腿**（0.6.0 起，**默认关闭**）。它在查询含中文时间表达时，把**事件时间**（写入时用
+  `event_date` 给出）落在窗口内的活跃事实作为额外一条腿参与融合——只增加候选、不删已有命中，也不会回退到写入时间。
+  在 `~/.avantf/configs/common.yaml` 打开：
+  ```yaml
+  retriever:
+    time_window: true
+  ```
+  打开前先看 `mem_admin stats` 的 `validity.coverage`（带事件时间的事实占比）：覆盖率接近 0 时这条腿等于没开。
+
 - **语义模型**：默认从 `hf-mirror.com` 下载并缓存，也可指向本地模型目录离线运行。
 - **升级前先备份 `~/.avantf`**：数据库迁移是单向的，用旧版本打开新库会被明确拒绝。
 

package/lib/client.js

@@ -5315,7 +5315,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				fact_id: count.optional(),
 				category: optionalText.optional(),
 				ttl_days: count.optional(),
-				reason: optionalText.optional()
+				reason: optionalText.optional(),
+				source_ref: optionalText.optional(),
+				event_date: optionalText.optional(),
+				valid_until: optionalText.optional()
 			})),
 			direct("recall", object({
 				action: optionalText.optional(),
@@ -5327,6 +5330,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				obj: optionalText.optional(),
 				second_pred: optionalText.optional(),
 				category: optionalText.optional(),
+				source: optionalText.optional(),
+				include_scores: bool.optional(),
 				limit: count.optional(),
 				max_tokens: count.optional(),
 				floors: optionalText.optional()
@@ -5336,6 +5341,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				fact_id: count.optional(),
 				category: optionalText.optional(),
 				status: optionalText.optional(),
+				source: optionalText.optional(),
 				limit: count.optional(),
 				offset: count.optional(),
 				reason: optionalText.optional(),
@@ -5366,6 +5372,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 				source: optionalText.optional(),
 				limit: count.optional(),
 				max_tokens: count.optional(),
+				include_scores: bool.optional(),
 				floors: optionalText.optional()
 			})),
 			direct("classifySource", object({ text: optionalText.optional() })),
@@ -5670,9 +5677,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		* the marker", never a decode failure.
 		*/
 		function hostSkew(hostWire) {
-			if (hostWire === 1) return void 0;
-			if (hostWire === void 0) return `宿主没有回报 wire 版本（它比本客户端旧）：面板可能缺少新字段，重启 dsh web 让两半对齐。（本客户端说 wire=${String(1)}）`;
-			return `宿主回报的 wire 版本是 ${String(hostWire)}，本客户端只认识 ${String(1)}：面板继续显示，但两半可能已经错位——重启 dsh web 后再试。`;
+			if (hostWire === 2) return void 0;
+			if (hostWire === void 0) return `宿主没有回报 wire 版本（它比本客户端旧）：面板可能缺少新字段，重启 dsh web 让两半对齐。（本客户端说 wire=${String(2)}）`;
+			return `宿主回报的 wire 版本是 ${String(hostWire)}，本客户端只认识 ${String(2)}：面板继续显示，但两半可能已经错位——重启 dsh web 后再试。`;
 		}
 		/**
 		* Whether a host reporting `hostWire` can have registered a method introduced at `required`.
@@ -6440,7 +6447,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 						}));
 					}
 				}) : null
-			]), detail?.id === f.fact_id ? h("div", { className: pages_module_css_default.meta }, `创建于 ${detail.data.created_at} / 更新于 ${detail.data.updated_at ?? "—"}`, h("br"), `实体：${(detail.data.entities ?? []).join("、") || "（无）"}`, h("br"), `三元组：${(detail.data.triples ?? []).map((t) => `${t.subj} —${t.pred}→ ${t.obj}（${t.confidence.toFixed(2)}）`).join("；") || "（无）"}`, h("br"), `检索次数：${String(detail.data.retrieval_count ?? 0)}${detail.data.supersedes_id ? ` · 修订自 #${String(detail.data.supersedes_id)}` : ""}`) : null))), truncated ? h("button", {
+			]), detail?.id === f.fact_id ? h("div", { className: pages_module_css_default.meta }, `创建于 ${detail.data.created_at} / 更新于 ${detail.data.updated_at ?? "—"}`, h("br"), `实体：${(detail.data.entities ?? []).join("、") || "（无）"}`, h("br"), `三元组：${(detail.data.triples ?? []).map((t) => `${t.subj} —${t.pred}→ ${t.obj}（${t.confidence.toFixed(2)}）`).join("；") || "（无）"}`, h("br"), `检索次数：${String(detail.data.retrieval_count ?? 0)}${detail.data.supersedes_id ? ` · 修订自 #${String(detail.data.supersedes_id)}` : ""} · 被断言 ${String(detail.data.assert_count ?? 1)} 次`, h("br"), `有效期：${detail.data.valid_from ?? "未知"} → ${detail.data.valid_to ?? (detail.data.status === "active" ? "仍在有效" : "未知")}` + (detail.data.superseded_by === null || detail.data.superseded_by === void 0 ? "" : ` · 被 #${String(detail.data.superseded_by)} 取代`), h("br"), `来源：${(detail.data.sources ?? []).length === 0 ? "（未记录）" : (detail.data.sources ?? []).map((s) => `${s.kind}:${s.ref}`).join("；")}`) : null))), truncated ? h("button", {
 				type: "button",
 				className: pages_module_css_default.more,
 				disabled: loading,
@@ -6457,10 +6464,13 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 		function HealthBlock(props) {
 			const r = props.stats.retrieval;
 			if (r === void 0) return h("div", { className: pages_module_css_default.status }, "检索健康度不可用。");
+			const vectors = props.stats.vectors;
+			const pendingVectors = vectors === void 0 ? 0 : vectors.stale + vectors.space_stale;
+			const wal = props.stats.wal;
 			const pct = (v) => `${String(Math.round(v * 100))}%`;
 			const kinds = Object.entries(r.by_kind).map(([kind, v]) => `${kind} ${String(v.queries)} 次（空 ${String(v.zero_results)}）`).join(" · ");
-			const truncated = r.embedding_truncated + r.rerank_truncated + r.output_truncated;
-			return h("div", { className: pages_module_css_default.detail }, h("div", { className: pages_module_css_default.status }, `检索 ${String(r.queries)} 次 · 空结果 ${pct(r.zero_result_rate)} · 平均 ${r.avg_latency_ms.toFixed(1)}ms · 峰值 ${r.max_latency_ms.toFixed(1)}ms`), h("div", { className: pages_module_css_default.meta }, `语义腿在线 ${pct(r.semantic_live_rate)} · 平均命中 ${String(r.avg_results_per_query)} 条${r.rerank_used > 0 ? ` · 重排 ${String(r.rerank_used)} 次` : ""}`), kinds === "" ? null : h("div", { className: pages_module_css_default.meta }, kinds), h("div", { className: pages_module_css_default.meta }, truncated === 0 ? "未被任何预算截断。" : `截断：嵌入 ${String(r.embedding_truncated)} · 重排 ${String(r.rerank_truncated)} · 输出 ${String(r.output_truncated)}${r.output_truncated > 0 ? "（调大 retrieval.max_output_tokens 或用 max_tokens 参数）" : ""}`), r.updated_at === null ? null : h("div", { className: pages_module_css_default.meta }, `更新于 ${r.updated_at}`));
+			const truncated = r.embedding_truncated + r.output_truncated;
+			return h("div", { className: pages_module_css_default.detail }, pendingVectors === 0 ? null : h("div", { className: pages_module_css_default.status }, `⚠ 向量空间待迁移：${String(pendingVectors)} 条 ACTIVE 向量来自旧嵌入空间（宽度不符 ${String(vectors?.stale ?? 0)} · 其他表示 ${String(vectors?.space_stale ?? 0)}）——语义腿对它们失效，正在后台分批重算；手动入口 \`avantf-mem vectors --fix\``), wal?.warning === null || wal?.warning === void 0 ? null : h("div", { className: pages_module_css_default.status }, `⚠ ${wal.warning}（当前 ${String(wal.bytes)} 字节）`), h("div", { className: pages_module_css_default.status }, `检索 ${String(r.queries)} 次 · 空结果 ${pct(r.zero_result_rate)} · 平均 ${r.avg_latency_ms.toFixed(1)}ms · 峰值 ${r.max_latency_ms.toFixed(1)}ms`), h("div", { className: pages_module_css_default.meta }, `语义腿在线 ${pct(r.semantic_live_rate)} · 平均命中 ${String(r.avg_results_per_query)} 条`), kinds === "" ? null : h("div", { className: pages_module_css_default.meta }, kinds), props.stats.sources === void 0 && props.stats.validity === void 0 ? null : h("div", { className: pages_module_css_default.meta }, `来源覆盖 ${props.stats.sources === void 0 ? "—" : pct(props.stats.sources.coverage)}（${String(props.stats.sources?.facts_with_source ?? 0)}/${String(props.stats.sources?.active ?? 0)}） · 事件时间覆盖 ${props.stats.validity === void 0 ? "—" : pct(props.stats.validity.coverage)}（${String(props.stats.validity?.facts_with_valid_from ?? 0)}/${String(props.stats.validity?.active ?? 0)}）`), h("div", { className: pages_module_css_default.meta }, truncated === 0 ? "未被任何预算截断。" : `截断：嵌入 ${String(r.embedding_truncated)} · 输出 ${String(r.output_truncated)}${r.output_truncated > 0 ? "（调大 retrieval.max_output_tokens 或用 max_tokens 参数）" : ""}`), r.updated_at === null ? null : h("div", { className: pages_module_css_default.meta }, `更新于 ${r.updated_at}`));
 		}
 		/**
 		* Group cross-store hits for display: memory facts vs `domain → source`.
@@ -6477,6 +6487,26 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			return domain || source || "文档切片";
 		}
 		/**
+		* P-01: render the per-leg evidence the query page explicitly asked for (`include_scores: true`).
+		*
+		* `scores` is absent for every other caller (the field is default-off), so this returns null and
+		* the row renders exactly as before. A leg that did not recall the hit is `null` and prints as
+		* `—`, which is the honest reading: the candidate entered through some OTHER leg.
+		*/
+		function legEvidenceLine(hit) {
+			const scores = hit.scores;
+			if (scores === void 0) return null;
+			const label = {
+				semantic: "语义",
+				fts: "FTS",
+				jaccard: "实体",
+				hrr: "HRR"
+			};
+			const parts = Object.entries(scores).map(([leg, score]) => score === null ? `${label[leg] ?? leg} —` : `${label[leg] ?? leg} ${score.normalized.toFixed(2)}（原始 ${score.raw.toFixed(2)}）`);
+			const final = hit.final === void 0 ? "" : ` · 融合 ${hit.final.toFixed(3)}`;
+			return `证据：${parts.join(" · ")}${final}`;
+		}
+		/**
 		* How many candidates one reply's relevance floors removed, across every leg.
 		*
 		* This is the difference between the two readings of an empty result ("the floors removed N" vs
@@ -6573,7 +6603,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 					domain: domain.trim() || void 0,
 					source: source.trim() || void 0,
 					limit: 10,
-					floors
+					floors,
+					include_scores: true
 				})).then((outcome) => {
 					if (!queryGuard.isCurrent(seq)) return;
 					if (outcome.ok) {
@@ -7042,7 +7073,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 			})), props.remote === void 0 ? null : h("div", { className: pages_module_css_default.status }, queryLoading ? "查询中…" : queryStatus), props.remote !== void 0 && !queryLoading && error === void 0 && hits.length === 0 && queryStatus.startsWith("命中") && floors === "strict" && floorDropped > 0 ? h("div", { className: pages_module_css_default.status }, `没有达到相关性门槛的结果（严格门槛丢弃了 ${String(floorDropped)} 条）——可切「宽松」重试。`) : null, props.remote !== void 0 && !queryLoading && error === void 0 && hits.length === 0 && queryStatus.startsWith("命中") && floors === "loose" && floorDropped > 0 ? h("div", { className: pages_module_css_default.status }, `确实没有相关结果（宽松门槛下仍丢弃了 ${String(floorDropped)} 条）。`) : null, props.remote !== void 0 && !queryLoading && error === void 0 && hits.length === 0 && queryStatus.startsWith("命中") && floorDropped === 0 ? h("div", { className: pages_module_css_default.status }, "没有匹配项。知识库为空时先用「入库/导入」添加文档；记忆里也只包含已写入的事实。") : null, groups.map(([groupName, groupHits]) => h("div", { key: groupName }, h("div", { className: pages_module_css_default.groupHead }, groupName), h("ul", { className: pages_module_css_default.list }, groupHits.map((hit) => h("li", {
 				key: `${hit.source_ref}:${String(hit.ref_id)}`,
 				className: pages_module_css_default.item
-			}, hit.text, h("span", { className: pages_module_css_default.meta }, `${hit.kind} · score ${hit.score.toFixed(3)} · ${hit.source_ref}` + (hit.entities && hit.entities.length > 0 ? ` · 实体：${hit.entities.join("、")}` : "") + ` · 创建于 ${hit.created_at}` + (hit.updated_at !== null && hit.updated_at !== hit.created_at ? ` · 更新于 ${hit.updated_at}` : "")))))))) : null, showIngest ? h("div", { className: `${pages_module_css_default.item} ${pages_module_css_default.form}` }, h("div", { className: pages_module_css_default.toolbar }, h(DomainField, {
+			}, hit.text, h("span", { className: pages_module_css_default.meta }, `${hit.kind} · score ${hit.score.toFixed(3)} · ${hit.source_ref}` + (hit.entities && hit.entities.length > 0 ? ` · 实体：${hit.entities.join("、")}` : "") + ` · 创建于 ${hit.created_at}` + (hit.updated_at !== null && hit.updated_at !== hit.created_at ? ` · 更新于 ${hit.updated_at}` : "") + (legEvidenceLine(hit) === null ? "" : ` · ${legEvidenceLine(hit) ?? ""}`)))))))) : null, showIngest ? h("div", { className: `${pages_module_css_default.item} ${pages_module_css_default.form}` }, h("div", { className: pages_module_css_default.toolbar }, h(DomainField, {
 				label: "知识域（domain）",
 				value: iDomain,
 				onChange: setIDomain,

package/lib/engine/mem/config/config_files.d.ts

@@ -15,7 +15,7 @@ import type { AvantfLogger } from '../../mem-contract/index.js';
  * UNCOMMENTED line is warned about by the loader, so a wrong name here would be a trap rather than a
  * hint. `config_files.spec.ts` pins the ones this template names.
  */
-export declare const DEFAULT_COMMON_CONFIG = "# avantf-mem \u516C\u5171\u914D\u7F6E\uFF08\u5206\u5C42\u7B2C\u2461\u5C42\uFF09\u3002\u8FD9\u91CC\u5168\u662F\u6CE8\u91CA\uFF1A\u5220\u6389/\u7559\u7A7A = \u7528\u5185\u5EFA\u9ED8\u8BA4\uFF0C\u53D6\u6D88\u6CE8\u91CA\u5373\u751F\u6548\u3002\n# \u5206\u5C42\uFF08\u4F4E\u2192\u9AD8\uFF09\uFF1A\u2460 \u5185\u5EFA\u9ED8\u8BA4 \u2192 \u2461 \u672C\u6587\u4EF6 \u2192 \u2462 \u540C\u76EE\u5F55\u7684 memory.yaml / knowledge.yaml\uFF08\u7F3A\u5931=\u4E0D\u8986\u76D6\uFF09\n#               \u2192 \u2463 \u73AF\u5883\u53D8\u91CF \u2192 \u2464 \u63D2\u4EF6/CLI \u663E\u5F0F\u4F20\u53C2\n# \u6240\u6709\u53EF\u7F16\u8F91\u6587\u672C\u90FD\u5728 ~/.avantf \u4E0B\uFF1Aconfigs/*.yaml\uFF08\u672C\u76EE\u5F55\uFF09\u4E0E prompts/*.md\uFF08\u6A21\u578B\u63D0\u793A\u8BCD\uFF09\u3002\n\n# \u6570\u636E\u6839\u4E0D\u5728\u8FD9\u91CC\u914D\uFF1A\u5B83\u7531 \u2463 AVANTF_HOME\uFF08\u6216 CLI --data-home\u3001\u63D2\u4EF6 profile \u7684 dataHome\uFF09\u51B3\u5B9A \u2014\u2014\n# \u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u7684\u65F6\u5019\u8FD8\u6CA1\u8BFB\u5230\u5B83\uFF0C\u6240\u4EE5\u5199\u5728\u8FD9\u91CC\u7684 dataHome \u5BF9\u6570\u636E\u6839\u65E0\u6548\uFF08DESIGN \u00A73\uFF09\u3002\n\n# semantic:                           # \u5D4C\u5165\u540E\u7AEF\uFF08\u8BB0\u5FC6\u4E0E\u77E5\u8BC6\u5171\u7528\uFF0C\u8DE8\u5E93\u5206\u6570\u624D\u53EF\u6BD4\uFF09\n#   backend: local_bge\n#   local_model: Xenova/bge-base-zh-v1.5    # \u5FC5\u987B\u662F ONNX \u4ED3\u5E93\n#   dim: 768\n#   auto_download: true\n#   \u26A0\uFE0F cache_dir / mirror \u7531\u5BB6\u65CF\u5E95\u5EA7 @avantf/dsh-plugin-base \u7BA1\u7406\uFF1A\u5199\u5728\u8FD9\u91CC\u4F1A\u88AB\u5FFD\u7565\u5E76\u544A\u8B66\u3002\n#      \u7F13\u5B58\u76EE\u5F55\u7528\u73AF\u5883\u53D8\u91CF AVANTF_MEM_MODEL_CACHE\uFF0C\u955C\u50CF\u7528 AVANTF_MEM_MODEL_MIRROR\uFF08\u6216 HF_ENDPOINT\uFF09\u3002\n\n# rerank:                             # \u91CD\u6392\u7684\u552F\u4E00\u5F00\u5173\uFF1Bnone = \u4E0D\u52A0\u8F7D\u4EFB\u4F55\u91CD\u6392\u6A21\u578B\n#   backend: none\n#   local_model: Xenova/bge-reranker-base\n\n# vectorStore:\n#   backend: auto                     # auto = \u8D8A\u8FC7\u9608\u503C\u81EA\u52A8\u4ECE local_numpy \u8FC1\u5230 hnswlib\n#   auto_thresholds:\n#     hnswlib: 2000\n#   hnswlib_ef_search: 256            # ANN \u7684\u53EC\u56DE/\u901F\u5EA6\u65CB\u94AE\uFF0C\u8BED\u6599\u53D8\u5927\u5148\u8C03\u5B83\n\n# retriever:                          # \u4E09\u6761\u68C0\u7D22\u817F\u5728\u878D\u5408\u91CC\u7684\u6743\u91CD\u4E0E\"\u76F8\u5173\u6027\u95E8\u69DB\"\n#   weight_semantic: 0.55\n#   weight_fts: 0.30\n#   weight_jaccard: 0.15\n#   # \u7EDD\u5BF9\u95E8\u69DB\u6253\u5728\u6BCF\u6761\u817F\u7684\u539F\u59CB\u5206\u4E0A\u3001fuse() \u4E4B\u524D\uFF08\u878D\u5408\u5206\u53EA\u5728\u4E00\u6B21\u67E5\u8BE2\u5185\u53EF\u6BD4\uFF0C\u4E0D\u80FD\u5F53\u95E8\u69DB\uFF09\u3002\n#   # 0 = \u5173\u95ED\u8BE5\u95E8\u69DB\uFF1B\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\u3002\u8BED\u4E49\u540E\u7AEF\u4E0D\u53EF\u7528\u65F6 min_fts_terms \u7684\u751F\u6548\u503C\u653E\u5BBD\u5230 1\u3002\n#   min_semantic_similarity: 0.5      # \u8BED\u4E49\u817F\u4F59\u5F26\uFF1B0.5 \u53EA\u5BF9 bge-base-zh-v1.5/768\uFF08mean pooling\uFF09\u6807\u5B9A\u8FC7\uFF0C\u6362\u6A21\u578B\u8981\u91CD\u6807\n#   min_fts_terms: 2                  # FTS \u817F\uFF1A\u8FD9\u4E00\u884C\u547D\u4E2D\u51E0\u4E2A\u4E0D\u540C\u7684\u67E5\u8BE2\u8BCD\u5143\uFF08\u62C9\u4E01\u8BCD\u22655\u5B57\u7B26 + CJK 3-gram\uFF09\n#   min_jaccard: 0.2                  # \u5B9E\u4F53\u817F Jaccard \u6BD4\u503C\n\n# lifecycle:\n#   purge_after_archived_days: 365    # \u5F52\u6863\u4E8B\u5B9E\u7684\u7269\u7406\u6E05\u7406\u7A97\u53E3\uFF08\u6D3B\u8DC3\u65E5\uFF09\n#   contradiction_threshold: 0.6\n\n# trust:\n#   decay_per_day: 0.0055\u2026\n#   presence:\n#     heartbeat_minutes: 60           # \u5E38\u9A7B\u8FDB\u7A0B\u7684\u5FC3\u8DF3\uFF08\u6D3B\u8DC3\u65E5\u65F6\u949F\u4E0E\u751F\u547D\u5468\u671F\u626B\u63CF\uFF09\n\n# tools:                              # \u5916\u90E8\u4E8C\u8FDB\u5236\uFF08pandoc\uFF09\u7684\u53D7\u7BA1\u76EE\u5F55\n#   dir: ''                           # \u7559\u7A7A = \u5BB6\u65CF\u6839 tools\uFF08~/.avantf/env/tools\uFF09\uFF1BAVANTF_TOOLS_DIR \u53EF\u8986\u76D6\n#   auto_install: true\n";
+export declare const DEFAULT_COMMON_CONFIG = "# avantf-mem \u516C\u5171\u914D\u7F6E\uFF08\u5206\u5C42\u7B2C\u2461\u5C42\uFF09\u3002\u8FD9\u91CC\u5168\u662F\u6CE8\u91CA\uFF1A\u5220\u6389/\u7559\u7A7A = \u7528\u5185\u5EFA\u9ED8\u8BA4\uFF0C\u53D6\u6D88\u6CE8\u91CA\u5373\u751F\u6548\u3002\n# \u5206\u5C42\uFF08\u4F4E\u2192\u9AD8\uFF09\uFF1A\u2460 \u5185\u5EFA\u9ED8\u8BA4 \u2192 \u2461 \u672C\u6587\u4EF6 \u2192 \u2462 \u540C\u76EE\u5F55\u7684 memory.yaml / knowledge.yaml\uFF08\u7F3A\u5931=\u4E0D\u8986\u76D6\uFF09\n#               \u2192 \u2463 \u73AF\u5883\u53D8\u91CF \u2192 \u2464 \u63D2\u4EF6/CLI \u663E\u5F0F\u4F20\u53C2\n# \u6240\u6709\u53EF\u7F16\u8F91\u6587\u672C\u90FD\u5728 ~/.avantf \u4E0B\uFF1Aconfigs/*.yaml\uFF08\u672C\u76EE\u5F55\uFF09\u4E0E prompts/*.md\uFF08\u6A21\u578B\u63D0\u793A\u8BCD\uFF09\u3002\n\n# \u6570\u636E\u6839\u4E0D\u5728\u8FD9\u91CC\u914D\uFF1A\u5B83\u7531 \u2463 AVANTF_HOME\uFF08\u6216 CLI --data-home\u3001\u63D2\u4EF6 profile \u7684 dataHome\uFF09\u51B3\u5B9A \u2014\u2014\n# \u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u7684\u65F6\u5019\u8FD8\u6CA1\u8BFB\u5230\u5B83\uFF0C\u6240\u4EE5\u5199\u5728\u8FD9\u91CC\u7684 dataHome \u5BF9\u6570\u636E\u6839\u65E0\u6548\uFF08DESIGN \u00A73\uFF09\u3002\n\n# semantic:                           # \u5D4C\u5165\u540E\u7AEF\uFF08\u8BB0\u5FC6\u4E0E\u77E5\u8BC6\u5171\u7528\uFF0C\u8DE8\u5E93\u5206\u6570\u624D\u53EF\u6BD4\uFF09\n#   backend: local_bge\n#   local_model: Xenova/bge-base-zh-v1.5    # \u5FC5\u987B\u662F ONNX \u4ED3\u5E93\n#   dim: 768\n#   auto_download: true\n#   auto_migrate: true                # \u6362\u6A21\u578B/\u5BBD\u5EA6\u540E\u81EA\u52A8\u5206\u6279\u91CD\u7B97\u65E7\u7A7A\u95F4\u7684\u5411\u91CF\uFF08\u9ED8\u8BA4\u5F00\uFF09\uFF1B\u5173\u6389\u53EA\u5269\u542F\u52A8\u544A\u8B66 + vectors --fix\n#   \u26A0\uFE0F cache_dir / mirror \u7531\u5BB6\u65CF\u5E95\u5EA7 @avantf/dsh-plugin-base \u7BA1\u7406\uFF1A\u5199\u5728\u8FD9\u91CC\u4F1A\u88AB\u5FFD\u7565\u5E76\u544A\u8B66\u3002\n#      \u7F13\u5B58\u76EE\u5F55\u7528\u73AF\u5883\u53D8\u91CF AVANTF_MEM_MODEL_CACHE\uFF0C\u955C\u50CF\u7528 AVANTF_MEM_MODEL_MIRROR\uFF08\u6216 HF_ENDPOINT\uFF09\u3002\n\n# vectorStore:\n#   backend: auto                     # auto = \u8D8A\u8FC7\u9608\u503C\u81EA\u52A8\u4ECE local_numpy \u8FC1\u5230 hnswlib\n#   auto_thresholds:\n#     hnswlib: 2000\n#   hnswlib_ef_search: 256            # ANN \u7684\u53EC\u56DE/\u901F\u5EA6\u65CB\u94AE\uFF0C\u8BED\u6599\u53D8\u5927\u5148\u8C03\u5B83\n\n# retriever:                          # \u4E09\u6761\u68C0\u7D22\u817F\u5728\u878D\u5408\u91CC\u7684\u6743\u91CD\u4E0E\"\u76F8\u5173\u6027\u95E8\u69DB\"\n#   weight_semantic: 0.55\n#   weight_fts: 0.30\n#   weight_jaccard: 0.15\n#   # \u7EDD\u5BF9\u95E8\u69DB\u6253\u5728\u6BCF\u6761\u817F\u7684\u539F\u59CB\u5206\u4E0A\u3001fuse() \u4E4B\u524D\uFF08\u878D\u5408\u5206\u53EA\u5728\u4E00\u6B21\u67E5\u8BE2\u5185\u53EF\u6BD4\uFF0C\u4E0D\u80FD\u5F53\u95E8\u69DB\uFF09\u3002\n#   # 0 = \u5173\u95ED\u8BE5\u95E8\u69DB\uFF1B\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\u3002\u8BED\u4E49\u540E\u7AEF\u4E0D\u53EF\u7528\u65F6 min_fts_terms \u7684\u751F\u6548\u503C\u653E\u5BBD\u5230 1\u3002\n#   min_semantic_similarity: 0.5      # \u8BED\u4E49\u817F\u4F59\u5F26\uFF1B0.5 \u53EA\u5BF9 bge-base-zh-v1.5/768\uFF08mean pooling\uFF09\u6807\u5B9A\u8FC7\uFF0C\u6362\u6A21\u578B\u8981\u91CD\u6807\n#   min_fts_terms: 2                  # FTS \u817F\uFF1A\u8FD9\u4E00\u884C\u547D\u4E2D\u51E0\u4E2A\u4E0D\u540C\u7684\u67E5\u8BE2\u8BCD\u5143\uFF08\u62C9\u4E01\u8BCD\u22655\u5B57\u7B26 + CJK 3-gram\uFF09\n#   min_jaccard: 0.2                  # \u5B9E\u4F53\u817F\uFF1A\u951A\u70B9\u5B9E\u4F53\u7684 Jaccard\uFF08\u4E8B\u5B9E\u5BBD\u5EA6\u9971\u548C\uFF09\uFF1B2 \u5B9E\u4F53\u547D\u4E2D 1 \u4E2A\u6B63\u597D 0.2\n#   # P-11 \u4E2D\u6587\u65F6\u95F4\u7A97\u817F\uFF08\u9ED8\u8BA4\u5173\uFF09\uFF1A\u5F00\u542F\u540E\uFF0C\u5E26\u4E2D\u6587\u65F6\u95F4\u8868\u8FBE\u7684\u67E5\u8BE2\uFF08\u4E0A\u4E2A\u6708 / \u6700\u8FD1\u4E09\u5929 / 2026\u5E749\u6708 \u2026\uFF09\n#   # \u4F1A\u989D\u5916\u628A\"\u4E8B\u4EF6\u65F6\u95F4 valid_from \u843D\u5728\u8BE5\u7A97\u53E3\"\u7684\u6D3B\u8DC3\u4E8B\u5B9E\u4F5C\u4E3A\u4E00\u6761\u817F\u53C2\u4E0E\u878D\u5408\u3002\u5B83\u662F**\u52A0\u4E00\u6761\u817F\u3001\u4E0D\u662F\u8FC7\u6EE4\u5668**\uFF1A\n#   # \u53EA\u589E\u52A0\u5019\u9009\uFF0C\u7EDD\u4E0D\u5220\u6389\u8BED\u4E49 / FTS / \u5B9E\u4F53\u817F\u5DF2\u7ECF\u627E\u5230\u7684\u4E8B\u5B9E\uFF1B\u6CA1\u6709\u4E8B\u4EF6\u65F6\u95F4\u7684\u4E8B\u5B9E\u4E0D\u4F5C\u4E3A\u8BE5\u817F\u5019\u9009\uFF0C\n#   # \u4E5F**\u4E0D\u56DE\u9000\u5230\u5199\u5165\u65F6\u95F4 created_at**\u3002\u5B83\u5171\u7528 jaccard \u6743\u91CD\u4F4D\uFF08\u5BF9\u5916\u7684\u4E09\u952E\u6743\u91CD\u4E0D\u53D8\uFF09\u3002\n#   # \u4EC0\u4E48\u65F6\u5019\u8BE5\u5F00\uFF1A\u5148\u7528 mem_admin stats \u770B validity.coverage\uFF08\u6709\u591A\u5C11\u6D3B\u8DC3\u4E8B\u5B9E\u5E26\u4E8B\u4EF6\u65F6\u95F4\uFF09\uFF0C\n#   # \u518D\u7528\u56DE\u5F52\u7F51\u786E\u8BA4\u5B83\u786E\u5B9E\u6539\u5584\u65F6\u95F4\u7C7B\u67E5\u8BE2\u2014\u2014\u8986\u76D6\u7387\u22480 \u65F6\u5B83\u7B49\u4E8E\u6CA1\u5F00\u3002\u5199\u5165\u4E8B\u4EF6\u65F6\u95F4\u7528 mem_remember \u7684 event_date\u3002\n#   time_window: false\n\n# lifecycle:\n#   purge_after_archived_days: 365    # \u5F52\u6863\u4E8B\u5B9E\u7684\u7269\u7406\u6E05\u7406\u7A97\u53E3\uFF08\u6D3B\u8DC3\u65E5\uFF09\n#   contradiction_threshold: 0.6\n\n# trust:\n#   decay_per_day: 0.0055\u2026\n#   presence:\n#     heartbeat_minutes: 60           # \u5E38\u9A7B\u8FDB\u7A0B\u7684\u5FC3\u8DF3\uFF08\u6D3B\u8DC3\u65E5\u65F6\u949F\u4E0E\u751F\u547D\u5468\u671F\u626B\u63CF\uFF09\n\n# tools:                              # \u5916\u90E8\u4E8C\u8FDB\u5236\uFF08pandoc\uFF09\u7684\u53D7\u7BA1\u76EE\u5F55\n#   dir: ''                           # \u7559\u7A7A = \u5BB6\u65CF\u6839 tools\uFF08~/.avantf/env/tools\uFF09\uFF1BAVANTF_TOOLS_DIR \u53EF\u8986\u76D6\n#   auto_install: true\n";
 /**
  * Ensure the common config exists with content, and hand back the path either way.
  *

package/lib/engine/mem/db/dao/chunks.d.ts

@@ -140,11 +140,30 @@ export declare class ChunksDao {
      * the cap makes `scores.size === legCap` — the "was this leg trimmed" signal — report the opposite
      * of the truth. (The memory store's sibling does not batch, so its single `LIMIT` is already exact.)
      */
-    candidatesByEntityNames(names: readonly string[], domain: string | undefined, source: string | undefined, limit: number): number[];
+    candidatesByEntityNames(names: readonly string[], domain: string | undefined, source: string | undefined, limit: number, queryWidth: number, widthCap: number): number[];
+    /**
+     * How many chunks carry each name — the knowledge side of the entity leg's document frequency.
+     *
+     * Mirrors `EntitiesDao.activeDocFrequency`: only the caller's query names are looked up. There is
+     * no status column to filter on (see `candidatesByEntityNames`), so "document frequency" is over
+     * all chunks, which is the population the leg ranks.
+     */
+    docFrequency(names: readonly string[]): Map<string, number>;
     /** FTS leg (`bm25` rank; negated by the caller so higher = better). */
     ftsSearch(ftsQuery: string, domain?: string, source?: string, limit?: number): {
         id: number;
         rank: number;
     }[];
+    /**
+     * The knowledge store's SHORT-QUERY fallback leg — the sibling of `FactsDao.ftsSubstringSearch`
+     * (see it for the score/tie/verify notes; the predicate itself is shared through
+     * `db/tokenizer.ts#likeSubstring`). It reads `doc_chunks` directly rather than the external-content
+     * FTS table: no index can serve a two-character pattern anyway, and the `documents` join is where
+     * the domain/source filter lives.
+     */
+    ftsSubstringSearch(terms: readonly string[], domain?: string, source?: string, limit?: number): {
+        id: number;
+        rank: number;
+    }[];
 }
 export {};

package/lib/engine/mem/db/dao/entities.d.ts

@@ -7,16 +7,23 @@
  * contradiction detection (see `db/chunk.ts`).
  */
 import type { Db } from '../port.js';
+import type { ExtractedEntity } from '../../entities/extract.js';
 export declare class EntitiesDao {
     private readonly db;
     constructor(db: Db);
     /**
-     * Ensure every name exists and link the fact to them.
+     * Ensure every entity exists (with the extractor's `type` / `method`) and link the fact to it.
      *
      * `INSERT OR IGNORE` + the `name` uniqueness make this idempotent, which matters because
      * both `add` and the revive branch of `persistFact` call it for the same fact.
+     *
+     * FIRST WRITE WINS for `entity_type` / `extraction_method`: a name already in the vocabulary
+     * keeps the type/method of whichever write introduced it (`INSERT OR IGNORE` skips the row),
+     * so an old row is never rewritten by a later fact that happens to share the name. That is the
+     * documented trade-off of not bumping `ENTITY_EXTRACTOR_VERSION` — new entities get real
+     * values, pre-existing ones keep theirs.
      */
-    linkFact(factId: number, names: readonly string[]): void;
+    linkFact(factId: number, entities: readonly ExtractedEntity[]): void;
     /**
      * Drop one fact's links, leaving the shared `entities` vocabulary alone.
      *
@@ -32,6 +39,16 @@ export declare class EntitiesDao {
     bagsForFacts(ids: readonly number[]): Map<number, string[]>;
     /** How many entities a fact is linked to — the scorer's `|A|`. */
     countForFact(factId: number): number;
+    /**
+     * How many ACTIVE facts carry each name — the entity leg's document frequency.
+     *
+     * The anchor filter (`store/entity_leg.ts`) needs it to drop corpus-wide words from a query's
+     * evidence: a name carried by ~half the store is not discriminative, and treating it as an anchor
+     * would make the entity leg drag the whole store in. Only the caller's QUERY names are looked up
+     * (a handful), so this is one indexed COUNT per name, not a corpus scan. A name absent from the
+     * map has frequency 0, i.e. no active fact carries it and it can never be shared.
+     */
+    activeDocFrequency(names: readonly string[]): Map<string, number>;
     /**
      * Candidate facts for the embedding leg, narrowed by the scorer's NECESSARY conditions
      * (see {@link ContradictDetector}): at least `minShared` shared entities and at most
@@ -48,20 +65,27 @@ export declare class EntitiesDao {
     activeFactsForEntity(name: string, category?: string): number[];
     /** Active facts linked to ALL of `names` (AND-join, `reason` leg). */
     activeFactsForAllEntities(names: readonly string[]): number[];
-    /** Active facts sharing ANY of `names`, in one category (`jaccard` leg). */
+    /** Active facts sharing ANY of `names`, in one category (the entity leg). */
     /**
-     * Candidate facts for an entity-Jaccard query, ordered by the ACTUAL Jaccard and CAPPED.
+     * Candidate facts for an entity query, ordered by the leg's score and CAPPED.
      *
      * The cap is the whole point: this leg used to return every fact sharing ANY query entity —
      * unbounded in the corpus (measured 6600 rows for a common phrase at 33k facts, and the fusion
      * step then normalized and sorted all of them).
      *
-     * Ordering by the shared COUNT alone (the first version of this cap) was WRONG: the leg's score
-     * is `shared / union`, so a fact sharing 3 of 10 entities (0.30) outranked one sharing 2 of 2
-     * (0.67) and pushed it out of the cap — measured: dropping the higher-scoring document. The
-     * ratio is computed in SQL instead: `union = |q| + |f| - shared`, and `|f|` is one indexed COUNT
-     * per candidate (the `fact_entities` primary key covers it). The caller still recomputes the same
-     * ratio in JS for the survivors, which is cheap (<= the cap) and keeps one formula in charge.
+     * The ordering must be the leg's own score order, or the cap drops the best rows: `fuse` scales
+     * by each leg's maximum, and a survivor's scaled value is unchanged only when the ordering (and
+     * therefore the maximum) survives the trim. The leg scores anchored Jaccard with a saturating
+     * union (`store/entity_leg.ts`): `shared / (queryWidth + min(total - shared, widthCap))`, where `queryWidth` is the
+     * query's FULL entity count and `names` is its anchors. That ratio — not the raw shared count — is what this orders by, because a
+     * narrower fact sharing one entity can outrank a wide one sharing two. `total ASC` is only a
+     * deterministic tie-break among equal ratios. The caller still recomputes the score in JS for the
+     * survivors, so one formula stays in charge.
+     */
+    candidateFactsForAnyEntity(names: readonly string[], category: string | undefined, limit: number, queryWidth: number, widthCap: number, 
+    /**
+     * P-08 provenance filter (`fact_sources.ref`). `EXISTS`, never a JOIN: a fact with several
+     * sources would fan out into several rows and eat the leg's `LIMIT`, silently shrinking recall.
      */
-    candidateFactsForAnyEntity(names: readonly string[], category: string | undefined, limit: number): number[];
+    source?: string): number[];
 }

package/lib/engine/mem/db/dao/fact_sources.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `fact_sources` — where a memory fact came from (P-08).
+ *
+ * One row per `(fact_id, kind, ref)`. `kind` is a closed vocabulary (`session` / `kb_doc` /
+ * `tool` / `manual`) so a reader can trust what a reference IS; `ref` is opaque to this layer
+ * (a session id, a document id, a tool name, or a free-form note).
+ *
+ * The SQL lives here like every other aggregate. The store decides WHICH source a write carries
+ * (and refuses to invent one when the caller gave none); the DAO only records and reads rows.
+ */
+import type { Db } from '../port.js';
+/** The closed `kind` vocabulary, spelled once so the store and the tests share it. */
+export declare const FACT_SOURCE_KINDS: readonly ["session", "kb_doc", "tool", "manual"];
+export type FactSourceKind = (typeof FACT_SOURCE_KINDS)[number];
+/** One provenance row as the read surfaces render it. */
+export interface FactSource {
+    kind: FactSourceKind;
+    ref: string;
+}
+/**
+ * Derive `(kind, ref)` from the single `source_ref` the write face accepts.
+ *
+ * The tool takes ONE string (the plan adds no second parameter), so the kind axis is spelled by a
+ * `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else is `manual` with the
+ * reference kept VERBATIM. No shape guessing: a bare `domain:source:title` becomes a `manual`
+ * source whose ref is exactly what the caller wrote, which is strictly more honest than inventing
+ * a category from how the string looks.
+ */
+export declare function classifySourceRef(sourceRef: string): {
+    kind: FactSourceKind;
+    ref: string;
+};
+export declare class FactSourcesDao {
+    private readonly db;
+    constructor(db: Db);
+    /**
+     * Record one source on one fact. Idempotent by the composite PRIMARY KEY: a repeated write of
+     * the same `(kind, ref)` is a no-op, so a caller can safely re-assert provenance.
+     */
+    insert(factId: number, kind: FactSourceKind, ref: string): void;
+    /** The sources of one fact; empty when no `source_ref` was ever given. */
+    listForFact(factId: number): FactSource[];
+    /**
+     * Coverage over the ACTIVE corpus: how many active facts carry at least one source.
+     *
+     * The `EXISTS` (rather than `COUNT(DISTINCT)` over a join) keeps the numerator cheap and — more
+     * importantly — makes "a fact with three sources" count once, which is what coverage means.
+     */
+    activeCoverage(): {
+        active: number;
+        facts_with_source: number;
+    };
+}

package/lib/engine/mem/db/dao/facts.d.ts

@@ -7,7 +7,8 @@
  */
 import type { Db } from '../port.js';
 /**
- * Every `facts` column EXCEPT the two BLOBs (`hrr_vector` ~8 KB, `semantic_vector` ~2 KB per row).
+ * Every `facts` column EXCEPT the two BLOBs (`hrr_vector` ~8 KB, `semantic_vector` ~2 KB per row)
+ * and the two DEPRECATED provenance columns (`mirror_source` / `mirror_target`, see below).
  *
  * Multi-row reads that only need scalars used to be `SELECT *`, so a page of the admin list and
  * every recall's trust settlement dragged the whole vector corpus through the driver — tens of
@@ -17,10 +18,15 @@ import type { Db } from '../port.js';
  * `getById` deliberately still selects everything: `restore` re-indexes the persisted vector it
  * reads off that one row.
  *
- * `test/db_lifecycle.spec.ts` asserts this list against `PRAGMA table_info(facts)`, so a new column
- * fails a test instead of silently vanishing from these two reads.
+ * `mirror_source` was written as the constant `'user'` at the single INSERT below and
+ * `mirror_target` never had a writer; neither had a reader left once the model-facing views
+ * dropped them (零迁移：the COLUMNS stay in `db/schema.ts` for a later migration to clean up,
+ * only this projection and the INSERT stop touching them).
+ *
+ * `test/db_lifecycle.spec.ts` asserts this list against `PRAGMA table_info(facts)` MINUS those
+ * two deprecations, so a new column fails a test instead of silently vanishing from these reads.
  */
-export declare const FACT_COLUMNS_NO_BLOB = "fact_id, content, category, tags, trust_score, settle_clock,\n    pinned, pinned_at, bonus_count, bonus_window_at, last_reinforced_at, archived_clock,\n    retrieval_count, helpful_count, last_retrieved_at, embedding_model, vector_store, status,\n    supersedes_id, entities_version, conflict_checked, archived_at, archive_reason, ttl_days,\n    mirror_source, mirror_target, created_at, updated_at";
+export declare const FACT_COLUMNS_NO_BLOB = "fact_id, content, category, tags, trust_score, settle_clock,\n    pinned, pinned_at, bonus_count, bonus_window_at, last_reinforced_at, archived_clock,\n    retrieval_count, helpful_count, last_retrieved_at, embedding_model, vector_store, status,\n    supersedes_id, entities_version, conflict_checked, archived_at, archive_reason, ttl_days,\n    valid_from, valid_to, assert_count, created_at, updated_at";
 /**
  * The FTS leg's exact SQL, exported so the plan guard (`test/fts_plan.spec.ts`) and the bench
  * control group EXPLAIN the production text itself instead of a copy that can silently drift.
@@ -53,6 +59,21 @@ export declare const FACT_COLUMNS_NO_BLOB = "fact_id, content, category, tags, t
  * `INDEXED BY`, which pins the plan against `PRAGMA optimize` flipping it back.
  */
 export declare const FTS_SEARCH_SQL = "SELECT f.rowid AS id, bm25(facts_fts) AS rank FROM facts_fts f\n         JOIN facts fa NOT INDEXED ON fa.fact_id = f.rowid\n         WHERE facts_fts MATCH ? AND fa.status = 'active' AND (? IS NULL OR fa.category = ?)\n         ORDER BY rank ASC\n         LIMIT ?";
+/**
+ * {@link FTS_SEARCH_SQL} with the P-08 source predicate, as a SEPARATE statement rather than one
+ * more `(? IS NULL OR …)` branch in the shared text.
+ *
+ * The unfiltered statement's query plan is guarded by `test/fts_plan.spec.ts` (the external-content
+ * MATCH must not become the inner loop on a fresh, un-analyzed database), and the guard EXPLAINs
+ * `FTS_SEARCH_SQL` itself. Keeping the two texts apart means the default path's plan is provably
+ * unchanged, and the filtered path is a NEW statement with its own comment instead of a silent
+ * modification of the guarded one.
+ *
+ * `EXISTS`, never a JOIN on `fact_sources`: a fact with several sources would fan out into several
+ * rows, and this leg is `ORDER BY bm25 … LIMIT cap` — the duplicates would eat cap slots and shrink
+ * recall behind the caller's back.
+ */
+export declare const FTS_SEARCH_SQL_FILTERED = "SELECT f.rowid AS id, bm25(facts_fts) AS rank FROM facts_fts f\n         JOIN facts fa NOT INDEXED ON fa.fact_id = f.rowid\n         WHERE facts_fts MATCH ? AND fa.status = 'active' AND (? IS NULL OR fa.category = ?)\n           AND (? IS NULL OR EXISTS (\n                 SELECT 1 FROM fact_sources fs WHERE fs.fact_id = fa.fact_id AND fs.ref = ?\n               ))\n         ORDER BY rank ASC\n         LIMIT ?";
 export declare class FactsDao {
     private readonly db;
     constructor(db: Db);
@@ -89,10 +110,12 @@ export declare class FactsDao {
     rowsByIds(ids: readonly number[]): Record<string, unknown>[];
     /** `fact_id → content` for a hit set (never N+1). */
     textsByIds(ids: readonly number[]): Map<number, string>;
-    /** `fact_id → created_at/updated_at` for a hit set (the recall hit's two timestamps). */
+    /** `fact_id → created_at/updated_at/validity` for a hit set (the recall hit's timestamps). */
     timesByIds(ids: readonly number[]): Map<number, {
         created_at: string;
         updated_at: string | null;
+        valid_from: string | null;
+        valid_to: string | null;
     }>;
     /** Active rows that carry a persisted vector (index classification). */
     activeVectorRows(): {
@@ -100,6 +123,18 @@ export declare class FactsDao {
         semantic_vector: Uint8Array;
         embedding_model: string | null;
     }[];
+    /**
+     * Width + recorded space of every ACTIVE persisted vector, WITHOUT reading the bytes.
+     *
+     * `length(blob)` is the byte count, so `bytes / 4` is the float width — enough to detect a
+     * changed `semantic.dim` without decoding a corpus. This is the cheap detection the startup
+     * warning and the `/mem` status surface read (see `MemoryStore.vectorSpaceHealth`).
+     */
+    activeVectorSpaces(): {
+        fact_id: number;
+        bytes: number;
+        embedding_model: string | null;
+    }[];
     /**
      * Facts per archive reason — the trust diagnostics breakdown. One grouped scan rather than
      * a count per reason, because the reasons are few but the table is not.
@@ -137,10 +172,75 @@ export declare class FactsDao {
         pinnedAt: string | null;
         windowAt: string;
         createdAt: string;
+        /**
+         * P-13: the caller's event time / known end, written straight onto the new row. `null` means
+         * "unknown" and is what an omitted argument leaves (the column has no default on purpose).
+         * `assert_count` is deliberately NOT named: the column default (1) is the semantics — "this
+         * content has been asserted once" — and naming it here would be a second place to keep in step.
+         */
+        validFrom?: string | null;
+        validTo?: string | null;
     }): {
         changes: number;
         lastInsertRowid: number | bigint;
     };
+    /**
+     * P-10: land an explicitly given validity on a row that already exists (a duplicate `add` whose
+     * caller named `event_date` / `valid_until`). Omitted arguments keep what the row has, exactly
+     * like `category`/`ttl_days` (see `add`'s doc).
+     */
+    applyValidity(factId: number, validFrom: string | undefined, validTo: string | undefined): void;
+    /** P-10: the row's assertion counter (`1` when the column is somehow NULL on a legacy row). */
+    assertCount(factId: number): number;
+    /**
+     * P-10: a verbatim re-assertion of an EXISTING active fact. Returns the new count.
+     *
+     * Only the pure-duplicate branch calls this: reviving an archived row is a resurrection, not a
+     * new assertion (`assert_count` answers "how many times was this said", and the archived row's
+     * own count already recorded that). `RETURNING` keeps the read and the write one statement, so
+     * two processes cannot interleave between them.
+     */
+    incrementAssertCount(factId: number): number;
+    /**
+     * P-07 audit: stamp `valid_to` on a row that is leaving the active corpus (supersede / a
+     * contradiction verdict). `COALESCE` keeps an end the caller already declared (`valid_until`):
+     * overwriting it with the archival instant would replace a real answer with an administrative one.
+     */
+    markValidTo(factId: number, at: string): void;
+    /**
+     * P-07: "who superseded this fact", derived from the existing `supersedes_id` link — no
+     * redundant column. `MIN` is deterministic when several revisions named the same predecessor
+     * (which a merge can produce); the caller renders it as a single direct successor.
+     */
+    supersededBy(factId: number): number | null;
+    /** P-13 coverage: ACTIVE facts that carry an event time (the `admin stats` numerator). */
+    countActiveWithValidFrom(): number;
+    /**
+     * P-11: the ids of ACTIVE facts whose EVENT time (`valid_from`) falls inside an INCLUSIVE local
+     * day range, newest first, capped.
+     *
+     * The comparison is on the DATE PREFIX (`substr(valid_from, 1, 10)`) rather than on the raw text:
+     * `valid_from` is whatever ISO string the caller wrote (`2026-09-15` or
+     * `2026-09-15T09:30:00+08:00`), and a lexicographic range over the full strings would put a
+     * midnight timestamp on the wrong side of a day boundary. Day granularity is the unit the window
+     * parser speaks (`store/time_window.ts`), so `substr` is the matching one. No index can serve it;
+     * the leg is default-OFF and capped, and a full scan of `facts` for one enabled query is the
+     * accepted cost (see the leg's own comment).
+     *
+     * The `GLOB` is a SHAPE guard, not decoration: the prefix is compared LEXICOGRAPHICALLY, so a
+     * non-padded `2026-9-5` (which `Date.parse` accepts, so `normalizeEventTime` stores it) would sort
+     * AFTER `2026-09-30` and leak into an October window. Requiring the canonical zero-padded prefix
+     * excludes such a value from the leg entirely — the same "no usable event time" treatment, never a
+     * mis-binned one.
+     *
+     * `valid_from IS NOT NULL` is the P-11 discipline written into SQL: a fact with no event time is
+     * NOT a candidate here, and there is deliberately no `COALESCE(valid_from, created_at)` fallback —
+     * mixing a write clock into an event-time axis is exactly what this leg must not do.
+     *
+     * `EXISTS`, never a JOIN on `fact_sources` (the {@link FTS_SEARCH_SQL_FILTERED} rule): the cap is
+     * `LIMIT`, and a multi-source fact would eat cap slots with duplicate rows.
+     */
+    windowRows(fromDate: string, toDate: string, category: string | undefined, cap: number, source?: string): number[];
     findByContent(content: string): Record<string, unknown> | undefined;
     /**
      * ACTIVE facts whose entity/triple rows were produced by OLDER extraction rules.
@@ -271,8 +371,8 @@ export declare class FactsDao {
      *    index in order and filter per row (measured 9.8 ms for a category with 17 rows at 33k),
      *    i.e. it would trade a fast path for a slow one to save an index we do not need.
      */
-    page(status: string, category: string | undefined, limit: number, offset: number): Record<string, unknown>[];
-    countInStatus(status: string, category?: string): number;
+    page(status: string, category: string | undefined, limit: number, offset: number, source?: string): Record<string, unknown>[];
+    countInStatus(status: string, category?: string, source?: string): number;
     /** Every ACTIVE fact (the report's `active`). */
     countActive(): number;
     /** ACTIVE and permanent — pinned facts are exempt from decay (the report's `pinned`). */
@@ -332,7 +432,7 @@ export declare class FactsDao {
      * facts with a cap of 200 it silently made 32.8k of them unreachable. Recency is the honest
      * prior for a memory store and `idx_facts_created(status, created_at DESC)` already serves it.
      */
-    activeHrrRows(category?: string, limit?: number): {
+    activeHrrRows(category?: string, limit?: number, source?: string): {
         fact_id: number;
         hrr_vector: Uint8Array;
     }[];
@@ -344,12 +444,12 @@ export declare class FactsDao {
      * which is the same information the HRR bundle encodes (its atoms ARE the entity names), so the
      * narrowing removes the O(N) part rather than a meaningful part of the ranking.
      */
-    hrrRowsForFacts(ids: readonly number[], category?: string): {
+    hrrRowsForFacts(ids: readonly number[], category?: string, source?: string): {
         fact_id: number;
         hrr_vector: Uint8Array;
     }[];
-    /** ACTIVE subset of `ids` in one category (`null` = any) — the semantic leg's filter. */
-    activeIdsIn(ids: readonly number[], category?: string): number[];
+    /** ACTIVE subset of `ids` in one category/source (`null` = any) — the semantic leg's filter. */
+    activeIdsIn(ids: readonly number[], category?: string, source?: string): number[];
     /** `retrieval_count` + the "last used" clock (spec §2.5), batched. */
     touchUsage(ids: readonly number[]): void;
     /** Recall bonus not granted: only the settled trust moved. */
@@ -364,7 +464,22 @@ export declare class FactsDao {
      * that JOIN from becoming the drive (see {@link FTS_SEARCH_SQL}, which carries the plans and
      * measurements).
      */
-    ftsSearch(ftsQuery: string, category?: string, limit?: number): {
+    ftsSearch(ftsQuery: string, category?: string, limit?: number, source?: string): {
+        id: number;
+        rank: number;
+    }[];
+    /**
+     * The SHORT-QUERY fallback leg: rows whose `content` contains at least one of the terms as a
+     * contiguous substring, scored by how many it contains.
+     *
+     * Reached only when `buildFtsQuery` produced nothing (a 2-char CJK query — see
+     * `db/tokenizer.ts#likeSubstring` and `store/lexical.ts`), so it cannot move an indexed query.
+     * `rank` is the number of distinct terms the row contains, which is the same quantity
+     * `applyTermFloor` grades with; ties break on ascending id, matching `fuse`'s own tie rule, so a
+     * single-term query (all ranks 1) has a deterministic order. `ORDER BY rank` must read the SELECT
+     * alias, so the LIKE expressions are built once and bound twice — same fragment, same order.
+     */
+    ftsSubstringSearch(terms: readonly string[], category?: string, limit?: number, source?: string): {
         id: number;
         rank: number;
     }[];

package/lib/engine/mem/db/invariants.d.ts

@@ -0,0 +1,26 @@
+/**
+ * P-07 validity invariants, as SQL an operator (or a test) can run against a database.
+ *
+ * The batch-1 fields are DISPLAY/AUDIT data — no retrieval leg reads them — so nothing in the read
+ * path would notice if a write stopped stamping them. These two statements are the check that
+ * cannot be satisfied vacuously: each has a planted-violation test in
+ * `test/fact_provenance.spec.ts` proving it reports a real inconsistency.
+ *
+ * ① The two SEMANTIC retirement paths (`update`'s supersede and a `true_positive` contradiction
+ *    verdict) archive a fact because it stopped being true. Both must leave an end time, or the
+ *    audit trail says "retired, cause known, end unknown". Lifecycle archival (`ttl` / `forgot` /
+ *    `idle` / `manual`) is deliberately NOT in the set: those are retention decisions, not statements
+ *    about when the fact stopped being true.
+ *
+ * ② A known end cannot precede a known start.
+ */
+import type { Db } from './port.js';
+/** Facts retired by a semantic path (`replaced` / `contradiction`) without a recorded end time. */
+export declare const RETIRED_WITHOUT_VALID_TO_SQL = "SELECT COUNT(*) AS n FROM facts\n  WHERE status = 'archived' AND archive_reason IN ('replaced', 'contradiction') AND valid_to IS NULL";
+/** Rows whose known end precedes their known start. */
+export declare const VALID_TO_BEFORE_VALID_FROM_SQL = "SELECT COUNT(*) AS n FROM facts\n  WHERE valid_from IS NOT NULL AND valid_to IS NOT NULL AND valid_to < valid_from";
+/** Every P-07 invariant, evaluated. All-zero is the healthy state. */
+export declare function validityInvariantViolations(db: Db): {
+    retired_without_valid_to: number;
+    valid_to_before_valid_from: number;
+};