Repository navigation
RestServerConfig.openApi31(OpenApi31Extensions / Callback / OpenApiWebhookEvent)declared ≠ enforced:没有任何运行时读取它 —— ADR-0049 enforce-or-remove 候选 #4579
Description
Activity
裁决(维护者 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
🔒 认领(实施 A 线;#3207 已收口于 PR #4734,#3715 核实为已实现并关单)
- 会话:
session_0176qgxgCXTJCUv4YFLtusP9 - 分支:
claude/issue-4579-retire-openapi31-block - 方向:remove(2026-08-02 委托裁决)——
openApi31键 +OpenApi31ExtensionsSchema+CallbackSchema+OpenApiWebhookEventSchema整块删除;非 strict schema 补墓碑位防静默剥离;major,v17 窗口(pre.json 实测仍mode: pre)。 - 现势快查已做:三 schema 仍在 main(不是 ADR-0089 D3a: flip
.strict()on view/page schemas so mis-layered visibility keys are loud errors #2902/Remove dead objectenable.trash/enable.mrucapability flags (ADR-0049 enforce-or-remove) #3207/[P2] Execute ADR-0033's deletion of the unenforcedtool.requiresConfirmation(safety-shaped, gated by nothing) #3715 那型陈旧单)。 - 并行:与在飞的 spec 双源清账 C6:EventSchema(./automation ≠ ./kernel)—— 1 条 #4658(automation/kernel 区)文件互斥;入队按 ✅ spec 双源清账主单:基线 52 → 0(2026-08-03 收官)—— #4446 gate 落地后的偿还 worklist #4535 新协议 rebase + 重生成串行。
Generated by Claude Code
- 会话:
- added a commit that references this issue
on Aug 3, 2026 🔁 入队协议 rebase 记录(PR #4764,
session_0176qgxgCXTJCUv4YFLtusP9)- 分支已 rebase:merge-base
56470061d→832047c57(含 C13+C15 PR feat(spec)!: 双源清账 C13+C15 —— 退役 L1「Simple Sync」整层,integration 冲突枚举改名ConnectorConflictResolution,ui 侧保名 (#4738) #4760);head77cd00ee8,--force-with-lease已推。 - 生成物按 ✅ spec 双源清账主单:基线 52 → 0(2026-08-03 收官)—— #4446 gate 落地后的偿还 worklist #4535 §7 全部从合并树重新生成(merge driver 拒绝 text-merge 的三份:
json-schema.manifest.json/authorable-surface.json/api-surface.json;rm -rf dist全量重建防孤儿 dts chunk)。三 def 的 gen:schema silently drops PageTabsProps since #2967 — references regen would delete real docs #2978 蓄意删行按门禁提示在同 commit 重做,authorable-surface 的 tombstone 门禁可被手编基线绕过 —— 删掉基线行就删掉了证据(#4638 / #4643 已两次这样过绿) #4650 门禁输出:3 baseline deletion(s) since 832047c57039 carry their own proof — def no longer emitted。 - 复验(flock 前台实跑):
check:generated8/8 全绿;check:dual-source-exportsPASS,基线保持 6 行不动;spec test 292 files / 7348 tests passed;spectypecheckexit=0;api-surface delta vs origin/main 恰为本单六行删除。 - draft 状态未动(归 PM);
releases/未触碰。
{"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
- 分支已 rebase:merge-base
✅ 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
- 内容(rebase 前已全查):
- added a commit that references this issue
on Aug 3, 2026 - added a commit that references this issue
on Oct 7, 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)
/openapi.json的 enrich 阶段把openApi31.webhooks/callbacks合入输出文档(OpenAPI 3.1 顶层webhooks是标准能力);或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。