From 04c578b5ef4669d57131b6eb7cb6f550fee36e21 Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Thu, 11 Dec 2025 06:20:00 -0500
Subject: [PATCH 01/21] Update types-and-traits.rst

added new guideline on unions
---
 .../gui_UnionFieldValidity.rst.inc            | 289 ++++++++++++++++++
 .../types-and-traits/index.rst                |   1 +
 2 files changed, 290 insertions(+)
 create mode 100644 src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
new file mode 100644
index 00000000..f939d3b0
--- /dev/null
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -0,0 +1,289 @@
+.. SPDX-License-Identifier: MIT OR Apache-2.0
+   SPDX-FileCopyrightText: The Coding Guidelines Subcommittee Contributors
+
+.. default-domain:: coding-guidelines
+
+.. guideline:: Ensure reads of union fields produce valid values for the field's type
+   :id: gui_UnionFieldValidity
+   :category: required
+   :status: draft
+   :release: 1.85.0
+   :decidability: undecidable
+   :scope: expression
+   :tags: unions, safety, undefined-behavior
+
+   When reading from a union field, ensure that the underlying bytes constitute a valid value 
+   for that field's type.
+   Reading a union field whose bytes do not represent a valid value 
+   for the field's type is undefined behavior.
+
+   Before accessing a union field:
+   
+   * Verify that the union was last written through that field, or
+   * Verify that the union was written through a field whose bytes are valid when reinterpreted as the target field's type, or
+   * Use explicit validity checks when the active field is uncertain
+
+   .. rationale::
+      :id: rat_UnionFieldValidityReason
+      :status: draft
+
+      Unions allow multiple fields to occupy the same memory, similar to C unions.
+      Unlike enums, unions do not track which field is currently active. It is the programmer's
+      responsibility to ensure that when a field is read, the underlying bytes are valid for
+      that field's type [RUST-REF-UNION]_.
+
+      Every type has a *validity invariant* — a set of constraints that all values of
+      that type must satisfy [UCG-VALIDITY]_.
+      Reading a union field performs a *typed read*,
+      which asserts that the bytes are valid for the target type.
+      Violating this invariant is undefined behavior.
+
+      Examples of validity requirements for common types:
+
+      * **bool**: Must be ``0`` (false) or ``1`` (true). Any other value (e.g., ``3``) is invalid.
+      * **char**: Must be a valid Unicode scalar value (0x0 to 0xD7FF or 0xE000 to 0x10FFFF).
+      * **References**: Must be non-null and properly aligned.
+      * **Enums**: Must hold a valid discriminant value.
+      * **Floating point**: All bit patterns are valid for the ``f32`` or ``f64``.type
+      * **Integers**: All bit patterns are valid for integer types.
+
+      Consequences of reading invalid values include:
+
+      * Immediate undefined behavior, even if the value is not used
+      * Miscompilation due to compiler assumptions about valid values
+      * Security vulnerabilities from unexpected program behavior
+      * Non-deterministic behavior that varies across optimization levels or platforms
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionBool
+      :status: draft
+
+      This example reads a boolean from a union field containing an invalid bit pattern.
+      The value ``3`` is not a valid boolean (only ``0`` and ``1`` are valid).
+
+      .. code-block:: rust
+
+         union IntOrBool {
+             i: u8,
+             b: bool,
+         }
+
+         fn main() {
+             let u = IntOrBool { i: 3 };
+             
+             // Noncompliant: reading bool field with invalid value (3)
+             let invalid_bool = unsafe { u.b };  // UB: 3 is not a valid bool
+         }
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionChar
+      :status: draft
+
+      This example reads a ``char`` from a union containing an invalid Unicode value.
+
+      .. code-block:: rust
+
+         union IntOrChar {
+             i: u32,
+             c: char,
+         }
+
+         fn main() {
+             // 0xD800 is a surrogate, not a valid Unicode scalar value
+             let u = IntOrChar { i: 0xD800 };
+             
+             // Non-compliant: reading char field with invalid Unicode value
+             let invalid_char = unsafe { u.c };  // UB: surrogates are not valid chars
+         }
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionEnum
+      :status: draft
+
+      This example reads an enum from a ``union`` containing an invalid discriminant.
+
+      .. code-block:: rust
+
+         #[repr(u8)]
+         enum Color {
+             Red = 0,
+             Green = 1,
+             Blue = 2,
+         }
+
+         union IntOrColor {
+             i: u8,
+             c: Color,
+         }
+
+         fn main() {
+             let u = IntOrColor { i: 42 };
+             
+             // Noncompliant: 42 is not a valid Color discriminant
+             let invalid_color = unsafe { u.c };  // UB: no Color variant for 42
+         }
+
+   .. non_compliant_example::
+      :id: non_compl_ex_UnionRef
+      :status: draft
+
+      This example reads a reference from a ``union`` containing a null or misaligned pointer.
+
+      .. code-block:: rust
+
+         union PtrOrRef {
+             p: *const i32,
+             r: &'static i32,
+         }
+
+         fn main() {
+             let u = PtrOrRef { p: std::ptr::null() };
+             
+             // Non-compliant: null is not a valid reference
+             let invalid_ref = unsafe { u.r };  // UB: references cannot be null
+         }
+
+   .. compliant_example::
+      :id: compl_ex_UnionTrackField
+      :status: draft
+
+      Track the active field explicitly to ensure valid reads.
+
+      .. code-block:: rust
+
+         union IntOrBool {
+             i: u8,
+             b: bool,
+         }
+
+         enum ActiveField {
+             Int,
+             Bool,
+         }
+
+         struct SafeUnion {
+             data: IntOrBool,
+             active: ActiveField,
+         }
+
+         impl SafeUnion {
+             fn new_int(value: u8) -> Self {
+                 Self {
+                     data: IntOrBool { i: value },
+                     active: ActiveField::Int,
+                 }
+             }
+
+             fn new_bool(value: bool) -> Self {
+                 Self {
+                     data: IntOrBool { b: value },
+                     active: ActiveField::Bool,
+                 }
+             }
+
+             fn get_bool(&self) -> Option<bool> {
+                 match self.active {
+                     // Compliant: only read bool when we know it was written as bool
+                     ActiveField::Bool => Some(unsafe { self.data.b }),
+                     ActiveField::Int => None,
+                 }
+             }
+         }
+
+   .. compliant_example::
+      :id: compl_ex_UnionSameField
+      :status: draft
+
+      Read from the same field that was written.
+
+      .. code-block:: rust
+
+         union IntOrBool {
+             i: u8,
+             b: bool,
+         }
+
+         fn main() {
+             let u = IntOrBool { b: true };
+             
+             // Compliant: reading the same field that was written
+             let valid_bool = unsafe { u.b };
+             println!("bool value: {}", valid_bool);
+         }
+
+   .. compliant_example::
+      :id: compl_ex_UnionValidReinterpret
+      :status: draft
+
+      Reinterpret between types where all bit patterns are valid.
+
+      .. code-block:: rust
+
+         union IntBytes {
+             i: u32,
+             bytes: [u8; 4],
+         }
+
+         fn main() {
+             let u = IntBytes { i: 0x12345678 };
+             
+             // Compliant: all bit patterns are valid for [u8; 4]
+             let bytes = unsafe { u.bytes };
+             println!("bytes: {:?}", bytes);
+             
+             let u2 = IntBytes { bytes: [0x11, 0x22, 0x33, 0x44] };
+             
+             // Compliant: all bit patterns are valid for u32
+             let int_value = unsafe { u2.i };
+             println!("integer: 0x{:08X}", int_value);
+         }
+
+   .. compliant_example::
+      :id: compl_ex_UnionValidateBool
+      :status: draft
+
+      Validate bytes before reading as a constrained type.
+
+      .. code-block:: rust
+
+         union IntOrBool {
+             i: u8,
+             b: bool,
+         }
+
+         fn try_read_bool(u: &IntOrBool) -> Option<bool> {
+             // Read as integer first (always valid for u8)
+             let raw = unsafe { u.i };
+             
+             // Validate before interpreting as bool
+             match raw {
+                 0 => Some(false),
+                 1 => Some(true),
+                 _ => None,  // Invalid bool value
+             }
+         }
+
+         fn main() {
+             let u1 = IntOrBool { i: 1 };
+             let u2 = IntOrBool { i: 3 };
+             
+             // Compliant: validates before reading as bool
+             println!("u1 as bool: {:?}", try_read_bool(&u1));  // Some(true)
+             println!("u2 as bool: {:?}", try_read_bool(&u2));  // None
+         }
+
+   .. bibliography::
+
+      .. [RUST-REF-UNION] The Rust Project Developers. "Rust Reference - Unions."
+         https://doc.rust-lang.org/reference/items/unions.html
+
+      .. [RUST-REF-UB] The Rust Project Developers. "Rust Reference - Behavior considered undefined."
+         https://doc.rust-lang.org/reference/behavior-considered-undefined.html
+
+      .. [UCG-VALIDITY] Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant."
+         https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant
+
+      .. [RUST-NOMICON-UNION] The Rust Project Developers. "The Rustonomicon - Unions."
+         https://doc.rust-lang.org/nomicon/unions.html
+
+>>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file
diff --git a/src/coding-guidelines/types-and-traits/index.rst b/src/coding-guidelines/types-and-traits/index.rst
index c0c6d817..95fea45d 100644
--- a/src/coding-guidelines/types-and-traits/index.rst
+++ b/src/coding-guidelines/types-and-traits/index.rst
@@ -7,3 +7,4 @@ Types and Traits
 ================
 
 .. include:: gui_xztNdXA2oFNC.rst.inc
