@a9i5k4/dsh-auto-memory 3.0.0 → 3.0.1

package/lib/wb-contract.js

@@ -42,7 +42,12 @@ export const WB_MARKERS_V1 = Object.freeze({
   userClose: '<!-- /user -->',
 })
 
-/** 卡片状态（与记忆条目状态同域；缺 `status` 视为 `current`，与 `isCurrentPre` 口径一致）。 */
+/** 卡片状态（与记忆条目状态同域；缺 `status` 视为 `current`，与 `isCurrentPre` 口径一致）。
+ *  ⚠️ 2026-09-17 L7 存活标注: 本常量**当前无仓内消费者**(全仓引用计数 = 1, 仅此定义)。
+ *  判定 = **对外契约保留**, 不删 —— 理由是它是 WB-FORMAT-CONVENTION 的**状态值域声明**
+ *  (`current`/`superseded`/`retracted`), 属已发布插件 (@a9i5k4/dsh-auto-memory 3.0.0, 有真实用户)
+ *  的公开导出面; 第三方按契约读取状态时需要它作为**单一真源**, 删掉等于把值域契约降级成散落字面量。
+ *  ⇒ 保留 + 显式标注, 不做"沉默留着"。 */
 export const WB_STATUSES_V1 = Object.freeze(['current', 'superseded', 'retracted'])
 
 /** 解析/校验的原因码 → 可读中文。 */
@@ -59,7 +64,11 @@ export const WB_REASONS_V1 = Object.freeze({
   'user-region-interleaved': '人机分区标记交错（user 段里又开 model 段）',
 })
 
