feat(ql3): expose run comparison over local mcp

docs/adr/ADR-0401-optional-local-mcp-run-comparison-surface.md

@@ -0,0 +1,88 @@
+# ADR-0401：可选本机 MCP Run 对比产品入口
+
+- 状态：Accepted
+- 日期：2026-08-14
+- 关联 RFC：QL-RFC-0001 D-309、Phase 2
+- 关联 ADR：ADR-0347、ADR-0351、ADR-0400
+
+## 问题
+
+ADR-0400 已在 Runtime Core 建立 `qinglong.run.compare@1.0.0` 的稳定 Definition、低敏
+projection 和受信 adapter，但尚无产品 composition 使用它。QingLong 3.0 的外部 AI 客户端
+因此只能分别调用两个 Run 点查，再自行拼接差异；这无法让服务端统一执行输入约束、Project
+屏蔽、差值算法和一致性声明，也没有独立的调用审计理由。
+
+本机已经有由 ADR-0347 建立的可选 `ql3-mcp` stdio 进程。它逐调用执行认证、Tool Policy、
+durable Security Audit、credential fence confirmation 和有界 SQLite read，且只在部署者显式
+选择 `edge-mcp|standalone-mcp` 制品时加载 MCP SDK。新增对比能力不应再造进程、package、
+数据库 authority 或后台服务，也不能把 MCP 依赖带入默认低配 Profile。
+
+## 决策
+
+1. 在既有 `@qinglong/local-mcp-server` 静态只读 Tool 集合中注册
+   `qinglong.run.compare@1.0.0`。Definition 与执行投影必须直接来自 Runtime Core 的
+   `/builtin-run-compare-projection` 显式 subpath；MCP 不复制 schema、字段裁剪或差值算法。
+2. 调用沿用同一固定顺序：每次重新认证 → 授权
+   `tool.call:qinglong.run.compare` → 授权 `run.read` → durable audit → confirm credential
+   fence → baseline/candidate 两次有序 Project-scoped point read。允许审计理由固定为
+   `tool_qinglong_run_compare`，repository/投影失败只返回稳定
+   `run_compare_unavailable`。
+3. MCP Tool 继续声明 `readOnlyHint=true`、`destructiveHint=false`、
+   `idempotentHint=true`、`openWorldHint=false`。Project ID 只来自私有进程配置，客户端不能
+   选择；找不到与跨 Project 均由共享投影输出 `found:false`。
+4. 该入口属于 ADR-0347 的轻量交互式只读 surface：它持久记录安全 admission，但不冒充
+   ADR-0163 的 encrypted Tool execution completion、StepRun 或模型 Trace。Agent/Copilot
+   内部经 Run/StepRun 执行受信 Tool 时仍必须走完整 start/result completion 链；未来如需让
+   MCP 调用本身成为 Run，必须独立设计 correlation 与重放语义，不能在本协议中静默增加写入。
+5. 不新增 workspace package、依赖、migration、表、索引、连接、timer、listener、watcher、
+   cache 或网络 endpoint。`LocalSqliteMcpReadDatabase` 现有
+   `findRunById` authority 已足够，不扩大其读写接口。
+
+## 低配与部署影响
+
+- 默认 Edge/Standalone application 与制品继续不导入 MCP package；未选择 MCP 的路由设备
+  没有新增安装体积、模块加载或空闲 RSS。
+- 选择 MCP 的设备只增加一个静态 descriptor；单次对比最多增加两次串行 Run 点查，不产生
+  并发数据库连接或后台采样。
+- Cluster Control 不通过本 ADR 开放 MCP endpoint。Cluster 的受信 Tool composition、远程
+  身份、限流和 PostgreSQL completion 仍须独立门禁。
+- 实现留在已有 deployable MCP package 内，不为单个 adapter 创建微型 package，也不把
+  MCP-only glue 移入 Runtime Core。
+
+## 被否决方案
+
+1. **复制 Run compare 到 MCP `tool-projection`**：该语义已有 Runtime Core adapter 和 MCP
+   两个消费者，复制会产生 Definition 与差值漂移。
+2. **让客户端组合两次 `run.get`**：服务端无法冻结读取顺序、一致性声明和审计语义。
+3. **把 MCP Server 加入默认 Edge application**：会让不使用 AI 的低配设备承担 MCP SDK
+   依赖与约 40 MiB 级加载成本。
+4. **为 compare 新建 package 或数据库 adapter**：没有独立生命周期、authority 或依赖隔离
+   收益，现有窄 reader 已满足需求。
+5. **把交互式 MCP 读取伪装成完整 Trusted Tool completion**：缺少 StepRun/Artifact/key/
+   replay correlation 事实，会给恢复和审计造成错误承诺。
+
+## 当前验证
+
+1. Local MCP 46/46：Tool discovery、固定 read-only annotations、双 permission、allowed audit
+   reason、credential confirm、两个有序读取和共享差值投影全部通过。真实 stdio E2E 使用
+   fresh production migration SQLite、真实 Owner credential 与 Project Policy，比较两个真实
+   Run 后验证第九条 durable allowed audit。
+2. 最终 18-package clean build/test 退出 0；backend 1,208 项为 1,206 pass、2 条平台条件
+   skip、0 fail。package boundary 保持 18 个 package，`singleSourcePackages=[]`、
+   `shallowSourcePackages=[]`；Cluster dependency、Edge import 与 Cluster deployment 审计
+   均无 finding。
+3. 默认 Edge artifact 为 2,589,812 bytes/315 files/56 loaded modules，import RSS 增量
+   11,091,968 bytes，继续完全裁掉 MCP Server 与 SDK。Edge-MCP 为 7,219,977 bytes/
+   792 files/217 modules、RSS 增量 38,649,856 bytes；Standalone-MCP 为 7,220,085 bytes/
+   792 files/217 modules、RSS 增量 38,043,648 bytes，均低于 16 MiB/1,536 files/48 MiB 门。
+4. GitNexus 对 `LOCAL_MCP_READ_TOOLS` 报告 LOW、0 上游；
+   `createQingLongLocalMcpServer` 为 LOW、1 个直接产品调用方、0 条 execution flow。
+   dependency firewall 的 `auditSourceImports` 为 LOW、1 个直接测试调用方、0 条 flow；
+   allowlist 只增加 exact compare projection subpath，宽 authority 负向门仍通过 53/53。
+
+## 后续门禁
+
+1. 增加按 Task 有界选择最近成功/失败 Run 的服务端 Tool，禁止模型执行无界搜索；
+2. 日志解释另建 Artifact range、redaction、prompt-injection 和字节预算协议；
+3. Copilot 调用走 Run/StepRun 与 encrypted result completion，建立模型/Tool Trace correlation；
+4. 固定物理 Edge MCP 延迟/RSS 和真实撤权竞态证据。

docs/adr/README.md

@@ -404,6 +404,7 @@
 | [ADR-0398](./ADR-0398-pre-activation-plugin-package-candidate-qualification.md)                             | Plugin Package 激活前候选资格校验与自动保留旧版本                                                                                       | Proposed（v2 私有报告/离线审计已编排、全量/HA 门完成；远端 Kubernetes 成功记录与物理低配门待闭合） |
 | [ADR-0399](./ADR-0399-external-release-attestation-for-physical-edge-evidence.md)                          | 物理 Edge 证据的外部发布归档证明                                                                                                           | Accepted（exact recorder 重建与离线验签已实现；固定实机 ceremony 待执行） |
 | [ADR-0400](./ADR-0400-bounded-trusted-run-comparison-tool.md)                                             | 有界、受信的 Run 对比 Tool                                                                                                                   | Accepted |
+| [ADR-0401](./ADR-0401-optional-local-mcp-run-comparison-surface.md)                                      | 可选本机 MCP Run 对比产品入口                                                                                                                  | Accepted |
 
 ## 规则