webloom-framework 0.4.2 → 0.4.3

package/dist/{runtimeTypes-CleHMFaq.d.ts → runtimeTypes-50LVQs0h.d.ts}

@@ -597,6 +597,8 @@ interface RuntimeServiceSnapshot {
 interface RuntimeSnapshot {
     /** 固定协议版本。 */
     protocolVersion: string;
+    /** 当前物理 endpoint 的框架绑定；旧兼容快照可以省略，收到后由 transport 补齐。 */
+    readonly binding?: RuntimeEndpointBinding;
     /** Runtime 逻辑标识。 */
     runtimeId: string;
     /** 真实 Runtime 类型。 */
@@ -896,223 +898,6 @@ declare const LIFECYCLE_ERROR_TEXT: Readonly<Record<string, string>>;
 /** 将生命周期错误码映射为中文提示。 */
 declare function lifecycleErrorText(code: string): string;
 
-declare const RUNTIME_PROTOCOL_VERSION: "webloom.runtime.v1";
-declare const RUNTIME_SNAPSHOT_TYPE: "webloom.runtime.v1.snapshot";
-declare const RUNTIME_ERROR_TYPE: "webloom.runtime.v1.runtime-error";
-declare const RUNTIME_CALL_TYPE: "webloom.runtime.v1.call";
-declare const RUNTIME_RESULT_TYPE: "webloom.runtime.v1.result";
-declare const RUNTIME_ERROR_MESSAGE_TYPE: "webloom.runtime.v1.error";
-declare const RUNTIME_CANCEL_TYPE: "webloom.runtime.v1.cancel";
-declare const RUNTIME_NEXT_TYPE: "webloom.runtime.v1.next";
-declare const RUNTIME_CREDIT_TYPE: "webloom.runtime.v1.credit";
-declare const RUNTIME_CLOSE_TYPE: "webloom.runtime.v1.close";
-declare const RUNTIME_CLOSE_ACK_TYPE: "webloom.runtime.v1.close-ack";
-/** 每条 Runtime wire 消息所属的框架 endpoint 身份。 */
-type RuntimeSessionBinding = RuntimeEndpointBinding;
-interface RuntimeSnapshotUnit {
-    /** 插件标识。 */
-    readonly pluginId: string;
-    /** 单元标识。 */
-    readonly unitId: string;
-    /** Runtime。 */
-    readonly runtime: RuntimeKind;
-    /** 实例标识。 */
-    readonly instanceId?: string;
-    /** 状态。 */
-    readonly state: PluginStateKind;
-}
-type RuntimeSnapshotMessage = RuntimeSnapshot & {
-    readonly type: typeof RUNTIME_SNAPSHOT_TYPE;
-    readonly binding: RuntimeSessionBinding;
-};
-interface RuntimeErrorMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_ERROR_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送此错误的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** 结构化错误码。 */
-    readonly code: string;
-    /** 脱敏消息。 */
-    readonly message: string;
-    /** 失败阶段。 */
-    readonly phase: "validate" | "wait" | "dispatch" | "execute" | "receive" | "dispose";
-    /** 可选插件标识。 */
-    readonly pluginId?: string;
-    /** 可选单元标识。 */
-    readonly unitId?: string;
-}
-interface RuntimeCallMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_CALL_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发起调用的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** 方向内唯一 call id。 */
-    readonly callId: string;
-    /** capability 标识。 */
-    readonly capabilityId: string;
-    /** 契约版本。 */
-    readonly contractVersion: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-    /** 调用模式。 */
-    readonly mode: "unary" | "stream";
-    /** 本次派发的剩余预算。 */
-    readonly timeoutMs: number;
-    /** 已 parser 验证的请求。 */
-    readonly request: unknown;
-    /** 产品操作标识。 */
-    readonly operationId?: string;
-    /** 领域授权标识。 */
-    readonly grantId?: string;
-    /** stream 初始 credit。 */
-    readonly initialCredit?: number;
-}
-interface RuntimeUnaryResultMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_RESULT_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送结果的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** call id。 */
-    readonly callId: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-    /** unary 结果。 */
-    readonly result: unknown;
-}
-interface RuntimeStreamReadyMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_RESULT_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送结果的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** call id。 */
-    readonly callId: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-    /** stream 建立确认。 */
-    readonly streamReady: true;
-}
-interface RuntimeStreamDoneMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_RESULT_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送结果的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** call id。 */
-    readonly callId: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-    /** stream 正常结束。 */
-    readonly done: true;
-}
-type RuntimeResultMessage = RuntimeUnaryResultMessage | RuntimeStreamReadyMessage | RuntimeStreamDoneMessage;
-interface RuntimeErrorResponseMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_ERROR_MESSAGE_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送错误响应的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** call id。 */
-    readonly callId: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-    /** 结构化错误。 */
-    readonly error: {
-        readonly code: string;
-        readonly message: string;
-        readonly phase: RuntimeErrorMessage["phase"];
-        readonly details?: Readonly<Record<string, unknown>>;
-    };
-}
-interface RuntimeCancelMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_CANCEL_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送取消的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** call id。 */
-    readonly callId: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-}
-interface RuntimeNextMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_NEXT_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送 stream item 的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** call id。 */
-    readonly callId: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-    /** 连续序号。 */
-    readonly sequence: number;
-    /** parser 验证的 item。 */
-    readonly item: unknown;
-}
-interface RuntimeCreditMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_CREDIT_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送 credit 的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** call id。 */
-    readonly callId: string;
-    /** exposure 身份。 */
-    readonly serviceInstanceId: string;
-    /** 新增 credit。 */
-    readonly count: number;
-}
-/** 请求对端先同步 fence、再等待真实执行排空。 */
-interface RuntimeCloseMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_CLOSE_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发起关闭的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** 对端 drain 的最大等待时间。 */
-    readonly timeoutMs?: number;
-}
-/** 对端完成或超时 drain 后返回的关闭确认。 */
-interface RuntimeCloseAckMessage {
-    /** 消息类型。 */
-    readonly type: typeof RUNTIME_CLOSE_ACK_TYPE;
-    /** 协议版本。 */
-    readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
-    /** 发送确认的物理 endpoint 绑定。 */
-    readonly binding: RuntimeSessionBinding;
-    /** 确认对应的发起方 binding，防止旧 close-ack 误配新 session。 */
-    readonly acknowledgedBinding: RuntimeSessionBinding;
-    /** 对端本次 drain 的结果。 */
-    readonly drained: boolean;
-    /** 是否达到 bounded deadline。 */
-    readonly timedOut: boolean;
-    /** deadline 到达时仍存活的执行槽数量。 */
-    readonly pendingExecutions: number;
-}
-type RuntimeWireMessage = RuntimeSnapshotMessage | RuntimeErrorMessage | RuntimeCallMessage | RuntimeResultMessage | RuntimeErrorResponseMessage | RuntimeCancelMessage | RuntimeNextMessage | RuntimeCreditMessage | RuntimeCloseMessage | RuntimeCloseAckMessage;
-interface RuntimeMessageCodec {
-    /** 严格验证并冻结 v4 message。 */
-    encode(message: RuntimeWireMessage): RuntimeWireMessage;
-    /** 严格解析 v4 message；旧协议直接拒绝。 */
-    decode(value: unknown): RuntimeWireMessage;
-}
-declare function createRuntimeMessageCodec(): RuntimeMessageCodec;
-declare function isRuntimeSnapshot(value: RuntimeWireMessage): value is RuntimeSnapshotMessage;
-
 /** 验证 unknown 并返回领域类型的生产 parser。 */
 interface ValueParser<T> {
     /** 验证 unknown；失败必须抛出校验错误。 */
@@ -1320,8 +1105,8 @@ interface CapabilityBridge {
     /** 取惰性 typed client；没有服务时不在此处同步失败。 */
     getClient<C extends RemoteCapability>(capability: C, scope?: LifecycleScope): CapabilityClient<C>;
     /** 应用一个完整对端目录。 */
-    /** 应用带框架 binding 的远端完整目录；缺失 binding 必须拒绝。 */
-    applySnapshot(snapshot: RuntimeSnapshotMessage): SnapshotApplyResult;
+    /** 应用一个远端完整目录；生产 wire 带 binding，旧 testing fixture 可省略。 */
+    applySnapshot(snapshot: RuntimeSnapshot): SnapshotApplyResult;
     /** 同步撤销全部旧代理。 */
     invalidate(reason?: string): void;
     /** 连接断开；旧代理永久失效。 */
@@ -1841,6 +1626,8 @@ interface RuntimeStatusSnapshot extends Omit<RuntimeSnapshot, "protocolVersion"
     readonly binding?: RuntimeEndpointBinding;
     /** 脱敏 Runtime 错误。 */
     readonly error?: string;
+    /** 结构化运行错误码，例如 runtime_lock_conflict。 */
+    readonly errorCode?: string;
 }
 type RuntimeStatusListener = (snapshot: RuntimeStatusSnapshot) => void;
 interface AppLike {
@@ -1903,4 +1690,4 @@ declare class RuntimeUnavailableError extends Error {
     constructor(message?: string);
 }
 
-export { type RuntimeNextMessage as $, type PluginHost as A, RUNTIME_CALL_TYPE as B, type CapabilityDescriptor as C, RUNTIME_CANCEL_TYPE as D, RUNTIME_CLOSE_ACK_TYPE as E, RUNTIME_CLOSE_TYPE as F, RUNTIME_CREDIT_TYPE as G, type HostCapabilityRegistration as H, RUNTIME_ERROR_MESSAGE_TYPE as I, RUNTIME_ERROR_TYPE as J, RUNTIME_NEXT_TYPE as K, type LifecycleScopeIdentity as L, RUNTIME_PROTOCOL_VERSION as M, RUNTIME_RESULT_TYPE as N, RUNTIME_SNAPSHOT_TYPE as O, type PluginManifest as P, type RuntimeCancelMessage as Q, type RuntimeKind as R, type ScopedTaskScheduler as S, type RuntimeCloseAckMessage as T, type UpgradeGate as U, type RuntimeCloseMessage as V, type WindowApp as W, type RuntimeCreditMessage as X, type RuntimeErrorMessage as Y, type RuntimeErrorResponseMessage as Z, type RuntimeMessageCodec as _, type PluginGraph as a, type PeerCapabilityDependency as a$, type RuntimeResultMessage as a0, type RuntimeSessionBinding as a1, type RuntimeSnapshotMessage as a2, type RuntimeSnapshotUnit as a3, type RuntimeStreamDoneMessage as a4, type RuntimeStreamReadyMessage as a5, type RuntimeUnaryResultMessage as a6, type RuntimeUnitAttributesInput as a7, type RuntimeUnitAvailabilityInput as a8, type RuntimeUnitParentScopeInput as a9, type FrameworkErrorCode as aA, type FrameworkErrorContext as aB, type FrameworkErrorPhase as aC, type HandlerCallContext as aD, type HandlerOptions as aE, type HandlerOrigin as aF, type HostListener as aG, type ItemOf as aH, LIFECYCLE_ERROR_TEXT as aI, type LifecycleCleanup as aJ, type LifecycleCleanupIssue as aK, type LifecycleCleanupPhase as aL, type LifecycleDisposeOptions as aM, type LifecycleDisposeResult as aN, type LifecycleResourceHandle as aO, type LifecycleResourceSnapshot as aP, type LifecycleScopeKind as aQ, LifecycleScopeRevokedError as aR, type LifecycleScopeState as aS, type LocalCapability as aT, type LocalServiceOf as aU, type Message as aV, type MessageBus as aW, type MessageBusSnapshot as aX, type MessageHandler as aY, type MessageMode as aZ, type OwnedResourceDefinition as a_, type RuntimeUnitSnapshot as aa, type RuntimeWireMessage as ab, StartupCapabilityError as ac, StartupPluginError as ad, createCapabilityRegistry as ae, createInMemoryPluginConfigStore as af, createPluginHost as ag, createRuntimeMessageCodec as ah, invokeCapabilityHandler as ai, isRuntimeSnapshot as aj, type Capability as ak, type CapabilityDependency as al, type PluginContribution as am, type PluginConfig as an, type PluginContextExtension as ao, type PluginSetup as ap, type PluginDefinition as aq, type AppLike as ar, type CapabilityBridge as as, type CapabilityClient as at, type CapabilityKind as au, type DefineLocalCapabilityOptions as av, type DefineRpcCapabilityOptions as aw, type DefineStreamCapabilityOptions as ax, type DispatchOptions as ay, type EventHandler as az, type RuntimeUnitDependency as b, type StreamSubscribeOptions as b$, type PeerScopeView as b0, PermissionDeniedError as b1, type PermissionLeaseBinding as b2, type PermissionLeaseBindingExpectation as b3, PermissionLeaseRevokedError as b4, type PluginAttributes as b5, type PluginContext as b6, type PluginIntentCommand as b7, type PluginIntentCommandResult as b8, type PluginIntentController as b9, type RpcCapability as bA, type RpcCapabilityBase as bB, type RpcClient as bC, type RpcHandler as bD, type RpcTransferDescriptor as bE, type RuntimeCapabilityDependency as bF, type RuntimeEndpointState as bG, RuntimeInitializationError as bH, type RuntimeLimits as bI, type RuntimeServiceSnapshot as bJ, type RuntimeSnapshot as bK, type RuntimeStatusListener as bL, type RuntimeStatusSnapshot as bM, RuntimeUnavailableError as bN, type RuntimeUnitDependencyInput as bO, type RuntimeUnitDescriptorInput as bP, type RuntimeUnitImplementationRegistry as bQ, SCOPED_TASK_SCHEDULER_CAPABILITY as bR, type ScopedTaskDefinition as bS, type ScopedTaskSnapshot as bT, type SnapshotApplyResult as bU, type StartupCapabilityErrorDetails as bV, type StartupPluginErrorDetails as bW, type StreamCapability as bX, type StreamCapabilityBase as bY, type StreamClient as bZ, type StreamHandler as b_, type PluginIntentCoordinator as ba, type PluginIntentSnapshot as bb, type PluginIntentSubmissionResult as bc, type PluginLifecycleState as bd, type PluginManifestInput as be, type PluginStartupMode as bf, type PluginState as bg, type PluginStateKind as bh, type PluginTeardown as bi, type PluginUnitGraph as bj, type PluginUnitState as bk, type PublishOptions as bl, RESOURCE_OWNER as bm, RESOURCE_REGISTRY as bn, RUNTIME_MESSAGE_BUS as bo, type RemoteCapability as bp, type RequestOf as bq, type RequestOptions as br, type ResourceContext as bs, type ResourceDefinition as bt, type ResourceKey as bu, type ResourceRegistry as bv, type ResourceSnapshot as bw, type ResourceStatus as bx, type ResponseOf as by, type RpcCallOptions as bz, type PluginReverseDep as c, type StreamSubscription as c0, type StreamTransferDescriptor as c1, type TransferExtractor as c2, type UpgradeDrainResult as c3, UpgradeGateRejectedError as c4, type UpgradeGateState as c5, type UpgradeHandshake as c6, type UpgradeHandshakeResult as c7, type UpgradeIoLease as c8, type UpgradeMode as c9, type UpgradeSession as ca, type ValueParser as cb, WebLoomError as cc, assertCapability as cd, capabilityDescriptor as ce, capabilityKey as cf, defineCapability as cg, isCapability as ch, isCapabilityDescriptor as ci, lifecycleErrorText as cj, createResourceStore as ck, type RuntimeUnitDescriptor as d, type PluginPermission as e, type LifecycleScope as f, type PermissionLease as g, type CreateUpgradeGateOptions as h, type RuntimeCallMessage as i, type ServiceReference as j, type RuntimeEndpointBinding as k, type CapabilityPeer as l, type RuntimeDrainResult as m, type ResourceStoreApi as n, type RuntimeHandle as o, type CapabilityRegistration as p, type CapabilityRegistry as q, type ContextExtensionInput as r, type ContributionAdapter as s, type ContributionAdapterInput as t, type ContributionHandle as u, type CreatePluginHostOptions as v, type HostInspection as w, type PermissionPolicyInput as x, type PermissionPolicyResult as y, type PluginConfigStore as z };
+export { type CapabilityClient as $, type RuntimeUnitAttributesInput as A, type RuntimeUnitAvailabilityInput as B, type CapabilityDescriptor as C, type RuntimeUnitParentScopeInput as D, type RuntimeUnitSnapshot as E, StartupCapabilityError as F, StartupPluginError as G, type HostCapabilityRegistration as H, createCapabilityRegistry as I, createInMemoryPluginConfigStore as J, createPluginHost as K, type LifecycleScopeIdentity as L, invokeCapabilityHandler as M, type Capability as N, type CapabilityDependency as O, type PluginManifest as P, type PluginContribution as Q, type RuntimeKind as R, type ScopedTaskScheduler as S, type PluginConfig as T, type UpgradeGate as U, type PluginContextExtension as V, type WindowApp as W, type PluginSetup as X, type PluginDefinition as Y, type AppLike as Z, type CapabilityBridge as _, type PluginGraph as a, type ResourceDefinition as a$, type CapabilityKind as a0, type DefineLocalCapabilityOptions as a1, type DefineRpcCapabilityOptions as a2, type DefineStreamCapabilityOptions as a3, type DispatchOptions as a4, type EventHandler as a5, type FrameworkErrorCode as a6, type FrameworkErrorContext as a7, type FrameworkErrorPhase as a8, type HandlerCallContext as a9, type PermissionLeaseBinding as aA, type PermissionLeaseBindingExpectation as aB, PermissionLeaseRevokedError as aC, type PluginAttributes as aD, type PluginContext as aE, type PluginIntentCommand as aF, type PluginIntentCommandResult as aG, type PluginIntentController as aH, type PluginIntentCoordinator as aI, type PluginIntentSnapshot as aJ, type PluginIntentSubmissionResult as aK, type PluginLifecycleState as aL, type PluginManifestInput as aM, type PluginStartupMode as aN, type PluginState as aO, type PluginStateKind as aP, type PluginTeardown as aQ, type PluginUnitGraph as aR, type PluginUnitState as aS, type PublishOptions as aT, RESOURCE_OWNER as aU, RESOURCE_REGISTRY as aV, RUNTIME_MESSAGE_BUS as aW, type RemoteCapability as aX, type RequestOf as aY, type RequestOptions as aZ, type ResourceContext as a_, type HandlerOptions as aa, type HandlerOrigin as ab, type HostListener as ac, type ItemOf as ad, LIFECYCLE_ERROR_TEXT as ae, type LifecycleCleanup as af, type LifecycleCleanupIssue as ag, type LifecycleCleanupPhase as ah, type LifecycleDisposeOptions as ai, type LifecycleDisposeResult as aj, type LifecycleResourceHandle as ak, type LifecycleResourceSnapshot as al, type LifecycleScopeKind as am, LifecycleScopeRevokedError as an, type LifecycleScopeState as ao, type LocalCapability as ap, type LocalServiceOf as aq, type Message as ar, type MessageBus as as, type MessageBusSnapshot as at, type MessageHandler as au, type MessageMode as av, type OwnedResourceDefinition as aw, type PeerCapabilityDependency as ax, type PeerScopeView as ay, PermissionDeniedError as az, type RuntimeUnitDependency as b, type ResourceKey as b0, type ResourceRegistry as b1, type ResourceSnapshot as b2, type ResourceStatus as b3, type ResponseOf as b4, type RpcCallOptions as b5, type RpcCapability as b6, type RpcCapabilityBase as b7, type RpcClient as b8, type RpcHandler as b9, type TransferExtractor as bA, type UpgradeDrainResult as bB, UpgradeGateRejectedError as bC, type UpgradeGateState as bD, type UpgradeHandshake as bE, type UpgradeHandshakeResult as bF, type UpgradeIoLease as bG, type UpgradeMode as bH, type UpgradeSession as bI, type ValueParser as bJ, WebLoomError as bK, assertCapability as bL, capabilityDescriptor as bM, capabilityKey as bN, defineCapability as bO, isCapability as bP, isCapabilityDescriptor as bQ, lifecycleErrorText as bR, createResourceStore as bS, type RpcTransferDescriptor as ba, type RuntimeCapabilityDependency as bb, type RuntimeEndpointState as bc, RuntimeInitializationError as bd, type RuntimeLimits as be, type RuntimeServiceSnapshot as bf, type RuntimeSnapshot as bg, type RuntimeStatusListener as bh, type RuntimeStatusSnapshot as bi, RuntimeUnavailableError as bj, type RuntimeUnitDependencyInput as bk, type RuntimeUnitDescriptorInput as bl, type RuntimeUnitImplementationRegistry as bm, SCOPED_TASK_SCHEDULER_CAPABILITY as bn, type ScopedTaskDefinition as bo, type ScopedTaskSnapshot as bp, type SnapshotApplyResult as bq, type StartupCapabilityErrorDetails as br, type StartupPluginErrorDetails as bs, type StreamCapability as bt, type StreamCapabilityBase as bu, type StreamClient as bv, type StreamHandler as bw, type StreamSubscribeOptions as bx, type StreamSubscription as by, type StreamTransferDescriptor as bz, type PluginReverseDep as c, type RuntimeUnitDescriptor as d, type PluginPermission as e, type LifecycleScope as f, type PermissionLease as g, type CreateUpgradeGateOptions as h, type ServiceReference as i, type RuntimeEndpointBinding as j, type CapabilityPeer as k, type RuntimeDrainResult as l, type ResourceStoreApi as m, type RuntimeHandle as n, type CapabilityRegistration as o, type CapabilityRegistry as p, type ContextExtensionInput as q, type ContributionAdapter as r, type ContributionAdapterInput as s, type ContributionHandle as t, type CreatePluginHostOptions as u, type HostInspection as v, type PermissionPolicyInput as w, type PermissionPolicyResult as x, type PluginConfigStore as y, type PluginHost as z };

package/dist/{sharedWorkerHost-BNMUW-8v.d.ts → sharedWorkerHost-DikS18hA.d.ts}

@@ -1,4 +1,4 @@
-import { aQ as LifecycleScopeKind, L as LifecycleScopeIdentity, f as LifecycleScope, aN as LifecycleDisposeResult, bI as RuntimeLimits, P as PluginManifest, ap as PluginSetup, ak as Capability, o as RuntimeHandle, as as CapabilityBridge, W as WindowApp, bp as RemoteCapability, k as RuntimeEndpointBinding, bG as RuntimeEndpointState, m as RuntimeDrainResult, l as CapabilityPeer, at as CapabilityClient, aD as HandlerCallContext, bM as RuntimeStatusSnapshot, bL as RuntimeStatusListener, w as HostInspection, v as CreatePluginHostOptions } from './runtimeTypes-CleHMFaq.js';
+import { am as LifecycleScopeKind, L as LifecycleScopeIdentity, f as LifecycleScope, aj as LifecycleDisposeResult, be as RuntimeLimits, P as PluginManifest, X as PluginSetup, N as Capability, n as RuntimeHandle, _ as CapabilityBridge, W as WindowApp, aX as RemoteCapability, j as RuntimeEndpointBinding, bc as RuntimeEndpointState, k as CapabilityPeer, $ as CapabilityClient, a9 as HandlerCallContext, l as RuntimeDrainResult, bi as RuntimeStatusSnapshot, bh as RuntimeStatusListener, v as HostInspection, u as CreatePluginHostOptions } from './runtimeTypes-50LVQs0h.js';
 
 interface CreateResourceScopeOptions {
     /** 可选固定作用域标识；生产代码通常省略，让实现生成不可复用 ID。 */
@@ -106,6 +106,53 @@ declare function connectSharedWorkerForTesting(options: ConnectSharedWorkerOptio
 /** advanced 装配层取得连接 bridge；普通 RuntimeHandle 不暴露该实现细节。 */
 declare function bridgeForRuntimeHandle(handle: RuntimeHandle): CapabilityBridge;
 
+declare const WEBLOOM_RUNTIME_LOCK_PREFIX: "webloom.runtime";
+/** 浏览器 LockManager 的最小可信接口，便于在 Node/单测中注入替身。 */
+interface RuntimeLockManagerLike {
+    request<T>(name: string, options: {
+        readonly mode: "exclusive";
+        readonly ifAvailable: true;
+    }, callback: (lock: RuntimeLockLike | null) => T | PromiseLike<T>): Promise<T>;
+}
+/** 浏览器授予的临时锁对象；业务不能依赖它保存任何状态。 */
+interface RuntimeLockLike {
+    readonly name: string;
+    readonly mode: "exclusive" | "shared";
+}
+type RuntimeLockFailureCode = "runtime_lock_conflict" | "runtime_lock_unavailable";
+interface RuntimeLockMessages {
+    /** 已有运行实例时显示的用户提示；应用可以替换为自己的产品名称。 */
+    readonly conflict?: string;
+    /** 浏览器没有 Web Locks 时显示的用户提示；应用可以替换为自己的产品名称。 */
+    readonly unavailable?: string;
+}
+/** WebLoom 运行锁失败；code 会通过 Runtime 状态和 wire 错误公开。 */
+declare class RuntimeLockError extends Error {
+    readonly code: RuntimeLockFailureCode;
+    readonly lockName: string;
+    constructor(code: RuntimeLockFailureCode, lockName: string, messages?: RuntimeLockMessages);
+}
+/** 锁名由 runtimeId 固定生成，不允许调用方拼接构建号、版本号或 Worker URL，避免升级后意外得到不同的锁。 */
+interface RuntimeLockOptions {
+    /** 测试可注入 LockManager；生产默认读取 navigator.locks。null 表示明确模拟不支持。 */
+    readonly manager?: RuntimeLockManagerLike | null;
+    /** 应用层中文提示；WebLoom 不绑定任何具体业务产品名称。 */
+    readonly messages?: RuntimeLockMessages;
+}
+interface RuntimeLockHandle {
+    /** 锁名，便于诊断；不会写入 localStorage/IndexedDB/业务桶。 */
+    readonly name: string;
+    /** 取得锁后完成；冲突或 API 缺失时拒绝。 */
+    readonly acquired: Promise<void>;
+    /** 结束 LockManager 回调并等待浏览器确认释放；Worker 终止时也会自动释放。 */
+    release(): Promise<void>;
+}
+/**
+ * testing 入口使用的进程内 LockManager；它只用于单测，不是生产回退。
+ * 生产入口如果 navigator.locks 不存在仍然必须失败。
+ */
+declare function createInMemoryRuntimeLockManager(): RuntimeLockManagerLike;
+
 interface SharedWorkerScopeLike {
     /** SharedWorker 连接事件。 */
     onconnect: ((event: {
@@ -193,6 +240,12 @@ interface StartSharedWorkerAppOptions extends Omit<CreatePluginHostOptions, "run
     readonly peerExposureAllowlist?: readonly RemoteCapability[];
     /** 可信 transport 配额；只能使用默认值或收紧。 */
     readonly limits?: RuntimeLimitsInput;
+    /**
+     * 浏览器唯一运行锁。锁名只由 runtime id 生成，不含构建号、版本号或
+     * Worker URL；生产入口缺少 navigator.locks 时安全失败。manager 仅供
+     * testing 入口注入，不能作为生产回退。
+     */
+    readonly runtimeLock?: RuntimeLockOptions;
 }
 interface StartSharedWorkerAppForTestingOptions extends StartSharedWorkerAppOptions {
     /** testing 入口注入的 SharedWorkerGlobalScope 替身。 */
@@ -222,4 +275,4 @@ declare function startSharedWorkerApp(options: StartSharedWorkerAppOptions): Sha
 /** testing/advanced harness 入口；生产包的 startSharedWorkerApp 不接受 scope 注入。 */
 declare function startSharedWorkerAppForTesting(options: StartSharedWorkerAppForTestingOptions): SharedWorkerApp;
 
-export { type ActivePeerSnapshot as A, type CreateResourceScopeOptions as C, type PeerController as P, type ReceivePortLedger as R, type SharedWorkerApp as S, type RuntimeLimitsInput as a, type RuntimeBudget as b, type RuntimePluginDefinition as c, type PeerExposureOptions as d, type PeerLifecycleEvent as e, type ResourceScopeOptions as f, type StartSharedWorkerAppForTestingOptions as g, type StartSharedWorkerAppOptions as h, bridgeForRuntimeHandle as i, createLifecycleScope as j, createResourceScope as k, type ConnectSharedWorkerOptions as l, type SharedWorkerLike as m, connectSharedWorker as n, type SharedWorkerFactory as o, type SharedWorkerScopeLike as p, connectSharedWorkerForTesting as q, startSharedWorkerAppForTesting as r, startSharedWorkerApp as s };
+export { type CreateResourceScopeOptions as C, type PeerController as P, type ReceivePortLedger as R, type SharedWorkerApp as S, WEBLOOM_RUNTIME_LOCK_PREFIX as W, type RuntimeLimitsInput as a, type RuntimeBudget as b, type RuntimePluginDefinition as c, type PeerExposureOptions as d, type ResourceScopeOptions as e, RuntimeLockError as f, type RuntimeLockFailureCode as g, type RuntimeLockHandle as h, type RuntimeLockManagerLike as i, type RuntimeLockMessages as j, type RuntimeLockOptions as k, type StartSharedWorkerAppForTestingOptions as l, type StartSharedWorkerAppOptions as m, bridgeForRuntimeHandle as n, createLifecycleScope as o, createResourceScope as p, type ConnectSharedWorkerOptions as q, type SharedWorkerLike as r, connectSharedWorker as s, startSharedWorkerApp as t, type SharedWorkerFactory as u, type SharedWorkerScopeLike as v, connectSharedWorkerForTesting as w, createInMemoryRuntimeLockManager as x, startSharedWorkerAppForTesting as y };

package/dist/testing.d.ts

@@ -1,9 +1,9 @@
-import { ab as RuntimeWireMessage, v as CreatePluginHostOptions, A as PluginHost } from './runtimeTypes-CleHMFaq.js';
-export { p as CapabilityRegistration, q as CapabilityRegistry, r as ContextExtensionInput, s as ContributionAdapter, t as ContributionAdapterInput, u as ContributionHandle, H as HostCapabilityRegistration, w as HostInspection, x as PermissionPolicyInput, y as PermissionPolicyResult, z as PluginConfigStore, a7 as RuntimeUnitAttributesInput, a8 as RuntimeUnitAvailabilityInput, a9 as RuntimeUnitParentScopeInput, aa as RuntimeUnitSnapshot, ac as StartupCapabilityError, ad as StartupPluginError, ae as createCapabilityRegistry, af as createInMemoryPluginConfigStore, ag as createPluginHost, ck as createResourceStore, ai as invokeCapabilityHandler } from './runtimeTypes-CleHMFaq.js';
-import { R as RuntimeTransport } from './messagePortServiceTransport-DyNmdgoa.js';
-export { C as CreateCapabilityBridgeOptions, b as CreatePluginIntentControllerOptions, M as MessagePortLike, d as RuntimeReceiveMetadata, e as RuntimeUnitImplementation, f as createCapabilityBridge, g as createMessagePortRuntimeTransport, h as createPluginIntentController, i as createResourceRegistry, l as createRuntimeUnitImplementationRegistry, v as validateTransferables } from './messagePortServiceTransport-DyNmdgoa.js';
-export { C as CreateResourceScopeOptions, f as ResourceScopeOptions, o as SharedWorkerFactory, p as SharedWorkerScopeLike, g as StartSharedWorkerAppForTestingOptions, q as connectSharedWorkerForTesting, j as createLifecycleScope, k as createResourceScope, r as startSharedWorkerAppForTesting } from './sharedWorkerHost-BNMUW-8v.js';
-export { c as createMessageBus } from './messageBus-BDtkjs6y.js';
+import { u as CreatePluginHostOptions, z as PluginHost } from './runtimeTypes-50LVQs0h.js';
+export { o as CapabilityRegistration, p as CapabilityRegistry, q as ContextExtensionInput, r as ContributionAdapter, s as ContributionAdapterInput, t as ContributionHandle, H as HostCapabilityRegistration, v as HostInspection, w as PermissionPolicyInput, x as PermissionPolicyResult, y as PluginConfigStore, A as RuntimeUnitAttributesInput, B as RuntimeUnitAvailabilityInput, D as RuntimeUnitParentScopeInput, E as RuntimeUnitSnapshot, F as StartupCapabilityError, G as StartupPluginError, I as createCapabilityRegistry, J as createInMemoryPluginConfigStore, K as createPluginHost, bS as createResourceStore, M as invokeCapabilityHandler } from './runtimeTypes-50LVQs0h.js';
+import { G as RuntimeWireMessage, a as RuntimeTransport } from './messagePortServiceTransport-B9-24RK6.js';
+export { C as CreateCapabilityBridgeOptions, c as CreatePluginIntentControllerOptions, M as MessagePortLike, w as RuntimeReceiveMetadata, F as RuntimeUnitImplementation, H as createCapabilityBridge, I as createMessagePortRuntimeTransport, J as createPluginIntentController, K as createResourceRegistry, N as createRuntimeUnitImplementationRegistry, Q as validateTransferables } from './messagePortServiceTransport-B9-24RK6.js';
+export { C as CreateResourceScopeOptions, e as ResourceScopeOptions, i as RuntimeLockManagerLike, j as RuntimeLockMessages, k as RuntimeLockOptions, u as SharedWorkerFactory, v as SharedWorkerScopeLike, l as StartSharedWorkerAppForTestingOptions, w as connectSharedWorkerForTesting, x as createInMemoryRuntimeLockManager, o as createLifecycleScope, p as createResourceScope, y as startSharedWorkerAppForTesting } from './sharedWorkerHost-DikS18hA.js';
+export { c as createMessageBus } from './messageBus-DigYfj74.js';
 
 /** 可观察的 transport 发送记录。 */
 interface FakeTransportMessage {

package/dist/testing.js

@@ -1,8 +1,8 @@
-export { startSharedWorkerAppForTesting } from './chunk-RRNUE457.js';
+export { startSharedWorkerAppForTesting } from './chunk-UZAO6ORB.js';
 export { createPluginIntentController } from './chunk-4DSINPZD.js';
-export { connectSharedWorkerForTesting, createCapabilityBridge, createMessagePortRuntimeTransport, validateTransferables } from './chunk-XVD7ALPV.js';
-import { createPluginHost } from './chunk-CKML74MG.js';
-export { StartupCapabilityError, StartupPluginError, createCapabilityRegistry, createInMemoryPluginConfigStore, createLifecycleScope, createMessageBus, createPluginHost, createResourceRegistry, createResourceScope, createResourceStore, createRuntimeUnitImplementationRegistry, invokeCapabilityHandler } from './chunk-CKML74MG.js';
+export { connectSharedWorkerForTesting, createCapabilityBridge, createInMemoryRuntimeLockManager, createMessagePortRuntimeTransport, validateTransferables } from './chunk-YIIDRFHK.js';
+import { createPluginHost } from './chunk-ZP5QYTXX.js';
+export { StartupCapabilityError, StartupPluginError, createCapabilityRegistry, createInMemoryPluginConfigStore, createLifecycleScope, createMessageBus, createPluginHost, createResourceRegistry, createResourceScope, createResourceStore, createRuntimeUnitImplementationRegistry, invokeCapabilityHandler } from './chunk-ZP5QYTXX.js';
 
 // src/testing/fakes.ts
 function createFakeRuntimeTransport() {

package/dist/{windowRuntime-BGl_jfbK.d.ts → windowRuntime-e1Tn6SnN.d.ts}

@@ -1,5 +1,5 @@
-import { v as CreatePluginHostOptions, A as PluginHost, W as WindowApp } from './runtimeTypes-CleHMFaq.js';
-import { c as RuntimePluginDefinition } from './sharedWorkerHost-BNMUW-8v.js';
+import { u as CreatePluginHostOptions, z as PluginHost, W as WindowApp } from './runtimeTypes-50LVQs0h.js';
+import { c as RuntimePluginDefinition } from './sharedWorkerHost-DikS18hA.js';
 
 interface CreateWindowAppOptions extends Omit<CreatePluginHostOptions, "runtime" | "runtimeUnitImplementationRegistry" | "runtimeInstanceId" | "runtimeId" | "capabilityBridge"> {
     /** Window Runtime 逻辑标识。 */

package/docs/api.md

@@ -1,6 +1,6 @@
 # WebLoom v4 API 说明
 
-WebLoom 0.4.2 只支持两个真实 JavaScript realm：`window-main` 和
+WebLoom 0.4.3 只支持两个真实 JavaScript realm：`window-main` 和
 `shared-worker`。`runtime` 是受限的 `RuntimeKind`，不是可自由填写的环境标签；不支持
 的 Runtime 在装配边界 fail closed。
 
@@ -71,6 +71,33 @@ RPC/stream。`ctx.capability(C)` 和 `ctx.optionalCapability(C)` 的参数、返
 
 ## SharedWorker 与双向 peer
 
+### SharedWorker 运行锁
+
+`startSharedWorkerApp()` 在插件注册前会向浏览器 `navigator.locks` 申请一把
+稳定的 exclusive（唯一）运行锁。锁名默认是
+`webloom.runtime:<runtimeId>`；它不包含 buildId（构建标识）、版本号或 Worker
+URL（脚本地址），所以两个都支持 Web Locks 的旧/新构建以及不同 URL 会竞争同一把锁。
+
+这里的“旧/新构建”不包括不认识 Web Locks 的旧包。例如 registry
+`webloom-framework@0.4.2` 的 Worker 不会申请这把锁，`0.4.3` 不能通过
+`LockManager` 发现一个仍存活的 `0.4.2` Worker。首次启用 Web Lock 必须先关闭所有
+旧页面并确认旧 Worker 已退出，再启动新版本；这属于部署冷切换，不是运行时自动接管。
+只有双方都已支持 Web Locks 的后续升级，才可以把下面的
+`runtime_lock_conflict` 当作“请刷新或关闭全部页面”的冲突提示。
+
+锁属于浏览器的 LockManager（浏览器锁管理器），不写 `localStorage`、IndexedDB
+或 Local/S3 业务桶。`ifAvailable`（立即检查）语义意味着第二个物理 Worker
+不会等待或启动插件，而是收到 `runtime_lock_conflict`（运行锁冲突）错误：
+“检测到另一个 WebLoom Runtime 正在运行。请刷新或关闭所有相关页面后重新打开。”
+应用可以通过 `runtimeLock.messages` 把“相关页面”替换为自己的产品名称；WebLoom
+核心不依赖具体业务。
+
+同一稳定 SharedWorker name（Worker 名称）的多个页面仍连接同一个物理 Worker，
+因此只申请一次锁。Worker 终止后浏览器自动释放锁；Web Locks 不可用时使用
+`runtime_lock_unavailable`（运行锁不可用）安全失败，不能退化为 localStorage
+锁或无锁运行。`StartSharedWorkerAppOptions.runtimeLock.manager` 仅供测试注入，
+不是生产回退。
+
 Worker 入口：
 
 ```ts

package/docs/proposals/webloom-v4/requirements.md

@@ -526,7 +526,7 @@ Local 桶是 Window `localStorage`，不换 IndexedDB；先选择/导入桶，
 
 业务异步边界前后及最终写入前仍校验，同步 revoke 先于 drain。初始化事务仍先构建完整 Hold 候选，catalog/CAS 最后可见；恢复记录使用生产 parser。不得为通过 v4 测试放宽非法恢复状态。
 
-旧页面/旧 Worker 与 v4 不混用业务调用。采用 build 隔离的 Worker 产物与名称，不共享旧 wire；新 Worker 不能因新名称就绕过 authority 接管。发现旧最终 I/O lease 未释放时仍进入 recovery-required，不能强抢或清空账本。
+旧页面/旧 Worker 与 v4 不混用业务调用。采用 build 隔离的 Worker 产物与名称，不共享旧 wire；新 Worker 不能因新名称就绕过运行唯一性。首次启用 Web Lock 时，旧版若不申请 Web Lock（例如 registry `0.4.2`）不会被新 Worker 自动发现，必须由部署门禁确认所有旧页面和旧 Worker 已退出后冷切换。只有新旧双方都申请同一稳定锁的后续升级，才用 `runtime_lock_conflict` 提示刷新；不能把它当成首次迁移检测。发现旧最终 I/O lease 未释放时仍进入 recovery-required，不能强抢或清空账本。
 
 产品可在断线后显式重建 Runtime/重开 session/重订阅；不自动重放已经发送的写入、签名或交易。响应丢失走已有 operation/transaction 查询或恢复流程。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webloom-framework",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "通用前端插件生命周期框架",
   "license": "AGPL-3.0-only",
   "repository": {