@a9i5k4/dsh-auto-memory 0.1.29 → 0.1.30

package/lib/intent-clean.js

@@ -0,0 +1,74 @@
+/**
+ * M8 采集侧 intent 清洗(2026-08-30 P1,docs/HANDOFF-M8-M9-M10.md §2 P1)。
+ *
+ * 背景:episode 的 intent 来自 consolidateTurn 取到的「本轮最后一条 user 文本」,而该文本
+ * 在真实运行时常被三种形态污染(已实录于 ~/.dsh/memory/hub/episodes.json):
+ *   ① harness 注入的上下文快照 —— 以 "Current runtime context. This snapshot supersedes…" 开头
+ *   ② 工具回包 —— role 也是 user,但 eventType='tool/result',正文是 JSON 转储
+ *   ③ 行号引用文本 —— 同属工具回包("436: ## 2026-08-25\n437: …")
+ *
+ * 三层修复原本内联在 lib/index.js consolidateTurn 的 for 循环里,只能靠「用户自然对话两轮」
+ * 实机验证,无法回归锁定。抽出为纯函数后,上述真实形态全部变成可重复执行的断言。
+ *
+ * 抽取时发现并修掉的实质缺陷(2026-08-30):
+ *   原第 2 层「正文含 <memory_system> 就整条跳过」会抢在第 3 层之前生效,于是第 3 层的
+ *   快照剥离**永远轮不到**——真人问题一旦与注入快照拼在同一条消息里,整条被丢,intent
+ *   只能退化成上一轮的旧问题。现改为「先剥离块,再看剩下什么」:剥离后为空或只剩
+ *   harness 前缀才判为合成消息,否则剩下的就是真人问题(严格优于原行为:原行为会丢问题,
+ *   新行为只是把问题捞回来;纯快照消息两种行为都跳过)。
+ *
+ * 设计约束:
+ *   - 纯函数、零 IO、零依赖;同输入同输出。
+ *   - 只认 eventType='user/message' 的真人消息(messageOfEvent 只产出
+ *     user/message | assistant/message | tool/result 三类)。
+ * 命名空间:_pre 隔离。UTF-8 无 BOM。
+ */
+
+/** 完整的注入快照块(开闭标签配对)。 */
+const SNAPSHOT_BLOCK_RE = /<memory_system>[\s\S]*?<\/memory_system>/g
+/** harness 合成前缀(剥离块后若只剩这段,说明整条都是注入)。 */
+const RUNTIME_CONTEXT_RE = /^current runtime context\./i
+
+/**
+ * 剥离注入内容,返回剩余的真人文本:
+ *   (a) 完整的 <memory_system>…</memory_system> 块整体移除(可多块);
+ *   (b) 只剩闭合标签(快照被拆条/半截注入)→ 取其后内容;
+ *   (c) 其余原样。
+ */
+export function stripInjectedBlockPre(text) {
+  let s = String(text == null ? '' : text)
+  s = s.replace(SNAPSHOT_BLOCK_RE, '')
+  const marker = '</memory_system>'
+  const idx = s.lastIndexOf(marker)
+  if (idx >= 0) s = s.slice(idx + marker.length)
+  // harness 的 "Current runtime context. …" 导语是整行噪声,且可能出现在任一行
+  // (快照在前真问题在后 / 真问题在前快照在后,两种拼法都要能剥干净)
+  return s.split(/\r?\n/).filter((ln) => !RUNTIME_CONTEXT_RE.test(ln.trim())).join('\n')
+}
+
+/** 合成注入消息识别:剥离注入内容后什么都不剩 → 整条都是注入。 */
+export function isInjectedContextTextPre(text) {
+  return !stripInjectedBlockPre(text).trim()
+}
+
+/**
+ * 从会话消息序列挑选本轮沉淀用的 user/assistant 文本。
+ * 第 1 层:只认 role=user && eventType='user/message'(滤掉工具回包);
+ * 第 2 层:剥离注入块后,空或仅剩 runtime-context 前缀 → 判为合成消息并跳过;
+ * 第 3 层:取**最后一条**真人消息(与原逻辑一致);assistant 取最后一条非空文本。
+ */
+export function pickConsolidationTextPre(messages) {
+  let userText = ''
+  let assistantText = ''
+  for (const m of Array.isArray(messages) ? messages : []) {
+    if (!m || typeof m !== 'object') continue
+    if (m.role === 'user' && m.eventType === 'user/message') {
+      const rest = stripInjectedBlockPre(m.text).trim()
+      if (!rest) continue
+      userText = rest
+    } else if (m.role === 'assistant' && m.text) {
+      assistantText = String(m.text)
+    }
+  }
+  return { userText, assistantText }
+}

