dsh-vscode-mode 0.14.6 → 0.14.7

package/src/shared/svn.ts

@@ -413,6 +413,61 @@ export function svnBadgeTitle(entry: SvnChangeEntry): string {
   return letter + ' ' + SVN_STATUS_LABEL[entry.status]
 }
 
+/** 文件夹子树聚合状态（资源管理器目录徽标数据源）。 */
+export interface SvnFolderAgg {
+  /** 子树内最强子项状态（决胜见 SVN_FOLDER_STATUS_RANK）。 */
+  status: SvnItemStatus
+  /** 子树内变更条目总数（含更深层目录下的）。 */
+  count: number
+}
+
+/**
+ * 文件夹聚合决胜优先级（强→弱）：冲突/障碍/缺失等 danger 态先于常规修改，
+ * 未版本控制最弱；未列出的状态（normal/external/ignored）不参与聚合。
+ */
+export const SVN_FOLDER_STATUS_RANK: Partial<Record<SvnItemStatus, number>> = {
+  conflicted: 90,
+  obstructed: 80,
+  missing: 70,
+  incomplete: 60,
+  deleted: 50,
+  replaced: 40,
+  modified: 30,
+  added: 20,
+  unversioned: 10,
+}
+
+/**
+ * 变更清单 → 目录路径 → 子树聚合状态表（P2-15 资源管理器文件夹徽标）。
+ * svn status 只报告目录自身状态、子项变更不上卷，受版本控制目录因此缺席清单；
+ * 此处对每条变更沿路径拆出全部祖先目录，累计计数并按 SVN_FOLDER_STATUS_RANK
+ * 取最强状态。目录自身被报告（A/?/属性M 等）时调用方以直接条目优先，本表只兜底。
+ * @author ddj 2026年10月09号
+ * @param entries 变更清单（host `svn.changes` 原始条目，路径 `/` 分隔）
+ * @returns 目录相对路径 → 聚合状态（根路径 '' 不入表；入参为空返回空表）
+ */
+export function svnFolderStatusOf(entries: readonly SvnChangeEntry[]): Record<string, SvnFolderAgg> {
+  const result: Record<string, SvnFolderAgg> = {}
+  for (const entry of entries) {
+    if (!isSvnChange(entry)) continue
+    const parts = String(entry.path ?? '').replace(/\\/g, '/').split('/').filter(Boolean)
+    const rank = SVN_FOLDER_STATUS_RANK[entry.status] ?? 0
+    let dir = ''
+    // 最后一段是条目自身，只向上聚合到祖先目录（目录自身的行走直接条目）
+    for (let i = 0; i < parts.length - 1; i++) {
+      dir = dir ? dir + '/' + parts[i] : parts[i]
+      const prev = result[dir]
+      if (!prev) {
+        result[dir] = { status: entry.status, count: 1 }
+        continue
+      }
+      prev.count += 1
+      if (rank > (SVN_FOLDER_STATUS_RANK[prev.status] ?? 0)) prev.status = entry.status
+    }
+  }
+  return result
+}
+
 // --endregion
 
 // --region P2 动作文案与判定

package/src/shared/svnExplorer.ts

