docs(architecture): add product surface contract guardrails

Author: limityan

docs/architecture/core-decomposition.md

@@ -128,17 +128,37 @@ owner 边界，否则不要把一个 feature group 继续拆成更小的 crate
     或任何产品 crate feature set 调整。
 - 高风险项不能作为 P2/P3 普通收尾任务顺带执行，必须先有等价性测试、port/provider 设计、
   旧路径兼容策略和用户确认。
-- 为减少 PR 次数，剩余 runtime 迁移可以压缩为 5 个主题 PR，但每个 PR 仍必须保持单一
+- 为减少 PR 次数，后续 runtime 迁移沿用 5 个主题 PR 的队列约束，每个 PR 仍必须保持单一
   owner 主题：`services-integrations` runtime 收口、MCP runtime/dynamic tools、
   remote-connect runtime、agent tools + `tool-packs` owner 化、`product-domains`
-  runtime + core facade finalization。`bitfun-core default = []` 和 per-product feature
-  matrix 仍是上述 5 个 PR 之后的独立评估。
+  runtime + core facade finalization。PR 2 的 MCP runtime/dynamic tools 已完成；后续不得把
+  remote-connect、tool registry owner 化或 product-domain runtime 顺带混入已完成的 MCP PR。
+  `bitfun-core default = []` 和 per-product feature matrix 仍是上述 runtime 队列之后的独立评估。
 - PR 2 的 MCP 迁移已覆盖 config service orchestration、server process / local-remote
   transport lifecycle、resource/prompt adapter、catalog cache、list-changed / reconnect policy、
   dynamic tool descriptor、dynamic tool provider 与 result rendering。`bitfun-core` 保留
   core `ConfigService` store adapter、OAuth data-dir 注入、`BitFunError` 映射、旧路径 facade
   和全局 tool registry 组装；tool registry owner 化仍归后续 tool/provider PR。
 
+## 产品表面边界（Product Surface Boundary）
+
+BitFun 的重构目标不是把 Desktop、CLI、Remote、Server 和 ACP 强行收敛成同一套命令或 UI。
+这些产品表面可以保持不同交互语义，但应逐步共享稳定的运行时事实和能力契约。简短原则是：
+**surface divergence, capability convergence**。
+
+- Surface presentation 留在 app adapters：Desktop pane / command center、CLI TUI、Remote card、
+  ACP protocol 和 Server routes 不进入 `core-types`、`runtime-ports`、`agent-tools` 或 owner runtime crate。
+- 可共享的是 capability contract：session/thread identity、environment identity、permission facts、
+  artifact refs、event facts、review/diff/terminal/usage/report 等稳定 DTO，以及必要的 port trait。
+- CLI/Desktop parity 不是迁移 presentation dependency 的理由；`ratatui`、`crossterm`、`arboard`、
+  `syntect-tui`、Tauri、Web UI 或 remote card rendering 依赖必须继续留在对应 surface adapter。
+- 命令是产品 affordance，能力是 runtime contract。类似 `/diff`、快捷键、状态卡或协议方法可以映射到
+  同一 capability contract，但不要求共享命令实现。
+- Permission / approval contract 必须能表达来源 surface、thread、turn 和 subagent identity；各 surface
+  的审批 UI 可以不同。
+- Product-surface refactor 只能在 contract 层先做 observational DTO / port 补强；若要改变 UI、命令、
+  权限策略或功能逻辑，必须作为单独产品变更 PR，而不是 core decomposition 的副作用。
+
 ## Feature 安全规则
 
 - 在让任何默认 feature 变轻之前，先引入 `product-full`。

docs/plans/core-decomposition-plan.md

@@ -1539,6 +1539,24 @@ cargo check --workspace
   - `cargo tree -p bitfun-product-domains --no-default-features --depth 1 --edges features` 仅显示 `serde`、`serde_json`，不会拉入 `dirs`。
   - `cargo tree -p bitfun-services-integrations --no-default-features --depth 1 --edges features` 仅显示 `bitfun-events`、`serde`、`serde_json`、`log`、`tokio`。
 
