@avantf/dsh-mem 0.4.1 → 0.4.2

package/lib/client.js

@@ -6457,10 +6457,12 @@ 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 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}`));
+			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\``), 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}`));
 		}
 		/**
 		* Group cross-store hits for display: memory facts vs `domain → source`.

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# 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";
 /**
  * Ensure the common config exists with content, and hand back the path either way.
  *

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

@@ -100,6 +100,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.

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

@@ -23,13 +23,19 @@ export declare function vectorSpaceId(backend: string, model: string, dim: numbe
  * The rows come from the owning store's DAO (DESIGN §19): this helper decodes and
  * filters them, it never runs SQL itself.
  *
+ * A row whose width does not fit the store is skipped (never `add()`ed — the store
+ * would throw). The OWNING store reports that condition itself, as one actionable
+ * line with the count, the reason and the manual re-encode entry (`reportStaleVectors`),
+ * so this helper stays quiet: two warnings for one condition read as two problems.
+ *
  * @param rows - `id` (fact/chunk id) + `vec` (BLOB), as read back from the store.
- * @param label - store name used in the dim-mismatch warning.
+ * @param _label - store name; unused here (the owning store owns the warning), kept so call sites read
+ *                 as "which store is reloading".
  */
 export declare function reloadVectorIndex(vstore: VectorStore, rows: readonly {
     id: number;
     vec: Uint8Array | null;
-}[], label: string): {
+}[], _label: string): {
     loaded: number;
     skipped: number;
 };

package/lib/engine/mem/store/common.d.ts

@@ -4,7 +4,7 @@
  * Small on purpose: `MemoryStore` and `KnowledgeStore` are separate stores over separate databases
  * and should stay that way (AGENTS.md). What they must NOT have is two copies of the same
  * three-line helper, because a fix then lands in one of them — which is exactly what happened to the
- * retrieval orchestration (see `store/hybrid.ts`) and to the foreign-vector-space warning below: the
+ * retrieval orchestration (see `store/hybrid.ts`) and to the stale-vector warning below: the
  * memory store checked whether its persisted vectors came from the CURRENT vector space and told the
  * operator how to fix it, while the knowledge store checked only the width, so a model swap left two
  * spaces silently mixed in one index until someone happened to run `kb_reindex`.
@@ -40,19 +40,29 @@ export declare function vectorSpaceOf(semantic: SemanticBackend, model: string):
  */
 export declare function evictVectors(vstore: VectorStore, ids: readonly number[]): void;
 /**
- * Tell the operator that persisted vectors came from ANOTHER vector space.
+ * Tell the operator that persisted vectors came from ANOTHER vector space — loudly, and with the
+ * manual remedy.
  *
- * A dim-valid vector from a different space is still RANKED — the reload cannot tell the difference
- * — so a silent model swap would mix two spaces in one index and degrade every semantic query
- * without an error anywhere. Said once per process; acting on it is the operator's choice because
- * re-encoding is a real cost (and they should see the count first).
+ * Changing the embedding space (model, width, pooling, normalization) is a DATA MIGRATION: the
+ * persisted bytes stay valid-looking but are no longer comparable with the current query vector, so
+ * the semantic leg must not serve them. Measured on the real library after the 512→768 default-model
+ * swap: 78 of 80 ACTIVE facts fell out of the semantic leg and retrieval silently degraded to
+ * lexical+entity (every probe query answered with the same unrelated short fact), with no error
+ * anywhere. The count, the reason and the ONE manual entry have to be visible at start.
+ *
+ * Both halves are reported in one message because they are one condition seen two ways: a changed
+ * WIDTH (`stale`, whose bytes cannot even be decoded into the current store) and a changed SPACE at
+ * the same width (`space_stale`, whose bytes decode but rank in another model's coordinates).
  *
  * @param kind   store label for the message (`memory` / `knowledge`)
  * @param space  the vector space the store writes into now
- * @param foreign how many persisted vectors were written in a different one
- * @param fix    the action that re-encodes them, as the operator would type it
+ * @param counts how many persisted vectors are unusable in the current space, by kind
+ * @param fix    the manual entry that re-encodes them, as the operator would type it
  */
-export declare function reportForeignVectors(kind: string, space: string, foreign: number, fix: string): void;
+export declare function reportStaleVectors(kind: string, space: string, counts: {
+    stale: number;
+    space_stale: number;
+}, fix: string): void;
 /**
  * Hand the event loop back between two synchronous batches.
  *

package/lib/engine/mem/store/floors.d.ts

@@ -52,7 +52,11 @@
  * FTS REACHABILITY. `min_fts_terms` counts distinct query terms a row hits, but a query can only
  * produce so many terms (`relevanceTerms`: latin words ≥5 chars + CJK 3-grams) — a 3-character CJK
  * query yields exactly ONE trigram, so a configured bar of 2 is unreachable and that leg is empty
- * for it by construction. The effective bar is therefore `min(configured, termCount)`.
+ * for it by construction. The effective bar is therefore `min(configured, termCount)`, and
+ * `termCount` is that of the text being GRADED — with 方案 A's augmentation the original and the
+ * rewrite are different texts with different counts, so each resolves its own bar
+ * (`store/hybrid.ts`). Resolving the rewrite from the original's count is the defect that let a
+ * single incidental trigram pass a bar it could not reach (2026-10-04).
  *
  * @module store/floors
  */
@@ -117,16 +121,24 @@ export declare function emptyFloorDrops(): RetrievalFloorDrops;
  * and changing the REPORTED value there would misdescribe what the caller is reading. `0` stays `0`
  * (the operator's off switch).
  *
- * This is the ONE place the clamp lives; `resolveFloors` (what the result reports) and
- * `applyTermFloor` (what the leg does) both call it, so the number the caller reads is the number
- * the leg used.
+ * This is the ONE place the clamp lives; `resolveFloors` (what the result reports / a run is handed)
+ * and `applyTermFloor` (what the leg does) both call it, so the number a run reads is the number its
+ * leg used. It is a `min`, i.e. one-directional: it can LOWER an unreachable configured bar but never
+ * RAISE a bar inherited from another text, which is why the caller must resolve per graded text
+ * rather than reusing one text's resolution for another.
  */
 export declare function effectiveTermFloor(floor: number, termCount?: number): number;
 /** The per-query floor resolution inputs beyond the configuration. */
 export interface FloorResolution {
     /** `loose` lowers each configured floor (see {@link LOOSE_FLOORS}); absent means `strict`. */
     profile?: FloorProfile;
-    /** This query's distinct term count (`relevanceTerms(query).length`), for the FTS clamp. */
+    /**
+     * The distinct term count of the text being GRADED (`relevanceTerms(text).length`), for the FTS
+     * clamp. It must describe the query the legs will actually run on: under 方案 A's augmentation the
+     * rewrite is a DIFFERENT text with its own term count, and resolving both runs from the original's
+     * count is the defect that let one incidental trigram through (see `store/hybrid.ts`). Callers with
+     * several graded texts resolve once per text.
+     */
     termCount?: number;
     /**
      * Which legs a `'loose'` profile may lower, from {@link droppedLegs} of the pass that made the

package/lib/engine/mem/store/memory.d.ts

@@ -1,4 +1,4 @@
-import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type TrustDiagnostic, type VectorsDiagnostic, type VectorsFixReport } from '../../mem-contract/index.js';
+import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type TrustDiagnostic, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixReport } from '../../mem-contract/index.js';
 import type { Reranker, SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
 import type { Db } from '../db/conn.js';
 import { type LexicalProbe } from './lexical.js';
@@ -21,6 +21,16 @@ export type { DetectedContradiction, RememberResult as AddResult } from '../../m
  * until `deferred === 0` instead.
  */
 export declare const ENTITY_SWEEP_BATCH = 2000;
+/**
+ * Rows one background vector-space migration slice may drop + re-encode.
+ *
+ * Small on purpose: the point of batching is that a query arriving mid-migration waits for at most
+ * one ONNX forward pass batch, not for a whole corpus. At ~30 ms per bge-base-zh encode a batch of 16
+ * is well under a second of contested model time, and the event loop is yielded between batches
+ * (`yieldToEventLoop`). The value is a default, not a promise — `migrateVectorsBatch(batchSize)` takes
+ * whatever the caller needs.
+ */
+export declare const DEFAULT_VECTOR_MIGRATION_BATCH = 16;
 /** What one derived-state sweep pass did (see `MemoryStore.reindexEntities`). */
 export interface EntitySweepReport {
     /**
@@ -173,6 +183,16 @@ export declare class MemoryStore {
      * `archive()` evicts and `restore()` re-adds, keeping the invariant.
      */
     private reloadIndex;
+    /**
+     * Cheapest possible DETECTION of "the embedding space changed under this store": counts of ACTIVE
+     * persisted vectors whose width or recorded space id no longer matches the one this store writes
+     * into. Reads blob LENGTHS only — never decodes — so the `/mem` status surface and the startup
+     * warning can afford it at any corpus size.
+     *
+     * The counts are the same two `VectorsDiagnostic` already separates (`stale` / `space_stale`); this
+     * is the read model those surfaces use instead of the full diagnose pass.
+     */
+    vectorSpaceHealth(): VectorSpaceHealth;
     add(content: string, category?: string, ttlDays?: number): Promise<RememberResult>;
     /**
      * Write-path contradiction detection (DESIGN §11): check the fact that was just
@@ -317,7 +337,7 @@ export declare class MemoryStore {
      */
     private classifyVectors;
     /**
-     * Repair the semantic read model:
+     * Repair the semantic read model, in ONE bounded slice or in full:
      *  (a) reload persisted, dim-valid vectors missing from the live index
      *      (restart / index loss — needs no model),
      *  (b) drop persisted vectors whose dim no longer matches `semantic.dim` so a
@@ -325,12 +345,46 @@ export declare class MemoryStore {
      *      throws on dim mismatch),
      *  (c) encode active facts that have no vector yet (needs the semantic backend),
      *  (d) re-encode vectors written in ANOTHER vector space (a model swap, or the one-time
-     *      adoption of a store predating the space id). Deliberately here and not at open: this is
-     *      the only path that re-encodes the whole table, so it is an explicit, counted action.
+     *      adoption of a store predating the space id).
+     *
+     * `limit` is what makes the SAME logic usable as a background migration: at most that many rows are
+     * dropped and at most that many are re-encoded, so one call is a bounded unit of work the caller can
+     * yield between. `vectorsFix` passes no limit (the explicit operator action drains everything);
+     * `migrateVectorsBatch` passes the migration's batch size.
+     */
+    private repairVectors;
+    /**
+     * The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
      * `dry_run` previews every count without writing — and without loading the model, which is why
      * the preview also reports `would_warm` (see the contract's `VectorsFixReport`).
      */
     vectorsFix(dryRun?: boolean): Promise<VectorsFixReport>;
+    /**
+     * ONE bounded slice of the vector-space migration: at most `batchSize` rows are dropped and
+     * re-encoded, so the caller keeps control of the event loop between slices. This is the unit the
+     * background migration ({@link migrateVectors}) and its tests drive.
+     *
+     * Resumability is a property of the DATABASE, not of this process: every slice re-derives what is
+     * stale from the persisted width/space, so a restart simply continues where the last slice stopped.
+     */
+    migrateVectorsBatch(batchSize?: number): Promise<VectorMigrationProgress>;
+    /**
+     * Drive the bounded background migration until the store is current, the model is unavailable, or
+     * `shouldStop()` turns true (plugin unmount / process shutdown). A batch FAILURE never rejects: it is
+     * logged and reported as `remaining > 0`, which is what makes the next heartbeat a retry (the caller
+     * still owns the outer catch for a closed database, e.g. a shutdown racing the first read). Never
+     * blocks the event loop for longer than one batch.
+     *
+     * Honours `semantic.auto_migrate` (default on) — the switch exists so a host that must not spend CPU
+     * on background re-encoding can leave the loud warning and the manual entry as the only path.
+     */
+    migrateVectors(opts?: {
+        batchSize?: number;
+        shouldStop?: () => boolean;
+        onProgress?: (progress: VectorMigrationOutcome) => void;
+    }): Promise<VectorMigrationOutcome>;
+    /** Active rows the semantic leg still cannot use (old width, old space, or no vector at all). */
+    private migrationRemaining;
     /**
      * One lifecycle pass, owned by the store so the DB writes and the live-index
      * invariant (ACTIVE vectors only) are maintained in ONE place — the runtime no

package/lib/engine/mem-contract/config.d.ts

@@ -21,6 +21,7 @@ export declare const ConfigSchema: z.ZodObject<{
         mirror: z.ZodDefault<z.ZodString>;
         cache_dir: z.ZodDefault<z.ZodString>;
         auto_download: z.ZodDefault<z.ZodBoolean>;
+        auto_migrate: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     rerank: z.ZodPrefault<z.ZodObject<{
         backend: z.ZodDefault<z.ZodString>;

package/lib/engine/mem-contract/types.d.ts

@@ -299,11 +299,29 @@ export interface RetrievalHealthSummary {
     updated_at: string | null;
     by_kind: Record<string, KindHealth>;
 }
+/**
+ * Persisted-vector health of the ACTIVE corpus, relative to the vector space the store writes into
+ * NOW — the DETECTION half of "changing the embedding space is a data migration" (DESIGN §20).
+ *
+ * Deliberately cheap: it compares the recorded width and space id only, never decoding the blobs, so
+ * the `/mem` status surface can read it on every poll without loading a whole corpus.
+ */
+export interface VectorSpaceHealth {
+    /** Active facts whose persisted vector has a different width than `semantic.dim`. */
+    stale: number;
+    /** Active facts whose persisted vector is provably from another model space (same width). */
+    space_stale: number;
+}
 /** `mem_admin stats`: store counts plus the retrieval-health counters. */
 export interface StatsSummary {
     active: number;
     archived: number;
     retrieval: RetrievalHealthSummary;
+    /**
+     * Vector-space health, so "retrieval silently degraded after a model upgrade" is visible from the
+     * status surface instead of only from a one-shot startup warning.
+     */
+    vectors: VectorSpaceHealth;
 }
 /** One page of facts (`mem_admin list`). */
 export interface FactPage {
@@ -347,10 +365,42 @@ export interface VectorsDiagnostic {
     space_stale: number;
     indexed: number;
     unindexed: number;
+    /**
+     * Distinct recorded spaces across the WHOLE table (archived rows included), while `stale` /
+     * `space_stale` count only ACTIVE rows — an archived row legitimately keeps its old vector, so the
+     * two must not be compared directly.
+     */
     models: Record<string, number>;
     /** Which backend is actually serving reads (`auto:local_numpy` → `auto:hnswlib`). */
     store: string;
 }
+/**
+ * One BOUNDED slice of the vector-space migration (`MemoryStore.migrateVectorsBatch`).
+ *
+ * The migration is what turns "the default embedder changed" from a silent degradation into a
+ * resumable background repair: each call re-encodes at most `batchSize` rows, and the remaining
+ * count is what the next call (or the next process, after a restart) resumes from.
+ */
+export interface VectorMigrationProgress {
+    /** Active rows still not usable by the semantic leg after this slice (old width/space, or no vector). */
+    remaining: number;
+    /** Rows re-encoded into the current space by this slice. */
+    migrated: number;
+    /** Rows whose old-space bytes were dropped so a re-encode could replace them. */
+    dropped: number;
+    /** Usable persisted vectors re-added to the live index (no model needed). */
+    reindexed: number;
+    /** `false` when the model was not loaded: nothing could be encoded this slice. */
+    semantic_available: boolean;
+}
+/**
+ * The outcome of a whole migration drive (`MemoryStore.migrateVectors`): the last slice plus
+ * cumulative counters, and whether the `semantic.auto_migrate` switch allowed any work at all.
+ */
+export interface VectorMigrationOutcome extends VectorMigrationProgress {
+    /** `false` when `semantic.auto_migrate` is off — nothing was migrated on purpose. */
+    enabled: boolean;
+}
 /**
  * `mem_admin vectors_fix`: what a repair did, or — with `dry_run` — what it WOULD do.
  *

package/lib/index.js

@@ -121,7 +121,19 @@ const semanticSchema = z.object({
 	max_input_tokens: maxInputTokens,
 	mirror: z.string().default("https://hf-mirror.com"),
 	cache_dir: z.string().default(""),
-	auto_download: z.boolean().default(true)
+	auto_download: z.boolean().default(true),
+	/**
+	* Migrate persisted vectors that belong to an OLDER vector space (a changed model or width) in a
+	* bounded background pass. Default ON: changing the embedding space IS a data migration, and
+	* without this the semantic leg silently skips every old-space vector while lexical+entity keep
+	* answering — measured on the real library after the 512→768 default-model swap, 78 of 80 ACTIVE
+	* facts became semantically unreachable with no error anywhere.
+	*
+	* Off = the loud startup warning and the manual entry (`vectors --fix` / `mem_admin vectors_fix`)
+	* stay, but nothing re-encodes on its own. Set to `false` on a metered/embedded host that must not
+	* spend CPU on background re-encoding.
+	*/
+	auto_migrate: z.boolean().default(true)
 });
 const rerankSchema = z.object({
 	backend: z.string().default("none"),
@@ -1416,6 +1428,7 @@ const DEFAULT_COMMON_CONFIG = `# avantf-mem 公共配置（分层第②层）。
 #   local_model: Xenova/bge-base-zh-v1.5    # 必须是 ONNX 仓库
 #   dim: 768
 #   auto_download: true
