Janady13/missionmatch / internal/modules/matching/intelligence/access.go

1package intelligence 2 3import ( 4 "fmt" 5 "time" 6) 7 8// THE BREAK IN ACCESS CLOCK: whether a cleared person can still be reinstated, or now needs an investigation. 9// 10// This is the fact that decides placeability for a cleared workforce, and it is the one this product could not 11// answer. Two TS/SCI candidates, one three months out of access and one twenty five months out, are entirely 12// different staffing propositions: the first can usually start on a new sponsor's paperwork, the second is 13// months of investigation lead time. missionMATCH rendered them identically. 14// 15// THE RULE, as it actually stands. Since 1 October 2021 DCSA has enrolled DoD clearance holders in Continuous 16// Vetting under Trusted Workforce 2.0, which replaced the five and ten year periodic reinvestigations with 17// ongoing monitoring. Separation pulls a person out of their sponsor's enrollment, and separation is the event 18// the window is measured from. Inside twenty four months, with a favourable adjudication closed within the 19// previous five years, a new employer can usually reinstate without a full reinvestigation. Outside either 20// bound, a new investigation is likely. 21// 22// THIS PACKAGE IS PURE and this file keeps that property: no database, no clock, an explicit asOf. The same 23// inputs produce the same posture every time, which is what lets a staffing decision made in March be 24// reconstructed in June. 25// 26// IT NEVER ASSERTS ELIGIBILITY. Like every other clearance surface in this product, what is computed here is 27// an INDICATOR derived from dates somebody entered. The real determination belongs to the hiring client's 28// facility security officer through DISS, and the language throughout says so. 29 30// AccessPosture is the answer, as a closed vocabulary a screen can branch on. 31type AccessPosture string 32 33const ( 34 // PostureInAccess is somebody currently sponsored and in continuous vetting. No window is running. 35 PostureInAccess AccessPosture = "in_access" 36 // PostureReinstatable is a break inside twenty four months with an adjudication inside five years. 37 PostureReinstatable AccessPosture = "reinstatable" 38 // PostureClosing is inside the window but with ninety days or less left on it. It exists because the 39 // difference between twenty two months and twenty five months is the difference between a placement and a 40 // lost candidate, and a recruiter needs to see it coming rather than discover it. 41 PostureClosing AccessPosture = "closing" 42 // PostureInvestigationLikely is past twenty four months, or an adjudication older than five years. 43 PostureInvestigationLikely AccessPosture = "investigation_likely" 44 // PostureUnknown is the honest answer when the dates were never entered. It is NOT a synonym for a 45 // problem, and it must never be rendered as one: most benches will start here. 46 PostureUnknown AccessPosture = "unknown" 47) 48 49// The two bounds the rule turns on, named rather than inlined so the numbers are findable and so a change in 50// policy is one edit. 51const ( 52 // ReinstatementWindowMonths is the break in access limit for reinstatement without a new investigation. 53 ReinstatementWindowMonths = 24 54 // AdjudicationValidYears is how recent the favourable adjudication must additionally be. 55 AdjudicationValidYears = 5 56 // ClosingSoonDays is how much of the window has to remain before it is called closing. 57 ClosingSoonDays = 90 58) 59 60// AccessFacts is what a candidate row carries about access. Every field is optional because every field is 61// optional in the database, and an absent date is a real state rather than a defect. 62type AccessFacts struct { 63 CVEnrolled *bool 64 AccessEndedOn *time.Time 65 LastAdjudicated *time.Time 66 ClearanceLevel string 67 ClearanceStatus string 68} 69 70// AccessIntel is the derived answer, shaped for a screen. 71type AccessIntel struct { 72 Posture AccessPosture `json:"posture"` 73 // Label is the posture in the words a recruiter uses. 74 Label string `json:"label"` 75 // Detail is the one sentence that explains the posture, including the numbers it turned on, so nobody has 76 // to trust the label alone. 77 Detail string `json:"detail"` 78 // MonthsOutOfAccess is how long the break has run. Absent while somebody is in access or unknown. 79 MonthsOutOfAccess *int `json:"months_out_of_access,omitempty"` 80 // DaysLeftInWindow is how much of the twenty four months remains, negative once it has passed. Absent 81 // when no window is running. 82 DaysLeftInWindow *int `json:"days_left_in_window,omitempty"` 83 // AdjudicationStale reports the second bound failing independently of the first, because a candidate two 84 // months out of access with a six year old adjudication is still an investigation and the reason matters. 85 AdjudicationStale bool `json:"adjudication_stale,omitempty"` 86} 87 88// Access derives the posture as of a given day. 89// 90// THE ORDER OF THE CHECKS IS THE RULE. In access wins over everything, because a person currently sponsored 91// has no window. Then unknown, because a posture computed from absent dates would be fiction. Then the two 92// bounds, adjudication first, because it fails independently of the clock and a recruiter told "past twenty 93// four months" about somebody eight months out would go looking for the wrong thing. 94func Access(f AccessFacts, asOf time.Time) AccessIntel { 95 day := asOf.UTC().Truncate(24 * time.Hour) 96 97 if f.CVEnrolled != nil && *f.CVEnrolled { 98 return AccessIntel{ 99 Posture: PostureInAccess, 100 Label: "In access", 101 Detail: "Currently in continuous vetting through a sponsor, so no break in access clock is " + 102 "running. Continuous vetting replaced periodic reinvestigation in October 2021.", 103 } 104 } 105 106 if f.AccessEndedOn == nil { 107 return AccessIntel{ 108 Posture: PostureUnknown, 109 Label: "Access history not known", 110 Detail: "Nobody has recorded when this person was last in access, so their reinstatement " + 111 "position cannot be worked out. It is not a problem with the candidate, it is a gap in the " + 112 "record.", 113 } 114 } 115 116 ended := f.AccessEndedOn.UTC().Truncate(24 * time.Hour) 117 // monthsBetween already exists in this package with exactly these semantics, calendar months rather than 118 // thirty day blocks. Reused rather than reimplemented: two functions computing the same thing is how they 119 // come to disagree, and at the twenty four month mark a disagreement decides an answer. 120 months := monthsBetween(ended, day) 121 deadline := ended.AddDate(0, ReinstatementWindowMonths, 0) 122 daysLeft := int(deadline.Sub(day).Hours() / 24) 123 124 out := AccessIntel{MonthsOutOfAccess: &months, DaysLeftInWindow: &daysLeft} 125 126 // The adjudication bound, checked first because it fails on its own. 127 if f.LastAdjudicated != nil { 128 if f.LastAdjudicated.UTC().AddDate(AdjudicationValidYears, 0, 0).Before(day) { 129 out.AdjudicationStale = true 130 out.Posture = PostureInvestigationLikely 131 out.Label = "A new investigation is likely" 132 out.Detail = fmt.Sprintf( 133 "The favourable adjudication closed more than %d years ago, so even though the break in "+ 134 "access is %d months, the simple reinstatement path does not apply.", 135 AdjudicationValidYears, months) 136 return out 137 } 138 } 139 140 switch { 141 case daysLeft < 0: 142 out.Posture = PostureInvestigationLikely 143 out.Label = "A new investigation is likely" 144 out.Detail = fmt.Sprintf( 145 "%d months out of access, past the %d month reinstatement window. Expect investigation lead "+ 146 "time rather than a paperwork reinstatement.", months, ReinstatementWindowMonths) 147 case daysLeft <= ClosingSoonDays: 148 out.Posture = PostureClosing 149 out.Label = "Reinstatement window closing" 150 out.Detail = fmt.Sprintf( 151 "%d months out of access, with %d days left of the %d month window. After that a new "+ 152 "investigation is likely.", months, daysLeft, ReinstatementWindowMonths) 153 default: 154 out.Posture = PostureReinstatable 155 out.Label = "Reinstatable" 156 out.Detail = fmt.Sprintf( 157 "%d months out of access, inside the %d month window, so a new sponsor can usually reinstate "+ 158 "without a full reinvestigation.", months, ReinstatementWindowMonths) 159 } 160 return out 161} 162