dsh-vscode-mode 0.19.2 → 0.20.0

package/src/officialCapture.ts

@@ -0,0 +1,199 @@
+/** Deferred official-event collection; no private snapshot access. @author ddj 2026年10月26号 */
+import { captureState, repairPaths, saveSnapshot } from './reviewDb.js'
+import type { OfficialDiff, OfficialSummary } from './shared/review.js'
+import type { Ctx } from './store.js'
+import { loadBucket } from './store.js'
+import { log } from './log.js'
+
+interface SourceEvent { type: string; seq: number; data: { turn?: number } }
+interface SourceSession { id: string; inheritedEventCount?: number; header?: { cwd?: string } }
+interface SourceService {
+  summary(sessionId: string, seq: number): OfficialSummary | undefined
+  diff(sessionId: string, seq: number, index: number, signal: AbortSignal): Promise<OfficialDiff | undefined>
+}
+interface CaptureTask { sessionId: string; turn: number; seq: number; cwd?: string }
+export interface CaptureDeps {
+  source: () => SourceService | undefined
+  prepare(cwd: string): Promise<void>
+  identity(cwd: string, path: string): Promise<string>
+  persist: typeof saveSnapshot
+  state: typeof captureState
+  report(message: string): void
+  timeoutMs?: number
+  retryMs?: number
+}
+
+/** @public @author ddj 2026年10月26号 @param deps Official source and workspace adapters. @returns Bounded collector with cancellation and deferred event reads. */
+export function createCollector(deps: CaptureDeps) {
+  const waiting: CaptureTask[] = []
+  const pending = new Set<string>()
+  const controller = new AbortController()
+  let active = 0
+  let stopped = false
+  const running = new Set<string>()
+  const tasks = new Set<Promise<void>>()
+
+  /** @private @author ddj 2026年10月26号 @param ms Delay; aborted on unload. @returns Deferred completion, not synchronous observer work. */
+  function pause(ms: number): Promise<void> {
+    return new Promise((resolve) => {
+      /** @private @author ddj 2026年10月26号 Release both timer and listener. */
+      function finish(): void { clearTimeout(timer); controller.signal.removeEventListener('abort', finish); resolve() }
+      const timer = setTimeout(finish, ms)
+      controller.signal.addEventListener('abort', finish, { once: true })
+      if (stopped) finish()
+    })
+  }
+
+  /** @private @author ddj 2026年10月26号 @param task Source identity. @returns Complete payload staged before one database transaction. */
+  async function collect(task: CaptureTask): Promise<void> {
+    await pause(0) // Official append publishes before summary registration.
+    if (stopped) return
+    // The session header may predate cd. Bind the durable inbox only after
+    // reading the official event cwd; header cwd is a gap-report fallback.
+    const source = deps.source()
+    if (!source) throw new Error('官方 workspaceChanges 服务不可用')
+    let summary: OfficialSummary | undefined
+    for (let attempt = 0; attempt < 4 && !stopped; attempt++) {
+      summary = source.summary(task.sessionId, task.seq)
+      if (summary) break
+      await pause(deps.retryMs ?? 100)
+    }
+    if (!summary || stopped) throw new Error('官方事件已公告，但 summary 已失效或尚不可用')
+    // Detach all source aliases before asynchronous work; never resolve against current session cwd.
+    summary = structuredClone(summary)
+    if (summary.turn !== task.turn) throw new Error('官方 summary 轮次与事件不一致')
+    task.cwd = summary.cwd
+    await deps.prepare(summary.cwd)
+    if (stopped) return
+    deps.state(summary.cwd, { ...task, error: '' }, 'queued')
+    try {
+      const files = []
+      for (const [index, file] of summary.files.entries()) {
+        if (stopped) return
+        const signal = AbortSignal.any([controller.signal, AbortSignal.timeout(deps.timeoutMs ?? 10000)])
+        const diff = await readDiff(source, task, index, signal)
+        if (!diff || diff.path !== file.path || diff.display !== file.display) throw new Error('官方文件差异缺失或身份不一致')
+        const identity = await deps.identity(summary.cwd, file.path)
+        files.push({ identity, diff: structuredClone(diff) })
+      }
+      if (!stopped) deps.persist(summary.cwd, { ...task, sourceKind: 'official', capturedAt: new Date().toISOString(), summary, files })
+    } catch (error) {
+      if (!stopped) deps.state(summary.cwd, { ...task, error: String(error) }, 'gap')
+      throw error
+    }
+  }
+
+  /** @private @author ddj 2026年10月26号 Starts at most two independent event reads, with each event's file reads serial. */
+  function drain(): void {
+    while (!stopped && active < 2 && waiting.length) {
+      const index = waiting.findIndex((task) => !running.has(JSON.stringify([task.sessionId, task.turn])))
+      if (index < 0) break
+      const task = waiting.splice(index, 1)[0]
+      const key = JSON.stringify([task.sessionId, task.turn, task.seq])
+      const turnKey = JSON.stringify([task.sessionId, task.turn])
+      active++; running.add(turnKey)
+      const work = collect(task).catch(async (error) => {
+        deps.report(`官方差异采集 ${key}: ${String(error)}`)
+        if (!stopped && task.cwd) {
+          try { await deps.prepare(task.cwd); if (!stopped) deps.state(task.cwd, { ...task, error: String(error) }, 'gap') }
+          catch (failure) { deps.report(`官方缺口落盘失败: ${String(failure)}`) }
+        }
+      }).finally(() => {
+        active--; pending.delete(key); running.delete(turnKey); tasks.delete(work); drain()
+      })
+      tasks.add(work)
+    }
+  }
+
+  /** @public @author ddj 2026年10月26号 @param session Source session. @param event Published event; inherited fork events are excluded. */
+  function enqueue(session: SourceSession, event: SourceEvent): void {
+    if (stopped || event.type !== 'workspace/changes' || !Number.isSafeInteger(event.data?.turn)
+      || !Number.isSafeInteger(event.seq) || event.seq < (session.inheritedEventCount ?? 0)) return
+    const task = { sessionId: session.id, turn: event.data.turn!, seq: event.seq, cwd: session.header?.cwd }
+    const key = JSON.stringify([task.sessionId, task.turn, task.seq])
+    if (pending.has(key)) return
+    pending.add(key); waiting.push(task); drain()
+  }
+
+  /** @public @author ddj 2026年10月26号 @returns Bounded durability checkpoint including work queued while active tasks finish. */
+  async function flush(): Promise<void> {
+    const deadline = Date.now() + (deps.timeoutMs ?? 10000)
+    while (tasks.size && !stopped && Date.now() < deadline) {
+      let timer: ReturnType<typeof setTimeout> | undefined
+      await Promise.race([Promise.all([...tasks]), new Promise<void>((resolve) => { timer = setTimeout(resolve, Math.max(1, deadline - Date.now())) })])
+      clearTimeout(timer)
+    }
+  }
+
+  /** @public @author ddj 2026年10月26号 @returns Bounded drain, then cancel timers and reads; incomplete staging cannot publish. */
+  async function dispose(): Promise<void> {
+    await flush()
+    stopped = true; controller.abort(); waiting.length = 0; pending.clear()
+    // Never await an uncooperative external adapter after the deadline.
+    // Every publish path checks stopped; late completion cannot reopen the database.
+  }
+  return { enqueue, flush, dispose }
+}
+
+/** @private @author ddj 2026年10月26号 @param source Public service. @param task Event. @param index File position. @param signal Cancellation/deadline. @returns A read bounded even if an adapter ignores abort. */
+async function readDiff(source: SourceService, task: CaptureTask, index: number, signal: AbortSignal): Promise<OfficialDiff | undefined> {
+  return new Promise((resolve, reject) => {
+    /** @private @author ddj 2026年10月26号 Propagate timeout or unload. */
+    function aborted(): void { reject(signal.reason) }
+    signal.addEventListener('abort', aborted, { once: true })
+    if (signal.aborted) { aborted(); return }
+    Promise.resolve().then(() => source.diff(task.sessionId, task.seq, index, signal))
+      .then(resolve, reject).finally(() => signal.removeEventListener('abort', aborted))
+  })
+}
+
+/** @public @author ddj 2026年10月26号 @param ctx Host lifecycle owner; services remain optional for older Hosts. */
+export function installCapture(ctx: Ctx): () => Promise<void> {
+  const collector = createCollector({
+    source: () => ctx.get('workspaceChanges'),
+    prepare: async (cwd) => { await loadBucket(ctx, cwd); await repairPaths(cwd, resolvePath) },
+    identity: resolvePath,
+    persist: saveSnapshot, state: captureState, report: (message) => log.warn(message),
+  })
+  // Subscribe first: seed reads must not create a live-event race window.
+  ctx.on('session/event', collector.enqueue)
+  ctx.on('session/created', backfill)
+  ctx.on('session/flush', collector.flush)
+  for (const session of ctx.get('sessions').list()) void backfill(session)
+  return collector.dispose
+
+  /** @private @author ddj 2026年10月27号 @param cwd Source workspace. @param path Official relative path. @returns Backend-owned process path; never stringify opaque targets. @throws Invalid backend path. */
+  async function resolvePath(cwd: string, path: string): Promise<string> {
+    const fs = ctx.get('fs')
+    const target = await fs.resolve(path, { cwd })
+    const processPath = fs.processPath(target)
+    if (typeof processPath !== 'string' || !processPath || processPath === '[object Object]') {
+      throw new Error('官方文件路径解析失败')
+    }
+    return processPath
+  }
+
+  /** @private @author ddj 2026年10月26号 @param session Live session. Only public async reads, excluding inherited records. */
+  async function backfill(session: SourceSession): Promise<void> {
+    const query = ctx.get('sessionQuery')
+    if (!query?.listEvents || !query?.readEvent) {
+      log.warn('官方历史补采不可用：缺少 sessionQuery；后续实时事件仍会采集')
+      return
+    }
+    try {
+      // Repair durable history independently: official summaries do not survive Host restart.
+      // Each saved snapshot resolves against its own cwd, not the current session directory.
+      if (session.header?.cwd) {
+        await loadBucket(ctx, session.header.cwd)
+        await repairPaths(session.header.cwd, resolvePath)
+      }
+      // Semantic search omits structural events; only the raw metadata list contains workspace/changes.
+      const events = await query.listEvents(session.id)
+      for (const event of events) {
+        if (event.type !== 'workspace/changes' || event.seq < (session.inheritedEventCount ?? 0)) continue
+        const window = await query.readEvent({ sessionId: session.id, seq: event.seq })
+        collector.enqueue(session, window.target)
+      }
+    } catch (error) { log.warn('官方历史补采失败：' + String(error)) }
+  }
+}

