📖 dmarx.github.io/luria — this record, published by luria site.
Governed knowledge, kept coherent under change.
Luria is a framework for maintaining bodies of knowledge whose meaning changes over time.
A Luria record can hold decisions, proposals, recommendations, evidence, policies, principles, incidents, standards, interpretations, observations, theories, or other claims that acquire relationships and standing as a corpus evolves.
The central idea is simple:
When one piece of knowledge changes, Luria helps expose what else may need reconsideration.
A document can become stale without anyone editing it. A decision is superseded; an implementation still cites it. A paper remains historically important while a recommendation based on it is retired. A policy still points to authority that no longer applies. The strings continue to resolve, but the surrounding context has changed.
Luria makes more of that context explicit.
A record begins with a declaration of the knowledge system you want:
luria.yaml
↓
luria init
↓
luria new
↓
author
↓
luria lint
↓
luria index
luria init plans the scaffold from configuration rather than copying one universal tree (ADR-048). luria new derives the entry kinds it can create from that same configured record (ADR-036).
A minimal record might declare RFCs:
vocabularies:
rfc-status:
Proposed: {}
Accepted: {}
Rejected: {}
Superseded: {}
schemes:
RFC:
dir: record/rfcs.d
output: docs/rfcs
active: Accepted
fields:
status:
vocabulary: rfc-statusThen:
$ luria init
$ luria new rfc --title "Introduce durable background jobs"
$ luria lint
$ luria indexThe important thing is not YAML or Markdown by themselves. It is that the repository now contains identifiable objects whose fields, relations, standing, and generated projections have declared semantics.
An object may keep the same identity while its standing changes:
RFC-017
Proposed → Accepted → Superseded
Historical existence and current authority are different properties.
Luria's own decision doctrine makes the same distinction at the level of change: if the choice changes, supersede it; if the choice stands but the recorded reason was wrong, correct the record visibly rather than manufacturing a false history (ADR-019).
A reference can mean more than “this string names another file.”
IMPLEMENTATION-008
──implements──►
DECISION-014
If DECISION-014 becomes superseded, the edge may still resolve while the use becomes questionable. Luria can surface that condition for review rather than pretending every consequence is mechanically decidable.
This is the truth-maintenance loop:
premise changes
↓
dependent condition surfaces
↓
finding
↓
human review
Some suspicious conditions are legitimate. A retrospective may intentionally cite a superseded decision. A remote reference may be temporarily unavailable. A corpus may have a known backlog.
Luria distinguishes findings from enforcement. Warning classes are reported by default and can be promoted to failures (ADR-035), baselined, or explicitly acknowledged — without the acknowledgement disappearing from the accounting (DP-1).
The useful pattern is:
lint discovers
↓
repair fixes what is mechanical
↓
ack records human judgment
Local relations can carry higher-order meaning.
Suppose records declare:
A extends B
C corrects A
D compared_against C
A Luria chain can walk one or more same-scheme succession relations into a generated sequence, add sibling/rival edges, carry vocabulary-backed facets onto each step, and check an invariant across the line (ADR-083, ADR-106, ADR-113).
Authors state the edges. Luria derives the line.
That supports decision succession, research lineages, evolving recommendations, standards families, policy histories, or explanatory theories without maintaining a second hand-written lineage that can drift.
See Relations and chains and the chains tutorial.
Luria's major record families are semantically distinct:
| Family | Role |
|---|---|
| Scheme | identifiable objects with standing and relations |
| Journal | dated observations whose sources persist |
| Fragment directory | distributed contributions assembled into another artifact |
| Remote | identities or authorities owned elsewhere |
Generated indexes, chain pages, reports, sites, and exports are projections, not competing sources of truth. DP-3 states the general rule: if a view can be derived from an authoritative source, derive it rather than maintaining a parallel copy.
A vocabulary can classify records, constrain admissible values, and act as an interpretive axis in generated views.
For example:
status = what this record currently endorses
consensus = what the field appears to believe
Those values can vary independently. On a chain, they can be rendered as facets so a converged trunk, a contested branch, and a provisional successor are not flattened into the same-looking sequence.
Some claims describe the subject:
Use renewable leases for durable jobs.
Others govern how claims are represented and changed:
Every superseded decision names its successor.
Call the subject-level record R and the governing knowledge M. The question Luria keeps asking is:
M; R ⊢ x
That is: given the current record and the rules under which it operates, does this object or relation still make sense?
The distinction can remain conceptual, be tagged inside one record, use a separate scheme, or live in a dedicated meta-record. Luria meets the corpus where it is rather than requiring one canonical decomposition (DP-14).
Luria's own documentation should depend on the decisions and principles that make its behavioral claims true.
This README says that luria init is configuration-driven, so it cites ADR-048. It says luria new derives entry kinds from configuration, so it cites ADR-036.
Those are maintenance edges, not decorative footnotes.
When a governing ADR stops being in force, the documentation that cites it becomes reviewable even though nobody edited the prose: luria lint reports the citation under the retired-citations warning class.
That is the product demonstrating its own thesis.
- New to Luria: Build a governed RFC process
- Want to see chains: Build a lineage with chains
- Already have a corpus: Adopt Luria around an existing corpus
- Understand the model: Concepts
- Do a specific task: How-to guides
- Look up exact behavior: Reference
- Understand why Luria behaves this way: follow the cited ADRs and DPs.
Luria requires Python 3.11 or later.
$ pip install luriaMIT — see LICENSE.
Luria — governed knowledge, kept coherent under change.