dsh-selfnote 0.0.0-stage → 0.12.0

package/lib/capture-run.js

@@ -0,0 +1,178 @@
+/**
+ * P1-B：把「发现」接到写入层。
+ *
+ * 边界（评审定的）：
+ *   - compareCandidate() 只做判定，不碰文件；这里才决定写什么
+ *   - 冲突 = 两条 candidate + 双向 similarTo；已 approved 的一侧只被指向，不被改写
+ *   - 合并 = 只加证据（occurrences / lastObserved / evidence），不动 status
+ *   - 一次事件的所有候选，用一次 writeFacts 原子落盘；写失败就不推游标
+ */
+
+import { alreadyCaptured, candidatesOf, commitObservation, compareCandidate, isDelegatedSession, isUserAuthored, triggersOf } from './capture.js'
+
+/** 从一条 UserMessage 的 content 里抽纯文本（content 可能是字符串或块数组）。 */
+export function textOfEvent(event) {
+  const content = event?.data?.content ?? event?.data?.text ?? ''
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const block of content) {
+    if (block === null || typeof block !== 'object') continue
+    if (block.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+  }
+  return parts.join('\n')
+}
+
+function newId(now, index) {
+  // 加随机段：不同会话之间没有串行化，同一毫秒里两次提交会撞出同一个 id，
+  // 撞了之后 setFactStatus 只改得到先找到的那条，另一条永远采纳不了。
+  const salt = Math.random().toString(36).slice(2, 6)
+  return `auto-${now.getTime().toString(36)}-${salt}-${index}`
+}
+
+/**
+ * 纯规划：给定文本与现有 facts，算出「写完之后 facts 长什么样」。
+ * 不读写任何文件，方便测试。
+ */
+export function planWrites(texts, options = {}) {
+  const facts = (options.facts ?? []).map((fact) => ({ ...fact }))
+  const sessionId = options.sessionId ?? 'unknown'
+  const seq = Number(options.seq ?? 0)
+  const now = options.now instanceof Date ? options.now : new Date()
+  const iso = now.toISOString()
+  const source = `${sessionId}#${seq}`
+
+  const created = []
+  const merged = []
+  const conflicts = []
+
+  texts.forEach((text, index) => {
+    let best = null
+    for (const fact of facts) {
+      if (typeof fact.text !== 'string') continue
+      const verdict = compareCandidate(text, fact.text)
+      if (best === null || verdict.score > best.verdict.score) {
+        best = { fact, verdict }
+      }
+    }
+
+    const action = best?.verdict.action ?? 'new'
+    const target = best?.fact ?? null
+
+    if (action === 'merge' && target !== null && target.status === 'candidate') {
+      target.occurrences = Number(target.occurrences ?? 1) + 1
+      target.lastObserved = iso
+      target.evidence = [...(target.evidence ?? []), source]
+      merged.push(target.id)
+      return
+    }
+
+    const fact = {
+      id: newId(now, index),
+      text,
+      status: 'candidate',
+      tags: [],
+      importance: 1,
+      hitCount: 0,
+      createdAt: iso,
+      updated: iso,
+      captureSource: 'auto',
+      triggers: triggersOf(text),
+      source,
+      occurrences: 1,
+      lastObserved: iso,
+      evidence: [source],
+    }
+
+    if (action === 'merge' && target !== null) {
+      // 命中已采纳的结论：不改它，只让新候选指过去
+      fact.similarTo = [target.id]
+      fact.mergeSuggestion = target.id
+    }
+
+    if (action === 'conflict' && target !== null) {
+      fact.similarTo = [target.id]
+      fact.conflictWith = target.id
+      conflicts.push({ incoming: fact.id, existing: target.id })
+      if (target.status === 'candidate') {
+        target.similarTo = [...(target.similarTo ?? []), fact.id]
+        target.conflictWith = fact.id
+      }
+    }
+
+    facts.push(fact)
+    created.push(fact.id)
+  })
+
+  return { nextFacts: facts, created, merged, conflicts, source }
+}
+
+/**
+ * 处理一条会话事件。
+ *
+ * deps: { readFacts(), writeFacts(facts), now? }
+ * 返回：{ handled: boolean, reason?, plan? }
+ */
+export async function handleEvent(event, deps) {
+  // 委派会话里的一切都不是这个人说的：先按会话粒度挡掉，再谈内容判断
+  if (deps?.delegated === true) return { handled: false, reason: 'delegated-session' }
+  if (!isUserAuthored(event)) return { handled: false, reason: 'not-user-authored' }
+
+  const sessionId = deps.sessionId ?? event?.sessionId ?? event?.data?.session?.id ?? 'unknown'
+  const seq = Number(event?.seq ?? event?.data?.seq)
+  if (!Number.isSafeInteger(seq) || seq < 0) return { handled: false, reason: 'no-seq' }
+
+  const texts = candidatesOf(textOfEvent(event))
+  if (texts.length === 0) {
+    // 没有候选也要推进游标，否则同一条消息下次还会被重新判断
+    await commitObservation({ sessionId, seq }, () => null, {})
+    return { handled: false, reason: 'no-candidate' }
+  }
+
+  // 读 → 改 → 写 必须在同一段同步代码里：中间不留 await，注入时记热度那条路径就插不进来。
+  // 宿主给了 mutateFacts 就用它的跨进程 CAS；老调用方只给 read/write 时，用同样的形状兜一个。
+  const transact =
+    typeof deps.mutateFacts === 'function'
+      ? deps.mutateFacts
+      : (mutate) => {
+          const facts = deps.readFacts()
+          const outcome = mutate(facts)
+          if (outcome?.changed === true) deps.writeFacts(facts)
+          return outcome
+        }
+
+  const plan = await commitObservation({ sessionId, seq, texts }, (observation) => {
+    let written = null
+    let repeated = false
+    const source = `${sessionId}#${seq}`
+    const outcome = transact((facts) => {
+      // 锁外那次判重只是省事：两个进程可能同时通过，进了事务再按最新快照看一遍
+      if (alreadyCaptured(facts, source)) {
+        repeated = true
+        return { changed: false }
+      }
+      const result = planWrites(observation.texts, {
+        facts,
+        sessionId,
+        seq,
+        now: deps.now,
+      })
+      written = result
+      // 一次写入：三份文件里只有 facts 会变，写成功才算提交成功
+      facts.length = 0
+      facts.push(...result.nextFacts)
+      return { changed: true, plan: result }
+    })
+    if (outcome?.error) throw new Error(outcome.error)
+    if (repeated) return { created: [], merged: [], conflicts: [], source, repeated: true }
+    if (written === null) throw new Error('facts 事务没有产出结果')
+    return written
+  }, { facts: deps.readFacts })
+
+  if (plan.ok !== true) return { handled: false, reason: 'commit-failed', error: plan.error }
+  if (plan.skipped !== null) return { handled: false, reason: plan.skipped }
+
+  return { handled: true, plan: plan.written }
+}
+
+export { alreadyCaptured }

