Artifact Loss/Corruption

1. A filename is not artifact identity

A build artifact can keep the same filename, tag, or version string while its bytes change. Start diagnosis from an expected immutable identity: expected digest, expected size, locator/reference, and known provenance. Names and mutable tags are labels or locators, not proof of byte identity.

2. Keep three evidence axes separate

For every artifact, ask three independent questions: is it reachable; do the bytes match the expected identity; and is the required provenance present for those bytes? A positive answer on one axis does not prove the other two. This separation prevents false recovery claims.

3. Lock expected digest and size before recovery

If the expected digest or size is unknown, later comparison has no trustworthy authority. OCI Content Descriptors require a digest and size for referenced content and recommend verifying retrieved content against them before trust. This lesson uses sha256 for fixture identity; another algorithm is acceptable only when the authority record declares it.

4. Separate reachability from integrity

An artifact can be missing or unreachable without evidence that any existing bytes are corrupt. Conversely, it can be fully reachable and still have the wrong digest. A missing object, broken locator, or tag problem belongs to reachability/reference evidence; digest and size belong to byte integrity.

5. Size mismatch is an early signal, not the whole diagnosis

If observed size differs from expected size, the content should not be trusted. That can indicate truncation, partial upload, or replacement, but final classification still needs digest and context. A size match is also insufficient: two different payloads can have the same length.

6. Quarantine digest mismatches

When content is reachable but the independently calculated digest differs from the expected digest, the owned classification is CORRUPT and the artifact must leave the release path. Correct name, correct tag, upload success, or matching size cannot bypass quarantine. Recovery must come from a trusted source or traceable rebuild.

7. Unreferenced is different from missing

Sometimes the correct bytes still exist and match digest and size, but a mutable tag or release reference no longer points to them. That state is UNREFERENCED, not MISSING or CORRUPT. Repair normally restores or rebinds the reference and then re-verifies identity rather than fetching a same-name copy from an unknown source.

8. Byte integrity is not provenance

Digest and size may match perfectly while the required provenance link, build attestation, or chain-of-custody is absent. Bytes can therefore be BYTE_VERIFIED while release remains blocked. A digest does not prove the intended source revision/build recipe or that execution is safe.

9. Git fsck is one concrete integrity oracle

For a Git object database, git fsck checks connectivity and validity and can report conditions such as missing <type> <object> and hash mismatch <object>. It is a useful official example of separating reachability from integrity failure, but it is not a universal verifier for every artifact store.

10. Recovery sources must be explicit and trusted

For MISSING or CORRUPT, do not recover from "any copy that can be found." The record should identify a trusted recovery source: a known snapshot, a rebuild from a pinned source revision and recipe, or a replica whose identity is independently verified. Without such a source, remain BLOCK_AND_ESCALATE.

11. Artifact Integrity, Reachability & Recovery Record v1

The owned artifact tracks twelve dimensions: expected digest, expected size, observed digest, size match, reachability, reference state, provenance state, integrity classification, trusted recovery source, quarantine state, reverification, and release state. Label each decisive cell as observation, authority, inference, or UNKNOWN; UNKNOWN never silently becomes PASS.

12. Build classification from evidence

The main lab outcomes are VERIFIED, MISSING, CORRUPT, UNREFERENCED, BYTE_VERIFIED_PROVENANCE_OPEN, and UNKNOWN. Establish reachability and expected identity first, then compare size/digest, then evaluate reference and provenance. Do not classify from filename, tag, or one message alone.

13. Containment is not closure

Quarantining a corrupt blob is containment; copying in a replacement is still not closure. Closure requires independent reverification of recovered bytes against expected size/digest, the required reference state, and the provenance requirement. If provenance cannot be restored or justified, release remains blocked even when bytes match.

14. Lab: eight fixtures and 64 assertions

The lab is fully local and synthetic. The eight cases cover a verified baseline, a missing blob, a same-name digest mismatch, correct but unreferenced content, a truncated payload, correct bytes with missing provenance, a one-byte transfer mutation, and a transfer with provenance removed. The evaluator emits eight fields per case for 64 assertions total.

15. Exit checklist and transfer

Before exit, explain where expected identity comes from, why reachability and integrity are independent, which artifact must be quarantined, what makes a recovery source trusted, and which independent reverification proves closure. In transfer, all filenames and tags stay unchanged while one payload changes by one byte and another loses provenance; rebuild the record from evidence rather than trusting the visible names.