webloom-framework 0.4.1 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,7 +1,7 @@
1
- export { startSharedWorkerApp } from './chunk-SX46RHDI.js';
2
- export { connectSharedWorker } from './chunk-ANA6GBEI.js';
3
- import { capabilityDescriptor } from './chunk-HJKPKWI7.js';
4
- 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';
1
+ export { startSharedWorkerApp } from './chunk-RRNUE457.js';
2
+ export { connectSharedWorker } from './chunk-XVD7ALPV.js';
3
+ import { capabilityDescriptor } from './chunk-CKML74MG.js';
4
+ 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-CKML74MG.js';
5
5
 
6
6
  // src/contracts/messageBus.ts
7
7
  var RUNTIME_MESSAGE_BUS = "webloom.messageBus";
@@ -1,4 +1,4 @@
1
- import { aq as MessageBus } from './runtimeTypes-DquUCHz-.js';
1
+ import { aW as MessageBus } from './runtimeTypes-CleHMFaq.js';
2
2
 
3
3
  declare function createMessageBus(): MessageBus;
4
4
 
@@ -0,0 +1,150 @@
1
+ import { ap as PluginSetup, ak as Capability, bQ as RuntimeUnitImplementationRegistry, bb as PluginIntentSnapshot, b9 as PluginIntentController, bv as ResourceRegistry, bt as ResourceDefinition, k as RuntimeEndpointBinding, bG as RuntimeEndpointState, m as RuntimeDrainResult, ab as RuntimeWireMessage, R as RuntimeKind, as as CapabilityBridge } from './runtimeTypes-CleHMFaq.js';
2
+ import { R as ReceivePortLedger, a as RuntimeLimitsInput, b as RuntimeBudget } from './sharedWorkerHost-BNMUW-8v.js';
3
+
4
+ interface RuntimeUnitImplementation {
5
+ /** 产品标识。 */
6
+ pluginId: string;
7
+ /** 稳定运行单元标识。 */
8
+ unitId: string;
9
+ /** 当前环境的可执行入口。 */
10
+ setup: PluginSetup;
11
+ /** 当前 realm 的 typed capability 定义。 */
12
+ capabilities?: readonly Capability[];
13
+ }
14
+ /** 创建一个拒绝重复注册、按产品和单元查找实现的运行时注册表。 */
15
+ declare function createRuntimeUnitImplementationRegistry(implementations?: readonly RuntimeUnitImplementation[]): RuntimeUnitImplementationRegistry & {
16
+ register(implementation: RuntimeUnitImplementation): void;
17
+ unregister(pluginId: string, unitId: string): void;
18
+ };
19
+
20
+ interface CreatePluginIntentControllerOptions {
21
+ /** 当前控制面启动身份;Worker 重启时应传入新值。 */
22
+ authorityInstanceId?: string;
23
+ /** Worker 恢复后读取的平台意图。 */
24
+ initial?: Partial<PluginIntentSnapshot>;
25
+ /** 将候选快照原子写入平台存储;缺省表示内存控制面(测试用)。 */
26
+ persist?: (snapshot: PluginIntentSnapshot) => Promise<void>;
27
+ /** 有界去重记录数量,避免 commandId 永久增长。 */
28
+ maxCommandRecords?: number;
29
+ }
30
+ /** 创建单一控制面上的插件意图控制器。 */
31
+ declare function createPluginIntentController(options?: CreatePluginIntentControllerOptions): PluginIntentController;
32
+
33
+ /**
34
+ * 资源注册表实现
35
+ *
36
+ * 设计缘由:管理资源定义的注册和查询,支持 owner-aware 生命周期。
37
+ * 重复 id 抛错,disable 时可回收。
38
+ */
39
+
40
+ /** 资源注册表实现 */
41
+ declare function createResourceRegistry(): ResourceRegistry;
42
+ /** Internal runtime hook; deliberately absent from ResourceRegistry's public type. */
43
+ declare function registerOwnedResource(registry: ResourceRegistry, ownerId: string, definition: ResourceDefinition<any, any>): void;
44
+
45
+ /** 关闭握手默认等待时间;调用方可以传入更严格的 deadline。 */
46
+ declare const DEFAULT_RUNTIME_DRAIN_TIMEOUT_MS = 2000;
47
+ /** 一个需要等待真实执行槽结束的框架参与者。 */
48
+ interface RuntimeDrainParticipant {
49
+ /** 等待该参与者自己的真实执行槽结束。 */
50
+ readonly drain: () => Promise<void>;
51
+ /** deadline 到达时报告仍未结束的真实执行槽数量。 */
52
+ readonly pending: () => number;
53
+ }
54
+ interface RuntimeEndpointSession {
55
+ /** 本端由框架生成、不可复用的 endpoint 身份。 */
56
+ readonly binding: RuntimeEndpointBinding;
57
+ /** 已由对端首条合法框架消息建立的身份;尚未建立时为空。 */
58
+ readonly remoteBinding?: RuntimeEndpointBinding;
59
+ /** active -> closing -> closed。 */
60
+ readonly state: RuntimeEndpointState;
61
+ /** 最近一次同步关闭原因;只用于本地诊断。 */
62
+ readonly closeReason?: string;
63
+ /** 本端允许的最大 drain 时间;远端只能进一步收紧,不能扩大。 */
64
+ readonly maxDrainTimeoutMs: number;
65
+ /** 精确比较并建立对端 binding;不接受后续替换。 */
66
+ acceptRemoteBinding(binding: unknown): boolean;
67
+ /** 同步停止准入、触发撤权和 abort;幂等。 */
68
+ beginClose(reason?: string): void;
69
+ /** 等待全部参与者排空,始终受 bounded deadline 限制。 */
70
+ drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
71
+ /** 物理 transport 即将关闭时标记终态;幂等。 */
72
+ close(): void;
73
+ /** 注册同步关闭回调。 */
74
+ onBeginClose(listener: (reason: string) => void): () => void;
75
+ /** 注册物理关闭回调。 */
76
+ onClosed(listener: () => void): () => void;
77
+ /** 注册一个真实执行排空参与者。 */
78
+ registerDrainParticipant(participant: RuntimeDrainParticipant): () => void;
79
+ }
80
+ /** 判断值是否为完整的框架 endpoint binding。 */
81
+ declare function isRuntimeEndpointBinding(value: unknown): value is RuntimeEndpointBinding;
82
+ /** 只比较框架 binding,不比较任何产品领域字段。 */
83
+ declare function sameRuntimeEndpointBinding(left: RuntimeEndpointBinding | undefined, right: RuntimeEndpointBinding | undefined): boolean;
84
+ /** 为一个 Runtime endpoint 生成不可复用的连接身份。 */
85
+ declare function createRuntimeEndpointBinding(runtimeInstanceId: string): RuntimeEndpointBinding;
86
+ /** 创建一条由 Runtime/transport 共用的 endpoint session。 */
87
+ declare function createRuntimeEndpointSession(binding: RuntimeEndpointBinding, options?: {
88
+ readonly defaultDrainTimeoutMs?: number;
89
+ }): RuntimeEndpointSession;
90
+
91
+ interface RuntimeReceiveMetadata {
92
+ /** 本次 MessageEvent 实际携带的业务 MessagePort;仅 transport 本地使用。 */
93
+ readonly ports?: readonly MessagePort[];
94
+ /** 由物理 endpoint transport 创建的一次性接收资源账本。 */
95
+ readonly ledger?: ReceivePortLedger;
96
+ /** 物理 endpoint 已完成一次 codec decode。 */
97
+ readonly decoded?: boolean;
98
+ }
99
+ interface RuntimeTransport {
100
+ /** 发送已验证 v4 message;transfer 由契约 extractor 提供。 */
101
+ send(message: RuntimeWireMessage, transfer?: readonly Transferable[]): void;
102
+ /** 订阅接收 message 及本次事件的本地 transfer 元数据。 */
103
+ subscribe(listener: (message: RuntimeWireMessage, metadata?: RuntimeReceiveMetadata) => void): () => void;
104
+ /** 关闭本端传输。 */
105
+ close?(): void;
106
+ /** 物理 endpoint 对 decode/接收账本错误的统一通知。 */
107
+ subscribeError?(listener: (error: unknown, metadata?: RuntimeReceiveMetadata) => void): () => void;
108
+ }
109
+ interface CreateCapabilityBridgeOptions {
110
+ /** 底层双向 transport。 */
111
+ readonly transport: RuntimeTransport;
112
+ /** 预期的对端 Runtime 类型。 */
113
+ readonly remoteRuntimeKind?: RuntimeKind;
114
+ /** 预期的对端逻辑 Runtime id。 */
115
+ readonly remoteRuntimeId?: string;
116
+ /** 默认调用预算。 */
117
+ readonly defaultCallTimeoutMs?: number;
118
+ /** 可信 Runtime/advanced 装配提供的预算;只能收紧 v4 默认值。 */
119
+ readonly limits?: RuntimeLimitsInput;
120
+ /** 可选的 Runtime 方向共享计数器。 */
121
+ readonly budget?: RuntimeBudget;
122
+ /** 当前物理 endpoint 的框架 binding;省略时由 bridge 生成。 */
123
+ readonly binding?: RuntimeEndpointBinding;
124
+ /** 与反向 provider 共用的 endpoint session。 */
125
+ readonly session?: RuntimeEndpointSession;
126
+ /** 关闭握手默认 drain deadline。 */
127
+ readonly drainTimeoutMs?: number;
128
+ }
129
+ /** 创建按 peer 绑定、可撤销且支持 typed stream 的 bridge。 */
130
+ declare function createCapabilityBridge(options: CreateCapabilityBridgeOptions): CapabilityBridge & {
131
+ readonly pendingCallCount: number;
132
+ readonly activeStreamCount: number;
133
+ readonly retainedPayloadBytes: number;
134
+ };
135
+ /** 内部 typed transfer 校验 helper;不接受 call 级临时 transfer 数组。 */
136
+ declare function validateTransferables(value: unknown, transfer: readonly Transferable[] | undefined, limits?: RuntimeLimitsInput): readonly Transferable[];
137
+
138
+ interface MessagePortLike {
139
+ addEventListener(type: "message" | "messageerror", listener: (event: MessageEvent) => void): void;
140
+ removeEventListener(type: "message" | "messageerror", listener: (event: MessageEvent) => void): void;
141
+ postMessage(message: unknown, transfer?: readonly Transferable[]): void;
142
+ start?(): void;
143
+ close?(): void;
144
+ }
145
+ /** 将一个真实 MessagePort 绑定为双向 v4 transport。 */
146
+ declare function createMessagePortRuntimeTransport(port: MessagePortLike, options?: {
147
+ readonly limits?: RuntimeLimitsInput;
148
+ }): RuntimeTransport;
149
+
150
+ export { type CreateCapabilityBridgeOptions as C, DEFAULT_RUNTIME_DRAIN_TIMEOUT_MS as D, type MessagePortLike as M, type RuntimeTransport as R, type RuntimeEndpointSession as a, type CreatePluginIntentControllerOptions as b, type RuntimeDrainParticipant as c, type RuntimeReceiveMetadata as d, type RuntimeUnitImplementation as e, createCapabilityBridge as f, createMessagePortRuntimeTransport as g, createPluginIntentController as h, createResourceRegistry as i, createRuntimeEndpointBinding as j, createRuntimeEndpointSession as k, createRuntimeUnitImplementationRegistry as l, isRuntimeEndpointBinding as m, registerOwnedResource as r, sameRuntimeEndpointBinding as s, validateTransferables as v };
package/dist/react.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
2
  import * as react from 'react';