@@ -0,0 +1,97 @@
+/** Explorer-only SVN presentation; change-list/menu semantics stay untouched. @author ddj 2026年10月09号 */
+import type { SvnChangeEntry, SvnItemStatus, SvnRemoteOutdatedEntry } from './svn.js'
+import { SVN_FOLDER_STATUS_RANK, SVN_STATUS_LABEL } from './svn.js'
+
+export type SvnIconKind = 'clean' | 'modified' | 'conflict' | 'added' | 'deleted' | 'unversioned' | 'ignored' | 'external'
+export interface SvnExplorerIndex {
+  entries: Map<string, SvnChangeEntry>
+  folders: Map<string, { status: SvnItemStatus; count: number }>
+  truncated: boolean
+}
+export interface SvnExplorerMark { kind: SvnIconKind; title: string }
+export interface SvnViewRow { path: string; isDir: boolean }
+export type SvnRefreshReason = 'read' | 'paths' | 'full' | 'calibrate'
+export interface SvnViewRequest {
+  sessionId?: string; rows: SvnViewRow[]; reason?: SvnRefreshReason; paths?: string[]
+  clientId?: string; eventId?: string; revision?: number; generation?: number
+}
+export interface SvnViewMark { path: string; kind: SvnIconKind | null; count: number; stale: boolean }
+export interface SvnViewPayload {
+  scopeId: string; prefix: string; revision: number; generation: number; observedGeneration: number
+  confirmedAt: number; complete: boolean; refreshing: boolean; scanMs: number; error: string
+  mismatch: boolean; rows: SvnViewMark[]
+}
+const ICON_KIND: Record<SvnItemStatus, SvnIconKind> = {
+  normal: 'clean', modified: 'modified', replaced: 'modified', added: 'added',
+  deleted: 'deleted', missing: 'deleted', incomplete: 'conflict', obstructed: 'conflict',
+  conflicted: 'conflict', unversioned: 'unversioned', ignored: 'ignored', external: 'external',
+}
+
+/** @public @author ddj 2026年10月09号 @param entry Local status. @returns Effective content/property status. */
+export function localStatusOf(entry: SvnChangeEntry): SvnItemStatus {
+  if (entry.props === 'conflicted') return 'conflicted'
+  if (entry.status === 'normal' && entry.props === 'modified') return 'modified'
+  return entry.status
+}
+
+/** @private @author ddj 2026年10月09号 @param path Relative path. @returns Ancestors, excluding self/root. */
+function parentsOf(path: string): string[] {
+  const result: string[] = []
+  let dir = path
+  while (dir.includes('/')) {
+    dir = dir.slice(0, dir.lastIndexOf('/'))
+    result.push(dir)
+  }
+  return result
+}
+
+/** @public @author ddj 2026年10月09号 @param entries Confirmed verbose statuses. @param truncated Incomplete snapshot. @returns Indexed entries and descendant changes. */
+export function explorerIndexOf(entries: readonly SvnChangeEntry[], truncated = false): SvnExplorerIndex {
+  const index: SvnExplorerIndex = { entries: new Map(), folders: new Map(), truncated }
+  for (const entry of entries) {
+    index.entries.set(entry.path, entry)
+    const status = localStatusOf(entry)
+    if (status === 'normal' || status === 'ignored' || status === 'external') continue
+    for (const dir of parentsOf(entry.path)) {
+      const prev = index.folders.get(dir)
+      if (!prev) { index.folders.set(dir, { status, count: 1 }); continue }
+      prev.count++
+      if ((SVN_FOLDER_STATUS_RANK[status] ?? 0) > (SVN_FOLDER_STATUS_RANK[prev.status] ?? 0)) prev.status = status
+    }
+  }
+  return index
+}
+
+/** @public @author ddj 2026年10月09号 @param index Confirmed snapshot. @param path Row path. @param isDir Directory row. @returns Overlay or null; absent entries never imply clean. */
+export function explorerMarkOf(index: SvnExplorerIndex | null, path: string, isDir: boolean): SvnExplorerMark | null {
+  if (!index) return null
+  let entry = index.entries.get(path)
+  if (!entry) {
+    for (const parent of parentsOf(path)) {
+      const ancestor = index.entries.get(parent)
+      if (ancestor?.status === 'ignored' || ancestor?.status === 'unversioned') { entry = ancestor; break }
+    }
+  }
+  let status = entry ? localStatusOf(entry) : null
+  const agg = isDir ? index.folders.get(path) : null
+  if (agg && (!status || (SVN_FOLDER_STATUS_RANK[agg.status] ?? 0) > (SVN_FOLDER_STATUS_RANK[status] ?? 0))) status = agg.status
+  if (!status) return null
+  if (status === 'normal' && (entry?.versioned !== true || (isDir && index.truncated))) return null
+  const title = status === 'normal' ? '本地正常（已受控，未修改；不表示仓库无更新）' : SVN_STATUS_LABEL[status]
+  return { kind: ICON_KIND[status], title: title + (agg ? '；子项 ' + agg.count + ' 处变更' : '') }
+}
+
+/** @public @author ddj 2026年10月09号 @param entries Remote changes. @returns Exact and ancestor update counts. */
+export function remoteIndexOf(entries: readonly SvnRemoteOutdatedEntry[]): Map<string, number> {
+  const result = new Map<string, number>()
+  for (const entry of entries) {
+    for (const path of [entry.path, ...parentsOf(entry.path)]) result.set(path, (result.get(path) ?? 0) + 1)
+  }
+  return result
+}
+
+/** @public @author ddj 2026年10月09号 @param path WC-relative path. @param prefix Session path under WC. @returns Session-relative path or null outside session. */
+export function explorerPathOf(path: string, prefix: string): string | null {
+  if (!prefix || prefix === '.') return path
+  return path.startsWith(prefix + '/') ? path.slice(prefix.length + 1) : null
+}

