@cmtlyt/lingshu-toolkit 0.5.0 → 0.7.0

package/dist/shared/lock-data/core/entry.d.ts

@@ -0,0 +1,133 @@
+/**
+ * lockData 主入口：组装 Registry / Adapters / Driver / Authority / Actions / ReadonlyView
+ *
+ * 对应 RFC.md「架构分层」「InstanceRegistry」「能力检测与降级」章节。
+ *
+ * 流程总览（wrapper 方案 + 单参数 API）：
+ *   lockData(options)
+ *     ├─ 顶层数组运行时拒绝（assertNotTopLevelArray，类型层已禁止；防擦除）
+ *     ├─ 参数校验（id / getValue / syncMode / listeners 等结构层）
+ *     ├─ 分派：id 存在 → defaultRegistry.getOrCreateEntry(id, options, factory)
+ *     │        id 缺失 → 直接执行 factory（无 Registry 跟踪）
+ *     │
+ *     ├─ factory 内部（entryFactory）：
+ *     │    ├─ pickDefaultAdapters(options.adapters)
+ *     │    ├─ prepareEntryData(id, options) —— 同步抛错走 LockDisposedError；
+ *     │    │   异步返回 { firstValue, dataReadyPromise }（首值 resolve 后由
+ *     │    │   `applyRemote` 写入 dataRef.current）
+ *     │    ├─ pickDriver({ adapters, options, id })
+ *     │    ├─ 构造 Entry 骨架（dataRef = { current: firstValue }；authority: null）
+ *     │    ├─ 若 syncMode='storage-authority' 且 id 存在 → 构造 StorageAuthority：
+ *     │    │   ├─ host = entry（提供 dataRef / applyRemote / rev / lastAppliedRev / epoch）
+ *     │    │   ├─ emitSync / emitCommit → fanoutSync / fanoutCommit
+ *     │    │   └─ registerTeardown(authority.dispose) + 发起 authority.init()
+ *     │    └─ 把 authority.init() 合成进 dataReadyPromise
+ *     │
+ *     ├─ createActions({ entry, options, releaseFromRegistry })
+ *     ├─ createReadonlyView(entry.dataRef) —— wrapper Proxy；trap 重定向到 dataRef.current
+ *     └─ 返回：dataReadyPromise === null ? [view, actions] : Promise<[view, actions]>
+ *
+ * 职责边界：
+ * - 参数校验只做"结构层"（类型 / 非空）；语义合法性（如 timeout < 0）由下游模块负责
+ * - Entry 构造期的部分字段（authority）是"一次性 readonly"：仅在 factory 内写入一次，
+ *   Entry 对外暴露后字段视为 frozen；用 mutable 视图收敛到 factory 闭包内
+ * - dataRef.current 在异步 resolve / commit / applyRemote 时由内部重新赋值；
+ *   wrapper Proxy view 自动看到最新值
+ */
+import { type ResolvedAdapters } from '../adapters/index';
+import type { CommitSource, LockDataMutation, LockDataOptions, LockDataResult, SyncSource } from '../types';
+import { type Entry, type EntryFactory } from './registry';
+/**
+ * @internal 仅供测试使用，不通过 index.ts 公开导出
+ *
+ * 重置进程级 Registry，用于测试间隔离（模拟"新 Tab / 新进程"场景）
+ *
+ * 注意：不会清理已有 Entry 的 teardown；调用者需自行确保没有活跃的 Entry 引用
+ */
+declare function __resetDefaultRegistry(): void;
+/**
+ * 构造期的可变 Entry 视图
+ *
+ * 在 factory 闭包内把全部字段视为可写，便于 `onStateChange` 写回状态 /
+ * authority 构造后回写 authority 引用；返回给调用方后视为 frozen
+ */
+type MutableEntry<T extends object> = {
+    -readonly [K in keyof Entry<T>]: Entry<T>[K];
+};
+/**
+ * 注册 authority 自 emit 回调的 teardown 守卫容器
+ *
+ * 生命周期：Entry 销毁时置 `disposed=true`，fanout 回调即使被滞后触发也直接 no-op
+ */
+interface FanoutGuard {
+    disposed: boolean;
+}
+/**
+ * emitCommit 事件体；由 StorageAuthority 在 onCommitSuccess 内部构造并透传（已包含 rev）
+ */
+interface AuthorityCommitEvent<T> {
+    readonly source: CommitSource;
+    readonly token: string;
+    readonly rev: number;
+    readonly mutations: readonly LockDataMutation[];
+    readonly snapshot: T;
+}
+/** emitSync 事件体；由 StorageAuthority 在 applyAuthorityIfNewer 内部构造并透传 */
+interface AuthoritySyncEvent<T> {
+    readonly source: SyncSource;
+    readonly rev: number;
+    readonly snapshot: T;
+}
+declare function buildEmitCommit<T extends object>(entry: Entry<T>, guard: FanoutGuard): (event: AuthorityCommitEvent<T>) => void;
+declare function buildEmitSync<T extends object>(entry: Entry<T>, guard: FanoutGuard): (event: AuthoritySyncEvent<T>) => void;
+/**
+ * 构造 StorageAuthority 并写回 entry.authority；返回 init Promise
+ *
+ * 仅在 `syncMode === 'storage-authority' && id` 时调用；authority 构造失败时
+ * 走 logger.warn（RFC「权威副本不可用 → 退化为同进程共享」），返回 null Promise
+ *
+ * wrapper 方案差异：
+ * - 不再注入 `applySnapshot` 钩子（authority 通过 `host.applyRemote(next)` 完成原子覆写）
+ * - 不再注入 `clone` 函数（authority 内部走 JSON 拷贝隔离）
+ */
+declare function attachAuthority<T extends object>(mutableEntry: MutableEntry<T>, options: LockDataOptions<T>, adapters: ResolvedAdapters<T>, id: string): Promise<void> | null;
+/**
+ * 合成 dataReadyPromise + authority.init() 为统一的就绪 Promise
+ *
+ * 两个 Promise 至少一个非 null 时返回合成结果；都为 null 时返回 null
+ */
+declare function mergeReadyPromises(dataReady: Promise<void> | null, authorityReady: Promise<void> | null): Promise<void> | null;
+/**
+ * lockData 主入口（单参数 + getValue 必传）
+ *
+ * 返回值类型：
+ * - getValue 同步返回 + 未启用 authority → `readonly [T, LockDataActions<T>]`
+ * - getValue 返回 Promise 或 syncMode='storage-authority' → `Promise<readonly [T, LockDataActions<T>]>`
+ *
+ * 初始化失败（getValue reject / getValue 同步抛错）时：
+ * - 同步路径：抛 `LockDisposedError`（getValue 同步抛错时 prepareEntryData 直接向上抛）
+ * - 异步路径：返回的 Promise reject `LockDisposedError`（cause 携带原始错误）
+ *
+ * id 冲突：同 id 多次调用 lockData 复用同一份 Entry（dataRef / driver / adapters / authority 共享），
+ * 自第二次起 getValue 不被重新执行（首值由首次调用产出）；非 listeners 字段冲突走 logger.warn
+ */
+declare function lockData<T extends object>(options: LockDataOptions<T>): LockDataResult<T> | Promise<LockDataResult<T>>;
+/**
+ * 无 id 路径：直接执行 factory；teardowns 在 dispose 时运行（Registry 不介入）
+ *
+ * 入参拆分：
+ * - 第一个参数 `'__local__'` 写入 `Entry.id`（展示用占位），用于日志、错误消息等稳定文本输出
+ * - 第二个参数 `undefined` 写入 `Entry.lockId`（语义判定用真实 id）；
+ *   下游 `pickDriver` / `attachAuthority` / driver acquire `name` 都以此识别"无真实 id"分支：
+ *     - pickDriver 看到 undefined → LocalLockDriver（mode 字段被忽略）
+ *     - syncMode='storage-authority' 不会启用 authority
+ *     - driver acquire 的 `name` 走 `${LOCK_PREFIX}:__local__` 占位
+ *
+ * 详见 `src/shared/lock-data/fixes/standalone-id-leak.md`
+ */
+declare function acquireStandalone<T extends object>(options: LockDataOptions<T>, factory: EntryFactory<T>): {
+    entry: Entry<T>;
+    releaseFromRegistry: () => void;
+};
+export type { FanoutGuard, MutableEntry };
+export { __resetDefaultRegistry, acquireStandalone, attachAuthority, buildEmitCommit, buildEmitSync, lockData, mergeReadyPromises, };