3
3
  import { ReactNode } from 'react';
4
- 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';
4
+ import { W as WindowApp, o as RuntimeHandle, ak as Capability, at as CapabilityClient, ar as AppLike, bg as PluginState, a as PluginGraph, c as PluginReverseDep, bc as PluginIntentSubmissionResult, P as PluginManifest, C as CapabilityDescriptor, n as ResourceStoreApi, bw as ResourceSnapshot } from './runtimeTypes-CleHMFaq.js';
5
5
 
6
6
  type WebLoomApp = WindowApp | RuntimeHandle;
7
7
  declare const WebLoomContext: react.Context<WebLoomApp | undefined>;
package/dist/react.js CHANGED
@@ -1,4 +1,4 @@
1
- import { hostForWindowApp } from './chunk-HJKPKWI7.js';
1
+ import { hostForWindowApp } from './chunk-CKML74MG.js';
2
2
  import { createContext, useContext, useCallback, useSyncExternalStore, useMemo, useRef } from 'react';
3
3
  import { jsx } from 'react/jsx-runtime';
4
4
 
@@ -393,6 +393,32 @@ type LifecycleScopeState = "active" | "stopping" | "stopped";
393
393
  type RuntimeKind = "window-main" | "shared-worker";
394
394
  /** 权限动作名称。 */
