personaEngine2/tests/Safety/WriteGate.Tests.ps1

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

<#
    FR-016: a write is issued only when all four conditions hold.

        1. Evaluation completed successfully (Outcome is not EvaluationError)
        2. Calculated differs from stored, ordinal comparison
        3. The target attribute is non-blank and approved
        4. ShouldProcess returned true for this user

    Each condition is tested in isolation by failing exactly that one, so a passing
    result cannot be explained by a different condition having blocked the write.
#>

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>'

    function New-Decision {
        param(
            [string] $Outcome = 'Matched',
            [AllowNull()] [string] $Calculated = 'Tier0-Admin',
            [AllowNull()] [string] $Stored = 'Employee',
            [string] $ErrorReason = $null
        )

        [pscustomobject]@{
            AccountObjectId       = '00000000-0000-0000-0000-000000000101'
            UserPrincipalName     = 'alex@example.invalid'
            Outcome               = $Outcome
            MatchedRuleId         = 'RULE-0030-TIER0'
            CalculatedPersona     = $Calculated
            StoredPersona         = $Stored
            Action                = 'Pending'
            EvaluationErrorReason = $ErrorReason
            RulesEvaluated        = 2
            DurationMs            = 4
            ConditionTrace        = $null
        }
    }
}

Describe 'Condition 1 - evaluation must have succeeded' -Tag 'Safety' {

    It 'skips an EvaluationError user even when the values differ' {
        $result = Compare-PersonaValue -Result (New-Decision -Outcome 'EvaluationError' -Calculated $null -ErrorReason 'lookup failed') `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @($target)

        $result.Action | Should -Be 'Skipped'
    }

    It 'preserves the stored value on an EvaluationError user (FR-014)' {
        $result = Compare-PersonaValue -Result (New-Decision -Outcome 'EvaluationError' -Calculated $null -Stored 'Tier0-Admin' -ErrorReason 'lookup failed') `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @($target)

        $result.StoredPersona | Should -Be 'Tier0-Admin'
        $result.Action | Should -Be 'Skipped'
    }

    It 'never reaches the write adapter for an EvaluationError user' {
        Mock Write-Host { }
        Mock Set-UserPersonaAttribute { [pscustomobject]@{ Succeeded = $true } }
        Mock Get-PersonaUsers { @(New-TestPopulation -Count 8 -TargetAttribute $script:target) }
        Mock Get-PersonaGroupMembership { New-PersonaMembershipRecord -DirectFailureReason 'Graph 503 after 5 attempts' }

        $config = New-TestRuntimeConfiguration -TargetAttribute $script:target -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' }) }
            })

        $outcome = Invoke-PersonaEngineRun -Configuration $config -TargetAttribute $script:target `
            -Context (New-TestAuditContext -Mode 'Enforce') -IsEnforcing `
            -ShouldProcessGate { param($t, $d) $true }

        $outcome.Counters.EvaluationError | Should -Be $outcome.Counters.Processed
        Should -Invoke Set-UserPersonaAttribute -Times 0 -Exactly
    }
}

Describe 'Condition 2 - the value must actually differ' -Tag 'Safety' {

    It 'reports Unchanged when stored and calculated are identical' {
        $result = Compare-PersonaValue -Result (New-Decision -Calculated 'Employee' -Stored 'Employee') `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @($target)

        $result.Action | Should -Be 'Unchanged'
    }

    It 'treats a case-only difference as a real change' {
        # Change detection is ordinal (FR-015). Treating these as equal would leave the
        # directory permanently inconsistent with the rule set.
        $result = Compare-PersonaValue -Result (New-Decision -Calculated 'Employee' -Stored 'employee') `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @($target)

        $result.Action | Should -Be 'Updated'
    }

    It 'treats a blank stored value against a calculated persona as a change' {
        $result = Compare-PersonaValue -Result (New-Decision -Calculated 'Employee' -Stored '') `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @($target)

        $result.Action | Should -Be 'Updated'
    }

    It 'treats a null stored value as equal to an empty calculated value' {
        $result = Compare-PersonaValue -Result (New-Decision -Calculated '' -Stored $null) `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @($target)

        $result.Action | Should -Be 'Unchanged'
    }
}