+P2 后产品表面契约轨道（contract-only）：
+
+- 背景：最新 CLI TUI、Desktop、Remote、Server 和 ACP 都是 first-class product surface。后续重构不应把它们
+  拉平成同一套命令实现，而应共享 runtime capability facts。
+- 原则：**surface divergence, capability convergence**。命令、快捷键、pane/card/TUI rendering 属于 surface
+  presentation；session/thread identity、environment identity、permission facts、artifact refs、event facts 和
+  capability request/response 属于可共享 contract。
+- 候选 contract：`SurfaceKind`、`ThreadEnvironment`、`RuntimeArtifactKind`、`RuntimeArtifactRef`、
+  `PermissionDecision`、`PermissionScope`、`ApprovalSource`、`CapabilityRequest`。纯 DTO 优先放入
+  `bitfun-core-types`；必要 port trait 放入 `bitfun-runtime-ports`。
+- 明确不做：不改 CLI slash command / TUI、不改 Desktop command palette 或 pane 行为、不新增 command engine crate、
+  不调整 `product-full`、不做 per-product feature set，也不把 `ratatui`、`crossterm`、Tauri 或 Web UI 依赖带入
+  contract crate。
+- 进入方式：该轨道可作为 PR3 前的 contract-only 前置提交或 PR3 的第一组无行为变更提交；一旦需要改变 UI、
+  命令语义、权限策略或运行时调用路径，必须拆成单独产品变更 PR 并先确认。
+- 验证：DTO/port 只做 serialization round-trip、conversion/no-op check 与 boundary check；不能只凭
+  `cargo check` 声明产品行为等价。
+
 需要单独审视的高风险项：
 
 - `ToolUseContext`、tool registry/provider、concrete tool implementation 外移。
@@ -1569,7 +1587,9 @@ cargo check --workspace
 2. 已完成：MCP runtime 与 dynamic tools：MCP config service orchestration、server process / transport lifecycle、adapter、dynamic tool/resource/prompt provider 已归属 `bitfun-services-integrations`；未混入 remote-connect 或 tool registry owner 化。验收重点是 MCP wire shape、auth/config merge、dynamic manifest 快照和 core registry 集成等价。
    - 保留边界：`bitfun-core` 只保留 core `ConfigService` store adapter、OAuth data-dir 注入、`BitFunError` 映射、legacy facade 和与全局 tool registry 的组装调用；配置写入、OAuth、SSE/session 与 registry 行为不得在本 PR 中改变。
    - 后续切片：tool registry/provider owner 化需要放入 PR4，并先保留 dynamic provider metadata、工具清单顺序和 snapshot wrapper 等价测试。
+   - 文档校正：P2 后补充文档中的 MCP runtime step 已由本 PR2 闭环；后续 MCP 相关工作只保留 tool registry/provider owner 化和 concrete tool implementation 迁移，不再重复迁移 config/process/transport lifecycle。
 3. remote-connect runtime：通过 `AgentSubmissionPort`、`SessionTranscriptReader`、`EventSink` 等 port 合约迁移 remote-connect / relay-facing runtime。验收重点是 message contract、session submission、remote control 同步与无真实网络依赖的 integration test。
+   - 进入前先复核产品表面契约轨道：如果 remote-connect 需要表达 source surface、thread environment、approval source 或 artifact ref，先补 contract-only DTO/port 和 round-trip/no-op tests，不改变现有 remote behavior。
 4. agent tools + `tool-packs` owner 化：`ToolUseContext` port 化、tool registry/provider 化、concrete tool implementation 按 feature group 迁移；必须保持 builtin/readonly/dynamic manifest、snapshot wrapping、runtime restrictions、cancellation 与 Deep Review tool flow 等价。
 5. `product-domains` runtime + core facade finalization：迁移 miniapp runtime/compiler/builtin 与 function-agent 运行逻辑，最后把 `bitfun-core` 收敛为 facade + product runtime assembly；不在本 PR 中修改 `bitfun-core default = []` 或 per-product feature matrix。
 
@@ -1605,6 +1625,7 @@ cargo check --workspace
 - 最近 `origin/main` 的 Deep Review 变更增加了 context profile、evidence ledger、capacity/cost/queue 控制、`deep_review_run_manifest` / `deep_review_cache`、以及 review-team UI orchestration；最新主干还补充了 agent-stream tool-call dedupe、search remote/fallback、session rollback persistence 和 companion typewriter。P3 facade 收敛前必须确认这些行为要么仍由 core product runtime assembly 拥有，要么已有对应 owner crate + port/provider 合约和等价测试。
 - 最新主干的 mode-scoped subagent visibility 将 `agentic::agents` 重组为 definitions / registry / visibility 边界，并扩展了 desktop subagent API 与 Review Team 可见性测试；后续若迁移 agent registry，不能只做路径 re-export，必须保留 mode 可见性过滤、hidden/custom/review 分组语义和前后端 API contract。
 - 最新主干的 CLI 重构主要新增 TUI/theme/selector/dialog/chat-state 等 app-layer 代码，后续又收敛预置 theme 并补充 desktop companion pet resize / Windows UX；这些当前没有改变 `services-integrations` 的迁移归属。后续若调整 shared crate 边界，必须继续把 `bitfun-cli`、`ratatui`、`crossterm`、`arboard`、`syntect-tui` 等 CLI-only 依赖限制在 app adapter / presentation layer，desktop / web-ui presentation 修复也不应被误判为 core service 迁移前置条件。
