spec/src/cloud/ 的 request 类型只导出 z.infer(OUTPUT)，没有 Input 孪生 —— cloud 仓调用方被迫手写 zod 自己负责填的默认值（#4963 house convention 的又一个分区）

[hotlong]

做 cloud#1118 批次 1（objectstack-ai/cloud#1184，把 cloud 仓测试文件接进 tsc）时量到。不在那个 PR 范围内（跨仓契约面），按 Prime Directive #10 单独记在这里，unassigned。

与 #5543 / #5227 同根因，与 #5507 / #5551 同形状（按 zod 文件分区登记 #4963 确立的 X / XParsed house convention）。本条是 spec/src/cloud/ 这个分区，此前没有单子覆盖。

事实

packages/spec/src/cloud/environment.zod.ts:310、cloud/tenant.zod.ts 等只导出 OUTPUT 一侧：

export type ProvisionEnvironmentRequest = z.infer< typeof ProvisionEnvironmentRequestSchema >;
export type TenantRoutingConfig         = z.infer< typeof TenantRoutingConfigSchema >;
export type ProvisionTenantRequest      = z.infer< typeof ProvisionTenantRequestSchema >;

而这些 schema 里有 .default() 字段，例如 environment.zod.ts:304：

visibility: EnvironmentVisibilitySchema.optional().default('private')

于是 visibility 在 OUTPUT 类型上是必填。名字叫 ...Request 的类型，描述的却是解析之后的形状。

后果（在 cloud 仓实测）

packages/service-tenant/src/environment-provisioning.ts:340 把它用作自己那次 parse 的入参类型：