Describe 'Condition 3 - the target must be valid and approved' -Tag 'Safety' {

    It 'skips when the target attribute is blank' {
        $result = Compare-PersonaValue -Result (New-Decision) `
            -IsEnforcing -TargetAttribute '' -ApprovedWritableAttributes @($target)

        $result.Action | Should -Be 'Skipped'
    }

    It 'skips when the target is absent from the approved list' {
        $result = Compare-PersonaValue -Result (New-Decision) `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @('extension_<EXTENSION-APP-ID>_<OTHER>')

        $result.Action | Should -Be 'Skipped'
    }

    It 'skips when the approved list is empty' {
        $result = Compare-PersonaValue -Result (New-Decision) `
            -IsEnforcing -TargetAttribute $target -ApprovedWritableAttributes @()

        $result.Action | Should -Be 'Skipped'
    }
}

Describe 'Condition 4 - the gate must have returned true' -Tag 'Safety' {

    It 'reports WouldUpdate rather than Updated when not enforcing' {
        $result = Compare-PersonaValue -Result (New-Decision) `
            -TargetAttribute $target -ApprovedWritableAttributes @($target)

        $result.Action | Should -Be 'WouldUpdate'
    }

    It 'downgrades Updated to WouldUpdate when the per-user gate refuses' {
        Mock Write-Host { }
        Mock Set-UserPersonaAttribute { [pscustomobject]@{ Succeeded = $true } }
        Mock Get-PersonaUsers { @(New-TestPopulation -Count 12 -TargetAttribute $script:target) }

        $outcome = Invoke-PersonaEngineRun `
            -Configuration (New-TestRuntimeConfiguration -TargetAttribute $script:target) `
            -TargetAttribute $script:target -Context (New-TestAuditContext -Mode 'Enforce') `
            -IsEnforcing -ShouldProcessGate { param($t, $d) $false }

        $outcome.Counters.Updated | Should -Be 0
        $outcome.Counters.WouldUpdate | Should -BeGreaterThan 0
        Should -Invoke Set-UserPersonaAttribute -Times 0 -Exactly
    }

    It 'reports UpdateFailed when the gate allowed the write but the PATCH failed' {
        Mock Write-Host { }
        Mock Get-PersonaUsers { @(New-TestPopulation -Count 12 -TargetAttribute $script:target) }
        Mock Set-UserPersonaAttribute { [pscustomobject]@{ Succeeded = $false; FailureReason = 'Response status code does not indicate success: 403 (Forbidden).' } }

        $outcome = Invoke-PersonaEngineRun `
            -Configuration (New-TestRuntimeConfiguration -TargetAttribute $script:target) `
            -TargetAttribute $script:target -Context (New-TestAuditContext -Mode 'Enforce') `
            -IsEnforcing -ShouldProcessGate { param($t, $d) $true }

        $outcome.Counters.UpdateFailed | Should -BeGreaterThan 0
        $outcome.Counters.Updated | Should -Be 0
    }

    It 'continues the run after a failed write rather than abandoning the population' {
        Mock Write-Host { }
        Mock Get-PersonaUsers { @(New-TestPopulation -Count 12 -TargetAttribute $script:target) }
        Mock Set-UserPersonaAttribute { [pscustomobject]@{ Succeeded = $false; FailureReason = 'Forbidden' } }

        $outcome = Invoke-PersonaEngineRun `
            -Configuration (New-TestRuntimeConfiguration -TargetAttribute $script:target) `
            -TargetAttribute $script:target -Context (New-TestAuditContext -Mode 'Enforce') `
            -IsEnforcing -ShouldProcessGate { param($t, $d) $true }

        $outcome.Counters.Processed | Should -Be 12
    }
}