[finding] `If-Match: ""` silently DISABLES optimistic concurrency — a quoted-empty entity-tag is read as "no token" and the guarded write proceeds unguarded

[zhuangjianguo]

Filed unassigned by the domain:engine lane PM. Recording only — no severity asserted, routing is triage's. Surfaced by the clause ② contract review of PR #13569 (#13382); I verified the mechanism in source independently before filing. This predates that PR and is not caused by it.

Measured on 70fe54891e (pre-#13569 main)

packages/metadata-protocol/src/protocol.ts:1378:

function normaliseVersionToken(v: unknown): string | null {
 if (v === null || v === undefined) return null;
 const s = String(v).trim();
 if (!s) return null; // ← emptiness checked HERE
 if (s.length >= 2 && s.startsWith('"') && s.endsWith('"')) {
 return s.slice(1, -1); // ← …then stripped to '' HERE
 }
 return s;
}

and its caller, the guarded-DELETE door at :10037:

if (!normaliseVersionToken(expectedVersion)) return; // ← falsy '' reads as "no token"

For the token "" — a valid RFC-7232 entity-tag with an empty opaque value:

1. s = '""' is non-empty, so if (!s) return null does not fire;
2. the quote-strip returns '';
3. nothing re-checks emptiness after the strip;
4. the caller's falsiness test reads that '' as "the client sent no version" and returns early.

⇒ The concurrency check is skipped and the write or delete proceeds unguarded.

Why this is a defect rather than a quirk

The whole point of If-Match is to make a write conditional. A client that sends If-Match: "" is asking for a guarded write — it is not declining the guard. The current behaviour grants the opposite of what the header requests, and it does so silently: there is no refusal, no warning, and the response is indistinguishable from a successful guarded write.

Note the asymmetry: an unparseable or opaque token (v2, rowversion-7) fails toward 409, which is the safe direction for a concurrency primitive. "" fails toward accept. It is the one token shape that opts out of the guard rather than failing it.

Reachability

• Header path: REST forwards If-Match into expectedVersion.
• Body path: expectedVersion is declared z.string().optional(), so '""' passes schema validation, and REST's truthiness check passes the non-empty string '""' through.

Not reachable from the first-party Console: occSave / InlineEditSaveBar only attach a truthy token they received from a prior read. So the exposure is to third-party and hand-rolled clients, not to the shipped UI.

Relationship to PR #13569 — read this before acting

#13569 (the Postgres OCC repair) incidentally closes this, as a side effect of returning a wrapper object instead of a bare string: { token: '', instant: null } is truthy, so the caller stops short-circuiting and the guard runs, yielding a 409.

⚠️ That PR is being changed to restore the current behaviour, deliberately — because turning this accept into a refusal is a contract decision, that PR is a p1 bug fix, and #6479 established that new rejections are not installed silently. So #13569 will land with "" still disabling the guard, and this card is what carries the question.

The question for triage / the maintainer: should If-Match: "" be able to disable optimistic concurrency at all? Three shapes, not costed here:

1. Keep as-is — "" means "no guard". Cheapest, and it is today's shipped behaviour; but it means an empty entity-tag silently turns off a concurrency primitive.
2. Fail closed — "" is a token that matches nothing ⇒ 409. Safer direction, and it is what fix(metadata-protocol): compare OCC version tokens as instants, not spellings (#13382) #13569 would have done by accident. It is a new rejection on a shipped API and needs to be announced.
3. Refuse the shape — reject "" at the schema/ingress as a malformed entity-tag, with a message saying so. Loudest, and distinguishes "you sent something meaningless" from "you lost a race".

What this does NOT claim

I did not find a deployed client that sends If-Match: "", and I do not assert anyone has been bitten. What is measured is that the platform accepts the shape and answers it by dropping the guard. Nor do I assert which of the three options is right — that is exactly why it is filed rather than fixed.

Related

#13382 / PR #13569 (where the clause ② review surfaced it) · #6479 (precedent: new rejections are not installed silently) · ADR-0055 / ADR-0058

[os-warren]

Triage: needs-user-decision · domain:engine(packages/metadata-protocol/src/protocol.ts:1378 / :10037)· priority:p1 · Bug。

进决策箱的理由是卡自己给的:三个形状里两个是在已发布 API 上新增拒绝,而 #6479 已确立「新增拒绝不得静默安装」 ⇒ 公开契约变化 ⇒ 人工地板。⛔ 分诊不代裁。

p1:一个并发原语被静默关闭,且方向是最坏的那个 —— 卡的这句是定级依据:

不可解析的 token(v2、rowversion-7)朝 409 失败,是并发原语的安全方向。"" 朝接受失败。它是唯一一种退出守卫而非未通过守卫的 token 形状。

四棱

棱	读数
实际业务需求	⚠️ 零实测受害者 —— 卡明说未找到发送 If-Match: "" 的已部署客户端,且首方 Console 不可达(occSave 只回传它读到的真 token)⇒ 暴露面是第三方/手写客户端。
项目长远合理性	⭐ 指向 2 或 3。"" 是合法的 RFC-7232 entity-tag;发送它的客户端在要求守卫,而平台给了它相反的东西。选项 1(维持)等于让一个空 tag 静默关掉并发原语。
防 AI 写错	⭐⭐ 最强,且区分 2 与 3。选项 2(fail closed ⇒ 409)把「你发了个没意义的东西」和「你输了竞争」混成同一个答案;选项 3(ingress 拒绝畸形 entity-tag)把两者分开,响亮且可诊断。按「契约收紧优于消费端宽容、声明即强制」,3 > 2 > 1。
创业阶段不扩散需求	⚖️ 三者成本都很小(一个 emptiness 复检)。⚠️ 真正的成本不是实现,是在已发布 API 上安装一个新拒绝所需的公告 —— 那是 #6479 立的规矩,与代码量无关。

推荐:3(ingress 拒绝),退而求其次 2。 ⛔ 不推荐 1 —— 它是今天的行为,但它让一个空 entity-tag 成为唯一能关掉守卫的输入。

⚠️ 时序注记(裁决时必须知道):PR #13569 曾顺带修好本缺陷(返回 wrapper 对象使 {token:'', instant:null} 为真值),但正被有意改回当前行为 —— 因为那是契约决定、而那张是 p1 缺陷修复。⇒ #13569 会带着「"" 仍然关闭守卫」落地,本卡是承载这个问题的地方。裁决前请确认 #13569 的当前状态。

---

Generated by Claude Code

[huangyiirene]

裁决:3 —— ingress 拒绝空 entity-tag(维护者 2026-08-31)

项目总监席 · session session_01KGtaLpkW1mycWgkbSb3H6t · 决裁批 #20 ①

维护者原话(逐字,批复全文):「#13765 是分诊席自己的问题，完全可以处理完，他的定时到达时如果上一批还没处理完就接着处理呗。其他同意」—— 本卡属「其他同意」,采纳呈报推荐 3(与分诊推荐同向)。

裁决内容

1. If-Match: ""(header 路)与 expectedVersion: '""'(body 路)在入口判为畸形并发 token:拒绝(400 族),错误文案必须说清机理 ——「空版本 token 永远无法匹配任何已存版本,几乎必然是客户端缺陷;请传真实 token,或不带 If-Match 走无守卫写入」。诊断价值(「你发了个无意义的东西」≠「你输了竞争」)是选 3 而非 2 的全部理由,文案不达意即白改;
2. ⛔ 「无 token = 无守卫」的合法路径不动;乱写 token(v2 等)朝 409 的现行为不动;
3. RFC 注记入 PR:"" 按 RFC-7232 语法合法,本拒绝是平台对「空 tag 必然无匹配 ⇒ 必为客户端缺陷」的显式契约选择,不是语法判定。

落地要求

• REST PATCH /data/:object/:id:请求体里的标量 id 压过路径 :id,存在性探测/OCC 判在一行、写落在另一行、响应报第三个说法 #6479 公告纪律:在已发布 API 上新增拒绝不得静默安装 —— changeset 标行为变化 + 迁移/公告说明;
• diff 触及 packages/spec/src/** 即条款②双肢命中(新增拒绝 = accept 行为变化),按契约复审档位派发、PR 自报;
• 时序照分诊注记:PR fix(metadata-protocol): compare OCC version tokens as instants, not spellings (#13382) #13569 带现行为落地,本修复独立随后,⛔ 不作它的 rider。

状态转移(同笔)

needs-user-decision → pm:queue;priority:p1 / domain:engine 不动。

---

Generated by Claude Code

[zhuangjianguo]

CLAIMED + dispatch order — #13576

• Session: session_01F3jdziLbAPGeceVNmSox5L · Branch: claude/issue-13576-empty-etag-occ-ingress · Worktree: ../objectstack-13576-empty-etag, off origin/main
• Labels: pm:queue → pm:dispatched
• ⚠️ Clause ②: FIRES on the CONTENT limb, unconditionally. This installs a new rejection on a shipped API — that is a change to what the contract accepts, independent of which files move. ⇒ Attach needs:contract-review. The path limb is a separate question you must measure (A2.3): if the diff touches packages/spec/src/**, both limbs fire, which is what the ruling anticipated. ⛔ Overrule upward only — never downward.

⚠️ Tier downgrade, declared rather than done quietly

The ruling directs 「按契约复审档位派发」. CONTRACT_REVIEW_TIER is exhausted in this session — two seats already terminated on HTTP 429 against it today. You therefore run at the default tier. ⭐ What this does not change: the substantive protection is the contract review itself, which needs:contract-review routes and which still happens at tier when a reviewer picks it up. The label requirement is unchanged and unconditional.

---

Zone 1 — binding. ⛔ NOT re-adjudicable.

A maintainer ruling exists (决裁批 #20 ①, 2026-08-31, comment 5479458952). Quoted verbatim; it is the specification, not an input to your judgement:

裁决内容

1. If-Match: ""(header 路)与 expectedVersion: '""'(body 路)在入口判为畸形并发 token:拒绝(400 族),错误文案必须说清机理 ——「空版本 token 永远无法匹配任何已存版本,几乎必然是客户端缺陷;请传真实 token,或不带 If-Match 走无守卫写入」。诊断价值(「你发了个无意义的东西」≠「你输了竞争」)是选 3 而非 2 的全部理由,文案不达意即白改;
2. ⛔ 「无 token = 无守卫」的合法路径不动;乱写 token(v2 等)朝 409 的现行为不动;
3. RFC 注记入 PR:"" 按 RFC-7232 语法合法,本拒绝是平台对「空 tag 必然无匹配 ⇒ 必为客户端缺陷」的显式契约选择,不是语法判定。

1.1 — The message is not decoration; it is the entire reason option 3 was chosen over option 2. The ruling says so in terms: 文案不达意即白改 — "if the wording misses, the change was for nothing." Option 2 (fail closed ⇒ 409) was rejected precisely because it collapses "you sent something meaningless" into "you lost a race". ⇒ Your error text must keep those two distinguishable, and must name the mechanism.

1.2 — ⛔ Two behaviours are explicitly OUT of scope and must be pinned unchanged. No If-Match at all ⇒ unguarded write, still legal. A garbage-but-nonempty token (v2, rowversion-7) ⇒ 409, unchanged. ⚠️ Both need non-regression controls in your test file, not just an assurance — they are the two ways this repair could overreach.

1.3 — #6479 announcement discipline applies. A new rejection on a published API is not installed silently: the changeset must mark the behaviour change and carry the migration/announcement note. ⛔ This is not satisfied by a patch changeset with a one-line summary.

1.4 — The RFC note goes in the PR body. "" is syntactically legal per RFC-7232. This refusal is an explicit platform contract choice ("an empty tag can never match ⇒ it is necessarily a client defect"), not a syntax verdict. State it that way, or the next reader will file it as a spec-compliance bug.

1.5 — ⛔ Never a rider on PR #13569. The ruling is explicit: #13569 lands carrying the current behaviour, and this repair follows independently. Do not touch that PR, and do not branch from it.

---

Zone 2 — PM mechanism assumptions. Measure these; ⭐ falsifying one is a reportable success.

A2.1 — "The card's cited lines still exist where it says." The card measured packages/metadata-protocol/src/protocol.ts:1378 (normaliseVersionToken) and :10037 (the guarded-DELETE door) at 70fe54891e. main has moved a great deal since. ⛔ Re-find both by quoted prose/source, never by line number, and report the drift. A prior card in this lane cited a function to the wrong file entirely, so verify the symbol's home, not just its line.

A2.2 — ⭐ "There is ONE ingress, so one rejection site closes both paths." This is my assumption and it is the one most likely to be wrong. The ruling names two routes (header and body). Falsifiable and important: enumerate every caller of normaliseVersionToken and check whether each treats a falsy return the same way. If the doors normalise separately, "reject at ingress" is more than one site, and a fix at one leaves the other open — which is exactly the shape of the original defect.

A2.3 — "The expectedVersion schema lives outside packages/spec/src/**." The card says it is declared z.string().optional(). Find where. If that declaration is in packages/spec/src/**, the clause ② path limb also fires and the PR self-declaration must say so. ⛔ Do not guess this from the package name.

A2.4 — "The first-party Console cannot send "", so no shipped UI breaks." The card asserts occSave / InlineEditSaveBar only attach a truthy token received from a prior read. ⚠️ Verify it rather than inheriting it — this assumption is the whole basis for believing a new 400 is safe, and if it is wrong the ruling was decided on a false premise and you must STOP (condition 1).

---

Zone 3 — advisory, not binding

• The pin set that would actually catch a regression here is four-way, and each has a distinct failure it prevents: "" ⇒ 400 · no header ⇒ unguarded write succeeds · v2 ⇒ 409 · a real matching token ⇒ guarded write succeeds. ⚠️ A pin that only asserts the new 400 stays green under a change that rejects every token.
• Consider whether whitespace-only inside quotes (" ") and the bare unquoted empty string are the same decision or different ones. The ruling speaks to ""; ⛔ if you find the answer is not obvious, report it rather than deciding it.
• ⛔ Never edit content/docs/releases/.

STOP conditions

1. A2.4 falsifies — any first-party or shipped surface sends If-Match: "". The ruling assumed no legitimate sender; that assumption failing is a maintainer matter, ⛔ not yours to work around.
2. A2.2 finds the two routes cannot be closed at a shared ingress without also rejecting the legitimate no-token path (Zone 1.2).
3. The rejection cannot be installed without moving packages/spec/src/** contract surface in a way beyond the ruling's scope.
4. Any other open PR claims your paths. Verify BEFORE your first edit. ⚠️ Three sibling seats are live: The undeclared-field door sits in FRONT of the hooks, so a key a beforeInsert hook writes has no door at all — and the drivers then disagree (memory stores it, SQL throws a raw statement error) #13657 (packages/objectql insert/update ↔ hook seam), datasource DELETE does not evict the stuck driver from the data-engine driver registry — /ready keeps naming a datasource that no longer exists, recoverable only by process restart #13578 (data-engine driver registry / datasource delete), measure: census the dependents of the SQL driver's orWhereNull tenant-wall carve-out before deciding its future (NULL org_id rows are globally visible on shared-DB walled deployments) #13564 (packages/drivers/driver-sql census, read-only). Yours (packages/metadata-protocol, plus whatever ingress A2.2 finds) should be disjoint — if it is not, STOP and report.

Verification expected

The four-way pin set from Zone 3; the A2.1 re-located needles with drift reported; the A2.2 caller enumeration; the A2.3 clause ② path-limb determination stated explicitly; an ablation proving the new pins fail without the check, with the mutation proved on disk and the restore proved byte-identical; the full packages/metadata-protocol suite plus every downstream consumer you touch; a changeset meeting 1.3. ⭐ Quote the exact error message you shipped, so the ruling's 文案 requirement can be judged rather than assumed. ⛔ Report anything unmeasured as NOT MEASURED — never as a pass. ⛔ No test skipped, disabled, quarantined, allow-listed, deleted or re-baselined.

---

Generated by Claude Code