Corrections or replacements?

Think of a printed book again. When the publisher finds a misprint, they paste an erratum slip into the same printing: the title is unchanged, and the faulty page is still there underneath for anyone who looks. When the author revises the work into a second edition, that is a new print run with its own identity, and the first edition stays on the shelf. MTRL makes the same two moves with your data, and the archive shelves both versions, always.

Two different repairs

A correction fixes one logical result. The old value was wrong — a mistake — and you are putting it right. correct_checkpoint keeps the CheckpointId: it is still “the spectrum”. It mints a new RecordId for the corrected record, makes that record the active one, and links it to the old record with a correction-of relationship. The erratum slip, in other words.

A replacement introduces different evidence. The old value was fine; better evidence now exists. replace_checkpoint mints a new CheckpointId and a new RecordId, reusing neither identity from the replaced checkpoint. The new record links to the old one with a replacement-of relationship. From then on the active view selects the replacement and no longer selects the old checkpoint. The replaced record is not deleted. It remains in the history, exactly as committed. The second edition, next to the first on the shelf.

If CheckpointId, RecordId, and RecordRef are new to you, read Two kinds of identity first; the rest of this page builds on them.

How to choose

The rule of thumb asks what the old value claims.

• Correct when the old value was wrong. The saturated detector clipped the peak of your FTIR spectrum, so the recorded absorbance misstates the film. You corrected that record in Fix a mistake, and the checkpoint name “spectrum” survived.
• Replace when the old value was honest but superseded. If you re-measure polymer-film-01 a year from now on a newer spectrometer, the original spectrum is not wrong. It is an accurate record of that day on that instrument. The new measurement is different evidence, so it earns a CheckpointId of its own.

Ask yourself which sentence you would defend in a report. “The old number was a mistake” calls for a correction. “The old number was sound, and here is a better one” calls for a replacement.

What both moves guarantee

Both operations are careful in the same ways.

Both aim at the active record. Each call takes an exact RecordRef naming its target, and that target must be the currently active record for the checkpoint. Point at a stale or historical version and the call fails with no state change at all: no partial write, no new revision.

Neither retargets the past. A correction does not rewrite records that used the old version, so the mean spectrum of your three replicates still names the exact records it consumed, even if one replicate is corrected afterwards. A replacement removes the old checkpoint from the active view, but never from the history.

Neither can overwrite an identity. Adding a checkpoint whose supplied CheckpointId already exists is rejected with DuplicateCheckpointError: new evidence always arrives under a fresh identity, and nothing committed is ever changed in place.

Each success creates exactly one revision. Each failure creates none. For the exact signatures and error names, see the reference.

Where next

To see how a correction-of link sits inside a full recorded recipe, read Lineage and the recorded recipe. To make a correction yourself, revisit Fix a mistake.