Execution receipts: the receipt object and attestation fc1a466a1e66

//! Execution receipts (spec §14.6): what a runner ran, in what, on which

//! inputs and with what result. A receipt names no state, so the same

//! receipt serves every state whose scope is unchanged; an attestation of

//! kind `receipt`, signed by the runner, binds it to the state it ran on.

use crate::attest::{Attest, AttestBody};

use crate::cbor::{self, Value};

use crate::hash::{hash_object, ObjectRef, ObjectType};

use crate::identity::{verify, Domain, Identity, SecretKey, Signature};

use crate::objects::{array, bytes, check_version, field, map, oref, text, uint, Hlc, ObjectError};

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct Receipt {

    pub job_name: String,

    /// The pipeline definition the job came from.

    pub pipeline_hash: ObjectRef,

    /// BLAKE3 over the sorted (path, content) of the files the job's scope

    /// matches; the whole tree when it has no scope.

    pub scope_tree_hash: ObjectRef,

    /// Artifacts and other inputs consumed beyond the tree.

    pub inputs: Vec<ObjectRef>,

    /// What the job ran in: isolation tier, rootfs, argv and environment.

    pub environment: ObjectRef,

    /// Blobs the job produced.

    pub outputs: Vec<ObjectRef>,

    pub exit_code: u32,

    pub duration_ms: u64,

}

fn refs(v: &[ObjectRef]) -> Value {

    Value::Array(v.iter().map(|h| Value::Bytes(h.0.to_vec())).collect())

}

fn refs_from(v: &Value, what: &str) -> Result<Vec<ObjectRef>, ObjectError> {

    array(v, what)?.iter().map(|h| oref(h, what)).collect()

}

impl Receipt {

    pub fn passed(&self) -> bool {

        self.exit_code == 0

    }

    pub fn to_value(&self) -> Value {

        Value::map([

            (0, Value::Uint(1)),

            (1, Value::Text(self.job_name.clone())),

            (2, Value::Bytes(self.pipeline_hash.0.to_vec())),

            (3, Value::Bytes(self.scope_tree_hash.0.to_vec())),

            (4, refs(&self.inputs)),

            (5, Value::Bytes(self.environment.0.to_vec())),

            (6, refs(&self.outputs)),

            (7, Value::Uint(self.exit_code as u64)),

            (8, Value::Uint(self.duration_ms)),

        ])

    }

    pub fn encode(&self) -> Vec<u8> {

        cbor::encode(&self.to_value())

    }

    pub fn hash(&self) -> ObjectRef {

        hash_object(ObjectType::Receipt, &self.encode())

    }

    pub fn decode(b: &[u8]) -> Result<Receipt, ObjectError> {

        let v = cbor::decode(b)?;

        let m = map(&v, "receipt")?;

        check_version(m)?;

        let exit_code = uint(field(m, 7, "exit_code")?, "exit_code")?;

        Ok(Receipt {

            job_name: text(field(m, 1, "job_name")?, "job_name")?.to_owned(),

            pipeline_hash: oref(field(m, 2, "pipeline_hash")?, "pipeline_hash")?,

            scope_tree_hash: oref(field(m, 3, "scope_tree_hash")?, "scope_tree_hash")?,

            inputs: refs_from(field(m, 4, "inputs")?, "inputs")?,

            environment: oref(field(m, 5, "environment")?, "environment")?,

            outputs: refs_from(field(m, 6, "outputs")?, "outputs")?,

            exit_code: u32::try_from(exit_code)

                .map_err(|_| ObjectError::Schema("exit_code: expected u32".into()))?,

            duration_ms: uint(field(m, 8, "duration_ms")?, "duration_ms")?,

        })

    }

}

#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]

pub enum ReceiptError {

    #[error("the attestation is not of kind receipt")]

    NotReceipt,

    #[error("the attestation names a different receipt")]

    WrongReceipt,

    #[error("no signature by the runner {0}")]

    Unsigned(String),

    #[error("the runner's signature does not verify: {0}")]

    BadSignature(String),

    #[error("{0}")]

    Schema(String),

}

impl From<ObjectError> for ReceiptError {

    fn from(e: ObjectError) -> Self {

        ReceiptError::Schema(e.to_string())

    }

}

/// A receipt as a runner hands it over: the receipt, the attestation

/// binding it to a state, the runner's signature over that attestation, and

/// the runner's identity, so it verifies with nothing else.

#[derive(Clone, Debug, PartialEq, Eq)]

pub struct SignedReceipt {

    pub receipt: Receipt,

    pub attest: Attest,

    pub sigs: Vec<Signature>,

    pub runner: Identity,

}

impl SignedReceipt {

    /// Bind `receipt` to `state` of repository `repo` for run `run` (a URL

    /// or other name of the run), signed by `runner` with `sk`.

