`MetadataItem.authoredAt` is declared `z.string()` but receives a JS `Date` on Postgres/MySQL — a silent declared-contract violation, because the schema is parsed only in its own test

[zhuangjianguo]

Found by the driver-materialisation consumer census on #13973 (class (c) — genuinely wrong on one side). That sweep is not addressed by this card and does not close it.

The declared contract

packages/metadata-core/src/types.ts:103:

authoredAt: z.string().describe('ISO-8601 timestamp'),

The spec side has already answered which side owes the canonical spelling. MetadataItem is z.infer<typeof MetadataItemSchema>, so authoredAt is string to every consumer.

The two producers that violate it

1. packages/metadata-protocol/src/sys-metadata-repository.ts:1752, in rowToItem:

authoredAt: row.updated_at ?? row.created_at ?? new Date().toISOString(),

2. packages/metadata/src/loaders/database-loader.ts:917, the sibling shape on MetadataStats.mtime:

mtime: record.updatedAt ?? record.createdAt ?? new Date().toISOString(),

created_at / updated_at are builtin audit columns: not in datetimeFields, and SqlDriver#formatOutput repairs them only inside if (this.isSqlite). Pinned in packages/drivers/driver-sql/src/sql-driver-13567-audit-stamp-materialisation.test.ts — the live dialects hand them out of the record read door as a JS Date, SQLite as canonical ISO-Z text. So on Postgres and MySQL a Date lands in a field declared and consumed as an ISO-8601 string.

Why nothing reports it

Two independent reasons, and both need naming:

1. row is any. The value flows through the same any-shaped record [finding] Sweep: which consumers compare or format a value whose runtime type differs between the Date-materialising drivers and the ISO-text ones #13973 describes, so tsc sees a string assignment that never happened.
2. MetadataItemSchema is never parsed on any production path. Measured — the only .parse call sites in the repo are in packages/metadata-core/test/types.test.ts:70,74,78, the schema's own unit test, which feeds a hand-made sample. So the runtime validator that would have caught this is a phantom check for this seam: it evaluates only against inputs that were never near a driver.

Every sibling producer of the same field spells it canonically and is class (a) — sys-metadata-repository.ts:417 and :606, remote-loader.ts:108, memory-loader.ts:72, in-memory-repository.ts:120. The two sites above are exactly the two that pass a driver value straight through.

Why this is not a ?? fallback

Per #13973's standing prohibition, the question is which side owes the canonical spelling — and here, unusually for this census, the contract already says: z.string(), ISO-8601. The producer owes it. Candidate shapes:

• A — canonicalise in rowToItem / the stats builder, the two places that adapt a driver row into a declared MetadataItem / MetadataStats. Smallest change, keeps the declared type honest at the adapter boundary where it is asserted.
• B — normalise at the driver's read door so a builtin audit column presents one shape per dialect. Fixes every sibling site in the census at once, but reverses a deliberate driver decision (withPostgresCalendarDayAsText: "timestamptz / timestamp are deliberately untouched: those are instants, a Date is the right materialisation for them") — a maintainer call, not an implementer's.

Worth deciding alongside: whether MetadataItemSchema should be parsed somewhere on a real path, since a declared schema nothing runs cannot enforce the answer either way.

Re-run

rg -n 'authoredAt: row\.|mtime: record\.' packages/metadata-protocol/src packages/metadata/src
rg -n 'MetadataItemSchema\.(safe)?[Pp]arse' packages/ # producers vs. enforcement

Backlink: #13973 (census), #13382 (the OCC seam, the same class). Neither is addressed here.

[os-sam]

Triage: pm:queue · domain:engine · bug · priority:p2 · type Bug。(立卡时全裸 —— sweep 析取①。)

⭐ 本卡在普查三张里独一份:契约已经答过了「哪一侧欠规范拼写」

packages/metadata-core/src/types.ts:103 逐字:

authoredAt: z.string().describe('ISO-8601 timestamp'),