+- P2 后产品表面策略要求“surface divergence, capability convergence”：CLI `/diff`、Desktop 快捷键/面板、Remote card、ACP method 可以映射到同一 capability contract，但不能为了复用把 surface command 或 UI rendering 下沉到 contract crate。
 - `ToolUseContext` 的 shared-context / evidence checkpoint hook、`TaskTool` / `CodeReviewTool` 的 Deep Review capacity flow、session manifest/cache persistence、rollback persisted-turn cleanup、search fallback chain 与 stream finish/tool-call contract 不能在 P3 中只通过 re-export 消失；如果外移，需要先补 boundary contract、旧路径兼容和对应 regression。
 - P3 的闭环检查应同时覆盖 Rust crate graph 与产品 runtime 行为：边界脚本只证明依赖方向，不能替代 Deep Review、MCP dynamic tools、remote connect、snapshot wrapping、miniapp/function-agent 的产品等价性验证。
 - 当前 PR 的 P3 范围按“显式保留 core-owned runtime + 强制 owner crate 边界”闭环；后续如果要继续外移这些 runtime 路径，需要作为新的迁移批次先补 port 设计、等价测试和用户确认。
@@ -1620,6 +1641,7 @@ cargo check --workspace
 - tool registry / concrete tool implementation 外移必须先有工具清单等价测试，并保留 dynamic provider metadata；不能把注册名解析、snapshot wrapper 或 runtime restriction 行为改成隐式约定。
 - 已新增并扩展内置工具清单基线测试，后续 registry/provider 外移必须先保持该清单、注册顺序、runtime collection 顺序、dynamic provider metadata 顺序和修改类工具 snapshot wrapper 等价，再评估 owner crate 边界。
 - miniapp 与 function-agent runtime 外移必须先明确 Git/AI service、PathManager、process execution 和 permission policy 边界；如果需要行为合约变化，必须作为后续单独 PR 并先确认。
+- 产品表面 contract 补强必须保持 observational：只记录 surface/thread/environment/permission/artifact facts，不改变 CLI、Desktop、Remote、ACP 的现有交互和运行时语义。
 - `bitfun-core default = []` 和依赖版本收敛仍是后续独立评估项，不与 runtime 外移或构建脚本调整混在同一批提交。
 
 **验收门：**
@@ -1664,10 +1686,11 @@ git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts
 9. 已完成：前移低风险保护项：dependency profile / feature graph 基线、轻量 contract crate 依赖瘦身、feature group 说明、boundary check 扩展、迁移前快照测试。
 10. 进行中：PR 1 `services-integrations` runtime 收口，先处理 remote-SSH workspace registry / session mirror helper 和已迁移 file-watch 的 contract 复核；announcement 仅迁移无 config/content/remote fetch 依赖的 helper。
 11. 已完成：PR 2 MCP runtime 与 dynamic tools；已迁移 config service orchestration、server process / transport lifecycle、adapter、dynamic tool/resource/prompt provider，core 保留 ConfigService store adapter、OAuth data-dir 注入、BitFunError 映射、legacy facade 和 registry assembly。
-12. 待执行：PR 3 remote-connect runtime。
-13. 待执行：PR 4 agent tools + `tool-packs` owner 化。
-14. 待执行：PR 5 `product-domains` runtime + core facade finalization。
-15. 后续独立评估：`bitfun-core default = []` 或 per-product feature set。
+12. P2 后前置轨道：产品表面 contract-only 补强，可在 PR3 前或 PR3 第一组提交中处理；只允许 DTO/port、round-trip/no-op tests 和 boundary check，不实现 CLI/Desktop/Remote/ACP UI 或命令变更。
+13. 待执行：PR 3 remote-connect runtime。
+14. 待执行：PR 4 agent tools + `tool-packs` owner 化。
+15. 待执行：PR 5 `product-domains` runtime + core facade finalization。
+16. 后续独立评估：`bitfun-core default = []` 或 per-product feature set。
 
 冗余清理 PR 不进入上述主线序号。只有在满足 `0A.6` 的绝对等价要求时，才可以插入到相邻里程碑之间，并且不得与主线拆分 PR 混合。