    pub fn sign(

        receipt: Receipt,

        repo: [u8; 16],

        state: ObjectRef,

        run: &str,

        runner: &Identity,

        sk: &SecretKey,

    ) -> SignedReceipt {

        let attest = Attest {

            repo,

            hlc: Hlc::now(),

            body: AttestBody::Receipt {

                receipt: receipt.hash(),

                state,

                run: run.into(),

            },

        };

        let sig = sk.sign(Domain::Attest, &runner.hash(), &attest.hash());

        SignedReceipt {

            receipt,

            attest,

            sigs: vec![sig],

            runner: runner.clone(),

        }

    }

    /// The state the receipt was made on.

    pub fn state(&self) -> ObjectRef {

        match &self.attest.body {

            AttestBody::Receipt { state, .. } => *state,

            _ => ObjectRef([0; 32]),

        }

    }

    pub fn run(&self) -> &str {

        match &self.attest.body {

            AttestBody::Receipt { run, .. } => run,

            _ => "",

        }

    }

    /// The attestation is a receipt attestation for this receipt, and the

    /// runner signed it. Whether to trust the runner is the reader's call.

    pub fn verify(&self) -> Result<(), ReceiptError> {

        let AttestBody::Receipt { receipt, .. } = &self.attest.body else {

            return Err(ReceiptError::NotReceipt);

        };

        if *receipt != self.receipt.hash() {

            return Err(ReceiptError::WrongReceipt);

        }

        let key = self.runner.hash();

        let target = self.attest.hash();

        let sig = self

            .sigs

            .iter()

            .find(|s| s.key == key)

            .ok_or_else(|| ReceiptError::Unsigned(key.short(12)))?;

        verify(&self.runner, sig, Domain::Attest, &target)

            .map_err(|e| ReceiptError::BadSignature(e.to_string()))

    }

    /// `[receipt, attest, [Signature], identity]`, each object as its bytes.

    pub fn encode(&self) -> Vec<u8> {

        cbor::encode(&Value::Array(vec![

            Value::Bytes(self.receipt.encode()),

            Value::Bytes(self.attest.encode()),

            Value::Array(self.sigs.iter().map(|s| s.to_value()).collect()),

            Value::Bytes(self.runner.encode()),

        ]))

    }

    pub fn decode(b: &[u8]) -> Result<SignedReceipt, ReceiptError> {

        let v = cbor::decode(b).map_err(ObjectError::from)?;

        let a = array(&v, "signed receipt")?;

        if a.len() != 4 {

            return Err(ReceiptError::Schema(

                "signed receipt: expected [receipt, attest, sigs, identity]".into(),

            ));

        }

        Ok(SignedReceipt {

            receipt: Receipt::decode(bytes(&a[0], "receipt")?)?,

            attest: Attest::decode(bytes(&a[1], "attest")?)?,

            sigs: array(&a[2], "sigs")?

                .iter()

                .map(Signature::from_value)

                .collect::<Result<_, _>>()?,

            runner: Identity::decode(bytes(&a[3], "identity")?)?,

        })

    }

}

#[cfg(test)]

mod tests {

    use super::*;

    pub(crate) fn sample() -> Receipt {

        Receipt {

            job_name: "test".into(),

            pipeline_hash: ObjectRef([1; 32]),

            scope_tree_hash: ObjectRef([2; 32]),

            inputs: vec![],

            environment: ObjectRef([3; 32]),

            outputs: vec![ObjectRef([4; 32])],

            exit_code: 0,

            duration_ms: 1500,

        }

    }

    #[test]

    fn receipts_round_trip_and_hash_as_receipt_objects() {

        let r = sample();

        assert_eq!(Receipt::decode(&r.encode()).unwrap(), r);

        let mut h = blake3::Hasher::new();

        h.update(format!("oxy1 receipt {}\0", r.encode().len()).as_bytes());

        h.update(&r.encode());

        assert_eq!(

            r.hash().0,

            *h.finalize().as_bytes(),

            "OxygenFlow's receipt hash"

        );

        assert!(r.passed());

    }

    #[test]

    fn a_signed_receipt_verifies_and_tampering_does_not() {

        let sk = SecretKey::generate();

        let runner = sk.identity("earth-1", "runner@earth", 1);

        let sr = SignedReceipt::sign(

            sample(),

            [7; 16],

            ObjectRef([9; 32]),

            "andy/demo#3",

            &runner,

            &sk,

        );

        sr.verify().unwrap();

        let back = SignedReceipt::decode(&sr.encode()).unwrap();

        assert_eq!(back, sr);

        assert_eq!(back.state(), ObjectRef([9; 32]));

        assert_eq!(back.run(), "andy/demo#3");

        let mut forged = sr.clone();

        forged.receipt.exit_code = 0;

        forged.receipt.duration_ms = 1;

        assert_eq!(forged.verify(), Err(ReceiptError::WrongReceipt));

        let mut moved = sr.clone();

        if let AttestBody::Receipt { state, .. } = &mut moved.attest.body {

            *state = ObjectRef([8; 32]);

        }

        assert!(matches!(moved.verify(), Err(ReceiptError::BadSignature(_))));

        let other = SecretKey::generate().identity("mallory", "m@x", 1);

        let mut swapped = sr.clone();

        swapped.runner = other;

        assert!(matches!(swapped.verify(), Err(ReceiptError::Unsigned(_))));

    }

}