package/dist/shared/lock-data/core/entry.js

@@ -0,0 +1 @@
+import{isObject as e,isString as t}from"../../utils/index.js";import{pickDefaultAdapters as r}from"../adapters/index.js";import{createStorageAuthority as o}from"../authority/index.js";import{DEFAULT_SESSION_PROBE_TIMEOUT as n}from"../constants.js";import{pickDriver as s}from"../drivers/index.js";import{cloneByJson as i}from"../utils/json-safe.js";import{createActions as a}from"./actions.js";import{fanoutCommit as l,fanoutSync as d}from"./fanout.js";import{createReadonlyView as u}from"./readonly-view.js";import{createInstanceRegistry as m,prepareEntryData as c}from"./registry.js";let g=null;function y(){g=null}function p(e,t){return r=>{t.disposed||l(e.listenersSet,r,e.adapters.logger)}}function h(e,t){return r=>{t.disposed||d(e.listenersSet,r,e.adapters.logger)}}function f(e,t,r,s){let i="persistent"===t.persistence?"persistent":"session",a=r.getAuthority({id:s}),l=r.getChannel({id:s,channel:"session"}),d=r.getSessionStore({id:s});if(null===a&&null===l&&null===d)return r.logger.warn(`[lockData] syncMode='storage-authority' requested on id=${s} but no authority/channel/sessionStore adapter is available; fallback to in-process sharing only`),null;let u={disposed:!1},m=o({host:e,authority:a,channel:l,sessionStore:d,persistence:i,sessionProbeTimeout:t.sessionProbeTimeout??n,logger:r.logger,emitSync:h(e,u),emitCommit:p(e,u)});return e.authority=m,e.registerTeardown(()=>m.dispose()),e.registerTeardown(()=>{u.disposed=!0}),m.init().then(()=>{},e=>{r.logger.warn(`[lockData] StorageAuthority.init failed on id=${s}`,e)})}function v(e,t){return null!==e&&null!==t?Promise.all([e,t]).then(()=>void 0):e??t}function w(o){var n,l,d,y,p;let h,w,P=function(e){let{id:r}=e;return t(r)&&r.length>0?r:void 0}(o),R=(t,o,n,a)=>{var l,d;let u=r(n.adapters),m=c(t,n),g=s({adapters:u,options:n,id:o}),y=new Set;e(n.listeners)&&y.add(n.listeners);let p={current:m.firstValue},h=e=>{p.current=i(e)},w={id:t,lockId:o,dataRef:p,driver:g,adapters:u,authority:null,listenersSet:y,initOptions:Object.freeze({timeout:n.timeout,mode:n.mode,syncMode:n.syncMode,persistence:n.persistence,sessionProbeTimeout:n.sessionProbeTimeout}),dataReadyPromise:null,registerTeardown:a.registerTeardown,refCount:1,rev:0,lastAppliedRev:0,epoch:null,applyRemote:h},j=(l=h,null===(d=m.dataReadyPromise)?null:d.then(e=>{l(e)})),P="storage-authority"==("storage-authority"===n.syncMode?"storage-authority":"none")&&void 0!==o?f(w,n,u,o):null;return w.dataReadyPromise=v(j,P),w},{entry:S,releaseFromRegistry:b}=void 0===P?j(o,R):(n=P,l=o,d=R,{entry:(h=(null===g&&(g=m()),g)).getOrCreateEntry(n,l,d),releaseFromRegistry:()=>{h.releaseEntry(n,l.listeners)}}),T=a({entry:S,options:o,releaseFromRegistry:b}),k=u(S.dataRef);return y=S,w=[k,p=T],null===y.dataReadyPromise?w:y.dataReadyPromise.then(()=>w,e=>{throw p.dispose(),e})}function j(e,t){let r=[],o={value:!0},n=t("__local__",void 0,e,{registerTeardown:e=>{o.value&&r.push(e)}});return{entry:n,releaseFromRegistry:()=>{if(o.value){o.value=!1;for(let e=r.length-1;e>=0;e--)try{r[e]()}catch(e){n.adapters.logger.warn("[lockData] standalone teardown threw",e)}r.length=0;try{n.driver.destroy()}catch(e){n.adapters.logger.warn("[lockData] standalone driver.destroy threw",e)}}}}}export{y as __resetDefaultRegistry,j as acquireStandalone,f as attachAuthority,p as buildEmitCommit,h as buildEmitSync,w as lockData,v as mergeReadyPromises};