+.. include:: gui_UnionFieldValidity.rst.inc

From 499e31c76fd81b234ef4871dc7ad71e867a6cbb0 Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Thu, 11 Dec 2025 06:35:18 -0500
Subject: [PATCH 02/21] Apply suggestion from @rcseacord

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc             | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index f939d3b0..524a66ac 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -10,7 +10,7 @@
    :release: 1.85.0
    :decidability: undecidable
    :scope: expression
-   :tags: unions, safety, undefined-behavior
+   :tags: defect, safety, undefined-behavior
 
    When reading from a union field, ensure that the underlying bytes constitute a valid value 
    for that field's type.

From 46312c5beb5717c892e5125ac0889eda666ad9a5 Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Thu, 11 Dec 2025 06:40:30 -0500
Subject: [PATCH 03/21] Update types-and-traits.rst

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc            | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 524a66ac..fcaf21e2 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -8,8 +8,9 @@
    :category: required
    :status: draft
    :release: 1.85.0
+   :fls: fls_oFIRXBPXu6Zv
    :decidability: undecidable
-   :scope: expression
+   :scope: system
    :tags: defect, safety, undefined-behavior
 
    When reading from a union field, ensure that the underlying bytes constitute a valid value 

From 4c9eb0822e935e530de08497f4b95f0bf8c4a0fb Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 12 Dec 2025 00:28:18 -0500
Subject: [PATCH 04/21] Update types-and-traits.rst

