@cmtlyt/lingshu-toolkit 0.5.0 → 0.7.0

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

@@ -0,0 +1,125 @@
+/**
+ * BroadcastDriver 状态层：状态机定义、消息处理、竞选流程、drain
+ *
+ * 本文件不对外暴露 API；`broadcast.ts` 作为工厂聚合层消费此处导出的内部符号。
+ *
+ * ## 本地状态机
+ *   - `idle`：无人持锁；可直接 announce
+ *   - `holding`：本 Tab 持锁；周期广播 heartbeat
+ *   - `remote-held`：远端持锁；监测心跳过期（DEAD_THRESHOLD 未收到 heartbeat → 回 idle）
+ *
+ * ## 竞选协议（非 force）
+ *   1. 广播 `announce`，启动 `REJECT_WINDOW` 窗口
+ *   2. 期间规则：
+ *      - 收到 `reject(requestId 匹配)` → abandonPendingAnnounce，waiter 回队等待
+ *      - 收到他方 `announce` → 按 (ts, requestId) 字典序仲裁；对方更早则本方 abandon
+ *      - 收到 `heartbeat` → 存在持有者，本方 abandon 并切 remote-held
+ *   3. 窗口到期无拒绝 → enterHolding
+ *
+ * ## force 协议（BC-1 修复：异步等待对端 revoke 完成）
+ *   1. 广播 `force`，启动 `FORCE_ARBITRATION_WINDOW` 窗口
+ *   2. 期间收到他方 `force` → 按 (ts, token) 字典序仲裁；对方更早则本方 abandon
+ *   3. 窗口到期后 enterHolding；对端持有者收到 force 时立即 revoke('force')
+ *
+ * ## 持锁期间冲突检测（BC-2 修复）
+ *   - `holding` 状态收到 `reject(holderToken != 自己)` → 双持冲突，revoke 自己
+ *   - `holding` 状态收到 `heartbeat(token != 自己)` → 双持冲突，revoke 自己
+ */
+/** biome-ignore-all lint/nursery/noExcessiveLinesPerFile: ignore */
+import type { ChannelAdapter, LockDriverHandle } from '../types';
+import { type AnnounceMessage, type ForceMessage, type HeartbeatMessage, type RejectMessage, type ReleaseMessage } from './broadcast-protocol';
+import type { LockDriverDeps } from './types';
+interface HoldingState {
+    readonly kind: 'holding';
+    readonly token: string;
+    readonly grantedAt: number;
+    released: boolean;
+    revokeCallback: ((reason: 'force' | 'timeout') => void) | null;
+    heartbeatTimer: ReturnType<typeof setInterval> | null;
+}
+interface RemoteHeldState {
+    readonly kind: 'remote-held';
+    token: string;
+    peerTs: number;
+    lastHeartbeat: number;
+    deadTimer: ReturnType<typeof setTimeout> | null;
+}
+interface IdleState {
+    readonly kind: 'idle';
+}
+type DriverState = IdleState | HoldingState | RemoteHeldState;
+interface Waiter {
+    readonly token: string;
+    readonly resolve: (handle: LockDriverHandle) => void;
+    readonly reject: (error: Error) => void;
+    readonly abort: (error: Error) => void;
+}
+interface PendingAnnounce {
+    readonly requestId: string;
+    readonly ts: number;
+    readonly waiter: Waiter;
+    abandoned: boolean;
+    timer: ReturnType<typeof setTimeout> | null;
+}
+interface PendingForce {
+    readonly token: string;
+    readonly ts: number;
+    readonly waiter: Waiter;
+    abandoned: boolean;
+    timer: ReturnType<typeof setTimeout> | null;
+}
+interface BroadcastDriverState {
+    readonly deps: LockDriverDeps;
+    readonly channel: ChannelAdapter;
+    readonly senderId: string;
+    status: DriverState;
+    readonly waiters: Waiter[];
+    pendingAnnounce: PendingAnnounce | null;
+    pendingForce: PendingForce | null;
+    destroyed: boolean;
+    unsubscribe: (() => void) | null;
+}
+declare function handleRemoteDead(state: BroadcastDriverState, deadToken: string): void;
+declare function revokeHolding(state: BroadcastDriverState, reason: 'force' | 'timeout'): void;
+declare function enterHolding(state: BroadcastDriverState, token: string): LockDriverHandle;
+declare function enterRemoteHeld(state: BroadcastDriverState, token: string, peerTs: number): void;
+declare function abandonPendingAnnounce(state: BroadcastDriverState, reason: string): void;
+declare function abandonPendingForce(state: BroadcastDriverState, reason: string): void;
+/**
+ * 收到他方 announce：
+ *   - 本方 holding（token 不同）→ 广播 reject；对方 handleReject 触发 abandonPendingAnnounce
+ *   - 本方有 pendingAnnounce → 按 (ts, requestId) 字典序仲裁：
+ *     - 我方更早 → 保持；对方在其本地也会执行相同仲裁并 abandon 自己
+ *     - 对方更早 → 本方 abandon，回队等待
+ *   - 本方 idle / remote-held（且无 pending）→ 不响应，让对方 announce 自然走完窗口
+ */
+declare function handleAnnounce(state: BroadcastDriverState, msg: AnnounceMessage): void;
+declare function handleReject(state: BroadcastDriverState, msg: RejectMessage): void;
+declare function handleHeartbeat(state: BroadcastDriverState, msg: HeartbeatMessage): void;
+declare function handleRelease(state: BroadcastDriverState, msg: ReleaseMessage): void;
+/**
+ * 收到他方 force：
+ *   - 本方 pendingForce → 按 (ts, token) 字典序仲裁；败方 abandon
+ *   - 本方 holding（token 不同）→ 立即 revoke('force')
+ *   - 切 / 刷新 remote-held
+ */
+declare function handleForce(state: BroadcastDriverState, msg: ForceMessage): void;
+declare function handleMessage(state: BroadcastDriverState, raw: unknown): void;
+declare function removeWaiter(waiters: Waiter[], target: Waiter): void;
+declare function pumpNextWaiter(state: BroadcastDriverState): void;
+/**
+ * 启动 announce 竞选
+ *
+ * 前置条件（由调用方 pumpNextWaiter / acquireBroadcastLock 保证）：
+ *   - state.destroyed === false
+ *   - state.status.kind === 'idle'
+ *   - state.pendingAnnounce === null && state.pendingForce === null
+ *
+ * 若违反前置条件视为 driver 内部 bug，logger.error 记录后把 waiter 回队兜底
+ * （而非静默死等 —— BC-K 修复）
+ */
+declare function startAnnounceCampaign(state: BroadcastDriverState, waiter: Waiter): void;
+declare function startForceCampaign(state: BroadcastDriverState, waiter: Waiter): void;
+declare function drainOnDestroy(state: BroadcastDriverState, buildAbortError: (token: string) => Error): void;
+export type { BroadcastDriverState, HoldingState, RemoteHeldState, Waiter };
+export { abandonPendingAnnounce, abandonPendingForce, drainOnDestroy, enterHolding, enterRemoteHeld, handleAnnounce, handleForce, handleHeartbeat, handleMessage, handleReject, handleRelease, handleRemoteDead, pumpNextWaiter, removeWaiter, revokeHolding, startAnnounceCampaign, startForceCampaign, };

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

