@cmtlyt/lingshu-toolkit 0.6.0 → 0.7.0

package/dist/shared/lock-data/adapters/session-store.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 默认 SessionStoreAdapter 实现：基于 sessionStorage
+ *
+ * 职责：同会话组（同 Tab 及其直系派生 Tab）内存 epoch 快照
+ *   - read：同步读取当前 raw value
+ *   - write：写入 raw value；QuotaExceededError 等失败降级 warn
+ *
+ * 能力探测：sessionStorage 不可用（SSR / 浏览器隐私模式 / 禁用 storage）时
+ *           工厂返回 null，由聚合层决定降级路径（session -> persistent）
+ *
+ * 对应 RFC.md「接口定义」「默认实现」
+ */
+import type { LoggerAdapter, SessionStoreAdapter, SessionStoreAdapterContext } from '../types';
+interface SessionStoreFactoryDeps {
+    readonly logger: LoggerAdapter;
+}
+/**
+ * 能力探测：sessionStorage 是否可实际读写
+ *
+ * 与 authority 的 localStorage 探测同构：仅判断 `typeof sessionStorage`
+ * 不够，Safari 隐私模式下 setItem 会抛 QuotaExceededError；
+ * 采用写-删探测法确保真的可用
+ */
+declare function hasUsableSessionStorage(): boolean;
+/**
+ * 构建 sessionStorage 的完整 key
+ *
+ * 规范：`${LOCK_PREFIX}:${id}:epoch`
+ */
+declare function buildSessionStoreKey(id: string): string;
+/**
+ * 创建默认 SessionStoreAdapter
+ *
+ * @returns SessionStoreAdapter 实例；sessionStorage 不可用时返回 null
+ */
+declare function createDefaultSessionStoreAdapter(ctx: SessionStoreAdapterContext, deps: SessionStoreFactoryDeps): SessionStoreAdapter | null;
+export { buildSessionStoreKey, createDefaultSessionStoreAdapter, hasUsableSessionStorage };

package/dist/shared/lock-data/adapters/session-store.js

@@ -0,0 +1 @@
+import{LOCK_PREFIX as e}from"../constants.js";function t(){try{let t=globalThis.sessionStorage;if(!t)return!1;let r=`${e}:__probe__`;return t.setItem(r,"1"),t.removeItem(r),!0}catch{return!1}}function r(t){return`${e}:${t}:epoch`}function s(e,s){if(!t())return s.logger.warn('sessionStorage is not available; default session store adapter is disabled. persistence="session" will fall back to "persistent".'),null;let o=r(e.id),n=globalThis.sessionStorage;return{read(){try{return n.getItem(o)}catch(e){return s.logger.warn("Failed to read session store from sessionStorage",e),null}},write(e){try{n.setItem(o,e)}catch(e){s.logger.warn("Failed to write session store to sessionStorage; epoch may be reset on next startup.",e)}}}}export{r as buildSessionStoreKey,s as createDefaultSessionStoreAdapter,t as hasUsableSessionStorage};