repaired bibliography
---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index fcaf21e2..e7a72148 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -275,16 +275,13 @@
 
    .. bibliography::
 
-      .. [RUST-REF-UNION] The Rust Project Developers. "Rust Reference - Unions."
-         https://doc.rust-lang.org/reference/items/unions.html
+.. [RUST-REF-UNION] The Rust Project Developers. “Rust Reference: Unions.” *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
 
-      .. [RUST-REF-UB] The Rust Project Developers. "Rust Reference - Behavior considered undefined."
-         https://doc.rust-lang.org/reference/behavior-considered-undefined.html
+.. [RUST-REF-UB] The Rust Project Developers. “Rust Reference: Behavior Considered Undefined.” *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/behavior-considered-undefined.html.
 
-      .. [UCG-VALIDITY] Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant."
-         https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant
+.. [UCG-VALIDITY] Rust Unsafe Code Guidelines Working Group. “Validity and Safety Invariant.” *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
+
+.. [RUST-NOMICON-UNION] The Rust Project Developers. “Unions.” *The Rustonomicon*, n.d. https://doc.rust-lang.org/nomicon/unions.html.
 
-      .. [RUST-NOMICON-UNION] The Rust Project Developers. "The Rustonomicon - Unions."
-         https://doc.rust-lang.org/nomicon/unions.html
 
 >>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file

From 4de7d26b793ec27b8ff0e98ec4933490c633abdc Mon Sep 17 00:00:00 2001
From: manhatsu <manhatsu@gmail.com>
Date: Fri, 12 Dec 2025 14:52:58 +0900
Subject: [PATCH 05/21] fix: add bibliography entry; delete unused citations

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc    | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index e7a72148..9de8fb4c 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -274,14 +274,12 @@
          }
 
    .. bibliography::
+      :id: bib_UnionFieldValidity
+      :status: draft
 
-.. [RUST-REF-UNION] The Rust Project Developers. “Rust Reference: Unions.” *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
-
-.. [RUST-REF-UB] The Rust Project Developers. “Rust Reference: Behavior Considered Undefined.” *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/behavior-considered-undefined.html.
-
-.. [UCG-VALIDITY] Rust Unsafe Code Guidelines Working Group. “Validity and Safety Invariant.” *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
+      .. [RUST-REF-UNION] The Rust Project Developers. “Rust Reference: Unions.” *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
+      .. [UCG-VALIDITY] Rust Unsafe Code Guidelines Working Group. “Validity and Safety Invariant.” *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
-.. [RUST-NOMICON-UNION] The Rust Project Developers. “Unions.” *The Rustonomicon*, n.d. https://doc.rust-lang.org/nomicon/unions.html.
 
 
 >>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file

From 0ce45566baa7c40baf6a35a4620f6240ae218cf4 Mon Sep 17 00:00:00 2001
From: manhatsu <manhatsu@gmail.com>
Date: Fri, 12 Dec 2025 15:18:29 +0900
Subject: [PATCH 06/21] chore: put citations in table

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc  | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 9de8fb4c..24b9b443 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -277,9 +277,13 @@
       :id: bib_UnionFieldValidity
       :status: draft
 
-      .. [RUST-REF-UNION] The Rust Project Developers. “Rust Reference: Unions.” *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
-      .. [UCG-VALIDITY] Rust Unsafe Code Guidelines Working Group. “Validity and Safety Invariant.” *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
-
-
+      .. list-table::
+         :header-rows: 0
+         :widths: 10 80
+
+         * - .. [RUST-REF-UNION]
+           - The Rust Project Developers. "Rust Reference: Unions." *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
+         * - .. [UCG-VALIDITY]
+           - Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant." *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
 >>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file

From 20d0418852f01911bf969f5a667a892952236852 Mon Sep 17 00:00:00 2001
From: manhatsu <manhatsu@gmail.com>
Date: Fri, 12 Dec 2025 17:32:03 +0900
Subject: [PATCH 07/21] fix: implement "Copy" to use enum in union

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc              | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 24b9b443..4c37f832 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -106,6 +106,7 @@
       .. code-block:: rust
 
          #[repr(u8)]
+         #[derive(Copy, Clone)]
          enum Color {
              Red = 0,
              Green = 1,

From 32de3d53c218581a3d6d4dd5abc0bc671d0d5228 Mon Sep 17 00:00:00 2001
From: manhatsu <manhatsu@gmail.com>
Date: Fri, 12 Dec 2025 17:44:50 +0900
Subject: [PATCH 08/21] fix: add main function

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc       | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 4c37f832..7367e7e0 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -192,6 +192,14 @@
              }
          }
 
+         fn main() {
+             let union_bool = SafeUnion::new_bool(true);
+             let union_int = SafeUnion::new_int(42);
+             
+             println!("Bool union as bool: {:?}", union_bool.get_bool());  // Some(true)
+             println!("Int union as bool: {:?}", union_int.get_bool());    // None
+         }
+
    .. compliant_example::
       :id: compl_ex_UnionSameField
       :status: draft

