docs(adr-0104): step 3 promises an abort the prescribed Postgres USING clause does not perform — measured, it flattens the cell instead

[claude]

What is wrong

ADR-0104's --apply R4 block promises that step 3 moves a media column while

aborting on the first cell that is not a JSON string

and the paragraph immediately below prescribes the realisation:

Postgres retypes the column to a varchar with a USING clause that unquotes the JSON string

Measured on live PostgreSQL 16.13, those two sentences contradict each other. The
USING clause does not abort — it converts. With one un-backfilled inline-object row
present, ALTER TABLE … ALTER COLUMN … TYPE varchar(2048) USING (col #>> '{}') was
ACCEPTED, and the object was flattened to the literal text
{"url":"https://x/y.png"} in a varchar column. #>> '{}' extracts any json type
as text; "unquotes the JSON string" is only what it does when the cell happens to be a
string.

⇒ An implementer who reads the prescribed statement as delivering the stated abort
silently destroys exactly the rows the backfill has not converted — the rows the
reconciliation exists to find.

The ADR's own confidence gap 2 already says the sketch is unrehearsed. This card is not
that gap; it is the result of the rehearsal it asked for, and the result is that one
half of the prescription does not implement the other half.

What was measured, and what was not

• Measured (live PostgreSQL 16.13, first step-3 rehearsal on that dialect): the
  retype above accepts a non-string cell and flattens it. The pre-check that does
  implement the ADR's requirement:
  select count(*) from t where json_typeof(col) IS DISTINCT FROM 'string' — returned
  1 on the same fixture, i.e. it sees the row the DDL did not refuse.
• Measured (SQLite, the same rehearsal): json_extract(col,'$') gated on
  json_valid + json_type = 'text' converts a quoted cell, leaves an already-bare
  cell untouched, and is idempotent on re-run. json_type of an un-backfilled
  inline-object cell is 'object', so that is the correct abort discriminator there.
• ⚠️ NOT measured: MySQL. Its ordering question (gap 2's own "the retype must precede
  the unquote or the two must be one statement") is untouched by this card.
• ⚠️ NOT measured: whether some other Postgres realisation would abort on its own.
  #>> '{}' is the idiom the ADR's words describe, and it does not; whether a different
  USING expression could is an open question, not a finding.

What this card changes

docs/adr/0104-field-runtime-value-shape-contract.md only — the Confidence gaps
section (and, if the author judges it clearer, the sketch paragraph itself), so that the
governed document no longer reads as though the USING clause performs the abort.
The requirement ("aborting on the first cell that is not a JSON string") is correct
and stays exactly as written; it is the statement list under it that was optimistic.

Two things the wording must end up saying, however it is phrased:

1. The abort is a pre-check step 3 runs before any DDL, not a property of the retype.
2. The Postgres rehearsal has now happened and this is what it returned — gap 2 is
   partly closed by a measurement whose result was negative, and gap 1's Postgres half
   moved from "reasoned" to "measured" for this one statement.

Boundaries

• ⛔ docs/adr/** is a governed surface: docs-only PR, draft, human merge. No code
  rides along.
• ⛔ Do not fold this into a code PR. The reason this is a separate card at all is
  that a code PR may not edit docs/adr/**.
• ⛔ Do not re-open the ADR's decision. D1/D3, the window, and the end-state column are
  ruled; this card corrects a statement about how a step is performed, nothing else.
• ⛔ Do not edit content/docs/releases/**.

Provenance

Measured by the #15989 execution round, which deliberately landed no code and stood up
a live PostgreSQL 16.13 to rehearse the sketch. Ruling and the full measurement:
#15989 (comment)

Part-of #15989.

---

Generated by Claude Code

[os-zhuang]

分诊：domain:engine / Bug / priority:p2 / pm:blocking / pm:queue

域 —— 文件面只有 docs/adr/0104-field-runtime-value-shape-contract.md。车道表未列 docs/adr/**（它是治理面）⇒ 按主语归车道：这段文字规定的是 driver 侧一次迁移步骤的 Postgres 实现方式 ⇒ domain:engine，与同一轮的兄弟卡 #16184（driver 检测器）同席。

⚠️ 治理面 ⇒ docs-only 草稿 PR + 人工合并，⛔ 不得有任何代码搭车（卡面已明说，且这正是它单独立卡的原因：一个代码 PR 不得编辑 docs/adr/**）。

类型 Bug，等级 p2 + pm:blocking

Bug 的判据：一份治理文档承诺了一个它自己开出的语句并不执行的动作。

R4 promises … "aborting on the first cell that is not a JSON string"
而紧接着的一段开的方子是：Postgres 用一个 USING 子句把列 retype 成 varchar 并"unquote the JSON string"

⭐ 实测（live PostgreSQL 16.13）：这两句互相矛盾。 USING 子句不中止 —— 它转换。在有一行未回填的 inline-object 行存在时：

ALTER TABLE … ALTER COLUMN … TYPE varchar(2048) USING (col #>> '{}')   → 被【接受】
结果：对象被压平成字面文本 {"url":"https://x/y.png"} 落在 varchar 列里

⇒ #>> '{}' 把任何 json 类型抽成文本；「unquote the JSON string」只是它恰好碰到字符串时的行为。

⇒ 后果：一个把这条方子读成"它实现了那个中止"的实现者，会静默销毁恰恰是回填没能转换的那些行 —— 也就是那次对账存在要找出来的那些行。

pm:blocking 的判据：只要这段文字还这样写着，任何去实现 step 3 的人都会写出那个破坏性语句。⇒ 它挡着 step 3，与 #16184 同为该步骤的前置。

p2 而非 p1：今天还没有人实现 step 3，所以尚无数据被销毁；且这是纯文字修正，落地成本低。⚠️ 若发现已有实现按现文字写成，立即抬到 p1 并回帖。

⭐ 这张卡最该被记住的一点：它是一次结果为负的复演

The ADR's own confidence gap 2 already says the sketch is unrehearsed. This card is not that gap; it is the result of the rehearsal it asked for, and the result is that one half of the prescription does not implement the other half.

⇒ ⭐ 一份治理文档自己声明了一个置信缺口，一轮工作照着去复演，复演证伪了方子，然后把结果写回来。这正是置信缺口机制该有的产出，值得单独记一笔。

测出来的正确判据（两个方言各一个，直接可用）

• Postgres —— 真正实现 ADR 要求的那个预检：

  select count(*) from t where json_typeof(col) IS DISTINCT FROM 'string'

  在同一 fixture 上返回 1，即它看得见那条 DDL 拒绝不了的行。
• SQLite：json_extract(col,'$') 在 json_valid + json_type = 'text' 的门下，转换带引号的单元、对已经是裸值的单元不动、且重跑幂等。未回填的 inline-object 单元其 json_type 是 'object' ⇒ 那才是那里正确的中止判据。

⚠️ 本席未复跑这两次复演；它们由 #15989 那一轮站起一个 live PostgreSQL 16.13 做的。认领时若要引用这两条 SQL，自己再跑一次 —— 它们会成为新文字里的规范语句。

⚠️ 两处明确未测，⛔ 不要在新文字里假装它们已知

• MySQL 完全未测。 gap 2 自己的排序问题（"the retype must precede the unquote or the two must be one statement"）本卡一个字都没碰。
• 是否存在别的 Postgres 写法能自行中止，未测。 #>> '{}' 是 ADR 文字所描述的那个惯用法，而它不中止；别的 USING 表达式能不能中止，是一个开放问题，不是一个发现。

⇒ 新文字必须把这两条继续标为未测，⛔ 不要顺手"补全"。

新文字必须说到的两件事（卡面已规定，本席保留）

1. 中止是 step 3 在任何 DDL 之前跑的一次预检，⛔ 不是 retype 的性质。
2. Postgres 的复演已经发生，结果如上 —— gap 2 被一次结果为负的测量部分关闭，gap 1 的 Postgres 那一半就这一条语句而言从"reasoned"变成"measured"。

⭐ 并且：要求本身（"aborting on the first cell that is not a JSON string"）是正确的，原样保留 —— 乐观的是它下面那份语句清单。⛔ 不要顺手改需求。

⛔ 边界（卡面已划死）

• ⛔ 不得重开 ADR 的决定：D1/D3、窗口、终态列都是已裁定的；本卡只更正一句关于某一步怎么执行的陈述。
• ⛔ 不得编辑 content/docs/releases/**。
• ⛔ 不得折进任何代码 PR。

Part-of #15989。Related：#16184（同一轮，driver 检测器与裁定终态矛盾，同为 pm:blocking）· #16185（同一轮，spec 字段，pm:blocking）—— ⭐ 三张卡都必须在 step 3 落地之前解决。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code

[os-musk]

Claim: session_01ADLdAs2pVcH17h9tZKWMBg — branch claude/issue-16183-adr-0104-step3-abort-precheck

Clause-②: no

Claimed by the domain:engine execution PM seat and dispatched to an os-dev subagent, which inherits this claim. ⛔ The dev posts no second claim and ⛔ never writes the assignee field.

Scope is the card and its triage comment. ⛔ This seat has deliberately not paraphrased either into the order; the card is the authority and the order is only the fence.

⛔⛔ GOVERNED SURFACE — this PR is a TERMINAL DRAFT

docs/adr/** is governed. ⇒ the PR is docs-only, stays a draft, and is merged by a human. ⛔ Never mark it ready for review, ⛔ never enqueue it, ⛔ never enable auto-merge. One governed path decides the whole PR — ⛔ there is no proportional weighing and no "the rest of the diff is harmless". The card says this itself and the seat is restating it because it is the one boundary that cannot be recovered after the fact.

⛔ No code rides along. ⛔ content/docs/releases/** is out of bounds whatever the prose says.

⭐ Context from a sibling round today that the card could not carry — a POINTER, not a paraphrase

Card #16184 (same ADR, driver side) was dispatched this session and its dev ran a live-Postgres measurement. Two of its readings bear directly on the wording you are correcting, and they are on that card at comments 5588522933 and 5588614136 — ⛔ read them there rather than from this summary:

• Step 3 does not exist yet. runFilesToReferencesMigration is backfill → verify → record-flag, with zero hits for unquote / JSON_UNQUOTE / #'>> / json_extract / ALTER COLUMN in it or in migrate/files-to-references.ts.
• ⇒ you are correcting the description of a step nobody has built, which is the cheapest possible moment to correct it — and it means ⛔ there is no implementation to reconcile the prose against, only the ADR's own words and the rehearsal this card reports.

⚠️ That is context, ⛔ not a widening: this card changes one governed document's wording. ⛔ Do not fold in #16184, ⛔ do not fold in #15989.

What the card fixes, and the two things the wording must end up saying

The card is explicit that the requirement — "aborting on the first cell that is not a JSON string" — is correct and stays exactly as written; it is the statement list under it that was optimistic. Its two required outcomes:

1. the abort is a pre-check step 3 runs before any DDL, ⛔ not a property of the retype;
2. the Postgres rehearsal has now happened, gap 2 is partly closed by a measurement whose result was negative, and gap 1's Postgres half moved from "reasoned" to "measured" for that one statement.

⛔ Do not re-open the ADR's decision. D1/D3, the window and the end-state column are ruled; this corrects a statement about how a step is performed, nothing else.

⚠️ Two things the card marks NOT MEASURED — carry them forward as unmeasured, ⛔ do not resolve them by reasoning

• MySQL was not measured, and gap 2's ordering question there ("the retype must precede the unquote or the two must be one statement") is untouched.
• Whether some other Postgres realisation would abort on its own was not measured — #>> '{}' is the idiom the ADR's words describe and it does not abort; anything else is an open question, ⛔ not a finding.

⇒ The corrected text must not accidentally promote either of those to "measured". ⭐ If you re-run the Postgres rehearsal yourself, say which tree and which server version you ran it on.

Collision fences, measured before claiming

Computed from git over all open PR head refs (one-at-a-time fetch; a synthetic non-existent branch requested in the same run was correctly reported MISSING — the denominator is a reading, not an assumption).

• ✅ docs/adr/0104-field-runtime-value-shape-contract.md is claimed by no open PR. ⚠️ docs(adr-0053): amend D-F1 — findWithWindowFunctions is a covered read door #16824 is another governed ADR draft (docs/adr/0053-*) — a different file, but a reminder that governed drafts queue behind a human, so ⛔ do not touch it.
• ⛔ packages/drivers/driver-sql/src/sql-driver.ts (feat(spec,driver-sql,cli): one physical representation for the NUMERIC column family, read by all three producers #16887), packages/metadata-protocol/src/protocol.ts (fix(metadata-protocol): stop persisting derived provenance keys, and restate tenant authorship at hydration for every type #16796, feat(engine)!: findOne, update and delete declare what they answer, and their hook seams are guarded (#16231) #16783), packages/objectql/src/engine.ts (fix(plugin-security)!: evaluate the insert-side RLS check on the row that will be stored, after beforeInsert #16805, feat(engine)!: findOne, update and delete declare what they answer, and their hook seams are guarded (#16231) #16783) — out of bounds, and in any case ⛔ no code belongs in this PR at all.

Dispatch tier: ordinary

Clause-②: no — a governed prose correction adds no exported symbol and no key on any published payload. ⚠️ If your reading contradicts that, report it; ⛔ never restate the carrier yourself.

⚠️ Changeset: measure what this diff publishes before choosing the route. ⛔ Never skip-changeset for a diff that publishes from a released package — and state the measurement rather than assuming a docs path publishes nothing.

⚠️ Anchors: measure every line you cite and name the tree you measured it on. The AGENTS.md changeset-floor sentence sits at :1036 on origin/main, :1029 on a PR branch and :1019 in the shared checkout — one sentence, three numbers.

---

Generated by Claude Code