docs: define capability runtime integration boundaries

Author: limityan

docs/architecture/agent-runtime-services-design.md

@@ -5,7 +5,9 @@ crate 内部结构和行为保护要求。本文件记录设计约束，不记
 生态兼容适配层、进程间通信和扩展贡献接口见
 [`plugin-runtime-host-design.md`](extensions/plugin-runtime-host-design.md)；产品定义、品牌资源、GUI/TUI 布局选择和产品组装
 结果见 [`product-customization-blueprint.md`](product-customization-blueprint.md)；CLI 入口、配置兼容和
-CLI Agent 体验边界见 [`cli-product-line-design.md`](cli-product-line-design.md)。
+CLI Agent 体验边界见 [`cli-product-line-design.md`](cli-product-line-design.md)；能力 Provider 如何装配、对外能力门面与
+多宿主 adapter 的状态、权限、并发和兼容边界见
+[`capability-runtime-integration-design.md`](extensions/capability-runtime-integration-design.md)。
 
 本文中的接口片段只说明依赖方向和职责，不自动构成当前 API 或实施承诺。当前接口名称、字段和消费方以代码为准；
 新增公共类型前必须有真实生产调用方、版本边界和验证路径。现有 Agent Runtime SDK 仍是 v1 preview，CLI、ACP、
@@ -49,6 +51,11 @@ Agent Runtime SDK 的发布边界以调用方能力为准，而不是以物理 c
 - 内部 SDK 最小特性不牵引 Desktop、Tauri、Git 提供方、MCP 客户端、AI HTTP 客户端、remote SSH 或产品 UI。
 - 完整产品能力只能通过产品组装或兼容 `bitfun-core/product-full` 组装，不反向污染 SDK 接口。
 
+Agent Runtime SDK 和“对外能力门面”不是同一发布包必须同时暴露的接口。前者服务于嵌入式 Agent Runtime，后者
+只为外部宿主暴露当前场景需要的 Memory 查询、Workflow 调用、状态或事件等窄用例。若外部产品只调用一项 BitFun
+能力，不得迫使其依赖完整 Runtime builder、产品组装、插件 Host ABI 或内部注册表。只有同一语义被真实嵌入方
+复用后，才允许两者共享稳定 DTO 或版本边界。
+
 SDK 公共接口以 `AGENT_RUNTIME_SDK_API_VERSION` 标记兼容边界。当前接口版本为 v1 preview：
 小版本更新允许增加可选 builder hook、DTO 字段或注册表查询能力，但不得改变既有端口语义、
 错误分类、session / turn 标识含义或默认 feature 依赖。任何需要调用方改写现有嵌入代码的变更，
@@ -87,7 +94,7 @@ SDK 公共接口以 `AGENT_RUNTIME_SDK_API_VERSION` 标记兼容边界。当前
 | 前后端能力服务切面 | 智能体内核如何产出会话、事件、权限和诊断事实 | 宿主协议 DTO、插件状态视图字段、产品形态状态词 |
 | BitFun 与插件切面 | 插件贡献如何进入内核、执行层和安全控制面 | 具体生态接口、未预算界面贡献字段、OpenCode 原始 payload |
 | 插件通用运行时切面 | `PluginRuntimeBinding` 如何注入 Agent Runtime 内部 builder | `PluginRuntimeClient`、dispatch/read schema、隔离字段；这些由插件主机文档和 `runtime-ports` 代码定义 |
-| OpenCode 适配切面 | 不进入 Agent Runtime SDK；只作为插件主机内部反腐层 | OpenCode client/server facade、配置导入细节、跨生态稳定接口 |
+| 外部生态兼容适配切面 | 不进入 Agent Runtime SDK；各生态 adapter 只作为来源或宿主边界的反腐层 | OpenCode client/server facade、Claude/Codex/Trae Hook 细节、配置导入细节、跨生态稳定 payload |
 
 OpenCode 适配器、ACP 桥接和未来插件运行时必须先映射到主架构定义的切面，再由产品组装注册。它们不能直接写智能体内核权威状态；通过 Compatibility Facade、Tool Runtime 或界面宿主调用的 BitFun 能力必须经过相应权限与审计路径。插件脚本直接使用 Bun 文件、网络或进程接口产生的副作用不在这项保证内：没有可执行的操作系统隔离时，严格策略必须禁用相应插件或明确报告 `policy-limited`，不能宣称已被沙箱拦截。
 
