@dimina-kit/fs-core 0.2.0-dev.20260711062001 → 0.3.0-dev.6-dev.20260711140249

package/dist/worker-lib/protocol.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 declare const FS_CORE_ERROR_CODES: readonly ["readonly", "draining", "turn-closed", "turn-active", "turn-quota", "agent-token-required", "agent-token-gate-armed", "restore-conflict", "cas-mismatch", "edit-no-match", "edit-ambiguous", "not-found", "bad-path", "bad-args", "bad-op", "derived-readonly", "rotate-needed", "internal"];
+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 declare function getFsCoreErrorCode(error: unknown): FsCoreErrorCode | undefined;
+/** True when `error` is an fs-core RPC rejection carrying exactly `code`. */
+export declare function isFsCoreErrorCode(error: unknown, code: FsCoreErrorCode): boolean;
+/** Names of the unsolicited events the core worker pushes to its client. */
+export type FsCoreEventName = 'writer-granted' | 'writer-lost' | 'fs-change';
+/** 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;
+}
+//# sourceMappingURL=protocol.d.ts.map

package/dist/worker-lib/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/worker-lib/protocol.ts"],"names":[],"mappings":"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"}

package/dist/worker-lib/protocol.js

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+/**
+ * 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',
+];
+/**
+ * `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) {
+    if (!error || typeof error !== 'object' || !('code' in error))
+        return undefined;
+    const code = error.code;
+    return FS_CORE_ERROR_CODES.includes(code) ? code : undefined;
+}
+/** True when `error` is an fs-core RPC rejection carrying exactly `code`. */
+export function isFsCoreErrorCode(error, code) {
+    return getFsCoreErrorCode(error) === code;
+}

package/dist/worker-lib/rpc-types.d.ts

@@ -0,0 +1,68 @@
+/** 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;
+}
+//# sourceMappingURL=rpc-types.d.ts.map

package/dist/worker-lib/rpc-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rpc-types.d.ts","sourceRoot":"","sources":["../../src/worker-lib/rpc-types.ts"],"names":[],"mappings":"AAAA;;;2BAG2B;AAC3B,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AACD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;CACf;AACD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;CACb;AACD,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB"}

package/dist/worker-lib/wal-codec.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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]
+ *   len = len 字段之后的字节数；crc 覆盖 gen..meta 末尾。
+ */
+export declare const enc: TextEncoder;
+export declare const dec: TextDecoder;
+export declare const CRC_TABLE: Uint32Array<ArrayBuffer>;
+export declare function crc32(bytes: Uint8Array, start?: number, end?: number): number;
+export declare function sha256hex(bytes: Uint8Array): Promise<string>;
+export interface SlotInfo {
+    epoch: number;
+    compactGen: number;
+    walStartGen: number;
+    manifestCrc: number;
+}
+export declare const SLOT_SIZE = 64;
+export declare function encodeSlot(s: SlotInfo): Uint8Array;
+export declare function decodeSlot(bytes: Uint8Array): SlotInfo | null;
+/** 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;
+}
+export declare function frameRecord(gen: number, epoch: number, opcode: number, meta: unknown): Uint8Array;
+/** 解析一条记录；返回 {rec, next} 或 null（framing/CRC/commit 任一失败）。 */
+export declare function parseRecord(u8: Uint8Array, off: number): {
+    rec: WalRecord;
+    next: number;
+} | null;
+//# sourceMappingURL=wal-codec.d.ts.map

