@cmtlyt/lingshu-toolkit 0.5.0 → 0.7.0

package/dist/shared/lock-data/__test__/_helpers/memory-adapters.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 测试专用：全内存的 Authority / Channel / SessionStore 适配器工厂
+ *
+ * 设计目的：
+ * - 在 Node 环境下模拟"多 Tab 共享浏览器存储 + BroadcastChannel"的完整链路
+ * - 7.2 集成测试（`__test__/integration/memory-adapters.node.test.ts`）复用此工厂验证 lockData 全链路
+ * - 7.3 合规性测试套件（`__test__/adapters/memory-integration.node.test.ts`）复用此工厂作为"参考实现"
+ *
+ * 共享语义对齐（与默认 localStorage / BroadcastChannel / sessionStorage 实现完全一致）：
+ * - `storage`：跨 Tab 共享的 key-value 存储（模拟 localStorage）
+ * - `bus`：跨 Tab 共享的消息总线（模拟 BroadcastChannel，按 channel name 分桶）
+ * - `sessionScope`：每个 Tab 独立的 session 存储（模拟 sessionStorage，不跨 Tab）
+ *
+ * 关键契约对齐（对齐 `src/shared/lock-data/adapters/*.ts` 的真实实现）：
+ * - `AuthorityAdapter.subscribe`：仅响应"跨 Tab"的 write 通知；本 Tab 自己 write 不触发自己的 subscribe 回调
+ *   （对齐原生 storage 事件：发起 write 的那个 document 不会收到自己的 storage 事件）
+ * - `ChannelAdapter.postMessage`：发送方不会收到自己 postMessage 的消息
+ *   （对齐原生 BroadcastChannel 规范）
+ * - 订阅回调异常走 `logger.error` 隔离，不会传播到发送方，也不会污染其他订阅者
+ *
+ * 参考：RFC.md「适配器合规测试套件」章节
+ */
+import type { AuthorityAdapter, AuthorityAdapterContext, ChannelAdapter, ChannelAdapterContext, LoggerAdapter, SessionStoreAdapter, SessionStoreAdapterContext } from '../../types';
+/**
+ * storage 订阅者记录：每个订阅者同时携带其所属 Tab 标识 + 订阅者自己的 logger，
+ * 用于：
+ * 1. 模拟「本 Tab write 不触发本 Tab subscribe 回调」的原生 storage 事件语义
+ * 2. 订阅者回调异常时用**订阅者自己**注入的 logger.error 记录（异常属于订阅者代码的责任）
+ */
+interface StorageSubscriber {
+    readonly tabId: symbol;
+    readonly logger: LoggerAdapter | undefined;
+    readonly onExternalUpdate: (newValue: string | null) => void;
+}
+/**
+ * 跨 Tab 共享的"浏览器环境"：authority storage + channel bus
+ *
+ * 注意：每个 Tab 的 sessionScope 独立（sessionStorage 语义），故由 `createMemoryAdapters`
+ * 内部维护，不在 env 里共享
+ */
+interface SharedMemoryEnv {
+    /** 跨 Tab 共享的 key-value 存储（模拟 localStorage） */
+    readonly storage: Map<string, string>;
+    /** 跨 Tab 共享的消息总线；key 为 channel name，value 为该 channel 上所有订阅者 */
+    readonly bus: Map<string, Set<ChannelSubscriber>>;
+    /** storage 订阅者按 key 分桶（AuthorityAdapter.subscribe 语义：仅订阅指定 key） */
+    readonly storageSubscribers: Map<string, Set<StorageSubscriber>>;
+}
+/**
+ * channel 订阅者记录：同样携带 Tab 标识用于模拟「postMessage 发送方不收自己消息」，
+ * 并携带订阅者自己的 logger 以便异常日志归属正确
+ */
+interface ChannelSubscriber {
+    readonly tabId: symbol;
+    readonly logger: LoggerAdapter | undefined;
+    readonly onMessage: (message: unknown) => void;
+}
+/**
+ * 创建一个"多 Tab 共享浏览器环境"的空白容器；随后调用 `createMemoryAdapters(env)`
+ * 创建每个 Tab 独立的 adapter 工厂集合即可
+ */
+declare function createSharedMemoryEnv(): SharedMemoryEnv;
+/**
+ * 单 Tab 的三件套 adapter 工厂集合
+ *
+ * 与 `LockDataAdapters<T>` 的 `getAuthority` / `getChannel` / `getSessionStore` 字段一一对应，
+ * 可直接作为 `lockData({ adapters: { ...memoryAdapters, logger } })` 注入
+ */
+interface MemoryAdapters {
+    readonly getAuthority: (ctx: AuthorityAdapterContext) => AuthorityAdapter;
+    readonly getChannel: (ctx: ChannelAdapterContext) => ChannelAdapter;
+    readonly getSessionStore: (ctx: SessionStoreAdapterContext) => SessionStoreAdapter;
+}
+/**
+ * 可选的 logger 注入：用于验证「回调异常走 logger.error 隔离」的合规测试
+ *
+ * 未提供时内部 silently swallow 异常（保持接口契约不向上抛）
+ */
+interface CreateMemoryAdaptersOptions {
+    readonly logger?: LoggerAdapter;
+}
+/**
+ * 创建"某一个 Tab"的内存 adapter 工厂集合
+ *
+ * 同一 env 下多次调用 `createMemoryAdapters(env)` 即模拟多 Tab：
+ * - 各 Tab 的 authority / channel 自然通过 env 共享
+ * - 各 Tab 的 sessionScope 由工厂闭包内部维护，互不可见
+ *
+ * 每次调用会生成一个新的 `tabId` symbol 作为订阅者归属标识，用于：
+ * - authority.subscribe：过滤"本 Tab write 触发的自通知"
+ * - channel.postMessage：过滤"发送方自己订阅的回调"
+ */
+declare function createMemoryAdapters(env: SharedMemoryEnv, options?: CreateMemoryAdaptersOptions): MemoryAdapters;
+export type { CreateMemoryAdaptersOptions, MemoryAdapters, SharedMemoryEnv };
+export { createMemoryAdapters, createSharedMemoryEnv };

