Three `isoFromValidDate` copies still stand beside the now-total shared canonical-ISO spelling — the collapse their docblocks promise is a decision #14078 did not make

[zhuangjianguo]

Filed from the #14078 implementation seat while executing the maintainer ruling (comment 5504838971, option B). ⛔ Not addressed there, and that card does not close this one.

What #14078 did, and what it left standing

#14078 made the Date arm of the shared canonical-ISO spelling total on all five arms at once: canonicalIsoInstant in sys-metadata-repository.ts and in database-loader.ts, canonicalIsoStamp and formatCsvCell in rest-server.ts, and the occurredAt arm inside auditMetaItem in protocol.ts.

It did not touch a second, near-identical family that three separate cards landed beside those arms:

copy	landed by	call sites
packages/metadata-protocol/src/sys-metadata-repository.ts — isoFromValidDate	#14037	1 (rowToEvent)
packages/metadata/src/loaders/database-loader.ts — isoFromValidDate	#14037	4 (rowToRecord ×2, two history adapters)
packages/metadata-protocol/src/protocol.ts — isoFromValidDate	#14038	1 (listCommits)

Three copies, six call sites. All three docblocks say, verbatim: "When #14078 rules, this helper collapses into the shared spelling."

#14078 ruled, and the collapse did not happen. This card is that unclosed sentence, filed rather than performed, because the collapse is not the mechanical act the docblocks imply.

Why it is not mechanical — measured on origin/main 0ea5f9d9f

The two helpers differ in more than the Invalid-Date shape, and after #14078 that is the ONLY shape on which they now agree:

• canonicalIsoInstant(value: unknown): string | undefined — rewrites the whole domain: nullish becomes undefined, a valid Date becomes ISO text, a string passes through, everything else becomes String(value).
• isoFromValidDate(value: unknown): unknown — rewrites exactly one shape: a valid Date becomes ISO text, and every other input is returned untouched, null, a number and an opaque column included.

So swapping one for the other changes behaviour at six call sites for inputs nobody analysed during the #14078 ruling. Three specifics:

1. MetadataHistoryRecord.recordedAt has no ruled-valid terminal value. It is a REQUIRED z.string().datetime() (packages/spec/src/system/metadata-persistence.zod.ts), fed at database-loader.ts from isoFromValidDate(row.recorded_at) as string in two places. Neither of the ruling's two answers validates there: the visible text "Invalid Date" fails the datetime() refinement, and undefined fails the required field. Today an Invalid Date object reaches it and also fails. That is a real defect, and it needs a third answer (a caller-side default, most likely) that only a decision can supply.
2. protocol.ts's copy carries an explicit contrary contract. Its docblock states that callers of listCommits "are promised the RAW value back untouched when it is not a valid Date — an absent/opaque column must still reach sort's fallback branch and any in-process reader exactly as before". Collapsing it silently reverses that.
3. Three in-repo NEUTRALITY pins assert the un-collapsed behaviour and are written to go red on exactly this swap — sys-metadata-repository-14037-event-ts-canonicalisation.test.ts §C, database-loader-14037-adapter-boundary-iso.test.ts §D, and protocol-14038-list-commits-created-at-iso.test.ts §D. They exist so the swap has to be a deliberate act with its own evidence, which is what this card asks for.

Also worth deciding while the family is open

database-loader.ts rowToRecord assigns isoFromValidDate(row.created_at) as string | undefined into MetadataRecord.createdAt / .updatedAt, both z.string().datetime().optional(). An Invalid Date therefore arrives as a Date object wearing a string | undefined cast — the same class of unchecked assertion #14037 was filed to remove, surviving on the one input shape it deliberately did not decide.

Options

• A — collapse, with a per-call-site terminal value, exactly as The shared canonical-ISO normaliser turns an Invalid Date from a driver into a 500, where String() served text #14078 did for its five arms: follow each of the six sites to its declared schema and its reader, and choose text / undefined / a caller default per site. Rewrites the three neutrality pins as ruled pins. Largest, and the one that actually ends the family.
• B — collapse only where the two are already equivalent, and leave listCommits alone under its stated pass-through contract. Smaller, leaves two spellings in the repo but with a documented reason each.
• C — keep both, permanently, and correct the three docblocks to describe two deliberate helpers rather than one pending merge. Cheapest; the sentence about collapsing is then simply retired.

⛔ No option removes the need to answer point 1 above — recordedAt is a required datetime() field with no valid terminal value today, whichever way the consolidation goes.

Re-check commands

git grep -n "isoFromValidDate" -- packages/metadata-protocol/src packages/metadata/src
git grep -n "recordedAt" -- packages/spec/src/system/metadata-persistence.zod.ts