@@ -0,0 +1 @@
+import{isFunction as e}from"../../utils/index.js";import{DEAD_THRESHOLD as n,FORCE_ARBITRATION_WINDOW as t,HEARTBEAT_INTERVAL as r,REJECT_WINDOW as d,genId as a,isBroadcastMessage as s,isEarlier as o}from"./broadcast-protocol.js";function i(e){null!==e.heartbeatTimer&&(clearInterval(e.heartbeatTimer),e.heartbeatTimer=null)}function l(e){null!==e.deadTimer&&(clearTimeout(e.deadTimer),e.deadTimer=null)}function u(e,n){let{name:t,logger:r}=e.deps;"remote-held"===e.status.kind&&e.status.token===n&&(l(e.status),r.warn(`[${t}] broadcast driver: remote holder token=${n} dead by heartbeat timeout`),e.status={kind:"idle"},w(e))}function c(n,t){if("holding"!==n.status.kind)return;let r=n.status;if(r.released)return;r.released=!0,i(r),n.status={kind:"idle"};let{name:d,logger:a}=n.deps;a.debug(`[${d}] broadcast driver: revoked token=${r.token} reason=${t}`);let s=r.revokeCallback;if(e(s))try{s(t)}catch(e){a.error(`[${d}] broadcast driver: revoke callback threw`,e)}w(n)}function k(e,n){let t={kind:"holding",token:n,grantedAt:Date.now(),released:!1,revokeCallback:null,heartbeatTimer:null};return e.status=t,t.heartbeatTimer=setInterval(()=>{t.released||e.destroyed?i(t):e.channel.postMessage({kind:"heartbeat",senderId:e.senderId,token:t.token,ts:Date.now()})},r),e.channel.postMessage({kind:"heartbeat",senderId:e.senderId,token:n,ts:t.grantedAt}),function(e,n){let{name:t,logger:r}=e.deps;return{release:()=>{if("holding"!==e.status.kind||e.status.token!==n||e.status.released)return;let d=e.status;d.released=!0,i(d),e.status={kind:"idle"},r.debug(`[${t}] broadcast driver: release token=${n}`),e.channel.postMessage({kind:"release",senderId:e.senderId,token:n}),w(e)},onRevokedByDriver:t=>{"holding"!==e.status.kind||e.status.token!==n||e.status.released||(e.status.revokeCallback=t)}}}(e,n)}function g(e,t,r){"remote-held"===e.status.kind&&l(e.status);let d={kind:"remote-held",token:t,peerTs:r,lastHeartbeat:Date.now(),deadTimer:null};e.status=d,l(d),d.deadTimer=setTimeout(()=>{u(e,d.token)},n)}function b(e,n){let t=e.pendingAnnounce;if(null===t||t.abandoned)return;t.abandoned=!0,null!==t.timer&&(clearTimeout(t.timer),t.timer=null),e.pendingAnnounce=null;let{name:r,logger:d}=e.deps;d.debug(`[${r}] broadcast driver: abandon pendingAnnounce reason=${n} token=${t.waiter.token}`),e.waiters.push(t.waiter)}function h(e,n){let t=e.pendingForce;if(null===t||t.abandoned)return;t.abandoned=!0,null!==t.timer&&(clearTimeout(t.timer),t.timer=null),e.pendingForce=null;let{name:r,logger:d}=e.deps;d.debug(`[${r}] broadcast driver: abandon pendingForce reason=${n} token=${t.token}`),e.waiters.push(t.waiter)}function f(e,n){if(n.senderId===e.senderId)return;if("holding"===e.status.kind&&!e.status.released){let t=e.status;e.channel.postMessage({kind:"reject",senderId:e.senderId,requestId:n.requestId,holderToken:t.token,holderTs:t.grantedAt});return}let t=e.pendingAnnounce;if(null!==t&&!t.abandoned){if(o(t.ts,t.requestId,n.ts,n.requestId))return;b(e,"arbitration-loss")}}function p(e,n){if(n.senderId===e.senderId)return;if("holding"===e.status.kind&&!e.status.released&&e.status.token!==n.holderToken){let{name:t,logger:r}=e.deps;r.warn(`[${t}] broadcast driver: double-hold detected (own=${e.status.token}, remote=${n.holderToken}); revoking self`),c(e,"force"),g(e,n.holderToken,n.holderTs);return}let t=e.pendingAnnounce;null===t||t.abandoned||t.requestId!==n.requestId||b(e,"rejected"),("idle"===e.status.kind||"remote-held"===e.status.kind)&&g(e,n.holderToken,n.holderTs)}function m(e,n){if(n.senderId!==e.senderId&&("holding"!==e.status.kind||e.status.token!==n.token)){if("holding"===e.status.kind&&!e.status.released){let{name:t,logger:r}=e.deps;r.warn(`[${t}] broadcast driver: double-hold detected via heartbeat (own=${e.status.token}, remote=${n.token}); revoking self`),c(e,"force"),g(e,n.token,n.ts);return}null===e.pendingAnnounce||e.pendingAnnounce.abandoned||b(e,"heartbeat-detected"),g(e,n.token,n.ts)}}function $(e,n){n.senderId!==e.senderId&&"remote-held"===e.status.kind&&e.status.token===n.token&&(l(e.status),e.status={kind:"idle"},w(e))}function v(e,n){if(n.senderId===e.senderId)return;let t=e.pendingForce;if(null!==t&&!t.abandoned){if(o(t.ts,t.token,n.ts,n.token))return;h(e,"arbitration-loss")}"holding"!==e.status.kind||e.status.released||e.status.token===n.token||c(e,"force"),g(e,n.token,n.ts)}function I(e,n){if(s(n))switch(n.kind){case"announce":f(e,n);return;case"reject":p(e,n);return;case"heartbeat":m(e,n);return;case"release":$(e,n);return;case"force":v(e,n);return;default:return}}function T(e,n){for(let t=0;t<e.length;t++)if(e[t]===n)return void e.splice(t,1)}function w(e){if(e.destroyed||"idle"!==e.status.kind||0===e.waiters.length||null!==e.pendingAnnounce||null!==e.pendingForce)return;let n=e.waiters.shift();n&&A(e,n)}function A(e,n){let{name:t,logger:r}=e.deps;if(e.destroyed)return void r.error(`[${t}] broadcast driver: startAnnounceCampaign called after destroyed`);if("idle"!==e.status.kind||null!==e.pendingAnnounce||null!==e.pendingForce){r.error(`[${t}] broadcast driver: startAnnounceCampaign precondition violated (status=${e.status.kind}, pendingAnnounce=${null!==e.pendingAnnounce}, pendingForce=${null!==e.pendingForce})`),e.waiters.push(n);return}let s=a("req"),o=Date.now(),i={requestId:s,ts:o,waiter:n,abandoned:!1,timer:null};e.pendingAnnounce=i,e.channel.postMessage({kind:"announce",senderId:e.senderId,requestId:s,token:n.token,ts:o,force:!1}),r.debug(`[${t}] broadcast driver: announce token=${n.token} reqId=${s}`),i.timer=setTimeout(()=>{if(i.timer=null,i.abandoned||e.destroyed)return;e.pendingAnnounce=null;let d=k(e,n.token);r.debug(`[${t}] broadcast driver: grant token=${n.token}`),n.resolve(d)},d)}function F(e,n){let{name:r,logger:d}=e.deps;if(e.destroyed)return void d.error(`[${r}] broadcast driver: startForceCampaign called after destroyed`);"holding"!==e.status.kind||e.status.released||c(e,"force");let a=Date.now(),s={token:n.token,ts:a,waiter:n,abandoned:!1,timer:null};e.pendingForce=s,e.channel.postMessage({kind:"force",senderId:e.senderId,token:n.token,ts:a}),d.debug(`[${r}] broadcast driver: force-announce token=${n.token} ts=${a}`),s.timer=setTimeout(()=>{if(s.timer=null,s.abandoned||e.destroyed)return;e.pendingForce=null;let t=k(e,n.token);d.debug(`[${r}] broadcast driver: grant (force) token=${n.token}`),n.resolve(t)},t)}function y(e,n){let{deps:t,waiters:r}=e,{name:d,logger:a}=t;a.debug(`[${d}] broadcast driver: destroy (waiters=${r.length}, status=${e.status.kind}, pendingAnnounce=${null!==e.pendingAnnounce}, pendingForce=${null!==e.pendingForce})`);let s=[];if(null!==e.pendingAnnounce){let{pendingAnnounce:n}=e;n.abandoned=!0,null!==n.timer&&clearTimeout(n.timer),e.pendingAnnounce=null,s.push(n.waiter)}if(null!==e.pendingForce){let{pendingForce:n}=e;n.abandoned=!0,null!==n.timer&&clearTimeout(n.timer),e.pendingForce=null,s.push(n.waiter)}for(let e=0;e<r.length;e++)s.push(r[e]);if(r.length=0,"holding"===e.status.kind){let n=e.status;i(n),n.released=!0;try{e.channel.postMessage({kind:"release",senderId:e.senderId,token:n.token})}catch(e){a.error(`[${d}] broadcast driver: release broadcast failed during destroy`,e)}}else"remote-held"===e.status.kind&&l(e.status);e.status={kind:"idle"};for(let e=0;e<s.length;e++)s[e].abort(n(s[e].token));if(null!==e.unsubscribe){try{e.unsubscribe()}catch(e){a.error(`[${d}] broadcast driver: unsubscribe threw`,e)}e.unsubscribe=null}try{e.channel.close()}catch(e){a.error(`[${d}] broadcast driver: channel.close threw`,e)}}export{b as abandonPendingAnnounce,h as abandonPendingForce,y as drainOnDestroy,k as enterHolding,g as enterRemoteHeld,f as handleAnnounce,v as handleForce,m as handleHeartbeat,I as handleMessage,p as handleReject,$ as handleRelease,u as handleRemoteDead,w as pumpNextWaiter,T as removeWaiter,c as revokeHolding,A as startAnnounceCampaign,F as startForceCampaign};

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