@@ -801,6 +808,13 @@ feature group、运行时服务要求、工具提供方组、Harness 描述符
 现有 `ProductCapabilityId`、`ProductFeatureGroup` 和归属模块的类型化注册路径；只有第二个真实实现出现且现有结构
 无法表达时，才评审新的公共抽象。
 
+Provider 装配同样按需增加，不提前为 Memory、Context、Workflow、Subagent 和 Scheduler 各建一套公共 registry。
+真实 Slot 必须由能力 owner 声明 `exclusive`、`ordered-chain`、`namespace-union`、`fallback` 或 `fan-out` 组合语义；
+产品组装只选择已编译 Provider/factory、Slot 支持和产品上限；动态来源由能力 owner/生命周期协调器在该上限内
+产出不可变的 Capability Resolution Generation，不重新触发产品组装。可替换 Scheduler 策略只能在已准入
+候选中排序或分配权重，admission、队列容量、deadline、取消和硬并发上限仍由 Runtime owner 持有。详细门槛见
+[`capability-runtime-integration-design.md#2-能力分类与可替换边界`](extensions/capability-runtime-integration-design.md#2-能力分类与可替换边界)。
+
 分层规则：
 
 - Code Agent 包允许声明智能体模式、工具包、提示模块，但不拥有工具执行。
@@ -824,6 +838,8 @@ feature group、运行时服务要求、工具提供方组、Harness 描述符
 - 插件贡献进入 Agent Runtime 前必须已经转换成 BitFun 类型化工具、Hook 输入/输出、诊断或明确不支持；
   OpenCode 原始对象不能进入业务状态。
 - 工具贡献必须复用工具 ABI；事件订阅必须复用事件清单；权限候选必须复用安全控制面。
+- BitFun 能力输出到外部宿主时不反向经过 `PluginRuntimeClient`。对外能力门面调用现有 owner，再由 MCP、Skill、
+  Plugin、Hook、SDK 或 Server adapter 映射；只有需要运行第三方代码的 import 路径才使用插件主机。
 
 本文件不定义 `UiContributionDescriptor`、OpenCode client/server facade、泛 hook registry、来源发现接口或多生态能力矩阵。这些能力只有在存在真实产品消费方、公开接口预算和安全评审后，才允许进入对应归属文档和代码。
 
@@ -938,6 +954,10 @@ pub trait BeforeToolExecution: Send + Sync {
 - hook error 必须可分类：fail turn、skip hook、deny tool、record warning。
 - hook 不得获取未声明的具体 service。
 - 修改 prompt / manifest / output 的 hook 必须有 snapshot 测试。
+- 外部 Host Hook 的并行、顺序和权限合并语义由对应 adapter 保留；Runtime 不建立一个覆盖所有宿主的统一 Hook ABI。
+- 跨协议事件在真实 Server/SDK 消费方出现前不冻结新 taxonomy。冻结时必须定义版本、同流 sequence、
+  correlation/causation、generation、scope、执行域、隐私分类和投递损失；不得从现有 `event_name + payload` 投影
+  直接推导完整兼容。
 
 ## 5. 质量保护与目标态判定
 
@@ -968,6 +988,12 @@ pub trait BeforeToolExecution: Send + Sync {
 - scheduler queue、subagent background、fork context 必须定义并发限制。
 - fork context 继续保留禁止字段和递归 subagent 保护。
 - 提供方注册表构建后应尽量不可变，避免运行时期间物化漂移。
+- 并发预算按进程/产品、执行域/工作区、session/workflow、subagent/provider、tool/hook 分层收紧；外部策略不能
+  放宽上层预算。具体数值由首个纵向切片测量，不在公共接口中预设。
+- 调用携带 request identity，以及由能力 owner/生命周期协调器下发的、带能力和来源实例作用域的 Capability
+  Resolution Generation fence；Product Assembly、Provider、Host 和执行服务都不选择或持久化第二份 active
+  generation，已退出代次的迟到结果不能提交到当前状态。
+- 查询和显式幂等步骤可以有界重试；写入、发送、删除和未知副作用在 worker 或网络失联后不得自动重放。
 
 ### 5.2 设计边界