package/dist/shared/lock-data/__test__/_helpers/memory-adapters.js

@@ -0,0 +1 @@
+function e(){return{storage:new Map,bus:new Map,storageSubscribers:new Map}}function r(e,a={}){let s=Symbol("lock-data.memory-adapters.tab"),o=new Map,{logger:n}=a;return{getAuthority:r=>{var a,o,l,u,i;let b;return a=e,o=s,l=r,u=n,b=(i=l.id,`authority:${i}`),{read:()=>a.storage.get(b)??null,write(e){a.storage.set(b,e),t(a,b,e,o)},remove(){a.storage.delete(b),t(a,b,null,o)},subscribe(e){let r={tabId:o,logger:u,onExternalUpdate:e},t=a.storageSubscribers.get(b)??new Set;return t.add(r),a.storageSubscribers.set(b,t),()=>{t.delete(r)}}}},getChannel:r=>{var t,a,o,l,u,i;let b,d,g;return t=e,a=s,o=r,l=n,b=(u=o.id,i=o.channel,`${u}:${i}`),d=new Set,g=!1,{postMessage(e){if(g)return;let r=t.bus.get(b);if(r){for(let t of Array.from(r))if(t.tabId!==a)try{t.onMessage(e)}catch(e){t.logger?.error("[memory-adapters] channel subscriber threw",e)}}},subscribe(e){if(g)return()=>{};let r={tabId:a,logger:l,onMessage:e},s=t.bus.get(b)??new Set;return s.add(r),t.bus.set(b,s),d.add(r),()=>{s.delete(r),d.delete(r)}},close(){if(g)return;g=!0;let e=t.bus.get(b);if(e)for(let r of d)e.delete(r);d.clear()}}},getSessionStore:e=>{var r,t;let a;return r=o,a=(t=e.id,`session:${t}`),{read:()=>r.get(a)??null,write(e){r.set(a,e)}}}}}function t(e,r,t,a){let s=e.storageSubscribers.get(r);if(s){for(let e of Array.from(s))if(e.tabId!==a)try{e.onExternalUpdate(t)}catch(r){e.logger?.error("[memory-adapters] authority subscriber threw",r)}}}export{r as createMemoryAdapters,e as createSharedMemoryEnv};