395
395
  type PluginPermission = string;
396
+ /**
397
+ * WebLoom 为每条物理 Runtime endpoint 生成的连接绑定。
398
+ *
399
+ * `runtimeInstanceId` 标识一次 Runtime 启动,`connectionId` 标识该启动内
400
+ * 的一条物理连接。两者只能由框架创建并且不得复用;它不是产品领域的
401
+ * lease、owner 或领域 generation,也不能由请求载荷覆盖。
402
+ */
403
+ interface RuntimeEndpointBinding {
404
+ /** 产生此 endpoint 的 Runtime 启动身份。 */
405
+ readonly runtimeInstanceId: string;
406
+ /** 此 Runtime 启动内不可复用的物理连接身份。 */
407
+ readonly connectionId: string;
408
+ }
409
+ /** Runtime endpoint 的通用关闭阶段。 */
410
+ type RuntimeEndpointState = "active" | "closing" | "closed";
411
+ /** 一次 bounded drain 的结果;超时不伪装成已经排空。 */
412
+ interface RuntimeDrainResult {
413
+ /** 关闭阶段结束时的状态。 */
414
+ readonly state: RuntimeEndpointState;
415
+ /** 是否在 deadline 前等待到所有框架执行槽结束。 */
416
+ readonly drained: boolean;
417
+ /** 是否达到 bounded deadline。 */
418
+ readonly timedOut: boolean;
419
+ /** deadline 到达时仍未完成的真实执行槽数量。 */
420
+ readonly pendingExecutions: number;
421
+ }
396
422
  /** 一个作用域的不可替换身份绑定。 */
