# AEGIS — Reference Architecture Review (RAR)

- **Document ID:** ARCH-60
- **Phase:** Final Pre-Implementation Gate
- **Status:** Proposed — awaiting Owner + Auditor sign-off for approval
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect
- **Approver:** Owner + Auditor + Chief Security Architect + Platform Architect + Implementation Owner
- **Depends on:** ARCH-01 through ARCH-59

---

## 1. Purpose

Validate — with the frozen corpus in hand and the implementation team about to begin — that the implementation plan is *still* consistent with the architecture. This is the "measure twice, cut once" moment before code lands.

Ten review items per your mandate. Each is scored **Pass / Conditional / Fail**. Any Fail blocks implementation start; Conditionals become tracked follow-ups.

## 2. The Ten Review Items

### R-1 Architecture Consistency

- **Verified.** 59 documents (ARCH-01..ARCH-59) form a coherent, cross-referenced corpus.
- Consistency-checker framework defined (ARCH-41 §3, 14 automated checks C-1..C-14); runs at CI once implementation begins.
- Cross-references informally verified at freeze; automation runs during first release cycle.
- **Verdict: Pass.**
- **Note.** "Capability Engine" (from priority order §5.3 below) is interpreted as the Kernel's Capability Broker sub-module (per ARCH-08 §6 and ARCH-06 §4.1). Not a new engine; a bounded implementation unit within the Kernel process. This must be reflected in Reference Repository Structure (§4).

### R-2 ADR Completeness

- ADR Process (ARCH-35 with amended template) defines the framework.
- **~140 embedded architectural Decisions (D-01-1 through D-57-1)** across the corpus are scheduled for retroactive conversion to numbered ADRs within 30 days post-freeze, led by the Platform Architect (per ARCH-35 §10).
- Going-forward: every new architectural change is a first-class ADR.
- **Verdict: Pass (Conditional on retrofit completion within 30 days).**
- **Follow-up.** PA to lead ADR retrofit; auditor visibility on progress; consistency-checker C-6 catches missing conversions.

### R-3 Threat Model Coverage

- ARCH-03 covers 12 adversary profiles, STRIDE across 13 boundaries, MITRE ATT&CK overlay, and a dedicated LLM-specific model.
- Extended by ARCH-15/16/17/18 (subsystem-specific threat additions) and ARCH-39/45 (simulation + red-team scenarios).
- Living Threat Model discipline: every incident + vulnerability + new subsystem triggers a threat diff (ARCH-41 §6; ARCH-55).
- Prompt-injection is ranked as the #1 likelihood/impact threat and has structural mitigations (ARCH-03 §5, ARCH-16 §11).
- **Verdict: Pass.**

### R-4 Security Standards

- Constitution (CLAUDE.md) + 12 Platform Design Principles (ARCH-33).
- ARCH-19 (Secure Coding), ARCH-20 (Logging/Audit), ARCH-21 (IR), ARCH-22 (Config), ARCH-23 (OpSec), ARCH-24 (Metrics) — all approved.
- Governance: ARCH-34 (Governance Model), ARCH-35 (ADR), ARCH-36 (Security Design Review).
- **Verdict: Pass.**

### R-5 Verification Coverage

- Framework: ARCH-27 (strategy), ARCH-37 (detailed matrix), ARCH-38 (testing), ARCH-39 (simulation), ARCH-40 (formal candidates), ARCH-41 (consistency), ARCH-43 (evidence traceability).
- Assurance targets set per subsystem (ARCH-27 §3); deltas Debt-Register-tracked.
- 5 Golden Invariants specified; property-test authorship begins with Kernel implementation.
- **Verdict: Pass (Conditional: Verification Matrix rows populated per subsystem IRA — this is the intended sequence).**

### R-6 Architecture Debt

- Debt Register defined (ARCH-29) with 10 v0-GA entries, each with owner, expiration, mitigation.
- Governance for additions, renewals, retirements, escalations defined.
- Debt is registered but not concealed; auditor visibility from freeze forward.
- **Verdict: Pass.**

### R-7 Operational Readiness

- Framework: ARCH-21 (IR), ARCH-22 (Config), ARCH-23 (OpSec), ARCH-24 (Metrics), ARCH-30 (Maturity), ARCH-49 (Tabletop), ARCH-51 (Recovery Exercises), ARCH-52 (Trust Score), ARCH-56 (ORR).
- Concrete runbooks + on-call rotation + drills authored during implementation Phase 5 (per ARCH-59 §7).
- Reference Deployment R-3 (Kubernetes small) is the v0-GA target; R-1 (VPS) for dev.
- **Verdict: Pass (Conditional: per-subsystem runbooks authored during implementation).**

