[Decision] the export-job API contract family (`ScheduledExport` / `ScheduleExportRequest` / `ExportJob…`) has zero consumers and, after #16320, an empty `schedule` block — retire the family, keep the contract, or build the scheduler?

[os-bill]

Decision needed

The export-job API contract family in packages/spec/src/api/export.zod.ts (the file's own comment calls it ExportJobApiContracts: ExportJob…, ScheduledExport, ScheduleExportRequest and the request / response bodies of POST /api/v1/data/export/…) declares an API that nothing on the platform serves: rest-server has no /api/v1/data/export route, IExportService (contracts/export-service.ts:15) records "no evidenced provider binding", and no package, example, app or skill outside packages/spec names any of the family's schemas or types.

#16320 (PR #17146) retired the family's two cron positions (ScheduledExport.schedule.cronExpression, ScheduleExportRequest.schedule.cronExpression) under the #15954 ruling. That ruling retires POSITIONS, not defs, so the PR left the blocks — and the tree it leaves makes the family-level question visible:

• ScheduledExport.schedule and ScheduleExportRequest.schedule are now REQUIRED objects whose only key is an optional timezone (defaulting to UTC): a schedule block with no schedule.
• ScheduleState (automation/execution.zod.ts, same ruling, same PR) keeps timezone, status and nextRunAt, which describe a cadence the row no longer declares.

Whether to retire the family is a maintainer decision — ADR-0049 enforce-or-remove applied to a def family rather than a key — and the contract review on #17146 asked for it to be filed as a decision, not decided by a dev seat. Nothing here is decided; the dev-seat reading at the end is non-binding.

Options

option	what it means	cost / risk
A. Retire the family	the export-job contracts (and IExportService / ScheduleExportInput) leave the public surface: RETIRED_DEFS_BY_MAJOR[18] rows, one D3 semantic entry, refusal pins, the api-surface/ and json-schema.manifest/ ratchets move, generated reference pages regenerate	a **BREAKING** minor on @objectstack/spec (launch-window convention); zero measured in-repo consumers (control below), out-of-repo NOT MEASURED; objectui at the pinned .objectui-sha must be grepped before landing (Post-Task Checklist step 4)
B. Keep the contract, declared-but-unserved	no change; the family stays a declared API with no server and the empty schedule blocks stay	the ADR-0049 posture this repo has been retiring elsewhere (declared ≠ enforced); the reference page keeps advertising an export scheduler that does not exist
C. Build the export scheduler	a rest-server route family plus a provider for IExportService, with Job.schedule.expression as the cadence	the largest cost; #15954 rejected "build the schedulers" (its option D) for the cron positions — the family-level question was not put to the maintainer there

Dev-seat reading, non-binding: A is consistent with the rulings that already retired the positions; B is the status quo; C contradicts the #15954 direction unless an export scheduler is wanted on a roadmap.

Evidence (every zero beside a lit control; #17146 branch at 90377d224)

• Family names outside spec: git grep -l -P '\b(ScheduledExport|ScheduleExportRequest|ExportJob|ExportJobApiContracts)(Schema)?\b' -- packages examples apps skills ':!packages/spec/**' → 1 file, and it is two comment lines in the D7 expression-conformance ledger (packages/qa/dogfood/test/expression-conformance.ledger.ts:384-385) recording the spec: retire the seven cron-typed positions nothing reads — export schedules, ScheduleState.cronExpression, DataSyncConfig.schedule, CacheWarmup.schedule, backup/DR schedules — under ADR-0049 (#15954 ruling, option A per family) #16320 retirement. Control: \bConnector(Schema)?\b on the same roots = 43 files.
• Server route: git grep -c 'data/export' -- packages/rest/src → 0 files. Control: api/v1/reports in rest-server.ts lights.
• Provider: contracts/export-service.ts:15 — "IExportService has no evidenced provider binding".

Filed from #16320 (PR #17146) as the boundary flag its contract review asked to become a decision card; not in that card's scope.

---

Generated by Claude Code

[os-bill]

维护者速读

packages/spec 里声明着一整套「导出任务 API」:创建导出、查询导出任务、还有一个定时导出的排程块。文档参考页照着它生成,所以对外看起来这是产品的一项能力。

平台上没有任何东西实现它。 没有这条路由,IExportService 没有任何提供方绑定,仓内除 packages/spec 外没有一个包、示例、应用或 skill 用到它(实测,带对照词)。

而且它现在比以前更糟:#16320 按裁决退掉了那两个 cron 位置之后,schedule 这个必填块里只剩一个可选的 timezone —— 一个装不下排程的排程块。填了 timezone 的人会以为自己排了程。

三条路:A 退役这一族(与已经退掉 cron 位置的裁决同向,但这是已发布包上的破坏性变更,仓外使用者未测);B 维持现状(声明与实现继续不一致,参考页继续宣传一个不存在的导出排程器);C 真的把导出排程器建出来(最贵;#15954 当时否掉过「把 scheduler 建出来」,但族级问题没送到你面前过)。

⚠️ 一句提醒:B 不是「先不动」的零成本选项 —— 上面那个装不下排程的必填块,是三条路里只有 B 会留下的状态。

A / B / C?

---

四棱卡面

① 长远合理性(权重 ≥50%) — ADR-0049「enforce-or-remove」是本仓的既定姿态,而且已经在这一族内部执行过一次:#15954 退掉了它的两个 cron 位置。一个无人实现的 def 族继续留在公开契约上,正是本仓在别处一直在清的形状(ADR-0112 对错误码词表的裁决是同一条推理)。⭐ 更关键的是 #16320 之后的树:必填 schedule 块只剩可选 timezone,这个状态在三个选项下都不是归宿 —— A 移除它,C 填满它,只有 B 把它固化下来。所以本卡的真正问题不是「要不要动」,而是「往哪个方向动」。

② 拉动 — 低,且诚实地低。仓内消费者为零,且这个零是完整枚举加点亮对照测出来的(Connector 对照命中 43 个文件;族名命中 1 个文件,读了,是 D7 台账里记录 #16320 退役的两行注释)。今天没有用户被它挡住。它的代价是慢性的:生成的参考页在替一个不存在的能力做广告。

③ 防 AI 犯错(⭐ 本卡最重的一棱) — 一个 AI 读 packages/spec,看到的是形状完整的导出任务 API:请求体、响应体、排程块一应俱全,于是它会照着写 POST /api/v1/data/export/…。没有服务端。这不是授权时的类型错误,而是运行时的 404 —— 正是本仓归为 (c) 类「AI 写的元数据会被运行时拒收或静默丢弃」的陷阱形状。#16320 之后陷阱更利:排程块看起来仍是放 cadence 的地方,实际已装不下,填 timezone 的作者会以为自己完成了排程。

④ 不扩散 — A 有界但不小:退役套件是十四个面(走 spec-property-retirement skill,⛔ 不要现搭),外加 RETIRED_DEFS_BY_MAJOR[18] 行、一条 D3 语义条目、拒收 pin、api-surface/ 与 json-schema.manifest/ 两道 ratchet 移动、参考页重新生成,以及落地前按 Post-Task Checklist 第 4 步在 pinned .objectui-sha 上 grep objectui。B 今天零成本,但它复利 —— 每多一个版本,退役时要写的迁移说明就多一层历史。C 无界:要发明一条路由族、一个 IExportService 的提供方绑定和一个排程器;#15954 否过它的 option D(「把 scheduler 建出来」),但那次否的是 cron 位置层面,族级从未上呈。

⚠️ 决策输入里唯一的未知,点名说清:仓外消费者 NOT MEASURED。仓内的零是完整且带对照的读数;仓外没有读数,也没有便宜的读法。A 是已发布包上的破坏性变更,所以这个未知不是脚注 —— 它正是 A 不能被当作「免费清理」的理由。⛔ 不要把仓内的零读成整体的零。

---

⚠️ 本卡仍欠一次分诊动作,不是本席位能做的:它至今没有任何标签,因此对每一条车道查询都不可见。它需要 needs-user-decision(决定待做,进维护者收件箱)加一个 domain:* —— ⛔ domain:* 只由分诊席产出,needs-user-decision 的首触定级同属分诊。本条补的是立卡人欠的内容债(四棱块 + 速读),⛔ 不是替分诊定级。

⛔ 本条不含裁决:上面每一棱都是给裁决者的输入,卡内原有的 dev 席读数仍是非约束性的,本席位 ⛔ 不代维护者答产品方向问题。

---

Generated by Claude Code