dsh-skill-hub 0.3.8 → 0.3.10

package/src/index.ts

@@ -19,7 +19,7 @@ import type {} from '@deepseek-ai/dsh-settings'
 import { HUB_CONFIG_DEFAULTS, HEX_COLOR_RE, type HubConfig, type HubSettingsValue } from './protocol.ts'
 import { SkillHubProvider } from './provider.ts'
 import { makeRoutes } from './routes.ts'
-import { createSkillStatsReader, type SkillStatsReader } from './stats.ts'
+import { createSkillStatsReader, asPersistenceSeam, type SessionPersistenceLike, type SessionQueryLike, type SkillStatsReader } from './stats.ts'
 import { SkillHubStore } from './store.ts'
 import { cleanupLeftoverImportDirs, setGithubToken } from './repo.ts'
 import { dshHome } from './store.ts'
@@ -252,13 +252,34 @@ export function apply(ctx: Context, config?: Config): void {
   // re-registers the routes with the reader attached (mirrors the optional
   // stats wiring — no sessionQuery service ever mounted means none of this
   // runs).
-  ctx.inject(['sessionQuery'], (sctx) => {
-    // 恢复 sidecar 里的增量扫描检查点后再建 reader（异步、不阻塞注入回调）：
-    // 重启后无需重新解压全部历史日志；每次扫描完都落盘（含上次总数），所以
-    // 重启后面板秒出旧数、后台重扫。扫描间隔与滚动窗口都从设置命名空间
-    // 实时读取——卡片里改完即生效，无需重启。
+  //
+  // Read-path preference: the host's sessionPersistence seam serves raw stored
+  // logs (decompress + parse only — no Session restore/validation, the host
+  // cost that OOMed large histories, see issue #7), with the query seam
+  // covering live sessions. Without a persistence service the reader falls
+  // back to sequential query reads. Scans are strictly lazy: the first one
+  // starts on the panel's first /stats poll, never at plugin startup (a
+  // headless boot with no browser must not pay for statistics nobody reads).
+  //
+  // Mount ordering between the two host services is not guaranteed, so the
+  // reader is (re-)built generation-guarded: a query-only reader wires
+  // immediately, and a later-arriving persistence service upgrades it to the
+  // cold path. A superseded build never assigns.
+  let statsQuery: SessionQueryLike | undefined
+  let statsPersistence: SessionPersistenceLike | undefined
+  let statsGeneration = 0
+  const wireStats = (): void => {
+    const query = statsQuery
+    if (query === undefined) return
+    const generation = ++statsGeneration
+    const cold = statsPersistence
     void (async () => {
+      // 恢复 sidecar 里的增量扫描检查点后再建 reader（异步、不阻塞）：
+      // 重启后无需重新解压全部历史日志；每次扫描完都落盘（含上次总数），所以
+      // 重启后面板秒出旧数、后台重扫。扫描间隔与滚动窗口都从设置命名空间
+      // 实时读取——卡片里改完即生效，无需重启。
       const saved = await store.getSkillStatsState().catch(() => undefined)
+      if (generation !== statsGeneration) return
       const scanMinutes = (): number => {
         const value = current().statsScanMinutes
         return typeof value === 'number' && value >= 1 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsScanMinutes
@@ -267,21 +288,61 @@ export function apply(ctx: Context, config?: Config): void {
         const value = current().statsWindowDays
         return typeof value === 'number' && value >= 0 ? Math.floor(value) : HUB_CONFIG_DEFAULTS.statsWindowDays
       }
-      const reader = createSkillStatsReader(sctx.sessionQuery, () => scanMinutes() * 60_000, {
+      const reader = createSkillStatsReader(query, () => scanMinutes() * 60_000, {
         checkpoint: saved,
         windowDays,
+        ...(cold === undefined ? {} : {
+          persistence: cold,
+          listLiveIds: async () => {
+            try {
+              const records = await query.listSessions()
+              return records.filter((record) => (record as { live?: unknown }).live === true).map((record) => record.header.id)
+            } catch {
+              return []
+            }
+          },
+          readLiveSession: async (id) => {
+            try {
+              return { events: (await query.readSession(id)).events }
+            } catch {
+              return undefined
+            }
+          },
+        }),
         onCheckpoint: (next) => {
           void store.saveSkillStatsState(next).catch((error) => {
             ctx.logger.warn('[dsh-skill-hub] persisting skill-stats checkpoint failed', error)
           })
         },
       })
+      if (generation !== statsGeneration) return
+      ctx.logger.info(`[dsh-skill-hub] stats seam: ${cold === undefined ? 'session-query (fallback)' : 'session-persistence (cold)'}`)
       stats = reader
       sync()
-      // 冷启动预热：检查点无总数时，全量扫描（数十 MB 会话日志）在启动时就
-      // 开始，而不是等面板第一次打开才起跑；有总数时这次调用命中内存缓存，
-      // 开销可忽略。失败由 reader 内部吞掉（保留旧总数），不影响启动。
-      void reader()
     })()
+  }
+  ctx.inject(['sessionQuery'], (sctx) => {
+    statsQuery = sctx.sessionQuery
+    wireStats()
+    // The persistence service may mount after the query service: upgrade the
+    // reader when it arrives (no-op when it never does).
+    sctx.inject(['sessionPersistence'] as unknown as ['sessionQuery'], (pctx) => {
+      void (async () => {
+        const raw = (pctx as unknown as { sessionPersistence?: unknown }).sessionPersistence
+        const seam = asPersistenceSeam(raw)
+        if (seam === undefined) {
+          ctx.logger.warn('[dsh-skill-hub] sessionPersistence shape mismatch, staying on query fallback')
+          return
+        }
+        try {
+          await seam.list() // probe: headers only, must succeed before trusting the cold path
+        } catch (error) {
+          ctx.logger.warn('[dsh-skill-hub] persistence seam probe failed, staying on query fallback', error)
+          return
+        }
+        statsPersistence = seam
+        wireStats()
+      })()
+    })
   })
 }

package/src/protocol/stats.ts

@@ -15,15 +15,25 @@ export interface StatsResponse {
   available: boolean
   /** Sorted per-skill invocation counts. */
   stats: SkillStat[]
+  /** Which read path produced the counts (debug aid for memory-issue follow-ups). */
+  source?: 'cold' | 'query'
 }
 
 /**
  * Persisted incremental-scan checkpoint for the usage statistics (sidecar
- * `skillStats` field). Sessions created before `frozenBefore` are treated as
- * finalized: their per-session counts live in `frozenSessions` (only sessions
- * with at least one invocation are kept) and they are not re-read on
- * incremental scans. A daily full reconciliation rebuilds the cache and
- * advances the watermark, so a resumed old session is eventually re-counted.
+ * `skillStats` field). Two buckets cover the two read paths:
+ *
+ * - `coldRevisions` (preferred): per-session counts keyed by the persistence
+ *   seam's opaque revision token. A session is re-read only when its revision
+ *   changes, so resumed old sessions are picked up exactly and the daily full
+ *   reconciliation is unnecessary on this path.
+ * - `frozenSessions` + `frozenBefore` + `lastFullReconcile` (fallback): the
+ *   legacy time-watermark scheme used when only the heavier `sessionQuery`
+ *   seam is available. Sessions older than the effective watermark are treated
+ *   as finalized: their per-session counts live in `frozenSessions` (only
+ *   sessions with at least one invocation are kept) and they are not re-read
+ *   on incremental scans. A daily full reconciliation rebuilds the cache and
+ *   advances the watermark, so a resumed old session is eventually re-counted.
  */
 export interface SkillStatsCheckpoint {
   /** The rolling-window configuration this checkpoint was built for (0 = all history). */
@@ -39,4 +49,20 @@ export interface SkillStatsCheckpoint {
    * start so a restart still shows numbers while the background rescan runs.
    */
   lastTotals?: SkillStat[]
+  /**
+   * Per-session counts read through the persistence seam, keyed by session id
+   * and stamped with the revision they were read at. Absent until the first
+   * cold-path scan completes; the query fallback path ignores it.
+   */
+  coldRevisions?: Record<string, ColdRevisionEntry>
+}
+
+/** One cold-path cache entry: what a session's log contained at a revision. */
+export interface ColdRevisionEntry {
+  /** The persistence seam's opaque revision token, stringified. */
+  rev: string
+  /** header.createdAt at read time (0 when the header carried none). */
+  createdAt: number
+  /** Per-skill counts (empty when the session invoked no skill). */
+  counts: Record<string, { count: number; lastUsed: number }>
 }

package/src/routes/catalog.ts

@@ -25,6 +25,7 @@ import {
 import { createSkill, disableSkill, enableSkill, parseFrontmatter, readSkillInterface, rootPath, trashSkill } from '../skillfs.ts'
 import {
   buildCatalog,
+  configOf,
   homeOf,
   pathExists,
   queryParam,
@@ -301,8 +302,15 @@ export function catalogRoutes(deps: SkillHubRouteDeps): RouteSpec[] {
           writeJson(res, 200, { ok: true, available: false, stats: [] } satisfies StatsResponse)
           return
         }
+        // All usage displays off means nobody reads statistics: answer
+        // unavailable without invoking the reader, so no scan is triggered.
+        const display = configOf(deps)
+        if (display.showUseCount === false && display.showUseTime === false && display.showGroupSummary === false) {
+          writeJson(res, 200, { ok: true, available: false, stats: [] } satisfies StatsResponse)
+          return
+        }
         const stats = await deps.stats()
-        writeJson(res, 200, { ok: true, available: true, stats } satisfies StatsResponse)
+        writeJson(res, 200, { ok: true, available: true, ...(deps.stats.source !== undefined ? { source: deps.stats.source } : {}), stats } satisfies StatsResponse)
       },
     },
   ]

package/src/routes.test.ts

@@ -110,6 +110,38 @@ describe('skill-hub routes', () => {
     expect(res.status).toBe(403)
   })
 
+  it('reports stats unavailable without a reader, or when all usage displays are off', async () => {
+    // 无 reader：面板显示空统计，不触发任何扫描。
+    const empty = new FakeResponse()
+    await routeFor(SKILL_HUB_API.stats).handler(fakeReq('GET', SKILL_HUB_API.stats), empty as never)
+    expect(empty.json()).toEqual({ ok: true, available: false, stats: [] })
+
+    // 有 reader 但三个展示开关全关：同样不调用 reader（kill-switch，issue #7）。
+    let calls = 0
+    deps.stats = async () => {
+      calls += 1
+      return [{ name: 'tdd', count: 1 }]
+    }
+    deps.config = () => ({ showUseCount: false, showUseTime: false, showGroupSummary: false }) as HubConfig
+    const off = new FakeResponse()
+    await routeFor(SKILL_HUB_API.stats).handler(fakeReq('GET', SKILL_HUB_API.stats), off as never)
+    expect(off.json()).toEqual({ ok: true, available: false, stats: [] })
+    expect(calls).toBe(0)
+
+    // 默认开任意一个即正常服务。
+    deps.config = () => ({ showUseCount: true }) as HubConfig
+    const on = new FakeResponse()
+    await routeFor(SKILL_HUB_API.stats).handler(fakeReq('GET', SKILL_HUB_API.stats), on as never)
+    expect(on.json()).toEqual({ ok: true, available: true, stats: [{ name: 'tdd', count: 1 }] })
+    expect(calls).toBe(1)
+
+    // reader 自带的来源标记会透出（无标记时不加字段）。
+    deps.stats.source = 'cold'
+    const sourced = new FakeResponse()
+    await routeFor(SKILL_HUB_API.stats).handler(fakeReq('GET', SKILL_HUB_API.stats), sourced as never)
+    expect(sourced.json()).toEqual({ ok: true, available: true, source: 'cold', stats: [{ name: 'tdd', count: 1 }] })
+  })
+
   it('serves the catalog with writable flags and diagnostics', async () => {
     skills.snapshot = async () => ({
       skills: [summary({ source: 'user-dsh' }), summary({ name: 'bundled-x', source: 'bundled', provider: 'bundled' })],

package/src/stats.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest'
-import { countSkillInvocations, createSkillStatsReader, readSkillStats, STATS_FREEZE_AFTER_MS, type SessionQueryLike } from './stats.ts'
+import { asPersistenceSeam, countSkillInvocations, createSkillStatsReader, readColdSkillStats, readSkillStats, STATS_FREEZE_AFTER_MS, type SessionPersistenceLike, type SessionQueryLike } from './stats.ts'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
+import type { SkillStatsCheckpoint } from './protocol.ts'
 
 /** Minimal user/message event carrying a skill-invocation source. */
 function invocationEvent(name: string, seq = 1, time = 0): SessionEvent {
@@ -148,7 +149,9 @@ describe('createSkillStatsReader', () => {
   it('serves stale totals after expiry and rescans only once', async () => {
     let reads = 0
     const query: SessionQueryLike = {
-      listSessions: async () => [{ header: { id: 'a' as never } }],
+      // 有时间戳的近期会话：增量扫描会重读，正好验证“过期触发且只刷一次”。
+      // （无时间戳会话首轮进冻结桶后不再重读，见下文增量测试。）
+      listSessions: async () => [{ header: { id: 'a' as never, createdAt: Date.now() } }],
       readSession: async () => {
         reads += 1
         return { events: [invocationEvent('tdd', 1)] }
@@ -200,7 +203,7 @@ async function flush(): Promise<void> {
 }
 
 describe('scan read concurrency', () => {
-  it('reads session logs in parallel, not one by one', async () => {
+  it('reads session logs sequentially (peak 1) to bound host restore memory', async () => {
     const ids = Array.from({ length: 8 }, (_, i) => 's' + i)
     let inFlight = 0
     let peak = 0
@@ -214,11 +217,11 @@ describe('scan read concurrency', () => {
         return { events: [invocationEvent(String(id))] }
       },
     }
-    // No checkpoint → full path, all 8 sessions read.
+    // No checkpoint → full path, all 8 sessions read, one at a time: a heavy
+    // corpus costs wall time (issue #7), never a memory spike.
     const stats = await readSkillStats(query)
     expect(stats).toHaveLength(8)
-    expect(peak).toBeGreaterThan(1)
-    expect(peak).toBeLessThanOrEqual(6)
+    expect(peak).toBe(1)
   })
 })
 
@@ -491,4 +494,239 @@ describe('rolling stats window (configurable days)', () => {
     expect(stats).toEqual([])
     expect(checkpoint.frozenSessions['stale-entry']).toBeUndefined() // 已被懒清理
   })
+
+  it('keeps sessions without createdAt in the frozen bucket after the first read', async () => {
+    // 无时间戳会话按时间永远冻不住：首轮全量读到调用就进缓存，
+    // 增量扫描不再重读（issue #7：否则每轮都重读）。
+    const reads: string[] = []
+    const query = fakeQuery(
+      [record('no-stamp'), record('fresh', NOW - 1 * DAY)],
+      { 'no-stamp': [invocationEvent('x', 1)], fresh: [invocationEvent('y', 1)] },
+      reads,
+    )
+    let clock = NOW
+    const checkpoint: SkillStatsCheckpoint = { windowDays: 0, frozenBefore: 0, frozenSessions: {}, lastFullReconcile: 0 }
+    const reader = createSkillStatsReader(query, 60_000, { now: () => clock, checkpoint })
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(reads).toEqual(['no-stamp', 'fresh']) // 首轮全量：两个都读
+    expect(checkpoint.frozenSessions['no-stamp']).not.toBeUndefined()
+    clock += 120_000 // TTL 过期 → 增量扫描
+    await reader()
+    await flush()
+    expect(reads).toEqual(['no-stamp', 'fresh', 'fresh']) // 只重读 fresh，no-stamp 不再读
+  })
+})
+
+// ------------------------------------------------ 冷路径（persistence seam）
+
+/** One fake persisted session. */
+function coldEntry(id: string, createdAt: number | undefined, rev: string, events: SessionEvent[] | 'corrupt'): { id: string; createdAt: number | undefined; rev: string; events: SessionEvent[] | 'corrupt' } {
+  return { id, createdAt, rev, events }
+}
+
+/** Fake persistence seam recording opens/closes (handles must always close). */
+function fakePersistence(
+  entries: ReturnType<typeof coldEntry>[],
+  trace: { lists: number; opens: string[]; closes: string[] },
+  failList = false,
+): SessionPersistenceLike {
+  return {
+    list: async () => {
+      trace.lists += 1
+      if (failList) throw new Error('backend down')
+      return entries.map((entry) => ({
+        header: { id: entry.id as never, ...(entry.createdAt !== undefined ? { createdAt: entry.createdAt } : {}) },
+        revision: entry.rev,
+      }))
+    },
+    open: async (id) => {
+      trace.opens.push(String(id))
+      const entry = entries.find((candidate) => candidate.id === String(id))
+      if (entry === undefined || entry.events === 'corrupt') throw new Error('unreadable')
+      const events = entry.events
+      return {
+        read: async () => ({ events }),
+        close: () => { trace.closes.push(String(id)) },
+      }
+    },
+  }
+}
+
+function coldTrace(): { lists: number; opens: string[]; closes: string[] } {
+  return { lists: 0, opens: [], closes: [] }
+}
+
+describe('readColdSkillStats', () => {
+  it('totals invocations across sessions and sorts by name', async () => {
+    const trace = coldTrace()
+    const persistence = fakePersistence([
+      coldEntry('a', NOW - 1 * DAY, 'r1', [invocationEvent('tdd', 1), invocationEvent('tdd', 2)]),
+      coldEntry('b', NOW - 2 * DAY, 'r1', [invocationEvent('code-review', 1), skillToolCall('tdd', 2)]),
+    ], trace)
+    expect(await readColdSkillStats(persistence)).toEqual([
+      { name: 'code-review', count: 1, lastUsed: 0 },
+      { name: 'tdd', count: 3, lastUsed: 0 },
+    ])
+    expect(trace.opens).toEqual(['a', 'b'])
+    expect(trace.closes).toEqual(['a', 'b']) // 每个 handle 都关闭
+  })
+
+  it('never opens out-of-window logs', async () => {
+    const trace = coldTrace()
+    const persistence = fakePersistence([
+      coldEntry('old', NOW - 10 * DAY, 'r1', [invocationEvent('oldskill', 1)]),
+      coldEntry('fresh', NOW - 1 * DAY, 'r1', [invocationEvent('tdd', 1)]),
+    ], trace)
+    const checkpoint = { windowDays: 7, frozenBefore: 0, frozenSessions: {}, lastFullReconcile: 0 }
+    const reader = createSkillStatsReader({ listSessions: async () => [], readSession: async () => ({ events: [] }) }, 60_000, {
+      now: () => NOW,
+      checkpoint,
+      windowDays: () => 7,
+      persistence,
+    })
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(await reader()).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+    expect(trace.opens).toEqual(['fresh']) // old 连开都没开
+  })
+
+  it('skips corrupt sessions without failing the scan', async () => {
+    const trace = coldTrace()
+    const persistence = fakePersistence([
+      coldEntry('bad', NOW - 1 * DAY, 'r1', 'corrupt'),
+      coldEntry('good', NOW - 1 * DAY, 'r1', [invocationEvent('tdd', 1)]),
+    ], trace)
+    expect(await readColdSkillStats(persistence)).toEqual([{ name: 'tdd', count: 1, lastUsed: 0 }])
+  })
+
+  it('re-reads only sessions whose revision changed', async () => {
+    const trace = coldTrace()
+    const entries = [
+      coldEntry('steady', NOW - 5 * DAY, 'r1', [invocationEvent('tdd', 1)]),
+      coldEntry('growing', NOW - 1 * DAY, 'r1', [invocationEvent('tdd', 1)]),
+    ]
+    const persistence = fakePersistence(entries, trace)
+    let clock = NOW
+    const query: SessionQueryLike = { listSessions: async () => [], readSession: async () => ({ events: [] }) }
+    const checkpoints: Array<Record<string, unknown>> = []
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => clock,
+      persistence,
+      onCheckpoint: (cp) => { checkpoints.push(cp as unknown as Record<string, unknown>) },
+    })
+    expect(await reader()).toEqual([])
+    await flush()
+    expect(await reader()).toEqual([{ name: 'tdd', count: 2, lastUsed: 0 }])
+    expect(trace.opens).toEqual(['steady', 'growing'])
+
+    // growing 续写（revision 变化），steady 不变：第二轮只重读 growing。
+    entries[1]!.rev = 'r2'
+    entries[1]!.events = [invocationEvent('tdd', 1), invocationEvent('tdd', 2)]
+    clock += 120_000 // TTL 过期，触发后台重扫
+    expect(await reader()).toEqual([{ name: 'tdd', count: 2, lastUsed: 0 }]) // 先回 stale
+    await flush()
+    expect(await reader()).toEqual([{ name: 'tdd', count: 3, lastUsed: 0 }])
+    expect(trace.opens).toEqual(['steady', 'growing', 'growing'])
+    // 检查点里记了两个 revision，下次重启不用重读。
+    const saved = checkpoints.at(-1)?.['coldRevisions'] as Record<string, { rev: string }>
+    expect(saved['steady']?.rev).toBe('r1')
+    expect(saved['growing']?.rev).toBe('r2')
+  })
+
+  it('reads live sessions through the query seam without double-counting', async () => {
+    const trace = coldTrace()
+    const persistence = fakePersistence([
+      coldEntry('live-one', NOW - 1 * DAY, 'r1', [invocationEvent('persisted-part', 1)]),
+      coldEntry('calm', NOW - 2 * DAY, 'r1', [invocationEvent('tdd', 1)]),
+    ], trace)
+    const query: SessionQueryLike = {
+      listSessions: async () => [],
+      readSession: async (id) => ({
+        // live 会话的内存态比落盘新：全量当前日志（含已落盘部分）。
+        events: String(id) === 'live-one'
+          ? [invocationEvent('persisted-part', 1), invocationEvent('live-part', 2)]
+          : [],
+      }),
+    }
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      persistence,
+      listLiveIds: async () => ['live-one' as never],
+      readLiveSession: (id) => query.readSession(id),
+    })
+    expect(await reader()).toEqual([])
+    await flush()
+    // live-one 只按 live 读了一次（persisted-part 不翻倍），calm 走 revision 缓存。
+    expect(await reader()).toEqual([
+      { name: 'live-part', count: 1, lastUsed: 0 },
+      { name: 'persisted-part', count: 1, lastUsed: 0 },
+      { name: 'tdd', count: 1, lastUsed: 0 },
+    ])
+    expect(trace.opens).toEqual(['calm'])
+  })
+
+  it('keeps previous totals when the listing fails', async () => {
+    const trace = coldTrace()
+    const persistence = fakePersistence([coldEntry('a', NOW - 1 * DAY, 'r1', [invocationEvent('tdd', 1)])], trace, true)
+    const query: SessionQueryLike = { listSessions: async () => [], readSession: async () => ({ events: [] }) }
+    const reader = createSkillStatsReader(query, 60_000, {
+      now: () => NOW,
+      persistence,
+      checkpoint: {
+        windowDays: 0,
+        frozenBefore: 0,
+        frozenSessions: {},
+        lastFullReconcile: NOW,
+        lastTotals: [{ name: 'oldskill', count: 9, lastUsed: 7 }],
+      },
+    })
+    expect(await reader()).toEqual([{ name: 'oldskill', count: 9, lastUsed: 7 }])
+    await flush()
+    expect(await reader()).toEqual([{ name: 'oldskill', count: 9, lastUsed: 7 }]) // 失败保留旧数
+    expect(trace.opens).toEqual([])
+  })
+})
+
+describe('asPersistenceSeam', () => {
+  it('rejects non-service values without I/O', () => {
+    expect(asPersistenceSeam(undefined)).toBeUndefined()
+    expect(asPersistenceSeam(null)).toBeUndefined()
+    expect(asPersistenceSeam({})).toBeUndefined()
+    expect(asPersistenceSeam({ list: async () => [] })).toBeUndefined()
+    expect(asPersistenceSeam({ open: async () => ({}) })).toBeUndefined()
+  })
+
+  it('adapts list/open/read/close with shape validation', async () => {
+    const closes: string[] = []
+    const seam = asPersistenceSeam({
+      list: async () => [{ header: { id: 'a', createdAt: 5 }, revision: 42 }],
+      open: async (id: unknown) => ({
+        read: async (offset: unknown) => {
+          expect(offset).toBe(0)
+          return { events: [invocationEvent('tdd', 1)] }
+        },
+        close: () => { closes.push(String(id)) },
+      }),
+    })
+    expect(seam).not.toBeUndefined()
+    const snapshots = await seam!.list()
+    expect(snapshots).toEqual([{ header: { id: 'a', createdAt: 5 }, revision: '42' }])
+    const handle = await seam!.open('a' as never, 'read')
+    expect((await handle.read()).events).toHaveLength(1)
+    await handle.close()
+    expect(closes).toEqual(['a'])
+  })
+
+  it('throws on malformed snapshots, handles, and reads', async () => {
+    const badList = asPersistenceSeam({ list: async () => [{ nope: true }], open: async () => ({}) })!
+    await expect(badList.list()).rejects.toThrow()
+    const badOpen = asPersistenceSeam({ list: async () => [], open: async () => ({}) })!
+    await expect(badOpen.open('a' as never, 'read')).rejects.toThrow()
+    const badRead = asPersistenceSeam({
+      list: async () => [],
+      open: async () => ({ read: async () => ({ nope: 1 }), close: () => {} }),
+    })!
+    await expect((await badRead.open('a' as never, 'read')).read()).rejects.toThrow()
+  })
 })