package/dist/shared/lock-data/__test__/playground.js

@@ -0,0 +1 @@
+import{LockDisposedError as e,NEVER_TIMEOUT as t,ReadonlyMutationError as n,lockData as o}from"../index.js";function a(e,t="info"){let n=document.getElementById("log"),o=new Date().toLocaleTimeString("zh-CN",{hour12:!1}),r=document.createElement("div");r.className="log-entry",r.innerHTML=`<span class="log-time">[${o}]</span> <span class="log-${t}">${e}</span>`,n.prepend(r)}function r(e){document.getElementById("last-error").textContent=e}let[s,c]=o({getValue:()=>({count:0,label:"init"}),listeners:{onCommit:e=>{a(`onCommit <span class="tag tag-rev">rev ${e.rev}</span> source=${e.source} snapshot=${JSON.stringify(e.snapshot)}`,"event"),i()},onLockStateChange:e=>{a(`onLockStateChange <span class="tag tag-phase">${e.phase}</span>`,"event"),u()},onRevoked:e=>{a(`onRevoked reason=${e.reason}`,"event")}}});function i(){document.getElementById("view-count").textContent=String(s.count),document.getElementById("view-label").textContent=s.label}function u(){document.getElementById("is-holding").textContent=String(c.isHolding)}async function d(){await c.update(e=>{e.count+=1}),i(),a(`count +1 → ${s.count}`,"success")}async function l(){await c.update(e=>{e.count-=1}),i(),a(`count -1 → ${s.count}`,"success")}async function g(){await c.replace({count:100,label:"replaced"}),i(),a(`replace → count=${s.count}, label=${s.label}`,"success")}i(),a("基础实例已创建（同步初始化）","success");let b=null,m=null;async function p(){let[e,t]=o({id:"playground-shared",getValue:()=>({counter:0})});return{view:e,actions:t}}let f=null,y=null,h=0;function $(){f&&(document.getElementById("cross-tab-value").textContent=String(f.value),document.getElementById("cross-tab-rev").textContent=String(h)),document.getElementById("cross-tab-holding").textContent=y?String(y.isHolding):"-"}let v=null,T=null,E=null;Object.assign(globalThis,{doIncrement:d,doDecrement:l,doReplace:g,doSnapshot:function(){let e=c.snapshot();a(`snapshot → ${JSON.stringify(e)}`,"info")},doWriteView:function(){try{s.count=999,a("未抛错（不应该到这里）","error")}catch(o){let e=o instanceof n,t=o instanceof Error?o.message:String(o);a(`捕获 ReadonlyMutationError: ${t} (instanceof=${e})`,e?"success":"error"),r(`ReadonlyMutationError: ${t}`)}},doDeleteView:function(){try{delete s.count,a("未抛错（不应该到这里）","error")}catch(o){let e=o instanceof n,t=o instanceof Error?o.message:String(o);a(`捕获 ReadonlyMutationError (delete): ${t}`,e?"success":"error"),r(`ReadonlyMutationError: ${t}`)}},doUseAfterDispose:async function t(){let[,t]=o({getValue:()=>({x:1})});await t.dispose();try{await t.update(e=>{e.x=2}),a("未抛错（不应该到这里）","error")}catch(o){let t=o instanceof e,n=o instanceof Error?o.message:String(o);a(`捕获 LockDisposedError: ${n} (instanceof=${t})`,t?"success":"error"),r(`LockDisposedError: ${n}`)}},doGetLock:async function e(){await c.getLock({holdTimeout:t}),u(),a(`getLock (holdTimeout=NEVER_TIMEOUT) → isHolding=${c.isHolding}`,"success")},doUpdateWhileHolding:async function e(){await c.update(e=>{e.count+=10}),i(),a(`持锁 update → count=${s.count}`,"success")},doRelease:function(){c.release(),u(),a(`release → isHolding=${c.isHolding}`,"success")},doCreateShared:async function e(){let e=await p();m=e.view,b=e.actions,document.getElementById("shared-counter").textContent=String(m.counter),a(`shared 实例已创建 id=playground-shared counter=${m.counter}`,"success")},doSharedUpdate:async function e(){b&&m?(await b.update(e=>{e.counter+=5}),document.getElementById("shared-counter").textContent=String(m.counter),a(`shared update → counter=${m.counter}`,"success")):a("请先创建 shared 实例","warn")},doSharedRead:function(){m?(document.getElementById("shared-counter").textContent=String(m.counter),a(`shared read → counter=${m.counter}`,"info")):a("请先创建 shared 实例","warn")},doSharedDispose:async function e(){b?(await b.dispose(),a("shared 实例已 dispose","success"),b=null,m=null,document.getElementById("shared-counter").textContent="-"):a("请先创建 shared 实例","warn")},doInitCrossTab:async function e(){try{let[e,t]=await o({id:"playground-cross-tab",syncMode:"storage-authority",getValue:()=>({value:0}),listeners:{onSync:e=>{h=e.rev,a(`[跨Tab] onSync rev=${e.rev} source=${e.source} snapshot=${JSON.stringify(e.snapshot)}`,"event"),$()},onCommit:e=>{h=e.rev,a(`[跨Tab] onCommit rev=${e.rev}`,"event"),$()}}});f=e,y=t,$(),a("跨 Tab 实例已初始化（打开多个 Tab 试试！）","success")}catch(t){let e=t instanceof Error?t.message:String(t);a(`跨 Tab 初始化失败: ${e}`,"error")}},doCrossTabUpdate:async function e(){y&&f?(await y.update(e=>{e.value+=1}),$(),a(`跨 Tab update → value=${f.value}`,"success")):a("请先初始化跨 Tab 实例","warn")},doCrossTabRead:function(){f?($(),a(`跨 Tab read → value=${f.value}`,"info")):a("请先初始化跨 Tab 实例","warn")},doCrossTabGetLock:async function e(){if(!y)return void a("[跨Tab] 请先初始化跨 Tab 实例","warn");try{await y.getLock({holdTimeout:t}),$(),a(`[跨Tab] getLock → isHolding=${y.isHolding}（其他 Tab 的 update 会排队等待）`,"success")}catch(t){let e=t instanceof Error?t.message:String(t);a(`[跨Tab] getLock 失败: ${e}`,"error")}},doCrossTabUpdateWhileHolding:async function e(){if(!y)return void a("[跨Tab] 请先初始化跨 Tab 实例","warn");try{await y.update(e=>{e.value+=10}),$(),a(`[跨Tab] 持锁 update → value=${f?.value}`,"success")}catch(t){let e=t instanceof Error?t.message:String(t);a(`[跨Tab] 持锁 update 失败: ${e}`,"error")}},doCrossTabRelease:function(){y?(y.release(),$(),a(`[跨Tab] release → isHolding=${y.isHolding}`,"success")):a("[跨Tab] 请先初始化跨 Tab 实例","warn")},doCrossTabDispose:async function e(){y?(await y.dispose(),a("跨 Tab 实例已 dispose","success"),f=null,y=null,document.getElementById("cross-tab-value").textContent="-",document.getElementById("cross-tab-rev").textContent="-",document.getElementById("cross-tab-holding").textContent="-"):a("请先初始化跨 Tab 实例","warn")},doCreateAbortable:function(){let[e,t]=o({getValue:()=>({count:0}),signal:(v=new AbortController).signal});T=e,E=t,document.getElementById("abortable-count").textContent=String(T.count),a("可取消实例已创建","success")},doAbortableUpdate:async function e(){if(!(E&&T))return void a("请先创建可取消实例","warn");try{await E.update(e=>{e.count+=1}),document.getElementById("abortable-count").textContent=String(T.count),a(`abortable update → count=${T.count}`,"success")}catch(t){let e=t instanceof Error?t.message:String(t);a(`abortable update 失败: ${e}`,"error")}},doAbort:function(){v?(v.abort(),a("已调用 abort()，实例等价 dispose","success")):a("请先创建可取消实例","warn")},doAbortableUpdateAfterAbort:async function t(){if(!E)return void a("请先创建可取消实例","warn");try{await E.update(e=>{e.count+=1}),a("未抛错（不应该到这里）","error")}catch(o){let t=o instanceof e,n=o instanceof Error?o.message:String(o);a(`abort 后 update 捕获 LockDisposedError: ${n} (instanceof=${t})`,t?"success":"error"),r(`LockDisposedError: ${n}`)}},clearLog:function(){document.getElementById("log").innerHTML=""}});

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