package/lib/capture.js

@@ -0,0 +1,433 @@
+/**
+ * P1-A 原型：自动采集的「发现」部分（不做提取模型调用，不做写库）。
+ *
+ * 设计约束（来自评审）：
+ *   - 只发现，不确认：产出永远是 candidate，永远不碰 approved
+ *   - 轻量触发：不满足条件就什么都不做
+ *   - 相似不等于相同：词面相近但方向相反（简洁 / 详细）判冲突，不合并
+ *   - 幂等：按会话 seq 推进游标，同一条消息不会被处理两次
+ *
+ * 修订（第二版）：
+ *   - 采集门槛两步走：先看有没有长期表达，再看是不是在说「对 AI 的要求 / 想让我记住的事」
+ *   - 方向判定改成集合，一句话同时涉及长短与快慢也能发现冲突
+ *   - seq 必须是安全的非负整数；游标文件损坏不再静默从头来，先备份再抛错
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { writeJsonAtomic } from './atomic.js'
+import { memoryRoot } from './memory.js'
+
+/* ------------------------------ 触发 ------------------------------ */
+
+/** 长期偏好 / 明确约束 / 主动纠正 —— 三类才采，普通闲聊不采。 */
+const TRIGGERS = [
+  { id: 'standing', re: /(以后|今后|往后|从现在起|之后都|一直|每次都)/ },
+  { id: 'prohibit', re: /(不要再|别再|不要用|不许|禁止|别用|不要再给|不用再)/ },
+  { id: 'prefer', re: /(我(更)?(喜欢|偏好|习惯|想要)|我讨厌|我受不了|请(你)?(记住|记下))/ },
+  { id: 'correct', re: /(你(刚才|这次)?(说|写|做)错了|不是这样|别这样|应该(先|用)|重来)/ },
+]
+
+/**
+ * 第二道门槛：这句话是不是在说「跟我交互的方式」或「要我记住的事」。
+ *
+ * 只看触发词是不够的 ——「我以后再也不熬夜了」有时间持续性，但不是给我的要求。
+ * 这里用规则白名单，不调模型：P1-A 阶段宁可漏，也不要乱采。
+ */
+const SCOPE_CUE = new RegExp(
+  [
+    // 回答方式
+    '回答', '回复', '解释', '说明', '讲(解|清楚)?', '输出', '格式', '排版', '语气', '称呼', '叫我', '称我',
+    '举例', '示例', '例子', '代码', '注释', '翻译', '中文', '英文', '分点', '列表', '结论', '总结', '步骤',
+    '详细', '简洁', '简短', '长一点', '短一点', '直接', '口语', '正式', '专业',
+    // 对我的要求 / 记忆请求
+    '提醒我', '记住', '记下', '别忘了', '每次(都)?', '一律', '统一',
+  ].join('|'),
+)
+
+const NEGATION = /(不|别|没|勿|禁止|避免|少|勿用)/
+
+/** 方向相反的两组词：词面再像也不能合并。 */
+const DIRECTIONS = [
+  ['简洁', '详细'],
+  ['简短', '详尽'],
+  ['短', '长'],
+  ['快', '慢'],
+  ['少', '多'],
+]
+
+const SENTENCE = /[^。！？!?；;\n]+[。！？!?；;]?/g
+
+/** 判一条用户消息值不值得采。返回命中的触发原因（空数组 = 不采）。 */
+export function triggersOf(text) {
+  const value = String(text ?? '')
+  if (value.trim() === '') return []
+  const hits = []
+  for (const trigger of TRIGGERS) {
+    if (trigger.re.test(value)) hits.push(trigger.id)
+  }
+  return hits
+}
+
+/** 这句话说的是不是「跟 AI 有关的要求 / 希望被记住的事」。 */
+export function hasScope(text) {
+  return SCOPE_CUE.test(String(text ?? ''))
+}
+
+/** 从一条消息里挑出候选句：既命中触发、又落在采集范围内。 */
+export function candidatesOf(text, limit = 3) {
+  const value = String(text ?? '')
+  const out = []
+  for (const sentence of value.match(SENTENCE) ?? []) {
+    const line = sentence.trim()
+    if (line.length < 4 || line.length > 200) continue
+    if (triggersOf(line).length === 0) continue
+    if (!hasScope(line)) continue
+    if (out.includes(line)) continue
+    out.push(line)
+    if (out.length >= limit) break
+  }
+  return out
+}
+
+/* ------------------------------ 去重 ------------------------------ */
+
+function bigrams(text) {
+  const value = String(text ?? '').toLowerCase().replace(/[\s\p{P}]/gu, '')
+  const set = new Set()
+  for (let i = 0; i + 1 < value.length; i += 1) set.add(value.slice(i, i + 2))
+  if (value.length === 1) set.add(value)
+  return set
+}
+
+/** 词面相似度（重叠系数），只作第一层筛选。 */
+export function similarity(a, b) {
+  const left = bigrams(a)
+  const right = bigrams(b)
+  if (left.size === 0 || right.size === 0) return 0
+  let shared = 0
+  for (const gram of left) if (right.has(gram)) shared += 1
+  // 用重叠系数而不是 Jaccard：中文长句稍改几个字，Jaccard 掉得太快
+  return shared / Math.min(left.size, right.size)
+}
+
+/**
+ * 每条话在每个方向组上站哪一边：Map<组序号, 'left'|'right'>。
+ * 组之间互不影响，所以一句话可以同时是「简短」和「慢」。
+ */
+export function directionMap(text) {
+  const value = String(text ?? '')
+  const map = new Map()
+  DIRECTIONS.forEach(([left, right], group) => {
+    const hasLeft = value.includes(left)
+    const hasRight = value.includes(right)
+    if (hasLeft && !hasRight) map.set(group, 'left')
+    if (hasRight && !hasLeft) map.set(group, 'right')
+  })
+  return map
+}
+
+/** 这句话站了哪几边的方向（可能是多个维度，空集合 = 没提）。 */
+export function directionsOf(text) {
+  const value = String(text ?? '')
+  const matched = []
+  for (const [left, right] of DIRECTIONS) {
+    if (value.includes(left)) matched.push(left)
+    if (value.includes(right)) matched.push(right)
+  }
+  // 「简短」已经包含了「短」，别把同一个意思数两遍
+  const kept = matched.filter((word) => !matched.some((other) => other !== word && other.includes(word)))
+  return new Set(kept)
+}
+
+/** 兼容旧调用：返回第一个方向词（没提就是 null）。新代码用 directionsOf。 */
+export function directionOf(text) {
+  const set = directionsOf(text)
+  for (const item of set) return item
+  return null
+}
+
+/**
+ * 两个候选该不该合并。
+ * 相似 + 同向 → 合并（只合并证据，状态各归各）
+ * 相似 + 反向 / 一边有一边没有 → 冲突，不许自动合并
+ */
+export function compareCandidate(incoming, existing) {
+  const score = similarity(incoming, existing)
+  if (score < 0.5) return { action: 'new', score }
+
+  const negA = NEGATION.test(incoming)
+  const negB = NEGATION.test(existing)
+  const mapA = directionMap(incoming)
+  const mapB = directionMap(existing)
+
+  // 同一组上双方都表了态、且方向相反 —— 这是真冲突
+  for (const [group, side] of mapA) {
+    if (mapB.has(group) && mapB.get(group) !== side) return { action: 'conflict', score }
+  }
+  // 一边提了方向、另一边完全没提 —— 也不自动合并
+  const oneSided = (mapA.size === 0) !== (mapB.size === 0)
+  if (negA !== negB || oneSided) return { action: 'conflict', score }
+  return { action: 'merge', score }
+}
+
+/* ------------------------------ 事件判定与提交顺序 ------------------------------ */
+
+/**
+ * 这条事件是不是「用户亲自打的字」。
+ * 两个条件都要满足：事件类型是 user/message，且消息自带 source.kind === 'user'。
+ * 只判其一不够 —— 注入的内容也可能走 user 通道，但 source.kind 不是 user。
+ */
+export function isUserAuthored(event) {
+  if (event === null || typeof event !== 'object') return false
+  if (event.type !== 'user/message') return false
+  const kind = event.data?.source?.kind
+  return kind === 'user'
+}
+
+/**
+ * 这个会话是不是子代理（委派）会话。
+ *
+ * 实测（2026-11-03，会话 8f5832a2…，seq 9）：委派消息也是 user/message + source.kind === 'user'，
+ * 光看事件分不出来 —— 那是父 agent 写的任务书，不是这个人说的话。
+ * 可靠判据在会话头里（SessionHeader）：origin === 'subagent'，且 delegationDepth > 0。
+ * 用会话粒度判断，不用正文标记：别的插件以后往注入里塞什么标记都不影响这里。
+ */
+export function isDelegatedSession(header) {
+  if (header === null || typeof header !== 'object') return false
+  if (header.origin === 'subagent') return true
+  return Number(header.delegationDepth ?? 0) > 0
+}
+
+/** 这条消息里已经有候选落在 facts 里了吗（按 会话#seq 判，重放时用来兜底去重）。 */
+export function alreadyCaptured(facts, source) {
+  // 除了初次写入时记的 source，还要看证据链：合并只追加 evidence、不改 source，
+  // 只看 source 的话，游标保存失败后重放会把同一条消息算成第二次出现，次数无限涨。
+  return (facts ?? []).some(
+    (fact) => fact.source === source || (Array.isArray(fact.evidence) && fact.evidence.includes(source)),
+  )
+}
+
+/**
+ * 提交一次观察：先写候选，成功了才推进游标。
+ *
+ * 顺序不能反 —— 先推进游标再写候选，写失败就等于这条消息永久丢了。
+ * 如果写成功但游标保存失败，下次会重放这一条：此时用 options.facts() 现读一遍
+ * facts（不传就只能靠调用方在 write 里自己判 alreadyCaptured）。
+ *
+ * options.facts: () => facts[]，每次调用都现读，不要传缓存快照。
+ */
+export async function commitObservation(observation, write, options = {}) {
+  const { sessionId, seq } = observation ?? {}
+  if (!sessionId) return { ok: false, error: '缺少 sessionId' }
+  // 只收真数字或纯数字字符串：Number(null) 会变 0，Number('') 也会变 0，这两种必须挡掉
+  const text = typeof seq === 'number' ? String(seq) : typeof seq === 'string' ? seq.trim() : ''
+  const value = text === '' || /^[0-9]+$/.test(text) === false ? NaN : Number(text)
+  if (!Number.isSafeInteger(value)) {
+    return { ok: false, error: 'seq 必须是非负整数：' + String(seq) }
+  }
+
+  // 只跳过「确实处理过」的：游标记着高水位和它下面漏过的空洞，
+  // 迟到的消息落在空洞里就照样处理；真正的重复由下面的 source 判定兜住。
+  if (alreadySeen(sessionId, value)) return { ok: true, skipped: 'cursor' }
+
+  const source = `${sessionId}#${value}`
+  if (typeof options.facts === 'function') {
+    const facts = options.facts()
+    if (alreadyCaptured(facts, source)) {
+      await markSeenLocked(sessionId, value)
+      return { ok: true, skipped: 'source' }
+    }
+  }
+
+  const written = await write(observation)
+  try {
+    await markSeenLocked(sessionId, value)
+  } catch (error) {
+    return { ok: false, written, error: '候选已写入，但游标保存失败：' + String(error?.message ?? error) }
+  }
+  return { ok: true, skipped: null, written }
+}
+
+/* ------------------------------ 游标（幂等） ------------------------------ */
+
+export class CursorCorruptError extends Error {
+  constructor(file, backup) {
+    super(`游标文件损坏，已备份到 ${backup}，请人工确认后再继续：${file}`)
+    this.name = 'CursorCorruptError'
+    this.file = file
+    this.backup = backup
+  }
+}
+
+export function cursorPath() {
+  return join(memoryRoot(), 'capture-cursor.json')
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+/** 每个会话最多记多少个空洞：超过就只留最近的，老空洞干脆当作没处理过（重判一次没害处）。 */
+export const HOLE_WINDOW = 500
+
+/** 游标里一条记录的两种形态归一化；认不出来返回 null（调用方当成损坏）。 */
+export function normalizeCursorEntry(raw) {
+  if (Number.isSafeInteger(raw) && raw >= 0) return { high: raw, holes: [] }
+  if (!isPlainObject(raw)) return null
+  const high = typeof raw.high === 'number' ? raw.high : NaN
+  if (!Number.isSafeInteger(high) || high < 0) return null
+  const holes = Array.isArray(raw.holes)
+    ? raw.holes.filter((item) => Number.isSafeInteger(item) && item >= 0 && item < high)
+    : []
+  return { high, holes: holes.slice(-HOLE_WINDOW) }
+}
+
+function backupBrokenCursor(file) {
+  const backup = `${file}.corrupt-${Date.now()}`
+  try {
+    renameSync(file, backup)
+  } catch {
+    throw new CursorCorruptError(file, '(备份失败)')
+  }
+  throw new CursorCorruptError(file, backup)
+}
+
+/**
+ * 读游标。
+ * - 文件不存在：首次运行，返回 {}
+ * - 结构不对：不是普通对象、或某个会话的值既不是旧的整数也不是新结构 → 同样是损坏
+ *   损坏一律「备份 + 抛错」，不静默从头来（重放历史比停一下更糟）
+ *
+ * 每个会话一条记录，两种形态都认：
+ *   { "<会话>": 12 }                         旧格式：只有高水位
+ *   { "<会话>": { high: 12, holes: [7, 9] } } 新格式：高水位 + 它下面漏过的 seq
+ * 只存高水位是答不出「seq=7 到底处理过没有」的 —— 迟到的消息会被永久丢掉。
+ */
+export function readCursor() {
+  const file = cursorPath()
+  if (!existsSync(file)) return {}
+  const raw = readFileSync(file, 'utf8')
+
+  let data = null
+  try {
+    data = JSON.parse(raw)
+  } catch {
+    backupBrokenCursor(file)
+  }
+  if (!isPlainObject(data)) backupBrokenCursor(file)
+  const normalized = {}
+  for (const [key, value] of Object.entries(data)) {
+    if (key.trim() === '') backupBrokenCursor(file)
+    const entry = normalizeCursorEntry(value)
+    if (entry === null) backupBrokenCursor(file)
+    normalized[key] = entry
+  }
+  return normalized
+}
+
+/**
+ * 这条消息处理过了吗？用 seq 判断，不靠时间戳。
+ *
+ * 判据不是「小于高水位就算处理过」——那会把迟到的消息一起吞掉。
+ * 真正处理过 = 等于/低于高水位，**且不落在空洞里**。
+ */
+export function alreadySeen(sessionId, seq, cursor = readCursor()) {
+  const entry = normalizeCursorEntry(cursor?.[sessionId])
+  // 没记录过就是「还没处理」；用 -1 而不是 0，否则 seq=0 的第一条会被误判成已处理
+  if (entry === null) return false
+  const value = Number(seq)
+  if (!Number.isSafeInteger(value) || value < 0) return false
+  if (value > entry.high) return false
+  return !entry.holes.includes(value)
+}
+
+/* ------------------------------ 两把锁 ------------------------------ */
+
+/** 游标文件的读—改—写必须串起来，否则两个会话并发写会互相覆盖。 */
+let cursorChain = Promise.resolve()
+
+/** 会话处理链：同一会话的事件严格按到达顺序串行，不同会话互不阻塞。 */
+const sessionChains = new Map()
+
+/** 把一段任务排进「游标锁」里执行（全局串行，只保护读改写这一小段）。 */
+export function withCursorLock(task) {
+  const run = cursorChain.then(task, task)
+  cursorChain = run.then(
+    () => undefined,
+    () => undefined,
+  )
+  return run
+}
+
+/** 把一段任务排进某个会话的串行链（会话内保序，没有全局串行）。 */
+export function enqueue(sessionId, task) {
+  const key = String(sessionId ?? '')
+  const previous = sessionChains.get(key) ?? Promise.resolve()
+  const run = previous.then(task, task)
+  const settled = run.then(
+    () => undefined,
+    () => undefined,
+  )
+  sessionChains.set(key, settled)
+  settled.then(() => {
+    if (sessionChains.get(key) === settled) sessionChains.delete(key)
+  })
+  return run
+}
+
+/**
+ * 同步写游标：read → 改 → write 全在一段同步代码里，单个 tick 内不会被别的会话插进来。
+ * 异步路径请用 markSeenLocked()，它会把这小段排进游标锁。
+ *
+ * 三种情况都要记：
+ *   新会话         → 记高水位，并把之前一个窗口内的 seq 全记成空洞（插件可能中途加载，
+ *                    那之前的消息我们确实没处理过；真被重放时靠 source 去重兜底）
+ *   seq 往前跳     → 高水位拔高，中间没见过的 seq 记成空洞（迟到时还要处理）
+ *   迟到的空洞补上 → 从空洞里划掉，高水位不动
+ */
+export function markSeen(sessionId, seq) {
+  const cursor = readCursor()
+  const entry = normalizeCursorEntry(cursor[sessionId])
+  const value = Number(seq)
+  if (!Number.isSafeInteger(value) || value < 0) return cursor
+
+  if (entry === null) {
+    // 第一次见到这个会话：它过去的 seq 我们一条都没处理过（插件可能中途才加载），
+    // 所以把它们记成空洞 —— 真被重放时照样处理，重复由 source 兜住。只留最近一个窗口。
+    const holes = []
+    for (let item = Math.max(0, value - HOLE_WINDOW); item < value; item += 1) holes.push(item)
+    cursor[sessionId] = { high: value, holes }
+  } else if (value > entry.high) {
+    const from = Math.max(entry.high + 1, value - HOLE_WINDOW)
+    const holes = [...entry.holes]
+    for (let item = from; item < value; item += 1) holes.push(item)
+    cursor[sessionId] = { high: value, holes: holes.sort((a, b) => a - b).slice(-HOLE_WINDOW) }
+  } else if (entry.holes.includes(value)) {
+    cursor[sessionId] = { high: entry.high, holes: entry.holes.filter((item) => item !== value) }
+  } else {
+    return cursor
+  }
+
+  mkdirSync(memoryRoot(), { recursive: true })
+  writeJsonAtomic(cursorPath(), cursor)
+  return cursor
+}
+
+/** 某个会话的高水位（没有记录返回 -1）。给体检与测试用，别自己去拆 entries。 */
+export function cursorSeq(cursor, sessionId) {
+  const entry = normalizeCursorEntry(cursor?.[sessionId])
+  return entry === null ? -1 : entry.high
+}
+
+/** 某个会话还欠着多少条没处理（空洞数）。 */
+export function cursorHoles(cursor, sessionId) {
+  const entry = normalizeCursorEntry(cursor?.[sessionId])
+  return entry === null ? 0 : entry.holes.length
+}
+
+/** 异步路径用的写游标：排进游标锁再写，避免跨会话并发覆盖。 */
+export function markSeenLocked(sessionId, seq) {
+  return withCursorLock(() => markSeen(sessionId, seq))
+}