# AEGIS — Long-Term Maintenance Strategy

- **Document ID:** ARCH-31
- **Phase:** D — Deployment & Long View
- **Status:** Draft for review (post four-reviewer discipline)
- **Version:** 0.1
- **Date:** 2026-07-10
- **Owner:** Chief Security Architect

---

## 1. Purpose

Codify the discipline that keeps AEGIS maintainable for 15 years without breaking trust. Implements mandate #34 (Platform Sustainability) and #44 (Platform Evolution).

## 2. Principles

1. **Interfaces are contracts.** Every public interface (schemas, APIs, event formats, capability vocabulary, audit record format) is versioned per semver; wire-compat within major.
2. **Deprecation is a formal process,** not a decision.
3. **Backward compatibility is intentional** — kept where value > cost; broken with explicit ARCH-doc justification.
4. **Debt paydown is scheduled,** not aspirational (ARCH-29).
5. **Team continuity is a first-class concern** — knowledge transfer, ownership rotation, documentation-as-code.

## 3. Interface Stability

### 3.1 Contract Registry
- Every public contract lives in `contracts/` with a schema, version, and deprecation cycle.
- Contracts include: capability vocabulary, event schemas, audit record schema, plugin manifest, provider adapter API, verifier CLI protocol.
- Contract diff at CI blocks breaking changes without an explicit ARCH-EXCEPTION.

### 3.2 Backward Compatibility
- **Wire compat within major.** Consumers must accept older + current wire formats.
- **Additive changes** are non-breaking; add fields; downstream tolerates.
- **Semantic changes** are breaking; require major bump + migration plan + ARCH-doc.
- **Removals** deprecated at least one major cycle before removal.

### 3.3 Migration Support
- Contract migrations documented per version.
- Migration tooling ships alongside major releases.
- Fallback compat window at least one major.

## 4. Deprecation Cycle

- **Announce** — ARCH-doc update + release-note; deprecation flag surfaced.
- **Deprecate** — warning logs on use; alarms on tenant usage.
- **Sunset** — removed in specified major; migration required.
- **Remove** — hard removal + ARCH-doc archived + Debt Register updated.

Timelines documented per contract; minimum one major cycle.

## 5. Debt Paydown

- Debt Register (ARCH-29) tracks compromises with expiration + target resolution.
- Debt paydown budgeted per release cycle.
- Metrics track debt count + age (ARCH-24 M-OPS-05).
- Debt escalation (§ARCH-29 §5) drives paydown priority.

## 6. Team Continuity

- **Ownership matrix** per subsystem; primary + backup owner.
- **Knowledge transfer** required on owner change; documented artifact.
- **Rotation** to avoid single-point-of-knowledge; typical 18-24 month cycles per subsystem for security-critical paths.
- **Docs-as-code** — every decision + architecture change lives in the repo; no tribal knowledge.
- **New engineer onboarding** includes architecture-doc reading list + shadow drills.

## 7. Technology Refresh

- **Framework upgrades** planned per release channel; Next.js, TS, Node.js LTS tracked.
- **Substrate upgrades** planned with migration drills (PostgreSQL, ClickHouse, Kafka, NATS).
- **Language boundaries** reviewed periodically — Rust footprint per ARCH-19 M-38a.
- **Deprecated dependencies** removed per SLO.

## 8. External Change

- **Regulatory change** — jurisdictional matrix (ARCH-23) updated; runbook adjustments.
- **AI provider change** — adapter contract absorbs; ARCH-15 D-15-1.
- **Cloud provider change** — reference deployment addendum + exit-path drill (ARCH-23 M-16a).

## 9. Independent Architecture Review

- **F-1.** *Contract stability could constrain innovation.* Deprecation cycle enables evolution; backward compat is not eternal.
- **F-2.** *Debt paydown competes with feature velocity.* Explicit budget; auditor visibility on trend.
- **F-3.** *Team continuity requires investment.* Onboarding + rotation are line items in ops budget.

## 10. Adversarial Architect Review

- **A-1.** *Attacker exploits deprecated but not-removed interface.* Deprecated interfaces monitored; usage-based alarms; sunset schedule.
- **A-2.** *Compromised contributor pushes breaking change.* Contract-diff CI blocks; two-approver on security-critical contracts.
- **A-3.** *Long-persistence attacker slowly shifts a "backward-compat" interface into insecurity.* Contract semantic tests + threat-model diffs per change.

## 11. Operational Reliability Review

- **O-1.** Long-term docs live in-repo; discoverable.
- **O-2.** Substrate migration playbooks drilled.
- **O-3.** Owner rotation smooth; documented handoff.
- **O-4.** Refresh cadence sustainable — not perpetual crises.

## 12. Self-Critique

- **S-1.** *"15 years"* is aspirational; predictions are unreliable. Framework designed to *survive* being wrong — deprecation cycle, contract versioning, debt register absorb change.
- **S-2.** *Backward compat can hide security issues.* Deprecated interfaces are treated as reduced-trust; usage triggers review.
- **S-3.** *Team continuity depends on org stability we can't fully control.* Documentation-as-code + shadow rotations + onboarding runbooks are the compensating controls.

## 13. First-Target Analysis and Redesign

**Target:** deprecated-but-not-removed interfaces. They accumulate over years; each is a smaller attack surface than a live interface but never fully retired. An attacker who knows what's deprecated can chain deprecated behavior to compose an unexpected exploit.

**Response:**
1. **Hard sunset schedule** — deprecated interfaces have a specific removal date, not "eventually."
2. **Usage monitoring** — tenant usage of deprecated interfaces surfaces to tenant admins with migration guidance.
3. **Compat-mode reduced trust** — deprecated interfaces run at reduced classification ceiling; some operations disallowed.
4. **Deprecation debt** — every deprecated interface has a Debt Register entry with target removal.
5. **Annual review** — deprecation portfolio reviewed by Auditor for silent renewals.

## 14. Decisions

### D-31-1. Contract versioning + deprecation cycle enforced by CI

- **Reason.** Mandate #44 Platform Evolution.

### D-31-2. Deprecated interfaces are reduced-trust and debt-tracked

- **Reason.** §13 first-target response.

## 15. Change Log

- **0.1 (2026-07-10)** — Initial draft.