ADR-0061: A Curated Explanation is replaced in place, never retired

Status: Superseded by ADR-0073 — do not follow this ruling; the second authoring is refused Date: 2026-09-20

Decisions

D-135 There is one live Curated Explanation per term, and authoring that term again replaces it in place

The replacement records the new reviewer and the new time. There is no retirement, so term @unique spanning soft-deleted rows cannot lock a term out.

Context

The open question was framed as retirement — how to take an explanation out of service — and retirement is what creates the problem. A soft-deleted row keeps the term's unique key, so a retired explanation would make its term unexplainable forever, and the only escape would be narrowing the constraint.

Replacement dissolves the question instead of answering it. A term either has a live explanation or it has never had one; there is no third state to represent, and no row is ever taken out of service.

The reason replacement is safe is ADR-0056. A published version carries its own copy of every explanation that existed when it was published, so replacing the live row cannot reach a version already shipped. A device's Corpus keeps what it pulled until the next publish checks a new one. Without that, replacement would be a silent edit of shipped safety text; with it, it is an edit of what the next publish will carry.

Decision

Authoring an explanation for a term that already has one replaces it, recording the new reviewer and time. Nothing is retired and nothing is soft-deleted.

Rejected options

• Retiring an explanation, soft-deleting the row — rejected because term @unique spans soft-deleted rows, so the retired row keeps the key and the term can never be explained again. The capability would break the thing it was meant to manage.
• Narrowing the unique constraint to live rows — rejected on the same precedent objection as the withdrawal ruling (D-132): it settles by migration a question nobody has needed answered. Here it is worse, because the case does not need it at all — replacement leaves no dead row for the constraint to trip over.
• Keeping a version history of explanations in the live store — rejected because ADR-0056 already keeps the copy that matters, inside each published version's payload. A second history beside it is a second source of truth for what a device received.

This ruling may not be re-decided

If a change contradicts this ADR: stop and raise it. Do not implement over it.

Specifically: do not add a retire or soft-delete path for a Curated Explanation, do not narrow term @unique to live rows, and do not treat a replacement as reaching a published version — it does not, and a change that made it do so would contradict ADR-0056.

Consequences

What becomes true. A term can always be re-explained, by anyone curating, however many times it has been explained before. Every live explanation names the person who last reviewed it and when.

What this costs. The previous wording is gone from the live store the moment it is replaced. What it said is recoverable only from the published versions that carry it, which is where the copy that was ever shown to anyone lives anyway.

What is closed off. Retirement, soft-deletion, and a live-row-only unique constraint.

Coverage

Upstream	Landed in	Evidence	Note
D-127	D-135	every published version stores the payload the gate passed, so a replacement cannot reach a version already shipped	ADR-0056; this is what makes replacement safe rather than a silent edit
D-123	D-135	a snapshot's explanations are those that existed when it was published, which is the rule replacement respects	ADR-0053
D-90	D-135	a term explanation is a Curated Explanation, held on device and displayed extractively — so the live row is authoring input, not the thing a person reads	ADR-0037