package/dist/shared/lock-data/authority/epoch.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 会话纪元（epoch）探测与解析
+ *
+ * 对应 RFC.md「会话级持久化与 epoch 探测」「resolveEpoch 协议」章节。
+ *
+ * epoch 的核心作用：解决 "localStorage 天然持久化 vs 用户期望的会话级协作" 语义冲突。
+ *   - `persistence === 'persistent'`：常量 `'persistent'`，跨会话共享同一权威副本
+ *   - `persistence === 'session'`：每个会话组（同源活跃 Tab 的最大存活期）独立 epoch；
+ *     权威副本中 epoch 字段与本地 epoch 不一致时直接丢弃，等价"所有 Tab 关闭即重置"
+ *
+ * resolveEpoch 六分支协议（RFC L1262）：
+ *
+ *   | 分支 | 判定 | epoch 来源 | clearAuthority |
+ *   | ---- | ---- | ---------- | -------------- |
+ *   | A    | persistence === 'persistent' | 常量 'persistent' | 否 |
+ *   | B    | session + !sessionStore      | 降级为 'persistent' | 否 (logger.warn) |
+ *   | C    | sessionStore.read() 有值     | 直接继承（刷新/bfcache） | 否 |
+ *   | D    | 首次 + !channel              | 生成新 UUID | 是 (logger.warn) |
+ *   | E    | 首次 + 收到 session-reply     | 继承响应方 epoch | 否 |
+ *   | F    | 首次 + 探测超时              | 生成新 UUID | 是 |
+ *
+ * 响应方（E 分支的对侧）：所有 storage-authority + session 的 Tab 在 channel 可用时
+ * 常驻订阅 session-probe，若自己已有 epoch 则广播 session-reply；由 StorageAuthority
+ * 生命周期管理订阅解绑（refCount === 0 时解绑）
+ */
+import type { ChannelAdapter, LoggerAdapter, Persistence, SessionStoreAdapter } from '../types';
+/**
+ * session-probe 消息：首次启动的 Tab 广播此消息询问 "当前是否有同会话组的 Tab"
+ *
+ * `probeId` 防止串扰：同一进程中可能同时有多个 id 的 StorageAuthority 发起 probe，
+ * 响应方必须带上原 probeId，发起方用 probeId 过滤避免串扰
+ */
+interface SessionProbeMessage {
+    readonly type: 'session-probe';
+    readonly probeId: string;
+}
+/**
+ * session-reply 消息：响应方在收到 probe 时广播自己的 epoch
+ */
+interface SessionReplyMessage {
+    readonly type: 'session-reply';
+    readonly probeId: string;
+    readonly epoch: string;
+}
+/**
+ * resolveEpoch 的输入上下文
+ *
+ * 刻意解耦于具体 Entry：Phase 5 的 registry 负责组装此 ctx 后调用 resolveEpoch
+ */
+interface ResolveEpochContext {
+    readonly persistence: Persistence;
+    /** sessionStorage adapter；null 表示能力不可用 */
+    readonly sessionStore: SessionStoreAdapter | null;
+    /** BroadcastChannel adapter；null 表示能力不可用 */
+    readonly channel: ChannelAdapter | null;
+    /** 权威副本 adapter；D/F 分支需要 `remove()` 清空残留；null 表示能力不可用 */
+    readonly authority: {
+        remove: () => void;
+    } | null;
+    /** 探测窗口（ms）；未传用 `DEFAULT_SESSION_PROBE_TIMEOUT`（100ms） */
+    readonly sessionProbeTimeout?: number;
+    readonly logger: LoggerAdapter;
+}
+/**
+ * resolveEpoch 的产物
+ *
+ * - `epoch`：最终决定的 epoch（常量 `'persistent'` 或 UUID）
+ * - `effectivePersistence`：若 B 分支降级，此字段为 `'persistent'`；否则与输入一致
+ * - `authorityCleared`：D/F 分支清空了权威副本（true 表示后续 initAuthority 不必再 pull）
+ */
+interface ResolveEpochResult {
+    readonly epoch: string;
+    readonly effectivePersistence: Persistence;
+    readonly authorityCleared: boolean;
+}
+/**
+ * 生成新 epoch
+ *
+ * 优先级：`crypto.randomUUID()` → `Math.random().toString(36) + Date.now()` fallback
+ *
+ * 不使用 `isObject(crypto)` + `isFunction(crypto.randomUUID)` 的完整守卫，
+ * 而是 try-catch：`crypto` 变量在部分 SSR 环境是未定义的（读取即 ReferenceError），
+ * 跟 navigator 一样必须用 typeof 守卫访问；try-catch 更简洁且能覆盖任何异常路径
+ */
+declare function generateUuid(): string;
+/**
+ * 构造 session-probe 消息 —— 集中写入保证消息形状一致
+ */
+declare function buildProbeMessage(probeId: string): SessionProbeMessage;
+/**
+ * 构造 session-reply 消息
+ */
+declare function buildReplyMessage(probeId: string, epoch: string): SessionReplyMessage;
+/**
+ * 判断消息是否为合法 session-probe
+ *
+ * 走 verify.ts 语义函数，对齐 `<code_style>` 类型判断规范
+ */
+declare function isSessionProbeMessage(message: unknown): message is SessionProbeMessage;
+/**
+ * 判断消息是否为合法 session-reply
+ */
+declare function isSessionReplyMessage(message: unknown): message is SessionReplyMessage;
+/**
+ * resolveEpoch：按六分支协议决定本 Tab 的 epoch
+ *
+ * 返回 `Promise<ResolveEpochResult>`，因为 E/F 分支需要异步等待 session-reply 或超时
+ */
+declare function resolveEpoch(ctx: ResolveEpochContext): Promise<ResolveEpochResult>;
+/**
+ * 广播 session-probe 并等待 session-reply
+ *
+ * @returns 首个收到的 reply.epoch；超时返回 null
+ */
+declare function probeForExistingSession(ctx: ResolveEpochContext): Promise<string | null>;
+/**
+ * 生成新 epoch（D / F 分支共用）
+ *
+ * 副作用：
+ *   - 写入 sessionStore（供本 Tab 后续刷新继承）
+ *   - 调用 authority.remove()（主动清空上一会话组残留，避免 epoch 不一致的旧数据继续占用配额）
+ */
+declare function freshEpoch(ctx: ResolveEpochContext): ResolveEpochResult;
+/**
+ * 订阅 session-probe 消息并自动回复 session-reply
+ *
+ * 由 Phase 4.4 `initAuthority` 在 session 策略下调用；订阅常驻直到 Entry 销毁。
+ *
+ * @param channel 本 Tab 的 session 通道
+ * @param getMyEpoch 返回当前 Tab 的 epoch（null 表示尚未 resolved，此时不回复）
+ * @returns 解绑函数；refCount === 0 时由 initAuthority 调用
+ */
+declare function subscribeSessionProbe(channel: ChannelAdapter, getMyEpoch: () => string | null): () => void;
+export type { ResolveEpochContext, ResolveEpochResult, SessionProbeMessage, SessionReplyMessage };
+export { buildProbeMessage, buildReplyMessage, freshEpoch, generateUuid, isSessionProbeMessage, isSessionReplyMessage, probeForExistingSession, resolveEpoch, subscribeSessionProbe, };

package/dist/shared/lock-data/authority/epoch.js

@@ -0,0 +1 @@
+import{isObject as e,isString as s}from"../../utils/index.js";import{withResolvers as r}from"../../with-resolvers/index.js";import{DEFAULT_SESSION_PROBE_TIMEOUT as t,PERSISTENT_EPOCH as o}from"../constants.js";function i(){try{let e=globalThis.crypto;if(e&&"function"==typeof e.randomUUID)return e.randomUUID()}catch{}return`${Math.random().toString(36).slice(2)}-${Date.now().toString(36)}`}function n(e){return{type:"session-probe",probeId:e}}function a(e,s){return{type:"session-reply",probeId:e,epoch:s}}function l(r){return!!e(r)&&"session-probe"===r.type&&s(r.probeId)}function c(r){return!!e(r)&&"session-reply"===r.type&&s(r.probeId)&&s(r.epoch)}async function u(e){if("persistent"===e.persistence)return{epoch:o,effectivePersistence:"persistent",authorityCleared:!1};if(!e.sessionStore)return e.logger.warn('[lockData] sessionStore adapter unavailable, persistence="session" falls back to "persistent"'),{epoch:o,effectivePersistence:"persistent",authorityCleared:!1};let r=e.sessionStore.read();if(s(r)&&r.length>0)return{epoch:r,effectivePersistence:"session",authorityCleared:!1};if(!e.channel)return e.logger.warn("[lockData] channel adapter unavailable, skip session-probe and treat as first tab"),f(e);let t=await p(e);return s(t)?(e.sessionStore.write(t),{epoch:t,effectivePersistence:"session",authorityCleared:!1}):f(e)}function p(e){let{channel:s}=e;if(!s)return Promise.resolve(null);let o=i(),a=e.sessionProbeTimeout||t,l=r(),u=!1,p=s.subscribe(e=>{u||!c(e)||e.probeId===o&&(u=!0,l.resolve(e.epoch))}),f=setTimeout(()=>{u||(u=!0,l.resolve(null))},a);return s.postMessage(n(o)),l.promise.finally(()=>{clearTimeout(f),p()})}function f(e){let s=i();e.sessionStore&&e.sessionStore.write(s);let r=!1;if(e.authority)try{e.authority.remove(),r=!0}catch(s){e.logger.warn("[lockData] authority.remove failed during freshEpoch",s)}return{epoch:s,effectivePersistence:"session",authorityCleared:r}}function h(e,r){return e.subscribe(t=>{if(!l(t))return;let o=r();s(o)&&0!==o.length&&e.postMessage(a(t.probeId,o))})}export{n as buildProbeMessage,a as buildReplyMessage,f as freshEpoch,i as generateUuid,l as isSessionProbeMessage,c as isSessionReplyMessage,p as probeForExistingSession,u as resolveEpoch,h as subscribeSessionProbe};

package/dist/shared/lock-data/authority/extract.d.ts

@@ -0,0 +1,107 @@
+/**
+ * 权威副本 Lazy Parse 快路径
+ *
+ * 对应 RFC.md「Lazy Parse 快路径」章节。
+ *
+ * 设计动机：
+ * - 高频 `storage` 事件（尤其同 Tab 频繁 commit 时）绝大多数命中"rev 未变"快路径
+ * - 避免对 MB 级 snapshot 反复 `JSON.parse`
+ * - `persistence: 'session'` 下 epoch 不匹配时同样走快路径直接丢弃，不误应用上一会话组数据
+ *
+ * 两条快路径：
+ * 1. `extractRev`：正则锚定开头匹配 `{"rev":<整数>`，失败走全量 parse 兜底
+ * 2. `extractEpoch`：正则匹配 `,"epoch":"<string>"`，用于快路径 epoch 过滤
+ *
+ * 快路径开销恒为 O(首部长度)，与 snapshot 总长无关；MB 级 value 下仍稳定在亚微秒
+ */
+/**
+ * 快路径提取 rev
+ *
+ * 匹配锚定开头的 `{"rev":<整数>` 字段；失败返回 null（调用方应走全量 parse 兜底）
+ *
+ * 支持负数 rev（理论上单调递增不会出现，但序列化格式允许）
+ */
+declare function extractRev(raw: string): number | null;
+/**
+ * 快路径提取 epoch
+ *
+ * 匹配 `,"epoch":"<string>"`；失败返回 null（调用方应走全量 parse 兜底或按"无 epoch"处理）
+ *
+ * 正则说明：
+ * - 逗号前缀锚定：epoch 必然出现在 rev / ts 之后，不会错匹配 snapshot 内字面量
+ * - `[^"\\]*`：epoch 由 UUID 或常量 `'persistent'` 生成，不含引号和反斜杠；
+ *   若用户自定义 adapter 注入了含转义的 epoch（理论上不应该），快路径会失配走 JSON.parse 兜底
+ */
+declare function extractEpoch(raw: string): string | null;
+/**
+ * `readIfNewer` 的最小输入契约
+ *
+ * 刻意不依赖完整 Entry 结构，只要求 rev 去重基线 + epoch 过滤基线两个字段。
+ * Phase 5 的 `core/registry.ts` 中 Entry 天然满足此结构。
+ */
+interface ReadIfNewerContext {
+    /**
+     * 已应用的最大 rev；用于去重判定
+     *
+     * 首次初始化时为 `0`（首个远端 rev > 0 必定命中）
+     */
+    readonly lastAppliedRev: number;
+    /**
+     * 当前 Tab 的会话纪元
+     *
+     * - `null` 表示"尚未 resolveEpoch 完成" / "不启用 epoch 过滤"（视调用上下文）
+     * - `'persistent'` 常量（persistence 策略）
+     * - UUID 字符串（session 策略）
+     *
+     * 非 null 时：快路径提取远端 epoch，若不一致则直接丢弃（不解析 snapshot）
+     */
+    readonly epoch: string | null;
+}
+/**
+ * `readIfNewer` 的产物
+ *
+ * 仅包含应用所需的最小字段；`ts` / `epoch` 对调用方无意义，不暴露
+ */
+interface ReadIfNewerResult {
+    readonly rev: number;
+    readonly snapshot: unknown;
+}
+/**
+ * 权威副本原始 value 的全量形态
+ *
+ * 仅在快路径失配走 `JSON.parse` 兜底时使用；字段与 `serializeAuthority` 的产物对应
+ */
+interface AuthorityFullShape {
+    readonly rev: number;
+    readonly ts: number;
+    readonly epoch: string;
+    readonly snapshot: unknown;
+}
+/**
+ * 按"是否比本地更新"决定是否返回 snapshot
+ *
+ * 流程（RFC L1167-1188）：
+ * 1. `raw` 为 null / 空串 → 返回 null（删除 key / 首次读取）
+ * 2. 快路径 `extractRev`：
+ *    - 失配 → 走 JSON.parse 兜底（旧格式 / 手动写入 / 自定义 adapter 产物）
+ *    - 命中但 `remoteRev <= lastAppliedRev` → 返回 null（不解析 snapshot，O(1) 丢弃）
+ * 3. epoch 快路径过滤：本地 epoch 非 null 时，对比远端 epoch；不一致 → 返回 null
+ * 4. 真的要应用时才 `JSON.parse(raw)` 解析 snapshot
+ */
+declare function readIfNewer(ctx: ReadIfNewerContext, raw: string | null): ReadIfNewerResult | null;
+/**
+ * 安全 JSON.parse + 结构校验
+ *
+ * 返回 null 的情况：
+ * - `JSON.parse` 抛错（非法 JSON）
+ * - 结构不符（缺 rev / epoch / snapshot 字段 / rev 非数字 / epoch 非字符串）
+ *
+ * 刻意不抛错：调用方（`storage` 事件 / 定时 pull）不应因单条脏数据中断
+ *
+ * `snapshot` 字段用键存在性（`Reflect.has`）判定而非真值判定 —— 因为 `null`、`false`、
+ * `0`、`''` 都是合法的 snapshot 值；只要 key 缺失就视为非法结构，与"缺 rev / epoch
+ * 返回 null"保持一致的契约
+ */
+declare function parseAuthorityRaw(raw: string): AuthorityFullShape | null;
+export type { AuthorityFullShape, ReadIfNewerContext, ReadIfNewerResult };
+export { extractEpoch, extractRev, parseAuthorityRaw, readIfNewer };

package/dist/shared/lock-data/authority/extract.js

@@ -0,0 +1 @@
+import{isNumber as e,isObject as t,isString as r}from"../../utils/index.js";function n(e){let t=/^\{"rev":(?<rev>-?\d+)/u.exec(e);return t?Number(t[1]):null}function l(e){let t=/,"epoch":"(?<epoch>[^"\\]*)"/u.exec(e);return t?t[1]:null}function u(e,t){if(!t)return null;let u=n(t);if(null===u){var p;let n;return p=e,!(n=o(t))||n.rev<=p.lastAppliedRev||r(p.epoch)&&n.epoch!==p.epoch?null:{rev:n.rev,snapshot:n.snapshot}}if(u<=e.lastAppliedRev)return null;if(r(e.epoch)){let n=l(t);if(r(n)&&n!==e.epoch)return null}let s=o(t);return s?{rev:u,snapshot:s.snapshot}:null}function o(n){let l;try{l=JSON.parse(n)}catch{return null}if(!t(l))return null;let u=l;return e(u.rev)&&r(u.epoch)&&Reflect.has(u,"snapshot")?{rev:u.rev,ts:e(u.ts)?u.ts:0,epoch:u.epoch,snapshot:u.snapshot}:null}export{l as extractEpoch,n as extractRev,o as parseAuthorityRaw,u as readIfNewer};

