@max-null/dsh-memory 0.14.0 → 0.15.0

package/dist/engine.d.ts

@@ -5,7 +5,6 @@
  * is always created `suggested` and becomes effective only through `setStatus`.
  */
 import { Service } from '@deepseek-ai/cordis';
-import { z } from 'zod';
 import { type PromptFile } from './prompt-files.ts';
 import type { AnchorProbes, MemoryAnchor } from './anchors.ts';
 import type { MemorySource, SourceStat } from './query-log.ts';
@@ -281,69 +280,6 @@ declare module '@deepseek-ai/cordis' {
         'memory/changed'(change: MemoryChange): void;
     }
 }
-/**
- * 存储块的 schema（门三的判据来源，2026-09-25）。
- *
- * **导出是为了让离线扫描器（`scripts/check-memory-files.mjs`）用它而不是自己再写一套**——
- * 两份判据会漂移，而漂移的方向恰好是「扫描器说没事、打开时炸」这种最难查的形态。
- */
-export declare const blockSchema: z.ZodObject<{
-    namespace: z.ZodEnum<{
-        global: "global";
-        project: "project";
-    }>;
-    status: z.ZodEnum<{
-        suggested: "suggested";
-        approved: "approved";
-        auto: "auto";
-        suggest: "suggest";
-    }>;
-    injected: z.ZodOptional<z.ZodBoolean>;
-    quarantined: z.ZodOptional<z.ZodBoolean>;
-    quarantineReason: z.ZodOptional<z.ZodString>;
-    hitCount: z.ZodOptional<z.ZodNumber>;
-    source: z.ZodOptional<z.ZodEnum<{
-        agent: "agent";
-        human: "human";
-    }>>;
-    injectedAuto: z.ZodOptional<z.ZodBoolean>;
-    anchor: z.ZodOptional<z.ZodObject<{
-        kind: z.ZodEnum<{
-            env: "env";
-            "tool-list": "tool-list";
-            "self-version": "self-version";
-            "path-exists": "path-exists";
-        }>;
-        name: z.ZodOptional<z.ZodString>;
-        value: z.ZodString;
-    }, z.core.$strip>>;
-    stale: z.ZodOptional<z.ZodBoolean>;
-    staleReason: z.ZodOptional<z.ZodString>;
-    content: z.ZodString;
-    keywords: z.ZodArray<z.ZodString>;
-    createdAt: z.ZodNumber;
-    updatedAt: z.ZodNumber;
-    lastUsedAt: z.ZodOptional<z.ZodNumber>;
-    vector: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
-    kind: z.ZodOptional<z.ZodEnum<{
-        fact: "fact";
-        prompt: "prompt";
-    }>>;
-    meta: z.ZodOptional<z.ZodObject<{
-        seq: z.ZodOptional<z.ZodNumber>;
-        name: z.ZodString;
-        dimension: z.ZodOptional<z.ZodString>;
-        difficulty: z.ZodOptional<z.ZodString>;
-        tags: z.ZodArray<z.ZodString>;
-        summary: z.ZodString;
-        path: z.ZodString;
-        mtime: z.ZodNumber;
-        source: z.ZodEnum<{
-            user: "user";
-            agent: "agent";
-        }>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
 /**
  * 嵌入能力（0.5.2 混合检索）：缺省不配置 = 纯 BM25（行为不变）；
  * 配置后 memory_search 以 BM25 与语义结果做 RRF 融合，向量持久化到

package/dist/engine.js

@@ -10,14 +10,14 @@ import { readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { Service } from '@deepseek-ai/cordis';
-import { z } from 'zod';
 import { defineDomain, domainTable, DomainFacility } from '@deepseek-ai/dsh-storage-domain';
 import { JsonStorageBackend } from '@deepseek-ai/dsh-storage-json';
 import { bm25FieldScores, cosineSimilarity, rrfFuse } from "./bm25.js";
 import { parsePromptFile, scanPromptDir, writePromptFile } from "./prompt-files.js";
 import { detectSensitive } from "./quarantine.js";
 import { SELF_VERSION } from "./self.js";
-import { ANCHOR_KINDS, anchorHolds } from "./anchors.js";
+import { anchorHolds } from "./anchors.js";
+import { blockSchema, describeIssues } from "./schema.js";
 import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, deriveSummary, renderInjection, } from "./injection.js";
 import { QueryLog, rankGapCandidates, summarizeQueryLog, summarizeSources } from "./query-log.js";
 /** Brand a string as a {@link MemoryId} (compile-time only). */
@@ -76,56 +76,9 @@ export function isAutoDemoteCandidate(record, threshold) {
     return (record.lastUsedAt ?? record.updatedAt) <= threshold;
 }
 /**
- * 存储块的 schema（门三的判据来源，2026-09-25）。
- *
- * **导出是为了让离线扫描器（`scripts/check-memory-files.mjs`）用它而不是自己再写一套**——
- * 两份判据会漂移，而漂移的方向恰好是「扫描器说没事、打开时炸」这种最难查的形态。
+ * 存储块的 schema 与 zod issue 的单行格式化，都在 {@link ./schema.ts}——单独成模块是为了
+ * 让离线扫描器能零 peer 依赖地加载它（见该文件头部）。
  */
-export const blockSchema = z.object({
-    namespace: z.enum(['global', 'project']),
-    status: z.enum(['suggested', 'approved', 'auto', 'suggest']),
-    injected: z.boolean().optional(),
-    quarantined: z.boolean().optional(),
-    quarantineReason: z.string().optional(),
-    hitCount: z.number().optional(),
-    source: z.enum(['agent', 'human']).optional(),
-    injectedAuto: z.boolean().optional(),
-    anchor: z.object({
-        kind: z.enum(ANCHOR_KINDS),
-        name: z.string().optional(),
-        value: z.string(),
-    }).optional(),
-    stale: z.boolean().optional(),
-    staleReason: z.string().optional(),
-    content: z.string(),
-    keywords: z.array(z.string()),
-    createdAt: z.number(),
-    updatedAt: z.number(),
-    lastUsedAt: z.number().optional(),
-    vector: z.array(z.number()).optional(),
-    kind: z.enum(['fact', 'prompt']).optional(),
-    meta: z.object({
-        seq: z.number().optional(),
-        name: z.string(),
-        dimension: z.string().optional(),
-        difficulty: z.string().optional(),
-        tags: z.array(z.string()),
-        summary: z.string(),
-        path: z.string(),
-        mtime: z.number(),
-        source: z.enum(['user', 'agent']),
-    }).optional(),
-});
-/**
- * 把 zod 的 issue 压成一行（门一，2026-09-25）。
- *
- * 排查成本的大头在「从 domain 打不开倒推」——`dsh-storage-domain` 封装后的错误只给到
- * 「哪个 domain 的哪条记录不合规」（`stored record '<id>' in table 'blocks' does not
- * match its schema`），**说不出是哪个字段、什么值、期望什么**。这行补的就是那段。
- */
-function describeIssues(error) {
-    return error.issues.map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
-}
 /** Shared table shape; the two domains differ only by name and backend route. */
 function memorySpec(name) {
     return defineDomain({

package/dist/schema.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 存储块的 schema —— **零 peer 依赖地可独立加载**。
+ *
+ * 为什么单独成模块：离线扫描器（`scripts/check-memory-files.mjs`）要 import 编译产物来跑
+ * 存量校验，而 `engine.js` 在运行时 import 了 `@deepseek-ai/cordis`、
+ * `@deepseek-ai/dsh-storage-domain`、`@deepseek-ai/dsh-storage-json`——那三个都是**由宿主
+ * 提供的 peer**，装版实体里没有。2026-09-29 实测：在 profile 里直接跑扫描器会报
+ * `Cannot find package '@deepseek-ai/cordis' imported from dist/engine.js`，于是
+ * 「用插件自己的 schema 扫存量」这条设计**在用户环境里根本跑不起来**。
+ *
+ * 本模块只依赖 `zod`（真 `dependencies`，装版有）与 `./anchors.ts`（只有 `node:fs` /
+ * `node:path`），所以 `dist/schema.js` 能被独立加载——**判据仍然只有一份**，不另写。
+ *
+ * @see docs/设计/2026-09-25-写入兜底与失败可见化-设计方案.md §四.3
+ */
+import { z } from 'zod';
+/**
+ * 存储块的 schema（门一与门三共用的判据来源，2026-09-25）。
+ *
+ * 门一（写入端）在 `putBlock` 里用它拒绝不合规的块；门三（存量体检）在扫描器里用它逐条
+ * 校验已有文件——**同一份定义**，因为两份判据会漂移，而漂移的方向恰好是「扫描器说没事、
+ * 打开时炸」这种最难查的形态。
+ */
+export declare const blockSchema: z.ZodObject<{
+    namespace: z.ZodEnum<{
+        global: "global";
+        project: "project";
+    }>;
+    status: z.ZodEnum<{
+        suggested: "suggested";
+        approved: "approved";
+        auto: "auto";
+        suggest: "suggest";
+    }>;
+    injected: z.ZodOptional<z.ZodBoolean>;
+    quarantined: z.ZodOptional<z.ZodBoolean>;
+    quarantineReason: z.ZodOptional<z.ZodString>;
+    hitCount: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodEnum<{
+        agent: "agent";
+        human: "human";
+    }>>;
+    injectedAuto: z.ZodOptional<z.ZodBoolean>;
+    anchor: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            env: "env";
+            "tool-list": "tool-list";
+            "self-version": "self-version";
+            "path-exists": "path-exists";
+        }>;
+        name: z.ZodOptional<z.ZodString>;
+        value: z.ZodString;
+    }, z.core.$strip>>;
+    stale: z.ZodOptional<z.ZodBoolean>;
+    staleReason: z.ZodOptional<z.ZodString>;
+    content: z.ZodString;
+    keywords: z.ZodArray<z.ZodString>;
+    createdAt: z.ZodNumber;
+    updatedAt: z.ZodNumber;
+    lastUsedAt: z.ZodOptional<z.ZodNumber>;
+    vector: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        fact: "fact";
+        prompt: "prompt";
+    }>>;
+    meta: z.ZodOptional<z.ZodObject<{
+        seq: z.ZodOptional<z.ZodNumber>;
+        name: z.ZodString;
+        dimension: z.ZodOptional<z.ZodString>;
+        difficulty: z.ZodOptional<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        summary: z.ZodString;
+        path: z.ZodString;
+        mtime: z.ZodNumber;
+        source: z.ZodEnum<{
+            user: "user";
+            agent: "agent";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * 把 zod 的 issue 压成一行（门一，2026-09-25）。
+ *
+ * 排查成本的大头在「从 domain 打不开倒推」——`dsh-storage-domain` 封装后的错误只给到
+ * 「哪个 domain 的哪条记录不合规」（`stored record '<id>' in table 'blocks' does not
+ * match its schema`），**说不出是哪个字段、什么值、期望什么**。这行补的就是那段。
+ */
+export declare function describeIssues(error: z.ZodError): string;

package/dist/schema.js

@@ -0,0 +1,69 @@
+/**
+ * 存储块的 schema —— **零 peer 依赖地可独立加载**。
+ *
+ * 为什么单独成模块：离线扫描器（`scripts/check-memory-files.mjs`）要 import 编译产物来跑
+ * 存量校验，而 `engine.js` 在运行时 import 了 `@deepseek-ai/cordis`、
+ * `@deepseek-ai/dsh-storage-domain`、`@deepseek-ai/dsh-storage-json`——那三个都是**由宿主
+ * 提供的 peer**，装版实体里没有。2026-09-29 实测：在 profile 里直接跑扫描器会报
+ * `Cannot find package '@deepseek-ai/cordis' imported from dist/engine.js`，于是
+ * 「用插件自己的 schema 扫存量」这条设计**在用户环境里根本跑不起来**。
+ *
+ * 本模块只依赖 `zod`（真 `dependencies`，装版有）与 `./anchors.ts`（只有 `node:fs` /
+ * `node:path`），所以 `dist/schema.js` 能被独立加载——**判据仍然只有一份**，不另写。
+ *
+ * @see docs/设计/2026-09-25-写入兜底与失败可见化-设计方案.md §四.3
+ */
+import { z } from 'zod';
+import { ANCHOR_KINDS } from "./anchors.js";
+/**
+ * 存储块的 schema（门一与门三共用的判据来源，2026-09-25）。
+ *
+ * 门一（写入端）在 `putBlock` 里用它拒绝不合规的块；门三（存量体检）在扫描器里用它逐条
+ * 校验已有文件——**同一份定义**，因为两份判据会漂移，而漂移的方向恰好是「扫描器说没事、
+ * 打开时炸」这种最难查的形态。
+ */
+export const blockSchema = z.object({
+    namespace: z.enum(['global', 'project']),
+    status: z.enum(['suggested', 'approved', 'auto', 'suggest']),
+    injected: z.boolean().optional(),
+    quarantined: z.boolean().optional(),
+    quarantineReason: z.string().optional(),
+    hitCount: z.number().optional(),
+    source: z.enum(['agent', 'human']).optional(),
+    injectedAuto: z.boolean().optional(),
+    anchor: z.object({
+        kind: z.enum(ANCHOR_KINDS),
+        name: z.string().optional(),
+        value: z.string(),
+    }).optional(),
+    stale: z.boolean().optional(),
+    staleReason: z.string().optional(),
+    content: z.string(),
+    keywords: z.array(z.string()),
+    createdAt: z.number(),
+    updatedAt: z.number(),
+    lastUsedAt: z.number().optional(),
+    vector: z.array(z.number()).optional(),
+    kind: z.enum(['fact', 'prompt']).optional(),
+    meta: z.object({
+        seq: z.number().optional(),
+        name: z.string(),
+        dimension: z.string().optional(),
+        difficulty: z.string().optional(),
+        tags: z.array(z.string()),
+        summary: z.string(),
+        path: z.string(),
+        mtime: z.number(),
+        source: z.enum(['user', 'agent']),
+    }).optional(),
+});
+/**
+ * 把 zod 的 issue 压成一行（门一，2026-09-25）。
+ *
+ * 排查成本的大头在「从 domain 打不开倒推」——`dsh-storage-domain` 封装后的错误只给到
+ * 「哪个 domain 的哪条记录不合规」（`stored record '<id>' in table 'blocks' does not
+ * match its schema`），**说不出是哪个字段、什么值、期望什么**。这行补的就是那段。
+ */
+export function describeIssues(error) {
+    return error.issues.map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`).join('; ');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {

package/scripts/check-memory-files.mjs

@@ -7,9 +7,14 @@
  * 的记忆静默消失」。2026-09-25 那次 154 条 project 记忆全部不可见就是这么来的：写入放行、
  * 加载才炸、失败还被吞。
  *
- * **判据怎么算**：用插件自己的 `blockSchema`（从 `dist/engine.js` import）逐条 `safeParse`。
+ * **判据怎么算**：用插件自己的 `blockSchema`（从 `dist/schema.js` import）逐条 `safeParse`。
  * 同源是刻意的——另写一套判定迟早漂移成「扫描器说没事、打开时炸」这种最难查的形态。
  *
+ * 为什么是 `dist/schema.js` 而不是 `dist/engine.js`：后者在运行时 import 了 `cordis` /
+ * `dsh-storage-domain` / `dsh-storage-json`，那三个是**宿主提供的 peer**，装版实体里没有
+ * ——直接加载会报 `Cannot find package '@deepseek-ai/cordis'`（2026-09-29 实测）。
+ * `schema.js` 只依赖 `zod`（真 dependencies）与 `anchors.js`（只有 node 内置），能独立加载。
+ *
  * **哪些情况答不了**：
  *   - 只校验 `tables.blocks` 里的条目，不校验外层信封结构；
  *   - 不处理压缩帧（那是 `unzstd-frames.mjs` 的事）；
@@ -37,13 +42,13 @@ function fail(message) {
 
 let blockSchema
 try {
-  ({ blockSchema } = await import('../dist/engine.js'))
+  ({ blockSchema } = await import('../dist/schema.js'))
 } catch (error) {
   fail(
-    `无法加载 dist/engine.js（先跑 npm run build）：${error instanceof Error ? error.message : String(error)}`,
+    `无法加载 dist/schema.js（先跑 npm run build）：${error instanceof Error ? error.message : String(error)}`,
   )
 }
-if (blockSchema === undefined) fail('dist/engine.js 没有导出 blockSchema——构建产物太旧？')
+if (blockSchema === undefined) fail('dist/schema.js 没有导出 blockSchema——构建产物太旧？')
 
 /** 递归收集目录下的 *.json（跳过 node_modules）。 */
 function collect(target, out = []) {