397
423
  interface LifecycleScopeIdentity<TAttributes extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
398
424
  /** 作用域唯一标识。 */
@@ -654,7 +680,7 @@ type SnapshotApplyResult = {
654
680
  receivedRevision?: number;
655
681
  };
656
682
  /** 框架结构化错误码。 */
657
- 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 & {});
683
+ 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 & {});
658
684
  /** 框架错误阶段。 */
659
685
  type FrameworkErrorPhase = "validate" | "wait" | "dispatch" | "execute" | "receive" | "dispose";
660
686
  /** 脱敏错误上下文。 */
@@ -870,6 +896,223 @@ declare const LIFECYCLE_ERROR_TEXT: Readonly<Record<string, string>>;
870
896
  /** 将生命周期错误码映射为中文提示。 */
871
897
  declare function lifecycleErrorText(code: string): string;
872
898
 
899
+ declare const RUNTIME_PROTOCOL_VERSION: "webloom.runtime.v1";
900
+ declare const RUNTIME_SNAPSHOT_TYPE: "webloom.runtime.v1.snapshot";
901
+ declare const RUNTIME_ERROR_TYPE: "webloom.runtime.v1.runtime-error";
902
+ declare const RUNTIME_CALL_TYPE: "webloom.runtime.v1.call";
903
+ declare const RUNTIME_RESULT_TYPE: "webloom.runtime.v1.result";
904
+ declare const RUNTIME_ERROR_MESSAGE_TYPE: "webloom.runtime.v1.error";
905
+ declare const RUNTIME_CANCEL_TYPE: "webloom.runtime.v1.cancel";
906
+ declare const RUNTIME_NEXT_TYPE: "webloom.runtime.v1.next";
907
+ declare const RUNTIME_CREDIT_TYPE: "webloom.runtime.v1.credit";
908
+ declare const RUNTIME_CLOSE_TYPE: "webloom.runtime.v1.close";
909
+ declare const RUNTIME_CLOSE_ACK_TYPE: "webloom.runtime.v1.close-ack";
910
+ /** 每条 Runtime wire 消息所属的框架 endpoint 身份。 */
911
+ type RuntimeSessionBinding = RuntimeEndpointBinding;
912
+ interface RuntimeSnapshotUnit {
913
+ /** 插件标识。 */
914
+ readonly pluginId: string;
915
+ /** 单元标识。 */
916
+ readonly unitId: string;
917
+ /** Runtime。 */
918
+ readonly runtime: RuntimeKind;
919
+ /** 实例标识。 */
920
+ readonly instanceId?: string;
921
+ /** 状态。 */
922
+ readonly state: PluginStateKind;
923
+ }
924
+ type RuntimeSnapshotMessage = RuntimeSnapshot & {
925
+ readonly type: typeof RUNTIME_SNAPSHOT_TYPE;
926
+ readonly binding: RuntimeSessionBinding;
927
+ };
928
+ interface RuntimeErrorMessage {
929
+ /** 消息类型。 */
930
+ readonly type: typeof RUNTIME_ERROR_TYPE;
931
+ /** 协议版本。 */
932
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
933
+ /** 发送此错误的物理 endpoint 绑定。 */
934
+ readonly binding: RuntimeSessionBinding;
935
+ /** 结构化错误码。 */
936
+ readonly code: string;
937
+ /** 脱敏消息。 */
938
+ readonly message: string;
939
+ /** 失败阶段。 */
940
+ readonly phase: "validate" | "wait" | "dispatch" | "execute" | "receive" | "dispose";
941
+ /** 可选插件标识。 */
942
+ readonly pluginId?: string;
943
+ /** 可选单元标识。 */
944
+ readonly unitId?: string;
945
+ }
946
+ interface RuntimeCallMessage {
947
+ /** 消息类型。 */
948
+ readonly type: typeof RUNTIME_CALL_TYPE;
949
+ /** 协议版本。 */
950
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
951
+ /** 发起调用的物理 endpoint 绑定。 */
952
+ readonly binding: RuntimeSessionBinding;
953
+ /** 方向内唯一 call id。 */
954
+ readonly callId: string;
955
+ /** capability 标识。 */
956
+ readonly capabilityId: string;
957
+ /** 契约版本。 */
958
+ readonly contractVersion: string;
959
+ /** exposure 身份。 */
960
+ readonly serviceInstanceId: string;
961
+ /** 调用模式。 */
962
+ readonly mode: "unary" | "stream";
963
+ /** 本次派发的剩余预算。 */
964
+ readonly timeoutMs: number;
965
+ /** 已 parser 验证的请求。 */
966
+ readonly request: unknown;
967
+ /** 产品操作标识。 */
968
+ readonly operationId?: string;
969
+ /** 领域授权标识。 */
970
+ readonly grantId?: string;
971
+ /** stream 初始 credit。 */
972
+ readonly initialCredit?: number;
973
+ }
974
+ interface RuntimeUnaryResultMessage {
975
+ /** 消息类型。 */
976
+ readonly type: typeof RUNTIME_RESULT_TYPE;
977
+ /** 协议版本。 */
978
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
979
+ /** 发送结果的物理 endpoint 绑定。 */
980
+ readonly binding: RuntimeSessionBinding;
981
+ /** call id。 */
982
+ readonly callId: string;
983
+ /** exposure 身份。 */
984
+ readonly serviceInstanceId: string;
985
+ /** unary 结果。 */
986
+ readonly result: unknown;
987
+ }
988
+ interface RuntimeStreamReadyMessage {
989
+ /** 消息类型。 */
990
+ readonly type: typeof RUNTIME_RESULT_TYPE;
991
+ /** 协议版本。 */
992
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
993
+ /** 发送结果的物理 endpoint 绑定。 */
994
+ readonly binding: RuntimeSessionBinding;
995
+ /** call id。 */
996
+ readonly callId: string;
997
+ /** exposure 身份。 */
998
+ readonly serviceInstanceId: string;
999
+ /** stream 建立确认。 */
1000
+ readonly streamReady: true;
1001
+ }
1002
+ interface RuntimeStreamDoneMessage {
1003
+ /** 消息类型。 */
1004
+ readonly type: typeof RUNTIME_RESULT_TYPE;
1005
+ /** 协议版本。 */
1006
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
1007
+ /** 发送结果的物理 endpoint 绑定。 */
1008
+ readonly binding: RuntimeSessionBinding;
1009
+ /** call id。 */
1010
+ readonly callId: string;
1011
+ /** exposure 身份。 */
1012
+ readonly serviceInstanceId: string;
1013
+ /** stream 正常结束。 */
1014
+ readonly done: true;
1015
+ }
1016
+ type RuntimeResultMessage = RuntimeUnaryResultMessage | RuntimeStreamReadyMessage | RuntimeStreamDoneMessage;
1017
+ interface RuntimeErrorResponseMessage {
1018
+ /** 消息类型。 */
1019
+ readonly type: typeof RUNTIME_ERROR_MESSAGE_TYPE;
1020
+ /** 协议版本。 */
1021
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
1022
+ /** 发送错误响应的物理 endpoint 绑定。 */
1023
+ readonly binding: RuntimeSessionBinding;
1024
+ /** call id。 */
1025
+ readonly callId: string;
1026
+ /** exposure 身份。 */
1027
+ readonly serviceInstanceId: string;
1028
+ /** 结构化错误。 */
1029
+ readonly error: {
1030
+ readonly code: string;
1031
+ readonly message: string;
1032
+ readonly phase: RuntimeErrorMessage["phase"];
1033
+ readonly details?: Readonly<Record<string, unknown>>;
1034
+ };
1035
+ }
1036
+ interface RuntimeCancelMessage {
1037
+ /** 消息类型。 */
1038
+ readonly type: typeof RUNTIME_CANCEL_TYPE;
1039
+ /** 协议版本。 */
1040
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
1041
+ /** 发送取消的物理 endpoint 绑定。 */
1042
+ readonly binding: RuntimeSessionBinding;
1043
+ /** call id。 */
1044
+ readonly callId: string;
1045
+ /** exposure 身份。 */
1046
+ readonly serviceInstanceId: string;
1047
+ }
1048
+ interface RuntimeNextMessage {
1049
+ /** 消息类型。 */
1050
+ readonly type: typeof RUNTIME_NEXT_TYPE;
1051
+ /** 协议版本。 */
1052
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
1053
+ /** 发送 stream item 的物理 endpoint 绑定。 */
1054
+ readonly binding: RuntimeSessionBinding;
1055
+ /** call id。 */
1056
+ readonly callId: string;
1057
+ /** exposure 身份。 */
1058
+ readonly serviceInstanceId: string;
1059
+ /** 连续序号。 */
1060
+ readonly sequence: number;
1061
+ /** parser 验证的 item。 */
1062
+ readonly item: unknown;
1063
+ }
1064
+ interface RuntimeCreditMessage {
1065
+ /** 消息类型。 */
1066
+ readonly type: typeof RUNTIME_CREDIT_TYPE;
1067
+ /** 协议版本。 */
1068
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
1069
+ /** 发送 credit 的物理 endpoint 绑定。 */
1070
+ readonly binding: RuntimeSessionBinding;
1071
+ /** call id。 */
1072
+ readonly callId: string;
1073
+ /** exposure 身份。 */
1074
+ readonly serviceInstanceId: string;
1075
+ /** 新增 credit。 */
1076
+ readonly count: number;
1077
+ }
1078
+ /** 请求对端先同步 fence、再等待真实执行排空。 */
1079
+ interface RuntimeCloseMessage {
1080
+ /** 消息类型。 */
1081
+ readonly type: typeof RUNTIME_CLOSE_TYPE;
1082
+ /** 协议版本。 */
1083
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
1084
+ /** 发起关闭的物理 endpoint 绑定。 */
1085
+ readonly binding: RuntimeSessionBinding;
1086
+ /** 对端 drain 的最大等待时间。 */
1087
+ readonly timeoutMs?: number;
1088
+ }
1089
+ /** 对端完成或超时 drain 后返回的关闭确认。 */
1090
+ interface RuntimeCloseAckMessage {
1091
+ /** 消息类型。 */
1092
+ readonly type: typeof RUNTIME_CLOSE_ACK_TYPE;
1093
+ /** 协议版本。 */
1094
+ readonly protocolVersion: typeof RUNTIME_PROTOCOL_VERSION;
1095
+ /** 发送确认的物理 endpoint 绑定。 */
1096
+ readonly binding: RuntimeSessionBinding;
1097
+ /** 确认对应的发起方 binding,防止旧 close-ack 误配新 session。 */
1098
+ readonly acknowledgedBinding: RuntimeSessionBinding;
1099
+ /** 对端本次 drain 的结果。 */
1100
+ readonly drained: boolean;
1101
+ /** 是否达到 bounded deadline。 */
1102
+ readonly timedOut: boolean;
1103
+ /** deadline 到达时仍存活的执行槽数量。 */
1104
+ readonly pendingExecutions: number;
1105
+ }
1106
+ type RuntimeWireMessage = RuntimeSnapshotMessage | RuntimeErrorMessage | RuntimeCallMessage | RuntimeResultMessage | RuntimeErrorResponseMessage | RuntimeCancelMessage | RuntimeNextMessage | RuntimeCreditMessage | RuntimeCloseMessage | RuntimeCloseAckMessage;
1107
+ interface RuntimeMessageCodec {
1108
+ /** 严格验证并冻结 v4 message。 */
1109
+ encode(message: RuntimeWireMessage): RuntimeWireMessage;
1110
+ /** 严格解析 v4 message;旧协议直接拒绝。 */
1111
+ decode(value: unknown): RuntimeWireMessage;
1112
+ }
1113
+ declare function createRuntimeMessageCodec(): RuntimeMessageCodec;
1114
+ declare function isRuntimeSnapshot(value: RuntimeWireMessage): value is RuntimeSnapshotMessage;
1115
+
873
1116
  /** 验证 unknown 并返回领域类型的生产 parser。 */