@@ -0,0 +1,40 @@
+/**
+ * 默认 AuthorityAdapter 实现：基于 localStorage
+ *
+ * 职责：作为跨 Tab 权威副本的存储与订阅通道
+ *   - read：同步读取当前 raw value
+ *   - write：写入 raw value，捕获 QuotaExceededError 降级为 warn（允许继续运行，
+ *            下次 commit 再次尝试；lock-data 的后续 authority 层会依 rev 去重）
+ *   - remove：删除当前 key
+ *   - subscribe：订阅跨 Tab 的 `storage` 事件，仅响应同 key 且 storageArea === localStorage 的变更
+ *
+ * 能力探测：localStorage 不可用（SSR / 浏览器隐私模式 / 禁用三方 cookie）时工厂返回 null，
+ * 由聚合层（pickDefaultAdapters）决定是否降级或抛 InvalidOptionsError
+ *
+ * 对应 RFC.md「接口定义」「默认实现」
+ */
+import type { AuthorityAdapter, AuthorityAdapterContext, LoggerAdapter } from '../types';
+interface AuthorityFactoryDeps {
+    /** 由聚合层传入；用于降级 / 异常路径的统一日志 */
+    readonly logger: LoggerAdapter;
+}
+/**
+ * 能力探测：localStorage 是否可实际读写
+ *
+ * 仅判断 `typeof localStorage === 'object'` 不够，Safari 隐私模式下 localStorage 存在
+ * 但写入会抛 QuotaExceededError；此处用写-删探测法确保真的可用
+ */
+declare function hasUsableLocalStorage(): boolean;
+/**
+ * 构建 localStorage 权威副本的完整 key
+ *
+ * 规范：`${LOCK_PREFIX}:${id}:latest`
+ */
+declare function buildAuthorityKey(id: string): string;
+/**
+ * 创建默认 AuthorityAdapter
+ *
+ * @returns AuthorityAdapter 实例；localStorage 不可用时返回 null
+ */
+declare function createDefaultAuthorityAdapter(ctx: AuthorityAdapterContext, deps: AuthorityFactoryDeps): AuthorityAdapter | null;
+export { buildAuthorityKey, createDefaultAuthorityAdapter, hasUsableLocalStorage };

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

