Architecture Decision Records
The load-bearing design decisions behind OGuardAI, why each was made, and where the code enforces it
What these records are
An Architecture Decision Record (ADR) captures one decision that shaped the system: the context that forced it, the choice that was made, and the consequences the codebase now lives with. These are the decisions that are expensive to reverse and that a contributor needs to understand before changing the runtime.
Each record follows the same shape: Context, Decision, Consequences, Status. Every decision cites the crate or module that enforces it, so the record and the code stay honest with each other.
The records
| ADR | Decision | Status |
|---|---|---|
| 0001 | The Line: a built-in safe floor that policy may only add to or tighten, never silently weaken; invalid config or a missing required detector fails closed | Accepted |
| 0002 | The trust boundary: detected raw PII exists only inside the runtime; the untrusted zone sees tokens and safe metadata | Accepted |
| 0003 | Semantic tokens {{type:id:cap}} over irreversible redaction, to keep round-trip restoration | Accepted |
| 0004 | Sealed session state: stateless per request, token mappings travel as an AES-256-GCM encrypted blob | Accepted |
| 0005 | Dynamic policy YAML over hardcoded domain rules, so a new vertical is a config file, not a code change | Accepted |
| 0006 | NER as a strict, fail-closed requirement: a policy that requires NER blocks rather than falling back to the regex floor | Accepted |
How to read them together
The six records are one connected argument. The Line (0001) is the governing principle: a fixed safe floor plus config that can only tighten. The trust boundary (0002) is what the floor protects. Semantic tokens (0003) are how a value crosses the boundary without leaving the runtime. Sealed session state (0004) is how the token-to-value mapping survives a stateless request. Dynamic policy YAML (0005) is how a deployment tightens the floor for its domain. GLiNER-required NER (0006) is the concrete fail-closed lever that makes "the model never sees the real value" true for a deployment that demands it.