@avantf/dsh-mem 0.6.3 → 0.7.0

package/lib/dsh-build.json

@@ -1,7 +1,7 @@
 {
-  "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-typert-registry": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-util-values": "0.2.0-rc.2"
+  "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-util-values": "0.2.1-rc.2"
 }

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#   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";
+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\u5BB6\u65CF\u6839\uFF1A\u540C\u65F6\u51B3\u5B9A\u6570\u636E\u6839\u4E0E models/tools\uFF09\u51B3\u5B9A \u2014\u2014\n# \u53EA\u60F3\u6362\u6570\u636E\u6839\u3001\u4E0D\u642C\u6A21\u578B\u7F13\u5B58\u65F6\u7528 CLI \u7684 \u2464 \u663E\u5F0F\u53C2\u6570 avantf-mem --data-home <path>\uFF08\u63D2\u4EF6\u5219\u662F profile \u7684\n# dataHome\uFF0C\u5C5E \u2461\uFF09\u3002\u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u65F6\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

@@ -115,6 +115,12 @@ export declare class ChunksDao {
      * This is what lets the shared repair flow read "what is stale" cheaply per slice instead of
      * re-scanning and hashing the corpus (`corpusState` reads every text; a batched migration must
      * not).
+     *
+     * The JS rule itself is `store/vector_space.ts` (`classifyVectorSpace` / `countVectorSpace`), and
+     * this projection is bound to it by the cross assertions in
+     * `test/knowledge_vector_migration.spec.ts` (the startup warning's count, the health count and the
+     * migration's `remaining` all have to be the same number). NOTHING here changes when the JS rule
+     * changes: the mirror is checked, not shared.
      */
     vectorSpaceCounts(space: string, expectedBytes: number): {
         stale: number;

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

@@ -8,10 +8,28 @@
  * 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 { FactSourceView } from '../../../mem-contract/index.js';
 import type { Db } from '../port.js';
-/** The closed `kind` vocabulary, spelled once so the store and the tests share it. */
+/**
+ * The kind axis is the CONTRACT's, not a second list: `FactSourceView['kind']` is what `admin detail`
+ * renders and what the writer below records, so deriving the type from it is what makes "the closed
+ * vocabulary" one thing. (Before, the array here and the union in `types.ts` were two independent
+ * spellings that happened to agree.)
+ */
+export type FactSourceKind = FactSourceView['kind'];
+/**
+ * The closed `kind` vocabulary, spelled once so the store and the tests share it.
+ *
+ * The `satisfies` pins every member to the contract's union; the `Exclude` below pins the other
+ * direction, so a kind the contract ADDS fails to compile here instead of silently never being
+ * recorded.
+ */
 export declare const FACT_SOURCE_KINDS: readonly ["session", "kb_doc", "tool", "manual"];
-export type FactSourceKind = (typeof FACT_SOURCE_KINDS)[number];
+/**
+ * The FALLBACK kind: a `source_ref` without a recognized `kind:` prefix is `manual` with the
+ * reference kept VERBATIM (the tool contract says so, and "no shape guessing" is the point).
+ */
+export declare const FACT_SOURCE_FALLBACK_KIND: "manual";
 /** One provenance row as the read surfaces render it. */
 export interface FactSource {
     kind: FactSourceKind;
@@ -21,10 +39,14 @@ export interface FactSource {
  * 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.
+ * `kind:` prefix — `session:…` / `kb_doc:…` / `tool:…` — and anything else, INCLUDING the fallback
+ * kind's own name, 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.
+ *
+ * The prefix table comes from {@link FACT_SOURCE_KINDS} (see {@link FACT_SOURCE_PREFIX_KINDS}) rather
+ * than from a hand-written alternation, which is what keeps the recognized set and the recorded set
+ * from being two lists.
  */
 export declare function classifySourceRef(sourceRef: string): {
     kind: FactSourceKind;

package/lib/engine/mem/defaults.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The two page/result defaults the engine falls back to when neither the caller nor the config says
+ * anything — spelled ONCE, because each of them used to be written in two or three places.
+ *
+ * They are the ENGINE's consumption points of numbers the CONTRACT documents:
+ *
+ *   - `DEFAULT_SEARCH_LIMIT` — `query`'s own input schema carries `.default(10)`
+ *     (`contract/src/tools.ts`), and the recall actions' descriptions say "默认 10"; the recall union
+ *     itself is `.optional()`, so the engine is what applies it. It reaches `hybridSearch` (a
+ *     non-finite limit) and the cross-store router.
+ *   - `DEFAULT_LIST_LIMIT` — the documented page for `admin list` and `kb_list` ("默认 50" /
+ *     "缺省 50", same file).
+ *
+ * The cross-layer equation is pinned by `test/hybrid.spec.ts` against the contract's parsed schema,
+ * so a contract default moving and this constant not moving is a red test rather than a silent
+ * off-by-page behaviour. (These live here rather than in the contract because `@avantf/mem-contract`
+ * is consumed as built output: a constant added there is only visible to this engine after the
+ * contract is rebuilt, which a source-only change may not assume.)
+ *
+ * @module defaults
+ */
+/** Page of a recall/query result when the caller gave no usable `limit`. */
+export declare const DEFAULT_SEARCH_LIMIT = 10;
+/** Page of a listing surface (`admin list`, `kb_list`) when the caller gave no `limit`. */
+export declare const DEFAULT_LIST_LIMIT = 50;

package/lib/engine/mem/dispatch.d.ts

@@ -16,10 +16,12 @@
 import type { KbAddRequest, ToolEnvelope, ToolSpec } from '../mem-contract/index.js';
 import type { AvantfRuntime } from './runtime.js';
 /**
- * The default page for a model-facing `kb_list`.
+ * The default page for a model-facing `kb_list` — the SAME page the operator's `admin list` uses.
  *
  * Without one, `kb_list` on a large library read and parsed EVERY managed file (resolving a path
- * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full.
+ * needs the file's frontmatter to detect collisions) to answer a question nobody asked in full. The
+ * two surfaces were separate literals; the contract documents both as 50, so they are one constant
+ * (`src/defaults.ts`).
  */
 export declare const KB_LIST_DEFAULT_LIMIT = 50;
 /**

package/lib/engine/mem/facts_io.d.ts

@@ -0,0 +1,288 @@
+import { EXPORT_STATUSES, type ExportStatus, type RememberRequest } from '../mem-contract/index.js';
+/**
+ * The runtime slice these flows actually touch.
+ *
+ * Narrow on purpose: export reads two config fields, import/merge also call the store's `add` path.
+ * Keeping the parameter structural (rather than the whole `AvantfRuntime`) is what lets the admin
+ * dispatcher — an object literal whose `closed` getter is attached only at return time — pass
+ * itself in without a cast, and it documents that these flows cannot reach any other store face.
+ */
+export interface FactsIoRuntime {
+    config: {
+        home: string;
+        memory: {
+            db: {
+                path: string;
+            };
+        };
+    };
+    remember(req: RememberRequest): Promise<unknown>;
+}
+/** The document's discriminator. A file without it is not an export of this tool. */
+export declare const FACTS_EXPORT_FORMAT = "avantf-mem-facts";
+/**
+ * The version THIS build writes: 2 (v1 + the facts columns v1 did not carry).
+ *
+ * Versions are additive by design: v2 adds OPTIONAL fields, so a v1 document is still the same
+ * shape minus the new keys. A version outside {@link FACTS_EXPORT_VERSIONS} must be refused, never
+ * guessed at.
+ */
+export declare const FACTS_EXPORT_VERSION = 2;
+/** A version this build can READ. v1 documents are what users already have on disk. */
+export declare const FACTS_EXPORT_VERSIONS: readonly [1, 2];
+/** The version literal, so a parsed document can say which field set it came from. */
+export type FactsExportVersion = (typeof FACTS_EXPORT_VERSIONS)[number];
+/**
+ * `--status` values accepted by `export` (the whole DB, or one status).
+ *
+ * Re-exported from the contract, where the admin action and the CLI flag read the same set. The
+ * engine's public face keeps the name its callers already import.
+ */
+export { EXPORT_STATUSES, type ExportStatus };
+/** One `fact_sources` row, copied verbatim. */
+export interface ExportedFactSource {
+    kind: string;
+    ref: string;
+}
+/**
+ * One fact, as it stands in the source database.
+ *
+ * Every field is part of the documented format even when v1 import ignores it — the point of the
+ * document is that a later restore does not have to invent what was never written down.
+ */
+export interface ExportedFact {
+    /** Source-local row id. For reports/debugging ONLY; content is the identity. */
+    source_id: number;
+    content: string;
+    category: string;
+    status: string;
+    created_at: string | null;
+    updated_at: string | null;
+    ttl_days: number;
+    pinned: boolean;
+    pinned_at: string | null;
+    trust_score: number;
+    assert_count: number;
+    helpful_count: number;
+    last_reinforced_at: string | null;
+    sources: ExportedFactSource[];
+    valid_from: string | null;
+    valid_to: string | null;
+    supersedes_source_id: number | null;
+    /** `null` for an active row; the archive bookkeeping for an archived one. */
+    archive: {
+        at: string | null;
+        reason: string | null;
+    } | null;
+    /** Active-day clock at the last trust settle — the decay baseline. v1 had no such column. */
+    settle_clock?: number | null;
+    /** Reinforcement events inside the current 24h window. */
+    bonus_count?: number | null;
+    /** Calendar start of that window. */
+    bonus_window_at?: string | null;
+    /** How many times this fact was RETURNED by a retrieval leg (local usage stat, still stored). */
+    retrieval_count?: number | null;
+    last_retrieved_at?: string | null;
+    /** Mirror bookkeeping (a fact copied between libraries); informational, restored verbatim. */
+    mirror_source?: string | null;
+    mirror_target?: string | null;
+    /**
+     * The DERIVED-STATE stamps. Exported for completeness/diagnostics, but restore deliberately does
+     * not trust them: it stamps `entities_version = 0` (so the entity sweep rebuilds) and
+     * `conflict_checked = 1` (no corpus-wide conflict re-scan after a rebuild).
+     */
+    entities_version?: number | null;
+    conflict_checked?: number | null;
+}
+/** The single JSON document `export` writes (and `import`/`restore` read). */
+export interface FactsExportDocument {
+    format: typeof FACTS_EXPORT_FORMAT;
+    /** The version the document was WRITTEN as (1 or 2); this build writes 2. */
+    version: FactsExportVersion;
+    exported_at: string;
+    source: {
+        data_home: string;
+        db: string;
+        /** The SOURCE database's whole-DB status counts, independent of `--status`. */
+        counts: {
+            active: number;
+            archived: number;
+        };
+    };
+    facts: ExportedFact[];
+}
+/** How v1 import may treat the provenance embedded in the document. */
+export interface ImportOptions {
+    /** Plan only: no write, and the report gets `would_import`. */
+    dryRun?: boolean;
+    /** Fallback provenance when the document has none (the CLI passes `import:<file>`). */
+    sourceRef?: string;
+    /**
+     * Use `sources[0].ref` when present (the default, and the import contract).
+     *
+     * `merge` turns this OFF: its documented provenance is `merge:<absolute source path>` for every
+     * imported row, so a merge must not start attributing rows to whatever the other host recorded.
+     */
+    preferEmbeddedSources?: boolean;
+}
+/** One row the store refused; the rest of the import continues. */
+export interface ImportFailure {
+    /** The document's `source_id`, or `null` when the row was too malformed to have one. */
+    source_id: number | null;
+    error: string;
+}
+/** Source id → target id for one fact this invocation actually CREATED. */
+export interface ImportNewId {
+    source_id: number | null;
+    new_fact_id: number;
+}
+/**
+ * Counts of values v1 could not carry, over the facts this invocation imported (or, for a dry run,
+ * planned to import). `1` per fact that actually carried the value; `0` when there was nothing to
+ * lose. See the module doc for why these are losses rather than silent successes.
+ */
+export interface MetadataDropped {
+    timestamps: number;
+    trust: number;
+    assert_count: number;
+    helpful_count: number;
+    pinned: number;
+    supersedes: number;
+}
+/** The single JSON object `import` prints (`file` is added by the CLI, which knows the argument). */
+export interface ImportReport {
+    /** The input form this run detected: an export document. */
+    mode: 'json';
+    version: number;
+    total: number;
+    imported: number;
+    /** Present on `--dry-run` only; the number of facts that WOULD be written. */
+    would_import?: number;
+    skipped_existing: number;
+    skipped_archived: number;
+    failed: ImportFailure[];
+    new_ids: ImportNewId[];
+    metadata_dropped: MetadataDropped;
+}
+/** The db→db variant's report. Field names kept from the original `merge` output. */
+export interface MergeReport {
+    /** The input form this run detected: a SQLite source database. */
+    mode: 'db';
+    source: string;
+    source_active: number;
+    added: number;
+    would_add: number;
+    skipped_existing: number;
+    skipped_archived: number;
+    failed: {
+        source_fact_id: number | null;
+        error: string;
+    }[];
+    new_ids: {
+        source_fact_id: number | null;
+        new_fact_id: number;
+    }[];
+}
+export interface MergeOptions {
+    /** Provenance for rows without an embedded source; default `merge:<absolute source path>`. */
+    sourceRef?: string;
+    /** Plan only: no model warmup, no write, `added` stays 0. */
+    dryRun?: boolean;
+}
+/**
+ * Export THIS runtime's memory facts. Read-only: the store's own connection is never asked to write
+ * (and this command needs no embedding model — the rows are already there).
+ */
+export declare function exportFacts(rt: FactsIoRuntime, options?: {
+    status?: ExportStatus;
+}): FactsExportDocument;
+/**
+ * The compression containers `export` can write. `none` is plain minified JSON (the format's
+ * canonical text, and what stdout always carries).
+ */
+export type FactsExportCodec = 'brotli' | 'gzip' | 'none';
+/**
+ * The one serialization. MINIFIED by default: the document is a machine artifact that gets
+ * compressed, and indentation only makes the uncompressed fallback bigger. `pretty` exists for
+ * debugging (a human reading a diff), never as the default — and it is the ONLY mode that appends
+ * the trailing newline that used to be unconditional.
+ */
+export declare function serializeFactsExport(doc: FactsExportDocument, options?: {
+    pretty?: boolean;
+}): string;
+/**
+ * Serialize + compress in one step. gzip uses level 9; brotli uses quality 11 and tells the encoder
+ * the input size, which is the smallest output either library produces for a one-shot export.
+ *
+ * `codec` defaults to `none` so a caller that says nothing gets the canonical minified JSON.
+ */
+export declare function encodeFactsExport(doc: FactsExportDocument, options?: {
+    codec?: FactsExportCodec;
+    pretty?: boolean;
+}): Buffer;
+/** The document an encoded file carries, plus the container it actually turned out to be. */
+export interface DecodedFactsExport {
+    doc: FactsExportDocument;
+    codec: FactsExportCodec;
+}
+/**
+ * Whether these bytes are a SQLite database, decided by the FILE HEADER.
+ *
+ * `mem_admin import` takes either an export document or another host's `memory.db`, and the only
+ * honest discriminator is the content: the export containers (plain / gzip / brotli) never start with
+ * the SQLite header, and a `.db` file renamed to `.json` still is one. Kept here, beside
+ * {@link decodeFactsExport}, so both content sniffers live together.
+ */
+export declare function isSqliteDatabase(bytes: Buffer): boolean;
+/**
+ * The same check for a PATH, reading only the 16-byte header.
+ *
+ * A `memory.db` can be hundreds of MiB; deciding which flow to take must not read it into memory
+ * first. The JSON path still reads the whole document (it has to decode it), but the db path hands the
+ * path straight to the read-only opener.
+ */
+export declare function isSqliteDatabaseFile(path: string): boolean;
+/**
+ * Decode one export file from its BYTES. The file name is deliberately not an input: gzip has a
+ * magic header, brotli does not, and a pre-compression export is plain JSON — so the only reliable
+ * discriminator is the content itself (a brotli file renamed to `.json` still imports, and a plain
+ * JSON file renamed to `.json.br` does too).
+ *
+ * Order, and why: gzip magic → gunzip (a corrupt gzip is refused as gzip, not silently "JSON");
+ * otherwise UTF-8 JSON (the backward-compatible path for every old pretty file); only when JSON
+ * parsing fails, brotli (its decoder rejects non-brotli input, so this cannot shadow a JSON
+ * document). A document that IS JSON but has the wrong format/version throws its own error right
+ * away — {@link parseFactsExport} is the format gate, not a fallback.
+ */
+export declare function decodeFactsExport(bytes: Buffer): DecodedFactsExport;
+/**
+ * Resolve the container for a file export: an explicit flag wins, then the extension (`.br` /
+ * `.gz`), then plain minified JSON. Shared by the CLI and `/mem` so the two surfaces cannot
+ * disagree about what `--out backup.json.gz` means.
+ */
+export declare function codecForExportPath(path: string, explicit?: FactsExportCodec): FactsExportCodec;
+/**
+ * Parse and validate an export document TEXT (the stdin entry point). Top-level format errors are
+ * FATAL (the caller must write nothing); a malformed individual fact is NOT — {@link importFacts}
+ * collects it in `failed` and keeps going. Restore is STRICTER by construction: it validates every
+ * row before opening its transaction, because skipping a row would produce a different history.
+ */
+export declare function parseFactsExport(text: string): FactsExportDocument;
+/**
+ * Import one export document into `rt`'s memory store.
+ *
+ * Order of decisions per fact: archived → skipped_archived (v1 never revives); content already in
+ * the target (or planned by an earlier row of this same document) → skipped_existing; otherwise the
+ * store's add path runs. A row the store refuses is collected in `failed` and the loop continues.
+ */
+export declare function importFacts(rt: FactsIoRuntime, doc: FactsExportDocument, options?: ImportOptions): Promise<ImportReport>;
+/**
+ * `merge` — the db→document→import form of the same union.
+ *
+ * The source is another host's file: opened read-only, never migrated, never written. The document is
+ * built in memory and handed to {@link importFacts}, so merge and `import` share one per-fact add
+ * path (and one failure-collection rule). Its provenance stays `merge:<absolute source path>` even
+ * when the source rows carry their own sources — that is the documented merge contract and the
+ * reason {@link ImportOptions.preferEmbeddedSources} can be turned off.
+ */
+export declare function mergeDb(rt: FactsIoRuntime, dbPath: string, options?: MergeOptions): Promise<MergeReport>;

package/lib/engine/mem/index.d.ts

@@ -21,6 +21,10 @@ export * from './trustHeartbeat.js';
 export * from './runtime.js';
 export * from './store/memory.js';
 export * from './store/knowledge.js';
+export { normalizeWrite } from './store/common.js';
+export * from './facts_io.js';
+export * from './maintenance_paths.js';
+export * from './store/facts_restore.js';
 export * from './store/vector_repair.js';
 export * from './store/hybrid.js';
 export * from './store/source_picker.js';

package/lib/engine/mem/maintenance_paths.d.ts

@@ -0,0 +1,41 @@
+import type { FactsExportCodec } from './facts_io.js';
+/** Hard cap on a file a maintenance action will read (import / merge / restore_snapshot). */
+export declare const MAINTENANCE_MAX_FILE_BYTES: number;
+/** Where an export lands when the caller does not name a file. */
+export declare const MAINTENANCE_BACKUP_DIRNAME = "backups";
+/**
+ * `<data home>/backups/memory-YYYYMMDD-HHMMSS.<ext>` — never inside `memory/`.
+ *
+ * Brotli is the default because it is the smallest (measured: 70.6 KiB vs 92.3 gzip vs 300.0 plain
+ * for 233 facts). A caller that passes another codec keeps the file name truthful by changing the
+ * suffix along with the bytes.
+ */
+export declare function defaultFactsExportPath(home: string, now?: Date, codec?: FactsExportCodec): string;
+/** A resolved export destination, plus whether this call will overwrite an existing file. */
+export interface MaintenanceExportTarget {
+    file: string;
+    existed: boolean;
+}
+/**
+ * Resolve an export destination inside the data root.
+ *
+ * The TARGET may not exist yet (that is the normal case), so containment is established on the
+ * nearest existing ancestor: every component below it is one this call will create, and a
+ * not-yet-created component cannot be a symlink. When the target DOES exist, its realpath is
+ * checked — a symlink pointing outside is refused rather than followed.
+ */
+export declare function resolveMaintenanceExportTarget(home: string, input?: string): MaintenanceExportTarget;
+/**
+ * Resolve an INPUT file (import / merge / restore_snapshot) inside the data root.
+ *
+ * The file must exist, be a regular file, and be no larger than {@link MAINTENANCE_MAX_FILE_BYTES}.
+ * A symlink to a regular file INSIDE the root is usable; a symlink that escapes it is refused before
+ * the size or existence of the outside target is examined.
+ */
+export declare function resolveMaintenanceInputFile(home: string, input: string): string;
+/**
+ * Write a file atomically: a sibling temp file, then one `rename` (same directory, so the rename
+ * cannot cross a filesystem). An overwrite is therefore either the old bytes or the new bytes, never
+ * a truncated export. The temp file is removed when anything fails.
+ */
+export declare function writeFileAtomic(path: string, bytes: Buffer | string): void;

package/lib/engine/mem/modelBootstrap.d.ts

@@ -55,22 +55,6 @@ export interface WarmOptions {
  *   path keeps it, because there the caller only sees this logger.
  */
 export declare function warmModels(rt: AvantfRuntime, options?: WarmOptions, reportFinal?: boolean): Promise<boolean>;
-/**
- * Warm ONLY the embedding model: load it from `semantic.cache_dir` and mark the engine ready.
- *
- * Split out of {@link warmModels} for the plugin's envinit path. There the framework fetches the
- * model in the BACKGROUND, so the warm has to wait for the item to settle instead of running at
- * mount — and the runtime's own constructor warm is deferred for exactly that reason
- * (`RuntimeOptions.managedRoots` → `deferWarm`), which is what stops it racing the install and
- * leaving a second copy behind. While the item is unsettled NOTHING warms; this function is the
- * explicit "files are there now, look" step, and it still runs when the item skipped/failed so
- * `semantic.auto_download` can decide between the runtime's own fetch and degradation.
- *
- * @param rt - the runtime whose memory store owns the semantic backend.
- * @param reportFinal - log the one-line verdict (default `true`).
- * @returns whether the semantic path is available.
- */
-export declare function warmSemantic(rt: AvantfRuntime, reportFinal?: boolean): Promise<boolean>;
 /**
  * Wait out the startup gate — the host readiness signal (bounded by {@link WAIT_FOR_HOST_MS}) and,
  * when asked, one quiet turn of the event loop.
@@ -88,18 +72,6 @@ export declare function warmSemantic(rt: AvantfRuntime, reportFinal?: boolean):
  * @returns how long the idle gate waited (ms), or `0` when it was not requested.
  */
 export declare function awaitStartupGate(options?: WarmOptions): Promise<number>;
-/**
- * Warm ONLY the tokenizer, after the host-readiness signal and (when asked) an idle event loop.
- *
- * nodejieba loads its dictionary lazily on the FIRST `tag()` (measured ~950 ms, after which a call
- * is 0.1 ms), so without this the first write/query of a session pays it while the user waits. Its
- * cost belongs to startup, and an unavailable jieba is worth saying out loud — entity extraction
- * silently degrades to the regex fallback (weaker entity/jaccard legs).
- *
- * @param rt - the runtime whose logger reports the outcome.
- * @param options - the host-readiness signal and the idle gate (see {@link WarmOptions}).
- */
-export declare function warmTokenizer(rt: AvantfRuntime, options?: WarmOptions): Promise<void>;
 /**
  * Non-blocking embedding warm, for a caller that knows the model files are already on disk.
  *
@@ -160,48 +132,7 @@ export interface ProvisionSweepResult {
  * @returns whether the sweep ran or was skipped for incompatibility.
  */
 export declare function provisionToolchainAsync(rt: AvantfRuntime, options?: ProvisionSweepOptions): Promise<ProvisionSweepResult>;
-/** The artifact id, used in the startup log and in the model artifact's errors. */
-export declare const MODEL_ARTIFACT_ID = "model";
 /** The environment a model-artifact call runs under: the runtime that owns the model cache. */
 export interface ModelArtifactEnv {
     runtime: AvantfRuntime;
 }
-/** The slice of an artifact call this module needs (`@avantf/mem-provision`'s InstallContext). */
-interface ModelInstallContext {
-    logger: {
-        info(message: string): void;
-        warn(message: string): void;
-        error(message: string): void;
-    };
-    artifactEnv?: unknown;
-    config: {
-        auto_install: boolean;
-    };
-}
-/**
- * The embedding model (plus the nodejieba tokenizer it shares its warm-up budget with) as an
- * ARTIFACT, so the startup sweep in `@avantf/mem-provision` is the only initialization path.
- *
- * It used to be a parallel model warm-up call beside the tools sweep, which meant two
- * startup mechanisms with two logging vocabularies and no single place that answered "is this host
- * fully provisioned?". The model has no pinned version and no managed directory of its own ON THIS
- * (the flat `<repo>/<file>` layout the transformers.js cache reads), so it
- * declares neither; its `isPresent` is `false` because "is the model warm?" is not a question that
- * can be answered without attempting the warm-up, and the warm-up is cheap when the cache is
- * already there (measured ~1.2 s, in the background). The DSH plugin uses this sweep only when the
- * family framework is unavailable — with the framework up, `mem:model` owns the model root instead
- * and this artifact is not registered.
- */
-export declare const modelArtifact: {
-    id: string;
-    title: string;
-    verb: string;
-    isPresent(): Promise<boolean>;
-    install(ctx: ModelInstallContext): Promise<void>;
-    verify(ctx: {
-        logger: ModelInstallContext["logger"];
-    }): Promise<void>;
-};
-/** Register the model artifact once per process (idempotent for a test that mounts twice). */
-export declare function registerModelArtifact(): void;
-export {};