@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/ledger-criteria.js

@@ -0,0 +1,142 @@
+/**
+ * ledger-criteria-pre —— WB-GRAPH P1 判据校验中间件核心(2026-09-16, ledger_criteria_v1)。
+ *
+ * 权威依据: WB-GRAPH-INTEGRATION-PLAN.md §2.2 判据定义表 + WB-FORMAT-CONVENTION.md v1
+ *   + WB-GRAPH-DECISIONS-20260914.md §E(2026-09-16 拍板: P1 全量、A6 照写+警示行、B7 跳过试点)。
+ *
+ * 设计(方案 §2.1-2.5):
+ *  - 纯函数、零 IO、fail closed(仿 handoff-anchor.js 契约)。
+ *  - 硬判据 = 确定性可计算(标题逐字/非空/占位符/长度), 不过 → 拒绝写入。
+ *  - 软判据 = 启发式, 只标记不拦截(误报不可忽略; 水位骨架素材空时天然不满足 → 绝不阻塞接续 I4)。
+ *  - 白板判据取可计算子集(零 LLM), 自然语言质量层交既有 prompt 纪律(§2.1 结论)。
+ *  - 报告契约 = §2.5 ledger_criteria_v1 JSON(机器可读, P2 确认事件消费)。
+ */
+
+export const LEDGER_CRITERIA_VERSION = 'ledger_criteria_v1'
+// 兼容性再导出(2026-09-16 勘误): P0 窗口的 wb-contract.js 已实现同名判据函数(H1-H4/S1-S4),
+// 且 index.js 两咽喉(checkMutationPre)已接线它 — 本模块勿重复造轮,统一转发保持单一真源。
+export { checkHandoffCriteriaPre as checkHandoffCriteriaContractPre, checkPlanCriteriaPre as checkPlanCriteriaContractPre } from './wb-contract.js'
+
+import { parseHandoffLedgerPre } from './handoff-anchor.js'
+
+/** 交接账本四段权威标题(与 handoff-anchor.js 权重表同源)。 */
+export const HANDOFF_SECTIONS_V1 = Object.freeze(['任务状态', '目标', '已试方案与失败原因', '进度与下一步'])
+
+/** 占位符黑名单(借 dsh-graph CRITERIA_PLACEHOLDERS 技巧, 方案 H3)。 */
+export const CRITERIA_PLACEHOLDERS_V1 = Object.freeze(['(待补充)', '（待补充）', 'TODO', '同上', '略', 'N/A', 'n/a'])
+
+/** 账本硬上限(H4, 与 sanitizeForWrite 8000 同源, 先于它执行)。 */
+export const LEDGER_MAX_CHARS_V1 = 8000
+/** 白板硬上限(P-H2, 200000)。 */
+export const PLAN_MAX_CHARS_V1 = 200000
+
+function nz(s) { return String(s || '') }
+
+function sectionBodies(parsed) {
+  // parseHandoffLedgerPre 的 title 保留 '## ' 前缀原样行 — 剥前缀与尾随空白后与权威表比对。
+  return parsed.sections.map((s) => ({ title: nz(s.title).replace(/^##\s*/, '').replace(/\s+$/, ''), body: s.body }))
+}
+
+function isPlaceholderLine(line) {
+  const t = nz(line).trim()
+  if (!t) return false
+  return CRITERIA_PLACEHOLDERS_V1.some((p) => t === p || t === '-' + p || t === '*' + p)
+}
+
+/** H2: 每段 body 非空(≥1 非空行且合计 ≥20 字符)。 */
+function bodyStat(body) {
+  const arr = Array.isArray(body) ? body : []
+  const nonEmpty = arr.filter((l) => nz(l).trim()).length
+  const chars = arr.join('').replace(/\s/g, '').length
+  return { nonEmpty, chars }
+}
+
+/**
+ * 校验交接账本(kind=handoff)。判据 H1-H4 硬 / S1-S4 软(方案 §2.2)。
+ * @param {string} text 账本全文
+ * @returns {report} §2.5 ledger_criteria_v1(不抛错; 解析失败按 H1 fail 处理)
+ */
+export function checkHandoffCriteriaPre(text) {
+  const hard = []
+  const soft = []
+  let parsed = null
+  try { parsed = parseHandoffLedgerPre(text) } catch (_) { parsed = null }
+
+  // H1 四段标题齐全且逐字匹配
+  const titles = parsed ? sectionBodies(parsed).map((x) => x.title) : []
+  const missing = HANDOFF_SECTIONS_V1.filter((t) => !titles.includes(t))
+  hard.push({ id: 'H1', pass: !!parsed && missing.length === 0, missing: parsed ? missing.map((t) => '缺段:' + t) : ['解析失败(无任何 ## 段)'] })
+
+  // H2 每段非空
+  const emptySections = parsed ? sectionBodies(parsed).filter((x) => { const st = bodyStat(x.body); return st.nonEmpty < 1 || st.chars < 20 }).map((x) => x.title) : []
+  hard.push({ id: 'H2', pass: !!parsed && emptySections.length === 0, missing: emptySections.map((t) => '空段:' + t) })
+
+  // H3 无占位符行(段 body 整行即占位符)
+  const placeholderHits = []
+  if (parsed) for (const s of sectionBodies(parsed)) for (const l of s.body) if (isPlaceholderLine(l)) placeholderHits.push('[' + s.title + '] ' + l.trim())
+  hard.push({ id: 'H3', pass: placeholderHits.length === 0, missing: placeholderHits.slice(0, 5) })
+
+  // H4 总长 ≤8000
+  const len = nz(text).length
+  hard.push({ id: 'H4', pass: len <= LEDGER_MAX_CHARS_V1, missing: len > LEDGER_MAX_CHARS_V1 ? ['总长 ' + len + ' > ' + LEDGER_MAX_CHARS_V1] : [] })
+
+  // S1 每段 ≤5 行(软)
+  const overLong = parsed ? sectionBodies(parsed).filter((x) => x.body.filter((l) => l.trim()).length > 5).map((x) => x.title) : []
+  soft.push({ id: 'S1', pass: overLong.length === 0, detail: overLong.length ? '超 5 行段: ' + overLong.join('、') : '' })
+
+  // S2 失败项含报错关键词(软)
+  const failSection = parsed ? sectionBodies(parsed).find((x) => x.title === '已试方案与失败原因') : null
+  const failText = failSection ? failSection.body.join('') : ''
+  const s2pass = !failSection || /失败|报错|错误|回滚|error|fail|bug/i.test(failText)
+  soft.push({ id: 'S2', pass: s2pass, detail: s2pass ? '' : '失败项建议写成「方案→失败原因」并保留报错关键词' })
+
+  // S3 下一步含可执行特征(软)
+  const nextSection = parsed ? sectionBodies(parsed).find((x) => x.title === '进度与下一步') : null
+  const nextText = nextSection ? nextSection.body.join('') : ''
+  const s3pass = !nextSection || /[\\/]|`|：:\s*(读取|运行|执行|检查|写|改|删|重建|跑)/.test(nextText)
+  soft.push({ id: 'S3', pass: s3pass, detail: s3pass ? '' : '下一步建议含可执行特征(路径/代码/命令动词)' })
+
+  const hard_pass = hard.every((x) => x.pass)
+  return { version: LEDGER_CRITERIA_VERSION, target: 'handoff', hard_pass, hard, soft }
+}
+
+/**
+ * 校验白板 PLAN(kind=plan)。判据刻意最弱(P-H1/P-H2 硬, P-S1 软, 方案 §2.2 白板表)。
+ */
+export function checkPlanCriteriaPre(text) {
+  const hard = []
+  const soft = []
+  const src = nz(text)
+  // P-H1 至少一个 '## ' 顶层节且非空(≥20 非空白字符)
+  const lines = src.split('\n')
+  const sections = []
+  let cur = null
+  for (const line of lines) {
+    if (/^## (.+)$/.test(line.replace(/\r$/, ''))) { if (cur) sections.push(cur); cur = { body: [] } }
+    else if (cur) cur.body.push(line)
+  }
+  if (cur) sections.push(cur)
+  const nonEmptySections = sections.filter((s) => s.body.join('').replace(/\s/g, '').length >= 20)
+  hard.push({ id: 'P-H1', pass: nonEmptySections.length >= 1, missing: nonEmptySections.length === 0 ? ['无非空 ## 顶层节(全部节被老化走或空白板)'] : [] })
+  // P-H2 长度
+  hard.push({ id: 'P-H2', pass: src.length <= PLAN_MAX_CHARS_V1, missing: src.length > PLAN_MAX_CHARS_V1 ? ['总长 ' + src.length + ' > ' + PLAN_MAX_CHARS_V1] : [] })
+  // P-S1 前瞻内容(软)
+  const s1pass = /下一步|待办|计划|todo/i.test(src)
+  soft.push({ id: 'P-S1', pass: s1pass, detail: s1pass ? '' : '建议含前瞻内容(下一步/待办/计划)' })
+  const hard_pass = hard.every((x) => x.pass)
+  return { version: LEDGER_CRITERIA_VERSION, target: 'plan', hard_pass, hard, soft }
+}
+
+/** 统一入口: 按 target 分派。未知 target fail closed(返回 hard_pass=false)。 */
+export function checkWriteCriteriaPre(target, text) {
+  if (target === 'handoff') return checkHandoffCriteriaPre(text)
+  if (target === 'plan') return checkPlanCriteriaPre(text)
+  return { version: LEDGER_CRITERIA_VERSION, target: String(target || ''), hard_pass: false, hard: [{ id: 'INVALID', pass: false, missing: ['未知 target'] }], soft: [] }
+}
+
+/** 把 report 渲染为可执行改写指引文案(P1-4 工具层拒绝文案用)。 */
+export function renderCriteriaRejectionPre(report) {
+  const misses = []
+  for (const h of report.hard) if (!h.pass) misses.push(...(h.missing || []))
+  return '[写入门·判据未过(' + report.target + ')] 以下硬判据不通过, 请修正后重试(结构修正即可, 无需重写全文):\n- ' + misses.join('\n- ')
+}

package/lib/m4-corpus.js

@@ -94,11 +94,17 @@ export function loadCorpusSnapshot(catalog, io = {}, opts = {}) {
     if (buf.length > INDEX_MAX_FILE_BYTES) { dropped.push({ stage: 'corpus', reason: 'oversized', sourceRef: source.sourceRef }); continue }
     const fileDigest = sha256Hex(buf)
     if (fileDigest !== sc.fileDigest) { dropped.push({ stage: 'corpus', reason: 'stale-source', sourceRef: source.sourceRef }); continue }
+    // ★ issue #66 修复（2026-09-19）：**byteStart/byteEnd 是相对「剥掉 BOM 之后」的坐标系**
+    //   （契约见 `memory-anchor.js` 的 `parseAnchors` 与其 C18 断言；`fileDigest` 则按含 BOM 的整 buffer 算）。
+    //   旧实现直接 `buf.subarray(...)` 用在**含 BOM 的原 buffer** 上 ⇒ BOM 文件整体偏 3 字节
+    //   ⇒ `recordDigest` 恒不等 ⇒ 该文件**全部记录被判 record-stale 丢弃**，从语料/召回静默消失。
+    //   修法：消费侧对齐——有 BOM 时先剥掉再切片（无 BOM 时 body === buf，零行为变化）。
+    const body = (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) ? buf.subarray(3) : buf
     for (const r of (sc.records || [])) {
-      if (!Number.isInteger(r.byteStart) || !Number.isInteger(r.byteEnd) || r.byteStart < 0 || r.byteEnd > buf.length) {
+      if (!Number.isInteger(r.byteStart) || !Number.isInteger(r.byteEnd) || r.byteStart < 0 || r.byteEnd > body.length) {
         dropped.push({ stage: 'corpus', reason: 'record-stale', memoryId: r.memoryId, sourceRef: source.sourceRef }); continue
       }
-      if (sha256Hex(buf.subarray(r.byteStart, r.byteEnd)) !== r.recordDigest) {
+      if (sha256Hex(body.subarray(r.byteStart, r.byteEnd)) !== r.recordDigest) {
         dropped.push({ stage: 'corpus', reason: 'record-stale', memoryId: r.memoryId, sourceRef: source.sourceRef }); continue
       }
       records.push({

package/lib/m7-index-sync-host.js

@@ -22,6 +22,7 @@
  */
 import { buildIndexSyncPlansPre, sendIndexSyncPlanPre } from './index-sync.js'
 import { workspaceRefOf } from './evidence-store.js'
+import { createEngineSwitchPre } from './engine-switch.js'
 
 export const M7_INDEX_SYNC_HOST_POLICY_VERSION = 'm7_index_sync_host_v1'
 const MAX_PATH_KEYS = 8
@@ -30,12 +31,23 @@ const MAX_DROPS = 16
 export function createIndexSyncHostPre(opts = {}) {
   const engine = opts.engine
   if (!engine) throw new Error('index-sync-host: engine required')
-  const readyCache = new Map()   // key=(wsRef,scope) -> { miv, epoch, at }
+  const readyCache = new Map()   // key=(wsRef,scope) -> { miv, epoch, at, generation }
   const inFlight = new Map()     // key=(wsRef,scope) -> { controller, promise, miv }
   const enabledKeys = new Set()  // 显式 disable 的 key(同一 miv 内不再重试;miv 变化自动解除)
   const volatileDrops = []       // ≤16 条最小投影(无文本)
   const stats = { syncsStarted: 0, syncsOk: 0, syncsFailed: 0, skippedCached: 0,
-    epochReset: 0, mivReplaced: 0, aborted: 0, drops: 0, readyHits: 0 }
+    epochReset: 0, mivReplaced: 0, aborted: 0, drops: 0, readyHits: 0, generationResets: 0 }
+  // ★P2（T2-9a）：**重建代际**。切档 = 新 generation ⇒ 旧代 readyCache 一律不得跳过重建
+  // （含 e5→BGE→e5 回到旧引擎：旧代的 ready 缓存同样作废，必须完整重跑）。
+  let generation = 0
+  // ★P2（T2-9b/c/d）：切换状态机由本宿主持有（评审 §3.5 采纳条目），状态唯一所有者；
+  // semantic-status / 向导只投影它，不另立计数。
+  const switchMachine = createEngineSwitchPre({
+    now: opts.now,
+    io: opts.switchIo || null,
+    persistPath: opts.switchPersistPath || '',
+    diag: opts.diag,
+  })
 
   function enabled() {
     return engine.config.associativeMemoryEnabled === true &&
@@ -78,8 +90,22 @@ export function createIndexSyncHostPre(opts = {}) {
     const epoch = currentEpoch()
     const k = keyOf(wsRef, scope)
     const cached = readyCache.get(k)
+    // ★P2（T2-9a）重建代际失效：切档后 generation 前进 ⇒ 旧代 ready 缓存**不得跳过重建**
+    // （e5→BGE→e5 回到旧引擎也一样：缓存是"旧代的"，必须完整重跑）。
+    if (cached && (Number(cached.generation) || 0) !== generation) {
+      readyCache.delete(k)
+      stats.generationResets++
+      drop('generation-reset', 0, ctxKey)
+    }
     // epoch 变化(worker 重启) → 缓存失效,必须重同步
-    if (cached && epoch && cached.epoch !== epoch) {
+    // ★ issue #69 修复（2026-09-19）：判据补上「**cached.epoch 为空 ⇒ 一律视为无效**」。
+    //   旧写法 `if (cached && epoch && cached.epoch !== epoch)` 里的 **`epoch &&` 前置**是缺陷所在：
+    //   当 `currentEpoch()` 返回 null（**client 未启动 / 已 exit 但 stdio 未排空**）时，该分支**永不成立**
+    //   ⇒ 一条 `cached.epoch === null` 的旧缓存（冷启动时采样于 lazy spawn 之前，见 `:90`）会被一直保留
+    //   ⇒ 对刚 spawn 出来的空索引 worker 误判 `ready=true`，该段 `context_push` 拿到零候选零激活，
+    //   且 `context-host` 的 `indexNotReady` 也不点亮（readyRes.ready 为 true）⇒ **连降级留痕都没有**。
+    //   保留旧语义的另一半（epoch 非空时要求严格相等）——worker 重启换 epoch 仍会正常失效重同步。
+    if (cached && (!cached.epoch || (epoch && cached.epoch !== epoch))) {
       readyCache.delete(k)
       stats.epochReset++
       drop('epoch-reset', 0, ctxKey)
@@ -117,12 +143,15 @@ export function createIndexSyncHostPre(opts = {}) {
     const promise = sendIndexSyncPlanPre(c, plan, { signal: signal2, timeoutMs: syncTimeoutMs })
       .then((res) => {
         if (res.ok) {
-          readyCache.set(k, { miv, epoch, at: Date.now() })
+          readyCache.set(k, { miv, epoch, at: Date.now(), generation })
           stats.syncsOk++
+          // ★P2（T2-9c）：进度**来自实际完成量** —— 只有真同步成功后才上报该 scope 单元。
+          try { switchMachine.reportDone(switchMachine.getEngineSwitchStatusPre().switchId, [k]) } catch (_) {}
           return { ok: true, ready: true, miv, epoch }
         }
         stats.syncsFailed++
         drop('sync:' + (res.reason || res.phase || 'failed'), 0, ctxKey)
+        try { switchMachine.reportFailed(switchMachine.getEngineSwitchStatusPre().switchId, 1, res.reason || res.phase || 'sync-failed') } catch (_) {}
         return { ok: false, ready: false, reason: (res.reason || res.phase || 'sync-failed') }
       })
       .catch((err) => {
@@ -164,7 +193,9 @@ export function createIndexSyncHostPre(opts = {}) {
     return {
       enabled: true,
       policyVersion: M7_INDEX_SYNC_HOST_POLICY_VERSION,
-      ready: [...readyCache.entries()].map(([k, v]) => ({ key: k, miv: v.miv, epoch: v.epoch ? v.epoch.slice(0, 12) : null })),
+      generation,
+      engineSwitch: switchMachine.getEngineSwitchStatusPre(),
+      ready: [...readyCache.entries()].map(([k, v]) => ({ key: k, miv: v.miv, epoch: v.epoch ? v.epoch.slice(0, 12) : null, generation: v.generation })),
       inFlightCount: inFlight.size,
       capturedPathKeys: [...enabledKeys].slice(0, MAX_PATH_KEYS),
       stats: { ...stats },
@@ -173,6 +204,33 @@ export function createIndexSyncHostPre(opts = {}) {
     }
   }
 
+  /**
+   * ★P2（T2-9）开始一次**实际**引擎切换：新 rebuild generation + 冻结目标身份。
+   * 由调用方在**配置落盘之后**调用。返回 {ok, switchId, generation}。
+   * 副作用：generation 前进 ⇒ 所有旧代 readyCache 立即失效（下次 ensureIndexReady 必完整重跑）。
+   */
+  function beginEngineSwitchPre(input = {}) {
+    const r = switchMachine.beginEngineSwitchPre(input)
+    if (r.ok && r.fresh) {
+      generation = Number(r.generation) || generation + 1
+      // 旧代 ready 缓存整体作废（不清盘、不删文件：缓存目录本身不就地覆盖，见回滚口径）
+      readyCache.clear()
+      for (const [, infl] of inFlight) { try { infl.controller.abort() } catch (_) {} }
+      stats.generationResets++
+      drop('engine-switch', 0, 'begin')
+    }
+    return r
+  }
+
+  function cancelEngineSwitchPre(switchId) { return switchMachine.cancelEngineSwitchPre(switchId) }
+  function getEngineSwitchStatusPre() { return switchMachine.getEngineSwitchStatusPre() }
+  function reportEngineSwitchDone(switchId, unitKeys, opts2) { return switchMachine.reportDone(switchId, unitKeys, opts2) }
+  function setEngineSwitchTotal(switchId, total) { return switchMachine.setTotal(switchId, total) }
+  function publishEngineSwitchReady(switchId) { return switchMachine.publishReady(switchId) }
+  function failEngineSwitch(switchId, reason) { return switchMachine.failSwitch(switchId, reason) }
+  /** 当前是否处于"强制全量重建"代际（切换未完成）。 */
+  function requiresFullRebuild() { return switchMachine.requiresFullRebuild() }
+
   function dispose(reason) {
     for (const [, infl] of inFlight) { try { infl.controller.abort() } catch (_) {} }
     inFlight.clear()
@@ -187,6 +245,16 @@ export function createIndexSyncHostPre(opts = {}) {
     ensureWorkspaceIndexReady,
     debugView,
     dispose,
+    // ★P2：切档 API（评审 §3.5 采纳：状态由本宿主持有，唯一所有者）
+    beginEngineSwitchPre,
+    cancelEngineSwitchPre,
+    getEngineSwitchStatusPre,
+    reportEngineSwitchDone,
+    setEngineSwitchTotal,
+    publishEngineSwitchReady,
+    failEngineSwitch,
+    requiresFullRebuild,
+    _generationForTest: () => generation,
     _stats: stats,
     _readyCacheForTest: readyCache,
     _inFlightForTest: inFlight,

package/lib/m7-wire.js

@@ -104,7 +104,7 @@ export function makeRequestFramePre(input) {
   const sentAt = Number(input && input.sentAt)
   const frame = {
     protocolVersion: M7_WIRE_PROTOCOL_VERSION_V1,
-    frameId: 'frm_' + first32(sha256Str(JSON.stringify(['m7-frame-pre-v1', type, requestId, sentAt]))),
+    frameId: 'frm_' + first32(sha256Str(JSON.stringify(['m7-frame-v1', type, requestId, sentAt]))),
     requestId,
     workerEpoch: String((input && input.workerEpoch) || ''),
     type,
@@ -224,12 +224,12 @@ export function validateIndexAckPayloadPre(pl) {
 
 /** 派生 chunk 身份(占位 chunking=整记录单 chunk;M7-2 tokenizer 落地前冻结此派生规则)。 */
 export function buildChunkIdPre(memoryId, recordDigest) {
-  return 'chk_' + first32(sha256Str(JSON.stringify(['semantic-chunk-pre-v1', String(memoryId || ''), String(recordDigest || '')])))
+  return 'chk_' + first32(sha256Str(JSON.stringify(['semantic-chunk-v1', String(memoryId || ''), String(recordDigest || '')])))
 }
 
 /** syncId:由 workspaceRef+scope+memoryIndexVersion+recordCount 确定(同快照重放同 id)。 */
 export function buildSyncIdPre(workspaceRef, scope, memoryIndexVersion, recordCount) {
-  return 'syn_' + first32(sha256Str(JSON.stringify(['index-sync-pre-v1', String(workspaceRef || ''), String(scope || ''), String(memoryIndexVersion || ''), Number(recordCount) | 0])))
+  return 'syn_' + first32(sha256Str(JSON.stringify(['index-sync-v1', String(workspaceRef || ''), String(scope || ''), String(memoryIndexVersion || ''), Number(recordCount) | 0])))
 }
 
 /** pageDigest = sha256(canonical(records 数组))。 */

package/lib/memory-anchor.js

@@ -26,7 +26,12 @@ export const SIDECAR_NAMESPACE = 'dsh-auto-memory'
 export const ANCHOR_PREFIX = 'memory:'
 export const MEMORY_ID_RE = /^mem_[0-9a-f]{32}$/
 export const MARKER_RE = /^<!-- memory:(mem_[0-9a-f]{32}) -->$/
-const MARKER_OPEN = '<!-- memory:'
+/**
+ * 保留语法开标记(issue #54):写入侧**必须**复用本常量做前置校验。
+ * 导出而非私有 —— 过去只被本文件的读取路径(:177/:182 判定)引用,写入路径零引用,
+ * 于是"文件已有内容干净"≠"本次要写的内容干净",一次误写即让该文件此后永久拒写。
+ */
+export const MARKER_OPEN = '<!-- memory:'
 const HEADING_RE = /^#{1,6}\s/
 const HEX64_RE = /^[0-9a-f]{64}$/
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
@@ -36,6 +41,38 @@ export function newMemoryId(rnd) {
   return 'mem_' + (rnd || randomUUID().replace(/-/g, ''))
 }
 
+/**
+ * issue #54：检测**待写入正文**是否含保留 marker 语法。
+ *
+ * 背景：`appendAnchoredRecord()` 等写入原语只对「文件已有内容」跑 `parseAnchors()`，
+ * 从不校验本次要写入的 `text`。含 `MARKER_OPEN` 的正文落盘后，从**下一次**写入起
+ * `parseAnchors` 判 `orphan-content` fail-closed ⇒ 该文件全部写入被永久拒绝。
+ *
+ * 本函数与 `parseAnchors` 用**同一个** `MARKER_OPEN` 常量判据，保证读写两侧口径永不漂移。
+ * 不做转义/静默改写（转义救不了：`parseAnchors` 无转义机制，`.includes()` 照样命中）。
+ *
+ * @param {string} text 待写入正文
+ * @returns {{ok:true}|{ok:false,reason:'reserved-syntax-in-content',line:number,detail:string}}
+ */
+export function checkReservedSyntaxInContent(text) {
+  const s = String(text == null ? '' : text)
+  if (!s.includes(MARKER_OPEN)) return { ok: true }
+  const lines = s.split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(MARKER_OPEN)) {
+      return {
+        ok: false,
+        reason: 'reserved-syntax-in-content',
+        // 行号按**待写入正文内**的 1-based 相对行号；调用方负责再映射为文件绝对行号。
+        line: i + 1,
+        detail: '待写入内容含保留 marker 语法 ' + MARKER_OPEN + '（第 ' + (i + 1) + ' 行）: ' + lines[i].slice(0, 60),
+      }
+    }
+  }
+  // 理论上不可达（上面已判 includes），保留兜底以便未来改判据时不静默漏过。
+  return { ok: false, reason: 'reserved-syntax-in-content', line: 1, detail: '待写入内容含保留 marker 语法' }
+}
+
 function sha256Hex(buf) {
   return createHash('sha256').update(buf).digest('hex')
 }
@@ -448,4 +485,22 @@ export function buildAnchoredIndex(sourceFile, content, prev) {
   return { sourceFile, fileDigest, sourceVersion, skipped: false, records }
 }
 
+/**
+ * issue #54 配套：把**跨文档引用**的正文里的结构 marker 行剥掉。
+ *
+ * 背景：把 A 文档的原文（含 A 的 `<!-- memory:mem_xxx -->` 行）当正文追加进 B 文档时，
+ * 那行 marker 会变成 B 的结构锚点 —— 产生一条**幻影记录**（身份属于 A、却挂在 B 上），
+ * 且此后 `parseAnchors` 会把它当真实锚点参与 sidecar/索引，属静默结构损坏。
+ *
+ * 口径：只剥「整行恰好是合法 marker」的行（`MARKER_RE`），保留其余一切字节；
+ * 行内出现的 marker 片段不在此处理（那属 #54 写入守卫的职责）。
+ * @param {string} text 待内联的正文
+ * @returns {string} 剥掉 marker 行后的文本
+ */
+export function stripAnchorLines(text) {
+  const s = String(text == null ? '' : text)
+  if (!s.includes(MARKER_OPEN)) return s
+  return s.split(/\r?\n/).filter((ln) => !MARKER_RE.test(ln)).join('\n')
+}
+
 export { detectNewline }

package/lib/memory-envelope.js

@@ -0,0 +1,257 @@
+/**
+ * 记忆注入信封 · 分项账本（memory_envelope_v1）—— 契约 T0-3 / 总纲 §0.5 第 6 条。
+ *
+ * 2026-09-14 建立（P0）。**为什么需要这个模块**：
+ *
+ * 现行注入存在**两处实测缺陷**（读码确认，不是推测）：
+ *   ① `lib/tier-layer-inject.js:327–335`（旧行号）：总长门只裁"下探段"，
+ *      `headParts`（目录 + 降级行）**从不动**；而且降级说明是**在裁剪之后**才追加的
+ *      ⇒ 最终长度可以**超过** `maxTotalChars`。
+ *   ② `lib/index.js`（`renderMemoryDynamic`）：`catalogCost` 被 `Math.min(…, budget*0.35)` **封顶**，
+ *      封顶的是"**扣账成本**"；实际注入用的是全文 `state.tier0LayerText`，**不参与 used 记账**。
+ *      另外 `used` 变量只累加、**从未被读取**（注水账本）。
+ *
+ * 后果：**没人能回答"这一轮到底注入了多少、分别花在哪"**。v2 的要求是把它换成
+ * **分项账本**：`chars: { rules, memoryReferences, otherDynamic, total }` +
+ * `limits: { memoryReferences, otherDynamic }`。
+ *
+ * **本模块的三条不变式**（每条都有能红的断言，见 `tests/smoke/smoke-test-t0-3-budget-ledger-pre.mjs`）：
+ *   E1 **总计 = 最终序列化长度**：`chars.total === text.length`（逐字节相等，不是估算）。
+ *   E2 **不允许未计费尾巴**：每个字符都归属某个分项；`rules + memoryReferences + otherDynamic === total`。
+ *      标题、分隔符、降级说明**都必须作为某一段的文本被计入**（本模块不给任何"隐含前缀"留位置）。
+ *   E3 **限制是硬约束**：启用了 `limits.X` 的分项，其实际字符数 **必须 ≤ 上限**；
+ *      超限时按**整段**从该分项尾部丢弃（不腰斩半段），仍超则截断最后一段并显式标注
+ *      —— **裁剪永远可见**（I7：不静默）。
+ *
+ * **明确代价**（v2 要求写清，不允许用换记账写法掩盖）：规则越长，注入总量越大；
+ * 本模块**不再承诺**"全部动态内容有一个与规则规模无关的固定上限"。总纲 §0.5 第 6 条已接受此代价。
+ *
+ * **设计取舍——为什么不重排段落**：分项账本只做"归类 + 计量 + 限额"，**输出顺序 = 调用方给的顺序**，
+ * 每段文本逐字节照搬（段自带前导 `\n`）。这样既满足 E1/E2，又不会顺手改变注入布局
+ * （前缀缓存命中、既有套件的字节断言都不受影响）。
+ *
+ * S9 合规：零 IO、零依赖、纯函数、无网络、无 LLM、无子进程、全同步。
+ * UTF-8 无 BOM。
+ */
+
+export const MEMORY_ENVELOPE_VERSION = 'memory_envelope_v1'
+
+/** 分项取值域（固定顺序仅用于**账本展示**；序列化顺序仍由调用方决定）。 */
+export const ENVELOPE_BUCKETS_V1 = Object.freeze(['rules', 'memoryReferences', 'otherDynamic'])
+
+/**
+ * 段落优先级（★2026-09-15 新增）—— 决定"超额时先丢谁"。
+ *
+ * **为什么必须有它**：旧的丢弃是**纯位置式**（从分项尾部丢）。而尾部恰好是
+ * `project-notes` 与 `user-memory`（本机实测：这两段被整段丢弃，而它们的价值最高）。
+ * 位置顺序是**渲染顺序**，不是**价值顺序** —— 用渲染顺序决定丢谁，等于让"谁写在后面谁先死"。
+ *
+ * - `must`：**永不丢弃**（用户级硬性规则、块首尾框架行）。若连它们都超限，如实报告超额，不静默丢。
+ * - `normal`：默认档。
+ * - `low`：先丢（如最近日志——量最大、时效性最强、可从文件重读）。
+ */
+export const ENVELOPE_PRIORITIES_V1 = Object.freeze(['low', 'normal', 'must'])
+const PRIORITY_RANK = Object.freeze({ low: 0, normal: 1, must: 2 })
+const normalizePriority = (v) => (Object.prototype.hasOwnProperty.call(PRIORITY_RANK, String(v)) ? String(v) : 'normal')
+
+/** 分项中文名（面板/日志可读；I7 精神：机器枚举之外要有人话）。 */
+export const ENVELOPE_BUCKET_TEXT_V1 = Object.freeze({
+  rules: '规则类',
+  memoryReferences: '记忆参考类',
+  otherDynamic: '其他动态内容',
+})
+
+/** 账本相关的原因码 → 可读中文。 */
+export const ENVELOPE_REASONS_V1 = Object.freeze({
+  'over-limit-dropped': '整段丢弃（超出分项上限）',
+  'over-limit-truncated': '截断（单段本身即超上限）',
+  'over-budget-total': '合计超出注入预算（分项账本如实记录，不掩盖）',
+  'unknown-bucket': '分项名非法（该段被计入 otherDynamic 并留痕）',
+})
+
+const clean = (v) => String(v == null ? '' : v)
+
+/**
+ * 组装注入信封（**纯函数**：同输入必定同输出）。
+ *
+ * @param {object} input
+ * @param {Array<{bucket:'rules'|'memoryReferences'|'otherDynamic', text:string, kind?:string}>} input.segments
+ *   **已渲染好的段落文本**，按调用方期望的输出顺序给出。每段文本逐字节照搬
+ *   （段内如需要前导换行，由调用方写进 `text`；本模块不补、不改、不重排）。
+ * @param {{memoryReferences?:number, otherDynamic?:number}} [input.limits]
+ *   分项字符上限。**未给出 = 该分项不设上限**（`rules` 在 P0/P6A 语义下**不参与裁剪**，
+ *   故即使传了也会被忽略并留痕）。
+ * @param {number} [input.budgetChars] 参考用的"总预算"（**只用于超额可见性**，不是硬门）。
+ *   给出后，若 `chars.total > budgetChars` 会产出一条 `over-budget-total` 降级项
+ *   —— 这是 v2 明确要求的"不许用记账写法掩盖代价"。
+ * @returns {{text:string, chars:{rules:number,memoryReferences:number,otherDynamic:number,total:number},
+ *            limits:{memoryReferences:number|null, otherDynamic:number|null, rulesIgnored?:boolean},
+ *            segments:Array, dropped:Array, truncated:Array, degradations:Array, ok:boolean}}
+ */
+export function composeMemoryEnvelopePre(input = {}) {
+  const o = input && typeof input === 'object' ? input : {}
+  const rawSegs = Array.isArray(o.segments) ? o.segments.filter(Boolean) : []
+  const limitsIn = o && typeof o.limits === 'object' && o.limits ? o.limits : {}
+  const dropped = []
+  const truncated = []
+  const degradations = []
+
+  // ── ① 归位：分项名非法的段落**不丢**，计入 otherDynamic 并留痕（不静默改归属） ──
+  const segs = rawSegs.map((s, i) => {
+    const text = clean(s && s.text)
+    let bucket = clean(s && s.bucket)
+    if (!ENVELOPE_BUCKETS_V1.includes(bucket)) {
+      degradations.push({
+        code: 'unknown-bucket', bucket: 'otherDynamic',
+        text: '[降级] 第 ' + (i + 1) + ' 段分项名非法（' + (bucket || '(空)') + '）→ 已计入其他动态内容，未丢弃',
+      })
+      bucket = 'otherDynamic'
+    }
+    return { bucket, kind: clean(s && s.kind), text, index: i, priority: normalizePriority(s && s.priority) }
+  })
+
+  // ── ② 限额：只对 memoryReferences / otherDynamic 生效；rules 不参与裁剪（P0/P6A 语义） ──
+  // ★2026-09-15 修复：`null` / `undefined` / 空串 **必须表示"不设限"**。
+  // 旧写法 `Number(limitsIn[b])` 会把 `null` 变成 **0**（`Number(null)===0`）⇒ 上限 0 ⇒ 该分项被整段丢光。
+  // 实测病症：调用方显式传 `otherDynamic: null`（= 未配置不设限）时，注入块只剩骨架两行，
+  // `smoke-test.mjs` 立刻报 "dynamic context missing status line"。
+  // 这类"缺省语义被数值化吃掉"的坑与 P6A 的 `Number(v) || 5` 是同一族，故在此显式区分三态。
+  const limitOf = (b) => {
+    if (b === 'rules') return null
+    const raw = limitsIn[b]
+    if (raw === null || raw === undefined || raw === '') return null
+    const n = Number(raw)
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null
+  }
+  const limits = {
+    memoryReferences: limitOf('memoryReferences'),
+    otherDynamic: limitOf('otherDynamic'),
+  }
+  // rules 若被显式传了上限 → 明确忽略并留痕（"规则不参与裁剪"是已定要求，不能被一个配置悄悄推翻）
+  const rulesLimitRaw = Number(limitsIn.rules)
+  if (limitsIn.rules !== undefined && Number.isFinite(rulesLimitRaw)) {
+    limits.rulesIgnored = true
+    degradations.push({
+      code: 'unknown-bucket', bucket: 'rules', inject: false,
+      text: '[降级] rules 分项上限（' + rulesLimitRaw + '）已被忽略：规则类不参与裁剪（分项账本仍如实体现在 chars.rules）',
+    })
+  }
+
+  const kept = segs.slice()
+  const rankOf = (s) => PRIORITY_RANK[normalizePriority(s.priority)]
+  const bucketTotal = (bucket) => kept.filter((s) => s.bucket === bucket).reduce((a, s) => a + s.text.length, 0)
+
+  /**
+   * ★2026-09-15 修复：丢弃顺序改为**优先级感知**（旧实现是纯位置式，从尾部丢）。
+   *
+   * 规则：同一分项内，先丢**优先级最低**的段；同档内部从**文档尾部**丢（顺序稳定）。
+   * `must` **永不丢弃** —— 若丢无可丢仍超限，**如实报告**而不是悄悄丢掉最高价值的内容。
+   * 只剩最后一段可丢时**截断**它（保留部分内容优于整段消失），与旧语义一致。
+   */
+  const enforceLimit = (bucket) => {
+    const lim = limits[bucket]
+    if (lim === null) return
+    for (;;) {
+      if (bucketTotal(bucket) <= lim) return
+      const mine = kept.filter((s) => s.bucket === bucket)
+      const droppable = mine.filter((s) => rankOf(s) < PRIORITY_RANK.must)
+      if (!droppable.length) {
+        // 全是 must ⇒ 不丢，如实报告超额（I7：可见，但不牺牲最高价值内容）
+        degradations.push({
+          code: 'over-limit-must', bucket, inject: true,
+          text: '[降级] ' + ENVELOPE_BUCKET_TEXT_V1[bucket] + '超出分项上限 ' + lim + ' 字符，但剩余 '
+            + mine.length + ' 段均为 must 级（不可丢）⇒ 本轮**保留全部**并如实报告超额 '
+            + (bucketTotal(bucket) - lim) + ' 字符（不静默丢弃硬性内容）',
+        })
+        return
+      }
+      if (droppable.length >= 2) {
+        const minRank = Math.min(...droppable.map(rankOf))
+        const group = droppable.filter((s) => rankOf(s) === minRank)
+        const victim = group[group.length - 1]
+        kept.splice(kept.indexOf(victim), 1)
+        dropped.push({ bucket, kind: victim.kind, chars: victim.text.length, priority: victim.priority, reason: 'over-limit-dropped' })
+        degradations.push({
+          code: 'over-limit-dropped', bucket, inject: true,
+          text: '[降级] ' + ENVELOPE_BUCKET_TEXT_V1[bucket] + '超出分项上限 ' + lim + ' 字符 → 丢弃优先级最低的一段'
+            + (victim.kind ? '（' + victim.kind + '，priority=' + normalizePriority(victim.priority) + '）' : '')
+            + '，未静默',
+        })
+        continue
+      }
+      // 只剩一段可丢 ⇒ 截断（截断标记本身占字符，先预留）
+      const only = droppable[0]
+      const mark = '…（已按分项预算截断，原文 ' + only.text.length + ' 字符）'
+      if (lim <= mark.length + 1) {
+        kept.splice(kept.indexOf(only), 1)
+        dropped.push({ bucket, kind: only.kind, chars: only.text.length, priority: only.priority, reason: 'over-limit-truncated' })
+        degradations.push({
+          code: 'over-limit-truncated', bucket, inject: true,
+          text: '[降级] ' + ENVELOPE_BUCKET_TEXT_V1[bucket] + '上限 ' + lim + ' 字符过小（放不下截断标记）→ 本段本轮为空',
+        })
+      } else {
+        const before = only.text.length
+        // ★2026-09-20 移植（issue #94③ / PR #100）：预算必须先扣掉同分项内 **must 段**的占用 ——
+        //   旧实现 room = lim − mark 不扣 must ⇒ 超限纯由 must 造成时，对本已放得下的段也追加
+        //   「已截断」标记（越截越长）并注入失实降级说明。
+        const mustChars = bucketTotal(bucket) - only.text.length
+        const available = Math.max(0, lim - mustChars)
+        const room = Math.max(1, available - mark.length)
+        only.text = only.text.slice(0, room) + mark
+        truncated.push({ bucket, kind: only.kind, charsBefore: before, charsAfter: only.text.length, reason: 'over-limit-truncated' })
+        degradations.push({
+          code: 'over-limit-truncated', bucket, inject: true,
+          text: '[降级] ' + ENVELOPE_BUCKET_TEXT_V1[bucket] + '只剩一段仍超上限 ' + lim + ' 字符 → 已截断（' + before + ' → ' + only.text.length + '）',
+        })
+      }
+      // 截断后复核：must 段自身超限时如实报告，不假装达标
+      if (bucketTotal(bucket) > lim) {
+        degradations.push({
+          code: 'over-limit-must', bucket, inject: true,
+          text: '[降级] ' + ENVELOPE_BUCKET_TEXT_V1[bucket] + '截断后仍超上限 ' + lim + ' 字符（剩余为 must 级不可丢）⇒ 如实报告超额 '
+            + (bucketTotal(bucket) - lim) + ' 字符',
+        })
+      }
+      return
+    }
+  }
+  enforceLimit('memoryReferences')
+  enforceLimit('otherDynamic')
+
+  // ── ③ 序列化：顺序 = 调用方给的顺序，逐字节拼接（不补分隔符、不重排） ──
+  const text = kept.map((s) => s.text).join('')
+
+  const chars = { rules: 0, memoryReferences: 0, otherDynamic: 0, total: text.length }
+  for (const s of kept) chars[s.bucket] += s.text.length
+
+  // ── ④ 超额可见性：分项账本如实记录，**不用任何写法掩盖**（v2 明确要求） ──
+  const budgetChars = Number.isFinite(Number(o.budgetChars)) && Number(o.budgetChars) > 0 ? Math.floor(Number(o.budgetChars)) : null
+  if (budgetChars !== null && chars.total > budgetChars) {
+    const parts = ENVELOPE_BUCKETS_V1.map((b) => ENVELOPE_BUCKET_TEXT_V1[b] + ' ' + chars[b]).join(' · ')
+    degradations.push({
+      code: 'over-budget-total', bucket: null, inject: false,
+      text: '[降级] 合计 ' + chars.total + ' 字符超出注入预算 ' + budgetChars + '（分项账本如实记录: ' + parts
+        + '）· 规则类与目录层不参与裁剪，超出的部分不会被掩盖',
+    })
+  }
+
+  return {
+    version: MEMORY_ENVELOPE_VERSION,
+    text,
+    chars,
+    limits,
+    segments: kept.map((s) => ({ bucket: s.bucket, kind: s.kind, chars: s.text.length })),
+    dropped,
+    truncated,
+    degradations,
+    // E1/E2 自证：调用方可以据此直接断言（也让"注水账本"不可能悄悄回来）
+    ok: chars.rules + chars.memoryReferences + chars.otherDynamic === chars.total,
+  }
+}
+
+/** 分项账本 → 单行可读文本（进降级行 / 面板 / 排障都用它，口径唯一）。 */
+export function describeEnvelopeCharsPre(envelope) {
+  const c = (envelope && envelope.chars) || { rules: 0, memoryReferences: 0, otherDynamic: 0, total: 0 }
+  return ENVELOPE_BUCKETS_V1.map((b) => ENVELOPE_BUCKET_TEXT_V1[b] + ' ' + (c[b] || 0)).join(' · ')
+    + ' · 合计 ' + (c.total || 0)
+}