package/dist/shared/lock-data/authority/index.d.ts

@@ -0,0 +1,182 @@
+/**
+ * StorageAuthority 主类：跨进程权威副本的读写 + 推送 + 拉取统一收口
+ *
+ * 对应 RFC.md「StorageAuthority（localStorage 权威副本）」章节。
+ *
+ * 职责边界（与 LockDriver 互不干扰）：
+ *   - 权威 snapshot 读写
+ *   - 跨 Tab 推送（authority.subscribe）/ 激活时主动拉取（pageshow / visibilitychange）
+ *   - 会话纪元（epoch）生命周期管理（首次 resolveEpoch + 常驻 session-probe 响应）
+ *   - 与锁调度完全无关（acquire / release / revoke 都不经过此处）
+ *
+ * 三条读路径共享同一应用流程：
+ *   | 触发源                | 时机                            | source              | 数据来源                      |
+ *   | --------------------- | ------------------------------- | ------------------- | ---------------------------- |
+ *   | acquire 时 pull       | driver.acquire 成功、进入 recipe 前 | 'pull-on-acquire'   | authority.read() 同步读      |
+ *   | authority.subscribe   | 其他进程写入触发订阅回调        | 'storage-event'     | 回调直接传入 newValue        |
+ *   | 激活时主动 pull       | pageshow / visibilitychange     | 'pageshow' 等       | authority.read() 同步读      |
+ *
+ * 一条写路径：
+ *   commit 成功 → rev++ → authority.write(serialize) → 触发 onCommit
+ *
+ * wrapper 方案下的契约（对应 fixes/api-getvalue-only-redesign.md §14.2 缺口 2）：
+ *   - 不再注入 `applySnapshot` 钩子 —— 远程同步通过 `host.applyRemote(next)` 完成原子覆写，
+ *     authority 不感知 wrapper / dataRef 实现细节
+ *   - 不再注入 `clone` 函数 —— 内部用 `cloneByJson` 完成 emit 事件的 snapshot 隔离
+ *   - 事件触发统一走 `emit` 回调，由调用方接到 listenersFanout
+ */
+import type { AuthorityAdapter, ChannelAdapter, CommitSource, LockDataMutation, LoggerAdapter, Persistence, SessionStoreAdapter, SyncSource } from '../types';
+import { type ResolveEpochResult } from './epoch';
+/**
+ * StorageAuthority 宿主契约（Entry 的最小子集）
+ *
+ * 设计动机：authority 不感知 Entry 完整结构，避免循环依赖；同时通过 `applyRemote` 方法
+ * 把"如何写入 dataRef.current"的实现细节封装到 Entry 内部，authority 只负责调用该方法
+ *
+ * 字段语义：
+ * - `applyRemote(next)`：远程同步入口；内部走 `cloneByJson(next)` + 赋值 `dataRef.current`，
+ *   与 emit 链解耦（emit 由 authority 自己负责）
+ * - `rev` / `lastAppliedRev` 读写双向；`epoch` 由 `StorageAuthority` 内部在首次
+ *   `resolveEpoch` 后回写
+ */
+interface StorageAuthorityHost<T extends object> {
+    /**
+     * 远程同步入口：把 awaited / 远程 snapshot 写入 `dataRef.current`
+     *
+     * 调用方语义：authority 拿到远端最新 snapshot 后，先 `host.applyRemote(snapshot)` 完成
+     * 内部状态切换，再由 authority 自己 `emitSync(...)` 通知 listener。Entry 内部实现
+     * 必须保证 `applyRemote` 走 JSON 拷贝隔离（详见 core/entry.ts buildApplyRemote）
+     */
+    readonly applyRemote: (next: T) => void;
+    /** 单调递增版本号；commit 时 `rev++` */
+    rev: number;
+    /** 已应用的最大 rev；commit 后同步更新；subscribe 回调时用于去重 */
+    lastAppliedRev: number;
+    /** 当前 Tab 的会话纪元；首次 resolveEpoch 完成后由此类回写 */
+    epoch: string | null;
+}
+/**
+ * StorageAuthority 的构造依赖集合
+ *
+ * adapters 三件套允许为 null：authority 或 channel 不可用时降级为
+ * 对应功能 no-op，保证 lockData 在任何环境下都能跑
+ */
+interface StorageAuthorityDeps<T extends object> {
+    readonly host: StorageAuthorityHost<T>;
+    readonly authority: AuthorityAdapter | null;
+    readonly channel: ChannelAdapter | null;
+    readonly sessionStore: SessionStoreAdapter | null;
+    readonly persistence: Persistence;
+    readonly sessionProbeTimeout?: number;
+    readonly logger: LoggerAdapter;
+    /** onSync 事件触发回调；上层接到 listenersFanout */
+    readonly emitSync: (event: {
+        source: SyncSource;
+        rev: number;
+        snapshot: T;
+    }) => void;
+    /** onCommit 事件触发回调；上层接到 listenersFanout */
+    readonly emitCommit: (event: {
+        source: CommitSource;
+        token: string;
+        rev: number;
+        mutations: readonly LockDataMutation[];
+        snapshot: T;
+    }) => void;
+}
+/**
+ * StorageAuthority 对外暴露的 API
+ */
+interface StorageAuthority<T extends object> {
+    /**
+     * 初始化：resolveEpoch + 常驻 session-probe 响应 + 初次 pull + 订阅推送通道
+     *
+     * 返回 `Promise<ResolveEpochResult>`；调用方（`core/entry.ts`）会把此 Promise 与
+     * getValue Promise 合成后挂到 `Entry.dataReadyPromise` 对外暴露
+     *
+     * 多次调用 init 是非法的：宿主自行保证只调用一次
+     */
+    init: () => Promise<ResolveEpochResult>;
+    /** 手动拉取（acquire 时使用）：等价于一次 source='pull-on-acquire' 的 readIfNewer + 应用 */
+    pullOnAcquire: () => void;
+    /**
+     * commit 成功后的写路径：`rev++` → `authority.write` → emit onCommit
+     *
+     * `mutations` 由 Draft 层（`core/draft.ts`）提供；commit 流程为空 mutations 时也可调用
+     * `snapshot` 必须是已隔离的独立副本（调用方走 `cloneByJson`，authority.write 之后
+     * 宿主可能继续改 dataRef.current，独立副本保证 listener 看到的是 commit 当时的值）
+     */
+    onCommitSuccess: (event: {
+        source: CommitSource;
+        token: string;
+        mutations: readonly LockDataMutation[];
+        snapshot: T;
+    }) => void;
+    /**
+     * 销毁：解绑所有订阅（authority.subscribe / pageshow / visibilitychange / session-probe）
+     * + close channel；幂等
+     */
+    dispose: () => void;
+}
+/**
+ * StorageAuthority 的内部可变状态容器
+ *
+ * 从 `createStorageAuthority` 中抽离，让生命周期函数（init / pullOnAcquire /
+ * onCommitSuccess / dispose）可以作为顶层纯函数独立存在；否则这些函数作为闭包
+ * 会让 `createStorageAuthority` 单函数行数超过 biome `noExcessiveLinesPerFunction`
+ * 默认阈值（100 行）
+ */
+interface AuthorityState {
+    readonly unsubscribers: Array<() => void>;
+    disposed: boolean;
+    initialized: boolean;
+}
+/**
+ * 根据远端 raw 应用到 host；三条读路径共享
+ *
+ * 命中条件 see extract.ts: `readIfNewer`
+ *
+ * wrapper 方案下：调用 `host.applyRemote(nextSnapshot)` 完成原子覆写，authority 不感知
+ * dataRef 实现细节；emitSync 的 snapshot 走 `cloneByJson` 拷贝隔离，避免 listener mutate
+ * 影响内部 dataRef.current
+ */
+declare function applyAuthorityIfNewer<T extends object>(state: AuthorityState, deps: StorageAuthorityDeps<T>, source: SyncSource, raw: string | null): void;
+/**
+ * 订阅激活时 pull：pageshow / visibilitychange → authority.read() + 应用
+ *
+ * 仅在浏览器环境（`window` / `document` 可用）注册；
+ * 非浏览器环境由自定义 AuthorityAdapter.subscribe 在合适时机回调即可
+ */
+declare function attachActivationPullSubscription<T extends object>(state: AuthorityState, deps: StorageAuthorityDeps<T>): void;
+/**
+ * 执行 init 流程：常驻 probe 响应 → resolveEpoch → 推送/激活订阅 → 初次 pull
+ */
+declare function performInit<T extends object>(state: AuthorityState, deps: StorageAuthorityDeps<T>): Promise<ResolveEpochResult>;
+/**
+ * 执行 pullOnAcquire 流程：dispose / authority 缺失时 no-op
+ */
+declare function performPullOnAcquire<T extends object>(state: AuthorityState, deps: StorageAuthorityDeps<T>): void;
+/**
+ * 执行 onCommitSuccess 写路径：rev 自增 → authority.write → emitCommit
+ */
+declare function performCommitSuccess<T extends object>(state: AuthorityState, deps: StorageAuthorityDeps<T>, event: {
+    source: CommitSource;
+    token: string;
+    mutations: readonly LockDataMutation[];
+    snapshot: T;
+}): void;
+/**
+ * 执行 dispose 流程：解绑所有订阅 + channel.close；幂等
+ */
+declare function performDispose<T extends object>(state: AuthorityState, deps: StorageAuthorityDeps<T>): void;
+/**
+ * 创建 StorageAuthority 实例
+ *
+ * 仅负责：state 初始化 + 绑定 deps 闭包 + 返回 API 表面
+ * 具体生命周期逻辑由顶层 `perform*` / `attach*` 纯函数承担
+ *
+ * 立即执行：不做初始化（resolveEpoch / 订阅）；这些在 `init()` 中异步触发
+ */
+declare function createStorageAuthority<T extends object>(deps: StorageAuthorityDeps<T>): StorageAuthority<T>;
+export type { AuthorityState, StorageAuthority, StorageAuthorityDeps, StorageAuthorityHost };
+export { applyAuthorityIfNewer, attachActivationPullSubscription, createStorageAuthority, performCommitSuccess, performDispose, performInit, performPullOnAcquire, };

