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

package/src/worker-files.ts

@@ -0,0 +1,43 @@
+/**
+ * The authoritative statement of fs-core's worker-artifact distribution
+ * contract, for Node-side consumers that copy/serve the worker files
+ * (dimina-kit workbench's vite-preset, qdmp-web-workbench's server.cjs):
+ *
+ *   dist/fs-core.worker.js and dist/fs-query.worker.js are single-file,
+ *   self-contained ESM (no import statements) living in the SAME directory
+ *   as dist/client.js, under exactly these file names.
+ *
+ * build-workers.js asserts this at build time; consumers should derive the
+ * names/locations from here instead of re-deriving them with hardcoded
+ * string joins. Pure string manipulation (no node:path) so the module loads
+ * in any runtime and ships as both ESM (dist/worker-files.js) and CJS
+ * (dist/worker-files.cjs — see the exports map's `require` condition, for
+ * CommonJS hosts like server.cjs).
+ */
+
+/** The worker artifacts' literal file names, siblings of `client.js`. */
+export const FS_CORE_WORKER_FILES = ['fs-core.worker.js', 'fs-query.worker.js'] as const
+
+export interface ResolvedWorkerFiles {
+  /** Directory holding client.js and both worker files. */
+  dir: string
+  /** Absolute path of each worker file, in {@link FS_CORE_WORKER_FILES} order. */
+  files: string[]
+}
+
+/**
+ * Resolve the on-disk worker file paths from the resolved path of the
+ * `./client` entry — the one path every consumer can obtain:
+ *
+ *   resolveWorkerFiles(require.resolve('@dimina-kit/fs-core/client'))
+ *
+ * Preserves whichever path separator the input uses (POSIX or Windows), so
+ * the result is joinable/copyable as-is on the host platform.
+ */
+export function resolveWorkerFiles(clientEntryPath: string): ResolvedWorkerFiles {
+  const cut = Math.max(clientEntryPath.lastIndexOf('/'), clientEntryPath.lastIndexOf('\\'))
+  if (cut < 0) throw new Error(`resolveWorkerFiles: not a path to client.js: ${clientEntryPath}`)
+  const sep = clientEntryPath[cut]!
+  const dir = clientEntryPath.slice(0, cut)
+  return { dir, files: FS_CORE_WORKER_FILES.map((name) => dir + sep + name) }
+}

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

@@ -6,20 +6,21 @@
  * （WebWorker lib）两个 program 同时编译。
  */
 import type { WalRecord } from './wal-codec.js'
