dsh-vscode-mode 0.21.4 → 0.22.0

package/src/pending/decide.ts

@@ -0,0 +1,213 @@
+/**
+ * 待审判定内核：Keep 只推进投影，Revert 才写磁盘；写盘由注入的 writer 完成以便测试零写断言。
+ * @author ddj 2026年10月29号
+ */
+import type { PendingDecide } from '../shared/pendingReview.js'
+import type { ReviewBlock, ReviewBlockState } from '../shared/reviewRegions.js'
+import { reviewBlocks } from '../shared/reviewRegions.js'
+import type { OfficialDiff } from '../shared/review.js'
+import { keepBlock, revertBlock, textDiff } from './hunks.js'
+import type { PendingEntry } from './kernel.js'
+import { applyUpdate, isSettled } from './kernel.js'
+import type { PendingFlags } from './persist.js'
+
+/** 写盘结果：`content` 是读回校验通过后的最终内容，null 表示删除。 */
+export type WriteResult = { ok: true; content: string | null } | { ok: false; reason: string }
+
+/** 写盘能力，由 host 侧实现；纯判定层只调用它一次。 */
+export type WriteBack = (content: string | null) => Promise<WriteResult>
+
+/** 一次判定的输入。 */
+export interface DecideInput {
+  request: PendingDecide
+  entry: PendingEntry
+  flags: PendingFlags
+  blocks: ReviewBlockState[]
+  now: number
+  write: WriteBack
+}
+
+/** 一次判定的输出。 */
+export interface DecideOutcome {
+  ok: boolean
+  reason: string
+  entry: PendingEntry
+  flags: PendingFlags
+  blocks: ReviewBlockState[]
+  /** 是否真正写过磁盘（Keep 恒为 false）。 */
+  wrote: boolean
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 执行一次 Keep/Revert；失败时返回原状态，调用方不得落库。
+ * @param input 判定输入
+ * @returns 判定结果
+ */
+export async function decide(input: DecideInput): Promise<DecideOutcome> {
+  const failed = (reason: string): DecideOutcome => ({
+    ok: false, reason, entry: input.entry, flags: input.flags, blocks: input.blocks, wrote: false,
+  })
+  if (input.request.revision !== input.flags.revision) return failed('revision-mismatch')
+  if (input.flags.oversized) return failed('oversized')
+  if (input.entry.oldText === input.entry.newText) return failed('settled')
+
+  const diff = textDiff(input.entry.path, input.entry.path, input.entry.oldText, input.entry.newText)
+  const targets = pickBlocks(reviewBlocks(diff), input)
+  if (targets === null) return failed('unknown-block')
+  if (input.request.scope !== 'file' && input.request.scope !== 'all' && targets.length === 0) {
+    return failed('no-block')
+  }
+  const isKeep = input.request.decision === 'accepted'
+  const whole = input.request.scope === 'file' || input.request.scope === 'all'
+  return isKeep ? keep(input, targets, whole) : revert(input, targets, whole)
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: Keep：只把目标块或整文件的新内容并入基线，绝不写目标文件。
+ * @param input 判定输入
+ * @param targets 目标块（整文件时为空）
+ * @param whole 是否整文件
+ * @returns 判定结果
+ */
+function keep(input: DecideInput, targets: ReviewBlock[], whole: boolean): DecideOutcome {
+  if (whole) {
+    const entry = applyUpdate(input.entry, { oldText: input.entry.newText }, input.now)
+    return {
+      ok: true, reason: '', entry, wrote: false,
+      flags: { ...input.flags, revision: input.flags.revision + 1 },
+      blocks: markAll(input.blocks, targets, 'accepted'),
+    }
+  }
+  let oldText = input.entry.oldText
+  for (const block of targets) {
+    const next = keepBlock(oldText, block)
+    if (next === null) {
+      return { ok: false, reason: 'ambiguous-block', entry: input.entry, flags: input.flags, blocks: input.blocks, wrote: false }
+    }
+    oldText = next
+  }
+  const entry = applyUpdate(input.entry, { oldText }, input.now)
+  return {
+    ok: true, reason: '', entry, wrote: false,
+    flags: { ...input.flags, revision: input.flags.revision + 1 },
+    blocks: markAll(input.blocks, targets, 'accepted'),
+  }
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: Revert：合成回退内容后交给 writer 写盘并读回，写失败则状态不变。
+ * @param input 判定输入
+ * @param targets 目标块（整文件时为空）
+ * @param whole 是否整文件
+ * @returns 判定结果
+ */
+async function revert(input: DecideInput, targets: ReviewBlock[], whole: boolean): Promise<DecideOutcome> {
+  const failed = (reason: string): DecideOutcome => ({
+    ok: false, reason, entry: input.entry, flags: input.flags, blocks: input.blocks, wrote: false,
+  })
+  const next = whole ? wholeRevert(input.entry) : blockRevert(input.entry, targets)
+  if (next === undefined) return failed('ambiguous-block')
+
+  const written = await input.write(next)
+  if (!written.ok) return failed(written.reason)
+
+  const entry = applyUpdate(input.entry, { newText: written.content ?? '' }, input.now)
+  return {
+    ok: true, reason: '', entry, wrote: true,
+    flags: { ...input.flags, revision: input.flags.revision + 1, missing: written.content === null },
+    blocks: markAll(input.blocks, targets, 'rejected'),
+  }
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 整文件回退目标：基线为"文件不存在"时删除，否则写回基线全文。
+ * @param entry 待审条目
+ * @returns 目标内容，null 表示删除
+ */
+function wholeRevert(entry: PendingEntry): string | null {
+  return entry.earlierVersion === 'none' ? null : entry.oldText
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 块级回退：在最新内容里依次换回目标块，任一不可定位即整体放弃。
+ * @param entry 待审条目
+ * @param targets 目标块
+ * @returns 新内容或 undefined
+ */
+function blockRevert(entry: PendingEntry, targets: ReviewBlock[]): string | null | undefined {
+  let newText = entry.newText
+  for (const block of targets) {
+    const next = revertBlock(newText, block)
+    if (next === null) return undefined
+    newText = next
+  }
+  return newText
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 按请求粒度挑出目标块；块不存在时返回 null 以区分"没有块"。
+ * @param blocks 当前差异块
+ * @param input 判定输入
+ * @returns 目标块，未知块 ID 时为 null
+ */
+function pickBlocks(blocks: ReviewBlock[], input: DecideInput): ReviewBlock[] | null {
+  const scope = input.request.scope
+  if (scope === 'file' || scope === 'all') return []
+  if (scope === 'block') {
+    const block = blocks.find((item) => item.id === input.request.blockId)
+    return block ? [block] : null
+  }
+  const start = input.request.startLine ?? 0
+  const end = input.request.endLine ?? start
+  return blocks.filter((block) => block.newStart <= end && block.newStart + Math.max(block.newLines.length, 1) >= start)
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 把目标块标记为已决定；整文件时把全部块一起标记。
+ * @param states 已存块决定
+ * @param targets 目标块
+ * @param decision 决定
+ * @returns 新的块决定列表
+ */
+function markAll(states: ReviewBlockState[], targets: ReviewBlock[], decision: 'accepted' | 'rejected'): ReviewBlockState[] {
+  const next = states.slice()
+  for (const block of targets) {
+    const at = next.findIndex((state) => state.id === block.id)
+    if (at >= 0) next[at] = { id: block.id, decision }
+    else next.push({ id: block.id, decision })
+  }
+  return next
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 能力口径：Keep 恒可；Revert 受超大/缺失/已解决限制，拒绝原因要能展示。
+ * @param entry 待审条目
+ * @param flags 持久标记
+ * @returns 能力与原因
+ */
+export function capabilityOf(entry: PendingEntry, flags: PendingFlags): { keep: boolean; revert: boolean; reason: string } {
+  if (isSettled(entry)) return { keep: false, revert: false, reason: 'settled' }
+  if (flags.oversized) return { keep: false, revert: false, reason: 'oversized' }
+  if (entry.earlierVersion === 'none' && entry.newText.length === 0) {
+    return { keep: true, revert: false, reason: 'empty-create' }
+  }
+  return { keep: true, revert: true, reason: '' }
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 供详情接口复用的差异构造。
+ * @param entry 待审条目
+ * @returns 官方差异
+ */
+export function diffOf(entry: PendingEntry): OfficialDiff {
+  return textDiff(entry.path, entry.path, entry.oldText, entry.newText)
+}

package/src/pending/hunks.ts

@@ -0,0 +1,241 @@
+/**
+ * 待审差异构造：把两侧全文变成官方视图复用的 hunk，并提供块级 Keep/Revert 的文本合成。
+ * @author ddj 2026年10月29号
+ */
+import type { OfficialDiff, ReviewHunk } from '../shared/review.js'
+import type { ReviewBlock } from '../shared/reviewRegions.js'
+import { logicalLines } from '../shared/lineEndings.js'
+
+/** 每个 hunk 的上下文行数。 */
+const CONTEXT = 3
+/** LCS 单元格上限：超过后退化为整段替换，避免大文件卡死。 */
+const CELL_LIMIT = 1_000_000
+
+/** 一行差异操作。 */
+type LineOp = { kind: ' ' | '-' | '+'; text: string }
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 构造可直接交给官方渲染器的差异；两侧完全相同时返回空 hunk 列表。
+ * @param path 相对路径
+ * @param display 展示名
+ * @param oldText 基线全文
+ * @param newText 当前全文
+ * @returns 文本差异
+ */
+export function textDiff(path: string, display: string, oldText: string, newText: string): OfficialDiff {
+  const hunks = buildHunks(logicalLines(oldText), logicalLines(newText))
+  return { kind: 'text', path, display, before: true, after: true, hunks, coarse: hunks.length > 0 && isCoarse(oldText, newText) }
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 块级 Keep：把该块的新内容写进基线，返回推进后的基线。
+ * @param oldText 当前基线
+ * @param block 目标块
+ * @returns 新基线；块在当前基线中无法唯一定位时返回 null
+ */
+export function keepBlock(oldText: string, block: ReviewBlock): string | null {
+  return spliceBlock(oldText, block.oldLines, block.newLines, block)
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 块级 Revert：把该块在最新内容里换回基线内容，返回换回后的内容。
+ * @param newText 当前内容
+ * @param block 目标块
+ * @returns 新内容；块无法唯一定位时返回 null
+ */
+export function revertBlock(newText: string, block: ReviewBlock): string | null {
+  return spliceBlock(newText, block.newLines, block.oldLines, block)
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 按"上下文 + 目标行"唯一定位后做一次整块替换，定位不唯一就不动。
+ * @param content 目标全文
+ * @param from 要被替换的块内行
+ * @param to 替换成的块内行
+ * @param block 来源块，提供上下文；缺上下文时退化为只看块内行
+ * @returns 新全文或 null
+ */
+function spliceBlock(content: string, from: string[], to: string[], block: ReviewBlock): string | null {
+  if (from.length === 0 && to.length === 0) return null
+  const lines = logicalLines(content)
+  const withContext = locateSpan(lines, [...block.contextBefore, ...from, ...block.contextAfter])
+  if (withContext !== null) {
+    const start = withContext + block.contextBefore.length
+    return spliceAt(lines, start, from.length, to)
+  }
+  const bare = locateSpan(lines, from)
+  return bare === null ? null : spliceAt(lines, bare, from.length, to)
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 在指定偏移处把连续若干行换成另一组行。
+ * @param lines 目标行集合
+ * @param start 起始偏移
+ * @param count 被替换行数
+ * @param to 替换成的行
+ * @returns 新全文
+ */
+function spliceAt(lines: string[], start: number, count: number, to: string[]): string {
+  return [...lines.slice(0, start), ...to, ...lines.slice(start + count)].join('\n')
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 唯一定位一段行；出现多处命中即视为不可定位。
+ * @param lines 目标行集合
+ * @param pattern 待定位行
+ * @returns 唯一偏移或 null
+ */
+function locateSpan(lines: string[], pattern: string[]): number | null {
+  if (pattern.length === 0) return null
+  let at = -1
+  for (let offset = 0; offset + pattern.length <= lines.length; offset++) {
+    if (!pattern.every((text, index) => lines[offset + index] === text)) continue
+    if (at >= 0) return null
+    at = offset
+  }
+  return at >= 0 ? at : null
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 生成带上下文的标准 hunk 列表。
+ * @param oldLines 基线行
+ * @param newLines 当前行
+ * @returns hunk 列表
+ */
+function buildHunks(oldLines: string[], newLines: string[]): ReviewHunk[] {
+  const ops = diffLines(oldLines, newLines)
+  const hunks: ReviewHunk[] = []
+  let index = 0
+  let oldLine = 0
+  let newLine = 0
+  while (index < ops.length) {
+    if (ops[index].kind === ' ') {
+      oldLine++
+      newLine++
+      index++
+      continue
+    }
+    const head = ops.slice(Math.max(0, index - CONTEXT), index)
+    const collected: LineOp[] = []
+    let probe = index
+    while (probe < ops.length) {
+      const op = ops[probe]
+      if (op.kind !== ' ') { collected.push(op); probe++; continue }
+      const rest = ops.slice(probe, probe + CONTEXT * 2 + 1)
+      if (rest.some((item) => item.kind !== ' ')) { collected.push(op); probe++; continue }
+      break
+    }
+    const tail = ops.slice(probe, probe + CONTEXT)
+    const oldStartLine = oldLine - head.length + 1
+    const newStartLine = newLine - head.length + 1
+    hunks.push(makeHunk([...head, ...collected, ...tail], oldStartLine, newStartLine))
+    for (const op of collected) {
+      if (op.kind !== '+') oldLine++
+      if (op.kind !== '-') newLine++
+    }
+    oldLine += head.length + tail.length
+    newLine += head.length + tail.length
+    index = probe + tail.length
+  }
+  return hunks
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 由一段操作装配 hunk。
+ * @param ops 该 hunk 的操作
+ * @param oldStart 基线起始行
+ * @param newStart 当前起始行
+ * @returns hunk
+ */
+function makeHunk(ops: LineOp[], oldStart: number, newStart: number): ReviewHunk {
+  const oldCount = ops.filter((op) => op.kind !== '+').length
+  const newCount = ops.filter((op) => op.kind !== '-').length
+  return { oldStart, oldLines: oldCount, newStart, newLines: newCount, lines: ops.map((op) => op.kind + op.text) }
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 行级差异：先剪公共前后缀，剩余部分在限额内做 LCS，超限按整段替换。
+ * @param oldLines 基线行
+ * @param newLines 当前行
+ * @returns 顺序完整的操作列表
+ */
+function diffLines(oldLines: string[], newLines: string[]): LineOp[] {
+  let head = 0
+  while (head < oldLines.length && head < newLines.length && oldLines[head] === newLines[head]) head++
+  let tail = 0
+  while (tail < oldLines.length - head && tail < newLines.length - head
+    && oldLines[oldLines.length - 1 - tail] === newLines[newLines.length - 1 - tail]) tail++
+  const left = oldLines.slice(head, oldLines.length - tail)
+  const right = newLines.slice(head, newLines.length - tail)
+  const middle = left.length * right.length > CELL_LIMIT ? coarseOps(left, right) : lcsOps(left, right)
+  return [
+    ...oldLines.slice(0, head).map((text) => ({ kind: ' ' as const, text })),
+    ...middle,
+    ...oldLines.slice(oldLines.length - tail).map((text) => ({ kind: ' ' as const, text })),
+  ]
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 超限时的退化口径：整段删除再整段新增，绝不谎报逐行对应。
+ * @param left 基线剩余行
+ * @param right 当前剩余行
+ * @returns 操作列表
+ */
+function coarseOps(left: string[], right: string[]): LineOp[] {
+  return [
+    ...left.map((text) => ({ kind: '-' as const, text })),
+    ...right.map((text) => ({ kind: '+' as const, text })),
+  ]
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 限额内的 LCS 行差异。
+ * @param left 基线剩余行
+ * @param right 当前剩余行
+ * @returns 操作列表
+ */
+function lcsOps(left: string[], right: string[]): LineOp[] {
+  const rows = left.length + 1
+  const cols = right.length + 1
+  const table = new Uint32Array(rows * cols)
+  for (let i = left.length - 1; i >= 0; i--) {
+    for (let j = right.length - 1; j >= 0; j--) {
+      table[i * cols + j] = left[i] === right[j]
+        ? table[(i + 1) * cols + j + 1] + 1
+        : Math.max(table[(i + 1) * cols + j], table[i * cols + j + 1])
+    }
+  }
+  const ops: LineOp[] = []
+  let i = 0
+  let j = 0
+  while (i < left.length && j < right.length) {
+    if (left[i] === right[j]) { ops.push({ kind: ' ', text: left[i] }); i++; j++; continue }
+    if (table[(i + 1) * cols + j] >= table[i * cols + j + 1]) { ops.push({ kind: '-', text: left[i] }); i++ }
+    else { ops.push({ kind: '+', text: right[j] }); j++ }
+  }
+  while (i < left.length) ops.push({ kind: '-', text: left[i++] })
+  while (j < right.length) ops.push({ kind: '+', text: right[j++] })
+  return ops
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 判断这次差异是否触发了大文件退化口径。
+ * @param oldText 基线全文
+ * @param newText 当前全文
+ * @returns 是否粗粒度
+ */
+function isCoarse(oldText: string, newText: string): boolean {
+  return logicalLines(oldText).length * logicalLines(newText).length > CELL_LIMIT
+}

package/src/pending/kernel.ts

@@ -0,0 +1,233 @@
+/**
+ * 待审条目内核：纯状态机，逐条对齐 dsh-diff-approval 的 pending 语义。
+ * 无 IO、无时钟、不改入参；调用方传入 now 与内容，便于测试与复用。
+ * @author ddj 2026年10月29号
+ */
+import type { PendingEarlier, PendingLineage } from '../shared/pendingReview.js'
+
+/** 内存态条目：比展示投影多保存两侧全文。 */
+export interface PendingEntry {
+  id: string
+  path: string
+  earlierVersion: PendingEarlier
+  oldText: string
+  newText: string
+  updatedAt: number
+  unseen?: boolean
+  sessionId: string
+  sessionIds: string[]
+  lineage?: PendingLineage
+}
+
+/** 新建条目的入参。 */
+export interface NewPending {
+  id: string
+  path: string
+  sessionId: string
+  earlierVersion: PendingEarlier
+  oldText: string
+  newText: string
+  updatedAt: number
+  lineage?: PendingLineage
+}
+
+/** 决定后对条目的局部推进；未出现的字段表示不改。 */
+export interface PendingPatch {
+  oldText?: string
+  newText?: string
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 严格比较两侧文本：不做 BOM/行尾归一化，归一化只允许用于展示。
+ * @param left 一侧全文
+ * @param right 另一侧全文
+ * @returns 两者是否逐码元相等
+ */
+export function sameEntryText(left: string, right: string): boolean {
+  return left === right
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 净零判定：基线等于当前内容即为已解决，但条目仍留在列表等待移除。
+ * @param entry 待审条目
+ * @returns 是否已无净差异
+ */
+export function isSettled(entry: PendingEntry): boolean {
+  return sameEntryText(entry.oldText, entry.newText)
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 合并同一身份的两条条目：基线取较早来源，最新内容取较晚来源，会话取并集。
+ * @param earlier 较早记录
+ * @param later 较晚记录
+ * @returns 合并后的新条目
+ */
+export function mergeEntries(earlier: PendingEntry, later: PendingEntry): PendingEntry {
+  const merged: PendingEntry = {
+    ...later,
+    updatedAt: later.updatedAt,
+    sessionIds: unionSessions(earlier, later),
+  }
+  if (later.lineage === undefined && earlier.lineage !== undefined) merged.lineage = earlier.lineage
+  if (earlier.earlierVersion === 'none' && later.earlierVersion === 'none') {
+    merged.earlierVersion = 'none'
+    merged.oldText = earlier.oldText
+    return merged
+  }
+  // 基线一旦有历史版本，Revert 就是写回内容而不是删除文件；创建期的内容成为新基线。
+  merged.earlierVersion = 'file'
+  merged.oldText = earlier.earlierVersion === 'none' ? earlier.newText : earlier.oldText
+  return merged
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 由新建入参构造条目，并把首个会话写进会话集合。
+ * @param input 新建入参
+ * @returns 新条目
+ */
+export function entryFromNew(input: NewPending): PendingEntry {
+  const entry: PendingEntry = {
+    id: input.id,
+    path: input.path,
+    earlierVersion: input.earlierVersion,
+    oldText: input.oldText,
+    newText: input.newText,
+    updatedAt: input.updatedAt,
+    sessionId: input.sessionId,
+    sessionIds: [input.sessionId],
+  }
+  if (input.lineage !== undefined) entry.lineage = input.lineage
+  return entry
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 应用一次决定带来的局部推进：块级 Keep 推进基线，块级 Revert 推进当前内容。
+ * @param entry 待审条目
+ * @param patch 要推进的一侧
+ * @param now 本次更新时间
+ * @returns 新条目；基线被推进时"创建"身份结束
+ */
+export function applyUpdate(entry: PendingEntry, patch: PendingPatch, now: number): PendingEntry {
+  const next: PendingEntry = { ...entry, updatedAt: now }
+  if (patch.oldText !== undefined) {
+    next.oldText = patch.oldText
+    next.earlierVersion = 'file'
+  }
+  if (patch.newText !== undefined) next.newText = patch.newText
+  delete next.unseen
+  return next
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 采纳外部改动：只替换当前内容并标记未读，基线保持不动。
+ * @param entry 待审条目
+ * @param content 磁盘上的最新全文
+ * @param now 本次更新时间
+ * @returns 新条目
+ */
+export function adoptExternal(entry: PendingEntry, content: string, now: number): PendingEntry {
+  return { ...entry, newText: content, updatedAt: now, unseen: true }
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 设置或清除未读圆点。
+ * @param entry 待审条目
+ * @param seen 是否已读
+ * @returns 新条目
+ */
+export function touchSeen(entry: PendingEntry, seen: boolean): PendingEntry {
+  const next: PendingEntry = { ...entry }
+  if (seen) delete next.unseen
+  else next.unseen = true
+  return next
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 撤销重放：条目内容回滚到快照，未读标记保留实时值。
+ * @param entry 快照条目
+ * @param live 实时条目，用于取未读标记
+ * @returns 重放后的新条目
+ */
+export function withUnseen(entry: PendingEntry, live: PendingEntry | undefined): PendingEntry {
+  return touchSeen(entry, live ? live.unseen !== true : entry.unseen !== true)
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 列表排序：按更新时间升序，与上游一致。
+ * @param left 左侧条目
+ * @param right 右侧条目
+ * @returns 比较结果
+ */
+export function byUpdatedAt(left: PendingEntry, right: PendingEntry): number {
+  return left.updatedAt - right.updatedAt
+}
+
+/**
+ * @author ddj 2026年10月29号
+ * @description: 合并两条条目的会话集合并去重，且保证首会话在列。
+ * @param earlier 较早记录
+ * @param later 较晚记录
+ * @returns 去重后的会话集合
+ */
+function unionSessions(earlier: PendingEntry, later: PendingEntry): string[] {
+  const merged: string[] = []
+  for (const sessionId of [earlier.sessionId, ...earlier.sessionIds, later.sessionId, ...later.sessionIds]) {
+    if (sessionId && !merged.includes(sessionId)) merged.push(sessionId)
+  }
+  return merged
+}
+
+/**
+ * 内容版本号分配器：只有内容变化才递增，条目删除后编号不复用。
+ * @author ddj 2026年10月29号
+ */
+export class ContentVersions {
+  /** 已分配编号与快照文本。 */
+  private readonly state = new Map<string, { version: number; text: string }>()
+  /** 下一个可用编号。 */
+  private next = 1
+
+  /**
+   * @author ddj 2026年10月29号
+   * @description: 记录条目当前内容并返回其版本号；内容未变时沿用旧号。
+   * @param id 条目身份
+   * @param text 当前内容
+   * @returns 该条目的版本号
+   */
+  note(id: string, text: string): number {
+    const known = this.state.get(id)
+    if (known && known.text === text) return known.version
+    const version = this.next++
+    this.state.set(id, { version, text })
+    return version
+  }
+
+  /**
+   * @author ddj 2026年10月29号
+   * @description: 查询已分配版本号，供评论锚定校验。
+   * @param id 条目身份
+   * @returns 版本号，未记录时为 undefined
+   */
+  versionOf(id: string): number | undefined {
+    return this.state.get(id)?.version
+  }
+
+  /**
+   * @author ddj 2026年10月29号
+   * @description: 条目离开列表时丢弃其版本号，且不回收编号。
+   * @param id 条目身份
+   * @returns 无
+   */
+  drop(id: string): void {
+    this.state.delete(id)
+  }
+}