package/dist/shared/lock-data/core/fanout.d.ts

@@ -0,0 +1,42 @@
+/**
+ * listeners fanout：把 driver / authority / actions 产生的事件分发给 Entry 的全部 listener
+ *
+ * 对应 RFC.md L666-667「listeners 不冲突 / listener 异常隔离」契约：
+ * - 每个实例的 `listeners` 独立保存在 `Entry.listenersSet` 中
+ * - 事件触发时遍历 Set 向每个 listener 的对应 hook 分发
+ * - 单个 listener 抛错（同步 throw / 异步 Promise reject）通过 logger.error
+ *   统一吞掉 + 记录，继续向剩余 listener 分发，不阻断 actions 状态机
+ *
+ * 设计边界：
+ * - 本模块**不产生**事件：事件对象由上游（actions / authority）构造好传入
+ * - 本模块**不管理订阅**：订阅通过 `entry.listenersSet.add/delete` 操作，
+ *   Registry 的 `releaseEntry` / `getOrCreateEntry` 已负责 Set 的增删
+ * - listener 未提供对应 hook 时跳过（不调用 undefined）
+ */
+import type { ResolvedLoggerAdapter } from '../adapters/logger';
+import type { CommitEvent, LockDataListeners, LockStateChangeEvent, RevokeEvent, SyncEvent } from '../types';
+/**
+ * fanoutLockStateChange：状态机流转事件（idle → acquiring → holding → ...）
+ *
+ * 触发时机：Actions 状态机每次状态切换（见 RFC L933「每一步状态流转都通过
+ * listenersFanout.onLockStateChange(event) 分发到所有实例的 listeners」）
+ */
+declare function fanoutLockStateChange<T extends object>(listeners: Iterable<LockDataListeners<T>>, event: LockStateChangeEvent, logger: ResolvedLoggerAdapter): void;
+/**
+ * fanoutRevoked：持有锁被 driver 驱逐 / timeout / dispose 主动释放时触发
+ */
+declare function fanoutRevoked<T extends object>(listeners: Iterable<LockDataListeners<T>>, event: RevokeEvent, logger: ResolvedLoggerAdapter): void;
+/**
+ * fanoutCommit：commit 成功时触发（RFC L1201 onCommitSuccess 写路径）
+ *
+ * 事件中的 snapshot 必须是**已 clone 的独立副本**，由调用方保证
+ * （StorageAuthority.onCommitSuccess 已在调用处 clone）
+ */
+declare function fanoutCommit<T extends object>(listeners: Iterable<LockDataListeners<T>>, event: CommitEvent<T>, logger: ResolvedLoggerAdapter): void;
+/**
+ * fanoutSync：authority 拉到新快照时触发（RFC L1214）
+ *
+ * 来源包括：pull-on-acquire / storage-event / pageshow / visibilitychange
+ */
+declare function fanoutSync<T extends object>(listeners: Iterable<LockDataListeners<T>>, event: SyncEvent<T>, logger: ResolvedLoggerAdapter): void;
+export { fanoutCommit, fanoutLockStateChange, fanoutRevoked, fanoutSync };

package/dist/shared/lock-data/core/fanout.js

@@ -0,0 +1 @@
+import{isFunction as o,isObject as n}from"../../utils/index.js";function t(t,e,r,c,i){for(let a of t){let t,f=r(a);if(f){try{t=f(c)}catch(o){i.error(`[lockData] listener threw (${e})`,o);continue}n(t)&&"then"in t&&o(t.then)&&Promise.resolve(t).catch(o=>{i.error(`[lockData] listener threw (${e})`,o)})}}}function e(o,n,e){t(o,"onLockStateChange",o=>o.onLockStateChange,n,e)}function r(o,n,e){t(o,"onRevoked",o=>o.onRevoked,n,e)}function c(o,n,e){t(o,"onCommit",o=>o.onCommit,n,e)}function i(o,n,e){t(o,"onSync",o=>o.onSync,n,e)}export{c as fanoutCommit,e as fanoutLockStateChange,r as fanoutRevoked,i as fanoutSync};

package/dist/shared/lock-data/core/readonly-view.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 深只读代理：用户从 lockData 拿到的第一个返回值
+ *
+ * 实现要点（wrapper Proxy 方案，对应 RFC.md「ReadonlyView<T>」+「引用稳定契约」章节）：
+ *
+ * - **wrapper Proxy**：顶层 view 是 `new Proxy(dataRef, ROOT_HANDLER)`，target 为
+ *   稳定 `dataRef = { current: T }` 引用；handler 把所有 trap 重定向到 `dataRef.current`
+ *   - 引用稳定：`dataRef` 引用在 Entry 生命周期内永不变更
+ *   - 跟随重新赋值：commit / `applyRemote` / 异步 getValue resolve 时 `dataRef.current` 重新赋值，
+ *     view 上后续读取自动看到最新值，无需重建 Proxy
+ *
+ * - **嵌套递归**：get 到对象类型的属性时，惰性创建嵌套 readonly Proxy
+ *   - 嵌套节点直接代理 `T` 类型的子对象（不需要 wrapper 间接层）
+ *   - WeakMap<object, Proxy> 缓存：同一子对象多次访问拿到同一代理，引用比较有效
+ *
+ * - **写拦截**：set / deleteProperty / defineProperty / setPrototypeOf 统一抛 `ReadonlyMutationError`
+ *
+ * - **JSON-safe 契约**：本期 lockData 强制数据为 JSON 安全（getValue / replace 入口由
+ *   `assertJsonSafe` 校验），故 readonly-view 不再处理 Set / Map / Date / class instance
+ *   等非 JSON 类型；仅需处理 plain object / array
+ *
+ * - **顶层数组禁止**：`dataRef.current` 在类型层（`LockDataValueShape<T>`）+ 运行时
+ *   （`assertNotTopLevelArray`）双重排除顶层数组，wrapper 方案下 `Object.keys` /
+ *   `JSON.stringify` 等不变量冲突自然消失
+ *
+ * - **判型一致性瑕疵**：`Object.isFrozen(view)` 返回 `false`（因为 target 是 wrapper
+ *   对象不是 frozen 的），但用户对 view 任何写入操作都会被 trap 拒绝抛 `ReadonlyMutationError`。
+ *   这是 wrapper 方案的轻微语义瑕疵，判定只读应通过约定（"由 lockData 返回的 view 必只读"）
+ */
+/**
+ * wrapper 引用：每个 Entry 持有一个稳定的 `{ current: T }`，view Proxy 以此为 target
+ *
+ * - `current` 在 commit / `applyRemote` / 异步 getValue resolve 时重新赋值
+ * - view Proxy 通过 ROOT_HANDLER 把所有 trap 重定向到 `current`
+ */
+interface DataRef<T extends object> {
+    current: T;
+}
+/**
+ * 创建顶层 readonly view（wrapper Proxy）
+ *
+ * @param dataRef 稳定的 `{ current: T }` 引用；commit / applyRemote / 异步 resolve 时
+ *                重新赋值 `dataRef.current`，view 自动看到最新值
+ *
+ * 缓存：同一 `dataRef` 多次创建 view 拿到同一代理（基于 WeakMap<dataRef, Proxy>）
+ */
+declare function createReadonlyView<T extends object>(dataRef: DataRef<T>): T;
+export type { DataRef };
+export { createReadonlyView };