-/** 原因码 → 可读中文（未知码原样返回，排障不吞信息）。 */
+/** 原因码 → 可读中文（未知码原样返回，排障不吞信息）。
+ *  ⚠️ 2026-09-17 L7 存活标注: 本函数**当前无仓内调用者**(全仓引用计数 = 1, 仅此定义)。
+ *  判定 = **对外契约保留**, 不删 —— 它是 `WB_REASONS_V1`(上文, **有消费者**) 的唯一
+ *  取值入口; 删掉函数会让那份码表的"怎么读"离开公开面, 而码表本身是契约的一部分
+ *  (发布版已有真实用户)。⇒ 保留 + 显式标注。 */
 export function describeWbReasonPre(code) {
   const k = String(code == null ? '' : code)
   return WB_REASONS_V1[k] || k || '未知原因'
@@ -254,6 +263,193 @@ function emptyResult(kind, issues) {
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// ★M2（2026-09-18）白板 lint —— 契约 §6「零 token 可判的四类」
+//
+// **硬约束（契约 §6 尾注，不可越）**：lint **只报告，不自动改**。
+//   「任何自动修正都会把白板变成状态机（违反边界）」
+// ⇒ 本模块是**纯函数**：不读文件、不写文件、不 import fs。
+//   输入什么就判什么，输出问题清单。任何写盘能力都不得塞进这里（报告与写入分离）。
+//
+// 四类判据（§6 原文）与**本实现的口径**（判据纪律：宁可漏判，不可误伤）：
+//   ① 孤立条目：无入站引用            → 全部卡正文里都找不到它的 id/标题
+//   ② 陈旧：status≠current 或超期 current → 状态直读 + 与 now 比日期
+//   ③ 被提及却无独立卡               → ★ 只判**客观可证**的一种：正文引用了
+//      `mem_<32hex>` 但该 id 没有对应卡片（"什么算概念"无法零 token 判定，不猜）
+//   ④ 缺交叉引用                    → ★ 只判**客观可证**的一种：两卡共享 ≥N 个 tag
+//      却互不引用（"什么算相关"由 tag 交集代言，不猜语义）
+//   ⑤ 矛盾检测 → 需 LLM，**不在本模块**（契约 §6：必须手动触发，不进自动路径）
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const WB_LINT_VERSION = 'wb_lint_v1'
+
+/** lint 问题码（§6 四类；⑤ 矛盾检测需 LLM，不在此列）。 */
+export const WB_LINT_CODES_V1 = Object.freeze({
+  ORPHAN: 'orphan',                   // ① 孤立条目
+  INACTIVE: 'inactive',               // ② 陈旧（已标 superseded/retracted）
+  EXPIRED: 'expired',                 // ② 陈旧（仍标 current 但超阈值）
+  DANGLING_REF: 'dangling-ref',       // ③ 被引用却无卡（悬空锚点引用）
+  NO_CROSS_REF: 'no-cross-ref',       // ④ 缺交叉引用（共享 tag 却互不引用）
+})
+
+/** 默认口径。 */
+export const WB_LINT_DEFAULTS_V1 = Object.freeze({
+  staleDays: 90,      // ② 仍标 current 但日期早于 now-90d ⇒ 报 expired
+  minSharedTags: 2,   // ④ 共享 tag 数 ≥ 2 才算"应互链"
+})
+
+const LINT_ANCHOR_RE = /mem_[0-9a-f]{32}/g
+
+const asDateMs = (v) => {
+  const s = String(v == null ? '' : v)
+  const m = s.match(/^(\d{4})-(\d{2})-(\d{2})/)
+  if (!m) return NaN
+  const t = Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))
+  return Number.isFinite(t) ? t : NaN
+}
+
+/**
+ * 白板 lint（**只读纯函数**，契约 §6）。
+ *
+ * @param {Array<object>|{entries?:Array<object>}} entries 条目数组；每项可含
+ *   `{id, title, status, date, ts, tags, body}`。`body` 为该卡正文（用于扫描引用）；
+ *   缺 `body` 时退化为用 `title+id` 判引用（**不报错**——信息少就少判，不猜）。
+ * @param {{now?:Date|string|number, staleDays?:number, minSharedTags?:number, corpus?:string}} [opts]
+ *   `corpus` 为白板之外的**额外文本**（如项目笔记/账本全文），一并参与"入站引用"扫描。
+ * @returns {{version:string, ok:boolean, findings:Array<object>, counts:object}}
+ */
+export function lintWhiteboardPre(entries, opts = {}) {
+  const o = opts && typeof opts === 'object' ? opts : {}
+  const list = Array.isArray(entries) ? entries
+    : (entries && Array.isArray(entries.entries) ? entries.entries : [])
+  const staleDays = Number.isFinite(Number(o.staleDays)) ? Number(o.staleDays) : WB_LINT_DEFAULTS_V1.staleDays
+  const minSharedTags = Number.isFinite(Number(o.minSharedTags)) ? Number(o.minSharedTags) : WB_LINT_DEFAULTS_V1.minSharedTags
+
+  const nowMs0 = o.now instanceof Date ? o.now.getTime()
+    : (typeof o.now === 'number' ? o.now : asDateMs(o.now))
+  const nowMs = Number.isFinite(nowMs0) ? nowMs0 : Date.now()
+
+  // ── 归一化（**永不抛**：坏条目降级为跳过，不打断整轮 lint）──
+  const cards = []
+  let skipped = 0
+  for (const e of list) {
+    if (!e || typeof e !== 'object') { skipped++; continue }
+    const id = String(e.id || '')
+    const title = String(e.title || '').trim()
+    if (!id && !title) { skipped++; continue }
+    const status = String(e.status || 'current').trim() || 'current'
+    const dateSrc = e.date || e.ts || ''
+    const tags = Array.isArray(e.tags) ? e.tags.map((t) => String(t)).filter(Boolean) : []
+    cards.push({ id, title, status, tags, dateMs: asDateMs(dateSrc), dateRaw: String(dateSrc || '') })
+  }
+
+  // ── 引用语料：所有卡正文 + 外部 corpus ──
+  const parts = []
+  for (const e of list) {
+    if (e && typeof e === 'object') {
+      if (e.body != null) parts.push(String(e.body))
+      if (e.preview != null) parts.push(String(e.preview))
+    }
+  }
+  if (o.corpus != null) parts.push(String(o.corpus))
+  const haystack = parts.join('\n')
+
+  const findings = []
+  const push = (code, card, detail) => {
+    findings.push({ code, id: card ? card.id : '', title: card ? card.title : '', detail })
+  }
+
+  // ── ① 孤立条目：无入站引用 ──
+  // 判据：除自己以外，任何卡正文/外部语料都未出现它的 id，也未出现它的标题。
+  // 纪律：**只报"全无提及"**；标题过短（<2 字符）时跳过，避免单字误命中（宁可漏判）。
+  for (const c of cards) {
+    let referenced = false
+    if (c.id) {
+      const re = new RegExp(c.id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')
+      const hits = haystack.match(re)
+      // 自己正文里出现自己的 id 不算入站引用
+      const selfBody = String((list.find((x) => x && x.id === c.id) || {}).body || '')
+      const selfHits = selfBody.match(re)
+      const inHits = (hits ? hits.length : 0) - (selfHits ? selfHits.length : 0)
+      if (inHits > 0) referenced = true
+    }
+    if (!referenced && c.title && c.title.length >= 2) {
+      if (haystack.includes(c.title)) {
+        // 标题出现次数 > 自身正文里的次数 ⇒ 有外部提及
+        const selfBody = String((list.find((x) => x && x.id === c.id) || {}).body || '')
+        const total = haystack.split(c.title).length - 1
+        const selfN = selfBody.split(c.title).length - 1
+        if (total - selfN > 0) referenced = true
+      }
+    }
+    if (!referenced) push(WB_LINT_CODES_V1.ORPHAN, c, '无任何其他卡片或语料引用它的 id/标题')
+  }
+
+  // ── ② 陈旧 ──
+  const cutoff = nowMs - staleDays * 86400000
+  for (const c of cards) {
+    if (c.status !== 'current') {
+      push(WB_LINT_CODES_V1.INACTIVE, c, 'status=' + c.status + '（已作废，仍在白板内）')
+      continue
+    }
+    if (Number.isFinite(c.dateMs) && c.dateMs < cutoff) {
+      const ageDays = Math.floor((nowMs - c.dateMs) / 86400000)
+      push(WB_LINT_CODES_V1.EXPIRED, c, '仍标 current 但日期为 ' + c.dateRaw + '（' + ageDays + ' 天前，超阈值 ' + staleDays + ' 天）')
+    }
+  }
+
+  // ── ③ 悬空锚点引用：正文引用了 mem_id 但没有对应卡片 ──
+  // 契约 §2 的 id 是"内容寻址、可复算"的 ⇒ 引用了不存在的 id 是**客观可证**的断裂。
+  const knownIds = new Set(cards.map((c) => c.id).filter(Boolean))
+  const allIds = new Set()
+  for (const m of haystack.match(LINT_ANCHOR_RE) || []) allIds.add(m)
+  for (const id of allIds) {
+    if (!knownIds.has(id)) {
+      findings.push({
+        code: WB_LINT_CODES_V1.DANGLING_REF, id, title: '',
+        detail: '正文引用了 ' + id + '，但白板内没有该 id 的卡片（悬空引用）',
+      })
+    }
+  }
+
+  // ── ④ 缺交叉引用：共享 ≥minSharedTags 个 tag 却互不引用 ──
+  for (let i = 0; i < cards.length; i++) {
+    for (let j = i + 1; j < cards.length; j++) {
+      const a = cards[i], b = cards[j]
+      if (!a.tags.length || !b.tags.length) continue
+      const shared = a.tags.filter((t) => b.tags.includes(t))
+      if (shared.length < minSharedTags) continue
+      const aRefB = (a.id && b.id && String((list.find((x) => x && x.id === a.id) || {}).body || '').includes(b.id)) ||
+        (b.title && String((list.find((x) => x && x.id === a.id) || {}).body || '').includes(b.title))
+      const bRefA = (a.id && b.id && String((list.find((x) => x && x.id === b.id) || {}).body || '').includes(a.id)) ||
+        (a.title && String((list.find((x) => x && x.id === b.id) || {}).body || '').includes(a.title))
+      if (!aRefB && !bRefA) {
+        findings.push({
+          code: WB_LINT_CODES_V1.NO_CROSS_REF, id: a.id, title: a.title,
+          detail: '与「' + (b.title || b.id) + '」共享 ' + shared.length + ' 个 tag（' + shared.join(', ') + '）但互不引用',
+        })
+      }
+    }
+  }
+
+  const byCode = {}
+  for (const f of findings) byCode[f.code] = (byCode[f.code] || 0) + 1
+
+  return {
+    version: WB_LINT_VERSION,
+    ok: findings.length === 0,
+    findings,
+    counts: {
+      cards: cards.length,
+      skipped,
+      findings: findings.length,
+      byCode,
+      // ⑤ 明确声明"未判" —— 不许静默省略（契约 §6：需 LLM，必须手动触发）
+      notChecked: ['contradiction'],
+    },
+  }
+}
+
 /**
  * 从投影里抽出"**必须逐字节保留**的用户区"（供写入门做前后比对）。
  *

package/lib/wb-sidecar.js

@@ -287,8 +287,17 @@ export function buildSectionCardsPre(workspaceKey, docs, opts = {}) {
  * 契约对齐 WB-GRAPH-INTEGRATION-PLAN §4.1(条目级): id/kind/source/section/tags/cues/preview/mtime/criteria。
  * 兼容旧字段: title/cue/chars/ts 保留(既有套件与工具描述在用)。
  *
+ * ★M1（2026-09-18）新增 `layer`/`status`：契约 §3 的索引派生行要求两者
+ *   （`… · layer=whiteboard · status=current · 日期`）。此前 entry 只有 `id`（已是
+ *   `mem_<32hex>` 形态），缺这两个字段 ⇒ 渲染侧拿不到值，一直退化成纯文本行。
+ *   - `layer` 恒为 `'whiteboard'`：本模块**只服务于白板/账本**这一层，
+ *     不是从调用方传入的自由值（避免调用方各传各的、导致层级语义漂移）。
+ *   - `status` 取 `o.status`，缺省 `'current'`（与契约 §3 尾注
+ *     「缺 status 视为 current」、与 `isCurrentPre` 口径一致）。
+ *   两个字段**只增不改**：既有字段顺序与语义逐字节不变。
+ *
  * @param {{workspaceKey:string, relPath:string, text:string, title:string, ts?:string,
- *          kind?:string, mtime?:number, criteria?:string}} o
+ *          kind?:string, mtime?:number, criteria?:string, status?:string}} o
  */
 export function buildSidecarEntryPre(o = {}) {
   const src = String(o.text || '')
@@ -308,6 +317,9 @@ export function buildSidecarEntryPre(o = {}) {
     preview: src.replace(/\s+/g, ' ').trim().slice(0, 120),
     mtime: Number(o.mtime) || 0,
     criteria: String(o.criteria || 'unknown'),
+    // ── ★M1：契约 §3 索引派生行所需（只增不改）──
+    layer: 'whiteboard',
+    status: String(o.status || 'current'),
     // ── 兼容旧套件/工具描述的字段 ──
     title,
     cue: cueLine.trim().slice(0, 120),
@@ -316,6 +328,45 @@ export function buildSidecarEntryPre(o = {}) {
   }
 }
 
+/**
+ * ★M1（2026-09-18）：sidecar 条目 → Tier-0 目录项（**契约 §8 的桥**）。
+ *
+ * 契约 §8 要求：「由页面派生出的 index 与 Tier-0 目录条目**一致**」。
+ * 实现方式 = **同一次派生、两种渲染** —— 本函数**只做字段映射，不复制任何逻辑**：
+ *   entries 与 Tier-0 条目本就是同一份数据，映射后交给
+ *   `renderCatalogLinePre` 渲染，一致性天然成立（无需额外同步机制）。
+ *
+ * 为什么不在此处直接渲染成字符串：渲染口径必须**只有一处实现**
+ *   （`renderCatalogLinePre`），否则「两种渲染」会退化成「两个渲染器」，
+ *   长期必然漂移 —— 这正是 §8 想防的。
+ *
+ * 字段映射（只映射，不发明）：
+ *   - title   ← entry.title
+ *   - oneLine ← entry.preview（已是单行化 + 120 字截断，即「一句话摘要」）
+ *   - layer   ← entry.layer（本模块恒为 'whiteboard'）
+ *   - status  ← entry.status（缺省 'current'）
+ *   - date    ← entry.ts 的日期部分（无则空；不编造）
+ *   - path    ← entry.source（相对路径，渲染时拼锚点）
+ *   - id      ← entry.id（已是 mem_<32hex>）
+ *
+ * @param {object} entry buildSidecarEntryPre 的产物
+ * @returns {{title:string,oneLine:string,layer:string,status:string,date:string,path:string,id:string}}
+ */
+export function sidecarEntryToCatalogItemPre(entry) {
+  const e = entry && typeof entry === 'object' ? entry : {}
+  const ts = String(e.ts || '')
+  const dateOnly = (ts.match(/^\d{4}-\d{2}-\d{2}/) || [''])[0]
+  return {
+    title: String(e.title || ''),
+    oneLine: String(e.preview || ''),
+    layer: String(e.layer || 'whiteboard'),
+    status: String(e.status || 'current'),
+    date: dateOnly,
+    path: String(e.source || ''),
+    id: String(e.id || ''),
+  }
+}
+
 /** tag → 条目 id 倒排(§3.3 by_tag)。 */
 export function buildByTagPre(entries) {
   const byTag = {}
@@ -389,10 +440,10 @@ export function rebuildSidecarIndexPre(workspaceKey, docs) {
 
 /** 生成 §4.1 的 hint 文案(工具返回值里引导模型向下走)。 */
 function hintForExpand() {
-  return '可用 memory_trace_pre(id) 回溯该条目的 cue/tag/邻居与归档版本'
+  return '可用 memory_trace(id) 回溯该条目的 cue/tag/邻居与归档版本'
 }
 function hintForTrace() {
-  return '可用 memory_expand_pre(tag) 按 tag 展开同主题条目; neighbors 为同 tag/同 cue 的相邻条目'
+  return '可用 memory_expand(tag) 按 tag 展开同主题条目; neighbors 为同 tag/同 cue 的相邻条目'
 }
 
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@a9i5k4/dsh-auto-memory",
   "description": "Proactive associative memory for DSH: zero-prompt recall injected before the model speaks, three-layer auto-consolidation, skill crystallization, and Astra-style context management - handoff ledgers, PLAN whiteboard, water-level sensing. Local-first, model-agnostic, zero deps. 主动联想记忆+Astra 式上下文管理:自动唤回/自动沉淀/技能固化/交接账本与白板跨窗口续命/水位感知。",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "type": "module",
   "main": "lib/index.js",
   "exports": {