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

package/src/fs-query.worker.ts

@@ -0,0 +1,152 @@
+/**
+ * fs-query worker — ProjectFS 只读镜像。
+ * fs-core 经专用 MessagePort 推 {gen, diff|full}；本 worker 承接 snapshot/grep/glob/大读，
+ * 查询永不进入写路径（fs-core 的事件循环不被大 grep 阻塞）。镜像无持久状态，可随时重建。
+ */
+
+interface MirrorEntry {
+  content: string
+  rev?: number
+}
+
+interface QueryOpError extends Error {
+  code?: string
+}
+
+interface SyncMsg {
+  gen: number
+  full?: boolean
+  files?: Record<string, MirrorEntry>
+  diff?: Record<string, MirrorEntry | null>
+}
+
+interface Waiter {
+  gen: number
+  resolve: () => void
+  timer: ReturnType<typeof setTimeout>
+}
+
+const state: {
+  mirror: Map<string, MirrorEntry>
+  gen: number
+  waiters: Waiter[]
+} = {
+  mirror: new Map(), // path -> {content, rev}
+  gen: -1,           // -1 = 尚未收到 core 的首次同步
+  waiters: [],       // [{gen, resolve, timer}]
+}
+
+function applySync(msg: SyncMsg): void {
+  if (msg.full) {
+    state.mirror.clear()
+    for (const [p, ent] of Object.entries(msg.files || {})) state.mirror.set(p, ent)
+  } else {
+    for (const [p, ent] of Object.entries(msg.diff || {})) {
+      if (ent === null) state.mirror.delete(p)
+      else state.mirror.set(p, ent)
+    }
+  }
+  state.gen = msg.gen
+  state.waiters = state.waiters.filter((w) => {
+    if (state.gen >= w.gen) { clearTimeout(w.timer); w.resolve(); return false }
+    return true
+  })
+}
+
+/** 等镜像追平 gen；超时则按当前 gen 返回（结果带 stale 标记）。 */
+function whenGen(gen: number | undefined): Promise<void> {
+  if (gen === undefined || state.gen >= gen) return Promise.resolve()
+  return new Promise((resolve) => {
+    const w: Waiter = { gen, resolve, timer: setTimeout(() => { state.waiters = state.waiters.filter((x) => x !== w); resolve() }, 5000) }
+    state.waiters.push(w)
+  })
+}
+
+const GLOB_SPECIAL_RE = /[.+^${}()|[\]\\]/
+
+/** Translates the glob token starting at `pattern[i]`; returns the regex
+ * fragment plus how many EXTRA characters (beyond the one at `i`) it consumed,
+ * so the caller's loop index can skip over a consumed double-star (with or
+ * without a trailing slash). */
+function translateGlobToken(pattern: string, i: number): { token: string; skip: number } {
+  const c = pattern[i]
+  if (c === '*') {
+    if (pattern[i + 1] === '*') {
+      const slash = pattern[i + 2] === '/'
+      return { token: slash ? '(?:.*/)?' : '.*', skip: slash ? 2 : 1 }
+    }
+    return { token: '[^/]*', skip: 0 }
+  }
+  if (c === '?') return { token: '[^/]', skip: 0 }
+  const escaped = GLOB_SPECIAL_RE.test(c!) ? '\\' + c : c!
+  return { token: escaped, skip: 0 }
+}
+
+function globToRegExp(pattern: string): RegExp {
+  let re = ''
+  for (let i = 0; i < pattern.length; i++) {
+    const { token, skip } = translateGlobToken(pattern, i)
+    re += token
+    i += skip
+  }
+  return new RegExp('^' + re + '$')
+}
+
+const ops = {
+  async snapshot({ gen }: { gen?: number }) {
+    await whenGen(gen)
+    const files: Record<string, string> = {}
+    for (const [p, ent] of state.mirror) files[p] = ent.content
+    return { files, gen: state.gen, stale: gen !== undefined && state.gen < gen }
+  },
+  async read({ path, gen }: { path: string; gen?: number }) {
+    await whenGen(gen)
+    const e = state.mirror.get(path)
+    if (!e) throw Object.assign(new Error(path), { code: 'not-found' })
+    return { content: e.content, rev: e.rev, gen: state.gen }
+  },
+  async glob({ pattern, gen }: { pattern: string; gen?: number }) {
+    await whenGen(gen)
+    const re = globToRegExp(pattern)
+    return { paths: [...state.mirror.keys()].filter((p) => re.test(p)).sort(), gen: state.gen }
+  },
+  async grep({ pattern, flags = '', glob, gen, limit = 200 }: { pattern: string; flags?: string; glob?: string; gen?: number; limit?: number }) {
+    await whenGen(gen)
+    const re = new RegExp(pattern, flags.replace('g', ''))
+    const scope = glob ? globToRegExp(glob) : null
+    const hits: Array<{ path: string; lineNo: number; line: string }> = []
+    for (const [path, ent] of state.mirror) {
+      if (scope && !scope.test(path)) continue
+      const lines = ent.content.split('\n')
+      for (let i = 0; i < lines.length; i++) {
+        if (re.test(lines[i]!)) {
+          hits.push({ path, lineNo: i + 1, line: lines[i]!.slice(0, 500) })
+          if (hits.length >= limit) return { hits, gen: state.gen, truncated: true }
+        }
+      }
+    }
+    return { hits, gen: state.gen, truncated: false }
+  },
+}
+
+self.onmessage = async (e: MessageEvent) => {
+  const msg = e.data
+  if (msg.type === 'init') {
+    msg.corePort.onmessage = (ev: MessageEvent) => applySync(ev.data)
+    self.postMessage({ type: 'ready' })
+    return
+  }
+  if (msg.id === undefined) return
+  try {
+    // ops's members are declared via method shorthand with their own distinct
+    // arg shapes; dispatching by dynamic string key needs one widening cast —
+    // through `unknown` since the concrete shapes don't structurally overlap
+    // with a single dynamic-args signature.
+    const dispatch = ops as unknown as Record<string, (args: Record<string, unknown>) => Promise<unknown>>
+    const result = await dispatch[msg.op]!(msg.args || {})
+    self.postMessage({ id: msg.id, ok: true, result })
+  } catch (err) {
+    const e = err as QueryOpError
+    self.postMessage({ id: msg.id, ok: false, code: e.code || 'internal', error: e.message || String(err) })
+  }
+}

