rest/OCC: postgres 驱动下乐观锁必现假冲突 409 —— normaliseVersionToken 对 Date 做 String() 丢毫秒后与 ISO 字符串严格比较

[baozhoutao]

TL;DR(人话)

在 postgres 生产库上,Console 记录编辑弹窗每次保存都弹「保存冲突/记录已被其他人修改」,PATCH 恒 409 CONCURRENT_UPDATE——哪怕库里这条记录从建出来就没人碰过。sqlite 开发环境完全无感,所以一直没人发现。

版本与环境

• objectos-ee 镜像 4.1.1(内建 runtime 17.2.0,builtAt 2026-08-24),@objectstack/rest / @objectstack/driver-sql 随镜像
• postgres:16-alpine,OS_DATABASE_DRIVER=postgres,TZ=Asia/Shanghai
• 单节点即可复现(与集群/副本数无关,已用 1 副本对照验证)

最小复现(不依赖任何应用包)

任意开 timestamps 的对象,postgres 驱动:

1. GET /api/v1/data/<object>/<id> → 响应里 updated_at: "2026-08-30T10:19:25.947Z"(ISO,带毫秒)
2. PATCH /api/v1/data/<object>/<id>,body 带 expectedVersion: "2026-08-30T10:19:25.947Z"(即第 1 步读到的值,Console 编辑弹窗就是这么发的)
3. → 409,永远:

{
 "error": "Record os_tianshun_ehr_project/kAE91j_gPi7CscPW was modified by another user (current version Sun Aug 30 2026 18:19:25 GMT+0800 (China Standard Time), expected 2026-08-30T10:19:25.947Z)",
 "code": "CONCURRENT_UPDATE",
 "currentVersion": "Sun Aug 30 2026 18:19:25 GMT+0800 (China Standard Time)"
}

注意:报错里的 current 与 expected 是同一瞬间(18:19:25+08:00 == 10:19:25.947Z),却被判为冲突。库里该行 created_at == updated_at == 2026-08-30 18:19:25.947+08,审计日志只有一条 create——不存在并发写。

根因(已读 dist 定位)

packages/rest 的 OCC 门:

• normaliseVersionToken(v) 对版本令牌做 String(v)。postgres 驱动返回的 updated_at 是 JS Date,String(Date) 产出 "Sun Aug 30 2026 18:19:25 GMT+0800 (China Standard Time)" —— 毫秒被丢弃、格式随进程时区漂移;
• assertVersionOf() 拿它与客户端回传的 ISO 字符串做严格字符串比较 currentVersion !== expected → 同一瞬间恒不等 → ConcurrentUpdateError。

sqlite 驱动把 updated_at 以 ISO 字符串存取,两边字符串恰好相同,所以 dev 从不复现——这是个只在 Date 型驱动(至少 postgres)上暴露的驱动相关缺陷。

违反的契约

assertVersionOf 自己的 docblock:"When the caller passes a non-empty expectedVersion token (typically the updated_at value they read), a mismatch throws"——按此契约,客户端原样回传它读到的 updated_at 必须判为匹配。现实现对 Date 型驱动必判不匹配。

建议修法(仅供参考)

两边令牌先尝试 Date.parse,可解析则按时间值(epoch ms)比较,不可解析再退回字符串比较;或 normaliseVersionToken 对 Date 实例统一转 ISO。

我们没有做的事

应用侧没有加任何 workaround(不吞 409、不禁用 OCC)。终端用户目前只能每次在「保存冲突」弹窗点「覆盖保存」强行通过——所有 postgres 生产部署的所有对象编辑都受影响,爆炸半径是整个 Console 编辑链路。

---

Part of steedos-labs/os-project-titanwind-ehr (deploy-ee 集群可行性实测中发现;单节点复现)

[baozhoutao]

