Implement Stage A: rule engine, validation, audit, and safety gates

Completes 109 of 121 tasks. Every remaining task needs a tenant connection (T055, T056, T101-T103) or an Azure Automation account (T115-T121). 354 offline Pester tests PASS Engine purity (Principle IV) PASS Sanitization (SC-013) PASS (156 files) Graph module loaded in tests none (SC-008 holds) What landed - Four-layer configuration validation with stable finding codes, covering every VR-002 and VR-003 condition, plus a 23-fixture invalid-config corpus - Run loop, audit records (NDJSON through a single sink), summaries, reconciliation, and exit codes 0-6 - Persistence behind a single write-body builder whose result always has exactly one key - Invoke-PersonaEngine.ps1 and Edit-PersonaEngineConfig.ps1 - Six docs, two pipelines, traceability matrix, V-5a and sanitization records Three deviations from tasks.md, each recorded in its status block T033 is not in Resolve-UserPersona. evaluationErrorThreshold is run-level state and the rule engine is pure; a counter there would break Principle IV. It lives in New-PersonaRunCounter and is applied in the run loop. A new src/Engine/ layer holds Invoke-PersonaEngineRun. The entry script imports the manifest, which requires Microsoft.Graph.Authentication, so a loop living only inside it could not run on a machine without the Graph SDK and SC-004 could not be proven at all. The entry script is now a thin wrapper and what ships is what is tested. The invalid-config corpus is generated by a committed script, with the generated fixtures committed too, so a reviewer sees the fixture in the diff. Defects found by running the code, not by reading it Group and role ID lists were double-wrapped: @(Get-PersonaGroupIdPage ...) around a comma-returned array collapsed every membership list into one bogus space-joined entry. That is a silent false non-match, exactly what FR-013 exists to prevent. A 403 whose status appears only in the exception message parsed as $null, which the retry policy treats as a transport error - five requests per account against a tenant already refusing. Status extraction now falls back to the message text, bounded to 400-599. The sanitization scan walked tracked files only, so it covered 34 of 156 files and none of this phase's code. It now scans untracked non-ignored files too, and a negative control confirms it catches a planted leak. Test-Json reports one error per violating location, not first-failure-only as the V-5a draft claimed. Record and pin corrected. Enforcement remains blocked on the V-4 security sign-off. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-20 21:48:19 -04:00
parent c59c85dd55
commit cdc6bb33d3
124 changed files with 16638 additions and 199 deletions
@@ -0,0 +1,127 @@
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+
+<#
+    FR-019, FR-020: interim summaries appear at the configured interval, an interval of
+    0 suppresses them, and a final summary appears in every case.
+
+    The zero case is the one that matters. Suppressing interim output is a reasonable
+    thing to want on a large run; suppressing the final summary too would leave an
+    operator with per-user lines and no totals.
+#>
+
+BeforeAll {
+    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
+    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }
+
+    $script:target = 'extension_<EXTENSION-APP-ID>_<PERSONA>'
+    $script:population = @(New-TestPopulation -Count 20 -TargetAttribute $target)
+}
+
+Describe 'Summary interval semantics (FR-019, FR-020)' {
+
+    BeforeEach {
+        Mock Get-PersonaUsers { $script:population }
+        Mock Write-Host { }
+        Mock Write-PersonaSummary { }
+    }
+
+    It 'emits a final summary and no interim summaries when the interval is 0' {
+        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 0
+
+        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)
+
+        Should -Invoke Write-PersonaSummary -Times 1 -Exactly
+        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
+        Should -Invoke Write-PersonaSummary -Times 0 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
+    }
+
+    It 'emits an interim summary at each interval boundary' {
+        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 5
+
+        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)
+
+        # 20 users at an interval of 5: boundaries at 5, 10, 15, 20.
+        Should -Invoke Write-PersonaSummary -Times 4 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
+        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
+    }
+
+    It 'honours the documented default of 25' {
+        # 20 users at the default interval: no boundary reached, so only the final
+        # summary appears. This is the shape of a small run.
+        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 25
+
+        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)
+
+        Should -Invoke Write-PersonaSummary -Times 0 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
+        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
+    }
+
+    It 'emits one interim summary per user at an interval of 1' {
+        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 1
+
+        $null = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)
+
+        Should -Invoke Write-PersonaSummary -Times 20 -Exactly -ParameterFilter { $SummaryType -eq 'Interim' }
+    }
+
+    It 'emits a final summary even when the population is empty' {
+        Mock Get-PersonaUsers { @() }
+
+        $config = New-TestRuntimeConfiguration -TargetAttribute $target -SummaryInterval 5
+        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $target -Context (New-TestAuditContext)
+
+        Should -Invoke Write-PersonaSummary -Times 1 -Exactly -ParameterFilter { $SummaryType -eq 'Final' }
+        $outcome.Counters.Processed | Should -Be 0
+    }
+}
+
+Describe 'Summary content (FR-019)' {
+
+    It 'lists every rule, including disabled ones and those with no matches' {
+        # A rule that never fired and a rule that is not in the configuration look
+        # identical if zero-match rules are omitted, and that difference is exactly
+        # what an operator investigating a missing classification needs.
+        $rules = @(
+            [pscustomobject]@{ id = 'RULE-0010-OFF'; name = 'Disabled rule'; enabled = $false; priority = 10; persona = 'Guest'
+                match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'UserType'; operator = 'equals'; value = 'Guest' }) } }
+            [pscustomobject]@{ id = 'RULE-0020-NEVER'; name = 'Never matches'; enabled = $true; priority = 20; persona = 'Tier0-Admin'
+                match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'equals'; value = 'NoSuchDepartment' }) } }
+            [pscustomobject]@{ id = 'RULE-0900-EMPLOYEE'; name = 'Employees'; enabled = $true; priority = 900; persona = 'Employee'
+                match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'isNotNull' }) } }
+        )
+
+        $counters = New-PersonaRunCounter -Rules $rules
+
+        $counters.RuleCounts.Count | Should -Be 3
+        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-0010-OFF').Enabled | Should -BeFalse
+        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-0020-NEVER').Matches | Should -Be 0
+    }
+
+    It 'orders rules by priority so the table reads in evaluation order' {
+        $rules = @(
+            [pscustomobject]@{ id = 'C'; name = 'C'; enabled = $true; priority = 900; persona = 'Employee'; match = $null }
+            [pscustomobject]@{ id = 'A'; name = 'A'; enabled = $true; priority = 10; persona = 'Guest'; match = $null }
+            [pscustomobject]@{ id = 'B'; name = 'B'; enabled = $true; priority = 30; persona = 'Tier0-Admin'; match = $null }
+        )
+
+        $counters = New-PersonaRunCounter -Rules $rules
+
+        ($counters.RuleCounts | ForEach-Object RuleId) -join ',' | Should -Be 'A,B,C'
+    }
+
+    It 'increments the matched rule and no other' {
+        $rules = @(
+            [pscustomobject]@{ id = 'RULE-A'; name = 'A'; enabled = $true; priority = 10; persona = 'Guest'; match = $null }
+            [pscustomobject]@{ id = 'RULE-B'; name = 'B'; enabled = $true; priority = 20; persona = 'Employee'; match = $null }
+        )
+
+        $counters = New-PersonaRunCounter -Rules $rules
+
+        Add-PersonaRunResult -Counters $counters -Result ([pscustomobject]@{
+                Outcome = 'Matched'; MatchedRuleId = 'RULE-B'; Action = 'Unchanged' })
+
+        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-A').Matches | Should -Be 0
+        ($counters.RuleCounts | Where-Object RuleId -EQ 'RULE-B').Matches | Should -Be 1
+    }
+}