[REQ-084] Alpha 页面通过窄 typed surface 接入路由

[jinjunnn]

简明目的

给 Alpha 页面一个稳定、很小的接入口，避免继续复制上游内部路由和 Provider，也不再保留旧页面回退开关。

Outcome（专业定义）

@opencode-ai/app 暴露最小、版本化的 typed surface seam，使 Alpha 的 Home、Draft 与 Session 叶页面在保持必要 Provider 生命周期的前提下由正式 route composition 挂载；所有深层 upstream context 依赖收敛在 adapter 边界。REQ-084 只定义接缝与结构性存活契约，最终 route manifest 和 alias/redirect 真相由 REQ-089（#204）拥有。

Complexity

M — 跨 package 的公开类型、Provider 生命周期与冻结同步守卫需要多处改动，但不引入新的安全域或数据迁移。

Context

窄 typed seam 与路由 helper 已有基础实现，剩余问题主要是行为证据与旧 fallback 清理。现有 #257 仍以“持久化 fatal 后回 legacy”为目标，已与“无既有用户、单一正式路由”原则冲突；#204 才是最终路由真相。

Scope

• 保留窄的 Home/New Session/Session leaf surface contract 和必要 preload 行为。
• 明确 Provider remount、server/directory/session 作用域和生产挂载点。
• 让 seam 在 upstream frozen-frontend restore 后可机械验证、漂移即阻断。
• 将消费者从重复 regex/codec 迁到临时统一 helper，并为 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204 接管 route manifest 留出单一边界。

Non-goals

