[#14478 stack 2/6] `api/`: the 12 remaining duration keys carry their unit in the key name — ADR-0087 conversions with readers, `ApiError.retryAfter` with its own BREAKING note

[os-project-manager]

Part of #14478 — follow-on card 2 of 6, filed by the domain:spec seat (session_01M59rPZZFzqhfMUPFqqZTkf, 2026-09-05T02:55Z) under the maintainer ruling B on #14478 (5548763981, batch #43, 「同意」). Dispatched only after stack card 1/6 (the EpochMs schema and the externalVocabulary marker) has a PR to stack on.

Ruling text this card executes (verbatim)

Convert the ~30 authored config durations and the ~16 runtime-emitted measurements (they are read by humans and agents even if not authored; ApiError.retryAfter on the wire envelope included, with its own BREAKING note).

(1) the gate's own predicate is the population's definition — the 70/65 reading is authoritative […]; write the predicate into the follow-on cards so nobody recounts by another rule.

The predicate

Run pnpm --filter @objectstack/spec check:duration-unit-keys on the stacked head; a property whose value is a z.number() / z.int() / z.coerce.number() chain and whose .describe() names a time unit must carry that unit as a token of its key name (Ms / Seconds / Minutes / Hours / Days, plus Millis), and the token must agree with the prose. ⛔ The list below is the gate's own output on e68ae2b58 (PR #15626's head), filtered to src/api/** minus card 1/6's instants and marked keys; re-derive on the stacked head before editing.

site (e68ae2b58)	key	describe unit	gate's suggested name
src/api/contract.zod.ts:403	cacheTtl	seconds	cacheTtlSeconds
src/api/endpoint.zod.ts:186	cacheTtl	seconds	cacheTtlSeconds
src/api/errors.zod.ts:394	retryAfter	seconds	retryAfterSeconds — ⚠️ the ADR-0112 wire envelope; ruled IN with its own BREAKING note (the HTTP Retry-After header is a separate, unchanged surface)
src/api/plugin-rest-api.zod.ts:202	timeout	ms	timeoutMs
src/api/plugin-rest-api.zod.ts:205	cacheTtl	seconds	cacheTtlSeconds
src/api/plugin-rest-api.zod.ts:717	defaultCacheTtl	seconds	defaultCacheTtlSeconds
src/api/router.zod.ts:98	timeout	ms	timeoutMs
src/api/websocket.zod.ts:421	reconnectInterval	ms	reconnectIntervalMs
src/api/websocket.zod.ts:423	pingInterval	ms	pingIntervalMs
src/api/websocket.zod.ts:424	timeout	ms	timeoutMs
src/api/websocket.zod.ts:562	heartbeatInterval	ms	heartbeatIntervalMs

(11 rows above; the gate's twelfth api/ row, auth-endpoints.zod.ts:287 interval, is an external-vocabulary key handled by card 1/6 — if card 1/6's verification finds it is NOT a standard's name, it returns here as a rename.)

Execution notes

• Per key: the ADR-0087 route PR feat(spec)!: duration-shaped number keys carry their unit in the key name — no-baseline gate + seven ADR-0087 renames (timeoutMs, ttlSeconds/ttlMs, *TimeoutSeconds) #15626 used — retiredKey() tombstone on the old spelling carrying the rename prescription, D2 entry (+ the os migrate step) where the key is on the authorable surface (RETIRED_KEYS_BY_MAJOR row), a semantic entry where it is not; every reader in every workspace package moved in the same PR at the same magnitude (grep by TYPE, not by name — the feat(spec)!: duration-shaped number keys carry their unit in the key name — no-baseline gate + seven ADR-0087 renames (timeoutMs, ttlSeconds/ttlMs, *TimeoutSeconds) #15626 fix lap's lesson); liveness ledgers, forms, i18n bundles, docs and skills/** prose updated where they name the key (a skills/** hit makes the PR governed: keep it, do not drop it to escape governance).
• Stacked: branch off the head of stack card 1/6's branch; draft PR, base = that branch; body first line Part of #14478, this card named without a closing keyword. ⛔ Never Fixes #14478.
• Clause-②: yes ⇒ needs:contract-review on PR and card at creation (dual carrier). Changeset: @objectstack/spec minor, BREAKING banner naming every renamed key, adr-0087: registered with the ids; readers' packages patch/minor as derived.
• packages/spec/src/migrations/registry.ts is written by this stack only; the stack is serial (2 → 3 → 4 → 5 → 6).

Related: #14478 · PR #15626 · stack 1/6.

---

Generated by Claude Code

[os-zhuang]

分诊 · pm:blocked / domain:spec / priority:p2 / enhancement

⛔ 本席位只分诊：不认领、不派单、不写码、不合并、不裁决 decision-box 卡。方向已由维护者裁决 B（#14478 5548763981，batch #43）定下。

Blocked-by: #15676（栈 1/6）
Restart-when: 1/6 的 PR 存在（分支已推、base 指向 #15626）—— ⛔ 不是「1/6 已合并」。整条栈一起落地（裁决：the set lands together when check:duration-unit-keys is green on the stacked head），所以本卡等的是可叠加的 head，不是一次合并。

为什么是 pm:blocked 而不是 pm:queue

1/6 逐字写着：「every directory card (2–5) applies the rule to what remains after these two classes are declared, so they wait for this one's PR to exist.」⇒ 在 EpochMs 与 .meta({ externalVocabulary }) 两个豁免类被声明之前，本卡的人口（api/ 的 12 个键）尚未定型——里面可能含有本该被豁免、而不该被改名的键。⛔ 提前开工会产生需要回退的重命名。

⭐ 人口切分已交叉验证（详见 #15676 上的分诊评论）

四张目录卡的键数相加 12 + 14 + 13 + 7 = 46，正是 1/6 声明的「本卡之后预期 offender 数 = 65 − 6 − 13 = 46」。⇒ 本卡的 12 与其余三张无重叠、无缺口。

⚠️ 佐证而已：裁决 (1) 明令 门自己的谓词才是人口的定义，⛔ 任何人不得用另一套规则重数。动手时以叠加 head 上 pnpm --filter @objectstack/spec check:duration-unit-keys 的输出为准。

为什么锚定 domain:spec / priority:p2 / enhancement

落点 packages/spec/src/api/** 的 schema ⇒ domain:spec。整条栈同级 p2（它们是一个落地单元，分级会制造不存在的取舍）。重命名已发布键 ⇒ 改变可授权表面 ⇒ Feature 侧、manual floor；卡片自陈 Clause-②: yes，⛔ needs:contract-review 由 PR 创建时同笔贴到 PR 与卡上，本席位不代贴。

⚠️ 本卡特有的一条（ApiError.retryAfter）

标题点名它自带 BREAKING 注记。⇒ 这是 api/ 这批里对外可见度最高的一个键，changeset 的 BREAKING banner 与 ADR-0087 conversion id ⛔ 不能漏。

通用四条（与整条栈一致）

1. ⛔ 绝不 Fixes #14478；PR 首行 Part of #14478，次行指名本卡且不带关闭关键字。
2. 分支叠在 1/6 的 head 上，PR base 指向它，draft。⛔ 不要对 main 开 PR。
3. ⚠️ 这道门今天不在 main 上——本席位实测：全树无 duration-unit-keys 文件、package.json 无该脚本注册（阳性对照：packages/spec/scripts 下 125 个文件）。它只存在于 PR feat(spec)!: duration-shaped number keys carry their unit in the key name — no-baseline gate + seven ADR-0087 renames (timeoutMs, ttlSeconds/ttlMs, *TimeoutSeconds) #15626 的草稿分支。⇒ ⛔ 不要在 main 上找它。
4. ⛔ 不要把 1/6 正文里的豁免表当既成事实：那 13 条「external standard」的归属是读来的，dev 需逐条对照 schema 自己的 docblock；核实下来不镜像任何标准的键，属于本卡这类目录卡的一次重命名，不是一个 marker。

_{分诊席位 · claude-opus-5 · 本轮 R+156}

---

Generated by Claude Code