@dimina-kit/fs-core 0.2.0-dev.20260710085051

package/dist/zip.js

@@ -0,0 +1,60 @@
+/**
+ * store-only ZIP 打包（P5 导出出口）—— 无压缩、无依赖，全浏览器可用。
+ * 项目导出走"另一介质"才真正提升持久等级；zip 是最低门槛的那条出口。
+ */
+import { crc32 } from './worker-lib/wal-codec.js';
+const enc = new TextEncoder();
+/** files: {relPath: string content} → Uint8Array（ZIP，UTF-8 文件名）。 */
+export function makeZip(files) {
+    const parts = [];
+    const central = [];
+    let offset = 0;
+    for (const [path, content] of Object.entries(files)) {
+        const name = enc.encode(path);
+        const data = enc.encode(content);
+        const crc = crc32(data);
+        const local = new Uint8Array(30 + name.length);
+        const lv = new DataView(local.buffer);
+        lv.setUint32(0, 0x04034b50, true); // local file header
+        lv.setUint16(4, 20, true); // version needed
+        lv.setUint16(6, 0x0800, true); // flags: UTF-8 names
+        lv.setUint16(8, 0, true); // method: store
+        lv.setUint32(14, crc, true);
+        lv.setUint32(18, data.length, true);
+        lv.setUint32(22, data.length, true);
+        lv.setUint16(26, name.length, true);
+        local.set(name, 30);
+        parts.push(local, data);
+        const cd = new Uint8Array(46 + name.length);
+        const cv = new DataView(cd.buffer);
+        cv.setUint32(0, 0x02014b50, true); // central directory header
+        cv.setUint16(4, 20, true);
+        cv.setUint16(6, 20, true);
+        cv.setUint16(8, 0x0800, true);
+        cv.setUint16(10, 0, true);
+        cv.setUint32(16, crc, true);
+        cv.setUint32(20, data.length, true);
+        cv.setUint32(24, data.length, true);
+        cv.setUint16(28, name.length, true);
+        cv.setUint32(42, offset, true); // local header offset
+        cd.set(name, 46);
+        central.push(cd);
+        offset += local.length + data.length;
+    }
+    const cdSize = central.reduce((s, c) => s + c.length, 0);
+    const eocd = new Uint8Array(22);
+    const ev = new DataView(eocd.buffer);
+    ev.setUint32(0, 0x06054b50, true);
+    ev.setUint16(8, central.length, true);
+    ev.setUint16(10, central.length, true);
+    ev.setUint32(12, cdSize, true);
+    ev.setUint32(16, offset, true);
+    const total = offset + cdSize + 22;
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const p of [...parts, ...central, eocd]) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@dimina-kit/fs-core",
+  "version": "0.2.0-dev.20260710085051",
+  "description": "Zero-dependency OPFS WAL filesystem core for the web, with an agent capability gate.",
+  "keywords": [
+    "dimina",
+    "opfs",
+    "filesystem",
+    "wal",
+    "agent"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "author": "EchoTechFE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EchoTechFE/dimina-kit.git",
+    "directory": "packages/fs-core"
+  },
+  "bugs": {
+    "url": "https://github.com/EchoTechFE/dimina-kit/issues"
+  },
+  "homepage": "https://github.com/EchoTechFE/dimina-kit/tree/main/packages/fs-core#readme",
+  "exports": {
+    "./client": {
+      "types": "./src/client.ts",
+      "default": "./dist/client.js"
+    },
+    "./agent-tools": {
+      "types": "./src/agent-tools.ts",
+      "default": "./dist/agent-tools.js"
+    },
+    "./disk-mirror": {
+      "types": "./src/disk-mirror.ts",
+      "default": "./dist/disk-mirror.js"
+    },
+    "./zip": {
+      "types": "./src/zip.ts",
+      "default": "./dist/zip.js"
+    },
+    "./sync": {
+      "types": "./sync/sync-engine.ts",
+      "default": "./dist/sync/sync-engine.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "sync"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.4",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.2.1",
+    "typescript": "5.9.2",
+    "vitest": "^4.1.4",
+    "@dimina-kit/eslint-config": "0.1.0",
+    "@dimina-kit/typescript-config": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.sync.build.json && node build-workers.js",
+    "check-types": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.worker.json",
+    "lint": "eslint . --max-warnings 0",
+    "test": "vitest run --reporter=default --reporter=json --outputFile.json=test-report.json --coverage.enabled --coverage.reporter=json-summary --coverage.reportsDirectory=coverage",
+    "test:dev": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/__checks__/types-smoke.ts

@@ -0,0 +1,23 @@
+/**
+ * Type-consumption smoke check: guards that the package.json `exports` map
+ * resolves `types` for all four public subpaths (not just `default`).
+ * Not a runtime test — only needs to satisfy `tsc --noEmit`.
+ */
+import type { ProjectFsClient } from '@dimina-kit/fs-core/client'
+import type { AgentTool, AgentToolsFs } from '@dimina-kit/fs-core/agent-tools'
+import { createAgentTools } from '@dimina-kit/fs-core/agent-tools'
+import type { DiskMirrorFs } from '@dimina-kit/fs-core/disk-mirror'
+import { createDiskMirror } from '@dimina-kit/fs-core/disk-mirror'
+import { makeZip } from '@dimina-kit/fs-core/zip'
+
+export function typesSmoke(client: ProjectFsClient, fs: AgentToolsFs & DiskMirrorFs): {
+  tool: AgentTool | undefined
+  zip: Uint8Array
+  mirrorActive: boolean
+} {
+  const agent = createAgentTools(fs)
+  const mirror = createDiskMirror(fs)
+  const zip = makeZip({ 'a.txt': 'hello' })
+  void client.projectId
+  return { tool: agent.byName.fs_read, zip, mirrorActive: mirror.active }
+}

package/src/agent-tools.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createAgentTools } from './agent-tools.js'
+
+/** Hand-written mock shaped like ProjectFsClient's public surface. Every
+ * method is a vi.fn() so tests can assert on the exact args it receives,
+ * and returns a distinguishable sentinel value so tests can assert the
+ * tool's execute() forwards the fs call's result untouched. */
+function createMockFs() {
+  return {
+    read: vi.fn(async (path: string) => ({ content: `content:${path}`, rev: 1 })),
+    ls: vi.fn(async () => ({ paths: ['a.txt'] })),
+    glob: vi.fn(async (pattern: string) => ({ paths: [pattern] })),
+    grep: vi.fn(async () => ({ hits: [] })),
+    write: vi.fn(async () => ({ rev: 2 })),
+    edit: vi.fn(async () => ({ rev: 3 })),
+    mv: vi.fn(async () => ({ ok: true })),
+    rm: vi.fn(async () => ({ ok: true })),
+    checkpoint: vi.fn(async () => ({ cpId: 'cp-1' })),
+    restore: vi.fn(async () => ({ ok: true })),
+    diff: vi.fn(async (turnId?: string) => ({ changes: [], turnId })),
+    turnBegin: vi.fn(async (_turnId: string, _opts?: Record<string, unknown>) => ({ cpId: 'cp-0', expiresAt: 1234 })),
+    turnEnd: vi.fn(async () => ({ closed: true })),
+  }
+}
+
+describe('createAgentTools', () => {
+  it('exposes exactly the ten tools by their documented names, each with a description, inputSchema, and execute', () => {
+    const { tools, byName } = createAgentTools(createMockFs())
+    const names = tools.map((t) => t.name).sort()
+    expect(names).toEqual(
+      ['fs_checkpoint', 'fs_diff', 'fs_edit', 'fs_glob', 'fs_grep', 'fs_ls', 'fs_mv', 'fs_read', 'fs_restore', 'fs_rm', 'fs_write'].sort(),
+    )
+    for (const t of tools) {
+      expect(byName[t.name]).toBe(t)
+      expect(typeof t.description).toBe('string')
+      expect(t.description.length).toBeGreaterThan(0)
+      expect(t.inputSchema).toBeTruthy()
+      expect(typeof t.execute).toBe('function')
+    }
+  })
+
+  it('marks only fs_restore as dangerous', () => {
+    const { tools } = createAgentTools(createMockFs())
+    for (const t of tools) {
+      if (t.name === 'fs_restore') expect(t.dangerous).toBe(true)
+      else expect(t.dangerous).toBeUndefined()
+    }
+  })
+
+  it('mints a fresh t-<base36>-<seq> turnId on beginTurn, forwards opts to fs.turnBegin, and merges its result', async () => {
+    const fs = createMockFs()
+    const agent = createAgentTools(fs)
+    const result = await agent.beginTurn({ reason: 'test' })
+    expect(fs.turnBegin).toHaveBeenCalledTimes(1)
+    const [turnIdArg, optsArg] = fs.turnBegin.mock.calls[0]!
+    expect(turnIdArg).toMatch(/^t-[0-9a-z]+-\d+$/)
+    expect(optsArg).toEqual({ reason: 'test' })
+    expect(result.turnId).toBe(turnIdArg)
+    expect(result.cpId).toBe('cp-0')
+    expect(result.expiresAt).toBe(1234)
+    expect(agent.activeTurn).toBe(turnIdArg)
+  })
+
+  it('returns {closed:false} without calling fs.turnEnd when there is no active turn', async () => {
+    const fs = createMockFs()
+    const { endTurn } = createAgentTools(fs)
+    const result = await endTurn()
+    expect(result).toEqual({ closed: false })
+    expect(fs.turnEnd).not.toHaveBeenCalled()
+  })
+
+  it('calls fs.turnEnd with the active turnId, clears activeTurn, and returns its result when a turn is active', async () => {
+    const fs = createMockFs()
+    const agent = createAgentTools(fs)
+    const { turnId } = await agent.beginTurn()
+    const result = await agent.endTurn()
+    expect(fs.turnEnd).toHaveBeenCalledExactlyOnceWith(turnId)
+    expect(result).toEqual({ closed: true })
+    expect(agent.activeTurn).toBeNull()
+  })
+
+  it('injects {actor:"agent", turnId:activeTurn} into fs.write, overriding any turnId the caller tries to pass', async () => {
+    const fs = createMockFs()
+    const agent = createAgentTools(fs)
+    const { turnId } = await agent.beginTurn()
+    await agent.byName.fs_write!.execute({ path: 'a.txt', content: 'hi', turnId: 'forged-turn' })
+    expect(fs.write).toHaveBeenCalledExactlyOnceWith('a.txt', 'hi', { actor: 'agent', turnId, ifMatch: undefined })
+  })
+
+  it('injects actor/turnId into every other write tool (edit, mv, rm, checkpoint, restore)', async () => {
+    const fs = createMockFs()
+    const agent = createAgentTools(fs)
+    const { turnId } = await agent.beginTurn()
+
+    await agent.byName.fs_edit!.execute({ path: 'a.txt', old: 'x', next: 'y' })
+    expect(fs.edit).toHaveBeenCalledExactlyOnceWith('a.txt', 'x', 'y', { actor: 'agent', turnId })
+
+    await agent.byName.fs_mv!.execute({ from: 'a.txt', to: 'b.txt' })
+    expect(fs.mv).toHaveBeenCalledExactlyOnceWith('a.txt', 'b.txt', { actor: 'agent', turnId })
+
+    await agent.byName.fs_rm!.execute({ path: 'a.txt' })
+    expect(fs.rm).toHaveBeenCalledExactlyOnceWith('a.txt', { actor: 'agent', turnId })
+
+    await agent.byName.fs_checkpoint!.execute({})
+    expect(fs.checkpoint).toHaveBeenCalledExactlyOnceWith({ actor: 'agent', turnId })
+
+    await agent.byName.fs_restore!.execute({ cpId: 'cp-1', force: true })
+    expect(fs.restore).toHaveBeenCalledExactlyOnceWith('cp-1', { actor: 'agent', turnId, force: true })
+  })
+
+  it('injects turnId:null (no actor forgery possible) when a write tool is invoked with no active turn', async () => {
+    const fs = createMockFs()
+    const { byName } = createAgentTools(fs)
+    await byName.fs_write!.execute({ path: 'a.txt', content: 'hi' })
+    expect(fs.write).toHaveBeenCalledExactlyOnceWith('a.txt', 'hi', { actor: 'agent', turnId: null, ifMatch: undefined })
+  })
+
+  it('forwards read tool args to fs without injecting actor or turnId', async () => {
+    const fs = createMockFs()
+    const agent = createAgentTools(fs)
+    await agent.beginTurn()
+
+    await agent.byName.fs_read!.execute({ path: 'a.txt' })
+    expect(fs.read).toHaveBeenCalledExactlyOnceWith('a.txt')
+
+    await agent.byName.fs_ls!.execute({})
+    expect(fs.ls).toHaveBeenCalledExactlyOnceWith()
+
+    await agent.byName.fs_glob!.execute({ pattern: '*.ts' })
+    expect(fs.glob).toHaveBeenCalledExactlyOnceWith('*.ts')
+
+    await agent.byName.fs_grep!.execute({ pattern: 'foo', glob: '*.ts', limit: 5 })
+    expect(fs.grep).toHaveBeenCalledExactlyOnceWith('foo', { glob: '*.ts', limit: 5 })
+  })
+
+  it('defaults fs_diff turnId to activeTurn when no turnId argument is passed', async () => {
+    const fs = createMockFs()
+    const agent = createAgentTools(fs)
+    const { turnId } = await agent.beginTurn()
+    await agent.byName.fs_diff!.execute()
+    expect(fs.diff).toHaveBeenCalledExactlyOnceWith(turnId)
+  })
+
+  it('lets fs_diff use an explicitly passed turnId instead of activeTurn', async () => {
+    const fs = createMockFs()
+    const agent = createAgentTools(fs)
+    await agent.beginTurn()
+    await agent.byName.fs_diff!.execute({ turnId: 'other-turn' })
+    expect(fs.diff).toHaveBeenCalledExactlyOnceWith('other-turn')
+  })
+})

package/src/agent-tools.ts

@@ -0,0 +1,117 @@
+/**
+ * Agent 工具面（P4）—— MCP 形状的工具表包装 ProjectFsClient。
+ *
+ * 设计对应架构文档 §13：Agent 拿到的不是裸 FS，而是这张工具表 +（宿主铸造的）
+ * turn 能力。要点：
+ *  - execute 自动注入 {actor:'agent', turnId}：turnId 由 beginTurn 铸造并闭包持有，
+ *    不出现在工具参数里 —— 模型伪造不了别的 turn。
+ *  - 真正的执法在 fs-core（checkTurn 与 WAL append 同一同步块）；这里只是便利面。
+ *  - inputSchema 用简化记法（K2 交付 Agent 组时再换成正式 JSON Schema + MCP server 包装）。
+ *  - fs_read 返回完整内容，绝不截断（上游 8000 字符腰斩教训）。
+ *
+ * `AgentToolsFs` only declares the methods this file actually calls on the
+ * ProjectFsClient handle it's given (structurally, so any object shaped like
+ * it — including test mocks — works without importing the concrete class).
+ */
+export interface AgentToolsFs {
+  read(path: string): unknown
+  ls(): unknown
+  glob(pattern: string): unknown
+  grep(pattern: string, opts?: Record<string, unknown>): unknown
+  write(path: string, content: string, opts?: Record<string, unknown>): unknown
+  edit(path: string, old: string, next: string, opts?: Record<string, unknown>): unknown
+  mv(from: string, to: string, opts?: Record<string, unknown>): unknown
+  rm(path: string, opts?: Record<string, unknown>): unknown
+  checkpoint(opts?: Record<string, unknown>): unknown
+  restore(cpId: string, opts?: Record<string, unknown>): unknown
+  diff(turnId?: string): unknown
+  turnBegin(turnId: string, opts?: Record<string, unknown>): Promise<Record<string, unknown>>
+  turnEnd(turnId: string): unknown
+}
+
+export interface AgentTool {
+  name: string
+  description: string
+  inputSchema: unknown
+  // Method shorthand (not an arrow-typed property): TS checks method members
+  // bivariantly, so each tool below can implement `execute` with its own
+  // narrower, concrete parameter shape (e.g. `({ path }: { path: string })`)
+  // instead of every implementation having to accept `unknown[]` directly.
+  execute(...args: unknown[]): unknown
+  dangerous?: boolean
+}
+
+export function createAgentTools(fs: AgentToolsFs): {
+  tools: AgentTool[]
+  byName: Record<string, AgentTool>
+  beginTurn(opts?: Record<string, unknown>): Promise<{ turnId: string } & Record<string, unknown>>
+  endTurn(): Promise<unknown>
+  readonly activeTurn: string | null
+} {
+  let turnSeq = 0
+  let activeTurn: string | null = null
+
+  /** 铸造一轮写能力：fs-core 侧自动打 checkpoint 锚（返回 {cpId, expiresAt}）。 */
+  async function beginTurn(opts: Record<string, unknown> = {}) {
+    const turnId = 't-' + Date.now().toString(36) + '-' + ++turnSeq
+    const r = await fs.turnBegin(turnId, opts)
+    activeTurn = turnId
+    return { turnId, ...r }
+  }
+
+  /** 结束（撤销）当前 turn；之后任何 agent 写都会被 fs-core 拒绝（turn-closed）。 */
+  async function endTurn() {
+    if (!activeTurn) return { closed: false }
+    const turnId = activeTurn
+    activeTurn = null
+    return fs.turnEnd(turnId)
+  }
+
+  const agentOpts = () => ({ actor: 'agent', turnId: activeTurn })
+  // E is inferred fresh per call from whatever concrete `execute` is passed
+  // (e.g. `({ path }: { path: string }) => …`) rather than checked against one
+  // fixed function type, so each tool below keeps its own narrow parameter
+  // shape; assigning it into the returned object's `execute` member is safe
+  // because AgentTool.execute is a method (bivariant), not an arrow-typed
+  // property.
+  function T<E extends (...args: never[]) => unknown>(name: string, description: string, inputSchema: unknown, execute: E, extra?: Record<string, unknown>): AgentTool {
+    return { name, description, inputSchema, execute, ...extra }
+  }
+
+  const tools: AgentTool[] = [
+    // 读/查询（路由 fs-query，不占写路径）
+    T('fs_read', '读文件，返回完整内容与版本 rev（绝不截断）', { path: 'string' },
+      ({ path }: { path: string }) => fs.read(path)),
+    T('fs_ls', '列出项目全部文件路径', {},
+      () => fs.ls()),
+    T('fs_glob', '按 glob 模式匹配文件路径', { pattern: 'string' },
+      ({ pattern }: { pattern: string }) => fs.glob(pattern)),
+    T('fs_grep', '按正则搜索文件内容，返回 {path, lineNo, line} 命中行', { pattern: 'string', glob: 'string?', limit: 'number?' },
+      ({ pattern, ...o }: { pattern: string; [k: string]: unknown }) => fs.grep(pattern, o)),
+    // 写（fs-core 执法：必须在有效 turn 内）
+    T('fs_write', '写整文件；可带 ifMatch(rev) 做 CAS 前置校验', { path: 'string', content: 'string', ifMatch: 'number?' },
+      ({ path, content, ifMatch }: { path: string; content: string; ifMatch?: number }) => fs.write(path, content, { ...agentOpts(), ifMatch })),
+    T('fs_edit', '精确替换：old 在文件中必须唯一匹配', { path: 'string', old: 'string', next: 'string' },
+      ({ path, old, next }: { path: string; old: string; next: string }) => fs.edit(path, old, next, agentOpts())),
+    T('fs_mv', '移动/重命名文件', { from: 'string', to: 'string' },
+      ({ from, to }: { from: string; to: string }) => fs.mv(from, to, agentOpts())),
+    T('fs_rm', '删除文件', { path: 'string' },
+      ({ path }: { path: string }) => fs.rm(path, agentOpts())),
+    // 回滚面
+    T('fs_checkpoint', '手动创建快照锚点（turn 开始时已自动有一个）', {},
+      () => fs.checkpoint(agentOpts())),
+    T('fs_restore', '回滚到指定 checkpoint（本身是一条可再撤销的写）；若 checkpoint 之后有人类编辑，默认拒绝并返回 restore-conflict{humanPaths}，需 force:true 确认覆盖', { cpId: 'string', force: 'boolean?' },
+      ({ cpId, force }: { cpId: string; force?: boolean }) => fs.restore(cpId, { ...agentOpts(), force }),
+      { dangerous: true }),
+    T('fs_diff', '列出某轮 turn 的全部改动（默认当前 turn）', { turnId: 'string?' },
+      ({ turnId }: { turnId?: string } = {}) => fs.diff(turnId ?? activeTurn ?? undefined)),
+  ]
+
+  return {
+    tools,
+    byName: Object.fromEntries(tools.map((t) => [t.name, t])),
+    beginTurn,
+    endTurn,
+    get activeTurn() { return activeTurn },
+  }
+}

package/src/client.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Unit tests for ProjectFsClient's writer-mode bookkeeping (`mode` / `onModeChange`).
+ * `connect()` itself needs a real Worker + OPFS + navigator.locks environment (only
+ * exercised by real-browser e2e probes), so these construct a bare `ProjectFsClient`
+ * instance and drive its internal `_onCoreMessage` dispatcher directly with the exact
+ * message shapes fs-core.worker.js sends (WELCOME / writer-granted / writer-lost / FATAL),
+ * matching what a real core→client MessagePort would deliver.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { ProjectFsClient } from './client.js'
+
+type Mode = 'starting' | 'writer' | 'readonly' | 'draining' | 'dead'
+type CoreEvent = { type?: string; evt?: string; error?: string; mode?: Mode; readonly?: boolean; gen?: number }
+
+/** Structural view of the internals `_onCoreMessage`/`_setMode` touch — not exposed
+ * on the public `ProjectFsClient` d.ts surface, so tests reach in via this narrow cast
+ * instead of `any`/`@ts-expect-error` sprinkled at every call site. */
+type ClientInternals = ProjectFsClient & {
+  changeCbs: Set<(evt: CoreEvent) => void>
+  modeCbs: Set<(mode: Mode) => void>
+  pending: Map<number, unknown>
+  _mode: Mode
+  _onCoreMessage(msg: CoreEvent, resolveWelcome?: (w: CoreEvent) => void, rejectWelcome?: (e: Error) => void): void
+  _setMode(mode: Mode): void
+}
+
+/** Builds a client instance with just the fields `_onCoreMessage`/`_setMode` touch,
+ * skipping the real `connect()` (Worker/OPFS/locks) entirely. */
+function makeBareClient(initialMode: Mode = 'starting'): ClientInternals {
+  const c = new ProjectFsClient() as unknown as ClientInternals
+  c.changeCbs = new Set()
+  c.modeCbs = new Set()
+  c.pending = new Map()
+  c._mode = initialMode
+  return c
+}
+
+describe('ProjectFsClient writer mode', () => {
+  it('adopts mode from WELCOME, mirroring what connect() does post-await', () => {
+    const c = makeBareClient()
+    let welcome: CoreEvent | undefined
+    c._onCoreMessage({ type: 'WELCOME', mode: 'writer', readonly: false }, (w) => { welcome = w })
+    expect(welcome?.mode).toBe('writer')
+    // connect() does: c._setMode(c.welcome.mode || (c.welcome.readonly ? 'readonly' : 'writer'))
+    c._setMode(welcome!.mode || (welcome!.readonly ? 'readonly' : 'writer'))
+    expect(c.mode).toBe('writer')
+  })
+
+  it('writer-granted flips mode to writer and notifies onModeChange subscribers', () => {
+    const c = makeBareClient('readonly')
+    const cb = vi.fn()
+    const unsubscribe = c.onModeChange(cb)
+
+    c._onCoreMessage({ evt: 'writer-granted', gen: 5 })
+
+    expect(c.mode).toBe('writer')
+    expect(cb).toHaveBeenCalledWith('writer')
+    expect(cb).toHaveBeenCalledTimes(1)
+
+    unsubscribe()
+    c._onCoreMessage({ evt: 'writer-lost', gen: 6 })
+    expect(cb).toHaveBeenCalledTimes(1) // unsubscribed — no further calls
+  })
+
+  it('writer-lost flips mode to readonly', () => {
+    const c = makeBareClient('writer')
+    const cb = vi.fn()
+    c.onModeChange(cb)
+
+    c._onCoreMessage({ evt: 'writer-lost', gen: 6 })
+
+    expect(c.mode).toBe('readonly')
+    expect(cb).toHaveBeenCalledWith('readonly')
+  })
+
+  it('does not notify subscribers when the mode is unchanged', () => {
+    const c = makeBareClient('writer')
+    const cb = vi.fn()
+    c.onModeChange(cb)
+
+    c._onCoreMessage({ evt: 'writer-granted', gen: 7 }) // already writer — no-op transition
+
+    expect(c.mode).toBe('writer')
+    expect(cb).not.toHaveBeenCalled()
+  })
+
+  it('FATAL flips mode to dead', () => {
+    const c = makeBareClient('writer')
+    const cb = vi.fn()
+    c.onModeChange(cb)
+
+    // mirrors self.postMessage({type:'FATAL', error}) in the worker
+    c._onCoreMessage({ type: 'FATAL', error: 'boom' })
+
+    expect(c.mode).toBe('dead')
+    expect(cb).toHaveBeenCalledWith('dead')
+  })
+
+  it('still delivers evt messages to onChange subscribers alongside mode updates', () => {
+    const c = makeBareClient('readonly')
+    const changeCb = vi.fn()
+    c.onChange(changeCb)
+
+    const msg: CoreEvent = { evt: 'writer-granted', gen: 9 }
+    c._onCoreMessage(msg)
+
+    expect(changeCb).toHaveBeenCalledWith(msg)
+    expect(c.mode).toBe('writer')
+  })
+})