[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