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

package/dist/fs-query.worker.js

@@ -0,0 +1,115 @@
+// src/fs-query.worker.ts
+var state = {
+  mirror: /* @__PURE__ */ new Map(),
+  // path -> {content, rev}
+  gen: -1,
+  // -1 = 尚未收到 core 的首次同步
+  waiters: []
+  // [{gen, resolve, timer}]
+};
+function applySync(msg) {
+  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;
+  });
+}
+function whenGen(gen) {
+  if (gen === void 0 || state.gen >= gen) return Promise.resolve();
+  return new Promise((resolve) => {
+    const w = { gen, resolve, timer: setTimeout(() => {
+      state.waiters = state.waiters.filter((x) => x !== w);
+      resolve();
+    }, 5e3) };
+    state.waiters.push(w);
+  });
+}
+var GLOB_SPECIAL_RE = /[.+^${}()|[\]\\]/;
+function translateGlobToken(pattern, i) {
+  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) {
+  let re = "";
+  for (let i = 0; i < pattern.length; i++) {
+    const { token, skip } = translateGlobToken(pattern, i);
+    re += token;
+    i += skip;
+  }
+  return new RegExp("^" + re + "$");
+}
+var ops = {
+  async snapshot({ gen }) {
+    await whenGen(gen);
+    const files = {};
+    for (const [p, ent] of state.mirror) files[p] = ent.content;
+    return { files, gen: state.gen, stale: gen !== void 0 && state.gen < gen };
+  },
+  async read({ path, gen }) {
+    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 }) {
+    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 }) {
+    await whenGen(gen);
+    const re = new RegExp(pattern, flags.replace("g", ""));
+    const scope = glob ? globToRegExp(glob) : null;
+    const hits = [];
+    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) => {
+  const msg = e.data;
+  if (msg.type === "init") {
+    msg.corePort.onmessage = (ev) => applySync(ev.data);
+    self.postMessage({ type: "ready" });
+    return;
+  }
+  if (msg.id === void 0) return;
+  try {
+    const dispatch = ops;
+    const result = await dispatch[msg.op](msg.args || {});
+    self.postMessage({ id: msg.id, ok: true, result });
+  } catch (err) {
+    const e2 = err;
+    self.postMessage({ id: msg.id, ok: false, code: e2.code || "internal", error: e2.message || String(err) });
+  }
+};

package/dist/sync/sync-engine.js