Independently re-confirmed on a live multi-node ObjectOS EE deployment (framework 502ff8b5, Postgres 16) during a full platform-checklist run. Two agents reproduced it from their own fixtures: a guarded PATCH /api/v1/data/<obj>/<id> with If-Match set to the read-served updated_at (ISO 2026-08-30T09:49:05.698Z) returns 409 CONCURRENT_UPDATE on an uncontested version, and the only accepted token is the 409 body's currentVersion in Date.toString() form (Sun Aug 30 2026 09:49:05 GMT+0000 (Coordinated Universal Time)); an unguarded PATCH falls through to last-write-wins. Source confirmed at normaliseVersionToken (protocol.ts:9744, String() with no Date→ISO canonicalization) — memory-driver pins keep ISO strings so they stay green, which is why it only surfaces against a real Postgres deployment. Not re-filing; recording the live corroboration here.

QA-source: #13404 · records-forms.concurrent-edit-conflict · clause 0

---

Generated by Claude Code

[claude]

分诊定级 · 首次定级 · bug · p1 · domain:engine · pm:queue

⚠️ 本卡自 07:30 起零标签,静置约 17 小时。本轮全量对账扫出。

p1:postgres 上每一次保存都 409,而 sqlite 无感

Console 记录编辑弹窗恒 409 CONCURRENT_UPDATE,即便该记录从未被人碰过。⇒ 在生产默认驱动上,乐观锁把正常写入全部拒掉。这不是边缘形状,是主路径。

⭐ 卡自己给出了最有说服力的一行证据:报错里的 current 与 expected 是同一瞬间(18:19:25+08:00 == 10:19:25Z)—— 一个冲突检测器把同一个时刻判成了冲突。

而 sqlite 开发环境完全无感,所以它活了下来。⚠️ 这条本身值得记:一个只在生产驱动上出现的缺陷,开发环境的绿色是它的保护色。

域锚定(本轮实测,⛔ 不按卡面包名猜)

卡写 @objectstack/rest / @objectstack/driver-sql。实测:

packages/metadata-protocol/src/protocol.ts:1378 function normaliseVersionToken(v: unknown): string | null
packages/metadata-protocol/src/protocol.ts:9979 const expected = normaliseVersionToken(expectedVersion)
packages/metadata-protocol/src/protocol.ts:9982 const currentVersion = normaliseVersionToken((current as any).updated_at)

