Delivery: A Repeatable Release · 25 min · free lesson

Bind an Artifact to Its Source

Verify release identity and digest metadata.

Core idea

A filename or version label does not prove which bytes were tested.

Diagram for Bind an Artifact to Its Source: a Rust code example flows to the lesson rule and the key observation.
The worked implementation exercises verify release identity and digest metadata. Its tests demonstrate the stated finite contract.

Understand it

A release artifact should have an identity that can be compared with the tested source and the expected content digest. Reusing a mutable latest filename makes rollback and incident investigation harder. Retain the source revision, exact target, digest and verification receipt beside immutable artifact bytes.

The lab validates metadata: a full lowercase 40-hex Git object ID, a lowercase 64-hex SHA-256 digest and an exact match with an independently supplied expected digest. It does not calculate SHA-256 or prove the claim by validating string shape. The actual delivery script computes the digest from built bytes with a standard tool, then compares it before promotion. A digest detects changed bytes when the expected digest is trusted; it is not an author signature. Keep signing and provenance decisions explicit rather than calling a checksum an authenticity guarantee.

The route project is Task Ledger: first keep a reproducible source history, then expose its data through a CLI and HTTP boundary, persist it in SQL, diagnose failures and prepare a release. This lesson owns one contract in that project. Run the worked example before changing the starter and explain which input makes the tempting shortcut fail.

Terminal practice: Run the desktop delivery script, inspect its source revision and computed artifact SHA-256, then modify an artifact copy and observe verification fail.

The compiler lab is independent of the reading question. Edit solution.rs; the app supplies a separate caller with normal, empty and adversarial inputs. A successful unchanged demonstration does not prove your implementation. After the lab, apply the same contract to the route companion project. Its README separates the on-device adapter from the desktop Cargo/TCP profile.

Read the code

pub fn artifact_matches(
    commit: &str,
    digest: &str,
    expected: &str,
) -> bool {
    let hex = |s: &str, n: usize| {
        s.len() == n
            && s.bytes().all(|b| {
                b.is_ascii_digit() || (b'a'..=b'f').contains(&b)
            })
    };
    hex(commit, 40)
        && hex(digest, 64)
        && hex(expected, 64)
        && digest == expected
}

fn main() {
    assert_eq!(
        artifact_matches(
            &"a".repeat(40),
            &"b".repeat(64),
            &"b".repeat(64)
        ),
        true,
        "case 1"
    );
    assert_eq!(
        artifact_matches("main", &"b".repeat(64), &"b".repeat(64)),
        false,
        "case 2"
    );
    assert_eq!(
        artifact_matches(
            &"a".repeat(40),
            &"b".repeat(64),
            &"c".repeat(64)
        ),
        false,
        "case 3"
    );
    assert_eq!(
        artifact_matches(
            &"A".repeat(40),
            &"b".repeat(64),
            &"b".repeat(64)
        ),
        false,
        "case 4"
    );
    assert_eq!(
        artifact_matches(&"a".repeat(40), "", ""),
        false,
        "case 5"
    );
    println!("worked example passed");
}

The worked implementation exercises verify release identity and digest metadata. Its tests demonstrate the stated finite contract.

Practice starter

pub fn artifact_matches(commit: &str, digest: &str, expected: &str) -> bool {
    todo!("implement the contract")
}

Open local example in Playground ↗

Try it

Validate lowercase hexadecimal commit(40) and digest/expected(64), then require digest==expected. This checks metadata only; actual digest computation belongs to the supplied build-byte verification step. Keep the public signature. Open the compiler lab and edit solution.rs; do not edit the private verification caller.

What success looks like: The separate caller accepts the changed solution and rejects unchanged TODO, a wrong implementation and a printed success message.

Check your understanding

Does a well-formed SHA-256 string prove the artifact bytes match?

Reveal the answer
  1. No, compute and compare the actual bytes against a trusted expected digest
  2. Yes, every 64-character value proves integrity
  3. A checksum automatically identifies the publisher

String shape, byte integrity and publisher authenticity are different properties.

Go deeper

Common misconception: Yes, every 64-character value proves integrity

A filename or version label does not prove which bytes were tested.

  1. Identify the boundary: Verify release identity and digest metadata. Write down its accepted inputs and observable output.
  2. Exercise the failure: String shape, byte integrity and publisher authenticity are different properties.
  3. Check the independent caller: Validate lowercase hexadecimal commit(40) and digest/expected(64), then require digest==expected. This checks metadata only; actual digest computation belongs to the supplied build-byte verification step.

Transfer challenge: Apply this contract to Task Ledger, introduce the failure described in the lesson, and show the failing check before fixing it.

Connections

  • Validate Before Starting the Service: Reject invalid deployment configuration
  • Release, Observe and Recover: Keep a known-good version until the candidate is healthy