@@ -0,0 +1,381 @@
+/**
+ * Sync arbitration engine — the memfs<->disk synchronization core factored
+ * out of dimina-kit's workbench `wal-audit.ts` (see
+ * devtools-fs-core-feasibility.md §7+§8). A host wires a `client` (the
+ * fs-core ledger: write/rm/read/ls) and a `TruthPort` (its external truth
+ * source — devtools' `/__fs` bridge + SSE watch, or a future FSA
+ * local-directory adapter) and gets back an engine that keeps the ledger,
+ * the external truth, and — via `applyToEditor` — the live editor buffer
+ * reconciled. `kernel` and turn enforcement never enter this module: a
+ * host's own audit-turn surface talks to `client` directly for that (see
+ * wal-audit.ts).
+ *
+ * Echo judgement (both directions):
+ *  - Outbound (`onHumanSave`): before recording, compare the saved text
+ *    against the ledger's current record for that path — identical content
+ *    is a no-op (the ledger already reflects it), skipping a redundant
+ *    write.
+ *  - Inbound (`changes` batches, via `handleInboundPath`): first check
+ *    `pendingWrite` — an entry there was registered by an `onHumanSave` still
+ *    in flight for the same path, and its presence means this inbound
+ *    notification is that write's own echo, absorbed with no ledger write
+ *    and no editor refresh. This check is a structural no-op for a 'push'
+ *    port (devtools' SSE): registration and clearing both happen inside the
+ *    SAME `ledgerTurn` FIFO slot as the write they guard (see
+ *    `onHumanSave`), so by the time any later-queued inbound turn for that
+ *    path runs, the entry is already gone — the branch exists for a future
+ *    'poll' host whose change detection runs OUTSIDE this FIFO (e.g. an
+ *    mtime/size sweep) and can therefore observe the entry while the write
+ *    is still in flight. When `pendingWrite` misses, the engine falls back
+ *    to today's content comparison (truth-source bytes vs. the ledger's own
+ *    record) — the only judgement a push host ever actually exercises.
+ *
+ * Inbound-echo consumption (`consumeInboundEcho`, `inboundApplied`): a 'poll'
+ * host (e.g. the web local-directory adapter) drives its OWN outbound path
+ * OUTSIDE this module — it reads the ledger and writes the truth source
+ * directly, not through `onHumanSave` — so a change this engine just applied
+ * INBOUND (disk -> ledger, via `handleInboundPath`) can race that host's
+ * outbound scan and get echoed straight back to disk before the poll
+ * baseline ever settles. `inboundApplied` (`rel -> {kind:'text'|'binary'|
+ * 'delete', ...}`) records exactly what `handleInboundPath` just applied,
+ * overwriting any prior entry for the same path; `consumeInboundEcho(rel,
+ * content)` lets such a host check "is this outbound write about to re-emit
+ * an inbound change I haven't published yet?" immediately BEFORE writing to
+ * the truth source, consuming (clearing) the record on a match so it is a
+ * one-shot suppression, not a standing content cache. A miss (different
+ * content, or no record at all) returns false and leaves any existing record
+ * untouched — it is not this call's echo to consume.
+ *
+ * Binary layering (v1): the first 8192 bytes of a file are sniffed for a NUL
+ * byte to classify it binary. A binary file never reaches the fs-core
+ * ledger (`client.write`/`read`) — it is tracked only in the in-memory
+ * `binaryIndex` (`rel -> { size, sha256 }`), and echo judgement for it is
+ * size+hash equality instead of a ledger content compare. What/why this is
+ * narrower than the text path: binary changes get NO WAL audit and NO
+ * rollback (the audit turn surface — `diff`/`restore` — is a string-content
+ * contract; v1 does not support an agent writing binary inside a turn), and
+ * `binaryIndex` is session-scoped — it is cleared and rebuilt from scratch on
+ * every `populateLedger()`, exactly like the ledger's own text reconciliation.
+ */
+const BINARY_SNIFF_BYTES = 8192;
+/** True when the first `BINARY_SNIFF_BYTES` of `bytes` contain a NUL byte. */
+function looksBinary(bytes) {
+    const len = Math.min(bytes.length, BINARY_SNIFF_BYTES);
+    for (let i = 0; i < len; i++) {
+        if (bytes[i] === 0)
+            return true;
+    }
+    return false;
+}
+async function sha256hex(bytes) {
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/** Byte-for-byte equality — used by `consumeInboundEcho`'s binary-content match. */
+function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/**
+ * True when `error` denotes "path does not exist" per the TruthPort error
+ * contract (see truth-port.ts): `error.code === 'not-found'` or
+ * `error.status === 404`. Every other rejection is "unavailable" (transient
+ * I/O failure, permission loss, dead connection, ...).
+ */
+function isNotFoundError(error) {
+    const e = error;
+    return Boolean(e) && (e.code === 'not-found' || e.status === 404);
+}
+export function createSyncEngine(client, port, opts = {}) {
+    const decoder = new TextDecoder();
+    const applyToEditor = opts.applyToEditor;
+    /**
+     * Paths with an `onHumanSave` write in flight — see the module doc's
+     * "Echo judgement" section. Registered synchronously when `onHumanSave` is
+     * called and cleared unconditionally (`finally`) once that write's own
+     * ledgerTurn slot finishes, success or failure.
+     */
+    const pendingWrite = new Set();
+    /**
+     * Binary files never enter the fs-core ledger — see the module doc's
+     * "Binary layering" section. Session-scoped: rebuilt from scratch on every
+     * `populateLedger()`.
+     */
+    const binaryIndex = new Map();
+    /**
+     * `rel -> { kind: 'text', text } | { kind: 'binary', bytes } | { kind: 'delete' }`
+     * — see the module doc's "Inbound-echo consumption" section. Written by
+     * `handleInboundPath` immediately after it actually applies an inbound
+     * change (ledger write/rm, or a binary/delete index update); consumed
+     * (checked + cleared on a match) by `consumeInboundEcho`. Session-scoped,
+     * same as `binaryIndex` — cleared on every `populateLedger()`.
+     */
+    const inboundApplied = new Map();
+    /**
+     * FIFO queue serializing every compare-then-record against the ledger
+     * (inbound change batches AND the onHumanSave accounting step). Without it
+     * the two race: an inbound echo's compare-read can run while an
+     * onHumanSave ledger write is still in flight, see stale content, and
+     * re-record the identical bytes. Serialized, the loser of the race sees
+     * the winner's write and absorbs it as an echo. The chain swallows step
+     * rejections (each caller handles its own errors), so one failed step can
+     * never wedge the queue.
+     */
+    let ledgerTurn = Promise.resolve();
+    function enqueueLedgerTurn(fn) {
+        const next = ledgerTurn.then(fn, fn);
+        ledgerTurn = next.catch(() => { });
+        return next;
+    }
+    /** Walk the port's tree into the ledger, then reconcile: ledger paths the
+     * walk did not produce are residue (e.g. from a previous session under the
+     * same persisted ledger identity) and are removed so the ledger ends up
+     * exactly matching the walked tree. */
+    async function seedFromDisk() {
+        binaryIndex.clear();
+        inboundApplied.clear();
+        const seen = new Set();
+        await port.walk(async (rel, bytes) => {
+            seen.add(rel);
+            if (looksBinary(bytes)) {
+                binaryIndex.set(rel, { size: bytes.length, sha256: await sha256hex(bytes) });
+                return; // binary never enters the ledger
+            }
+            await client.write(rel, decoder.decode(bytes), { actor: 'human' });
+        });
+        const { paths } = await client.ls();
+        for (const p of paths) {
+            // Residue from a previous session, OR a path that used to be
+            // ledgered as text but is now classified binary (migration cleanup —
+            // binaryIndex.has(p) is authoritative once the walk above ran).
+            if (!seen.has(p) || binaryIndex.has(p))
+                await client.rm(p, { actor: 'human' });
+        }
+    }
+    /**
+     * Process one inbound path. `pendingWrite` is checked first (see module
+     * doc); a miss falls back to content comparison: identical content is the
+     * echo of our own last write and is dropped with no ledger write and no
+     * `applyToEditor` call. A `port.read` rejection classified as not-found
+     * (see truth-port.ts) is a deletion; any other rejection
+     * ("unavailable") is transient and skips the path entirely — inferring a
+     * deletion from it would rm the ledger record and close the file in the
+     * editor while it still exists at the truth source.
+     */
+    async function handleInboundPath(rel) {
+        if (pendingWrite.has(rel)) {
+            pendingWrite.delete(rel);
+            return;
+        }
+        let bytes;
+        try {
+            bytes = await port.read(rel);
+        }
+        catch (e) {
+            if (!isNotFoundError(e)) {
+                console.warn('[fs-core/sync] transient port read failure, skipping', rel, e);
+                return;
+            }
+            bytes = null;
+        }
+        if (bytes === null) {
+            // Deletion. A path the binaryIndex knows about was never in the
+            // ledger (it never took the client.write path), so removal here is
+            // index-only — no client.rm.
+            if (binaryIndex.has(rel)) {
+                binaryIndex.delete(rel);
+                inboundApplied.set(rel, { kind: 'delete' });
+                await applyToEditor?.(rel, null);
+                return;
+            }
+            let ledgerContent;
+            try {
+                ledgerContent = (await client.read(rel)).content;
+            }
+            catch {
+                ledgerContent = undefined;
+            }
+            if (ledgerContent === undefined)
+                return; // already absent from both sides
+            await client.rm(rel, { actor: 'human' });
+            inboundApplied.set(rel, { kind: 'delete' });
+            await applyToEditor?.(rel, null);
+            return;
+        }
+        if (looksBinary(bytes)) {
+            const prior = binaryIndex.get(rel);
+            const sha256 = await sha256hex(bytes);
+            if (prior && prior.size === bytes.length && prior.sha256 === sha256)
+                return; // echo: same bytes already indexed
+            binaryIndex.set(rel, { size: bytes.length, sha256 });
+            inboundApplied.set(rel, { kind: 'binary', bytes });
+            await applyToEditor?.(rel, bytes);
+            return;
+        }
+        let ledgerContent;
+        try {
+            ledgerContent = (await client.read(rel)).content;
+        }
+        catch {
+            // Not in the ledger yet (or a transient read failure) — treated the
+            // same as "no prior recorded content", so a real file at the truth
+            // source always gets recorded/applied below rather than silently
+            // dropped.
+            ledgerContent = undefined;
+        }
+        const text = decoder.decode(bytes);
+        if (ledgerContent !== undefined && text === ledgerContent)
+            return; // echo of our own write
+        await client.write(rel, text, { actor: 'human' });
+        inboundApplied.set(rel, { kind: 'text', text });
+        await applyToEditor?.(rel, bytes);
+    }
+    /**
+     * One-shot check for a 'poll' host's own outbound path: "is `content` (the
+     * bytes/text about to be written to the truth source for `rel`, or `null`
+     * for a delete) exactly what `handleInboundPath` just applied FROM that
+     * same truth source?" A match means writing it back out would be a pure
+     * echo — the host should skip the write entirely — and the record is
+     * cleared (consumed) so it cannot match again. See the module doc's
+     * "Inbound-echo consumption" section for why a push host (devtools) never
+     * needs this: its outbound path goes through `onHumanSave`/`pendingWrite`
+     * instead.
+     */
+    function consumeInboundEcho(rel, content) {
+        const entry = inboundApplied.get(rel);
+        if (!entry)
+            return false;
+        let matches;
+        if (content === null)
+            matches = entry.kind === 'delete';
+        else if (typeof content === 'string')
+            matches = entry.kind === 'text' && entry.text === content;
+        else
+            matches = entry.kind === 'binary' && bytesEqual(entry.bytes, content);
+        if (matches)
+            inboundApplied.delete(rel);
+        return matches;
+    }
+    /**
+     * A batch is trusted as-is: the port adapter (see truth-port.ts's
+     * `changes` doc) is responsible for turning a watcher's coalesced/lossy
+     * events into the actual set of paths worth re-examining BEFORE calling
+     * this engine — devtools' adapter (wal-audit.ts +
+     * wal-audit-watch-expand.ts) does that via a stat-level disk compare
+     * against a session index, so paths arriving here have already earned
+     * their re-examination and no further expansion happens at this layer.
+     */
+    async function handleBatch(paths) {
+        for (const rel of paths) {
+            try {
+                // Per-path (not per-batch) queue turns, so a long batch cannot
+                // starve an interleaved onHumanSave accounting step of its FIFO
+                // position.
+                await enqueueLedgerTurn(() => handleInboundPath(rel));
+            }
+            catch (e) {
+                console.warn('[fs-core/sync] disk sync failed for', rel, e);
+            }
+        }
+    }
+    let pendingInboundPaths = new Set();
+    let inboundBatchRunning = false;
+    function enqueueInboundBatch(paths) {
+        for (const rel of paths)
+            pendingInboundPaths.add(rel);
+        if (inboundBatchRunning)
+            return;
+        inboundBatchRunning = true;
+        void (async () => {
+            try {
+                while (pendingInboundPaths.size) {
+                    const raw = [...pendingInboundPaths];
+                    pendingInboundPaths = new Set();
+                    await handleBatch(raw);
+                }
+            }
+            finally {
+                inboundBatchRunning = false;
+                if (pendingInboundPaths.size)
+                    enqueueInboundBatch([]);
+            }
+        })();
+    }
+    let stopWatching = () => { };
+    /** Subscribe to `port.changes`. `active` gates BOTH callbacks so a
+     * late/duplicate event delivered after `onDead` (or after a fresh
+     * `start()` superseded this subscription) is a guaranteed no-op, not just
+     * best-effort. */
+    function start() {
+        let active = true;
+        const dispose = port.changes((paths) => {
+            if (!active)
+                return;
+            enqueueInboundBatch(paths);
+        }, () => {
+            if (!active)
+                return;
+            active = false;
+            console.warn('[fs-core/sync] watcher died — reverting to open-time mirror only');
+            dispose();
+        });
+        stopWatching = () => {
+            active = false;
+            dispose();
+        };
+    }
+    function stop() {
+        stopWatching();
+        stopWatching = () => { };
+    }
+    /**
+     * Outbound accounting for a human save: registers `rel` in `pendingWrite`
+     * for the duration of the ledger compare-then-write (see module doc),
+     * skips the ledger write when the saved text already matches the ledger's
+     * record, and runs inside the same `ledgerTurn` FIFO as inbound batches so
+     * the two can never interleave. Errors propagate to the caller — a host's
+     * onSave wrapper decides whether a ledger-write failure should be
+     * swallowed (best-effort accounting must never unwind a save that already
+     * landed at the truth source).
+     *
+     * `content` may be the decoded text (string, unchanged legacy path) or the
+     * raw saved bytes (`Uint8Array`) — passing raw bytes lets this function
+     * sniff for binary (see module doc's "Binary layering" section) before
+     * deciding whether to decode. A binary save skips the ledger write
+     * entirely and only updates `binaryIndex`.
+     */
+    async function onHumanSave(rel, content) {
+        pendingWrite.add(rel);
+        try {
+            if (content instanceof Uint8Array && looksBinary(content)) {
+                await enqueueLedgerTurn(async () => {
+                    binaryIndex.set(rel, { size: content.length, sha256: await sha256hex(content) });
+                });
+                return;
+            }
+            const text = typeof content === 'string' ? content : decoder.decode(content);
+            await enqueueLedgerTurn(async () => {
+                const unchanged = await client
+                    .read(rel)
+                    .then((r) => r.content === text)
+                    .catch(() => false);
+                if (!unchanged)
+                    await client.write(rel, text, { actor: 'human' });
+            });
+        }
+        finally {
+            pendingWrite.delete(rel);
+        }
+    }
+    return {
+        populateLedger: seedFromDisk,
+        onHumanSave,
+        consumeInboundEcho,
+        start,
+        stop,
+    };
+}

package/dist/sync/truth-port.js

@@ -0,0 +1 @@
+export {};

package/dist/worker-lib/engine-shared.js

@@ -0,0 +1,25 @@
+export const OP = { WRITE: 1, RM: 2, MV: 3, MKDIR: 4, CHECKPOINT: 5, RESTORE: 6 };
+export const OP_NAME = { 1: 'write', 2: 'rm', 3: 'mv', 4: 'mkdir', 5: 'checkpoint', 6: 'restore' };
+// §4.7 restore 冲突检查只关心"写类"操作（改变文件内容/存在性），checkpoint 本身不算
+export const WRITE_OPCODES = new Set([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 function rpcErr(code, message, extra) {
+    const e = new Error(message);
+    e.code = code;
+    if (extra)
+        e.extra = extra;
+    return e;
+}
+/** 供 fs-core-recovery.ts 的回放循环使用；纯函数（无副作用）。 */
+export function epochFloor(replayed) {
+    return replayed.length ? replayed[replayed.length - 1].epoch : 0; // epoch 单调不减
+}

package/dist/worker-lib/paths.js

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

package/dist/worker-lib/rpc-types.js

@@ -0,0 +1 @@
+export {};

package/dist/worker-lib/wal-codec.js

@@ -0,0 +1,111 @@
+/**
+ * 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, start = 0, end = bytes.length) {
+    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) {
+    const d = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(d)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+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) {
+    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) {
+    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 记录编解码 ─────────────────────────
+export function frameRecord(gen, epoch, opcode, meta) {
+    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, off) {
+    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;
+    try {
+        meta = JSON.parse(dec.decode(u8.subarray(metaStart, crcAt)));
+    }
+    catch {
+        return null;
+    }
+    return { rec: { gen, epoch, opcode, meta }, next: off + 4 + len };
+}