# ADR 0001: Search-ready local runtime bootstrap

- Date: 2026-05-28
- Status: accepted

## Context

`make dev:server` 的默认本地 TiDB playground 不包含消息搜索 FULLTEXT 所需的 TiFlash / TiDB Ultra 能力，因此无法在本地稳定验证 message-search readiness、backfill、finalize 和 promote-ready 路径。

我们需要一条 opt-in 的本地开发 profile，满足下面的约束：

- `make dev:server` 保持唯一入口，默认不启用重型 FTS runtime；
- 可选能力统一由 `AGENTTEAM_DEV_FEATURES` 选择；
- FTS runtime 逻辑收敛在独立的 `dev/` module 内，但与普通 TiDB playground 逻辑保持边界；
- 尽量少依赖 repo 内持久化的外部二进制/元数据；
- 可以在当前 worktree 内独立启动、复用和清理；
- 能保证当前开发库里的所有 workspace 都完成 workspace-global message-search readiness。

## Decision

### 1. 入口与边界

- 保持 `make dev:server` 作为唯一入口。
- 不新增 `make dev-search` 或第二套开发编排器。
- 通过 `AGENTTEAM_DEV_FEATURES=FTS` 启用 FTS profile，runtime bootstrap 实现收敛进 `dev/` module。

### 2. 本地 runtime bootstrap

- 使用 workspace-local `TIUP_HOME`，放在当前 worktree 的 `.data/dev/ultra/tiup-home`。
- 使用 coarse-grained lifecycle lock，围绕 ensure-to-ready / stop-clean 流程串行化。
- 运行时从内网 TiUP mirror `http://10.2.103.2:8989` bootstrap。
- `root.json` 不持久化在 repo 内；运行时从 `http://10.2.103.2:8989/root.json` 拉取。
- 内网环境接受 TOFU over HTTP。
- 本地 runtime 只保留一套内置 profile：`tiup playground v9.0.1 --mode tidb-ultra`。
- 当 `AGENTTEAM_DATABASE_DSN` 指向非本地 TiDB 时，跳过本地 runtime bootstrap，直接复用远端 DSN。

### 3. Search readiness orchestration

- 高层 readiness helper 只保留一层 global 能力：确保当前数据库里的所有 workspace 都 ready。
- workspace 枚举顺序固定为 `created_at ASC, id ASC`。
- 已 ready 的 workspace 走 fast path。
- 未 ready 的 workspace 顺序执行 backfill → finalize → promote-ready。
- 第一个 workspace 失败时立即返回；不做全库聚合失败。
- 整个 ensure-ready 流程有显式总 timeout。
- phase 进度日志写 stderr，最终结果写 stdout JSON。

### 4. Admin surface cutover

- 外部命令从 `scope-message-search-*` 直接改名为 `workspace-message-search-*`。
- low-level repair/debug surface 只支持 workspace-global readiness row。
- 删除外部 `scope_id`、`workspace_global` 模式切换和 projection selector。
- low-level 单 workspace targeting 只保留 `AGENTTEAM_WORKSPACE_MESSAGE_SEARCH_WORKSPACE_ID`。
- 不保留兼容期，直接切换。

## Consequences

### Positive

- `make dev:server` 默认继续保持轻量，只有设置 `AGENTTEAM_DEV_FEATURES=FTS` 的开发者才进入重路径。
- runtime 状态隔离在当前 worktree，减少不同 worktree 之间的污染。
- search readiness 的日志、失败定位和执行顺序可复现。
- 外部 admin surface 和真实语义一致：只有 workspace-global，没有假的 scope/projection 选择器。

### Negative

- `AGENTTEAM_DEV_FEATURES=FTS make dev:server` 依赖内网 TiUP mirror 可访问。
- 本地 search-ready runtime 比默认 `make dev:server` 更重，启动时间更长。
- 直接 cutover 命名后，旧命令/旧环境变量不会继续兼容。

## Follow-up

- 在开发手册、message-search spec、storage spec 和 rollout 文档中同步新的命令名与 workspace-global contract。
- 为 `agentteam-tidb-admin` 和 `internal/devsearch` 增补测试覆盖。