From a3035a8e21766fe2367df3a0ba07696381da894d Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 12 Dec 2025 07:42:58 -0500
Subject: [PATCH 09/21] Update types-and-traits.rst

fixing up bibliography
---
 .../gui_UnionFieldValidity.rst.inc            | 21 +++++++++----------
 1 file changed, 10 insertions(+), 11 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 7367e7e0..88a607c7 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -13,10 +13,8 @@
    :scope: system
    :tags: defect, safety, undefined-behavior
 
-   When reading from a union field, ensure that the underlying bytes constitute a valid value 
-   for that field's type.
-   Reading a union field whose bytes do not represent a valid value 
-   for the field's type is undefined behavior.
+   When reading from a union field, ensure that the underlying bytes constitute a valid value for that field's type.
+   Reading a union field whose bytes do not represent a valid value for the field's type is undefined behavior.
 
    Before accessing a union field:
    
@@ -29,12 +27,12 @@
       :status: draft
 
       Unions allow multiple fields to occupy the same memory, similar to C unions.
-      Unlike enums, unions do not track which field is currently active. It is the programmer's
-      responsibility to ensure that when a field is read, the underlying bytes are valid for
-      that field's type [RUST-REF-UNION]_.
+      Unlike enumeration types, unions do not track which field is currently active.
+      You must ensure that when a field is read,
+      the underlying bytes are valid for that field's type [1]_.
 
       Every type has a *validity invariant* — a set of constraints that all values of
-      that type must satisfy [UCG-VALIDITY]_.
+      that type must satisfy [2]_.
       Reading a union field performs a *typed read*,
       which asserts that the bytes are valid for the target type.
       Violating this invariant is undefined behavior.
@@ -286,13 +284,14 @@
       :id: bib_UnionFieldValidity
       :status: draft
 
+      ```rst
       .. list-table::
          :header-rows: 0
-         :widths: 10 80
+         :widths: 5 85
 
-         * - .. [RUST-REF-UNION]
+         * - .. [1]
            - The Rust Project Developers. "Rust Reference: Unions." *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
-         * - .. [UCG-VALIDITY]
+         * - .. [2]
            - Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant." *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
 >>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file

From 5f36ca3cbba9cbb91afc68974f12434c1d5c1ddc Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 12 Dec 2025 07:48:48 -0500
Subject: [PATCH 10/21] Update types-and-traits.rst

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc       | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 88a607c7..cdca8449 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -29,10 +29,10 @@
       Unions allow multiple fields to occupy the same memory, similar to C unions.
       Unlike enumeration types, unions do not track which field is currently active.
       You must ensure that when a field is read,
-      the underlying bytes are valid for that field's type [1]_.
+      the underlying bytes are valid for that field's type [UNION]_.
 
       Every type has a *validity invariant* — a set of constraints that all values of
-      that type must satisfy [2]_.
+      that type must satisfy [VALID]_.
       Reading a union field performs a *typed read*,
       which asserts that the bytes are valid for the target type.
       Violating this invariant is undefined behavior.
@@ -289,9 +289,9 @@
          :header-rows: 0
          :widths: 5 85
 
-         * - .. [1]
+         * - .. [UNION]
            - The Rust Project Developers. "Rust Reference: Unions." *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
-         * - .. [2]
+         * - .. [VALID]
            - Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant." *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
 >>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file

From 9b3b574a03f0ebc06772cd4b1555f1f372b75db6 Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 12 Dec 2025 07:53:58 -0500
Subject: [PATCH 11/21] Update types-and-traits.rst

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc              | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index cdca8449..8792662f 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -284,7 +284,6 @@
       :id: bib_UnionFieldValidity
       :status: draft
 
-      ```rst
       .. list-table::
          :header-rows: 0
          :widths: 5 85

From 60fd5439d692073c7dc7d1c30460a992edc717fa Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 12 Dec 2025 08:24:26 -0500
Subject: [PATCH 12/21] Update types-and-traits.rst

interim save
---
 .../gui_UnionFieldValidity.rst.inc            | 42 ++++++++-----------
 1 file changed, 18 insertions(+), 24 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 8792662f..eca6fc3e 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -35,7 +35,6 @@
       that type must satisfy [VALID]_.
       Reading a union field performs a *typed read*,
       which asserts that the bytes are valid for the target type.
-      Violating this invariant is undefined behavior.
 
       Examples of validity requirements for common types:
 
@@ -46,19 +45,14 @@
       * **Floating point**: All bit patterns are valid for the ``f32`` or ``f64``.type
       * **Integers**: All bit patterns are valid for integer types.
 
-      Consequences of reading invalid values include:
-
-      * Immediate undefined behavior, even if the value is not used
-      * Miscompilation due to compiler assumptions about valid values
-      * Security vulnerabilities from unexpected program behavior
-      * Non-deterministic behavior that varies across optimization levels or platforms
+      Reading an invalid value is undefined behavior.
 
    .. non_compliant_example::
       :id: non_compl_ex_UnionBool
       :status: draft
 
-      This example reads a boolean from a union field containing an invalid bit pattern.
-      The value ``3`` is not a valid boolean (only ``0`` and ``1`` are valid).
+      This noncompliant example reads a Boolean from a union field containing an invalid bit pattern.
+      The value ``3`` is not a valid Boolean (only ``0`` and ``1`` are valid).
 
       .. code-block:: rust
 