package/dist/shared/lock-data/core/readonly-view.js

@@ -0,0 +1 @@
+import{throwError as e}from"../../throw-error/index.js";import{ERROR_FN_NAME as t}from"../constants.js";import{ReadonlyMutationError as r}from"../errors/index.js";let o=new WeakMap;function n(e){return"object"==typeof e&&null!==e}function f(){e(t,"cannot mutate readonly view",r)}let l={get(e,t,r){let o=Reflect.get(e,t,r);return n(o)?i(o):o},set:f,deleteProperty:f,defineProperty:f,setPrototypeOf:f};function i(e){let t=o.get(e);if(void 0!==t)return t;let r=new Proxy(e,l);return o.set(e,r),r}let c={get(e,t){let r=Reflect.get(e.current,t);return n(r)?i(r):r},set:f,deleteProperty:f,defineProperty:f,setPrototypeOf:f,has:(e,t)=>Reflect.has(e.current,t),ownKeys:e=>Reflect.ownKeys(e.current),getOwnPropertyDescriptor:(e,t)=>{let r=Reflect.getOwnPropertyDescriptor(e.current,t);if(void 0!==r)return{...r,writable:!1,configurable:!0}},getPrototypeOf:e=>Reflect.getPrototypeOf(e.current)};function u(e){let t=o.get(e);if(void 0!==t)return t;let r=new Proxy(e,c);return o.set(e,r),r}export{u as createReadonlyView};

package/dist/shared/lock-data/core/registry.d.ts

@@ -0,0 +1,282 @@
+/**
+ * InstanceRegistry：同 id 进程内单例池
+ *
+ * 对应 RFC.md「InstanceRegistry（同 id 进程内单例）」章节。
+ *
+ * 职责：
+ * - 按 id 缓存 Entry；同 id 再次 lockData(...) 复用同一份 dataRef / driver / adapters / authority
+ * - refCount 管理：每次 lockData(...) +1，actions.dispose() -1，归零时销毁 Entry
+ * - listenersSet 管理：每实例独立保留一份 listeners，driver 事件向全部 fanout
+ * - dataReadyPromise 共享：getValue 返回 Promise 时，同 id 多实例共享同一个就绪 Promise；
+ *   resolve 后由外部 factory 调用 `entry.applyRemote(awaited)` 把 dataRef.current 重新赋值
+ * - initOptions 冲突检查：非 listeners 字段与首次注册不一致时走 logger.warn，以首次为准
+ *
+ * 设计边界：
+ * - 本模块**不感知** actions 状态机 / Draft / fanout / authority 的具体实现
+ * - Entry 的构造（pickDriver / pickDefaultAdapters / 初始化 data）由外部 `EntryFactory` 完成
+ * - Registry 通过 `EntryFactoryContext.registerTeardown` 把销毁回调通道注入给 factory；
+ *   StorageAuthority / fanout 等模块通过此回调登记清理，Registry 在 refCount 归零时逆序运行
+ * - 无 id 场景不进入本 Registry（由 entry.ts 直接构造独立 Entry）
+ *
+ * wrapper 方案契约（与旧契约的根本差异）：
+ * - `Entry.dataRef` 引用本身在 Entry 生命周期内永不变更
+ * - `Entry.dataRef.current` 在以下场景被重新赋值（`= JSON.parse(JSON.stringify(next))`）：
+ *   ① 异步 getValue resolve 后；② commit 成功后；③ `entry.applyRemote(next)` 远程同步
+ * - readonly view 通过 wrapper Proxy 跟随 `dataRef.current`，所有用户读取都看到最新值
+ */
+import type { ResolvedAdapters } from '../adapters/index';
+import type { StorageAuthority } from '../authority/index';
+import type { LockDriver } from '../drivers/index';
+import type { LockDataListeners, LockDataOptions, LockMode, Persistence, SyncMode, TimeoutValue } from '../types';
+/**
+ * Entry 结构：同 id 共享的全部状态
+ *
+ * 字段说明对应 RFC「Entry 结构关键字段」表格。
+ *
+ * 引用稳定性（wrapper 方案）：
+ * - `dataRef` 引用本身在 Entry 生命周期内永不变更
+ * - `dataRef.current` 在 commit / `applyRemote` / 异步 getValue resolve 时被重新赋值
+ * - readonly view 通过 wrapper Proxy（target = dataRef）跟随 `dataRef.current`
+ */
+interface Entry<T extends object> {
+    /**
+     * 锁的展示用 id；用于日志、错误消息、Registry slot key 等"对外稳定文本"输出
+     *
+     * - Registry 路径：等于真实 id（非空字符串）
+     * - Standalone（无 id）路径：占位字符串 `'__local__'`
+     *
+     * **重要**：永远不要拿这个字段去做"是否有真实 id"的语义判定 —— standalone 路径
+     * 它只是占位。语义判定请使用 `lockId` 字段（详见下方）
+     */
+    readonly id: string;
+    /**
+     * 真实锁 id；用于"是否启用跨 Tab 能力"的语义判定
+     *
+     * - Registry 路径：与 `id` 同值（必为非空字符串）
+     * - Standalone（无 id）路径：`undefined`，由此驱动 `pickDriver` 走 LocalLockDriver、
+     *   `syncMode='storage-authority'` 不启用 authority、driver acquire `name` 走本地占位
+     *
+     * 详见 `src/shared/lock-data/fixes/standalone-id-leak.md`
+     */
+    readonly lockId: string | undefined;
+    /**
+     * 共享数据 wrapper 引用
+     *
+     * - `dataRef` 引用本身在 Entry 生命周期内永不变更
+     * - `dataRef.current` 在 commit / `applyRemote` / 异步 getValue resolve 时被重新赋值
+     * - readonly view 通过 wrapper Proxy（target = dataRef）跟随 `dataRef.current`
+     *
+     * 不直接暴露 `T` 引用（而是包一层 `{ current: T }`）是为了让 wrapper Proxy 始终持有
+     * 一个稳定的 target，commit / 远程同步只需替换 `dataRef.current`，无需重建 view
+     */
+    readonly dataRef: {
+        current: T;
+    };
+    /**
+     * 远程同步入口：替换 `dataRef.current`
+     *
+     * 内部执行 `dataRef.current = JSON.parse(JSON.stringify(next))`，
+     * 由 authority 远程 push / 异步 getValue resolve 等场景调用
+     *
+     * JSON 拷贝隔离契约：调用方传入的 `next` 对象与内部 `dataRef.current` 完全隔离，
+     * 任一方的后续 mutate 都不会影响另一方
+     */
+    readonly applyRemote: (next: T) => void;
+    /** 共享锁驱动实例；由首次 pickDriver 产出，Entry 销毁时 destroy */
+    readonly driver: LockDriver;
+    /** 已解析适配器集合 */
+    readonly adapters: ResolvedAdapters<T>;
+    /**
+     * 跨 Tab 权威副本（对应 RFC L646）
+     *
+     * - `syncMode === 'storage-authority'` 时由 factory 构造并注入
+     * - 其他 syncMode / 无 id 场景下为 null
+     *
+     * 生命周期：factory 创建后通过 registerTeardown 注册 `authority.dispose`，
+     * Entry 销毁时随 teardown 统一释放
+     */
+    readonly authority: StorageAuthority<T> | null;
+    /** 每实例独立的 listeners；driver 事件向全部 fanout */
+    readonly listenersSet: Set<LockDataListeners<T>>;
+    /** 首次注册的冻结配置；用于后续同 id 实例的冲突检查 */
+    readonly initOptions: FrozenInitOptions;
+    /**
+     * 异步初始化未就绪场景的等待依据
+     *
+     * - 同步路径下为 `null`（Entry 构造瞬间即已就绪）
+     * - 异步路径下持有合成 Promise，resolve 时表示 `dataRef.current` 已被赋值为真实值
+     *
+     * 真实用途场景（详见 fixes/api-getvalue-only-redesign.md §14.3）：
+     * ① 同 Tab 二次 lockData 调用方命中已存在 Entry 但首次调用尚未 resolve
+     * ② authority.init 等待异步初始化完成后再做远程拉取
+     * ③ 异步初始化期间 Entry 提前注册 + 二次调用方共享
+     *
+     * 异步初始化失败时 Promise reject，所有持有此 Entry 的同 Tab 调用方
+     * 在 action 时通过 `ensureDataReady` 抛 `LockDisposedError`（cause 携带原始原因）
+     */
+    readonly dataReadyPromise: Promise<void> | null;
+    /**
+     * 注册 Entry 销毁回调；refCount 归零时逆序调用
+     *
+     * 调用异常隔离：单个回调抛错通过 logger.warn 捕获，继续运行后续回调
+     * Entry 已进入销毁流程后再调用本方法，回调被静默丢弃
+     */
+    readonly registerTeardown: (teardown: () => void) => void;
+    /** 引用计数；每次 lockData(...) +1，actions.dispose() -1；归零销毁 Entry */
+    refCount: number;
+    /** 当前数据的权威单调序号；commit 成功 +1，初始 0 */
+    rev: number;
+    /** 最近一次应用 authority snapshot 的 rev；与 rev 分离用于去重 */
+    lastAppliedRev: number;
+    /** 当前 Tab 所属会话纪元；persistent 策略为 'persistent'，session 策略首次为 null */
+    epoch: string | null;
+}
+/**
+ * 首次注册冻结的配置子集，用于冲突检查
+ *
+ * 仅记录 RFC 要求"跨实例必须一致"的字段；listeners / signal / getValue / adapters 等
+ * 每实例独立字段不参与冲突检查
+ */
+interface FrozenInitOptions {
+    readonly timeout: TimeoutValue | undefined;
+    readonly mode: LockMode | undefined;
+    readonly syncMode: SyncMode | undefined;
+    readonly persistence: Persistence | undefined;
+    readonly sessionProbeTimeout: number | undefined;
+}
+/**
+ * EntryFactory 调用上下文
+ *
+ * Registry 把生命周期通道（`registerTeardown`）通过此对象注入 factory；
+ * factory 组装 Entry 时直接把 `registerTeardown` 写进 Entry 字段
+ */
+interface EntryFactoryContext {
+    /** 供 factory 写进 Entry 的 `registerTeardown`；Registry 归零时使用这些回调 */
+    readonly registerTeardown: (teardown: () => void) => void;
+}
+/**
+ * Entry 构造工厂：由外部（entry.ts）注入，避免 Registry 直接依赖 driver / adapter 层
+ *
+ * 工厂契约：
+ * 1. 解析 adapters（pickDefaultAdapters）→ 解析 driver（pickDriver）
+ * 2. 按 `prepareEntryData` 准备 `dataRef` / `applyRemote` / `dataReadyPromise`
+ *    （同步路径直接得到首值；异步路径下 Entry 构造延迟到 awaited resolve 之后）
+ * 3. 把 `ctx.registerTeardown` 写入返回 Entry 的 `registerTeardown` 字段
+ * 4. refCount 初始 1，listenersSet 含当次 options.listeners（若提供）
+ * 5. 把入参 `id` 写入 `Entry.id`、`lockId` 写入 `Entry.lockId`
+ *
+ * 工厂抛错时 Registry 不会把条目放入 Map —— **partial 资源的清理由 factory 自己负责**
+ * （factory 应当在内部用 try/catch 处理中途失败；例如已构造的 driver、已注册的订阅等）。
+ * Registry 不介入 partial 构造链，避免在无 logger 可用的场景被迫使用 console 兜底
+ *
+ * 参数语义：
+ * - `id`：展示用 id（必为非空字符串）；Registry 路径下 = 真实 id，
+ *   standalone 路径下 = 占位 `'__local__'`
+ * - `lockId`：真实 id；Registry 路径下与 `id` 同值，standalone 路径下为 `undefined`
+ *   下游（pickDriver / attachAuthority / driver acquire name）必须基于此参数
+ *   做"是否有真实 id"的语义判定，详见 `fixes/standalone-id-leak.md`
+ */
+type EntryFactory<T extends object> = (id: string, lockId: string | undefined, options: LockDataOptions<T>, ctx: EntryFactoryContext) => Entry<T>;
+/** Registry 对外 API */
+interface InstanceRegistry {
+    /**
+     * 获取或创建指定 id 的 Entry
+     *
+     * - 命中已存在 Entry：refCount++ + 加入 listenersSet + 冲突检查 + 返回
+     * - 首次创建：调用 factory 构造 Entry 并注册
+     *
+     * 命中已存在 Entry 时**不会**等待 dataReadyPromise：Actions 层通过
+     * `await entry.dataReadyPromise` 自行感知初始化失败，由 Actions 层抛 LockDisposedError
+     *
+     * @throws 仅在 id 为空字符串时抛错（其他参数合法性由调用方保证）
+     */
+    getOrCreateEntry: <T extends object>(id: string, options: LockDataOptions<T>, factory: EntryFactory<T>) => Entry<T>;
+    /**
+     * 释放指定实例对 Entry 的持有
+     *
+     * - 若传入 listeners 则从 listenersSet 移除（Set.delete 幂等）
+     * - refCount--；归零时逆序运行 teardownCallbacks → driver.destroy() → registry.delete(id)
+     * - 未命中 id / refCount 已为 0 时 no-op（幂等）
+     */
+    releaseEntry: <T extends object>(id: string, listeners: LockDataListeners<T> | undefined) => void;
+    /** 仅用于测试 / 调试 */
+    readonly peek: {
+        has: (id: string) => boolean;
+        size: () => number;
+    };
+}
+/** 冻结 options 子集用于冲突检查 */
+declare function freezeInitOptions<T extends object>(options: LockDataOptions<T>): FrozenInitOptions;
+/**
+ * 创建一个独立的 InstanceRegistry
+ *
+ * 通常单进程只创建一个（由 entry.ts 持有模块级单例），但允许测试构造隔离实例
+ */
+declare function createInstanceRegistry(): InstanceRegistry;
+/**
+ * `prepareEntryData` 的产物；由 EntryFactory 用来组装 Entry 字段
+ *
+ * 字段语义：
+ * - `firstValue`：进入 Entry 时 `dataRef.current` 的首个值（已经过 JSON 拷贝隔离）
+ * - `dataReadyPromise`：异步路径下的就绪等待依据；同步路径下为 `null`
+ *
+ * 与旧版 `InitialDataPatch` 的差异：
+ * - 不再返回引用稳定的 `data`（wrapper 方案下 `dataRef.current` 可被重新赋值，无需引用稳定）
+ * - 不再返回 `dataReadyState` / `dataReadyError` 字段（这两个字段已删除）
+ * - 同步抛错路径不返回 patch，而是直接抛 `LockDisposedError`（Entry 不构造）
+ */
+interface EntryInitialData<T extends object> {
+    /**
+     * 进入 Entry 时 `dataRef.current` 的初始值
+     *
+     * - **同步路径**：已经过 `assertJsonSafeInput` + `cloneByJson` 隔离，是真实首值
+     * - **异步路径**：占位 `{} as T`；真实首值通过 `dataReadyPromise` resolve 时携带的值，
+     *   由 EntryFactory 在 resolve 后调用 `entry.applyRemote(awaited)` 写入 `dataRef.current`
+     */
+    readonly firstValue: T;
+    /**
+     * 异步就绪通道（同步路径为 `null`）
+     *
+     * - 异步路径 resolve 时携带 awaited 真实首值（已经过 `assertJsonSafeInput` 校验）；
+     *   EntryFactory 拿到该值后 `applyRemote(awaited)` 写入 `dataRef.current`
+     * - 异步路径 reject 时携带 `LockDisposedError`（cause 字段保留原始 reject 原因）
+     * - 同步路径下首值已写入 `firstValue`，无需异步通道
+     *
+     * 通道资源严禁外泄：仅 `EntryFactory` 内部使用；`Entry.dataReadyPromise` 是
+     * 经过 `.then(() => undefined)` 抹平后的 `Promise<void>`，对外只暴露就绪与否
+     */
+    readonly dataReadyPromise: Promise<T> | null;
+}
+/**
+ * 按 `options.getValue` 形态准备 Entry 的首值 + dataReadyPromise
+ *
+ * 两种形态（types 层已强制 `getValue` 必传）：
+ *
+ * 1. **同步路径**：`getValue()` 返回非 PromiseLike
+ *    - 同步抛错 → 抛 `LockDisposedError`（Entry 不构造，不进 registry）
+ *    - 顶层数组 / 非 JSON-safe 值 → 抛 `InvalidOptionsError` / `TypeError`（Entry 不构造）
+ *    - 正常返回 → `firstValue = cloneByJson(returned)`，`dataReadyPromise = null`
+ *
+ * 2. **异步路径**：`getValue()` 返回 Promise / thenable
+ *    - 占位 `firstValue = {} as T`；真实首值通过 `dataReadyPromise` resolve 时携带（仅一次 await）
+ *    - resolve 后 `assertJsonSafeInput` 校验 awaited，校验失败 → reject `LockDisposedError`
+ *    - 原始 Promise reject → reject `LockDisposedError`（cause 携带原始原因）
+ *    - **Entry 构造延迟到 awaited resolve 之后**：调用方 `lockData()` 在 resolve 前不返回元组
+ *
+ * 校验闸单点收敛：所有进入 `dataRef.current` 的值（同步 / 异步）都在本函数内统一走
+ * `assertJsonSafeInput`，调用方拿到 firstValue 时已是 JSON 安全状态
+ */
+declare function prepareEntryData<T extends object>(id: string, options: LockDataOptions<T>): EntryInitialData<T>;
+/**
+ * 构造 LockDisposedError，cause 字段携带 getValue 原始 reject 原因
+ *
+ * 由本模块（同步抛错路径）+ Actions 层（异步 dataReadyPromise reject 路径）共同调用，
+ * 对外统一抛 LockDisposedError。
+ *
+ * 放在本模块的理由：`LockDisposedError + cause` 的错误格式是 Registry 对外的数据契约
+ * （RFC 规定"错误 cause 字段携带 getValue 原始 reject 原因"）—— 让同一处代码产出
+ * 同步路径与异步路径下的 LockDisposedError，避免契约漂移
+ */
+declare function createFailedInitError(id: string, cause: unknown): Error;
+export type { Entry, EntryFactory, EntryFactoryContext, EntryInitialData, FrozenInitOptions, InstanceRegistry };
+export { createFailedInitError, createInstanceRegistry, freezeInitOptions, prepareEntryData };

package/dist/shared/lock-data/core/registry.js

@@ -0,0 +1 @@
+import{createError as e}from"../../throw-error/index.js";import{isFunction as t,isObject as r}from"../../utils/index.js";import{withResolvers as o}from"../../with-resolvers/index.js";import{ERROR_FN_NAME as n}from"../constants.js";import{LockDisposedError as i}from"../errors/index.js";import{assertJsonSafeInput as s,cloneByJson as a}from"../utils/json-safe.js";function l(e){return Object.freeze({timeout:e.timeout,mode:e.mode,syncMode:e.syncMode,persistence:e.persistence,sessionProbeTimeout:e.sessionProbeTimeout})}function u(){let o=new Map;return{getOrCreateEntry:(i,s,a)=>{if(0===i.length)throw e(n,"InstanceRegistry requires a non-empty id",TypeError);let u=o.get(i);if(u){let{entry:e}=u;e.refCount++;let{listeners:t}=s;return r(t)&&e.listenersSet.add(t),!function(e,t,r,o){let n=["timeout","mode","syncMode","persistence","sessionProbeTimeout"];for(let i=0;i<n.length;i++){let s=n[i];t[s]!==r[s]&&o.warn(`[lockData] option conflict on id=${e} (field=${String(s)}, first=${String(r[s])}, incoming=${String(t[s])}), using first registered value`)}}(i,l(s),e.initOptions,e.adapters.logger),e}let c=[],d={value:!0},f=a(i,i,s,{registerTeardown:e=>{!t(e)||d.value&&c.push(e)}});return o.set(i,{entry:f,teardowns:c,alive:d}),f},releaseEntry:(e,t)=>{let r=o.get(e);if(!r||r.entry.refCount<=0)return;let{entry:n,teardowns:i,alive:s}=r;void 0!==t&&n.listenersSet.delete(t),n.refCount--,n.refCount>0||(s.value=!1,o.delete(e),function(e,t){let{driver:r,adapters:o,id:n}=e,{logger:i}=o;for(let e=t.length-1;e>=0;e--)try{t[e]()}catch(e){i.warn(`[lockData] teardown callback threw on id=${n}`,e)}try{r.destroy()}catch(e){i.warn(`[lockData] driver.destroy threw on id=${n}`,e)}}(n,i))},peek:{has:e=>o.has(e),size:()=>o.size}}}function c(r,i){var l,u,c;let m,p,{getValue:g}=i;if(!t(g))throw e(n,`lockData id=${r} requires options.getValue (function)`,TypeError);try{p=g()}catch(e){throw f(r,e)}return null===(l=p)||"object"!=typeof l||"function"!=typeof l.then?(s(p,"lockData getValue() result"),{firstValue:a(p),dataReadyPromise:null}):(u=r,c=p,m=o(),Promise.resolve(c).then(e=>{try{s(e,"lockData getValue() result")}catch(e){m.reject(f(u,e));return}m.resolve(e)},e=>{m.reject(f(u,e))}),m.promise.catch(d),{firstValue:{},dataReadyPromise:m.promise})}function d(){}function f(t,r){return e(n,`lockData id=${t} initialization failed during getValue()`,i,{cause:r})}export{f as createFailedInitError,u as createInstanceRegistry,l as freezeInitOptions,c as prepareEntryData};