package/src/import-smoke.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+
+/** Guards that none of the four public entry points touch a browser-only
+ * global (navigator.storage, Worker, showDirectoryPicker, ...) merely by
+ * being imported — those APIs are only allowed to be touched when their
+ * exported functions/classes are actually invoked. This suite runs under
+ * plain Node with no jsdom globals, so any import-time access would throw. */
+describe('public entry points import cleanly under plain Node', () => {
+  it('imports client.js and exposes the ProjectFsClient class with its static/instance API', async () => {
+    const mod = await import('./client.js')
+    expect(typeof mod.ProjectFsClient).toBe('function')
+    expect(typeof mod.ProjectFsClient.connect).toBe('function')
+    expect(typeof mod.ProjectFsClient.wipe).toBe('function')
+    expect(typeof mod.ProjectFsClient.prototype.write).toBe('function')
+    expect(typeof mod.ProjectFsClient.prototype.read).toBe('function')
+  })
+
+  it('imports agent-tools.js and exposes createAgentTools as a function', async () => {
+    const mod = await import('./agent-tools.js')
+    expect(typeof mod.createAgentTools).toBe('function')
+  })
+
+  it('imports disk-mirror.js and exposes createDiskMirror as a function', async () => {
+    const mod = await import('./disk-mirror.js')
+    expect(typeof mod.createDiskMirror).toBe('function')
+  })
+
+  it('imports zip.js and exposes makeZip as a function', async () => {
+    const mod = await import('./zip.js')
+    expect(typeof mod.makeZip).toBe('function')
+  })
+
+  it('does not touch navigator.storage, Worker, or showDirectoryPicker in this Node environment', () => {
+    // Node itself defines a minimal `navigator` global (userAgent info only);
+    // it has no `storage` property, unlike a real browser's OPFS-capable one.
+    expect((globalThis.navigator as { storage?: unknown } | undefined)?.storage).toBeUndefined()
+    expect(typeof (globalThis as { Worker?: unknown }).Worker).toBe('undefined')
+    expect(typeof (globalThis as { showDirectoryPicker?: unknown }).showDirectoryPicker).toBe('undefined')
+  })
+})