@@ -70,15 +64,15 @@
          fn main() {
              let u = IntOrBool { i: 3 };
              
-             // Noncompliant: reading bool field with invalid value (3)
-             let invalid_bool = unsafe { u.b };  // UB: 3 is not a valid bool
+             // Undefined behavior reading an invalid value from a union field of type 'bool'
+             unsafe { u.b };  // Noncompliant
          }
 
    .. non_compliant_example::
       :id: non_compl_ex_UnionChar
       :status: draft
 
-      This example reads a ``char`` from a union containing an invalid Unicode value.
+      This noncompliant example reads a ``char`` from a ``union`` containing an invalid Unicode value.
 
       .. code-block:: rust
 
@@ -88,18 +82,18 @@
          }
 
          fn main() {
-             // 0xD800 is a surrogate, not a valid Unicode scalar value
+             // 0xD800 is a surrogate and not a valid Unicode scalar value
              let u = IntOrChar { i: 0xD800 };
              
-             // Non-compliant: reading char field with invalid Unicode value
-             let invalid_char = unsafe { u.c };  // UB: surrogates are not valid chars
+             // Noncompliant: reading an invalid Unicode value from a union field of type 'char'
+             unsafe { u.c };  // Noncompliant
          }
 
    .. non_compliant_example::
       :id: non_compl_ex_UnionEnum
       :status: draft
 
-      This example reads an enum from a ``union`` containing an invalid discriminant.
+      This noncompliant example reads an invalid discriminant from a ``union`` field of 'Color' enumeration type.
 
       .. code-block:: rust
 
@@ -119,15 +113,15 @@
          fn main() {
              let u = IntOrColor { i: 42 };
              
-             // Noncompliant: 42 is not a valid Color discriminant
-             let invalid_color = unsafe { u.c };  // UB: no Color variant for 42
+             // Undefined behavior reading an invalid discriminant from the 'Color' enumeration type
+             unsafe { u.c };  // Noncompliant
          }
 
    .. non_compliant_example::
       :id: non_compl_ex_UnionRef
       :status: draft
 
-      This example reads a reference from a ``union`` containing a null or misaligned pointer.
+      This noncompliant example reads a reference from a ``union`` containing a null or misaligned pointer.
 
       .. code-block:: rust
 
@@ -147,7 +141,7 @@
       :id: compl_ex_UnionTrackField
       :status: draft
 
-      Track the active field explicitly to ensure valid reads.
+      This compliant example tracks the active field explicitly to ensure valid reads.
 
       .. code-block:: rust
 
@@ -202,7 +196,7 @@
       :id: compl_ex_UnionSameField
       :status: draft
 
-      Read from the same field that was written.
+      This compliant solution read from the same field that was written.
 
       .. code-block:: rust
 
@@ -223,7 +217,7 @@
       :id: compl_ex_UnionValidReinterpret
       :status: draft
 
-      Reinterpret between types where all bit patterns are valid.
+      This compliant example reinterprets the value as a different types where all bit patterns are valid.
 
       .. code-block:: rust
 
@@ -250,7 +244,7 @@
       :id: compl_ex_UnionValidateBool
       :status: draft
 
-      Validate bytes before reading as a constrained type.
+      This compliant solution validates bytes before reading as a constrained type.
 
       .. code-block:: rust
 
@@ -286,7 +280,7 @@
 
       .. list-table::
          :header-rows: 0
-         :widths: 5 85
+         :widths: 5 60
 
          * - .. [UNION]
            - The Rust Project Developers. "Rust Reference: Unions." *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.

From 2e94771775ca18a8eaba31481a9ba200fe745a10 Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 12 Dec 2025 10:07:42 -0500
Subject: [PATCH 13/21] Update types-and-traits.rst

---
 .../gui_UnionFieldValidity.rst.inc            | 22 ++++++++++++-------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index eca6fc3e..9275fa8a 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -29,10 +29,10 @@
       Unions allow multiple fields to occupy the same memory, similar to C unions.
       Unlike enumeration types, unions do not track which field is currently active.
       You must ensure that when a field is read,
-      the underlying bytes are valid for that field's type [UNION]_.
+      the underlying bytes are valid for that field's type [RUST-REF-UNION]_.
 
       Every type has a *validity invariant* — a set of constraints that all values of
-      that type must satisfy [VALID]_.
+      that type must satisfy [UCG-VALIDITY]_.
       Reading a union field performs a *typed read*,
       which asserts that the bytes are valid for the target type.
 
@@ -280,11 +280,17 @@
 
       .. list-table::
          :header-rows: 0
-         :widths: 5 60
-
-         * - .. [UNION]
-           - The Rust Project Developers. "Rust Reference: Unions." *The Rust Reference*, n.d. https://doc.rust-lang.org/reference/items/unions.html.
-         * - .. [VALID]
-           - Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant." *Rust Unsafe Code Guidelines*, n.d. https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
+         :widths: 10 90
+         :class: bibliography-table
+
+         * - .. [RUST-REF-UNION]
+           - The Rust Project Developers. "Rust Reference: Unions." 
+             *The Rust Reference*, n.d. 
+             https://doc.rust-lang.org/reference/items/unions.html.
+
+         * - .. [UCG-VALIDITY]
+           - Rust Unsafe Code Guidelines Working Group. "Validity and Safety 
+             Invariant." *Rust Unsafe Code Guidelines*, n.d. 
+             https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
 >>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file

