luria

Fixture codes come from a registered prefix, not from the sequence

3 min read

Graph View

ADR-034: Fixture codes come from a registered prefix, not from the sequence

Status Active · Filed 2026-08-07 · Issue #38

Context

Example codes had been borrowed from the local sequence: ADR-032 was the canonical specimen of “a code that resolves to nothing” in two decision bodies, two test files and a config.py comment, each excused with an unresolved-ok directive. Filing the real thirty-second decision made every specimen resolve at once; five directives went stale together, and one multi-code directive’s stale argument un-excused its neighbours, surfacing a phantom ADR-188 citation (#38).

The stale-annotation check caught all of it — the machinery worked — but the failure was structural: any specimen drawn from the sequence is a collision waiting for the sequence to arrive. The template already avoided this by convention (ADR-777), and a convention that matters gets walked up the ladder to a mechanism (DP-5).

Decision

Register FX as a remote whose every code resolves to the fixture-codes note:

[luria.remotes.FX]
name = "fixtures"
url  = "https://github.com/dmarx/luria/blob/main/docs/directives.md#fixture-codes"

FX-ADR-032 and FX-DP-9 are then first-class references — luria link --fix writes the link, luria lint demands it in prose, the scan resolves it by construction — and no fixture can ever collide with the real sequence, because it is not in it. The template scaffold ships the same entry, so an adopting project starts with the convention mechanized.

The prefix is for references, not for directive arguments. inactive-ok: and unresolved-ok: name local codes by design (ADR-006); the boundary is stated in the directives doc.

History keeps its directives. The bare-code specimens in ADR-014/015/017 quote what was true when written — unprefixed codes were the point of those examples — so they keep their unresolved-ok acknowledgements rather than being rewritten into a claim they never made.

Alternatives considered

  • A dedicated local scheme ([luria.schemes.FX]). A scheme’s codes resolve to documents in a directory; fixture codes must resolve to no document while still being valid references. The remote-with-url shape is the only rung that resolves by construction with nothing on disk.
  • Reserve a number range (“900+ are fixtures”). A convention with no teeth — nothing stops the sequence or a specimen from crossing the line, and nothing links a reserved number to the explanation of why it is one.
  • Keep using unresolved-ok per site. It works until the sequence arrives, then every excuse detonates at once — the incident this decision is the record of.
  • Point FX at a repo-relative path instead of an absolute URL. A remote’s url is absolute by nature; the constant GitHub URL costs a hop for local readers but is the same reference from every project that copies the template, which is the property a fixture prefix is for.

Consequences

  • Fixture codes in tests, docstrings and examples need no annotation at all from now on; the unresolved-ok fixture lists stop growing.
  • luria remotes lists FX alongside SG and LU, and luria remotes --check verifies the note’s URL like any other construction — the convention is now something a build can notice breaking.
  • The anchor lives in docs/directives.md; renaming that heading breaks every fixture link at once, which remotes --check reports (the same fragility every anchor construction carries, ADR-023).

Backlinks