personaEngine2/docs/Architecture.md

Architecture

How Persona Engine is put together, and why the boundaries sit where they do.

The one structural rule

The rule engine is pure. It takes a normalized record and a rule set, and returns a decision. It has no knowledge of Microsoft Graph, no authentication, no console, no filesystem, and no clock.

Everything else follows from that. It is constitution Principle IV, it is enforced by tests/Test-EnginePurity.ps1 on every build, and it is the reason 354 tests can run on a laptop with no tenant, no credentials, and no network.

The purity check is a tokenizer pass, not a text search: it parses each file under src/RuleEngine/ with the PowerShell AST parser and inspects only the code tokens. An earlier text-matching version flagged a comment that merely mentioned a persistence function, which is the kind of false positive that gets a check disabled.

Layers

Loaded in this order by PersonaEngine.psm1. Order matters only for readability — PowerShell resolves function names at call time — but the dependency direction is real and one-way.

Layer	Responsibility	May depend on
Normalization	Convert raw directory objects into UserRecord and MembershipRecord	nothing
Configuration	Load, validate, and resolve configuration	Normalization
RuleEngine	Evaluate conditions, groups, rules; produce a decision	Normalization only
Authentication	Acquire a Graph connection	nothing in this module
DataProviders	Retrieve users, membership, roles; retry policy	Normalization
Persistence	Compare values; build and issue the write	DataProviders
Presentation	Per-user output, summaries, reconciliation	nothing
Engine	The run loop that composes all of the above	everything
Audit	Build and emit structured records	Presentation

The arrow never points into RuleEngine. Nothing in RuleEngine may reference anything from Authentication, DataProviders, Persistence, or Presentation.

The normalization boundary

ConvertTo-PersonaUserRecord and ConvertTo-PersonaMembershipRecord are the only places where a raw Graph shape becomes an engine shape. Downstream of them, nothing knows Graph exists.

Two consequences worth stating plainly:

Fixtures are real inputs. A synthetic UserRecord built in a test is indistinguishable to the engine from one built from a live tenant response. That is what makes the offline suite evidence rather than a rehearsal.

Filtering rules live in one place. memberOf returns directory objects of mixed type. Administrative units arriving on that endpoint are discarded during normalization, not by each caller. An administrative unit ID treated as a group ID would never match — which reads as "not a member", a false non-match, the exact outcome FR-013 exists to prevent.

The MembershipRecord shape

Three independently-retrieved facets — direct groups, transitive groups, directory roles — each with its own retrieval flag and failure reason.

This started as a single record with one Mode field, and running the code against the example configuration is what proved it wrong: RE-007 makes membership mode a per-condition choice, so a rule set may legitimately ask for transitive membership in one rule and direct in another. A record carrying only one mode cannot answer both, and seven of nine fixtures came back as EvaluationError. The engine was right; the contract was wrong.

Independent facets also contain failure. If the transitive lookup times out but the direct lookup succeeded, only conditions needing transitive data become Unknown. One collapsed flag would turn one slow endpoint into a tenant-wide outage.

Every *Retrieved flag defaults to $false. An unset flag means unknown, never not a member, so a forgotten flag degrades to EvaluationError rather than silently misclassifying a privileged account.

Tri-state evaluation

Conditions return 'True', 'False', or 'Unknown' — not a boolean. Unknown propagates through condition groups by the table in data-model.md, and an Unknown reaching a rule's root becomes EvaluationError for that account.

An Unknown at priority 30 stops evaluation even though a lower-priority rule might have matched. Continuing would risk assigning a persona from priority 900 when the account may in truth have matched at 30 — a privilege downgrade drawn from data nobody could read. Preserving the stored value is the only safe answer.

The write gate has one origin

Mode is derived from $PSCmdlet.ShouldProcess() and nothing else. There is no -Preview switch, no configuration key that suppresses writes, and no reading of $WhatIfPreference. Two sources of truth for a write gate is the defect class Principle III exists to prevent: the day they disagree, one of them is wrong and the directory finds out first.

Invoke-PersonaEngine.ps1 owns the ShouldProcess call and passes the result down to Invoke-PersonaEngineRun as a scriptblock. The run loop never learns what -WhatIf is, so it cannot disagree with it — and it defaults to a gate that refuses, so a caller that forgets to supply one previews rather than writes.

Why the run loop is a module function

Invoke-PersonaEngine.ps1 is a thin wrapper: parameter binding, module import, ShouldProcess, exit code. The loop itself is Invoke-PersonaEngineRun in src/Engine/.

That split exists because SC-004 requires proof that a -WhatIf run issues zero writes across a full population. A loop that only exists inside an entry script — one that imports a manifest requiring the Graph SDK — cannot be exercised without a tenant, so the claim could not be tested. What ships and what is tested are now the same code.

Single emission point for audit

Every audit record passes through Write-PersonaAuditRecord. Adding a transport is a change to that one function. If call sites wrote their own output, each new transport would mean auditing every call site again, and the one that got missed would be silent.

Records go to the Information stream, not the success stream. Audit records on the success stream would be indistinguishable from a function's return value — the run loop returns its outcome there, and mixing the two turns one object into an array of several thousand.

Failure containment

Failure	Scope	Outcome
Configuration invalid	Run	Exit 1, before any connection is attempted
Authentication fails	Run	Exit 2
Enumeration truncated	Run	Exit 3 — a partial population is never processed
One membership lookup fails	One facet, one user	EvaluationError, stored value preserved
Too many EvaluationError	Run status only	Exit 4; no value was changed
Counters disagree	Run	Exit 5, EngineDefect record
One write fails	One user	UpdateFailed, run continues

The dividing line: anything affecting the whole population ends the run; anything affecting one account is contained and reported.

Related

• SecurityModel.md — the OTD-003 trade-off and its compensating controls
• ConfigurationReference.md — every schema field and finding code
• OperationsRunbook.md — kill switch and rollback
• Logging.md — record types and what they may contain