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>
This commit is contained in:
2026-08-20 21:48:19 -04:00
parent c59c85dd55
commit cdc6bb33d3
124 changed files with 16638 additions and 199 deletions
@@ -0,0 +1,99 @@
#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '5.0.0' }
BeforeAll {
$repoRoot = Split-Path (Split-Path $PSScriptRoot -Parent) -Parent
foreach ($f in @(
'src/Normalization/New-PersonaMembershipRecord.ps1'
'src/Normalization/New-PersonaUserRecord.ps1'
'src/RuleEngine/Test-PersonaCondition.ps1'
'src/RuleEngine/Test-PersonaConditionGroup.ps1'
)) { . (Join-Path $repoRoot $f) }
# A user whose membership lookup failed: any membership condition against this
# record yields Unknown, which is how these tests inject the tri-state.
$script:user = New-PersonaUserRecord `
-AccountObjectId '00000000-0000-0000-0000-000000000101' `
-UserPrincipalName 'alex.employee@example.invalid' `
-Properties @{ Department = 'Finance' } `
-Membership (New-PersonaMembershipRecord -DirectFailureReason 'Graph 503 after 5 attempts')
$script:TRUE_COND = [pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'equals'; value = 'Finance' }
$script:FALSE_COND = [pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'equals'; value = 'Legal' }
$script:UNKNOWN_COND = [pscustomobject]@{ type = 'membership'; operator = 'memberOf'; groupObjectIds = @('00000000-0000-0000-0000-0000000000a0') }
function Eval {
param([string] $Operator, [object[]] $Conditions)
Test-PersonaConditionGroup -Group ([pscustomobject]@{ operator = $Operator; conditions = $Conditions }) -UserRecord $user
}
}
Describe 'Unknown propagation table (data-model.md)' {
Context 'the injected conditions behave as intended' {
It 'TRUE_COND is True' { Test-PersonaCondition -Condition $TRUE_COND -UserRecord $user | Should -Be 'True' }
It 'FALSE_COND is False' { Test-PersonaCondition -Condition $FALSE_COND -UserRecord $user | Should -Be 'False' }
It 'UNKNOWN_COND is Unknown' { Test-PersonaCondition -Condition $UNKNOWN_COND -UserRecord $user | Should -Be 'Unknown' }
}
Context 'row 1: all + any False -> False' {
It 'a definite non-match decides the group despite an unknown sibling' {
# The rule cannot match either way, so degrading to Unknown here would
# manufacture EvaluationErrors for rules that were never going to match.
Eval 'all' @($FALSE_COND, $UNKNOWN_COND) | Should -Be 'False'
}
It 'holds regardless of sibling order' {
Eval 'all' @($UNKNOWN_COND, $FALSE_COND) | Should -Be 'False'
}
}
Context 'row 2: all + only True and Unknown -> Unknown' {
It 'cannot confirm a match' {
Eval 'all' @($TRUE_COND, $UNKNOWN_COND) | Should -Be 'Unknown'
}
It 'holds regardless of sibling order' {
Eval 'all' @($UNKNOWN_COND, $TRUE_COND) | Should -Be 'Unknown'
}
}
Context 'row 3: any + any True -> True' {
It 'a definite match decides the group despite an unknown sibling' {
Eval 'any' @($TRUE_COND, $UNKNOWN_COND) | Should -Be 'True'
}
It 'holds regardless of sibling order' {
Eval 'any' @($UNKNOWN_COND, $TRUE_COND) | Should -Be 'True'
}
}
Context 'row 4: any + only False and Unknown -> Unknown' {
It 'cannot rule out a match' {
Eval 'any' @($FALSE_COND, $UNKNOWN_COND) | Should -Be 'Unknown'
}
It 'holds regardless of sibling order' {
Eval 'any' @($UNKNOWN_COND, $FALSE_COND) | Should -Be 'Unknown'
}
}
Context 'no-unknown baselines' {
It 'all with only True is True' { Eval 'all' @($TRUE_COND, $TRUE_COND) | Should -Be 'True' }
It 'all with a False is False' { Eval 'all' @($TRUE_COND, $FALSE_COND) | Should -Be 'False' }
It 'any with a True is True' { Eval 'any' @($FALSE_COND, $TRUE_COND) | Should -Be 'True' }
It 'any with only False is False' { Eval 'any' @($FALSE_COND, $FALSE_COND) | Should -Be 'False' }
}
Context 'propagation through nesting' {
It 'carries Unknown up from a nested group' {
$inner = [pscustomobject]@{ operator = 'all'; conditions = @($TRUE_COND, $UNKNOWN_COND) }
Eval 'all' @($TRUE_COND, $inner) | Should -Be 'Unknown'
}
It 'lets a definite False at the outer level still decide the group' {
$inner = [pscustomobject]@{ operator = 'all'; conditions = @($TRUE_COND, $UNKNOWN_COND) }
Eval 'all' @($FALSE_COND, $inner) | Should -Be 'False'
}
It 'lets a definite True at the outer level still decide an any group' {
$inner = [pscustomobject]@{ operator = 'any'; conditions = @($FALSE_COND, $UNKNOWN_COND) }
Eval 'any' @($TRUE_COND, $inner) | Should -Be 'True'
}
}
}