package/src/worker-lib/engine-shared.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest'
+import { epochFloor, rpcErr } from './engine-shared.js'
+import type { WalRecord } from './wal-codec.js'
+
+describe('rpcErr', () => {
+  it('builds an Error carrying a code', () => {
+    const e = rpcErr('not-found', 'missing thing')
+    expect(e).toBeInstanceOf(Error)
+    expect(e.message).toBe('missing thing')
+    expect(e.code).toBe('not-found')
+    expect(e.extra).toBeUndefined()
+  })
+
+  it('attaches optional extra fields', () => {
+    const e = rpcErr('restore-conflict', 'boom', { humanPaths: ['a.txt'] })
+    expect(e.extra).toEqual({ humanPaths: ['a.txt'] })
+  })
+})
+
+describe('epochFloor', () => {
+  const rec = (epoch: number): WalRecord => ({ gen: 1, epoch, opcode: 1, meta: {} })
+
+  it('returns 0 for an empty replay list (epoch floor before anything replayed)', () => {
+    expect(epochFloor([])).toBe(0)
+  })
+
+  it('returns the last replayed record\'s epoch', () => {
+    expect(epochFloor([rec(0), rec(2), rec(2)])).toBe(2)
+  })
+})

package/src/worker-lib/engine-shared.ts

@@ -0,0 +1,74 @@
+/**
+ * fs-core 引擎共享定义（lib 中立）—— opcode 语义、调优常量、内存态记录形状、
+ * RPC 错误构造。被 fs-core.worker.ts 及其拆出的 fs-core-recovery.ts /
+ * fs-core-write-ops.ts 三方共用；纯类型/常量声明，不含任何 DOM/WebWorker
+ * 专属全局引用，可被主 tsconfig（DOM lib）与 tsconfig.worker.json
+ * （WebWorker lib）两个 program 同时编译。
+ */
+import type { WalRecord } from './wal-codec.js'
+
+export const OP = { WRITE: 1, RM: 2, MV: 3, MKDIR: 4, CHECKPOINT: 5, RESTORE: 6 } as const
+export const OP_NAME: Record<number, string> = { 1: 'write', 2: 'rm', 3: 'mv', 4: 'mkdir', 5: 'checkpoint', 6: 'restore' }
+// §4.7 restore 冲突检查只关心"写类"操作（改变文件内容/存在性），checkpoint 本身不算
+export const WRITE_OPCODES = new Set<number>([OP.WRITE, OP.RM, OP.MV, OP.RESTORE])
+export const INLINE_MAX = 4096          // payload ≤4KB 内联进 WAL 记录
+export const GROUP_WINDOW_MS = 50       // 人类写组提交窗口
+export const SEGMENT_ROTATE_BYTES = 4 * 1024 * 1024
+export const OPID_WINDOW = 1024
+// P4 turn 能力：agent 写必须在有效 turn 内（fs-core 侧执法，不信任调用方透传）
+export const TURN_DEFAULT_TTL_MS = 120000
+export const TURN_MAX_OPS = 1000        // per-turn 限额（跑飞的 agent 刹车）
+export const AUDIT_CAP = 4096           // 内存审计环（fs_diff 的数据源；重启由 WAL 回放重建）
+// P5 checkpoint LRU：保留最近 N 个；被淘汰者的 blob 在下次 compaction GC 回收
+export const CHECKPOINT_KEEP = 20
+
+export interface MirrorEntry {
+  content: string
+  rev: number
+}
+
+export interface AuditEntry {
+  gen: number
+  opcode: number
+  actor?: string
+  turnId?: string
+  path?: string
+  from?: string
+  to?: string
+  cpId?: string
+}
+
+export interface TurnState {
+  turnId: string
+  cpId: string
+  expiresAt: number
+  ops: number
+}
+
+export interface WindowOp {
+  respond: (r: Record<string, unknown>) => void
+  gen: number
+  path?: string
+  actor?: string
+  opId?: string
+  extra?: Record<string, unknown>
+}
+
+export type Respond = (r: Record<string, unknown>) => void
+
+export interface WorkerError extends Error {
+  code?: string
+  extra?: Record<string, unknown>
+}
+
+export function rpcErr(code: string, message: string, extra?: Record<string, unknown>): WorkerError {
+  const e = new Error(message) as WorkerError
+  e.code = code
+  if (extra) e.extra = extra
+  return e
+}
+
+/** 供 fs-core-recovery.ts 的回放循环使用；纯函数（无副作用）。 */
+export function epochFloor(replayed: WalRecord[]): number {
+  return replayed.length ? replayed[replayed.length - 1]!.epoch : 0 // epoch 单调不减
+}

