Terminology around safety/safeguard levels

Renames:
- "checks" -> "safeguards"
- "debug" -> "dev" (matches Cargo profile)
- "paranoid" -> "strict"
- "fast-unsafe" -> "disengaged"

Author: Bromeon

godot-bindings/Cargo.toml

@@ -33,8 +33,9 @@ api-custom = ["dep:bindgen", "dep:regex", "dep:which"]
 api-custom-json = ["dep:nanoserde", "dep:bindgen", "dep:regex", "dep:which"]
 api-custom-extheader = []
 
-debug-checks-balanced = []
-release-checks-fast-unsafe = []
+# Safeguard levels (see godot/lib.rs for detailed documentation).
+safeguards-dev-balanced = []
+safeguards-release-disengaged = []
 
 [dependencies]
 gdextension-api = { workspace = true }

godot-bindings/src/lib.rs

@@ -268,22 +268,22 @@ pub fn since_api(major_minor: &str) -> bool {
     !before_api(major_minor)
 }
 
-pub fn emit_checks_mode() {
-    let check_modes = ["fast-unsafe", "balanced", "paranoid"];
-    let mut checks_level = if cfg!(debug_assertions) { 2 } else { 1 };
+pub fn emit_safeguard_levels() {
+    let safeguard_modes = ["disengaged", "balanced", "strict"];
+    let mut safeguards_level = if cfg!(debug_assertions) { 2 } else { 1 };
     #[cfg(debug_assertions)]
-    if cfg!(feature = "debug-checks-balanced") {
-        checks_level = 1;
+    if cfg!(feature = "safeguards-dev-balanced") {
+        safeguards_level = 1;
     }
     #[cfg(not(debug_assertions))]
-    if cfg!(feature = "release-checks-fast-unsafe") {
-        checks_level = 0;
+    if cfg!(feature = "safeguards-release-disengaged") {
+        safeguards_level = 0;
     }
 
-    for mode in check_modes.iter() {
-        println!(r#"cargo:rustc-check-cfg=cfg(checks_at_least, values("{mode}"))"#);
+    for mode in safeguard_modes.iter() {
+        println!(r#"cargo:rustc-check-cfg=cfg(safeguards_at_least, values("{mode}"))"#);
     }
-    for mode in check_modes.iter().take(checks_level + 1) {
-        println!(r#"cargo:rustc-cfg=checks_at_least="{mode}""#);
+    for mode in safeguard_modes.iter().take(safeguards_level + 1) {
+        println!(r#"cargo:rustc-cfg=safeguards_at_least="{mode}""#);
     }
 }

godot-codegen/src/generator/classes.rs

@@ -195,7 +195,7 @@ fn make_class(class: &Class, ctx: &mut Context, view: &ApiView) -> GeneratedClas
         fn __checked_id(&self) -> Option<crate::obj::InstanceId> {
             // SAFETY: only Option due to layout-compatibility with RawGd<T>; it is always Some because stored in Gd<T> which is non-null.
             let rtti = unsafe { self.rtti.as_ref().unwrap_unchecked() };
-            #[cfg(checks_at_least = "paranoid")]
+            #[cfg(safeguards_at_least = "strict")]
             rtti.check_type::<Self>();
             Some(rtti.instance_id())
         }

godot-codegen/src/generator/native_structures.rs

@@ -219,7 +219,7 @@ fn make_native_structure_field_and_accessor(
 
                 let obj = #snake_field_name.upcast();
 
-                #[cfg(checks_at_least = "balanced")]
+                #[cfg(safeguards_at_least = "balanced")]
                 assert!(obj.is_instance_valid(), "provided node is dead");
 
                 let id = obj.instance_id().to_u64();

godot-core/Cargo.toml

@@ -38,8 +38,9 @@ api-4-4 = ["godot-ffi/api-4-4"]
 api-4-5 = ["godot-ffi/api-4-5"]
 # ]]
 
-debug-checks-balanced = ["godot-ffi/debug-checks-balanced"]
-release-checks-fast-unsafe = ["godot-ffi/release-checks-fast-unsafe"]
+# Safeguard levels (see godot/lib.rs for detailed documentation).
+safeguards-dev-balanced = ["godot-ffi/safeguards-dev-balanced"]
+safeguards-release-disengaged = ["godot-ffi/safeguards-release-disengaged"]
 
 [dependencies]
 godot-ffi = { path = "../godot-ffi", version = "=0.4.1" }

godot-core/build.rs

@@ -18,5 +18,5 @@ fn main() {
 
     godot_bindings::emit_godot_version_cfg();
     godot_bindings::emit_wasm_nothreads_cfg();
-    godot_bindings::emit_checks_mode();
+    godot_bindings::emit_safeguard_levels();
 }

godot-core/src/builtin/collections/array.rs

@@ -968,7 +968,7 @@ impl<T: ArrayElement> Array<T> {
     }
 
     /// Validates that all elements in this array can be converted to integers of type `T`.
-    #[cfg(checks_at_least = "paranoid")]
+    #[cfg(safeguards_at_least = "strict")]
     pub(crate) fn debug_validate_int_elements(&self) -> Result<(), ConvertError> {
         // SAFETY: every element is internally represented as Variant.
         let canonical_array = unsafe { self.assume_type_ref::<Variant>() };
@@ -990,7 +990,7 @@ impl<T: ArrayElement> Array<T> {
     }
 
     // No-op in Release. Avoids O(n) conversion checks, but still panics on access.
-    #[cfg(not(checks_at_least = "paranoid"))]
+    #[cfg(not(safeguards_at_least = "strict"))]
     pub(crate) fn debug_validate_int_elements(&self) -> Result<(), ConvertError> {
         Ok(())
     }
@@ -1233,7 +1233,7 @@ impl<T: ArrayElement> Clone for Array<T> {
         let copy = unsafe { self.clone_unchecked() };
 
         // Double-check copy's runtime type in Debug mode.
-        if cfg!(checks_at_least = "paranoid") {
+        if cfg!(safeguards_at_least = "strict") {
             copy.with_checked_type()
                 .expect("copied array should have same type as original array")
         } else {

godot-core/src/classes/class_runtime.rs

@@ -8,10 +8,10 @@
 //! Runtime checks and inspection of Godot classes.
 
 use crate::builtin::{GString, StringName, Variant, VariantType};
-#[cfg(checks_at_least = "paranoid")]
+#[cfg(safeguards_at_least = "strict")]
 use crate::classes::{ClassDb, Object};
 use crate::meta::CallContext;
-#[cfg(checks_at_least = "paranoid")]
+#[cfg(safeguards_at_least = "strict")]
 use crate::meta::ClassId;
 use crate::obj::{bounds, Bounds, Gd, GodotClass, InstanceId, RawGd, Singleton};
 use crate::sys;
@@ -191,7 +191,7 @@ where
     Gd::<T>::from_obj_sys(object_ptr)
 }
 
-#[cfg(checks_at_least = "balanced")]
+#[cfg(safeguards_at_least = "balanced")]
 pub(crate) fn ensure_object_alive(
     instance_id: InstanceId,
     old_object_ptr: sys::GDExtensionObjectPtr,
@@ -212,7 +212,7 @@ pub(crate) fn ensure_object_alive(
     );
 }
 
-#[cfg(checks_at_least = "paranoid")]
+#[cfg(safeguards_at_least = "strict")]
 pub(crate) fn ensure_object_inherits(derived: ClassId, base: ClassId, instance_id: InstanceId) {
     if derived == base
         || base == Object::class_id() // for Object base, anything inherits by definition
@@ -227,7 +227,7 @@ pub(crate) fn ensure_object_inherits(derived: ClassId, base: ClassId, instance_i
     )
 }
 
-#[cfg(checks_at_least = "paranoid")]
+#[cfg(safeguards_at_least = "strict")]
 pub(crate) fn ensure_binding_not_null<T>(binding: sys::GDExtensionClassInstancePtr)
 where
     T: GodotClass + Bounds<Declarer = bounds::DeclUser>,
@@ -255,7 +255,7 @@ where
 // Implementation of this file
 
 /// Checks if `derived` inherits from `base`, using a cache for _successful_ queries.
-#[cfg(checks_at_least = "paranoid")]
+#[cfg(safeguards_at_least = "strict")]
 fn is_derived_base_cached(derived: ClassId, base: ClassId) -> bool {
     use std::collections::HashSet;
 

godot-core/src/init/mod.rs

@@ -311,8 +311,12 @@ fn gdext_on_level_deinit(level: InitLevel) {
 /// responsible to uphold them: namely in GDScript code or other GDExtension bindings loaded by the engine.
 /// Violating this may cause undefined behavior, even when invoking _safe_ functions.
 ///
+/// If you use the `disengaged` [safeguard level], you accept that UB becomes possible even **in safe Rust APIs**, if you use them wrong
+/// (e.g. accessing a destroyed object).
+///
 /// [gdextension]: attr.gdextension.html
 /// [safety]: https://godot-rust.github.io/book/gdext/advanced/safety.html
+/// [safeguard level]: ../index.html#safeguard-levels
 // FIXME intra-doc link
 #[doc(alias = "entry_symbol", alias = "entry_point")]
 pub unsafe trait ExtensionLibrary {
@@ -530,6 +534,18 @@ unsafe fn ensure_godot_features_compatible() {
 
     out!("Check Godot precision setting...");
 
+    #[cfg(feature = "debug-log")] // Display safeguards level in debug log.
+    let safeguards_level = if cfg!(safeguards_at_least = "strict") {
+        "strict"
+    } else if cfg!(safeguards_at_least = "balanced") {
+        "balanced"
+    } else if cfg!(safeguards_at_least = "disengaged") {
+        "disengaged"
+    } else {
+        "unknown"
+    };
+    out!("Safeguards: {safeguards_level}");
+
     let os_class = StringName::from("OS");
     let single = GString::from("single");
     let double = GString::from("double");

godot-core/src/meta/error/convert_error.rs

@@ -189,7 +189,7 @@ pub(crate) enum FromGodotError {
     },
 
     /// Special case of `BadArrayType` where a custom int type such as `i8` cannot hold a dynamic `i64` value.
-    #[cfg(checks_at_least = "paranoid")]
+    #[cfg(safeguards_at_least = "strict")]
     BadArrayTypeInt {
         expected_int_type: &'static str,
         value: i64,
@@ -234,7 +234,7 @@ impl fmt::Display for FromGodotError {
 
                 write!(f, "expected array of type {exp_class}, got {act_class}")
             }
-            #[cfg(checks_at_least = "paranoid")]
+            #[cfg(safeguards_at_least = "strict")]
             Self::BadArrayTypeInt {
                 expected_int_type,
                 value,