pub enum SalvageStatus {
Intact,
Complete,
Unattested,
Unverified(UnverifiedCause),
Partial,
}Expand description
What was proven about an entry AFTER decoding it.
Variants§
Intact
A checksum the original writer computed agrees.
Complete
Every declared byte was present and the header self-verified, but the
format offers NO CHECKSUM AT ALL to prove the content — tar, in
this project’s own formats. Never the right answer for a format that
DOES carry one; see SalvageStatus::Unverified for that case,
which this status is not permitted to stand in for.
§cpio and ar are NOT this tier, and were named here until Stage 3
This doc said “tar, cpio and ar” from Stage 1 until Salvage Stage 3,
which is where the sentence’s own “and the header self-verified”
clause was measured against the three formats it named. tar has a
header checksum and really does self-verify. cpio and ar have
neither a content checksum nor a self-verifying header, so for
those two the clause is not merely unproven — there is nothing in the
format it could ever be true of, and a scanner answering Complete
for one would be asserting a header self-check that does not exist.
They are SalvageStatus::Unattested.
stuffr_core::testing::check_salvage_claim is what holds the line: this
tier requires a format whose only checksum covers the HEADER
(Attestation::HeaderChecksumOnly) AND that checksum to have been
checked — so the checksumless pair cannot reach it, and neither can a
format with a content checksum, whose honest tiers are Intact,
Partial and Unverified.
Unattested
Nothing attests that this candidate is an entry AT ALL: the format
carries no checksum and no self-verifying header, so a
coincidental header match and a real entry are indistinguishable in
the bytes — cpio and ar, in this project’s own formats.
The entry is still WRITTEN, under its real name: salvage is the
recovery-biased verb, and a tier that refused to write would make
these two formats unsalvageable rather than honestly salvaged. What
the tier buys is that the run says so — salvage_exit_code answers
4 for it (degraded fidelity, never 3: nothing was refused and no
capability was missing), and the --list row carries the reason
beside the entry. There is no flag to opt into or out of this; the
formats’ own shape decides it.
§Not Self::Unverified — and the near-miss name is the hazard
The variant deliberately is NOT called Unverifiable: that is two
letters from the Self::Unverified this enum already has, in an
enum whose variants select exit codes, and a reviewer skimming match
arms would not reliably see the difference. The distinction, stated
wherever both appear:
Self::Unverified— the format has a checksum; this build could not use it (an undecodable method), or the header declared nothing to check.Unattested— the format has no checksum and no self-verifying header, so nothing attests that this candidate is an entry at all.
The consequences differ as much as the claims do: Unverified is
NOT written and exits 3 (this build could not do it — a rebuild may
fix it), Unattested IS written and exits 4 (nothing can fix it;
the format carries no evidence to find).
Unverified(UnverifiedCause)
Nothing about this entry’s content was verified.
Two causes (UnverifiedCause), and the tier does not distinguish
them because the decision is identical — the entry is listed, not
written, and the run exits 3:
- this build could not decode the method (zip 99 is AES, 14 is LZMA);
- no length was available to bound the payload, so it was never read (a data-descriptor entry the raw scan found with no central-directory record to reconcile against).
Distinct from Self::Complete, which asserts every DECLARED byte
was present — a claim that requires something to have been declared
in the first place. Reporting Complete for either cause above was
this enum’s third instance of “nothing to disprove” being read as
“proven” (after the Task 1 hardcoded placeholder and the Task 4
undecodable-method case this variant was originally added for) — the
exit-code table this status exists to keep honest reserves exit 3 for
both causes, never exit 0, which is what Complete would have routed
either one to.
Partial
The payload ran out, the decoder failed mid-stream, or the content
decoded whole and disagreed with the checksum the original writer
computed. All three are the same fact from a caller’s perspective —
this build could not confirm the content is what was written — and
none of them is Complete (something WAS checked) or Intact (it
did not agree, or never finished).