webloom-framework 0.3.0 → 0.4.0

package/dist/runtimeTypes-DquUCHz-.d.ts

@@ -0,0 +1,1640 @@
+/** runtime messageBus capability key；manifest 通过 ctx.get<...> 取出。 */
+declare const RUNTIME_MESSAGE_BUS = "webloom.messageBus";
+/** 消息调用语义。 */
+type MessageMode = "event" | "command" | "request";
+/** 消息 envelope。 */
+interface Message<TPayload = unknown> {
+    id: string;
+    type: string;
+    mode: MessageMode;
+    payload: TPayload;
+    /** 由哪个 actor mailbox 消费。缺省时同步调用 subscriber 或无 mailbox。 */
+    target?: string;
+    /** 数值越大越优先（actor 内部解读）。 */
+    priority?: number;
+    /** 超时（ms）；超时后 message 标记为超时失败。 */
+    timeoutMs?: number;
+    /**
+     * MessageBus 内部维护的 abort signal。
+     *  - 来自调用方 DispatchOptions.signal 的 upstream 取消会触发。
+     *  - 来自 MessageBus 自身的 timeout 触发。
+     *  - 来自 actor / MessageBus 内部主动 abort。
+     *  handler 应优先用此 signal 取消 fetch 等异步操作；payload.signal 仍
+     *  可保留以兼容旧调用方。
+     */
+    signal?: AbortSignal;
+    causationId?: string;
+    createdAt: number;
+}
+/** 消息 handler 签名。 */
+type MessageHandler<TPayload = unknown, TResult = unknown> = (message: Message<TPayload>) => TResult | Promise<TResult>;
+/** publish 行为：仅同步广播给订阅者，不等待异步 handler 完成。 */
+interface PublishOptions {
+    /** 关联上一条消息（同一业务动作触发的子事件）。 */
+    causationId?: string;
+    /** 自定义 message id；缺省由 MessageBus 生成。 */
+    messageId?: string;
+}
+/**
+ * dispatch 行为：投递给 actor mailbox；返回 messageId。
+ *  - target 必填：dispatch 期望被 actor 处理，不退化为 publish 语义。
+ *  - 找到 handler 时消息会真正入 mailbox 并被 pump 串行消费。
+ *  - 找不到 handler 时消息被记为 failed + lastError，但**不抛**给调用方
+ *    （dispatch 不返回结果）。
+ */
+interface DispatchOptions extends PublishOptions {
+    target: string;
+    priority?: number;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** 消息进入终态后调用一次；生命周期 facade 用它释放临时 signal 监听。 */
+    onSettled?: () => void;
+}
+/**
+ * request 行为：等待 actor 返回结果；选项语义与 dispatch 完全一致。
+ *  - 行为差异：request 返回 Promise<TResult>，handler reject 即 promise reject。
+ *  - 找不到 handler / no target 时立即 reject。
+ *  - timeoutMs 触发时会先 abort 内部 signal，再 reject 外层 promise；
+ *    handler 内部应该监听 message.signal 取消 fetch。
+ */
+type RequestOptions = DispatchOptions;
+/** handle 注册选项。 */
+interface HandlerOptions {
+    target?: string;
+    priority?: number;
+    /**
+     * 同 target 投递并发上限。
+     * 缺省 1：同 target actor 严格串行。
+     * 同 target 全部 handler 注册时必须使用一致 concurrency，否则
+     * MessageBus 抛 `Conflicting concurrency for target "..."`。
+     * 注意：这是 MessageBus 投递并发，不是 handler 内部副作用（如网络
+     * 请求）的并发；高并发适合"内部 actor 自己做限流"的场景（如 WOC
+     * 内部 mailbox）。
+     */
+    concurrency?: number;
+}
+/** 快照。 */
+interface MessageBusSnapshot {
+    /** 消息总数（含已完成、失败、被取消）。 */
+    total: number;
+    /** 队列中尚未处理的消息数。 */
+    queued: number;
+    /** 飞行中消息数。 */
+    inFlight: number;
+    /** 已成功完成的消息数。 */
+    completed: number;
+    /** handler 抛错或被 lastError 路径标记失败的消息数。 */
+    failed: number;
+    /** 被 abort signal 取消的消息数。 */
+    canceled: number;
+    /** 最近一次错误。 */
+    lastError?: string;
+    /** 各 target 队列长度。 */
+    byTarget: Record<string, number>;
+}
+/** 订阅事件快捷方式：仅接收 mode=event 的消息。 */
+type EventHandler<TPayload = unknown> = (payload: TPayload) => void;
+/**
+ * MessageBus 契约。
+ * 设计缘由：业务插件调用方只看到这一套入口。
+ */
+interface MessageBus {
+    /** 事件广播：已发生的事实，不等待业务完成；同步调用 subscriber。 */
+    publish<TPayload>(type: string, payload: TPayload, options?: PublishOptions): string;
+    /** 事件订阅：仅接收 mode=event 的消息；返回取消订阅函数。 */
+    subscribe<TPayload>(type: string, handler: EventHandler<TPayload>): () => void;
+    /**
+     * 命令投递：把消息入 actor mailbox，返回 messageId。
+     *  不等待 handler 完成；handler 抛错 / 超时 / 找不到 handler 仅写
+     *  snapshot.lastError，不冒泡。
+     */
+    dispatch<TPayload>(type: string, payload: TPayload, options: DispatchOptions): string;
+    /** 请求响应：等待 actor 返回结果。 */
+    request<TPayload, TResult>(type: string, payload: TPayload, options: RequestOptions): Promise<TResult>;
+    /** 注册 handler：带 target 时进入对应 actor mailbox。 */
+    handle<TPayload, TResult>(type: string, handler: MessageHandler<TPayload, TResult>, options?: HandlerOptions): () => void;
+    /** 快照。 */
+    snapshot(): MessageBusSnapshot;
+    /** 订阅快照变更。 */
+    onSnapshot(handler: (snapshot: MessageBusSnapshot) => void): () => void;
+}
+
+/** 宿主注入的只读结构化属性；不得放入私钥、口令或 Seed。 */
+type PluginAttributes = Readonly<Record<string, unknown>>;
+/** 插件配置的默认形状。 */
+type PluginConfig = Readonly<Record<string, unknown>>;
+/** 插件对宿主的领域贡献；具体产品通过泛型定义。 */
+type PluginContribution = unknown;
+/** 插件 Context Extension 的默认形状。 */
+type PluginContextExtension = Readonly<Record<string, unknown>>;
+/** 插件运行单元的清理函数。 */
+type PluginTeardown = () => void | Promise<void>;
+type DeclaredCapability<TProvides extends readonly Capability[]> = TProvides[number];
+type DeclaredDependencyCapability<TDependencies extends readonly CapabilityDependency[]> = TDependencies[number] extends CapabilityDependency<infer C> ? C : never;
+type DeclaredPeerDependencyCapability<TDependencies extends readonly CapabilityDependency[]> = TDependencies[number] extends infer D ? D extends PeerCapabilityDependency<infer C> ? C : never : never;
+type DeclaredRuntimeDependencyCapability<TDependencies extends readonly CapabilityDependency[]> = Exclude<DeclaredDependencyCapability<TDependencies>, DeclaredPeerDependencyCapability<TDependencies>>;
+type AvailableCapability<TProvides extends readonly Capability[], TDependencies extends readonly CapabilityDependency[]> = DeclaredCapability<TProvides> | DeclaredRuntimeDependencyCapability<TDependencies>;
+type DeclaredLocal<TProvides extends readonly Capability[]> = Extract<DeclaredCapability<TProvides>, {
+    kind: "local";
+}>;
+type DeclaredRemote<TProvides extends readonly Capability[]> = Extract<DeclaredCapability<TProvides>, {
+    kind: "rpc" | "stream";
+}>;
+/** 插件 Context；能力参数和返回值从 capability 对象端到端推导。 */
+interface PluginContext<TProvides extends readonly Capability[] = readonly Capability[], TDependencies extends readonly CapabilityDependency[] = readonly CapabilityDependency[], TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> {
+    /** Host 绑定的稳定插件标识。 */
+    readonly pluginId: string;
+    /** 本次插件启动生成的实例标识。 */
+    readonly instanceId: string;
+    /** 稳定运行单元标识。 */
+    readonly unitId: string;
+    /** 当前插件实例作用域。 */
+    readonly scope: LifecycleScope;
+    /** 撤权和停止信号。 */
+    readonly signal: AbortSignal;
+    /** 可信装配批准后的权限视图。 */
+    readonly permissions: readonly PluginPermission[];
+    /** 绑定实例与权限身份的租约。 */
+    readonly permissionLease: PermissionLease;
+    /** 当前插件实例的后台任务调度器。 */
+    readonly taskScheduler?: ScopedTaskScheduler;
+    /** 宿主注入的只读领域扩展。 */
+    readonly extension: TExtension;
+    /** 插件配置。 */
+    readonly config?: TConfig;
+    /** 注册在同步撤权之后异步执行的清理。 */
+    onDispose(cleanup: PluginTeardown): void;
+    /** 只允许注册本插件声明的 local provides。 */
+    provide<C extends DeclaredLocal<TProvides>>(capability: C, value: LocalServiceOf<C>): void;
+    /** 只允许注册本插件声明的 RPC/stream provides。 */
+    handle<C extends DeclaredRemote<TProvides>>(capability: C, handler: C extends RpcCapability<infer TRequest, infer TResponse> ? RpcHandler<RpcCapability<TRequest, TResponse>> : C extends StreamCapability<infer TRequest, infer TItem> ? StreamHandler<StreamCapability<TRequest, TItem>> : never): void;
+    /** 获取当前声明范围内的 typed 能力；远程能力获取是惰性的。 */
+    capability<C extends AvailableCapability<TProvides, TDependencies>>(capability: C): CapabilityClient<Extract<C, Capability>>;
+    /** 当前目录没有该能力时返回 undefined。 */
+    optionalCapability<C extends AvailableCapability<TProvides, TDependencies>>(capability: C): CapabilityClient<Extract<C, Capability>> | undefined;
+    /** scoped MessageBus；业务事件不承担 Runtime 控制 wire。 */
+    readonly messageBus: MessageBus;
+}
+/** 静态依赖描述；wire 不携带 capability 对象引用。 */
+type RuntimeUnitDependency = {
+    /** 依赖 capability 的静态身份。 */
+    readonly capability: CapabilityDescriptor;
+    /** 可选依赖只影响局部功能。 */
+    readonly optional?: boolean;
+    /** 面向诊断的依赖说明。 */
+    readonly reason?: string;
+} & (
+/** 按调用 peer 解析的依赖；不参加全局 Host 启动图。 */
+{
+    readonly source: "peer";
+    readonly sourceRuntime?: never;
+}
+/** 精确来源 Runtime。 */
+ | {
+    readonly source?: never;
+    readonly sourceRuntime: RuntimeKind;
+});
+/** 作者输入的依赖；装配层补齐 sourceRuntime。 */
+type RuntimeUnitDependencyInput = CapabilityDependency & {
+    /** 当前 realm 的 capability 对象。 */
+    readonly capability: Capability;
+};
+/** 一个静态运行单元描述；不含 setup/parser/transfer 函数。 */
+interface RuntimeUnitDescriptor<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig> {
+    /** 稳定运行单元标识。 */
+    readonly id: string;
+    /** 真实执行 Runtime。 */
+    readonly runtime?: RuntimeKind;
+    /** 该单元的精确依赖。 */
+    readonly dependencies?: readonly RuntimeUnitDependency[];
+    /** 该单元提供的 capability 静态身份。 */
+    readonly provides?: readonly CapabilityDescriptor[];
+    /** 领域贡献。 */
+    readonly contribution?: TContribution;
+    /** 该单元申请的权限。 */
+    readonly permissions?: readonly PluginPermission[];
+    /** 单元只读配置。 */
+    readonly config?: TConfig;
+}
+/** 作者输入的运行单元描述；capability 对象仅留在当前 realm 装配层。 */
+type RuntimeUnitDescriptorInput<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig> = Omit<RuntimeUnitDescriptor<TContribution, TConfig>, "dependencies" | "provides" | "runtime"> & {
+    /** 运行时注入的目标 Runtime。 */
+    readonly runtime?: RuntimeKind;
+    /** 当前 realm 的 typed 依赖对象。 */
+    readonly dependencies?: readonly RuntimeUnitDependencyInput[];
+    /** 当前 realm 的 typed 提供对象。 */
+    readonly provides?: readonly Capability[];
+};
+type PluginStartupMode = "required" | "optional";
+/** 插件静态 manifest；startup/defaultEnabled/canDisable 是唯一启停策略。 */
+interface PluginManifest<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig> {
+    /** 全局稳定插件标识。 */
+    readonly id: string;
+    /** 展示名称。 */
+    readonly name: string;
+    /** 可选诊断描述。 */
+    readonly description?: string;
+    /** 初始启停策略。 */
+    readonly startup: PluginStartupMode;
+    /** 默认启用意图。 */
+    readonly defaultEnabled: boolean;
+    /** 是否允许控制面停用。 */
+    readonly canDisable: boolean;
+    /** 多 Runtime 静态单元。 */
+    readonly units?: readonly RuntimeUnitDescriptor<TContribution, TConfig>[];
+}
+/** 作者输入的静态 manifest。 */
+type PluginManifestInput<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig> = PluginManifest<TContribution, TConfig>;
+/** 插件运行状态。 */
+type PluginStateKind = "registered" | "starting" | "stopping" | "enabled" | "disabled" | "blocked" | "error-disabled" | "cleanup-pending" | "unknown";
+/** 对外稳定的插件生命周期语义。 */
+type PluginLifecycleState = "disabled" | "waiting" | "starting" | "running" | "stopping" | "failed";
+/** Host 查询到的插件状态。 */
+interface PluginState {
+    /** 插件标识。 */
+    readonly id: string;
+    /** 当前内部状态。 */
+    readonly kind: PluginStateKind;
+    /** 稳定生命周期映射。 */
+    readonly lifecycleState: PluginLifecycleState;
+    /** 脱敏错误文本。 */
+    readonly error?: string;
+    /** 当前启用意图。 */
+    readonly desiredEnabled: boolean;
+    /** 当前意图修订。 */
+    readonly desiredRevision?: number;
+    /** 当前启动实例。 */
+    readonly instanceId?: string;
+    /** 当前运行单元。 */
+    readonly unitId?: string;
+    /** 阻塞原因。 */
+    readonly blockedBy?: readonly string[];
+    /** 最近一次清理结果。 */
+    readonly cleanup?: LifecycleDisposeResult;
+    /** 单元状态。 */
+    readonly units: readonly PluginUnitState[];
+}
+/** 运行单元状态。 */
+interface PluginUnitState {
+    /** 所属插件。 */
+    readonly pluginId: string;
+    /** 稳定单元标识。 */
+    readonly unitId: string;
+    /** 真实 Runtime。 */
+    readonly runtime: RuntimeKind;
+    /** 当前启动实例。 */
+    readonly instanceId?: string;
+    /** 当前意图修订。 */
+    readonly desiredRevision?: number;
+    /** 单元状态。 */
+    readonly kind: PluginStateKind;
+    /** 脱敏错误文本。 */
+    readonly error?: string;
+    /** 清理结果。 */
+    readonly cleanup?: LifecycleDisposeResult;
+}
+/** 依赖图中的反向依赖者。 */
+interface PluginReverseDep {
+    /** 反向依赖插件标识。 */
+    readonly pluginId: string;
+    /** 依赖者是否启用。 */
+    readonly enabled: boolean;
+    /** 触发依赖的 capability 身份。 */
+    readonly capabilities: readonly CapabilityDescriptor[];
+}
+/** 插件依赖图快照。 */
+interface PluginGraph {
+    /** 已知插件。 */
+    readonly plugins: readonly string[];
+    /** 插件依赖。 */
+    readonly dependencies: Readonly<Record<string, readonly CapabilityDescriptor[]>>;
+    /** 可选依赖。 */
+    readonly optionalDependencies: Readonly<Record<string, readonly CapabilityDescriptor[]>>;
+    /** 插件提供。 */
+    readonly provides: Readonly<Record<string, readonly CapabilityDescriptor[]>>;
+    /** 反向依赖。 */
+    readonly reverse: Readonly<Record<string, readonly PluginReverseDep[]>>;
+    /** capability 到提供者。 */
+    readonly providers: Readonly<Record<string, readonly string[]>>;
+    /** 依赖环。 */
+    readonly cycles: readonly (readonly string[])[];
+    /** 运行单元图。 */
+    readonly units: Readonly<Record<string, PluginUnitGraph>>;
+}
+/** 运行单元依赖图节点。 */
+interface PluginUnitGraph {
+    /** 所属插件。 */
+    readonly pluginId: string;
+    /** 单元标识。 */
+    readonly unitId: string;
+    /** 真实 Runtime。 */
+    readonly runtime: RuntimeKind;
+    /** capability 依赖。 */
+    readonly dependencies: readonly CapabilityDescriptor[];
+    /** capability 提供。 */
+    readonly provides: readonly CapabilityDescriptor[];
+}
+/** Host 状态订阅。 */
+type HostListener = (snapshot: {
+    readonly version: number;
+}) => void;
+/** 缺少能力的结构化启动详情。 */
+interface StartupCapabilityErrorDetails {
+    /** capability 身份。 */
+    readonly capability: CapabilityDescriptor;
+    /** 已知提供者插件。 */
+    readonly providerPluginId?: string;
+    /** 提供者状态。 */
+    readonly providerState?: PluginStateKind;
+    /** 提供者错误。 */
+    readonly providerError?: string;
+    /** 当前启用意图。 */
+    readonly configuredEnabled?: boolean;
+}
+/** 启动插件失败详情。 */
+interface StartupPluginErrorDetails {
+    /** 插件标识。 */
+    readonly pluginId: string;
+    /** 失败单元。 */
+    readonly unitId?: string;
+    /** 声明提供的 capability。 */
+    readonly capabilities: readonly CapabilityDescriptor[];
+    /** 当前状态。 */
+    readonly state: PluginStateKind;
+    /** 脱敏错误。 */
+    readonly error?: string;
+}
+/** 插件定义：静态 manifest 与当前 realm setup 分离。 */
+interface PluginDefinition<TProvides extends readonly Capability[] = readonly Capability[], TDependencies extends readonly CapabilityDependency[] = readonly CapabilityDependency[], TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> {
+    /** 不含函数的静态描述。 */
+    readonly manifest: PluginManifest<TContribution, TConfig>;
+    /** 当前实现绑定的单元描述。 */
+    readonly descriptor: RuntimeUnitDescriptor<TContribution, TConfig>;
+    /** 当前 realm 的 setup。 */
+    readonly setup: PluginSetup<TProvides, TDependencies, TConfig, TExtension>;
+    /** 当前 realm 使用的完整 capability 对象集合。 */
+    readonly capabilities: readonly Capability[];
+}
+/** 插件运行单元实现。 */
+type PluginSetup<TProvides extends readonly Capability[] = readonly Capability[], TDependencies extends readonly CapabilityDependency[] = readonly CapabilityDependency[], TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> = (ctx: PluginContext<TProvides, TDependencies, TConfig, TExtension>) => void | Promise<void> | PluginTeardown | Promise<PluginTeardown>;
+/** 按插件/单元查找当前 realm 的 setup。 */
+interface RuntimeUnitImplementationRegistry {
+    /** 未注册实现时返回 undefined。 */
+    get(pluginId: string, unitId: string): PluginSetup | undefined;
+    /** 当前 realm 的 capability 定义表；静态 manifest 只含 descriptor。 */
+    getCapabilities?(pluginId: string, unitId: string): readonly Capability[] | undefined;
+}
+
+/** 作用域类型由宿主命名，框架只比较和调度。 */
+type LifecycleScopeKind = string;
+/** 作用域状态；stopping 已同步撤权，仍可能有异步清理。 */
+type LifecycleScopeState = "active" | "stopping" | "stopped";
+/** 浏览器中的真实 JavaScript Runtime。 */
+type RuntimeKind = "window-main" | "shared-worker";
+/** 权限动作名称。 */
+type PluginPermission = string;
+/** 一个作用域的不可替换身份绑定。 */
+interface LifecycleScopeIdentity<TAttributes extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+    /** 作用域唯一标识。 */
+    readonly scopeId: string;
+    /** 作用域所属实例；重建不得复用。 */
+    readonly instanceId: string;
+    /** 作用域类型。 */
+    readonly kind: LifecycleScopeKind;
+    /** 父作用域标识。 */
+    readonly parentScopeId?: string;
+    /** 绑定插件标识。 */
+    readonly pluginId?: string;
+    /** 宿主绑定的只读结构化属性。 */
+    readonly attributes: TAttributes;
+}
+/** 资源清理函数。 */
+type LifecycleCleanup = (reason: string) => void | Promise<void>;
+/** 清理阶段。 */
+type LifecycleCleanupPhase = "before-teardown" | "after-teardown";
+/** 作用域资源快照。 */
+interface LifecycleResourceSnapshot {
+    /** 资源唯一标识。 */
+    readonly resourceId: string;
+    /** 当前资源状态。 */
+    readonly state: "acquiring" | "active" | "released" | "pending";
+    /** 脱敏释放错误。 */
+    readonly error?: string;
+}
+/** 资源清理问题。 */
+interface LifecycleCleanupIssue {
+    /** 资源标识。 */
+    readonly resourceId: string;
+    /** 清理失败或超时。 */
+    readonly code: "lifecycle.cleanup_failed" | "lifecycle.cleanup_timeout";
+    /** 脱敏错误信息。 */
+    readonly message: string;
+}
+/** 作用域停止结果。 */
+interface LifecycleDisposeResult {
+    /** 作用域标识。 */
+    readonly scopeId: string;
+    /** 终态。 */
+    readonly state: "stopped";
+    /** 尝试释放的数量。 */
+    readonly attempted: number;
+    /** 已完成释放的数量。 */
+    readonly released: number;
+    /** 仍在清理的资源。 */
+    readonly pending: readonly string[];
+    /** 所有清理错误。 */
+    readonly errors: readonly LifecycleCleanupIssue[];
+    /** 是否有未完成收尾。 */
+    readonly cleanupIncomplete: boolean;
+}
+/** 作用域停止选项。 */
+interface LifecycleDisposeOptions {
+    /** 每项清理最多等待的毫秒数。 */
+    readonly timeoutMs?: number;
+    /** 清理原因。 */
+    readonly reason?: string;
+    /** 领域 teardown。 */
+    readonly teardown?: LifecycleCleanup;
+    /** 超时项迟到成功的本地投影回调。 */
+    readonly onLateSuccess?: (resourceId: string, result?: LifecycleDisposeResult) => void;
+    /** 超时项迟到失败的本地投影回调。 */
+    readonly onLateFailure?: (resourceId: string, error: unknown, result?: LifecycleDisposeResult) => void;
+}
+/** 已登记资源的幂等释放句柄。 */
+interface LifecycleResourceHandle {
+    /** 资源标识。 */
+    readonly resourceId: string;
+    /** 是否已完成释放。 */
+    readonly released: boolean;
+    /** 释放资源。 */
+    release(reason?: string): Promise<void>;
+}
+/** 生命周期作用域。 */
+interface LifecycleScope {
+    /** 作用域身份。 */
+    readonly identity: LifecycleScopeIdentity;
+    /** 当前状态。 */
+    readonly state: LifecycleScopeState;
+    /** 撤权信号。 */
+    readonly signal: AbortSignal;
+    /** 订阅同步撤权。 */
+    onRevoke(listener: (reason: string) => void): () => void;
+    /** 登记异步清理。 */
+    onDispose(cleanup: LifecycleCleanup, resourceId?: string, phase?: LifecycleCleanupPhase): () => void;
+    /** 登记已有资源；返回原资源，释放通过 Scope 统一执行。 */
+    track<T>(resource: T, release: (resource: T, reason: string) => void | Promise<void>, resourceId?: string): T;
+    /** 异步创建并绑定资源；晚到资源会被撤销后立即清理。 */
+    acquire<T>(resourceId: string, create: (signal: AbortSignal) => T | Promise<T>, release: (resource: T, reason: string) => void | Promise<void>): Promise<T>;
+    /** 创建子作用域。 */
+    child(kind: LifecycleScopeKind, metadata?: Partial<Omit<LifecycleScopeIdentity, "scopeId" | "instanceId" | "kind" | "parentScopeId">>): LifecycleScope;
+    /** 同步撤权并阻止新资源。 */
+    revoke(reason?: string): void;
+    /** 异步清理全部资源。 */
+    dispose(options?: LifecycleDisposeOptions): Promise<LifecycleDisposeResult>;
+    /** 作用域不活跃时抛错。 */
+    assertActive(): void;
+    /** 资源快照。 */
+    resources(): readonly LifecycleResourceSnapshot[];
+    /** 绑定 DOM/EventTarget listener；revoke 时同步解绑。 */
+    listen(target: EventTarget, event: string, listener: EventListenerOrEventListenerObject, options?: AddEventListenerOptions | boolean): () => void;
+    /** 绑定同步 interval callback；revoke 时同步停止。 */
+    interval(callback: () => void, milliseconds: number): () => void;
+    /** 绑定一个 subscribe/unsubscribe 资源；revoke 时同步退订。 */
+    subscribe(subscribe: (listener: () => void) => () => void, listener: () => void): () => void;
+}
+/** 作用域已撤权。 */
+declare class LifecycleScopeRevokedError extends Error {
+    readonly code: "lifecycle.scope_revoked";
+    constructor(message?: string);
+}
+/** 权限租约已撤销或身份不匹配。 */
+declare class PermissionLeaseRevokedError extends Error {
+    readonly code: "permission.lease_revoked";
+    constructor(message?: string);
+}
+/** 权限未获可信装配批准。 */
+declare class PermissionDeniedError extends Error {
+    readonly code: "permission.denied";
+    readonly permission: PluginPermission;
+    constructor(permission: PluginPermission, message?: string);
+}
+/** 权限租约的不可变绑定。 */
+interface PermissionLeaseBinding extends LifecycleScopeIdentity {
+    /** 插件申请的权限。 */
+    readonly requested: readonly PluginPermission[];
+    /** 可信策略批准的权限。 */
+    readonly approved: readonly PluginPermission[];
+    /** 当前会话限制。 */
+    readonly sessionConstraints?: readonly PluginPermission[];
+    /** 策略修订。 */
+    readonly policyRevision?: number;
+    /** 用户授权修订。 */
+    readonly grantRevision?: number;
+    /** 外部授权标识。 */
+    readonly grantId?: string;
+}
+/** 最终边界比较的租约期望。 */
+type PermissionLeaseBindingExpectation = Partial<Pick<LifecycleScopeIdentity, "pluginId" | "instanceId">> & {
+    attributes?: Readonly<Record<string, unknown>>;
+} & Partial<Pick<PermissionLeaseBinding, "policyRevision" | "grantRevision" | "grantId">>;
+/** 权限租约。 */
+interface PermissionLease {
+    readonly binding: PermissionLeaseBinding;
+    readonly revoked: boolean;
+    /** 是否拥有权限。 */
+    has(permission: PluginPermission): boolean;
+    /** 断言权限。 */
+    assert(permission: PluginPermission): void;
+    /** 断言身份。 */
+    assertBinding(expected: PermissionLeaseBindingExpectation): void;
+    /** 撤销租约。 */
+    revoke(reason?: string): void;
+}
+/** 紧凑 Runtime 服务目录项；不重复外层 Runtime 身份和状态。 */
+interface RuntimeServiceSnapshot {
+    /** 服务形态。 */
+    kind: "rpc" | "stream";
+    /** capability 标识。 */
+    capabilityId: string;
+    /** 精确契约版本。 */
+    contractVersion: string;
+    /** exposure 身份。 */
+    serviceInstanceId: string;
+    /** 无环公开属性。 */
+    attributes: Readonly<Record<string, unknown>>;
+    /** 可选授权标识。 */
+    grantId?: string;
+    /** 授权修订。 */
+    authorizationRevision?: number;
+}
+/** Runtime 完整目录快照。 */
+interface RuntimeSnapshot {
+    /** 固定协议版本。 */
+    protocolVersion: string;
+    /** Runtime 逻辑标识。 */
+    runtimeId: string;
+    /** 真实 Runtime 类型。 */
+    runtimeKind: RuntimeKind;
+    /** Runtime 一次启动身份。 */
+    runtimeInstanceId: string;
+    /** 当前 peer 的投影修订。 */
+    revision: number;
+    /** Runtime 状态。 */
+    state: "starting" | "ready" | "stopping" | "failed" | "disposed";
+    /** 单元状态。 */
+    units: readonly {
+        /** 插件标识。 */
+        pluginId: string;
+        /** 单元标识。 */
+        unitId: string;
+        /** 真实 Runtime。 */
+        runtime: RuntimeKind;
+        /** 启动实例。 */
+        instanceId?: string;
+        /** 单元状态。 */
+        state: PluginStateKind;
+    }[];
+    /** ready 时仅发布当前可调用服务。 */
+    services: readonly RuntimeServiceSnapshot[];
+}
+/**
+ * Runtime/transport 的可信资源预算。
+ *
+ * 这些值只允许由 Runtime 装配层收紧，不能由 wire 或普通插件扩大。
+ * 省略的字段使用 WebLoom v4 的默认预算；不存在 Infinity/无限预算。
+ */
+interface RuntimeLimits {
+    /** 每个 Runtime 可接入的最大 peer 数。 */
+    readonly maxPeers: number;
+    /** 每个 peer、每个方向可等待的最大 call 数。 */
+    readonly maxPendingCallsPerPeer: number;
+    /** 每个 Runtime、每个方向可等待的最大 call 数。 */
+    readonly maxPendingCallsPerRuntime: number;
+    /** 每个 peer、每个方向的最大活动 stream 数。 */
+    readonly maxActiveStreamsPerPeer: number;
+    /** 每个 Runtime、每个方向的最大活动 stream 数。 */
+    readonly maxActiveStreamsPerRuntime: number;
+    /** 每个 peer 可保留的未完成执行槽数。 */
+    readonly maxExecutionSlotsPerPeer: number;
+    /** 每个 Runtime 可保留的未完成执行槽数。 */
+    readonly maxExecutionSlotsPerRuntime: number;
+    /** 单条消息的确定性 DTO 预算。 */
+    readonly maxMessageBudgetBytes: number;
+    /** 每个 peer、每个方向的保留载荷预算。 */
+    readonly maxRetainedPayloadBytesPerPeer: number;
+    /** 每个 Runtime、每个方向的保留载荷预算。 */
+    readonly maxRetainedPayloadBytesPerRuntime: number;
+    /** 单个 snapshot 的 unit 上限。 */
+    readonly maxSnapshotUnits: number;
+    /** 单个 snapshot 的 service 上限。 */
+    readonly maxSnapshotServices: number;
+    /** 单条 DTO 图的最大深度。 */
+    readonly maxDtoDepth: number;
+    /** 单条 DTO 图的唯一对象节点上限。 */
+    readonly maxDtoNodes: number;
+    /** 单条 DTO 图的引用边/字段槽位上限。 */
+    readonly maxDtoEdges: number;
+    /** 单个 transfer extractor 原始返回列表上限。 */
+    readonly maxTransferEntries: number;
+    /** 去重后的 transfer 总数上限。 */
+    readonly maxTransfers: number;
+    /** 去重后的 MessagePort 数量上限。 */
+    readonly maxMessagePorts: number;
+    /** stream credit/push 队列窗口上限。 */
+    readonly maxStreamCredit: number;
+}
+/** 快照应用结果。 */
+type SnapshotApplyResult = {
+    accepted: true;
+    state: "empty" | "ready" | "stale";
+    revision: number;
+} | {
+    accepted: false;
+    reason: "stale-revision" | "protocol-mismatch" | "invalid-snapshot" | "disposed";
+    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 FrameworkErrorPhase = "validate" | "wait" | "dispatch" | "execute" | "receive" | "dispose";
+/** 脱敏错误上下文。 */
+interface FrameworkErrorContext {
+    /** capability 标识。 */
+    capabilityId?: string;
+    /** Runtime 启动身份。 */
+    runtimeInstanceId?: string;
+    /** service exposure 身份。 */
+    serviceInstanceId?: string;
+}
+/** WebLoom v4 统一错误入口。 */
+declare class WebLoomError extends Error {
+    readonly code: FrameworkErrorCode;
+    readonly phase: FrameworkErrorPhase;
+    readonly context?: Readonly<FrameworkErrorContext>;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: FrameworkErrorCode, message: string, phase?: FrameworkErrorPhase, context?: FrameworkErrorContext, details?: Readonly<Record<string, unknown>>);
+}
+/** 升级切换模式。 */
+type UpgradeMode = "cold-switch" | "two-phase";
+/** 升级门禁状态。 */
+type UpgradeGateState = "active" | "draining" | "closed";
+/** 新旧构建接管握手。 */
+interface UpgradeHandshake {
+    /** 真实连接标识。 */
+    connectionId: string;
+    /** 控制协议版本。 */
+    protocolVersion: string;
+    /** 构建标识。 */
+    buildId: string;
+    /** 权威实例。 */
+    authorityInstanceId: string;
+    /** 接管世代。 */
+    handoverGeneration: number;
+    /** 支持的精确契约版本。 */
+    supportedContractVersions: readonly string[];
+}
+/** 握手结果。 */
+type UpgradeHandshakeResult = {
+    accepted: true;
+    mode: UpgradeMode;
+    handoverGeneration: number;
+    contractVersion: string;
+    connectionId: string;
+    sessionId: string;
+    session: UpgradeSession;
+} | {
+    accepted: false;
+    reason: "protocol-mismatch" | "build-incompatible" | "stale-generation" | "future-generation" | "contract-mismatch" | "draining" | "closed";
+};
+/** I/O 租约。 */
+interface UpgradeIoLease {
+    readonly connectionId: string;
+    readonly sessionId: string;
+    readonly authorityInstanceId: string;
+    readonly handoverGeneration: number;
+    readonly contractVersion: string;
+    readonly operation: "read" | "write";
+    readonly revoked: boolean;
+    readonly signal: AbortSignal;
+    assertActive(): void;
+    release(): void;
+}
+/** 已握手会话。 */
+interface UpgradeSession {
+    readonly connectionId: string;
+    readonly sessionId: string;
+    readonly authorityInstanceId: string;
+    readonly handoverGeneration: number;
+    readonly contractVersion: string;
+    readonly revoked: boolean;
+    readonly signal: AbortSignal;
+    assertActive(): void;
+    admit(input: {
+        operation: "read" | "write";
+        signal?: AbortSignal;
+    }): UpgradeIoLease;
+    close(reason?: string): void;
+}
+/** 排空结果。 */
+interface UpgradeDrainResult {
+    readonly state: UpgradeGateState;
+    readonly drained: boolean;
+    readonly pending: number;
+}
+/** 升级门禁参数。 */
+interface CreateUpgradeGateOptions {
+    readonly protocolVersion: string;
+    readonly buildId: string;
+    readonly authorityInstanceId: string;
+    readonly handoverGeneration: number;
+    readonly supportedContractVersions: readonly string[];
+    readonly mode?: UpgradeMode;
+    readonly compatibleBuildIds?: ReadonlySet<string>;
+    readonly isBuildCompatible?: (buildId: string) => boolean;
+}
+/** 升级门禁。 */
+interface UpgradeGate {
+    readonly state: UpgradeGateState;
+    readonly mode: UpgradeMode;
+    readonly authorityInstanceId: string;
+    readonly handoverGeneration: number;
+    handshake(input: UpgradeHandshake): UpgradeHandshakeResult;
+    assertAccepting(): void;
+    admit(input: {
+        session: UpgradeSession;
+        operation: "read" | "write";
+        signal?: AbortSignal;
+    }): UpgradeIoLease;
+    beginDrain(reason?: string): void;
+    drain(timeoutMs?: number): Promise<UpgradeDrainResult>;
+    close(reason?: string): void;
+    activeIo(): number;
+}
+/** 升级门禁拒绝。 */
+declare class UpgradeGateRejectedError extends Error {
+    readonly code: "upgrade.gate_rejected";
+    readonly reason: string;
+    constructor(reason: string, message?: string);
+}
+/** 插件启停绝对意图命令。 */
+interface PluginIntentCommand {
+    readonly commandId: string;
+    readonly authorityInstanceId: string;
+    readonly expectedRevision: number;
+    readonly pluginId: string;
+    readonly desiredEnabled: boolean;
+}
+/** 插件启停意图快照。 */
+interface PluginIntentSnapshot {
+    readonly revision: number;
+    readonly desiredEnabled: Readonly<Record<string, boolean>>;
+    readonly desiredRevision: Readonly<Record<string, number>>;
+}
+/** 意图持久化结果。 */
+type PluginIntentCommandResult = {
+    status: "accepted" | "duplicate";
+    commandId: string;
+    snapshot: PluginIntentSnapshot;
+    persisted: true;
+} | {
+    status: "stale-authority";
+    commandId: string;
+    expectedAuthorityInstanceId: string;
+} | {
+    status: "command-conflict";
+    commandId: string;
+    message: string;
+} | {
+    status: "revision-conflict";
+    commandId: string;
+    snapshot: PluginIntentSnapshot;
+} | {
+    status: "persistence-failed";
+    commandId: string;
+    message: string;
+    snapshot: PluginIntentSnapshot;
+};
+/** Host 提交意图的完整结果。 */
+type PluginIntentSubmissionResult = PluginIntentCommandResult | {
+    status: "transport-error";
+    message: string;
+    retryable: boolean;
+};
+/** 单一启停控制面。 */
+interface PluginIntentController {
+    readonly authorityInstanceId: string;
+    snapshot(): PluginIntentSnapshot;
+    submit(command: PluginIntentCommand): Promise<PluginIntentCommandResult>;
+    subscribe(listener: (snapshot: PluginIntentSnapshot) => void): () => void;
+}
+/** Host 接入的启停控制面。 */
+interface PluginIntentCoordinator {
+    readonly authorityInstanceId: string;
+    snapshot(): PluginIntentSnapshot;
+    submit(command: PluginIntentCommand): Promise<PluginIntentSubmissionResult>;
+    subscribe(listener: (snapshot: PluginIntentSnapshot) => void): () => void;
+}
+/** scoped 后台任务定义。 */
+interface ScopedTaskDefinition {
+    readonly id: string;
+    readonly pluginId?: string;
+    readonly label: string;
+    readonly intervalMs?: number;
+    run(context: {
+        signal: AbortSignal;
+        reason: string;
+    }): void | Promise<void>;
+}
+/** 任务快照。 */
+interface ScopedTaskSnapshot {
+    readonly id: string;
+    readonly pluginId: string;
+    readonly label: string;
+    readonly state: "idle" | "queued" | "running" | "failed";
+    readonly error?: string;
+    readonly lastCompletedAt?: string;
+    readonly nextRunAt?: string;
+}
+/** scoped 任务调度器。 */
+interface ScopedTaskScheduler {
+    register(definition: ScopedTaskDefinition): () => void;
+    runNow(id: string, reason?: string): Promise<void>;
+    cancel(id: string): Promise<void>;
+    snapshot(): readonly ScopedTaskSnapshot[];
+    subscribe(listener: (snapshot: readonly ScopedTaskSnapshot[]) => void): () => void;
+}
+/** 内建任务调度器 capability 的保留静态标识。 */
+declare const SCOPED_TASK_SCHEDULER_CAPABILITY = "runtime.task-scheduler";
+/** 生命周期稳定错误文案。 */
+declare const LIFECYCLE_ERROR_TEXT: Readonly<Record<string, string>>;
+/** 将生命周期错误码映射为中文提示。 */
+declare function lifecycleErrorText(code: string): string;
+
+/** 验证 unknown 并返回领域类型的生产 parser。 */
+interface ValueParser<T> {
+    /** 验证 unknown；失败必须抛出校验错误。 */
+    parse(value: unknown): T;
+}
+/** 从已经通过 parser 的值中提取可转移资源。 */
+type TransferExtractor<T> = (value: T) => readonly Transferable[];
+/** RPC 请求与结果的契约级 transfer 声明。 */
+interface RpcTransferDescriptor<TRequest, TResponse> {
+    /** 从规范化请求中提取可转移资源。 */
+    readonly request?: TransferExtractor<TRequest>;
+    /** 从规范化结果中提取可转移资源。 */
+    readonly response?: TransferExtractor<TResponse>;
+}
+/** stream 订阅请求与 item 的契约级 transfer 声明。 */
+interface StreamTransferDescriptor<TRequest, TItem> {
+    /** 从规范化订阅请求中提取可转移资源。 */
+    readonly request?: TransferExtractor<TRequest>;
+    /** 从规范化 item 中提取可转移资源。 */
+    readonly item?: TransferExtractor<TItem>;
+}
+type CapabilityKind = "local" | "rpc" | "stream";
+/** 可序列化的 capability 身份；不包含 parser、transfer 或 handler。 */
+interface CapabilityDescriptor {
+    /** capability 行为形态。 */
+    readonly kind: CapabilityKind;
+    /** 稳定业务标识。 */
+    readonly id: string;
+    /** 精确业务契约版本。 */
+    readonly version: string;
+}
+declare const localServiceType: unique symbol;
+declare const rpcRequestType: unique symbol;
+declare const rpcResponseType: unique symbol;
+declare const streamRequestType: unique symbol;
+declare const streamItemType: unique symbol;
+/** local capability；只在同一 realm 提供/消费，不可远程调用。 */
+interface LocalCapability<TService = unknown> extends CapabilityDescriptor {
+    readonly kind: "local";
+    readonly [localServiceType]?: TService;
+}
+/** RPC capability 的非泛型形状；用于跨不同请求/结果类型的内部集合。 */
+interface RpcCapabilityBase extends CapabilityDescriptor {
+    /** 固定 RPC kind。 */
+    readonly kind: "rpc";
+}
+/** stream capability 的非泛型形状；用于跨不同请求/item 类型的内部集合。 */
+interface StreamCapabilityBase extends CapabilityDescriptor {
+    /** 固定 stream kind。 */
+    readonly kind: "stream";
+}
+/** typed unary RPC capability。 */
+interface RpcCapability<TRequest, TResponse> extends RpcCapabilityBase {
+    readonly kind: "rpc";
+    /** 请求边界 parser。 */
+    readonly request: ValueParser<TRequest>;
+    /** 结果边界 parser。 */
+    readonly response: ValueParser<TResponse>;
+    /** 请求/结果资源所有权声明。 */
+    readonly transfer?: RpcTransferDescriptor<TRequest, TResponse>;
+    readonly [rpcRequestType]?: TRequest;
+    readonly [rpcResponseType]?: TResponse;
+}
+/** typed back-pressure stream capability。 */
+interface StreamCapability<TRequest, TItem> extends StreamCapabilityBase {
+    readonly kind: "stream";
+    /** 订阅请求边界 parser。 */
+    readonly request: ValueParser<TRequest>;
+    /** item 边界 parser。 */
+    readonly item: ValueParser<TItem>;
+    /** item 资源所有权声明。 */
+    readonly transfer?: StreamTransferDescriptor<TRequest, TItem>;
+    readonly [streamRequestType]?: TRequest;
+    readonly [streamItemType]?: TItem;
+}
+type RemoteCapability = RpcCapabilityBase | StreamCapabilityBase;
+type Capability = LocalCapability<unknown> | RpcCapabilityBase | StreamCapabilityBase;
+type RequestOf<C extends Capability> = C extends RpcCapability<infer TRequest, infer _TResponse> ? TRequest : C extends StreamCapability<infer TRequest, infer _TItem> ? TRequest : never;
+type ResponseOf<C extends Capability> = C extends RpcCapability<infer _TRequest, infer TResponse> ? TResponse : never;
+type ItemOf<C extends Capability> = C extends StreamCapability<infer _TRequest, infer TItem> ? TItem : never;
+type LocalServiceOf<C extends Capability> = C extends LocalCapability<infer TService> ? TService : never;
+/** 单次调用的公开选项；callId 由框架生成，operationId 由产品传入。 */
+interface RpcCallOptions {
+    /** 调用方撤销信号。 */
+    readonly signal?: AbortSignal;
+    /** 从本次 call 开始计算的总截止时间预算。 */
+    readonly timeoutMs?: number;
+    /** 产品审计/幂等标识；框架不自动去重或重放。 */
+    readonly operationId?: string;
+}
+/** typed unary 客户端。 */
+interface RpcClient<C extends RpcCapabilityBase> {
+    /** 使用 capability parser 约束请求和结果。 */
+    call(request: RequestOf<C>, options?: RpcCallOptions): Promise<ResponseOf<C>>;
+}
+/** stream 订阅选项。 */
+interface StreamSubscribeOptions<TItem> extends RpcCallOptions {
+    /** 每个 item 交付完成后才归还一个 credit。 */
+    readonly onNext: (item: TItem) => void | Promise<void>;
+    /** 初始窗口；默认 16，最大 256。 */
+    readonly initialCredit?: number;
+}
+/** 一个 typed stream 的本端生命周期。 */
+interface StreamSubscription<TItem> {
+    /** 远端已建立订阅并发送 streamReady 后 resolve。 */
+    readonly ready: Promise<void>;
+    /** 正常 done 时 resolve，错误/撤销时 reject。 */
+    readonly closed: Promise<void>;
+    /** 幂等取消；立即阻止本地新 item 回调。 */
+    cancel(reason?: string): void;
+}
+/** typed stream 客户端。 */
+interface StreamClient<C extends StreamCapabilityBase> {
+    /** 建立一个有界 credit 的订阅。 */
+    subscribe(request: RequestOf<C>, options: StreamSubscribeOptions<ItemOf<C>>): StreamSubscription<ItemOf<C>>;
+}
+/** 按 capability 形态推导消费端返回值。 */
+type CapabilityClient<C extends Capability> = C extends LocalCapability<infer TService> ? TService : C extends RpcCapabilityBase ? RpcClient<Extract<C, RpcCapabilityBase>> : C extends StreamCapabilityBase ? StreamClient<Extract<C, StreamCapabilityBase>> : never;
+/** handler 调用来源。 */
+type HandlerOrigin = "local" | "remote";
+/** 普通 handler 可见的 peer 作用域视图；不含任何管理/创建方法。 */
+interface PeerScopeView {
+    /** 当前连接作用域状态。 */
+    readonly state: "active" | "stopping" | "stopped";
+    /** 连接撤销信号。 */
+    readonly signal: AbortSignal;
+    /** 订阅连接撤销；返回函数只能取消本次监听。 */
+    onRevoke(listener: (reason: string) => void): () => void;
+}
+/** 服务绑定身份；由框架创建，不能从 request 覆盖。 */
+interface ServiceReference {
+    /** capability 行为形态。 */
+    readonly kind: "rpc" | "stream";
+    /** 稳定 capability 标识。 */
+    readonly capabilityId: string;
+    /** 精确契约版本。 */
+    readonly contractVersion: string;
+    /** 提供者真实 Runtime。 */
+    readonly runtime: "window-main" | "shared-worker";
+    /** 提供者 Runtime 一次启动身份。 */
+    readonly runtimeInstanceId: string;
+    /** 一次 exposure 身份；撤销后永不复用。 */
+    readonly serviceInstanceId: string;
+    /** 已复制/冻结的无环公开属性。 */
+    readonly attributes: Readonly<Record<string, unknown>>;
+    /** 可选领域授权标识；不是认证凭据。 */
+    readonly grantId?: string;
+    /** 授权策略修订。 */
+    readonly authorizationRevision?: number;
+}
+/** 远程调用的绑定对端只读视图。 */
+interface CapabilityPeer {
+    /** 对端连接的不可复用身份。 */
+    readonly peerId: string;
+    /** 已观察到的对端 Runtime 类型；首个快照前为空。 */
+    readonly runtime?: RuntimeKind;
+    /** 已观察到的对端 Runtime 一次启动身份；首个快照前为空。 */
+    readonly runtimeInstanceId?: string;
+    /** 对端连接 Scope。 */
+    readonly scope: PeerScopeView;
+    /** 获取当前 peer 上的 typed 能力。 */
+    capability<C extends RemoteCapability>(capability: C): CapabilityClient<C>;
+}
+/** 插件的 typed capability 依赖；静态清单只保存 capabilityDescriptor。 */
+interface CapabilityDependencyMetadata {
+    /** 缺失时只关闭局部功能。 */
+    readonly optional?: boolean;
+    /** 面向诊断的依赖说明。 */
+    readonly reason?: string;
+}
+/** 当前 Runtime（或明确的另一个 Runtime）的依赖。 */
+type RuntimeCapabilityDependency<C extends Capability = Capability> = CapabilityDependencyMetadata & {
+    /** 要求的 capability 对象。 */
+    readonly capability: C;
+    /** 跨 Runtime 的精确来源；省略表示当前 Runtime。 */
+    readonly sourceRuntime?: RuntimeKind;
+    /** 与 peer 来源互斥。 */
+    readonly source?: never;
+};
+/** 按一次远程调用解析的 peer 依赖；不进入全局启动依赖图。 */
+type PeerCapabilityDependency<C extends RemoteCapability = RemoteCapability> = CapabilityDependencyMetadata & {
+    /** 要求的远程 capability 对象。 */
+    readonly capability: C;
+    /** 能力来自当前调用绑定的 peer。 */
+    readonly source: "peer";
+    /** peer 依赖不能伪装成固定 Runtime 依赖。 */
+    readonly sourceRuntime?: never;
+};
+/** 插件 typed capability 依赖；source 与 sourceRuntime 不能同时出现。 */
+type CapabilityDependency<C extends Capability = Capability> = C extends LocalCapability<unknown> ? RuntimeCapabilityDependency<C> : RuntimeCapabilityDependency<C> | PeerCapabilityDependency<Extract<C, RemoteCapability>>;
+/** 远程 capability bridge 的最小内部/advanced 契约。 */
+interface CapabilityBridge {
+    /** 当前连接状态。 */
+    readonly state: "empty" | "ready" | "stale" | "disposed";
+    /** 当前连接的远端 Runtime 身份。 */
+    readonly runtimeInstanceId?: string;
+    /** 当前已观察到的对端 Runtime 类型；快照到达前为空。 */
+    readonly runtimeKind?: RuntimeKind;
+    /** 取惰性 typed client；没有服务时不在此处同步失败。 */
+    getClient<C extends RemoteCapability>(capability: C, scope?: LifecycleScope): CapabilityClient<C>;
+    /** 应用一个完整对端目录。 */
+    applySnapshot(snapshot: RuntimeSnapshot): SnapshotApplyResult;
+    /** 同步撤销全部旧代理。 */
+    invalidate(reason?: string): void;
+    /** 连接断开；旧代理永久失效。 */
+    disconnect(reason?: string): void;
+    /** 永久销毁 bridge。 */
+    dispose(reason?: string): void;
+    /** 订阅目录/连接状态变化。 */
+    subscribe(listener: () => void): () => void;
+    /** 当前已发布的完整服务引用。 */
+    services(): readonly ServiceReference[];
+}
+/** handler 收到的框架绑定调用上下文。 */
+interface HandlerCallContext {
+    /** 取消信号。 */
+    readonly signal: AbortSignal;
+    /** 调用总截止时间的 epoch 毫秒值。 */
+    readonly deadlineAt: number;
+    /** 产品操作 ID。 */
+    readonly operationId?: string;
+    /** 当前服务 exposure 身份。 */
+    readonly reference: ServiceReference;
+    /** 调用来源。 */
+    readonly origin: HandlerOrigin;
+    /** 远程调用的框架绑定对端；local 调用必为 undefined。 */
+    readonly peer?: CapabilityPeer;
+}
+type RpcHandler<C extends RpcCapabilityBase> = (request: RequestOf<C>, call: HandlerCallContext) => ResponseOf<C> | Promise<ResponseOf<C>>;
+type StreamHandler<C extends StreamCapabilityBase> = (request: RequestOf<C>, call: HandlerCallContext) => AsyncIterable<ItemOf<C>> | Promise<AsyncIterable<ItemOf<C>>>;
+interface DefineLocalCapabilityOptions {
+    /** 固定 capability kind。 */
+    readonly kind: "local";
+    /** 非空业务标识。 */
+    readonly id: string;
+    /** 非空业务契约版本。 */
+    readonly version: string;
+}
+interface DefineRpcCapabilityOptions<TRequest, TResponse> {
+    /** 固定 capability kind。 */
+    readonly kind: "rpc";
+    /** 非空业务标识。 */
+    readonly id: string;
+    /** 非空业务契约版本。 */
+    readonly version: string;
+    /** 请求 parser。 */
+    readonly request: ValueParser<TRequest>;
+    /** 结果 parser。 */
+    readonly response: ValueParser<TResponse>;
+    /** 契约级 transfer。 */
+    readonly transfer?: RpcTransferDescriptor<TRequest, TResponse>;
+}
+interface DefineStreamCapabilityOptions<TRequest, TItem> {
+    /** 固定 capability kind。 */
+    readonly kind: "stream";
+    /** 非空业务标识。 */
+    readonly id: string;
+    /** 非空业务契约版本。 */
+    readonly version: string;
+    /** 订阅请求 parser。 */
+    readonly request: ValueParser<TRequest>;
+    /** item parser。 */
+    readonly item: ValueParser<TItem>;
+    /** 契约级 transfer。 */
+    readonly transfer?: StreamTransferDescriptor<TRequest, TItem>;
+}
+/** 定义 local capability；local 不携带 wire parser，也不能跨 Runtime。 */
+declare function defineCapability<TService>(options: DefineLocalCapabilityOptions): LocalCapability<TService>;
+/** 定义 typed unary RPC；request/response parser 是强制边界。 */
+declare function defineCapability<TRequest, TResponse>(options: DefineRpcCapabilityOptions<TRequest, TResponse>): RpcCapability<TRequest, TResponse>;
+/** 定义 typed stream；request/item parser 是强制边界。 */
+declare function defineCapability<TRequest, TItem>(options: DefineStreamCapabilityOptions<TRequest, TItem>): StreamCapability<TRequest, TItem>;
+/** 产生不含函数的静态 capability DTO。 */
+declare function capabilityDescriptor(capability: Capability): CapabilityDescriptor;
+/** 计算契约身份键；只用于 Host/目录内部比较。 */
+declare function capabilityKey(capability: CapabilityDescriptor): string;
+/** 运行时校验静态 capability DTO。 */
+declare function isCapabilityDescriptor(value: unknown): value is CapabilityDescriptor;
+/** 运行时校验 realm 内 capability 对象。 */
+declare function isCapability(value: unknown): value is Capability;
+/** capability 不合法时抛出统一错误。 */
+declare function assertCapability(value: unknown): asserts value is Capability;
+
+/** 资源键：稳定、可比较且不含秘密的字符串元组。 */
+type ResourceKey = readonly [resourceId: string, ...parts: readonly string[]];
+/** 资源当前状态。 */
+type ResourceStatus = "pending" | "ready" | "stale" | "error" | "blocked";
+/** 资源快照：状态、数据、错误和单调修订。 */
+interface ResourceSnapshot<T> {
+    /** 资源键。 */
+    readonly key: ResourceKey;
+    /** 当前加载状态。 */
+    readonly status: ResourceStatus;
+    /** 当前数据；未 ready 时可以为空。 */
+    readonly data: T | undefined;
+    /** 稳定错误码和可展示错误信息。 */
+    readonly error?: {
+        readonly code: string;
+        readonly message: string;
+    };
+    /** 快照修订，每次有效变化递增。 */
+    readonly revision: number;
+}
+/** 资源读取上下文；只提供通用 capability 和宿主扩展属性。 */
+interface ResourceContext<TAttributes extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> {
+    /** 读取已注入的 capability；不存在时返回 undefined。 */
+    getCapability<T>(id: string): T | undefined;
+    /** 资源定义所属的插件实例标识；由注册表绑定，插件不能伪造。 */
+    readonly ownerId: string;
+    /** 宿主绑定的当前作用域属性；资源定义不能写入。 */
+    readonly attributes: TAttributes;
+}
+/** Runtime-only metadata used to bind a definition to an owner. */
+declare const RESOURCE_OWNER: unique symbol;
+type OwnedResourceDefinition = ResourceDefinition<unknown, readonly string[]> & {
+    readonly [RESOURCE_OWNER]?: string;
+};
+/** 资源定义：描述键、加载、失效订阅与比较方式。 */
+interface ResourceDefinition<T, TArgs extends readonly string[] = readonly string[]> {
+    /** 资源唯一标识。 */
+    readonly id: string;
+    /** 资源所依附的生命周期标签，由宿主解释。 */
+    readonly scope: string;
+    /** 生成资源键。 */
+    key(args: TArgs, context: ResourceContext): ResourceKey;
+    /** 加载资源数据；实现必须响应 signal。 */
+    load(args: TArgs, context: ResourceContext, signal: AbortSignal): Promise<T>;
+    /** 订阅失效事件；只表达失效，不直接改写快照。 */
+    subscribe?(args: TArgs, context: ResourceContext, invalidate: () => void): () => void;
+    /** 语义相等判断；返回 true 时不发布新数据快照。 */
+    equals?(previous: T | undefined, next: T | undefined): boolean;
+    /** 同一事件循环内是否合并失效通知。 */
+    readonly invalidation: "immediate" | "microtask";
+}
+/** 资源定义注册表。 */
+interface ResourceRegistry {
+    /** 注册资源定义。 */
+    register<T, TArgs extends readonly string[]>(definition: ResourceDefinition<T, TArgs>): void;
+    /** 注销资源定义。 */
+    unregister(id: string): void;
+    /** 查询资源定义。 */
+    get<T, TArgs extends readonly string[]>(id: string): ResourceDefinition<T, TArgs> | undefined;
+    /** 调试和宿主清理使用的定义标识。 */
+    _ids(): string[];
+}
+/** Host 内置的 typed Resource Registry capability。 */
+declare const RESOURCE_REGISTRY: LocalCapability<ResourceRegistry>;
+
+/** Resource Store 公共 API。 */
+interface ResourceStoreApi {
+    /** 确保资源已加载，并返回当前快照。 */
+    ensure<T>(definitionId: string, args: readonly string[]): ResourceSnapshot<T>;
+    /** 订阅资源变更。 */
+    subscribe(definitionId: string, args: readonly string[], callback: () => void): () => void;
+    /** 读取资源快照，不触发加载。 */
+    read<T>(definitionId: string, args: readonly string[]): ResourceSnapshot<T> | undefined;
+    /** 使资源失效并重新加载。 */
+    invalidate(definitionId: string, args: readonly string[]): void;
+    /** 清理指定 owner 的所有资源记录。 */
+    disposeOwner(ownerId: string): void;
+    /** 宿主属性或 capability 变化后刷新绑定。 */
+    refreshRuntimeBindings(): void;
+    /** 订阅宿主 Context 变化。 */
+    subscribeContext(callback: () => void): () => void;
+}
+type Attributes = Readonly<Record<string, unknown>>;
+/** 创建通用 Resource Store。 */
+declare function createResourceStore(registry: ResourceRegistry, getCapability: <T>(id: string) => T | undefined, getAttributes?: (ownerId?: string) => Attributes): ResourceStoreApi;
+
+/** Host 内部保存的 capability 注册。 */
+interface CapabilityRegistration {
+    /** realm 内 capability 对象。 */
+    readonly capability: Capability;
+    /** 提供该能力的插件实例。 */
+    readonly ownerId: string;
+    /** local 服务值。 */
+    readonly value?: unknown;
+    /** RPC/stream 显式 handler。 */
+    readonly handler?: unknown;
+    /** 提供者作用域。 */
+    readonly scope?: LifecycleScope;
+    /** 该 handler 允许通过 call.peer 观察的 capability 身份。 */
+    readonly peerDependencies?: readonly CapabilityDescriptor[];
+    /** 注册身份。 */
+    readonly reference: ServiceReference;
+}
+/** 能力 registry；不提供字符串或未约束泛型入口。 */
+interface CapabilityRegistry {
+    /** 注册 local value；重复契约身份会抛错。 */
+    provide<C extends LocalCapability<unknown>>(capability: C, value: LocalServiceOf<C>, ownerId?: string, scope?: LifecycleScope): void;
+    /** 注册 RPC handler。 */
+    handle<C extends RpcCapabilityBase>(capability: C, handler: RpcHandler<C>, ownerId: string, scope: LifecycleScope, reference: CapabilityRegistration["reference"], peerDependencies?: readonly CapabilityDescriptor[]): void;
+    /** 注册 stream handler。 */
+    stream<C extends StreamCapabilityBase>(capability: C, handler: StreamHandler<C>, ownerId: string, scope: LifecycleScope, reference: CapabilityRegistration["reference"], peerDependencies?: readonly CapabilityDescriptor[]): void;
+    /** 撤销指定 owner 的一项能力。 */
+    revoke(capability: Capability, ownerId?: string): void;
+    /** 获取 local value。 */
+    get<C extends LocalCapability<unknown>>(capability: C): LocalServiceOf<C>;
+    /** 获取注册记录。 */
+    registration(capability: Capability): CapabilityRegistration | undefined;
+    /** 当前契约身份是否存在。 */
+    has(capability: Capability): boolean;
+    /** 要求当前契约身份存在。 */
+    require(capability: Capability): CapabilityRegistration;
+    /** 当前注册身份 DTO。 */
+    descriptors(): readonly CapabilityDescriptor[];
+    /** 当前注册记录；仅供 advanced/runtime 适配。 */
+    registrations(): readonly CapabilityRegistration[];
+    /** 在当前 realm 调用一个已注册的 RPC handler。 */
+    invoke(capability: RemoteCapability, request: unknown, call: HandlerCallContext): Promise<unknown>;
+    /** 在当前 realm 建立一个已注册的 stream handler。 */
+    openStream(capability: StreamCapabilityBase, request: unknown, call: HandlerCallContext): Promise<AsyncIterable<unknown>>;
+}
+/** 创建一个拒绝重复契约和 owner 越权撤销的 registry。 */
+declare function createCapabilityRegistry(): CapabilityRegistry;
+/** 在 registry 记录中执行已判别的 handler；供 transport/provider 使用。 */
+declare function invokeCapabilityHandler(registration: CapabilityRegistration, request: unknown, context: HandlerCallContext): unknown | Promise<unknown>;
+
+interface PluginConfigStore {
+    /** 读取产品级绝对启停意图。 */
+    read(): Readonly<Record<string, boolean>>;
+    /** 写入一个产品的绝对启停意图。 */
+    setEnabled(pluginId: string, enabled: boolean): void;
+    /** 订阅外部控制面变化。 */
+    subscribe(listener: (snapshot: Readonly<Record<string, boolean>>) => void): () => void;
+}
+declare function createInMemoryPluginConfigStore(initial?: Readonly<Record<string, boolean>>, readOnly?: boolean): PluginConfigStore;
+interface PermissionPolicyInput {
+    /** 插件标识。 */
+    readonly pluginId: string;
+    /** 运行单元标识。 */
+    readonly unitId: string;
+    /** 当前 Scope 身份。 */
+    readonly identity: LifecycleScopeIdentity;
+    /** 清单申请的权限。 */
+    readonly requested: readonly PluginPermission[];
+}
+interface PermissionPolicyResult {
+    /** 可信批准集合；缺省时为 requested。 */
+    readonly approved?: readonly PluginPermission[];
+    /** 当前会话额外限制。 */
+    readonly sessionConstraints?: readonly PluginPermission[];
+    /** 租约绑定的策略/授权修订。 */
+    readonly binding?: Partial<Pick<PermissionLeaseBinding, "policyRevision" | "grantRevision" | "grantId">>;
+}
+interface ContextExtensionInput {
+    /** 插件标识。 */
+    readonly pluginId: string;
+    /** 单元标识。 */
+    readonly unitId: string;
+    /** 实例标识。 */
+    readonly instanceId: string;
+    /** 实例 Scope。 */
+    readonly scope: LifecycleScope;
+    /** 静态 manifest。 */
+    readonly manifest: PluginManifest;
+}
+interface ContributionAdapterInput {
+    /** 插件标识。 */
+    readonly pluginId: string;
+    /** 单元标识。 */
+    readonly unitId: string;
+    /** 实例标识。 */
+    readonly instanceId: string;
+    /** 实例 Scope。 */
+    readonly scope: LifecycleScope;
+    /** 产品贡献。 */
+    readonly contribution: unknown;
+    /** 静态 manifest。 */
+    readonly manifest: PluginManifest;
+}
+interface ContributionHandle {
+    /** 同步撤下入口。 */
+    revoke?(): void;
+    /** 异步收尾。 */
+    dispose?(): void | Promise<void>;
+}
+interface ContributionAdapter {
+    /** 适配器名称。 */
+    readonly name?: string;
+    /** 注册一份产品贡献。 */
+    register(input: ContributionAdapterInput): void | ContributionHandle | (() => void | Promise<void>) | Promise<void | ContributionHandle | (() => void | Promise<void>)>;
+}
+interface RuntimeUnitAvailabilityInput {
+    /** 插件标识。 */
+    readonly pluginId: string;
+    /** 单元标识。 */
+    readonly unitId: string;
+    /** 真实 Runtime。 */
+    readonly runtime: RuntimeKind;
+}
+interface RuntimeUnitAttributesInput extends RuntimeUnitAvailabilityInput {
+    /** 静态 manifest。 */
+    readonly manifest: PluginManifest;
+}
+type RuntimeUnitParentScopeInput = RuntimeUnitAttributesInput;
+interface RuntimeUnitSnapshot {
+    /** 插件标识。 */
+    readonly pluginId: string;
+    /** 单元标识。 */
+    readonly unitId: string;
+    /** Runtime。 */
+    readonly runtime: RuntimeKind;
+    /** 当前实例。 */
+    readonly instanceId?: string;
+    /** 状态。 */
+    readonly state: PluginStateKind;
+}
+interface HostCapabilityRegistration {
+    /** Host-owned capability。 */
+    readonly capability: LocalCapability<unknown>;
+    /** 对应服务值。 */
+    readonly value: unknown;
+}
+interface CreatePluginHostOptions {
+    /** 当前 Host 的真实 Runtime。 */
+    readonly runtime?: RuntimeKind;
+    /** Runtime 逻辑标识。 */
+    readonly runtimeId?: string;
+    /** Runtime 启动实例标识。 */
+    readonly runtimeInstanceId?: string;
+    /** 根 Scope 属性。 */
+    readonly rootAttributes?: Readonly<Record<string, unknown>>;
+    /** Host-owned local capability；不接受字符串键。 */
+    readonly capabilities?: ReadonlyMap<LocalCapability<unknown>, unknown> | readonly HostCapabilityRegistration[];
+    /** capabilities 的显式别名。 */
+    readonly builtinCapabilities?: ReadonlyMap<LocalCapability<unknown>, unknown> | readonly HostCapabilityRegistration[];
+    /** 共享 MessageBus。 */
+    readonly messageBus?: MessageBus;
+    /** 资源定义注册表。 */
+    readonly resourceRegistry?: ResourceRegistry;
+    /** 资源读取时的领域 capability resolver。 */
+    readonly resourceCapabilityResolver?: <T>(id: string) => T | undefined;
+    /** 领域 Context Extension。 */
+    readonly contextExtension?: (input: ContextExtensionInput) => Readonly<Record<string, unknown>>;
+    /** 清单额外校验。 */
+    readonly manifestValidator?: (manifest: PluginManifest) => void;
+    /** 权限策略。 */
+    readonly permissionPolicy?: (input: PermissionPolicyInput) => PermissionPolicyResult;
+    /** 启停配置。 */
+    readonly configStore?: PluginConfigStore;
+    /** 内存启停配置。 */
+    readonly initialPluginConfig?: Readonly<Record<string, boolean>>;
+    /** 外部启停控制面。 */
+    readonly pluginIntentCoordinator?: PluginIntentCoordinator;
+    /** 当前 Runtime 的 typed remote bridge。 */
+    readonly capabilityBridge?: CapabilityBridge;
+    /** 实现注册表。 */
+    readonly runtimeUnitImplementationRegistry?: RuntimeUnitImplementationRegistry;
+    /** 按 plugin/unit 提供当前 realm capability 定义。 */
+    readonly capabilityDefinitions?: ReadonlyMap<string, readonly Capability[]>;
+    /** Runtime 可用性检查。 */
+    readonly runtimeUnitAvailability?: (input: RuntimeUnitAvailabilityInput) => string | undefined;
+    /** 实例 Scope 属性。 */
+    readonly runtimeUnitAttributes?: (input: RuntimeUnitAttributesInput) => Readonly<Record<string, unknown>> | undefined;
+    /** 实例 Scope 父级。 */
+    readonly runtimeUnitParentScope?: (input: RuntimeUnitParentScopeInput) => LifecycleScope | undefined;
+    /** 贡献适配器。 */
+    readonly contributionAdapters?: readonly ContributionAdapter[];
+    /** 清理超时。 */
+    readonly lifecycleCleanupTimeoutMs?: number;
+    /** 外部 Runtime dependency 是否允许。 */
+    readonly externalRuntimeDependencies?: boolean;
+}
+declare class StartupCapabilityError extends Error {
+    readonly details: readonly StartupCapabilityErrorDetails[];
+    constructor(details: readonly StartupCapabilityErrorDetails[], phase?: string);
+}
+declare class StartupPluginError extends Error {
+    readonly details: {
+        readonly pluginId: string;
+        readonly unitId?: string;
+        readonly capabilities: readonly CapabilityDescriptor[];
+        readonly state: PluginStateKind;
+        readonly error?: string;
+    };
+    constructor(details: {
+        readonly pluginId: string;
+        readonly unitId?: string;
+        readonly capabilities: readonly CapabilityDescriptor[];
+        readonly state: PluginStateKind;
+        readonly error?: string;
+    });
+}
+/** 创建 v4 Host。 */
+declare function createPluginHost(options?: CreatePluginHostOptions): PluginHost;
+interface HostInspection {
+    /** Runtime 逻辑标识。 */
+    readonly runtimeId: string;
+    /** Runtime 类型。 */
+    readonly runtimeKind: RuntimeKind;
+    /** Runtime 启动实例。 */
+    readonly runtimeInstanceId: string;
+    /** Host 变化修订。 */
+    readonly version: number;
+    /** 已注册插件数。 */
+    readonly pluginCount: number;
+    /** 当前 peer 数；Host 本身不拥有远端 peer。 */
+    readonly peerCount: number;
+    /** 当前本地框架 pending 调用数。 */
+    readonly pendingCallCount: number;
+    /** 当前本地活动流数。 */
+    readonly activeStreamCount: number;
+    /** 插件状态。 */
+    readonly plugins: readonly PluginState[];
+}
+interface PluginHost {
+    /** v4 capability registry。 */
+    readonly capabilities: CapabilityRegistry;
+    /** 绑定到根 Scope 的 MessageBus。 */
+    readonly messageBus: MessageBus;
+    /** 资源定义注册表。 */
+    readonly resourceRegistry: ResourceRegistry;
+    /** 资源缓存 Store。 */
+    readonly resourceStore: ResourceStoreApi;
+    /** Host Runtime。 */
+    readonly runtimeKind: RuntimeKind;
+    /** Runtime 逻辑标识。 */
+    readonly runtimeId: string;
+    /** Runtime 启动实例。 */
+    readonly runtimeInstanceId: string;
+    /** 根 Scope。 */
+    readonly rootScope: LifecycleScope;
+    /** 根任务调度器。 */
+    readonly taskScheduler: ScopedTaskScheduler;
+    /** 已注册插件。 */
+    installed(): string[];
+    /** 已注册插件。 */
+    manifests(): string[];
+    /** 状态查询。 */
+    state(pluginId: string): PluginState;
+    /** 插件实例 Scope。 */
+    scope(pluginId: string): LifecycleScope | undefined;
+    /** 刷新 Host 观察修订。 */
+    refreshRuntimeUnitSnapshots(): void;
+    /** 协调启停。 */
+    reconcile(): Promise<void>;
+    /** 依赖图。 */
+    graph(): PluginGraph;
+    /** Host 观察修订。 */
+    version(): number;
+    /** Host 变化订阅。 */
+    subscribe(listener: HostListener): () => void;
+    /** manifest 查询。 */
+    getManifest(pluginId: string): PluginManifest | undefined;
+    /** 反向依赖查询。 */
+    reverseDeps(pluginId: string): readonly PluginReverseDep[];
+    /** manifest 集合校验。 */
+    validateManifestSet(manifests: readonly PluginManifest[]): void;
+    /** 显式 Host-owned local 注册。 */
+    provide<C extends LocalCapability<unknown>>(capability: C, value: LocalServiceOf<C>): void;
+    /** 注册插件。 */
+    register(manifest: PluginManifest): Promise<void>;
+    /** 批量注册插件。 */
+    registerAll(manifests: readonly PluginManifest[]): Promise<void>;
+    /** 启动插件。 */
+    enable(pluginId: string): Promise<void>;
+    /** 重试失败插件。 */
+    retry(pluginId: string): Promise<void>;
+    /** 提交启停意图。 */
+    submitIntent(pluginId: string, desiredEnabled: boolean): Promise<PluginIntentSubmissionResult>;
+    /** 停止插件及反向依赖者。 */
+    disable(pluginId: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** 撤销当前实例但保留启用意图。 */
+    suspend(pluginId: string, reason?: string): Promise<void>;
+    /** 删除插件。 */
+    unregister(pluginId: string): Promise<void>;
+    /** 释放 Host。 */
+    dispose(reason?: string): Promise<LifecycleDisposeResult>;
+    /** 启动前检查 local capability。 */
+    assertCapabilities(required: readonly CapabilityDescriptor[], options?: {
+        phase?: string;
+    }): void;
+    /** 当前可调用的 remote service 引用。 */
+    serviceReferences(): readonly ServiceReference[];
+    /** advanced/WindowApp 使用的 typed capability 获取。 */
+    capability<C extends Capability>(capability: C): CapabilityClient<C>;
+    /** 当前已存在的 typed capability。 */
+    optionalCapability<C extends Capability>(capability: C): CapabilityClient<C> | undefined;
+    /** 绑定一个 SharedWorker remote bridge。 */
+    attachRemote(bridge: CapabilityBridge): void;
+    /** 撤销当前 remote bridge。 */
+    detachRemote(reason?: string): void;
+    /** advanced 分阶段注册当前 realm implementation。 */
+    registerImplementation(implementation: {
+        readonly pluginId: string;
+        readonly unitId: string;
+        readonly setup: PluginSetup;
+        readonly capabilities?: readonly Capability[];
+    }): void;
+    /** 结构化诊断。 */
+    inspect(): HostInspection;
+    /** 解释插件或 capability。 */
+    explain(target: string | CapabilityDescriptor): {
+        readonly target: string;
+        readonly state?: PluginStateKind;
+        readonly reasons: readonly string[];
+    };
+}
+
+type RuntimeAppState = RuntimeSnapshot["state"] | "disconnected";
+interface RuntimeStatusSnapshot extends Omit<RuntimeSnapshot, "protocolVersion" | "state"> {
+    /** 当前框架协议。 */
+    readonly protocolVersion: string;
+    /** Runtime 当前状态。 */
+    readonly state: RuntimeAppState;
+    /** 脱敏 Runtime 错误。 */
+    readonly error?: string;
+}
+type RuntimeStatusListener = (snapshot: RuntimeStatusSnapshot) => void;
+interface AppLike {
+    /** Runtime 类型。 */
+    readonly runtimeKind: RuntimeKind;
+    /** Runtime 逻辑标识。 */
+    readonly runtimeId: string;
+    /** Runtime 启动实例。 */
+    readonly runtimeInstanceId: string;
+    /** 当前不可变状态。 */
+    state(): RuntimeStatusSnapshot;
+    /** 按插件读取稳定状态；RuntimeHandle 可能没有本地插件状态。 */
+    pluginState?(pluginId: string): PluginState | undefined;
+    /** 订阅状态。 */
+    subscribe(listener: RuntimeStatusListener): () => void;
+    /** 结构化诊断。 */
+    inspect(): HostInspection | Readonly<Record<string, unknown>>;
+    /** 释放本端资源。 */
+    dispose(reason?: string): Promise<LifecycleDisposeResult | void>;
+}
+interface WindowApp extends AppLike {
+    readonly runtimeKind: "window-main";
+    /** 获取本地 typed capability。 */
+    capability<C extends Capability>(capability: C): CapabilityClient<C>;
+    /** 可选本地 typed capability。 */
+    optionalCapability<C extends Capability>(capability: C): CapabilityClient<C> | undefined;
+}
+interface RuntimeHandle extends AppLike {
+    readonly runtimeKind: "shared-worker";
+    /** 获取远程 typed RPC/stream capability；代理构造不等待 Worker。 */
+    capability<C extends RemoteCapability>(capability: C): CapabilityClient<C>;
+    /** 当前已观察到的 remote capability。 */
+    optionalCapability<C extends RemoteCapability>(capability: C): CapabilityClient<C> | undefined;
+}
+declare class RuntimeInitializationError extends Error {
+    readonly code: "runtime_initialization_failed";
+    readonly details: {
+        readonly pluginId?: string;
+        readonly unitId?: string;
+        readonly phase: "validate" | "register" | "startup" | "snapshot";
+        readonly error: string;
+    };
+    constructor(details: {
+        readonly pluginId?: string;
+        readonly unitId?: string;
+        readonly phase: "validate" | "register" | "startup" | "snapshot";
+        readonly error: string;
+    });
+}
+declare class RuntimeUnavailableError extends Error {
+    readonly code: "transport_unavailable";
+    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 };