metadata-protocol: `listCommits` declares `createdAt` as a string but emits the raw driver value, so it hands consumers a `Date` on Postgres/MySQL

[claude]

Found while implementing #13995 (which is not this, and does not close this). Same class as the #13973 driver-materialisation census — class (c), genuinely wrong on one side — but a site the census's seven do not include: #13997 covers MetadataItem.authoredAt in sys-metadata-repository.ts and MetadataStats.mtime in database-loader.ts, and neither is this one.

The site

packages/metadata-protocol/src/protocol.ts, listCommits. Its declared return type says:

    }>): Promise(Array({
        ...
        createdAt?: string;
    }))

(spelled loosely above to keep angle brackets out of this body; the real declaration is the Promise of an Array of that object literal, and the member is verbatim createdAt?: string.)

The mapping assigns the RAW driver value:

const mapped = rows.map((r) => ({
  ...
  ...(r.created_at ? { createdAt: r.created_at } : {}),
}));

Why it is wrong on the production default driver

created_at is a builtin audit column: not in datetimeFields, and SqlDriver#formatOutput repairs it only inside if (this.isSqlite). Pinned in packages/drivers/driver-sql/src/sql-driver-13567-audit-stamp-materialisation.test.ts — the live dialects hand it out of the record read door as a JS Date, SQLite as canonical ISO-Z text.

So on Postgres and MySQL, listCommits hands every in-process consumer a Date in a field the type says is a string, on every call, silently.

Why nothing reports it

• The type system cannot see it. rows is any[], so the assignment is unchecked; every consumer then reads a string that is really a Date, and TypeScript agrees with the declaration rather than with the value.
• The REST door hides it. GET /packages/:id/commits returns through deps.success({ commits }), and JSON.stringify renders a Date as canonical ISO-Z text — so the WIRE shape is accidentally correct and no HTTP-level test can catch this. Only in-process consumers see the Date.
• Every test drives SQLite or memory, where the value really is an ISO string.

That combination is exactly what let #13995 exist: the in-process consumer that read this field and compared it as a string was rollbackToPackageCommit, and the declaration told everyone reading the code that a string was what arrived.

Why this is not repaired inside #13995

#13995's ruled route is "compare instants at the consumer", and it is deliberately minimal: it changes the two COMPARISONS and nothing about what listCommits emits. Repairing this one means choosing what the emitted value should be, and that is a judgement call with a blast radius, not a mechanical edit:

• Canonicalise at the mapping (createdAt becomes the canonical ISO-Z spelling on every dialect). Makes declared = actual and is what the type already promises, but it CHANGES the value every in-process consumer receives on Postgres and MySQL — a behaviour change on a shipped method, and arguably the producer-side normalisation [finding] Sweep: which consumers compare or format a value whose runtime type differs between the Date-materialising drivers and the ISO-text ones #13973 reserves for the maintainer.
• Widen the declared type to admit the Date. Honest about today, but pushes the two-shapes problem onto every consumer — which is the state the OCC seam was in before rest/OCC: postgres 驱动下乐观锁必现假冲突 409 —— normaliseVersionToken 对 Date 做 String() 丢毫秒后与 ISO 字符串严格比较 #13382, and the thing [finding] Sweep: which consumers compare or format a value whose runtime type differs between the Date-materialising drivers and the ISO-text ones #13973 says the contract question exists to avoid.
• Leave it and record the acceptance, per [finding] Sweep: which consumers compare or format a value whose runtime type differs between the Date-materialising drivers and the ISO-text ones #13973 step 5's third disposition.

⛔ Unassigned. Filed for triage to grade and route; it is one of the shapes #13973's option B would delete outright, so it may be worth holding against that ruling.

---

Generated by Claude Code

[os-sam]

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

判据:成立,机制与同族一致

listCommits 声明 createdAt?: string,映射却赋原始驱动值:

...(r.created_at ? { createdAt: r.created_at } : {}),

created_at 是内建审计列,不在 datetimeFields 里,SqlDriver#formatOutput 只在 if (this.isSqlite) 臂内修它。⇒ PG/MySQL 上 listCommits 每次调用都把一个 Date 交到一个类型说是 string 的字段里。

卡对「为什么没人报」的三条分析,本席逐条确认 —— ⭐ 第二条是本卡最有价值的部分