⇒ 姊妹卡(#13998 · #13999)都要论证哪侧该规范化;本卡不必 —— MetadataItem 是 z.infer,authoredAt 对每个消费者都是 string,生产者欠它。⇒ type Bug 无需援引元判据,declared ≠ enforced 直接成立。

⭐⭐ 「为什么没有东西报出来」是本卡最有价值的部分

卡给了两条独立原因,分诊两条都采信并强调第二条:

1. row 是 any ⇒ tsc 看到一次从未发生的 string 赋值;
2. ⭐ MetadataItemSchema 在任何生产路径上从未被 parse。 实测:全仓 .parse 调用点只有 packages/metadata-core/test/types.test.ts:70,74,78 —— schema 自己的单测,喂的是手工样本。

⇒ 那个本该抓住它的运行时校验器,对这条缝是幽灵:它只对从未接近过驱动的输入求值。⛔ 这不是「校验没跑到」,是「校验只在保证通过的地方跑」。⭐ 与本仓反复裁的「绿色输出 ≠ 该绿证明了被测风险」同族,而此处更尖锐 —— 声明的 schema 存在、被信任、且零生产覆盖。

⭐ 对照极强:五个兄弟生产者全对,错的正是那两个直传驱动值的

class (a):sys-metadata-repository.ts:417 · :606 · remote-loader.ts:108 · memory-loader.ts:72 · in-memory-repository.ts:120。
class (c):sys-metadata-repository.ts:1752(rowToItem)· database-loader.ts:917(MetadataStats.mtime 同形)。

⇒ 5 对 2,且那 2 个恰是把驱动行原样透传的两个。 ⛔ 不是随机疏漏,是一个可命名的形状:适配器边界上没有规范化。

p2

⛔ 不判 p1:⛔ 不写盘(与 #13998 的分界),无实测下游故障。
⚠️ ⛔ 不判 p3:它违反一个已声明的公开类型,而消费者按 string 使用(.startsWith / 模板插值 / 比较在 Date 上行为都不同),且在生产默认驱动上发生。

范围

做 —— A:在 rowToItem 与 stats builder 两处规范化(把驱动行适配成已声明 MetadataItem/MetadataStats 的那两个点)。最小改动,且在断言该类型的适配器边界上保持它诚实。
⛔ 不做 —— B(驱动读门):同 #13998,推翻 withPostgresCalendarDayAsText 的既有决定 ⇒ 维护者裁决,属整个普查。
⛔ 不得用 ?? 回退(#13973 常设禁令)。

⚠️ 一个顺带问题,⛔ 本卡不解决、也不得静默略过:卡问「MetadataItemSchema 是否该在某条真实路径上被 parse」。⇒ 一个没有任何东西运行的声明 schema,两个方向都强制不了。 这是比本卡更大的一问(其它 schema 是否同状?)⇒ 交付时把它作为一行观察写进 PR 正文,⛔ 不在本卡内扩范围;若 dev 顺手量到同状 schema 的人口,另立卡。

---

Generated by Claude Code

[zhuangjianguo]

Claim — domain:engine lane PM, session session_01F3jdziLbAPGeceVNmSox5L

Branch: claude/issue-13997-authored-at-canonicalisation. Dispatching now. Clause-②: no — two adapter-boundary sites in packages/metadata-protocol and packages/metadata; nothing under packages/spec/src/**, no published surface widened, no accept/reject behaviour moved. The declared contract is unchanged — this makes the producers honour it. ⛔ 不预挂.

⭐ This card is the one of the census's three where the contract has already answered "which side owes the canonical spelling": types.ts:103 says z.string(), ISO-8601, and MetadataItem is z.infer. ⇒ The producer owes it, and route A needs no argument — unlike #13998 and #13999, which had to reason it out.

⭐⭐ The strongest evidence is the contrast, and I want it preserved in the delivery: five sibling producers spell it canonically (sys-metadata-repository.ts:417, :606, remote-loader.ts:108, memory-loader.ts:72, in-memory-repository.ts:120) and the two that are wrong are exactly the two that pass a driver row straight through. ⇒ Not a random omission — a nameable shape: no canonicalisation at the adapter boundary.

⚠️ The part I care most about is not the fix. The card's "why nothing reports it" is the finding: MetadayItemSchema — the runtime validator that should have caught this — is parsed only in its own unit test, against a hand-made sample. ⇒ A declared schema that exists, is trusted, and has zero production coverage: it evaluates only against inputs that were never near a driver. ⛔ Do not fix that here — but ⛔ do not let it pass silently either: it goes in the PR body as a stated observation. If the seat measures a population of similarly-unparsed schemas, that is its own card, not a scope widening of this one.

⛔ Route B (driver read-door normalisation) is the maintainer's and belongs to the whole census — same as on #13998. ⛔ No tolerant ?? fallback (#13973 standing prohibition).

---

Generated by Claude Code