package/src/worker-lib/paths.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+import { DERIVED_PREFIXES, normalizePath } from './paths.js'
+
+describe('normalizePath', () => {
+  it('strips a leading "./" and collapses internal "."/empty segments', () => {
+    expect(normalizePath('./a/./b')).toBe('a/b')
+    expect(normalizePath('a//b')).toBe('a/b')
+  })
+
+  it('rejects absolute paths', () => {
+    expect(normalizePath('/a/b')).toBeNull()
+  })
+
+  it('rejects paths that escape via ".."', () => {
+    expect(normalizePath('a/../../b')).toBeNull()
+  })
+
+  it('rejects non-string, empty, NUL, and backslash input', () => {
+    expect(normalizePath(undefined)).toBeNull()
+    expect(normalizePath(42)).toBeNull()
+    expect(normalizePath('')).toBeNull()
+    expect(normalizePath('a\0b')).toBeNull()
+    expect(normalizePath('a\\b')).toBeNull()
+  })
+
+  it('returns null for a path that normalizes to nothing (all "." segments)', () => {
+    expect(normalizePath('./.')).toBeNull()
+  })
+
+  it('leaves an already-clean relative path untouched', () => {
+    expect(normalizePath('a/b/c.txt')).toBe('a/b/c.txt')
+  })
+})
+
+describe('DERIVED_PREFIXES', () => {
+  it('lists the derived-area prefixes checkWrite rejects', () => {
+    expect(DERIVED_PREFIXES).toEqual(['node_modules/', '.checkpoints/'])
+  })
+})

package/src/worker-lib/paths.ts

@@ -0,0 +1,14 @@
+/** 路径监狱（纯函数，lib 中立）—— fs-core.worker.ts 的写路径统一走这里做归一化/校验。 */
+export const DERIVED_PREFIXES = ['node_modules/', '.checkpoints/']
+
+export function normalizePath(p: unknown): string | null {
+  if (typeof p !== 'string' || !p || p.includes('\0') || p.includes('\\')) return null
+  if (p.startsWith('/')) return null
+  const parts: string[] = []
+  for (const seg of p.split('/')) {
+    if (seg === '' || seg === '.') continue
+    if (seg === '..') return null
+    parts.push(seg)
+  }
+  return parts.length ? parts.join('/') : null
+}

package/src/worker-lib/rpc-types.ts