package/dist/shared/lock-data/core/signal.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AbortSignal 合并工具
+ *
+ * 为什么不直接用 `AbortSignal.any`：
+ * - 较老 Safari / Node 18 不支持，而 lock-data 目标环境包括 SSR / Node 多进程
+ * - 需要在 polyfill 路径里正确处理"构造时已有 signal 处于 aborted 态"的边界
+ *
+ * 语义与 `AbortSignal.any` 一致：任一输入 signal abort 即派生 signal abort；
+ * 若构造时已有任何输入为 aborted，则派生 signal 立即 aborted
+ */
+type SignalLike = AbortSignal | null | undefined;
+/**
+ * 合并任意数量的 AbortSignal；null / undefined 会被过滤
+ *
+ * 返回值：
+ * - `signal`：合并后的派生 signal
+ * - `dispose`：手动解绑所有监听（避免长生命周期 signal 泄漏）
+ */
+declare function anySignal(signals: readonly SignalLike[]): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
+/**
+ * 把已有 signal（若未完成）+ 超时合成一个新 signal
+ *
+ * 返回值包含 `dispose`，用于提前清理 setTimeout（如 action 正常完成时）
+ */
+declare function signalWithTimeout(baseSignal: SignalLike, timeoutMs: number): {
+    signal: AbortSignal;
+    dispose: () => void;
+};
+export type { SignalLike };
+export { anySignal, signalWithTimeout };