Backlinks: #14078 (the ruling, and where the docblocks' promise was made), #14037 and #14038 (which landed the three copies). None are addressed here.

[os-zhuang]

分诊：domain:engine / bug / priority:p2 / pm:queue / type Bug

车道：packages/metadata-protocol + packages/metadata —— 车道表 domain:engine 行（packages/metadata*）。

复核（origin/main 5e53d73d）：三份副本在，而你的第 1 点我直接核到了，它是本卡的重心

isoFromValidDate 命中：protocol.ts 3 · sys-metadata-repository.ts 2 · database-loader.ts 5
                      （+ 三份中立性 pin 各自的命中）

packages/spec/src/system/metadata-persistence.zod.ts:452
  recordedAt: z.string().datetime().describe('Timestamp when this version was recorded'),
                                    ↑ ⛔ 没有 .optional()

⇒ recordedAt 是必填的 z.string().datetime()，而 database-loader.ts 两处以 isoFromValidDate(row.recorded_at) as string 喂它。你列的三种终值没有一个能通过：

• 可见文本 "Invalid Date" ⇒ 过不了 datetime() 精化；
• undefined ⇒ 过不了必填；
• 今天的行为（Invalid Date 对象原样返回）⇒ 也过不了。

⭐ 三个候选终值，零个合法。 ⇒ 这不是"合并的时候顺带要想一想"，是一个今天就存在、且无论合并怎么走都必须被回答的缺陷。你把它写成 ⛔「No option removes the need to answer point 1」是对的，我把它抬成本卡的第一工项。

priority:p2

不是 p3：第 1 点是一个已声明契约在一条真实读路径上无法满足的状态 —— 一个必填 datetime() 字段，在 Invalid Date 输入下没有任何合法终值。且第 4 节那半同类：rowToRecord 把 isoFromValidDate(row.created_at) as string | undefined 塞进 MetadataRecord.createdAt / .updatedAt ⇒ 一个 Date 对象穿着 string | undefined 的断言外衣 —— ⭐ 正是 #14037 立卡要清除的那类"未经检查的断言"，在它有意没有裁定的那一个输入形状上活了下来。

不是 p1：⛔ 需要一个 Invalid Date 真的从列里读上来才触发，⛔ 而这条路径的发生率无人测过；也 ⛔ 无数据损坏 —— 坏的是一次读的解析。

⭐ 本卡最值钱的一句，是它拒绝执行那句 docblock

三份 docblock 逐字说："When #14078 rules, this helper collapses into the shared spelling."
而你的判词是：

#14078 ruled, and the collapse did not happen. This card is that unclosed sentence, filed rather than performed, because the collapse is not the mechanical act the docblocks imply.

⭐ 一句写在代码里的"等某某裁决之后就合并"，读起来像一条待办；而它实际上是一个未经检验的假设 —— 假设两个 helper 在那次裁决之后就等价了。 你去核了，它们不等价：

	定义域
canonicalIsoInstant(v): string | undefined	重写整个定义域 —— nullish→undefined，有效 Date→ISO，string 直通，其余一律 String(value)
isoFromValidDate(v): unknown	只重写一个形状 —— 有效 Date→ISO，其余一律原样返回（null、number、不透明列在内）

⇒ 「after #14078 that is the ONLY shape on which they now agree」。一次让两者在某一形状上对齐的裁决，被三份 docblock 读成了"两者已经可以互换"。 ⛔ 承接者不得沿用那句 docblock 的读法。

⭐ 而三份中立性 pin（…14037…test.ts §C、…14037…test.ts §D、…14038…test.ts §D）正是为在这次交换上变红而写的 —— 你指出它们「exist so the swap has to be a deliberate act with its own evidence」。⇒ 这些 pin 不是障碍，它们是本卡要求的那份证据的接收器。 ⛔ 不得为了通过而改写它们，除非改写本身带着逐点的裁定。

⛔ A/B/C 我不裁，但定次序并给一条判据

• 第 1 点先做，⛔ 与 A/B/C 解耦。 它是缺陷，⛔ 不是选项；且你已指出它多半需要第三种答案（调用侧默认值），而那需要一次决定。⇒ 若承接席能给出该默认值的依据（例如"记录时刻取写入时刻"），这一半可以独立落地。
• ⛔ 不建议 C（永久保留两份并改掉那句 docblock）作为唯一动作 —— 它把第 1 点原样留着。⚠️ 但 C 作为A 的补集是合理的：即"合并能合的、剩下的正式声明为两个有意的 helper"，那其实就是 B。
• B 的吸引力在于它有一条现成的、书面的理由：protocol.ts 那份的 docblock 明确承诺 listCommits 的调用方「are promised the RAW value back untouched when it is not a valid Date」。⇒ 那不是疏忽，是一条相反的契约。 合并它会静默反转一条已声明的承诺 ⇒ ⛔ 不得顺手做。
• A 是唯一真正终结这一族的，代价是六个站点逐个跟到它的声明 schema 与读者。