• 不定义完整 route table、alias、redirect 或最终 href 规则；归 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204。
• 不实现 Home、Draft、Session 具体产品行为；分别归 [REQ-085] Home 在正式路由中可靠创建 Session #200、[REQ-086] Draft 在正式路由中可恢复地晋升为 Session #201、[REQ-088] Alpha Session Shell 稳定挂载并管理生命周期 #203。
• 不保留 alpha|legacy|auto-fallback、same-URL legacy reload、双页面预载或旧 Provider tree 热切换。
• 不公开全部 upstream context，也不允许 Alpha 页面 deep import packages/app/src/context/**。

Acceptance criteria

AC1. Home、New Session 与 Session 可分别通过窄 typed surface 注入，未被选择的叶页面不会同时挂载或预载。
AC2. typed surface 只暴露 Alpha 所需 props/events，不泄漏 upstream 私有 context 类型。
AC3. server、directory、draft 与 session 的 remount 规则在 Web Router 与桌面 MemoryRouter 中保持确定且一致。
AC4. 生产 route 入口直接调用 seam；Alpha 页面不存在对 upstream 隐藏 DOM、Portal anchor 或私有 context 的旁路依赖。
AC5. 上游前端版本升级(滚动 pin)后,若 Alpha 依赖的页面接缝形状发生变化,本地检查失败,而不是静默通过。 (2026-09-17 按 owner 裁决改写,原文见编辑历史)
AC6. legacy surface flag、fatal 后 legacy reload 与双 composition 路径被移除；失败显示可恢复错误但不切回旧页面。
AC7. #204 接管 route manifest 后，本 seam 仍只是叶页面挂载接口，不形成第二套路由真相。 —— 2026-09-17 删除(owner 裁决):与 REQ-089(alpha-code#204)AC2「不存在第二套路由真相」重复,证据已由该需求的 route-authority-ratchet 承载。

Evidence map

AC	Evidence surface
AC1	packages/ui-mac/src/renderer/route-composition.test.ts:28
AC2	packages/ui-mac/src/renderer/alpha-ui/surface-seam-contract.test.ts:77、:116
AC3	packages/ui-mac/src/renderer/surface-remount.test.ts:154-224
AC4	route-composition.test.ts:56-73(源码文本断言,证据形态弱,owner 2026-09-17 裁决接受)
AC5	packages/ui-mac/src/shared/route-upstream-shape.test.ts(ADR-034 滚动 pin;PR #638)
AC6	packages/ui-mac/src/renderer/alpha-ui/surface-boundary.test.ts:18 + packages/ui-mac/src/shared/route-authority-ratchet.test.ts:128/:136
AC7	已删除(见 AC7)

Acceptance owner

@jinjunnn — 按 AC 逐条验收并手工关闭；PR 不得关闭父需求。

设计要点

• seam 应是小型 leaf contract，不复制完整 Router 或 Provider 图。
• 运行时错误恢复保留当前输入/状态，避免以 legacy 页面作为恢复机制。
• seam/version 不认识的未来值应 fail closed；这不是旧页面兼容。
• upstream 同步必须先验证再进入可推送阶段，相关权限边界见 上游同步候选无法使用仓库推送凭据 #227。

潜在问题与风险

• [REQ-084][CODE] Remove fatal legacy fallback and recover through the typed surface #257 当前目标会重新引入旧页面兼容和双状态真相。
• seam 与 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204 同时解析路径会产生 double composition 与 redirect 分歧。
• 只测模块不测生产入口，可能出现“接口存在但正式路由未调用”。
• Provider remount 错误会泄漏跨目录/跨 server 状态。

过时性与兼容性结论

需求核心有效且已部分交付；旧 legacy fallback、热切换和旧 URL 兼容责任已过时，应删除。保留窄 seam、状态作用域正确性、同步漂移 fail-closed 与未来版本拒绝。

关联与职责边界

• [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204 是 canonical route manifest、alias、redirect 与 composition 的最终权威。
• [REQ-085] Home 在正式路由中可靠创建 Session #200/[REQ-086] Draft 在正式路由中可恢复地晋升为 Session #201/[REQ-088] Alpha Session Shell 稳定挂载并管理生命周期 #203 只实现各自 surface 行为。
• 上游同步候选无法使用仓库推送凭据 #227 拥有 upstream sync 的只读候选与特权推送分权。
• [VERIFY][cap:session-surface] Router/MemoryRouter leaf-XOR、preload、provider remount、fatal reload 矩阵 #322 是 route/surface capability 的共享 VERIFY。

Delivery plan / 建议子票

• [REQ-084] LegacyRouteAbiV1、typed surface seam 与冻结契约 #177 — typed seam 基础实现。
• [REQ-084][CODE] Remove fatal legacy fallback and recover through the typed surface #257 — 删除 fatal legacy fallback，并由 typed recovery 接管（由 PR feat(ui-mac): REQ-089 路由权威残余 —— 上游形状 ratchet、deep-link 单一解码权威、legacy surface 硬切 #638 交付，已关）。
• [REQ-084][CODE] Run seam tests during frozen-frontend restore and align base-3 authority docs #258 — frozen-frontend restore 与权威文档对齐（冻结前端已被 ADR-034 滚动 pin 取代，已关）。
• [VERIFY][cap:session-surface] Router/MemoryRouter leaf-XOR、preload、provider remount、fatal reload 矩阵 #322 — Router/MemoryRouter、leaf-XOR、preload、remount、fatal recovery 验证（已关）。

Dependencies

• 最终路由收口依赖 [REQ-089] Alpha route manifest 成为唯一的路由组合真相 #204。
• 未发现需要保留的既有用户兼容数据。

[jinjunnn]

2026-07-12 评审预决策倾向（用户采纳；最终在 ADR-027 门内定）

Scope §5「冻结同步集成」的二选一，预倾向 新冻结基点（建立包含中性 typed seam 的 frontend-freeze-base-2），而非「恢复后机械 seam patch」：

• patch 方案 = 新增一个需要持续维护的补丁面（基点/上游漂移时反复修 patch），与 ADR-020 选冻结的初衷（摆脱逐次跟随）相悖；
• 新基点方案走 ADR-020 §5 既有的受控 re-freeze 通道（体检清单现成），机制零新增；seam 进基点后 restore_frozen_frontend 无需附加步骤，Acceptance §8 天然满足。

分级依据见 ADR-029《上游主权阶梯》草案（proposed，待拍板）：新基点 = L3 冻结接管的既有通道；恢复后 patch = 新增一台 L2 机器。镜像修订已同步 docs/requirements/REQ-084-alpha-surface-seam.md。

[jinjunnn]

补记：ADR-029《上游主权阶梯》已于 2026-07-12 当日拍板 accepted（随 PR #233 入库）。上方预决策倾向评注中的「草案待拍板」表述以此为准。