@@ -0,0 +1,36 @@
+/**
+ * BroadcastDriver：基于 BroadcastChannel 的跨 Tab 互斥锁
+ *
+ * 适用场景（由 pickDriver 决定）：
+ * - 浏览器环境但不支持 `navigator.locks`（Safari < 15.4 / 老版 Firefox）
+ * - 支持 `BroadcastChannel`（否则继续降级到 StorageDriver）
+ *
+ * 本文件是工厂聚合层，只负责：
+ * - 前置依赖校验（getChannel / id 必须提供）
+ * - 构造 state 容器并订阅 channel
+ * - 暴露 acquire / destroy
+ *
+ * 协议细节、状态机、消息处理、竞选流程、drain 逻辑分别放在：
+ * - `./broadcast-protocol`：消息类型 + 常量 + 校验 + 仲裁工具
+ * - `./broadcast-state`：状态机 + 消息处理 + 竞选流程 + drainOnDestroy
+ *
+ * 前置条件：`deps.getChannel` 必须提供且返回非 null（由 pickDriver 保证）；否则构造期抛错
+ */
+import type { LockDriverContext, LockDriverHandle } from '../types';
+import { type BroadcastDriverState, type Waiter } from './broadcast-state';
+import type { LockDriver, LockDriverDeps } from './types';
+/**
+ * 构造一个 waiter 并绑定 signal / timeout 的 abort 生命周期
+ *
+ * 职责：
+ * - `settled` 标志保证 resolve / reject / abort 互斥，只有第一次生效
+ * - `cleanup`：清理 timeout + signal listener
+ * - `abort`：把 waiter 从队列 / pending 中移除后，走 reject 兜底
+ */
+declare function buildWaiter(ctx: LockDriverContext, state: BroadcastDriverState, resolve: (handle: LockDriverHandle) => void, reject: (error: Error) => void): Waiter;
+declare function acquireBroadcastLock(state: BroadcastDriverState, ctx: LockDriverContext): Promise<LockDriverHandle>;
+/**
+ * 创建 BroadcastDriver 实例
+ */
+declare function createBroadcastDriver(deps: LockDriverDeps): LockDriver;
+export { acquireBroadcastLock, buildWaiter, createBroadcastDriver };

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

@@ -0,0 +1 @@
+import{throwError as e}from"../../throw-error/index.js";import{isFunction as t,isNumber as n,isString as r}from"../../utils/index.js";import{ERROR_FN_NAME as o}from"../constants.js";import{LockAbortedError as i,LockTimeoutError as u}from"../errors/index.js";import{genId as l}from"./broadcast-protocol.js";import{drainOnDestroy as a,handleMessage as s,pumpNextWaiter as d,removeWaiter as c,startAnnounceCampaign as m,startForceCampaign as b}from"./broadcast-state.js";function g(e,t,r,l){let a=!1,s=null;function m(){null!==s&&(clearTimeout(s),s=null),e.signal.removeEventListener("abort",g)}let b={token:e.token,resolve:e=>{a||(a=!0,m(),r(e))},reject:e=>{a||(a=!0,m(),l(e))},abort:e=>{if(!a){if(c(t.waiters,b),null!==t.pendingAnnounce&&t.pendingAnnounce.waiter===b){let e=t.pendingAnnounce;e.abandoned=!0,null!==e.timer&&(clearTimeout(e.timer),e.timer=null),t.pendingAnnounce=null}if(null!==t.pendingForce&&t.pendingForce.waiter===b){let e=t.pendingForce;e.abandoned=!0,null!==e.timer&&(clearTimeout(e.timer),e.timer=null),t.pendingForce=null}b.reject(e),d(t)}}};function g(){b.abort(new i(`[@cmtlyt/lingshu-toolkit#${o}]: acquire aborted (token=${e.token})`))}if(e.signal.aborted)return queueMicrotask(()=>g()),b;if(e.signal.addEventListener("abort",g,{once:!0}),n(e.acquireTimeout)&&e.acquireTimeout>0){let t=e.acquireTimeout;s=setTimeout(()=>{b.abort(new u(`[@cmtlyt/lingshu-toolkit#${o}]: acquire timed out after ${t}ms (token=${e.token})`))},t)}return b}function p(e,t){return t.signal.aborted?Promise.reject(new i(`[@cmtlyt/lingshu-toolkit#${o}]: acquire aborted (token=${t.token})`)):e.destroyed?Promise.reject(new i(`[@cmtlyt/lingshu-toolkit#${o}]: broadcast driver has been destroyed (token=${t.token})`)):new Promise((n,r)=>{let o=g(t,e,n,r);if(t.force)return void b(e,o);if("idle"===e.status.kind&&null===e.pendingAnnounce&&null===e.pendingForce)return void m(e,o);e.waiters.push(o);let{name:i,logger:u}=e.deps;u.debug(`[${i}] broadcast driver: enqueue token=${t.token}, queue=${e.waiters.length}, status=${e.status.kind}`)})}function k(n){let{id:u,getChannel:d}=n;t(d)||e(o,"broadcast driver requires getChannel factory",TypeError),r(u)&&0!==u.length||e(o,"broadcast driver requires a non-empty id",TypeError);let c=d({id:u,channel:"custom"});null===c&&e(o,"broadcast driver getChannel returned null",TypeError);let m={deps:n,channel:c,senderId:l("sender"),status:{kind:"idle"},waiters:[],pendingAnnounce:null,pendingForce:null,destroyed:!1,unsubscribe:null};function b(e){return new i(`[@cmtlyt/lingshu-toolkit#${o}]: broadcast driver destroyed (token=${e})`)}return m.unsubscribe=c.subscribe(e=>s(m,e)),{acquire:e=>p(m,e),destroy:()=>{m.destroyed||(m.destroyed=!0,a(m,b))}}}export{p as acquireBroadcastLock,g as buildWaiter,k as createBroadcastDriver};

package/dist/shared/lock-data/drivers/custom.d.ts

