KArtSell.Aegis/docs/CURRENT/AEG-X-001_VERSION_SUPPORT_POLICY.md

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

# 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)

# 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)

# 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 — Package-level compatibility (NuGet, npm)
• SOURCE_COVERAGE_MATRIX.csv — Artifact SHA256 tracking
• WBS_PROGRESS_TRACKER.csv — AEG-X-001 status updates
• .gitea/workflows/ci.yml — Current CI gate
• .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)