dave
cdc6bb33d3
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>
4.2 KiB
Contract: Structured Audit Records
Serialized form of the audit trail (FR-022, NFR-005, Principle V). Format is newline-delimited JSON,
one record per line (OTD-006). All emission goes through a single Write-PersonaAuditRecord sink so
a future transport can be added without touching call sites.
Common envelope
Every record carries:
| Field | Type | Notes |
|---|---|---|
timestamp |
string (ISO 8601 UTC) | |
recordType |
string | RunStart, UserEvent, Summary, RunComplete, EngineDefect |
runId |
string (GUID) | Constant for the run (NFR-005) |
engineVersion |
string | |
configVersion |
string | |
configurationHash |
string | SHA-256 of the configuration file |
mode |
string | Preview or Enforce |
UserEvent
Emitted once per processed user. 100% of these records carry runId, userPrincipalName, and
accountObjectId (SC-006).
{
"timestamp": "2026-08-20T09:14:02.187Z",
"recordType": "UserEvent",
"runId": "<RUN-ID>",
"engineVersion": "1.0.0",
"configVersion": "1.4.0",
"configurationHash": "<SHA256>",
"mode": "Preview",
"accountObjectId": "<ACCOUNT-OBJECT-ID>",
"userPrincipalName": "<USER>@<PRIMARY-DOMAIN>",
"outcome": "Matched",
"matchedRuleId": "RULE-0100-TIER0",
"storedPersona": "Employee",
"calculatedPersona": "Tier0-Admin",
"previousValue": "Employee",
"action": "WouldUpdate",
"rulesEvaluated": 4,
"durationMs": 38,
"evaluationErrorReason": null
}
Field requirements
| Field | Requirement |
|---|---|
outcome |
Exactly one of Matched, Unclassified, EvaluationError (SC-001) |
matchedRuleId |
Non-null on every Matched record (SC-006) |
previousValue |
Captured at write time on every Updated record. This is what makes OTD-010 rollback possible; omitting it in v1 makes rollback impossible retroactively |
evaluationErrorReason |
Non-null exactly when outcome is EvaluationError |
Prohibited fields: access tokens, Authorization headers, secrets, and full Graph responses
MUST NEVER appear in any record.
Condition tracing: a conditionTrace array may be added only under -Debug
(logging.traceConditionValues). It contains diagnostic condition-level values and is therefore
gated by acknowledgement (VR-003).
Summary
Emitted every summaryInterval users and once at completion.
{
"recordType": "Summary",
"runId": "<RUN-ID>",
"summaryType": "Interim",
"processed": 250,
"matched": 231,
"unclassified": 14,
"evaluationError": 5,
"unchanged": 220,
"wouldUpdate": 11,
"updated": 0,
"updateFailed": 0,
"reconciliationPassed": true,
"ruleCounts": [
{ "ruleId": "RULE-0100-TIER0", "name": "Tier 0 administrators", "enabled": true, "matches": 3 }
]
}
reconciliationPassed is processed == matched + unclassified + evaluationError (FR-021, SC-007).
ruleCounts lists all business rules, including disabled and zero-match rules — an absent rule
is indistinguishable from a rule that never fired, and operators need that distinction.
RunComplete
{
"recordType": "RunComplete",
"runId": "<RUN-ID>",
"startedUtc": "2026-08-20T09:00:00.000Z",
"completedUtc": "2026-08-20T09:12:44.913Z",
"durationMs": 764913,
"processed": 4820,
"matched": 4611,
"unclassified": 190,
"evaluationError": 19,
"unchanged": 4400,
"wouldUpdate": 211,
"updated": 0,
"updateFailed": 0,
"reconciliationPassed": true,
"exitCode": 0
}
EngineDefect
Emitted when reconciliation fails (FR-021) or an internal invariant is violated. Severity is always
Error. A failed reconciliation is a defect in the engine, not a property of the data, and is
reported as such rather than being folded into ordinary counters.
Sanitization (SC-013)
Committed artifacts — this contract, examples, fixtures, tests, and documentation — use placeholders
only: <ORGANIZATION-NAME>, <PRIMARY-DOMAIN>, <TENANT-ID>, <ACCOUNT-OBJECT-ID>,
<GROUP-OBJECT-ID>, <APPROVED-PERSONA-ATTRIBUTE-NAME>, <AUTOMATION-ACCOUNT-NAME>,
<LOG-OUTPUT-PATH>, <RUN-ID>. Runtime records naturally contain real UPNs and Object IDs — which
are approved for logs — but no such value may ever be committed to this repository.