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
+103
View File
@@ -0,0 +1,103 @@
#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'
'src/RuleEngine/Test-PersonaRule.ps1'
'src/RuleEngine/Resolve-UserPersona.ps1'
)) { . (Join-Path $repoRoot $f) }
$script:fixtures = (Get-Content (Join-Path $repoRoot 'tests/TestData/Users/users.json') -Raw | ConvertFrom-Json).users
$script:users = foreach ($f in $fixtures) {
$props = @{}
foreach ($p in $f.properties.PSObject.Properties) { $props[$p.Name] = $p.Value }
New-PersonaUserRecord `
-AccountObjectId $f.accountObjectId `
-UserPrincipalName $f.userPrincipalName `
-DisplayName $f.displayName `
-UserType $f.userType `
-AccountEnabled $f.accountEnabled `
-Properties $props `
-StoredPersona $f.storedPersona
}
$script:rules = @(
[pscustomobject]@{
id = 'R-020'; priority = 20; persona = 'Guest'; enabled = $true
match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'UserType'; operator = 'equals'; value = 'Guest' }) }
}
[pscustomobject]@{
id = 'R-040'; priority = 40; persona = 'Service-Account'; enabled = $true
match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'UserPrincipalName'; operator = 'startsWith'; value = 'svc-' }) }
}
[pscustomobject]@{
id = 'R-900'; priority = 900; persona = 'Employee'; enabled = $true
match = [pscustomobject]@{ operator = 'all'; conditions = @([pscustomobject]@{ type = 'property'; property = 'Department'; operator = 'isNotNull' }) }
}
)
function Get-DecisionSignature {
param([object[]] $Users, [object[]] $RuleSet)
# Deliberately excludes DurationMs: timing is telemetry, not part of the
# decision, and including it would make this test measure the clock.
($Users | ForEach-Object {
$r = Resolve-UserPersona -UserRecord $_ -Rules $RuleSet
'{0}|{1}|{2}|{3}' -f $r.AccountObjectId, $r.Outcome, $r.CalculatedPersona, $r.MatchedRuleId
} | Sort-Object) -join "`n"
}
}
Describe 'Determinism (SC-003)' {
It 'produces identical results across repeated runs' {
$first = Get-DecisionSignature -Users $users -RuleSet $rules
$second = Get-DecisionSignature -Users $users -RuleSet $rules
$second | Should -Be $first
}
It 'produces identical results when the user collection is shuffled' {
$ordered = Get-DecisionSignature -Users $users -RuleSet $rules
foreach ($seed in 1..5) {
$shuffled = $users | Sort-Object { ($_.AccountObjectId + $seed).GetHashCode() }
Get-DecisionSignature -Users $shuffled -RuleSet $rules | Should -Be $ordered
}
}
It 'produces identical results when the rule collection is shuffled' {
$ordered = Get-DecisionSignature -Users $users -RuleSet $rules
foreach ($seed in 1..5) {
$shuffled = $rules | Sort-Object { ($_.id + $seed).GetHashCode() }
Get-DecisionSignature -Users $users -RuleSet $shuffled | Should -Be $ordered
}
}
It 'assigns exactly one outcome to every fixture (SC-001)' {
foreach ($u in $users) {
$r = Resolve-UserPersona -UserRecord $u -Rules $rules
$r.Outcome | Should -BeIn @('Matched', 'Unclassified', 'EvaluationError')
}
}
}
Describe 'Offline execution (SC-008)' {
It 'evaluates every fixture without any network-capable command in the engine' {
# The structural guarantee is enforced by tests/Test-EnginePurity.ps1. This
# asserts the practical consequence: the engine runs with nothing loaded but
# its own files.
$results = $users | ForEach-Object { Resolve-UserPersona -UserRecord $_ -Rules $rules }
$results | Should -HaveCount $users.Count
}
It 'has not loaded the Graph authentication module' {
(Get-Module -Name 'Microsoft.Graph.Authentication') | Should -BeNullOrEmpty
}
}