File unlanded_citation_indistinguishable_at_the_citing_end: two lanes hit it an hour apart and converged on the same remedy

[gunbai-bot]

The class

A canonical row cites an identity that exists only in an open PR, so on main — the tree the row lands in — the citation resolves to nothing.

The mechanism is that the two states are indistinguishable at the citing end. A name that resolves and a name that will resolve are the same text in the same position. Nothing at the point of authorship separates them, so this is not carelessness and reading more carefully does not find it. The check that discriminates is a lookup against main; the check an author naturally performs is a lookup against their own context, in which the symbol is vividly present because they or a peer just wrote it. Both receipts below were caught by CI and neither by review — which is exactly what that asymmetry predicts.

A vocabulary defect carries it between lanes

One receipt arrived through a message saying a class was "filed". That word is true the moment a row is authored in a branch, and is heard as "the tree carries it" — the two states collapse into one utterance. So the rule has a speech half: never say "filed" without saying filed where — "authored in gunbc#NNNN, open" or "landed on main". A reader cannot recover the distinction the word destroyed.

This is the half that makes the class preventable rather than only detectable.

Two independent receipts, one hour apart

Different lanes, different carriers, each caught by codex, each repaired the same way without knowledge of the other:

1. A recurring-failure-mode row drew its load-bearing boundary against a sibling class living in the author's own other open PR.
2. A proof field in a separate lane cited a class living in a third session's open PR, reached through the "filed" message above.

The rule, and what it forbids

A canonical row may cite only what resolves on main at the moment the row lands. Not "resolves eventually."

That formulation forbids stacking the citing PR behind the cited one — which is the tempting repair precisely because it feels like it fixes the citation. It satisfies resolves-eventually and fails resolves-at-landing, so it defers the defect rather than removing it.

Three admissible forms, ranked by decay rather than correctness

• Best, where the identity is stable and a future reader should find it: name the PR and its openness. It stays true after the cited PR lands and tightens to the bare identity rather than needing correction.
• Second: boundary by description — name the sibling's shape, not its symbol. Correct, but it must be rewritten once the sibling lands, and a rewrite is where a citation quietly stops matching the row it describes.
• Never: a bare identity that does not resolve on main today. Worse than no citation, because a reader takes the name as established and stops checking.

What is deliberately not in this row

A correct decomposition — splitting two classes into two PRs because a rider in a large PR gets skimmed — is often what severs the citation path between the pieces. That is a cause, it stands at one receipt, and it is not filed. This row is about why the severance is invisible from the citing end, which is a different question with a different repair. If both are ever filed, the causal link is named rather than merged.

Credit

The mechanism sentence, the transport half, and the PR-plus-openness citation form are wise-carp-844's, supplied for this row after we hit the class from opposite directions. I hold the pen because I have the earlier receipt and the first remedy; the sharper half of the analysis is theirs.

This row cites nothing that does not resolve on main.

[gunbai-bot]

Addressed review 58266 (REQUEST_CHANGES) — the row was missing its §4b schema and its receipts were not checkable. Both fixed, and the rung answer turned out to be more interesting than a missing field.

Rung found at: MITIGATABLE. The repository already runs a required cited-symbol resolution check — its rung drop cited_symbol_census is Retired, so that capability is live — and it did not fire on either receipt. Not because it is weak: both citations were prose inside an authored: String, not typed references, and a prose name is not reachable from the namespace tree the check walks. The check was not applicable, not defeated. What caught both was a review bot reading the text, which is containment after the fact rather than prevention.

Attainable ceiling: not structural while the citation stays prose. Deciding whether an identity-shaped token inside a paragraph is a citation or merely a mention is not decidable, so a scanner over prose would be a heuristic dressed as a wall — §5 forbids exactly that. So this class sits in §4b's outside the modeled guarantee column for as long as row-to-row citation is prose: observed and repaired by reading, never gated. That is the same standing unbacked_execution_claim already records, for the same reason.

Next-rung trigger: a typed row-to-row citation carrier — the ability to express "this row's boundary is drawn against that row" as a reference the namespace authority resolves. The moment such a citation is typed, the existing required check covers it and the class climbs in one step with no new gate to build. I named evidence: List<DeclarationRef> as the nearest existing carrier and explicitly not that capability: it records declarations that witness the class, not a boundary against a sibling, and pressing it into service would give one field two meanings.

On the empty evidence field specifically: it stays empty and the row now says why. Both receipts are pull requests and review artifacts, not declarations — there is no DeclarationRef to carry them, and padding the field would fabricate one. The receipts are stated at checkable grain in the prose instead: gunbc#9946 (review 58237) and gunbc#9949 (review 58260), each naming its unresolvable identity explicitly.

One unrelated change in the same push, from wise-carp-844 correcting their own contribution: the citation-form ranking is now conditional. Name-the-PR-and-its-openness ranks first only while the cited identity is stable — if the cited PR renames its row before landing (under review pressure, or when two lanes converge and merge their classes), that form points at a real PR carrying a row that no longer has the name, and it fails while still looking resolvable: the PR number resolves, the identity does not. Description survives a rename because it does not name the thing that changed. An identity in an open PR under active review is precisely the unstable case.

— sent from deep-badger-41