package/dist/shared/lock-data/authority/index.js

@@ -0,0 +1 @@
+import{isObject as e,isString as t}from"../../utils/index.js";import{cloneByJson as r}from"../utils/json-safe.js";import{resolveEpoch as i,subscribeSessionProbe as o}from"./epoch.js";import{readIfNewer as s}from"./extract.js";import{serializeAuthority as n}from"./serialize.js";function a(t,i,o,n){if(t.disposed)return;let{host:a,logger:c,emitSync:u}=i,l=s({lastAppliedRev:a.lastAppliedRev,epoch:a.epoch},n);if(!l)return;if(!e(l.snapshot))return void c.warn(`[lockData] authority snapshot is not an object (source=${o}), skip apply`);let p=l.snapshot;try{a.applyRemote(p)}catch(e){c.error(`[lockData] host.applyRemote failed (source=${o}, rev=${l.rev})`,e);return}a.rev=l.rev,a.lastAppliedRev=l.rev;try{u({source:o,rev:l.rev,snapshot:r(p)})}catch(e){c.error(`[lockData] emitSync listener threw (source=${o})`,e)}}function c(e,t){let{authority:r}=t;if(!r||void 0===globalThis.window||"u"<typeof document)return;let i=i=>{i.persisted&&a(e,t,"pageshow",r.read())},o=()=>{"visible"===document.visibilityState&&a(e,t,"visibilitychange",r.read())};window.addEventListener("pageshow",i),document.addEventListener("visibilitychange",o),e.unsubscribers.push(()=>{window.removeEventListener("pageshow",i),document.removeEventListener("visibilitychange",o)})}async function u(e,t){let{host:r,authority:s,channel:n,sessionStore:u,persistence:l,sessionProbeTimeout:p,logger:h}=t;if(e.initialized)return h.warn("[lockData] StorageAuthority.init called twice, ignore the second call"),{epoch:r.epoch||"persistent",effectivePersistence:l,authorityCleared:!1};e.initialized=!0,function(e,t){if("session"!==t.persistence||!t.channel)return;let r=o(t.channel,()=>t.host.epoch);e.unsubscribers.push(r)}(e,t);let d=await i({persistence:l,sessionStore:u,channel:n,authority:s?{remove:()=>s.remove()}:null,sessionProbeTimeout:p,logger:h});return e.disposed||(r.epoch=d.epoch,!function(e,t){let{authority:r}=t;if(!r)return;let i=r.subscribe(r=>{a(e,t,"storage-event",r)});e.unsubscribers.push(i)}(e,t),c(e,t),s&&!d.authorityCleared&&a(e,t,"pull-on-acquire",s.read())),d}function l(e,t){let{authority:r}=t;!e.disposed&&r&&a(e,t,"pull-on-acquire",r.read())}function p(e,r,i){if(e.disposed)return;let{host:o,authority:s,logger:a,emitCommit:c}=r;if(o.rev++,o.lastAppliedRev=o.rev,s&&t(o.epoch)){let e=n(o.rev,Date.now(),o.epoch,i.snapshot);s.write(e)}try{c({source:i.source,token:i.token,rev:o.rev,mutations:i.mutations,snapshot:i.snapshot})}catch(e){a.error(`[lockData] emitCommit listener threw (source=${i.source})`,e)}}function h(e,t){if(e.disposed)return;e.disposed=!0;let{channel:r,logger:i}=t;for(let t=0;t<e.unsubscribers.length;t++)try{e.unsubscribers[t]()}catch(e){i.warn("[lockData] StorageAuthority dispose: unsubscriber threw",e)}if(e.unsubscribers.length=0,r)try{r.close()}catch(e){i.warn("[lockData] StorageAuthority dispose: channel.close threw",e)}}function d(e){let t={unsubscribers:[],disposed:!1,initialized:!1};return{init:()=>u(t,e),pullOnAcquire:()=>l(t,e),onCommitSuccess:r=>p(t,e,r),dispose:()=>h(t,e)}}export{a as applyAuthorityIfNewer,c as attachActivationPullSubscription,d as createStorageAuthority,p as performCommitSuccess,h as performDispose,u as performInit,l as performPullOnAcquire};

