Document PAM domain entities, enums, and read-model fields

Add XML doc comments to the AccessRequest/AccessLease/AccessDecision
entities, their status/verdict/kind enum members, and the denormalized
identity fields on the AccessRequestDetails read model. Documents the
non-obvious semantics (nullability, lifecycle, granted vs requested
window) while leaving plain ids and straight projections bare.

Author: Hinton

src/Pam.Domain/Entities/AccessDecision.cs

@@ -13,8 +13,14 @@ public class AccessDecision : ITableObject<Guid>
 {
     public Guid Id { get; set; }
 
+    /// <summary>
+    /// The request this decision was made on.
+    /// </summary>
     public Guid AccessRequestId { get; set; }
 
+    /// <summary>
+    /// Discriminates the decision: determines whether <see cref="ApproverId"/> or <see cref="ConditionKind"/> is populated.
+    /// </summary>
     public AccessDeciderKind DeciderKind { get; set; }
 
     /// <summary>
@@ -28,6 +34,9 @@ public class AccessDecision : ITableObject<Guid>
     /// </summary>
     public AccessConditionKind? ConditionKind { get; set; }
 
+    /// <summary>
+    /// The approve-or-deny outcome recorded by this decision.
+    /// </summary>
     public AccessDecisionVerdict Verdict { get; set; }
 
     /// <summary>
@@ -40,6 +49,9 @@ public class AccessDecision : ITableObject<Guid>
     /// </summary>
     public string? EvaluationContext { get; set; }
 
+    /// <summary>
+    /// When the decision was recorded, stamped in UTC at construction.
+    /// </summary>
     public DateTime CreationDate { get; set; } = DateTime.UtcNow;
 
     public void SetNewId()

src/Pam.Domain/Entities/AccessLease.cs

@@ -23,13 +23,35 @@ public class AccessLease : ITableObject<Guid>
     public Guid CipherId { get; set; }
     public Guid RequesterId { get; set; }
 
+    /// <summary>
+    /// The lease's position in its lifecycle. Only an <see cref="AccessLeaseStatus.Active"/> lease within its window
+    /// authorizes access.
+    /// </summary>
     public AccessLeaseStatus Status { get; set; }
+
+    /// <summary>
+    /// The start of the granted access window, carried over from the approved <see cref="AccessRequest"/>.
+    /// </summary>
     public DateTime NotBefore { get; set; }
+
+    /// <summary>
+    /// The end of the granted access window.
+    /// </summary>
     public DateTime NotAfter { get; set; }
 
+    /// <summary>
+    /// Set when an operator revokes the lease (<see cref="AccessLeaseStatus.Revoked"/>). NULL otherwise.
+    /// </summary>
     public DateTime? RevokedDate { get; set; }
+
+    /// <summary>
+    /// The operator who revoked the lease. NULL unless <see cref="Status"/> is <see cref="AccessLeaseStatus.Revoked"/>.
+    /// </summary>
     public Guid? RevokedBy { get; set; }
 
+    /// <summary>
+    /// When the lease was minted, stamped in UTC at construction.
+    /// </summary>
     public DateTime CreationDate { get; set; } = DateTime.UtcNow;
 
     public void SetNewId()

src/Pam.Domain/Entities/AccessRequest.cs

@@ -49,7 +49,15 @@ public class AccessRequest : ITableObject<Guid>
     /// </summary>
     public string? Reason { get; set; }
 
+    /// <summary>
+    /// The request's position in its lifecycle. Created <see cref="AccessRequestStatus.Pending"/> for human approval or
+    /// already <see cref="AccessRequestStatus.Approved"/> for automatic approval, then settling in one terminal state.
+    /// </summary>
     public AccessRequestStatus Status { get; set; }
+
+    /// <summary>
+    /// When the request was submitted, stamped in UTC at construction.
+    /// </summary>
     public DateTime CreationDate { get; set; } = DateTime.UtcNow;
 
     /// <summary>

src/Pam.Domain/Enums/AccessConditionKind.cs

@@ -7,7 +7,12 @@
 /// </summary>
 public enum AccessConditionKind : byte
 {
+    /// <summary>Requires a human approver; matching requests are routed for manual approval rather than auto-decided.</summary>
     HumanApproval = 0,
+
+    /// <summary>Matches when the requester's IP is on a configured allowlist.</summary>
     IpAllowlist = 1,
+
+    /// <summary>Matches when the request falls within a configured time-of-day window.</summary>
     TimeOfDay = 2,
 }

src/Pam.Domain/Enums/AccessDeciderKind.cs

@@ -5,7 +5,10 @@
 /// </summary>
 public enum AccessDeciderKind : byte
 {
+    /// <summary>A condition on the governing access rule decided, with no human involved.</summary>
     Automatic = 0,
+
+    /// <summary>A human approver decided.</summary>
     Human = 1,
 }
 
@@ -14,6 +17,9 @@ public enum AccessDeciderKind : byte
 /// </summary>
 public enum AccessDecisionVerdict : byte
 {
+    /// <summary>Access was refused.</summary>
     Deny = 0,
+
+    /// <summary>Access was granted.</summary>
     Approve = 1,
 }

src/Pam.Domain/Enums/AccessLeaseStatus.cs

@@ -5,8 +5,13 @@
 /// </summary>
 public enum AccessLeaseStatus : byte
 {
+    /// <summary>Live; within its window it authorizes access.</summary>
     Active = 0,
+
+    /// <summary>The lease's window ended on its own.</summary>
     Expired = 1,
+
+    /// <summary>An operator ended the lease early.</summary>
     Revoked = 2,
 
     /// <summary>The holder ended their own lease early, as opposed to <see cref="Revoked"/> (an operator ended it).</summary>

src/Pam.Domain/Enums/AccessRequestStatus.cs

@@ -6,9 +6,18 @@
 /// </summary>
 public enum AccessRequestStatus : byte
 {
+    /// <summary>Awaiting a human approver's decision.</summary>
     Pending = 0,
+
+    /// <summary>Approved automatically or by an approver; the requester can activate it into a lease within its window.</summary>
     Approved = 1,
+
+    /// <summary>An approver refused the request.</summary>
     Denied = 2,
+
+    /// <summary>Withdrawn by the requester before it was decided.</summary>
     Cancelled = 3,
+
+    /// <summary>The approval window lapsed with no decision recorded.</summary>
     ExpiredUnanswered = 4,
 }

src/Pam.Domain/Models/AccessRequestDetails.cs

@@ -47,6 +47,9 @@ public class AccessRequestDetails
     /// </summary>
     public List<AccessRequestDecision> Decisions { get; set; } = new();
 
+    /// <summary>The requester's display name, denormalized from the User join; null when unset or the user could not be resolved.</summary>
     public string? RequesterName { get; set; }
+
+    /// <summary>The requester's email, the fallback display when <see cref="RequesterName"/> is unset.</summary>
     public string? RequesterEmail { get; set; }
 }