Epic: MAPL3 Readiness Roadmap

Summary

This epic tracks the full modernization of GEOS GCM GridComp components in
preparation for migration from MAPL2 to MAPL3. It spans multiple git
sub-repositories and is organized into four issue types that govern how
work is discovered, planned, and executed.

---

Motivation

Three overlapping needs drive this effort:

1. Accumulated spec boilerplate — many components carry hundreds of
   hand-written MAPL_AddImportSpec / MAPL_AddExportSpec /
   MAPL_AddInternalSpec calls. The ACG code-generator (mapl_acg) eliminates
   this entirely, replacing it with a compact, validated *_StateSpecs.rc file.

2. Error-handling hygiene — widespread use of the legacy VERIFY_(STATUS)
   macro instead of the modern _RC / __RC__ forms makes error traces
   harder to follow and complicates MAPL3 migration diffs.

3. MAPL3 API incompatibility — MAPL3 changes core interfaces. Components
   must be in a clean state before that migration to avoid conflating debt
   cleanup with API changes in the same PR.

---

Scope

In scope: all GEOS-owned MAPL GridComp components in GEOSgcm_GridComp,
GEOSradiation_GridComp, GEOS_OceanGridComp, and FVdycoreCubed_GridComp
sub-repos (~47 components total).

Excluded: CatchCNGridComp, CatchCNCLM40GridComp, CatchCNCLM45GridComp,
ARIESg3GridComp — to be evaluated separately.

Already complete:

• GwdGridComp — ACG reference implementation; Type 1 issue is pre-closed.
• DataSeaGridComp — ACG already complete; Type 1 issue is pre-closed.

---

Reference Implementation (ACG)

All Type 1 (ACG migration) work follows GwdGridComp as the template:

• Spec file: GWD_StateSpecs.rc — schema_version: 2.0.0 with IMPORT:, EXPORT:, INTERNAL: sections
• CMakeLists.txt: mapl_acg(${this} GWD_StateSpecs.rc IMPORT_SPECS EXPORT_SPECS INTERNAL_SPECS GET_POINTERS DECLARE_POINTERS)
• GridComp F90: #include "GWD_Import___.h" / Export___.h / Internal___.h; all manual MAPL_Add*Spec calls removed

---

Issue Taxonomy

Work is structured into four issue types. The lifecycle for each component is:

[Type 1: ACG Migration]  ─────────────────────────────────────────┐
                                                                   │
[Type 2: Audit]  →  spawns  →  [Type 3: Fix A]                    ├──▶  [Type 4: MAPL3]
                                [Type 3: Fix B]  (all closed)      │
                                (may be zero)  ────────────────────┘

Type	Label	When created	Blocked by
1 ACG Migration	acg-migration	Now (upfront)	Nothing
2 Pre-Migration Audit	pre-migration-audit	Now (upfront)	Nothing
3 Pre-Migration Fix	pre-migration-fix	Dynamically (from audits)	Parent Type 2 audit
4 MAPL3 Migration	mapl3-migration	Late (after Type 2+3 closed)	Type 1 + Type 2 + all Type 3s; children's Type 4s for parent components

Title convention

[ACG]   ComponentName: migrate to mapl_acg
[Audit] ComponentName: pre-migration audit
[Fix]   ComponentName: <specific description of finding>
[MAPL3] ComponentName: migrate to MAPL3 APIs

---

Priority Notes

• MoistGridComp — highest priority. Largest leaf by spec count (612 specs, 898 VERIFY_ calls, 6570 LOC).
• Type 1 runs independently — ACG work does not wait for audits; they proceed in parallel.
• Type 4 bottom-up ordering — leaf nodes must be migrated before parents.

---

Milestones

Milestone	Closed when
Phase 1 Complete	All Type 1, 2, 3 issues closed
MAPL3 Migration Complete	All Type 4 issues closed

---

Phase 1 — Definition of Done

• All in-scope components have ACG-generated spec headers (all Type 1 closed)
• All in-scope components have had a pre-migration audit (all Type 2 closed)
• All Type 3 fixes spawned by audits are closed
• CI passes on main with no regressions

Phase 2 — Definition of Done

• All in-scope components migrated to MAPL3 APIs (all Type 4 closed)
• Integration tests pass on MAPL3 branch

Start with the GwdGridComp reference files, including GWD_StateSpecs.rc, its CMakeLists.txt mapl_acg entry, and the GridComp Fortran includes. Review the in-scope components and the Type 1–4 issue lifecycle before selecting a component-sized task. The roadmap is complete when all listed Type 1–3 work is closed, CI passes, and later MAPL3 migrations satisfy their stated dependencies.