package/dist/shared/lock-data/authority/serialize.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 权威副本存储格式序列化
+ *
+ * 对应 RFC.md「存储格式（固化契约）」章节。
+ *
+ * 固化字段顺序：`rev → ts → epoch → snapshot`
+ *
+ * 固化理由：
+ * 1. `JSON.stringify({ rev, ts, epoch, snapshot })` 在 JS 规范上不保证字段顺序
+ *    （V8 / SpiderMonkey 实测按插入顺序，但不作为契约），手动拼接避免任何引擎差异
+ * 2. `rev` 固定首位：`extractRev` 用锚定开头的正则即可安全提取，不被 snapshot 内容干扰
+ * 3. `epoch` 固定在 snapshot 之前：`extractEpoch` 在小范围内匹配，快路径开销与 value 总长无关
+ * 4. `snapshot` 固定尾部：用户数据可能包含 `"rev"` / `"epoch"` 等字面量，放在尾部避免正则锚定出错
+ *
+ * snapshot 的序列化统一走 `JSON.stringify`，不做字段顺序保证（snapshot 内部由用户控制）
+ */
+interface AuthoritySerializedParts {
+    readonly rev: number;
+    readonly ts: number;
+    readonly epoch: string;
+    readonly snapshot: unknown;
+}
+/**
+ * 序列化权威副本 value
+ *
+ * 产物形如：`{"rev":42,"ts":1714198800123,"epoch":"ab12...","snapshot":{...}}`
+ *
+ * @param rev 单调递增版本号
+ * @param ts 写入时间戳（ms，来自 `Date.now()`）
+ * @param epoch 会话纪元；`persistence === 'persistent'` 时固定为 `'persistent'`，否则为 UUID 字符串
+ * @param snapshot 用户数据快照；由调用方保证已通过 `cloneByJson` 深克隆（JSON 拷贝隔离）
+ */
+declare function serializeAuthority(rev: number, ts: number, epoch: string, snapshot: unknown): string;
+export type { AuthoritySerializedParts };
+export { serializeAuthority };

