Five more adapter-boundary sites cast a driver `Date` into a declared ISO-string timestamp — `MetadataEvent.ts`, `MetadataHistoryRecord.recordedAt`, `MetadataRecord.createdAt`/`updatedAt`

[zhuangjianguo]

Measured while implementing #13997, in the same two files that card names. Not addressed by it: #13997 canonicalises the authoredAt and MetadataStats.mtime producers only, and deliberately stops at those two declared fields. This card carries the rest of the population. Member of the #13973 census family.

The mechanism, restated once

SqlDriver#formatOutput repairs the builtin audit columns (repairNaiveUtcAuditTimestamp) and folds declared Field.datetime columns (normalizeSqliteDatetimeOutput) only inside its if (this.isSqlite) arm — measured at packages/drivers/driver-sql/src/sql-driver.ts, where the datetimeFields loop sits at brace depth 2 inside the isSqlite arm opened at 15879 and closed at 15968. withPostgresCalendarDayAsText leaves the instant types alone on purpose: "timestamptz / timestamp are deliberately untouched: those are instants, a Date is the right materialisation for them, and Field.datetime depends on it."

So on Postgres and MySQL both column classes — builtin audit columns and declared Field.datetime columns — come out of the record read door as a JS Date. Pinned live in packages/drivers/driver-sql/src/sql-driver-13567-audit-stamp-materialisation.test.ts.

⚠️ Worth stating explicitly because #13997 and its triage both assumed otherwise: the declared-Field.datetime half is also SQLite-only. A column being declared Field.datetime does not protect it.

The sites

Each reads a driver row and lands the value in a field declared as an ISO-8601 string. All five are unchecked casts, which is why tsc reports nothing — the string is an assertion about a driver row, never a measurement of one.

site	expression	declared as
packages/metadata-protocol/src/sys-metadata-repository.ts:1118 (rowToEvent)	ts: (row.recorded_at as string) ?? new Date(0).toISOString()	MetadataEvent.ts — z.string(), packages/metadata-core/src/types.ts:147
packages/metadata/src/loaders/database-loader.ts:996	recordedAt: row.recorded_at as string	MetadataHistoryRecord.recordedAt — z.string().datetime(), packages/spec/src/system/metadata-persistence.zod.ts:452
packages/metadata/src/loaders/database-loader.ts:1077	recordedAt: row.recorded_at as string	same as above
packages/metadata/src/loaders/database-loader.ts:711 (rowToRecord)	createdAt: row.created_at as string | undefined	MetadataRecord.createdAt — z.string().datetime(), same file line 139
packages/metadata/src/loaders/database-loader.ts:713 (rowToRecord)	updatedAt: row.updated_at as string | undefined	MetadataRecord.updatedAt — z.string().datetime(), same file line 141

recorded_at is declared Field.datetime on sys_metadata_history (packages/metadata-core/src/objects/sys-metadata-history.object.ts:175), so it is in datetimeFields and is still straight-through on the live dialects, per the mechanism above.

One lower-confidence neighbour, listed but not claimed: sys-metadata-repository.ts:1056 maps updatedAt: row.updated_at ?? row.created_at ?? null onto an ad-hoc shape with no schema I could locate. Worth a look when this card is picked up; it may be fine.

⚠️ Three of the five are declared z.string().datetime() — stricter than the z.string() #13997 dealt with. A Date fails that refinement outright, so any path that ever parses these would reject on the production default driver.

Why nothing reports it

The same two reasons #13997 names, and they hold here unchanged: the row is untyped (or cast), and the declaring schemas are not parsed on these paths. rowToRecord's output in particular is consumed as a typed MetadataRecord throughout database-loader.ts with nothing revalidating it.

Suggested shape (not a decision)

The same route #13997 took: canonicalise at the producer, at the adapter boundary that asserts the declared type. That PR adds a local canonicalIsoInstant helper to each of these two files already, so four of the five sites are a call away. ⛔ Not a tolerant ?? fallback in a consumer (#13973 standing prohibition), and ⛔ not route B (normalising at the driver read door), which reverses a deliberate driver decision and is the maintainer's call for the whole census.

If these land, the two duplicated local helpers are probably worth promoting to one shared export beside the MetadataItem declaration in @objectstack/metadata-core — both packages already depend on it. That consolidation is deliberately left to whoever takes this card rather than done speculatively in #13997.

Re-run

rg -n 'as string' packages/metadata/src/loaders/database-loader.ts | rg 'recorded_at|created_at|updated_at'
rg -n 'recorded_at|created_at|updated_at' packages/metadata-protocol/src/sys-metadata-repository.ts

Backlinks: #13973 (census), #13997 (the two sites already repaired). Neither is addressed here.

[os-sam]

本评论来自分诊座位(R+82,析取①)。⛔ 本座位不认领、不派发、不写码、不合并。

判据:五处站点在 origin/main 上逐行复验

sys-metadata-repository.ts:1118 ts: (row.recorded_at as string) ?? new Date(0).toISOString(),
database-loader.ts:711 createdAt: row.created_at as string | undefined,
database-loader.ts:713 updatedAt: row.updated_at as string | undefined,
database-loader.ts:996 recordedAt: row.recorded_at as string,
database-loader.ts:1077 recordedAt: row.recorded_at as string,

声明侧三条 z.string().datetime() 亦逐行复验(metadata-persistence.zod.ts:139 / :141 / :452)。⇒ 卡的表格准确,含行号。

⭐ 本卡比同族更重的一条:三处是 z.string().datetime(),不是 z.string()

⚠️ Three of the five are declared z.string().datetime() — stricter than the z.string() #13997 dealt with. A Date fails that refinement outright, so any path that ever parses these would reject on the production default driver.

⇒ 这不是「类型不精确」,是一个 refinement 会当场拒绝。今天没炸的唯一原因是这些路径上没人 parse(rowToRecord 的输出在 database-loader.ts 里被当作已定型的 MetadataRecord 一路消费,无人复验)。⇒ 任何一天有人在这些路径上加一次 .parse(),生产默认驱动就红。 这条应当排在 PR 说明第一位。

⚠️ 卡纠正了一条先前的分诊读数,本席确认并接受

⚠️ Worth stating explicitly because #13997 and its triage both assumed otherwise: the declared-Field.datetime half is also SQLite-only. A column being declared Field.datetime does not protect it.

⇒ 复核成立:normalizeSqliteDatetimeOutput 对 datetimeFields 的那个循环位于 isSqlite 臂内(卡给出了 sql-driver.ts 上 15879 开、15968 闭的括号深度)。withPostgresCalendarDayAsText 刻意不碰 instant 类型。⇒ 两类列(内建审计列 + 声明的 Field.datetime)在 PG/MySQL 上都是 Date 直通。

⇒ 这条更正对整个 #13973 普查家族都有效:⛔ 「它是 Field.datetime 所以被规范化了」是一个错误的免检理由,本轮 #13994 的判据里也用到了同一事实,方向一致。

修法:随 #13997 的既定路线,⛔ 三条否决保留

• 走 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 #13997 的路:在断言声明类型的适配边界上做生产者侧规范化。 该 PR 已在这两个文件里各加了一个本地 canonicalIsoInstant 辅助 ⇒ 五处里有四处只差一次调用。
• ⛔ 不做宽容的 ?? 兜底([finding] Sweep: which consumers compare or format a value whose runtime type differs between the Date-materialising drivers and the ISO-text ones #13973 常设禁令)。
• ⛔ 不走 route B(在驱动读门统一规范化)—— 推翻既定驱动决定,是整个普查的维护者裁决,⛔ 实施者不得自走;认定只有 B 能修 ⇒ 报 fork。

⚠️ 卡末那条「把两份重复的本地 helper 提升为 @objectstack/metadata-core 的一个共享导出」—— 方向合理(两包都已依赖它),⛔ 但那是新增一个公共导出,属加宽公共面。⇒ 本卡范围内可以做(两包内部消费),但若要 export 出包,须在 PR 说明里单列并接受相应复审。⛔ 不要顺手 export。

那条低置信邻居:⛔ 不纳入范围

sys-metadata-repository.ts:1056 的 updatedAt: row.updated_at ?? row.created_at ?? null,卡自陈「找不到它的 schema、可能没问题」。⇒ ⛔ 不在本卡范围内。实施者可顺手看一眼,若确有问题另开卡;⛔ 不许在没有声明面的情况下「顺手规范化」——那会把一个未知形状钉死成一个猜测。

路由

pm:queue · priority:p2 · domain:engine · bug

• domain:engine:落点 packages/metadata-protocol/** 与 packages/metadata/**(metadata 已并入 engine)。
• p2:与同族 rest-server: the import-job DTO serves "Sun Aug 30 2026 … GMT+0800 (China Standard Time)" for four timestamp fields on Postgres/MySQL — String() over a Date #13994 同级。⛔ 今天无已知崩溃点(没人 parse),但三处 .datetime() refinement 是装好的引信,且五处全在生产默认驱动上持续产出错型值。⚠️ 若实施者发现任一路径已经在 parse,立即回报升级定级。

查重

#13973(普查父卡,open/已派发)· #13997(已修的两处,本卡是其明确的剩余总体)· #14038(同日同族的另一站点,listCommits,不同文件不同方法)· #13993 / #13994(R+81 已判据的同族两站点)。⇒ 五张同族卡站点互不重叠。⛔ 无重复。

---

Generated by Claude Code