Skip to content

RestServerConfig.openApi31(OpenApi31Extensions / Callback / OpenApiWebhookEvent)declared ≠ enforced:没有任何运行时读取它 —— ADR-0049 enforce-or-remove 候选 #4579

Closed
#4764
Closed
RestServerConfig.openApi31(OpenApi31Extensions / Callback / OpenApiWebhookEvent)declared ≠ enforced:没有任何运行时读取它 —— ADR-0049 enforce-or-remove 候选#4579
#4764
Assignees
os-zhuang
Labels
pm:queueprotocol:breaking

Description

@os-zhuang
os-zhuang
opened on Aug 2, 2026

在 #4572(spec 双源 C1)的三仓消费方扫描中发现,范围外,按第十条军规立案。

现象

packages/spec/src/api/rest-server.zod.ts 的 OpenAPI 3.1 扩展块整体是 declared-but-unenforced:

  • RestServerConfigSchema.openApi31(OpenApi31ExtensionsSchema:webhooks / callbacks / jsonSchemaDialect / pathItemReferences)是可作者化的配置键,但 没有任何运行时读取它:
    • packages/rest/src/rest-server.ts 的 normalizeConfig 只读 api / crud / metadata / batch / routes,openApi31 被静默丢弃;
    • GET <basePath>/openapi.json 由静态 @objectstack/spec/openapi.json 加载后 enrich,不看配置;
    • packages/spec/scripts/build-openapi.ts(gen:openapi)零 webhook/callback/openApi31 引用;
    • plugin-hono-server 只透传 RestServerConfig,同样无人消费该键。
  • CallbackSchema / OpenApiWebhookEventSchema(spec 双源 C1:WebhookConfig / WebhookEvent —— ./api ≠ ./integration(4 条,#4535 C 组) #4572 中由 WebhookEventSchema 改名)与 OpenApi31ExtensionsSchema 三个导出在三仓(framework / cloud / objectui)的 import 级消费方均为零(各自的单测除外)。

即:作者在 openApi31.webhooks 里声明的 webhook 定义永远不会出现在服务出的 OpenAPI 文档里 —— 典型的「declared ≠ enforced」(Prime Directive #10 corollary),与 #3197(connector webhooks 声明未强制)同类。

建议处置(二选一,ADR-0049)

  1. enforce:让 /openapi.json 的 enrich 阶段把 openApi31.webhooks / callbacks 合入输出文档(OpenAPI 3.1 顶层 webhooks 是标准能力);或
  2. remove:整块删除(openApi31 键 + OpenApi31ExtensionsSchema + CallbackSchema + OpenApiWebhookEventSchema)。这是插件 TS 配置面(非 metadata 文件),但 openApi31 是 authorable-surface 记账键,删除需走 authorable-surface 台账 + major changeset;RestServerConfigSchema 非 strict,删除后作者继续写 openApi31 会被静默剥离 —— 需评估是否要 UNKNOWN_KEY_GUIDANCE/tombstone 位。

#4572 已把 ./api 侧死掉的 WebhookConfig(Schema) 删除、WebhookEvent(Schema) 改名 OpenApiWebhookEvent(Schema)(消歧,不改变本 issue 的判定);本 issue 决定剩余整块的去留。

关联:#4572(发现现场)、#3197(同类:connector webhooks declared-not-enforced)、#4535(双源清账主单)、ADR-0049。

Activity

  1. os-zhuang
    added
    pm:queue
    protocol:breaking
    needs-user-decision
    on Aug 2, 2026

  2. os-zhuang commented on Aug 2, 2026

    @os-zhuang
    os-zhuang
    on Aug 2, 2026 – with Claude
    ContributorAuthor

    裁决(维护者 2026-08-02 委托,按四轴评估:长远合理性 / 防 AI 静默犯错 / 实际业务 / 不扩边界):remove —— openApi31 键 + OpenApi31ExtensionsSchema + CallbackSchema + OpenApiWebhookEventSchema 整块删除。

    • 边界:enforce 等于新建「配置驱动的 OpenAPI webhooks/callbacks 文档合成」能力——三仓零消费者、零运行时读者,没有业务在等它。创业阶段不为死键立功能。
    • 防 AI 犯错:作者写进 openApi31.webhooks 的定义永远不会出现在 /openapi.json,典型 declared ≠ enforced 假合规,制造虚假完成。
    • 长远:OpenAPI 3.1 webhooks 是标准能力,将来有真实需求时以 enforce 路线回来(经 ADR);从干净地面重建比维护死键便宜。

    实施按正文备注:authorable-surface 台账 + major changeset;RestServerConfigSchema 非 strict,需补 UNKNOWN_KEY_GUIDANCE / tombstone 位,防止作者继续写 openApi31 被静默剥离。v17 窗口内落地。

    Generated by Claude Code

  3. os-zhuang
    removed
    needs-user-decision
    on Aug 2, 2026
  4. os-zhuang
    self-assigned this
    on Aug 3, 2026

  5. os-zhuang commented on Aug 3, 2026

    @os-zhuang
    os-zhuang
    on Aug 3, 2026 – with Claude
    ContributorAuthor

    🔒 认领(实施 A 线;#3207 已收口于 PR #4734,#3715 核实为已实现并关单)

    Generated by Claude Code

  6. os-zhuang
    added a commit that references this issue on Aug 3, 2026

    feat(spec)!: 退役 RestServerConfig.openApi31 整块 —— declared ≠ enforced,…

    77cd00e

  7. os-zhuang commented on Aug 3, 2026

    @os-zhuang
    os-zhuang
    on Aug 3, 2026 – with Claude
    ContributorAuthor

    🔁 入队协议 rebase 记录(PR #4764,session_0176qgxgCXTJCUv4YFLtusP9)

    {"rebased_onto": "832047c57", "checks": {"check:generated": "8/8 PASS", "check:dual-source-exports": "PASS (baseline 6, unchanged)", "spec_test": "292 files / 7348 tests passed", "spec_typecheck": "exit=0"}, "pushed": "77cd00ee8 (--force-with-lease)"}

    Generated by Claude Code

  8. os-zhuang commented on Aug 3, 2026

    @os-zhuang
    os-zhuang
    on Aug 3, 2026 – with Claude
    ContributorAuthor

    ✅ PM 验收通过(session_0176qgxgCXTJCUv4YFLtusP9,04:25Z):PR #4764 已转正并启用 auto-merge。

    核验记录(本地实测,不采信自报):

    • 内容(rebase 前已全查):OpenApi31ExtensionsSchema / CallbackSchema / OpenApiWebhookEventSchema 三 def 整删,api-surface −6、manifest −3、authorable −15/+1(openApi31 以 retiredKey() 墓碑入账 [RETIRED]);迁移登记 D3 语义迁移的「插件 TS 配置面、stack 树无源可改写 ⇒ 免 D2」论证成立;pin 全入口负断言 + 防空转守卫;墓碑 sabotage 与 S1 双通道记录完整。
    • changeset 处置:新增 major 据实(TS2305 + 键删除、零元数据迁移);同 major 内吸收 spec 双源 C1:WebhookConfig / WebhookEvent —— ./api ≠ ./integration(4 条,#4535 C 组) #4572 的 WebhookEvent→OpenApiWebhookEvent 改名并更正旧 changeset 指向被删导出的 TO 指引——「改名不发货为着陆点」的注记是诚实做法。
    • 入队协议:两轮 rebase(→ 5647006 → 832047c),生成物从合并树重生;merge-base 实测 = 832047c,与 main 尖(040ecd2)之间仅隔 service-messaging 一单,与 spec 零重叠,无需三轮 rebase。基线零触碰(保持 6,本单非双源行)。
    • 分区:11 文件全落 api 区 + 生成物/登记/升级指南,与在飞 C10(system+cloud)不相交;releases/ 零触碰。

    合并后 ADR-0049 队列推进;A 线接 C17 #4737(studio 区,即刻并飞)。

    Generated by Claude Code

  9. os-zhuang
    closed this as completedin #4764on Aug 3, 2026
  10. akarma-synetal
    added a commit that references this issue on Aug 3, 2026

    feat(spec)!: 退役 RestServerConfig.openApi31 整块 —— declared ≠ enforced,…

    695cfbd
  11. akarma-synetal
    added a commit that references this issue on Oct 7, 2026

    test(spec): the second api/ file group's test titles state each cited…

    dcf3eb4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

pm:queueprotocol:breaking

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions