ogar-dir-sim: mail is a business-card property; ExchangeGuid is the immutable mailbox identity (doc)

crates/ogar-dir-sim/src/exchange.rs

@@ -342,17 +342,18 @@ impl Recipient {
 /// `ExchangeGuid` across a move) and the address it receives at
 /// (`PrimarySmtpAddress`).
 ///
-/// Identities are GUIDs: `node` is the on-premises object, and a
-/// provisioned mailbox is identified by its `exchange_guid`. The user is the
+/// A provisioned mailbox's immutable identity is its `exchange_guid`;
+/// `PrimarySmtpAddress` (`primary_smtp`) identifies the recipient
+/// implicitly, as a string, and can change; `node` is the on-premises
+/// object. The user is the
 /// Entra object (Azure AD, formerly the MsolUser), which carries
 /// `{alias}@{tenant}.onmicrosoft.com`, Microsoft's internal cloud address.
 /// Every mail recipient links its mailbox to that user through
 /// `ExternalDirectoryObjectId` — "external" because it points into the
 /// directory outside Exchange. None of these is the routing address
 /// `{alias}@{tenant}.mail.onmicrosoft.com` ([`ROUTING`]), the external
-/// target EOP delivers to. An address is a value of an identity,
-/// never the key it is found by, and `mail` in particular is a label that
-/// hydrates no identity.
+/// target EOP delivers to. `mail` is a property on the user's business card,
+/// like the telephone number, and hydrates no identity.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ExchangeIdentity {
     /// The object (`objectGUID`).
@@ -361,7 +362,8 @@ pub struct ExchangeIdentity {
     pub recipient: Option<Recipient>,
     /// `msExchMailboxGuid`; `None` = no mailbox, or not read.
     pub exchange_guid: Option<Guid128>,
-    /// `PrimarySmtpAddress`.
+    /// `PrimarySmtpAddress`: identifies the recipient implicitly, as a
+    /// string; mutable, unlike `exchange_guid`.
     pub primary_smtp: Option<ValueId>,
 }
 

crates/ogar-dir-sim/src/violation.rs

@@ -25,10 +25,12 @@ pub enum AddressRole {
     PrimarySmtp,
     /// A secondary SMTP proxy (`smtp:`).
     SecondarySmtp,
-    /// The `mail` attribute: the licence plate. It is shown in the address
-    /// book and used inside messages, and it matters, but it is a label:
-    /// not the identity of the mailbox or the user (identity is read by
-    /// GUID, [`ExchangeIdentity`](crate::exchange::ExchangeIdentity)), not an
+    /// The `mail` attribute: a property on the user's business card, like
+    /// the telephone number. It is shown in the address book and used inside
+    /// messages, and it follows the user, not the mailbox or the recipient.
+    /// It is not the recipient's identity (immutably the mailbox's
+    /// `ExchangeGuid`, implicitly its `PrimarySmtpAddress`; see
+    /// [`ExchangeIdentity`](crate::exchange::ExchangeIdentity)), not an
     /// address anything is received at, and not provisioned. Exchange does
     /// not reserve it, so it never makes an object a holder in
     /// [`Violation::AddressConflict`]. This holds as long as AD Connect does