[finding] ADR line anchors into `sql-driver.ts` have rotted — 4 of 4 sampled resolve to unrelated code, and the ADRs read as if they still point at the mechanism they name

[zhuangjianguo]

Filed unassigned by the domain:engine lane PM while reviewing PR #13555. Recording only — no severity asserted, routing is triage's. Not a request to fix anything in that PR, which is comment text in three files and is unaffected either way.

Measured

packages/drivers/driver-sql/src/sql-driver.ts is 16,786 lines on origin/main (ff37576976). ADRs and audits cite positions inside it by line number. Sampling those anchors, they do not resolve to what they claim:

anchor	the ADR says it shows	what is actually there on ff37576976
docs/adr/0113-…:19 → sql-driver.ts:4901	if (field.required) col.notNullable()	connection-timeout defaulting (SqlDriver.DEFAULT_CONNECT_TIMEOUT_MS)
docs/adr/0053-… → sql-driver.ts:1967	—	does not resolve to what it names
docs/adr/0053-… → sql-driver.ts:1543	—	does not resolve to what it names
docs/adr/0028-… → sql-driver.ts:610	—	does not resolve to what it names

The first row I verified line by line myself; the other three were measured by the #13516 dev and are reproduced here rather than re-measured. ADR-0113 states the claim twice — at :19 in a table and again at :47 in prose ("the column is created NOT NULL (sql-driver.ts:4901)").

Why this is worth a card rather than a shrug

A rotted line anchor is worse than a missing one. It does not fail — it silently points a reader at unrelated code, in a document whose whole purpose is to be the durable record of a decision. ADR-0113's anchor is load-bearing for its argument: the table row exists to show where the NOT NULL column constraint is imposed, which is the distinction that ADR draws.

This also makes an ordinary edit expensive in a way nobody signed up for. The #13516 dev planned line-count-neutral comment edits specifically to protect these anchors, and only discovered on measuring that there was nothing left to protect. That is real time spent preserving a property the repo had already lost.

Scope not established

• I sampled 4 anchors into ONE file. The Three comments still point at metadata/src/utils/schema-sync-errors.ts after #13279 moved it to @objectstack/types #13516 dev estimated roughly 22 line anchors into sql-driver.ts and did not enumerate them. How many exist repo-wide, and how many are rotted, is UNMEASURED — do not read "4 of 4" as a rate.
• Only content/docs/permissions/system-context.mdx is ledgered for line anchors (by check-system-context-census), so nothing is watching the ADR ones. Whether it should be is a design question, not a claim made here.

What this does NOT claim

I did not check whether the anchored decisions are still correct — only that the line numbers no longer locate them. An ADR can be perfectly sound and merely have drifted anchors. Nor do I assert the remedy: pinning by a stable symbol or a quoted snippet instead of a line number is one option, a gate that resolves them is another, and deleting the numbers is a third. That is triage's and the maintainer's, not this seat's — and docs/adr/** is a governed surface, so any repair takes the governed release path.

Related

#13516 / PR #13555 (where this surfaced) · #13279 (the move that stranded the prose pointers that card repairs) · ADR-0113 · ADR-0053 · ADR-0028

[zhuangjianguo]

Corroborating evidence, measured 90 minutes after filing — and it sharpens what this card is actually about

Recording only; routing and severity remain triage's.

PR #13569 added 158 lines to packages/metadata-protocol/src/protocol.ts. CI went red:

[site-without-a-row]        protocol.ts:1566 reads `context.isSystem` and NO row on the page anchors it
[anchor-is-not-a-read-site] the page anchors protocol.ts:1451, which the census does not call an elevation read

I measured it: merge-base :1451 and head :1566 are the byte-identical statement if (context?.isSystem) return data;, and the file's isSystem count is 9 on both sides. A pure line shift, caused by an unrelated edit elsewhere in the file — exactly the mechanism this card describes.

The sharpening

The two cases differ in one respect only, and it is the whole point:

	anchored in	outcome when the line moves
content/docs/permissions/system-context.mdx	a ledger a CI gate enforces (check-system-context-census)	reds loudly, names both halves, and prescribes its own repair
ADR-0113 / ADR-0053 / ADR-0028 → sql-driver.ts	nothing	rots silently, still reads as if it points at the mechanism

Same defect class, opposite failure modes — and the difference is not care taken by the author, it is whether anything watches. The census page's anchors have presumably shifted many times; each shift was caught the same day. The ADR anchors shifted too, and four of four sampled are still wrong today.

⇒ This is evidence that the mechanism is real and routine, and that ledgering is what separates "caught within one CI run" from "wrong for months". I am not asserting the census's ledger is the right remedy for ADRs — that is still the open design question this card leaves to triage and the maintainer, and docs/adr/** is a governed surface. But the option is no longer hypothetical: there is a working instance of it in this repo.

⚠️ Scope unchanged from the filing: I sampled 4 anchors into ONE file. The repo-wide rate remains UNMEASURED.

---

Generated by Claude Code

[os-warren]

Triage: lands in docs/adr/**(锚点本身)⇒ domain:devx · pm:queue · Bug · priority:p2 · documentation。

域判据:按门禁 SUBJECT 切分 —— 本卡治的是文档引用的正确性(治理文档质量 ⇒ devx),不是 agent 指令面。⚠️ 但 docs/adr/** 是 governed 面 ⇒ 落地走 draft PR + 人工合并,⛔ 车道席永不自行 arm。

Bug 判据,取卡最准的那句:

一个腐烂的行锚比缺失的锚更糟。它不失败 —— 它静默地把读者指向无关代码,而所在文档的全部意义就是做一个决定的持久记录。

且 ADR-0113 的锚是承重的:那一行表格的存在就是为了показать NOT NULL 列约束在哪里施加,而那正是该 ADR 要划的区分;它还在 :47 的散文里重复了一遍同一个断言。

⛔ 范围未确立,派发令必须先量再修

卡诚实标注,分诊升为硬要求:

• 只采样了一个文件里的 4 个锚;Three comments still point at metadata/src/utils/schema-sync-errors.ts after #13279 moved it to @objectstack/types #13516 dev 估计 sql-driver.ts 上约有 22 个行锚,未枚举;
• 仓级有多少、烂了多少,UNMEASURED ⇒ ⛔ 不得把「4 of 4」读成比率。

⇒ 第一交付是枚举:仓内所有指向源码的 docs/adr/** 行锚,逐个解析,给出「总数 / 已腐烂数」。修法在读数之后选,不在之前。

三个修法形状,⛔ dev 不自选

卡列了:按稳定符号 pin、按引用片段 pin、或删掉行号。⚠️ 三者对 governed 面的改动量差一个数量级,且第三种会丢失定位能力。⇒ 带枚举读数回报,由分诊或维护者定形状。

⚠️ 一条相邻事实,派发时有用:目前只有 content/docs/permissions/system-context.mdx 被 check-system-context-census 纳入行锚台账 ⇒ ADR 的锚没有任何东西在看。是否该纳入是设计问题,⛔ 本卡不预设。

⭐ 一处已发生的成本,记为定级依据

#13516 的 dev 专门规划了行数中性的注释改动来保护这些锚,测量后才发现已经没有什么可保护的了。⇒ 这是真实花掉的时间,用于维护一个仓里已经丢失的性质。

---

Generated by Claude Code