ADR 0002: The Trust Boundary

Status: Accepted

Context

The product claim is that AI can be used with sensitive data without the sensitive data leaving your control. That claim only holds if there is a precise, enforced boundary that raw values never cross. Without a stated boundary, "safe" is a hope. Everything outside the runtime, the LLM, external tools, logs, and vector stores, has to be treated as untrusted, because any of them can be logged, cached, or exfiltrated.

Decision

We define one trust boundary and make the runtime the only place raw PII lives.

• Trusted zone (the OGuardAI runtime): raw PII, token-to-value mappings, encryption keys, and policy rules.
• Untrusted zone (LLMs, tools, logs, vector stores): only {{type:id:cap}} tokens, safe metadata, and encrypted session blobs.
• The one deliberate exception: an explicit policy whitelist can pass a specific value through. It is opt-in per policy, never a default.

The boundary is enforced at the type level, not just by convention. In crates/core/src/token.rs, a token's Display renders only {{type:id:cap}} (via render_display_token), while Debug redacts, so a raw value cannot leak into a log line or an error message by accident. crates/core/src/log_hygiene.rs backs the "no PII in logs" rule. On the return path, crates/output-guard re-scans model output for new PII the model may have generated, catching values that were never in the input.

Outbound across the boundary: tokenized text plus safe entity context (type, and metadata such as gender or formality), never the raw value. Inbound: model output that contains tokens. The token-to-value mapping and the keys never cross.

Consequences

• The boundary is the legal and technical foundation of the product: reviewers and auditors can point to exactly what leaves the runtime.
• Logs, traces, vector stores, and third-party tools can hold OGuardAI output without holding PII, because the tokens are safe to persist.
• Passing a real value to the model is possible but always explicit, through a policy whitelist, so it shows up in review rather than happening by omission.
• The boundary constrains the design: any feature that would send raw values outward (richer prompts, tool arguments, embeddings) has to tokenize first or declare a whitelist, which is intentional friction.

Reference

See the Architecture Overview trust boundary section for the full zone model.