//! Execution receipts in a repository (spec §14.6): kept beside the state

//! they were made on, with the runner's identity and signature.

use super::*;

use crate::receipt::SignedReceipt;

/// A stored receipt and what verifying it found.

#[derive(Clone, Debug)]

pub struct ReceiptInfo {

    /// The receipt attestation's ObjectRef, which names it.

    pub attest: ObjectRef,

    pub signed: SignedReceipt,

    /// Why it does not verify, if it does not.

    pub problem: Option<String>,

    /// The runner's key was revoked (spec §14.2).

    pub revoked: bool,

}

impl Repo {

    /// Verify `sr` and keep it: the receipt, the attestation with its

    /// signatures, and the runner's identity. Returns the attestation's

    /// ObjectRef. Receipts for another repository are refused.

    pub fn add_receipt(&self, sr: &SignedReceipt) -> Result<ObjectRef> {

        sr.verify()

            .map_err(|e| RepoError::Msg(format!("receipt does not verify: {e}")))?;

        if sr.attest.repo != self.id()? {

            return fail("that receipt is for another repository");

        }

        self.store.put_identity(&sr.runner)?;

        self.store.put_receipt(&sr.receipt)?;

        let r = self.store.put_attest(&sr.attest)?;

        for sig in &sr.sigs {

            self.store.put_signature(&r, sig)?;

        }

        self.store.index_receipt(&sr.state(), &r)?;

        Ok(r)

    }

    /// The receipt named by attestation `r`, verified again from the store.

    pub fn receipt(&self, r: &ObjectRef) -> Result<ReceiptInfo> {

        let attest = self.store.get_attest(r)?;

        let AttestBody::Receipt { receipt, .. } = &attest.body else {

            return fail(format!("#{} is not a receipt", r.short(12)));

        };

        let receipt = self.store.get_receipt(receipt)?;

        let sigs = self.store.signatures(r)?;

        let Some(key) = sigs.first().map(|s| s.key) else {

            return fail(format!("receipt #{} has no signature", r.short(12)));

        };

        let runner = self.store.get_identity(&key)?;

        let signed = SignedReceipt {

            receipt,

            attest,

            sigs,

            runner,

        };

        let problem = signed.verify().err().map(|e| e.to_string());

        Ok(ReceiptInfo {

            attest: *r,

            revoked: self.is_revoked(&key)?,

            signed,

            problem,

        })

    }

    /// Every receipt kept for the state of `heads`, oldest first.

    pub fn receipts(&self, heads: &[ChangeHash]) -> Result<Vec<ReceiptInfo>> {

        let state = hash_object(

            ObjectType::State,

            &StateObject::new(heads.to_vec()).encode(),

        );

        let mut out = self

            .store

            .receipts_for(&state)?

            .iter()

            .map(|r| self.receipt(r))

            .collect::<Result<Vec<_>>>()?;

        out.sort_by_key(|i| i.signed.attest.hlc);

        Ok(out)

    }

    /// Receipts to keep through garbage collection: those whose state's

    /// heads `keep` holds, with their receipts, runners and outputs.

    pub(crate) fn reachable_receipts(&self, keep: &mut HashSet<ObjectRef>) -> Result<()> {

        for state in self.store.receipt_states()? {

            let heads = match self.store.get_state(&state) {

                Ok(s) => s.heads,

                // A receipt may arrive before its state object; its heads

                // are unknown, so keep it.

                Err(StoreError::NotFound(_)) => vec![],

                Err(e) => return Err(e.into()),

            };

            if !heads.iter().all(|h| keep.contains(h)) {

                continue;

            }

            keep.insert(state);

            for a in self.store.receipts_for(&state)? {

                keep.insert(a);

                for sig in self.store.signatures(&a)? {

                    keep.insert(sig.key);

                }

                let Ok(attest) = self.store.get_attest(&a) else {

                    continue;

                };

                let AttestBody::Receipt { receipt, .. } = attest.body else {

                    continue;

                };

                keep.insert(receipt);

                let Ok(r) = self.store.get_receipt(&receipt) else {

                    continue;

                };

                for b in r.outputs.iter().chain(&r.inputs) {

                    if keep.insert(*b) {

                        if let Ok(bytes) = self.store.get_typed(b, ObjectType::Blob) {

                            keep.extend(Blob::decode(&bytes)?.chunks);

                        }

                    }

                }

            }

        }

        Ok(())

    }

}

