Skip to main content

qualia_core_db/semantic_instruments/execution/
receipt.rs

1//! SI-06 instrument execution receipt.
2//!
3//! Distinct from the LLM decode `inference/runtime/receipt` type. Cold path.
4
5use crate::semantic_instruments::canonical::sha256_prefixed;
6
7/// Generic SI-06 runner identity. Dispatch is by entry point, not a Host ID.
8pub const GENERIC_RUNNER: &str = "si-generic-v0";
9
10/// Durable record of one employment: release, lock, runner, I/O commitments, outcome.
11#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
12pub struct ExecutionReceipt {
13    pub release_id: String,
14    pub content_digest: String,
15    pub lock_digest: String,
16    pub entry_point: String,
17    pub runner: String,
18    pub input_commitment: String,
19    pub output_commitment: String,
20    pub parent_receipt: Option<String>,
21    pub outcome: String,
22}
23
24impl ExecutionReceipt {
25    /// Bind a receipt to exact release, lock, entry point, and I/O bytes.
26    ///
27    /// `input_commitment` / `output_commitment` are `sha256:` digests of the
28    /// raw buffers. Restricted payloads stay out of the receipt body.
29    pub fn bind(
30        release_id: &str,
31        content_digest: &str,
32        lock_digest: &str,
33        entry_point: &str,
34        input: &[u8],
35        output: &[u8],
36        parent_receipt: Option<String>,
37        outcome: &str,
38    ) -> Self {
39        Self {
40            release_id: release_id.to_owned(),
41            content_digest: content_digest.to_owned(),
42            lock_digest: lock_digest.to_owned(),
43            entry_point: entry_point.to_owned(),
44            runner: GENERIC_RUNNER.to_owned(),
45            input_commitment: sha256_prefixed(input),
46            output_commitment: sha256_prefixed(output),
47            parent_receipt,
48            outcome: outcome.to_owned(),
49        }
50    }
51
52    /// Content-address of this receipt: `sha256:` of compact canonical JSON.
53    pub fn id(&self) -> String {
54        let bytes = serde_json::to_vec(self).expect("ExecutionReceipt JSON is infallible");
55        sha256_prefixed(&bytes)
56    }
57}
58
59#[cfg(test)]
60mod tests {
61    use super::*;
62
63    const RELEASE: &str = "https://ns.webizen.org/demo/unit-convert/releases/1.0.0";
64    const CONTENT: &str = "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa";
65    const LOCK: &str = "sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb";
66    const INPUT: &[u8] = b"{\"value\":1,\"unit\":\"m\"}";
67
68    fn bind_with(output: &[u8], parent: Option<String>, outcome: &str) -> ExecutionReceipt {
69        ExecutionReceipt::bind(
70            RELEASE, CONTENT, LOCK, "assess", INPUT, output, parent, outcome,
71        )
72    }
73
74    #[test]
75    fn same_inputs_same_id() {
76        let a = bind_with(b"ok", None, "completed");
77        let b = bind_with(b"ok", None, "completed");
78        assert_eq!(a, b);
79        assert_eq!(a.id(), b.id());
80        assert!(a.id().starts_with("sha256:"));
81        assert_eq!(a.id().len(), 7 + 64);
82        assert_eq!(a.runner, GENERIC_RUNNER);
83        assert_eq!(a.input_commitment, sha256_prefixed(INPUT));
84        assert_eq!(a.output_commitment, sha256_prefixed(b"ok"));
85    }
86
87    #[test]
88    fn parent_child_binds_parent_id() {
89        let parent = bind_with(b"first", None, "completed");
90        let child = bind_with(b"second", Some(parent.id()), "completed");
91        assert_eq!(child.parent_receipt.as_deref(), Some(parent.id().as_str()));
92        assert_ne!(child.id(), parent.id());
93    }
94
95    #[test]
96    fn changing_output_changes_commitment_and_id() {
97        let a = bind_with(b"alpha", None, "completed");
98        let b = bind_with(b"beta", None, "completed");
99        assert_ne!(a.output_commitment, b.output_commitment);
100        assert_eq!(a.input_commitment, b.input_commitment);
101        assert_ne!(a.id(), b.id());
102        assert_eq!(a.output_commitment, sha256_prefixed(b"alpha"));
103        assert_eq!(b.output_commitment, sha256_prefixed(b"beta"));
104    }
105}