package/dist/worker-lib/wal-codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wal-codec.d.ts","sourceRoot":"","sources":["../../src/worker-lib/wal-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,GAAG,aAAoB,CAAA;AACpC,eAAO,MAAM,GAAG,aAAoB,CAAA;AAGpC,eAAO,MAAM,SAAS,0BAQlB,CAAA;AACJ,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,SAAI,EAAE,GAAG,GAAE,MAAqB,GAAG,MAAM,CAItF;AAED,wBAAsB,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlE;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB;AAGD,eAAO,MAAM,SAAS,KAAK,CAAA;AAI3B,wBAAgB,UAAU,CAAC,CAAC,EAAE,QAAQ,GAAG,UAAU,CAUlD;AACD,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,QAAQ,GAAG,IAAI,CAW7D;AAED;uDACuD;AACvD,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,CAAC,CAAC,EAAE,MAAM,CAAA;CACX;AAED,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,OAAO,CAAA;CACd;AAGD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,UAAU,CAgBjG;AACD,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAiBhG"}

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

@@ -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/dist/zip.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dimina-kit/fs-core",
-  "version": "0.2.0-dev.20260711062001",
+  "version": "0.3.0-dev.6-dev.20260711140249",
   "description": "Zero-dependency OPFS WAL filesystem core for the web, with an agent capability gate.",
   "keywords": [
     "dimina",
@@ -25,6 +25,12 @@
     "url": "https://github.com/EchoTechFE/dimina-kit/issues"
   },
   "homepage": "https://github.com/EchoTechFE/dimina-kit/tree/main/packages/fs-core#readme",