@@ -0,0 +1 @@
+import{LOCK_PREFIX as e}from"../constants.js";function t(){try{let t=globalThis.localStorage;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}:latest`}function o(e,o){if(!t())return o.logger.warn('localStorage is not available; default authority adapter is disabled. syncMode="storage-authority" will fall back to local-only semantics.'),null;let a=r(e.id),l=globalThis.localStorage;return{read(){try{return l.getItem(a)}catch(e){return o.logger.warn("Failed to read authority snapshot from localStorage",e),null}},write(e){try{l.setItem(a,e)}catch(e){o.logger.warn("Failed to write authority snapshot to localStorage (likely QuotaExceededError); remote Tabs will not see this commit until next successful write.",e)}},remove(){try{l.removeItem(a)}catch(e){o.logger.warn("Failed to remove authority snapshot from localStorage",e)}},subscribe(e){let t=t=>{if(t.storageArea===l&&t.key===a)try{e(t.newValue)}catch(e){o.logger.error("Authority subscribe callback threw",e)}},r=globalThis;return"function"!=typeof r.addEventListener?(o.logger.warn("globalThis.addEventListener is not available; authority subscribe is noop."),()=>void 0):(r.addEventListener("storage",t),()=>{r.removeEventListener?.("storage",t)})}}}export{r as buildAuthorityKey,o as createDefaultAuthorityAdapter,t as hasUsableLocalStorage};

package/dist/shared/lock-data/adapters/channel.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 默认 ChannelAdapter 实现：基于原生 BroadcastChannel
+ *
+ * 职责：跨同源 Tab / Worker 的消息广播通道
+ *   - postMessage：发送消息；已关闭时降级为 warn，不抛错
+ *   - subscribe：订阅 message 事件；回调异常走 logger.error 隔离
+ *   - close：幂等关闭，后续操作全部降级 noop
+ *
+ * 能力探测：`BroadcastChannel` 不可用（SSR / 老浏览器）时工厂返回 null，
+ * 由聚合层决定降级路径
+ *
+ * 对应 RFC.md「接口定义」「默认实现」
+ */
+import type { ChannelAdapter, ChannelAdapterContext, LoggerAdapter } from '../types';
+interface ChannelFactoryDeps {
+    readonly logger: LoggerAdapter;
+}
+/**
+ * 能力探测：BroadcastChannel 是否可实例化
+ *
+ * 仅判断构造器存在还不够，某些环境（如部分 Electron 版本 / 早期 Safari）
+ * 构造器存在但实例化会抛错；此处用 try-catch 做真实构造探测
+ */
+declare function hasUsableBroadcastChannel(): boolean;
+/**
+ * 构建 BroadcastChannel 名称
+ *
+ * 规范：`${LOCK_PREFIX}:${id}:${channel}`
+ * - channel === 'session'：session-probe / session-reply 协议通道
+ * - channel === 'custom'：Phase 3 广播驱动等其他业务通道
+ */
+declare function buildChannelName(id: string, channel: ChannelAdapterContext['channel']): string;
+/**
+ * 创建默认 ChannelAdapter
+ *
+ * @returns ChannelAdapter 实例；BroadcastChannel 不可用时返回 null
+ */
+declare function createDefaultChannelAdapter(ctx: ChannelAdapterContext, deps: ChannelFactoryDeps): ChannelAdapter | null;
+export { buildChannelName, createDefaultChannelAdapter, hasUsableBroadcastChannel };

package/dist/shared/lock-data/adapters/channel.js

@@ -0,0 +1 @@
+import{LOCK_PREFIX as e}from"../constants.js";function r(){let r=globalThis.BroadcastChannel;if("function"!=typeof r)return!1;try{return new r(`${e}:__probe__`).close(),!0}catch{return!1}}function a(r,a){return`${e}:${r}:${a}`}function n(e,n){if(!r())return n.logger.warn("BroadcastChannel is not available; default channel adapter is disabled. Cross-tab sync features may fall back to degraded mode."),null;let t=new globalThis.BroadcastChannel(a(e.id,e.channel)),l=!1;return{postMessage(e){if(l||null===t)return void n.logger.warn("postMessage on closed ChannelAdapter is ignored.");try{t.postMessage(e)}catch(e){n.logger.warn("BroadcastChannel.postMessage failed",e)}},subscribe(e){if(l||null===t)return n.logger.warn("subscribe on closed ChannelAdapter is ignored; returning noop unsubscriber."),()=>void 0;let r=r=>{try{e(r.data)}catch(e){n.logger.error("Channel subscribe callback threw",e)}};return t.addEventListener("message",r),()=>{try{t?.removeEventListener("message",r)}catch{}}},close(){if(!l){l=!0;try{t?.close()}catch(e){n.logger.warn("BroadcastChannel.close failed",e)}finally{t=null}}}}}export{a as buildChannelName,n as createDefaultChannelAdapter,r as hasUsableBroadcastChannel};

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

@@ -0,0 +1,58 @@
+/**
+ * adapters 聚合入口：pickDefaultAdapters
+ *
+ * 职责：把 `options.adapters` 的用户自定义项与默认实现合并，产出"已解析"形态
+ * 供 Phase 3+ 消费。合并策略：用户提供 > 默认实现 > null。
+ *
+ * 输入形态（用户向）：工厂函数（getXxx(ctx) => Adapter | null）+ 实例（logger）
+ * 输出形态（内部向）：工厂保留工厂形态（延迟到使用时调用），但工厂内部自动做"用户工厂返回
+ *           null 时降级到默认工厂"的合并；实例直接用解析好的值
+ *
+ * 设计要点：
+ * 1. logger 无 id 作用域 —— 直接解析为实例，内部 adapter 构造时可复用同一个 logger，
+ *    保证所有降级日志走用户注入的 logger
+ * 2. getAuthority / getChannel / getSessionStore 保留工厂形态，因为 id / channel 语义
+ *    要在调用点才确定
+ * 3. getLock 直接透传（由 Phase 3 drivers 层解释）
+ *
+ * wrapper 方案契约（与旧 clone 适配器的根本差异）：
+ * - 历史版本曾通过 `adapters.clone`（structuredClone / 用户自定义）做深拷贝；
+ *   wrapper 方案下统一改为 `JSON.parse(JSON.stringify(...))`（详见 utils/json-safe.ts），
+ *   配合 JSON-only 数据契约（顶层数组禁止 + 非 JSON-safe 类型 fail-fast）确保隔离正确性
+ * - 不再支持自定义 clone：用户若需保留 Set / Map / Date 等，应在业务层自行序列化为 JSON 形态
+ *
+ * 对应 RFC.md「设计原则」：用户提供 > 默认实现 > null
+ */
+import type { AuthorityAdapter, AuthorityAdapterContext, ChannelAdapter, ChannelAdapterContext, LockDataAdapters, SessionStoreAdapter, SessionStoreAdapterContext } from '../types';
+import { type ResolvedLoggerAdapter } from './logger';
+/**
+ * 解析后的适配器集合
+ *
+ * 所有字段均为"可直接调用"形态：
+ * - logger：实例
+ * - getAuthority / getChannel / getSessionStore：工厂（返回 null 时表示能力不可用）
+ * - getLock：原样透传；Phase 3 的 pickDriver 决定是否使用
+ */
+interface ResolvedAdapters<T> {
+    readonly logger: ResolvedLoggerAdapter;
+    readonly getAuthority: (ctx: AuthorityAdapterContext) => AuthorityAdapter | null;
+    readonly getChannel: (ctx: ChannelAdapterContext) => ChannelAdapter | null;
+    readonly getSessionStore: (ctx: SessionStoreAdapterContext) => SessionStoreAdapter | null;
+    readonly getLock: LockDataAdapters<T>['getLock'];
+}
+/**
+ * 合并用户自定义 adapters 与默认实现
+ *
+ * 合并语义：
+ * - logger：`userAdapters.logger` 优先；未提供时用默认 logger
+ * - getAuthority：用户工厂存在 → 先调用；返回非 null 直接用；返回 null 时 fallback 到默认工厂
+ *   用户未提供 → 直接用默认工厂
+ *   默认工厂也返回 null 时表示能力不可用
+ * - getChannel / getSessionStore：同 getAuthority
+ * - getLock：透传（聚合层不关心其行为）
+ *
+ * @param userAdapters 用户传入的 `options.adapters`；未传视为空
+ */
+declare function pickDefaultAdapters<T>(userAdapters?: LockDataAdapters<T>): ResolvedAdapters<T>;
+export type { ResolvedAdapters };
+export { pickDefaultAdapters };

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

@@ -0,0 +1 @@
+import{createDefaultAuthorityAdapter as t}from"./authority.js";import{createDefaultChannelAdapter as e}from"./channel.js";import{resolveLoggerAdapter as r}from"./logger.js";import{createDefaultSessionStoreAdapter as o}from"./session-store.js";function n(n){let i=n||{},l=r(i.logger),u=i.getAuthority,s=i.getChannel,f=i.getSessionStore;return{logger:l,getAuthority:e=>{if(u){let t=u(e);if(null!==t)return t}return t(e,{logger:l})},getChannel:t=>{if(s){let e=s(t);if(null!==e)return e}return e(t,{logger:l})},getSessionStore:t=>{if(f){let e=f(t);if(null!==e)return e}return o(t,{logger:l})},getLock:i.getLock}}export{n as pickDefaultAdapters};

package/dist/shared/lock-data/adapters/logger.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 默认 LoggerAdapter 实现 + 用户 logger 兜底合并
+ *
+ * 委托到 `@/shared/logger` 的全局 logger（console Proxy），
+ * 负责把 `LoggerAdapter` 契约的 `(message, ...extras)` 形态
+ * 适配为 `shared/logger` 的 `(fnName, ...args)` 形态。
+ *
+ * - fnName 固定为 `ERROR_FN_NAME`（`lockData`），保证错误消息前缀一致
+ * - `globalThis.$lingshu$.disableLogger` 可全局关闭日志输出，无需在此额外处理
+ *
+ * 对应 RFC.md「默认实现」：默认 LoggerAdapter 委托到 shared/logger
+ *
+ * **logger 混合兜底契约（Phase 2 决策）**：
+ * `LoggerAdapter` 的 `warn` / `error` 为必选、`debug` 为可选。为避免下游链路
+ * 在调用 `logger.debug` 时需要反复 guard、且保证"用户覆盖 + 默认补全"的
+ * 无缝混合，`resolveLoggerAdapter` 对用户 logger 做缺失方法补全：
+ *   - 用户 logger 存在且已实现的方法 → 原样使用（保持用户日志目的地）
+ *   - 用户 logger 未实现的方法 → 走默认 logger（仍带 `[lockData]` 前缀）
+ * 输出永远是"三方法齐全"的 logger，`debug` 在下游可直接调用无需 optional chain
+ */
+import type { LoggerAdapter } from '../types';
+/**
+ * 必选方法齐全的 logger 内部形态
+ *
+ * 与 `LoggerAdapter` 的差异：`debug` 由可选变为必选，`resolveLoggerAdapter`
+ * 的产物一律满足此形态，供下游（clone / authority / channel / ...）直接调用
+ */
+interface ResolvedLoggerAdapter extends LoggerAdapter {
+    debug: NonNullable<LoggerAdapter['debug']>;
+}
+/**
+ * 创建默认的 LoggerAdapter（三方法齐全）
+ *
+ * 设计要点：
+ * 1. 始终返回一个可用实例，不需要能力探测（console 在所有运行环境存在）
+ * 2. `warn` / `error` / `debug` 均委托到全局 logger，统一加 `[@cmtlyt/lingshu-toolkit#lockData]` 前缀
+ */
+declare function createDefaultLogger(): ResolvedLoggerAdapter;
+/**
+ * 把"用户 logger（可能部分缺失）"与"默认 logger"混合为"三方法齐全"的 logger
+ *
+ * 合并规则（字段级）：
+ * - `warn` / `error` / `debug` 每个方法独立判定：
+ *   - 用户 logger 的该方法是 `function` → 用用户版本（保持日志目的地）
+ *   - 否则 → 用默认 logger 的该方法（走 shared/logger 通道，带统一前缀）
+ *
+ * 为什么不直接 `{ ...defaultLogger, ...userLogger }`：
+ * - 用户可能显式传 `debug: undefined`（例：从对象里 pick 字段），这会把默认
+ *   的 `debug` 覆盖为 `undefined`；严格按方法类型判定才能避免此类陷阱
+ *
+ * @param userLogger 用户传入的 logger（未传或为 undefined 等价于"全部走默认"）
+ * @returns 三方法齐全的 logger；下游可直接调用 `logger.debug(...)` 无需 guard
+ */
+declare function resolveLoggerAdapter(userLogger?: LoggerAdapter): ResolvedLoggerAdapter;
+export type { ResolvedLoggerAdapter };
+export { createDefaultLogger, resolveLoggerAdapter };

package/dist/shared/lock-data/adapters/logger.js

@@ -0,0 +1 @@
+import{logger as r}from"../../logger/index.js";import{ERROR_FN_NAME as e}from"../constants.js";function n(){return{warn(n,...o){r.warn(e,n,...o)},error(n,...o){r.error(e,n,...o)},debug(n,...o){r.debug(e,n,...o)}}}function o(r){let e=n(),o=r||{};return{warn:"function"==typeof o.warn?o.warn.bind(o):e.warn,error:"function"==typeof o.error?o.error.bind(o):e.error,debug:"function"==typeof o.debug?o.debug.bind(o):e.debug}}export{n as createDefaultLogger,o as resolveLoggerAdapter};

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};