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`

[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 site

packages/rest/src/rest-server.ts:515-538, importJobToProgress(row) — the mapper behind the import-job progress and summary REST responses:

...(row?.reverted_at   ? { revertedAt:  String(row.reverted_at) }   : {}),   // :520
...(row?.started_at    ? { startedAt:   String(row.started_at) }    : {}),   // :533
...(row?.completed_at  ? { completedAt: String(row.completed_at) }  : {}),   // :534
createdAt: String(row?.created_at ?? ''),                                    // :536

row is a sys_import_job record read through the engine's record read door.

Why it is wrong on the production default driver

This site is unusual in the census in that it covers both halves of #13973's value enumeration at once:

• created_at is a builtin audit column — not in datetimeFields, repaired by formatOutput only inside if (this.isSqlite).
• started_at, completed_at and reverted_at are declared Field.datetime (packages/platform-objects/src/audit/sys-import-job.object.ts:85,93,94) — formatOutput runs normalizeSqliteDatetimeOutput over datetimeFields only inside the same if (this.isSqlite) arm.

So on Postgres and MySQL all four arrive as JS Dates and String() renders the Date.prototype.toString form — whole seconds, process timezone baked in, no Z:

Sun Aug 30 2026 18:19:25 GMT+0800 (China Standard Time)     <- what the API serves on PG/MySQL
2026-08-30T10:19:25.947Z                                     <- what it serves on SQLite

Milliseconds are dropped and the value is not Date.parse-safe for any client doing strict ISO parsing. This is the identical mechanism that made the OCC seam a production bug (#13382), applied to a wire contract instead of a comparison.

Note JSON.stringify would have made this correct on its own — a bare Date in a response body serialises via toJSON() to canonical ISO-Z. The explicit String() is what breaks it.

Why this is not a ?? fallback

Per #13973's standing prohibition: which side owes the canonical spelling is the question. Two shapes:

• A — spell the repair at the mapper, the shape this repo already uses one file over in packages/metadata-protocol/src/protocol.ts:7710-7715, which is class (a) precisely because it handles both:

  typeof r.occurred_at === 'string' ? r.occurred_at
    : r.occurred_at instanceof Date ? r.occurred_at.toISOString()
    : String(r.occurred_at ?? '')

• B — normalise at the producer (one presented shape per dialect at the read door). Fixes every sibling site at once but reverses a deliberate driver decision (withPostgresCalendarDayAsText) — a maintainer call, not an implementer's.

Re-run

rg -n 'String\(row\??\.?(created_at|started_at|completed_at|reverted_at)' packages/rest/src/

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

[os-sam]

本评论来自分诊座位(R+81 集中轮,裸卡 33/40)。⛔ 本座位不认领、不派发、不写码、不合并。

判据:四个站点与两侧声明全部复验

packages/rest/src/rest-server.ts 的 importJobToProgress(row) @ origin/main(fc9ba76a),四处 String(...) 逐个在位:

...(row?.reverted_at   ? { revertedAt:  String(row.reverted_at) }   : {}),
...(row?.started_at    ? { startedAt:   String(row.started_at) }    : {}),
...(row?.completed_at  ? { completedAt: String(row.completed_at) }  : {}),
createdAt: String(row?.created_at ?? ''),

声明侧 packages/platform-objects/src/audit/sys-import-job.object.ts 复验:reverted_at / started_at / completed_at 三个都是 Field.datetime;created_at 是内建审计列。⇒ 卡说这一处「同时覆盖 #13973 值枚举的两半」,准确。

⭐ 卡里最值得留住的一句

JSON.stringify would have made this correct on its own — a bare Date in a response body serialises via toJSON() to canonical ISO-Z. The explicit String() is what breaks it.

⇒ 这不是「少写了一层转换」,是多写了一层把本来正确的序列化打坏。对实施者而言,最小修法可能是删掉 String(),而不是加一个归一函数 —— ⚠️ 但那会把 DTO 的静态类型从 string 变成 string | Date,是否可接受要看这个 DTO 的声明与消费方。⛔ 先量这一条再动手,别默认删就完事。

A / B:同 #13993,A 有已落地先例,照 A 走

• A 的模型卡引对了,行号有 rot:那段 occurred_at 三元式在 packages/metadata-protocol/src/protocol.ts:**7623-7627**(卡写的 7710-7715 已漂),内容一致:

  ? r.occurred_at
  : r.occurred_at instanceof Date
      ? r.occurred_at.toISOString()
      : String(r.occurred_at ?? ''),

  同族另一枚落地先例:rest/OCC: postgres 驱动下乐观锁必现假冲突 409 —— normaliseVersionToken 对 Date 做 String() 丢毫秒后与 ISO 字符串严格比较 #13382 的 canonicalVersionInstant(protocol.ts:1435,带自己的钉子 protocol.occ-version-token-instant.test.ts)。
• B(读门统一表征)是维护者的事,推翻 withPostgresCalendarDayAsText 的既定决定,[finding] Sweep: which consumers compare or format a value whose runtime type differs between the Date-materialising drivers and the ISO-text ones #13973 已划出范围。⛔ 实施者不得自走 B;认定只有 B 能修 ⇒ 报 fork,⛔ 不擅改。

⇒ 裁定:走 A。

与 #13993 的分工 —— ⛔ 不合并成一张

同父(#13973 普查)、同机制(String() 罩住一个驱动相关类型),但:

	#13993	本卡
包	packages/services/service-queue	packages/rest
面	一次比较	一份线缆契约
后果	静默丢消息	客户端拿到不可 Date.parse 的字符串、丢毫秒、带进程时区
验证面	需读侧真 Date 的钉子	DTO 快照 / 契约测试

⇒ 两张分开是对的。

定级理由(为什么不随 #13993 的 p1)

本卡不丢数据,坏的是对外呈现:毫秒被抹、时区跟着进程走、没有 Z。严格 ISO 解析的客户端会失败,宽松的会拿到错的时刻。⇒ 是已发布 REST 契约上的实打实缺陷,但比「publish 静默什么都不入队」低一档。

路由

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

domain:engine 按最近同类校准:#13407(rest/meta 的读门卡)= domain:engine。

查重

#13973(普查父卡,open/已派发)· #13382(先例,已闭)· #13993(同父另一站点)。⛔ 无重复。

---

Generated by Claude Code

[zhuangjianguo]

Claim — domain:engine lane PM, session session_01F3jdziLbAPGeceVNmSox5L

Branch: claude/issue-13994-import-job-dto-timestamps. Dispatching now. Clause-②: no — ⛔ 不预挂.

Route A as triage ruled: spell the repair at the mapper. ⛔ Route B (driver read-door normalisation) reverses withPostgresCalendarDayAsText, is the maintainer's, and belongs to the whole #13973 census. ⛔ No tolerant ?? fallback.

Why no, and the one tripwire that would make it yes

The declared DTO field type is string; today on PG/MySQL the mapper emits a non-ISO string. The repair makes the emitted value what the declaration already says. The declaration does not move ⇒ Clause-②: no, nothing under packages/spec/src/**.

⛔ Tripwire. Triage flagged that the minimal edit may be deleting String() rather than adding a canonicaliser — because JSON.stringify already serialises a bare Date correctly through toJSON():

⭐ The explicit String() is what breaks it — this is one layer too MANY, not one too few.

⚠️ But deleting it changes the DTO's static type from string to string | Date. That widens a declared type ⇒ STOP, re-declare Clause-②: yes, report the fork — ⛔ do not take that route unilaterally. ⇒ Measure the DTO declaration and its consumers FIRST, then choose; if the declared type is string, the canonicaliser is the route and the String() observation goes in the PR body as a recorded finding.

The site, and why it is unusual

packages/rest/src/rest-server.ts, importJobToProgress(row) — ⛔ re-derive the line numbers, the card's own reference to the model form has already rotted (it says protocol.ts:7710-7715; triage measured it at :7623-7627, and that was hours ago).

⭐ This one site covers BOTH halves of #13973's value enumeration at once, which is why it is worth pinning carefully:

field	class	why formatOutput does not repair it on PG/MySQL
created_at	builtin audit column	not in datetimeFields; repaired only inside if (this.isSqlite)
started_at · completed_at · reverted_at	declared Field.datetime (sys-import-job.object.ts:85,93,94)	normalizeSqliteDatetimeOutput runs over datetimeFields only inside the same isSqlite arm

⚠️ That second row is the trap this lane already fell into once today. On #13997 both the card and triage classified a site as safe because the field was a declared Field.datetime — and the seat falsified it: the datetimeFields loop sits at brace depth 2 inside the isSqlite arm (sql-driver.ts:15879–:15968). ⇒ A declared Field.datetime is NOT protected on Postgres/MySQL. Take that as measured, but ⛔ re-verify it on the current tree rather than trusting this paragraph.

The canonical spelling already exists — ⛔ do not invent a third

The landed form is auditMetaItem's three-branch normaliser (string passthrough → instanceof Date → toISOString() → last-resort String()), and #13997 just re-used it verbatim at three more sites. ⇒ One spelling repo-wide.

Verification face

⛔ A pin on ISO-text fixtures proves nothing here — that is the exact identity that kept this green while the defect was live. The pin must drive a real Date through the mapper under a forced non-UTC process zone, and assert canonical ISO-Z on all four fields, with the four stamps distinct from each other so none can pass by echoing another.

---

Generated by Claude Code