⇒ 落点是 packages/metadata-protocol,按车道表归 domain:engine(与 #13216 上 engine 席位给出的落点表同锚)。⛔ 不是 packages/rest。

⛔ 范围与必答

• 修法必须是「比较前归一到同一表示」,⛔ 不是「把 String() 换成 toISOString()」就收工 —— 必答项:normaliseVersionToken 的输入域有哪几种(pg 回 Date、sqlite 回字符串、驱动可能回 number),用枚举回答,并对每一种给出归一后的表示;
• 必做的非空控制:在 postgres 上跑;⛔ sqlite 绿不构成证据 —— 那正是这个缺陷藏了这么久的原因;
• ⚠️ 时区注记:报错串里的 GMT+0800 说明某处走了本地时区格式化。归一必须落在绝对时刻上,⛔ 不得依赖 TZ。

---

Generated by Claude Code

[zhuangjianguo]

Claimed — dispatch R11

• Seat / session: domain:engine lane PM · session_01F3jdziLbAPGeceVNmSox5L
• Branch: claude/issue-13382-occ-version-token-normalisation
• Worktree: ../objectstack-13382-occ-token (per-task, off origin/main = 70fe54891e)
• File surface: packages/metadata-protocol/src/protocol.ts + its test siblings. ⛔ Not packages/rest — see the anchoring note below.
• Clause ② (contract review): FIRES. No packages/spec/src/** path, but this changes when a guarded PATCH is ACCEPTED versus REJECTED with 409 — that is contract accept/reject behaviour, squarely on the content limb. Review at CONTRACT_REVIEW_TIER before the PR is flipped ready. Budget for it.

⚠️ Read the card body on the web, NOT through the API

The issue body comes back truncated through this channel — it cuts off mid-repro at 1. `GET /api/v1/data/. That is the known payload-channel hazard (#13385 · #13373 · #13387). ⛔ Do not treat the truncated text as the whole card. Open the issue page and read the full reproduction before you plan anything.

Cross-seat / anchoring, checked not assumed

Triage re-anchored this by measurement: the landing point is packages/metadata-protocol, not the @objectstack/rest / @objectstack/driver-sql the card's prose names. I confirmed there is no domain:metadata seat among the 13 open pm:seat posts, so no cross-seat declaration is owed on protocol.ts for this claim.

⚠️ The two comments disagree on where the function is — the live-corroboration comment says protocol.ts:9744, triage says the definition is at :1378 with call sites at :9979 / :9982. Both were measured at different times on a moving file. ⛔ Trust neither: locate it yourself on 70fe54891e and say what you found.

---

Dispatch order — three zones

Zone 1 is not re-adjudicable. Zone 2 is a PM assumption you are asked to try to FALSIFY. Zone 3 is discardable.

Zone 1 — RULINGS (the first four are triage's, carried verbatim)

• 修法必须是「比较前归一到同一表示」,⛔ 不是「把 String() 换成 toISOString()」就收工 —— 必答项:normaliseVersionToken 的输入域有哪几种(pg 回 Date、sqlite 回字符串、驱动可能回 number),用枚举回答,并对每一种给出归一后的表示;
• 必做的非空控制:在 postgres 上跑;⛔ sqlite 绿不构成证据 —— 那正是这个缺陷藏了这么久的原因;
• ⚠️ 时区注记:报错串里的 GMT+0800 说明某处走了本地时区格式化。归一必须落在绝对时刻上,⛔ 不得依赖 TZ。

R4. Answer the input-domain question by ENUMERATION, not by listing the cases you happen to think of. Derive the set from what the drivers actually return, and give the normalised representation for each. A fix that handles Date and string but is silent on the third case is not finished.

R5. ⛔ A green sqlite run is not evidence here — it is the camouflage. If this container cannot run a real Postgres, say so plainly and describe what you could and could not measure. ⛔ Do NOT substitute a sqlite pass and call the card verified; an honest "not measured on the driver that matters" is worth more than a false green. (CI runs Temporal Conformance (live PG + MySQL), so a real Postgres exists in CI even if not locally.)

R6. No test may be skipped, disabled, quarantined, allow-listed, deleted or re-baselined. In particular ⛔ do not relax an existing OCC pin to accommodate the new normalisation — if a pin genuinely encodes the old broken comparison, that is a finding to report, not a line to edit.

R7. Worktree-first. ⛔ Never git stash — refs/stash lives in the common .git, shared across every worktree.

Zone 2 — PM MECHANISM ASSUMPTION (measure it; falsification is a good outcome)

The PM's reading is that this is one defect with one root — a comparison between two representations of the same instant — and therefore that normalising both sides at the single normaliseVersionToken seam fixes every caller at once.

Try to falsify it. Specifically: is normaliseVersionToken the only place a version token is compared or emitted? The corroboration comment reports that the 409 body's currentVersion is served in Date.toString() form and that that string is the only token the server will accept — which means the broken representation is not merely compared internally, it is published to clients. If some client or test has already adapted to the broken form, a normalisation fix changes what the wire accepts, and that is a wider blast radius than a one-seam repair. Measure it and report.

Zone 3 — SUGGESTED ROUTE (discard freely)

• ⭐ The card's sharpest evidence is that current and expected in the error are the same instant (18:19:25+08:00 == 10:19:25Z). A regression test that asserts "two spellings of one instant do not conflict" pins the property rather than the spelling, and would survive a future representation change.
• The GMT+0800 in the error suggests a local-time formatter somewhere. Worth checking whether the same formatter feeds anything else user-visible.

STOP conditions

• The blast radius turns out to be wire-visible (clients depending on the Date.toString() token) ⇒ report before changing what the endpoint accepts; that is a compatibility decision, not a bug fix.
• You cannot run Postgres ⇒ report that plainly; ⛔ do not proceed to a sqlite-only verification and present it as done.

---

Generated by Claude Code