package/dist/shared/lock-data/core/signal.js

@@ -0,0 +1 @@
+function e(e){let t=e.filter(e=>e instanceof AbortSignal);if("function"==typeof AbortSignal.any)return{signal:AbortSignal.any(t),dispose:n};let o=new AbortController,r=t.find(e=>e.aborted);if(void 0!==r)return o.abort(r.reason),{signal:o.signal,dispose:n};let i=[],a=()=>{for(let e=0;e<i.length;e++)i[e]();i.length=0};for(let e=0;e<t.length;e++){let n=t[e],r=()=>{o.abort(n.reason),a()};n.addEventListener("abort",r,{once:!0}),i.push(()=>n.removeEventListener("abort",r))}return{signal:o.signal,dispose:a}}function n(){}function t(n,t){let o=new AbortController,r=setTimeout(()=>o.abort(new DOMException("timeout","TimeoutError")),t),i=e([n,o.signal]);function a(){l()}let l=()=>{clearTimeout(r),i.dispose(),i.signal.removeEventListener("abort",a)};return i.signal.aborted?l():i.signal.addEventListener("abort",a,{once:!0}),{signal:i.signal,dispose:l}}export{e as anySignal,t as signalWithTimeout};

package/dist/shared/lock-data/drivers/broadcast-protocol.d.ts

@@ -0,0 +1,71 @@
+/**
+ * BroadcastDriver 协议层：消息类型定义、常量、校验
+ *
+ * 消息类型（所有消息都带 `senderId`，接收方据此判定是否来自自己 —— BroadcastChannel 不
+ * 回环，但用户可能替换为自定义 ChannelAdapter，因此本 driver 不依赖"不回环"假设）：
+ *   - `announce`：抢锁请求广播（requestId + token + ts + force）
+ *   - `reject`：持有者对 announce 的拒绝响应（带 holderToken + holderTs）
+ *   - `release`：持有者主动释放
+ *   - `force`：强制抢占通知（带 ts 仲裁字段）
+ *   - `heartbeat`：持有者周期心跳
+ *
+ * 仲裁规则：`isEarlier(tsA, idA, tsB, idB)`；时间戳小者优先，时间戳相等时字典序小者优先；
+ * 两端独立执行相同仲裁得出一致结果（基于消息内容是全局确定的：(ts, id) 一旦发出就不变）
+ */
+/** announce 的拒绝等待窗口（ms）；窗口内无 reject / 无更早的他方 announce → 拿锁 */
+declare const REJECT_WINDOW = 50;
+/** force 抢占的仲裁等待窗口（ms）；给对端时间响应 force 并可能反向广播 force 仲裁 */
+declare const FORCE_ARBITRATION_WINDOW = 50;
+/** 心跳周期（ms） */
+declare const HEARTBEAT_INTERVAL = 1000;
+/** 崩溃阈值（ms）；连续此毫秒未收到 heartbeat → 视为远端崩溃回 idle */
+declare const DEAD_THRESHOLD = 3000;
+interface AnnounceMessage {
+    readonly kind: 'announce';
+    readonly senderId: string;
+    readonly requestId: string;
+    readonly token: string;
+    readonly ts: number;
+    readonly force: boolean;
+}
+interface RejectMessage {
+    readonly kind: 'reject';
+    readonly senderId: string;
+    readonly requestId: string;
+    readonly holderToken: string;
+    readonly holderTs: number;
+}
+interface ReleaseMessage {
+    readonly kind: 'release';
+    readonly senderId: string;
+    readonly token: string;
+}
+interface ForceMessage {
+    readonly kind: 'force';
+    readonly senderId: string;
+    readonly token: string;
+    readonly ts: number;
+}
+interface HeartbeatMessage {
+    readonly kind: 'heartbeat';
+    readonly senderId: string;
+    readonly token: string;
+    readonly ts: number;
+}
+type BroadcastMessage = AnnounceMessage | RejectMessage | ReleaseMessage | ForceMessage | HeartbeatMessage;
+/**
+ * 严格校验每个 kind 的必需字段（BC-6 修复）
+ *
+ * 运行时消息可能来自任意源（错位的 channel / 用户误用 / 注入），必须 shape 校验后再 narrow
+ */
+declare function isBroadcastMessage(value: unknown): value is BroadcastMessage;
+/** 生成请求 / sender 的唯一 id；不使用 `crypto.randomUUID()` 以保持广兼容 */
+declare function genId(prefix: string): string;
+/**
+ * 仲裁：`(tsA, idA)` 是否严格先于 `(tsB, idB)`
+ *
+ * 时间戳小者优先；时间戳相等时字符串字典序小者优先。两端独立执行一致
+ */
+declare function isEarlier(tsA: number, idA: string, tsB: number, idB: string): boolean;
+export type { AnnounceMessage, BroadcastMessage, ForceMessage, HeartbeatMessage, RejectMessage, ReleaseMessage };
+export { DEAD_THRESHOLD, FORCE_ARBITRATION_WINDOW, genId, HEARTBEAT_INTERVAL, isBroadcastMessage, isEarlier, REJECT_WINDOW, };

package/dist/shared/lock-data/drivers/broadcast-protocol.js

@@ -0,0 +1 @@
+import{isBoolean as e,isNumber as r,isObject as t,isString as n}from"../../utils/index.js";let s=50,o=50,i=1e3,u=3e3;function a(e){return r(e)&&Number.isFinite(e)}function c(r){if(!t(r)||!n(r.senderId))return!1;switch(r.kind){case"announce":return n(r.requestId)&&n(r.token)&&a(r.ts)&&e(r.force);case"reject":return n(r.requestId)&&n(r.holderToken)&&a(r.holderTs);case"release":return n(r.token);case"force":case"heartbeat":return n(r.token)&&a(r.ts);default:return!1}}function d(e){return`${e}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,10)}`}function f(e,r,t,n){return e!==t?e<t:r<n}export{u as DEAD_THRESHOLD,o as FORCE_ARBITRATION_WINDOW,i as HEARTBEAT_INTERVAL,s as REJECT_WINDOW,d as genId,c as isBroadcastMessage,f as isEarlier};