@@ -0,0 +1,27 @@
+/**
+ * CustomDriver：包装用户注入的 `adapters.getLock` 为统一 `LockDriver` 接口
+ *
+ * 适用场景：`adapters.getLock` 存在时由 pickDriver 直接选中；`mode` 字段被忽略
+ * （对应 RFC.md「能力检测与降级」「CustomDriver」章节）
+ *
+ * 职责范围：
+ * - 透传 `name` / `token` / `force` / `source` / 超时 / 合并 signal 到用户工厂
+ * - 把 `acquireTimeout` 统一映射为 signal abort，让用户工厂只需监听 `ctx.signal`
+ *   即可同时响应"超时"与"外部取消"两条路径
+ * - 把用户返回的 `LockDriverHandle`（可能是 Promise）规范化为"同步 handle"返回给上层
+ * - `destroy` 不碰用户资源（用户 handle 由 actions 的 release 路径负责释放）；仅
+ *   清理本 driver 内部持有的合并 controller / 订阅（当前无）
+ *
+ * 与其他 driver 的关键差异：
+ * - 不维护排队 / 心跳 / storage 订阅；完全信任用户实现的互斥语义
+ * - 不拒绝"用户工厂返回的 handle 缺失 onRevokedByDriver"的情况（Phase 5 状态机会
+ *   在 force / timeout 触发时自发广播，不强依赖 driver 上报）
+ */
+import type { LockDriver, LockDriverDeps } from './types';
+/**
+ * 创建 CustomDriver 实例
+ *
+ * 前置条件：`deps.userGetLock` 必须已提供（由 pickDriver 保证）；否则构造期抛错
+ */
+declare function createCustomLockDriver(deps: LockDriverDeps): LockDriver;
+export { createCustomLockDriver };

package/dist/shared/lock-data/drivers/custom.js

@@ -0,0 +1 @@
+import{throwError as e}from"../../throw-error/index.js";import{isFunction as r,isNullOrUndef as t,isNumber as o,isPromiseLike as n}from"../../utils/index.js";import{ERROR_FN_NAME as i}from"../constants.js";import{LockAbortedError as u,LockTimeoutError as a}from"../errors/index.js";function s(s){let{name:c,logger:l,userGetLock:d}=s;r(d)||e(i,"custom driver requires adapters.getLock to be a function",TypeError);let m=!1;return{acquire:async function k(k){m&&e(i,"custom driver has been destroyed",u);let{signal:f,cleanup:v,getTimeoutFired:g}=function(e,r,t){let n=new AbortController,u=!1,s=null;if(e.aborted)return n.abort(e.reason),{signal:n.signal,cleanup:()=>void 0,getTimeoutFired:()=>u};function c(){n.abort(e.reason)}return e.addEventListener("abort",c,{once:!0}),o(r)&&r>0&&(s=setTimeout(()=>{u=!0,n.abort(new a(`[@cmtlyt/lingshu-toolkit#${i}]: acquire timed out after ${r}ms (token=${t})`))},r)),{signal:n.signal,cleanup:function(){null!==s&&(clearTimeout(s),s=null),e.removeEventListener("abort",c)},getTimeoutFired:()=>u}}(k.signal,k.acquireTimeout,k.token),$={name:c,token:k.token,force:k.force,acquireTimeout:k.acquireTimeout,holdTimeout:k.holdTimeout,signal:f};try{let o=d($),u=await Promise.resolve(o);var b=k.token;if(!(u&&r(u.release))){let r=t(u)?String(u):typeof u.release;e(i,`adapters.getLock must return an object with a "release" function, got ${r} (token=${b})`,TypeError)}return v(),l.debug(`[${c}] custom driver: grant token=${k.token}`),function(e,t,o){let{name:i,logger:u}=t,a=e.release,s=e.onRevokedByDriver,c={release:()=>{let r;try{r=a.call(e)}catch(e){u.error(`[${i}] custom driver: user release threw (token=${o})`,e);return}if(n(r))return Promise.resolve(r).catch(e=>{u.error(`[${i}] custom driver: user release rejected (token=${o})`,e)})}};return r(s)&&(c.onRevokedByDriver=s.bind(e)),c}(u,s,k.token)}catch(r){throw v(),g()&&e(i,`acquire timed out after ${String(k.acquireTimeout)}ms (token=${k.token})`,a,{cause:r}),k.signal.aborted&&e(i,`acquire aborted (token=${k.token})`,u,{cause:r}),l.error(`[${c}] custom driver: user getLock rejected (token=${k.token})`,r),r}},destroy:function(){m||(m=!0,l.debug(`[${c}] custom driver: destroy`))}}}export{s as createCustomLockDriver};

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

@@ -0,0 +1,59 @@
+/**
+ * drivers 层入口：能力检测 + 驱动选择 + barrel export
+ *
+ * 对应 RFC.md「能力检测与降级」：pickDriver 按以下优先级决策（首次创建 Entry 时调用一次）：
+ *
+ * 1. `adapters.getLock` 存在 → CustomDriver（最高优先级，覆盖 `mode`）
+ * 2. `id` 未提供（纯本地只读锁）→ LocalLockDriver
+ * 3. `mode` 显式指定（非 `'auto'`）→ 强制使用对应 driver；能力不可用时抛错
+ * 4. `mode === 'auto'` 的降级链：web-locks → broadcast → storage；全不可用时抛错
+ *
+ * 能力探测：
+ * - navigator.locks：Web Locks API，Safari >= 15.4 / Chromium 稳定支持
+ * - BroadcastChannel：同源 Tab 间广播通道
+ * - localStorage：最通用的同步存储，探测需做"实际读写一次"防隐私模式误判
+ *
+ * 本文件**不持久化探测结果**：pickDriver 的入参已决定单次构造的 driver；同 id 二次
+ * 构造直接复用 registry 中的 driver 实例，不会走 pickDriver，所以无需缓存
+ */
+import type { ResolvedAdapters } from '../adapters/index';
+import type { LockDataOptions } from '../types';
+import type { LockDriver } from './types';
+/**
+ * pickDriver 的参数容器
+ *
+ * 把"需要给 driver 的能力"从 `ResolvedAdapters` 中抽出单独字段，避免 driver 层依赖
+ * adapters 层的完整类型（drivers 与 adapters 是平级关系，不应循环依赖）
+ */
+interface PickDriverArgs<T> {
+    /** 已解析的 adapters（pickDefaultAdapters 产出） */
+    readonly adapters: ResolvedAdapters<T>;
+    /** lockData 原始 options —— 只读取 `mode` */
+    readonly options: Pick<LockDataOptions<T>, 'mode'>;
+    /** lockData 原始 id；未提供代表纯本地只读锁 */
+    readonly id: string | undefined;
+}
+/** navigator.locks 可用（Web Locks API） */
+declare function hasNavigatorLocks(): boolean;
+/** BroadcastChannel 可实例化（探测构造不抛错） */
+declare function hasBroadcastChannel(): boolean;
+/** localStorage 可实际读写（隐私模式 / quota 满时返回 false） */
+declare function hasUsableLocalStorage(): boolean;
+/**
+ * 根据能力 / mode / id 选择并构造 LockDriver
+ *
+ * 优先级（RFC.md:689-696）：
+ * 1. `adapters.getLock` 存在 → CustomDriver（最高优先级，覆盖 mode）
+ * 2. `id` 未提供 → LocalLockDriver
+ * 3. 显式 `mode` → 强制使用，不降级（能力不可用抛错）
+ * 4. `mode === 'auto'`（默认）→ web-locks → broadcast → storage
+ */
+declare function pickDriver<T>(args: PickDriverArgs<T>): LockDriver;
+export { createBroadcastDriver } from './broadcast';
+export { createCustomLockDriver } from './custom';
+export { createLocalLockDriver } from './local';
+export { createStorageDriver } from './storage';
+export type { LockDriver, LockDriverDeps } from './types';
+export { createWebLocksDriver } from './web-locks';
+export type { PickDriverArgs };
+export { hasBroadcastChannel, hasNavigatorLocks, hasUsableLocalStorage, pickDriver };

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