package/src/store.ts

@@ -6,7 +6,7 @@
 import type { ArchiveBatch, DiffRecord, SidecarData } from './shared/types.js'
 import type { ReadState } from './shared/diff.js'
 import { fingerprint, isNoopHunk, locateHunks, normalizeForCompare, normalizeHunk, preciseHunk } from './shared/diff.js'
-import { archiveEntryFor, normalizeRecord } from './model.js'
+import { archiveEntryFor, findCanceledPairs, findInversePrior, normalizeRecord } from './model.js'
 import { SIDECAR, SIDECAR_ARCHIVE } from './paths.js'
 import { log } from './log.js'
 import { debugRecord } from './debugLog.js'
@@ -246,6 +246,41 @@ export async function autoArchiveStale(ctx: Ctx, session: Session, cwd: string,
   return stale.length
 }
 
+/**
+ * @public
+ * @author ddj 2026年10月10号
+ * 归档整记录精确抵消对；捕获时仅检查新记录，列表维护时检查整个桶。
+ * @param ctx DSH 上下文
+ * @param session 当前会话
+ * @param cwd 工作区
+ * @param bucket 活跃记录桶
+ * @param record 可选的新捕获记录
+ * @returns 本次归档记录数（不是配对数）
+ * @throws 归档失败时恢复内存标志并透传错误，已保存的捕获记录不受影响
+ */
+export async function archiveCanceled(
+  ctx: Ctx, session: Session, cwd: string, bucket: Map<string, DiffRecord>, record?: DiffRecord,
+): Promise<number> {
+  const records = [...bucket.values()]
+  const prior = record ? findInversePrior(records, record) : null
+  const pairs = record ? (prior ? [[prior, record]] : []) : findCanceledPairs(records)
+  const canceled = pairs.flat()
+  if (!canceled.length) return 0
+  const original = canceled.map((rec) => ({ rec, at: rec.at, superseded: rec.superseded }))
+  const at = new Date().toISOString()
+  for (const rec of canceled) { rec.superseded = true; rec.at = at }
+  try {
+    await archiveRecords(ctx, session, cwd, bucket, canceled, '编辑过程自抵消（新增后还原），自动跳过审查')
+  } catch (error) {
+    for (const item of original) {
+      item.rec.superseded = item.superseded
+      item.rec.at = item.at
+    }
+    throw error
+  }
+  return canceled.length
+}
+
 /** 读取归档 sidecar 文本（缺失/失败 → null）。 */
 export async function readArchiveText(ctx: Ctx, cwd: string | null): Promise<string | null> {
   const fs = ctx.get('fs')

package/src/svn.ts

@@ -19,6 +19,12 @@ import { attrOf, numAttrOf, scanXmlTags, textOf, unescapeXml } from './svnXml.js
 import { TEXT_OUTPUT_CAP, batchResultOf, tailOfText, updateResultOf } from './svnText.js'
 import { LOG_CAP, LOG_DEFAULT_LIMIT, SVN_LOG_SHOW_ALL_CAP, parseLogXml, parseSvnInfoRevision } from './svnLog.js'
 import { SvnUpdateJobs } from './svnUpdateJob.js'
+import { EXPLORER_CAP, explorerViewOf, scopeEntriesOf, statusXmlValid, viewArgsValid } from './svnExplorer.js'
+import { ExplorerScopes, explorerKey } from './svnExplorerCache.js'
+import type { ExplorerScan } from './svnExplorerCache.js'
+import type { SvnViewRequest } from './shared/svnExplorer.js'
+import { readStatusPipe } from './svnStatusStream.js'
+import type { StatusPipe } from './svnStatusStream.js'
 import type { UpdateProcess } from './svnUpdateJob.js'
 export { batchResultOf, commitResultOf, updateResultOf } from './svnText.js'
 export { mapRepoPath, parseLogXml } from './svnLog.js'
@@ -245,7 +251,8 @@ export function parseStatusXml(xml: string, cap: number = CHANGES_CAP): { entrie
     if (!pendingPath) continue
     const rawItem = attrOf(hit.attrs, 'item')
     const item = (rawItem || 'modified') as SvnItemStatus
-    const status: SvnItemStatus = KNOWN_ITEM_STATUS.has(item) ? item : 'modified'
+    const status: SvnItemStatus = attrOf(hit.attrs, 'tree-conflicted') === 'true'
+      ? 'conflicted' : (KNOWN_ITEM_STATUS.has(item) ? item : 'modified')
     const path = changePathOf(pendingPath)
     if (!path) { pendingPath = null; continue }
     if (entries.length >= cap) { truncated = true }
@@ -370,13 +377,14 @@ export function parseRemoteStatusXml(
     const repos = /<repos-status\b([^>]*?)\/?>/.exec(match[2])
     if (!repos) continue
     const item = attrOf(repos[1], 'item')
-    if (!item || item === 'none') continue
+    const props = attrOf(repos[1], 'props')
+    if ((!item || item === 'none' || item === 'normal') && props !== 'modified') continue
     // 路径形态双兼容（同 parseSummarizeXml：绝对/相对取决于调用目标形态）
     const rawPath = attrOf(match[1], 'path')
     const rel = relPathOfAbs(rawPath, wcRoot) ?? changePathOf(rawPath)
     if (!rel) continue
     if (outdated.length >= cap) { truncated = true; break }
-    outdated.push({ path: rel, item })
+    outdated.push({ path: rel, item: item && item !== 'none' && item !== 'normal' ? item : 'modified' })
   }
   return { outdated, againstRev, truncated }
 }
@@ -500,6 +508,9 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
   const updateRootCache = new Map<string, { at: number; root: string }>()
   /** 变更清单缓存（键 = 工作副本根；TTL 短，仅合并同一轮 UI 的多处拉取）。 */
   const changesCache = new Map<string, { at: number; value: { entries: SvnChangeEntry[]; truncated: boolean } }>()
+  /** Explorer snapshots are bounded and short-lived; concurrent scans share one subprocess. */
+  const explorerCache = new Map<string, { at: number; entries: SvnChangeEntry[]; truncated: boolean }>()
+  const explorerFlight = new Map<string, Promise<{ entries: SvnChangeEntry[]; truncated: boolean }>>()
   /** 混合通道方案收件箱（key = 工作副本根；覆盖式入箱 + TTL，见 svn.aiPlanSubmit/Pending）。 */
   const planInbox = new Map<string, { plan: SvnAiPlan; dropped: number; at: number }>()
   /** 工作副本根 relative-url 缓存（日志路径映射用；探测失败也缓存空串避免反复 spawn）。 */
@@ -936,7 +947,96 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
     return { ok, count, summary, output: [...notes, ...failures].join('\n') }
   }
 