//! Execution receipts (spec §14.6): list, show, verify and import the

//! signed receipts runners make.

use super::json;

use super::open;

use super::ui;

use anyhow::{bail, Result};

use oxy_core::receipt::SignedReceipt;

use oxy_core::repo::ReceiptInfo;

fn status(problem: Option<&str>, revoked: bool) -> String {

    match (problem, revoked) {

        (Some(p), _) => ui::err(format!("{} {p}", ui::glyph("✘", "x"))),

        (None, true) => ui::warn(format!("{} runner key revoked", ui::glyph("!", "!"))),

        (None, false) => ui::ok(format!("{} signed", ui::glyph("✔", "v"))),

    }

}

fn line(sr: &SignedReceipt, problem: Option<&str>, revoked: bool) -> String {

    let r = &sr.receipt;

    let result = if r.passed() {

        ui::ok(format!("{} passed", ui::glyph("●", "*")))

    } else {

        ui::err(format!("{} exit {}", ui::glyph("●", "*"), r.exit_code))

    };

    format!(

        "{} {}{}{}{}{}",

        result,

        ui::subject(&r.job_name),

        ui::sep() + &ui::dim(format!("{:.1} s", r.duration_ms as f64 / 1000.0)),

        ui::sep() + &ui::author(&sr.runner.name),

        ui::sep() + &status(problem, revoked),

        ui::sep() + &ui::dim(ui::ago(sr.attest.hlc.wall_ms)),

    )

}

fn to_json(

    attest: Option<String>,

    sr: &SignedReceipt,

    problem: Option<&str>,

    revoked: bool,

) -> String {

    let r = &sr.receipt;

    let refs = |v: &[oxy_core::hash::ObjectRef]| json::arr(v.iter().map(|h| json::s(&h.to_hex())));

    json::obj([

        ("attest", json::opt(attest.as_ref(), |a| json::s(a))),

        ("receipt", json::s(&r.hash().to_hex())),

        ("state", json::s(&sr.state().to_hex())),

        ("run", json::s(sr.run())),

        ("job", json::s(&r.job_name)),

        ("exit_code", json::n(r.exit_code)),

        ("duration_ms", json::n(r.duration_ms)),

        ("pipeline", json::s(&r.pipeline_hash.to_hex())),

        ("scope", json::s(&r.scope_tree_hash.to_hex())),

        ("environment", json::s(&r.environment.to_hex())),

        ("inputs", refs(&r.inputs)),

        ("outputs", refs(&r.outputs)),

        ("runner", json::s(&sr.runner.hash().to_hex())),

        ("runner_name", json::s(&sr.runner.name)),

        ("made_ms", json::n(sr.attest.hlc.wall_ms)),

        ("valid", json::b(problem.is_none())),

        ("problem", json::opt(problem, json::s)),

        ("revoked", json::b(revoked)),

    ])

}

fn detail(sr: &SignedReceipt, problem: Option<&str>, revoked: bool) {

    let r = &sr.receipt;

    println!("{}", line(sr, problem, revoked));

    println!(

        "{}",

        ui::kv("run", if sr.run().is_empty() { "-" } else { sr.run() })

    );

    println!(

        "{}",

        ui::kv("state", ui::hash(format!("#{}", sr.state().short(12))))

    );

    println!(

        "{}",

        ui::kv("receipt", ui::hash(format!("#{}", r.hash().short(12))))

    );

    println!(

        "{}",

        ui::kv("pipeline", ui::hash(r.pipeline_hash.short(12)))

    );

    println!("{}", ui::kv("scope", ui::hash(r.scope_tree_hash.short(12))));

    println!(

        "{}",

        ui::kv("environment", ui::hash(r.environment.short(12)))

    );

    println!(

        "{}",

        ui::kv(

            "runner",

            format!("{} {}", sr.runner.name, ui::dim(sr.runner.hash().short(12)))

        )

    );

    for (what, v) in [("input", &r.inputs), ("output", &r.outputs)] {

        for h in v.iter() {

            println!("{}", ui::kv(what, ui::hash(h.short(12))));

        }

    }

}

/// `oxy receipt list [REV]`: the receipts kept for a state.

pub fn list(rev: Option<&str>, as_json: bool) -> Result<i32> {

    let repo = open()?;

    let heads = match rev {

        Some(r) => repo.resolve_heads(r)?,

        None => repo.bookmark_heads()?,

    };

    let found = repo.receipts(&heads)?;

    if as_json {

        println!(

            "{}",

            json::arr(found.iter().map(|i| to_json(

                Some(i.attest.to_hex()),

                &i.signed,

                i.problem.as_deref(),

                i.revoked

            )))

        );

        return Ok(0);

    }

    if found.is_empty() {

        println!("{}", ui::dim("No receipts for this state."));

    }

    for i in &found {

        println!(

            "{} {}",

            ui::hash(format!("#{}", i.attest.short(12))),

            line(&i.signed, i.problem.as_deref(), i.revoked)

        );

    }

    Ok(0)

}

