ADR-088: A derived alias is kept; a former spelling is rewritten

Context

Adopting sequential codes costs a record the identifier a reader could interpret. The consuming anthology’s pre-migration ids were MLR-2014-Kingma001-0001 — prefix, year, first author, disambiguator — and became SOTA-001.

ADR-040 already had the resolution machinery for a second spelling: a document names its past in formerly:, references written that way resolve, and the fixer upgrades them. But that machinery exists to retire a spelling, and what a readable identifier needs is the opposite.

Decision

A scheme may declare a template rendered from each document’s own frontmatter:

alias = "LIT-{first_author}-{published:.4}-{number}"

Both kinds live in one map and each entry carries its kind, because the fixer’s instruction differs and nothing in the shape of a spelling distinguishes them:

• Formerly — a past spelling. luria link --fix rewrites it to the code.
• Also known as — rendered now. The fixer leaves it written, because canonicalizing it would erase the readable identifier on the first --fix, silently, which is the outcome this exists to prevent.

Three constraints fall out and are enforced:

• The template must start with the scheme’s prefix. Every reference scanner finds a code by its prefix first, so a spelling without one is unreachable however well it resolves. Refused where the config is read.
• Resolution decides what is a reference, never the pattern. An alias tail is loose by necessity, so a widened pattern would match prose; a spelling absent from the map was never a reference. The rule legacy_spellings already states, applied to a case that makes it load-bearing.
• A collision is a violation. One spelling answering for two documents makes every citation through it ambiguous. Including {number} makes that impossible by construction.

Alternatives considered

• Auto-suffix a collision. Rejected: an automatic -002 is order-dependent and would silently renumber when a third document arrives. The template is the fix, and {number} is the version of it that cannot fail.
• Canonicalize aliases in the fixer, like every other spelling. The consistent choice, and it defeats the feature: the readable identifier would survive exactly until someone ran luria link --fix.
• Derive the code itself rather than an alias. Rejected in ADR-087: a value may participate in identity only if it is recomputed, and may only be recomputed if it is not identity.
• A filter vocabulary for the template (slugify, truncate). Deferred, and by measurement rather than taste: str.format’s own spec language already truncates a string, so {published:.4} yields the year and the motivating case needs no filters at all.

Consequences

Resolution moved from an on-demand scan to the cached map. alias_number used to read every document’s frontmatter per lookup, and its docstring gave the sound reason — the path only ran for temporary codes, which are rare. A spelling people choose to cite is not rare, so that assumption expired the moment this landed. The cache is now load-bearing for correctness too, since resolution is what gates the loose pattern.

An alias is recomputed and therefore always true — until someone writes one down. Correcting an author moves the spelling, so a superseded one lands in formerly:, where it keeps resolving forever and the fixer starts rewriting it. luria repair does that hand-off, and it is what makes an alias safe to cite durably rather than only to resolve.

The old spelling comes from git, not from a ledger. The previous frontmatter is already written down — the record’s history is the repository’s — so the repair renders the alias from the last commit and compares. Recording each rendered alias in the document as well would be one copy per revision, which is precisely the hand-kept ledger ADR-040 rejected. Where git cannot answer — a new file, no repository — nothing is retired: absence of history is not a change of spelling, and guessing there would write a formerly: naming a spelling that never existed.

Fired on the real record: 218 literature notes rendered LIT-{first_author}-{published:.4}-{number} with no collisions — LIT-Dao-2022-074 for FlashAttention, which is the pre-migration shape recovered.