### R-8 Security Priorities

- The eight security priorities in ARCH-59 §8 remain valid:
  1. Kernel + Cryptographic Identity + Capability Model FIRST.
  2. Immutable Event Sourcing + Audit Chain SECOND.
  3. Storage Engine with tenant scoping THIRD.
  4. Boundary contracts + Kernel mediation FOURTH.
  5. AI Safety Layer BEFORE AI Engine value features.
  6. Recovery Domain + backups EARLY.
  7. Watchdog Quorum in parallel with Kernel.
  8. Verification instruments continuously.
- **Verdict: Pass.**

### R-9 Implementation Sequence

The refined priority order specified for implementation (post-freeze):

1. **Security Kernel** (E-Kernel; sole mediator) — implements ARCH-06.
2. **Identity Engine** (E-07) — implements ARCH-09 workload + principal identity.
3. **Capability Engine** — Kernel Capability Broker sub-module implementing ARCH-08.
4. **Policy Engine** (E-06) — OPA/Rego per Q-08-3 resolution.
5. **Evidence Engine** (E-15) — implements ARCH-12.
6. **Audit Engine** (E-08) — Layer-A receiver + Layer-B batches; implements ARCH-13.
7. **Runtime Risk Engine** (E-14) — implements ARCH-11 §4.
8. **Verification Infrastructure** — CI + property test framework + CAV runner + Threat Simulation runner (implements ARCH-37/38/39/50).
9. **Recovery Domain** — Recovery Engine (E-11) + Recovery Domain isolation (ARCH-18).
10. **AI Safety Layer** — sub-engine of AI Engine with its own SVID (ARCH-16).

**AI Engine (E-05) implemented only after steps 1–10 are functional.**

Reconciliation with ARCH-59 §7 (48-week plan):
- Steps 1–4 → ARCH-59 Phase 1 + start of Phase 2.
- Steps 5–7 → ARCH-59 Phase 2 + start of Phase 3.
- Steps 8–9 → ARCH-59 Phases 3–5.
- Step 10 (Safety Layer) → early in ARCH-59 Phase 4.
- AI Engine → late Phase 4.

The refined ordering **strengthens** ARCH-59 §7 by making explicit that the deterministic decision-making layer (Policy + Evidence + Audit + Risk + Verification) is fully live before AI. This aligns with mandate #14 Deterministic Core + mandate #13 Human Authority.

**Verdict: Pass.** Implementation team should follow the refined priority order over ARCH-59 §7 for the security-critical sequencing.

### R-10 Reference Repository Structure

Proposed structure (below in §4). Implementation team may adjust minor details, but the overall layout is architecture-mandated to preserve the microkernel + Docs-as-Code principles.

**Verdict: Pass (subject to Implementation Owner acceptance of structure).**

## 3. Overall Review Verdict

- **Failures:** 0
- **Conditionals:** 4 (R-2 ADR retrofit, R-5 Matrix population, R-7 runbook authoring, R-10 structure acceptance).
- **Overall verdict: PASS.** Implementation may begin subject to the four tracked follow-ups.

## 4. Reference Repository Structure

