@a9i5k4/dsh-auto-memory 2.5.3 → 3.0.1

package/lib/activation-host.js

@@ -19,6 +19,7 @@ import {
 import { createActivationInboxPre, ActivationInboxRegistry, REFERENCE_TAIL_COOLDOWN_STEPS_V1 } from './activation-inbox-state.js'
 import { createAccessEvidencePre } from './context-bridge.js'
 import path from 'node:path'
+import { resolveDshHomeForEnginePre } from './dsh-home.js'
 import { buildSourceCatalog, loadCorpusSnapshot, CorpusRegistry, canonicalize } from './m4-corpus.js'
 
 /** §11 capability 快照版本。 */
@@ -43,9 +44,18 @@ export function createActivationHost(opts = {}) {
   const registry = new ActivationInboxRegistry()
   const corpusRegistry = new CorpusRegistry({ sidecarDir: path.join(dshHome(), 'memory', 'index', 'files') })
   const runtimeState = new Map() // runtime.key → {step, claimed:{packet, inbox}|null, identity:{sessionId,workspaceKey}|null}
-  let mivCache = { wsRef: null, miv: null }
+  // ★多工作区适配(2026-09-17):以下两处此前是**单槽**(一个变量只装"最后写入者")。
+  // 症状:会话 A 投递 → 槽里是 A;会话 B(或用户点开另一个工作区触发 B)投递 → 槽里变 B;
+  // A 下一轮来取 ⇒ 身份不匹配 ⇒ 降级"投影来自其它会话/工作区" ⇒ A **永远不下探 Tier-1**。
+  // 现改为按身份分片:投影按 sessionId、miv 按 wsRef。**只增 key 维度,不改任何判定口径**。
+  const mivCacheByWs = new Map()   // wsRef -> miv(每个工作区各记一份,不再互相踢)
   const pathsByKey = new Map()
+  // ★#84（2026-09-20）：`≤16 最小投影` —— 原实现在超出上限时**静默 shift**，
+  //   于是「诊断面看不到最近事件」没有任何痕迹；排查时会误判成「压根没产生事件」。
+  //   现补 `volatileDropped` 计数并具名化上限。
   const volatileEvents = [] // ≤16 最小投影
+  let volatileDropped = 0
+  const VOLATILE_MAX_V1 = 16
   const stats = { injected: 0, injectedAccepted: 0, injectedRejected: 0, claims: 0, claimFails: 0, rendered: 0, delivered: 0, seenCreated: 0, seenSkippedNoProv: 0, errors: 0 }
 
   function effectiveEnabled() {
@@ -65,14 +75,17 @@ export function createActivationHost(opts = {}) {
     return 'invalid'
   }
   function dshHome() {
-    const env = process.env.DSH_HOME
-    if (env && env.trim()) return env.trim()
-    const base = engine.__homedirFn ? engine.__homedirFn() : (process.env.USERPROFILE || process.env.HOME || '')
-    return base ? path.join(base, '.dsh') : '.'
+    // ★#86-3：统一口径。原实现全失败时返回 '.'（**与其余站点不同**）；
+    //   __homedirFn 注入点由 resolveDshHomeForEnginePre 保留，测试兼容。
+    return resolveDshHomeForEnginePre(engine)
   }
   function pushEvent(entry) {
     volatileEvents.push({ at: Date.now(), ...entry })
-    if (volatileEvents.length > 16) volatileEvents.shift()
+    if (volatileEvents.length > VOLATILE_MAX_V1) {
+      volatileEvents.shift()
+      // ★#84：丢弃必须留痕（否则「看不到事件」无法区分「没产生」与「被挤掉」）
+      volatileDropped++
+    }
   }
   function capturePaths(runtimeKey, p) {
     pathsByKey.set(String(runtimeKey || ''), {
@@ -84,10 +97,13 @@ export function createActivationHost(opts = {}) {
   }
 
 
-  /** 当前 workspace 的 memoryIndexVersion(自有 CorpusRegistry 懒加载;失败 null 并清缓存)。 */
+  /** 当前 workspace 的 memoryIndexVersion(自有 CorpusRegistry 懒加载;失败 null 并清缓存)。
+   *  ★多工作区适配(2026-09-17):缓存**按 wsRef 分片**。旧实现是单变量 `mivCache`,只认最后一个
+   *  wsRef —— 用户点开另一个工作区、或另一会话投递时就会把前一个的缓存踢掉,于是两个工作区
+   *  来回切换时每次 `currentMiv` 都必然 miss、每次都重算语料快照,并进一步放大 P0-4e
+   *  ("持续变更 ⇒ 索引永远不就绪")。分片后各工作区各记一份,互不干扰。 */
   function currentMiv(workspaceKey) {
     const ws = canonicalize(workspaceKey)
-    const p = null
     for (const [, v] of pathsByKey) {
       if (v.workspaceKey !== ws) continue
       try {
@@ -99,16 +115,26 @@ export function createActivationHost(opts = {}) {
         })
         const res = corpusRegistry.get(catalog)
         if (res && res.ok) {
-          mivCache = { wsRef: ws, miv: res.snapshot.memoryIndexVersion }
-          return mivCache.miv
+          mivCacheByWs.set(ws, res.snapshot.memoryIndexVersion)
+          return res.snapshot.memoryIndexVersion
         }
       } catch (_) {}
       break
     }
-    if (mivCache.wsRef === ws) return mivCache.miv
-    return null
+    return mivCacheByWs.get(ws) || null
+  }
+  function setMiv(workspaceKey, miv) { mivCacheByWs.set(canonicalize(workspaceKey), miv) }
+  /** 取某工作区最近一次已知 miv(无则 null)。供上层投影/诊断读取,不再假设"全局只有一个"。 */
+  function mivFor(workspaceKey) {
+    const ws = canonicalize(workspaceKey)
+    return mivCacheByWs.get(ws) || null
+  }
+  /** 最近写入的一份 miv(兼容投影:给既有诊断面板/老调用方用;多工作区语义请用 mivFor)。 */
+  function latestMiv() {
+    let last = null
+    for (const v of mivCacheByWs.values()) last = v
+    return last
   }
-  function setMiv(workspaceKey, miv) { mivCache = { wsRef: canonicalize(workspaceKey), miv } }
 
   function identityFor(runtime) {
     const sessionId = runtime.sessionId || ''
@@ -137,11 +163,73 @@ export function createActivationHost(opts = {}) {
       return finishInject(box, req)
     } catch (e) { stats.errors++; return { ok: false, reason: 'internal-error' } }
   }
+  /**
+   * C5 闸门输入(2026-09-14 三层契约 §5):把本轮语义命中压成**轻量投影**挂到 engine,
+   * 供注入层决定"要不要下探 Tier-1/Tier-2"(未命中就只给 Tier-0 目录层 = 省 token 的关键)。
+   * 只存 memoryId/score/摘要/layer/status —— 不复制 packet,不做任何 IO,零 LLM(S9)。
+   *
+   * T0-2(2026-09-14 P0):**必须同时存版本四元组** `contextVersion / miv / observationId / requestKey`。
+   * 旧实现在注入侧只用 `Date.now() - gh.at < 30*60000` 判复用 —— **只查时间不查版本**,
+   * 于是「A 快照产生的候选到 B 快照才准备输出」时 A 的正文会进 B 的注入(违反契约 I6「三层同一快照」)。
+   * 这里补齐投影字段,判定与 fail-closed 语义在 `lib/tier-layer-inject.js:selectReusableTierHitsPre`。
+   * `workspaceKey` 同时补齐:身份门需要它证明投影归属(旧实现压根没存工作区)。
+   */
+  function recordTierGateHits(req) {
+    try {
+      if (!engine || typeof engine !== 'object') return
+      const sid = String(req.sessionId || '')
+      const lq = engine._lastTierQuery || null
+      const q = (lq && Date.now() - (Number(lq.at) || 0) < 120000 && String(lq.sessionId || '') === sid)
+        ? String(lq.text || '') : String(req.triggerText || '')
+      const projection = {
+        sessionId: sid,
+        agentId: String(req.agentId || ''),
+        workspaceKey: String(req.workspaceKey || ''),
+        at: Date.now(),
+        question: q.slice(0, 1200),
+        // —— T0-2 版本四元组（复用前必须逐项比对；缺任一项下游 fail closed 不复用）——
+        contextVersion: Number.isInteger(req.contextVersion) ? req.contextVersion : undefined,
+        miv: String(req.memoryIndexVersion || '') || undefined,
+        observationId: String(req.observationId || '') || undefined,
+        requestKey: String(req.requestKey || '') || undefined,
+        // 状态过滤（I5/C8）在注入侧做（见 tier-layer-inject-pre 的 filterCurrentHitsPre），
+        // 这里**照原样保留 status**：投影是审计面，过滤是准入面，两者不混。
+        hits: (Array.isArray(req.candidates) ? req.candidates : []).slice(0, 8).map((c) => ({
+          memoryId: String((c && c.memoryId) || ''),
+          score: Number(c && c.score),
+          excerpt: String((c && c.excerpt) || ''),
+          layer: (c && c.layer) || 'log',
+          status: (c && c.status) || 'current',
+          sourceRef: String((c && c.sourceRef) || ''),
+          scope: String((c && c.scope) || ''),
+        })),
+      }
+      // ★多工作区适配(2026-09-17)：投影**按会话分片**存放，读取侧按当前会话取。
+      // 旧实现是单槽 `engine._tierGateHits = {...}`：会话 A 投递后被 B 覆盖，A 下一轮取到的
+      // 是 B 的投影 ⇒ 身份门判 session-mismatch ⇒ A **永远不下探 Tier-1**（"谁也没法注入"）。
+      // 分片后 A/B 各存各的，互不覆盖；仍然**逐项比对四元组**，判定口径一字未改。
+      if (!engine._tierGateHitsBySession || typeof engine._tierGateHitsBySession.set !== 'function') {
+        engine._tierGateHitsBySession = new Map()
+      }
+      // ★2026-09-20 移植（issue #94⑤ / PR #100）：Map.set 对既有键**不刷新插入序** ⇒
+      //   keys().next() 淘汰的是「最老创建」而非「最久未用」，最活跃会话反被逐出。
+      engine._tierGateHitsBySession.delete(sid)
+      engine._tierGateHitsBySession.set(sid, projection)
+      // 兼容投影：保留旧字段指向"最近一次投递"，供旧诊断面板/测试继续可读（只增不改语义）。
+      engine._tierGateHits = projection
+      // 有界：最多保留 32 个会话的投影，避免长时间运行后 Map 无限增长。
+      if (engine._tierGateHitsBySession.size > 32) {
+        const oldest = engine._tierGateHitsBySession.keys().next().value
+        engine._tierGateHitsBySession.delete(oldest)
+      }
+    } catch (_) {}
+  }
   function finishInject(box, req) {
     box.setCursor({ contextVersion: req.contextVersion, memoryIndexVersion: req.memoryIndexVersion })
     const r = box.offerActivation(req, { nowStep: stepFor(req.sessionId, req.workspaceKey), currentMemoryIndexVersion: req.memoryIndexVersion })
     if (r.ok) {
       stats.injectedAccepted++
+      recordTierGateHits(req)
       // fake 来源「注入即泵」：立刻以请求自声明版本过四重门 claim，并把 claimed 挂到
       // 目标 runtime 态——下一次该 session 的自然 compose 会渲染尾注并 markDelivered(+seen)。
       pumpClaimed(box, req)
@@ -158,7 +246,10 @@ export function createActivationHost(opts = {}) {
    */
   function pumpClaimed(box, req) {
     const c2 = box.claim({
-      nowStep: stepFor(req.sessionId, req.workspaceKey),
+      // ★ issue #75 CC-11 修复：用**只读**步号，不再自增。
+      //   pump 总是紧跟在同键 `stepFor`（offer 时）之后同步调用 ⇒ 读到的就是刚烘焙 TTL 的那个步。
+      //   旧实现此处再 `stepFor` 一次 ⇒ 同一步内凭空消耗 2 步 TTL（见 currentStepOf 注释）。
+      nowStep: currentStepOf(req.sessionId, req.workspaceKey),
       currentContextVersion: req.contextVersion,
       currentMemoryIndexVersion: req.memoryIndexVersion,
     })
@@ -215,6 +306,7 @@ export function createActivationHost(opts = {}) {
         // 在回合中段必死(cv 每段自增+TTL3 步),Python emit 的时序机制完全相同,同一证据
         // 同一修法。泵是 M6 投递侧机制,不耦合任何语义档(JS/Python 各自独立可用)。
         pumpClaimed(box, req)
+        recordTierGateHits(req) // C5 闸门输入(与 fake 档同一投影)
       } else stats.injectedRejected++
       return r
     } catch (e) { stats.errors++; return { ok: false, reason: 'internal-error' } }
@@ -271,12 +363,39 @@ export function createActivationHost(opts = {}) {
     return { ok: true, request }
   }
   const stepsByRuntime = new Map()
+  /**
+   * 步进计数器的**唯一键格式**（issue#58 修复，2026-09-19）。
+   * 旧实现：写入侧用 `sessionId + '|ws:' + workspaceKey`，而删除侧 `disposeRuntime` 用
+   * `String(runtimeKey)`（= `session:<sid>`）⇒ **两个键空间永不相交** ⇒ 删除是空操作，
+   * `stepsByRuntime` 只增不减（「会话×工作区」一条，进程内永不回收）。
+   * 现在格式收敛到这一处，写入与删除共用，杜绝再次漂移。
+   */
+  function stepKeyOf(sessionId, workspaceKey) {
+    return String(sessionId || '') + '|ws:' + String(workspaceKey || '')
+  }
   function stepFor(sessionId, workspaceKey) {
-    const key = sessionId + '|ws:' + workspaceKey
+    const key = stepKeyOf(sessionId, workspaceKey)
     const n = (stepsByRuntime.get(key) || 0) + 1
     stepsByRuntime.set(key, n)
     return n
   }
+  /**
+   * ★ issue #75 CC-11 修复（2026-09-19）：**只读**当前步（不自增）。
+   *
+   * 动机：`stepFor` 是自增器（+1 写回）。而「注入即泵」路径是
+   * `finishInject` 先 `offerActivation({nowStep: stepFor(...)})` 烘焙 TTL 起点，
+   * 紧接着**同一同步块内** `pumpClaimed` 又调一次 `stepFor` 去 claim
+   * ⇒ **offer 与 pump 各消耗 1 步而零时间流逝** ⇒ `expiresAtStep` 按第一次烘焙、
+   * 判定却用第二次 ⇒ TTL 窗口凭空少 1 步（实测 ttl=3 的自然投递窗由 2 次机会缩为 1；
+   * ttl=2 的 rollback 场景整包必死）。
+   *
+   * 语义上「同步 offer + pump」是**同一步内**的投递动作，不该消耗 2 步 TTL。
+   * 因此给 pump 侧提供只读版本：它总是紧跟在同键的 `stepFor` 之后调用，
+   * 读到的必然是刚自增过的那个值（≥1），不会读到 0。
+   */
+  function currentStepOf(sessionId, workspaceKey) {
+    return stepsByRuntime.get(stepKeyOf(sessionId, workspaceKey)) || 0
+  }
 
   /**
    * agent/pre-step(§8):先校验当前 cursor/index/TTL 再 claim;claimed packet 存 runtime 态,
@@ -294,6 +413,8 @@ export function createActivationHost(opts = {}) {
       const miv = currentMiv(identity.workspaceKey)
       box.setCursor({ contextVersion: runtime.contextVersion, memoryIndexVersion: miv || undefined })
       const nowStep = stepFor(identity.sessionId, identity.workspaceKey)
+      // issue#58:把步进键登记进 runtime 态,供 disposeRuntime 精确回收(否则计数器只增不减)。
+      const stepKeyHere = stepKeyOf(identity.sessionId, identity.workspaceKey)
       const c = box.claim({
         nowStep,
         currentContextVersion: runtime.contextVersion,
@@ -302,6 +423,7 @@ export function createActivationHost(opts = {}) {
       let st = runtimeState.get(runtime.key)
       if (!st) { st = { step: 0, claimed: null }; runtimeState.set(runtime.key, st) }
       st.step = nowStep
+      st.stepKey = stepKeyHere
       if (c.ok) { st.claimed = { packet: c.packet, inbox: box }; stats.claims++ }
       else {
         // 2026-08-28 浏览器实测修复:claim 失败(none-pending 等)不得清掉已存在的 claimed——
@@ -386,7 +508,11 @@ export function createActivationHost(opts = {}) {
       cooldownSteps: REFERENCE_TAIL_COOLDOWN_STEPS_V1,
       capability: cap,
       sourceMode: sourceMode(),
-      memoryIndexVersion: mivCache.miv || null,
+      // 多工作区适配(2026-09-17):不再返回"最后一个写入者"的 miv,而是按工作区分片的映射。
+      // 同时保留旧字段 `memoryIndexVersion` 作为**兼容投影**(取最近写入的那一份),供既有
+      // 诊断面板/测试继续工作 —— 只增字段不改语义,避免开关耦合。
+      memoryIndexVersion: latestMiv() || null,
+      mivByWorkspace: Object.fromEntries(mivCacheByWs),
       inboxCount: registry.size,
       stats: { ...stats },
       recentEvents: volatileEvents.slice(-4),
@@ -424,9 +550,18 @@ export function createActivationHost(opts = {}) {
     } catch (e) { stats.errors++; return { ok: false, reason: 'internal-error' } }
   }
 
+  /**
+   * 单 runtime 清理。issue#58 修复（2026-09-19）：**必须清掉步进计数器**。
+   * 旧实现 `stepsByRuntime.delete(String(runtimeKey))` 是坏键（见 `stepKeyOf` 注释）⇒ 空操作。
+   * 现在优先用创建时登记的 `stepKey`；同时保留 runtimeKey 形态的删除，
+   * 兼容「调用方直接传 step-key」的情况（两条都删，代价为零）。
+   */
   function disposeRuntime(runtimeKey) {
-    runtimeState.delete(runtimeKey)
-    stepsByRuntime.delete(String(runtimeKey))
+    const k = String(runtimeKey)
+    const st = runtimeState.get(k)
+    runtimeState.delete(k)
+    if (st && st.stepKey) stepsByRuntime.delete(st.stepKey)
+    stepsByRuntime.delete(k)
   }
   function disposeAll(reason) {
     runtimeState.clear()

package/lib/activation-inbox.js

@@ -200,14 +200,26 @@ export function validateActivationSkillPre(s) {
   }
 }
 
-/** 单条引用块(provenance 三行身份永不省略;reference 行内容经卫生处理)。 */
-function renderItemBlock(item, reason) {
+/**
+ * 单条引用块(provenance 三行身份永不省略;reference 行内容经卫生处理)。
+ * 2026-09-14 P1-⑮:补 **Score 行** —— 0-1 相似度与批内排名此前在渲染时被丢弃,
+ * 注入侧只看得见 lane/reasonCodes,看不到"到底多像"(用户报告"0-1 相似度排序没了")。
+ * 分值与排名都取自 packet 内既有字段(item.score + 排序后的位置),确定性同 build/重渲染;
+ * score 非法(非有限数)时整行省略,保持与旧版逐字节一致的降级行为。
+ */
+function renderItemBlock(item, reason, rank, total) {
   const refText = item.reference != null ? sanitizeTailText(item.reference) : ''
+  const sc = Number(item.score)
   const lines = [
     TAIL_MARKER_LINE_V1,
     'Source: ' + item.memoryId + ' / ' + item.scope + ' / v' + item.sourceVersion + ' / ' + String(item.recordDigest).slice(0, 16),
     'Reason: ' + reason,
   ]
+  if (Number.isFinite(sc)) {
+    const r = Number.isInteger(rank) && rank > 0 ? rank : null
+    const t = Number.isInteger(total) && total > 0 ? total : null
+    lines.push('Score: ' + sc.toFixed(2) + (r && t ? ' (rank ' + r + '/' + t + ')' : ''))
+  }
   lines.push(refText ? 'Reference: ' + refText : 'Reference: (omitted by budget)')
   return lines.join('\n')
 }
@@ -256,8 +268,9 @@ export function renderReferenceTail(items, opts = {}) {
     if (used + skillCost > budget) skillDropped = true
     else { skillBlock = sb; used += skillCost }
   }
-  for (const it of sorted) {
-    const block = renderItemBlock(it, reason)
+  for (let rank = 0; rank < sorted.length; rank++) {
+    const it = sorted[rank]
+    const block = renderItemBlock(it, reason, rank + 1, sorted.length)
     const cost = Buffer.byteLength(block, 'utf8') + 1
     if (used + cost > budget) { dropped.push({ memoryId: it.memoryId, recordDigest: it.recordDigest, reason: 'tail-budget' }); continue }
     blocks.push(block)
@@ -277,7 +290,7 @@ export function renderReferenceTail(items, opts = {}) {
 
 /** §5 packetId:由 activationId+contextVersion+indexVersion+exactDigest 确定。 */
 export function buildPacketId(activationId, contextVersion, memoryIndexVersion, exactDigest) {
-  const parts = ['reference-tail-packet-pre-v1', String(activationId || ''), contextVersion | 0, String(memoryIndexVersion || ''), String(exactDigest || '')]
+  const parts = ['reference-tail-packet-v1', String(activationId || ''), contextVersion | 0, String(memoryIndexVersion || ''), String(exactDigest || '')]
   return PACKET_ID_PREFIX + first32(sha256Str(JSON.stringify(parts)))
 }
 
@@ -391,7 +404,7 @@ export function buildReferenceTailPacketPre(input) {
  */
 export function makeFakeActivationRequestPre(opts = {}) {
   const seed = String(opts.seed || 'fake-seed')
-  const activationId = ACTIVATION_ID_PREFIX + first32(sha256Str('fake-activation-pre-v1\u0000' + seed))
+  const activationId = ACTIVATION_ID_PREFIX + first32(sha256Str('fake-activation-v1\u0000' + seed))
   const records = Array.isArray(opts.records) ? opts.records : []
   const picked = records.slice(0, Math.max(1, Math.min(opts.maxItems || 3, REFERENCE_TAIL_BUDGET_V1.maxCandidates)))
   const candidates = picked.map((rec, i) => ({
@@ -400,6 +413,8 @@ export function makeFakeActivationRequestPre(opts = {}) {
     sourceEpoch: rec.sourceEpoch, sourceVersion: rec.sourceVersion, fileDigest: rec.fileDigest, recordDigest: rec.recordDigest,
     score: typeof rec.score === 'number' ? rec.score : 0.9 - i * 0.05,
     excerpt: rec.excerpt != null ? sanitizeExcerpt(rec.excerpt) : undefined,
+    // C8/I5（2026-09-14）：fixture 也要能构造"非 current"候选，否则注入侧过滤无从测起。
+    status: rec.status || 'current',
   }))
   const now = Number.isFinite(opts.now) ? opts.now : Date.now()
   const ttlSteps = opts.ttlSteps || 2
@@ -409,7 +424,10 @@ export function makeFakeActivationRequestPre(opts = {}) {
     kind: 'activation_request',
     activationId,
     observationId: opts.observationId || ('obs_' + first32(sha256Str('fake-obs\u0000' + seed))),
-    workerEpoch: opts.workerEpoch || 'fake-epoch-pre-v1',
+    // T0-2（2026-09-14）：请求侧可显式给 requestKey（同一次用户请求的稳定标识）。
+    // 缺省为空串——下游对它 fail closed（"没有就不复用"），不会因此误判为同请求。
+    requestKey: opts.requestKey || '',
+    workerEpoch: opts.workerEpoch || 'fake-epoch-v1',
     sessionId: opts.sessionId || '',
     agentId: opts.agentId || '',
     workspaceKey: opts.workspaceKey || '',

package/lib/board-mode.js

@@ -0,0 +1,30 @@
+/**
+ * board-mode-pre —— WB-GRAPH 白板线总开关(2026-09-16, board_mode_v1)。
+ *
+ * 裁定来源: WB-GRAPH-DECISIONS-20260914.md §E + 用户 2026-09-16 凌晨原话:
+ *   「一口气全做完，但是线先别着急接。可以先在设置里，或者在接续面板上设置一个按钮，一键切换旧版和新版。」
+ *
+ * 设计(硬纪律):
+ *  - boardMode = 'legacy'(默认) | 'graph'(新版看板 dsh-graph + sidecar + 遍历工具)。
+ *  - **开关解耦**(用户硬性规则): boardMode 只决定"白板线新能力是否激活",
+ *    不顺带改变任何其他功能行为; legacy 模式下一切行为与 P5 收官时**字节级一致**。
+ *  - graph_* 工具(dsh-graph vendor)与 memory_expand/memory_trace(P3)
+ *    仅在 boardMode='graph' 时注册; P2 sidecar 仅在 'graph' 时写盘。
+ *  - fail closed: 非法值一律按 legacy(旧行为), 绝不猜。
+ */
+
+export const BOARD_MODE_VERSION = 'board_mode_v1'
+export const BOARD_MODES_V1 = Object.freeze(['legacy', 'graph'])
+
+/**
+ * 解析白板模式。非法/缺省 → legacy(旧行为, fail closed)。
+ * @param {string|undefined} raw 配置里的 boardMode 原值
+ * @returns {{mode:'legacy'|'graph', graphEnabled:boolean, source:'default'|'config'|'fallback'}}
+ */
+export function resolveBoardModePre(raw) {
+  const s = String(raw == null ? '' : raw).trim().toLowerCase()
+  if (s === 'graph') return { mode: 'graph', graphEnabled: true, source: 'config' }
+  if (s === 'legacy' || s === '') return { mode: 'legacy', graphEnabled: false, source: s === '' ? 'default' : 'config' }
+  // 非法值: fallback 到 legacy 并留痕(调用方可把 source==='fallback' 记 diag)
+  return { mode: 'legacy', graphEnabled: false, source: 'fallback' }
+}