package/lib/m4-corpus.js

@@ -0,0 +1,169 @@
+/**
+ * M4-2 Corpus Adapter — SourceCatalog/M3b sidecar 校验/CorpusRegistry(docs/M4-CONTRACT.md §7/§8)。
+ * 纯适配层:输入为受控 source paths 与磁盘 shadow-copy;不接触 live Host、不做 audit、不注入。
+ *
+ * 职责:
+ *   1) buildSourceCatalog({workspaceKey, userMemoryPath, workspaceMemoryPath, todayLogPath}):
+ *      固定顺序三源 catalog(user/workspace/workspace-log),canonical 化,sourceRef 稳定相对引用。
+ *   2) canonicalScopeGuard:sidecar.sourceFile 必须与 catalog canonical 完全一致;
+ *      symlink/reparse 解析真实路径不得逃逸允许根(realpathSync)。
+ *   3) loadCorpusSnapshot(catalog, fsApi):逐源 parseSidecar→stat/read→fileDigest 比对→
+ *      record byte range/digest 校验→CorpusRecord[](legacy/conflict/stale fail closed 记原因);
+ *      memoryIndexVersion(canonical tuples);预算(sources≤3/records≤512/corpusBytes≤64MiB/单文件 5MiB)。
+ *   4) CorpusRegistry:fingerprint(stat size+mtimeMs)缓存;fingerprint 未变化复用 snapshot;
+ *      变化只 reload 受影响 source 并整体替换;completedKeys/recentHits 上限由调用方持有。
+ */
+import { readFileSync, existsSync, statSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import { parseSidecar } from './memory-anchor.js'
+import { memoryIndexVersion as computeIndexVersion, SHADOW_LEXICAL_BUDGET_V1 as BUDGET } from './shadow-retrieval.js'
+
+const sha256Hex = (buf) => createHash('sha256').update(buf).digest('hex')
+const INDEX_MAX_FILE_BYTES = 5 * 1024 * 1024
+
+/** Windows 稳定 canonical:resolve + 正斜杠 + 小写(大小写不敏感 FS)。 */
+export function canonicalize(p) {
+  return path.resolve(String(p == null ? '' : p)).replace(/\\/g, '/').toLowerCase()
+}
+
+/** sourceRef 稳定相对引用(契约 §15.3:audit 只允许这三类前缀)。 */
+function refFor(kind, file) {
+  const base = path.basename(file)
+  if (kind === 'user') return 'user:' + base
+  if (kind === 'workspace-log') return 'workspace-log:' + base
+  return 'workspace:' + base
+}
+
+
+/** §7.2 SourceCatalog:三源固定顺序;canonical 化;scope 授权由调用方受控路径决定。 */
+export function buildSourceCatalog({ workspaceKey, userMemoryPath, workspaceMemoryPath, todayLogPath }) {
+  const entries = []
+  if (userMemoryPath) entries.push({ kind: 'user', scope: 'User', sourceClass: 'user-memory', file: userMemoryPath })
+  if (workspaceMemoryPath) entries.push({ kind: 'workspace', scope: 'Workspace', sourceClass: 'workspace-notes', file: workspaceMemoryPath })
+  if (todayLogPath) entries.push({ kind: 'workspace-log', scope: 'Workspace', sourceClass: 'workspace-log', file: todayLogPath })
+  const sources = entries.map((e) => ({
+    kind: e.kind, scope: e.scope, sourceClass: e.sourceClass,
+    file: path.resolve(e.file),
+    canonicalFile: canonicalize(e.file),
+    sourceRef: refFor(e.kind, e.file),
+    workspaceKey: String(workspaceKey || ''),
+  }))
+  return { workspaceKey: String(workspaceKey || ''), sources }
+}
+
+/**
+ * §7.3 scope guard:sidecar.sourceFile 必须与 catalog canonical 完全一致;
+ * 真实路径(realpath,解析 symlink/reparse/8.3)不得逃逸声明目录。
+ */
+export function canonicalScopeGuard(source, sidecarSourceFile, fsApi = { realpathSync }) {
+  if (canonicalize(sidecarSourceFile) !== canonicalize(source.file)) {
+    return { ok: false, reason: 'source-mismatch' }
+  }
+  let real
+  try { real = canonicalize(fsApi.realpathSync(source.file)) } catch (_) { return { ok: false, reason: 'sidecar-invalid' } }
+  const declaredRoot = canonicalize(path.dirname(path.resolve(source.file)))
+  if (!real.startsWith(declaredRoot)) return { ok: false, reason: 'cross-workspace' }
+  return { ok: true }
+}
+
+// —— IO 抽象(测试注入;默认同步 node:fs)——
+function existsSyncIo(io, p) { return io && io.existsSync ? io.existsSync(p) : existsSync(p) }
+function readFileSyncIo(io, p) { return io && io.readFileSync ? io.readFileSync(p) : readFileSync(p) }
+
+/** §7.3/§8 loader:sidecar→guard→文件 digest→record 校验→CorpusSnapshot(预算 fail closed)。 */
+export function loadCorpusSnapshot(catalog, io = {}, opts = {}) {
+  const sidecarDir = io.sidecarDir
+  const dropped = []
+  const records = []
+  const versionSources = []
+  let loadedSources = 0
+  for (const source of catalog.sources) {
+    const canonHash = sha256Hex(Buffer.from(canonicalize(source.file), 'utf8'))
+    const sp = path.join(sidecarDir, canonHash + '.json')
+    if (!existsSyncIo(io, sp)) { dropped.push({ stage: 'corpus', reason: 'sidecar-missing', sourceRef: source.sourceRef }); continue }
+    let sideText
+    try { sideText = readFileSyncIo(io, sp) } catch (_) { dropped.push({ stage: 'corpus', reason: 'sidecar-invalid', sourceRef: source.sourceRef }); continue }
+    const parsed = parseSidecar(String(sideText))
+    if (!parsed.ok) { dropped.push({ stage: 'corpus', reason: 'sidecar-invalid', sourceRef: source.sourceRef }); continue }
+    const sc = parsed.sidecar
+    const g = canonicalScopeGuard(source, sc.sourceFile)
+    if (!g.ok) { dropped.push({ stage: 'corpus', reason: g.reason, sourceRef: source.sourceRef }); continue }
+    let buf
+    try { buf = readFileSyncIo(io, source.file) } catch (_) { dropped.push({ stage: 'corpus', reason: 'stale-source', sourceRef: source.sourceRef }); continue }
+    if (buf.length > INDEX_MAX_FILE_BYTES) { dropped.push({ stage: 'corpus', reason: 'oversized', sourceRef: source.sourceRef }); continue }
+    const fileDigest = sha256Hex(buf)
+    if (fileDigest !== sc.fileDigest) { dropped.push({ stage: 'corpus', reason: 'stale-source', sourceRef: source.sourceRef }); continue }
+    for (const r of (sc.records || [])) {
+      if (!Number.isInteger(r.byteStart) || !Number.isInteger(r.byteEnd) || r.byteStart < 0 || r.byteEnd > buf.length) {
+        dropped.push({ stage: 'corpus', reason: 'record-stale', memoryId: r.memoryId, sourceRef: source.sourceRef }); continue
+      }
+      if (sha256Hex(buf.subarray(r.byteStart, r.byteEnd)) !== r.recordDigest) {
+        dropped.push({ stage: 'corpus', reason: 'record-stale', memoryId: r.memoryId, sourceRef: source.sourceRef }); continue
+      }
+      records.push({
+        memoryId: r.memoryId, anchorId: r.anchorId,
+        scope: source.scope, sourceClass: source.sourceClass, sourceRef: source.sourceRef,
+        sourceEpoch: sc.sourceEpoch, sourceVersion: sc.sourceVersion,
+        fileDigest: sc.fileDigest, recordDigest: r.recordDigest,
+        lineStart: r.lineStart || 0, lineEnd: r.lineEnd || 0,
+        byteStart: r.byteStart, byteEnd: r.byteEnd,
+        heading: r.heading != null ? r.heading : null,
+        text: buf.toString('utf8', r.byteStart, Math.min(r.byteEnd, r.byteStart + BUDGET.recordScanKiB * 1024)),
+        bytes: r.bytes != null ? r.bytes : (r.byteEnd - r.byteStart),
+      })
+    }
+    loadedSources++
+    versionSources.push({ scope: source.scope, sourceRef: source.sourceRef, sourceEpoch: sc.sourceEpoch, sourceVersion: sc.sourceVersion, fileDigest: sc.fileDigest })
+  }
+  if (loadedSources > BUDGET.sourceFiles) return { ok: false, reason: 'source-budget', dropped }
+  if (records.length > BUDGET.corpusRecords) return { ok: false, reason: 'record-budget', dropped }
+  let totalBytes = 0
+  for (const r of records) totalBytes += Number(r.bytes || 0)
+  if (totalBytes > BUDGET.corpusBytes) return { ok: false, reason: 'corpus-byte-budget', dropped }
+  const miv = computeIndexVersion(versionSources)
+  return {
+    ok: true,
+    snapshot: {
+      memoryIndexVersion: miv,
+      sources: versionSources,
+      records,
+      counts: { sources: loadedSources, records: records.length, legacyConflicts: dropped.filter((d) => d.reason === 'legacy-conflict').length, rawHits: 0, kept: 0, dropped: dropped.length },
+      dropped,
+    },
+    dropped,
+  }
+}
+
+/** §14.3 stat fingerprint(size+mtimeMs)。 */
+export function sourceFingerprint(file, fsApi = {}) {
+  try {
+    const st = (fsApi.statSync || statSync)(file)
+    return st.size + ':' + st.mtimeMs
+  } catch (_) { return null }
+}
+
+/** CorpusRegistry:fingerprint 缓存;未变化复用(零重读),变化整体重建。 */
+export class CorpusRegistry {
+  constructor(opts = {}) { this.sidecarDir = opts.sidecarDir || null; this._cache = new Map() }
+
+  get(catalog) {
+    const key = canonicalize(catalog.workspaceKey || '__all__')
+    const cached = this._cache.get(key)
+    const fingerprints = new Map()
+    const changed = []
+    for (const s of catalog.sources) {
+      const fp = sourceFingerprint(s.file)
+      fingerprints.set(s.canonicalFile, fp)
+      const prevFp = cached && cached.fingerprints.get(s.canonicalFile)
+      if (prevFp !== fp) changed.push(s)
+    }
+    if (cached && changed.length === 0) return { ok: true, snapshot: cached.snapshot, reloaded: [], fromCache: true }
+    const res = loadCorpusSnapshot(catalog, { sidecarDir: this.sidecarDir }, {})
+    if (!res.ok) return res
+    this._cache.set(key, { fingerprints, snapshot: res.snapshot })
+    return { ok: true, snapshot: res.snapshot, reloaded: changed.map((c) => c.sourceRef), fromCache: false }
+  }
+
+  invalidate() { this._cache.clear() }
+}

package/lib/m7-index-sync-host.js

@@ -0,0 +1,194 @@
+/**
+ * M7-8 Host Index Sync Orchestrator(docs/PYTHON-SIDECAR-CONTRACT.md §19.10;修复 live blocker)。
+ *
+ * 根因(M7-8 live Phase E 实证):M7-1 的 index_sync 只实现了 plan/client 层,生产 Host
+ * 从未调用 buildIndexSyncPlansPre/sendIndexSyncPlanPre → Python worker 收不到全库语料,
+ * 无法建库;context_push 的 memoryRefs(top-8 lexical)不足以做语义检索。
+ *
+ * 本模块把授权 corpus snapshot → index_sync begin/page/commit 的编排接进 Host,并保证:
+ *   - 默认关闭零 IO(assoc∧bridge∧pythonBackend∧sink='python' 四门全开才启用);
+ *   - 输入必须是 loadCorpus(paths) 得到的已授权 M4 CorpusSnapshot(绝不自行读文件);
+ *   - 每个 (workspaceRef, scope, memoryIndexVersion, workerEpoch) 最多成功同步一次;
+ *   - worker 重启/epoch 变化 → 重新同步当前 index;
+ *   - 新 memoryIndexVersion latest-wins;旧 in-flight sync abort/cancel;
+ *   - 同一 workspace 的 Workspace/User plans 按确定顺序发送;
+ *   - 任一失败结构化记录,允许下一有效 Segment 重试,绝不向未 ready 的 index 发 context_push;
+ *   - 禁止在每个 Segment 重复全量 sync(成功后缓存 ready identity);
+ *   - dispose 清理 in-flight/ready cache/abort controller,不删除 derived cache。
+ *
+ * 可观察性(最小投影,不泄内容):capturedPathKeys(≤8)、lastSegmentRuntimeKey、
+ * lastSegmentSessionRef、lastDrop{reason,contextVersion,runtimeKey}、readyState。
+ * UTF-8 无 BOM。
+ */
+import { buildIndexSyncPlansPre, sendIndexSyncPlanPre } from './index-sync.js'
+import { workspaceRefOf } from './evidence-store.js'
+
+export const M7_INDEX_SYNC_HOST_POLICY_VERSION = 'm7_index_sync_host_v1'
+const MAX_PATH_KEYS = 8
+const MAX_DROPS = 16
+
+export function createIndexSyncHostPre(opts = {}) {
+  const engine = opts.engine
+  if (!engine) throw new Error('index-sync-host: engine required')
+  const readyCache = new Map()   // key=(wsRef,scope) -> { miv, epoch, at }
+  const inFlight = new Map()     // key=(wsRef,scope) -> { controller, promise, miv }
+  const enabledKeys = new Set()  // 显式 disable 的 key(同一 miv 内不再重试;miv 变化自动解除)
+  const volatileDrops = []       // ≤16 条最小投影(无文本)
+  const stats = { syncsStarted: 0, syncsOk: 0, syncsFailed: 0, skippedCached: 0,
+    epochReset: 0, mivReplaced: 0, aborted: 0, drops: 0, readyHits: 0 }
+
+  function enabled() {
+    return engine.config.associativeMemoryEnabled === true &&
+      engine.config.contextBridgeEnabled === true &&
+      engine.config.pythonBackendEnabled === true &&
+      String(engine.config.contextSinkMode || 'null') === 'python'
+  }
+  function client() { return engine._pythonSidecar || null }
+  function keyOf(wsRef, scope) { return wsRef + '|' + scope }
+  function drop(reason, contextVersion, runtimeKey) {
+    volatileDrops.push({ at: Date.now(), reason, contextVersion, runtimeKey: String(runtimeKey || '').slice(0, 40) })
+    if (volatileDrops.length > MAX_DROPS) volatileDrops.shift()
+    stats.drops++
+  }
+
+  /** 当前 worker epoch(可能未启动);null 表示未启动。 */
+  function currentEpoch() {
+    const c = client()
+    if (!c || typeof c.currentEpoch !== 'function') return null
+    try { return c.currentEpoch() } catch (_) { return null }
+  }
+
+  /**
+   * 使指定 workspace/scope 的 index 就绪(幂等)。返回 {ok, ready, reason}。
+   * - ready=true 表示该 (wsRef,scope,miv,epoch) 已同步过(缓存命中)。
+   * - 新 epoch → 清除该 key 的缓存并重同步(worker 重启后内存态清零)。
+   * - 新 miv → latest-wins:abort 旧 in-flight,替换缓存,重同步。
+   * - 失败不抛,结构化记录,允许重试。
+   */
+  async function ensureIndexReady(snapshot, paths, scope, opts = {}) {
+    const signal = (opts && opts.signal) || undefined
+    const ctxKey = String((opts && opts.runtimeKey) || '')
+    if (!enabled()) return { ok: false, ready: false, reason: 'disabled' }
+    const c = client()
+    if (!c) return { ok: false, ready: false, reason: 'no-client' }
+    if (!snapshot || !snapshot.records || !snapshot.records.length) return { ok: false, ready: false, reason: 'empty-corpus' }
+    const wsRef = workspaceRefOf(paths.workspaceKey)
+    const miv = String(snapshot.memoryIndexVersion || '')
+    if (!miv.startsWith('idx_')) return { ok: false, ready: false, reason: 'bad-miv' }
+    const epoch = currentEpoch()
+    const k = keyOf(wsRef, scope)
+    const cached = readyCache.get(k)
+    // epoch 变化(worker 重启) → 缓存失效,必须重同步
+    if (cached && epoch && cached.epoch !== epoch) {
+      readyCache.delete(k)
+      stats.epochReset++
+      drop('epoch-reset', 0, ctxKey)
+    }
+    // miv 变化 → 旧缓存/旧 in-flight 作废,latest-wins
+    if (cached && cached.miv !== miv) {
+      readyCache.delete(k)
+      stats.mivReplaced++
+      const infl = inFlight.get(k)
+      if (infl) { try { infl.controller.abort() } catch (_) {}; stats.aborted++ }
+      drop('miv-replaced', 0, ctxKey)
+    }
+    if (readyCache.has(k)) { stats.readyHits++; return { ok: true, ready: true, miv, epoch } }
+    if (inFlight.has(k)) {
+      const infl = inFlight.get(k)
+      // 同 key 已在同步中:若 miv 相同则等待;否则 abort 旧的(latest-wins)
+      if (infl.miv === miv) {
+        try { await infl.promise; return infl.result } catch (_) { return { ok: false, ready: false, reason: 'inflight-failed' } }
+      }
+      try { infl.controller.abort() } catch (_) {}
+      stats.aborted++
+      drop('miv-replaced-inflight', 0, ctxKey)
+    }
+    // 构建计划(Workspace→User 固定序;本函数只处理单个 scope 的计划)
+    const built = buildIndexSyncPlansPre({ snapshot, workspaceKey: paths.workspaceKey })
+    if (!built.ok) { drop('plan:' + built.reason, 0, ctxKey); return { ok: false, ready: false, reason: built.reason } }
+    const plan = built.plans.find((p) => p.scope === scope)
+    if (!plan) { drop('no-plan:' + scope, 0, ctxKey); return { ok: false, ready: false, reason: 'no-plan:' + scope } }
+    const controller = new AbortController()
+    const signal2 = signal || controller.signal
+    stats.syncsStarted++
+    // M7-8 live 修复:sync 帧用独立长超时(覆盖 BGE 加载+全量建库),不套 client 默认 5s——
+    // 否则 worker 首次加载/建库期间 begin/page 帧超时→重生成风暴(实测 syncsOk=0 死循环)
+    const syncTimeoutMs = Number((opts && opts.syncTimeoutMs) || 120000)
+    const promise = sendIndexSyncPlanPre(c, plan, { signal: signal2, timeoutMs: syncTimeoutMs })
+      .then((res) => {
+        if (res.ok) {
+          readyCache.set(k, { miv, epoch, at: Date.now() })
+          stats.syncsOk++
+          return { ok: true, ready: true, miv, epoch }
+        }
+        stats.syncsFailed++
+        drop('sync:' + (res.reason || res.phase || 'failed'), 0, ctxKey)
+        return { ok: false, ready: false, reason: (res.reason || res.phase || 'sync-failed') }
+      })
+      .catch((err) => {
+        const aborted = err && err.name === 'AbortError'
+        if (aborted) stats.aborted++
+        else stats.syncsFailed++
+        drop('sync:' + (aborted ? 'aborted' : String(err && err.message || 'error')), 0, ctxKey)
+        return { ok: false, ready: false, reason: aborted ? 'aborted' : 'sync-error' }
+      })
+    const entry = { controller, promise, miv, result: null }
+    entry.result = promise
+    inFlight.set(k, entry)
+    try {
+      const r = await promise
+      if (inFlight.get(k) === entry) inFlight.delete(k)
+      return r
+    } catch (_) {
+      if (inFlight.get(k) === entry) inFlight.delete(k)
+      return { ok: false, ready: false, reason: 'sync-error' }
+    }
+  }
+
+  /** 一次调用同步一个 workspace 的全部 scope(Workspace→User 固定序)。返回逐 scope 结果。 */
+  async function ensureWorkspaceIndexReady(snapshot, paths, opts = {}) {
+    if (!enabled()) return [{ ok: false, ready: false, reason: 'disabled' }]
+    const results = []
+    const scopes = ['Workspace', 'User']
+    for (const scope of scopes) {
+      const has = snapshot.records.some((r) => r.scope === scope)
+      if (!has) continue
+      results.push(await ensureIndexReady(snapshot, paths, scope, opts))
+    }
+    return results
+  }
+
+  function debugView() {
+    if (!enabled()) return { enabled: false }
+    const c = client()
+    return {
+      enabled: true,
+      policyVersion: M7_INDEX_SYNC_HOST_POLICY_VERSION,
+      ready: [...readyCache.entries()].map(([k, v]) => ({ key: k, miv: v.miv, epoch: v.epoch ? v.epoch.slice(0, 12) : null })),
+      inFlightCount: inFlight.size,
+      capturedPathKeys: [...enabledKeys].slice(0, MAX_PATH_KEYS),
+      stats: { ...stats },
+      recentDrops: volatileDrops.slice(-4),
+      epoch: c && typeof c.currentEpoch === 'function' ? (c.currentEpoch() || '').slice(0, 12) : null,
+    }
+  }
+
+  function dispose(reason) {
+    for (const [, infl] of inFlight) { try { infl.controller.abort() } catch (_) {} }
+    inFlight.clear()
+    readyCache.clear()
+    enabledKeys.clear()
+    volatileDrops.length = 0
+    stats.drops = 0
+  }
+
+  return {
+    ensureIndexReady,
+    ensureWorkspaceIndexReady,
+    debugView,
+    dispose,
+    _stats: stats,
+    _readyCacheForTest: readyCache,
+    _inFlightForTest: inFlight,
+  }
+}