@@ -0,0 +1 @@
+import{throwError as r}from"../../throw-error/index.js";import{isFunction as e,isObject as t,isString as o}from"../../utils/index.js";import{ERROR_FN_NAME as a,LOCK_PREFIX as n}from"../constants.js";import{createBroadcastDriver as i}from"./broadcast.js";import{createCustomLockDriver as c}from"./custom.js";import{createLocalLockDriver as s}from"./local.js";import{createStorageDriver as l}from"./storage.js";import{createWebLocksDriver as u}from"./web-locks.js";function m(){let r=globalThis.navigator;if(!t(r))return!1;let{locks:o}=r;return!!t(o)&&e(o.request)}function g(){let r=globalThis.BroadcastChannel;if(!e(r))return!1;try{return new r(`${n}:__pick_driver_probe__`).close(),!0}catch{return!1}}function d(){try{let r=globalThis.localStorage;if(!r)return!1;let e=`${n}:__pick_driver_probe__`;return r.setItem(e,"1"),r.removeItem(e),!0}catch{return!1}}function v(r,e,t){let{adapters:a,id:i}=r;return{name:o(i)&&i.length>0?`${n}:${i}`:`${n}:__local__`,id:i,logger:a.logger,getChannel:e?a.getChannel:void 0,userGetLock:t?a.getLock:void 0}}function b(t){let{adapters:n,options:b,id:f}=t;if(e(n.getLock))return c(v(t,!1,!0));if(!o(f)||0===f.length)return s(v(t,!1,!1));let p=b.mode||"auto";switch(p){case"web-locks":return m()||r(a,"mode='web-locks' requested but navigator.locks is unavailable in current environment",TypeError),u(v(t,!1,!1));case"broadcast":return g()||r(a,"mode='broadcast' requested but BroadcastChannel is unavailable in current environment",TypeError),i(v(t,!0,!1));case"storage":return d()||r(a,"mode='storage' requested but localStorage is unavailable in current environment",TypeError),l(v(t,!1,!1));case"auto":return m()?u(v(t,!1,!1)):g()?i(v(t,!0,!1)):d()?l(v(t,!1,!1)):void r(a,"mode='auto' requires one of navigator.locks / BroadcastChannel / localStorage to be available; got none",TypeError);default:r(a,`unknown mode: ${String(p)}`,TypeError)}}export{i as createBroadcastDriver,c as createCustomLockDriver,s as createLocalLockDriver,l as createStorageDriver,u as createWebLocksDriver,g as hasBroadcastChannel,m as hasNavigatorLocks,d as hasUsableLocalStorage,b as pickDriver};

package/dist/shared/lock-data/drivers/local.d.ts

@@ -0,0 +1,86 @@
+/**
+ * LocalLockDriver：进程内互斥锁
+ *
+ * 适用场景（由 pickDriver 决定）：
+ * - 未传 id（纯本地只读锁）
+ * - `mode` 显式指定为 'storage' 但环境完全不可用时的最终兜底
+ *
+ * 实现要点（对应 RFC.md「LocalLockDriver」「能力检测与降级」）：
+ * - 同 driver 实例内维护一个 FIFO 等待队列；`acquire` 产生的 `LockHandle` 在 `release`
+ *   调用时把下一个 waiter 从队首取出并 resolve
+ * - `force: true` 立即抢占：当前持有者的 `onRevokedByDriver` 以 `'force'` 回调，
+ *   新请求跳过队列直接持锁
+ * - `acquireTimeout` 用本地 `setTimeout` 计时；signal.aborted 或 timeout 触发时把
+ *   对应 waiter 从队列中移除并 reject
+ * - `destroy`：把所有等待者 reject 为 `LockAbortedError`，并清空队列；当前持有者
+ *   `onRevokedByDriver('force')` 并让 release 变成幂等 no-op
+ *
+ * **注意**：本 driver 与 id 无关；同一进程内如有多份 LocalLockDriver 实例，它们
+ * 之间不互斥（由 InstanceRegistry 按 id 唯一化 driver 保证"同 id 共享同一 driver"）
+ */
+import type { LockDriverContext, LockDriverHandle } from '../types';
+import type { LockDriver, LockDriverDeps } from './types';
+/**
+ * 队列中的等待者；每次 `acquire` 未立即拿到锁时会 push 一条
+ *
+ * `force: true` 的 acquire 走 seize 快路径不入队列，所以 waiter 永远是"普通等待者"
+ *
+ * - `resolve` / `reject`：完成该次 acquire 的 Promise
+ * - `abort`：外部通知 waiter "放弃等待"（signal / timeout / destroy），需要解绑计时器
+ *   + 从队列里移除自己，再把 promise reject
+ * - `token`：用于日志与 debug
+ */
+interface LocalWaiter {
+    readonly token: string;
+    readonly resolve: (handle: LockDriverHandle) => void;
+    readonly reject: (error: Error) => void;
+    /** 外部请求中止等待（signal.aborted / timeout / destroy），返回时 waiter 已从队列移除 */
+    readonly abort: (error: Error) => void;
+}
+/** 当前持有者；driver 内部维护，release / revoke 时清空 */
+interface LocalHolder {
+    readonly token: string;
+    /** 通知持有者被驱逐；由 driver 在 force 抢占 / destroy 时调用 */
+    readonly notifyRevoke: (reason: 'force' | 'timeout') => void;
+    /** release 幂等开关；多次 release 只有第一次会推进队列 */
+    released: boolean;
+}
+/**
+ * driver 闭包共享的可变状态句柄；拆出来是为了把原 `createLocalLockDriver` 超长主体拆成独立工具函数
+ *
+ * 通过引用共享 holder 指针：每个工具函数都能读写同一个 holder / waiters / destroyed
+ */
+interface LocalDriverState {
+    readonly name: string;
+    readonly logger: LockDriverDeps['logger'];
+    readonly waiters: LocalWaiter[];
+    holder: LocalHolder | null;
+    destroyed: boolean;
+}
+/**
+ * 把队首 waiter 出队并授予锁；若队列为空则保持空闲
+ *
+ * 这里不做 signal 校验（waiter 进入队列时已注册监听器，signal.aborted 会自行出队）
+ */
+declare function pumpNextWaiter(state: LocalDriverState): void;
+/**
+ * 从队列移除指定 waiter（waiter 放弃等待时调用）
+ *
+ * 使用索引 for 是因为 Array.findIndex + splice 对热路径的两次遍历并不划算
+ */
+declare function removeWaiter(waiters: LocalWaiter[], target: LocalWaiter): void;
+/**
+ * 构造 waiter 并把它 enqueue 到队列；返回 Promise 在拿到锁 / abort 时 settle
+ *
+ * 拆分为独立函数是为了控制 `createLocalLockDriver` 的函数行数（biome noExcessiveLinesPerFunction）
+ */
+declare function enqueueWaiter(state: LocalDriverState, ctx: LockDriverContext): Promise<LockDriverHandle>;
+/**
+ * 创建一个 LocalLockDriver 实例
+ *
+ * driver 为"按 id 单例"（由 InstanceRegistry 管理），本函数只负责实例化，
+ * 不关心 id 是否存在（name 已由 pickDriver 拼好）
+ */
+declare function createLocalLockDriver(deps: LockDriverDeps): LockDriver;
+export type { LocalDriverState, LocalWaiter };
+export { createLocalLockDriver, enqueueWaiter, pumpNextWaiter, removeWaiter };

package/dist/shared/lock-data/drivers/local.js