+#   auto_migrate: true                # 换模型/宽度后自动分批重算旧空间的向量（默认开）；关掉只剩启动告警 + vectors --fix
 #   ⚠️ cache_dir / mirror 由家族底座 @avantf/dsh-plugin-base 管理：写在这里会被忽略并告警。
 #      缓存目录用环境变量 AVANTF_MEM_MODEL_CACHE，镜像用 AVANTF_MEM_MODEL_MIRROR（或 HF_ENDPOINT）。
 
@@ -6910,9 +6923,11 @@ function emptyFloorDrops() {
 * and changing the REPORTED value there would misdescribe what the caller is reading. `0` stays `0`
 * (the operator's off switch).
 *
-* This is the ONE place the clamp lives; `resolveFloors` (what the result reports) and
-* `applyTermFloor` (what the leg does) both call it, so the number the caller reads is the number
-* the leg used.
+* This is the ONE place the clamp lives; `resolveFloors` (what the result reports / a run is handed)
+* and `applyTermFloor` (what the leg does) both call it, so the number a run reads is the number its
+* leg used. It is a `min`, i.e. one-directional: it can LOWER an unreachable configured bar but never
+* RAISE a bar inherited from another text, which is why the caller must resolve per graded text
+* rather than reusing one text's resolution for another.
 */
 function effectiveTermFloor(floor, termCount) {
 	if (!(floor > 0)) return floor;
@@ -7128,9 +7143,21 @@ async function hybridSearch(deps, plan) {
 	* The corpus writes the user in the third person and the user asks in the first, so a
 	* first-person question shares no lexical term with the fact that answers it and the semantic leg
 	* has to carry the whole decision. The intent table (`store/self_query.ts`) supplies ONE canonical
-	* third-person rewrite; the ORIGINAL query and the rewrite each run the full leg set, and each
-	* leg's raw scores are UNIONED (a candidate in both keeps its MAX score — this is not a second
-	* leg, so it must not double the leg's weight).
+	* third-person rewrite and the ORIGINAL query and the rewrite each run the full leg set.
+	*
+	* THE FLOOR IS RESOLVED PER RUN (0.4.2). Each run is graded by ITS OWN reachability clamp —
+	* `min(configured, relevanceTerms(variant).length)` — because a variant with MORE terms has a
+	* HIGHER bar, and grading it at the original's lower bar is what let a single incidental trigram
+	* from the rewrite become that leg's head. Measured on the live store: `我是谁？` yields ONE term
+	* (`我是谁`) while its rewrite `用户是谁` yields TWO (`用户是` / `户是谁`), and the rewrite's
+	* `用户是` is a literal substring of an unrelated long note — that note then took the FTS leg's
+	* head (weight × 1.0) and outvoted the identity fact, which the rewrite had correctly put first.
+	* `applyTermFloor` re-clamps to the query it is grading, but the clamp is one-directional
+	* (`min`): it can only LOWER an unreachable bar, never RAISE a bar inherited from another text, so
+	* the resolution has to happen per variant (see {@link resolveFloors}). Each variant's own bar is
+	* then floored at the reported one, so every run is graded at or ABOVE what the envelope says: the
+	* envelope reports the ORIGINAL query's floors (the question the user actually asked) and can never
+	* overstate the bar a run was held to.
 	*
 	* WHY AUGMENT, NOT REPLACE. The table is a closed cue list over a language with unbounded
 	* self-reference variants, so a wrong match is inevitable. Under augmentation a false positive can
@@ -7139,10 +7166,16 @@ async function hybridSearch(deps, plan) {
 	* asked. `queries.length === 1` (the overwhelming majority) leaves the run below bit-identical to
 	* the pre-A path: one `deps.legs` call, same context, same vector wiring.
 	*
-	* The floors are resolved ONCE from the ORIGINAL query and applied to both runs. That is what
-	* makes "never narrows" structural rather than a promise: the merged per-leg score is
-	* `max(original, rewrite) >= original`, and a floor only removes entries, so any candidate the
-	* original query cleared its floor with still clears it in the union.
+	* FLOORS, `relaxed` AND `dropped_by_floor` UNDER AUGMENTATION. The PROFILE is resolved once per
+	* pass from the ORIGINAL query and handed to both runs; only the per-variant reachability clamp
+	* above differs, and it can only raise. Every leg of every run is therefore judged by AT LEAST the
+	* numbers the result reports — the envelope can never say "strict" while a rewrite run answered from
+	* the relaxed band (the distortion this design exists to rule out). `relaxed` is decided exactly as
+	* it was: the automatic loose pass fires only when the strict pass returned NOTHING with drops, and
+	* it re-runs BOTH variants under the loosened floors. Because a leg only ever REMOVES entries, the
+	* per-leg merge of the two runs' drop counts uses `max` (summing would count the same candidate
+	* twice) and `capped` uses OR — both conservative, neither inflates the report that feeds the retry
+	* decision.
 	*/
 	const augment = (plan.rewriteQuery ?? selfQueryRewrite)(query);
 	const queries = augment !== void 0 && augment !== query ? [query, augment] : [query];
@@ -7181,6 +7214,15 @@ async function hybridSearch(deps, plan) {
 		const runs = await Promise.all(queries.map(async (variant, index) => {
 			const isOriginal = index === 0;
 			const vector = isOriginal ? passVector : augmentVectors.get(variant);
+			const ownFloors = isOriginal ? floors : resolveFloors(retriever, semAvail, {
+				profile,
+				termCount: relevanceTerms(variant).length,
+				...relaxLegs === void 0 ? {} : { relaxLegs }
+			});
+			const variantFloors = ownFloors === floors ? floors : {
+				...ownFloors,
+				fts: Math.max(floors.fts, ownFloors.fts)
+			};
 			return runLegs(deps, {
 				query: variant,
 				limit,
@@ -7188,7 +7230,7 @@ async function hybridSearch(deps, plan) {
 				legCap,
 				semAvail,
 				weights,
-				floors,
+				floors: variantFloors,
 				...vector === void 0 ? {} : { queryVector: vector },
 				onQueryVector: (vec) => {
 					if (isOriginal) passVector = vec;
@@ -7363,10 +7405,16 @@ function vectorSpaceId(backend, model, dim) {
 * The rows come from the owning store's DAO (DESIGN §19): this helper decodes and
 * filters them, it never runs SQL itself.
 *
+* A row whose width does not fit the store is skipped (never `add()`ed — the store
+* would throw). The OWNING store reports that condition itself, as one actionable
+* line with the count, the reason and the manual re-encode entry (`reportStaleVectors`),
+* so this helper stays quiet: two warnings for one condition read as two problems.
+*
 * @param rows - `id` (fact/chunk id) + `vec` (BLOB), as read back from the store.
-* @param label - store name used in the dim-mismatch warning.
+* @param _label - store name; unused here (the owning store owns the warning), kept so call sites read
+*                 as "which store is reloading".
 */
-function reloadVectorIndex(vstore, rows, label) {
+function reloadVectorIndex(vstore, rows, _label) {
 	const entries = [];
 	let skipped = 0;
 	for (const r of rows) {
@@ -7377,7 +7425,6 @@ function reloadVectorIndex(vstore, rows, label) {
 		});
 		else skipped++;
 	}
-	if (skipped > 0) retrievalLogger().warn(`${label} index reload: skipped ${skipped} vector(s) with dim != ${vstore.dim}`);
 	vstore.rebuild(entries);
 	return {
 		loaded: entries.length,
@@ -7442,21 +7489,32 @@ function evictVectors(vstore, ids) {
 	else for (const id of ids) vstore.remove(id);
 }
 /**
-* Tell the operator that persisted vectors came from ANOTHER vector space.
+* Tell the operator that persisted vectors came from ANOTHER vector space — loudly, and with the
+* manual remedy.
+*
+* Changing the embedding space (model, width, pooling, normalization) is a DATA MIGRATION: the
+* persisted bytes stay valid-looking but are no longer comparable with the current query vector, so
+* the semantic leg must not serve them. Measured on the real library after the 512→768 default-model
+* swap: 78 of 80 ACTIVE facts fell out of the semantic leg and retrieval silently degraded to
+* lexical+entity (every probe query answered with the same unrelated short fact), with no error
+* anywhere. The count, the reason and the ONE manual entry have to be visible at start.
 *
-* A dim-valid vector from a different space is still RANKED — the reload cannot tell the difference
-* — so a silent model swap would mix two spaces in one index and degrade every semantic query
-* without an error anywhere. Said once per process; acting on it is the operator's choice because
-* re-encoding is a real cost (and they should see the count first).
+* Both halves are reported in one message because they are one condition seen two ways: a changed
+* WIDTH (`stale`, whose bytes cannot even be decoded into the current store) and a changed SPACE at
+* the same width (`space_stale`, whose bytes decode but rank in another model's coordinates).
 *
 * @param kind   store label for the message (`memory` / `knowledge`)
 * @param space  the vector space the store writes into now
-* @param foreign how many persisted vectors were written in a different one
-* @param fix    the action that re-encodes them, as the operator would type it
+* @param counts how many persisted vectors are unusable in the current space, by kind
+* @param fix    the manual entry that re-encodes them, as the operator would type it
 */
-function reportForeignVectors(kind, space, foreign, fix) {
-	if (foreign <= 0) return;
-	retrievalLogger().warn(`${kind} index: ${String(foreign)} vector(s) were written in another space than ${space} — they are still ranked; run ${fix} to re-encode them`);
+function reportStaleVectors(kind, space, counts, fix) {
+	const total = counts.stale + counts.space_stale;
+	if (total <= 0) return;
+	const reasons = [];
+	if (counts.stale > 0) reasons.push(`${String(counts.stale)} with a width that no longer matches`);
+	if (counts.space_stale > 0) reasons.push(`${String(counts.space_stale)} written by another model`);
+	retrievalLogger().warn(`${kind} index: ${String(total)} persisted vector(s) belong to an OLDER embedding space than ${space} (${reasons.join("; ")}) — the semantic leg cannot use them, so retrieval degrades to lexical+entity (this is a data migration, not a transient error); run ${fix} to re-encode them`);
 }
 /**
 * Hand the event loop back between two synchronous batches.
@@ -8038,6 +8096,17 @@ var FactsDao = class FactsDao {
           WHERE semantic_vector IS NOT NULL AND status = 'active'`).all();
 	}
 	/**
+	* 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() {
+		return this.db.prepare(`SELECT fact_id, length(semantic_vector) AS bytes, embedding_model FROM facts
+          WHERE semantic_vector IS NOT NULL AND status = 'active'`).all();
+	}
+	/**
 	* 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.
 	*/
@@ -9585,13 +9654,38 @@ var MemoryStore = class {
 	*/
 	reloadIndex() {
 		const space = this.vectorSpace();
-		const persisted = this.facts.activeVectorRows();
-		const rows = persisted.map((r) => ({
+		const rows = this.facts.activeVectorRows().map((r) => ({
 			id: r.fact_id,
 			vec: r.semantic_vector
 		}));
 		reloadVectorIndex(this.vstore, rows, "memory");
-		reportForeignVectors("memory", space, persisted.filter((r) => r.embedding_model !== space).length, "mem_admin vectors_fix (dry_run=true previews the count)");
+		reportStaleVectors("memory", space, this.vectorSpaceHealth(), "`avantf-mem vectors --fix` (MCP/plugin: `mem_admin vectors_fix`)");
+	}
+	/**
+	* Cheapest possible DETECTION of "the embedding space changed under this store": counts of ACTIVE
+	* persisted vectors whose width or recorded space id no longer matches the one this store writes
+	* into. Reads blob LENGTHS only — never decodes — so the `/mem` status surface and the startup
+	* warning can afford it at any corpus size.
+	*
+	* The counts are the same two `VectorsDiagnostic` already separates (`stale` / `space_stale`); this
+	* is the read model those surfaces use instead of the full diagnose pass.
+	*/
+	vectorSpaceHealth() {
+		const space = this.vectorSpace();
+		const expectedBytes = this.vstore.dim * 4;
+		let stale = 0;
+		let spaceStale = 0;
+		for (const row of this.facts.activeVectorSpaces()) {
+			if (row.bytes !== expectedBytes) {
+				stale++;
+				continue;
+			}
+			if (row.embedding_model !== space) spaceStale++;
+		}
+		return {
+			stale,
+			space_stale: spaceStale
+		};
 	}
 	async add(content, category, ttlDays) {
 		const normalized = normalizeWrite(content).trim();
@@ -10020,7 +10114,7 @@ var MemoryStore = class {
 		};
 	}
 	/**
-	* Repair the semantic read model:
+	* Repair the semantic read model, in ONE bounded slice or in full:
 	*  (a) reload persisted, dim-valid vectors missing from the live index
 	*      (restart / index loss — needs no model),
 	*  (b) drop persisted vectors whose dim no longer matches `semantic.dim` so a
@@ -10028,64 +10122,162 @@ var MemoryStore = class {
 	*      throws on dim mismatch),
 	*  (c) encode active facts that have no vector yet (needs the semantic backend),
 	*  (d) re-encode vectors written in ANOTHER vector space (a model swap, or the one-time
-	*      adoption of a store predating the space id). Deliberately here and not at open: this is
-	*      the only path that re-encodes the whole table, so it is an explicit, counted action.
-	* `dry_run` previews every count without writing — and without loading the model, which is why
-	* the preview also reports `would_warm` (see the contract's `VectorsFixReport`).
+	*      adoption of a store predating the space id).
+	*
+	* `limit` is what makes the SAME logic usable as a background migration: at most that many rows are
+	* dropped and at most that many are re-encoded, so one call is a bounded unit of work the caller can
+	* yield between. `vectorsFix` passes no limit (the explicit operator action drains everything);
+	* `migrateVectorsBatch` passes the migration's batch size.
 	*/
-	async vectorsFix(dryRun = false) {
+	async repairVectors(opts) {
+		const limit = opts.limit ?? Number.POSITIVE_INFINITY;
 		const c = this.classifyVectors();
 		const loadedNow = this.semantic.isAvailable();
 		let semAvailable = loadedNow;
-		if (!semAvailable && !dryRun) semAvailable = await this.warmupSemantic();
+		if (!semAvailable && !opts.dryRun) semAvailable = await this.warmupSemantic();
 		const wouldWarm = !loadedNow;
-		if (dryRun) return {
-			missing: c.missing,
-			stale: c.staleIds.length,
-			space_stale: c.spaceStaleIds.length,
-			unindexed: c.unindexed.length,
-			reindexed: 0,
-			dropped: 0,
-			fixed: 0,
-			semantic_available: semAvailable,
-			would_warm: wouldWarm,
-			dry_run: true
+		const remainingOf = (fixed) => Math.max(0, c.staleIds.length + c.spaceStaleIds.length + c.missing - fixed);
+		if (opts.dryRun) return {
+			report: {
+				missing: c.missing,
+				stale: c.staleIds.length,
+				space_stale: c.spaceStaleIds.length,
+				unindexed: c.unindexed.length,
+				reindexed: 0,
+				dropped: 0,
+				fixed: 0,
+				semantic_available: semAvailable,
+				would_warm: wouldWarm,
+				dry_run: true
+			},
+			remaining: remainingOf(0)
 		};
 		let reindexed = 0;
-		for (const u of c.unindexed) {
+		for (const u of c.unindexed.slice(0, limit)) {
 			this.vstore.add(u.id, u.vec);
 			reindexed++;
 		}
 		let dropped = 0;
 		if (semAvailable) {
-			const toDrop = [...c.staleIds, ...c.spaceStaleIds];
+			const toDrop = [...c.staleIds, ...c.spaceStaleIds].slice(0, limit);
 			if (toDrop.length) {
+				const spaceStale = new Set(c.spaceStaleIds);
 				dropped = this.facts.clearVectors(toDrop);
-				this.evictVectors(c.spaceStaleIds);
+				this.evictVectors(toDrop.filter((id) => spaceStale.has(id)));
 			}
 		}
 		let fixed = 0;
 		if (semAvailable) {
-			const missingRows = this.facts.missingVectorRows();
+			const missingRows = this.facts.missingVectorRows().slice(0, limit);
 			for (const m of missingRows) {
 				if (!await this.maybeIndexSemantic(m.fact_id, m.content)) continue;
 				fixed++;
 			}
 		}
 		return {
-			missing: c.missing,
-			stale: c.staleIds.length,
-			space_stale: c.spaceStaleIds.length,
-			unindexed: c.unindexed.length,
-			reindexed,
-			dropped,
-			fixed,
-			semantic_available: semAvailable,
-			would_warm: wouldWarm,
-			dry_run: false
+			report: {
+				missing: c.missing,
+				stale: c.staleIds.length,
+				space_stale: c.spaceStaleIds.length,
+				unindexed: c.unindexed.length,
+				reindexed,
+				dropped,
+				fixed,
+				semantic_available: semAvailable,
+				would_warm: wouldWarm,
+				dry_run: false
+			},
+			remaining: remainingOf(fixed)
 		};
 	}
 	/**
+	* The explicit, unbounded repair behind `mem_admin vectors_fix` / `avantf-mem vectors --fix`.
+	* `dry_run` previews every count without writing — and without loading the model, which is why
+	* the preview also reports `would_warm` (see the contract's `VectorsFixReport`).
+	*/
+	async vectorsFix(dryRun = false) {
+		return (await this.repairVectors({ dryRun })).report;
+	}
+	/**
+	* ONE bounded slice of the vector-space migration: at most `batchSize` rows are dropped and
+	* re-encoded, so the caller keeps control of the event loop between slices. This is the unit the
+	* background migration ({@link migrateVectors}) and its tests drive.
+	*
+	* Resumability is a property of the DATABASE, not of this process: every slice re-derives what is
+	* stale from the persisted width/space, so a restart simply continues where the last slice stopped.
+	*/
+	async migrateVectorsBatch(batchSize = 16) {
+		const size = Math.max(1, Math.floor(batchSize));
+		const { report, remaining } = await this.repairVectors({
+			dryRun: false,
+			limit: size
+		});
+		return {
+			remaining,
+			migrated: report.fixed,
+			dropped: report.dropped,
+			reindexed: report.reindexed,
+			semantic_available: report.semantic_available
+		};
+	}
+	/**
+	* Drive the bounded background migration until the store is current, the model is unavailable, or
+	* `shouldStop()` turns true (plugin unmount / process shutdown). A batch FAILURE never rejects: it is
+	* logged and reported as `remaining > 0`, which is what makes the next heartbeat a retry (the caller
+	* still owns the outer catch for a closed database, e.g. a shutdown racing the first read). Never
+	* blocks the event loop for longer than one batch.
+	*
+	* Honours `semantic.auto_migrate` (default on) — the switch exists so a host that must not spend CPU
+	* on background re-encoding can leave the loud warning and the manual entry as the only path.
+	*/
+	async migrateVectors(opts = {}) {
+		const enabled = this.config.semantic.auto_migrate !== false;
+		const snapshot = () => ({
+			enabled,
+			remaining: this.migrationRemaining(),
+			migrated: 0,
+			dropped: 0,
+			reindexed: 0,
+			semantic_available: this.semantic.isAvailable()
+		});
+		if (!enabled) return snapshot();
+		let migrated = 0;
+		let dropped = 0;
+		let reindexed = 0;
+		let last = snapshot();
+		if (last.remaining === 0) return last;
+		for (;;) {
+			if (opts.shouldStop?.() === true) break;
+			let step;
+			try {
+				step = await this.migrateVectorsBatch(opts.batchSize);
+			} catch (error) {
+				retrievalLogger().warn(`memory vector migration: batch failed (${describeError$2(error)}) — ${String(this.migrationRemaining())} vector(s) still belong to an older embedding space; the next pass retries`);
+				break;
+			}
+			migrated += step.migrated;
+			dropped += step.dropped;
+			reindexed += step.reindexed;
+			last = {
+				...step,
+				enabled,
+				migrated,
+				dropped,
+				reindexed
+			};
+			opts.onProgress?.(last);
+			if (step.migrated === 0 && step.dropped === 0 && step.reindexed === 0) break;
+			if (last.remaining === 0) break;
+			await yieldToEventLoop();
+		}
+		return last;
+	}
+	/** Active rows the semantic leg still cannot use (old width, old space, or no vector at all). */
+	migrationRemaining() {
+		const health = this.vectorSpaceHealth();
+		return health.stale + health.space_stale + this.facts.vectorCounts().missing;
+	}
+	/**
 	* One lifecycle pass, owned by the store so the DB writes and the live-index
 	* invariant (ACTIVE vectors only) are maintained in ONE place — the runtime no
 	* longer has to patch the index behind the store's back.
@@ -12417,7 +12609,20 @@ var KnowledgeStore = class {
 		const space = this.vectorSpace();
 		const persisted = this.chunks.vectorRows();
 		reloadVectorIndex(this.vstore, persisted, "knowledge");
-		reportForeignVectors("knowledge", space, persisted.filter((r) => r.embedding_model !== space).length, "kb_reindex (dry_run=true previews the count)");
+		let stale = 0;
+		let spaceStale = 0;
+		const expectedBytes = this.vstore.dim * 4;
+		for (const row of persisted) {
+			if (!row.vec || row.vec.byteLength !== expectedBytes) {
+				stale++;
+				continue;
+			}
+			if (row.embedding_model !== space) spaceStale++;
+		}
+		reportStaleVectors("knowledge", space, {
+			stale,
+			space_stale: spaceStale
+		}, "`avantf-mem kb reindex` (MCP/plugin: `kb_reindex`)");
 	}
 	/**
 	* The write-side domain allowlist AND the 知识页 picker's data, in one place: the configured
@@ -13698,7 +13903,8 @@ function buildRuntime(opts) {
 			switch (req.action) {
 				case "stats": return {
 					...this.memory.countByStatus(),
-					retrieval: retrievalHealthSummary()
+					retrieval: retrievalHealthSummary(),
+					vectors: this.memory.vectorSpaceHealth()
 				};
 				case "list": return this.memory.list(req.category, req.status ?? "active", req.limit ?? 50, req.offset ?? 0);
 				case "detail": return this.memory.get(req.fact_id) ?? { error: `fact_id=${req.fact_id} not found` };
@@ -15397,6 +15603,58 @@ function openDocumentPath(documentPath, target, configured, deps = {}) {
 	throw new Error(`无法启动编辑器（试过：${tried.join("、")}${detail}）`);
 }
 //#endregion
+//#region lib/types/vectorMigration.js
+function createVectorMigration(opts) {
+	const { rt, logger } = opts;
+	let running = false;
+	let stopped = false;
+	let warnedDisabled = false;
+	const run = async () => {
+		const health = rt.memory.vectorSpaceHealth();
+		const pending = health.stale + health.space_stale;
+		if (pending === 0) return;
+		if (rt.closed || !opts.isActive()) return;
+		if (rt.config.common.semantic.auto_migrate === false) {
+			if (!warnedDisabled) {
+				warnedDisabled = true;
+				logger.warn(`vector migration: ${String(pending)} ACTIVE vector(s) belong to an older embedding space and \`semantic.auto_migrate\` is off — the semantic leg stays blind to them; run \`avantf-mem vectors --fix\` (MCP/plugin: \`mem_admin vectors_fix\`) or set \`semantic.auto_migrate: true\``);
+			}
+			return;
+		}
+		const startedAt = Date.now();
+		logger.info(`vector migration: ${String(pending)} ACTIVE vector(s) belong to an older embedding space (${String(health.space_stale)} same-width other-model, ${String(health.stale)} wrong-width) — re-encoding in the background`);
+		const outcome = await rt.memory.migrateVectors({
+			...opts.batchSize === void 0 ? {} : { batchSize: opts.batchSize },
+			shouldStop: () => stopped || rt.closed || !opts.isActive(),
+			onProgress: (progress) => {
+				logger.info(`vector migration: re-encoded ${String(progress.migrated)}/${String(pending)} (${String(progress.remaining)} left)`);
+			}
+		});
+		if (outcome.remaining === 0) {
+			logger.info(`vector migration: complete — ${String(outcome.migrated)} vector(s) re-encoded in ${String(Date.now() - startedAt)}ms; the semantic leg is current`);
+			return;
+		}
+		if (!stopped && !rt.closed && opts.isActive()) logger.warn(`vector migration: ${String(outcome.remaining)} vector(s) still belong to an older embedding space (the embedding model may be unavailable) — the next heartbeat retries; manual entry \`avantf-mem vectors --fix\``);
+	};
+	return {
+		start() {
+			if (stopped || running) return;
+			running = true;
+			run().catch((error) => {
+				logger.warn(`vector migration failed: ${error instanceof Error ? error.message : String(error)}`);
+			}).finally(() => {
+				running = false;
+			});
+		},
+		stop() {
+			stopped = true;
+		},
+		get running() {
+			return running;
+		}
+	};
+}
+//#endregion
 //#region lib/types/tool_schema.js
 /**
 * zod → DSH parameter schema derivation for the agent tools.
@@ -16143,6 +16401,14 @@ async function apply(ctx, config) {
 		...waitFor === void 0 ? {} : { waitFor },
 		...verdict === void 0 ? {} : { dshCompat: verdict }
 	});
+	const vectorMigration = createVectorMigration({
+		rt,
+		logger,
+		isActive: () => stillActive(ctx)
+	});
+	ctx.effect(() => () => {
+		vectorMigration.stop();
+	});
 	const sweepEntities = () => {
 		rt.memory.reindexEntities(ENTITY_SWEEP_PER_HEARTBEAT).then((swept) => {
 			if (swept.rebuilt > 0) logger.info(`entity sweep: rebuilt ${swept.rebuilt} fact(s) written by older rules (${swept.deferred} still stale)`);
@@ -16154,7 +16420,10 @@ async function apply(ctx, config) {
 		...waitFor === void 0 ? {} : { waitFor },
 		deferTokenizerUntilIdle: true
 	}).then(() => {
-		if (!rt.closed && stillActive(ctx)) sweepEntities();
+		if (!rt.closed && stillActive(ctx)) {
+			sweepEntities();
+			vectorMigration.start();
+		}
 	}).catch((error) => {
 		logger.warn(`entity sweep gate failed: ${error instanceof Error ? error.message : String(error)}`);
 	});
@@ -16167,6 +16436,7 @@ async function apply(ctx, config) {
 				logger.warn(`trust tick failed: ${error instanceof Error ? error.message : String(error)}`);
 			}
 			sweepEntities();
+			vectorMigration.start();
 		}, heartbeatMinutes * 6e4);
 		const unref = timer.unref;
 		if (typeof unref === "function") unref.call(timer);

package/lib/types/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAwGA,wDAAwD;AACxD,UAAU,aAAa;IACrB,KAAK,EAAE;QACL,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;QAChD,QAAQ,CACN,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,MAAM,CAAA;SAAE,EACzE,SAAS,EAAE,MAAM,OAAO,GACvB,IAAI,CAAA;KACR,CAAA;IACD,MAAM,EAAE;QACN,wEAAwE;QACxE,MAAM,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;KAC5D,CAAA;IACD;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3B;AA8gDD,2DAA2D;AAC3D,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,MAAM,UAAsB,CAAA;AAEzC,mGAAmG;AACnG,wBAAsB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC7D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAwGA,wDAAwD;AACxD,UAAU,aAAa;IACrB,KAAK,EAAE;QACL,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;QAChD,QAAQ,CACN,OAAO,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,MAAM,CAAA;SAAE,EACzE,SAAS,EAAE,MAAM,OAAO,GACvB,IAAI,CAAA;KACR,CAAA;IACD,MAAM,EAAE;QACN,wEAAwE;QACxE,MAAM,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;KAC5D,CAAA;IACD;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAC3B;AAyhDD,2DAA2D;AAC3D,eAAO,MAAM,IAAI,sBAAsB,CAAA;AAEvC;;;;GAIG;AACH,eAAO,MAAM,MAAM,UAAsB,CAAA;AAEzC,mGAAmG;AACnG,wBAAsB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC7D"}

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,EAAE,mBAAmB,EAAU,MAAM,kCAAkC,CAAA;AAE9E,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,EAeL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAG1B,MAAM,sBAAsB,CAAA;AAoB7B,eAAO,MAAM,IAAI,eAAe,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAQ7E,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AACD,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAO3B,CAAA;AA6CF,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAOvC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBACtB,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa;IAK3C;;;;;;;;;OASG;YACW,IAAI;IAclB;;;;OAIG;IAEH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAMlF,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAMnF,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAKhF;;;;;OAKG;IAEH,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAOpD,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAI5D;;;;OAIG;IAEG,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAUnF,qFAAqF;IAE/E,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAUvE;;;;OAIG;IAEG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAQvG;;;;OAIG;IAEG,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IAUpG;;;;;OAKG;IAEG,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;CAiBpE;AAiID,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA4WvE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAQlD,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAExC,OAAO,EAAE,mBAAmB,EAAU,MAAM,kCAAkC,CAAA;AAE9E,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAEhB,KAAK,WAAW,EACjB,MAAM,aAAa,CAAA;AACpB,OAAO,EAeL,KAAK,aAAa,EAClB,KAAK,WAAW,EAEhB,KAAK,YAAY,EACjB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EAG1B,MAAM,sBAAsB,CAAA;AAqB7B,eAAO,MAAM,IAAI,eAAe,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAQ7E,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,mBAAmB,EACnB,KAAK,QAAQ,EACb,KAAK,eAAe,EACpB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAA;AAEpB,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AACD,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAO3B,CAAA;AA6CF,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAOvC;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,mBAAmB;IACvD,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAe;gBACtB,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,aAAa;IAK3C;;;;;;;;;OASG;YACW,IAAI;IAclB;;;;OAIG;IAEH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC,CAAC;IAMlF,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;IAMnF,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAC;IAKhF;;;;;OAKG;IAEH,EAAE,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAOpD,KAAK,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,YAAY,CAAC,CAAC;IAI5D;;;;OAIG;IAEG,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,oBAAoB,CAAC,CAAC;IAUnF,qFAAqF;IAE/E,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,aAAa,CAAC,CAAC;IAUvE;;;;OAIG;IAEG,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC,CAAC;IAQvG;;;;OAIG;IAEG,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;IAUpG;;;;;OAKG;IAEG,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;CAiBpE;AAiID,wBAAsB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAuYvE"}

package/lib/types/vectorMigration.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The plugin's driver for the bounded, resumable background migration of persisted vectors into the
+ * current embedding space.
+ *
+ * Changing the embedding space (default model, width, pooling, normalization) is a DATA MIGRATION,
+ * not a config tweak: every persisted vector still decodes, but in another model's coordinates, so
+ * the semantic leg must not serve it. Measured on the real library after the 512→768 default-model
+ * swap, 78 of 80 ACTIVE facts fell out of the semantic leg and retrieval degraded to lexical+entity
+ * with no error anywhere — the store's open-time warning now says so, and this module is what
+ * repairs it without the operator having to know `vectors --fix` exists.
+ *
+ * It sits BEHIND the startup gate (`awaitStartupGate`, see index.ts): the model warm and this first
+ * batch must not land in the boot window (DESIGN §20.14), and the tokenizer/model are the expensive
+ * resources the gate exists to move out. The loop itself lives in the store
+ * (`MemoryStore.migrateVectors`), which owns the batch size, the per-batch error handling and the
+ * event-loop yield; this module owns the LOGGING (start / progress / end) and the lifecycle
+ * (`shouldStop` = plugin disposed or runtime closed).
+ *
+ * Deliberately no new state in this file: what still needs migrating is derived from the database on
+ * every pass, which is exactly what makes the migration resumable across a restart.
+ */
+import { type AvantfRuntime } from '../engine/mem/index.js';
+import type { AvantfLogger } from '../engine/mem-contract/index.js';
+export interface VectorMigrationHandle {
+    /**
+     * Run one migration pass. Quiet no-op when the store is already current, when a pass is already
+     * running, or after {@link stop}. Failures never escape: they are logged and left for the next
+     * heartbeat to retry.
+     */
+    start(): void;
+    /** Stop a running pass at its next batch boundary; later `start()` calls are no-ops. */
+    stop(): void;
+    /** `true` while a pass is in flight. */
+    readonly running: boolean;
+}
+export declare function createVectorMigration(opts: {
+    rt: AvantfRuntime;
+    logger: AvantfLogger;
+    /** False once the plugin's fiber is disposed (profile reload / unload). */
+    isActive: () => boolean;
+    /** Rows per batch; the store's `DEFAULT_VECTOR_MIGRATION_BATCH` when omitted. */
+    batchSize?: number;
+}): VectorMigrationHandle;
+//# sourceMappingURL=vectorMigration.d.ts.map

package/lib/types/vectorMigration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectorMigration.d.ts","sourceRoot":"","sources":["../../src/vectorMigration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExD,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAA;IACb,wFAAwF;IACxF,IAAI,IAAI,IAAI,CAAA;IACZ,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAC1B;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,EAAE,EAAE,aAAa,CAAA;IACjB,MAAM,EAAE,YAAY,CAAA;IACpB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,OAAO,CAAA;IACvB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,qBAAqB,CAsExB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avantf/dsh-mem",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "avantf-mem DSH native Cordis plugin: host service + tools + RPC + client tabs 记忆/知识",
   "type": "module",
   "main": "lib/index.js",
@@ -78,10 +78,10 @@
   },
   "devDependencies": {
     "@avantf/dsh-plugin-base": ">=0.3.0 <1.0.0",
-    "@avantf/mem": "0.4.1",
-    "@avantf/mem-contract": "0.4.1",
-    "@avantf/mem-convert": "0.4.1",
-    "@avantf/mem-provision": "0.4.1",
+    "@avantf/mem": "0.4.2",
+    "@avantf/mem-contract": "0.4.2",
+    "@avantf/mem-convert": "0.4.2",
+    "@avantf/mem-provision": "0.4.2",
     "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "lightningcss": "^1.32.0",