```
aegis/
├── CLAUDE.md                              # Constitution + all mandates (kept current)
├── README.md
│
├── docs/
│   ├── architecture/                      # ARCH-01..ARCH-60 (frozen; ADR-governed after freeze)
│   ├── adr/                               # Retroactive + new ADRs (ADR-NNNN-slug.md)
│   ├── runbooks/                          # Operational runbooks per category (ARCH-21)
│   ├── ceremonies/                        # Ceremony scripts + recordings-metadata
│   ├── exceptions/                        # ARCH-19-EXCEPTION register with expiry
│   ├── debt/                              # Architecture Debt Register (ARCH-29)
│   ├── verification/
│   │   ├── matrix.yaml                    # Verification Matrix (ARCH-37)
│   │   ├── claims-registry.yaml           # Assurance Claim Registry (ARCH-43)
│   │   └── evidence/                      # Structured evidence artifacts (signed)
│   ├── ira/                               # Implementation Readiness Assessments per subsystem
│   ├── orr/                               # Operational Readiness Reviews per deployment
│   ├── releases/
│   │   └── checklist.yaml                 # Release Certification (ARCH-54)
│   ├── traceability.md                    # Requirement → verification map
│   ├── schemas/                           # Public schema references
│   └── knowledge-base/                    # Structured incident + lessons-learned (ARCH-42)
│
├── config/                                # All signed configuration (ARCH-22)
│   ├── kernel/
│   ├── policy/                            # OPA/Rego rules (signed)
│   ├── catalogs/                          # Risk + Trust + Confidence weight catalogs
│   ├── detection/                         # Sigma rules (signed contributor)
│   ├── redaction/                         # Redaction rulesets (signed)
│   ├── admission/                         # Kyverno / OPA Gatekeeper policies
│   ├── tenants/                           # Per-tenant configuration
│   └── deployment/                        # Topology-specific config
│
├── contracts/                             # Wire-format contracts (versioned)
│   ├── audit-record.proto
│   ├── capability-token.proto
│   ├── evidence-bundle.proto
│   ├── plugin-manifest.proto
│   ├── ocsf-mapping/
│   └── provider-adapter.proto
│
├── crates/                                # Rust workspace (security-critical)
│   ├── kernel/
│   │   ├── capability-broker/             # ← "Capability Engine" per priority #3
│   │   ├── audit-gateway/
│   │   ├── policy-enforcement/
│   │   ├── identity-verifier/
│   │   ├── integrity-verification/        # RIV + beacons (ARCH-13)
│   │   └── quota-governor/
│   ├── crypto/                            # Vendored primitives + hybrid PQC scaffolding
│   ├── verifier-cli/                      # Public verifier (ARCH-20 M-28; Rust per Q-12-1)
│   └── shared-security/                   # Common types shared to TS via bindings
│
├── packages/                              # TypeScript workspace (pnpm)
│   ├── kernel-orchestrator/               # Kernel-runtime coordination in TS
│   ├── identity-engine/
│   ├── audit-engine/
│   ├── policy-engine/
│   ├── evidence-engine/
│   ├── risk-engine/
│   ├── storage-engine/
│   ├── recovery-engine/
│   ├── telemetry-engine/
│   ├── connector-engine/
│   ├── normalization-engine/
│   ├── detection-engine/
│   ├── case-engine/
│   ├── ai-engine/
│   ├── ai-safety-layer/                   # Distinct SVID; own topics
│   ├── plugin-engine/
│   ├── ui/                                # Next.js
│   └── shared/                            # Common types, adapters, utilities
│
├── tools/
│   ├── ceremony-workstation/              # Hardened image + scripts
│   ├── threatsim-runner/                  # ARCH-39
│   ├── cav-runner/                        # ARCH-50
│   ├── chaos/                             # ARCH-48 scenarios + runner
│   ├── consistency-checker/               # ARCH-41
│   ├── knowledge-graph-builder/           # Materializes ARCH-41 graph
│   └── docs-executable/                   # Executable-doc harnesses
│
├── tests/
│   ├── golden/                            # Golden Invariants (special approver to modify)
│   ├── property/
│   ├── fuzz/
│   ├── integration/
│   ├── contract/                          # Substitutable-substrate contracts
│   ├── e2e/
│   └── fixtures/
│
├── deployments/                           # Reference topologies (ARCH-26)
│   ├── r1-vps/
│   ├── r3-k8s-small/
│   ├── r4-k8s-ha/
│   ├── r5-airgap/
│   ├── r6-cloud-aws/
│   ├── r6-cloud-azure/
│   └── r6-cloud-gcp/
│
├── plugins/                               # Example/reference plugins (starter kit)
├── models/                                # Model manifests (weights fetched at build)
├── scripts/                               # Repo-tooling scripts
└── .github/ or .gitlab/                   # CI + admission + branch protection
```

**Structural rules (enforced by CI):**
- Rust crates in `crates/` implement security-critical hot paths (per ARCH-19 D-19-1).
- TS packages in `packages/` implement orchestration + engines.
- `contracts/` is the *only* place wire formats are defined; consumers depend on generated types.
- `docs/architecture/` is frozen post-approval; new architectural changes flow through `docs/adr/`.
- `tests/golden/` requires special approver + Auditor visibility for any modification (per ARCH-28 §4).
- `config/` is signed; ceremony-controlled changes only for high classes (ARCH-22).

## 5. Implementation Principles Encoded

