Skip to main content

mimir_node_map/
proof.rs

1//! Stable proof identifiers. Legacy descriptions are read for diagnostics;
2//! unknown rules remain unaccepted. Readiness policy lives with the consumer.
3use super::*;
4use serde::{Deserialize, Serialize};
5
6/// Assumptions that a proof uses but cannot derive from the pinned image or tables.
7/// Unknown names fail deserialization; a missing compiler fact is never a premise.
8#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
9#[serde(rename_all = "kebab-case")]
10pub enum Premise {
11    CodeOrigin,
12    PointerCall,
13    ScopeAncestor,
14    ExecReach,
15    LineOrigin,
16    InlineCallOrigin,
17    TargetSetComplete,
18}
19
20impl Premise {
21    pub const ALL: &'static [Self] = &[
22        Self::CodeOrigin,
23        Self::PointerCall,
24        Self::ScopeAncestor,
25        Self::ExecReach,
26        Self::LineOrigin,
27        Self::InlineCallOrigin,
28        Self::TargetSetComplete,
29    ];
30
31    pub fn description(self) -> &'static str {
32        match self {
33            Self::TargetSetComplete => {
34                "the pinned image's vtable-set or escaped-function candidate enumeration is exhaustive for the call type, including the rule's type/ABI compatibility assumption; an empty set means the call never runs under this premise"
35            }
36            Self::CodeOrigin => {
37                "the code of a function is compiled from its own instances and their closure over exec.reached.calls"
38            }
39            Self::PointerCall => {
40                "a line-0 indirect transfer through a register or object slot, in a function where DWARF names a fitting pointer call, comes from a MIR pointer call"
41            }
42            Self::ScopeAncestor => {
43                "every scope on the DWARF chain at an address is an inlining ancestor of the instruction's MIR origin"
44            }
45            Self::ExecReach => {
46                "exec.reached bounds MIR-origin instances; excluding a linked body additionally needs machine-entry evidence and assumes data-held addresses do not hide a reached merged alias"
47            }
48            Self::InlineCallOrigin => {
49                "for hole elimination, a unique depth-one scope joined by exact call position and target identifies the call origin, with complete copy transfer coverage; for syscall assembly, one depth-one inline scope at the wrapper-variant position, one assembly terminator in the whole pinned body and compatible syscall numbers describe the MIR origin under the absent-wrapper-identity limit; no target join is available; missing scopes imply no absence"
50            }
51            Self::LineOrigin => {
52                "an instruction at a debug position under an instance's scope comes from a terminator of that instance at that position"
53            }
54        }
55    }
56}
57
58/// One use of a typed premise. Program-wide uses list boundary addresses;
59/// function/address premises name the narrower evidence location instead.
60#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
61pub struct PremiseUse {
62    pub name: Premise,
63    pub rule: String,
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub function: Option<u64>,
66    #[serde(default, skip_serializing_if = "Option::is_none")]
67    pub address: Option<u64>,
68    #[serde(default, skip_serializing_if = "Vec::is_empty")]
69    pub uses: Vec<u64>,
70}
71
72/// Premises from known proof rules, deduplicated in stable order.
73pub fn of_proofs<'a>(proofs: impl IntoIterator<Item = &'a str>) -> Vec<Premise> {
74    proofs
75        .into_iter()
76        .filter_map(ProofKind::parse)
77        .flat_map(ProofKind::premises)
78        .copied()
79        .collect::<std::collections::BTreeSet<_>>()
80        .into_iter()
81        .collect()
82}
83
84#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
85#[serde(rename_all = "kebab-case")]
86pub enum ProofKind {
87    SiteReport,
88    HoleReport,
89    KernelIpsAsm,
90    KernelIps,
91    KernelIpsNull,
92    KernelIpsOpens,
93    RegisterConstant,
94    Site,
95    SiteAsmInlined,
96    SiteAsmOnly,
97    EntryMain,
98    EntryDwarf,
99    SitePointer,
100    Entry,
101    Hole,
102    HoleDirect,
103    HoleSite,
104    HoleReturn,
105    HoleDuplicated,
106    HoleInlined,
107    HolePureCall,
108    HoleQuiet,
109    HoleReturnTail,
110    HoleEdge,
111    HoleUnreached,
112    HoleOutsideReach,
113    HoleMerged,
114}
115impl ProofKind {
116    pub const ALL: &'static [Self] = &[
117        Self::SiteReport,
118        Self::HoleReport,
119        Self::KernelIpsAsm,
120        Self::KernelIps,
121        Self::KernelIpsNull,
122        Self::KernelIpsOpens,
123        Self::RegisterConstant,
124        Self::Site,
125        Self::SiteAsmInlined,
126        Self::SiteAsmOnly,
127        Self::EntryMain,
128        Self::EntryDwarf,
129        Self::SitePointer,
130        Self::Entry,
131        Self::Hole,
132        Self::HoleDirect,
133        Self::HoleSite,
134        Self::HoleReturn,
135        Self::HoleDuplicated,
136        Self::HoleInlined,
137        Self::HolePureCall,
138        Self::HoleQuiet,
139        Self::HoleReturnTail,
140        Self::HoleEdge,
141        Self::HoleUnreached,
142        Self::HoleOutsideReach,
143        Self::HoleMerged,
144    ];
145    pub fn description(self) -> &'static str {
146        match self {
147            Self::SiteReport => PROOF_SITE_REPORT,
148            Self::HoleReport => PROOF_HOLE_REPORT,
149            Self::KernelIpsAsm => PROOF_KERNEL_IPS_ASM,
150            Self::KernelIps => PROOF_KERNEL_IPS,
151            Self::KernelIpsNull => PROOF_KERNEL_IPS_NULL,
152            Self::KernelIpsOpens => PROOF_KERNEL_IPS_OPENS,
153            Self::RegisterConstant => PROOF_REGISTER_CONSTANT,
154            Self::Site => PROOF_SITE,
155            Self::SiteAsmInlined => PROOF_SITE_ASM_INLINED,
156            Self::SiteAsmOnly => PROOF_SITE_ASM_ONLY,
157            Self::EntryMain => PROOF_ENTRY_MAIN,
158            Self::EntryDwarf => PROOF_ENTRY_DWARF,
159            Self::SitePointer => PROOF_SITE_POINTER,
160            Self::Entry => PROOF_ENTRY,
161            Self::Hole => PROOF_HOLE,
162            Self::HoleDirect => PROOF_HOLE_DIRECT,
163            Self::HoleSite => PROOF_HOLE_SITE,
164            Self::HoleReturn => PROOF_HOLE_RETURN,
165            Self::HoleDuplicated => PROOF_HOLE_DUPLICATED,
166            Self::HoleInlined => PROOF_HOLE_INLINED,
167            Self::HolePureCall => PROOF_HOLE_PURE_CALL,
168            Self::HoleQuiet => PROOF_HOLE_QUIET,
169            Self::HoleReturnTail => PROOF_HOLE_RETURN_TAIL,
170            Self::HoleEdge => PROOF_HOLE_EDGE,
171            Self::HoleUnreached => PROOF_HOLE_UNREACHED,
172            Self::HoleOutsideReach => PROOF_HOLE_OUTSIDE_REACH,
173            Self::HoleMerged => PROOF_HOLE_MERGED,
174        }
175    }
176    /// Premises of this binding rule, separate from its checked evidence.
177    pub fn premises(self) -> &'static [Premise] {
178        match self {
179            Self::SiteAsmInlined => &[Premise::LineOrigin, Premise::InlineCallOrigin],
180            Self::Site
181            | Self::SiteAsmOnly
182            | Self::Hole
183            | Self::HoleDirect
184            | Self::HoleSite
185            | Self::HoleDuplicated => &[Premise::LineOrigin],
186            Self::HoleInlined => &[
187                Premise::CodeOrigin,
188                Premise::LineOrigin,
189                Premise::InlineCallOrigin,
190            ],
191            Self::HoleOutsideReach => &[Premise::ScopeAncestor, Premise::ExecReach],
192            Self::HoleMerged => &[
193                Premise::CodeOrigin,
194                Premise::PointerCall,
195                Premise::ExecReach,
196            ],
197            _ => &[],
198        }
199    }
200
201    pub fn parse(value: &str) -> Option<Self> {
202        Self::ALL
203            .iter()
204            .copied()
205            .find(|p| p.description() == value)
206            .or_else(|| serde_json::from_value(serde_json::Value::String(value.into())).ok())
207    }
208}
209
210// Keep source compatibility with decoder clients while the wire uses enum
211// identifiers. Unknown input is retained only so the common gate can name it.
212pub mod wire {
213    use super::*;
214    pub fn serialize<S: serde::Serializer>(s: &str, out: S) -> Result<S::Ok, S::Error> {
215        match ProofKind::parse(s) {
216            Some(kind) => kind.serialize(out),
217            None => s.serialize(out),
218        }
219    }
220    pub fn deserialize<'de, D: serde::Deserializer<'de>>(input: D) -> Result<String, D::Error> {
221        let value = String::deserialize(input)?;
222        Ok(ProofKind::parse(&value).map_or(value.clone(), |p| p.description().into()))
223    }
224}
225pub mod optional_wire {
226    use super::*;
227    pub fn serialize<S: serde::Serializer>(s: &Option<String>, out: S) -> Result<S::Ok, S::Error> {
228        match s {
229            Some(value) => match ProofKind::parse(value) {
230                Some(kind) => out.serialize_some(&kind),
231                None => out.serialize_some(value),
232            },
233            None => out.serialize_none(),
234        }
235    }
236    pub fn deserialize<'de, D: serde::Deserializer<'de>>(
237        input: D,
238    ) -> Result<Option<String>, D::Error> {
239        let value = Option::<String>::deserialize(input)?;
240        Ok(value.map(|v| ProofKind::parse(&v).map_or(v.clone(), |p| p.description().into())))
241    }
242}