@@ -0,0 +1,67 @@
+/** Per-op RPC argument shapes (lib-neutral type aliases only) —— handleRpc's
+ * dispatch table narrows the incoming `Record<string, unknown>` bag to one of
+ * these via a single `as` per op, matching each op method's own destructured
+ * parameter type below. */
+export interface WriteArgs {
+  path: string
+  content: unknown
+  ifMatch?: number | null
+  actor?: string
+  turnId?: string
+  agentToken?: string
+  opId?: string
+}
+export interface EditArgs {
+  path: string
+  old: string
+  next: string
+  ifMatch?: number
+  actor?: string
+  turnId?: string
+  agentToken?: string
+  opId?: string
+}
+export interface RmArgs {
+  path: string
+  actor?: string
+  turnId?: string
+  agentToken?: string
+  opId?: string
+}
+export interface MvArgs {
+  from: string
+  to: string
+  actor?: string
+  turnId?: string
+  agentToken?: string
+  opId?: string
+}
+export interface CheckpointArgs {
+  actor?: string
+  turnId?: string
+  agentToken?: string
+  opId?: string
+}
+export interface RestoreArgs {
+  cpId: string
+  baseGen?: number
+  force?: boolean
+  actor?: string
+  turnId?: string
+  agentToken?: string
+  opId?: string
+}
+export interface TurnBeginArgs {
+  turnId: string
+  ttlMs?: number
+  opId?: string
+}
+export interface TurnEndArgs {
+  turnId: string
+}
+export interface ReadArgs {
+  path: string
+}
+export interface DiffArgs {
+  turnId?: string
+}

package/src/worker-lib/wal-codec.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+import { crc32, decodeSlot, encodeSlot, frameRecord, parseRecord, sha256hex } from './wal-codec.js'
+
+describe('crc32', () => {
+  it('matches the well-known CRC-32 of "123456789" (0xCBF43926)', () => {
+    const bytes = new TextEncoder().encode('123456789')
+    expect(crc32(bytes)).toBe(0xcbf43926)
+  })
+
+  it('returns 0 for an empty input', () => {
+    expect(crc32(new Uint8Array(0))).toBe(0)
+  })
+
+  it('honors the start/end window', () => {
+    const bytes = new TextEncoder().encode('xx123456789yy')
+    expect(crc32(bytes, 2, 11)).toBe(0xcbf43926)
+  })
+})
+
+describe('sha256hex', () => {
+  it('matches the well-known SHA-256 of the empty string', async () => {
+    const hex = await sha256hex(new Uint8Array(0))
+    expect(hex).toBe('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855')
+  })
+})
+
+describe('superblock slot encode/decode', () => {
+  it('round-trips a slot', () => {
+    const slot = { epoch: 7, compactGen: 42, walStartGen: 43, manifestCrc: 0xdeadbeef }
+    const decoded = decodeSlot(encodeSlot(slot))
+    expect(decoded).toEqual(slot)
+  })
+
+  it('rejects a corrupted slot (bad CRC)', () => {
+    const bytes = encodeSlot({ epoch: 1, compactGen: 2, walStartGen: 3, manifestCrc: 4 })
+    bytes[0] = bytes[0]! ^ 0xff // flip a byte inside the magic — CRC no longer matches
+    expect(decodeSlot(bytes)).toBeNull()
+  })
+
+  it('rejects a too-short buffer', () => {
+    expect(decodeSlot(new Uint8Array(10))).toBeNull()
+  })
+})
+
+describe('WAL record frame/parse', () => {
+  it('round-trips a record through frameRecord → parseRecord', () => {
+    const meta = { path: 'a.txt', actor: 'human', payload: { inline: 'hi' } }
+    const frame = frameRecord(5, 1, 1, meta)
+    const parsed = parseRecord(frame, 0)
+    expect(parsed).not.toBeNull()
+    expect(parsed!.rec).toEqual({ gen: 5, epoch: 1, opcode: 1, meta })
+    expect(parsed!.next).toBe(frame.length)
+  })
+
+  it('parses back-to-back records at sequential offsets', () => {
+    const a = frameRecord(1, 0, 1, { path: 'a' })
+    const b = frameRecord(2, 0, 2, { path: 'a' })
+    const buf = new Uint8Array(a.length + b.length)
+    buf.set(a, 0); buf.set(b, a.length)
+    const first = parseRecord(buf, 0)!
+    expect(first.rec.gen).toBe(1)
+    const second = parseRecord(buf, first.next)!
+    expect(second.rec.gen).toBe(2)
+    expect(second.next).toBe(buf.length)
+  })
+
+  it('returns null on a truncated buffer', () => {
+    const frame = frameRecord(1, 0, 1, { path: 'a' })
+    expect(parseRecord(frame.subarray(0, frame.length - 1), 0)).toBeNull()
+  })
+
+  it('returns null when the trailing CRC is corrupted', () => {
+    const frame = frameRecord(1, 0, 1, { path: 'a' })
+    frame[frame.length - 2] = frame[frame.length - 2]! ^ 0xff
+    expect(parseRecord(frame, 0)).toBeNull()
+  })
+
+  it('returns null when the commit byte is wrong', () => {
+    const frame = frameRecord(1, 0, 1, { path: 'a' })
+    frame[frame.length - 1] = 0x00
+    expect(parseRecord(frame, 0)).toBeNull()
+  })
+})