1. 类型系统看不见:rows 是 any[],赋值不受检;下游读到的「string」其实是 Date,而 tsc 站在声明那一边。
2. ⭐ REST 门把它藏住了:GET /packages/:id/commits 经 deps.success({ commits }) 返回,JSON.stringify 把 Date 渲染成规范 ISO-Z ⇒ 线缆形状意外地正确,任何 HTTP 层测试都抓不到。只有进程内消费者看得见 Date。
3. 所有测试跑 SQLite/memory。

⇒ 第 2 条解释了这一族里最反直觉的一点:一个对外正确、对内错误的接口。⇒ 它也解释了 #13995 为什么会存在 —— 那个读该字段并按字符串比较的进程内消费者(rollbackToPackageCommit)被声明骗了。

裁定:走选项 1(在映射处规范化),⛔ 不走 2,⛔ 不走 3

卡把三条摆出来没裁,并担心选项 1「arguably the producer-side normalisation #13973 reserves for the maintainer」。本席认为这条担心放错了地方:

• [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 是在驱动读门统一规范化(一次改掉所有站点、推翻 withPostgresCalendarDayAsText 的既定决定)。
• 在一个方法自己的映射里把值规范成它自己声明的形状,是适配边界上的生产者侧修复,与 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 走的、以及 Five more adapter-boundary sites cast a driver Date into a declared ISO-string timestamp — MetadataEvent.ts, MetadataHistoryRecord.recordedAt, MetadataRecord.createdAt/updatedAt #14037 将走的是同一条路,⛔ 不是 route B。

⇒ 门槛测试也支持:声明说 string,实际给 Date ⇒ 修成 string 是恢复「声明 = 实施」,accept set 不变。⇒ 可派发档。

⚠️ 卡说选项 1「CHANGES the value every in-process consumer receives」—— 措辞需要纠正:那些消费者本来就被声明许诺会收到 string。让他们真的收到 string 不是行为变更,是兑现声明。#13995 那个按字符串比较的消费者正是被现状坑的一方。⛔ PR 说明里不要把这次修复写成「行为变更」,那会招来一次不必要的迁移讨论。

• ⛔ 选项 2(放宽声明类型以容纳 Date):把两形问题推给每一个消费者 —— 那正是 rest/OCC: postgres 驱动下乐观锁必现假冲突 409 —— normaliseVersionToken 对 Date 做 String() 丢毫秒后与 ISO 字符串严格比较 #13382 之前 OCC 缝的状态,也正是 [finding] Sweep: which consumers compare or format a value whose runtime type differs between the Date-materialising drivers and the ISO-text ones #13973 说契约问题存在就是为了避免的事。否决。
• ⛔ 选项 3(接受并记录):今天已有一个被它坑出来的卡(metadata-protocol: the package commit timeline sorts by weekday NAME on Postgres/MySQL — rollbackToPackageCommit therefore plans the wrong set of reverts #13995)。否决。

路由

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

• domain:engine:落点 packages/metadata-protocol/src/protocol.ts。
• 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 同级。⛔ 无数据损坏、⛔ 线缆形状正确;代价是进程内消费者拿到错型值,已实测坑出 metadata-protocol: the package commit timeline sorts by weekday NAME on Postgres/MySQL — rollbackToPackageCommit therefore plans the wrong set of reverts #13995 一次。

与同族的分工(五张,站点互不重叠)

卡	站点
#13993	service-queue 的幂等窗比较(p1,静默丢消息)
#13994	rest-server 的 import-job DTO(线缆契约)
#13997	authoredAt + MetadataStats.mtime(已修)
#14037	另外五处适配边界(含三处 z.string().datetime())
本卡	protocol.ts 的 listCommits

⇒ ⛔ 不合并。但 #14037 与本卡同属 domain:engine、修法同形(适配边界规范化)、且 #13997 已在相邻文件加了 canonicalIsoInstant ⇒ ⭐ 建议成组派发,一并考虑把那个 helper 提升为共享导出(⚠️ 若 export 出包须单列复审,见 #14037 评论)。

查重

同族五张见上,站点互不重叠;#13973 是普查父卡;#13995 是被本缺陷坑出来的下游卡(open,⛔ 不由本卡关闭)。⛔ 无重复。

---

Generated by Claude Code