+import type { FsCoreErrorCode } from './protocol.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 本身不算
+// 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 侧执法，不信任调用方透传）
+// 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 回收
+// checkpoint LRU：保留最近 N 个；被淘汰者的 blob 在下次 compaction GC 回收
 export const CHECKPOINT_KEEP = 20
 
 export interface MirrorEntry {
@@ -54,14 +55,27 @@ export interface WindowOp {
   extra?: Record<string, unknown>
 }
 
+/** An opId's cached RPC result, replayed verbatim (+`idempotent: true`) when
+ * the same opId is re-sent after a response timeout. The live write path
+ * caches the FULL respond payload (`{gen, rev, ...extra}` / restore's
+ * `{gen, restored}`) so a replay carries the same fields the first response
+ * did — `cpId`/`turnId`/`expiresAt`/`restored` included. Entries rebuilt by
+ * WAL replay after a worker restart only carry `{gen}` (the WAL does not
+ * record memory-only extras); those entries serve cross-session dedup, which
+ * a same-session retry never hits. */
+export type OpIdResult = { gen: number; rev?: number } & Record<string, unknown>
+
 export type Respond = (r: Record<string, unknown>) => void
 
 export interface WorkerError extends Error {
-  code?: string
+  code?: FsCoreErrorCode
   extra?: Record<string, unknown>
 }
 
-export function rpcErr(code: string, message: string, extra?: Record<string, unknown>): WorkerError {
+/** `code` is typed against the exported wire contract (worker-lib/protocol.ts),
+ * so the set of codes this worker can throw and the set consumers can match on
+ * are the same list by construction. */
+export function rpcErr(code: FsCoreErrorCode, message: string, extra?: Record<string, unknown>): WorkerError {
   const e = new Error(message) as WorkerError
   e.code = code
   if (extra) e.extra = extra

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

@@ -0,0 +1,37 @@
+/**
+ * Guards the exported wire contract: consumers match rejections via
+ * `isFsCoreErrorCode`/`getFsCoreErrorCode` against the SAME code list the
+ * worker's `rpcErr` factory is typed against — so a code the worker can
+ * throw and a code a consumer can match are one set by construction.
+ */
+import { describe, expect, it } from 'vitest'
+import { FS_CORE_ERROR_CODES, getFsCoreErrorCode, isFsCoreErrorCode } from './protocol.js'
+import { rpcErr } from './engine-shared.js'
+
+describe('fs-core error-code contract', () => {
+  it('recognizes an error produced by the worker-side rpcErr factory', () => {
+    const e = rpcErr('turn-closed', 'turn expired: t-1')
+    expect(getFsCoreErrorCode(e)).toBe('turn-closed')
+    expect(isFsCoreErrorCode(e, 'turn-closed')).toBe(true)
+    expect(isFsCoreErrorCode(e, 'readonly')).toBe(false)
+  })
+
+  it('recognizes the plain-object shape a structured-clone/client rejection carries', () => {
+    // client.ts materializes rejections as Object.assign(new Error(msg), {code})
+    const clientShaped = Object.assign(new Error('fs-core is readonly'), { code: 'readonly' })
+    expect(getFsCoreErrorCode(clientShaped)).toBe('readonly')
+    expect(isFsCoreErrorCode(clientShaped, 'readonly')).toBe(true)
+  })
+
+  it('returns undefined for non-fs-core errors, unknown codes, and non-objects', () => {
+    expect(getFsCoreErrorCode(new Error('plain'))).toBeUndefined()
+    expect(getFsCoreErrorCode(Object.assign(new Error('x'), { code: 'ENOENT' }))).toBeUndefined()
+    expect(getFsCoreErrorCode(null)).toBeUndefined()
+    expect(getFsCoreErrorCode('readonly')).toBeUndefined()
+    expect(isFsCoreErrorCode(undefined, 'readonly')).toBe(false)
+  })
+
+  it('lists every code exactly once', () => {
+    expect(new Set(FS_CORE_ERROR_CODES).size).toBe(FS_CORE_ERROR_CODES.length)
+  })
+})

package/src/worker-lib/protocol.ts

@@ -0,0 +1,184 @@
+/**
+ * fs-core wire contract — the single authoritative enumeration of the error
+ * codes, event names, mode values, and message shapes that cross the worker
+ * boundary. Both ends compile against this module (worker side:
+ * engine-shared.ts's `rpcErr` signature; main-thread side: client.ts), and
+ * consumers should match on these exported symbols instead of quoting string
+ * literals from worker source or citing dist line numbers — those references
+ * rot on every version bump while the wire strings silently stay load-bearing.
+ *
+ * Lib-neutral (types + pure predicates only) so it stays compilable by both
+ * the DOM and the WebWorker tsc programs — see this directory's convention in
+ * ../../tsconfig.json.
+ */
+
+/**
+ * Single-writer lifecycle of one fs-core worker, as observed by a client:
+ * starting (HELLO sent, WELCOME not yet received) | writer (holds the Web
+ * Locks writer lease) | readonly (queued for the lease, or handed it over) |
+ * draining (worker-side handover transient — a client never observes it for
+ * long; see fs-core-recovery.ts, which converges to readonly before
+ * broadcasting) | dead (FATAL received, the worker is unusable).
+ */
+export type FsCoreMode = 'starting' | 'writer' | 'readonly' | 'draining' | 'dead'
+
+/**
+ * Every `code` a rejected fs-core RPC can carry (client-side: `error.code` on
+ * the rejection; wire-side: the `code` field of a `{ok: false}` reply). The
+ * worker's `rpcErr` factory is typed against this list, so a code appearing
+ * here and a code the worker can actually throw are the same set by
+ * construction.
+ */
+export const FS_CORE_ERROR_CODES = [
+  /** Write attempted while this worker does not hold the writer lease (another tab owns it). */
+  'readonly',
+  /** Write attempted while the writer lease handover is in progress. */
+  'draining',
+  /** Agent write without an active matching turn, or the turn has expired. */
+  'turn-closed',
+  /** `turnBegin` while another turn is already active. */
+  'turn-active',
+  /** Per-turn op quota exceeded. */
+  'turn-quota',
+  /** Agent write without the armed agent token (see `armAgentTokenGate`). */
+  'agent-token-required',
+  /** `armAgentTokenGate` re-armed with a DIFFERENT token (same token replays are ok+idempotent). */
+  'agent-token-gate-armed',
+  /** `restore` refused: the audit window no longer covers `baseGen`, or human edits landed since (carries `humanPaths`/`auditGap` extras). */
+  'restore-conflict',
+  /** Optimistic-concurrency failure: `ifMatch` mismatch, or the target path already exists. */
+  'cas-mismatch',
+  /** `edit`'s old string not found in the file. */
+  'edit-no-match',
+  /** `edit`'s old string matches more than once. */
+  'edit-ambiguous',
+  /** Path (or checkpoint id) does not exist. */
+  'not-found',
+  /** Path failed normalization (absolute, `..`, empty, ...). */
+  'bad-path',
+  /** Malformed argument (non-string content, missing turnId, ...). */
+  'bad-args',
+  /** Unknown RPC op name. */
+  'bad-op',
+  /** Write into a derived (read-only) area. */
+  'derived-readonly',
+  /** Internal write-path signal (WAL segment rotation needed); not expected to surface to clients. */
+  'rotate-needed',
+  /** Fallback for a worker-side error that carried no code of its own. */
+  'internal',
+] as const
+
+export type FsCoreErrorCode = (typeof FS_CORE_ERROR_CODES)[number]
+
+/** Extra fields a `restore-conflict` rejection carries (see `rpcErr`'s `extra`). */
+export interface FsCoreErrorExtras {
+  humanPaths?: string[]
+  auditGap?: boolean
+}
+
+/**
+ * `error.code` of `error` when it looks like an fs-core RPC rejection,
+ * else `undefined`. Purely structural — works on the plain `Error` the client
+ * materializes as well as on a structured-clone of it.
+ */
+export function getFsCoreErrorCode(error: unknown): FsCoreErrorCode | undefined {
+  if (!error || typeof error !== 'object' || !('code' in error)) return undefined
+  const code = (error as { code?: unknown }).code
+  return (FS_CORE_ERROR_CODES as readonly unknown[]).includes(code) ? (code as FsCoreErrorCode) : undefined
+}
+
+/** True when `error` is an fs-core RPC rejection carrying exactly `code`. */
+export function isFsCoreErrorCode(error: unknown, code: FsCoreErrorCode): boolean {
+  return getFsCoreErrorCode(error) === code
+}
+
+/** Names of the unsolicited events the core worker pushes to its client. */
+export type FsCoreEventName = 'writer-granted' | 'writer-lost' | 'fs-change'
+
+// ── Wire message shapes (worker → client main port) ──
+
+/** First message after HELLO; resolves `ProjectFsClient.connect`. */
+export interface CoreWelcomeMessage {
+  type: 'WELCOME'
+  epoch: number
+  memGen: number
+  readonly: boolean
+  mode: FsCoreMode
+}
+
+/** Unrecoverable worker failure — the worker is unusable afterwards. */
+export interface CoreFatalMessage {
+  type: 'FATAL'
+  error: string
+}
+
+/** Liveness reply to the client's PING. */
+export interface CorePongMessage {
+  type: 'PONG'
+  t?: number
+}
+
+/**
+ * Unsolicited event push. `writer-granted`/`writer-lost` drive the client's
+ * `mode`; `fs-change` reports a committed write batch (`paths` when ≤ 32,
+ * else just `count`; `restore` carries the checkpoint id a restore replayed).
+ */
+export interface CoreEventMessage {
+  evt: FsCoreEventName
+  gen?: number
+  actor?: string
+  paths?: string[]
+  count?: number
+  restore?: string
+}
+
+/** RPC reply, success. */
+export interface CoreReplyOkMessage {
+  id: number
+  ok: true
+  result: unknown
+}
+
+/** RPC reply, failure — `code` is one of {@link FS_CORE_ERROR_CODES}. */
+export interface CoreReplyErrMessage extends FsCoreErrorExtras {
+  id: number
+  ok: false
+  code: FsCoreErrorCode
+  error: string
+}
+
+/** Everything the core worker's main port can deliver, as a discriminated union. */
+export type CoreWireMessage =
+  | CoreWelcomeMessage
+  | CoreFatalMessage
+  | CorePongMessage
+  | CoreEventMessage
+  | CoreReplyOkMessage
+  | CoreReplyErrMessage
+
+/**
+ * Loosely-shaped dynamic view of {@link CoreWireMessage}: every field
+ * optional, distinguished at runtime by which ones are present. This matches
+ * how `ProjectFsClient` actually reads the port (each field independently
+ * checked), and is the type its `onChange` callbacks receive; the union above
+ * is the authoritative shape each individual message satisfies.
+ */
+export interface CoreMessage {
+  type?: string
+  evt?: string
+  error?: string
+  mode?: FsCoreMode
+  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
+}

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

@@ -1,9 +1,12 @@
 /**
- * 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 编解码（纯函数，lib 中立）—— crc32、superblock 槽、WAL 记录成帧/解析、
+ * sha256hex。从 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 实现（消除重复代码）。sync/ 侧
+ * （独立 rootDir 的第三个 tsc program）经 package.json 的 `imports` 自引用
+ * （`#worker-lib/wal-codec.js`，见 tsconfig.worker-lib.build.json）复用同一份
+ * sha256hex，同样消除重复代码。
  *
  * WAL 记录成帧：
  *   [u32 len][u64 gen][u32 epoch][u8 opcode][u16 metaLen][meta JSON][u32 crc32][u8 0xC1]

package/src/zip.ts

@@ -1,5 +1,5 @@
 /**
- * store-only ZIP 打包（P5 导出出口）—— 无压缩、无依赖，全浏览器可用。
+ * store-only ZIP 打包（导出出口）—— 无压缩、无依赖，全浏览器可用。
  * 项目导出走"另一介质"才真正提升持久等级；zip 是最低门槛的那条出口。
  */
 import { crc32 } from './worker-lib/wal-codec.js'

package/sync/binary-sidecar.test.ts

@@ -0,0 +1,150 @@
+/**
+ * Contract tests for the binary side-car: classification, the size+sha256
+ * index, echo judgement, bytes retention, overlay precedence, and change
+ * events — the one authority every host's "binary never enters the string
+ * ledger" handling builds on.
+ */
+import { describe, expect, it, vi } from 'vitest'
+import { createBinarySidecar, looksBinary } from './binary-sidecar.js'
+
+const png = (...bytes: number[]) => new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0, ...bytes])
+
+describe('looksBinary', () => {
+  it('classifies by a NUL byte in the first 8192 bytes', () => {
+    expect(looksBinary(png())).toBe(true)
+    expect(looksBinary(new TextEncoder().encode('plain text'))).toBe(false)
+  })
+
+  it('does not scan past the sniff window', () => {
+    const big = new Uint8Array(10000).fill(0x61)
+    big[9500] = 0 // NUL beyond the 8192-byte window
+    expect(looksBinary(big)).toBe(false)
+  })
+})
+
+describe('createBinarySidecar — index + echo judgement', () => {
+  it('put() records a new entry and reports changed', async () => {
+    const sc = createBinarySidecar()
+    expect(await sc.put('a.png', png(1))).toBe(true)
+    expect(sc.has('a.png')).toBe(true)
+    const entry = sc.entry('a.png')
+    expect(entry?.size).toBe(6)
+    expect(entry?.sha256).toMatch(/^[0-9a-f]{64}$/)
+    expect(sc.size).toBe(1)
+  })
+
+  it('put() of identical bytes is an echo: unchanged, no event', async () => {
+    const sc = createBinarySidecar()
+    const onChange = vi.fn()
+    await sc.put('a.png', png(1))
+    sc.onChange(onChange)
+    expect(await sc.put('a.png', png(1))).toBe(false)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('put() of different same-length bytes IS a change (sha decides, not size)', async () => {
+    const sc = createBinarySidecar()
+    await sc.put('a.png', png(1))
+    expect(await sc.put('a.png', png(2))).toBe(true)
+  })
+
+  it('remove() reports whether an entry existed and emits null once', async () => {
+    const sc = createBinarySidecar()
+    const onChange = vi.fn()
+    sc.onChange(onChange)
+    await expect(sc.remove('ghost.png')).resolves.toBe(false)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('index-only sidecar retains no bytes and refuses overlay()', async () => {
+    const sc = createBinarySidecar()
+    await sc.put('a.png', png(1))
+    expect(sc.bytes('a.png')).toBeUndefined()
+    expect(sc.toRecord()).toEqual({})
+    expect(() => sc.overlay({})).toThrow(/retainBytes/)
+  })
+})
+
+describe('createBinarySidecar — retainBytes host shape', () => {
+  it('retains bytes and overlays them UNDER the ledger files (ledger wins)', async () => {
+    const sc = createBinarySidecar({ retainBytes: true })
+    await sc.put('img/a.png', png(1))
+    await sc.put('both.txt', png(9))
+    const merged = sc.overlay({ 'app.json': '{}', 'both.txt': 'ledger text' })
+    expect(merged['img/a.png']).toEqual(png(1))
+    expect(merged['app.json']).toBe('{}')
+    expect(merged['both.txt']).toBe('ledger text')
+  })
+
+  it('reset() reseeds silently-cleared state with the new entries', async () => {
+    const sc = createBinarySidecar({ retainBytes: true })
+    await sc.put('old.png', png(1))
+    await sc.reset({ 'new.png': png(2) })
+    expect(sc.has('old.png')).toBe(false)
+    expect(sc.keys()).toEqual(['new.png'])
+    expect(sc.bytes('new.png')).toEqual(png(2))
+  })
+
+  it('onChange fires for effective put/remove, unsubscribes cleanly, and a throwing subscriber cannot break the mutation', async () => {
+    const sc = createBinarySidecar({ retainBytes: true })
+    const seen: Array<[string, Uint8Array | null]> = []
+    sc.onChange(() => {
+      throw new Error('subscriber bug')
+    })
+    const off = sc.onChange((rel, bytes) => seen.push([rel, bytes]))
+    await sc.put('a.png', png(1))
+    await sc.remove('a.png')
+    expect(seen).toEqual([
+      ['a.png', png(1)],
+      ['a.png', null],
+    ])
+    expect(sc.has('a.png')).toBe(false)
+    off()
+    await sc.put('b.png', png(2))
+    expect(seen).toHaveLength(2)
+  })
+
+  it('reset() is atomic to readers and silent: a mid-reset read sees the OLD set, and no events fire', async () => {
+    const sc = createBinarySidecar({ retainBytes: true })
+    await sc.put('old.png', png(1))
+    const onChange = vi.fn()
+    sc.onChange(onChange)
+    const resetting = sc.reset({ 'new.png': png(2) })
+    // Hashing has suspended reset(); a concurrent reader (compile/export
+    // overlaying the sidecar) must still see the complete old set — never an
+    // empty or half-built one.
+    expect(sc.keys()).toEqual(['old.png'])
+    expect(sc.toRecord()).toEqual({ 'old.png': png(1) })
+    await resetting
+    expect(sc.keys()).toEqual(['new.png'])
+    expect(onChange).not.toHaveBeenCalled()
+  })
+
+  it('a put issued AFTER reset() queues behind it and lands in the NEW session (never silently swallowed by the swap)', async () => {
+    const sc = createBinarySidecar({ retainBytes: true })
+    const resetting = sc.reset({ 'seed.png': png(1) })
+    const putting = sc.put('live.png', png(2))
+    await Promise.all([resetting, putting])
+    expect(sc.keys().sort()).toEqual(['live.png', 'seed.png'])
+  })
+
+  it('overlapping resets resolve in CALLER order: the later caller wins even when the earlier one hashes longer', async () => {
+    const sc = createBinarySidecar({ retainBytes: true })
+    const slow = Object.fromEntries(Array.from({ length: 40 }, (_, i) => [`slow${i}.png`, png(i)]))
+    const r1 = sc.reset(slow)
+    const r2 = sc.reset({ 'winner.png': png(9) })
+    await Promise.all([r1, r2])
+    expect(sc.keys()).toEqual(['winner.png'])
+  })
+
+  it('clear() is a silent session reseed: no per-entry removal events', async () => {
+    const sc = createBinarySidecar({ retainBytes: true })
+    await sc.put('a.png', png(1))
+    const onChange = vi.fn()
+    sc.onChange(onChange)
+    await sc.clear()
+    expect(sc.size).toBe(0)
+    expect(sc.toRecord()).toEqual({})
+    expect(onChange).not.toHaveBeenCalled()
+  })
+})