@@ -0,0 +1 @@
+import{throwError as e}from"../../throw-error/index.js";import{isFunction as r,isNumber as t}from"../../utils/index.js";import{ERROR_FN_NAME as o}from"../constants.js";import{LockAbortedError as l,LockTimeoutError as n}from"../errors/index.js";function i(e,t,o){let{name:l,logger:n}=e,i=null,d=null;return{handle:{release:()=>{let{holder:r}=e;r&&r.token===t&&!r.released&&(r.released=!0,e.holder=null,n.debug(`[${l}] local driver: release by token=${t}`),o())},onRevokedByDriver:e=>{if(i=e,null!==d)try{i(d)}catch(e){n.error(`[${l}] local driver: revoke callback threw`,e)}}},notifyRevoke:e=>{if(d=e,r(i))try{i(e)}catch(e){n.error(`[${l}] local driver: revoke callback threw`,e)}}}}function d(e){let{name:r,logger:t,waiters:o}=e;if(e.holder||0===o.length)return;let l=o.shift();if(!l)return;let{handle:n,notifyRevoke:a}=i(e,l.token,()=>d(e));e.holder={token:l.token,notifyRevoke:a,released:!1},t.debug(`[${r}] local driver: grant token=${l.token}`),l.resolve(n)}function a(e,r){for(let t=0;t<e.length;t++)if(e[t]===r)return void e.splice(t,1)}function u(e,r){let{name:i,logger:d,waiters:u}=e;return new Promise((e,c)=>{let s=!1,k=null;function f(){null!==k&&(clearTimeout(k),k=null),r.signal.removeEventListener("abort",$)}let h={token:r.token,resolve:r=>{s||(s=!0,f(),e(r))},reject:e=>{s||(s=!0,f(),c(e))},abort:e=>{s||(a(u,h),h.reject(e))}};function $(){h.abort(new l(`[@cmtlyt/lingshu-toolkit#${o}]: acquire aborted (token=${r.token})`))}if(t(r.acquireTimeout)&&r.acquireTimeout>0){let e=r.acquireTimeout;k=setTimeout(()=>{h.abort(new n(`[@cmtlyt/lingshu-toolkit#${o}]: acquire timed out after ${e}ms (token=${r.token})`))},e)}r.signal.addEventListener("abort",$,{once:!0}),u.push(h),d.debug(`[${i}] local driver: enqueue token=${r.token}, queue size=${u.length}`)})}async function c(r,t){let{name:n,logger:a}=r;if(r.destroyed&&e(o,"local driver has been destroyed",l),t.signal.aborted&&e(o,`acquire aborted before start (token=${t.token})`,l),t.force)return function(e,r){let{name:t,logger:o}=e;if(e.holder){let l=e.holder;l.released=!0,e.holder=null,o.debug(`[${t}] local driver: force-seize from token=${l.token} by token=${r}`),l.notifyRevoke("force")}let{handle:l,notifyRevoke:n}=i(e,r,()=>d(e));return e.holder={token:r,notifyRevoke:n,released:!1},o.debug(`[${t}] local driver: grant (force) token=${r}`),l}(r,t.token);if(!r.holder){let{handle:e,notifyRevoke:o}=i(r,t.token,()=>d(r));return r.holder={token:t.token,notifyRevoke:o,released:!1},a.debug(`[${n}] local driver: grant (fast-path) token=${t.token}`),e}return u(r,t)}function s(e){let{name:r,logger:t}=e,n={name:r,logger:t,waiters:[],holder:null,destroyed:!1};return{acquire:e=>c(n,e),destroy:()=>{n.destroyed||(n.destroyed=!0,function(e){let{name:r,logger:t,waiters:n}=e;if(t.debug(`[${r}] local driver: destroy (waiters=${n.length}, holding=${e.holder?"yes":"no"})`),e.holder){let r=e.holder;r.released=!0,e.holder=null,r.notifyRevoke("force")}let i=n.slice();n.length=0;for(let e=0;e<i.length;e++)i[e].abort(new l(`[@cmtlyt/lingshu-toolkit#${o}]: local driver destroyed (token=${i[e].token})`))}(n))}}}export{s as createLocalLockDriver,u as enqueueWaiter,d as pumpNextWaiter,a as removeWaiter};

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

@@ -0,0 +1,67 @@
+/**
+ * StorageDriver 协议层：存储格式定义、常量、校验、nonce 生成
+ *
+ * ## 存储格式（对应 RFC.md「StorageDriver 协议」）
+ * key：`${LOCK_PREFIX}:${id}:driver-lock`
+ * value：JSON
+ * ```
+ * {
+ *   "holder": { "token": string, "heartbeat": number, "nonce": string } | null,
+ *   "queue": Array<{ "token": string, "ts": number }>,
+ *   "rev": number
+ * }
+ * ```
+ *
+ * ## 关键字段
+ * - `holder.nonce`：每次 holder 写入生成一次的随机值；CAS verify 时用 token + nonce
+ *   双重匹配（ST-1 修复）。两个 Tab 并发写入时，后写者覆盖先写者；先写者读回验证发现
+ *   token 相同但 nonce 不同 → 判定竞争失败，退避重试
+ * - `queue`：本地 FIFO 等待队列的持久化视图；所有 Tab 共享，入队 / 出队均走 CAS 重试
+ * - `rev`：每次写入递增，辅助调试丢更新问题；storage 事件可能在 rev 相同时也触发
+ *
+ * ## 时间常量
+ * - HEARTBEAT_INTERVAL=500ms：下调自 1000ms，缩短 force 抢占被原持有者发现的最大延迟（ST-6）
+ * - DEAD_THRESHOLD=2500ms：>= 4 个心跳周期，避免系统短时停顿误判崩溃
+ * - POLL_INTERVAL=250ms：同 Tab 多实例场景下 storage 事件不触发，用 polling 兜底
+ * - WRITE_RETRY_MAX=3：CAS / 入队 / 出队的最大重试次数（ST-5）
+ * - WRITE_RETRY_JITTER_MAX=20ms：重试前随机退避 0~20ms，分散并发写者
+ */
+/** 心跳周期（ms）；持有者每此毫秒更新一次 holder.heartbeat */
+declare const HEARTBEAT_INTERVAL = 500;
+/** 崩溃阈值（ms）；`now - holder.heartbeat > 此值` 视为远端崩溃 */
+declare const DEAD_THRESHOLD = 2500;
+/** 同 Tab 多实例的 polling 兜底周期（storage 事件不跨同 Tab 触发） */
+declare const POLL_INTERVAL = 250;
+/** CAS / 入队 / 出队的最大重试次数 */
+declare const WRITE_RETRY_MAX = 3;
+interface StorageHolder {
+    readonly token: string;
+    readonly heartbeat: number;
+    /** 随机 nonce；CAS verify 时用 token + nonce 双重匹配 */
+    readonly nonce: string;
+}
+interface StorageQueueEntry {
+    readonly token: string;
+    readonly ts: number;
+}
+interface StorageLockValue {
+    readonly holder: StorageHolder | null;
+    readonly queue: readonly StorageQueueEntry[];
+    readonly rev: number;
+}
+declare const EMPTY_VALUE: StorageLockValue;
+declare function isStorageLockValue(value: unknown): value is StorageLockValue;
+/**
+ * 生成 holder 的随机 nonce
+ *
+ * 同 `broadcast-protocol.genId`：不依赖 crypto.randomUUID，保持广兼容
+ */
+declare function genNonce(): string;
+/** 生成 waiter token（driver 内部排队用，与用户传入的 ctx.token 区分） */
+declare function genWaiterId(): string;
+/** 计算下一次重试的退避时长（0~WRITE_RETRY_JITTER_MAX ms 的随机数） */
+declare function nextRetryJitter(): number;
+/** 判定 holder 是否已崩溃（heartbeat 超过阈值未更新） */
+declare function isHolderDead(holder: StorageHolder): boolean;
+export type { StorageHolder, StorageLockValue, StorageQueueEntry };
+export { DEAD_THRESHOLD, EMPTY_VALUE, genNonce, genWaiterId, HEARTBEAT_INTERVAL, isHolderDead, isStorageLockValue, nextRetryJitter, POLL_INTERVAL, WRITE_RETRY_MAX, };

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