⇒ 承接席自选 A 或 B，⛔ 但必须逐站点给出终值与依据；⚠️ 若选 A 且发现某个站点的终值会改变已发布的读响应形状，回本卡说明，本席按需送箱。

验收口径（承接 PR 请照抄进 ## 验收备注）

1. 第 1 点单独有断言：一个 Invalid Date 的 recorded_at 列 ⇒ MetadataHistoryRecord 必须解析成功（终值由本 PR 选定并写明依据）。⛔ 不得留在"三个候选都不合法"的状态。
2. 第 4 节那半一并处理：createdAt / .updatedAt 上的 as string | undefined 断言必须消失或被证明成立。⛔ 不要只修 recordedAt。
3. 三份中立性 pin 逐条处置：保留（B）或改写为裁定 pin（A），⛔ 每一条都要写明为什么。⛔ 不得删除。
4. listCommits 的直通契约（protocol.ts docblock）⛔ 不得被静默反转 —— 要么保留，要么在 PR 里正面声明反转它并说明理由。
5. 阴性对照必测：一个有效 Date、一个 ISO 字符串、一个 null、一个 number 在六个站点上的输出，改动前后逐个对照 —— ⛔ 只测 Invalid Date 会让"把 isoFromValidDate 换成 canonicalIsoInstant"这种全域重写看起来无害。
6. 三份 docblock 里那句"When The shared canonical-ISO normaliser turns an Invalid Date from a driver into a 500, where String() served text #14078 rules, this helper collapses"必须改掉，无论选哪条路 —— ⛔ 它已经过期，且它正是让这件事看起来机械的原因。

本席权限声明：分诊席只分类/定级/定车道，以及裁定第 1 点与 A/B/C 解耦、以及那条送箱门槛。⛔ 不认领、⛔ 不派发、⛔ 不写代码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code

[claude]

Claim: PM loop round 1
Session: session_01XTBcV7zZHmokdyQgXjbyEU
Branch: claude/issue-16422-iso-from-valid-date-collapse
Domain: domain:engine
Clause-②: yes
Container & model: mode:subagent, model: opus

File surface: the isoFromValidDate definitions and their call sites + tests + .changeset/*.md. ⚠️ Region-level and larger than the card says — see below. Report the final landing set before widening beyond it.

⚠️⚠️ THE CARD'S PREMISE IS INCOMPLETE — re-measured on origin/main fd5cff209 at 2026-09-09T15:21Z.

The card says "three copies, six call sites" in sys-metadata-repository.ts, database-loader.ts and protocol.ts. There are FOUR definitions:

file	signature
packages/metadata-protocol/src/sys-metadata-repository.ts:218	function isoFromValidDate(value: unknown): unknown
packages/metadata/src/loaders/database-loader.ts:169	function isoFromValidDate(value: unknown): unknown
packages/metadata-protocol/src/protocol.ts:1843	function isoFromValidDate(value: unknown): unknown
packages/drivers/driver-sql/src/sql-driver.ts:335	function isoFromValidDate(value: Date): unknown ← ⚠️ not named by the card, and a different parameter type

Control fires: canonicalIsoInstant resolves to its 2 known definitions on the same pathspec.

Two further non-test files reference the name and are unaccounted for in the card: packages/rest/src/rest-server.ts, packages/services/service-storage/src/stranded-orphan-inventory.ts. Classify each before you touch it.

⇒ The card's framing — "the collapse is not the mechanical act the docblocks imply" — is more true than it knew. A fourth copy taking Date rather than unknown is a different contract, and whether it belongs in the collapse is this round's first judgment, not an assumption. ⛔ Do not fold it in silently, and ⛔ do not fold it out silently: state the call either way, with the measurement.

⚠️ packages/drivers/driver-sql/src/sql-driver.ts is a hot file that #16887 changed 195 lines of this round. Re-derive every anchor in it by symbol.

Serial constraints cleared: sys-metadata-repository.ts, loaders/database-loader.ts and protocol.ts are disjoint from #17073's fence, which is packages/metadata*/src/**migrations/** only — verified file-by-file against that PR's 14-file list. sql-driver.ts is free (#16887 landed).

---

Generated by Claude Code