+  "imports": {
+    "#worker-lib/wal-codec.js": {
+      "types": "./src/worker-lib/wal-codec.ts",
+      "default": "./dist/worker-lib/wal-codec.js"
+    }
+  },
   "exports": {
     "./client": {
       "types": "./src/client.ts",
@@ -45,6 +51,23 @@
     "./sync": {
       "types": "./sync/sync-engine.ts",
       "default": "./dist/sync/sync-engine.js"
+    },
+    "./sync/binary-sidecar": {
+      "types": "./sync/binary-sidecar.ts",
+      "default": "./dist/sync/binary-sidecar.js"
+    },
+    "./sync/watch-expander": {
+      "types": "./sync/watch-expander.ts",
+      "default": "./dist/sync/watch-expander.js"
+    },
+    "./protocol": {
+      "types": "./src/worker-lib/protocol.ts",
+      "default": "./dist/worker-lib/protocol.js"
+    },
+    "./worker-files": {
+      "types": "./src/worker-files.ts",
+      "require": "./dist/worker-files.cjs",
+      "default": "./dist/worker-files.js"
     }
   },
   "files": [
@@ -65,7 +88,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.sync.build.json && node build-workers.js",
+    "build": "tsc -p tsconfig.worker-lib.build.json && 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",

package/src/__checks__/types-smoke.ts

@@ -4,6 +4,9 @@
  * Not a runtime test — only needs to satisfy `tsc --noEmit`.
  */
 import type { ProjectFsClient } from '@dimina-kit/fs-core/client'
+import type {
+  FsCheckpointOpts, FsRestoreOpts, FsTurnBeginOpts, FsWriteCallOpts,
+} 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'
@@ -21,3 +24,61 @@ export function typesSmoke(client: ProjectFsClient, fs: AgentToolsFs & DiskMirro
   void client.projectId
   return { tool: agent.byName.fs_read, zip, mirrorActive: mirror.active }
 }
+
+// ── Write-API contract smoke: client write methods must carry their real
+// worker-side opts/result shapes end to end, not the current `Record<string,
+// unknown> → Promise<unknown>` erasure (src/client.ts:200-232). Guards that
+// FsWriteCallOpts/FsCheckpointOpts/FsRestoreOpts/FsTurnBeginOpts and their
+// matching result types are exported from `/client` and threaded onto every
+// write method's signature. Not a runtime test — `tsc --noEmit` only.
+export async function fsWriteContractSmoke(client: ProjectFsClient): Promise<void> {
+  // 1) write()'s result carries {gen, rev} — `Promise<unknown>` cannot be
+  // assigned here, so this line only compiles once the return type is real.
+  const written: { gen: number; rev: number } = await client.write('a', 'b')
+  void written
+
+  // 2) every FsWriteCallOpts field is accepted by write()'s third param.
+  const fullOpts: FsWriteCallOpts = { actor: 'agent', turnId: 't', agentToken: 'x', ifMatch: 3 }
+  void client.write('a', 'b', fullOpts)
+
+  // 3) checkpoint/turnBegin/turnEnd expose their op-specific extra fields.
+  const cp = await client.checkpoint()
+  const cpId: string = cp.cpId
+  const turn = await client.turnBegin('t', { ttlMs: 1 })
+  const expiresAt: number = turn.expiresAt
+  const ended = await client.turnEnd('t')
+  const closed: boolean = ended.closed
+  void [cpId, expiresAt, closed]
+
+  // restore()/checkpoint() share the {actor,turnId,agentToken} shape by
+  // construction (FsRestoreOpts extends FsCheckpointOpts).
+  const restoreOpts: FsRestoreOpts = { baseGen: 1, force: true, actor: 'human' }
+  const checkpointOpts: FsCheckpointOpts = restoreOpts
+  void checkpointOpts
+  const beginOpts: FsTurnBeginOpts = { ttlMs: 500 }
+  void beginOpts
+}
+
+// ── Reverse guards: opts objects that violate the contract must NOT
+// type-check against it. Expressed as an "assign to never on regression"
+// trick (no @ts-expect-error — that counts as a type-escape under this
+// repo's ratchet): `Assignable<Bad, Good>` is `false` today, so `Guard`
+// below is `true` and the `const` assignment is inert; if a future change
+// widens FsWriteCallOpts enough that `Bad` becomes assignable, `Guard`
+// collapses to `never` and this file stops compiling.
+type Assignable<T, U> = [T] extends [U] ? true : false
+type RejectsBadActorLiteral = Assignable<{ actor: 'robot' }, FsWriteCallOpts> extends false ? true : never
+const _guardRejectsBadActorLiteral: RejectsBadActorLiteral = true
+void _guardRejectsBadActorLiteral
+
+// A misspelled key (`turnid` instead of `turnId`) is an excess-property
+// error, which TS only raises for a *fresh* object literal in assignment/
+// call position — not through a structural `extends` check like the one
+// above (every FsWriteCallOpts field is optional, so `{ turnid: 'x' }`
+// structurally satisfies it once the mismatched key is erased by widening).
+// Expressing "this typo must be rejected" as a standing assertion would
+// therefore need either @ts-expect-error (banned by the ratchet) or a
+// direct literal assignment that hard-fails compilation forever (defeats
+// the point of a check file meant to go green). Left unexpressed here;
+// verified manually instead — see below.
+//   const _typoRejected: FsWriteCallOpts = { turnid: 'x' } // <- real tsc error today: "'turnid' does not exist in type 'FsWriteCallOpts'"

package/src/agent-tools.ts

@@ -1,12 +1,12 @@
 /**
- * Agent 工具面（P4）—— MCP 形状的工具表包装 ProjectFsClient。
+ * Agent 工具面 —— MCP 形状的工具表包装 ProjectFsClient。
  *
- * 设计对应架构文档 §13：Agent 拿到的不是裸 FS，而是这张工具表 +（宿主铸造的）
+ * 设计立场：Agent 拿到的不是裸 FS，而是这张工具表 +（宿主铸造的）
  * turn 能力。要点：
  *  - execute 自动注入 {actor:'agent', turnId}：turnId 由 beginTurn 铸造并闭包持有，
  *    不出现在工具参数里 —— 模型伪造不了别的 turn。
  *  - 真正的执法在 fs-core（checkTurn 与 WAL append 同一同步块）；这里只是便利面。
- *  - inputSchema 用简化记法（K2 交付 Agent 组时再换成正式 JSON Schema + MCP server 包装）。
+ *  - inputSchema 用简化记法（对外交付 Agent 集成时再换成正式 JSON Schema + MCP server 包装）。
  *  - fs_read 返回完整内容，绝不截断（上游 8000 字符腰斩教训）。
  *
  * `AgentToolsFs` only declares the methods this file actually calls on the

package/src/client-retry.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Guards ProjectFsClient's write-RPC timeout semantics: a timed-out write op
+ * (which always carries an idempotent opId) is re-sent EXACTLY once with the
+ * same opId — the retry's own timer rejects terminally instead of re-entering
+ * the retry branch — and a plain read RPC (no opId) rejects on first timeout.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { ProjectFsClient } from './client.js'
+
+type Internals = Omit<ProjectFsClient, 'core'> & {
+  pending: Map<number, unknown>
+  seq: number
+  // Narrow structural stand-in for the real `Worker` — `_rpc` only posts.
+  core: { postMessage: (msg: unknown) => void }
+  _rpc<T>(op: string, args: Record<string, unknown>, opts?: { opId?: string; timeout?: number }): Promise<T>
+}
+
+function makeRpcClient(): { client: Internals; posted: Array<{ id: number; op: string; opId?: string }> } {
+  const posted: Array<{ id: number; op: string; opId?: string }> = []
+  const c = new ProjectFsClient() as unknown as Internals
+  c.pending = new Map()
+  c.seq = 0
+  c.core = { postMessage: (msg) => posted.push(msg as { id: number; op: string; opId?: string }) }
+  return { client: c, posted }
+}
+
+describe('ProjectFsClient — write-RPC timeout retry', () => {
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('re-sends once with the SAME opId, then rejects terminally on the retry timeout', async () => {
+    vi.useFakeTimers()
+    const { client, posted } = makeRpcClient()
+    const p = client._rpc('write', { path: 'a.txt' }, { opId: 'op-1', timeout: 1000 })
+    const rejected = expect(p).rejects.toThrow('write timeout (after retry)')
+    expect(posted).toHaveLength(1)
+
+    await vi.advanceTimersByTimeAsync(1000) // first timeout → one retry
+    expect(posted).toHaveLength(2)
+    expect(posted[1]!.opId).toBe('op-1')
+    expect(posted[1]!.id).not.toBe(posted[0]!.id)
+
+    await vi.advanceTimersByTimeAsync(1000) // retry timeout → terminal reject, no third send
+    await rejected
+    expect(posted).toHaveLength(2)
+    expect(client.pending.size).toBe(0)
+  })
+
+  it('a second timed-out call still gets its own retry (per-call, not per-client-lifetime)', async () => {
+    vi.useFakeTimers()
+    const { client, posted } = makeRpcClient()
+    const first = client._rpc('write', { path: 'a.txt' }, { opId: 'op-1', timeout: 1000 })
+    const firstRejected = expect(first).rejects.toThrow('timeout (after retry)')
+    await vi.advanceTimersByTimeAsync(2000)
+    await firstRejected
+
+    const second = client._rpc('write', { path: 'b.txt' }, { opId: 'op-2', timeout: 1000 })
+    const secondRejected = expect(second).rejects.toThrow('timeout (after retry)')
+    await vi.advanceTimersByTimeAsync(1000)
+    // The second call retried too — 2 sends for op-1 + 2 sends for op-2.
+    expect(posted.filter((m) => m.opId === 'op-2')).toHaveLength(2)
+    await vi.advanceTimersByTimeAsync(1000)
+    await secondRejected
+  })
+
+  it('an opId-less RPC with a timeout rejects on first timeout without a retry', async () => {
+    vi.useFakeTimers()
+    const { client, posted } = makeRpcClient()
+    const p = client._rpc('compact', {}, { timeout: 500 })
+    const rejected = expect(p).rejects.toThrow('compact timeout')
+    await vi.advanceTimersByTimeAsync(500)
+    await rejected
+    expect(posted).toHaveLength(1)
+  })
+})