personaEngine2/tests/Unit/AuditCompleteness.Tests.ps1

#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }

<#
    SC-006, NFR-005: 100% of user events carry run ID, UPN, and Account Object ID, and
    100% of matched results carry a rule ID.

    "100%" is asserted across a whole run rather than on a single hand-built record.
    A record builder can be correct in isolation and still be called wrongly on one
    branch, and the branch that gets missed is invariably the error path - which is
    the one an auditor will ask about.
#>

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:runId = '00000000-0000-0000-0000-00000000f001'

    $script:rules = @(
        (New-TestMembershipRule)
        [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' })
            }
        }
    )

    $script:config = New-TestRuntimeConfiguration -TargetAttribute $target -Rules $script:rules
}

Describe 'Audit completeness across a full run (SC-006)' {

    BeforeAll {
        Mock Get-PersonaUsers { @(New-TestPopulation -Count 24 -TargetAttribute $script:target) }
        Mock Write-Host { }
        Mock Set-UserPersonaAttribute { [pscustomobject]@{ Succeeded = $true } }

        # A mixed run: some lookups fail so EvaluationError records are produced too.
        $script:lookup = 0
        Mock Get-PersonaGroupMembership {
            $script:lookup++
            ($script:lookup % 4) -eq 0 `
                ? (New-PersonaMembershipRecord -DirectFailureReason 'Graph 503 after 5 attempts') `
                : (New-PersonaMembershipRecord -AllRetrieved)
        }

        $info = $null
        $script:outcome = Invoke-PersonaEngineRun -Configuration $script:config -TargetAttribute $script:target `
            -Context (New-TestAuditContext -Mode 'Enforce' -RunId $script:runId) `
            -AuditParameters @{ Destination = 'stream' } `
            -IsEnforcing -ShouldProcessGate { param($t, $d) $true } `
            -InformationVariable info

        $script:records = Get-CapturedAuditRecord -Captured $info
        $script:userEvents = Get-CapturedAuditRecord -Captured $info -RecordType 'UserEvent'
    }

    It 'emits one UserEvent per processed user' {
        $script:userEvents.Count | Should -Be $script:outcome.Counters.Processed
    }

    It 'carries the run ID on every record, not only user events' {
        foreach ($record in $script:records) {
            $record['runId'] | Should -Be $script:runId
        }
    }

    It 'carries the UPN and Account Object ID on every user event' {
        foreach ($event in $script:userEvents) {
            $event['userPrincipalName'] | Should -Not -BeNullOrEmpty
            $event['accountObjectId'] | Should -Not -BeNullOrEmpty
        }
    }

    It 'carries a matched rule ID on every Matched record' {
        $matched = @($script:userEvents | Where-Object { $_['outcome'] -eq 'Matched' })

        $matched.Count | Should -BeGreaterThan 0
        foreach ($event in $matched) {
            $event['matchedRuleId'] | Should -Not -BeNullOrEmpty
        }
    }

    It 'carries an evaluationErrorReason on exactly the EvaluationError records' {
        $errors = @($script:userEvents | Where-Object { $_['outcome'] -eq 'EvaluationError' })
        $errors.Count | Should -BeGreaterThan 0

        foreach ($event in $script:userEvents) {
            if ($event['outcome'] -eq 'EvaluationError') {
                $event['evaluationErrorReason'] | Should -Not -BeNullOrEmpty
            }
            else {
                $event['evaluationErrorReason'] | Should -BeNullOrEmpty
            }
        }
    }

    It 'carries the configuration version and hash on every record' {
        foreach ($record in $script:records) {
            $record['configVersion'] | Should -Be '1.0.0'
            $record['configurationHash'] | Should -Not -BeNullOrEmpty
        }
    }

    It 'carries the mode on every record' {
        foreach ($record in $script:records) {
            $record['mode'] | Should -Be 'Enforce'
        }
    }

    It 'carries an ISO 8601 UTC timestamp on every record' {
        foreach ($record in $script:records) {
            $record['timestamp'] | Should -Match '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$'
        }
    }

    It 'records previousValue on every Updated event and on no other' {
        # Captured at write time. Without it, OTD-010 rollback is impossible
        # retroactively - no later run can reconstruct what a value used to be.
        $updated = @($script:userEvents | Where-Object { $_['action'] -eq 'Updated' })
        $updated.Count | Should -BeGreaterThan 0

        foreach ($event in $script:userEvents) {
            if ($event['action'] -eq 'Updated') {
                $event.Contains('previousValue') | Should -BeTrue
            }
            else {
                $event['previousValue'] | Should -BeNullOrEmpty
            }
        }
    }

    It 'emits exactly one outcome value per user event' {
        foreach ($event in $script:userEvents) {
            $event['outcome'] | Should -BeIn @('Matched', 'Unclassified', 'EvaluationError')
        }
    }
}

Describe 'Run report completeness' {

    It 'produces a RunComplete record carrying the counters and the exit code' {
        $counters = New-PersonaRunCounter -Rules $script:rules
        $counters.Processed = 10
        $counters.Matched = 8
        $counters.Unclassified = 2

        $record = Export-PersonaRunReport -Context (New-TestAuditContext) -Counters $counters `
            -StartedUtc ([DateTime]::UtcNow.AddMinutes(-5)) -ExitCode 0

        $record['recordType'] | Should -Be 'RunComplete'
        $record['processed'] | Should -Be 10
        $record['exitCode'] | Should -Be 0
        $record['reconciliationPassed'] | Should -BeTrue
        $record['startedUtc'] | Should -Match '^\d{4}-\d{2}-\d{2}T'
        $record['completedUtc'] | Should -Match '^\d{4}-\d{2}-\d{2}T'
        $record['durationMs'] | Should -BeGreaterThan 0
    }

    It 'refuses an exit code outside the documented range' {
        $counters = New-PersonaRunCounter -Rules @()

        { Export-PersonaRunReport -Context (New-TestAuditContext) -Counters $counters `
                -StartedUtc ([DateTime]::UtcNow) -ExitCode 9 } | Should -Throw
    }
}