150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例

#4570 把 reference 页的 import 示例改成对照 api-surface.json 真实导出面生成之后,顺带把「推导得到但导出面里查无此名」的名字全部落成了棘轮基线 packages/spec/docs-import-surface.baseline.json。目前 154 条,其中 150 条是 no type export:schema 常量 XSchema 正常导出,但对应的 export type X = z.infer< typeof XSchema > 不存在。

为什么值得单独跟

这 150 个 schema 的文档页现在只有 import { XSchema } 一行,没有 import type { X }。对手写代码的人只是不方便;对 AI 写元数据应用的人是缺一半契约——他能拿到运行时校验器,却没有可以标注变量、写函数签名的类型,只能退化成 any 或自己 z.infer<>(而 z 的版本和 lazySchema() 包装并不总是好写)。

分布很集中,像是历史习惯而非有意设计:system/ 的可观测性枚举(LogLevel、SpanKind、MetricType、TaskStatus …)、ui/ 的 Element*Props / Page*Props 一族、data/ 的若干 request 形状(DataEngine*Request)。完整清单见基线文件。

需要决策的点

补齐:给这 150 个逐一加 export type。方向上正确(声明即导出、类型可用),但一次性把 api-surface.json 撑大 150 个导出,是可观的公共面扩张,需要维护者点头;
按需补:只补真正会被外部引用的(枚举类、request/props 形状),其余保留在基线里并注明理由;
维持现状:基线已经把它们变成可数、可审的债务,新增的会被 check:docs 挡红,存量慢慢还。

倾向 (2):枚举与 props 形状是元数据作者最常需要标注的,补起来收益最直接;而纯内部的中间 schema 留在基线里,比硬凑一批没人用的导出更诚实。

无论选哪条,修复方式都一样:加别名 → gen:api-surface → gen:docs,并删掉基线里对应的行(只减不增的棘轮,陈旧条目同样会让 check:docs 变红)。

发现于 #4570。

裁决(PM 代决,维护者可否决):策略 (2) 按需补 ——

优先补两类:枚举类(system/ 可观测性枚举)与 request/props 形状(ui/ Element*Props/Page*Props、data/ DataEngine*Request)——这些是 AI 使用者最需要可标注类型的位置;
路径统一:加 export type 别名 → gen:api-surface → gen:docs → 删基线行;棘轮只减不增(基线现为 138 条,全部 no-type-export);
不一次性全补:一次撑大 api-surface 约 150 个导出而无消费方验证,与 Response bodies are never checked against the schemas that declare them — staged plan, not a repo-wide sweep #3877 Stage C 不排期同理;
新增 spec 形状(spec: dashboard date filter 的 defaultValue 没有作者时校验 —— 拼错的预设名要到浏览器控制台才被发现 #4614 / ConnectorActionDescriptor declares nothing about whether an action reads or writes, so the platform cannot count what a connector_action did #4395 / [i18n] 为 flow 与 workflow 提供可作者化的标签和节点翻译契约 #4426 等)一律自带类型别名,不添新债——此条作为后续 spec PR 的评审项。

防 AI 轴:有可标注类型,使用侧才不会退化到 any 或自己 z.infer 被 lazySchema() 拖累。已入队待派(按需分批)。

Generated by Claude Code

fix(objectstack-ai#4570): spell reference-doc import examples from th…

Release-board audit (maintainer-directed re-audit of non-board domain:spec items, 2026-08-07): adding target:v17 — metadata-protocol change, size M, low-risk: strategy 2 already ruled — batch-add export type aliases for enums/props/request shapes so the 150 published schemas get import type examples; purely additive type-export surface, the ratchet baseline only shrinks and check:docs gates it. Maintainer directive: protocol changes land in v17 unless large/risky. Triage seat may veto.

Generated by Claude Code

Maintainer ruling (2026-08-08): Option B — the remaining 40 non-isomorphic schemas stay on the baseline; no XParsed pairs are minted without a measured consumer.

Rationale (three-axis review):

Business: XParsed has zero measured consumers today — minting 40 unconsumed public names is exactly the shape the startup-focus principle exists to stop.
Long-term: every name that enters api-surface costs a major to exit. Not minting is free today; minting wrongly is a batch of future ADR-0049 retirement debt. The asymmetry decides it.
AI-error containment: the check:spec-parsed-alias ratchet already blocks new drift, so the unused aliases would add no protection for AI authors.

The fallback (aliasing only the ElementProps / DataEngineRequest families) stays available if a real parsed-state consumer shows up — reopen or file fresh on measured demand. Standing rules unchanged: the baseline ratchet is shrink-only, and every new spec shape ships with its alias.

Bookkeeping: batch 1 shipped via PR #6606 (73 aliases + 73 ADR-0122 pins, merged 2026-08-08). Of the remaining 63 baseline entries: 17 belong to the #4570 rename track, 5 live in in-flight host files, 1 (ServiceStatus dual-source) is #6604, and the 40 are decided here. Closing as completed; with the decision made this card exits the v17 board.

Maintainer directive (verbatim, covering all 14 inbox cards): 「你的建议全部接受」. Recorded by PM session session_01JaVVMrSxt7Tgi1uwEuDtH7.

Generated by Claude Code

refactor(spec): rename ./system ServiceStatus to KernelServiceStatus (o…

test(spec): keep the pin file's prose true after the re-key

test(spec): name each isomorphic pin for its module and schema, sorted (

Navigation Menu

Repository navigation

150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例 #4593

为什么值得单独跟

需要决策的点

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

150 个已发布 schema 没有配套的 export type 别名,reference 页给不出 import type 示例 #4593

Description

为什么值得单独跟

需要决策的点

Activity

os-zhuang commented on Aug 3, 2026

hotlong commented on Aug 7, 2026

os-zhuang commented on Aug 8, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions