@dimina-kit/fs-core 0.2.0-dev.20260710085051 → 0.3.0-dev.6-dev.20260711133419

package/src/client.ts

@@ -1,40 +1,94 @@
 /**
- * ProjectFsClient — 主线程侧 ProjectFS 封装（P0，同 origin）。
+ * ProjectFsClient — 主线程侧 ProjectFS 封装（同 origin）。
  * 起 fs-core / fs-query 两个 worker，牵好 core→query 的 diff 端口，
  * 暴露 Promise API；写请求自动带 opId，超时重试幂等（同 opId 重发）。
  */
-const WRITE_TIMEOUT_MS = 8000
+import type { CoreMessage, FsCoreMode } from './worker-lib/protocol.js'
 
-type Mode = 'starting' | 'writer' | 'readonly' | 'draining' | 'dead'
+// The wire contract (error codes, event names, message shapes) lives in
+// worker-lib/protocol.ts — shared verbatim with the worker's own emit sites —
+// and is re-exported here so consumers can match on symbols instead of
+// quoting string literals from worker source.
+export { FS_CORE_ERROR_CODES, getFsCoreErrorCode, isFsCoreErrorCode } from './worker-lib/protocol.js'
+export type {
+  CoreMessage, CoreWireMessage, FsCoreErrorCode, FsCoreErrorExtras, FsCoreEventName, FsCoreMode,
+} from './worker-lib/protocol.js'
 