From d74513f6258684aa065359317767de6947556b9f Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Fri, 12 Dec 2025 10:39:36 -0500
Subject: [PATCH 14/21] Update types-and-traits.rst

---
 .../gui_UnionFieldValidity.rst.inc                | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 9275fa8a..82424463 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -51,8 +51,8 @@
       :id: non_compl_ex_UnionBool
       :status: draft
 
-      This noncompliant example reads a Boolean from a union field containing an invalid bit pattern.
-      The value ``3`` is not a valid Boolean (only ``0`` and ``1`` are valid).
+      This noncompliant example reads an invalid bit pattern from a Boolean union field.
+      The value ``3`` is not a valid value of type ``bool`` (only ``0`` and ``1`` are valid).
 
       .. code-block:: rust
 
@@ -72,7 +72,7 @@
       :id: non_compl_ex_UnionChar
       :status: draft
 
-      This noncompliant example reads a ``char`` from a ``union`` containing an invalid Unicode value.
+      This noncompliant example reads an invalid Unicode value from a ``union`` field of type ``char`` .
 
       .. code-block:: rust
 
@@ -121,7 +121,8 @@
       :id: non_compl_ex_UnionRef
       :status: draft
 
-      This noncompliant example reads a reference from a ``union`` containing a null or misaligned pointer.
+      This noncompliant example reads a reference from a ``union`` containing a null pointer.
+      A similar problem occurs when reading a misaligned pointer.
 
       .. code-block:: rust
 
@@ -133,8 +134,8 @@
          fn main() {
              let u = PtrOrRef { p: std::ptr::null() };
              
-             // Non-compliant: null is not a valid reference
-             let invalid_ref = unsafe { u.r };  // UB: references cannot be null
+             //  Undefined behavior reading a null value from a reference field of a union
+             unsafe { u.r };  // Noncompliant
          }
 
    .. compliant_example::
@@ -196,7 +197,7 @@
       :id: compl_ex_UnionSameField
       :status: draft
 
-      This compliant solution read from the same field that was written.
+      This compliant solution reads from the same field that was written.
 
       .. code-block:: rust
 

From 4b2ef9f32de4ee4f09d928897b2868cb5c9e9a37 Mon Sep 17 00:00:00 2001
From: manhatsu <manhatsu@gmail.com>
Date: Tue, 16 Dec 2025 11:02:03 +0900
Subject: [PATCH 15/21] chore: enable line breaks

---
 .../gui_UnionFieldValidity.rst.inc                 | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 82424463..2e9331cd 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -281,17 +281,17 @@
 
       .. list-table::
          :header-rows: 0
-         :widths: 10 90
+         :widths: auto
          :class: bibliography-table
 
          * - .. [RUST-REF-UNION]
-           - The Rust Project Developers. "Rust Reference: Unions." 
-             *The Rust Reference*, n.d. 
-             https://doc.rust-lang.org/reference/items/unions.html.
+           - | The Rust Project Developers. "Rust Reference: Unions."
+             | *The Rust Reference*, n.d. 
+             | https://doc.rust-lang.org/reference/items/unions.html.
 
          * - .. [UCG-VALIDITY]
-           - Rust Unsafe Code Guidelines Working Group. "Validity and Safety 
-             Invariant." *Rust Unsafe Code Guidelines*, n.d. 
-             https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
+           - | Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant."
+             | *Rust Unsafe Code Guidelines*, n.d. 
+             | https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
 >>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file

From f4813ca4efd41ae0a42f605c78b5291d9e86961f Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Tue, 16 Dec 2025 07:09:10 -0500
Subject: [PATCH 16/21] Update gui_UnionFieldValidity.rst.inc

cleaned up
---
 .../gui_UnionFieldValidity.rst.inc            | 52 +++++++++----------
 1 file changed, 25 insertions(+), 27 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 2e9331cd..f1caf992 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -13,22 +13,23 @@
    :scope: system
    :tags: defect, safety, undefined-behavior
 
-   When reading from a union field, ensure that the underlying bytes constitute a valid value for that field's type.
+   Ensure that the underlying bytes constitute a valid value for that field's type when reading from a union field.
    Reading a union field whose bytes do not represent a valid value for the field's type is undefined behavior.
 
-   Before accessing a union field:
+   Before accessing a union field, verify that that the union was either:
    
-   * Verify that the union was last written through that field, or
-   * Verify that the union was written through a field whose bytes are valid when reinterpreted as the target field's type, or
-   * Use explicit validity checks when the active field is uncertain
+   * last written through that field, or
+   * written through a field whose bytes are valid when reinterpreted as the target field's type
+
+   If the active field is uncertain, use explicit validity checks.
 
    .. rationale::
       :id: rat_UnionFieldValidityReason
       :status: draft
 
-      Unions allow multiple fields to occupy the same memory, similar to C unions.
+      Similar to C, unions allow multiple fields to occupy the same memory.
       Unlike enumeration types, unions do not track which field is currently active.
-      You must ensure that when a field is read,
+      You must ensure that when a field is read that
       the underlying bytes are valid for that field's type [RUST-REF-UNION]_.
 
       Every type has a *validity invariant* — a set of constraints that all values of
@@ -39,7 +40,7 @@
       Examples of validity requirements for common types:
 
       * **bool**: Must be ``0`` (false) or ``1`` (true). Any other value (e.g., ``3``) is invalid.