874
1117
  interface ValueParser<T> {
875
1118
  /** 验证 unknown;失败必须抛出校验错误。 */
@@ -1024,6 +1267,8 @@ interface ServiceReference {
1024
1267
  interface CapabilityPeer {
1025
1268
  /** 对端连接的不可复用身份。 */
1026
1269
  readonly peerId: string;
1270
+ /** 当前物理 endpoint 的框架 binding;不包含产品领域授权。 */
1271
+ readonly binding: RuntimeEndpointBinding;
1027
1272
  /** 已观察到的对端 Runtime 类型;首个快照前为空。 */
1028
1273
  readonly runtime?: RuntimeKind;
1029
1274
  /** 已观察到的对端 Runtime 一次启动身份;首个快照前为空。 */
@@ -1068,16 +1313,25 @@ interface CapabilityBridge {
1068
1313
  readonly runtimeInstanceId?: string;
1069
1314
  /** 当前已观察到的对端 Runtime 类型;快照到达前为空。 */
1070
1315
  readonly runtimeKind?: RuntimeKind;
1316
+ /** 本端物理 endpoint 的框架 binding。 */
1317
+ readonly binding: RuntimeEndpointBinding;
1318
+ /** 当前 endpoint 生命周期;与远端 Runtime state 独立。 */
1319
+ readonly endpointState: RuntimeEndpointState;
1071
1320
  /** 取惰性 typed client;没有服务时不在此处同步失败。 */
1072
1321
  getClient<C extends RemoteCapability>(capability: C, scope?: LifecycleScope): CapabilityClient<C>;
1073
1322
  /** 应用一个完整对端目录。 */
1074
- applySnapshot(snapshot: RuntimeSnapshot): SnapshotApplyResult;
1323
+ /** 应用带框架 binding 的远端完整目录;缺失 binding 必须拒绝。 */
1324
+ applySnapshot(snapshot: RuntimeSnapshotMessage): SnapshotApplyResult;
1075
1325
  /** 同步撤销全部旧代理。 */
1076
1326
  invalidate(reason?: string): void;
1077
1327
  /** 连接断开;旧代理永久失效。 */
1078
1328
  disconnect(reason?: string): void;
1079
1329
  /** 永久销毁 bridge。 */
1080
1330
  dispose(reason?: string): void;
1331
+ /** 同步停止新调用、撤销代理并 abort 已进入调用;幂等。 */
1332
+ beginClose(reason?: string): void;
1333
+ /** 等待本端与对端框架执行槽 bounded drain;超时不伪装成功。 */
1334
+ drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
1081
1335
  /** 订阅目录/连接状态变化。 */
1082
1336
  subscribe(listener: () => void): () => void;
1083
1337
  /** 当前已发布的完整服务引用。 */
@@ -1093,6 +1347,8 @@ interface HandlerCallContext {
1093
1347
  readonly operationId?: string;
1094
1348
  /** 当前服务 exposure 身份。 */
1095
1349
  readonly reference: ServiceReference;
1350
+ /** 远程调用对应的框架 endpoint binding;同 realm 调用没有物理 endpoint。 */
1351
+ readonly binding?: RuntimeEndpointBinding;
1096
1352
  /** 调用来源。 */
1097
1353
  readonly origin: HandlerOrigin;
1098
1354
  /** 远程调用的框架绑定对端;local 调用必为 undefined。 */
@@ -1581,6 +1837,8 @@ interface RuntimeStatusSnapshot extends Omit<RuntimeSnapshot, "protocolVersion"
1581
1837
  readonly protocolVersion: string;
1582
1838
  /** Runtime 当前状态。 */
1583
1839
  readonly state: RuntimeAppState;
1840
+ /** 当前观察到的远端物理 endpoint binding;本地 WindowApp 不填写。 */
1841
+ readonly binding?: RuntimeEndpointBinding;
1584
1842
  /** 脱敏 Runtime 错误。 */
1585
1843
  readonly error?: string;
1586
1844
  }
@@ -1612,10 +1870,18 @@ interface WindowApp extends AppLike {
1612
1870
  }
1613
1871
  interface RuntimeHandle extends AppLike {
1614
1872
  readonly runtimeKind: "shared-worker";
1873
+ /** 当前 Window ↔ Worker 物理 endpoint 的不可复用框架 binding。 */
1874
+ readonly binding: RuntimeEndpointBinding;
1875
+ /** 当前物理连接生命周期;不等同于远端 Runtime state。 */
1876
+ readonly endpointState: RuntimeEndpointState;
1615
1877
  /** 获取远程 typed RPC/stream capability;代理构造不等待 Worker。 */
1616
1878
  capability<C extends RemoteCapability>(capability: C): CapabilityClient<C>;
1617
1879
  /** 当前已观察到的 remote capability。 */
1618
1880
  optionalCapability<C extends RemoteCapability>(capability: C): CapabilityClient<C> | undefined;
1881
+ /** 同步停止新调用与本端反向 handler admission。 */
1882
+ beginClose(reason?: string): void;
1883
+ /** 等待本端及远端框架执行槽的 bounded drain。 */
1884
+ drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
1619
1885
  }
1620
1886
  declare class RuntimeInitializationError extends Error {
1621
1887
  readonly code: "runtime_initialization_failed";
@@ -1637,4 +1903,4 @@ declare class RuntimeUnavailableError extends Error {
1637
1903
  constructor(message?: string);
1638
1904
  }
1639
1905
 
1640
- 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 };
1906
+ 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 };
@@ -1,4 +1,4 @@
1
- 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';
1
+ 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';
2
2
 
3
3
  interface CreateResourceScopeOptions {
4
4
  /** 可选固定作用域标识;生产代码通常省略,让实现生成不可复用 ID。 */
@@ -127,6 +127,10 @@ interface PeerExposureOptions {
127
127
  interface PeerController {
128
128
  /** peer 标识。 */
129
129
  readonly peerId: string;
130
+ /** 当前物理 endpoint 的不可复用框架 binding。 */
131
+ readonly binding: RuntimeEndpointBinding;
132
+ /** 当前物理 endpoint 的关闭阶段。 */
133
+ readonly endpointState: RuntimeEndpointState;
130
134
  /** 已观察到的页面 Runtime 实例;首个页面快照前为空。 */
131
135
  readonly runtimeInstanceId?: string;
132
136
  /** 对端 Window Runtime 类型。 */
@@ -150,9 +154,32 @@ interface PeerController {
150
154
  };
151
155
  /** 断开此 peer,不影响其它页面。 */
152
156
  disconnect(reason?: string): void;
157
+ /** 同步停止新调用与暴露;后续由 drain/close 完成异步收尾。 */
158
+ beginClose(reason?: string): void;
159
+ /** 等待该 peer endpoint 的 bounded drain。 */
160
+ drain(timeoutMs?: number): Promise<RuntimeDrainResult>;
153
161
  /** peer 诊断。 */
154
162
  inspect(): Readonly<Record<string, unknown>>;
155
163
  }
164
+ /** 可信 Host 可观察的 peer 生命周期事件;不包含 owner/lease 等领域字段。 */
165
+ interface PeerLifecycleEvent {
166
+ /** active 建立、handoff 通知或关闭阶段。 */
167
+ readonly event: "active" | "handoff" | "closing" | "closed";
168
+ /** peer 物理连接的 opaque 标识。 */
169
+ readonly peerId: string;
170
+ /** 当前物理 endpoint 的框架 binding。 */
171
+ readonly binding: RuntimeEndpointBinding;
172
+ /** endpoint 的框架生命周期。 */
173
+ readonly state: RuntimeEndpointState;
174
+ /** closed 事件的真实 bounded drain 结果。 */
175
+ readonly drain?: RuntimeDrainResult;
176
+ /** 可信 Host 提供的 handoff 修订;WebLoom 不解释或选择 owner。 */
177
+ readonly handoffRevision?: number;
178
+ }
179
+ /** 可信 Host 查询到的 active peer 只读投影。 */
180
+ type ActivePeerSnapshot = Omit<PeerLifecycleEvent, "event" | "drain" | "handoffRevision"> & {
181
+ readonly event: "active";
182
+ };
156
183
  interface StartSharedWorkerAppOptions extends Omit<CreatePluginHostOptions, "runtime" | "runtimeUnitImplementationRegistry" | "runtimeId" | "runtimeInstanceId"> {
157
184
  /** Worker Runtime 逻辑标识。 */
158
185
  readonly id: string;
@@ -182,6 +209,12 @@ interface SharedWorkerApp {
182
209
  state(): RuntimeStatusSnapshot;
183
210
  subscribe(listener: RuntimeStatusListener): () => void;
184
211
  inspect(): HostInspection;
212
+ /** 只读查询当前仍处于 active 的物理 peer。 */
213
+ activePeers(): readonly ActivePeerSnapshot[];
214
+ /** 订阅 Host 可见的 peer active/closing/closed/handoff 事件。 */
215
+ subscribePeerLifecycle(listener: (event: PeerLifecycleEvent) => void): () => void;
216
+ /** 可信领域在完成自己的 owner/session 交接后报告 handoff;框架不选择 owner。 */
217
+ notifyPeerHandoff(peerId: string, handoffRevision?: number): boolean;
185
218
  dispose(reason?: string): Promise<LifecycleDisposeResult>;
186
219
  }
187
220
  /** 生产入口:只从真实 SharedWorkerGlobalScope 获取连接事件。 */
@@ -189,4 +222,4 @@ declare function startSharedWorkerApp(options: StartSharedWorkerAppOptions): Sha
189
222
  /** testing/advanced harness 入口;生产包的 startSharedWorkerApp 不接受 scope 注入。 */
190
223
  declare function startSharedWorkerAppForTesting(options: StartSharedWorkerAppForTestingOptions): SharedWorkerApp;
191
224
 
192
- 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 };
225
+ 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 };