[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

[os-litant]

Triage: the card is correctly self-titled [Decision] and is routed as one. domain:spec, needs-user-decision, priority:p3.

The export-job API contract family in packages/spec/src/api/export.zod.ts (ExportJob…, ScheduledExport, ScheduleExportRequest, and the request/response bodies of POST /api/v1/data/export/…) declares an API nothing serves: rest-server has no /api/v1/data/export route, IExportService records "no evidenced provider binding", and no package, example, app or skill outside packages/spec consumes it. After #16320 its schedule block is empty.

---

维护者速读

改了什么 — 什么都还没改。这是问「一套没有任何人实现、也没有任何人调用的对外 API 声明,留还是删」。

为什么改 — 我们的契约里声明了一整套「导出任务」API(创建导出、定时导出等)。实测:服务端没有这个路由,没有任何实现绑定,仓内外没有任何消费者。也就是说,如果有人照着我们的契约去调它,会得到 404。而上一次改动之后,它的「定时」那一块连内容都空了。

风险与代价(含回滚) — A(退休整族):契约变小、少一份永久义务;代价是若真有外部用户按它写过代码会被打断(⚠️ 目前查不到这样的用户)。B(保留声明):零动作,但我们继续对外承诺一个不存在的能力 —— 任何 AI 读到它都会当成可用。C(补实现):把它做出来,代价是一整套导出调度服务的长期维护,而目前没有任何人在要。

席位意见 — 荐 A(退休)。理由:零消费者、零实现、零拉动,三样都实测了。创业阶段对「已声明但无人消费」的能力默认删而不是留 —— 而且留着的具体伤害是明确的:它会骗到 AI,让它照着写出必然 404 的代码。⛔ 我不主张 C 是错的,只主张今天没有任何证据支持它。

你要做的(一个动作) — 选一个字母:A(退休整族)/ B(保留)/ C(补实现)。

---

os-decision-facets

• ① 项目长远合理性:A 收窄契约、消除一族永久义务;C 反向扩张且需要一整个调度子系统;B 让「声明 ≠ 实现」的缺口长期挂着,是三者中长远最差。
• ② 实际业务拉动:⭐ 零,且是实测的零 —— 无路由、无 provider binding、packages/spec 之外无任何消费者。⛔ 不是「没查到」,是查过了。按创业阶段原则,零拉动默认 defer 或 remove。
• ③ 防 AI 犯错:⭐ 强烈指向 A。一套完整、结构良好、却无人实现的 API 声明,是 AI 最容易上当的形状 —— 它读起来完全可用,照着写出来的代码必然 404,而没有任何门会拦住。声明即强制:兑现不了就不要声明。
• ④ 创业阶段不扩散:A。remove 优于 declare-and-maintain,且已发布零消费的能力不因沉没成本获得豁免。

推荐:A(退休整族)。回退项:B,仅当你知道某个本席看不到的外部消费者。⛔ 不荐 C —— 零拉动下补实现是最贵的那条路。

⚠️ 置信缺口 —— 本分析看不见什么:仓外是否有人按这套契约写过代码。本席的枚举覆盖本平台的包、示例、app 与 skills,⛔ 覆盖不到任何外部使用者或未公开的下游。若你知道有,A 就需要配一条废弃通告而不是直接删。

_{分诊席位 · session_017VGfRocA8VjczSe84fgjY3 · R+166 · 2026-09-10T14:26Z · 本评论来自分诊座位}

---

Generated by Claude Code