The record

Generated by luria index from this project’s luria.yaml — built, not edited. A table configured is a row here whether or not anyone remembered to describe it.

This is the shape this project gave the record machinery: the document families it named, where entries are filed, where views are rendered, and what to type to add one. It is a description of luria.yaml as configured, not of what luria.yaml can hold — for the key-by-key schema, with defaults and meanings, see Luria’s configuration reference.

Referable documents

A code — ADR-012 — resolves to a document, and every reference to it in this repository is checked. luria lint fails on a bare code that was never linked; luria link --fix writes the link so nobody has to know where the document renders.

a code looks like	filed in	rendered to	in force when status is
`SOTA-001`	`record/practices.d/`	`docs/practices/README.md` + tag pages	`Active`
`THEORY-001`	`record/theory.d/`	`docs/theory/README.md` + tag pages	`Active`
`LIT-001`	`record/literature.d/`	`docs/literature/README.md` + tag pages	`Active`
`NOTE-001`	`record/notes.d/`	`docs/notes/README.md` + tag pages	`Read`
`ADR-001`	`record/decisions.d/`	`docs/decisions/README.md` + tag pages	`Active`
`DP-001`	`record/principles.d/`	`docs/design-principles.md` (one page, read as a whole)	`Active`

What each family is

A scheme’s own account of itself, where it gives one — title and blurb on schemes.X. The table above says where a family’s files live and how its codes are spelled; this says what the family is for, which is the part a reader needs first and the part a config could not previously state (#279).

What an entry must carry

Every entry carries title and date. Everything else is listed below rather than assumed: status and the axis are controlled fields the scheme declares, and every relation — the successor a retiring document names included — is a reference the scheme declares, with the conditions it states (ADR-071, ADR-125). What each scheme’s entries must carry, compiled from luria.yaml into the contract luria lint checks, with where each obligation was declared. A finding cites the same line.

SOTA

source — required, one or more LIT codes (luria.yaml: schemes.SOTA.references.source) — the work that produced evidence about this claim. ADR-017’s test picks it: what the recommendation could not survive losing. Contrast is not support — a position argued against stays out (ADR-010).
introduced_by — optional, one or more LIT codes when present (luria.yaml: schemes.SOTA.references.introduced_by) — the work that first made this recommendation, which is frequently not the work that evidenced it. Separating origin from evidence is ADR-029, refined by ADR-030; with one field the record would read as though every practice began with the paper it cites. Leave it empty only to say the record looked and found no origin document, with a comment saying so — ADR-053.
explained_by — optional, one or more THEORY codes when present (luria.yaml: schemes.SOTA.references.explained_by) — the account of WHY this works, if the record holds one. Most practices have none, and a Rejected explanation does not retire the practice it explained (ADR-031).
extends — optional, one or more SOTA codes when present (luria.yaml: schemes.SOTA.references.extends) — the earlier practice this one builds on and could not stand without — a later version of the same recommendation, a narrower case of it, or a rule that only exists because the earlier one is followed. Direction is the point: the line reads oldest first. NOT for two practices that merely resemble each other (ADR-047).
extended_by — optional, one or more SOTA codes when present (luria.yaml: schemes.SOTA.references.extended_by) — the converse of extends, written by luria link --fix.
compared_against — optional, one or more SOTA codes when present (luria.yaml: schemes.SOTA.references.compared_against) — this work evaluated itself against that one — somebody ran the comparison (ADR-011). Not an analogy, not a family resemblance, and not a general rule beside its instance: those are extends or nothing.
corrects — optional, one or more SOTA codes when present (luria.yaml: schemes.SOTA.references.corrects) — this practice fixes something the earlier one got wrong, rather than building on it. The earlier one is normally Superseded and keeps its body (ADR-002).
corrected_by — optional, one or more SOTA codes when present (luria.yaml: schemes.SOTA.references.corrected_by) — the converse of corrects, written by luria link --fix.
contested_by — required when consensus is contested, one or more LIT codes when present (luria.yaml: schemes.SOTA.references.contested_by) — the published work that disputes this practice. Required once consensus says contested, so the claim that the field disagrees has to name who.
superseded_by — required when status is Superseded, one or more SOTA or THEORY codes when present; forbidden when status is Active (luria.yaml: schemes.SOTA.references.superseded_by)
consensus — one of unassessed, unreplicated, contested, emerging, converged, universal; absent means unassessed (luria.yaml: schemes.SOTA.fields.consensus; vocabulary ‘consensus’: values) — How far THE FIELD has converged on a practice, which is orthogonal to status — this record’s own editorial position. The useful cases are the corners: Deferred + converged is a practice everybody follows that we have not satisfied ourselves is deliberate, and Active + contested is this record being ahead of the field and saying so, which an anthology should be able to do (ADR-015).
status — optional, one of Active, Proposed, Deferred, Superseded, Rejected (luria.yaml: schemes.SOTA.fields.status; vocabulary ‘sota-statuses’: values) — What a status means for a PRACTICE: whether this record says to do the thing today. It is not the standing of the paper underneath — that is lit-statuses, and the two are allowed to disagree — and it is not what the field does, which is consensus (ADR-002).
tags — required, one or more of training-optimization, systems-optimization, numerics-and-precision, model-stability, distributed-optimization, data-pipeline, attention-techniques, model-architecture, inference-optimization, adaptation-and-tuning, in-context-learning, representation-and-encoding, analysis-and-evaluation, generative-modeling, vision-and-graphics, multimodal-learning, deployment-and-society, biomolecular-modeling, signal-structure, concept-geometry, agents-and-environments, graphs-and-networks, physical-sciences, human-ai-interaction, tiny-models, capability-thresholds, flows-and-transport, few-step-generation (luria.yaml: schemes.SOTA.fields.tags; vocabulary ‘topics’: values) — The twenty-eight kinds of claim this anthology files against — the primary axis of both the practice registry and the reading list, and the same twenty-eight for each (ADR-026). The filing rule is the point: take a domain topic when the claim is ABOUT the domain; a claim merely discovered in one still takes its kind. The axis organizes the record, it does not bound it: content the list cannot place is evidence the list is short (ADR-059).
promote_when — required when status is Proposed, Deferred (luria.yaml: schemes.SOTA.fields.promote_when)
primary_topic — derived — {tags[0]}, never written (luria.yaml: schemes.SOTA.fields.primary_topic)
published — derived — {published} from source[0], never written (luria.yaml: schemes.SOTA.fields.published)

THEORY

source — required, one or more LIT codes (luria.yaml: schemes.THEORY.references.source) — the work this account comes from. Same test as a practice’s: what the explanation could not survive losing.
explains — optional, one or more SOTA codes when present (luria.yaml: schemes.THEORY.references.explains) — the practice this account is about. An explanation may be Rejected while the practice it explained goes on working (ADR-031).
extends — optional, one or more THEORY codes when present (luria.yaml: schemes.THEORY.references.extends) — the earlier account this one builds on — a refinement or a widening of the same mechanism, not a rival one.
extended_by — optional, one or more THEORY codes when present (luria.yaml: schemes.THEORY.references.extended_by) — the converse of extends, written by luria link --fix.
corrects — optional, one or more THEORY codes when present (luria.yaml: schemes.THEORY.references.corrects) — this account replaces the earlier one’s reasoning. What the old account explained may still happen; only the reason was wrong.
corrected_by — optional, one or more THEORY codes when present (luria.yaml: schemes.THEORY.references.corrected_by) — the converse of corrects, written by luria link --fix.
contested_by — optional, one or more LIT codes when present (luria.yaml: schemes.THEORY.references.contested_by) — the published work whose evidence disputes this account. Not a paper that merely proposes a different account: that is rivals, between the two theories.
rivals — optional, one or more THEORY codes when present (luria.yaml: schemes.THEORY.references.rivals) — another account of the same phenomenon that cannot also be right, where neither yet corrects the other. Settled, it becomes corrects on the winner and a status on the loser.
superseded_by — required when status is Superseded, one or more SOTA codes when present; forbidden when status is Active (luria.yaml: schemes.THEORY.references.superseded_by)
status — optional, one of Active, Proposed, Deferred, Rejected, Superseded (luria.yaml: schemes.THEORY.fields.status; vocabulary ‘theory-statuses’: values) — Whether the record believes the ACCOUNT, which is not what the same word means on a practice. An explanation can be Rejected while the thing it explained goes on working exactly as well as it ever did (ADR-031).
tags — required, one or more of training-optimization, systems-optimization, numerics-and-precision, model-stability, distributed-optimization, data-pipeline, attention-techniques, model-architecture, inference-optimization, adaptation-and-tuning, in-context-learning, representation-and-encoding, analysis-and-evaluation, generative-modeling, vision-and-graphics, multimodal-learning, deployment-and-society, biomolecular-modeling, signal-structure, concept-geometry, agents-and-environments, graphs-and-networks, physical-sciences, human-ai-interaction, tiny-models, capability-thresholds, flows-and-transport, few-step-generation (luria.yaml: schemes.THEORY.fields.tags; vocabulary ‘topics’: values) — The twenty-eight kinds of claim this anthology files against — the primary axis of both the practice registry and the reading list, and the same twenty-eight for each (ADR-026). The filing rule is the point: take a domain topic when the claim is ABOUT the domain; a claim merely discovered in one still takes its kind. The axis organizes the record, it does not bound it: content the list cannot place is evidence the list is short (ADR-059).
promote_when — required when status is Proposed, Deferred (luria.yaml: schemes.THEORY.fields.promote_when)
primary_topic — derived — {tags[0]}, never written (luria.yaml: schemes.THEORY.fields.primary_topic)
published — derived — {published} from source[0], never written (luria.yaml: schemes.THEORY.fields.published)

LIT

extends — optional, one or more LIT codes when present (luria.yaml: schemes.LIT.references.extends) — the earlier paper this one builds on and could not stand without. Papers fork where the DESIGNS differ, practices where the RECOMMENDATIONS do, so a fork can exist at one layer and not the other (ADR-011).
extended_by — optional, one or more LIT codes when present (luria.yaml: schemes.LIT.references.extended_by) — the converse of extends, written by luria link --fix.
compared_against — optional, one or more LIT codes when present (luria.yaml: schemes.LIT.references.compared_against) — this paper evaluated itself against that one. Somebody ran the comparison; a shared topic is not one (ADR-011).
corrects — optional, one or more LIT codes when present (luria.yaml: schemes.LIT.references.corrects) — this paper shows the earlier one wrong on something it claimed. Retire by status, never by deletion — the body stays.
corrected_by — optional, one or more LIT codes when present (luria.yaml: schemes.LIT.references.corrected_by) — the converse of corrects, written by luria link --fix.
superseded_by — required when status is Superseded, one or more LIT or ARXIV codes when present; forbidden when status is Active (luria.yaml: schemes.LIT.references.superseded_by)
status — optional, one of Active, Proposed, Deferred, Superseded, Rejected (luria.yaml: schemes.LIT.fields.status; vocabulary ‘lit-statuses’: values) — A paper’s standing in the anthology: whether it is worth reading. NOT whether its findings are true. Adam is Active here because it is worth reading; whether any particular thing it recommends is still what you should do is the SOTA scheme’s business, and the two can disagree in either direction (ADR-002).
tags — required, one or more of training-optimization, systems-optimization, numerics-and-precision, model-stability, distributed-optimization, data-pipeline, attention-techniques, model-architecture, inference-optimization, adaptation-and-tuning, in-context-learning, representation-and-encoding, analysis-and-evaluation, generative-modeling, vision-and-graphics, multimodal-learning, deployment-and-society, biomolecular-modeling, signal-structure, concept-geometry, agents-and-environments, graphs-and-networks, physical-sciences, human-ai-interaction, tiny-models, capability-thresholds, flows-and-transport, few-step-generation (luria.yaml: schemes.LIT.fields.tags; vocabulary ‘topics’: values) — The twenty-eight kinds of claim this anthology files against — the primary axis of both the practice registry and the reading list, and the same twenty-eight for each (ADR-026). The filing rule is the point: take a domain topic when the claim is ABOUT the domain; a claim merely discovered in one still takes its kind. The axis organizes the record, it does not bound it: content the list cannot place is evidence the list is short (ADR-059).
published — required (luria.yaml: schemes.LIT.fields.published)
primary_topic — derived — {tags[0]}, never written (luria.yaml: schemes.LIT.fields.primary_topic)
source — at least one of arxiv, doi, url (luria.yaml: schemes.LIT.field_groups.source)

NOTE

paper — required, a LIT code (luria.yaml: schemes.NOTE.references.paper) — the paper this note is a close reading of. Absence of a note means the paper is unread (ADR-025).
superseded_by — required when status is Superseded, one or more NOTE codes when present; forbidden when status is Read (luria.yaml: schemes.NOTE.references.superseded_by)
status — optional, one of Read, Skimmed, Unread, Superseded (luria.yaml: schemes.NOTE.fields.status; vocabulary ‘note-statuses’: values) — How deeply the paper was READ — not whether it is any good, which is lit-statuses. The two disagree in every direction: a foundational paper can carry a Skimmed note, and a paper in the attic can carry a Read one, since reading it carefully is often how it got there (ADR-025).
published — derived — {published} from paper, never written (luria.yaml: schemes.NOTE.fields.published)
primary_topic — derived — {tags[0]} from paper, never written (luria.yaml: schemes.NOTE.fields.primary_topic)
tags — derived — {tags} from paper, never written (luria.yaml: schemes.NOTE.fields.tags)

ADR

superseded_by — required when status is Superseded, one or more ADR codes when present; forbidden when status is Active (luria.yaml: schemes.ADR.references.superseded_by)
influenced_by — optional, one or more ADR codes when present (luria.yaml: schemes.ADR.references.influenced_by)
status — optional, one of Active, Proposed, Deferred, Superseded, Rejected (luria.yaml: schemes.ADR.fields.status; vocabulary ‘adr-statuses’: values) — Whether a decision is in force. Shared by ADR and DP, because as far as being in force goes a principle and a decision are the same kind of object.
tags — required, one or more of record, taxonomy, mechanism, migration (luria.yaml: schemes.ADR.fields.tags; vocabulary ‘adr-tags’: values) — What a decision is about, in the order the index shows them. Open, unlike the topics: a decision that needs a word it does not have simply gets one.

DP

superseded_by — required when status is Superseded, one or more DP codes when present; forbidden when status is Active (luria.yaml: schemes.DP.references.superseded_by)
influenced_by — optional, one or more ADR codes when present (luria.yaml: schemes.DP.references.influenced_by)
status — optional, one of Active, Proposed, Deferred, Superseded, Rejected (luria.yaml: schemes.DP.fields.status; vocabulary ‘adr-statuses’: values) — Whether a decision is in force. Shared by ADR and DP, because as far as being in force goes a principle and a decision are the same kind of object.
tags — required, one or more of record, evidence, craft (luria.yaml: schemes.DP.fields.tags; vocabulary ‘dp-tags’: values) — What a principle is about. Shares its words with the decision tags where they overlap, deliberately — the same subject should not have two names depending on which scheme is talking about it.

Journals

Dated observations. An entry is true about the day it was written and is never revised or consumed — the books are a view over sources that stay, which is what makes a journal safe to write into without coordinating.

journal	entries filed at	books rendered to	one book per	titled
`curation`	`record/curation.d/` `yyyy/mm/dd/hhmmss.md`	`docs/curation/`	month	Curation log

Fragment directories

One file per contribution, assembled into a single document and then consumed. The point is the absence of a shared file to conflict on: every contributor writes a new path.

directory	assembled into	style
`record/changelog.d/`	`CHANGELOG.md`	changelog

Other projects this record cites

A prefixed code reaches into another project’s record, so a citation says whose decision it is at the point of use rather than leaving the reader to guess.

cited as	project	repository	ref
`ARXIV-ADR-001`	arXiv	—	main
`DOI-ADR-001`	DOI	—	main
`LU-DP-001`	luria	dmarx/luria	main
`FX-ADR-001`	fixtures	—	main

Filing something new

Every kind this project scaffolds, straight from the dispatch table luria new itself uses.

command	files
`luria new --kind adr --title "…"`	a document in the `ADR` scheme, numbered for you
`luria new --kind changelog --title "…"`	a fragment in `record/changelog.d/`
`luria new --kind curation --title "…"` — or just `luria new --title "…"`, the default kind	a dated entry in the `curation` journal
`luria new --kind dp --title "…"`	a document in the `DP` scheme, numbered for you
`luria new --kind lit --title "…"`	a document in the `LIT` scheme, numbered for you
`luria new --kind migration --title "…"`	a migration spec
`luria new --kind note --title "…"`	a document in the `NOTE` scheme, numbered for you
`luria new --kind sota --title "…"`	a document in the `SOTA` scheme, numbered for you
`luria new --kind theory --title "…"`	a document in the `THEORY` scheme, numbered for you

Settings this project changed

Everything not listed here is at Luria’s default.

key	this project	Luria’s default
`issue_url`	`https://github.com/dmarx/anthology-of-the-sota/issues/{n}`	empty
`code.globs`	`src/*/.py`, `luria.yaml`, `.github/workflows/*.yml`	empty
`code.historical`	`CHANGELOG.md`, `README.md`	`CHANGELOG.md`
`chains.practice`	7 keys set	unset
`chains.lineage`	6 keys set	unset
`chains.theory`	6 keys set	unset
`lint.fail_on`	`source-mismatch`	empty
`lint.mute`	`inert-status`, `acknowledged-uniformity`	empty
`lint.narrow_terms`	`adam`, `adamw`, `batchnorm`, `layernorm`, `transformer`, `llama2`, `flash-attention`, `arxiv`, `registry`	empty
`site.icon`	`assets/logo.svg`	empty
`vocabularies.topics`	4 keys set	unset
`vocabularies.sota-statuses`	4 keys set	unset
`vocabularies.lit-statuses`	4 keys set	unset
`vocabularies.note-statuses`	4 keys set	unset
`vocabularies.theory-statuses`	4 keys set	unset
`vocabularies.adr-tags`	3 keys set	unset
`vocabularies.adr-statuses`	4 keys set	unset
`vocabularies.dp-tags`	3 keys set	unset
`vocabularies.consensus`	4 keys set	unset

anthology-of-the-sota

Explorer