@a9i5k4/dsh-auto-memory 2.5.2 → 3.0.0

package/lib/water-window.js

@@ -27,9 +27,19 @@ export function parseModelWindowsPre(text) {
     // provider 段(block 风格,2 空格缩进的裸键,如 `opencode-go:`);flow 风格段名同样以冒号结尾但缩进更深
     const pm = line.match(/^ {2}([A-Za-z0-9_.-]+):\s*$/)
     if (pm) { currentProvider = pm[1]; currentId = null; continue }
-    // 模型 id:兼容 block(`- id: x`)与 flow(`id: x,`)两种写法,允许行尾逗号
-    const im = line.match(/^\s*(?:-\s*)?id:\s*([A-Za-z0-9._:-]+?)\s*,?\s*$/)
+    // 模型 id:兼容 block(`- id: x`)与 flow(`id: x,`)两种写法,允许行尾逗号。
+    // 2026-09-14 移植 PR #31(上游修复,作者 Minervaowl7):字符类须含 `/` ——
+    // provider 前缀式 id(`deepseek/deepseek-v4.1-flash`、`z-ai/glm-5.3-flash`、`meituan/LongCat-2.0:free`)
+    // 是常见形态;旧字符类不含斜杠 → 整条 id 行匹配失败,其 contextWindow 被**静默丢弃**,
+    // 窗口退化为 fallback 131072。实测:真实窗口 1,000,000 的会话被按 131,072 当分母,
+    // **水位放大 7.63 倍(12.8% 显示成 98%)**,未达 0.75 阈值即误弹「接续到新会话」确认卡。
+    const im = line.match(/^\s*(?:-\s*)?id:\s*([A-Za-z0-9._:/-]+?)\s*,?\s*$/)
     if (im) { currentId = im[1]; if (byModel[currentId] === undefined) byModel[currentId] = 0; continue }
+    // 2026-09-14 补齐 PR #31 的第二半:上一轮只移植了「字符类须含 `/`」那一半,漏了本条。
+    // id 行存在但格式仍不被识别(带引号/含空格/中文等):重置 currentId,避免紧随其后的
+    // contextWindow 被记到上一条模型头上 —— 静默错配比"读不到"更危险:读不到只退化为 fallback,
+    // 错配会给出**偏小**的窗口,使水位漏报。
+    if (/^\s*(?:-\s*)?id:/.test(line)) { currentId = null; continue }
     // 窗口:允许行尾逗号(flow 风格)
     const cm = line.match(/^\s*contextWindow:\s*([0-9]+)\s*,?\s*$/)
     if (cm && currentId) {
@@ -175,3 +185,79 @@ export function findOfficialContextWindowPre(events, maxScan = 0) {
   }
   return 0
 }
+
+/**
+ * 判断「会话模型扫描结果」缓存可否复用(2026-09-14)。
+ *
+ * checkWaterLevel 把事件扫描结果按会话缓存 5 分钟,但**空结果也被一并缓存**:
+ *   `if (cached && cached.sid === sid && now - cached.at < 300000 && cached.info) { 复用 }`
+ * `cached.info` 恒为对象(即使内容为空) ⇒ 空结果照样命中,并被锁死 5 分钟。
+ *
+ * 而 `request/header` / `request/context` 是**发起请求时**才追加的事件 —— 实测同一轮内
+ * `turn/start`(seq=4) → `request/context`(seq=13) 仅相隔 58ms,而首轮 `agent/pre-step`
+ * 的测量早于这两条(step/start 在 request/context 之前约 21ms)。所以首次扫描必然扫不到
+ * `request/context`:只能从 `request/header` 拿到 provider/model,`contextWindow` 为 0。
+ * 该结果随后被锁死 5 分钟,这 5 分钟里 `official-context`(路由权威口径)始终不可用,
+ * 窗口只能靠 settings.yaml 查表;若该模型在 settings.yaml 里查不到(新模型 / 切到未配置的
+ * provider),窗口即退化为 fallback 131072,水位被系统性放大。
+ *
+ * 复用规则:
+ *  - **非空**(contextWindow > 0):TTL 内直接复用 —— `request/context` 只在会话开头追加、值稳定,
+ *    且扫描是 O(n),长会话理应避免重复全量扫描。
+ *  - **空**:仅在**事件数未增长**时复用 —— 事件数增长意味着可能有新事件写入,值得重扫一次;
+ *    未增长则复用,不为每个 pre-step 付出一次 O(n) 扫描。
+ *
+ * 兼容性:`cached.events` 为本次新增字段,旧缓存对象取到 undefined ⇒ 与 eventsLen 不相等 ⇒
+ * 不复用、走重扫 —— 安全降级。
+ *
+ * @param {{sid:string, at:number, info:object, events:number}|null|undefined} cached - 上次缓存(cached.events = 扫描时的事件数)。
+ * @param {string} sid - 当前会话 id。
+ * @param {number} eventsLen - 当前事件数组长度。
+ * @param {number} now - 当前时间戳(ms)。
+ * @param {number} [ttlMs=300000] - 缓存有效期。
+ * @returns {boolean} true 表示可复用 cached.info。
+ */
+export function reusableWindowCachePre(cached, sid, eventsLen, now, ttlMs = 300000) {
+  if (!cached || !sid) return false
+  if (cached.sid !== sid) return false
+  if (!(now - Number(cached.at || 0) < ttlMs)) return false
+  const info = cached.info
+  if (!info) return false
+  if (Number(info.contextWindow) > 0) return true
+  return Number(cached.events) === Number(eventsLen)
+}
+
+/**
+ * 判断是否具备「按水位比例触发自动接续」的资格(2026-09-14)。
+ *
+ * 背景:窗口来源优先级为 手动覆盖 > 官方 request/context > settings.yaml 按「会话真实模型」查表
+ * > fallback 131072。而「会话真实模型」只能从会话事件 `request/header` / `request/context` 读取 ——
+ * DSH 的 sessionApi 只提供 `selectModel`(只写不读),没有任何查询会话当前模型的接口。
+ *
+ * 这两个事件都是**发起请求时**才追加的:实测首轮 `turn/start` → `request/header` 之间不存在任何
+ * 模型信息,即在 **新会话首轮 `agent/pre-step`** 的测量点上,`findSessionModelPre` 返回
+ * `{provider:'',model:'',contextWindow:0,maxTokens:0}` —— **全空**。此时窗口与预留额度只能用
+ * settings.yaml 的 `agent-default-model` 推算,而它与会话实际模型可以完全不同
+ * (实测同一台机器上 `agent-default-model` 是 `command-code/deepseek-v4.1-flash`,
+ * 而某个会话实际跑的是 `deepseek-official/deepseek-flash`,连 `maxTokens` 都不一致)。
+ *
+ * 用推算出来的分母按比例触发「建新会话 + 注入交接材料 + 切走窗口」这类重动作,风险不对称:
+ * 分母偏小会让水位虚高数倍(实测 1,000,000 被当 131,072,放大 7.63 倍),未达阈值即误弹接续卡。
+ * 因此模型未知时**只放行硬信号**(`compaction` / `overflow` / 撞硬墙 —— 均为真实事件,不依赖窗口估算);
+ * 纯比例判据推迟到轮末再判 —— 届时 `request/header` 已写入,模型已知,判定链条完整。
+ *
+ * `wl.modelKnown !== true` 采用 fail-closed(2026-09-14 审查修正):字段缺失(undefined/null/0)一律
+ * 视为「未知」,只放行硬信号。原先 `=== false` 显式判等本意是让未传字段的旧调用点行为不变,但
+ * checkWaterLevel 存在早退路径(handoff 关闭 / win<=0 / 测量中途异常),此时 rt.waterLevelModelKnown
+ * 为 undefined → 闸被静默绕过(变异验证:直调 {ratio:0.99, modelKnown:undefined, hard:false} 放行)。
+ * fail-closed 后该路径收口为「不按比例 arm」—— 漏判优于误判,与本函数的整体取舍一致;两个 in-repo
+ * 调用点都以 `!!(...)` 写入真布尔,正常测量路径行为不变。
+ *
+ * @param {{ratio:number, modelKnown?:boolean, hard?:boolean}|null|undefined} wl - 水位快照。
+ * @returns {boolean} true 表示允许按比例 arm。
+ */
+export function shouldArmAutoContinuePre(wl) {
+  if (!wl) return false
+  if (wl.modelKnown !== true && !wl.hard) return false
+  return true
+}

package/lib/wb-contract.js

@@ -0,0 +1,495 @@
+/**
+ * 白板格式适配器（wb_contract_v1）—— 白板线拥有「白板格式及其适配器」。
+ *
+ * 2026-09-14 建立（P0 最小适配边界）。**边界（总纲 §0.5 / ROUND3 §3.1 定案）**：
+ *   - **3.0 主体**拥有「共同提交与保护入口」= `lib/memory-mutation.js:validateMutationBoundaryPre`
+ *     —— 它**只接收规范化投影**（`beforeIds/afterIds/protectedRegions/changes`），**不自行解释图格式**。
+ *   - **白板线**拥有「白板格式及其适配器」= **本模块** `parseWhiteboardPre`
+ *     —— 格式只维护一份（`docs/internal/WB-FORMAT-CONVENTION.md` 是规格源）。
+ *   这样切的意义：写入门要保护**卡片集合**与**用户区**，而这两个概念由白板格式定义；
+ *   没有适配器就是"接口接上了但保护失效"。
+ *
+ * **规格源**：`docs/internal/WB-FORMAT-CONVENTION.md`
+ *   §2 锚点契约（每个卡片/小节标题行下方紧跟 `<!-- memory:mem_<32hex> -->`）；
+ *   §5 人机分区（`<!-- model -->…<!-- /model -->` 与 `<!-- user -->…<!-- /user -->`，模型整篇重写
+ *      必须原样带回 user 段）。**B4 预授权默认值**：从选项 (c) 起步 = 每张卡片分「模型维护区 / 用户备注区」。
+ *   **A8 预授权默认值**：id = `mem_` + sha256(workspaceKey + '\u0000' + 页面相对路径 + '\u0000' + 卡片标题) 前 32 位。
+ *
+ * **现状缺口（2026-09-14 实测，这是本模块存在的直接理由）**：规范 §5 **早已定义**人机分区，
+ * 但实际 `PLAN.md` **一个锚点、一个分区标记都没有** —— 规范已批准、代码从未实现。
+ * 这正是「白板被整篇覆盖成骨架」事故的根因。
+ *
+ * **本模块只做解析，不做判定**：它产出规范化投影（卡 id 集合、用户区集合、状态、标题），
+ * 由 `validateMutationBoundaryPre` 决定接受/拒绝。职责不混，是为了让"格式"只有一个真源。
+ *
+ * S9 合规：零 IO、纯函数、同输入同输出、无网络/无 LLM/无子进程/无 await。
+ * UTF-8 无 BOM。
+ */
+import { createHash } from 'node:crypto'
+// 账本四段判据复用既有解析器（`handoff-anchor.js` 是账本段结构的既有权威，不另写一份）
+import { parseHandoffLedgerPre, HANDOFF_LEDGER_SECTION_WEIGHTS_V1 } from './handoff-anchor.js'
+
+export const WB_CONTRACT_VERSION = 'wb_contract_v1'
+
+/** 锚点正则（与 `l0-extract.js` 的 `MEM_ANCHOR_RE` 完全一致；契约 §2 要求"完全一致"）。 */
+export const WB_ANCHOR_RE_V1 = /^<!--\s*memory:(mem_[0-9a-f]{32})\s*-->$/
+
+/** 分区标记（契约 §5 逐字）。 */
+export const WB_MARKERS_V1 = Object.freeze({
+  modelOpen: '<!-- model -->',
+  modelClose: '<!-- /model -->',
+  userOpen: '<!-- user -->',
+  userClose: '<!-- /user -->',
+})
+
+/** 卡片状态（与记忆条目状态同域；缺 `status` 视为 `current`，与 `isCurrentPre` 口径一致）。 */
+export const WB_STATUSES_V1 = Object.freeze(['current', 'superseded', 'retracted'])
+
+/** 解析/校验的原因码 → 可读中文。 */
+export const WB_REASONS_V1 = Object.freeze({
+  'not-string': '内容不是字符串',
+  'empty': '内容为空',
+  'no-card': '页面里没有任何卡片标题（`### ` 行）',
+  'anchor-missing': '卡片标题下方缺少锚点行 `<!-- memory:mem_<32hex> -->`',
+  'anchor-format': '锚点格式不合法（必须是 mem_ + 32 位小写十六进制）',
+  'anchor-duplicate': '同一个 id 被两个卡片复用（契约 §2 禁止）',
+  'anchor-mid-body': '锚点不在标题行下方紧跟位置（契约 §2 禁止把锚点写在卡片正文中间）',
+  'user-region-unclosed': '`<!-- user -->` 未闭合',
+  'model-region-unclosed': '`<!-- model -->` 未闭合',
+  'user-region-interleaved': '人机分区标记交错（user 段里又开 model 段）',
+})
+
+/** 原因码 → 可读中文（未知码原样返回，排障不吞信息）。 */
+export function describeWbReasonPre(code) {
+  const k = String(code == null ? '' : code)
+  return WB_REASONS_V1[k] || k || '未知原因'
+}
+
+const isAnchor = (line) => WB_ANCHOR_RE_V1.test(String(line || '').replace(/\r$/, ''))
+const anchorIdOf = (line) => {
+  const m = WB_ANCHOR_RE_V1.exec(String(line || '').replace(/\r$/, ''))
+  return m ? m[1] : ''
+}
+const isCardTitle = (line) => /^#{3,}\s+\S/.test(String(line || '').replace(/\r$/, ''))
+const titleTextOf = (line) => String(line || '').replace(/\r$/, '').replace(/^#{3,}\s+/, '').trim()
+
+/**
+ * 内容寻址 id（契约 §2 / A8 预授权默认值）：
+ * `mem_` + `sha256(workspaceKey + '\u0000' + 页面相对路径 + '\u0000' + 卡片标题)` 前 32 位十六进制。
+ *
+ * **不复算既有锚点**：本函数只用于"写新卡时该用什么 id"，以及测试验证"重排不变、改名即变"。
+ * 已有锚点一律**照用**（复算会在标题被小改时把整卡换 id，那是白板线 P1 的 supersede 语义，不在 P0 范围）。
+ *
+ * @param {string} workspaceKey 工作区标识（canonicalize 后的形态由调用方决定，本函数只做拼接）
+ * @param {string} pageRelPath 页面相对路径（如 `handoff/PLAN.md`）
+ * @param {string} cardTitle 卡片标题（不含 `### ` 前缀）
+ * @returns {string} `mem_<32hex>`
+ */
+export function computeWhiteboardCardIdPre(workspaceKey, pageRelPath, cardTitle) {
+  const src = String(workspaceKey == null ? '' : workspaceKey) + '\u0000'
+    + String(pageRelPath == null ? '' : pageRelPath) + '\u0000'
+    + String(cardTitle == null ? '' : cardTitle)
+  return 'mem_' + createHash('sha256').update(src).digest('hex').slice(0, 32)
+}
+
+/**
+ * 解析白板页面 → **规范化投影**（供 `validateMutationBoundaryPre` 消费）。
+ *
+ * 返回结构刻意做成"通用投影"而不是"白板专有结构"：写入门不需要知道 `### ` 是什么，
+ * 它只需要知道「有哪些卡片 id」「哪些区域是用户区」「每个卡片的标题与状态」。
+ *
+ * @param {string} text 页面全文（文件字节按 utf8 解出的字符串）
+ * @param {object} [opts]
+ * @param {string} [opts.kind] 'plan' | 'handoff' | 'other'（仅用于报告可读性与判据选择，不改变解析）
+ * @returns {{ok:boolean, version:string, kind:string, cards:Array, cardIds:string[],
+ *            userRegions:Array<{cardId:string, text:string, digest:string}>,
+ *            modelRegions:Array<{cardId:string, text:string}>,
+ *            issues:Array<{code:string, detail:string, line:number}>, counts:object}}
+ */
+export function parseWhiteboardPre(text, opts = {}) {
+  const kind = String((opts && opts.kind) || 'plan')
+  const issues = []
+  if (typeof text !== 'string') {
+    return emptyResult(kind, [{ code: 'not-string', detail: '输入类型 ' + typeof text, line: 0 }])
+  }
+  const raw = text.replace(/^\uFEFF/, '') // 防御：绝不因 BOM 让首行标题判不出来
+  if (!raw.trim()) return emptyResult(kind, [{ code: 'empty', detail: '内容为空', line: 0 }])
+
+  const lines = raw.split('\n')
+  const cards = []
+  const userRegions = []
+  const modelRegions = []
+  const seenIds = new Map() // id → 首次出现的行号（重复检测）
+  let cur = null
+
+  // 分区状态：null = 不在任何区；'model' | 'user' = 在当前卡片的哪个区
+  let region = null
+  let regionStart = 0
+  let regionLines = []
+
+  const closeRegion = () => {
+    if (!region || !cur) { region = null; regionLines = []; return }
+    const body = regionLines.join('\n')
+    if (region === 'user') {
+      userRegions.push({ cardId: cur.id || '', text: body, digest: shortDigest(body) })
+    } else {
+      modelRegions.push({ cardId: cur.id || '', text: body })
+    }
+    region = null
+    regionLines = []
+  }
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const trimmed = line.replace(/\r$/, '')
+
+    // ── 分区标记（先于一切判定：标记行本身既不是标题也不是内容） ──
+    if (trimmed === WB_MARKERS_V1.userOpen) {
+      if (region === 'user') issues.push({ code: 'user-region-interleaved', detail: '重复的 user 开始标记', line: i + 1 })
+      if (region === 'model') closeRegion()
+      if (!cur) issues.push({ code: 'user-region-unclosed', detail: 'user 段不在任何卡片内（契约 §5 要求每卡分区）', line: i + 1 })
+      region = 'user'
+      regionStart = i + 1
+      regionLines = []
+      continue
+    }
+    if (trimmed === WB_MARKERS_V1.userClose) {
+      if (region !== 'user') issues.push({ code: 'user-region-unclosed', detail: 'user 结束标记没有对应的开始标记', line: i + 1 })
+      else closeRegion()
+      continue
+    }
+    if (trimmed === WB_MARKERS_V1.modelOpen) {
+      if (region === 'user') issues.push({ code: 'user-region-interleaved', detail: 'user 段里又开了 model 段（契约 §5 禁止）', line: i + 1 })
+      region = 'model'
+      regionStart = i + 1
+      regionLines = []
+      continue
+    }
+    if (trimmed === WB_MARKERS_V1.modelClose) {
+      if (region !== 'model') issues.push({ code: 'model-region-unclosed', detail: 'model 结束标记没有对应的开始标记', line: i + 1 })
+      else closeRegion()
+      continue
+    }
+
+    // ── 卡片标题 ──
+    if (isCardTitle(trimmed)) {
+      if (region) { closeRegion(); issues.push({ code: 'user-region-unclosed', detail: '新卡片开始前上一张卡的分区未闭合', line: i + 1 }) }
+      cur = { id: '', title: titleTextOf(trimmed), titleLine: i + 1, anchorLine: 0, status: 'current', expectAnchor: true }
+      cards.push(cur)
+      continue
+    }
+
+    // ── 锚点行（必须在标题行下方**紧跟**的位置） ──
+    if (isAnchor(trimmed)) {
+      if (!cur) { issues.push({ code: 'anchor-mid-body', detail: '锚点不在任何卡片标题下方', line: i + 1 }); continue }
+      if (i + 1 !== cur.titleLine + 1) {
+        issues.push({ code: 'anchor-mid-body', detail: '锚点在标题行下方第 ' + (i + 1 - cur.titleLine) + ' 行（契约为紧跟下一行）', line: i + 1 })
+      }
+      const id = anchorIdOf(trimmed)
+      if (seenIds.has(id)) {
+        issues.push({ code: 'anchor-duplicate', detail: 'id ' + id + ' 已被第 ' + seenIds.get(id) + ' 行的卡片占用', line: i + 1 })
+      } else seenIds.set(id, i + 1)
+      cur.id = id
+      cur.anchorLine = i + 1
+      cur.expectAnchor = false
+      continue
+    }
+
+    // ── 状态声明（`status=superseded` 这类；缺省 current，与 isCurrentPre 口径一致） ──
+    const sm = /(?:^|\s)status\s*[=:]\s*(current|superseded|retracted)\b/i.exec(trimmed)
+    if (sm && cur && !region) cur.status = sm[1].toLowerCase()
+
+    if (region) regionLines.push(line)
+  }
+  if (region) {
+    issues.push({
+      code: region === 'user' ? 'user-region-unclosed' : 'model-region-unclosed',
+      detail: '文件结束时分区仍未闭合（起始行 ' + regionStart + '）', line: lines.length,
+    })
+  }
+
+  // ── 逐卡检查：缺锚点 / 锚点格式 ──
+  if (!cards.length) {
+    // 空页面不算"缺卡"事故（首建白板是合法路径）；但**有内容却一张卡都没有**要报出来
+    if (raw.trim()) issues.push({ code: 'no-card', detail: '页面有内容但没有任何 `### ` 卡片标题', line: 0 })
+  } else {
+    for (const c of cards) {
+      if (!c.id) issues.push({ code: 'anchor-missing', detail: '卡片「' + c.title + '」缺锚点行', line: c.titleLine })
+    }
+  }
+
+  const cardIds = cards.map((c) => c.id).filter(Boolean)
+  return {
+    ok: issues.length === 0,
+    version: WB_CONTRACT_VERSION,
+    kind,
+    cards: cards.map((c) => ({
+      id: c.id, title: c.title, status: c.status,
+      titleLine: c.titleLine, anchorLine: c.anchorLine,
+      hasUserRegion: userRegions.some((u) => u.cardId && u.cardId === c.id),
+      hasModelRegion: modelRegions.some((m) => m.cardId && m.cardId === c.id),
+    })),
+    cardIds,
+    userRegions,
+    modelRegions,
+    issues,
+    counts: {
+      cards: cards.length,
+      anchored: cardIds.length,
+      unanchored: cards.length - cardIds.length,
+      userRegions: userRegions.length,
+      modelRegions: modelRegions.length,
+      lines: lines.length,
+    },
+  }
+}
+
+const shortDigest = (s) => createHash('sha256').update(String(s == null ? '' : s)).digest('hex').slice(0, 16)
+
+function emptyResult(kind, issues) {
+  return {
+    ok: false, version: WB_CONTRACT_VERSION, kind,
+    cards: [], cardIds: [], userRegions: [], modelRegions: [], issues,
+    counts: { cards: 0, anchored: 0, unanchored: 0, userRegions: 0, modelRegions: 0, lines: 0 },
+  }
+}
+
+/**
+ * 从投影里抽出"**必须逐字节保留**的用户区"（供写入门做前后比对）。
+ *
+ * 只返回**有 cardId 的用户区**：没有 cardId 的用户区无法与卡片对应，
+ * 其"是否被保留"无从判定（那属于 lint/格式问题，不是写入门能拦的丢卡问题）。
+ *
+ * @param {object} projection `parseWhiteboardPre` 的返回值
+ * @returns {Array<{key:string, digest:string, chars:number, cardId:string}>}
+ */
+export function extractProtectedRegionsPre(projection) {
+  const p = projection && typeof projection === 'object' ? projection : {}
+  const out = []
+  for (const u of Array.isArray(p.userRegions) ? p.userRegions : []) {
+    const cardId = String((u && u.cardId) || '')
+    if (!cardId) continue
+    out.push({
+      key: 'user:' + cardId,
+      cardId,
+      digest: String((u && u.digest) || shortDigest(u && u.text)),
+      chars: String((u && u.text) || '').length,
+    })
+  }
+  return out
+}
+
+/**
+ * 把白板投影适配成写入门要的**规范化投影**（`{beforeIds, afterIds, protectedRegions}`）。
+ *
+ * @param {object} projection `parseWhiteboardPre` 的返回值
+ * @returns {{beforeIds?:string[], afterIds?:string[], protectedRegions:Array, cards:Array, issues:Array}}
+ */
+export function toMutationProjectionPre(projection) {
+  const p = projection && typeof projection === 'object' ? projection : {}
+  return {
+    afterIds: Array.isArray(p.cardIds) ? p.cardIds.slice() : [],
+    protectedRegions: extractProtectedRegionsPre(p),
+    cards: Array.isArray(p.cards) ? p.cards : [],
+    issues: Array.isArray(p.issues) ? p.issues : [],
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 判据门（criteria gate）—— 账本用 H1–H4/S1–S4；PLAN 用 P-H1/P-H2/P-S1
+//
+// ⚠️ **判据不能张冠李戴**（v2 修正，务必遵守；`ROUND3 §2.2` 把我方原写法判为实质错误）：
+//   H1–H4/S1–S4 是**交接账本**的判据；PLAN 是自由全貌文档（节名不固定，P7 老化按标题分类），
+//   其判据**刻意保持最弱** = P-H1/P-H2/P-S1。把账本判据套给 PLAN 会误拒合法白板。
+//
+// **与共同保护的关系**（ROUND3 §3.7 第 4 条）：本判据门是**可选质量门**，
+// `criteriaGate=false` 只退掉它；**丢卡 / 用户区 / 重复 id 三条保护在
+// `memory-mutation.js` 里，无条件生效**，任何开关都绕不过。
+// ═══════════════════════════════════════════════════════════════════════════
+
+export const CRITERIA_GATE_VERSION = 'wb_criteria_v1'
+
+/** 账本四段标题（逐字匹配；与 `handoff-anchor.js` 的权重表同源，不另写一份）。 */
+export const HANDOFF_REQUIRED_SECTIONS_V1 = Object.freeze(
+  HANDOFF_LEDGER_SECTION_WEIGHTS_V1.map((x) => x.title),
+)
+
+/** 占位符黑名单（H3）：段 body 只含这些即视为未填写。 */
+export const CRITERIA_PLACEHOLDERS_V1 = Object.freeze(['(待补充)', '（待补充）', 'todo', '同上', '略', 'n/a', '待补充'])
+
+/** 账本/白板判据的阈值（与 `sanitizeForWrite` 上限同源，先于它执行以免双重截断语义混乱）。 */
+export const CRITERIA_LIMITS_V1 = Object.freeze({
+  handoffMaxChars: 8000,
+  planMaxChars: 200000,
+  sectionMinChars: 20,
+  sectionMaxLines: 5,
+})
+
+const PLACEHOLDER_SET = new Set(CRITERIA_PLACEHOLDERS_V1.map((x) => x.toLowerCase()))
+
+/** 段 body 的"实质内容"行（去空行、去纯占位行）。 */
+function bodyRealLines(body) {
+  return (Array.isArray(body) ? body : [])
+    .map((l) => String(l == null ? '' : l).trim())
+    .filter((l) => l && !PLACEHOLDER_SET.has(l.toLowerCase()))
+}
+
+/**
+ * 交接账本判据（H1–H4 硬；S1–S4 软）。**纯函数、零 IO**。
+ *
+ * @param {string} text 账本全文（写入函数会自带 `# 交接账本 · <日期> <时间>` 标题行，故解析 preamble 非空）
+ * @returns {{ok:boolean, version:string, target:'handoff', hardPass:boolean,
+ *            hard:Array, soft:Array, report:object}}
+ */
+export function checkHandoffCriteriaPre(text) {
+  const src = typeof text === 'string' ? text : ''
+  const parsed = parseHandoffLedgerPre(src)
+  const hard = []
+  const soft = []
+
+  // H1 四段标题齐全且逐字匹配
+  const gotTitles = parsed ? parsed.sections.map((s) => String(s.title).replace(/\r$/, '').replace(/^##\s+/, '').trim()) : []
+  const missing = HANDOFF_REQUIRED_SECTIONS_V1.filter((t) => !gotTitles.includes(t))
+  hard.push({
+    id: 'H1', pass: missing.length === 0, missing: missing.slice(),
+    detail: missing.length
+      ? '缺少或标题不逐字匹配的四段标题：' + missing.join('、') + '（标题错会让权重化截断失效并让注入端解析失败）'
+      : '四段标题齐全且逐字匹配',
+  })
+
+  // H2 每段 body 非空（≥1 非空行且合计 ≥20 字符）
+  const thinSections = []
+  if (parsed) {
+    for (const s of parsed.sections) {
+      const name = String(s.title).replace(/\r$/, '').replace(/^##\s+/, '').trim()
+      if (!HANDOFF_REQUIRED_SECTIONS_V1.includes(name)) continue
+      const real = bodyRealLines(s.body)
+      const chars = real.join('').length
+      if (!real.length || chars < CRITERIA_LIMITS_V1.sectionMinChars) thinSections.push(name + '(' + chars + ' 字符)')
+    }
+  } else {
+    thinSections.push('(无法解析出任何段)')
+  }
+  hard.push({
+    id: 'H2', pass: thinSections.length === 0, missing: thinSections.slice(),
+    detail: thinSections.length
+      ? '这些段为空或少于 ' + CRITERIA_LIMITS_V1.sectionMinChars + ' 字符：' + thinSections.join('、')
+      : '四段 body 均非空且达到最小长度',
+  })
+
+  // H3 无占位符行
+  const placeholderHits = []
+  if (parsed) {
+    for (const s of parsed.sections) {
+      const name = String(s.title).replace(/\r$/, '').replace(/^##\s+/, '').trim()
+      const real = bodyRealLines(s.body)
+      const allBody = (Array.isArray(s.body) ? s.body : []).map((l) => String(l == null ? '' : l).trim()).filter(Boolean)
+      if (allBody.length && !real.length) placeholderHits.push(name)
+    }
+  }
+  hard.push({
+    id: 'H3', pass: placeholderHits.length === 0, missing: placeholderHits.slice(),
+    detail: placeholderHits.length
+      ? '这些段的正文只有占位符（' + CRITERIA_PLACEHOLDERS_V1.slice(0, 4).join('/') + ' 等）：' + placeholderHits.join('、')
+      : '无纯占位符段',
+  })
+
+  // H4 总长 ≤ 8000
+  hard.push({
+    id: 'H4', pass: src.length <= CRITERIA_LIMITS_V1.handoffMaxChars, missing: [],
+    detail: '总长 ' + src.length + ' 字符（上限 ' + CRITERIA_LIMITS_V1.handoffMaxChars + '）',
+  })
+
+  // S1 每段 ≤5 行（软·警告；prompt 纪律既有约定）
+  const longSections = []
+  if (parsed) {
+    for (const s of parsed.sections) {
+      const name = String(s.title).replace(/\r$/, '').replace(/^##\s+/, '').trim()
+      if (!HANDOFF_REQUIRED_SECTIONS_V1.includes(name)) continue
+      const n = bodyRealLines(s.body).length
+      if (n > CRITERIA_LIMITS_V1.sectionMaxLines) longSections.push(name + '(' + n + ' 行)')
+    }
+  }
+  soft.push({ id: 'S1', pass: longSections.length === 0, detail: longSections.length ? '超过 5 行的段：' + longSections.join('、') : '各段均 ≤5 行' })
+
+  // S2「已试方案与失败原因」写成「方案→失败原因」且保留报错关键词
+  const failSec = parsed ? parsed.sections.find((s) => String(s.title).replace(/\r$/, '').replace(/^##\s+/, '').trim() === '已试方案与失败原因') : null
+  const failBody = failSec ? bodyRealLines(failSec.body).join('\n') : ''
+  const hexArrow = /→|->|⇒/.test(failBody)
+  const errWord = /失败|报错|错误|回滚|error|fail|bug/i.test(failBody)
+  soft.push({
+    id: 'S2', pass: hexArrow && errWord,
+    detail: (hexArrow ? '' : '缺「方案→失败原因」箭头；') + (errWord ? '' : '缺关键报错词；') || '失败项格式良好',
+  })
+
+  // S3「进度与下一步」含可执行特征（路径分隔符 / 反引号代码 / 命令动词）
+  const nextSec = parsed ? parsed.sections.find((s) => String(s.title).replace(/\r$/, '').replace(/^##\s+/, '').trim() === '进度与下一步') : null
+  const nextBody = nextSec ? bodyRealLines(nextSec.body).join('\n') : ''
+  const execish = /[\\/][\w.-]+|`[^`]+`|\bnode\b|\bnpm\b|\bgit\b|\brun\b|执行|运行|命令/i.test(nextBody)
+  soft.push({ id: 'S3', pass: execish, detail: execish ? '下一步含可执行特征' : '下一步看不出可直接执行的第一步（软提示）' })
+
+  // S4 无临时信息（低置信启发，仅 diag）
+  const tempish = /临时路径|tmp\\|\\\\tmp|搜索结果[:：]|console\.log\(/i.test(src)
+  soft.push({ id: 'S4', pass: !tempish, detail: tempish ? '疑似含临时信息（低置信，仅诊断）' : '未见明显临时信息' })
+
+  return {
+    ok: hard.every((h) => h.pass), version: CRITERIA_GATE_VERSION, target: 'handoff',
+    hardPass: hard.every((h) => h.pass), hard, soft,
+    report: { chars: src.length, sections: gotTitles.length, requiredSections: HANDOFF_REQUIRED_SECTIONS_V1.length },
+  }
+}
+
+/**
+ * 白板 PLAN 判据（P-H1/P-H2 硬；P-S1 软）。**刻意保持最弱**（v2 修正）。
+ *
+ * P-H1 至少一个非空 `## ` 顶层节（与 P7 老化的节切分逻辑一致）—— 防"全部节被老化走"的空白板；
+ * P-H2 ≤ 200000 字符；P-S1 含至少一处前瞻内容（软）。
+ *
+ * @param {string} text 白板全文
+ * @param {object} [projection] 已有的 `parseWhiteboardPre` 结果（省略则只看文本，不看卡片）
+ */
+export function checkPlanCriteriaPre(text, projection) {
+  const src = typeof text === 'string' ? text : ''
+  const hard = []
+  const soft = []
+  // 与 P7 老化同一口径：按 `## ` 切顶层节（`### ` 不算顶层节）
+  const sections = src.split(/(?=^## )/m).filter((s) => /^## /.test(s))
+  const nonEmpty = sections.filter((s) => {
+    const body = s.split('\n').slice(1).join('\n').trim()
+    return body.length >= CRITERIA_LIMITS_V1.sectionMinChars
+  })
+  hard.push({
+    id: 'P-H1', pass: nonEmpty.length >= 1, missing: nonEmpty.length ? [] : ['(无非空 ## 顶层节)'],
+    detail: nonEmpty.length
+      ? '有 ' + nonEmpty.length + ' 个非空顶层节（共 ' + sections.length + ' 个）'
+      : '没有任何非空 `## ` 顶层节（' + CRITERIA_LIMITS_V1.sectionMinChars + ' 字符以上）—— 这是"白板被整篇覆盖成骨架/空白板"的形态',
+  })
+  hard.push({
+    id: 'P-H2', pass: src.length <= CRITERIA_LIMITS_V1.planMaxChars, missing: [],
+    detail: '总长 ' + src.length + ' 字符（上限 ' + CRITERIA_LIMITS_V1.planMaxChars + '）',
+  })
+  const forward = /下一步|待办|计划|todo/i.test(src)
+  soft.push({ id: 'P-S1', pass: forward, detail: forward ? '含前瞻内容' : '未见前瞻内容（下一步/待办/计划）—— 软提示，不拦截' })
+
+  // 卡片情况只作**报告**，不作 PLAN 硬判据（P0 既有白板没有锚点，硬判会立刻误拒所有现存白板）。
+  // 锚点完备性属白板线 P1/P2，不在此拦截。
+  const cards = projection && Array.isArray(projection.cards) ? projection.cards : null
+  return {
+    ok: hard.every((h) => h.pass), version: CRITERIA_GATE_VERSION, target: 'plan',
+    hardPass: hard.every((h) => h.pass), hard, soft,
+    report: {
+      chars: src.length, sections: sections.length, nonEmptySections: nonEmpty.length,
+      cards: cards ? cards.length : null, anchored: projection ? (projection.cardIds || []).length : null,
+    },
+  }
+}
+
+/** 判据报告 → 给模型的可执行拒绝文案（缺什么、哪段空、占位符原文，逐条列出）。 */
+export function criteriaRefusalTextPre(res) {
+  const r = res && typeof res === 'object' ? res : {}
+  const failed = (Array.isArray(r.hard) ? r.hard : []).filter((h) => !h.pass)
+  if (!failed.length) return ''
+  return '写入被判据门拦截（' + failed.map((h) => h.id).join('/') + '），原文件未改动：\n'
+    + failed.map((h) => '· [' + h.id + '] ' + h.detail).join('\n')
+    + '\n请补齐后重试。'
+}