+  /** @private @author ddj 2026年10月10号 @param root Native WC root. @param prefix Session prefix. @param paths Subtree targets. @returns Existing parent roots, merged with segment boundaries; missing session forces full. */
+  const scopeRootsOf = async (root: string, prefix: string, paths: readonly string[]): Promise<string[]> => {
+    const roots: string[] = []
+    for (const raw of paths) {
+      let path = raw
+      while (path) {
+        try { if ((await stat(join(root, prefix, path))).isDirectory()) break } catch { /* Deleted subtree: climb. */ }
+        path = path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : ''
+      }
+      if (roots.some((parent) => !parent || path === parent || path.startsWith(parent + '/'))) continue
+      for (let i = roots.length - 1; i >= 0; i--) if (!path || roots[i].startsWith(path + '/')) roots.splice(i, 1)
+      roots.push(path)
+    }
+    return roots
+  }
+
+  /** @private @author ddj 2026年10月10号 @param cwd Session directory. @param root WC root. @param roots Bounded subtrees. @param signal Owner disposal. @returns Confirmed local statuses; malformed/pipe-empty output rejects. */
+  const scanExplorer = async (cwd: string, root: string, roots: readonly string[] = [''], signal?: AbortSignal): Promise<ExplorerScan> => {
+    const target = svnPathOf(cwd, root, '')
+    if (target === null) throw new Error('工作区不在 SVN 根目录内')
+    const spawn = subprocess()
+    if (!spawn) throw new Error('缺少 subprocess 服务')
+    const fs = ctx.get('fs') as { resolve?: (p: string, o: object) => Promise<unknown>; processPath?: (t: unknown) => string } | null
+    const realRoot = fs?.resolve && fs?.processPath ? fs.processPath(await fs.resolve(root, {})) : root
+    const validRoots = await scopeRootsOf(realRoot, target, roots)
+    const targets = validRoots.map((path) => {
+      const rel = [target === '.' ? '' : target, path].filter(Boolean).join('/') || '.'
+      return rel.includes('@') ? rel + '@' : rel
+    })
+    const handle = spawn({
+      argv: [settings.svn().svnPath.trim() || SVN_CLI_DEFAULT, '--non-interactive', 'status', '--xml', '--verbose', '--no-ignore', '--', ...targets],
+      cwd: realRoot, stdio: { stdout: 'pipe', stderr: { maxBytes: OUTPUT_CAP }, stdin: 'ignore' }, graceMs: STATUS_GRACE_MS,
+    }) as StatusPipe
+    const parsed = await readStatusPipe(handle, parseStatusXml, EXPLORER_CAP, STATUS_GRACE_MS, signal)
+    return { entries: scopeEntriesOf(parsed.entries, target), truncated: parsed.truncated, roots: validRoots }
+  }
+
+  /** @private @author ddj 2026年10月09号 @param cwd Session directory. @param root WC root. @param force Bypass TTL. @returns Shared bounded scan; old cache entries are evicted. */
+  const explorerOf = async (cwd: string, root: string, force: boolean) => {
+    const pending = explorerFlight.get(cwd)
+    if (pending) return pending
+    const hit = explorerCache.get(cwd)
+    if (!force && hit && now() - hit.at < CHANGES_TTL_MS) return hit
+    const work = scanExplorer(cwd, root)
+    explorerFlight.set(cwd, work)
+    try {
+      const result = await work
+      explorerCache.delete(cwd)
+      if (explorerCache.size >= 2) explorerCache.delete(explorerCache.keys().next().value!)
+      explorerCache.set(cwd, { at: now(), ...result })
+      return result
+    } finally { explorerFlight.delete(cwd) }
+  }
+
+  const explorerScopes = new ExplorerScopes()
+  /** @private @author ddj 2026年10月10号 @param args Validated view projection. @returns Scope-isolated compact evidence; no repository contact. */
+  const viewExplorer = async (args: SvnViewRequest) => {
+    if (!viewArgsValid(args)) return { ok: false as const, error: 'SVN 图标请求无效或超出行数/路径上限' }
+    const sc = await requireSvnSession(ctx, args.sessionId)
+    if ('err' in sc) return { ok: false as const, error: sc.err }
+    const status = await statusOf(sc.cwd)
+    if (!status.managed || !status.wcRoot || !status.svnCli) return { ok: false as const, error: 'SVN 工作副本或命令不可用' }
+    try {
+      const root = status.wcRoot
+      const scopeId = JSON.stringify([explorerKey(root), explorerKey(sc.cwd)])
+      /** @private @author ddj 2026年10月10号 @param roots Scoped subtrees. @param signal Owner disposal. @returns Streamed scan. */
+      const scan = (roots: readonly string[], signal: AbortSignal) => scanExplorer(sc.cwd, root, roots, signal)
+      const queue = explorerScopes.get(scopeId, scan, now)
+      const reason = args.reason ?? 'read'
+      if (reason !== 'read' && (reason !== 'calibrate' || now() - queue.state().confirmedAt > CHANGES_TTL_MS)) {
+        queue.invalidate({ full: reason !== 'paths', paths: args.paths, event: JSON.stringify([args.clientId, args.eventId]) })
+      }
+      await queue.initial()
+      return { ok: true as const, ...explorerViewOf(queue, scopeId, svnPathOf(sc.cwd, root, '') ?? '.', args) }
+    } catch (error) { return { ok: false as const, error: '读取 SVN 图标状态失败：' + String(error) } }
+  }
+
   const handlers = {
+    'svn.explorerView': viewExplorer,
+    /** @public @author ddj 2026年10月09号 @param args Session and refresh flag. @returns Read-only explorer snapshot; no repository contact. */
+    'svn.explorerStatus': async (args: { sessionId?: string; force?: boolean }) => {
+      const sc = await requireSvnSession(ctx, args.sessionId)
+      if ('err' in sc) return { ok: false as const, error: sc.err }
+      const status = await statusOf(sc.cwd)
+      if (!status.managed || !status.wcRoot || !status.svnCli) return { ok: false as const, error: 'SVN 工作副本或命令不可用' }
+      try {
+        const result = await explorerOf(sc.cwd, status.wcRoot, args.force === true)
+        return { ok: true as const, ...result, prefix: svnPathOf(sc.cwd, status.wcRoot, '') ?? '.' }
+      } catch (error) { return { ok: false as const, error: '读取 SVN 图标状态失败：' + String(error) } }
+    },
     'svn.status': async (args: { sessionId?: string; force?: boolean }) => {
       const sc = await requireSvnSession(ctx, args.sessionId)
       if ('err' in sc) return { ok: false as const, error: sc.err }
@@ -1174,12 +1274,14 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       if (!status.svnCli) return { ok: false as const, error: 'svn 命令不可用（可在设置页配置 svn 路径）' }
       try {
         // W2-3：M3 实测 —— 离线/无凭据会长时间挂起，REMOTE_GRACE_MS 短超时是硬约束
-        const argv = ['status', '-u', '--xml']
-        if (rel) argv.push('--', rel)
+        const target = svnPathOf(sc.cwd, status.wcRoot, rel)
+        if (target === null) return { ok: false as const, error: '路径不在 SVN 工作副本内' }
+        const argv = ['status', '-u', '--xml', '--', target]
         const outcome = await runSvn(status.wcRoot, argv, REMOTE_GRACE_MS, SUM_OUTPUT_CAP)
         if (outcome.code !== 0) {
           return { ok: false as const, error: '远端检查失败：' + tailOfText([outcome.stderr, outcome.stdout].filter(Boolean).join('\n')) }
         }
+        if (!statusXmlValid(outcome.stdout)) return { ok: false as const, error: '远端状态输出为空或不完整' }
         return { ok: true as const, ...parseRemoteStatusXml(outcome.stdout, status.wcRoot) }
       } catch (error) {
         return { ok: false as const, error: '远端检查失败：' + String(error) }
@@ -1492,5 +1594,5 @@ export function createSvnRpc(deps: SvnRpcDeps): { handlers: Record<string, unkno
       }
     },
   }
-  return { handlers, dispose: () => { updateJobs.dispose(); updateRootCache.clear() } }
+  return { handlers, dispose: () => { explorerScopes.dispose(); explorerCache.clear(); updateJobs.dispose(); updateRootCache.clear() } }
 }