-/**
- * Loosely-shaped dynamic message bag flowing over the fs-core worker's main
- * port: both the WELCOME/PONG/event messages (`event()`/`welcome()` in
- * fs-core.worker.ts) and the RPC reply messages (`respond()`/`fail()` there)
- * land here, distinguished at runtime by which optional fields are present.
- * One flat interface (rather than a narrowed union) matches how the code
- * actually reads it — every field is optional and independently checked.
- */
-export interface CoreMessage {
-  type?: string
-  evt?: string
-  error?: string
-  mode?: Mode
-  readonly?: boolean
-  gen?: number
-  id?: number
-  ok?: boolean
-  result?: unknown
-  code?: string
-  humanPaths?: string[]
-  auditGap?: boolean
-  actor?: string
-  paths?: string[]
-  count?: number
-  restore?: string
-  t?: number
+// ── Write-API opts/results — the client-side mirror of the worker RPC args
+// in worker-lib/rpc-types.ts, narrowed to what a caller actually supplies
+// (the worker also accepts `opId`, but callers never set it directly —
+// `_writeOp` stamps one via `crypto.randomUUID()` for the idempotent-retry
+// contract). `actor` is a literal union here (rpc-types.ts's `WriteArgs` etc.
+// use a plain `string` because the worker only validates it at runtime) so
+// that a typo'd actor is a compile error at the call site.
+export interface FsWriteCallOpts {
+  actor?: 'human' | 'agent'
+  turnId?: string
+  agentToken?: string
+  ifMatch?: number | null
+}
+
+export interface FsCheckpointOpts {
+  actor?: 'human' | 'agent'
+  turnId?: string
+  agentToken?: string
+}
+
+export interface FsRestoreOpts extends FsCheckpointOpts {
+  baseGen?: number
+  force?: boolean
 }
 
+export interface FsTurnBeginOpts {
+  ttlMs?: number
+}
+
+export interface FsWriteResult {
+  gen: number
+  rev: number
+  idempotent?: boolean
+}
+
+export interface FsCheckpointResult extends FsWriteResult {
+  cpId: string
+}
+
+export interface FsTurnBeginResult extends FsWriteResult {
+  turnId: string
+  cpId: string
+  expiresAt: number
+}
+
+export interface FsTurnEndResult {
+  turnId: string
+  closed: boolean
+  ops: number
+}
+
+/** opRestore's respond replaces the mirror wholesale rather than appending to
+ * it, so it carries no `rev` — see fs-core-write-ops.ts's `opRestore`. */
+export interface FsRestoreResult {
+  gen: number
+  restored: number
+}
+
+/** Directories are implicit (no tracked entry), so mkdir's respond carries
+ * only `gen`, no `rev` — see fs-core.worker.ts's `mkdir` dispatch. */
+export interface FsMkdirResult {
+  gen: number
+}
+
+/** compactNow's return shape (fs-core.worker.ts) — `skipped` when the
+ * active segment was already below the rotation threshold. */
+export interface FsCompactResult {
+  gen: number
+  skipped?: boolean
+}
+
+const WRITE_TIMEOUT_MS = 8000
+
+type Mode = FsCoreMode
+
 interface PendingEntry {
   resolve: (v: unknown) => void
   reject: (e: unknown) => void
@@ -80,7 +134,6 @@ export class ProjectFsClient {
   welcome: CoreMessage | null = null
   pingTimer!: ReturnType<typeof setInterval>
   lastPong!: number
-  private _retried?: boolean
 
   /** 测试用：抹掉一个项目的全部持久层（只能在无 core 运行时调用）。 */
   static async wipe(projectId: string): Promise<void> {
@@ -88,6 +141,11 @@ export class ProjectFsClient {
     try { await root.removeEntry(projectId, { recursive: true }) } catch {}
   }
 
+  /** `coreUrl`/`queryUrl` default to the `/ide/fs/` deployment convention of
+   * the original dwc host (documented in this package's README「使用」节);
+   * every other real host serves the worker files elsewhere and passes both
+   * URLs explicitly — see `resolveWorkerFiles` (`./worker-files`) for the
+   * authoritative file-name/sibling contract. */
   static async connect({
     projectId,
     coreUrl = '/ide/fs/fs-core.worker.js',
@@ -178,8 +236,10 @@ export class ProjectFsClient {
       const entryResolve = resolve as (v: unknown) => void
       const timer = timeout
         ? setTimeout(() => {
-            // 超时重试一次：同 opId 幂等（fs-core 对已知 opId 返回既有结果）
-            if (opId && !this._retried) {
+            // 超时重试一次：同 opId 幂等（fs-core 对已知 opId 返回既有结果）；
+            // 重试自己的 timer 只会终止性 reject，不会再进这个分支，所以每次
+            // 调用恰好一次重试。
+            if (opId) {
               const retryId = ++this.seq
               this.pending.set(retryId, { resolve: entryResolve, reject, timer: setTimeout(() => { this.pending.delete(retryId); reject(new Error(op + ' timeout (after retry)')) }, timeout) })
               this.pending.delete(id)
@@ -208,24 +268,24 @@ export class ProjectFsClient {
   }
 
   // ── 写 API（{actor:'human'|'agent', turnId, ifMatch} 透传）──
-  write(path: string, content: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('write', { path, content, ...opts }) }
-  edit(path: string, old: string, next: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('edit', { path, old, next, ...opts }) }
-  rm(path: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('rm', { path, ...opts }) }
-  mv(from: string, to: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('mv', { from, to, ...opts }) }
-  mkdir(path: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('mkdir', { path, ...opts }) }
-  checkpoint(opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('checkpoint', { ...opts }) }
-  /** opts: {baseGen?, force?} 透传给 fs-core（§4.7 restore 冲突策略）；baseGen 缺省时
+  write(path: string, content: string, opts: FsWriteCallOpts = {}): Promise<FsWriteResult> { return this._writeOp<FsWriteResult>('write', { path, content, ...opts }) }
+  edit(path: string, old: string, next: string, opts: FsWriteCallOpts = {}): Promise<FsWriteResult> { return this._writeOp<FsWriteResult>('edit', { path, old, next, ...opts }) }
+  rm(path: string, opts: FsWriteCallOpts = {}): Promise<FsWriteResult> { return this._writeOp<FsWriteResult>('rm', { path, ...opts }) }
+  mv(from: string, to: string, opts: FsWriteCallOpts = {}): Promise<FsWriteResult> { return this._writeOp<FsWriteResult>('mv', { from, to, ...opts }) }
+  mkdir(path: string, opts: FsWriteCallOpts = {}): Promise<FsMkdirResult> { return this._writeOp<FsMkdirResult>('mkdir', { path, ...opts }) }
+  checkpoint(opts: FsCheckpointOpts = {}): Promise<FsCheckpointResult> { return this._writeOp<FsCheckpointResult>('checkpoint', { ...opts }) }
+  /** opts.baseGen/force 透传给 fs-core（restore 冲突策略）；baseGen 缺省时
    * fs-core 从 checkpoint 自身记录的 gen 推导。 */
-  restore(cpId: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('restore', { cpId, ...opts }) }
-  compact(): Promise<unknown> { return this._rpc('compact', {}, { timeout: 30000 }) }
+  restore(cpId: string, opts: FsRestoreOpts = {}): Promise<FsRestoreResult> { return this._writeOp<FsRestoreResult>('restore', { cpId, ...opts }) }
+  compact(): Promise<FsCompactResult> { return this._rpc<FsCompactResult>('compact', {}, { timeout: 30000 }) }
 
-  // ── P4 turn 能力：铸造（附带 checkpoint 锚）→ agent 写执法 → 撤销 ──
-  turnBegin(turnId: string, opts: Record<string, unknown> = {}): Promise<unknown> { return this._writeOp('turnBegin', { turnId, ...opts }) }
-  turnEnd(turnId: string): Promise<unknown> { return this._writeOp('turnEnd', { turnId }) }
+  // ── turn 能力：铸造（附带 checkpoint 锚）→ agent 写执法 → 撤销 ──
+  turnBegin(turnId: string, opts: FsTurnBeginOpts = {}): Promise<FsTurnBeginResult> { return this._writeOp<FsTurnBeginResult>('turnBegin', { turnId, ...opts }) }
+  turnEnd(turnId: string): Promise<FsTurnEndResult> { return this._writeOp<FsTurnEndResult>('turnEnd', { turnId }) }
   /** 该 turn 的改动清单（WAL actor/turnId 审计标注免费提供）。 */
   diff(turnId?: string): Promise<DiffResult> { return this._rpc<DiffResult>('diff', { turnId }) }
 
-  /** W4 纵深加固令牌门（docs/k3-terminal-split-plan.md §6 替代方案 A / §8.3）：特权方法，只应
+  /** 纵深加固令牌门：特权方法，只应
    * 由内核（kernel.js createKernel）在 boot 早期调用一次，把只有内核持有的随机令牌交给 fs-core；
    * 此后 actor:'agent' 的写类 op 必须在 opts 里携带匹配的 agentToken（fs-core 侧强制，见
    * fs-core.worker.js checkTurn/armAgentToken）。无 opId/超时重试——一次性 admin 调用，非写路径
@@ -233,6 +293,13 @@ export class ProjectFsClient {
   armAgentTokenGate(token: string): Promise<{ armed: boolean; idempotent?: boolean }> { return this._rpc('armAgentTokenGate', { token }) }
 
   // ── 读 API：小读走 core（权威），查询/快照走 query（不占写路径）──
+  /** readonly 端主动请求写权交接（协作交接协议，禁 steal）：现任写者排干释放后，
+   * 本 client 的排队锁请求 granted → mode 经 writer-granted 事件翻转（订阅
+   * onModeChange 观察结果）。只有 readonly 会真正行动：writer/dead/starting 上
+   * 调用是 no-op（如实返回 {mode}），draining 以错误码 'draining' 拒绝。
+   * 何时调用是宿主策略——典型是用户在"另一个标签页持有写权"提示上点"在此接管"。 */
+  requestHandover(): Promise<{ requested?: boolean; mode?: FsCoreMode }> { return this._rpc('requestHandover', {}) }
+
   read(path: string): Promise<{ content: string; rev?: number; gen: number }> { return this._rpc('read', { path }) }
   ls(): Promise<{ paths: string[]; gen: number }> { return this._rpc('ls', {}) }
   status(): Promise<StatusResult> { return this._rpc<StatusResult>('status', {}) }

package/src/disk-mirror.ts

@@ -1,7 +1,7 @@
 /**
- * 本地磁盘镜像（P5，Chromium only）—— showDirectoryPicker() 授权一个真实磁盘目录，
+ * 本地磁盘镜像（Chromium only）—— showDirectoryPicker() 授权一个真实磁盘目录，
  * 把项目树 write-through 镜像过去：用户在访达/资源管理器里能看到自己的项目。
- * 这是"持久化到磁盘"的字面回答（架构文档 §4 出口 1）。
+ * 这是"持久化到磁盘"的字面回答。
  *
  * 策略：fs-change 防抖 2s 全量比对同步（内容不变的文件跳过 —— 内容比对在内存，
  * 磁盘只写变更）；删除按上次镜像记录清理。授权需要用户手势，无授权时静默不动。

package/src/fs-core-handover.test.ts

@@ -0,0 +1,215 @@
+/**
+ * Guards `requestHandover(core)` — the readonly-side counterpart to the
+ * writer-side handover in `onBroadcast` (fs-core-recovery.ts): a readonly
+ * client actively asking the current writer to hand off the lease, instead
+ * of only ever passively upgrading once a queued `navigator.locks` request
+ * happens to land. Also guards the client-facing `ProjectFsClient.requestHandover()`
+ * wrapper that posts the RPC.
+ *
+ * `core` is a structural fake — only the fields `requestHandover`/`onBroadcast`
+ * touch — narrowed through `as unknown as FsCore`, matching the pattern in
+ * client.test.ts/fs-core-recovery-lock.test.ts (no `as any`/`@ts-expect-error`).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { onBroadcast, requestHandover } from './fs-core-recovery.js'
+import type { FsCore } from './fs-core.worker.js'
+import { isFsCoreErrorCode, type CoreMessage, type FsCoreMode } from './worker-lib/protocol.js'
+import { ProjectFsClient } from './client.js'
+
+type LockRequestFn = (name: string, opts: unknown, cb: (lock: unknown) => Promise<void>) => Promise<unknown>
+
+interface FakeCore {
+  mode: FsCoreMode
+  bc: { postMessage: (msg: unknown) => void }
+  writerLockQueued: boolean
+  writerLockHeld: boolean
+  handoverRequested: boolean
+  becomeWriter: () => Promise<void>
+  enqueue: (fn: () => unknown) => Promise<unknown>
+}
+
+function makeCore(overrides: Partial<FakeCore> = {}): FakeCore {
+  return {
+    mode: 'readonly',
+    bc: { postMessage: vi.fn() },
+    writerLockQueued: false,
+    writerLockHeld: false,
+    handoverRequested: false,
+    becomeWriter: vi.fn(async () => {}),
+    enqueue: vi.fn((fn: () => unknown) => Promise.resolve(fn())),
+    ...overrides,
+  }
+}
+
+describe('fs-core-recovery requestHandover() — readonly-initiated handover request', () => {
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('mode writer returns {mode:\'writer\'} immediately — no broadcast, no lock request', async () => {
+    const request: LockRequestFn = vi.fn()
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'writer' })
+
+    const result = await requestHandover(core as unknown as FsCore)
+
+    expect(result).toEqual({ mode: 'writer' })
+    expect(core.bc.postMessage).not.toHaveBeenCalled()
+    expect(request).not.toHaveBeenCalled()
+  })
+
+  it('mode draining rejects with the draining error code', async () => {
+    const core = makeCore({ mode: 'draining' })
+    let caught: unknown
+    try {
+      await requestHandover(core as unknown as FsCore)
+    } catch (e) {
+      caught = e
+    }
+    expect(isFsCoreErrorCode(caught, 'draining')).toBe(true)
+  })
+
+  it('mode dead returns {mode:\'dead\'} without broadcasting or requesting a lock', async () => {
+    // A FATAL'd worker cannot upgrade even if the lease later lands (the
+    // deferred writer upgrade bails on dead), so broadcasting
+    // handover-request from it would only drain a healthy writer for nothing.
+    const request: LockRequestFn = vi.fn()
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'dead' })
+
+    const result = await requestHandover(core as unknown as FsCore)
+
+    expect(result).toEqual({ mode: 'dead' })
+    expect(core.bc.postMessage).not.toHaveBeenCalled()
+    expect(request).not.toHaveBeenCalled()
+    expect(core.handoverRequested).toBe(false)
+  })
+
+  it('mode starting returns {mode:\'starting\'} without broadcasting or requesting a lock', async () => {
+    // start()'s own lock arbitration is still in flight — acting here would
+    // race it with a second queued lock request and a premature broadcast.
+    const request: LockRequestFn = vi.fn()
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'starting' })
+
+    const result = await requestHandover(core as unknown as FsCore)
+
+    expect(result).toEqual({ mode: 'starting' })
+    expect(core.bc.postMessage).not.toHaveBeenCalled()
+    expect(request).not.toHaveBeenCalled()
+    expect(core.handoverRequested).toBe(false)
+  })
+
+  it('mode readonly with a lock already queued rebroadcasts without requesting a second lock', async () => {
+    const request: LockRequestFn = vi.fn()
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'readonly', writerLockQueued: true })
+
+    const result = await requestHandover(core as unknown as FsCore)
+
+    expect(result).toEqual({ requested: true })
+    expect(core.bc.postMessage).toHaveBeenCalledTimes(1)
+    expect(core.bc.postMessage).toHaveBeenCalledWith({ type: 'handover-request' })
+    expect(request).not.toHaveBeenCalled()
+  })
+
+  it('mode readonly with the lock already granted (upgrade in flight) neither re-queues nor broadcasts', async () => {
+    // Window between lock grant and becomeWriter completion: the lock callback
+    // clears writerLockQueued at grant time, but mode stays 'readonly' until
+    // the async recover finishes. Acting here would queue a stale second lock
+    // request (which could later grab the lease and corrupt the handover) and
+    // broadcast a pointless drain to the outgoing writer.
+    const request: LockRequestFn = vi.fn()
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'readonly', writerLockQueued: false, writerLockHeld: true })
+
+    const result = await requestHandover(core as unknown as FsCore)
+
+    expect(result).toEqual({ requested: true })
+    expect(request).not.toHaveBeenCalled()
+    expect(core.bc.postMessage).not.toHaveBeenCalled()
+    expect(core.handoverRequested).toBe(false)
+  })
+
+  it('mode readonly with no lock queued issues a fresh writer-lock request and upgrades once granted', async () => {
+    let grantCb!: (lock: unknown) => Promise<void>
+    const request: LockRequestFn = vi.fn((_name, _opts, cb) => {
+      grantCb = cb
+      return new Promise(() => {})
+    })
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'readonly', writerLockQueued: false })
+
+    const result = await requestHandover(core as unknown as FsCore)
+
+    expect(result).toEqual({ requested: true })
+    expect(request).toHaveBeenCalledTimes(1)
+    expect(core.bc.postMessage).toHaveBeenCalledWith({ type: 'handover-request' })
+    expect(core.becomeWriter).not.toHaveBeenCalled()
+
+    grantCb({})
+    await Promise.resolve()
+    await Promise.resolve()
+
+    expect(core.enqueue).toHaveBeenCalled()
+    expect(core.becomeWriter).toHaveBeenCalledTimes(1)
+  })
+
+  it('a repeated call within the same pending cycle merges: no extra lock request or broadcast', async () => {
+    const request: LockRequestFn = vi.fn(() => new Promise(() => {}))
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'readonly', writerLockQueued: false })
+
+    const first = await requestHandover(core as unknown as FsCore)
+    const second = await requestHandover(core as unknown as FsCore)
+
+    expect(first).toEqual({ requested: true })
+    expect(second).toEqual({ requested: true })
+    expect(request).toHaveBeenCalledTimes(1)
+    expect(core.bc.postMessage).toHaveBeenCalledTimes(1)
+  })
+
+  it('a handover-done broadcast clears the merge flag so a later requestHandover broadcasts again', async () => {
+    const request: LockRequestFn = vi.fn(() => new Promise(() => {}))
+    vi.stubGlobal('navigator', { locks: { request } })
+    const core = makeCore({ mode: 'readonly', writerLockQueued: false })
+
+    await requestHandover(core as unknown as FsCore) // 1st: broadcasts, marks the pending cycle
+    await onBroadcast(core as unknown as FsCore, { type: 'handover-done' })
+    await requestHandover(core as unknown as FsCore) // merge flag reset — broadcasts again
+
+    expect(core.bc.postMessage).toHaveBeenCalledTimes(2)
+  })
+})
+
+type ClientInternals = Omit<ProjectFsClient, 'core'> & {
+  pending: Map<number, unknown>
+  seq: number
+  core: { postMessage: (msg: unknown) => void }
+  _onCoreMessage(msg: CoreMessage, resolveWelcome?: (w: CoreMessage) => void, rejectWelcome?: (e: Error) => void): void
+  requestHandover(): Promise<unknown>
+}
+
+function makeBareRpcClient(): { client: ClientInternals; posted: Array<{ id: number; op: string }> } {
+  const posted: Array<{ id: number; op: string }> = []
+  const c = new ProjectFsClient() as unknown as ClientInternals
+  c.pending = new Map()
+  c.seq = 0
+  c.core = { postMessage: (msg) => posted.push(msg as { id: number; op: string }) }
+  return { client: c, posted }
+}
+
+describe('ProjectFsClient.requestHandover', () => {
+  it('posts a requestHandover op to the core worker and resolves via the RPC reply', async () => {
+    const { client, posted } = makeBareRpcClient()
+
+    const p = client.requestHandover()
+
+    expect(posted).toHaveLength(1)
+    expect(posted[0]!.op).toBe('requestHandover')
+
+    client._onCoreMessage({ id: posted[0]!.id, ok: true, result: { requested: true } } as CoreMessage)
+
+    await expect(p).resolves.toEqual({ requested: true })
+  })
+})

package/src/fs-core-opid-replay.test.ts

@@ -0,0 +1,158 @@
+/**
+ * Guards the opId idempotent-replay cache's payload completeness: when a
+ * timed-out client retries with the same opId, handleRpc (fs-core.worker.ts)
+ * answers from `core.opIds` instead of re-executing — so the cached entry
+ * must carry the FULL result the live path responded with. A cache that only
+ * stores `{gen}` makes the replay lose checkpoint's cpId, turnBegin's
+ * turnId/cpId/expiresAt, and restore's restored count, breaking the client's
+ * typed result contract (client.ts declares those fields as always present).
+ *
+ * Recovery-rebuilt entries legitimately hold only `{gen}` (WAL records do not
+ * persist in-memory extras) — that cross-session degradation is documented at
+ * the implementation, not tested here; these tests pin the LIVE path only.
+ *
+ * `core` fakes are structural (only the fields flushWindow/opRestore touch),
+ * narrowed via `as unknown as FsCore`; `rememberOpId` is the REAL
+ * implementation bound to the fake so assertions read the actual cache Map.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import * as writeOps from './fs-core-write-ops.js'
+import type { FsCore } from './fs-core.worker.js'
+import type { Respond, WindowOp } from './worker-lib/engine-shared.js'
+
+interface FakeFlushCore {
+  flushTimer: ReturnType<typeof setTimeout> | null
+  windowOps: WindowOp[]
+  walHandle: { flush: () => void }
+  walGen: number
+  appendedGen: number
+  memGen: number
+  ackGen: number
+  staged: Map<string, unknown>
+  mirror: Map<string, unknown>
+  opIds: Map<string, { gen: number }>
+  pushDiff: (diff: Record<string, unknown>, gen: number) => void
+  rememberOpId: (opId: string, v: { gen: number }) => void
+  event: (e: unknown) => void
+  bc: { postMessage: (msg: unknown) => void }
+}
+
+function makeFlushCore(windowOps: WindowOp[]): FakeFlushCore {
+  const core: FakeFlushCore = {
+    flushTimer: null,
+    windowOps,
+    walHandle: { flush: vi.fn() },
+    walGen: 0,
+    appendedGen: Math.max(0, ...windowOps.map((w) => w.gen)),
+    memGen: 0,
+    ackGen: 0,
+    staged: new Map(),
+    mirror: new Map(),
+    opIds: new Map(),
+    pushDiff: vi.fn(),
+    rememberOpId: (opId, v) => writeOps.rememberOpId(core as unknown as FsCore, opId, v),
+    event: vi.fn(),
+    bc: { postMessage: vi.fn() },
+  }
+  return core
+}
+
+describe('flushWindow — opId replay cache stores the full respond result', () => {
+  it('caches a checkpoint windowOp as {gen, rev, cpId}, matching what the live respond delivered', () => {
+    const respond = vi.fn()
+    const core = makeFlushCore([{ respond, gen: 3, actor: 'human', opId: 'op-c1', extra: { cpId: 'c1' } }])
+
+    writeOps.flushWindow(core as unknown as FsCore)
+
+    expect(respond).toHaveBeenCalledWith({ ok: true, result: { gen: 3, rev: 3, cpId: 'c1' } })
+    // A retry replay answers from this entry verbatim — a {gen}-only cache
+    // would hand the client a checkpoint result with no cpId.
+    expect(core.opIds.get('op-c1')).toEqual({ gen: 3, rev: 3, cpId: 'c1' })
+  })
+
+  it('caches a turnBegin windowOp as {gen, rev, turnId, cpId, expiresAt}', () => {
+    const respond = vi.fn()
+    const extra = { turnId: 't-1', cpId: 'cp-9', expiresAt: 4200 }
+    const core = makeFlushCore([{ respond, gen: 6, actor: 'agent', opId: 'op-t1', extra }])
+
+    writeOps.flushWindow(core as unknown as FsCore)
+
+    expect(respond).toHaveBeenCalledWith({ ok: true, result: { gen: 6, rev: 6, ...extra } })
+    expect(core.opIds.get('op-t1')).toEqual({ gen: 6, rev: 6, ...extra })
+  })
+
+  it('caches a plain write windowOp (no extra) as {gen, rev}', () => {
+    const respond = vi.fn()
+    const core = makeFlushCore([{ respond, gen: 4, path: 'a.txt', actor: 'human', opId: 'op-w1' }])
+
+    writeOps.flushWindow(core as unknown as FsCore)
+
+    expect(respond).toHaveBeenCalledWith({ ok: true, result: { gen: 4, rev: 4 } })
+    expect(core.opIds.get('op-w1')).toEqual({ gen: 4, rev: 4 })
+  })
+})
+
+interface FakeRestoreCore {
+  mode: string
+  flushWindow: () => void
+  rotateIfNeeded: () => Promise<void>
+  checkpoints: Map<string, { h: string; gen: number }>
+  readBlob: (h: string) => Promise<string>
+  appendSync: (opcode: number, meta: Record<string, unknown>, checks?: () => void) => number
+  checkTurn: (actor: string | undefined, turnId: string | undefined, agentToken: string | undefined) => void
+  checkRestoreConflict: (baseGen: number) => void
+  walHandle: { flush: () => void }
+  walGen: number
+  memGen: number
+  ackGen: number
+  mirror: Map<string, unknown>
+  opIds: Map<string, { gen: number }>
+  rememberOpId: (opId: string, v: { gen: number }) => void
+  pushFullToQuery: () => void
+  event: (e: unknown) => void
+  bc: { postMessage: (msg: unknown) => void }
+}
+
+/** Two files in the checkpoint manifest — opRestore's live respond carries
+ * restored: 2, and the replay cache must preserve it. */
+function makeRestoreCore(): FakeRestoreCore {
+  const manifest: Record<string, string> = { 'a.txt': 'h-a', 'b.txt': 'h-b' }
+  const core: FakeRestoreCore = {
+    mode: 'writer',
+    flushWindow: vi.fn(),
+    rotateIfNeeded: vi.fn(async () => {}),
+    checkpoints: new Map([['cp-1', { h: 'h-manifest', gen: 5 }]]),
+    readBlob: vi.fn(async (h: string) => (h === 'h-manifest' ? JSON.stringify(manifest) : 'content-of-' + h)),
+    appendSync: vi.fn((_opcode: number, _meta: Record<string, unknown>, checks?: () => void) => {
+      checks?.()
+      return 7
+    }),
+    checkTurn: vi.fn(),
+    checkRestoreConflict: vi.fn(),
+    walHandle: { flush: vi.fn() },
+    walGen: 0,
+    memGen: 0,
+    ackGen: 0,
+    mirror: new Map(),
+    opIds: new Map(),
+    rememberOpId: (opId, v) => writeOps.rememberOpId(core as unknown as FsCore, opId, v),
+    pushFullToQuery: vi.fn(),
+    event: vi.fn(),
+    bc: { postMessage: vi.fn() },
+  }
+  return core
+}
+
+describe('opRestore — opId replay cache stores the full respond result', () => {
+  it('caches a restore as {gen, restored}, matching what the live respond delivered', async () => {
+    const core = makeRestoreCore()
+    const respond: Respond = vi.fn()
+
+    await writeOps.opRestore(core as unknown as FsCore, { cpId: 'cp-1', actor: 'human', opId: 'op-r1' }, respond)
+
+    expect(respond).toHaveBeenCalledWith({ ok: true, result: { gen: 7, restored: 2 } })
+    // A retry replay answers from this entry verbatim — a {gen}-only cache
+    // would hand the client a restore result with no restored count.
+    expect(core.opIds.get('op-r1')).toEqual({ gen: 7, restored: 2 })
+  })
+})