@@ -0,0 +1 @@
+import{isArray as e,isNumber as t,isObject as n,isString as r}from"../../utils/index.js";let o=500,u=2500,i=250,a=3,l={holder:null,queue:[],rev:0};function c(e){return t(e)&&Number.isFinite(e)}function f(t){var o,u;if(!n(t)||!c(t.rev)||!e(t.queue))return!1;for(let e=0;e<t.queue.length;e++)if(!(n(o=t.queue[e])&&r(o.token)&&c(o.ts)))return!1;return null===t.holder||!!(n(u=t.holder)&&r(u.token)&&c(u.heartbeat)&&r(u.nonce))}function d(){return`n_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,10)}`}function h(){return`w_${Date.now().toString(36)}_${Math.random().toString(36).slice(2,10)}`}function E(){return Math.floor(20*Math.random())}function _(e){return Date.now()-e.heartbeat>u}export{u as DEAD_THRESHOLD,l as EMPTY_VALUE,o as HEARTBEAT_INTERVAL,i as POLL_INTERVAL,a as WRITE_RETRY_MAX,d as genNonce,h as genWaiterId,_ as isHolderDead,f as isStorageLockValue,E as nextRetryJitter};

package/dist/shared/lock-data/drivers/storage-state.d.ts

@@ -0,0 +1,103 @@
+/**
+ * StorageDriver 状态层：状态机 + CAS 读写 + 队列操作 + 心跳 + drain
+ *
+ * ## CAS 模式（ST-1 修复）
+ * 读取 → 判定（idle / dead-holder / queue-head-ready）→ 生成新 holder（带 nonce）→
+ * 写入 → 再读回 verify（token + nonce 必须都匹配）。verify 失败 → 随机退避 → 重试；
+ * 超过 WRITE_RETRY_MAX 次 → 放弃本次尝试，等 storage 事件 / polling 触发下一轮
+ *
+ * ## 状态机
+ *   - `idle`：无人持锁（本 Tab 视角）
+ *   - `holding`：本 Tab 持锁；周期心跳 + 读 verify（发现被覆盖 → revoke('force')）
+ *
+ * 注意：storage driver **不维护 remote-held 状态**，因为 storage 是"随时可读的权威"；
+ * 需要知道远端持有者状态时直接 readStorage()，比内存状态机更可靠
+ *
+ * ## 队列（ST-5 修复）
+ * 本地队列 `state.waiters`（driver 内存）+ storage 队列 `value.queue`（跨 Tab 持久化）
+ * 两者通过 waiter.token 关联；入队 / 出队均走 CAS 重试（最多 WRITE_RETRY_MAX 次）
+ */
+import type { LockDriverHandle } from '../types';
+import type { LockDriverDeps } from './types';
+interface HoldingState {
+    readonly kind: 'holding';
+    readonly token: string;
+    /** 本 Tab 写入 holder 时生成的 nonce；CAS verify 依据 */
+    readonly nonce: string;
+    released: boolean;
+    revokeCallback: ((reason: 'force' | 'timeout') => void) | null;
+    heartbeatTimer: ReturnType<typeof setInterval> | null;
+}
+interface IdleState {
+    readonly kind: 'idle';
+}
+type DriverLocalState = IdleState | HoldingState;
+interface Waiter {
+    readonly token: string;
+    readonly resolve: (handle: LockDriverHandle) => void;
+    readonly reject: (error: Error) => void;
+    readonly abort: (error: Error) => void;
+    /**
+     * 查询 waiter 是否已 settled（resolve / reject / abort 任一）
+     *
+     * pump / force 路径需要在拿到 grant 后 resolve 前检查：若已 settled 说明 waiter
+     * 已被 abort / timeout / signal 终结，此时抢到的 storage 锁应立即释放，避免泄漏（S-4 修复）
+     */
+    readonly isSettled: () => boolean;
+}
+interface StorageDriverState {
+    readonly deps: LockDriverDeps;
+    readonly storage: Storage;
+    readonly key: string;
+    status: DriverLocalState;
+    readonly waiters: Waiter[];
+    destroyed: boolean;
+    /** 并发保护：pumpNextWaiter 进行中；避免 storage 事件 + polling 同时触发多路 tryAcquire */
+    pumping: boolean;
+    unsubscribeStorageEvent: (() => void) | null;
+    pollTimer: ReturnType<typeof setInterval> | null;
+}
+declare function enqueueInStorage(state: StorageDriverState, token: string): Promise<boolean>;
+interface AcquireGrant {
+    readonly token: string;
+    readonly nonce: string;
+}
+declare function tryAcquire(state: StorageDriverState, token: string, force: boolean): Promise<AcquireGrant | null>;
+declare function revokeHolding(state: StorageDriverState, reason: 'force' | 'timeout'): void;
+declare function removeWaiter(waiters: Waiter[], target: Waiter): void;
+/**
+ * 尝试推进队首 waiter
+ *
+ * SS-1 修复：加 `state.pumping` 并发保护 —— storage 事件 + polling 可能并发触发，
+ * 必须保证同一时刻只有一个 `tryAcquire` 流程在跑
+ */
+declare function pumpNextWaiter(state: StorageDriverState): void;
+/**
+ * 在 storage 中释放 holder（幂等；仅当 token + nonce 匹配才真释放）
+ */
+declare function releaseHolderInStorage(state: StorageDriverState, token: string, nonce: string): void;
+declare function enterHolding(state: StorageDriverState, token: string, nonce: string): LockDriverHandle;
+/**
+ * 当 storage 发生外部变更（其他 Tab 写入 / polling 检测到 holder 崩溃）时触发
+ *
+ * 职责：
+ *   1. 若本 Tab holding 且 holder 在 storage 中已被覆盖 → revoke('force')
+ *   2. 若本 Tab idle 且有 waiter → 尝试 pump
+ */
+declare function handleExternalChange(state: StorageDriverState): void;
+/**
+ * 订阅 window 的 storage 事件（跨 Tab 通知）
+ *
+ * 注意：storage 事件不跨同 Tab 触发，同 Tab 多实例需 polling 兜底（见 startPolling）
+ */
+declare function subscribeStorageEvent(state: StorageDriverState): (() => void) | null;
+declare function startPolling(state: StorageDriverState): ReturnType<typeof setInterval>;
+/**
+ * 判断当前是否应立即尝试抢锁（快路径，避开入队 → 等事件 → pump 的流程）
+ *
+ * 条件：本 Tab idle + 无其他本地 waiter + (storage 无 holder 或 holder 已崩溃) + 队列空
+ */
+declare function canFastAcquire(state: StorageDriverState): false | true;
+declare function drainOnDestroy(state: StorageDriverState, buildAbortError: (token: string) => Error): void;
+export type { AcquireGrant, StorageDriverState, Waiter };
+export { canFastAcquire, drainOnDestroy, enqueueInStorage, enterHolding, handleExternalChange, pumpNextWaiter, releaseHolderInStorage, removeWaiter, revokeHolding, startPolling, subscribeStorageEvent, tryAcquire, };

package/dist/shared/lock-data/drivers/storage-state.js