package/src/reviewDb.ts

@@ -0,0 +1,214 @@
+/** Official history shares the archive connection, but never the legacy callId namespace. @author ddj 2026年10月26号 */
+import { createHash } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import { activeReady, dbFor } from './archiveDb.js'
+import type { CaptureGap, DecideReview, OfficialDiff, ReviewDetail, ReviewItem, ReviewPage, ReviewSnapshot } from './shared/review.js'
+
+type Row = Record<string, string | number | null>
+
+/** @public @author ddj 2026年10月26号 @param cwd Migrated workspace. @returns Schema4 connection; DDL and version change roll back together. */
+export function reviewDb(cwd: string): DatabaseSync {
+  if (!activeReady(cwd)) throw new Error('官方审查要求先完成活跃库迁移')
+  const db = dbFor(cwd)
+  const version = db.prepare("SELECT value FROM metadata WHERE name='schema'").get() as Row
+  if (version.value === '4') return db
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    db.exec(`CREATE TABLE review_snapshots (
+      session_id TEXT NOT NULL, turn INTEGER NOT NULL, seq INTEGER NOT NULL,
+      payload TEXT NOT NULL, digest TEXT NOT NULL, current INTEGER NOT NULL DEFAULT 1,
+      PRIMARY KEY(session_id,turn,seq));
+      CREATE TABLE review_files (
+      id TEXT PRIMARY KEY, session_id TEXT NOT NULL, turn INTEGER NOT NULL, seq INTEGER NOT NULL,
+      identity TEXT NOT NULL, summary TEXT NOT NULL, diff TEXT NOT NULL,
+      decision TEXT NOT NULL DEFAULT 'pending', revision INTEGER NOT NULL DEFAULT 0,
+      current INTEGER NOT NULL DEFAULT 1);
+      CREATE INDEX review_pending ON review_files(current,decision,id);
+      CREATE INDEX review_turn ON review_files(session_id,turn,seq);
+      CREATE TABLE review_capture (
+      session_id TEXT NOT NULL, turn INTEGER NOT NULL, seq INTEGER NOT NULL,
+      state TEXT NOT NULL, error TEXT, PRIMARY KEY(session_id,turn,seq));
+      CREATE TABLE review_ops (
+      operation_id TEXT PRIMARY KEY, request TEXT NOT NULL, state TEXT NOT NULL, result TEXT,
+      evidence TEXT);
+      UPDATE metadata SET value='4' WHERE name='schema';`)
+    db.exec('COMMIT')
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+  return db
+}
+
+/** @private @author ddj 2026年10月26号 @param text Canonical serialized input. @returns Collision-resistant identity. */
+function digest(text: string): string { return createHash('sha256').update(text).digest('hex') }
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param snapshot Complete staged event. @returns False for late versions; commits facts, pointers and capture state atomically. */
+export function saveSnapshot(cwd: string, snapshot: ReviewSnapshot): boolean {
+  const db = reviewDb(cwd)
+  const { sessionId, turn, seq } = snapshot
+  if (snapshot.summary.cwd !== cwd || snapshot.summary.turn !== turn || snapshot.files.length !== snapshot.summary.files.length) throw new Error('官方采集不完整')
+  const identities = new Set(snapshot.files.map((file) => file.identity))
+  if (identities.size !== snapshot.files.length) throw new Error('官方文件身份重复')
+  // capturedAt is acquisition metadata, not part of the immutable source identity.
+  const hash = digest(JSON.stringify({ ...snapshot, capturedAt: '' }))
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    const prior = db.prepare('SELECT digest FROM review_snapshots WHERE session_id=? AND turn=? AND seq=?').get(sessionId, turn, seq) as Row | undefined
+    if (prior && prior.digest !== hash) throw new Error('同一官方事件的内容发生变化')
+    const latest = db.prepare('SELECT MAX(seq) AS seq FROM review_snapshots WHERE session_id=? AND turn=?').get(sessionId, turn) as Row
+    if (prior || (typeof latest.seq === 'number' && latest.seq > seq)) { db.exec('COMMIT'); return false }
+    insertSnapshot(db, snapshot, hash)
+    db.prepare("INSERT INTO review_capture VALUES(?,?,?,'complete',NULL) ON CONFLICT(session_id,turn,seq) DO UPDATE SET state='complete',error=NULL").run(sessionId, turn, seq)
+    db.exec('COMMIT')
+    return true
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+}
+
+/** @public @author ddj 2026年10月27号 @param cwd Workspace. @param resolvePath Backend path adapter. @returns Repairs only historical object-string identities; preserves IDs, decisions and immutable official facts. @throws Resolution or concurrent payload changes. */
+export async function repairPaths(cwd: string, resolvePath: (cwd: string, path: string) => Promise<string>): Promise<void> {
+  const db = reviewDb(cwd)
+  const broken = db.prepare(`SELECT DISTINCT s.* FROM review_snapshots s JOIN review_files f
+    USING(session_id,turn,seq) WHERE f.identity='[object Object]'`).all() as Row[]
+  for (const row of broken) {
+    const snapshot = JSON.parse(String(row.payload)) as ReviewSnapshot
+    for (const file of snapshot.files) {
+      if (file.identity !== '[object Object]') continue
+      file.identity = await resolvePath(snapshot.summary.cwd, file.diff.path)
+      if (!file.identity || file.identity === '[object Object]') throw new Error('官方文件路径修复失败')
+    }
+    if (new Set(snapshot.files.map((file) => file.identity)).size !== snapshot.files.length) throw new Error('官方文件身份重复')
+
+    // All IO is staged before locking; compare the persisted payload to avoid overwriting newer repairs.
+    db.exec('BEGIN IMMEDIATE')
+    try {
+      const current = db.prepare('SELECT payload FROM review_snapshots WHERE session_id=? AND turn=? AND seq=?')
+        .get(snapshot.sessionId, snapshot.turn, snapshot.seq) as Row | undefined
+      if (current?.payload === row.payload) {
+        for (const file of snapshot.files) {
+          db.prepare(`UPDATE review_files SET identity=? WHERE session_id=? AND turn=? AND seq=?
+            AND identity='[object Object]' AND json_extract(diff,'$.path')=?`)
+            .run(file.identity, snapshot.sessionId, snapshot.turn, snapshot.seq, file.diff.path)
+        }
+        db.prepare('UPDATE review_snapshots SET payload=?,digest=? WHERE session_id=? AND turn=? AND seq=?')
+          .run(JSON.stringify(snapshot), digest(JSON.stringify({ ...snapshot, capturedAt: '' })), snapshot.sessionId, snapshot.turn, snapshot.seq)
+      }
+      db.exec('COMMIT')
+    } catch (error) {
+      if (db.isTransaction) db.exec('ROLLBACK')
+      throw error
+    }
+  }
+}
+
+/** @private @author ddj 2026年10月26号 @param db Transaction. @param snapshot Source payload. @param hash Source digest. */
+function insertSnapshot(db: DatabaseSync, snapshot: ReviewSnapshot, hash: string): void {
+  const { sessionId, turn, seq } = snapshot
+  const previous = db.prepare('SELECT identity,diff,decision FROM review_files WHERE session_id=? AND turn=? AND current=1').all(sessionId, turn) as Row[]
+  db.prepare('UPDATE review_snapshots SET current=0 WHERE session_id=? AND turn=?').run(sessionId, turn)
+  db.prepare('UPDATE review_files SET current=0 WHERE session_id=? AND turn=?').run(sessionId, turn)
+  db.prepare('INSERT INTO review_snapshots VALUES(?,?,?,?,?,1)').run(sessionId, turn, seq, JSON.stringify(snapshot), hash)
+  const insert = db.prepare('INSERT INTO review_files VALUES(?,?,?,?,?,?,?,?,0,1)')
+  for (const [index, file] of snapshot.files.entries()) {
+    const encoded = JSON.stringify(file.diff)
+    const unchanged = previous.find((item) => item.identity === file.identity && item.diff === encoded)
+    const id = digest(JSON.stringify([sessionId, turn, seq, file.identity]))
+    insert.run(id, sessionId, turn, seq, file.identity, JSON.stringify(snapshot.summary.files[index]), encoded, unchanged?.decision ?? 'pending')
+  }
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param gap Announced event identity. @param state Durable inbox or explicit failure. */
+export function captureState(cwd: string, gap: CaptureGap, state: 'queued' | 'gap'): void {
+  reviewDb(cwd).prepare(`INSERT INTO review_capture VALUES(?,?,?,?,?) ON CONFLICT(session_id,turn,seq)
+    DO UPDATE SET state=excluded.state,error=excluded.error WHERE review_capture.state<>'complete'`).run(gap.sessionId, gap.turn, gap.seq, state, gap.error)
+}
+
+/** @private @author ddj 2026年10月26号 @param row File and state. @returns Wire-safe summary without hunks. */
+function itemOf(row: Row): ReviewItem {
+  const summary = JSON.parse(String(row.summary))
+  const kind = row.kind ?? (JSON.parse(String(row.diff)) as OfficialDiff).kind
+  return { id: String(row.id), sessionId: String(row.session_id), turn: Number(row.turn), seq: Number(row.seq),
+    ...summary, currentPath: String(row.identity), kind: kind as ReviewItem['kind'], decision: row.decision as ReviewItem['decision'], revision: Number(row.revision), current: row.current === 1 }
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param cursor Page offset. @param history Include withdrawn/decided history. @returns Bounded metadata page; pending across all source sessions/turns. */
+export function reviewPage(cwd: string, cursor = 0, history = false, path?: string): ReviewPage {
+  const db = reviewDb(cwd)
+  const offset = Number.isSafeInteger(cursor) && cursor >= 0 ? cursor : 0
+  const conditions = history ? [] : ["current=1 AND decision='pending'"]
+  if (path !== undefined) conditions.push('identity=?')
+  const clause = conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''
+  const parameters = path === undefined ? [offset] : [path, offset]
+  const rows = db.prepare(`SELECT id,session_id,turn,seq,identity,summary,decision,revision,current,
+    json_extract(diff,'$.kind') AS kind FROM review_files ${clause} ORDER BY rowid DESC LIMIT 51 OFFSET ?`).all(...parameters) as Row[]
+  const count = db.prepare("SELECT COUNT(*) AS n FROM review_files WHERE current=1 AND decision='pending'").get() as Row
+  const gaps = db.prepare("SELECT * FROM review_capture WHERE state<>'complete' ORDER BY seq DESC LIMIT 50").all() as Row[]
+  const capped = db.prepare(`SELECT session_id,turn,seq,json_extract(payload,'$.summary.total') AS total,
+    json_array_length(payload,'$.summary.files') AS listed FROM review_snapshots WHERE current=1
+    AND json_extract(payload,'$.summary.total')>json_array_length(payload,'$.summary.files') LIMIT 50`).all() as Row[]
+  // Navigation is metadata-only and independent of the 50-row patch-history page.
+  const files = db.prepare(`SELECT identity,MIN(json_extract(summary,'$.display')) AS label,COUNT(*) AS n
+    FROM review_files WHERE current=1 AND decision='pending' GROUP BY identity ORDER BY identity`).all() as Row[]
+  const covered = db.prepare('SELECT DISTINCT identity FROM review_files').all() as Row[]
+  return { overview: { files: files.map((row) => ({ sourceKind: 'official', path: String(row.identity), label: String(row.label), pending: Number(row.n) })),
+    coveredPaths: covered.map((row) => String(row.identity)) },
+    items: rows.slice(0, 50).map(itemOf), pending: Number(count.n), nextCursor: rows.length > 50 ? offset + 50 : null,
+    gaps: [
+      ...gaps.map((row) => ({ sessionId: String(row.session_id), turn: Number(row.turn), seq: Number(row.seq), error: String(row.error || '采集中或上次采集被中断') })),
+      ...capped.map((row) => ({ sessionId: String(row.session_id), turn: Number(row.turn), seq: Number(row.seq), error: `官方列表已截断：总计 ${row.total} 个文件，仅提供 ${row.listed} 个` })),
+    ] }
+
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Migrated workspace. @param path Legacy write target. @returns Whether any official version owns the file, including decided history. */
+export function hasOfficial(cwd: string, path: string): boolean {
+  const db = dbFor(cwd)
+  // A read guard must not acquire a migration write lock on legacy-only databases.
+  if (!db.prepare("SELECT 1 FROM sqlite_master WHERE name='review_files' AND type='table'").get()) return false
+  if (/^[A-Za-z]:[\\/]/.test(path)) {
+    return !!db.prepare("SELECT 1 FROM review_files WHERE lower(replace(identity,char(92),'/'))=? LIMIT 1")
+      .get(path.replace(/\\/g, '/').toLowerCase())
+  }
+  return !!db.prepare('SELECT 1 FROM review_files WHERE identity=? LIMIT 1').get(path)
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param id Immutable file identity. @returns Historical patch, not a reconstruction from disk. */
+export function reviewDetail(cwd: string, id: string): ReviewDetail | null {
+  const db = reviewDb(cwd)
+  const row = db.prepare(`SELECT f.*,json_extract(s.payload,'$.capturedAt') AS captured_at FROM review_files f JOIN review_snapshots s
+    USING(session_id,turn,seq) WHERE f.id=?`).get(id) as Row | undefined
+  if (!row) return null
+  return { item: itemOf(row), diff: JSON.parse(String(row.diff)), capturedAt: String(row.captured_at),
+    capability: { keep: row.current === 1 && row.decision === 'pending', undo: false,
+      reason: '官方仅提供差异块，缺少可验证的历史全文及原始字节；拒绝写回已禁用。可标记已审或打开当前文件继续编辑。' } }
+}
+
+/** @public @author ddj 2026年10月26号 @param cwd Workspace. @param request Frozen identity/revision. @returns Idempotent decision; rejection never guesses a target. */
+export function decideReview(cwd: string, request: DecideReview): { revision: number } {
+  const db = reviewDb(cwd)
+  const encoded = JSON.stringify(request)
+  if (!request.operationId || request.operationId.length > 128) throw new Error('operationId 无效')
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    const previous = db.prepare('SELECT request,result FROM review_ops WHERE operation_id=?').get(request.operationId) as Row | undefined
+    if (previous) {
+      if (previous.request !== encoded) throw new Error('operationId 已用于其他请求')
+      db.exec('COMMIT')
+      return JSON.parse(String(previous.result))
+    }
+    if (request.decision !== 'accepted') throw new Error('缺少可信全文证据，禁止拒绝写回')
+    const change = db.prepare(`UPDATE review_files SET decision='accepted',revision=revision+1
+      WHERE id=? AND seq=? AND revision=? AND current=1 AND decision='pending'`).run(request.id, request.seq, request.revision)
+    if (change.changes !== 1) throw new Error('审查版本冲突，请刷新后重试')
+    const result = { revision: request.revision + 1 }
+    db.prepare("INSERT INTO review_ops VALUES(?,?,'committed',?,NULL)").run(request.operationId, encoded, JSON.stringify(result))
+    db.exec('COMMIT')
+    return result
+  } catch (error) {
+    if (db.isTransaction) db.exec('ROLLBACK')
+    throw error
+  }
+}

package/src/reviewRpc.ts

@@ -0,0 +1,33 @@
+/** Session-scoped official review RPC. @author ddj 2026年10月26号 */
+import type { RpcHandlerMap } from './shared/rpc.js'
+import { decideReview, reviewDetail, reviewPage } from './reviewDb.js'
+import { bucketOf, cwdOfSession, sessionOf } from './registry.js'
+import type { Registry } from './registry.js'
+import type { Ctx } from './store.js'
+
+/** @public @author ddj 2026年10月26号 @param ctx Host. @param registry Workspace cache. @returns Handlers resolving workspace from the live authenticated session, never caller cwd. */
+export function reviewHandlers(ctx: Ctx, registry: Registry): Partial<RpcHandlerMap> {
+  /** @private @author ddj 2026年10月26号 @param sessionId Request scope. @returns Migrated workspace, or explicit failure without fallback. */
+  async function workspace(sessionId: string): Promise<string> {
+    const session = sessionOf(ctx, sessionId)
+    const cwd = cwdOfSession(ctx, session)
+    if (!session || !cwd) throw new Error('会话不存在或没有工作区')
+    await bucketOf(registry, ctx, cwd)
+    return cwd
+  }
+  return {
+    'edrv.review.list': async (args) => {
+      const cwd = await workspace(args.sessionId)
+      return { ok: true, page: reviewPage(cwd, args.cursor, args.history, args.path) }
+    },
+    'edrv.review.detail': async (args) => {
+      const cwd = await workspace(args.sessionId)
+      const detail = reviewDetail(cwd, args.id)
+      return detail ? { ok: true, detail } : { ok: false, error: '官方审查记录不存在' }
+    },
+    'edrv.review.decide': async (args) => {
+      const cwd = await workspace(args.sessionId)
+      return { ok: true, ...decideReview(cwd, args) }
+    },
+  }
+}

package/src/rpc.ts

@@ -23,6 +23,7 @@ import { cp, mkdir, readFile, rename, rm, stat, writeFile, readdir } from 'node:
 import { basename, dirname, join } from 'node:path'
 import { archiveEntryFor, markDecision, recordResolved, reconstructOriginal } from './model.js'
 import { clearRevertState, listArchives, pageArchives, readArchives, revertState, setRevertState, startReverts } from './archiveDb.js'
+import { hasOfficial } from './reviewDb.js'
 import { log } from './log.js'
 import type { Registry } from './registry.js'
 import { bucketOf, cwdOfSession, sessionOf } from './registry.js'
@@ -57,6 +58,7 @@ import { patchHasPerfConfig, patchInsertPerfConfig, patchRemovePerfConfig, perfC
 import type { FileVersions } from './fileVersions.js'
 import { settingsDocPath } from './settingsDocPath.js'
 import { createTextPages } from './textPages.js'
+import { reviewHandlers } from './reviewRpc.js'
 
 /** Process-local cursor signer; reads must stay on the Host filesystem capability. */
 const readTextPage = createTextPages()
@@ -239,17 +241,8 @@ async function afterManualSave(
 ): Promise<void> {
   // 手动保存后目录树可能变化（新建/删除文件）：父目录+祖先进失效，后台自愈。
   invalidateIndex(ctx, sc.cwd, path)
-  const bucket = await bucketOf(registry, ctx, sc.cwd)
-  let changed = false
-  for (const rec of bucket.values()) {
-    if (rec.path === path && rec.superseded !== true) { rec.superseded = true; rec.at = new Date().toISOString(); changed = true }
-  }
-  if (changed) {
-    const done: DiffRecord[] = []
-    for (const rec of bucket.values()) if (rec.path === path && rec.superseded) done.push(rec)
-    if (done.length) await archiveRecords(ctx, sc.session, sc.cwd, bucket, done, '被手动编辑覆盖')
-    else await saveBucket(ctx, sc.cwd, bucket, sc.session, { upserts: [...bucket.values()].filter((rec) => rec.path === path), removed: [] })
-  }
+  // Editing disk is not a review decision. Keep all historical pending records;
+  // location checks may report conflict but must not silently accept or archive them.
 }
 
 /**
@@ -288,6 +281,10 @@ async function applyDecisions(
       results.push({ callId: item.callId, ok: false, error: '记录不存在' })
       continue
     }
+    if (hasOfficial(cwd, record.path)) {
+      results.push({ callId: item.callId, ok: false, error: '该文件已有官方审查记录；旧工具记录禁止决策或回滚，请使用官方审查入口' })
+      continue
+    }
     if (record.archived) {
       results.push({ callId: item.callId, ok: false, error: '记录已归档，无法重复决策' })
       continue
@@ -364,8 +361,8 @@ async function applyDecisions(
       // #endregion
       grouped.delete(index)
       try {
-        if (outcome.ok || outcome.stale === true) setRevertState(cwd, record.callId, scope, hunkIndex, 'applied')
-        else if (outcome.error === '找不到该差异块' || outcome.error === '回滚失败：文件不存在'
+        if (outcome.ok) setRevertState(cwd, record.callId, scope, hunkIndex, 'applied')
+        else if (outcome.stale === true || outcome.error === '找不到该差异块' || outcome.error === '回滚失败：文件不存在'
           || outcome.error === '回滚失败：文件过大，无法安全定位') {
           clearRevertState(cwd, record.callId, scope, hunkIndex)
         }
@@ -375,11 +372,8 @@ async function applyDecisions(
         continue
       }
       if (!outcome.ok) {
-        if (scope !== 'hunk' || outcome.stale !== true) {
-          results.push({ callId: item.callId, ok: false, error: outcome.error })
-          continue
-        }
-        revertedStale = true
+        results.push({ callId: item.callId, ok: false, error: outcome.error || '差异已偏移，未修改文件，保留待处理' })
+        continue
       }
     }
     const wasResolved = recordResolved(record)
@@ -595,6 +589,7 @@ export function buildHandlers(
     ...((svnHandlers ?? {}) as RpcHandlerMap),
     // edrv.dap.* 由 createDapRpc 提供（调试会话单例），这里并入。
     ...((dapHandlers ?? {}) as RpcHandlerMap),
+    ...(reviewHandlers(ctx, registry) as RpcHandlerMap),
     'edrv.list': async (args) => {
       // #region debug log
       const start = performance.now()
@@ -945,6 +940,7 @@ export function buildHandlers(
       if (!fs) return { ok: false, error: '缺少 fs' }
       const batch = args.batch
       const bucket = await bucketOf(registry, ctx, sc.cwd)
+      if (hasOfficial(sc.cwd, args.path)) return { ok: false, error: '该文件已有官方审查记录，禁止使用旧版批次回滚覆盖当前文件' }
       try {
         let affected: DiffRecord[] = []
         let beforeRec: DiffRecord | null = null

package/src/shared/review.ts

@@ -0,0 +1,91 @@
+/** Official facts are immutable; review decisions never imply a disk version. @author ddj 2026年10月26号 */
+export interface ChangedFile {
+  path: string
+  display: string
+  added: number
+  deleted: number
+  binary?: true
+  oversized?: true
+}
+export interface ReviewHunk {
+  oldStart: number
+  oldLines: number
+  newStart: number
+  newLines: number
+  lines: string[]
+}
+export type OfficialDiff = { kind: 'text'; path: string; display: string; before: boolean; after: boolean; hunks: ReviewHunk[]; coarse: boolean }
+  | { kind: 'binary' | 'oversized'; path: string; display: string }
+export interface OfficialSummary {
+  turn: number
+  cwd: string
+  files: ChangedFile[]
+  total: number
+  added: number
+  deleted: number
+  snapshot?: { before: string; after: string }
+}
+export interface ReviewSnapshot {
+  sourceKind: 'official'
+  sessionId: string
+  turn: number
+  seq: number
+  capturedAt: string
+  summary: OfficialSummary
+  files: { identity: string; diff: OfficialDiff }[]
+}
+export type ReviewDecision = 'pending' | 'accepted' | 'rejected'
+export interface ReviewItem {
+  id: string
+  sessionId: string
+  turn: number
+  seq: number
+  path: string
+  currentPath: string
+  display: string
+  added: number
+  deleted: number
+  kind: OfficialDiff['kind']
+  decision: ReviewDecision
+  revision: number
+  current: boolean
+}
+export interface ReviewDetail {
+  item: ReviewItem
+  diff: OfficialDiff
+  capturedAt: string
+  capability: { keep: boolean; undo: boolean; reason: string }
+}
+export interface CaptureGap {
+  sessionId: string
+  turn: number
+  seq: number
+  error: string
+}
+export interface ReviewFile {
+  sourceKind: 'official'
+  path: string
+  label: string
+  pending: number
+}
+export interface ReviewOverview {
+  files: ReviewFile[]
+  /** Every official identity, including decided files: never revive legacy actions for them. */
+  coveredPaths: string[]
+}
+export interface ReviewPage {
+  overview?: ReviewOverview
+  items: ReviewItem[]
+  pending: number
+  nextCursor: number | null
+  gaps: CaptureGap[]
+}
+export interface ReviewRequest { sessionId: string }
+export interface DecideReview extends ReviewRequest {
+  id: string
+  seq: number
+  revision: number
+  operationId: string
+  decision: 'accepted' | 'rejected'
+}
+export type ReviewResult<T> = ({ ok: true } & T) | { ok: false; error: string }

package/src/shared/rpc.ts

@@ -25,6 +25,7 @@ import { DAP_ACTIONS } from './dap.js'
 import { appUrl } from './appUrl.js'
 import type { LoggerLevel } from './logger.js'
 import type { SvnViewRequest, SvnViewPayload } from './svnExplorer.js'
+import type { DecideReview, ReviewDetail, ReviewPage, ReviewRequest } from './review.js'
 
 /** webServer 精确路由。 */
 export const RPC_PATH = '/edrv/rpc'
@@ -368,6 +369,9 @@ export interface UiStatePatchInput {
 
 /** 每个方法的请求参数（sessionId 为公共可选字段）。 */
 export interface RpcRequestMap {
+  'edrv.review.list': ReviewRequest & { cursor?: number; history?: boolean; path?: string }
+  'edrv.review.detail': ReviewRequest & { id: string }
+  'edrv.review.decide': DecideReview
   'edrv.list': { sessionId?: string; callIds?: string[]; skipStale?: boolean }
   'edrv.accept': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
   'edrv.reject': { sessionId?: string; callId: string; scope?: RpcScope; hunkIndex?: number }
@@ -537,6 +541,9 @@ export type RpcMethod = keyof RpcRequestMap
 
 /** 每个方法成功（ok:true）时的附加载荷。 */
 export interface RpcOkMap {
+  'edrv.review.list': { page: ReviewPage }
+  'edrv.review.detail': { detail: ReviewDetail }
+  'edrv.review.decide': { revision: number }
   'edrv.list': { records: RecordView[] }
   'edrv.accept': { record: RecordView }
   'edrv.reject': { record: RecordView }