package/src/worker-lib/wal-codec.ts

@@ -0,0 +1,130 @@
+/**
+ * WAL 编解码（纯函数，lib 中立）—— crc32、superblock 槽、WAL 记录成帧/解析。
+ * 从 fs-core.worker.ts 抽出：不含任何 OPFS/Worker 专属 API，可被主 tsconfig
+ * （DOM lib）与 tsconfig.worker.json（WebWorker lib）两个 program 同时编译，
+ * 因此 zip.ts（主 program 侧）与 fs-core.worker.ts（worker program 侧）
+ * 都能 import 同一份 crc32/CRC_TABLE 实现（消除重复代码）。
+ *
+ * WAL 记录成帧：
+ *   [u32 len][u64 gen][u32 epoch][u8 opcode][u16 metaLen][meta JSON][u32 crc32][u8 0xC1]
+ *   len = len 字段之后的字节数；crc 覆盖 gen..meta 末尾。
+ */
+export const enc = new TextEncoder()
+export const dec = new TextDecoder()
+
+// ───────────────────────── crc32（查表法） ─────────────────────────
+export const CRC_TABLE = (() => {
+  const t = new Uint32Array(256)
+  for (let n = 0; n < 256; n++) {
+    let c = n
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+    t[n] = c >>> 0
+  }
+  return t
+})()
+export function crc32(bytes: Uint8Array, start = 0, end: number = bytes.length): number {
+  let c = 0xffffffff
+  for (let i = start; i < end; i++) c = CRC_TABLE[(c ^ bytes[i]!) & 0xff]! ^ (c >>> 8)
+  return (c ^ 0xffffffff) >>> 0
+}
+
+export async function sha256hex(bytes: Uint8Array): Promise<string> {
+  const d = await crypto.subtle.digest('SHA-256', bytes as BufferSource)
+  return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, '0')).join('')
+}
+
+export interface SlotInfo {
+  epoch: number
+  compactGen: number
+  walStartGen: number
+  manifestCrc: number
+}
+
+const SB_MAGIC = 0x44574331 // 'DWC1'
+export const SLOT_SIZE = 64
+
+// ───────────────────────── superblock 槽编解码 ─────────────────────────
+// 布局：magic u32 | epoch u32 | compactGen f64 | walStartGen f64 | manifestCrc u32 | pad→60 | crc32 u32
+export function encodeSlot(s: SlotInfo): Uint8Array {
+  const buf = new ArrayBuffer(SLOT_SIZE)
+  const dv = new DataView(buf)
+  dv.setUint32(0, SB_MAGIC)
+  dv.setUint32(4, s.epoch)
+  dv.setFloat64(8, s.compactGen)
+  dv.setFloat64(16, s.walStartGen)
+  dv.setUint32(24, s.manifestCrc)
+  dv.setUint32(60, crc32(new Uint8Array(buf, 0, 60)))
+  return new Uint8Array(buf)
+}
+export function decodeSlot(bytes: Uint8Array): SlotInfo | null {
+  if (bytes.length < SLOT_SIZE) return null
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, SLOT_SIZE)
+  if (dv.getUint32(60) !== crc32(bytes, 0, 60)) return null
+  if (dv.getUint32(0) !== SB_MAGIC) return null
+  return {
+    epoch: dv.getUint32(4),
+    compactGen: dv.getFloat64(8),
+    walStartGen: dv.getFloat64(16),
+    manifestCrc: dv.getUint32(24),
+  }
+}
+
+/** WAL 记录的 meta 载荷形状 —— 各 opcode 只填自己用到的字段（落 WAL 的持久
+ * 线格式，字段名/结构不可随意变更，见 fs-core.worker.ts 里对应 op* 方法）。 */
+export interface WalMeta {
+  opId?: string
+  path?: string
+  from?: string
+  to?: string
+  actor?: string
+  turnId?: string
+  ifMatch?: number | null
+  payload?: { inline?: string; h?: string }
+  cpId?: string
+  h?: string
+}
+
+export interface WalRecord {
+  gen: number
+  epoch: number
+  opcode: number
+  meta: WalMeta
+}
+
+// ───────────────────────── WAL 记录编解码 ─────────────────────────
+export function frameRecord(gen: number, epoch: number, opcode: number, meta: unknown): Uint8Array {
+  const metaBytes = enc.encode(JSON.stringify(meta))
+  const len = 8 + 4 + 1 + 2 + metaBytes.length + 4 + 1
+  const buf = new ArrayBuffer(4 + len)
+  const dv = new DataView(buf)
+  const u8 = new Uint8Array(buf)
+  dv.setUint32(0, len)
+  dv.setBigUint64(4, BigInt(gen))
+  dv.setUint32(12, epoch)
+  dv.setUint8(16, opcode)
+  dv.setUint16(17, metaBytes.length)
+  u8.set(metaBytes, 19)
+  const crcEnd = 19 + metaBytes.length
+  dv.setUint32(crcEnd, crc32(u8, 4, crcEnd))
+  dv.setUint8(crcEnd + 4, 0xc1)
+  return u8
+}
+/** 解析一条记录；返回 {rec, next} 或 null（framing/CRC/commit 任一失败）。 */
+export function parseRecord(u8: Uint8Array, off: number): { rec: WalRecord; next: number } | null {
+  if (off + 4 > u8.length) return null
+  const dv = new DataView(u8.buffer, u8.byteOffset)
+  const len = dv.getUint32(off)
+  if (len < 20 || off + 4 + len > u8.length) return null
+  const gen = Number(dv.getBigUint64(off + 4))
+  const epoch = dv.getUint32(off + 12)
+  const opcode = dv.getUint8(off + 16)
+  const metaLen = dv.getUint16(off + 17)
+  const metaStart = off + 19
+  const crcAt = metaStart + metaLen
+  if (crcAt + 5 !== off + 4 + len) return null
+  if (dv.getUint32(crcAt) !== crc32(u8, off + 4, crcAt)) return null
+  if (dv.getUint8(crcAt + 4) !== 0xc1) return null
+  let meta: WalMeta
+  try { meta = JSON.parse(dec.decode(u8.subarray(metaStart, crcAt))) as WalMeta } catch { return null }
+  return { rec: { gen, epoch, opcode, meta }, next: off + 4 + len }
+}