personaEngine2/tests/Configuration/TraceAcknowledgement.Tests.ps1

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

<#
    VR-003: traceConditionValues without explicit acknowledgement is a safety finding.

    The acknowledgement lives in the configuration rather than in a command-line
    switch, and that placement is the point. A flag passed at the console is invisible
    to review; a field in the configuration appears in the diff of the change that
    enables tracing, next to the person who approved it.
#>

BeforeAll {
    $repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
    . (Join-Path $repoRoot 'tests/TestHelpers.ps1')
    foreach ($file in (Get-PersonaSourceFile -RepoRoot $repoRoot)) { . $file }

    $script:schema = Join-Path $repoRoot 'config/persona-engine.schema.json'
    $script:scratch = Join-Path ([System.IO.Path]::GetTempPath()) ("pe-trace-{0}" -f [guid]::NewGuid().ToString('N'))
    $null = New-Item -ItemType Directory -Path $script:scratch -Force
}

AfterAll {
    Remove-Item -LiteralPath $script:scratch -Recurse -Force -ErrorAction SilentlyContinue
}

Describe 'Tracing acknowledgement (VR-003)' {

    It 'produces PE-SAF-006 when tracing is on and acknowledgement is absent' {
        $document = New-TestConfigurationDocument
        $document.logging = @{ destination = 'stream'; traceConditionValues = $true }

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.IsValid | Should -BeFalse
        $result.Findings.Code | Should -Contain 'PE-SAF-006'
    }

    It 'produces PE-SAF-006 when acknowledgement is present but false' {
        $document = New-TestConfigurationDocument
        $document.logging = @{ destination = 'stream'; traceConditionValues = $true; acknowledgeConditionTracing = $false }

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.Findings.Code | Should -Contain 'PE-SAF-006'
    }

    It 'accepts tracing when acknowledgement is true' {
        $document = New-TestConfigurationDocument
        $document.logging = @{ destination = 'stream'; traceConditionValues = $true; acknowledgeConditionTracing = $true }

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.IsValid | Should -BeTrue
        $result.Findings.Code | Should -Not -Contain 'PE-SAF-006'
    }

    It 'does not require acknowledgement when tracing is off' {
        # Acknowledging something that is not happening would train people to set the
        # field reflexively, which is how an acknowledgement stops meaning anything.
        $document = New-TestConfigurationDocument
        $document.logging = @{ destination = 'stream'; traceConditionValues = $false }

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.IsValid | Should -BeTrue
        $result.Findings.Code | Should -Not -Contain 'PE-SAF-006'
    }

    It 'blocks the run: the finding is an Error, not a Warning' {
        $document = New-TestConfigurationDocument
        $document.logging = @{ destination = 'stream'; traceConditionValues = $true }

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        ($result.Findings | Where-Object Code -EQ 'PE-SAF-006').Severity | Should -Be 'Error'
    }

    It 'explains what tracing actually widens, not merely that it is enabled' {
        $document = New-TestConfigurationDocument
        $document.logging = @{ destination = 'stream'; traceConditionValues = $true }

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $finding = (Test-PersonaConfiguration -Path $path -SchemaPath $script:schema).Findings |
            Where-Object Code -EQ 'PE-SAF-006'

        $finding.Description | Should -Match 'attribute values'
        $finding.SuggestedResolution | Should -Match 'acknowledgeConditionTracing'
    }
}

Describe 'The schema accepts the acknowledgement field' {

    It 'validates a configuration carrying acknowledgeConditionTracing' {
        # additionalProperties is false on the logging block, so the field has to be
        # declared in the schema or the acknowledgement itself becomes a schema error.
        $document = New-TestConfigurationDocument
        $document.logging = @{ destination = 'both'; path = '<LOG-OUTPUT-PATH>'; traceConditionValues = $true; acknowledgeConditionTracing = $true }

        $path = Save-TestConfiguration -Document $document -Directory $script:scratch
        $result = Test-PersonaConfiguration -Path $path -SchemaPath $script:schema

        $result.Findings.Code | Should -Not -Contain 'PE-SCH-001'
    }
}