Why Preserve Run Artifacts?
A model run is evidence of a particular computational event: it used particular inputs and produced particular outputs in a particular execution environment. If an input file is later edited, or an output is overwritten during analysis, it may become impossible to tell whether a difference reflects a genuine new run or an accidental change to the old one. Preserving the original files makes that distinction checkable.
The goal is not to prevent all later work. It is to keep a stable record of the inputs and outputs that belong to a completed run, while placing transformations, summaries, plots, and other subsequent work elsewhere. Checksums can reveal that file contents differ from a recorded baseline; read-only storage helps prevent routine editing. Neither measure, by itself, proves that a model was scientifically appropriate or that the run can be reproduced.
Immutability is a preservation rule, not a claim that files can never be copied or that storage permissions are physically impossible to override. It means that the original artifact set is treated as fixed, and any authorized change creates a distinguishable new record rather than silently replacing the old one. The earlier material on run manifests and execution environments supplies useful context: a file list and environment description help identify what belongs to a run, while integrity checks help determine whether those files have changed.
Define What Must Remain Unchanged
Before creating checksums, decide which files count as original inputs and outputs. For example, a run's input data, model specification, control settings, and final output tables may be retained as artifacts. A later diagnostic plot or a spreadsheet that reformats a result is derived work, not an original output merely because it concerns the same run. Keep the distinction explicit in the records.
A checksum is calculated from a file's bytes. It does not automatically include the filename, location, creation time, permissions, or the reason a file was produced. Therefore, a useful integrity record associates each checksum with an unambiguous file identity, such as a relative path within the artifact set, and identifies the checksum algorithm. A record that says only “hash: abc…” without saying which file and which algorithm is not sufficient for reliable verification.
The comparison is exact: if the newly computed digest matches the trusted digest, the bytes match to the extent supported by the hash function's collision resistance. If the digests differ, the file is not byte-for-byte identical to the recorded version. A mismatch does not reveal which edit occurred, when it happened, or whether the change was intentional; those questions require other records and investigation.
Worked Example: Detecting a Changed Input File
Worked Example: Detecting a Changed Input File
Suppose a hypothetical run uses a comma-separated input file named analysis_data.csv. At the time the run is finalized, its full SHA-256 digest is recorded in a trusted manifest. For compact display here, assume the illustrative digest begins 4c1a9e70…; the ellipsis means that the remaining hexadecimal characters are omitted, not that an abbreviated digest should be used for actual verification.
The verification operation is:
On the first check, the current file produces the same full digest as the manifest: 4c1a9e70… equals 4c1a9e70…. The content matches the recorded version under this check. Later, someone corrects one concentration value in the CSV and saves the file. A new check produces an illustrative digest beginning bd3092f4…. Since bd3092f4… is not equal to 4c1a9e70…, the current bytes differ from those originally recorded.
The comparison does not establish that the correction was wrong, nor does it identify the row that changed. It establishes that this file is no longer the original input. Preserve the edited version as a new, clearly identified input version if it is to be used in a later run; do not replace the original file while leaving the original record unchanged.
These digest strings are illustrative shortened displays, not real hashes of a supplied file. In practice, use the complete digest and an established implementation of SHA-256. Do not manually compare only a few leading characters: a shortened string is more likely to match by coincidence and does not provide the stated strength of the full digest.
A Practical Preservation Workflow
A dependable process separates defining the artifact set, recording its baseline, protecting it, and checking it when needed. The precise storage system may differ, but the integrity logic remains the same.
List the exact inputs and outputs to preserve. Distinguish them from later reports, plots, transformed data, or other derived files.
For each artifact, record an unambiguous file name or path, the checksum algorithm, and its full digest. Keep the record associated with the run and protect it from untracked edits.
Store the original artifact set in a location intended for preservation. Apply read-only permissions or stronger storage controls where available, and retain a protected copy of the checksum record.
Recompute checksums when retrieving or transferring artifacts, or when a change is suspected. Compare each full digest with the trusted baseline and investigate every mismatch.
Write new analyses and outputs as derived files or as a new run's artifacts. Do not overwrite the preserved baseline.
A read-only flag is a useful control against ordinary accidental editing, but its strength depends on the system. A user with sufficient privileges may change permissions; a program may write to a different copy; and a storage failure may affect the file despite its read-only status. More protective systems can include access controls, versioned storage, snapshots, or retention locks. Whatever the mechanism, verify the bytes: a permission label alone does not demonstrate that the file remained unchanged.
Worked Example: Separating Outputs From Derived Work
Worked Example: Separating Outputs From Derived Work
Consider a hypothetical run whose original output includes parameter_estimates.csv and fit_report.txt. Their full recorded SHA-256 digests are represented here by the illustrative prefixes aa72c431… and 18f5d60b…. A reviewer imports the estimates into a spreadsheet, rounds estimates to three significant figures, and creates a plot.
The two original outputs remain the files with their recorded digests. The rounded spreadsheet and plot are derived files: rounding changes the represented values, and the plot is a new file. They should be saved under distinct names and should not be substituted for, or written over, the original output files.
Suppose the reviewer accidentally saves the rounded table over parameter_estimates.csv. The recomputed digest now begins 53de901a…, rather than the recorded aa72c431…. The check detects that the output bytes changed. The appropriate conclusion is not “the model run changed,” because the fitted run may have been completed before this edit. The supported conclusion is that the file currently at that location no longer matches the preserved output.
If the original output is available from a protected copy, restore it as the original artifact and retain the rounded table separately as derived work. If no trustworthy original copy remains, the recorded digest can document the expected content but cannot reconstruct it. A checksum is a comparison tool, not a backup.
Why the Checksum Comparison Works—and Its Limits
A hash function deterministically maps any file's byte sequence to a fixed-length digest. The same bytes, processed with the same algorithm, produce the same digest. A cryptographic hash is designed so that it is computationally infeasible to find a different byte sequence with the same digest. This design makes a digest practical for detecting accidental file changes without storing a second copy solely for comparison.
For intuition, if SHA-256 outputs behaved like uniformly random 256-bit strings, a specified altered file would have probability \(1/2^{256}\) of matching one fixed expected digest. This is an idealized model, not a guarantee that every real-world threat has that probability. The security claim depends on using the algorithm correctly and on its collision resistance; it does not mean a checksum proves who created a file or prevents deliberate replacement.
The trusted-baseline condition matters. If someone can edit both an artifact and the only checksum record, they can replace the file and make a new matching record. Protect the manifest or checksum list separately, or use a trusted signature or controlled storage when intentional tampering is within the threat model. A checksum also does not authenticate the scientific origin of a file: a matching digest says that bytes match a baseline, not that the baseline was generated by the claimed run.
Checksums operate on bytes, so format-preserving or apparently harmless changes can still produce a mismatch. Rewriting line endings, changing a text encoding, or adding a final newline changes bytes even if the displayed values seem identical. Conversely, a digest alone does not record timestamps, permissions, or provenance. Record such metadata separately if it matters to interpretation or audit.
Worked Example: Interpreting a Mismatch After Transfer
Worked Example: Interpreting a Mismatch After Transfer
A hypothetical analyst copies a preserved text output from one computer to another. The trusted record gives a full SHA-256 digest beginning 7d8e214c…. On the destination, the digest begins c1095a33…, so the comparison fails: the received bytes do not match the recorded bytes.
The analyst checks the file and finds that a text-transfer step converted line endings. The displayed lines and numerical values appear unchanged, but the byte sequence differs, so a mismatch is expected. The check has correctly identified a byte-level difference; it cannot decide whether that difference is acceptable for the intended use.
The analyst should not silently update the trusted digest to c1095a33…. First determine which copy is the original, whether the transfer change was intentional, and whether an exact copy can be retrieved. If the altered file is retained for a reason, label it as a transformed copy, preserve the original digest record, and record what transformation occurred. This keeps the evidence about the original artifact distinct from the status of the new file.
Diagnostics, Alternatives, and Common Pitfalls
A mismatch is a signal to investigate, not a diagnosis. Check that the right file was selected, that the same hash algorithm was used, and that the complete digest was compared. Then examine whether a transfer, editor, export, or process may have rewritten the file. If several files are involved, identify each mismatch separately; a single statement that “the run changed” is too broad.
Checksums and read-only storage serve different purposes. Checksums detect a difference relative to a baseline; read-only controls reduce the chance of an in-place change. Backups preserve recoverable copies; version control can retain a history of text-file changes; signed records can help authenticate a baseline. These approaches can complement one another, but none makes the others unnecessary. For example, a checksum cannot restore a lost file, and read-only storage alone does not show whether a file was already different before it was protected.
- Pitfall: treating “read-only” as proof of integrity. Read-only permissions can be bypassed or applied after an unintended edit. Correction: verify the current digest against a protected baseline.
- Pitfall: updating the checksum after a mismatch without investigation. That makes the changed file the new baseline and erases the evidence of the discrepancy. Correction: preserve the original record and document any authorized new version distinctly.
- Pitfall: assuming matching checksums establish provenance. The match only supports byte equality against the recorded digest. Correction: protect the checksum record and use provenance or authentication controls when identity matters.
- Pitfall: treating derived files as original run outputs. A rounded table or plot may be useful, but it is not the unmodified output. Correction: label and preserve derived work separately.
Check Your Understanding
Answer each question, then compare your reasoning with the solutions.
- A file's current SHA-256 digest differs from its recorded digest. What can you conclude, and what can you not conclude?
- Why should a checksum record identify the file and algorithm, rather than store a digest by itself?
- A spreadsheet rounds values from an original output and is saved under a new name. Is it an original output or a derived file? Explain.
- Why is a checksum not a substitute for a backup?
- If a file and its only checksum record can both be edited by the same person, what protection is missing?
Solutions. (1) The current file's bytes do not match the recorded version under the stated check. The mismatch alone does not identify the edit, its timing, its cause, or whether it was intentional. (2) The identity connects a digest to the artifact it is meant to verify, and the algorithm specifies how the digest was computed; without these, comparison is ambiguous. (3) It is derived work because rounding transforms the original values, even if the spreadsheet is useful for review. (4) A checksum can indicate that a file differs but cannot reconstruct the original bytes; a backup provides a recoverable copy. (5) The baseline is not protected from coordinated replacement. A separately protected record, controlled storage, or an authenticated signature is needed to make unauthorized changes to the baseline detectable.