Skip to main content

rapx/contract/
spec.rs

1//! Declaration table mapping tag names to their property specs.
2//!
3//! This is the single source of truth for every safety tag `rapx` understands:
4//! its `PropertyKind`, the argument shapes it accepts (for variable-arity tags
5//! there is more than one form), its default `ContractKind`, and its rendering
6//! template.
7//!
8//! `PropertyKind` orthogonalisation lives on `PropertyKind` in `types.rs`.
9//!
10//! Some tags are declared but not fully supported: `Unwrap`, `Pinned`,
11//! `Opened` and `Unreachable` are parsed but the checker returns `Unknown`;
12//! `NonVolatile` is assumed satisfied (the VM does not model volatile access).
13
14use super::*;
15
16#[derive(Clone, Copy, Debug, PartialEq, Eq)]
17pub(crate) enum ArgKind {
18    Target,
19    Ty,
20    Expr,
21    Ident,
22}
23
24pub(crate) struct PropertySpec {
25    /// Tag name as written in contracts (e.g. `"Allocated"`).
26    pub tag: &'static str,
27    /// The `PropertyKind` this tag resolves to.
28    pub kind: PropertyKind,
29    /// Accepted argument shapes (authoritative for positional builds only).
30    pub forms: &'static [&'static [ArgKind]],
31    /// Default contract kind (`Precond` / `Hazard` / `Option_`).
32    pub contract_kind: ContractKind,
33    /// Explanation template with `{0}`, `{1}`, `{2}` placeholders.
34    pub meaning: &'static str,
35}
36
37const fn ps(
38    tag: &'static str,
39    kind: PropertyKind,
40    forms: &'static [&'static [ArgKind]],
41    contract_kind: ContractKind,
42    meaning: &'static str,
43) -> PropertySpec {
44    PropertySpec {
45        tag,
46        kind,
47        forms,
48        contract_kind,
49        meaning,
50    }
51}
52
53use ArgKind::{Expr, Ident, Target, Ty};
54
55// ── Table ────────────────────────────────────────────────────────────
56
57static SPECS: &[PropertySpec] = &[
58    // Single-form primitives.
59    ps(
60        "NonNull",
61        PropertyKind::NonNull,
62        &[&[Target]],
63        ContractKind::Precond,
64        "{0} as usize != 0",
65    ),
66    ps(
67        "SliceOffset",
68        PropertyKind::SliceOffset,
69        &[&[Target, Target, Target]],
70        ContractKind::Postcond,
71        "addr({0}) = addr({1}) + start({2}) * size_of_element({1})",
72    ),
73    ps(
74        "Null",
75        PropertyKind::Null,
76        &[&[Target]],
77        ContractKind::Precond,
78        "{0} is the null pointer",
79    ),
80    ps(
81        "Owning",
82        PropertyKind::Owning,
83        &[&[Target], &[Target, Ty], &[Target, Ty, Expr]],
84        ContractKind::Precond,
85        "ownership(*{0}) = none: no other live owner points to the pointee",
86    ),
87    ps(
88        "RefCountShare",
89        PropertyKind::RefCountShare,
90        &[&[Target]],
91        ContractKind::Precond,
92        "{0} carries an unclaimed Arc/Rc strong-reference share",
93    ),
94    // Unverified: the checker returns `Unknown` (no implementation yet).
95    ps(
96        "Opened",
97        PropertyKind::Opened,
98        &[&[Target]],
99        ContractKind::Precond,
100        "{0} is a valid open file descriptor",
101    ),
102    // Unverified: the checker returns `Unknown` (no implementation yet).
103    ps(
104        "Unreachable",
105        PropertyKind::Unreachable,
106        &[&[]],
107        ContractKind::Precond,
108        "this branch is unreachable",
109    ),
110    ps(
111        "Align",
112        PropertyKind::Align,
113        &[&[Target, Ty]],
114        ContractKind::Precond,
115        "({0} as usize) % align_of::<{1}>() == 0",
116    ),
117    ps(
118        "Typed",
119        PropertyKind::Typed,
120        &[&[Target], &[Target, Ty], &[Target, Ty, Expr]],
121        ContractKind::Precond,
122        "*{0} holds TypeInvariant({1})",
123    ),
124    ps(
125        "Init",
126        PropertyKind::Init,
127        &[&[Target], &[Target, Ty], &[Target, Ty, Expr]],
128        ContractKind::Precond,
129        "forall i in 0..{2}: *({0} + i*sizeof({1})) |= type_invariant({1}), and the {2} value(s) are initialized",
130    ),
131    ps(
132        "ValidString",
133        PropertyKind::ValidString,
134        &[&[Target, Ty, Expr], &[Target]],
135        ContractKind::Precond,
136        "{0} is valid UTF-8",
137    ),
138    // Assumed satisfied: the VM does not model volatile access.
139    ps(
140        "NonVolatile",
141        PropertyKind::NonVolatile,
142        &[&[Target], &[Target, Ty], &[Target, Ty, Expr]],
143        ContractKind::Precond,
144        "{0} does not reference volatile memory",
145    ),
146    ps(
147        "ValidTransmute",
148        PropertyKind::ValidTransmute,
149        &[&[Ty, Ty]],
150        ContractKind::Precond,
151        "bytes_of({1}) within bytes_of({0})",
152    ),
153    ps(
154        "Trait",
155        PropertyKind::Trait,
156        &[&[Ty, Ident]],
157        ContractKind::Precond,
158        "{0} satisfies the trait bound {1}",
159    ),
160    // Variable-arity negative type predicate: first arg is the target type,
161    // the rest are negative type names the target must not (structurally)
162    // contain.  Arity is validated by `build_contain_no_type`.
163    ps(
164        "ContainNoType",
165        PropertyKind::ContainNoType,
166        &[&[Ty, Ident]],
167        ContractKind::Precond,
168        "{0} does not structurally contain {1}",
169    ),
170    // `&T: Send` — the type can be shared across threads: every
171    // interior-mutability / raw-pointer field of {0} is guarded by a
172    // synchronization primitive (mutex/rwlock/atomic).
173    ps(
174        "RefSend",
175        PropertyKind::RefSend,
176        &[&[Ty]],
177        ContractKind::Precond,
178        "&{0} is Send: all shared mutations of {0} go through a synchronization primitive",
179    ),
180    // Interior-mutability predicates for taming raw pointers in `Send`/`Sync`.
181    ps(
182        "NoRawPtr",
183        PropertyKind::NoRawPtr,
184        &[&[Ty]],
185        ContractKind::Precond,
186        "{0} has no raw pointers",
187    ),
188    ps(
189        "NoInternalMut",
190        PropertyKind::NoInternalMut,
191        &[&[Ty]],
192        ContractKind::Precond,
193        "{0} has no interior mutation through raw pointers",
194    ),
195    ps(
196        "UniInternalMut",
197        PropertyKind::UniInternalMut,
198        &[&[Ty]],
199        ContractKind::Precond,
200        "{0} has unique interior mutation (exclusive owner, no aliasing Clone)",
201    ),
202    ps(
203        "AtomicUpdate",
204        PropertyKind::AtomicUpdate,
205        &[&[Ty]],
206        ContractKind::Precond,
207        "{0} updates its raw pointers under synchronization or atomically",
208    ),
209    ps(
210        "NoPadding",
211        PropertyKind::NoPadding,
212        &[&[Ty]],
213        ContractKind::Precond,
214        "{0} has no padding bytes between fields",
215    ),
216    ps(
217        "ValidCStr",
218        PropertyKind::ValidCStr,
219        &[&[Target], &[Target, Expr]],
220        ContractKind::Precond,
221        "{0} is a null-terminated valid UTF-8 byte sequence",
222    ),
223    // Unverified: the checker returns `Unknown` (no implementation yet).
224    ps(
225        "Unwrap",
226        PropertyKind::Unwrap,
227        &[&[Target, Ident]],
228        ContractKind::Precond,
229        "unwrap({0}) = {1}",
230    ),
231    // Variable-arity / special-build primitives.
232    ps(
233        "Size",
234        PropertyKind::Size,
235        &[&[Ty, Ident], &[Ty, Expr]],
236        ContractKind::Precond,
237        "sizeof({0}) = {1}",
238    ),
239    ps(
240        "Allocated",
241        PropertyKind::Allocated,
242        &[&[Target], &[Target, Ty], &[Target, Ty, Expr], &[Target, Ty, Ident], &[Target, Ty, Expr, Ident]],
243        ContractKind::Precond,
244        "{0} points to a live allocation of size: size_of({1}) * {2}",
245    ),
246    ps(
247        "InBound",
248        PropertyKind::InBound,
249        &[&[Target], &[Target, Ty], &[Target, Expr], &[Target, Ty, Expr]],
250        ContractKind::Precond,
251        "same_alloc([{0}, {0} + sizeof({1})*{2}])",
252    ),
253    ps(
254        "NonOverlap",
255        PropertyKind::NonOverlap,
256        &[&[Target], &[Target, Target], &[Target, Target, Ty], &[Target, Target, Ty, Expr]],
257        ContractKind::Precond,
258        "[{0}] are pairwise disjoint memory ranges",
259    ),
260    ps(
261        "ValidNum",
262        PropertyKind::ValidNum,
263        &[&[Expr], &[Expr, Expr]],
264        ContractKind::Precond,
265        "{0}",
266    ),
267    ps(
268        "Alias",
269        PropertyKind::Alias,
270        &[&[Target, Target]],
271        ContractKind::Hazard,
272        "{0} and {1} alias each other (hazard)",
273    ),
274    ps(
275        "Alive",
276        PropertyKind::Alive,
277        &[&[Target, Target]],
278        ContractKind::Precond,
279        "*{0} outlives '{1}",
280    ),
281    // Unverified: the checker returns `Unknown` (no implementation yet).
282    ps(
283        "Pinned",
284        PropertyKind::Pinned,
285        &[&[Target, Ident]],
286        ContractKind::Precond,
287        "{0} will not be moved",
288    ),
289    ps(
290        "SplitTransmute",
291        PropertyKind::SplitTransmute,
292        &[&[Ty, Ty]],
293        ContractKind::Precond,
294        "[{0}] as [{1}]: every size_of({1})-byte contiguous chunk of [{0}] is a valid bit-pattern of {1} (type_invariant satisfied, alignment not required)\nforall w subset bytes([{0}]), |w| == |{1}|: reinterpret_as_{1}(w) |= type_invariant({1})",
295    ),
296    ps(
297        "TobeSpecified",
298        PropertyKind::Unknown,
299        &[],
300        ContractKind::Precond,
301        "(unresolved contract)",
302    ),
303];
304
305pub(crate) fn find_spec(name: &str) -> Option<&'static PropertySpec> {
306    SPECS.iter().find(|s| s.tag == name)
307}
308
309/// The first tag name that maps to `kind` (the inverse of [`find_spec`]).
310pub(crate) fn tag_name_for_kind(kind: PropertyKind) -> Option<&'static str> {
311    SPECS.iter().find(|s| s.kind == kind).map(|s| s.tag)
312}
313
314/// The canonical meaning template for a property kind (the first tag that maps
315/// to `kind`).  Argument-dependent kinds override this at render time.
316pub(crate) fn kind_meaning(kind: PropertyKind) -> &'static str {
317    SPECS
318        .iter()
319        .find(|s| s.kind == kind)
320        .map(|s| s.meaning)
321        .unwrap_or("(unresolved contract)")
322}