discovery 广播「跨对象原子 batch」能力位(让客户端声明式协商,取代 404/405/501 运行时探测)

[os-zhuang]

背景

POST /api/v1/batch(跨对象原子批量,#1604 / ADR-0034 item 4)已落地。SDK 侧 client.data.batchTransaction() 也已合并(#3271)。但服务端 discovery 响应目前不声明「本后端是否支持原子跨对象 batch」。

GET /api/v1/discovery 现在只产出 routes / scoping / mcp(见 packages/rest/src/rest-server.ts 的 discovery 生产者 + packages/spec/src/api/discovery.zod.ts 的 ApiRoutesSchema/capabilities),没有 batch 能力信号。

问题

客户端(尤其 ObjectUI 的 ObjectStackAdapter)现在只能靠运行时探测判断后端支不支持原子批量——打一次 /batch,看返回 404/405(端点不存在)或 501(运行时不支持事务),失败再降级到非原子客户端模拟。这是"打了才知道",不是声明式能力协商:

• 无法在连接时提前决策;
• 无法作为"最低支持后端版本已具备 /batch"的判据 —— 这正卡住了 ObjectUI 侧硬删除非原子模拟回退(见 objectui#2679 验收第 4 条 / 其配套 issue)。

方案

在 discovery 契约里新增一个能力信号(命名待定,如 capabilities.transactionalBatch: true,或一个最低版本号),由所有 discovery 生产方真实填充:

• packages/spec/src/api/discovery.zod.ts — schema 定义;
• packages/rest/src/rest-server.ts(discovery 生产);
• packages/plugins/plugin-hono-server(hono discovery);
• metadata-protocol(protocol discovery)。

⚠️ 关键约束(否则又是一个 declared-but-unpopulated 路由)

加了 key 就必须每个生产方都真实填充,否则会变成"声明了但没人填"的空能力位——这正是 #3271 里故意不给 ApiRoutesSchema 加 batch key 的原因(避免 3+ 处生产者失配)。所以本 issue 的验收必须包含"三处生产者同步填充 + 测试断言 discovery 里带该位"。

验收

• discovery schema 新增 batch 能力位;
• rest-server / hono-plugin / metadata-protocol 三处生产者均填充;
• 测试断言 GET /discovery 返回该位;
• @objectstack/client 暴露该能力供消费方读取(可选)。

关联

• 承接 Cross-object atomic batch write (master-detail parent+children in one transaction) #1604 / ADR-0034 item 4;SDK 方法见 feat(client): 类型化 data.batchTransaction() —— master-detail 保存统一走原子跨对象批量(#1604 / ADR-0034 item 4) #3271(已合并)。
• 下游依赖:ObjectUI 侧"硬删除非原子模拟回退"以本 issue 为前提。