-      * **char**: Must be a valid Unicode scalar value (0x0 to 0xD7FF or 0xE000 to 0x10FFFF).
+      * **char**: Must be a valid Unicode scalar value (``0x0`` to ``0xD7FF`` or ``0xE000`` to ``0x10FFFF``).
       * **References**: Must be non-null and properly aligned.
       * **Enums**: Must hold a valid discriminant value.
       * **Floating point**: All bit patterns are valid for the ``f32`` or ``f64``.type
@@ -82,10 +83,10 @@
          }
 
          fn main() {
-             // 0xD800 is a surrogate and not a valid Unicode scalar value
+             // '0xD800' is a surrogate and not a valid Unicode scalar value
              let u = IntOrChar { i: 0xD800 };
              
-             // Noncompliant: reading an invalid Unicode value from a union field of type 'char'
+             // Reading an invalid Unicode value from a union field of type 'char'
              unsafe { u.c };  // Noncompliant
          }
 
@@ -93,7 +94,7 @@
       :id: non_compl_ex_UnionEnum
       :status: draft
 
-      This noncompliant example reads an invalid discriminant from a ``union`` field of 'Color' enumeration type.
+      This noncompliant example reads an invalid discriminant from a union field of 'Color' enumeration type.
 
       .. code-block:: rust
 
@@ -121,7 +122,7 @@
       :id: non_compl_ex_UnionRef
       :status: draft
 
-      This noncompliant example reads a reference from a ``union`` containing a null pointer.
+      This noncompliant example reads a reference from a union containing a null pointer.
       A similar problem occurs when reading a misaligned pointer.
 
       .. code-block:: rust
@@ -209,9 +210,8 @@
          fn main() {
              let u = IntOrBool { b: true };
              
-             // Compliant: reading the same field that was written
-             let valid_bool = unsafe { u.b };
-             println!("bool value: {}", valid_bool);
+             // Read the same field that was written
+             println!("bool value: {}", unsafe { u.b }); // compliant
          }
 
    .. compliant_example::
@@ -230,22 +230,20 @@
          fn main() {
              let u = IntBytes { i: 0x12345678 };
              
-             // Compliant: all bit patterns are valid for [u8; 4]
-             let bytes = unsafe { u.bytes };
-             println!("bytes: {:?}", bytes);
+             // All bit patterns are valid for [u8; 4]
+             println!("bytes: {:?}", unsafe { u.bytes }); // compliant
              
              let u2 = IntBytes { bytes: [0x11, 0x22, 0x33, 0x44] };
              
-             // Compliant: all bit patterns are valid for u32
-             let int_value = unsafe { u2.i };
-             println!("integer: 0x{:08X}", int_value);
+             // All bit patterns are valid for 'u32'
+             println!("integer: 0x{:08X}", unsafe { u2.i }); // compliant
          }
 
    .. compliant_example::
       :id: compl_ex_UnionValidateBool
       :status: draft
 
-      This compliant solution validates bytes before reading as a constrained type.
+      This compliant example validates bytes before reading as a constrained type.
 
       .. code-block:: rust
 
@@ -255,14 +253,14 @@
          }
 
          fn try_read_bool(u: &IntOrBool) -> Option<bool> {
-             // Read as integer first (always valid for u8)
+             // Read as integer (always valid for 'u8')
              let raw = unsafe { u.i };
              
-             // Validate before interpreting as bool
+             // Validate before interpreting as a value of type 'bool'
              match raw {
                  0 => Some(false),
                  1 => Some(true),
-                 _ => None,  // Invalid bool value
+                 _ => None,  // Invalid Boolean value
              }
          }
 
@@ -270,7 +268,7 @@
              let u1 = IntOrBool { i: 1 };
              let u2 = IntOrBool { i: 3 };
              
-             // Compliant: validates before reading as bool
+             // Validates before reading as value of type 'bool'
              println!("u1 as bool: {:?}", try_read_bool(&u1));  // Some(true)
              println!("u2 as bool: {:?}", try_read_bool(&u2));  // None
          }
@@ -294,4 +292,4 @@
              | *Rust Unsafe Code Guidelines*, n.d. 
              | https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
->>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst
\ No newline at end of file
+>>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst

From 8c78d437914377d2a789fd06f71ad5905d14c29e Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Tue, 16 Dec 2025 11:41:35 -0500
Subject: [PATCH 17/21] Update
 src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Fernando José <fernando.iglesiasg@gmail.com>
---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc             | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index f1caf992..18032a45 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -43,7 +43,7 @@
       * **char**: Must be a valid Unicode scalar value (``0x0`` to ``0xD7FF`` or ``0xE000`` to ``0x10FFFF``).
       * **References**: Must be non-null and properly aligned.
       * **Enums**: Must hold a valid discriminant value.
-      * **Floating point**: All bit patterns are valid for the ``f32`` or ``f64``.type
+      * **Floating point**: All bit patterns are valid for the ``f32`` or ``f64`` types.
       * **Integers**: All bit patterns are valid for integer types.
 
       Reading an invalid value is undefined behavior.

From 5ad6d1862a7ed05c6829ed4f4c683b2c73edcae7 Mon Sep 17 00:00:00 2001
From: Pete LeVasseur <plevasseur@gmail.com>
Date: Tue, 16 Dec 2025 21:27:54 -0500
Subject: [PATCH 18/21] Remove git cruft

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc              | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 18032a45..0641ac62 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -292,4 +292,3 @@
              | *Rust Unsafe Code Guidelines*, n.d. 
              | https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
 