@@ -0,0 +1 @@
+import{isFunction as e}from"../../utils/index.js";import{EMPTY_VALUE as t,HEARTBEAT_INTERVAL as r,POLL_INTERVAL as n,WRITE_RETRY_MAX as o,genNonce as l,isHolderDead as a,isStorageLockValue as s,nextRetryJitter as u}from"./storage-protocol.js";function i(e){let r,{storage:n,key:o,deps:l}=e;try{r=n.getItem(o)}catch(e){return l.logger.warn(`[${l.name}] storage driver: getItem failed at key=${o}`,e),t}if(null===r||""===r)return t;try{let e=JSON.parse(r);if(s(e))return e;return l.logger.warn(`[${l.name}] storage driver: malformed value at key=${o}; treating as empty`),t}catch(e){return l.logger.warn(`[${l.name}] storage driver: JSON.parse failed at key=${o}`,e),t}}function d(e,t){let{storage:r,key:n,deps:o}=e;try{return r.setItem(n,JSON.stringify(t)),"success"}catch(e){return o.logger.warn(`[${o.name}] storage driver: setItem failed`,e),"abort"}}function c(e,t){var r;return r=()=>(function(e,t){if(e.destroyed)return"abort";let r=i(e);for(let e=0;e<r.queue.length;e++)if(r.queue[e].token===t)return"success";if("abort"===d(e,{holder:r.holder,queue:[...r.queue,{token:t,ts:Date.now()}],rev:r.rev+1}))return"abort";let n=i(e);for(let e=0;e<n.queue.length;e++)if(n.queue[e].token===t)return"success";return"retry"})(e,t),new Promise(e=>{let t=0,n=()=>{let l=r();"success"===l?e(!0):"abort"===l||++t>=o?e(!1):setTimeout(n,u())};n()})}function g(e,t,r){return new Promise(n=>{let s=0,c=()=>{let g=function(e,t,r){if(e.destroyed)return"abort";let n=i(e),{holder:o,queue:s}=n;if(null!==o&&!a(o)&&!r||!r&&s.length>0&&s[0].token!==t)return"cannot-acquire";let u=l(),c=Date.now(),g=s.filter(e=>e.token!==t);if("abort"===d(e,{holder:{token:t,heartbeat:c,nonce:u},queue:g,rev:n.rev+1}))return"abort";let h=i(e);return null===h.holder||h.holder.token!==t||h.holder.nonce!==u?"retry":{token:t,nonce:u}}(e,t,r);"abort"===g||"cannot-acquire"===g?n(null):"retry"!==g?n(g):++s>=o?n(null):setTimeout(c,u())};c()})}function h(e){null!==e.heartbeatTimer&&(clearInterval(e.heartbeatTimer),e.heartbeatTimer=null)}function f(t,r){if("holding"!==t.status.kind)return;let n=t.status;if(n.released)return;n.released=!0,h(n),t.status={kind:"idle"};let{name:o,logger:l}=t.deps;l.debug(`[${o}] storage driver: revoked token=${n.token} reason=${r}`);let a=n.revokeCallback;if(e(a))try{a(r)}catch(e){l.error(`[${o}] storage driver: revoke callback threw`,e)}v(t)}function k(e,t){for(let r=0;r<e.length;r++)if(e[r]===t)return void e.splice(r,1)}function v(e){if(e.destroyed||e.pumping||"idle"!==e.status.kind||0===e.waiters.length)return;let[t]=e.waiters;e.pumping=!0,g(e,t.token,!1).then(r=>{if(e.pumping=!1,null===r)return;if(e.destroyed){b(e,t.token,r.nonce),k(e.waiters,t);return}if("idle"!==e.status.kind)return void b(e,t.token,r.nonce);let[n]=e.waiters;if(n!==t)return void b(e,t.token,r.nonce);if(t.isSettled()){e.waiters.shift(),b(e,t.token,r.nonce);return}e.waiters.shift();let o=m(e,t.token,r.nonce);e.deps.logger.debug(`[${e.deps.name}] storage driver: grant token=${t.token}`),t.resolve(o)})}function b(e,t,r){let n=i(e);null===n.holder||n.holder.token!==t||n.holder.nonce!==r||d(e,{holder:null,queue:n.queue,rev:n.rev+1})}function m(e,t,n){let o={kind:"holding",token:t,nonce:n,released:!1,revokeCallback:null,heartbeatTimer:null};return e.status=o,o.heartbeatTimer=setInterval(()=>{if(o.released||e.destroyed)return void h(o);let t=i(e);null===t.holder||t.holder.token!==o.token||t.holder.nonce!==o.nonce?f(e,"force"):d(e,{holder:{token:o.token,heartbeat:Date.now(),nonce:o.nonce},queue:t.queue,rev:t.rev+1})},r),function(e,t,r){let{name:n,logger:o}=e.deps;return{release:()=>{if("holding"!==e.status.kind||e.status.token!==t||e.status.nonce!==r||e.status.released)return;let l=e.status;l.released=!0,h(l),e.status={kind:"idle"},o.debug(`[${n}] storage driver: release token=${t}`),b(e,t,r),v(e)},onRevokedByDriver:n=>{"holding"!==e.status.kind||e.status.token!==t||e.status.nonce!==r||e.status.released||(e.status.revokeCallback=n)}}}(e,t,n)}function p(e){if(e.destroyed)return;let t=i(e);if("holding"===e.status.kind&&!e.status.released){(null===t.holder||t.holder.token!==e.status.token||t.holder.nonce!==e.status.nonce)&&f(e,"force");return}"idle"===e.status.kind&&e.waiters.length>0&&(null===t.holder||a(t.holder))&&v(e)}function y(t){let r=globalThis;if(!e(r.addEventListener))return t.deps.logger.warn(`[${t.deps.name}] storage driver: globalThis.addEventListener unavailable; cross-tab notification disabled`),null;let n=e=>{if(e.storageArea===t.storage&&(e.key===t.key||null===e.key))try{p(t)}catch(e){t.deps.logger.error(`[${t.deps.name}] storage driver: handleExternalChange threw`,e)}};return r.addEventListener("storage",n),()=>{r.removeEventListener?.("storage",n)}}function w(e){return setInterval(()=>{try{p(e)}catch(t){e.deps.logger.error(`[${e.deps.name}] storage driver: polling threw`,t)}},n)}function $(e){if("idle"!==e.status.kind||e.waiters.length>0)return!1;let t=i(e);return!(t.queue.length>0)&&(null===t.holder||a(t.holder))}function q(e,t){let{deps:r,waiters:n}=e,{name:o,logger:l}=r;if(l.debug(`[${o}] storage driver: destroy (waiters=${n.length}, status=${e.status.kind})`),null!==e.pollTimer&&(clearInterval(e.pollTimer),e.pollTimer=null),null!==e.unsubscribeStorageEvent){try{e.unsubscribeStorageEvent()}catch(e){l.error(`[${o}] storage driver: unsubscribe storage event threw`,e)}e.unsubscribeStorageEvent=null}if("holding"===e.status.kind){let t=e.status;h(t),t.released=!0,b(e,t.token,t.nonce)}e.status={kind:"idle"};let a=n.slice();if(n.length=0,a.length>0)try{let t=i(e),r=new Set;for(let e=0;e<a.length;e++)r.add(a[e].token);let n=t.queue.filter(e=>!r.has(e.token));n.length!==t.queue.length&&d(e,{holder:t.holder,queue:n,rev:t.rev+1})}catch(e){l.error(`[${o}] storage driver: batch dequeue failed during destroy`,e)}for(let e=0;e<a.length;e++)a[e].abort(t(a[e].token))}export{$ as canFastAcquire,q as drainOnDestroy,c as enqueueInStorage,m as enterHolding,p as handleExternalChange,v as pumpNextWaiter,b as releaseHolderInStorage,k as removeWaiter,f as revokeHolding,w as startPolling,y as subscribeStorageEvent,g as tryAcquire};