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:
@@ -0,0 +1,127 @@
|
||||
# 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).
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user