->>>>>>> c93b2cb (Update types-and-traits.rst):src/coding-guidelines/types-and-traits.rst

From b25c3008db27d1ef995b34166b7954cce54965d9 Mon Sep 17 00:00:00 2001
From: "Robert C. Seacord" <rcseacord@gmail.com>
Date: Wed, 17 Dec 2025 12:40:36 -0500
Subject: [PATCH 19/21] Update
 src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc

---
 .../types-and-traits/gui_UnionFieldValidity.rst.inc             | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
index 0641ac62..820f6c6e 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
@@ -7,7 +7,7 @@
    :id: gui_UnionFieldValidity
    :category: required
    :status: draft
-   :release: 1.85.0
+   :release: unknown
    :fls: fls_oFIRXBPXu6Zv
    :decidability: undecidable
    :scope: system

From 21a9c525ad2c1f08925b70d6185ba99473766ab9 Mon Sep 17 00:00:00 2001
From: masahiro-sakurai-1_stargate <masahiro.sakurai@woven-planet.global>
Date: Fri, 19 Dec 2025 11:13:15 +0900
Subject: [PATCH 20/21] chore: rename with unique ID

---
 ...{gui_UnionFieldValidity.rst.inc => gui_0cuTYG8RVYjg.rst.inc} | 2 +-
 src/coding-guidelines/types-and-traits/index.rst                | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
 rename src/coding-guidelines/types-and-traits/{gui_UnionFieldValidity.rst.inc => gui_0cuTYG8RVYjg.rst.inc} (99%)

diff --git a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc b/src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc
similarity index 99%
rename from src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
rename to src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc
index 820f6c6e..190fe915 100644
--- a/src/coding-guidelines/types-and-traits/gui_UnionFieldValidity.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc
@@ -4,7 +4,7 @@
 .. default-domain:: coding-guidelines
 
 .. guideline:: Ensure reads of union fields produce valid values for the field's type
-   :id: gui_UnionFieldValidity
+   :id: gui_0cuTYG8RVYjg
    :category: required
    :status: draft
    :release: unknown
diff --git a/src/coding-guidelines/types-and-traits/index.rst b/src/coding-guidelines/types-and-traits/index.rst
index 95fea45d..538a791f 100644
--- a/src/coding-guidelines/types-and-traits/index.rst
+++ b/src/coding-guidelines/types-and-traits/index.rst
@@ -7,4 +7,4 @@ Types and Traits
 ================
 
 .. include:: gui_xztNdXA2oFNC.rst.inc
-.. include:: gui_UnionFieldValidity.rst.inc
+.. include:: gui_0cuTYG8RVYjg.rst.inc

From 696e63334de2c1953969a92a693a9f5b5e1727ec Mon Sep 17 00:00:00 2001
From: masahiro-sakurai-1_stargate <masahiro.sakurai@woven-planet.global>
Date: Fri, 19 Dec 2025 11:27:39 +0900
Subject: [PATCH 21/21] fix: bibliography style

---
 .../types-and-traits/gui_0cuTYG8RVYjg.rst.inc  | 18 +++++++-----------
 1 file changed, 7 insertions(+), 11 deletions(-)

diff --git a/src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc b/src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc
index 190fe915..63a094eb 100644
--- a/src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc
+++ b/src/coding-guidelines/types-and-traits/gui_0cuTYG8RVYjg.rst.inc
@@ -30,10 +30,10 @@
       Similar to C, unions allow multiple fields to occupy the same memory.
       Unlike enumeration types, unions do not track which field is currently active.
       You must ensure that when a field is read that
-      the underlying bytes are valid for that field's type [RUST-REF-UNION]_.
+      the underlying bytes are valid for that field's type :cite:`gui_0cuTYG8RVYjg:RUST-REF-UNION`.
 
       Every type has a *validity invariant* — a set of constraints that all values of
-      that type must satisfy [UCG-VALIDITY]_.
+      that type must satisfy :cite:`gui_0cuTYG8RVYjg:UCG-VALIDITY`.
       Reading a union field performs a *typed read*,
       which asserts that the bytes are valid for the target type.
 
@@ -274,7 +274,7 @@
          }
 
    .. bibliography::
-      :id: bib_UnionFieldValidity
+      :id: bib_WNCi5njUWLuZ
       :status: draft
 
       .. list-table::
@@ -282,13 +282,9 @@
          :widths: auto
          :class: bibliography-table
 
-         * - .. [RUST-REF-UNION]
-           - | The Rust Project Developers. "Rust Reference: Unions."
-             | *The Rust Reference*, n.d. 
-             | https://doc.rust-lang.org/reference/items/unions.html.
+         * - :bibentry:`gui_0cuTYG8RVYjg:RUST-REF-UNION`
+           - The Rust Reference. "Unions." https://doc.rust-lang.org/reference/items/unions.html.
 
-         * - .. [UCG-VALIDITY]
-           - | Rust Unsafe Code Guidelines Working Group. "Validity and Safety Invariant."
-             | *Rust Unsafe Code Guidelines*, n.d. 
-             | https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.
+         * - :bibentry:`gui_0cuTYG8RVYjg:UCG-VALIDITY`
+           - Rust Unsafe Code Guidelines. "Validity and Safety Invariant." https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#validity-and-safety-invariant.