配置了 `api.apiPath` 时,rest 的 9 条 direct-mount 路由挂在 `{basePath}/{version}` 而不是 `{apiPath}`

[qq9340100]

现象

RestServer.getApiBasePath() 与 rest-api-plugin.ts 的 direct-mount registrar 各自算了一次 API base，两者只在 apiPath 未设时相等：

• packages/rest/src/rest-server.ts — getApiBasePath() 返回 api.apiPath ?? \${api.basePath}/${api.version}``；
• packages/rest/src/rest-api-plugin.ts — const versionedBase = \${basePath}/${version}`（**不读 apiPath**），供 packages.（4 条）与 datasources/:name/external/`（5 条）两个 direct-mount registrar 使用。

于是设置了 api.apiPath 的部署上，route-manager 面整体迁到 {apiPath}，而这 9 条 direct-mount 路由留在 /api/v1/...：同一部署两个 API 前缀，{apiPath}/openapi.json 的 isUnderBase 过滤把这 9 条排除在文档之外。

复现

apiPath 无 authoring 路径（defineStack({server:{api:…}}) 被 strict 块 loud 拒绝，os serve 只转发两个 scoping 键），仅程序化 embedder 直接组合 createRestApiPlugin 可达：

createRestApiPlugin({ api: { api: { apiPath: '/backend/api/v9' } } })

启动后枚举挂载：route-manager 面全部在 /backend/api/v9/...，packages.* / datasources/:name/external/* 仍在 /api/v1/...；GET {apiPath}/packages 404，GET /api/v1/packages 200。

裁定（maintainer，2026-08-07 / 2026-08-08）

Option 1 —— 单一真相源：direct-mount registrar 消费 RestServer.getApiBasePath() 的同一个 base（thread 该值，不复制 ?? 表达式），9 条路由跟随 apiPath。不做兼容双挂载。

落地顺序按路线 B：先 #6633（discovery 通告 routes.packages / routes.datasources，且与挂载同源；SDK 从通告派生 base），再移动本卡的 9 条路由 —— 前置件已由 PR #6712 合入 main。

验收

• 设置 apiPath 时，9 条 direct-mount 路由在 {apiPath} 下应答，旧 /api/v1/... 不再服务；
• {apiPath}/openapi.json 列出这 9 条；
• /discovery 的 routes.packages / routes.datasources 按构造跟随（同源投影，通告侧无需改动）；
• 默认配置（未设 apiPath）逐字节不变。

[claude]

Triage: needs-user-decision + domain:cli + target:v17.

Both sides of the divergence verified on origin/main:

• packages/rest/src/rest-server.ts:2951 — ```js
  return api.apiPath ?? ${api.basePath}/${api.version}; // getApiBasePath()

  `apiPath` is threaded through at `:1484` / `:2890`.
- `packages/rest/src/rest-api-plugin.ts:379` — ```js
  const versionedBase = `${basePath}/${version}`;

consumed at :389, :393, :395 (packages routes) and :414 (external-datasource routes). apiPath appears nowhere in this file.

So the two prefixes are computed from different expressions, and they coincide only while apiPath is unset. Repro in the body is sound.

Why the decision inbox, not the queue. All three dispositions the body lists are contract answers, and the cheapest-looking one is a behaviour change:

1. Single-source the base ⇒ 9 route URLs move on any deployment that sets apiPath. That is a breaking change to live URLs, not a bug fix.
2. Rule that apiPath governs the route-manager surface only ⇒ formally blesses two API prefixes in one deployment, and the boundary has to be written into the key's .describe() and the reference docs.
3. Retire apiPath under ADR-0049 ⇒ removes a shipped, documented, declarable spec key.

Nothing in the code answers which one is right; this is appetite and compatibility, which is the maintainer's call (step 8), not the routing question (which is settled below and was never escalated).

Domain: packages/rest sits in the domain:cli package family, and the fix — under any of the three answers — lands in packages/rest/src/rest-api-plugin.ts and/or packages/spec's rest-server.zod.ts describe text. Labelled to the primary landing site; if the answer is (3), the spec-side removal transfers to domain:spec under "shared contract surfaces have one owner".

Release board (target:v17): criterion ② — apiPath is a declarable, documented public config key (packages/spec/src/api/rest-server.zod.ts, published to content/docs/references/api/rest-server.mdx) that is honoured by only part of the server. A key that half the routes obey is a schema that lies. Flagged so the release list shows it needs adjudication before GA rather than surfacing as a support case. It is on the board pending a decision, not pending a fix — the needs-user-decision label remains the operative state.

Not stale, and not #5822's doing. rest-api-plugin.ts has taken no change since 1363084; the divergence predates PR #6303, which deliberately left the prefix alone (moving 9 live URLs is not a rider). #6303 only made the inconsistency visible by enumerating the routes.

Dedup: all 463 open issues and PRs paginated. No duplicate. Neighbours: #5822 / PR #6303 (the discovery site, different disposition surface, explicitly documented as out of scope there) and #5969 (components.schemas unreferenced in the served OpenAPI — same document, different defect).

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[os-project-manager]

Maintainer ruling — 2026-08-07. The maintainer reviewed the PM's three-axis analysis of the decision inbox and accepted the recommendations (「你帮我综合评估，我接受你的建议」). Recorded by the PM session; needs-user-decision comes off with this comment.

Decision: Option 1 — single source of truth for the API base. Expose the base computation from RestServer.getApiBasePath() (or an equivalent shared helper) and make rest-api-plugin.ts consume it, so all 9 direct-mount routes (packages.*, datasources/:name/external/*) follow apiPath.

Rationale: default deployments are unchanged (apiPath unset ⇒ identical prefixes); the only behavior change lands on deployments that set apiPath — exactly the ones currently split-brained, and fixing them is the point. Option 2 (documenting two prefixes per deployment) is a standing trap for every future author; Option 3 (retiring apiPath) pays a removal ceremony for a legitimately useful reverse-proxy key.

Acceptance: with apiPath set, the repro in the body flips — {apiPath}/packages answers 200 and the old /api/v1/packages no longer double-serves; /openapi.json under {apiPath} lists all 9.

---

Generated by Claude Code

[os-project-manager]

认领 — dev agent 开始实现。

• Session ID: session_017uFVNMmTxLpmfQYiuKM1Yx
• Branch: claude/issue-6306-direct-mount-follows-apipath
• 依据 2026-08-07 maintainer ruling(Option 1,单一真相源):direct-mount registrar 复用 RestServer.getApiBasePath() 的同一 base 表达式,9 条路由跟随 apiPath。不做兼容双挂载。

---

Generated by Claude Code

[os-project-manager]

继续实现（同一会话的 re-dispatch,前一个 dev agent 在写码前因 API session-limit 中断）。

• Session ID: session_017uFVNMmTxLpmfQYiuKM1Yx（与上一条认领相同）
• Branch: claude/issue-6306-direct-mount-follows-apipath(复用已有 worktree)

---

Generated by Claude Code