package/src/svnExplorer.ts

@@ -0,0 +1,56 @@
+/** Bounded verbose status reader for confirmed clean icons. @author ddj 2026年10月09号 */
+import type { SvnChangeEntry } from './shared/svn.js'
+import { explorerPathOf } from './shared/svnExplorer.js'
+import type { SvnViewPayload, SvnViewRequest } from './shared/svnExplorer.js'
+import type { ExplorerQueue } from './svnExplorerCache.js'
+
+/** Covers measured 125415-entry WC while bounding retained RPC objects, not XML bytes. */
+export const EXPLORER_CAP = 250_000
+export const EXPLORER_ROWS = 1000
+
+/** @public @author ddj 2026年10月10号 @param raw Untrusted RPC request. @returns Whether bounded relative row/invalidation paths and tokens are legal. */
+export function viewArgsValid(raw: unknown): raw is SvnViewRequest {
+  if (!raw || typeof raw !== 'object') return false
+  const args = raw as SvnViewRequest
+  if (!Array.isArray(args.rows) || args.rows.length > EXPLORER_ROWS) return false
+  if (args.reason && !['read', 'paths', 'full', 'calibrate'].includes(args.reason)) return false
+  if (args.paths && (!Array.isArray(args.paths) || args.paths.length > 256 || !args.paths.every(viewPathValid))) return false
+  if (!args.rows.every((row) => row && typeof row.isDir === 'boolean' && viewPathValid(row.path))) return false
+  if (args.rows.reduce((bytes, row) => bytes + Buffer.byteLength(JSON.stringify(row.path)) + 80, 0) > 240 * 1024) return false
+  if ([args.clientId, args.eventId].some((id) => id !== undefined && (typeof id !== 'string' || !id || id.length > 128))) return false
+  if (args.reason && args.reason !== 'read' && (!args.clientId || !args.eventId)) return false
+  return [args.revision, args.generation].every((n) => n === undefined || (Number.isSafeInteger(n) && n >= 0))
+}
+/** @private @author ddj 2026年10月10号 @param path Untrusted relative path. @returns No absolute/traversal/control characters; max row size bounds JSON. */
+function viewPathValid(path: unknown): path is string {
+  if (typeof path !== 'string' || path.length > 1024 || /[\x00-\x1f]/.test(path)) return false
+  const normalized = path.replace(/\\/g, '/')
+  return !normalized.startsWith('/') && !/^[A-Za-z]:/.test(normalized) && !normalized.split('/').includes('..')
+}
+
+/** @public @author ddj 2026年10月10号 @param queue Scope-owned index. @param scopeId Canonical scope. @param prefix WC prefix. @param args Rows and consistency token. @returns Compact rows; page mismatch returns no mixed-version data. */
+export function explorerViewOf(queue: ExplorerQueue, scopeId: string, prefix: string, args: SvnViewRequest): SvnViewPayload {
+  const state = queue.state()
+  const mismatch = (args.revision !== undefined && args.revision !== state.revision)
+    || (args.generation !== undefined && args.generation !== state.generation)
+  const rows = mismatch ? [] : args.rows.map((row) => {
+    const { mark, count } = queue.data.mark(row.path, row.isDir)
+    return { path: row.path, kind: mark?.kind ?? null, count, stale: queue.stale(row.path, row.isDir) }
+  })
+  return { scopeId, prefix, ...state, mismatch, rows }
+}
+
+/** @public @author ddj 2026年10月09号 @param xml Collected CLI output. @returns True only for a complete status document. */
+export function statusXmlValid(xml: string): boolean {
+  return /^\s*(?:<\?xml[^>]*>\s*)?<status(?:\s[^>]*)?>/.test(xml) && /<\/status>\s*$/.test(xml)
+}
+
+/** @public @author ddj 2026年10月09号 @param entries WC-relative statuses. @param prefix Session prefix. @returns Session-relative subset. */
+export function scopeEntriesOf(entries: readonly SvnChangeEntry[], prefix: string): SvnChangeEntry[] {
+  const scoped: SvnChangeEntry[] = []
+  for (const entry of entries) {
+    const path = explorerPathOf(entry.path, prefix)
+    if (path !== null) scoped.push({ ...entry, path })
+  }
+  return scoped
+}