# AEG-X-001: Version Support Policy & Cross-Version Test Matrix

**Status:** ✅ DECISION APPROVED (2026-08-17)  
**Owner:** Architecture Lead / DevOps  
**Requirement:** REQ-PLAT-001 (Version Coverage Matrix)  
**Gateway:** G0 (Platform Foundation)

---

## 1. Approved Version Support Range

### .NET Framework Support Matrix

| Version | Release | LTS | EOL | Status | Support |
|---------|---------|-----|-----|--------|---------|
| **.NET 8** | Nov 2023 | ✅ 3yr LTS | Nov 2026 | ✅ CURRENT | Legacy (maintenance only) |
| **.NET 10** | Nov 2024 | ✅ 8yr LTS | Nov 2032 | ✅ CURRENT | **Primary Support** |
| **.NET 12** | Nov 2025 | ✅ 8yr LTS | Nov 2033 | 📅 PLANNED | Future support (v12.0+ GA approval pending) |

**Decision: Primary = .NET 10 (LTS), Secondary = .NET 8 (legacy), Future = .NET 12**

### PostgreSQL Version Support

| Version | Release | LTS | EOL | Status | Support |
|---------|---------|-----|-----|--------|---------|
| **PostgreSQL 13** | Oct 2020 | ✅ 5yr LTS | Oct 2025 | ⚠️ EOL | Maintenance only |
| **PostgreSQL 14** | Oct 2021 | ✅ 5yr LTS | Oct 2026 | ✅ CURRENT | Legacy support |
| **PostgreSQL 15** | Oct 2022 | ✅ 5yr LTS | Oct 2027 | ✅ CURRENT | **Primary Support** |
| **PostgreSQL 16** | Oct 2023 | ✅ 5yr LTS | Oct 2028 | ✅ CURRENT | **Primary Support** |

**Decision: Primary = PostgreSQL 15/16, Legacy = PostgreSQL 14**

### Node.js / pnpm Support

| Component | Version | LTS | Status | Support |
|-----------|---------|-----|--------|---------|
| **Node.js** | 18 (LTS) | ✅ | EOL 2025-04 | Legacy |
| **Node.js** | 20 (LTS) | ✅ | EOL 2026-04 | Current |
| **Node.js** | 22 (LTS) | ✅ | EOL 2027-04 | **Primary** |
| **pnpm** | 9 | — | ✅ | Current |
| **pnpm** | 10 | — | ✅ | **Primary** |

**Decision: Node.js 22 LTS + pnpm 10**

---

## 2. Cross-Version Test Coverage Matrix

### Test Scope Per Framework Version

| Test Level | .NET 8 | .NET 10 | .NET 12 | Requirement |
|-----------|--------|---------|---------|------------|
| Build | ✅ YES | ✅ YES | 📅 PLANNED | Restore + compile (no runtime) |
| Unit Tests | ✅ YES | ✅ YES | 📅 PLANNED | dotnet test (xUnit, isolated) |
| Integration Tests | ✅ YES | ✅ YES | 📅 PLANNED | Real DB, migration, async |
| DbUp Migration | ✅ YES | ✅ YES | 📅 PLANNED | Fresh/upgrade/re-run/failure recovery |
| Outbox/Inbox | ✅ YES | ✅ YES | 📅 PLANNED | Async replay, idempotency |
| E2E (Host + Frontend) | ✅ SMOKE | ✅ FULL | 📅 PLANNED | ShadowRun API, Host startup |

### Database Version Compatibility (Independent Test)

| Operation | PG 14 | PG 15 | PG 16 | Requirement |
|-----------|-------|-------|-------|------------|
| Fresh Migration | ✅ YES | ✅ YES | ✅ YES | 0000-0041 schema + DDL |
| Upgrade (14→16) | ⚠️ N/A | ✅ YES | ✅ YES | Data preservation + no downtime |
| Re-run (idempotent) | ✅ YES | ✅ YES | ✅ YES | DbUp checksums match |
| Failure Recovery | ✅ YES | ✅ YES | ✅ YES | Rollback + retry scenarios |

---

## 3. CI/CD Cross-Version Automation

### Job: `cross-version-matrix` (Gitea Actions)

**Trigger:** Every push to `main` (blocking gate)

#### Stage 1: Backend Cross-Version Test

```bash
# Matrix: [[dotnet: 8, 10], [postgres: 14, 15, 16]]
for dotnet_version in 8 10; do
  for postgres_version in 14 15 16; do
    dotnet restore KArtSell.sln --framework net${dotnet_version}0
    dotnet build KArtSell.sln -c Release --no-restore
    dotnet test KArtSell.sln -c Release --no-build --logger trx --results-directory evidence/AEG-X-001/net${dotnet_version}0-pg${postgres_version}/
  done
done

# Evidence stored: evidence/AEG-X-001/net{8,10}0-pg{14,15,16}/*.trx
```

#### Stage 2: Frontend Build (Single Version)

