webloom-framework 0.4.1 → 0.4.3

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { K as Capability, M as CapabilityDependency, N as PluginContribution, O as PluginConfig, Q as PluginContextExtension, R as RuntimeKind, e as PluginPermission, T as PluginSetup, V as PluginDefinition } from './runtimeTypes-DquUCHz-.js';
-export { X as AppLike, Y as CapabilityBridge, Z as CapabilityClient, C as CapabilityDescriptor, _ as CapabilityKind, j as CapabilityPeer, h as CreateUpgradeGateOptions, $ as DefineLocalCapabilityOptions, a0 as DefineRpcCapabilityOptions, a1 as DefineStreamCapabilityOptions, a2 as DispatchOptions, a3 as EventHandler, a4 as FrameworkErrorCode, a5 as FrameworkErrorContext, a6 as FrameworkErrorPhase, a7 as HandlerCallContext, a8 as HandlerOptions, a9 as HandlerOrigin, aa as HostListener, ab as ItemOf, ac as LIFECYCLE_ERROR_TEXT, ad as LifecycleCleanup, ae as LifecycleCleanupIssue, af as LifecycleCleanupPhase, ag as LifecycleDisposeOptions, ah as LifecycleDisposeResult, ai as LifecycleResourceHandle, aj as LifecycleResourceSnapshot, f as LifecycleScope, L as LifecycleScopeIdentity, ak as LifecycleScopeKind, al as LifecycleScopeRevokedError, am as LifecycleScopeState, an as LocalCapability, ao as LocalServiceOf, ap as Message, aq as MessageBus, ar as MessageBusSnapshot, as as MessageHandler, at as MessageMode, au as OwnedResourceDefinition, av as PeerCapabilityDependency, aw as PeerScopeView, ax as PermissionDeniedError, g as PermissionLease, ay as PermissionLeaseBinding, az as PermissionLeaseBindingExpectation, aA as PermissionLeaseRevokedError, aB as PluginAttributes, aC as PluginContext, a as PluginGraph, aD as PluginIntentCommand, aE as PluginIntentCommandResult, aF as PluginIntentController, aG as PluginIntentCoordinator, aH as PluginIntentSnapshot, aI as PluginIntentSubmissionResult, aJ as PluginLifecycleState, P as PluginManifest, aK as PluginManifestInput, c as PluginReverseDep, aL as PluginStartupMode, aM as PluginState, aN as PluginStateKind, aO as PluginTeardown, aP as PluginUnitGraph, aQ as PluginUnitState, aR as PublishOptions, aS as RESOURCE_OWNER, aT as RESOURCE_REGISTRY, aU as RUNTIME_MESSAGE_BUS, aV as RemoteCapability, aW as RequestOf, aX as RequestOptions, aY as ResourceContext, aZ as ResourceDefinition, a_ as ResourceKey, a$ as ResourceRegistry, b0 as ResourceSnapshot, b1 as ResourceStatus, b2 as ResponseOf, b3 as RpcCallOptions, b4 as RpcCapability, b5 as RpcCapabilityBase, b6 as RpcClient, b7 as RpcHandler, b8 as RpcTransferDescriptor, b9 as RuntimeCapabilityDependency, l as RuntimeHandle, ba as RuntimeInitializationError, bb as RuntimeLimits, bc as RuntimeServiceSnapshot, bd as RuntimeSnapshot, be as RuntimeStatusListener, bf as RuntimeStatusSnapshot, bg as RuntimeUnavailableError, b as RuntimeUnitDependency, bh as RuntimeUnitDependencyInput, d as RuntimeUnitDescriptor, bi as RuntimeUnitDescriptorInput, bj as RuntimeUnitImplementationRegistry, bk as SCOPED_TASK_SCHEDULER_CAPABILITY, bl as ScopedTaskDefinition, S as ScopedTaskScheduler, bm as ScopedTaskSnapshot, i as ServiceReference, bn as SnapshotApplyResult, bo as StartupCapabilityErrorDetails, bp as StartupPluginErrorDetails, bq as StreamCapability, br as StreamCapabilityBase, bs as StreamClient, bt as StreamHandler, bu as StreamSubscribeOptions, bv as StreamSubscription, bw as StreamTransferDescriptor, bx as TransferExtractor, by as UpgradeDrainResult, U as UpgradeGate, bz as UpgradeGateRejectedError, bA as UpgradeGateState, bB as UpgradeHandshake, bC as UpgradeHandshakeResult, bD as UpgradeIoLease, bE as UpgradeMode, bF as UpgradeSession, bG as ValueParser, bH as WebLoomError, W as WindowApp, bI as assertCapability, bJ as capabilityDescriptor, bK as capabilityKey, bL as defineCapability, bM as isCapability, bN as isCapabilityDescriptor, bO as lifecycleErrorText } from './runtimeTypes-DquUCHz-.js';
-export { k as ConnectSharedWorkerOptions, P as PeerController, d as PeerExposureOptions, c as RuntimePluginDefinition, S as SharedWorkerApp, l as SharedWorkerLike, g as StartSharedWorkerAppOptions, m as connectSharedWorker, i as createLifecycleScope, j as createResourceScope, s as startSharedWorkerApp } from './sharedWorkerHost-KI7TIGdX.js';
-export { C as CreateWindowAppOptions, a as createWindowApp } from './windowRuntime-BKkLPsAS.js';
-export { c as createMessageBus } from './messageBus-CtrwkjrO.js';
+import { N as Capability, O as CapabilityDependency, Q as PluginContribution, T as PluginConfig, V as PluginContextExtension, R as RuntimeKind, e as PluginPermission, X as PluginSetup, Y as PluginDefinition } from './runtimeTypes-50LVQs0h.js';
+export { Z as AppLike, _ as CapabilityBridge, $ as CapabilityClient, C as CapabilityDescriptor, a0 as CapabilityKind, k as CapabilityPeer, h as CreateUpgradeGateOptions, a1 as DefineLocalCapabilityOptions, a2 as DefineRpcCapabilityOptions, a3 as DefineStreamCapabilityOptions, a4 as DispatchOptions, a5 as EventHandler, a6 as FrameworkErrorCode, a7 as FrameworkErrorContext, a8 as FrameworkErrorPhase, a9 as HandlerCallContext, aa as HandlerOptions, ab as HandlerOrigin, ac as HostListener, ad as ItemOf, ae as LIFECYCLE_ERROR_TEXT, af as LifecycleCleanup, ag as LifecycleCleanupIssue, ah as LifecycleCleanupPhase, ai as LifecycleDisposeOptions, aj as LifecycleDisposeResult, ak as LifecycleResourceHandle, al as LifecycleResourceSnapshot, f as LifecycleScope, L as LifecycleScopeIdentity, am as LifecycleScopeKind, an as LifecycleScopeRevokedError, ao as LifecycleScopeState, ap as LocalCapability, aq as LocalServiceOf, ar as Message, as as MessageBus, at as MessageBusSnapshot, au as MessageHandler, av as MessageMode, aw as OwnedResourceDefinition, ax as PeerCapabilityDependency, ay as PeerScopeView, az as PermissionDeniedError, g as PermissionLease, aA as PermissionLeaseBinding, aB as PermissionLeaseBindingExpectation, aC as PermissionLeaseRevokedError, aD as PluginAttributes, aE as PluginContext, a as PluginGraph, aF as PluginIntentCommand, aG as PluginIntentCommandResult, aH as PluginIntentController, aI as PluginIntentCoordinator, aJ as PluginIntentSnapshot, aK as PluginIntentSubmissionResult, aL as PluginLifecycleState, P as PluginManifest, aM as PluginManifestInput, c as PluginReverseDep, aN as PluginStartupMode, aO as PluginState, aP as PluginStateKind, aQ as PluginTeardown, aR as PluginUnitGraph, aS as PluginUnitState, aT as PublishOptions, aU as RESOURCE_OWNER, aV as RESOURCE_REGISTRY, aW as RUNTIME_MESSAGE_BUS, aX as RemoteCapability, aY as RequestOf, aZ as RequestOptions, a_ as ResourceContext, a$ as ResourceDefinition, b0 as ResourceKey, b1 as ResourceRegistry, b2 as ResourceSnapshot, b3 as ResourceStatus, b4 as ResponseOf, b5 as RpcCallOptions, b6 as RpcCapability, b7 as RpcCapabilityBase, b8 as RpcClient, b9 as RpcHandler, ba as RpcTransferDescriptor, bb as RuntimeCapabilityDependency, l as RuntimeDrainResult, j as RuntimeEndpointBinding, bc as RuntimeEndpointState, n as RuntimeHandle, bd as RuntimeInitializationError, be as RuntimeLimits, bf as RuntimeServiceSnapshot, bg as RuntimeSnapshot, bh as RuntimeStatusListener, bi as RuntimeStatusSnapshot, bj as RuntimeUnavailableError, b as RuntimeUnitDependency, bk as RuntimeUnitDependencyInput, d as RuntimeUnitDescriptor, bl as RuntimeUnitDescriptorInput, bm as RuntimeUnitImplementationRegistry, bn as SCOPED_TASK_SCHEDULER_CAPABILITY, bo as ScopedTaskDefinition, S as ScopedTaskScheduler, bp as ScopedTaskSnapshot, i as ServiceReference, bq as SnapshotApplyResult, br as StartupCapabilityErrorDetails, bs as StartupPluginErrorDetails, bt as StreamCapability, bu as StreamCapabilityBase, bv as StreamClient, bw as StreamHandler, bx as StreamSubscribeOptions, by as StreamSubscription, bz as StreamTransferDescriptor, bA as TransferExtractor, bB as UpgradeDrainResult, U as UpgradeGate, bC as UpgradeGateRejectedError, bD as UpgradeGateState, bE as UpgradeHandshake, bF as UpgradeHandshakeResult, bG as UpgradeIoLease, bH as UpgradeMode, bI as UpgradeSession, bJ as ValueParser, bK as WebLoomError, W as WindowApp, bL as assertCapability, bM as capabilityDescriptor, bN as capabilityKey, bO as defineCapability, bP as isCapability, bQ as isCapabilityDescriptor, bR as lifecycleErrorText } from './runtimeTypes-50LVQs0h.js';
+export { q as ConnectSharedWorkerOptions, P as PeerController, d as PeerExposureOptions, f as RuntimeLockError, g as RuntimeLockFailureCode, h as RuntimeLockHandle, i as RuntimeLockManagerLike, j as RuntimeLockMessages, k as RuntimeLockOptions, c as RuntimePluginDefinition, S as SharedWorkerApp, r as SharedWorkerLike, m as StartSharedWorkerAppOptions, W as WEBLOOM_RUNTIME_LOCK_PREFIX, s as connectSharedWorker, o as createLifecycleScope, p as createResourceScope, t as startSharedWorkerApp } from './sharedWorkerHost-DikS18hA.js';
+export { C as CreateWindowAppOptions, a as createWindowApp } from './windowRuntime-e1Tn6SnN.js';
+export { c as createMessageBus } from './messageBus-DigYfj74.js';
 
 /** 普通插件定义选项；插件声明只使用 typed capability 与单一启动策略。 */
 interface DefinePluginOptions<TProvides extends readonly Capability[] = readonly Capability[], TDependencies extends readonly CapabilityDependency[] = readonly CapabilityDependency[], TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> {

package/dist/index.js

@@ -1,7 +1,7 @@
-export { startSharedWorkerApp } from './chunk-SX46RHDI.js';
-export { connectSharedWorker } from './chunk-ANA6GBEI.js';
-import { capabilityDescriptor } from './chunk-HJKPKWI7.js';
-export { LIFECYCLE_ERROR_TEXT, LifecycleScopeRevokedError, PermissionDeniedError, PermissionLeaseRevokedError, RESOURCE_OWNER, RESOURCE_REGISTRY, RuntimeInitializationError, RuntimeUnavailableError, SCOPED_TASK_SCHEDULER_CAPABILITY, UpgradeGateRejectedError, WebLoomError, assertCapability, capabilityDescriptor, capabilityKey, createLifecycleScope, createMessageBus, createResourceScope, createWindowApp, defineCapability, isCapability, isCapabilityDescriptor, lifecycleErrorText } from './chunk-HJKPKWI7.js';
+export { startSharedWorkerApp } from './chunk-UZAO6ORB.js';
+export { RuntimeLockError, WEBLOOM_RUNTIME_LOCK_PREFIX, connectSharedWorker } from './chunk-YIIDRFHK.js';
+import { capabilityDescriptor } from './chunk-ZP5QYTXX.js';
+export { LIFECYCLE_ERROR_TEXT, LifecycleScopeRevokedError, PermissionDeniedError, PermissionLeaseRevokedError, RESOURCE_OWNER, RESOURCE_REGISTRY, RuntimeInitializationError, RuntimeUnavailableError, SCOPED_TASK_SCHEDULER_CAPABILITY, UpgradeGateRejectedError, WebLoomError, assertCapability, capabilityDescriptor, capabilityKey, createLifecycleScope, createMessageBus, createResourceScope, createWindowApp, defineCapability, isCapability, isCapabilityDescriptor, lifecycleErrorText } from './chunk-ZP5QYTXX.js';
 
 // src/contracts/messageBus.ts
 var RUNTIME_MESSAGE_BUS = "webloom.messageBus";

package/dist/{messageBus-CtrwkjrO.d.ts → messageBus-DigYfj74.d.ts}

@@ -1,4 +1,4 @@
-import { aq as MessageBus } from './runtimeTypes-DquUCHz-.js';
+import { as as MessageBus } from './runtimeTypes-50LVQs0h.js';
 
 declare function createMessageBus(): MessageBus;
 

package/dist/{messagePortServiceTransport-BYprNvQY.d.ts → messagePortServiceTransport-B9-24RK6.d.ts}

@@ -1,5 +1,5 @@
-import { T as PluginSetup, K as Capability, bj as RuntimeUnitImplementationRegistry, aH as PluginIntentSnapshot, aF as PluginIntentController, a$ as ResourceRegistry, aZ as ResourceDefinition, bd as RuntimeSnapshot, R as RuntimeKind, aN as PluginStateKind, Y as CapabilityBridge } from './runtimeTypes-DquUCHz-.js';
-import { R as ReceivePortLedger, a as RuntimeLimitsInput, b as RuntimeBudget } from './sharedWorkerHost-KI7TIGdX.js';
+import { X as PluginSetup, N as Capability, bm as RuntimeUnitImplementationRegistry, aJ as PluginIntentSnapshot, aH as PluginIntentController, b1 as ResourceRegistry, a$ as ResourceDefinition, bg as RuntimeSnapshot, j as RuntimeEndpointBinding, R as RuntimeKind, aP as PluginStateKind, bc as RuntimeEndpointState, l as RuntimeDrainResult, _ as CapabilityBridge } from './runtimeTypes-50LVQs0h.js';
+import { R as ReceivePortLedger, a as RuntimeLimitsInput, b as RuntimeBudget } from './sharedWorkerHost-DikS18hA.js';
 
 interface RuntimeUnitImplementation {
     /** 产品标识。 */
@@ -51,6 +51,10 @@ 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;
@@ -65,12 +69,15 @@ interface RuntimeSnapshotUnit {
 }
 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;
     /** 脱敏消息。 */
@@ -87,6 +94,8 @@ interface RuntimeCallMessage {
     readonly type: typeof RUNTIME_CALL_TYPE;
     /** 协议版本。 */
     readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
+    /** 发起调用的物理 endpoint 绑定。 */
+    readonly binding?: RuntimeSessionBinding;
     /** 方向内唯一 call id。 */
     readonly callId: string;
     /** capability 标识。 */
@@ -113,6 +122,8 @@ interface RuntimeUnaryResultMessage {
     readonly type: typeof RUNTIME_RESULT_TYPE;
     /** 协议版本。 */
     readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
+    /** 发送结果的物理 endpoint 绑定。 */
+    readonly binding?: RuntimeSessionBinding;
     /** call id。 */
     readonly callId: string;
     /** exposure 身份。 */
@@ -125,6 +136,8 @@ interface RuntimeStreamReadyMessage {
     readonly type: typeof RUNTIME_RESULT_TYPE;
     /** 协议版本。 */
     readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
+    /** 发送结果的物理 endpoint 绑定。 */
+    readonly binding?: RuntimeSessionBinding;
     /** call id。 */
     readonly callId: string;
     /** exposure 身份。 */
@@ -137,6 +150,8 @@ interface RuntimeStreamDoneMessage {
     readonly type: typeof RUNTIME_RESULT_TYPE;
     /** 协议版本。 */
     readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
+    /** 发送结果的物理 endpoint 绑定。 */
+    readonly binding?: RuntimeSessionBinding;
     /** call id。 */
     readonly callId: string;
     /** exposure 身份。 */
@@ -150,6 +165,8 @@ 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 身份。 */
@@ -167,6 +184,8 @@ interface RuntimeCancelMessage {
     readonly type: typeof RUNTIME_CANCEL_TYPE;
     /** 协议版本。 */
     readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
+    /** 发送取消的物理 endpoint 绑定。 */
+    readonly binding?: RuntimeSessionBinding;
     /** call id。 */
     readonly callId: string;
     /** exposure 身份。 */
@@ -177,6 +196,8 @@ 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 身份。 */
@@ -191,6 +212,8 @@ 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 身份。 */
@@ -198,7 +221,35 @@ interface RuntimeCreditMessage {
     /** 新增 credit。 */
     readonly count: number;
 }
-type RuntimeWireMessage = RuntimeSnapshotMessage | RuntimeErrorMessage | RuntimeCallMessage | RuntimeResultMessage | RuntimeErrorResponseMessage | RuntimeCancelMessage | RuntimeNextMessage | RuntimeCreditMessage;
+/** 请求对端先同步 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;
@@ -208,6 +259,40 @@ interface RuntimeMessageCodec {
 declare function createRuntimeMessageCodec(): RuntimeMessageCodec;
 declare function isRuntimeSnapshot(value: RuntimeWireMessage): value is RuntimeSnapshotMessage;
 
+/** 一个需要等待真实执行槽结束的框架参与者。 */
+interface RuntimeDrainParticipant {
+    /** 等待该参与者自己的真实执行槽结束。 */
+    readonly drain: () => Promise<void>;
+    /** deadline 到达时报告仍未结束的真实执行槽数量。 */
+    readonly pending: () => number;
+}
+interface RuntimeEndpointSession {
+    /** 本端由框架生成、不可复用的 endpoint 身份。 */
+    readonly binding: RuntimeEndpointBinding;
+    /** 已由对端首条合法框架消息建立的身份；尚未建立时为空。 */
+    readonly remoteBinding?: RuntimeEndpointBinding;
+    /** active -> closing -> closed。 */
+    readonly state: RuntimeEndpointState;
+    /** 最近一次同步关闭原因；只用于本地诊断。 */
+    readonly closeReason?: string;
+    /** 本端允许的最大 drain 时间；远端只能进一步收紧，不能扩大。 */
+    readonly maxDrainTimeoutMs: number;
+    /** 精确比较并建立对端 binding；不接受后续替换。 */
+    acceptRemoteBinding(binding: unknown): boolean;
+    /** 同步停止准入、触发撤权和 abort；幂等。 */
+    beginClose(reason?: string): void;
+    /** 等待全部参与者排空，始终受 bounded deadline 限制。 */
+    drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
+    /** 物理 transport 即将关闭时标记终态；幂等。 */
+    close(): void;
+    /** 注册同步关闭回调。 */
+    onBeginClose(listener: (reason: string) => void): () => void;
+    /** 注册物理关闭回调。 */
+    onClosed(listener: () => void): () => void;
+    /** 注册一个真实执行排空参与者。 */
+    registerDrainParticipant(participant: RuntimeDrainParticipant): () => void;
+}
+
 interface RuntimeReceiveMetadata {
     /** 本次 MessageEvent 实际携带的业务 MessagePort；仅 transport 本地使用。 */
     readonly ports?: readonly MessagePort[];
@@ -239,6 +324,12 @@ interface CreateCapabilityBridgeOptions {
     readonly limits?: RuntimeLimitsInput;
     /** 可选的 Runtime 方向共享计数器。 */
     readonly budget?: RuntimeBudget;
+    /** 当前物理 endpoint 的框架 binding；省略时由 bridge 生成。 */
+    readonly binding?: RuntimeEndpointBinding;
+    /** 与反向 provider 共用的 endpoint session。 */
+    readonly session?: RuntimeEndpointSession;
+    /** 关闭握手默认 drain deadline。 */
+    readonly drainTimeoutMs?: number;
 }
 /** 创建按 peer 绑定、可撤销且支持 typed stream 的 bridge。 */
 declare function createCapabilityBridge(options: CreateCapabilityBridgeOptions): CapabilityBridge & {
@@ -261,4 +352,4 @@ declare function createMessagePortRuntimeTransport(port: MessagePortLike, option
     readonly limits?: RuntimeLimitsInput;
 }): RuntimeTransport;
 
-export { createCapabilityBridge as A, createMessagePortRuntimeTransport as B, type CreateCapabilityBridgeOptions as C, createPluginIntentController as D, createResourceRegistry as E, createRuntimeMessageCodec as F, createRuntimeUnitImplementationRegistry as G, isRuntimeSnapshot as H, registerOwnedResource as I, validateTransferables as J, type MessagePortLike as M, type RuntimeCallMessage as R, type RuntimeTransport as a, type CreatePluginIntentControllerOptions as b, RUNTIME_CALL_TYPE as c, RUNTIME_CANCEL_TYPE as d, RUNTIME_CREDIT_TYPE as e, RUNTIME_ERROR_MESSAGE_TYPE as f, RUNTIME_ERROR_TYPE as g, RUNTIME_NEXT_TYPE as h, RUNTIME_PROTOCOL_VERSION as i, RUNTIME_RESULT_TYPE as j, RUNTIME_SNAPSHOT_TYPE as k, type RuntimeCancelMessage as l, type RuntimeCreditMessage as m, type RuntimeErrorMessage as n, type RuntimeErrorResponseMessage as o, type RuntimeMessageCodec as p, type RuntimeNextMessage as q, type RuntimeReceiveMetadata as r, type RuntimeResultMessage as s, type RuntimeSnapshotMessage as t, type RuntimeSnapshotUnit as u, type RuntimeStreamDoneMessage as v, type RuntimeStreamReadyMessage as w, type RuntimeUnaryResultMessage as x, type RuntimeUnitImplementation as y, type RuntimeWireMessage as z };
+export { type RuntimeSnapshotUnit as A, type RuntimeStreamDoneMessage as B, type CreateCapabilityBridgeOptions as C, type RuntimeStreamReadyMessage as D, type RuntimeUnaryResultMessage as E, type RuntimeUnitImplementation as F, type RuntimeWireMessage as G, createCapabilityBridge as H, createMessagePortRuntimeTransport as I, createPluginIntentController as J, createResourceRegistry as K, createRuntimeMessageCodec as L, type MessagePortLike as M, createRuntimeUnitImplementationRegistry as N, isRuntimeSnapshot as O, registerOwnedResource as P, validateTransferables as Q, type RuntimeCallMessage as R, type RuntimeTransport as a, type RuntimeEndpointSession as b, type CreatePluginIntentControllerOptions as c, RUNTIME_CALL_TYPE as d, RUNTIME_CANCEL_TYPE as e, RUNTIME_CLOSE_ACK_TYPE as f, RUNTIME_CLOSE_TYPE as g, RUNTIME_CREDIT_TYPE as h, RUNTIME_ERROR_MESSAGE_TYPE as i, RUNTIME_ERROR_TYPE as j, RUNTIME_NEXT_TYPE as k, RUNTIME_PROTOCOL_VERSION as l, RUNTIME_RESULT_TYPE as m, RUNTIME_SNAPSHOT_TYPE as n, type RuntimeCancelMessage as o, type RuntimeCloseAckMessage as p, type RuntimeCloseMessage as q, type RuntimeCreditMessage as r, type RuntimeErrorMessage as s, type RuntimeErrorResponseMessage as t, type RuntimeMessageCodec as u, type RuntimeNextMessage as v, type RuntimeReceiveMetadata as w, type RuntimeResultMessage as x, type RuntimeSessionBinding as y, type RuntimeSnapshotMessage as z };

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { W as WindowApp, l as RuntimeHandle, K as Capability, Z as CapabilityClient, X as AppLike, aM as PluginState, a as PluginGraph, c as PluginReverseDep, aI as PluginIntentSubmissionResult, P as PluginManifest, C as CapabilityDescriptor, k as ResourceStoreApi, b0 as ResourceSnapshot } from './runtimeTypes-DquUCHz-.js';
+import { W as WindowApp, n as RuntimeHandle, N as Capability, $ as CapabilityClient, Z as AppLike, aO as PluginState, a as PluginGraph, c as PluginReverseDep, aK as PluginIntentSubmissionResult, P as PluginManifest, C as CapabilityDescriptor, m as ResourceStoreApi, b2 as ResourceSnapshot } from './runtimeTypes-50LVQs0h.js';
 
 type WebLoomApp = WindowApp | RuntimeHandle;
 declare const WebLoomContext: react.Context<WebLoomApp | undefined>;

package/dist/react.js

@@ -1,4 +1,4 @@
-import { hostForWindowApp } from './chunk-HJKPKWI7.js';
+import { hostForWindowApp } from './chunk-ZP5QYTXX.js';
 import { createContext, useContext, useCallback, useSyncExternalStore, useMemo, useRef } from 'react';
 import { jsx } from 'react/jsx-runtime';
 

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

@@ -393,6 +393,32 @@ type LifecycleScopeState = "active" | "stopping" | "stopped";
 type RuntimeKind = "window-main" | "shared-worker";
 /** 权限动作名称。 */
 type PluginPermission = string;
+/**
+ * WebLoom 为每条物理 Runtime endpoint 生成的连接绑定。
+ *
+ * `runtimeInstanceId` 标识一次 Runtime 启动，`connectionId` 标识该启动内
+ * 的一条物理连接。两者只能由框架创建并且不得复用；它不是产品领域的
+ * lease、owner 或领域 generation，也不能由请求载荷覆盖。
+ */
+interface RuntimeEndpointBinding {
+    /** 产生此 endpoint 的 Runtime 启动身份。 */
+    readonly runtimeInstanceId: string;
+    /** 此 Runtime 启动内不可复用的物理连接身份。 */
+    readonly connectionId: string;
+}
+/** Runtime endpoint 的通用关闭阶段。 */
+type RuntimeEndpointState = "active" | "closing" | "closed";
+/** 一次 bounded drain 的结果；超时不伪装成已经排空。 */
+interface RuntimeDrainResult {
+    /** 关闭阶段结束时的状态。 */
+    readonly state: RuntimeEndpointState;
+    /** 是否在 deadline 前等待到所有框架执行槽结束。 */
+    readonly drained: boolean;
+    /** 是否达到 bounded deadline。 */
+    readonly timedOut: boolean;
+    /** deadline 到达时仍未完成的真实执行槽数量。 */
+    readonly pendingExecutions: number;
+}
 /** 一个作用域的不可替换身份绑定。 */
 interface LifecycleScopeIdentity<TAttributes extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
     /** 作用域唯一标识。 */
@@ -571,6 +597,8 @@ interface RuntimeServiceSnapshot {
 interface RuntimeSnapshot {
     /** 固定协议版本。 */
     protocolVersion: string;
+    /** 当前物理 endpoint 的框架绑定；旧兼容快照可以省略，收到后由 transport 补齐。 */
+    readonly binding?: RuntimeEndpointBinding;
     /** Runtime 逻辑标识。 */
     runtimeId: string;
     /** 真实 Runtime 类型。 */
@@ -654,7 +682,7 @@ type SnapshotApplyResult = {
     receivedRevision?: number;
 };
 /** 框架结构化错误码。 */
-type FrameworkErrorCode = "protocol_mismatch" | "invalid_snapshot" | "capability_unavailable" | "contract_mismatch" | "request_validation_failed" | "response_validation_failed" | "request_clone_failed" | "response_clone_failed" | "transfer_invalid" | "handler_failed" | "call_timeout" | "request_cancelled" | "service_revoked" | "service_stale" | "transport_unavailable" | "runtime_initialization_failed" | "stream_overflow" | "resource_limit_exceeded" | "permission_denied" | (string & {});
+type FrameworkErrorCode = "protocol_mismatch" | "invalid_snapshot" | "capability_unavailable" | "contract_mismatch" | "request_validation_failed" | "response_validation_failed" | "request_clone_failed" | "response_clone_failed" | "transfer_invalid" | "handler_failed" | "call_timeout" | "request_cancelled" | "service_revoked" | "service_stale" | "transport_unavailable" | "runtime_initialization_failed" | "stream_overflow" | "resource_limit_exceeded" | "permission_denied" | "session_binding_mismatch" | (string & {});
 /** 框架错误阶段。 */
 type FrameworkErrorPhase = "validate" | "wait" | "dispatch" | "execute" | "receive" | "dispose";
 /** 脱敏错误上下文。 */
@@ -1024,6 +1052,8 @@ interface ServiceReference {
 interface CapabilityPeer {
     /** 对端连接的不可复用身份。 */
     readonly peerId: string;
+    /** 当前物理 endpoint 的框架 binding；不包含产品领域授权。 */
+    readonly binding: RuntimeEndpointBinding;
     /** 已观察到的对端 Runtime 类型；首个快照前为空。 */
     readonly runtime?: RuntimeKind;
     /** 已观察到的对端 Runtime 一次启动身份；首个快照前为空。 */
@@ -1068,9 +1098,14 @@ interface CapabilityBridge {
     readonly runtimeInstanceId?: string;
     /** 当前已观察到的对端 Runtime 类型；快照到达前为空。 */
     readonly runtimeKind?: RuntimeKind;
+    /** 本端物理 endpoint 的框架 binding。 */
+    readonly binding: RuntimeEndpointBinding;
+    /** 当前 endpoint 生命周期；与远端 Runtime state 独立。 */
+    readonly endpointState: RuntimeEndpointState;
     /** 取惰性 typed client；没有服务时不在此处同步失败。 */
     getClient<C extends RemoteCapability>(capability: C, scope?: LifecycleScope): CapabilityClient<C>;
     /** 应用一个完整对端目录。 */
+    /** 应用一个远端完整目录；生产 wire 带 binding，旧 testing fixture 可省略。 */
     applySnapshot(snapshot: RuntimeSnapshot): SnapshotApplyResult;
     /** 同步撤销全部旧代理。 */
     invalidate(reason?: string): void;
@@ -1078,6 +1113,10 @@ interface CapabilityBridge {
     disconnect(reason?: string): void;
     /** 永久销毁 bridge。 */
     dispose(reason?: string): void;
+    /** 同步停止新调用、撤销代理并 abort 已进入调用；幂等。 */
+    beginClose(reason?: string): void;
+    /** 等待本端与对端框架执行槽 bounded drain；超时不伪装成功。 */
+    drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
     /** 订阅目录/连接状态变化。 */
     subscribe(listener: () => void): () => void;
     /** 当前已发布的完整服务引用。 */
@@ -1093,6 +1132,8 @@ interface HandlerCallContext {
     readonly operationId?: string;
     /** 当前服务 exposure 身份。 */
     readonly reference: ServiceReference;
+    /** 远程调用对应的框架 endpoint binding；同 realm 调用没有物理 endpoint。 */
+    readonly binding?: RuntimeEndpointBinding;
     /** 调用来源。 */
     readonly origin: HandlerOrigin;
     /** 远程调用的框架绑定对端；local 调用必为 undefined。 */
@@ -1581,8 +1622,12 @@ interface RuntimeStatusSnapshot extends Omit<RuntimeSnapshot, "protocolVersion"
     readonly protocolVersion: string;
     /** Runtime 当前状态。 */
     readonly state: RuntimeAppState;
+    /** 当前观察到的远端物理 endpoint binding；本地 WindowApp 不填写。 */
+    readonly binding?: RuntimeEndpointBinding;
     /** 脱敏 Runtime 错误。 */
     readonly error?: string;
+    /** 结构化运行错误码，例如 runtime_lock_conflict。 */
+    readonly errorCode?: string;
 }
 type RuntimeStatusListener = (snapshot: RuntimeStatusSnapshot) => void;
 interface AppLike {
@@ -1612,10 +1657,18 @@ interface WindowApp extends AppLike {
 }
 interface RuntimeHandle extends AppLike {
     readonly runtimeKind: "shared-worker";
+    /** 当前 Window ↔ Worker 物理 endpoint 的不可复用框架 binding。 */
+    readonly binding: RuntimeEndpointBinding;
+    /** 当前物理连接生命周期；不等同于远端 Runtime state。 */
+    readonly endpointState: RuntimeEndpointState;
     /** 获取远程 typed RPC/stream capability；代理构造不等待 Worker。 */
     capability<C extends RemoteCapability>(capability: C): CapabilityClient<C>;
     /** 当前已观察到的 remote capability。 */
     optionalCapability<C extends RemoteCapability>(capability: C): CapabilityClient<C> | undefined;
+    /** 同步停止新调用与本端反向 handler admission。 */
+    beginClose(reason?: string): void;
+    /** 等待本端及远端框架执行槽的 bounded drain。 */
+    drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
 }
 declare class RuntimeInitializationError extends Error {
     readonly code: "runtime_initialization_failed";
@@ -1637,4 +1690,4 @@ declare class RuntimeUnavailableError extends Error {
     constructor(message?: string);
 }
 
-export { type DefineLocalCapabilityOptions as $, type RuntimeUnitParentScopeInput as A, type RuntimeUnitSnapshot as B, type CapabilityDescriptor as C, StartupCapabilityError as D, StartupPluginError as E, createCapabilityRegistry as F, createInMemoryPluginConfigStore as G, type HostCapabilityRegistration as H, createPluginHost as I, invokeCapabilityHandler as J, type Capability as K, type LifecycleScopeIdentity as L, type CapabilityDependency as M, type PluginContribution as N, type PluginConfig as O, type PluginManifest as P, type PluginContextExtension as Q, type RuntimeKind as R, type ScopedTaskScheduler as S, type PluginSetup as T, type UpgradeGate as U, type PluginDefinition as V, type WindowApp as W, type AppLike as X, type CapabilityBridge as Y, type CapabilityClient as Z, type CapabilityKind as _, type PluginGraph as a, type ResourceRegistry as a$, type DefineRpcCapabilityOptions as a0, type DefineStreamCapabilityOptions as a1, type DispatchOptions as a2, type EventHandler as a3, type FrameworkErrorCode as a4, type FrameworkErrorContext as a5, type FrameworkErrorPhase as a6, type HandlerCallContext as a7, type HandlerOptions as a8, type HandlerOrigin as a9, PermissionLeaseRevokedError as aA, type PluginAttributes as aB, type PluginContext as aC, type PluginIntentCommand as aD, type PluginIntentCommandResult as aE, type PluginIntentController as aF, type PluginIntentCoordinator as aG, type PluginIntentSnapshot as aH, type PluginIntentSubmissionResult as aI, type PluginLifecycleState as aJ, type PluginManifestInput as aK, type PluginStartupMode as aL, type PluginState as aM, type PluginStateKind as aN, type PluginTeardown as aO, type PluginUnitGraph as aP, type PluginUnitState as aQ, type PublishOptions as aR, RESOURCE_OWNER as aS, RESOURCE_REGISTRY as aT, RUNTIME_MESSAGE_BUS as aU, type RemoteCapability as aV, type RequestOf as aW, type RequestOptions as aX, type ResourceContext as aY, type ResourceDefinition as aZ, type ResourceKey as a_, type HostListener as aa, type ItemOf as ab, LIFECYCLE_ERROR_TEXT as ac, type LifecycleCleanup as ad, type LifecycleCleanupIssue as ae, type LifecycleCleanupPhase as af, type LifecycleDisposeOptions as ag, type LifecycleDisposeResult as ah, type LifecycleResourceHandle as ai, type LifecycleResourceSnapshot as aj, type LifecycleScopeKind as ak, LifecycleScopeRevokedError as al, type LifecycleScopeState as am, type LocalCapability as an, type LocalServiceOf as ao, type Message as ap, type MessageBus as aq, type MessageBusSnapshot as ar, type MessageHandler as as, type MessageMode as at, type OwnedResourceDefinition as au, type PeerCapabilityDependency as av, type PeerScopeView as aw, PermissionDeniedError as ax, type PermissionLeaseBinding as ay, type PermissionLeaseBindingExpectation as az, type RuntimeUnitDependency as b, type ResourceSnapshot as b0, type ResourceStatus as b1, type ResponseOf as b2, type RpcCallOptions as b3, type RpcCapability as b4, type RpcCapabilityBase as b5, type RpcClient as b6, type RpcHandler as b7, type RpcTransferDescriptor as b8, type RuntimeCapabilityDependency as b9, type UpgradeGateState as bA, type UpgradeHandshake as bB, type UpgradeHandshakeResult as bC, type UpgradeIoLease as bD, type UpgradeMode as bE, type UpgradeSession as bF, type ValueParser as bG, WebLoomError as bH, assertCapability as bI, capabilityDescriptor as bJ, capabilityKey as bK, defineCapability as bL, isCapability as bM, isCapabilityDescriptor as bN, lifecycleErrorText as bO, createResourceStore as bP, RuntimeInitializationError as ba, type RuntimeLimits as bb, type RuntimeServiceSnapshot as bc, type RuntimeSnapshot as bd, type RuntimeStatusListener as be, type RuntimeStatusSnapshot as bf, RuntimeUnavailableError as bg, type RuntimeUnitDependencyInput as bh, type RuntimeUnitDescriptorInput as bi, type RuntimeUnitImplementationRegistry as bj, SCOPED_TASK_SCHEDULER_CAPABILITY as bk, type ScopedTaskDefinition as bl, type ScopedTaskSnapshot as bm, type SnapshotApplyResult as bn, type StartupCapabilityErrorDetails as bo, type StartupPluginErrorDetails as bp, type StreamCapability as bq, type StreamCapabilityBase as br, type StreamClient as bs, type StreamHandler as bt, type StreamSubscribeOptions as bu, type StreamSubscription as bv, type StreamTransferDescriptor as bw, type TransferExtractor as bx, type UpgradeDrainResult as by, UpgradeGateRejectedError 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 CapabilityPeer as j, type ResourceStoreApi as k, type RuntimeHandle as l, type CapabilityRegistration as m, type CapabilityRegistry as n, type ContextExtensionInput as o, type ContributionAdapter as p, type ContributionAdapterInput as q, type ContributionHandle as r, type CreatePluginHostOptions as s, type HostInspection as t, type PermissionPolicyInput as u, type PermissionPolicyResult as v, type PluginConfigStore as w, type PluginHost as x, type RuntimeUnitAttributesInput as y, type RuntimeUnitAvailabilityInput 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-KI7TIGdX.d.ts → sharedWorkerHost-DikS18hA.d.ts}

@@ -1,4 +1,4 @@
-import { ak as LifecycleScopeKind, L as LifecycleScopeIdentity, f as LifecycleScope, ah as LifecycleDisposeResult, bb as RuntimeLimits, P as PluginManifest, T as PluginSetup, K as Capability, l as RuntimeHandle, Y as CapabilityBridge, W as WindowApp, aV as RemoteCapability, j as CapabilityPeer, Z as CapabilityClient, a7 as HandlerCallContext, bf as RuntimeStatusSnapshot, be as RuntimeStatusListener, t as HostInspection, s as CreatePluginHostOptions } from './runtimeTypes-DquUCHz-.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: {
@@ -127,6 +174,10 @@ interface PeerExposureOptions {
 interface PeerController {
     /** peer 标识。 */
     readonly peerId: string;
+    /** 当前物理 endpoint 的不可复用框架 binding。 */
+    readonly binding: RuntimeEndpointBinding;
+    /** 当前物理 endpoint 的关闭阶段。 */
+    readonly endpointState: RuntimeEndpointState;
     /** 已观察到的页面 Runtime 实例；首个页面快照前为空。 */
     readonly runtimeInstanceId?: string;
     /** 对端 Window Runtime 类型。 */
@@ -150,9 +201,32 @@ interface PeerController {
     };
     /** 断开此 peer，不影响其它页面。 */
     disconnect(reason?: string): void;
+    /** 同步停止新调用与暴露；后续由 drain/close 完成异步收尾。 */
+    beginClose(reason?: string): void;
+    /** 等待该 peer endpoint 的 bounded drain。 */
+    drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
     /** peer 诊断。 */
     inspect(): Readonly<Record<string, unknown>>;
 }
+/** 可信 Host 可观察的 peer 生命周期事件；不包含 owner/lease 等领域字段。 */
+interface PeerLifecycleEvent {
+    /** active 建立、handoff 通知或关闭阶段。 */
+    readonly event: "active" | "handoff" | "closing" | "closed";
+    /** peer 物理连接的 opaque 标识。 */
+    readonly peerId: string;
+    /** 当前物理 endpoint 的框架 binding。 */
+    readonly binding: RuntimeEndpointBinding;
+    /** endpoint 的框架生命周期。 */
+    readonly state: RuntimeEndpointState;
+    /** closed 事件的真实 bounded drain 结果。 */
+    readonly drain?: RuntimeDrainResult;
+    /** 可信 Host 提供的 handoff 修订；WebLoom 不解释或选择 owner。 */
+    readonly handoffRevision?: number;
+}
+/** 可信 Host 查询到的 active peer 只读投影。 */
+type ActivePeerSnapshot = Omit<PeerLifecycleEvent, "event" | "drain" | "handoffRevision"> & {
+    readonly event: "active";
+};
 interface StartSharedWorkerAppOptions extends Omit<CreatePluginHostOptions, "runtime" | "runtimeUnitImplementationRegistry" | "runtimeId" | "runtimeInstanceId"> {
     /** Worker Runtime 逻辑标识。 */
     readonly id: string;
@@ -166,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 替身。 */
@@ -182,6 +262,12 @@ interface SharedWorkerApp {
     state(): RuntimeStatusSnapshot;
     subscribe(listener: RuntimeStatusListener): () => void;
     inspect(): HostInspection;
+    /** 只读查询当前仍处于 active 的物理 peer。 */
+    activePeers(): readonly ActivePeerSnapshot[];
+    /** 订阅 Host 可见的 peer active/closing/closed/handoff 事件。 */
+    subscribePeerLifecycle(listener: (event: PeerLifecycleEvent) => void): () => void;
+    /** 可信领域在完成自己的 owner/session 交接后报告 handoff；框架不选择 owner。 */
+    notifyPeerHandoff(peerId: string, handoffRevision?: number): boolean;
     dispose(reason?: string): Promise<LifecycleDisposeResult>;
 }
 /** 生产入口：只从真实 SharedWorkerGlobalScope 获取连接事件。 */
@@ -189,4 +275,4 @@ declare function startSharedWorkerApp(options: StartSharedWorkerAppOptions): Sha
 /** testing/advanced harness 入口；生产包的 startSharedWorkerApp 不接受 scope 注入。 */
 declare function startSharedWorkerAppForTesting(options: StartSharedWorkerAppForTestingOptions): SharedWorkerApp;
 
-export { 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 ResourceScopeOptions as e, type StartSharedWorkerAppForTestingOptions as f, type StartSharedWorkerAppOptions as g, bridgeForRuntimeHandle as h, createLifecycleScope as i, createResourceScope as j, type ConnectSharedWorkerOptions as k, type SharedWorkerLike as l, connectSharedWorker as m, type SharedWorkerFactory as n, type SharedWorkerScopeLike as o, connectSharedWorkerForTesting as p, startSharedWorkerAppForTesting as q, 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 { s as CreatePluginHostOptions, x as PluginHost } from './runtimeTypes-DquUCHz-.js';
-export { m as CapabilityRegistration, n as CapabilityRegistry, o as ContextExtensionInput, p as ContributionAdapter, q as ContributionAdapterInput, r as ContributionHandle, H as HostCapabilityRegistration, t as HostInspection, u as PermissionPolicyInput, v as PermissionPolicyResult, w as PluginConfigStore, y as RuntimeUnitAttributesInput, z as RuntimeUnitAvailabilityInput, A as RuntimeUnitParentScopeInput, B as RuntimeUnitSnapshot, D as StartupCapabilityError, E as StartupPluginError, F as createCapabilityRegistry, G as createInMemoryPluginConfigStore, I as createPluginHost, bP as createResourceStore, J as invokeCapabilityHandler } from './runtimeTypes-DquUCHz-.js';
-import { z as RuntimeWireMessage, a as RuntimeTransport } from './messagePortServiceTransport-BYprNvQY.js';
-export { C as CreateCapabilityBridgeOptions, b as CreatePluginIntentControllerOptions, M as MessagePortLike, r as RuntimeReceiveMetadata, y as RuntimeUnitImplementation, A as createCapabilityBridge, B as createMessagePortRuntimeTransport, D as createPluginIntentController, E as createResourceRegistry, G as createRuntimeUnitImplementationRegistry, J as validateTransferables } from './messagePortServiceTransport-BYprNvQY.js';
-export { C as CreateResourceScopeOptions, e as ResourceScopeOptions, n as SharedWorkerFactory, o as SharedWorkerScopeLike, f as StartSharedWorkerAppForTestingOptions, p as connectSharedWorkerForTesting, i as createLifecycleScope, j as createResourceScope, q as startSharedWorkerAppForTesting } from './sharedWorkerHost-KI7TIGdX.js';
-export { c as createMessageBus } from './messageBus-CtrwkjrO.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-SX46RHDI.js';
+export { startSharedWorkerAppForTesting } from './chunk-UZAO6ORB.js';
 export { createPluginIntentController } from './chunk-4DSINPZD.js';
-export { connectSharedWorkerForTesting, createCapabilityBridge, createMessagePortRuntimeTransport, validateTransferables } from './chunk-ANA6GBEI.js';
-import { createPluginHost } from './chunk-HJKPKWI7.js';
-export { StartupCapabilityError, StartupPluginError, createCapabilityRegistry, createInMemoryPluginConfigStore, createLifecycleScope, createMessageBus, createPluginHost, createResourceRegistry, createResourceScope, createResourceStore, createRuntimeUnitImplementationRegistry, invokeCapabilityHandler } from './chunk-HJKPKWI7.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-BKkLPsAS.d.ts → windowRuntime-e1Tn6SnN.d.ts}

@@ -1,5 +1,5 @@
-import { s as CreatePluginHostOptions, x as PluginHost, W as WindowApp } from './runtimeTypes-DquUCHz-.js';
-import { c as RuntimePluginDefinition } from './sharedWorkerHost-KI7TIGdX.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 逻辑标识。 */