webloom-framework 0.1.0 → 0.3.0

package/dist/{createPluginHost-CcW9sPNs.d.ts → createPluginHost-BVsUCDKN.d.ts}

@@ -2,10 +2,8 @@
 type LifecycleScopeKind = string;
 /** 作用域状态；stopping 表示已撤权但异步收尾还未结束。 */
 type LifecycleScopeState = "active" | "stopping" | "stopped";
-/** 插件默认存活范围；名称由宿主定义，单次请求可由宿主派生。 */
-type PluginLifetime = string;
-/** 插件运行代码所在环境；名称由宿主定义。 */
-type PluginExecution = string;
+/** 浏览器中由 WebLoom 管理的真实 JavaScript 运行空间。 */
+type RuntimeKind = "window-main" | "shared-worker";
 /** 权限动作名称；权限集合和最终 I/O allowlist 由宿主定义。 */
 type PluginPermission = string;
 /** 一个运行作用域的身份绑定；敏感句柄必须带上这些字段。 */
@@ -172,68 +170,42 @@ interface PermissionLease {
 interface RemoteServiceReference {
     /** 服务契约标识。 */
     capabilityId: string;
-    /** 提供该服务的运行实例；实例重建后必须变化。 */
-    providerInstanceId: string;
-    /** 提供者所在执行环境。 */
-    execution: PluginExecution;
-    /** 服务契约版本；第一阶段要求精确匹配。 */
+    /** 要求精确匹配的服务契约版本。 */
     contractVersion: string;
+    /** 提供者所在真实 Runtime。 */
+    runtime: RuntimeKind;
     /** 提供环境的启动身份；重启后变化。 */
-    authorityInstanceId: string;
-    /** 提供者作用域身份。 */
-    scopeId: string;
-    /** 提供者所在 Coordinator 的升级接管世代；旧 Worker 引用不能跨世代使用。 */
-    handoverGeneration: number;
-    /** 宿主绑定的只读服务属性；服务桥不解释其业务含义。 */
-    attributes: Readonly<Record<string, unknown>>;
+    runtimeInstanceId: string;
+    /** 服务实例身份；撤销后永不复用。 */
+    serviceInstanceId: string;
     /** 当前服务目录状态。 */
     status: "starting" | "ready" | "unavailable" | "failed";
-    /** 当前权威目录流修订号。 */
-    snapshotRevision: number;
+    /** 宿主绑定的只读服务属性；服务桥不解释其业务含义。 */
+    attributes: Readonly<Record<string, unknown>>;
     /** 可选的外部授权标识；引用不是授权本身，Provider 仍需查权威状态。 */
     grantId?: string;
     /** 服务端授权策略修订；策略变化时旧引用必须失效。 */
     authorizationRevision?: number;
 }
-/** 服务桥握手输入；connectionId 必须由实际端口连接生成。 */
-interface RemoteServiceHandshake {
-    /** 当前端口 / MessagePort 连接标识。 */
-    connectionId: string;
-    /** 对端提供环境的启动身份。 */
-    authorityInstanceId: string;
-    /** 桥协议版本。 */
-    protocolVersion: string;
-}
-/** 一次服务目录基线或增量快照。 */
+/** 传给服务桥的完整目录快照；Runtime Host 是它的唯一权威发布者。 */
 interface RemoteServiceSnapshot {
-    /** 快照来自哪条端口连接。 */
-    connectionId: string;
-    /** 快照来自哪个权威启动身份。 */
-    authorityInstanceId: string;
-    /** 同一启动身份、同一订阅范围内单调递增。 */
-    snapshotRevision: number;
-    /** 是否为包含完整订阅范围的基线。 */
-    baseline: boolean;
-    /** 当前订阅范围内的服务引用。 */
+    /** 快照协议版本；解析成功但版本不匹配时不得当成可用目录。 */
+    protocolVersion: string;
+    /** 权威 Runtime 的逻辑标识；独立服务桥可省略。 */
+    runtimeId?: string;
+    /** 权威 Runtime 类型；独立服务桥可省略。 */
+    runtimeKind?: RuntimeKind;
+    /** 每次 Worker 启动唯一的 Runtime 身份。 */
+    runtimeInstanceId: string;
+    /** 当前完整目录修订；同一 Runtime 只接受严格递增值。 */
+    revision: number;
+    /** Runtime 当前状态。 */
+    state?: "starting" | "ready" | "stopping" | "failed" | "disposed";
+    /** 当前完整服务目录。 */
     services: readonly RemoteServiceReference[];
 }
-/** 服务桥在独立 MessagePort 上发送的控制消息。 */
-type RemoteServicePortControlMessage = {
-    /** 控制消息类型由 codec 绑定，核心不固定产品前缀。 */
-    type: string;
-    handshake: RemoteServiceHandshake;
-} | {
-    type: string;
-    snapshot: RemoteServiceSnapshot;
-} | {
-    type: string;
-    reason?: string;
-} | {
-    type: string;
-    reason?: string;
-};
-/** MessagePort 服务消息类别；具体字符串由 codec 统一编码。 */
-type RemoteServiceMessageKind = "call" | "result" | "error" | "cancel" | "handshake" | "snapshot" | "invalidate" | "disconnect";
+/** MessagePort 服务消息类别；codec 只承载调用生命周期。 */
+type RemoteServiceMessageKind = "call" | "result" | "error" | "cancel";
 /** 服务桥 wire codec；负责类型名、编解码和协议版本，不让传输层散落字符串判断。 */
 interface RemoteServiceMessageCodec {
     /** codec 对应的协议版本。 */
@@ -245,7 +217,7 @@ interface RemoteServiceMessageCodec {
     /** 将 wire 数据解码为对象；无效消息返回 undefined。 */
     decode(input: unknown): Record<string, unknown> | undefined;
 }
-/** 创建默认 WebLoom codec；产品可用同一工厂绑定旧协议前缀。 */
+/** 创建 WebLoom v2 codec；产品可以只替换 wire 前缀，不能恢复控制消息。 */
 declare function createRemoteServiceMessageCodec(options?: {
     prefix?: string;
     protocolVersion?: string;
@@ -256,84 +228,91 @@ interface RemoteServiceLookup {
     capabilityId: string;
     /** 要求的精确契约版本。 */
     contractVersion: string;
-    /** 可选的预期提供环境。 */
-    execution?: PluginExecution;
-    /** 可选的预期作用域。 */
-    scopeId?: string;
+    /** 可选的预期提供 Runtime。 */
+    runtime?: RuntimeKind;
 }
 /** 服务代理调用上下文；服务端必须在最终边界重新检查引用和租约。 */
 interface RemoteServiceCallContext {
     /** 业务操作标识；可由调用方复用，用于审计和幂等，不作为传输关联键。 */
     operationId?: string;
-    /** 实际建立代理的端口连接标识。 */
-    connectionId: string;
     /** 创建代理时捕获的不可变引用。 */
     reference: RemoteServiceReference;
     /** 引用绑定的外部授权标识，供最终服务边界再次核验。 */
     grantId?: string;
     /** 同时受消费者作用域和本次请求控制的 signal。 */
     signal: AbortSignal;
+    /** 从调用开始计算的总 deadline；等待目录和远程执行共用它。 */
+    deadlineAt?: number;
+    /** 传输直调用时的总 timeout；桥调用会同时提供 deadlineAt。 */
+    timeoutMs?: number;
 }
 /** 跨环境传输实现；桥不负责自动重放有外部副作用的请求。 */
 interface RemoteServiceTransport {
     call<TRequest, TResult>(request: TRequest, context: RemoteServiceCallContext): Promise<TResult>;
 }
-/** 已绑定服务引用的代理；提供者重建后旧代理永久失效。 */
+interface RemoteServiceCallOptions {
+    signal?: AbortSignal;
+    operationId?: string;
+    /** 兼容旧业务命名；只作为 operationId，不作为传输 callId。 */
+    requestId?: string;
+    /** 覆盖 RuntimeHandle 的默认有限 deadline。 */
+    timeoutMs?: number;
+}
+/** 惰性服务代理；第一次成功调用后永久绑定一份服务引用。 */
 interface RemoteServiceProxy {
-    readonly reference: RemoteServiceReference;
+    /** 未绑定时为 undefined；绑定后引用永远不换绑。 */
+    readonly reference?: RemoteServiceReference;
     readonly revoked: boolean;
-    call<TRequest, TResult>(request: TRequest, options?: {
-        signal?: AbortSignal;
-        operationId?: string; /** 旧 requestId 调用方别名；不作为传输 callId。 */
-        requestId?: string;
-    }): Promise<TResult>;
+    call<TRequest, TResult>(request: TRequest, options?: RemoteServiceCallOptions): Promise<TResult>;
     revoke(reason?: string): void;
 }
-type RemoteServiceBridgeState = "disconnected" | "handshaking" | "ready" | "stale";
-/** 服务桥快照结果；调用方据此决定等待、重新握手或重新同步基线。 */
+type RemoteServiceBridgeState = "empty" | "ready" | "stale" | "disposed";
+/** 服务桥完整快照结果；旧/重复 revision 直接忽略，不清空当前目录。 */
 type RemoteServiceSnapshotResult = {
     accepted: true;
     state: RemoteServiceBridgeState;
-    snapshotRevision: number;
+    revision: number;
 } | {
     accepted: false;
-    reason: "wrong-connection" | "wrong-authority" | "stale-revision" | "baseline-required" | "revision-gap";
-    expectedRevision?: number;
-    receivedRevision: number;
+    reason: "stale-revision" | "protocol-mismatch" | "invalid-snapshot" | "disposed";
+    receivedRevision?: number;
 };
+/** WebLoom v2 调用错误的稳定码；业务 handler 可以附加自己的 code。 */
+type RemoteServiceErrorCode = "transport_unavailable" | "call_timeout" | "runtime_initialization_failed" | "protocol_mismatch" | "capability_unavailable" | "contract_version_mismatch" | "service_stale" | "service_revoked" | "permission_denied" | "request_cancelled" | "request_clone_failed" | "handler_failed" | (string & {});
+declare class RemoteServiceError extends Error {
+    readonly code: RemoteServiceErrorCode;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: RemoteServiceErrorCode, message: string, details?: Readonly<Record<string, unknown>>);
+}
 /** 跨 Worker 服务桥最小本地契约。 */
 interface RemoteServiceBridge {
     /** 当前端口连接状态。 */
     readonly state: RemoteServiceBridgeState;
-    /** 当前握手连接标识。 */
-    readonly connectionId?: string;
-    /** 当前权威启动身份。 */
-    readonly authorityInstanceId?: string;
-    /** 接受一次新握手；新连接会使旧代理全部失效。 */
-    handshake(input: RemoteServiceHandshake): {
-        accepted: boolean;
-        reason?: "protocol-mismatch";
-    };
-    /** 应用基线或连续增量快照；乱序和旧连接快照会被丢弃。 */
+    /** 当前权威 Runtime 启动身份。 */
+    readonly runtimeInstanceId?: string;
+    /** 应用一份完整快照；第一次调用可以早于它到达。 */
     applySnapshot(snapshot: RemoteServiceSnapshot): RemoteServiceSnapshotResult;
-    /** 查询当前 ready 且版本精确匹配的服务代理。 */
+    /** 记录可解析但版本不兼容的对端；后续调用返回 protocol_mismatch。 */
+    markProtocolMismatch(reason?: string): void;
+    /** 记录权威 Runtime 初始化失败；后续调用返回 runtime_initialization_failed。 */
+    markInitializationFailed(reason?: string): void;
+    /** 总 deadline 默认值；必须是有限且大于零的毫秒数。 */
+    readonly defaultCallTimeoutMs: number;
+    /** 获取一个惰性、单次绑定代理；不得因当前目录为空同步失败。 */
     getProxy(lookup: RemoteServiceLookup, scope?: LifecycleScope): RemoteServiceProxy | undefined;
-    /** 查询代理失败时抛出稳定错误。 */
+    /** 获取惰性代理的显式别名；只在桥 disposed 后仍返回会失败的代理。 */
     requireProxy(lookup: RemoteServiceLookup, scope?: LifecycleScope): RemoteServiceProxy;
     /** 同步撤下全部代理；不等待远端。 */
     invalidate(reason?: string): void;
-    /** 端口断线；清除当前连接身份，后续快照必须等待新握手和基线。 */
+    /** 端口断线；旧代理永久失效，后续恢复必须创建新 RuntimeHandle。 */
     disconnect(reason?: string): void;
+    /** 永久销毁桥，并拒绝所有等待绑定和 pending call。 */
+    dispose(reason?: string): void;
     /** 订阅桥状态和服务目录变化。 */
     subscribe(listener: () => void): () => void;
     /** 只读当前有效服务引用。 */
     services(): readonly RemoteServiceReference[];
 }
-/** 服务桥未就绪或代理已失效。 */
-declare class RemoteServiceUnavailableError extends Error {
-    readonly code: "service.unavailable";
-    constructor(message?: string);
-}
 /** 首次发布采用的升级并存策略。冷切换要求旧环境先退出；两阶段允许
  * 短暂并存，但必须先在写入边界完成同一接管世代的排空。 */
 type UpgradeMode = "cold-switch" | "two-phase";
@@ -769,60 +748,57 @@ interface PluginContext<TConfig extends PluginConfig = PluginConfig, TExtension
     /** 宿主注入的只读配置；不与启停意图存储混用。 */
     readonly config?: TConfig;
 }
-/** 产品级依赖描述；简单插件可使用，跨环境单元应使用严格依赖。 */
-interface PluginDependency {
+/** v1 运行时依赖；跨 Runtime 绑定必须使用精确契约版本和来源 Runtime。 */
+interface RuntimeDependency {
     /** 依赖的 capability 标识。 */
     capability: string;
-    /** 精确契约版本；跨环境依赖不得省略。 */
+    /** 精确契约版本；跨 Runtime 依赖必须显式填写，本地可由 helper 推导。 */
     contractVersion?: string;
-    /** 提供者代码所在执行环境；由宿主定义。 */
-    sourceExecution?: PluginExecution;
-    /** 提供者允许存在的生命周期；由宿主定义。 */
-    scope?: PluginLifetime;
+    /** 提供者实际运行空间；省略时由当前 Runtime 补齐。 */
+    sourceRuntime?: RuntimeKind;
     /** 可选的人类可读诊断说明。 */
     reason?: string;
     /** 缺失时只关闭局部能力，不阻止主体运行。 */
     optional?: boolean;
 }
+/** 简单插件的产品级依赖别名。 */
+type PluginDependency = RuntimeDependency;
 /** 运行单元的严格依赖描述。 */
 interface RuntimeUnitDependency {
     /** 依赖的 capability 标识。 */
     capability: string;
     /** 精确契约版本；第一阶段只接受完全匹配。 */
     contractVersion: string;
-    /** 提供者实际运行环境。 */
-    sourceExecution: PluginExecution;
-    /** 提供者允许存在的生命周期。 */
-    scope: PluginLifetime;
+    /** 提供者实际运行空间；跨 Runtime 依赖在 materialize/validate 边界必须补齐。 */
+    sourceRuntime: RuntimeKind;
     /** 可选的人类可读诊断说明。 */
     reason?: string;
     /** 缺失时只关闭局部能力；未填写表示硬依赖。 */
     optional?: boolean;
 }
+/** 作者入口的未归一化 unit 依赖；进入 Host 前必须补齐版本和来源 Runtime。 */
+type RuntimeUnitDependencyInput = Omit<RuntimeUnitDependency, "contractVersion" | "sourceRuntime"> & {
+    contractVersion?: string;
+    sourceRuntime?: RuntimeKind;
+};
 /** 返回稳定的 capability 契约版本。 */
 declare function runtimeCapabilityContractVersion(capability: string): string;
 /** 将依赖清单补齐为严格运行单元依赖。 */
-declare function defineRuntimeUnitDependencies(dependencies: readonly Pick<PluginDependency, "capability" | "reason" | "optional">[], defaults?: Partial<Pick<RuntimeUnitDependency, "sourceExecution" | "scope">>): RuntimeUnitDependency[];
+declare function defineRuntimeUnitDependencies(dependencies: readonly Pick<PluginDependency, "capability" | "reason" | "optional">[], defaults: {
+    sourceRuntime: RuntimeKind;
+}): RuntimeUnitDependency[];
 /** 为运行单元生成精确的 capability 契约版本表。 */
 declare function defineRuntimeUnitProvidedContracts(capabilities: readonly string[]): Record<string, string>;
 /** 插件在产品清单中的启动要求。 */
 type PluginStartupMode = "required" | "optional";
-/** 插件展示元数据；kind、group 和 execution 都由宿主或产品定义。 */
+/** 插件装配元数据；v1 不解释产品分类字段。 */
 interface PluginMeta {
-    /** 产品自定义分类，不由 WebLoom 解释。 */
-    kind?: string;
     /** 首次装配时默认是否启用。 */
     defaultEnabled: boolean;
     /** 是否允许产品控制面禁用。 */
     canDisable: boolean;
     /** 是否属于启动必需插件。 */
     startup?: PluginStartupMode;
-    /** 产品自定义展示分组。 */
-    displayGroup?: string;
-    /** 默认运行生命周期；未填写时使用宿主默认值。 */
-    lifetime?: PluginLifetime;
-    /** 默认执行环境；不从 UI 或实现类型推断。 */
-    execution?: PluginExecution;
 }
 /** 插件 setup 返回的清理函数。 */
 type PluginTeardown = () => void | Promise<void>;
@@ -837,10 +813,8 @@ interface RuntimeUnitImplementationRegistry<TConfig extends PluginConfig = Plugi
 interface RuntimeUnitDescriptor<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig> {
     /** 稳定运行单元标识。 */
     id: string;
-    /** 运行代码所在环境。 */
-    execution: PluginExecution;
-    /** 依附的作用域寿命。 */
-    lifetime: PluginLifetime;
+    /** 运行代码所在真实 Runtime。 */
+    runtime: RuntimeKind;
     /** 本单元所需的精确 capability 契约。 */
     dependencies?: RuntimeUnitDependency[];
     /** 本单元提供的 capability。 */
@@ -854,6 +828,11 @@ interface RuntimeUnitDescriptor<TContribution = PluginContribution, TConfig exte
     /** 单元专属只读配置声明或装配默认值。 */
     config?: TConfig;
 }
+/** 作者入口的未归一化运行单元；runtime 可由 createWindowApp/startSharedWorkerApp 注入。 */
+type RuntimeUnitDescriptorInput<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig> = Omit<RuntimeUnitDescriptor<TContribution, TConfig>, "runtime" | "dependencies"> & {
+    runtime?: RuntimeKind;
+    dependencies?: readonly RuntimeUnitDependencyInput[];
+};
 /** 插件清单；插件作者导出的唯一静态描述。 */
 interface PluginManifest<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> {
     /** 全局稳定产品标识。 */
@@ -877,6 +856,10 @@ interface PluginManifest<TContribution = PluginContribution, TConfig extends Plu
     /** 简单插件的只读配置。 */
     config?: TConfig;
 }
+/** 作者入口的未归一化静态清单；进入 Host 前必须 materialize 成 PluginManifest。 */
+type PluginManifestInput<TContribution = PluginContribution, TConfig extends PluginConfig = PluginConfig, TExtension extends PluginContextExtension = PluginContextExtension> = Omit<PluginManifest<TContribution, TConfig, TExtension>, "units"> & {
+    units?: readonly RuntimeUnitDescriptorInput<TContribution, TConfig>[];
+};
 /** 插件运行状态类别；registered 不代表已经运行。 */
 type PluginStateKind = "registered" | "starting" | "stopping" | "enabled" | "disabled" | "blocked" | "error-disabled" | "cleanup-pending" | "unknown";
 /** 对外稳定的产品运行语义。 */
@@ -912,8 +895,8 @@ interface PluginUnitState {
     pluginId: string;
     /** 稳定运行单元标识。 */
     unitId: string;
-    /** 运行环境。 */
-    execution: PluginExecution;
+    /** 真实运行空间。 */
+    runtime: RuntimeKind;
     /** 当前运行实例。 */
     instanceId?: string;
     /** 当前意图修订。 */
@@ -961,8 +944,8 @@ interface PluginUnitGraph {
     pluginId: string;
     /** 稳定运行单元标识。 */
     unitId: string;
-    /** 运行环境。 */
-    execution: PluginExecution;
+    /** 真实运行空间。 */
+    runtime: RuntimeKind;
     /** capability 依赖。 */
     dependencies: string[];
     /** 精确依赖描述。 */
@@ -993,6 +976,8 @@ interface StartupCapabilityErrorDetails {
 interface StartupPluginErrorDetails {
     /** 产品标识。 */
     pluginId: string;
+    /** 失败的运行单元。 */
+    unitId?: string;
     /** 能力列表。 */
     capabilities: string[];
     /** 当前状态。 */
@@ -1115,37 +1100,6 @@ interface PluginConfigStore {
 }
 /** 创建内存配置端口；产品可通过 configStore 注入持久化实现。 */
 declare function createInMemoryPluginConfigStore(initial?: Readonly<Record<string, boolean>>, readOnly?: boolean): PluginConfigStore;
-/** ScopeResolver 的输入；宿主可以基于当前状态决定 Scope 是否存在。 */
-interface ScopeResolverInput {
-    /** 产品标识。 */
-    pluginId: string;
-    /** 稳定运行单元标识。 */
-    unitId: string;
-    /** 当前单元声明的生命周期标签。 */
-    lifetime: PluginLifetime;
-    /** 完整静态清单。 */
-    manifest: PluginManifest;
-}
-/** 一个运行单元当前是否可以挂载。 */
-interface ScopeResolution {
-    /** 是否允许创建实例 Scope。 */
-    available: boolean;
-    /** 不可用时的稳定诊断原因。 */
-    reason?: string;
-    /** 父 Scope；未提供时使用 Host 根 Scope。 */
-    parent?: LifecycleScope;
-    /** Scope 身份的只读扩展属性。 */
-    attributes?: Readonly<Record<string, unknown>>;
-    /** 宿主用于检测身份变化的稳定键。 */
-    key?: string;
-}
-/** Scope 状态变化订阅端口。 */
-interface ScopeResolver {
-    /** 解析当前单元是否具备可用父 Scope。 */
-    resolve(input: ScopeResolverInput): ScopeResolution;
-    /** 状态变化后通知 Host 重新协调；可选。 */
-    subscribe?(listener: () => void): () => void;
-}
 /** 权限策略输入；申请、批准和会话约束必须分开计算。 */
 interface PermissionPolicyInput {
     /** 产品标识。 */
@@ -1208,24 +1162,38 @@ interface ContributionAdapter {
     /** 注册一份泛型贡献。 */
     register(input: ContributionAdapterInput): void | ContributionHandle | (() => void | Promise<void>) | Promise<void | ContributionHandle | (() => void | Promise<void>)>;
 }
+/** 运行单元可用性检查；返回稳定原因表示当前实例不能装配。 */
+interface RuntimeUnitAvailabilityInput {
+    /** 产品标识。 */
+    pluginId: string;
+    /** 运行单元标识。 */
+    unitId: string;
+    /** 真实 Runtime。 */
+    runtime: RuntimeKind;
+}
+/** 新运行单元 Scope 的身份属性输入。 */
+interface RuntimeUnitAttributesInput extends RuntimeUnitAvailabilityInput {
+    /** 静态产品清单。 */
+    manifest: PluginManifest;
+}
+/** 为运行单元选择父 Scope；未提供时运行单元直接挂在 Host 根 Scope。 */
+type RuntimeUnitParentScopeInput = RuntimeUnitAttributesInput;
 /** 通用运行单元快照；用于展示远端单元未知/恢复状态。 */
 interface RuntimeUnitSnapshot {
     /** 产品标识。 */
     pluginId: string;
     /** 单元标识。 */
     unitId: string;
-    /** 执行环境。 */
-    execution: string;
+    /** 真实 Runtime。 */
+    runtime: RuntimeKind;
     /** 远端实例标识。 */
     instanceId?: string;
     /** 远端当前状态。 */
     state: PluginStateKind;
 }
 interface CreatePluginHostOptions {
-    /** 当前 Host 所在执行环境；用于选择运行单元。 */
-    execution?: string;
-    /** 默认插件生命周期。 */
-    defaultLifetime?: string;
+    /** 当前 Host 所在真实 Runtime。 */
+    runtime?: RuntimeKind;
     /** 根 Scope 的宿主只读属性。 */
     rootAttributes?: Readonly<Record<string, unknown>>;
     /** 预注入的内建 capability；不归属于任何插件实例。 */
@@ -1240,8 +1208,6 @@ interface CreatePluginHostOptions {
     contextExtension?: (input: ContextExtensionInput) => Readonly<Record<string, unknown>>;
     /** 校验产品清单中的宿主扩展字段。 */
     manifestValidator?: (manifest: PluginManifest) => void;
-    /** 解析当前生命周期是否存在以及其父 Scope。 */
-    scopeResolver?: ScopeResolver;
     /** 计算权限批准与会话交集。 */
     permissionPolicy?: (input: PermissionPolicyInput) => PermissionPolicyResult;
     /** 启停意图持久化端口。 */
@@ -1254,12 +1220,22 @@ interface CreatePluginHostOptions {
     serviceBridgeForPlugin?: (pluginId: string, instanceId: string) => RemoteServiceBridge | undefined;
     /** 当前执行环境的运行单元实现注册表。 */
     runtimeUnitImplementationRegistry?: RuntimeUnitImplementationRegistry;
+    /** 当前身份/授权不允许装配时返回稳定的 blockedBy 原因。 */
+    runtimeUnitAvailability?: (input: RuntimeUnitAvailabilityInput) => string | undefined;
+    /** 为每次新建运行单元 Scope 生成当前绑定的只读属性。 */
+    runtimeUnitAttributes?: (input: RuntimeUnitAttributesInput) => Readonly<Record<string, unknown>> | undefined;
+    /** 为每次新建运行单元 Scope 选择生命周期父级；返回 undefined 使用 Host 根 Scope。 */
+    runtimeUnitParentScope?: (input: RuntimeUnitParentScopeInput) => LifecycleScope | undefined;
     /** 贡献适配器集合。 */
     contributionAdapters?: readonly ContributionAdapter[];
     /** 允许每一项清理等待的时间。 */
     lifecycleCleanupTimeoutMs?: number;
     /** 读取远端单元真实状态。 */
     runtimeSnapshots?: () => readonly RuntimeUnitSnapshot[];
+    /** 读取其它真实 Runtime 当前已接受的服务目录。 */
+    remoteServiceReferences?: () => readonly RemoteServiceReference[];
+    /** 允许来源 Runtime 不同且尚未出现在本地 manifest 集合中的依赖。 */
+    externalRuntimeDependencies?: boolean;
 }
 declare class StartupCapabilityError extends Error {
     readonly details: StartupCapabilityErrorDetails[];
@@ -1327,6 +1303,8 @@ interface PluginHost {
         ok: false;
         reason: string;
     }>;
+    /** 暂停当前实例但保留启用意图；供宿主身份世代切换时撤权重建。 */
+    suspend(pluginId: string, reason?: string): Promise<void>;
     /** 从 Host 删除一个插件。 */
     unregister(pluginId: string): Promise<void>;
     /** 停止所有实例并释放根 Scope。 */
@@ -1337,4 +1315,4 @@ interface PluginHost {
     }): void;
 }
 
-export { type PluginContribution as $, type LifecycleScopeState as A, type Message as B, type CreateUpgradeGateOptions as C, type DispatchOptions as D, type EventHandler as E, type MessageBusSnapshot as F, type MessageHandler as G, type HandlerOptions as H, type MessageMode as I, PermissionDeniedError as J, type PermissionLeaseBinding as K, type LifecycleScope as L, type MessageBus as M, type PermissionLeaseBindingExpectation as N, type OwnedResourceDefinition as O, type PluginExecution as P, PermissionLeaseRevokedError as Q, type RemoteServiceHandshake as R, type ScopedTaskScheduler as S, type PermissionPolicyInput as T, type UpgradeGate as U, type PermissionPolicyResult as V, type PluginAttributes as W, type PluginConfig as X, type PluginConfigStore as Y, type PluginContext as Z, type PluginContextExtension as _, type PluginManifest as a, createInMemoryPluginConfigStore as a$, type PluginHost as a0, type PluginIntentCommand as a1, type PluginIntentCommandResult as a2, type PluginIntentController as a3, type PluginIntentCoordinator as a4, type PluginIntentSnapshot as a5, type PluginIntentSubmissionResult as a6, type PluginLifecycleState as a7, type PluginLifetime as a8, type PluginMeta as a9, type ResourceRegistry as aA, type ResourceSnapshot as aB, type ResourceStatus as aC, type ResourceStoreApi as aD, type RuntimeUnitDependency as aE, type RuntimeUnitDescriptor as aF, type RuntimeUnitImplementationRegistry as aG, type RuntimeUnitSnapshot as aH, SCOPED_TASK_SCHEDULER_CAPABILITY as aI, type ScopeResolution as aJ, type ScopeResolver as aK, type ScopeResolverInput as aL, type ScopedTaskDefinition as aM, type ScopedTaskSnapshot as aN, StartupCapabilityError as aO, type StartupCapabilityErrorDetails as aP, StartupPluginError as aQ, type StartupPluginErrorDetails as aR, type UpgradeDrainResult as aS, UpgradeGateRejectedError as aT, type UpgradeGateState as aU, type UpgradeHandshake as aV, type UpgradeHandshakeResult as aW, type UpgradeIoLease as aX, type UpgradeMode as aY, type UpgradeSession as aZ, createCapabilityRegistry as a_, type PluginSetup as aa, type PluginStartupMode as ab, type PluginState as ac, type PluginStateKind as ad, type PluginTeardown as ae, type PluginUnitGraph as af, type PluginUnitState as ag, type PublishOptions as ah, RESOURCE_OWNER as ai, RESOURCE_REGISTRY_CAPABILITY as aj, RUNTIME_MESSAGE_BUS as ak, type RemoteServiceBridge as al, type RemoteServiceBridgeState as am, type RemoteServiceCallContext as an, type RemoteServiceLookup as ao, type RemoteServiceMessageKind as ap, type RemoteServicePortControlMessage as aq, type RemoteServiceProxy as ar, type RemoteServiceReference as as, type RemoteServiceSnapshotResult as at, type RemoteServiceTransport as au, RemoteServiceUnavailableError as av, type RequestOptions as aw, type ResourceContext as ax, type ResourceDefinition as ay, type ResourceKey as az, type PluginGraph as b, createPluginHost as b0, createRemoteServiceMessageCodec as b1, createResourceStore as b2, defineRuntimeUnitDependencies as b3, defineRuntimeUnitProvidedContracts as b4, lifecycleErrorText as b5, runtimeCapabilityContractVersion as b6, type PluginDependency as c, type PluginReverseDep as d, type LifecycleScopeIdentity as e, type PluginPermission as f, type PermissionLease as g, type RemoteServiceSnapshot as h, type RemoteServiceMessageCodec as i, type CapabilityRegistry as j, type ContextExtensionInput as k, type ContributionAdapter as l, type ContributionAdapterInput as m, type ContributionHandle as n, type CreatePluginHostOptions as o, type HostListener as p, LIFECYCLE_ERROR_TEXT as q, type LifecycleCleanup as r, type LifecycleCleanupIssue as s, type LifecycleCleanupPhase as t, type LifecycleDisposeOptions as u, type LifecycleDisposeResult as v, type LifecycleResourceHandle as w, type LifecycleResourceSnapshot as x, type LifecycleScopeKind as y, LifecycleScopeRevokedError as z };
+export { PermissionLeaseRevokedError as $, type LifecycleCleanup as A, type LifecycleCleanupIssue as B, type CreatePluginHostOptions as C, type DispatchOptions as D, type EventHandler as E, type LifecycleCleanupPhase as F, type LifecycleDisposeOptions as G, type HandlerOptions as H, type LifecycleResourceHandle as I, type LifecycleResourceSnapshot as J, type LifecycleScopeKind as K, type LifecycleDisposeResult as L, type MessageBus as M, LifecycleScopeRevokedError as N, type LifecycleScopeState as O, type PluginManifest as P, type Message as Q, type RuntimeKind as R, type ScopedTaskScheduler as S, type MessageBusSnapshot as T, type UpgradeGate as U, type MessageHandler as V, type MessageMode as W, type OwnedResourceDefinition as X, PermissionDeniedError as Y, type PermissionLeaseBinding as Z, type PermissionLeaseBindingExpectation as _, type PluginGraph as a, type UpgradeMode as a$, type PermissionPolicyInput as a0, type PermissionPolicyResult as a1, type PluginAttributes as a2, type PluginConfigStore as a3, type PluginContext as a4, type PluginIntentCommand as a5, type PluginIntentCommandResult as a6, type PluginIntentController as a7, type PluginIntentCoordinator as a8, type PluginIntentSnapshot as a9, type ResourceDefinition as aA, type ResourceKey as aB, type ResourceRegistry as aC, type ResourceSnapshot as aD, type ResourceStatus as aE, type ResourceStoreApi as aF, type RuntimeUnitAttributesInput as aG, type RuntimeUnitAvailabilityInput as aH, type RuntimeUnitDependency as aI, type RuntimeUnitDependencyInput as aJ, type RuntimeUnitDescriptor as aK, type RuntimeUnitImplementationRegistry as aL, type RuntimeUnitParentScopeInput as aM, type RuntimeUnitSnapshot as aN, SCOPED_TASK_SCHEDULER_CAPABILITY as aO, type ScopedTaskDefinition as aP, type ScopedTaskSnapshot as aQ, StartupCapabilityError as aR, type StartupCapabilityErrorDetails as aS, StartupPluginError as aT, type StartupPluginErrorDetails as aU, type UpgradeDrainResult as aV, UpgradeGateRejectedError as aW, type UpgradeGateState as aX, type UpgradeHandshake as aY, type UpgradeHandshakeResult as aZ, type UpgradeIoLease as a_, type PluginIntentSubmissionResult as aa, type PluginLifecycleState as ab, type PluginStartupMode as ac, type PluginState as ad, type PluginStateKind as ae, type PluginTeardown as af, type PluginUnitGraph as ag, type PluginUnitState as ah, type PublishOptions as ai, RESOURCE_OWNER as aj, RESOURCE_REGISTRY_CAPABILITY as ak, RUNTIME_MESSAGE_BUS as al, type RemoteServiceBridge as am, type RemoteServiceBridgeState as an, type RemoteServiceCallContext as ao, type RemoteServiceCallOptions as ap, RemoteServiceError as aq, type RemoteServiceErrorCode as ar, type RemoteServiceLookup as as, type RemoteServiceMessageKind as at, type RemoteServiceProxy as au, type RemoteServiceSnapshot as av, type RemoteServiceSnapshotResult as aw, type RemoteServiceTransport as ax, type RequestOptions as ay, type ResourceContext as az, type PluginDependency as b, type UpgradeSession as b0, createCapabilityRegistry as b1, createInMemoryPluginConfigStore as b2, createPluginHost as b3, createRemoteServiceMessageCodec as b4, createResourceStore as b5, defineRuntimeUnitDependencies as b6, defineRuntimeUnitProvidedContracts as b7, lifecycleErrorText as b8, runtimeCapabilityContractVersion as b9, type PluginReverseDep as c, type PluginContribution as d, type PluginConfig as e, type PluginContextExtension as f, type PluginManifestInput as g, type RuntimeUnitDescriptorInput as h, type PluginSetup as i, type RuntimeDependency as j, type PluginPermission as k, type PluginMeta as l, type PluginHost as m, type LifecycleScope as n, type LifecycleScopeIdentity as o, type PermissionLease as p, type CreateUpgradeGateOptions as q, type RemoteServiceReference as r, type RemoteServiceMessageCodec as s, type CapabilityRegistry as t, type ContextExtensionInput as u, type ContributionAdapter as v, type ContributionAdapterInput as w, type ContributionHandle as x, type HostListener as y, LIFECYCLE_ERROR_TEXT as z };