```bash
# Node.js 22 LTS + pnpm 10 only (no cross-version needed)
cd frontend
pnpm install --frozen-lockfile
pnpm typecheck
pnpm build
# Evidence: frontend/dist (gzip sizes logged)
```

#### Stage 3: Database Migration Rehearsal (Per PG Version)

```bash
# Matrix: [postgres: 14, 15, 16]
for postgres_version in 14 15 16; do
  # Fresh migration
  dotnet run --project src/KArtSell.DbMigrator -c Release
  
  # Re-run (idempotent)
  dotnet run --project src/KArtSell.DbMigrator -c Release
  
  # Evidence: evidence/AEG-X-001/migration-pg${postgres_version}.log
done
```

---

## 4. Evidence Preservation & Artifact Structure

### Directory Structure

```
evidence/AEG-X-001/
├── 2026-08-17_cross-version-run/
│   ├── net80-pg14/
│   │   ├── Unit.trx
│   │   ├── Integration.trx
│   │   ├── DbUpMigration.trx
│   │   └── DbUpRecovery.trx
│   ├── net80-pg15/
│   ├── net80-pg16/
│   ├── net100-pg14/
│   ├── net100-pg15/
│   ├── net100-pg16/
│   ├── frontend-build.log
│   ├── migration-pg14.log
│   ├── migration-pg15.log
│   ├── migration-pg16.log
│   └── SUMMARY.md  ← This session's cross-version matrix result
```

### Artifact Tracking (SHA256)

Each run generates:
- **Build artifacts**: `net{8,10}0-{date}.zip` (gzip measured)
- **Test results**: `.trx` files with pass/fail counts
- **Migration logs**: Text logs with checksum validation
- **Summary**: Per-version pass/fail matrix

---

## 5. Acceptance Criteria (VERIFIED)

| Criterion | Evidence | Status |
|-----------|----------|--------|
| ✅ Version Support Policy approved | This document (MD) | COMPLETED 2026-08-17 |
| ⏳ .NET 8 build + test PASS | evidence/AEG-X-001/net80-*/*.trx | IN_PROGRESS |
| ⏳ .NET 10 build + test PASS | evidence/AEG-X-001/net100-*/*.trx | IN_PROGRESS |
| ⏳ PG 14/15/16 migration PASS | evidence/AEG-X-001/migration-*.log | IN_PROGRESS |
| ⏳ Frontend build PASS (Node 22) | frontend/dist + build.log | IN_PROGRESS |
| ⏳ All artifacts stored + indexed | SUMMARY.md | IN_PROGRESS |
| ⏳ WBS_PROGRESS_TRACKER updated | Status=COMPLETED | IN_PROGRESS |

---

## 6. Rollout Timeline

| Phase | Action | Owner | ETA | Evidence |
|-------|--------|-------|-----|----------|
| A | Implement CI/CD cross-version job | DevOps | 2026-08-17 | .gitea/workflows/cross-version-matrix.yml |
| B | Execute matrix on CI (first run) | Gitea Actions | 2026-08-17 | evidence/AEG-X-001/2026-08-17_*/ |
| C | Analyze results + fix blockers | BE/QA | 2026-08-17 | Per-version PASS/FAIL report |
| D | Document DECISION outcome | Architecture | 2026-08-17 | This document + SUMMARY.md |
| E | Mark AEG-X-001 COMPLETED | PM | 2026-08-17 | WBS_PROGRESS_TRACKER updated |

---

## 7. Risk Mitigation

### Known Issues & Workarounds

| Issue | Impact | Mitigation | Evidence |
|-------|--------|-----------|----------|
| .NET 12 not GA | 📅 Future builds unavailable | PLANNED status, skip in CI for now | .gitea/workflows conditional logic |
| PG 13 EOL (Oct 2025) | ⚠️ Maintenance window | Drop from primary, keep docs | VERSION_COVERAGE_MATRIX.md |
| Node 18 LTS EOL (Apr 2025) | ⚠️ Next quarter | Plan Node 22 rollover | docs/DECISIONS/ADR-FRONTEND-RUNTIME.md |

---

## 8. Related Documents

- **[VERSION_COVERAGE_MATRIX.md](../../contracts/platform/VERSION_COVERAGE_MATRIX.md)** — Package-level compatibility (NuGet, npm)
- **[SOURCE_COVERAGE_MATRIX.csv](./CATALOGS/SOURCE_COVERAGE_MATRIX.csv)** — Artifact SHA256 tracking
- **[WBS_PROGRESS_TRACKER.csv](./CATALOGS/WBS_PROGRESS_TRACKER.csv)** — AEG-X-001 status updates
- **[.gitea/workflows/ci.yml](../../.gitea/workflows/ci.yml)** — Current CI gate
- **[.gitea/workflows/cross-version-matrix.yml](../../.gitea/workflows/cross-version-matrix.yml)** — New cross-version job (to implement)

---

**Decision Approved:** 2026-08-17  
**Next Step:** Implement .gitea/workflows/cross-version-matrix.yml (Step 2)