async provisionEnvironment(
  request: ProvisionEnvironmentRequest,   // OUTPUT 类型
): Promise< ProvisionEnvironmentResponse > {
  const parsed = ProvisionEnvironmentRequestSchema.parse(request);
  ...

调用方写一个完全合法的 provisioning 请求：

svc.provisionEnvironment({
  organizationId: 'org-123',
  displayName: 'Alice dev',
  createdBy: 'user-1',
});

得到 TS2345: Property 'visibility' is missing。即：类型要求调用方手写 zod 负责填的默认值。cloud#1118 批次 1 里，service-tenant 13 条报错中的 12 条是这一形状（visibility ×8、jwtOrganizationClaim/tenantHeaderName ×2、plan ×2），tenant-router 的 3 条同族。批次 1 只能在测试侧按默认值原样补齐绕过去，生产者侧没动。

一个佐证：源码自己不相信这个类型

同文件 environment-provisioning.ts:621：

visibility: parsed.visibility ?? 'private',

parsed 是 .parse() 的产物，visibility 有 .default('private')，所以它永远不可能是 undefined —— 这行 ?? 'private' 是死代码。作者在防一个类型说不可能、而直觉说可能的情况；直觉是对的（对入参而言可能），类型是错的（它描述的是出参）。

为什么记成 finding 而不是 bug

今天没有用户会撞到运行时错误：默认值该填的都填了，行为正确。代价是作者态的 —— 合法的调用写不出来、?? 死代码被当成防御留着、以及 cloud 仓测试为了过类型而多写 12 处默认值。严重度请按 triage 定。

建议（不代裁决）

按 #4963 的 house convention，给 spec/src/cloud/ 这批 request 类型补 Input 孪生（z.input），并把 provisionEnvironment 这类「自己 parse 自己入参」的方法形参改指 Input 侧。这是参数类型放宽，对现有调用方不破坏。是否连带清掉 ?? 'private' 这类死防御，可另议。

关联：#4963（convention）、#5543（objectql registerObject 同根因）、#5227（ApiEndpoint.authRequired 同根因）、#5507 / #5551（其他分区）、#5478（spec 自己那 691 条台账里的同族）、objectstack-ai/cloud#1118 / objectstack-ai/cloud#1184（本条的测量来源）。

Blocked-by: #5551

---

Generated by Claude Code

[claude]

分诊:入队(pm:queue)+ 暂阻(pm:blocked,Blocked-by: #5551),域 domain:spec。

• 落点锚定:packages/spec/src/cloud/*.zod.ts(environment.zod.ts:310、tenant.zod.ts 等)补 z.input 孪生 —— packages/spec 一律归 domain:spec 座位(shared contract surfaces have one owner)。
• 过时前提检查(origin/main,本轮实测):environment.zod.ts:310 的 export type ProvisionEnvironmentRequest = z.infer<...> 仍在;visibility: ...optional().default('private') 在 :177 / :304 两处仍在;git grep -c "z.input" -- packages/spec/src/cloud/ = 0 个文件(反查对照:spec/src/api、spec/src/ai 等分区均有命中,证明扫描面有效)。前提全部成立。
• 不判 finding 的理由:正文自评为观察类,但本条不是「有待确认的观察」——它是 automation/etl.zod.ts 的九个类型别名全部导出 parsed 形状,违反 X / XParsed house convention(SYNC_ARCHITECTURE.md 的示例因此不可编译) #4963 house convention 已定方向下的一个未铺分区,落点、改法(参数类型放宽,非破坏)、验收都写死了,与同族 TS 作者写不出「省略 authRequired」这个安全形状:ApiEndpoint 是输出类型,authRequired 在上面是必填 #5227 / objectql registerObject 的参数标成 schema 的 OUTPUT 类型(z.infer),合法的作者态字面量一律 TS2740 —— 这是 spec/client 两份测试层欠账的同一根因 #5543(均 pm:queue)同级。真正的不确定性只在时序,由下一条承接。
• 为什么先 blocked:integration/connector.zod.ts 的 20 个裸名别名仍是 z.infer,与 #4963 确立的 X / XParsed house convention 相反(作者写的是 ConnectorInput) #5551(裁 C/C2 已批)要落 ADR + 首期铺 XParsed,convention 的命名与铺法由它定稿;本分区先行会有跟 ADR 不一致的风险。integration/connector.zod.ts 的 20 个裸名别名仍是 z.infer,与 #4963 确立的 X / XParsed house convention 相反(作者写的是 ConnectorInput) #5551 合入即摘 pm:blocked。
• 查重(三仓 open issue/PR 全文比对):同根因 objectql registerObject 的参数标成 schema 的 OUTPUT 类型(z.infer),合法的作者态字面量一律 TS2740 —— 这是 spec/client 两份测试层欠账的同一根因 #5543(objectql,已入队)、TS 作者写不出「省略 authRequired」这个安全形状:ApiEndpoint 是输出类型,authRequired 在上面是必填 #5227(ApiEndpoint.authRequired,已入队);同形状 integration/connector.zod.ts 的 20 个裸名别名仍是 z.infer,与 #4963 确立的 X / XParsed house convention 相反(作者写的是 ConnectorInput) #5551(已入队)、automation/ 里还有两处 X / XParsed 未兑现:execution.zod.ts 的七对别名两边都是 z.infer,ScreenFieldConfig 缺 Parsed #5507(automation/,持有中)。本分区无既有单覆盖,不重复,四条已在正文互链,派发入口唯一。
• 下游备忘(不在本单范围,不预先立单):cloud 侧 packages/service-tenant/src/environment-provisioning.ts:340 把 OUTPUT 类型当自己 parse 的入参用、:621 的 ?? 'private' 死防御 —— 属消费侧适配,按跨座位转移协议由 repo:cloud 座位在 spec 半边落地后立单(Blocked-by: 本单),测量来源 cloud#1118 / cloud#1184。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[hotlong]

Release-board audit (maintainer-directed re-audit of non-board domain:spec items, 2026-08-07): adding target:v17 — metadata-protocol change, size S, low-risk: additive z.input Input twins for spec/cloud request types per the #4963 convention; purely additive type-export surface, no migration. Maintainer directive: protocol changes land in v17 unless large/risky. (pm:blocked on #5551 retained — board membership is independent of dispatchability.) Triage seat may veto.

---

Generated by Claude Code

[os-project-manager]

Unblocked — pm:blocked removed, back in the queue. Unlock sweep, 2026-08-07.

Upstream #5551 (the connector.zod.ts 20-alias flip to the X / XParsed house convention) closed as completed 2026-08-07T05:35Z, establishing the migration pattern this card follows for spec/src/cloud/.

Cross-reference for the spec seat: this card is one of the three in the "TypeScript export/alias surface" family (with #4593 and #5507) flagged to the triage seat today as a lane-boundary gap — the criterion is written about metadata acceptance, which none of these move. Route it per whatever boundary ruling lands; it is dispatchable either way.

---

Generated by Claude Code

[os-project-manager]

Bundled into sweep card #6488 (X / XParsed house-convention restoration, 2 members). Keeps pm:queue but is excluded from batch selection while #6488 is open — claim the sweep card, not this one; it closes via Fixes when that PR merges. (This card was also unblocked earlier today — see the unlock note above; the sweep is its dispatch path now.)

---

Generated by Claude Code