package/dist/shared/lock-data/authority/serialize.js

@@ -0,0 +1 @@
+function t(t,i,r,e){return`{"rev":${t},"ts":${i},"epoch":${JSON.stringify(r)},"snapshot":${JSON.stringify(e)}}`}export{t as serializeAuthority};

package/dist/shared/lock-data/constants.d.ts

@@ -0,0 +1,46 @@
+/**
+ * lock-data 模块的全局常量
+ *
+ * 所有 key / 默认值统一收敛到此文件，避免散落在各模块中导致跨 Tab 契约漂移。
+ * 详见 RFC.md「默认值总览」「StorageAuthority / 存储格式」章节。
+ */
+/**
+ * 跨 Tab 存储 key 的统一前缀
+ *
+ * 为什么不用 `lingshu:lock-data`：包含作者 scope 可避免与其他未来集成到页面的
+ * 第三方锁库（同样用 lock-data 命名）发生 localStorage key 冲突
+ */
+declare const LOCK_PREFIX = "@cmtlyt/lingshu-toolkit:lockData";
+/**
+ * "永不超时"标记
+ *
+ * 使用 unique symbol（而非 Infinity / -1 / 0）是为了：
+ * 1. 在 TypeScript 层完整区别于"未设置"和任意数值
+ * 2. 避免 setTimeout 对非法数值的静默降级
+ * 3. 让业务侧必须显式 import 才能使用，降低误用概率
+ */
+declare const NEVER_TIMEOUT: unique symbol;
+/**
+ * 默认抢锁超时（毫秒）
+ *
+ * 5000ms 是协作类场景的经验值：
+ * - 大于人类主动操作的响应延迟阈值（2s）
+ * - 小于用户感知到"卡住"的耐心上限（10s）
+ */
+declare const DEFAULT_TIMEOUT = 5000;
+/**
+ * session-probe 探测响应的等待窗口（毫秒）
+ *
+ * 仅首次启动（sessionStorage 无 epoch 时）阻塞；刷新 / bfcache 恢复走快路径跳过探测。
+ * 100ms 已覆盖同源 Tab 间 BroadcastChannel 的典型回响延迟（<30ms）。
+ */
+declare const DEFAULT_SESSION_PROBE_TIMEOUT = 100;
+/**
+ * persistent 策略下固定使用的 epoch 值
+ *
+ * 使用常量字符串而非随机 uuid，保证跨会话重开仍能匹配同一权威副本。
+ */
+declare const PERSISTENT_EPOCH = "persistent";
+/** 统一用于 throwError 第一参数的函数名，保证错误消息前缀一致 */
+declare const ERROR_FN_NAME = "lockData";
+export { DEFAULT_SESSION_PROBE_TIMEOUT, DEFAULT_TIMEOUT, ERROR_FN_NAME, LOCK_PREFIX, NEVER_TIMEOUT, PERSISTENT_EPOCH };

package/dist/shared/lock-data/constants.js

@@ -0,0 +1 @@
+let E="@cmtlyt/lingshu-toolkit:lockData",t=Symbol("@cmtlyt/lingshu-toolkit:lockData#NEVER_TIMEOUT"),T=5e3,l=100,_="persistent",o="lockData";export{l as DEFAULT_SESSION_PROBE_TIMEOUT,T as DEFAULT_TIMEOUT,o as ERROR_FN_NAME,E as LOCK_PREFIX,t as NEVER_TIMEOUT,_ as PERSISTENT_EPOCH};