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,221 @@
+#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
+
+<#
+    Each record type matches contracts/audit-record.md.
+
+    The contract is what downstream ingestion will be written against, so a field
+    quietly renamed here breaks a consumer that this repository never sees. These
+    tests are the contract's enforcement.
+#>
+
+BeforeAll {
+    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
+    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
+    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }
+
+    $script:envelope = @('timestamp', 'recordType', 'runId', 'engineVersion', 'configVersion', 'configurationHash', 'mode')
+
+    $script:counterFields = @('processed', 'matched', 'unclassified', 'evaluationError',
+        'unchanged', 'wouldUpdate', 'updated', 'updateFailed', 'skipped', 'reconciliationPassed')
+
+    function New-Result {
+        param(
+            [string] $Outcome = 'Matched',
+            [string] $Action = 'Unchanged',
+            [string] $MatchedRuleId = 'RULE-0010-GUEST',
+            [string] $ErrorReason = $null
+        )
+
+        [pscustomobject]@{
+            AccountObjectId       = '00000000-0000-0000-0000-000000000101'
+            UserPrincipalName     = 'alex@example.invalid'
+            Outcome               = $Outcome
+            MatchedRuleId         = $MatchedRuleId
+            CalculatedPersona     = 'Guest'
+            StoredPersona         = 'Employee'
+            Action                = $Action
+            EvaluationErrorReason = $ErrorReason
+            RulesEvaluated        = 3
+            DurationMs            = 12
+            ConditionTrace        = $null
+        }
+    }
+}
+
+Describe 'Common envelope' {
+
+    It 'appears on every record type' {
+        $counters = New-PersonaRunCounter -Rules @()
+        $context = New-TestAuditContext
+
+        $records = @(
+            New-PersonaAuditRecord -Context $context -RecordType 'RunStart'
+            New-PersonaAuditRecord -Context $context -RecordType 'UserEvent' -Result (New-Result)
+            New-PersonaAuditRecord -Context $context -RecordType 'Summary' -Counters $counters
+            New-PersonaAuditRecord -Context $context -RecordType 'EngineDefect' -Properties @{ severity = 'Error' }
+            Export-PersonaRunReport -Context $context -Counters $counters -StartedUtc ([DateTime]::UtcNow) -ExitCode 0
+        )
+
+        foreach ($record in $records) {
+            foreach ($field in $script:envelope) {
+                $record.Contains($field) | Should -BeTrue -Because "$($record['recordType']) must carry '$field'"
+            }
+        }
+    }
+
+    It 'places the envelope first, so a truncated line still identifies the run' {
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' -Result (New-Result)
+
+        @($record.Keys)[0..6] | Should -Be $script:envelope
+    }
+}
+
+Describe 'UserEvent shape' {
+
+    It 'carries every documented field' {
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' -Result (New-Result)
+
+        foreach ($field in @('accountObjectId', 'userPrincipalName', 'outcome', 'matchedRuleId',
+                'storedPersona', 'calculatedPersona', 'previousValue', 'action',
+                'rulesEvaluated', 'durationMs', 'evaluationErrorReason')) {
+            $record.Contains($field) | Should -BeTrue -Because "the contract names '$field'"
+        }
+    }
+
+    It 'populates previousValue only on an Updated action' {
+        $updated = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' `
+            -Result (New-Result -Action 'Updated') -PreviousValue 'Employee'
+
+        $wouldUpdate = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' `
+            -Result (New-Result -Action 'WouldUpdate') -PreviousValue 'Employee'
+
+        $updated['previousValue'] | Should -Be 'Employee'
+        $wouldUpdate['previousValue'] | Should -BeNullOrEmpty
+    }
+
+    It 'carries a null matchedRuleId on an Unclassified record' {
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' `
+            -Result (New-Result -Outcome 'Unclassified' -MatchedRuleId $null)
+
+        $record['outcome'] | Should -Be 'Unclassified'
+        $record['matchedRuleId'] | Should -BeNullOrEmpty
+    }
+
+    It 'carries an evaluationErrorReason on an EvaluationError record' {
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' `
+            -Result (New-Result -Outcome 'EvaluationError' -MatchedRuleId $null -Action 'Skipped' -ErrorReason 'membership lookup failed')
+
+        $record['evaluationErrorReason'] | Should -Be 'membership lookup failed'
+    }
+
+    It 'omits conditionTrace unless tracing is explicitly requested' {
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' -Result (New-Result)
+
+        $record.Contains('conditionTrace') | Should -BeFalse
+    }
+
+    It 'refuses to build a UserEvent without a result' {
+        { New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'UserEvent' } | Should -Throw
+    }
+}
+
+Describe 'Summary shape' {
+
+    It 'carries the summary type, counters, and rule counts' {
+        $rules = @(
+            [pscustomobject]@{ id = 'RULE-0010'; name = 'Guests'; enabled = $true; priority = 10; persona = 'Guest'; match = $null }
+            [pscustomobject]@{ id = 'RULE-0020'; name = 'Disabled'; enabled = $false; priority = 20; persona = 'Employee'; match = $null }
+        )
+        $counters = New-PersonaRunCounter -Rules $rules
+
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'Summary' `
+            -Counters $counters -Properties @{ summaryType = 'Interim' }
+
+        $record['summaryType'] | Should -Be 'Interim'
+        foreach ($field in $script:counterFields) { $record.Contains($field) | Should -BeTrue }
+
+        $record['ruleCounts'].Count | Should -Be 2
+        $record['ruleCounts'][0]['ruleId'] | Should -Be 'RULE-0010'
+        $record['ruleCounts'][1]['enabled'] | Should -BeFalse
+    }
+
+    It 'defaults to Interim when no summary type is given' {
+        $record = New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'Summary' `
+            -Counters (New-PersonaRunCounter -Rules @())
+
+        $record['summaryType'] | Should -Be 'Interim'
+    }
+
+    It 'refuses to build a Summary without counters' {
+        { New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'Summary' } | Should -Throw
+    }
+}
+
+Describe 'RunComplete shape' {
+
+    It 'carries the timing fields, counters, and exit code' {
+        $record = Export-PersonaRunReport -Context (New-TestAuditContext) `
+            -Counters (New-PersonaRunCounter -Rules @()) -StartedUtc ([DateTime]::UtcNow.AddSeconds(-3)) -ExitCode 4
+
+        foreach ($field in (@('startedUtc', 'completedUtc', 'durationMs', 'exitCode') + $script:counterFields)) {
+            $record.Contains($field) | Should -BeTrue
+        }
+
+        $record['exitCode'] | Should -Be 4
+    }
+}
+
+Describe 'NDJSON serialization' {
+
+    It 'writes one record per line to file' {
+        $path = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-ndjson-{0}.log" -f [guid]::NewGuid().ToString('N'))
+        $context = New-TestAuditContext
+
+        try {
+            1..3 | ForEach-Object {
+                New-PersonaAuditRecord -Context $context -RecordType 'UserEvent' -Result (New-Result) |
+                    Write-PersonaAuditRecord -Destination 'file' -Path $path
+            }
+
+            $lines = @(Get-Content -LiteralPath $path)
+            $lines.Count | Should -Be 3
+
+            foreach ($line in $lines) {
+                $line | Should -Not -Match "`n"
+                { $line | ConvertFrom-Json } | Should -Not -Throw
+                ($line | ConvertFrom-Json).recordType | Should -Be 'UserEvent'
+            }
+        }
+        finally { Remove-Item -LiteralPath $path -Force -ErrorAction SilentlyContinue }
+    }
+
+    It 'emits nothing when the destination is none' {
+        $path = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-none-{0}.log" -f [guid]::NewGuid().ToString('N'))
+
+        New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'RunStart' |
+            Write-PersonaAuditRecord -Destination 'none' -Path $path
+
+        Test-Path -LiteralPath $path | Should -BeFalse
+    }
+
+    It 'warns once and keeps running when the file sink fails' {
+        # A locked log file is an operational problem with the sink, not a reason to
+        # abandon a run mid-population and leave the directory half-reconciled.
+        $state = New-PersonaAuditSinkState
+        $badPath = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-bad-{0}" -f [guid]::NewGuid().ToString('N'))
+        $null = New-Item -ItemType Directory -Path $badPath -Force
+
+        try {
+            $warnings = @()
+            1..5 | ForEach-Object {
+                New-PersonaAuditRecord -Context (New-TestAuditContext) -RecordType 'RunStart' |
+                    Write-PersonaAuditRecord -Destination 'file' -Path $badPath -State $state 3>&1 |
+                    ForEach-Object { $warnings += $_ }
+            }
+
+            $state.FileSinkFailed | Should -BeTrue
+            @($warnings).Count | Should -Be 1
+        }
+        finally { Remove-Item -LiteralPath $badPath -Recurse -Force -ErrorAction SilentlyContinue }
+    }
+}