Every PR must satisfy (from user directive):
1. Architecture Compliance (checked by consistency checker).
2. Threat Model Compliance (ADR must include threat-model diff per ARCH-35).
3. Verification Coverage (Verification Matrix rows added for new claims).
4. Security Review (SR sign-off per ARCH-34 decision-rights matrix).
5. Operational Review (OR sign-off for operational changes).
6. Recovery Validation (Recovery-First 5 questions answered for new components).
7. Documentation Update (Docs-as-Code mandate #43).
8. ADR Update (if architecture changes).

## 6. Bypass Prohibitions

No implementation may bypass:
- Security Kernel (all cross-engine calls Kernel-mediated per ARCH-05).
- Capability Model (every action requires a capability per ARCH-08).
- Policy Engine (every mediated call consults Policy per ARCH-06 §4.2).
- Audit Chain (every sensitive operation produces Layer-A per ARCH-13).
- Verification (Golden Invariants + Verification Matrix binding per ARCH-37/38).
- Architecture Governance (ADRs + Design Review Board per ARCH-34/36).

These are structural, not procedural — enforced by broker ACLs, capability verification, consistency checker, and CI. Bypass attempts fail closed.

## 7. Success Criteria

Implementation success is measured by:
- **Architecture preserved** (consistency checker green; drift < policy threshold).
- **Verification maintained** (Golden Invariants green; Matrix coverage growing).
- **Security guarantees upheld** (Trust Score healthy; no Golden regression).
- **Operational simplicity retained** (runbooks executable by trained SE without hidden knowledge).
- **Evidence remains reproducible** (Evidence Chain reproduction canary green).
- **Recovery remains verifiable** (Recovery Integrity Attestations green).

**Not features completed.** Feature-count metrics are *lagging indicators* of platform health; the above are *leading indicators* of trustworthiness.

## 8. Four-Reviewer Notes on the RAR

### 8.1 Independent
- **F-1.** *Have we skipped anything?* All 10 items reviewed; 4 Conditionals tracked with follow-ups.
- **F-2.** *Are Conditionals substantive?* Yes — they are the intended sequence, not deferred obligations.

### 8.2 Adversarial
- **A-1.** *Attacker exploits the retrofit-ADR gap.* Retrofit scheduled + consistency checker catches missing conversions.
- **A-2.** *Implementation drifts from repo structure.* CI rules + branch protection + reviewer discipline.
- **A-3.** *"Capability Engine" reinterpretation invalidates the architecture.* Clearly documented interpretation (§2 R-1 note); implementation sub-module, not new architectural element.

### 8.3 Operational Reliability
- **O-1.** *Repository structure sustainable at 15 years.* Standard patterns; clear ownership per directory.
- **O-2.** *Follow-ups tracked.* Auditor visibility on the four Conditionals.

### 8.4 Self-Critique
- **S-1.** *Am I approving too aggressively?* Every architectural claim + verification path exists in documented form. The Conditionals are sequencing, not gaps.
- **S-2.** *Should more items have been Conditional?* Reviewed each — the four called out are the natural implementation-time artifacts; others are complete-as-authored.
- **S-3.** *Did I under-detail the Repository Structure?* Reference structure is prescriptive at the top level; sub-tree details evolve per Implementation Owner within the frame.

## 9. First-Target Analysis

**Target:** the interpretation of "Capability Engine" in the priority order. If a future contributor reads it and creates a distinct engine, the architecture fragments. Response: this document explicitly reconciles the term as *Kernel Capability Broker sub-module*, not a new engine. Repository structure encodes: `crates/kernel/capability-broker/`. Consistency checker enforces the 15-engine roster from ARCH-07.

## 10. Recommendation

The Chief Security Architect certifies:
- All 10 review items **Pass**, with 4 Conditionals tracked.
- No structural gaps found.
- Implementation team may begin subject to the four follow-ups being active work streams from day one.

**Recommendation:** approve the Reference Architecture Review. Implementation may begin as of RAR approval.

The four Conditionals become the first tickets in the implementation backlog:
1. ADR retrofit (PA, 30-day SLO).
2. Verification Matrix population (per-subsystem IRA).
3. Runbook authoring (per-subsystem, during Phase 5).
4. Repository structure adoption (Implementation Owner, week 1).

## 11. Future Risks / Known Limitations / Out-of-Scope / Retirement

- **Future Risks.** Post-RAR drift; retrofit ADR quality; structure erosion under pressure.
- **Known Limitations.** RAR is a snapshot; Continuous Architecture Review keeps it honest.
- **Out-of-Scope.** Implementation execution planning at engineering-team level.
- **Retirement Conditions.** RAR is one-time; superseded by ongoing Continuous Architecture Review after implementation begins.

## 12. Sign-off

- **Chief Security Architect:** __________________
- **Platform Architect:** __________________
- **Owner:** __________________
- **Auditor:** __________________
- **Implementation Owner:** __________________
- **RAR approved on:** __________________
- **Implementation begins as of:** __________________

## 13. Change Log

- **0.1 (2026-07-10)** — Initial draft; awaiting sign-off.