@a9i5k4/dsh-auto-memory 3.1.4 → 3.1.6

package/lib/hub-io.js

@@ -23,11 +23,11 @@
  *   · 不做 unlink/copy 回退：调用方各自保留自己的原子性策略（同 `fs-retry.js` 的边界声明）。
  */
 
-import { mkdirSync, writeFileSync, renameSync, readFileSync, rmSync } from 'node:fs'
+import { mkdirSync, writeFileSync, renameSync, readFileSync, rmSync, existsSync } from 'node:fs'
 import path from 'node:path'
 
 /** errno → 人话。口径：暴露给前端/工具的原因必须人能看懂，不能只甩机器码。 */
-export const HUB_IO_ERRNO_MESSAGES_V1 = Object.freeze({
+export const HUB_IO_ERRNO_MESSAGES_PRE_V1 = Object.freeze({
   EACCES: '权限被拒绝（目标目录不可写）',
   EPERM: '操作被系统拒绝（权限或安全策略拦截，Windows 下也常见于文件被占用）',
   ENOSPC: '磁盘空间不足',
@@ -45,7 +45,7 @@ export const HUB_IO_ERRNO_MESSAGES_V1 = Object.freeze({
 /** 把任意异常翻成一句人话（带 errno 便于排障；无 code 时回落 message）。 */
 export function explainHubIoErrorPre(e) {
   const code = e && e.code ? String(e.code) : ''
-  const mapped = code ? HUB_IO_ERRNO_MESSAGES_V1[code] : ''
+  const mapped = code ? HUB_IO_ERRNO_MESSAGES_PRE_V1[code] : ''
   if (mapped) return mapped + '（' + code + '）'
   if (code) return '文件系统错误 ' + code
   return String((e && e.message) || e || '未知错误')
@@ -215,3 +215,356 @@ export function hubIoHealthSnapshotPre(health) {
     return empty
   }
 }
+
+/**
+ * ★M8-B（2026-09-23 用户拍板，方案甲）：**procedure 双库 IO —— 合并读 + 按 scope 分派写**。
+ *
+ * ── 为什么单独做一层 ──
+ * `createHubIoPre` 是**三店共用**的通用适配器（episodes / facts / procedures）。给它加作用域语义
+ * 会顺带改变另两店行为。故作用域只在本层实现，**只给 procedures 用**；另两店仍走原路径，
+ * 行为逐字节不变。
+ *
+ * ── 落点（与 migrate-pack 既有分层对齐）──
+ *   · 通用库（跨工作区）   = `<globalDir>/<name>`（既有 55 条所在，原地不动）
+ *   · 工作区库（本工作区） = `<resolveWorkspace().dir>/<name>`（新增）
+ *
+ * ── 三条硬约束 ──
+ *   ① **工作区目录必须惰性解析**：hub 在**引擎构造期**就建好（index.js 的 hubDir 同为构造期常量），
+ *      而工作区 state.ws 要等 _doRefresh 才赋值 ⇒ 构造期缓存会锁死空工作区，
+ *      随后 save 就可能把**空集**写进工作区库（灾难性覆盖）。故每次调用都现算。
+ *   ② **路径未知一律不写工作区库**：宁可这一轮不落盘（内存态仍完整、下轮再写），
+ *      也绝不用空集/错集覆盖用户的工作区技能库。所有跳过都**可见**（返回值 + health 记账）。
+ *   ③ **读坏过的文件不覆盖**：load 时「文件存在却解析失败」记入 corrupt 集，save 对这类文件**拒写**。
+ *      既有实现在「快照损坏 → load 返回 null → 内存空 → 下次 save 整份覆盖」下会**静默清空全部条目**；
+ *      双库把这一暴露面翻倍，故在此收紧为「宁可不写」。
+ *
+ * ── 明确声明的取舍 ──
+ *   procedures 的 save **不参与** createHubIoPre 的批内合并（批深度由 hub 侧的通用工厂持有，
+ *   本层看不到）⇒ 批内每次 persist 都是一次整份原子写。这是**刻意选择**：本轮刚因「机器定时回写」
+ *   付出过代价，宁可多写几次也不引入新的延迟写盘通道；数据量有界（当前 55 条 / 约 100KB）。
+ *   若日后实测写放大成问题，再单独评估合并策略 —— **不要顺手加定时器**。
+ *
+ * @param {object} opts
+ * @param {string}   opts.globalDir                  通用库目录（必填）
+ * @param {string}  [opts.name='procedures.json']     文件名
+ * @param {function} opts.resolveWorkspace           () => {dir,key}；未知时给空串（必填）
+ * @param {function} [opts.isWorkspaceScoped]        (entry) => boolean；缺省 scope==='workspace'
+ * @param {object}  [opts.health]                    复用 createHubIoHealthPre() 台账
+ * @param {function} [opts.onError]                  (key,msg) 失败回调
+ * @param {object}  [opts.fsApi]                     测试注入（透传给 createHubIoPre）
+ * @returns {{save:Function, load:Function, clear:Function, lastWrite:Function, isCorrupt:Function}}
+ */
+export function createScopedHubIoPre(opts = {}) {
+  const globalDir = String(opts.globalDir || '')
+  const fileName = String(opts.name || 'procedures.json')
+  const health = opts.health || createHubIoHealthPre()
+  const onError = opts.onError
+  const resolveWorkspace = typeof opts.resolveWorkspace === 'function'
+    ? opts.resolveWorkspace
+    : () => ({ dir: '', key: '' })
+  const isWs = typeof opts.isWorkspaceScoped === 'function'
+    ? opts.isWorkspaceScoped
+    : (e) => !!(e && e.scope === 'workspace')
+
+  // 每目录一个既有工厂（复用其原子写与 health 记账；不新建第二套 IO 实现）
+  const factories = new Map()
+  function ioFor(dir) {
+    let f = factories.get(dir)
+    if (!f) { f = createHubIoPre({ dir, health, onError, fsApi: opts.fsApi }); factories.set(dir, f) }
+    return f
+  }
+  const corrupt = new Set()
+  let last = {
+    at: 0, wroteGlobal: false, wroteWorkspace: false,
+    skippedUnknownWs: 0, skippedForeign: 0, refusedCorrupt: 0, foreignIds: [],
+  }
+
+  /** 取当前工作区 {dir,key}；任何异常都退化为「未知」⇒ 走约束②不写。 */
+  function wsNow() {
+    try {
+      const r = resolveWorkspace() || {}
+      return { dir: String(r.dir || ''), key: String(r.key || '') }
+    } catch (e) {
+      notePre(health, fileName, 'resolve-ws', e, onError)
+      return { dir: '', key: '' }
+    }
+  }
+
+  /** 读一份；「文件存在但解析失败 ⇒ null」记入 corrupt（供 save 拒写）。 */
+  function readOne(dir) {
+    const file = path.join(dir, fileName)
+    const data = ioFor(dir)(fileName).load()
+    let existed
+    try { existed = existsSync(file) } catch (_) { existed = false }
+    if (data === null && existed) corrupt.add(dir)
+    else corrupt.delete(dir)
+    return data
+  }
+
+  function load() {
+    const g = readOne(globalDir)
+    const w = wsNow()
+    const wsData = w.dir ? readOne(w.dir) : null
+    const gp = (g && Array.isArray(g.procedures)) ? g.procedures : []
+    const wp = (wsData && Array.isArray(wsData.procedures)) ? wsData.procedures : []
+    const any = g || wsData
+    if (!any) return null                      // 两库皆无 ⇒ 保持既有「空启动」语义
+    if (!gp.length && !wp.length) return Object.assign({}, any, { procedures: [] })
+    // 同 id 去重：**工作区优先**（更具体的一侧胜出）
+    const byId = new Map()
+    for (const p of gp) byId.set(String(p && p.procedureId), p)
+    for (const p of wp) byId.set(String(p && p.procedureId), p)
+    return {
+      schemaVersion: (g && g.schemaVersion) || (wsData && wsData.schemaVersion) || 1,
+      namespace: (g && g.namespace) || (wsData && wsData.namespace) || undefined,
+      policyVersion: (g && g.policyVersion) || (wsData && wsData.policyVersion) || undefined,
+      savedAt: Date.now(),
+      procedures: [...byId.values()],
+    }
+  }
+
+  function save(snapshot) {
+    const all = (snapshot && Array.isArray(snapshot.procedures)) ? snapshot.procedures : []
+    const w = wsNow()
+    const globals = []
+    const mine = []
+    const foreign = []
+    for (const p of all) {
+      if (!isWs(p)) { globals.push(p); continue }
+      const ref = String((p && p.workspaceRef) || '')
+      // 归属本工作区；ref 缺失时按「当前库」保守处理（不丢用户刚写的条目）
+      if (!ref || !w.key || ref === w.key) mine.push(p)
+      else foreign.push(p)
+    }
+    // 约束③：读坏过的文件拒写（宁可不动，也不静默清空）
+    let refused = 0
+    let wroteGlobal = false
+    if (corrupt.has(globalDir)) {
+      refused += globals.length
+    } else {
+      try {
+        ioFor(globalDir)(fileName).save(Object.assign({}, snapshot, { procedures: globals }))
+        wroteGlobal = true
+      } catch (_) { wroteGlobal = false }
+    }
+    let wroteWorkspace = false
+    if (!w.dir) {
+      // 约束②：路径未知 ⇒ 不写工作区库（不抛错，但必须可见）
+      if (mine.length) {
+        notePre(health, fileName, 'ws-unknown', new Error('工作区目录未解析：工作区库未写入，' + mine.length + ' 条留在内存，下轮再写'), onError)
+      }
+    } else if (corrupt.has(w.dir)) {
+      refused += mine.length
+    } else {
+      try {
+        ioFor(w.dir)(fileName).save(Object.assign({}, snapshot, { procedures: mine }))
+        wroteWorkspace = true
+      } catch (_) { wroteWorkspace = false }
+    }
+    last = {
+      at: Date.now(), wroteGlobal, wroteWorkspace,
+      skippedUnknownWs: w.dir ? 0 : mine.length,
+      skippedForeign: foreign.length,
+      refusedCorrupt: refused,
+      foreignIds: foreign.map((p) => String(p && p.procedureId)).slice(0, 5),
+    }
+    return Object.assign({ ok: wroteGlobal || wroteWorkspace }, last)
+  }
+
+  function clear() {
+    let ok = true
+    try { ioFor(globalDir)(fileName).clear(); corrupt.delete(globalDir) } catch (e) {
+      ok = false; notePre(health, fileName, 'clear-global', e, onError)
+    }
+    const w = wsNow()
+    if (w.dir) {
+      try { ioFor(w.dir)(fileName).clear(); corrupt.delete(w.dir) } catch (e) {
+        ok = false; notePre(health, fileName, 'clear-ws', e, onError)
+      }
+    }
+    return { ok }
+  }
+
+
+  /**
+   * ★M8-B 第4步：**两阶段迁移**（写接收库 → 读回校验 → 写捐赠库 → 读回校验；任一失败整体回滚）。
+   *
+   * 为什么必须两阶段：跨文件移动**不是原子的**。写目标成功、删源失败 ⇒ 条目复制成两份；
+   * 反序则更糟——删源成功、写目标失败 ⇒ **条目直接消失**。故这里定死两条：
+   *   ① **先写接收库、后写捐赠库**——失败时最坏是「多留一份」而非「丢一份」，
+   *      即 **fail toward duplication, never toward loss**（可见、可重试、可人工清理）。
+   *   ② 每写一步就**读回校验**，不是写完就当成功（写盘函数的返回不等于内容真落对）。
+   * 任一步校验不过：把两库恢复到**迁移前快照**，并如实返回 rolledBack。
+   *
+   * @param {Array<{procedureId:string, scope:string, workspaceRef?:string}>} entries 目标归属
+   * @param {function} [onProgress] (done,total,item) —— 进度是两阶段提交的**可见化**
+   * @returns {{ok:boolean,total:number,moved:number,failed:number,rolledBack:boolean,results:Array}}
+   */
+  function migrate(entries, onProgress) {
+    const list = (Array.isArray(entries) ? entries : [entries]).filter(Boolean)
+    const total = list.length
+    const results = []
+    let moved = 0
+    let failed = 0
+    let rolledBack = false
+    const w = wsNow()
+
+    // 回滚凭据：两库**迁移前**的解析快照（null = 该库无文件/为空；损坏库已被 readOne 记入 corrupt）
+    const globalBefore = readOne(globalDir)
+    const wsBefore = w.dir ? readOne(w.dir) : null
+    // 深拷一份作为回滚源，避免后续 map 改动污染凭据
+    const snapOf = (x) => (x && Array.isArray(x.procedures))
+      ? Object.assign({}, x, { procedures: x.procedures.map((p) => Object.assign({}, p)) })
+      : null
+
+    function rollbackBoth() {
+      let ok = true
+      try { ioFor(globalDir)(fileName).save(snapOf(globalBefore) || { schemaVersion: 1, procedures: [] }) }
+      catch (e) { ok = false; notePre(health, fileName, 'migrate-rollback-global', e, onError) }
+      if (w.dir) {
+        try { ioFor(w.dir)(fileName).save(snapOf(wsBefore) || { schemaVersion: 1, procedures: [] }) }
+        catch (e) { ok = false; notePre(health, fileName, 'migrate-rollback-ws', e, onError) }
+      }
+      return ok
+    }
+
+    // 以「迁移前快照」为工作副本，逐条改归属；两条目的条目集合由 scope 决定
+    let gList = (globalBefore && Array.isArray(globalBefore.procedures)) ? globalBefore.procedures.map((p) => Object.assign({}, p)) : []
+    let wList = (wsBefore && Array.isArray(wsBefore.procedures)) ? wsBefore.procedures.map((p) => Object.assign({}, p)) : []
+    const findIn = (arr, id) => arr.findIndex((p) => String(p && p.procedureId) === String(id))
+
+    for (let i = 0; i < list.length; i++) {
+      const it = list[i] || {}
+      const id = String(it.procedureId || '')
+      const targetScope = it.scope === 'workspace' ? 'workspace' : 'global'
+      const targetRef = String(it.workspaceRef || '')
+      const tag = { procedureId: id, targetScope, targetRef }
+      // 目标库落地检查：要进工作区库但工作区未知 ⇒ 明确失败（绝不猜一个目录写下去）
+      if (targetScope === 'workspace' && (!w.dir || !w.key)) {
+        failed++
+        results.push(Object.assign({ ok: false, reason: 'ws-unknown' }, tag))
+        if (onProgress) onProgress(i + 1, total, results[results.length - 1])
+        continue
+      }
+      if (targetScope === 'workspace' && targetRef && targetRef !== w.key) {
+        failed++
+        results.push(Object.assign({ ok: false, reason: 'foreign-workspace' }, tag))
+        if (onProgress) onProgress(i + 1, total, results[results.length - 1])
+        continue
+      }
+      // 定位源（两库都找）
+      let gi = findIn(gList, id)
+      let wi = findIn(wList, id)
+      // ★双库同 id：先按 `load()` 的**既有读优先级（工作区优先）**去重，维持「一个 id 只住在一个库」。
+      //   不做这步的实测后果：接收库那条留着、又从捐赠库推一条进来 ⇒ 同一 id 两份
+      //   —— 正是两阶段迁移专门要防的「复制成两份」，静态检查与语法检查都发现不了。
+      if (gi >= 0 && wi >= 0) { gList.splice(gi, 1); gi = findIn(gList, id) }
+      const src = gi >= 0 ? 'global' : (wi >= 0 ? 'workspace' : null)
+      if (!src) {
+        failed++
+        results.push(Object.assign({ ok: false, reason: 'not-found' }, tag))
+        if (onProgress) onProgress(i + 1, total, results[results.length - 1])
+        continue
+      }
+      if (src === targetScope) {
+        // 已在目标库：只把 workspaceRef 校正到位（幂等，不动位置）
+        const arr = src === 'global' ? gList : wList
+        const idx = src === 'global' ? gi : wi
+        arr[idx].scope = targetScope
+        if (targetScope === 'workspace') arr[idx].workspaceRef = w.key
+        moved++
+        results.push(Object.assign({ ok: true, noop: true, from: src, to: targetScope }, tag))
+        if (onProgress) onProgress(i + 1, total, results[results.length - 1])
+        continue
+      }
+      // 迁移：先改内存副本
+      const entry = src === 'global' ? gList.splice(gi, 1)[0] : wList.splice(wi, 1)[0]
+      entry.scope = targetScope
+      entry.workspaceRef = targetScope === 'workspace' ? w.key : ''
+      const receiving = targetScope === 'workspace' ? wList : gList
+      const donating = targetScope === 'workspace' ? gList : wList
+      receiving.push(entry)
+
+      // 两阶段提交
+      const recvDir = targetScope === 'workspace' ? w.dir : globalDir
+      const donDir = targetScope === 'workspace' ? globalDir : w.dir
+      const recvSnap = { schemaVersion: 1, namespace: 'dsh-auto-memory-pre', procedures: receiving }
+      const donSnap = { schemaVersion: 1, namespace: 'dsh-auto-memory-pre', procedures: donating }
+      let step = 'write-receiving'
+      let stepOk = false
+      try {
+        if (corrupt.has(recvDir)) throw new Error('receiving library corrupt: ' + recvDir)
+        ioFor(recvDir)(fileName).save(recvSnap)
+        step = 'verify-receiving'
+        const back = ioFor(recvDir)(fileName).load()
+        const hit = back && Array.isArray(back.procedures) && back.procedures.some((p) => String(p.procedureId) === id && (p.scope || 'global') === targetScope)
+        if (!hit) throw new Error('receiving verify failed')
+        step = 'write-donating'
+        if (corrupt.has(donDir)) throw new Error('donating library corrupt: ' + donDir)
+        ioFor(donDir)(fileName).save(donSnap)
+        step = 'verify-donating'
+        const back2 = ioFor(donDir)(fileName).load()
+        const stillThere = back2 && Array.isArray(back2.procedures) && back2.procedures.some((p) => String(p.procedureId) === id)
+        if (stillThere) throw new Error('donating verify failed (still present)')
+        stepOk = true
+      } catch (e) {
+        notePre(health, fileName, 'migrate-' + step, e, onError)
+        // 回滚：两库都恢复到迁移前快照；同时把内存副本复位，避免下一条基于坏状态继续
+        rolledBack = true
+        rollbackBoth()
+        gList = (globalBefore && Array.isArray(globalBefore.procedures)) ? globalBefore.procedures.map((p) => Object.assign({}, p)) : []
+        wList = (wsBefore && Array.isArray(wsBefore.procedures)) ? wsBefore.procedures.map((p) => Object.assign({}, p)) : []
+        failed++
+        results.push(Object.assign({ ok: false, reason: 'phase-failed', step, error: String((e && e.message) || e) }, tag))
+        if (onProgress) onProgress(i + 1, total, results[results.length - 1])
+        continue
+      }
+      if (stepOk) {
+        moved++
+        results.push(Object.assign({ ok: true, from: src, to: targetScope, phase: 'committed' }, tag))
+      }
+      if (onProgress) onProgress(i + 1, total, results[results.length - 1])
+    }
+
+    last = {
+      at: Date.now(), wroteGlobal: false, wroteWorkspace: false,
+      skippedUnknownWs: 0, skippedForeign: 0, refusedCorrupt: 0, foreignIds: [],
+      migrated: moved, migrateFailed: failed, rolledBack,
+    }
+    return { ok: failed === 0, total, moved, failed, rolledBack, results }
+  }
+  /**
+   * ★M8-B 第6步（2026-09-23）：**只读**描述两库现状，供前端「双库视图」回答
+   * 「当前是哪个库 / 各库各有多少条 / 能不能写工作区库」。
+   *
+   * 为什么不把路径给前端：前端不需要、也不该拿到真实磁盘路径（那是注入面与
+   * 迁移包才关心的事）；这里只回**库标识与计数**，足够渲染归属徽标与禁用理由。
+   * 读盘失败一律 fail-soft 记 -1（前端显示「不可读」），绝不让面板整个挂掉。
+   */
+  function describe() {
+    const w = wsNow()
+    const countIn = (dir) => {
+      if (!dir) return -1
+      try {
+        const d = readOne(dir)
+        return (d && Array.isArray(d.procedures)) ? d.procedures.length : 0
+      } catch (_) { return -1 }
+    }
+    return {
+      defaultScope: 'global',
+      workspaceKey: w.key,
+      workspaceReady: !!(w.dir && w.key),
+      globalDirCorrupt: corrupt.has(String(globalDir || '')),
+      workspaceDirCorrupt: w.dir ? corrupt.has(String(w.dir)) : false,
+      globalCount: countIn(globalDir),
+      // 工作区未知时不探盘：`countIn('')` 会回 -1，含义是「当前无法归属」而非「0 条」
+      workspaceCount: countIn(w.dir),
+    }
+  }
+
+  return {
+    save, load, clear, migrate, describe,
+    lastWrite: () => Object.assign({}, last),
+    isCorrupt: (dir) => corrupt.has(String(dir || '')),
+  }
+}

package/lib/index-sync.js

@@ -13,7 +13,7 @@ import { workspaceRefOf } from './evidence-store.js'
 import {
   buildChunkIdPre, buildSyncIdPre, computePageDigestPre, computeFinalDigestPre,
   validateIndexSyncBeginPre, validateIndexSyncPagePre, validateIndexSyncCommitPre, validateSemanticRecordPre,
-  M7_INDEX_POLICY_VERSION_V1,
+  M7_INDEX_POLICY_VERSION_PRE_V1,
 } from './m7-wire.js'
 
 /**
@@ -28,7 +28,7 @@ import {
  *
  * 故留 **4KiB 余量**（≈ 实测信封 202–230B 的 18 倍）。
  */
-export const INDEX_SYNC_PAGE_BUDGET_V1 = Object.freeze({ maxRecordsPerPage: 64, maxPageBytes: 252 * 1024 })
+export const INDEX_SYNC_PAGE_BUDGET_PRE_V1 = Object.freeze({ maxRecordsPerPage: 64, maxPageBytes: 252 * 1024 })
 const SCOPE_ORDER_PRE = ['Workspace', 'User']
 
 function pagePayloadBytes(syncId, pageNo, pageCount, records) {
@@ -67,12 +67,12 @@ export function toSemanticRecordPre(rec, workspaceRef) {
  * 返回 {ok:true, plans:[{scope, begin, pages[], commit}], recordTotal}|{ok:false, reason}。
  */
 export function buildIndexSyncPlansPre(input) {
-  const B = INDEX_SYNC_PAGE_BUDGET_V1
+  const B = INDEX_SYNC_PAGE_BUDGET_PRE_V1
   const snap = input && input.snapshot
   const recordsRaw = Array.isArray(input && input.records) ? input.records : (snap ? snap.records : [])
   const sourcesAll = Array.isArray(input && input.sources) ? input.sources : (snap ? snap.sources : [])
   const miv = String((input && input.memoryIndexVersion) || (snap ? snap.memoryIndexVersion : '') || '')
-  if (!miv.startsWith('idx_')) return { ok: false, reason: 'memoryIndexVersion' }
+  if (!miv.startsWith('idx_pre_')) return { ok: false, reason: 'memoryIndexVersion' }
   const wsRef = workspaceRefOf(String((input && input.workspaceKey) || ''))
   const byScope = new Map()
   for (const r of recordsRaw) {
@@ -118,7 +118,7 @@ export function buildIndexSyncPlansPre(input) {
     const pageCount = pagesRecords.length
     const begin = {
       schemaVersion: 1, syncId, workspaceRef: wsRef, scope, memoryIndexVersion: miv,
-      sourceTuples, recordCount, pageCount, indexPolicyVersion: M7_INDEX_POLICY_VERSION_V1,
+      sourceTuples, recordCount, pageCount, indexPolicyVersion: M7_INDEX_POLICY_VERSION_PRE_V1,
     }
     const bv = validateIndexSyncBeginPre(begin)
     if (!bv.ok) return { ok: false, reason: 'begin:' + bv.reason }