fn find(repo: &oxy_core::repo::Repo, prefix: &str, rev: Option<&str>) -> Result<ReceiptInfo> {

    let heads = match rev {

        Some(r) => repo.resolve_heads(r)?,

        None => repo.bookmark_heads()?,

    };

    let p = prefix.trim_start_matches('#').to_ascii_lowercase();

    let mut hits: Vec<ReceiptInfo> = repo

        .receipts(&heads)?

        .into_iter()

        .filter(|i| i.attest.to_hex().starts_with(&p))

        .collect();

    match hits.len() {

        1 => Ok(hits.remove(0)),

        0 => bail!("no receipt #{p} for this state; `oxy receipt list` shows them"),

        n => bail!("#{p} matches {n} receipts; give more of the hash"),

    }

}

/// `oxy receipt show HASH [--rev REV]`.

pub fn show(prefix: &str, rev: Option<&str>, as_json: bool) -> Result<i32> {

    let repo = open()?;

    let i = find(&repo, prefix, rev)?;

    if as_json {

        println!(

            "{}",

            to_json(

                Some(i.attest.to_hex()),

                &i.signed,

                i.problem.as_deref(),

                i.revoked

            )

        );

    } else {

        detail(&i.signed, i.problem.as_deref(), i.revoked);

    }

    Ok(if i.problem.is_some() { 1 } else { 0 })

}

/// `oxy receipt export HASH FILE`: the signed receipt, to hand to anyone.

pub fn export(prefix: &str, file: &str, rev: Option<&str>) -> Result<i32> {

    let repo = open()?;

    let i = find(&repo, prefix, rev)?;

    std::fs::write(file, i.signed.encode())?;

    println!(

        "{} {} {}",

        ui::done("Exported receipt"),

        ui::hash(format!("#{}", i.attest.short(12))),

        ui::path(file)

    );

    Ok(0)

}

fn read(file: &str) -> Result<SignedReceipt> {

    let bytes = std::fs::read(file).map_err(|e| anyhow::anyhow!("{file}: {e}"))?;

    SignedReceipt::decode(&bytes).map_err(|e| anyhow::anyhow!("{file}: not a signed receipt: {e}"))

}

/// `oxy receipt verify FILE`: check a signed receipt without keeping it.

pub fn verify(file: &str, as_json: bool) -> Result<i32> {

    let sr = read(file)?;

    let problem = sr.verify().err().map(|e| e.to_string());

    if as_json {

        println!("{}", to_json(None, &sr, problem.as_deref(), false));

    } else {

        detail(&sr, problem.as_deref(), false);

    }

    Ok(if problem.is_some() { 1 } else { 0 })

}

/// `oxy receipt import FILE`: verify a signed receipt and keep it.

pub fn import(file: &str) -> Result<i32> {

    let repo = open()?;

    let sr = read(file)?;

    let r = repo.add_receipt(&sr)?;

    println!(

        "{} {} {} {} {}",

        ui::done("Kept receipt"),

        ui::hash(format!("#{}", r.short(12))),

        ui::subject(&sr.receipt.job_name),

        ui::dim("by"),

        ui::author(&sr.runner.name)

    );

    Ok(0)

}

//! of changes, and runs (receipts, §14.6).

    /// A runner ran the job of `receipt` on `state` (spec §14.6); `run`

    /// names the run, usually by URL.

    Receipt {

        receipt: ObjectRef,

        state: ObjectRef,

        run: String,

    },

            AttestBody::Receipt { .. } => "receipt",

            ]),

            AttestBody::Receipt {

                receipt,

                state,

                run,

            } => Value::map([

                (0, Value::Bytes(receipt.0.to_vec())),

                (1, Value::Bytes(state.0.to_vec())),

                (2, Value::Text(run.clone())),

            },

            "receipt" => AttestBody::Receipt {

                receipt: oref(field(b, 0, "receipt")?, "receipt")?,

                state: oref(field(b, 1, "state")?, "state")?,

                run: text(field(b, 2, "run")?, "run")?.to_owned(),

    Receipt,

    pub const ALL: [ObjectType; 10] = [

        ObjectType::Receipt,

            ObjectType::Receipt => "receipt",

pub mod receipt;

        ObjectType::Receipt => crate::receipt::Receipt::decode(body).map(|_| ()),

//! `core.op-retention`, reference attestations, and the policy; receipts

//! live as long as the changes of their state. Operation

        self.reachable_receipts(&mut keep)?;

mod receipts;

pub use receipts::ReceiptInfo;

#[test]

fn receipts_are_kept_with_their_state_and_verified() {

    use crate::receipt::{Receipt, SignedReceipt};

    hermetic();

    let dir = tempfile::tempdir().unwrap();

    let root = dir.path();

    let repo = Repo::init(root).unwrap().with_home(root.join("home"));

    write(root, "a.txt", b"1\n");

    repo.commit("A", &[]).unwrap();

    let heads = repo.bookmark_heads().unwrap();

    let state = repo

        .store()

        .put_state(&StateObject::new(heads.clone()))

        .unwrap();

    let out = repo.store_blob(b"built\n").unwrap();

    let receipt = Receipt {

        job_name: "build".into(),

        pipeline_hash: ObjectRef([1; 32]),

        scope_tree_hash: ObjectRef([2; 32]),

        inputs: vec![],

        environment: ObjectRef([3; 32]),

        outputs: vec![out],

        exit_code: 0,

        duration_ms: 42,

    };

    let sk = SecretKey::generate();

    let runner = sk.identity("earth-1", "runner@earth", 1);

    let sr = SignedReceipt::sign(

        receipt.clone(),

        repo.id().unwrap(),

        state,

        "demo#1",

        &runner,

        &sk,

    );

    let r = repo.add_receipt(&sr).unwrap();

    let found = repo.receipts(&heads).unwrap();

    assert_eq!(found.len(), 1);

    assert_eq!(found[0].attest, r);

    assert_eq!(found[0].signed, sr);

    assert!(found[0].problem.is_none() && !found[0].revoked);

    assert!(repo.receipts(&[ObjectRef([5; 32])]).unwrap().is_empty());

    // Another repository's receipt, or a forged one, is refused.

    let elsewhere = SignedReceipt::sign(receipt.clone(), [0; 16], state, "x", &runner, &sk);

    assert!(repo

        .add_receipt(&elsewhere)

        .unwrap_err()

        .to_string()

        .contains("another repository"));

    let mut forged = sr.clone();

    forged.receipt.exit_code = 1;

    assert!(repo

        .add_receipt(&forged)

        .unwrap_err()

        .to_string()

        .contains("does not verify"));

    // gc keeps the receipt, its runner and its output while the state lives.

    repo.gc(true).unwrap();

    assert_eq!(repo.receipts(&heads).unwrap().len(), 1);

    assert_eq!(repo.read_blob(&out).unwrap(), b"built\n");

    assert!(repo.fsck().unwrap().problems.is_empty());

}

use crate::receipt::Receipt;

        let sidecars = [

            self.sig_path(r),

            self.index_path("seals", r),

            self.index_path("receipts", r),

        ];

        for path in sidecars {

    }

    pub fn put_receipt(&self, r: &Receipt) -> Result<ObjectRef> {

        self.put(ObjectType::Receipt, &r.encode())

    pub fn get_receipt(&self, r: &ObjectRef) -> Result<Receipt> {

        Ok(Receipt::decode(&self.get_typed(r, ObjectType::Receipt)?)?)

    fn index_path(&self, index: &str, key: &ObjectRef) -> PathBuf {

        let h = key.to_hex();

        self.dir.join(index).join(&h[..2]).join(&h[2..])

    }

    /// Add `value` to the sorted list kept for `key` in `index`.

    fn index_add(&self, index: &str, key: &ObjectRef, value: &ObjectRef) -> Result<()> {

        let mut values = self.index_get(index, key)?;

        if values.contains(value) {

        values.push(*value);

        values.sort();

        let path = self.index_path(index, key);

        let text: String = values.iter().map(|s| format!("{}\n", s.to_hex())).collect();

    fn index_get(&self, index: &str, key: &ObjectRef) -> Result<Vec<ObjectRef>> {

        match fs::read_to_string(self.index_path(index, key)) {

    }

    /// Record that seal attestation `attest` covers `change`.

    pub fn index_seal(&self, change: &ObjectRef, attest: &ObjectRef) -> Result<()> {

        self.index_add("seals", change, attest)

    }

    /// Seal attestations known to cover `change`.

    pub fn seals_for(&self, change: &ObjectRef) -> Result<Vec<ObjectRef>> {

        self.index_get("seals", change)

    }

    /// Record receipt attestation `attest` for `state` (spec §14.6).

    pub fn index_receipt(&self, state: &ObjectRef, attest: &ObjectRef) -> Result<()> {

        self.index_add("receipts", state, attest)

    }

    /// Receipt attestations recorded for `state`.

    pub fn receipts_for(&self, state: &ObjectRef) -> Result<Vec<ObjectRef>> {

        self.index_get("receipts", state)

    }

    /// Every state with a receipt, for garbage collection.

    pub fn receipt_states(&self) -> Result<Vec<ObjectRef>> {

        let mut out = Vec::new();

        let dir = self.dir.join("receipts");

        let top = match fs::read_dir(&dir) {

            Ok(d) => d,

            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(out),

            Err(e) => return Err(e.into()),

        };

        for d in top {

            let d = d?;

            let prefix = d.file_name().to_string_lossy().into_owned();

            for f in fs::read_dir(d.path())? {

                let name = f?.file_name().to_string_lossy().into_owned();

                if let Some(r) = ObjectRef::from_hex(&format!("{prefix}{name}")) {

                    out.push(r);

                }

            }

        }

        out.sort();

        Ok(out)

- [x] P1 **Conflict resolution on OxygenHub** (Andy's list, item 1). A resolver page for a conflicted state:

- [x] P3 **Swimlanes** (item 3):

- [ ] P4a The `receipt` object and attestation in the Oxygen spec and oxy-core: a signed receipt verifies on its own; the repository keeps receipts by state; `oxy receipt list|show|export|verify|import` (first part of P4, below).

- [ ] P4c The runner signs each receipt with its own identity; the hub verifies it against its known runner keys, keeps it in the repository, and shows it on the run, the check and the change.

- [ ] P4d Flow `output` and artifacts: a job's declared outputs become blobs named by its receipt, and a release asset links to the receipt that built it.

### Receipts from CI

A runner such as OxygenFlow signs a receipt for every job it runs: what ran,

in what environment, on which files, and the result. Receipts are kept with

the state they ran on.

```

oxy receipt list                         # receipts for the bookmark's state

oxy receipt show 3f2a9c                  # one in full, with its signature checked

oxy receipt export 3f2a9c build.receipt  # hand it to someone

oxy receipt verify build.receipt         # check one without keeping it

oxy receipt import build.receipt         # verify and keep it

```

| **Status** | Draft 0.8o |

| `receipt` | What a runner ran and its result. | §14.6 |

  kind    [1]: "ref" | "tag" | "seal" | "rotate" | "revoke" | "lock" | "receipt"

receipt: { receipt: ObjectRef, state: ObjectRef, run: text }   // §14.6

### 14.6 Execution receipts

A runner (OxygenFlow, or any CI) records each job it ran as a `receipt` object:

```

Receipt {

  version         [0]: 1

  job_name        [1]: text

  pipeline_hash   [2]: ObjectRef      // the pipeline definition the job came from

  scope_tree_hash [3]: ObjectRef      // BLAKE3 over the sorted (path, content) of the files the job's scope matches; the whole tree without a scope

  inputs          [4]: [ObjectRef]    // artifacts and other inputs beyond the tree

  environment     [5]: ObjectRef      // what it ran in: isolation tier, rootfs, argv, environment

  outputs         [6]: [ObjectRef]    // blobs the job produced

  exit_code       [7]: u32            // 0 passed

  duration_ms     [8]: u64

}

```

A receipt names no state: the same job on the same scope in the same environment gives the same receipt, which is what lets a runner reuse it for a later state whose scope is unchanged. An attestation of kind `receipt` (§14.4) binds a receipt to the `state` it ran on and names the `run` (usually its URL). The runner signs that attestation with its own identity (§14.2), an ordinary composite key, in domain `attest`.

**Signed receipt.** A runner hands a receipt over as `[receipt bytes, attest bytes, [Signature], identity bytes]`, so it verifies with nothing else: the attestation's `receipt` is the receipt's ObjectRef, and a signature by the included identity verifies over the attestation. Whether a runner is trusted is the reader's decision (a host lists its runners' keys); a revoked runner key is reported.

**Storage.** A repository keeps receipts beside the state they name: the receipt, the attestation with its signatures, and the runner's identity, indexed by state ObjectRef. Receipts live as long as the changes of their state, and keep their outputs and inputs alive (§21). `oxy receipt list|show|export|verify|import` reads and exchanges them; a receipt for another repository is refused.

*Changelog.* Draft 0.8o (2026-09-29): execution receipts, the `receipt` object and attestation (§14.6). Draft 0.8n (2026-09-29): line history, `oxy log -L` (§27). Draft 0.8m (2026-09-29): resolving replace conflicts (§9.3). Draft 0.8l (2026-09-28): deleting a reference on a remote; first serials from the clock (§16.4). Draft 0.8k (2026-09-28): the manifest records graph keys, so unchanged files are neither read nor rendered (§12.4). Draft 0.8j (2026-09-28): checkpoint payload version 2, file graphs by reference (§11).

mod receipt;

    /// Execution receipts: signed records of what a runner ran on a state

    Receipt {

        #[command(subcommand)]

        cmd: ReceiptCmd,

    },

enum ReceiptCmd {

    /// The receipts kept for a state (default: the bookmark heads)

    List {

        /// Change, bookmark or tag whose state to look at

        rev: Option<String>,

        /// Machine-readable output: one JSON document on stdout

        #[arg(long)]

        json: bool,

    },

    /// One receipt in full, and whether its signature verifies

    Show {

        /// The receipt (a prefix of its hash, as `list` shows it)

        receipt: String,

        /// Change, bookmark or tag whose state holds it

        #[arg(long)]

        rev: Option<String>,

        /// Machine-readable output: one JSON document on stdout

        #[arg(long)]

        json: bool,

    },

    /// Write a signed receipt to FILE

    Export {

        /// The receipt (a prefix of its hash, as `list` shows it)

        receipt: String,

        /// Where to write it

        file: String,

        /// Change, bookmark or tag whose state holds it

        #[arg(long)]

        rev: Option<String>,

    },

    /// Check a signed receipt in FILE without keeping it

    Verify {

        /// A signed receipt, as a runner or `export` writes it

        file: String,

        /// Machine-readable output: one JSON document on stdout

        #[arg(long)]

        json: bool,

    },

    /// Verify a signed receipt in FILE and keep it with its state

    Import {

        /// A signed receipt, as a runner or `export` writes it

        file: String,

    },

}

#[derive(Subcommand)]

        },

        Cmd::Receipt { cmd } => match cmd {

            ReceiptCmd::List { rev, json } => receipt::list(rev.as_deref(), json),

            ReceiptCmd::Show {

                receipt: r,

                rev,

                json,

            } => receipt::show(&r, rev.as_deref(), json),

            ReceiptCmd::Export {

                receipt: r,

                file,

                rev,

            } => receipt::export(&r, &file, rev.as_deref()),

            ReceiptCmd::Verify { file, json } => receipt::verify(&file, json),

            ReceiptCmd::Import { file } => receipt::import(&file),

#[test]

fn receipts_verify_import_list_show_and_export() {

    use oxy_core::hash::{ObjectRef, ObjectType};

    use oxy_core::identity::SecretKey;

    use oxy_core::objects::StateObject;

    use oxy_core::receipt::{Receipt, SignedReceipt};

    let tmp = tempfile::tempdir().unwrap();

    let home = tmp.path().join("home");

    std::fs::create_dir_all(&home).unwrap();

    let r = tmp.path().join("repo");

    assert_eq!(oxy(tmp.path(), &home, &["init", r.to_str().unwrap()]).0, 0);

    write(&r, "a.txt", "a\n");

    assert_eq!(oxy(&r, &home, &["commit", "-m", "A"]).0, 0);

    let repo = oxy_core::repo::Repo::open(&r).unwrap();

    let heads = repo.bookmark_heads().unwrap();

    let state = oxy_core::hash::hash_object(ObjectType::State, &StateObject::new(heads).encode());

    let receipt = Receipt {

        job_name: "test".into(),

        pipeline_hash: ObjectRef([1; 32]),

        scope_tree_hash: ObjectRef([2; 32]),

        inputs: vec![],

        environment: ObjectRef([3; 32]),

        outputs: vec![],

        exit_code: 0,

        duration_ms: 2500,

    };

    let sk = SecretKey::generate();

    let runner = sk.identity("earth-1", "runner@earth", 1);

    let sr = SignedReceipt::sign(receipt, repo.id().unwrap(), state, "demo#7", &runner, &sk);

    let file = tmp.path().join("r.receipt");

    std::fs::write(&file, sr.encode()).unwrap();

    let f = file.to_str().unwrap();

    let v = json(&r, &home, &["receipt", "verify", f, "--json"]);

    assert_eq!(

        (v["valid"].as_bool(), v["job"].as_str(), v["run"].as_str()),

        (Some(true), Some("test"), Some("demo#7"))

    );

    assert!(v["attest"].is_null());

    assert!(json(&r, &home, &["receipt", "list", "--json"])

        .as_array()

        .unwrap()

        .is_empty());

    assert_eq!(oxy(&r, &home, &["receipt", "import", f]).0, 0);

    let list = json(&r, &home, &["receipt", "list", "--json"]);

    let list = list.as_array().unwrap();

    assert_eq!(list.len(), 1);

    assert_eq!(list[0]["runner_name"], "earth-1");

    assert_eq!(list[0]["state"], state.to_hex());

    let attest = list[0]["attest"].as_str().unwrap().to_string();

    let shown = json(&r, &home, &["receipt", "show", &attest[..10], "--json"]);

    assert_eq!(shown["duration_ms"], 2500);

    let out = tmp.path().join("out.receipt");

    assert_eq!(

        oxy(

            &r,

            &home,

            &["receipt", "export", &attest[..10], out.to_str().unwrap()]

        )

        .0,

        0

    );

    assert_eq!(std::fs::read(&out).unwrap(), sr.encode());

    // A receipt whose result was changed after signing does not verify.

    let mut forged = sr.clone();

    forged.receipt.exit_code = 3;

    std::fs::write(&file, forged.encode()).unwrap();

    let (code, out, _) = oxy(&r, &home, &["receipt", "verify", f]);

    assert_eq!(code, 1);

    assert!(String::from_utf8_lossy(&out).contains("different receipt"));

    let (code, _, err) = oxy(&r, &home, &["receipt", "import", f]);

    assert_ne!(code, 0);

    assert!(err.contains("does not verify"), "{err}");

}